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/`.