lib

Core libraries for Radroots
git clone https://radroots.dev/git/lib.git
Log | Files | Refs | README

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.