app

Local-first trade for farms and co-ops
git clone https://radroots.dev/git/app.git
Log | Files | Refs | README | LICENSE

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.