commit 752a5981330042a4208e938e74a299163656b9d9
parent db87c5488dd92151b691d51d46247ec54c872a9a
Author: triesap <tyson@radroots.org>
Date: Sat, 3 Oct 2026 20:21:42 +0000
repo: split root and subtree agent responsibilities (HCR-002)
- Scope common product guidance separately from native runtime boundaries
- State browser IndexedDB ownership and independent verification rules
- Enforce required guidance in real repository and qualification audits
- Reject weakened boundaries and invalid guidance with mutation fixtures
Diffstat:
3 files changed, 218 insertions(+), 4 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
@@ -5,8 +5,9 @@ A more specific `AGENTS.md` may refine them for its subtree.
## Repository role and source boundary
-This repository owns the public HarvestCircle desktop product: the
-Kotlin/Compose presentation shell, desktop lifecycle, client-side state,
+This repository owns the public HarvestCircle product with separate native
+and browser runtimes. The native runtime owns the Kotlin/Compose presentation
+shell, desktop lifecycle, client-side state,
generated UniFFI integration, host packaging, product-specific Rust core, and
their tests. The Rust workspace under `core/**` owns HarvestCircle application,
domain, runtime, persistence, Nostr-adapter, preference, native FFI, and UniFFI
@@ -105,7 +106,19 @@ source. Planned web command surfaces must be implemented and verified before
being advertised as available. HCAV-021 and later desktop availability work
remain paused; authorizing `web/**` does not resume them.
-## Application and security boundaries
+## Common application and security boundaries
+
+Both runtimes preserve protocol fidelity, bounded resource use, explicit
+user-authorized effects, and independent buildability. Keep secret material
+out of logs, crash text, analytics, filenames, public caches, and long-lived
+presentation state. Keep lifecycle work structured, cancelable, and scoped;
+never infer external mutation from environment state. Presentation code is
+client orchestration, not domain or shared-library authority. Tests and
+qualification records must identify actual checked inputs and executed lanes.
+Browser custody and persistence follow `web/AGENTS.md`; native storage, OS
+custody, transport, and ABI rules below apply only to the native runtime.
+
+## Native runtime boundaries
- Product state is bound only through `radroots_runtime_paths::RuntimeContext`
for service `harvestcircle` and instance `desktop`; the canonical database
@@ -190,6 +203,14 @@ configuration before editing. Make one coherent, reviewable change at a time;
keep implementation, tests, generated outputs, dependency evidence, and public
behavior aligned while preserving unrelated work.
+The currently implemented root Make and Gradle commands below qualify the
+native runtime only. They do not qualify a browser application. Browser checks
+follow `web/AGENTS.md` once their actual standalone scripts exist; do not wire
+browser dependencies into native commands or require native tools for ordinary
+browser install, check, or build. Root guidance and audit changes require fresh
+affected native and repository checks. Browser evidence must be reported as
+unimplemented until the corresponding real checks exist and run.
+
The root `Makefile` is the standalone command surface and its durable behavior
belongs in Gradle or public producer tools. Standalone targets never invoke or
probe extbuild, even when it is installed. Explicit `governed-*` targets run a
@@ -228,7 +249,7 @@ Do not reset, discard, rewrite, push, tag, sign, publish, deploy, package for
distribution, change signing/notarization identities, or rotate credentials
without the corresponding explicit authority.
-The change is complete only when it is implemented at the correct desktop or
+The change is complete only when it is implemented at the correct runtime or
public producer boundary, the relevant standalone lanes are green, locks and
generated evidence are fresh, forbidden roots remain absent, and final review
finds no secret exposure, private dependency, stale native artifact, hidden
diff --git a/tools/xtask/src/lib.rs b/tools/xtask/src/lib.rs
@@ -292,10 +292,69 @@ fn repo_audit(root: &Path, inventory: &Inventory, findings: &mut Vec<String>) {
}
}
}
+ runtime_guidance_audit(root, findings);
git_source_policy(root, findings);
native_runtime_boundary(root, findings);
}
+// These small text contracts guard instruction scope, not runtime ownership or
+// product implementation. Keep the existing native/source checks independent.
+fn runtime_guidance_audit(root: &Path, findings: &mut Vec<String>) {
+ let contracts: &[(&str, &[&str])] = &[
+ (
+ "AGENTS.md",
+ &[
+ "public HarvestCircle product with separate native and browser runtimes",
+ "## Common application and security boundaries",
+ "## Native runtime boundaries",
+ "native storage, OS custody, transport, and ABI rules below apply only to the native runtime",
+ "SQLx is the only high-level SQLite library.",
+ "schema v3, storage API v3, FFI v4.5, snapshot v1, custody, and the exact Radroots source pin remain unchanged",
+ "Private keys and signing operations remain behind the generated native boundary.",
+ "platform/ABI",
+ "must not depend on private parent code",
+ "All `docs/**`, `spec/**`, `.github/**`, and `.act/**` paths are forbidden here.",
+ "HCAV-021 and later desktop availability work remain paused",
+ "do not wire browser dependencies into native commands or require native tools for ordinary browser install, check, or build",
+ ],
+ ),
+ (
+ "web/AGENTS.md",
+ &[
+ "instructions apply only to `web/**`",
+ "guidance alone is not an implemented application or a passing qualification",
+ "Browser persistence uses bounded IndexedDB",
+ "desktop SQLx database, operating-system keyring, and UniFFI implementation",
+ "Identity and signing require explicit extension interaction",
+ "Generic Nostr belongs in `src/lib/nostr`, using qualified Applesauce",
+ "WASM launch dependency",
+ "dependency on parent documentation",
+ "Do not introduce `docs/**`, `spec/**`, `.github/**`, or `.act/**` anywhere in this standalone repository.",
+ "do not invent commands or claim an absent web suite passed",
+ ],
+ ),
+ ];
+ for (path, markers) in contracts {
+ let source = match bounded_no_follow_bytes(root, Path::new(path), 64 * 1024)
+ .and_then(|bytes| String::from_utf8(bytes).map_err(|error| error.to_string()))
+ {
+ Ok(source) => source,
+ Err(error) => {
+ findings.push(format!("{path}: unable to read runtime guidance: {error}"));
+ continue;
+ }
+ };
+ let text = source.split_whitespace().collect::<Vec<_>>().join(" ");
+ for marker in *markers {
+ if !text.contains(marker) {
+ findings.push(format!(
+ "{path}: required runtime guidance is missing: {marker}"
+ ));
+ }
+ }
+ }
+}
+
fn native_runtime_boundary(root: &Path, findings: &mut Vec<String>) {
let domain_lib = root.join("core/crates/harvestcircle_domain/src/lib.rs");
if !domain_lib.is_file() {
@@ -1769,6 +1828,136 @@ mod tests {
use super::*;
use std::time::{SystemTime, UNIX_EPOCH};
+ const ROOT_GUIDANCE: &str = include_str!("../../../AGENTS.md");
+ const WEB_GUIDANCE: &str = include_str!("../../../web/AGENTS.md");
+
+ fn guidance_findings(root_source: &str, web_source: &str) -> Vec<String> {
+ let root = fixture("runtime-guidance");
+ write(&root, "AGENTS.md", root_source);
+ write(&root, "web/AGENTS.md", web_source);
+ let inventory = Inventory::load(&root).expect("guidance inventory");
+ let mut findings = Vec::new();
+ repo_audit(&root, &inventory, &mut findings);
+ fs::remove_dir_all(root).expect("remove guidance fixture");
+ findings
+ .into_iter()
+ .filter(|finding| finding.contains("guidance"))
+ .collect()
+ }
+
+ #[test]
+ fn current_runtime_guidance_preserves_separate_boundaries() {
+ let findings = guidance_findings(ROOT_GUIDANCE, WEB_GUIDANCE);
+ assert!(findings.is_empty(), "{findings:#?}");
+ assert!(ROOT_GUIDANCE.contains("## Native runtime boundaries"));
+ assert!(WEB_GUIDANCE.contains("IndexedDB"));
+ }
+
+ #[test]
+ fn runtime_guidance_accepts_wrapping_and_rejects_missing_or_invalid_text() {
+ assert!(
+ guidance_findings(
+ &ROOT_GUIDANCE
+ .split_whitespace()
+ .collect::<Vec<_>>()
+ .join("\n"),
+ &WEB_GUIDANCE
+ .split_whitespace()
+ .collect::<Vec<_>>()
+ .join("\n"),
+ )
+ .is_empty()
+ );
+ let root = fixture("invalid-guidance");
+ write(&root, "AGENTS.md", ROOT_GUIDANCE);
+ let mut findings = Vec::new();
+ runtime_guidance_audit(&root, &mut findings);
+ assert!(
+ findings.iter().any(
+ |finding| finding.starts_with("web/AGENTS.md: unable to read runtime guidance")
+ )
+ );
+ write(&root, "web/AGENTS.md", WEB_GUIDANCE);
+ fs::write(root.join("AGENTS.md"), [0xff]).expect("invalid UTF-8 guidance");
+ findings.clear();
+ runtime_guidance_audit(&root, &mut findings);
+ assert!(
+ findings
+ .iter()
+ .any(|finding| finding.starts_with("AGENTS.md: unable to read runtime guidance"))
+ );
+ fs::remove_dir_all(root).expect("remove invalid guidance fixture");
+ }
+
+ #[test]
+ fn runtime_guidance_rejects_lost_native_boundaries() {
+ for marker in [
+ "SQLx is the only high-level SQLite library.",
+ "schema v3, storage API v3, FFI v4.5, snapshot v1, custody,",
+ "exact Radroots source pin",
+ "platform/ABI",
+ "Private keys and signing operations remain behind the generated native",
+ ] {
+ assert!(ROOT_GUIDANCE.contains(marker), "fixture marker: {marker}");
+ let altered = ROOT_GUIDANCE.replace(marker, "native boundary removed");
+ assert!(
+ !guidance_findings(&altered, WEB_GUIDANCE).is_empty(),
+ "accepted lost native rule: {marker}"
+ );
+ }
+ }
+
+ #[test]
+ fn runtime_guidance_rejects_lost_browser_boundaries() {
+ for marker in [
+ "IndexedDB",
+ "explicit\n extension interaction",
+ "Applesauce",
+ "operating-system keyring",
+ "UniFFI implementation",
+ "do not invent commands or claim an absent web suite passed",
+ ] {
+ assert!(WEB_GUIDANCE.contains(marker), "fixture marker: {marker}");
+ let altered = WEB_GUIDANCE.replace(marker, "browser boundary removed");
+ assert!(
+ !guidance_findings(ROOT_GUIDANCE, &altered).is_empty(),
+ "accepted lost browser rule: {marker}"
+ );
+ }
+ }
+
+ #[test]
+ fn runtime_guidance_rejects_relaxed_source_and_product_scope() {
+ for marker in [
+ "All `docs/**`,",
+ "`.github/**`",
+ "`.act/**`",
+ "must not depend on private parent code",
+ "HCAV-021",
+ ] {
+ assert!(ROOT_GUIDANCE.contains(marker), "fixture marker: {marker}");
+ let altered = ROOT_GUIDANCE.replace(marker, "permitted");
+ assert!(
+ !guidance_findings(&altered, WEB_GUIDANCE).is_empty(),
+ "accepted relaxed root rule: {marker}"
+ );
+ }
+ for marker in [
+ "Do not introduce `docs/**`",
+ "`.github/**`",
+ "`.act/**`",
+ "dependency on parent documentation",
+ "WASM launch dependency",
+ ] {
+ assert!(WEB_GUIDANCE.contains(marker), "fixture marker: {marker}");
+ let altered = WEB_GUIDANCE.replace(marker, "permitted");
+ assert!(
+ !guidance_findings(ROOT_GUIDANCE, &altered).is_empty(),
+ "accepted relaxed subtree rule: {marker}"
+ );
+ }
+ }
+
#[test]
fn commands_are_exact_and_unknown_values_fail_closed() {
assert_eq!(
diff --git a/web/AGENTS.md b/web/AGENTS.md
@@ -14,6 +14,10 @@ guidance alone is not an implemented application or a passing qualification.
- Preserve native source, commands, manifests, locks, generated inputs,
schema/API, runtime paths, custody, and exact public Radroots source pin.
Native build integration requires its own explicit authorized step.
+- Browser persistence uses bounded IndexedDB under the approved browser
+ resource contracts. Public drafts are strings; private unsent plaintext
+ stays memory-only. Native schema, quotas, and backup/restore wrappers do
+ not govern browser storage.
- Keep browser storage and sessions separate from the desktop SQLx database,
operating-system keyring, and UniFFI implementation. No shared UI, hidden
backend, native binary, WASM launch dependency, private artifact, implicit