AGENTS.md (16222B)
1 # AGENTS.md — HarvestCircle 2 3 These instructions apply to the complete standalone HarvestCircle repository. 4 A more specific `AGENTS.md` may refine them for its subtree. 5 6 ## Repository role and source boundary 7 8 This repository owns the public HarvestCircle product with separate native 9 and browser runtimes. The native runtime owns the Kotlin/Compose presentation 10 shell, desktop lifecycle, client-side state, 11 generated UniFFI integration, host packaging, product-specific Rust core, and 12 their tests. The Rust workspace under `core/**` owns HarvestCircle application, 13 domain, runtime, persistence, Nostr-adapter, preference, native FFI, and UniFFI 14 binding-generator implementation. 15 16 The repository also authorizes an isolated browser runtime under `web/**`. 17 Its implementation is planned; this guidance does not establish a working 18 browser application or new commands. Browser source, dependencies, storage, 19 sessions, and extension signing belong only to that subtree, governed by 20 `web/AGENTS.md`. Native-specific guidance below continues to govern the 21 desktop runtime; it does not make browser state use the native database, 22 keyring, UniFFI boundary, or native transport implementation. 23 24 HarvestCircle remains a client of canonical public Radroots library packages. 25 It does not own shared Radroots identity, transport, signing, wire-contract, or 26 other reusable library policy. Product-specific Rust code must live in this 27 repository and may depend on the exact public Radroots library revision selected 28 by the capsule; it must not depend on an implicit sibling checkout. 29 30 Product-owned names use the HarvestCircle identity consistently: 31 32 - Human-facing product name: `HarvestCircle`. 33 - Rust crate directories, Cargo packages, and dependency keys: 34 `harvestcircle_*`. 35 - Kotlin source namespace: `org.harvestcircle`. 36 - Product-owned Kotlin and UniFFI types: `HarvestCircle*`. 37 - Product-owned environment variables: `HARVESTCIRCLE_*`. 38 39 These product-specific names are intentionally distinct from canonical shared 40 `radroots_*` library packages, Radroots service terminology, and Radroots 41 corporate or vendor identity, which retain their existing names. 42 43 The repository must remain independently cloneable, buildable, testable, and 44 packageable through its checked-in command surfaces with or without extbuild. 45 It must not depend on private parent code, parent-only contracts, unpublished 46 local artifacts, absolute host paths, or an enclosing monorepo layout. 47 48 ## Machine authority and generated inputs 49 50 - `core/Cargo.toml`, `core/Cargo.lock`, `core/rust-toolchain.toml`, 51 `radroots.lib.source-lock.v1.toml`, and the product crates under 52 `core/crates/**` own the Rust workspace inputs. 53 - Gradle settings, build scripts, the version catalog, wrapper properties, 54 policy configuration, and `config/product/harvestcircle-v1.properties` own 55 the desktop build, dependency, product-coordinate, and package inputs. 56 Kotlin and Rust source and tests are implementation evidence. 57 - `gradlew`, `gradlew.bat`, and `gradle/wrapper/gradle-wrapper.jar` are 58 checked-in command implementation and supply-chain inputs, not policy 59 authority. Review them with `gradle-wrapper.properties`; keep the launcher, 60 distribution URL/version, and distribution checksum aligned, and never 61 replace the wrapper binary without explicit provenance review. 62 - Keep every shared Radroots dependency on the canonical public Git source, 63 one exact immutable revision, and the declared exact version. The manifests, 64 lockfile, compatibility baseline, and generated native package metadata must 65 agree. 66 - Never use a path dependency, floating branch or tag, private mirror, 67 implicit sibling override, dirty source cache, or unrecorded native binary. 68 Local product crates are workspace path dependencies; shared Radroots 69 packages remain immutable public Git dependencies. 70 - The repository retains only concise standalone governance and operational 71 guidance in `README.md`, `NOTICE`, `CONTRIBUTING.md`, `SECURITY.md`, 72 `LICENSE`, and `LICENSES/**`. Authoritative product specifications, 73 decisions, reviews, handoffs, and qualification evidence are owned by the 74 consuming Radroots monorepo under `docs/oss/harvestcircle/**` and must not be 75 required to build or test this standalone source tree. All `docs/**`, 76 `spec/**`, `.github/**`, and `.act/**` paths are forbidden here. Local 77 workflow orchestration belongs to the consuming monorepo's governed 78 `.act/**` surface and must call this capsule's standalone Make targets. 79 80 Generated UniFFI Kotlin and native libraries are derived build output. Change 81 the local canonical Rust producer contract/generator first, regenerate into 82 the active Gradle and Cargo build locations, and inspect the result. Never 83 hand-edit or check in generated bindings or native binaries as a source 84 substitute. 85 86 ## Isolated browser source boundary 87 88 Use SvelteKit with strict TypeScript and static output under `web/**`, with 89 one web-owned pnpm lockfile and pinned toolchain and package inputs. Do not add 90 a root JavaScript workspace, aggregate Cargo workspace, shared UI, hosted 91 backend, or browser dependency on native binaries or WASM. Existing native 92 Make targets, Gradle inputs, both Cargo graphs, product/install identities, 93 persisted paths, schema v3, storage API v3, FFI v4.5, snapshot v1, custody, 94 and the exact Radroots source pin remain unchanged by browser work unless a 95 separate change is explicitly authorized. 96 97 Browser storage and sessions are separate from native state. Browser identity 98 and signing use explicit extension interaction without raw private-key custody. 99 Generic browser Nostr implementation uses Applesauce in `web/src/lib/nostr`; 100 pure Radroots contract adapters must conform to the exact pinned public Rust 101 oracle rather than invent shared policy. Public interop vectors belong under 102 `contracts/interop/**`; they do not introduce a runtime dependency on Rust or 103 the parent tree. Browser build and test inputs remain standalone, subject to 104 the same forbidden document roots and private-dependency rules as native 105 source. Planned web command surfaces must be implemented and verified before 106 being advertised as available. HCAV-021 and later desktop availability work 107 remain paused; authorizing `web/**` does not resume them. 108 109 ## Common application and security boundaries 110 111 Both runtimes preserve protocol fidelity, bounded resource use, explicit 112 user-authorized effects, and independent buildability. Keep secret material 113 out of logs, crash text, analytics, filenames, public caches, and long-lived 114 presentation state. Keep lifecycle work structured, cancelable, and scoped; 115 never infer external mutation from environment state. Presentation code is 116 client orchestration, not domain or shared-library authority. Tests and 117 qualification records must identify actual checked inputs and executed lanes. 118 Browser custody and persistence follow `web/AGENTS.md`; native storage, OS 119 custody, transport, and ABI rules below apply only to the native runtime. 120 121 ## Native runtime boundaries 122 123 - Product state is bound only through `radroots_runtime_paths::RuntimeContext` 124 for service `harvestcircle` and instance `desktop`; the canonical database 125 and lock names are `state.sqlite` and `state.lock`. Fresh state initializes 126 at schema v1 and is migrated through the pinned current schema v3 before host 127 exposure; `radroots_service_sqlite` owns the governed SQLite mechanics. 128 - Public listing-version evidence retains exact verified original wire and first 129 named provenance independently of installed accounts or local signing custody. 130 The global public payload meter admits at most 4,096 versions and 120 MiB of 131 ordinary growth within its 128 MiB total; 8 MiB remains reserved for recovery. 132 Charges are logical payload bytes. Duplicate IDs preserve first evidence 133 without growth; no automatic eviction or recovery bypass is exposed. 134 - The durable-operation journal records terminal completion time, retains 135 terminal receipts for exactly seven days, admits at most 1,024 unfinished 136 operations and 4,096 total rows, and deletes no more than 256 expired terminal 137 rows in one transaction. Admission reserves terminal capacity in the same row 138 and must never evict an in-window receipt. 139 - `harvestcircle.sqlite3` is legacy evidence only. Never delete, rename, 140 import, dual-read, dual-write, or otherwise treat it as current state. 141 - SQLx is the only high-level SQLite library. HarvestCircle may use its sealed 142 application-schema callback inside `radroots_service_sqlite` initialization, 143 but must not create another pool, expose a raw connection, or reintroduce 144 Rusqlite, Refinery, arbitrary repair, or a second migration authority. 145 - Storage bootstrap requires the injected runtime context's canonical state 146 root to exist. `RuntimeContext::state_directory_plan` is the only production 147 authority allowed to create the exact `services/harvestcircle/desktop` 148 suffix. `ServiceSqliteHost::open_or_initialize` alone selects create versus 149 existing state under one retained writer authority and returns the actual 150 verified database metadata. Do not probe paths, recursively create roots, 151 repair permissions, or open a raw SQLx connection during bootstrap. 152 - Native production qualification is limited to macOS aarch64 and Linux 153 x86_64. Do not add or claim another target without an explicit contract 154 change and its complete platform evidence. 155 - Keep Compose screens and stores as client presentation and orchestration. 156 Do not make them a source of truth for accounts, identities, approvals, 157 domain objects, synchronization, reconciliation, or publication state. 158 - Private keys and signing operations remain behind the generated native 159 boundary. Kotlin must handle opaque identifiers and bounded public DTOs; it 160 must not persist, log, fixture, or expose raw secret material. 161 - Recovery and backup operations must be explicit, user-initiated, bounded, 162 fail closed, and keep sensitive material out of logs, crash text, analytics, 163 filenames, and long-lived UI state. 164 - Backup and restore must use the sealed HarvestCircle wrappers over Lib's 165 capture, verify, stage, finalize, and marker-recovery protocol. Verification 166 requires a trusted manifest digest, current database identity, and positive 167 caller-supplied member limit; never accept an arbitrary replacement path. 168 - Clipboard writes of sensitive output require explicit user action, bounded 169 lifetime, ownership-aware clearing, and tests for cancellation and 170 replacement. Never clear unrelated clipboard content. 171 - Native library loading must verify the generated artifact, platform/ABI, 172 compatibility baseline, and exact source provenance before application use. 173 Do not search ambient library paths or silently fall back to another binary. 174 - Keep lifecycle and coroutine work structured, cancelable, and scoped. Avoid 175 hidden workers, process-global mutable state, unbounded retries, blocking UI 176 work, and external mutation inferred from environment state. 177 - Relay parsing, destination policy, DNS admission, and connection ownership 178 come from the pinned `radroots_transport_nostr` boundary. Product code may 179 select a governed profile and verify product events, but must not recreate 180 relay URL policy or open a second production `nostr-sdk` client. 181 - The native host owns its Tokio runtime for exactly one application-core 182 lifetime. Runtime close is explicit, idempotent, and cancellation-resumable; 183 observer work and the bounded keyring worker must finish before terminal 184 close is reported. `SecretStore` is an object-safe asynchronous application 185 port. Every caller awaits it, Tokio workers await one-shot results, and only 186 the dedicated credential thread may drive the blocking platform adapter. 187 Authoritative locks fail closed on poison. The worker queue remains fixed at 188 eight, mutations carry the canonical UUIDv7 durable request identity, queued 189 cancellation has no effect, started caller loss is recovery-required, and 190 shutdown succeeds only after join within the fixed 30-second bound. Native 191 creation is create-only (`SecKeychainAddGenericPassword` on macOS and Secret 192 Service `replace=false` on Linux); exact same-operation replay verifies the 193 complete zeroizing credential envelope before it is accepted as idempotent. 194 - Services-hardening changes use the approved target-state contracts. Do not 195 add compatibility aliases, dual reads, dual writes, or fallback behavior for 196 prototype surfaces removed by the clean-slate refactor. 197 198 ## Change and command rules 199 200 Inspect status, all relevant manifests and locks, compatibility inputs, Gradle 201 tasks, native generation logic, source, tests, and package 202 configuration before editing. Make one coherent, reviewable change at a time; 203 keep implementation, tests, generated outputs, dependency evidence, and public 204 behavior aligned while preserving unrelated work. 205 206 The currently implemented root Make and Gradle commands below qualify the 207 native runtime only. They do not qualify a browser application. Browser checks 208 follow `web/AGENTS.md` once their actual standalone scripts exist; do not wire 209 browser dependencies into native commands or require native tools for ordinary 210 browser install, check, or build. Root guidance and audit changes require fresh 211 affected native and repository checks. Browser evidence must be reported as 212 unimplemented until the corresponding real checks exist and run. 213 214 The root `Makefile` is the standalone command surface and its durable behavior 215 belongs in Gradle or public producer tools. Standalone targets never invoke or 216 probe extbuild, even when it is installed. Explicit `governed-*` targets run a 217 green extbuild doctor and route the same underlying commands through extbuild. 218 Gradle otherwise uses its standard ignored `build/` directories and Cargo uses 219 the ignored target trees. Run `make doctor` before the first standalone 220 mutating lane and `make governed-doctor` before a governed lane. Use `make 221 format`, `make lint`, and `make test` while iterating, and run `make check` or 222 `make governed-check` for a complete source checkpoint. The active development 223 milestone is qualified with `make governed-development-check` on macOS aarch64 224 and `make governed-linux-x86_64-development-check` for the faithful Linux 225 x86_64 lane. These development targets must retain source, runtime, generated, 226 API, source-lock, SQLx-topology, and offline license/source verification without 227 activating advisory retrieval, package assembly, release evidence, signing, 228 notarization, Nix, or OCI work. Signing, notarization, and release targets are 229 governed-only and require a separately declared release candidate and fresh 230 authority. Unknown build modes fail before build mutation. 231 232 Shared public Git dependencies and deferred package or advisory lanes may 233 require external services. Do not weaken immutable inputs or silently switch 234 sources when offline. During the active development milestone, do not run or 235 claim the deferred release integrations merely because they remain available 236 as explicit targets. Never claim a lane passed unless it ran successfully; 237 report network, toolchain, platform, or external-artifact blockers exactly. 238 239 Verify exact manifests/lock agreement, generated binding and native artifact 240 freshness when affected, compatibility and architecture guards, 241 license/source policy, zero forbidden roots, `git diff --check`, and final 242 status and diff. Parent local-`act` proof is integration evidence only: it must 243 execute, and never replace, the standalone repository validation commands. 244 245 ## Git and external gates 246 247 Use focused commits in the established `<scope>: <imperative summary>` style. 248 Do not reset, discard, rewrite, push, tag, sign, publish, deploy, package for 249 distribution, change signing/notarization identities, or rotate credentials 250 without the corresponding explicit authority. 251 252 The change is complete only when it is implemented at the correct runtime or 253 public producer boundary, the relevant standalone lanes are green, locks and 254 generated evidence are fresh, forbidden roots remain absent, and final review 255 finds no secret exposure, private dependency, stale native artifact, hidden 256 domain authority, or unreported skipped lane.