AGENTS.md (5877B)
1 # radrootsd — agent specification 2 3 ## Scope and authority 4 5 - This file applies to the complete standalone `radrootsd` repository. A 6 closer `AGENTS.md` overrides it only for that subtree. 7 - This repository owns the public `radrootsd` daemon. Keep it cloneable, 8 inspectable, buildable, testable, and operable from its checked-in source and 9 public dependency surface. 10 - Read `README`, `Cargo.toml`, `radroots.lib.source-lock.v1.toml`, the relevant 11 implementation, and nearby tests before changing behavior. Treat checked-in 12 manifests, lockfiles, source locks, tests, and public protocol behavior as 13 implementation authority; do not invent private or parent-repository 14 requirements. 15 - Preserve exact public Git dependency revisions and source-lock agreement. 16 Never replace them with sibling paths, unpublished artifacts, private 17 repositories, or ambient monorepo state. 18 19 ## Repository boundaries 20 21 - Keep daemon lifecycle, configuration, path resolution, identity storage, 22 service state, domain policy, and network transports explicit and separate. 23 - `src/app/**` owns process-facing CLI, configuration, paths, identity-storage, 24 and runtime composition. `src/core/**` owns daemon state and protocol policy. 25 `src/host_nostr.rs` owns the private upstream Nostr client edge, while 26 `src/transport/**` owns typed daemon transport protocols and JSON-RPC/Nostr 27 ingress and egress. Do not move policy into transport glue or process 28 behavior into reusable core modules. 29 - Preserve typed JSON-RPC and NIP-46 boundaries. Public Nostr behavior must 30 remain protocol-interoperable, and signed events must retain their author, 31 canonical event-id, and signature verification guarantees. 32 - Do not make this repository responsible for platform-wide release contracts, 33 builder selection, publication, promotion, deployment transport, or private 34 dependency coordination. 35 - `.github/**` and capsule-local CI workflows are forbidden; keep validation 36 forge-agnostic, and place any required monorepo orchestration exclusively 37 under the parent monorepo's root `.act/**` authority. 38 - Do not add or retain tracked `docs/**` or `.act/**`. Keep standalone 39 contributor and operator guidance in `README` or `AGENTS.md`, and keep 40 machine authority in explicit repository-root contracts. 41 42 ## Change discipline 43 44 - Prefer the smallest coherent target-state change. Do not mix unrelated 45 cleanup, speculative abstractions, compatibility scaffolding, or roadmap 46 work into the same checkpoint. 47 - Service hardening is clean-slate. Do not add or preserve prototype 48 configuration readers, environment-file configuration, JSON or JSONL mutable 49 service state, fallback path searches, compatibility aliases, deprecated 50 APIs or re-exports, dual wire encodings, or old/new behavior switches. Update 51 affected callers directly. 52 - Use exact stable Rust and MSRV `1.99.0`, edition `2024`, and resolver `3`. 53 Keep current package minimums, the stable selector and Cargo metadata aligned. 54 Preserve original compiler identities in frozen execution history and the 55 dedicated nightly API tooling. Compiler minimums alone do not qualify Nix 56 acquisition or a new release candidate. Use dependency versions and feature 57 choices from `Cargo.toml`. 58 - Prefer typed models, explicit state transitions, deterministic behavior, 59 narrow side effects, and precise error enums. Avoid hidden production 60 panics. Avoid `unsafe`; if it is strictly necessary, document the invariant 61 next to the smallest possible unsafe block. 62 - Keep `lib.rs` and `main.rs` thin. Put reusable behavior in focused modules, 63 and inject clocks, entropy, transports, and other nondeterministic inputs 64 where tests need control. 65 - Bound requests, responses, queues, collections, retries, and retained 66 diagnostics. Make startup, shutdown, interruption, recovery, and partial 67 failure deterministic and observable. 68 69 ## Security and data handling 70 71 - Never expose secrets, private keys, credentials, tokens, invite codes, 72 private identifiers, sensitive user data, or sensitive event content in 73 source, logs, errors, status output, tests, fixtures, docs, or examples. 74 - Keep key material and identity state behind narrow ownership boundaries; 75 zeroize sensitive buffers where the existing type contract supports it. 76 - Reject ambiguous or invalid configuration, paths, RPC input, event data, and 77 transport responses. Do not silently fall back, broaden permissions, or 78 accept partially verified signed content. 79 80 ## Validation 81 82 - Through RCLD-RSHR-170, use the native standalone lanes: `cargo fmt --all 83 --check`, `cargo check --workspace --all-targets --locked`, `cargo test 84 --workspace --all-targets --locked`, `cargo clippy --workspace --all-targets 85 --locked -- -D warnings`, warnings-denied Rustdoc, and 86 `scripts/verify-boundaries.sh` plus `scripts/verify-supply-chain.sh`. Route 87 them through extbuild when it is enabled. Nix and OCI remain deferred and 88 unclaimed. 89 - The supply-chain gate uses exact cargo-deny 0.19.8 and cargo-vet 0.10.2. Its 90 checked-in exemptions are visible accepted review debt, not claims of 91 independent source audits; only the justified Nostr 0.44 advisory exceptions 92 are allowed. 93 - Add deterministic tests for new behavior, failure modes, parsing, recovery, 94 protocol verification, and security boundaries. Prefer stable public or 95 repo-owned interfaces over implementation-detail tests. 96 - If a lane cannot run, report the exact command, failure, and affected 97 confidence. Never claim a check passed unless it completed successfully. 98 99 ## Commits and irreversible actions 100 101 - Keep commits focused and reviewable. Use 102 `<scope>: <imperative summary>` unless a more specific repository convention 103 is added later. 104 - Do not publish, push, tag, sign, deploy, rotate credentials, or mutate remote 105 service or repository state without explicit authority.