AGENT_INSTRUCTIONS.md (13286B)
1 # Radroots Core Libraries - Agent Instructions 2 3 **For repository overview and setup, see [README.md](README.md). For repository rules, see [AGENTS.md](AGENTS.md).** 4 5 This document contains detailed operational instructions for contributors and coding agents working on development, testing, and releases in the Radroots Core Libraries repository. 6 7 `AGENTS.md` is the concise repo contract. Read it first, then use this file for execution detail. 8 9 ## 1. How to use this file 10 11 - Treat `AGENTS.md` as the durable always-on contract. 12 - Use this file for interpretation, procedures, and detailed engineering expectations. 13 - If a closer subtree-specific `AGENTS.md` is added later, that file overrides root guidance for its scope. 14 - Keep durable rules short and proven; if a problem repeats, tighten the root contract instead of growing ad hoc prompt text. 15 16 ## 2. Repository operating model 17 18 This repository is a public open-source Rust workspace. Optimize for: 19 20 - portable library design 21 - deterministic behavior 22 - explicit contracts 23 - cross-target consistency 24 - clean public APIs 25 26 Stay disciplined: 27 28 - keep scope tight 29 - avoid drive-by cleanup 30 - avoid speculative abstraction 31 - avoid compatibility scaffolding unless it is explicitly required 32 - do not leave dead paths, temporary adapters, or silent fallback behavior behind 33 34 This repo is a library workspace, not an app monolith. The right default is small, durable changes that preserve clean crate boundaries. 35 Release automation should stay forge-agnostic. Keep release truth in repo-owned 36 xtask commands, native Cargo lanes, tags, and contract metadata rather than 37 committed provider-specific workflow files. Checked-in Nix surfaces are 38 deferred compatibility inputs and are not current qualification authority. 39 40 ## 3. Preflight workflow 41 42 Before editing code: 43 44 - Read `AGENTS.md`. 45 - Read this file. 46 - Read `README.md` when the change touches workflow or public surfaces. 47 - When preserving deferred Nix behavior, read `flake.nix` and the relevant 48 implementation files under `build/nix/`, but do not install, invoke, or 49 require Nix as part of current qualification. 50 - Read the relevant crate manifest, implementation files, and nearby tests before proposing a new structure. 51 - Check `git status --short`. 52 53 Before running governed build, test, check, generation, package, artifact, or 54 release-preflight commands: 55 56 - Run `cargo extbuild doctor` once for the working session. 57 - Route the command through `cargo extbuild run --`. 58 - Prefer the documented repo-owned command surface over improvised local commands. 59 60 Fail early when: 61 62 - the environment is missing required tooling 63 - the task materially changes a public contract without enough local context 64 - the working tree is contaminated in a way that changes the requested scope 65 66 ## 4. Workspace interpretation 67 68 Use this mental model: 69 70 - `crates/` 71 - library crates and workspace tooling crates 72 - keep domain logic inside the correct crate rather than spreading it across the workspace 73 - `contracts/` 74 - core-library contract metadata, release-candidate policy, coverage governance, and public conformance assets 75 - `contracts/api_baselines/` 76 - reviewed generated public Rust API surfaces 77 - `contracts/architecture/` 78 - machine-readable deviations, decisions, and compatibility-retirement authority 79 - `contracts/crates/release_v1/` 80 - historical machine catalog, inventory, graph, and checksums retained by release V2 81 - `contracts/conformance/` 82 - cross-language and cross-surface vector expectations 83 - `build/nix/`, `flake.nix`, `treefmt.nix` 84 - deferred compatibility surfaces whose evaluation and outputs are not 85 current qualification evidence 86 - `tools/xtask/` 87 - typed repo-owned automation used by canonical lanes 88 89 Do not duplicate contract knowledge between crates when `contracts/`, `contracts/conformance/`, or `tools/xtask` already owns it. 90 91 The approved successor authority is 92 `contracts/architecture/decisions/shared_sdk_refactor.v1.json`. Shared reusable 93 semantics and execution belong in Lib, with `radroots` as the facade; the SDK 94 repository consumes the owning generators and artifacts. Its complete actor, 95 host, budget and provenance requirements govern direct replacement. Target 96 metadata does not qualify current APIs, artifacts, compiler migration or a 97 consumer. Preserve original release evidence and bind actual changed inputs. 98 99 Do not add or retain tracked `docs/**`, `.github/**`, or `.act/**`. Root 100 `README.md`, `AGENTS.md`, `AGENT_INSTRUCTIONS.md`, conventional public project 101 files, package READMEs, and Rustdoc carry concise standalone guidance. Extended 102 human authority is parent-owned and is never a standalone command input. 103 104 Deviation `spec_anchors` target the Release V1 TOML and must use one of the 105 machine selectors enforced by `cargo xtask architecture`: 106 `repositories.<name>`, `repository_policy`, `release_policy`, 107 `quality_policy.coverage`, or `package.<name>`. Markdown heading fragments and 108 unresolved free-form fragments are invalid. 109 110 ## 5. Rust engineering standards 111 112 ### Core design 113 114 - Prefer pure functions and explicit data flow in core logic. 115 - Keep IO, filesystem, network, clocks, randomness, and runtime glue at the edges. 116 - Prefer data transformation pipelines over stateful orchestration when the problem is fundamentally transformational. 117 - Prefer explicit state machines and enums over ad hoc flags or loosely related booleans. 118 - Keep mutation local and minimal. 119 - Avoid hidden shared mutable state and interior mutability unless the boundary truly requires it. 120 121 ### API design 122 123 - Public APIs should make invalid states hard to represent. 124 - Prefer newtypes, enums, and dedicated structs when semantics matter. 125 - Avoid exposing dependency-specific types in public API surfaces unless that dependency is a deliberate part of the contract. 126 - Separate parsing, validation, normalization, and serialization instead of collapsing them into a single opaque function. 127 - Prefer exhaustive `match` behavior for semantic enums over wildcard-heavy control flow. 128 129 ### Errors and invariants 130 131 - Library code should not panic on normal invalid input. 132 - Reserve `unwrap`, `expect`, and panic-based control flow for tests, build scripts, or tightly proven internal invariants. 133 - Use precise typed errors for public and semantically important boundaries. 134 - Keep opaque convenience errors inside binaries, narrow tooling layers, or internal glue when appropriate. 135 - When an invariant truly cannot be violated, document it close to the code. 136 137 ### Portability and feature discipline 138 139 - Preserve `no_std` intent where the crate is designed for it. 140 - Gate `std` behavior, wasm behavior, and runtime-specific behavior explicitly and predictably. 141 - Keep feature interactions simple and testable. 142 - When a change affects native, wasm, or `std`/`no_std` parity, update the affected tests or validation flow in the same change. 143 144 ### Performance and allocation 145 146 - Borrow before cloning. 147 - Prefer `&str`, `&[u8]`, slices, and iterators when ownership is not required. 148 - Avoid unnecessary intermediate allocations. 149 - Preallocate only when the size is known or bounded meaningfully. 150 - Do not trade away clarity for micro-optimizations unless profiling or the hot-path nature of the code justifies it. 151 152 ### Module layout 153 154 - Keep `lib.rs` thin. 155 - Put heavy logic in focused modules. 156 - Avoid giant files that mix models, parsing, validation, transformations, and integration glue. 157 - Introduce traits only when they remove real duplication or encode a stable abstraction boundary. 158 - Avoid generic abstraction that makes the code harder to reason about without clear reuse value. 159 160 ### Documentation and source comments 161 162 - Do not add explanatory comments by habit. 163 - Add concise Rustdoc for non-obvious public APIs, invariants, and cross-target behavior. 164 - Keep docs aligned with the actual code and contract surface. 165 166 ## 6. Contract, conformance, and release workflow 167 168 `contracts/`, `contracts/conformance/`, and `tools/xtask` are first-class parts of the product surface, not secondary metadata. 169 170 The package authority is `contracts/crates/catalog.v2.toml`. Imported entries 171 retain their exact immutable source repository, full revision, source path, and 172 source-tree digest. A newly created repository-native package instead uses 173 `provenance_kind = "native"` and records only its 174 `introduction_tree_sha256`. Native entries begin active and private; a later 175 approved public allocation preserves that immutable provenance. Stage 176 the complete new package path before running `cargo xtask catalog check` or 177 `cargo xtask catalog write`. Before the first commit, xtask verifies the digest 178 against canonical stage-zero index tree records. After that commit, xtask 179 derives the earliest adding commit from history and verifies the same digest 180 against that commit's package tree. Later source changes do not change the 181 introduction digest, and the catalog never stores the introducing commit OID. 182 183 When a change affects exported models, transforms, identifiers, or public runtime expectations: 184 185 - update the relevant contract metadata 186 - update or add conformance vectors 187 - update repo-aware validation flows if needed 188 - keep release and export rules aligned with the new behavior 189 190 Do not change public behavior in Rust and leave contract or conformance assets stale. 191 192 Public API baselines are generated with `cargo-public-api` `0.52.0` and 193 rustdoc JSON from `nightly-2026-07-16`; the workspace's pinned stable toolchain 194 still governs package verification. From the canonical development shell, 195 regenerate one package with: 196 197 ```sh 198 RUSTC="$(rustup which --toolchain nightly-2026-07-16 rustc)" \ 199 RUSTDOC="$(rustup which --toolchain nightly-2026-07-16 rustdoc)" \ 200 RUSTUP_TOOLCHAIN=nightly-2026-07-16 \ 201 cargo +nightly-2026-07-16 public-api --manifest-path crates/<crate>/Cargo.toml \ 202 --all-features -sss \ 203 > contracts/api_baselines/<package>.txt 204 ``` 205 206 Review each baseline change with the package's machine charter and intended 207 SemVer impact. Generated listings are evidence of the Rust surface, not 208 authority to expand it. 209 210 ## 7. Canonical validation strategy 211 212 Use the smallest authoritative lane that proves the change green. 213 214 Repo-wide canonical lanes, all routed through `cargo extbuild run --`: 215 216 - `cargo check --workspace --all-targets --locked` 217 - `cargo test --workspace --all-targets --locked` 218 - `cargo clippy --workspace --all-targets --all-features -- -D warnings` 219 - `cargo doc --workspace --no-deps` 220 - `cargo xtask contract validate` 221 - `cargo xtask release preflight` 222 223 Targeted iteration, also routed through `cargo extbuild run --`: 224 225 - `cargo check -p <crate>` 226 - `cargo test -p <crate>` 227 - `cargo xtask dto-roots --check` 228 - `cargo xtask dto-roots --write` after changing configured DTO exports 229 - `cargo xtask hygiene forbidden-identifiers` 230 - `cargo xtask hygiene prototype-contracts` for the deterministic report-only 231 service-prototype census; strict mode is enabled only after the owning 232 cleanup sequence clears its findings 233 234 Validation rules: 235 236 - crate-local changes may iterate with targeted cargo commands 237 - contract, export, conformance, release, or multi-crate changes should close 238 on the applicable extbuild-routed repository-wide lanes 239 - Nix evaluation and Nix-derived package, app, check, development-shell, 240 NixOS-module, and OCI outputs remain explicitly deferred and unclaimed 241 - deterministic tests are required for new behavior and edge cases 242 - do not rely on wall-clock time, random order, external network access, or ambient machine state in unit tests 243 244 Release discipline: 245 246 - create annotated release tags that match the current versioned release contract under `contracts/releases/` 247 - keep repo-owned release commands runnable without depending on GitHub-specific workflow files 248 - when documenting release flow here, document the local repo contract rather than forge-specific orchestration 249 250 ## 8. Commit and handoff guidance 251 252 Commit messages in this repo are part of the public open-source surface. 253 254 That means: 255 256 - use `<scope>: <imperative summary>` 257 - keep the scope lowercase and meaningful 258 - keep the summary standalone and readable outside monorepo context 259 - do not reference internal repository paths, internal migration rationale, or private coordination context 260 - when using a body, leave a blank line after the summary and use `- ` bullets 261 262 Handoffs should state: 263 264 - what changed 265 - what validations ran 266 - any assumptions made 267 - any follow-up risks or missing work 268 269 ## 9. Beads and Agent Mail 270 271 If Beads is active for the task: 272 273 - use `.beads/PRIME.md` as the Beads-specific operator layer 274 - keep live execution state in Beads rather than markdown task lists 275 - do not use `bd edit` 276 - use Beads for durable multi-commit work, not as a replacement for contract docs or repo docs 277 278 If Agent Mail is active for the task: 279 280 - use `.beads/PRIME.md` for the repository coordination conventions 281 - use the active Beads issue id as the Agent Mail thread id and reservation reason when both tools are active 282 - reserve files before the first write for coordinated multi-agent work 283 - use shared build slots for long-running singleton lanes such as contract or release-preflight runs 284 285 If Beads or Agent Mail is not active, the repo still follows the same coding and validation standards; only the task-state and coordination backend changes.