lib

commit 4cd6c3d2c48f5cd0c33c39032669013150c8ab6f
parent f9bf2d7b83782c6f6e879de31ff0a8b33f0f67e1
Author: triesap <tyson@radroots.org>
Date:   Wed, 18 Mar 2026 20:11:18 +0000

docs: align agent guidance and beads coordination

- define repository-wide agent guidance and operating rules
- document beads usage as an optional task-state and planning layer
- document agent mail coordination, reservation, and shared-lane conventions
- make beads closeout behavior conditional on configured shared state

Diffstat:
M
.beads/PRIME.md
 | 
34
+++++++++++++++++-----------------
M
AGENTS.md
 | 
122
++++++++++++++++++++++++++++++++++++++++++++++++-------------------------------
A
AGENT_INSTRUCTIONS.md
 | 
206
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

3 files changed, 298 insertions(+), 64 deletions(-)
diff --git a/.beads/PRIME.md b/.beads/PRIME.md
@@ -1,13 +1,12 @@
 # Radroots Core Libraries Beads Prime
 
-Read `AGENTS.md` first. That file remains the authoritative code and commit-style contract for this repository.
-
-## RCL
-- This repo uses RCL for multi-commit work.
-- When Beads is active, Beads is the live execution state.
-- Every goal is an epic.
-- Only the next 1-3 slices may be concrete at any time.
-- Every slice needs a clear scope, a definition of green, and one dominant verify lane.
+Read `AGENTS.md` first, then read `AGENT_INSTRUCTIONS.md`. `AGENTS.md` remains the authoritative concise contract for this repository.
+
+## Workflow
+- When Beads is active, use it as the live execution state.
+- Keep active work scoped to the smallest coherent green checkpoint.
+- For larger efforts, keep only the next few follow-up issues concrete.
+- Every issue should have a clear scope, a definition of green, and one dominant verify lane.
 - Do not create markdown TODO trackers when Beads is active.
 - Do not use `bd edit`.
 
@@ -16,15 +15,16 @@ Read `AGENTS.md` first. That file remains the authoritative code and commit-styl
 - `bd show <id>`
 - `bd update <id> --claim --json`
 - Trust cwd auto-filtering when working from a mapped crate or repo surface.
+- When working from an external parent repo or worktree, switch into this repo root before running Beads or Agent Mail commands.
 
 ## Environment Contract
 - Nix is the canonical environment contract for this workspace.
 - Prefer `nix develop` or `direnv allow` before targeted cargo work.
 - Prefer repo-owned Nix lanes over ad hoc raw commands for closeout validation.
 
-## Slice Rules
-- Keep slices small enough that one dominant verify lane can prove them green.
-- If a slice needs unrelated lanes, split it.
+## Planning Rules
+- Keep work small enough that one dominant verify lane can prove it green.
+- If a change needs unrelated lanes, split it into separate issues.
 - If new work is discovered, create it immediately and link it with `discovered-from:<parent-id>`.
 - Use stdin-based `bd create` or `bd update` forms when text contains backticks or quotes.
 
@@ -43,13 +43,13 @@ Read `AGENTS.md` first. That file remains the authoritative code and commit-styl
   - `cargo run -q -p xtask -- sdk release preflight`
 
 ## Closeout Guidance
-- any contract, export, conformance, release, flake, or multi-crate slice should close on a Nix lane, not on targeted cargo alone
-- crate-local slices may iterate with targeted cargo commands, but should still finish with the narrowest canonical Nix lane that proves the change green
+- any contract, export, conformance, release, flake, or multi-crate issue should close on a Nix lane, not on targeted cargo alone
+- crate-local issues may iterate with targeted cargo commands, but should still finish with the narrowest canonical Nix lane that proves the change green
 
-## RCL-Swarm
-- In `rcl-swarm`, the Beads issue id is the Agent Mail thread id.
+## Coordination
+- If Agent Mail is active for the session, use the Beads issue id as the thread id.
 - Use the same Beads issue id as the reservation reason.
-- Reserve files before the first write.
+- Reserve files before the first write when coordinating across agents.
 - Use build slots for long-running singleton resources when needed:
   - `rr-contract`
   - `rr-release-preflight`
@@ -57,4 +57,4 @@ Read `AGENTS.md` first. That file remains the authoritative code and commit-styl
 
 ## End Of Session
 - `bd close <id> --reason "..."`
-- `bd dolt push`
+- if a Beads remote or shared state target is configured for the session, run `bd dolt push`
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,48 +1,76 @@
-# Rad Roots - Code Directives
-
-## Purpose
-- The crates are a shared Rust library layer used by Radroots networking apps and libraries across web (wasm), native, daemons, and embedded systems. Prioritize portability, correctness, and low overhead.
-
-## Scope
-- Applies to the workspace in this repository.
-
-## Workspace Architecture
-- core: no_std core value types (money, currency, quantity, percent, discount, unit) with serde/typeshare gates.
-- types: API wrapper types (IError, IResult, IResultList) with ts-rs support.
-- events: Nostr event models (post, profile, job, tags, kinds) with ts-rs support.
-- events-codec: encode/decode for events (jobs, profiles) for nostr payloads.
-- events-indexed: manifest/checkpoint/types for indexed event archives (typeshare + serde gates).
-- nostr: Nostr utilities (filters, tags, relays, parsing) and SDK adapters.
-- log: tracing-based logging helpers with std/no_std split.
-- runtime: config loading, JSON IO, tracing init, signals, CLI helpers.
-- identity: identity spec + load/generate utilities, built on runtime.
-- net-core: networking core, build info, config, optional tokio runtime and Nostr client.
-- net: thin re-export of net-core.
-- sql-core: SQL executor trait + migrations for native/web/embedded targets.
-- sql-wasm-bridge: wasm JS bridge for exec/query and savepoint transactions.
-- sql-wasm-core: wasm-bindgen exports + error marshaling for SQL.
-- tangle-db-schema: Tangle schema models and relation types (ts-rs bindings).
-- tangle-db: SQL access layer for Tangle schema, migrations, backup/restore.
-- tangle-db-wasm: wasm-bindgen exports for Tangle SQL operations.
-- trade: trade/listing domain models and tags.
-
-## Rust Code Directives
-- Toolchain: Rust 1.88, edition 2024; use workspace versions from the root Cargo.toml.
-- Portability: preserve no_std patterns; gate std usage with cfg(feature = "std") and use alloc when needed.
-- Safety: avoid unsafe; prefer safe, explicit APIs. Add #![forbid(unsafe_code)] on new crates/modules.
-- Public API: keep Radroots* prefix; avoid hidden panics; return Result/Option for fallible ops; use precise error enums (thiserror where appropriate).
-- Features: keep serde/typeshare/ts-rs derives behind existing feature gates and in the current style; ensure feature combinations compile (no_std, std, wasm).
-- Events modules: in `crates/events`, each `.rs` file must map to a single Nostr kind (or a single NIP-defined kind range), and a kind must not be defined in multiple modules.
-- Generated outputs: treat */bindings/ts/src/types.ts as generated; do not hand-edit.
-- Performance: borrow over clone, avoid intermediate allocations, preallocate when sizes are known, and prefer iterators over indexing loops.
-- DRY: consolidate shared logic into core/types/events-codec or dedicated helpers.
-- Parity: maintain feature parity across native/wasm layers when adding SQL or Tangle APIs.
-- Module layout: keep lib.rs as a module manifest and re-export surface; avoid heavy logic in lib.rs.
-- Testing: add or update unit tests for new behavior and edge cases, especially around parsing, invariants, conversions, and rounding.
-
-## Git Commit Directives
-- Format commits like the latest reference: `<scope>: <imperative summary>` (scope = crate or subsystem, lowercase).
-- Leave a blank line after the summary.
-- Add a bullet list of key changes, each prefixed with `- `, matching the structure of the last commit.
-- Keep the summary concise; use bullets for notable changes, tests run, and compatibility notes.
+# Radroots Core Libraries - Agent Specification
+
+See [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for full instructions.
+
+This file exists for compatibility with tools that look for AGENTS.md.
+
+## 1. Scope and hierarchy
+
+- This file applies to the full repository.
+- Keep this file concise and durable.
+- Put detailed procedures, examples, and extended guidance in `AGENT_INSTRUCTIONS.md`.
+- If a closer directory-level `AGENTS.md` is added later, it overrides this file for that subtree.
+
+## 2. Repository operating model
+
+- This is a public open-source library workspace; optimize for durable library design, portability, determinism, and explicit contracts.
+- Prefer clean target-state changes over compatibility scaffolding unless compatibility is explicitly required.
+- Stay within the requested scope and the smallest coherent file set.
+- Do not fold unrelated cleanup, speculative refactors, or roadmap work into the same change.
+- Do not create hidden task trackers in markdown checklists, source comments, or stray notes.
+- Keep commits and handoff language standalone and open-source-readable; do not reference internal monorepo paths, internal mapping rationale, or private repository context.
+
+## 3. Preflight before edits
+
+Before editing code:
+
+- Read this file, `AGENT_INSTRUCTIONS.md`, `README.md`, `docs/nix.md`, and `contract/README.md`.
+- Enter the canonical environment with `nix develop` or `direnv allow` before targeted cargo work.
+- Discover commands from checked-in repo surfaces; do not invent ad hoc workflows.
+- Read the current implementation and nearby tests before designing a change.
+- Inspect `git status --short` before broad edits or refactors.
+- Fail early when the task is blocked by missing prerequisites, contaminated scope, or unresolved public contract questions.
+
+## 4. Canonical command surface
+
+- `nix flake check`
+- `nix run .#contract`
+- `nix run .#release-preflight`
+- targeted `cargo check -p <crate>` and `cargo test -p <crate>` only inside the Nix shell
+- targeted `cargo run -q -p xtask -- ...` only when narrowing a repo-owned contract or export workflow
+- if Beads is active, read `.beads/PRIME.md`
+
+## 5. Rust engineering rules
+
+- Use Rust `1.92.0`, edition `2024`, and workspace dependency versions from the root `Cargo.toml`.
+- Preserve intended `no_std` portability; gate `std`, wasm, and runtime-specific behavior explicitly.
+- Keep core logic functional and composable: prefer pure transformations, explicit state, and narrow side-effect boundaries.
+- Prefer enums, newtypes, and typed domain models over stringly APIs, boolean mode switches, or loosely typed maps.
+- Avoid hidden panics in library code; reserve `unwrap` and `expect` for tests, build tooling, or proven internal invariants.
+- Prefer typed public error surfaces; do not expose opaque convenience errors as stable library contracts.
+- Avoid `unsafe` unless it is strictly necessary and documented by invariants close to the code.
+- Borrow first, clone late, and allocate intentionally.
+- Keep `lib.rs` thin as a module manifest and public re-export surface.
+- Treat generated bindings and generated type artifacts as generated; do not hand-edit them.
+- Add or update deterministic tests for new behavior, invariants, parsing, conversions, feature gates, and cross-target behavior where relevant.
+
+## 6. Contract and release discipline
+
+- `contract/`, `conformance/`, and `crates/xtask` are authoritative for public SDK contract, export, and release governance.
+- Behavior changes that affect public surfaces must update the relevant contract metadata, conformance vectors, export rules, or validation flows in the same change.
+- Keep pure flake checks and repo-aware command apps aligned with the documented Nix command map.
+
+## 7. Commit directives
+
+- Format commits as `<scope>: <imperative summary>`.
+- Use lowercase scopes that match the crate or subsystem being changed.
+- Leave a blank line after the summary when writing a multi-line commit.
+- Use `- ` bullets for notable changes, validations, or compatibility notes when a body is needed.
 - Split unrelated changes into separate commits.
+
+## 8. Definition of done
+
+- The requested change is implemented.
+- Affected code, tests, docs, and contract surfaces are updated together.
+- Relevant canonical validation ran, or a concrete blocker is reported.
+- The handoff states what changed, what validations ran, and any follow-up risks or assumptions.
diff --git a/AGENT_INSTRUCTIONS.md b/AGENT_INSTRUCTIONS.md
@@ -0,0 +1,206 @@
+# Radroots Core Libraries - Agent Instructions
+
+**For repository overview and setup, see [README.md](README.md). For repository rules, see [AGENTS.md](AGENTS.md).**
+
+This document contains detailed operational instructions for contributors and coding agents working on development, testing, and releases in the Radroots Core Libraries repository.
+
+`AGENTS.md` is the concise repo contract. Read it first, then use this file for execution detail.
+
+## 1. How to use this file
+
+- Treat `AGENTS.md` as the durable always-on contract.
+- Use this file for interpretation, procedures, and detailed engineering expectations.
+- If a closer subtree-specific `AGENTS.md` is added later, that file overrides root guidance for its scope.
+- Keep durable rules short and proven; if a problem repeats, tighten the root contract instead of growing ad hoc prompt text.
+
+## 2. Repository operating model
+
+This repository is a public open-source Rust workspace. Optimize for:
+
+- portable library design
+- deterministic behavior
+- explicit contracts
+- cross-target consistency
+- clean public APIs
+
+Stay disciplined:
+
+- keep scope tight
+- avoid drive-by cleanup
+- avoid speculative abstraction
+- avoid compatibility scaffolding unless it is explicitly required
+- do not leave dead paths, temporary adapters, or silent fallback behavior behind
+
+This repo is a library workspace, not an app monolith. The right default is small, durable changes that preserve clean crate boundaries.
+
+## 3. Preflight workflow
+
+Before editing code:
+
+- Read `AGENTS.md`.
+- Read this file.
+- Read `README.md`, `docs/nix.md`, and `contract/README.md` when the change touches workflow, exports, or public surfaces.
+- Read the relevant crate manifest, implementation files, and nearby tests before proposing a new structure.
+- Check `git status --short`.
+
+Before running cargo commands:
+
+- Prefer `nix develop` or `direnv allow`.
+- Treat Nix as the canonical environment contract.
+- Prefer the documented repo-owned command surface over improvised local commands.
+
+Fail early when:
+
+- the environment is missing required tooling
+- the task materially changes a public contract without enough local context
+- the working tree is contaminated in a way that changes the requested scope
+
+## 4. Workspace interpretation
+
+Use this mental model:
+
+- `crates/`
+  - library crates and workspace tooling crates
+  - keep domain logic inside the correct crate rather than spreading it across the workspace
+- `contract/`
+  - public SDK contract metadata, export policy, release policy, and coverage governance
+- `conformance/`
+  - cross-language and cross-surface vector expectations
+- `docs/`
+  - durable workflow and environment documentation
+- `nix/`, `flake.nix`, `treefmt.nix`
+  - canonical environment and CI contract
+- `scripts/`
+  - repo-owned automation used by canonical lanes
+
+Do not duplicate contract knowledge between crates when `contract/`, `conformance/`, or `xtask` already owns it.
+
+## 5. Rust engineering standards
+
+### Core design
+
+- Prefer pure functions and explicit data flow in core logic.
+- Keep IO, filesystem, network, clocks, randomness, and runtime glue at the edges.
+- Prefer data transformation pipelines over stateful orchestration when the problem is fundamentally transformational.
+- Prefer explicit state machines and enums over ad hoc flags or loosely related booleans.
+- Keep mutation local and minimal.
+- Avoid hidden shared mutable state and interior mutability unless the boundary truly requires it.
+
+### API design
+
+- Public APIs should make invalid states hard to represent.
+- Prefer newtypes, enums, and dedicated structs when semantics matter.
+- Avoid exposing dependency-specific types in public API surfaces unless that dependency is a deliberate part of the contract.
+- Separate parsing, validation, normalization, and serialization instead of collapsing them into a single opaque function.
+- Prefer exhaustive `match` behavior for semantic enums over wildcard-heavy control flow.
+
+### Errors and invariants
+
+- Library code should not panic on normal invalid input.
+- Reserve `unwrap`, `expect`, and panic-based control flow for tests, build scripts, or tightly proven internal invariants.
+- Use precise typed errors for public and semantically important boundaries.
+- Keep opaque convenience errors inside binaries, narrow tooling layers, or internal glue when appropriate.
+- When an invariant truly cannot be violated, document it close to the code.
+
+### Portability and feature discipline
+
+- Preserve `no_std` intent where the crate is designed for it.
+- Gate `std` behavior, wasm behavior, and runtime-specific behavior explicitly and predictably.
+- Keep feature interactions simple and testable.
+- When a change affects native, wasm, or `std`/`no_std` parity, update the affected tests or validation flow in the same change.
+
+### Performance and allocation
+
+- Borrow before cloning.
+- Prefer `&str`, `&[u8]`, slices, and iterators when ownership is not required.
+- Avoid unnecessary intermediate allocations.
+- Preallocate only when the size is known or bounded meaningfully.
+- Do not trade away clarity for micro-optimizations unless profiling or the hot-path nature of the code justifies it.
+
+### Module layout
+
+- Keep `lib.rs` thin.
+- Put heavy logic in focused modules.
+- Avoid giant files that mix models, parsing, validation, transformations, and integration glue.
+- Introduce traits only when they remove real duplication or encode a stable abstraction boundary.
+- Avoid generic abstraction that makes the code harder to reason about without clear reuse value.
+
+### Documentation and source comments
+
+- Do not add explanatory comments by habit.
+- Add concise Rustdoc for non-obvious public APIs, invariants, and cross-target behavior.
+- Keep docs aligned with the actual code and contract surface.
+
+## 6. Contract, conformance, and release workflow
+
+`contract/`, `conformance/`, and `crates/xtask` are first-class parts of the product surface, not secondary metadata.
+
+When a change affects exported models, transforms, identifiers, or public runtime expectations:
+
+- update the relevant contract metadata
+- update or add conformance vectors
+- update repo-aware validation flows if needed
+- keep release and export rules aligned with the new behavior
+
+Do not change public behavior in Rust and leave contract or conformance assets stale.
+
+## 7. Canonical validation strategy
+
+Use the smallest authoritative lane that proves the change green.
+
+Repo-wide canonical lanes:
+
+- `nix flake check`
+- `nix run .#contract`
+- `nix run .#release-preflight`
+
+Targeted iteration inside the Nix shell:
+
+- `cargo check -p <crate>`
+- `cargo test -p <crate>`
+- `cargo run -q -p xtask -- sdk validate`
+- `cargo run -q -p xtask -- sdk release preflight`
+
+Validation rules:
+
+- crate-local changes may iterate with targeted cargo commands
+- contract, export, conformance, flake, release, or multi-crate changes should close on a canonical Nix lane
+- deterministic tests are required for new behavior and edge cases
+- do not rely on wall-clock time, random order, external network access, or ambient machine state in unit tests
+
+## 8. Commit and handoff guidance
+
+Commit messages in this repo are part of the public open-source surface.
+
+That means:
+
+- use `<scope>: <imperative summary>`
+- keep the scope lowercase and meaningful
+- keep the summary standalone and readable outside monorepo context
+- do not reference internal repository paths, internal migration rationale, or private coordination context
+- when using a body, leave a blank line after the summary and use `- ` bullets
+
+Handoffs should state:
+
+- what changed
+- what validations ran
+- any assumptions made
+- any follow-up risks or missing work
+
+## 9. Beads and Agent Mail
+
+If Beads is active for the task:
+
+- use `.beads/PRIME.md` as the Beads-specific operator layer
+- keep live execution state in Beads rather than markdown task lists
+- do not use `bd edit`
+- use Beads for durable multi-commit work, not as a replacement for contract docs or repo docs
+
+If Agent Mail is active for the task:
+
+- use `.beads/PRIME.md` for the repository coordination conventions
+- use the active Beads issue id as the Agent Mail thread id and reservation reason when both tools are active
+- reserve files before the first write for coordinated multi-agent work
+- use shared build slots for long-running singleton lanes such as contract, release-preflight, or wasm-build runs
+
+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.