commit 9875810912e604c347b7c97cfd39dc91e6a1d5d1
parent f1c90b3abf3e04e9d0850753242770022ccfd36d
Author: triesap <tyson@radroots.org>
Date: Sun, 4 Oct 2026 02:27:46 +0000
repo: publish the two-runtime contributor map (HCR-008)
- Document native aliases and standalone versus governed command modes
- Keep planned browser ownership and extension custody distinct
- Preserve optional parent orchestration and exact-tree source archives
- Retain compatibility contracts and deferred qualification boundaries
Diffstat:
| M | CONTRIBUTING.md | | | 55 | ++++++++++++++++++++++++++++++++++++++++++++++++++++--- |
| M | README.md | | | 89 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---------------- |
| M | SECURITY.md | | | 28 | ++++++++++++++++++++++++++++ |
3 files changed, 151 insertions(+), 21 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -7,13 +7,35 @@ repository is consumed by the Radroots monorepo, also read the relevant
normative material under its `docs/oss/harvestcircle/` tree. Standalone changes
must not add normative documentation roots to this repository.
+## Runtime ownership
+
+Native presentation belongs in `app/`; product-specific Rust, SQLx persistence,
+native signing and OS keyring orchestration belong in `core/`. Root Gradle and
+native configuration retain their existing ownership. Keep generated UniFFI
+bindings derived from the canonical Rust producer.
+
+The browser runtime is planned in `web/` with SvelteKit, strict TypeScript,
+static output, and web-owned package inputs. Its IndexedDB, sessions, explicit
+extension signing, and Applesauce Nostr adapters are separate from native
+storage, custody, and FFI. No browser build or check lane exists yet. Follow
+`web/AGENTS.md` before implementing it; ordinary browser work must not depend
+on Cargo, Gradle, native binaries, or parent artifacts.
+
+Shared public conformance vectors are planned under `contracts/interop/`.
+They test the exact pinned Radroots semantics rather than establish new shared
+protocol policy. Browser and interop qualification remain pending real runners
+and assertions.
+
## Development flow
-1. Use the current development branch policy.
+1. Use the current development branch policy and work from this capsule root.
2. Make one coherent change at a time.
3. Add or update tests.
-4. Run focused checks.
-5. Run:
+4. Run focused checks for the affected runtime and repository boundaries.
+ Native `make native-doctor`, `make native-dev`, `make native-check`,
+ `make native-build`, and `make native-package-check` alias the existing
+ native targets without changing their prerequisites or evidence rules.
+5. In the standalone native lane, run `make native-doctor`, then:
```sh
make format
@@ -26,6 +48,26 @@ make check
7. Do not include secrets or private event plaintext.
8. Document intentional architecture deviations.
+Standalone is the default build mode and requires no extbuild or private
+parent. Where governed execution is required, run `cargo extbuild doctor`
+first and use `BUILD_MODE=governed` on the native targets. Existing
+`governed-check`, `governed-integration-check`, `governed-development-check`,
+and `governed-linux-x86_64-development-check` select their governed native
+lanes. Follow the README for development qualification; package/release checks
+remain deferred and require separate candidate authority.
+
+Parent orchestration may invoke these standalone lanes for integration, but
+must not become a build/test prerequisite. Keep normative records in the
+consuming parent's documentation; do not add `docs/`, `spec/`, `.github/`, or
+`.act/` here. Standalone inputs must not require private contracts, unpublished
+artifacts, implicit sibling checkouts, or absolute host paths.
+
+Preserve the artifact-v3 exact clean Git-tree archive contract, including
+tracked browser source. Do not relabel a native-only filtered bundle as an
+exact-tree archive. Record actual revisions and runtime inputs, and distinguish
+fresh checks from reused evidence. Production archives and release qualification
+remain deferred and unclaimed.
+
## Commit style
```text
@@ -36,3 +78,10 @@ make check
Changes to FFI, product coordinates, storage migrations, or future Radroots
event contracts require explicit compatibility review.
+
+Preserve native runtime behavior, persisted paths,
+installation/keyring identities, schema v3, storage API v3, FFI v4.5, snapshot
+v1, migrations, custody, and the exact Radroots source pin. HCAV-021 and later
+desktop availability work remain paused. The existing HCP/HCR checkpoints,
+product/design acceptance obligations, and eleven planned browser routes remain
+in force; repository guidance does not qualify the product or resume them.
diff --git a/README.md b/README.md
@@ -30,8 +30,8 @@ commitments, a selectable open reference authority, pickup, and proof.
An isolated browser prototype is planned under `web/`, using SvelteKit,
strict TypeScript, and static output. The prototype is not implemented and
has no browser build or run commands yet. It will use separate browser
-storage and sessions, explicit extension identity and signing, and Applesauce
-for generic Nostr behavior. Shared Radroots contracts must conform to the
+IndexedDB storage and sessions, explicit extension identity and signing without
+raw private-key custody, and Applesauce for generic Nostr behavior. Shared Radroots contracts must conform to the
exact pinned public Rust oracle without requiring native binaries or the
consuming monorepo to build the browser application.
@@ -40,27 +40,76 @@ commands, database/schema/API, operating-system keyring custody, and exact
Radroots dependency pin. Desktop availability work beyond HCAV-020 remains
paused. See `web/AGENTS.md` for the browser source boundary.
-## Build
+## Contributor entry points
-Prerequisites include JDK 21, Rust 1.97.1, and platform packaging tools.
+Run commands from the standalone HarvestCircle repository root.
+
+| | Native desktop (implemented) | Browser (planned) |
+|---|---|---|
+| Source | Kotlin/Compose in `app/`, product Rust in `core/`, root Gradle inputs | SvelteKit with strict TypeScript and static output in `web/` |
+| State and custody | SQLx service database, OS keyring, generated UniFFI boundary | Separate IndexedDB and sessions; explicit extension identity/signing without raw private-key custody |
+| Start | `make native-doctor`, then `make native-dev` | Read `web/AGENTS.md`; no browser install, run, build, or check commands are implemented yet |
+| Check/build | `make native-check`, `make native-build` | Working standalone commands will be documented after implementation and verification |
+
+Native prerequisites include JDK 21, Rust 1.97.1, and platform packaging tools.
+Node is not a native prerequisite. The `native-*` targets are recipe-free
+aliases of the existing native targets:
+
+| Alias | Existing target |
+|---|---|
+| `native-doctor` | `doctor` |
+| `native-dev` | `dev` |
+| `native-check` | `check` |
+| `native-build` | `build` |
+| `native-package-check` | `package-check` |
+
+Unqualified `doctor`, `dev`, `check`, `build`, and `package-check` retain their
+native meanings. The default `BUILD_MODE=standalone` lane runs without
+extbuild or a private parent checkout. For example:
+
+```sh
+make native-doctor
+make native-check
+make native-build
+```
+
+For an extbuild-governed lane, run the diagnostic before mutating checks and
+select `BUILD_MODE=governed`; aliases inherit the selected mode:
```sh
-make doctor
-make check
-make build
-make governed-development-check
+cargo extbuild doctor
+make BUILD_MODE=governed native-check
```
-These commands always use the standalone contributor lane. Use
-`make governed-check` or `make governed-integration-check` when a narrower
-extbuild-governed lane is required. The full active development milestone uses
+`make governed-check` and `make governed-integration-check` also select governed
+mode for their existing native checks. The active development milestone uses
`make governed-development-check` on macOS aarch64 and
-`make governed-linux-x86_64-development-check` for Linux x86_64. It verifies
-source, runtime, generated bindings, the public storage API, the exact Radroots
-source lock, the single SQLx-selected SQLite linkage, and offline license/source
-policy. Network advisory services, package assembly, release evidence, signing,
-notarization, Nix, and OCI qualification remain deferred and unclaimed until a
-release candidate is declared with fresh authority.
+`make governed-linux-x86_64-development-check` for Linux x86_64. These targets
+route their build/check commands through extbuild and verify source, runtime,
+generated bindings, the public storage API, the exact Radroots source lock,
+the single SQLx-selected SQLite linkage, and offline license/source policy.
+
+`native-package-check` retains the full existing package-check prerequisites
+and clean-candidate evidence rules; it is not a routine development check.
+Package assembly, production source archives, release evidence, network
+advisory services, signing, notarization, Nix, and OCI qualification remain
+deferred and unclaimed until a release candidate is declared with fresh
+authority. Listing a target does not authorize its deferred effects.
+
+## Conformance and source provenance
+
+Planned public test vectors under `contracts/interop/` will compare browser
+Radroots adapters with the exact pinned public Rust oracle. Ordinary browser
+conformance will use checked vectors without invoking native tools; explicit
+interop qualification will execute both real consumers. These browser and
+interop lanes are not implemented or qualified yet.
+
+The native artifact contract v3 requires an exact clean Git-revision tree
+source archive, including newly tracked `web/` files. A native-only filtered
+bundle cannot satisfy that whole-tree contract. Source archives are distinct
+from compiled desktop packages and future static website output. A new source
+revision changes provenance even when native runtime inputs are unchanged;
+it does not imply byte-identical binaries or production archive qualification.
## Development branch
@@ -139,7 +188,11 @@ eviction or recovery bypass is exposed.
The consuming Radroots monorepo owns normative HarvestCircle specifications,
decisions, handoffs, reviews, and qualification evidence under
`docs/oss/harvestcircle/`. This standalone source tree remains independently
-buildable and testable without that documentation tree.
+cloneable, buildable, testable, and packageable without private parent code,
+contracts, documentation, unpublished artifacts, sibling checkouts, or absolute
+host paths. Parent orchestration is optional integration evidence and must
+invoke the capsule's standalone commands; it does not replace them. Do not add
+`docs/`, `spec/`, `.github/`, or `.act/` roots inside this repository.
## Security
diff --git a/SECURITY.md b/SECURITY.md
@@ -22,6 +22,34 @@ Security-sensitive areas include:
- package provenance;
- dependency policy.
+## Runtime boundaries
+
+The implemented native runtime keeps private keys and signing behind the
+UniFFI boundary with operating-system keyring custody. Kotlin handles opaque
+identifiers and bounded public data. Native SQLx state, migrations, recovery,
+installation identities, and FFI compatibility retain their existing contracts.
+
+The planned browser runtime uses explicit extension identity/signing without
+raw private-key custody. Its IndexedDB and sessions are separate from the
+native database and keyring. Browser-specific threats include XSS, extension
+interaction, private-session teardown, inbox ownership/readiness, and private
+message authentication. Applesauce adapters and pure Radroots contract adapters
+must follow `web/AGENTS.md`; the browser implementation and its security
+qualification remain pending.
+
+Keep private AUTH, decrypted messages, and private unsent plaintext out of
+public caches, metadata, logs, analytics, static output, and long-lived UI
+state. Browser private unsent plaintext stays in memory. Identity, signing,
+and publication require explicit user action; a displayed name or message body
+is not identity evidence. Reports and tests must distinguish controlled test
+providers from real extension, relay, and independent-client qualification.
+
+Source archives bind the complete exact clean Git tree under native artifact
+contract v3, including tracked browser source. Compiled native packages and
+future static website output have separate payload boundaries; neither may
+include secrets, local databases, private transcripts, or parent documents.
+Production archive and release qualification are deferred and unclaimed.
+
## Expectations
Reports should include: