AGENTS.md (5610B)
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 Rust `1.97.1`, edition `2024`, and resolver `3` as declared by the 53 repository. Use dependency versions and feature choices from `Cargo.toml`. 54 - Prefer typed models, explicit state transitions, deterministic behavior, 55 narrow side effects, and precise error enums. Avoid hidden production 56 panics. Avoid `unsafe`; if it is strictly necessary, document the invariant 57 next to the smallest possible unsafe block. 58 - Keep `lib.rs` and `main.rs` thin. Put reusable behavior in focused modules, 59 and inject clocks, entropy, transports, and other nondeterministic inputs 60 where tests need control. 61 - Bound requests, responses, queues, collections, retries, and retained 62 diagnostics. Make startup, shutdown, interruption, recovery, and partial 63 failure deterministic and observable. 64 65 ## Security and data handling 66 67 - Never expose secrets, private keys, credentials, tokens, invite codes, 68 private identifiers, sensitive user data, or sensitive event content in 69 source, logs, errors, status output, tests, fixtures, docs, or examples. 70 - Keep key material and identity state behind narrow ownership boundaries; 71 zeroize sensitive buffers where the existing type contract supports it. 72 - Reject ambiguous or invalid configuration, paths, RPC input, event data, and 73 transport responses. Do not silently fall back, broaden permissions, or 74 accept partially verified signed content. 75 76 ## Validation 77 78 - Through RCLD-RSHR-170, use the native standalone lanes: `cargo fmt --all 79 --check`, `cargo check --workspace --all-targets --locked`, `cargo test 80 --workspace --all-targets --locked`, `cargo clippy --workspace --all-targets 81 --locked -- -D warnings`, warnings-denied Rustdoc, and 82 `scripts/verify-boundaries.sh` plus `scripts/verify-supply-chain.sh`. Route 83 them through extbuild when it is enabled. Nix and OCI remain deferred and 84 unclaimed. 85 - The supply-chain gate uses exact cargo-deny 0.19.8 and cargo-vet 0.10.2. Its 86 checked-in exemptions are visible accepted review debt, not claims of 87 independent source audits; only the justified Nostr 0.44 advisory exceptions 88 are allowed. 89 - Add deterministic tests for new behavior, failure modes, parsing, recovery, 90 protocol verification, and security boundaries. Prefer stable public or 91 repo-owned interfaces over implementation-detail tests. 92 - If a lane cannot run, report the exact command, failure, and affected 93 confidence. Never claim a check passed unless it completed successfully. 94 95 ## Commits and irreversible actions 96 97 - Keep commits focused and reviewable. Use 98 `<scope>: <imperative summary>` unless a more specific repository convention 99 is added later. 100 - Do not publish, push, tag, sign, deploy, rotate credentials, or mutate remote 101 service or repository state without explicit authority.