radrootsd

JSON-RPC bridge for Radroots event publishing
git clone https://radroots.dev/git/radrootsd.git
Log | Files | Refs | README | LICENSE

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.