app

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

README.md (12265B)


      1 # HarvestCircle
      2 
      3 HarvestCircle is an open-source Nostr application for coordinating local-food
      4 buying circles.
      5 
      6 The project is in early desktop development. It is not ready for real
      7 commercial use.
      8 
      9 ## Current foundation
     10 
     11 - Kotlin Multiplatform shared application code;
     12 - Compose Desktop host;
     13 - product-specific Rust core through UniFFI;
     14 - local Nostr identity creation and import;
     15 - operating-system keyring custody;
     16 - canonical service-instance persistence through the governed SQLx host;
     17 - configurable Nostr relay bootstrap;
     18 - compatibility-gated native startup;
     19 - reproducible source and development qualification.
     20 
     21 ## Sovereign direction
     22 
     23 The MVP is designed to work without a managed HarvestCircle account or API.
     24 
     25 Future work adds canonical Radroots collective-market contracts, private buyer
     26 commitments, a selectable open reference authority, pickup, and proof.
     27 
     28 ## Browser prototype bootstrap
     29 
     30 The isolated bootstrap under `web/` uses SvelteKit, strict TypeScript, and
     31 static output. Product controllers remain planned. It will use separate browser
     32 IndexedDB storage and sessions, explicit extension identity and signing without
     33 raw private-key custody, and Applesauce for generic Nostr behavior. Shared Radroots contracts must conform to the
     34 exact pinned public Rust oracle without requiring native binaries or the
     35 consuming monorepo to build the browser application.
     36 
     37 The desktop runtime retains its Kotlin/Compose/Rust implementation, native
     38 commands, database/schema/API, operating-system keyring custody, and exact
     39 Radroots dependency pin. Desktop availability work beyond HCAV-020 remains
     40 paused. See `web/AGENTS.md` for the browser source boundary.
     41 
     42 ## Contributor entry points
     43 
     44 Run commands from the standalone HarvestCircle repository root.
     45 
     46 | | Native desktop (implemented) | Browser bootstrap |
     47 |---|---|---|
     48 | Source | Kotlin/Compose in `app/`, product Rust in `core/`, root Gradle inputs | SvelteKit with strict TypeScript and static output in `web/` |
     49 | State and custody | SQLx service database, OS keyring, generated UniFFI boundary | Separate IndexedDB and sessions; explicit extension identity/signing without raw private-key custody |
     50 | Start | `make native-doctor`, then `make native-dev` | `make web-doctor`, `make web-install`, then `make web-dev` |
     51 | Check/build | `make native-check`, `make native-build` | `make web-check`, `make web-build` |
     52 
     53 Browser commands require Node 24.21.0, Corepack with pnpm 12.9.1 available,
     54 Make, Git for build provenance, and standard Unix shell/`mkfifo` utilities for
     55 the provenance tests. The doctor checks exact selected versions
     56 without downloading tooling; install uses the frozen web lock. Check runs the
     57 actual type/Svelte, lint/style/import, unit/provenance, and static-conformance
     58 assertions. It requires no Rust, Java, Gradle, or browser installation.
     59 Controlled browser tests remain separate web package scripts requiring a
     60 qualified Playwright browser. Browser commands use the web directory before
     61 Corepack resolves its package manager; no root JavaScript workspace is added.
     62 
     63 Native prerequisites include JDK 21, Rust 1.99.0, and platform packaging tools.
     64 Node is not a native prerequisite. The `native-*` targets are recipe-free
     65 aliases of the existing native targets:
     66 
     67 | Alias | Existing target |
     68 |---|---|
     69 | `native-doctor` | `doctor` |
     70 | `native-dev` | `dev` |
     71 | `native-check` | `check` |
     72 | `native-build` | `build` |
     73 | `native-package-check` | `package-check` |
     74 
     75 Unqualified `doctor`, `dev`, `check`, `build`, and `package-check` retain their
     76 native meanings. The default `BUILD_MODE=standalone` lane runs without
     77 extbuild or a private parent checkout. For example:
     78 
     79 ```sh
     80 make native-doctor
     81 make native-check
     82 make native-build
     83 ```
     84 
     85 For an extbuild-governed lane, run the diagnostic before mutating checks and
     86 select `BUILD_MODE=governed`; aliases inherit the selected mode:
     87 
     88 ```sh
     89 cargo extbuild doctor
     90 make BUILD_MODE=governed native-check
     91 ```
     92 
     93 `make governed-check` and `make governed-integration-check` also select governed
     94 mode for their existing native checks. The active development milestone uses
     95 `make governed-development-check` on macOS aarch64 and
     96 `make governed-linux-x86_64-development-check` for Linux x86_64. These targets
     97 route their build/check commands through extbuild and verify source, runtime,
     98 generated bindings, the public storage API, the exact Radroots source lock,
     99 the single SQLx-selected SQLite linkage, and offline license/source policy.
    100 
    101 `native-package-check` retains the full existing package-check prerequisites
    102 and clean-candidate evidence rules; it is not a routine development check.
    103 Package assembly, production source archives, release evidence, network
    104 advisory services, signing, notarization, Nix, and OCI qualification remain
    105 deferred and unclaimed until a release candidate is declared with fresh
    106 authority. Listing a target does not authorize its deferred effects.
    107 
    108 ## Conformance and source provenance
    109 
    110 Checked Food fixtures under `contracts/interop/` exercise the exact pinned
    111 public Rust codec and browser adapters. `make interop-check` runs both actual
    112 consumers and reports unsupported browser cases explicitly. Ordinary browser
    113 conformance uses checked vectors without invoking native tools. This is source
    114 conformance evidence; Message interoperability and independent-client, relay,
    115 extension and deployed Tera qualification remain pending.
    116 
    117 `make repo-check` runs fresh repository source policy without Node.
    118 `make web-integration-check` runs web integration and browser tests without
    119 native tooling. `make check-all` explicitly requires both toolchains and runs
    120 repository, native, web, browser integration and interop checks; an unavailable
    121 tool or failed lane fails the aggregate. It does not install dependencies.
    122 Existing unqualified `check`, `build`, `dev` and `package-check` retain their
    123 native meanings.
    124 
    125 `make affected-check BASE=<commit>` reports the actual Git merge-base diff,
    126 dirty inputs, runtime selection and complete input fingerprints. Renames,
    127 deletions, unknown paths, shallow or missing history widen selection to all
    128 runtimes. It always runs fresh source policy. The report records source HEAD
    129 separately from runtime input identity; selection and equal fingerprints do
    130 not mean runtime checks executed or qualify reuse of old artifact provenance.
    131 Missing tools are explicit, and the diagnostic never installs them.
    132 Fingerprints cover default repository source checks. Custom compiler wrappers,
    133 external build configuration or additional command arguments require separate
    134 evidence; the diagnostic never qualifies their artifacts or automatic reuse.
    135 
    136 The native artifact contract v3 requires an exact clean Git-revision tree
    137 source archive, including newly tracked `web/` files. A native-only filtered
    138 bundle cannot satisfy that whole-tree contract. Source archives are distinct
    139 from compiled desktop packages and future static website output. A new source
    140 revision changes provenance even when native runtime inputs are unchanged;
    141 it does not imply byte-identical binaries or production archive qualification.
    142 
    143 ## Development branch
    144 
    145 Active implementation proceeds on `master`.
    146 
    147 ## Local state
    148 
    149 HarvestCircle derives one canonical `harvestcircle`/`desktop` runtime context
    150 and stores application state only in its governed `state.sqlite` service
    151 database. SQLx is the sole high-level SQLite library, while
    152 `radroots_service_sqlite` owns connection, authority, migration, integrity,
    153 close, backup, and restore mechanics. The historical `harvestcircle.sqlite3`
    154 file is legacy evidence only and is never imported, repaired, deleted, or
    155 treated as current state.
    156 
    157 The platform or development harness must supply the existing canonical state
    158 root. HarvestCircle then uses the runtime context's sealed provisioning plan to
    159 create or validate only `services/harvestcircle/desktop`. The SQLite host makes
    160 the create-versus-existing decision atomically and returns the actual verified
    161 metadata; product storage never probes the database path, recursively creates
    162 roots, repairs existing permissions, or opens a raw SQLx connection.
    163 
    164 Online backup capture returns the canonical manifest in memory and writes only
    165 the governed `state.sqlite` member into a caller-selected new directory.
    166 Restore accepts only a digest-bound, identity-bound, size-bounded verified
    167 backup capability, closes the live host, uses the governed marker protocol,
    168 and reopens recovered state before returning. There is no arbitrary database
    169 repair or pathname-only restore authority.
    170 
    171 Relay endpoints are explicit inputs validated by the pinned Radroots Nostr
    172 transport policy before any socket work. HarvestCircle owns profile selection
    173 and signature-verified kind-0 interpretation, while the shared transport owns
    174 relay URL, destination, DNS, connection, and bounded-fetch behavior. The
    175 native FFI host owns one runtime per application core and closes it
    176 idempotently. Cancelling a close never reopens command admission, and a later
    177 close call resumes the same shutdown. Operating-system keyring calls run
    178 through an object-safe asynchronous application port and a bounded supervised
    179 worker rather than directly on an async runtime worker. Callers await one-shot
    180 responses; the dedicated operating-system thread alone drives the blocking
    181 platform adapter. Its request queue is fixed at eight entries and credential
    182 mutations carry the caller's canonical UUIDv7 durable request identity. Work
    183 cancelled while still queued has no credential effect; caller loss after work
    184 starts is an unknown outcome reconciled from the durable operation journal.
    185 Shutdown has a fixed 30-second wait and reports success only after the worker
    186 thread is joined; a timeout remains recovery-required and a later close resumes
    187 the same drain.
    188 
    189 Credential creation is native and atomic: macOS uses create-only Keychain
    190 insertion, while Linux uses Secret Service creation with replacement disabled.
    191 The stored zeroizing envelope binds the creating durable operation to the
    192 secret. Exact same-operation replay is idempotent only when the complete
    193 envelope matches; another operation conflicts and never overwrites the existing
    194 credential. No compatibility path reads the former plaintext credential shape.
    195 
    196 The state database initializes at schema v1 and applies the pinned schema-v2
    197 operation-journal and schema-v3 public evidence migrations before host exposure.
    198 Terminal receipts carry an explicit completion time and remain replayable for
    199 exactly seven days.
    200 Admission caps unfinished operations at 1,024 and all journal rows at 4,096,
    201 deletes at most 256 expired terminal receipts in one transaction, reserves each
    202 accepted operation's terminal row in place, and never evicts an in-window
    203 receipt. The migrations, resulting tables and guards, and all three schema
    204 snapshots are checksum-pinned. Invalid legacy state is refused without replacement;
    205 failed migration transactions roll back atomically.
    206 
    207 Public listing versions retain their exact signed wire, full unsigned event
    208 timestamps, tolerant admission result, and first named provenance without
    209 installing an account or local signer. Loads re-verify bounded original wire.
    210 One durable public payload meter admits at most 4,096 versions and 120 MiB of
    211 ordinary logical payload within a 128 MiB total, preserving an 8 MiB recovery
    212 reserve. Exact-ID duplicates consume no additional capacity; no automatic
    213 eviction or recovery bypass is exposed.
    214 
    215 ## Project documentation
    216 
    217 The consuming Radroots monorepo owns normative HarvestCircle specifications,
    218 decisions, handoffs, reviews, and qualification evidence under
    219 `docs/oss/harvestcircle/`. This standalone source tree remains independently
    220 cloneable, buildable, testable, and packageable without private parent code,
    221 contracts, documentation, unpublished artifacts, sibling checkouts, or absolute
    222 host paths. Parent orchestration is optional integration evidence and must
    223 invoke the capsule's standalone commands; it does not replace them. Do not add
    224 `docs/`, `spec/`, `.github/`, or `.act/` roots inside this repository.
    225 
    226 ## Security
    227 
    228 Do not submit secret keys, nsec values, signer secrets, or decrypted private
    229 contracts in issues or logs.
    230 
    231 See `SECURITY.md`.
    232 
    233 ## Licence
    234 
    235 HarvestCircle is licensed under GPL-3.0-only. See `LICENSE` and `LICENSES/`.