lib

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

AGENTS.md (29027B)


      1 # Radroots Core Libraries - Agent Specification
      2 
      3 See [CONTRIBUTING.md](CONTRIBUTING.md) for the contributor workflow and
      4 [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for extended execution detail.
      5 
      6 This file exists for compatibility with tools that look for AGENTS.md.
      7 
      8 ## 1. Scope and hierarchy
      9 
     10 - This file applies to the full repository.
     11 - Keep this file concise and durable.
     12 - Put detailed procedures, examples, and extended guidance in `AGENT_INSTRUCTIONS.md`.
     13 - If a closer directory-level `AGENTS.md` is added later, it overrides this file for that subtree.
     14 
     15 ## 2. Source of intent
     16 
     17 - Read `contracts/crates/release.v2.toml`,
     18   `contracts/crates/release_v1/radroots_crates_release_v1.toml`, and
     19   `contracts/crates/catalog.v2.toml` before changing a public package, package
     20   identity, dependency, feature, or release control.
     21 - Machine contracts under `contracts/**` are the standalone authority. Human
     22   specifications, decisions, runbooks, and qualification evidence belong
     23   under the parent monorepo's `docs/oss/lib/**` authority and must never become
     24   a standalone build, test, package, or release input.
     25 - The approved shared SDK target is
     26   `contracts/architecture/decisions/shared_sdk_refactor.v1.json`.
     27   Lib owns shared domain, execution, persistence, signing, transport and recovery;
     28   `radroots` is the ordinary facade. The SDK repository consumes source-owned
     29   generators and artifacts. Its target graph, roles, limits and host matrix are
     30   prospective requirements, not current implementation or qualification claims.
     31   Preserve the exact source and proving inputs at each migration checkpoint.
     32 - The pre-implementation service-event reservation is
     33   `contracts/architecture/decisions/services_hardening_events.v1.json`.
     34   Service-event source, registry, generated, and consumer work must implement
     35   that exact kind, tag, cardinality, query, and supersession contract; it may
     36   not reinterpret the reservation from current prototype wire behavior.
     37 - The pre-implementation local-admin, process-exit, doctor, readiness,
     38   peer-credential, systemd, and bare-Rust host decisions are reserved by
     39   `contracts/architecture/decisions/services_hardening_host.v1.json`.
     40   Service-host and service-owned operator contracts must implement or narrow
     41   that boundary without adding a second transport, exit map, or readiness
     42   authority.
     43 - Source-lock consumer identities include `sdk`, `myc`, and `rhi`.
     44   Only `sdk` is a generated-artifact product identity;
     45   accepting a service consumer marker must not expose an artifact route.
     46   Tera owns its application packages and native/WASM artifact routes. Lib must
     47   not regain an application package or a dependency on the Tera application.
     48 - The current service source lock is the bounded, canonical
     49   `radroots.service.source_lock.v4.toml`, defined by
     50   `contracts/architecture/decisions/services_hardening_source_lock.v4.json`.
     51   It binds exact public Lib source, catalog, Cargo/Nix lock and service artifact
     52   inputs to Rust `1.99.0`, the `service-host` profile and positive contract
     53   versions. Bound Nix inputs must match the active Lib revision and do not
     54   establish executed qualification. Preserve V1-V3 contracts and bootstrap
     55   evidence as history. Reject noncanonical/extra fields and coexisting
     56   predecessor locks; keep the codec and diagnostics private to repo tooling.
     57 - Generate or verify the current lock with `cargo xtask service-source-lock
     58   --mode write|check --service-root <absolute-directory> --source-archive
     59   <absolute-bundle>`. The verified bundle transports the exact public revision;
     60   the lock binds its canonical exact-tree archive, never its Git history.
     61   Every Lib dependency, Cargo/Nix input and public remote must agree. The
     62   service-owned V4 artifact contract must be committed in that service revision.
     63   Ordinary write/check rejects every source-tree change except the exact
     64   generated lock path. For an atomic migration before a green commit, use
     65   `--mode prepare`: stage the complete intended candidate first. Preparation
     66   requires no other unstaged/untracked inputs, a resolved stable index and
     67   HEAD, and exact index/live artifact-contract bytes. It grants no acceptance;
     68   verify and commit the complete candidate, then run clean-source check.
     69 - Current unsigned artifact preparation is governed by
     70   `contracts/architecture/decisions/services_hardening_release_artifacts.v5.json`.
     71   Bound source and generated outputs require separate executed platform and
     72   release evidence; this command never activates a candidate.
     73 - Generate or verify one immutable service release artifact set with `cargo
     74   xtask service-release-artifacts --mode write|check --service-root
     75   <absolute-directory> --lib-root <absolute-directory> --input-root
     76   <absolute-directory> --output-root <absolute-directory> --target <rust-target>
     77   --source-date-epoch <seconds> --candidate-digest <sha256>`.
     78   The command consumes the exact fixed input inventory, validates clean and
     79   stable service and Lib source bundles, and emits the canonical binary
     80   archive, OCI/source metadata, CycloneDX SBOM, notices, manifest, unsigned
     81   provenance signing input, and checksums. Signing credentials and signatures
     82   remain external; generated artifacts must contain no protected material.
     83 - Current SDK compiler-preparation requirements are governed by
     84   `contracts/architecture/decisions/shared_sdk_compiler_preparation.v1.json`.
     85   Existing contract and preflight commands validate exact current inputs;
     86   declaration validation supplies no execution or release qualification.
     87 - Historical shared-build qualification contracts V2 and V3 remain under
     88   `contracts/architecture/decisions/services_hardening_build_qualification.*.json`.
     89   Their fixed targets, fixtures and evidence do not qualify current compiler
     90   changes. Current native checks use the approved shared SDK compiler target;
     91   successor qualification and actual platform execution remain required.
     92   Preserve the historical Nix output deferrals without claiming execution.
     93 - Current source and tests are implementation evidence. They do not silently
     94   override machine contracts. Release V2 preserves Release V1 as historical
     95   authority; the approved shared SDK decision governs the successor target.
     96 - Record any evidence-based plan deviation in
     97   `contracts/architecture/deviations.toml` before proceeding. Validate it with
     98   `cargo xtask architecture`; a normative architecture exception also requires
     99   the applicable machine decision under `contracts/architecture/decisions/**`.
    100   Deviation anchors must resolve the Release V1 TOML through a validated
    101   selector: `repositories.<name>`, `repository_policy`, `release_policy`,
    102   `quality_policy.coverage`, or `package.<name>`.
    103 
    104 ## 3. Repository operating model
    105 
    106 - This is a public open-source library workspace; optimize for durable library design, portability, determinism, and explicit contracts.
    107 - Keep release and validation automation forge-agnostic; repo-owned xtask
    108   commands, native Cargo lanes, tags, and contract metadata are canonical,
    109   while committed provider-specific workflow automation is not. Checked-in
    110   Nix surfaces are deferred compatibility inputs, not current qualification
    111   authority.
    112 - Do not add or retain tracked `docs/**`, `.github/**`, or `.act/**` content.
    113   Keep validation forge-agnostic. Any required monorepo orchestration belongs
    114   exclusively to the parent repository's root `.act/**` authority and must not
    115   be copied into this standalone capsule.
    116 - Prefer clean target-state changes over compatibility scaffolding unless compatibility is explicitly required.
    117 - Stay within the requested scope and the smallest coherent file set.
    118 - Do not fold unrelated cleanup, speculative refactors, or roadmap work into the same change.
    119 - Do not create hidden task trackers in markdown checklists, source comments, or stray notes.
    120 - Keep commits and handoff language standalone and open-source-readable; do
    121   not reference non-public repository paths, internal mapping rationale, or
    122   private repository context.
    123 
    124 ## 4. Preflight before edits
    125 
    126 Before editing code:
    127 
    128 - Read this file, `AGENT_INSTRUCTIONS.md`, and `README.md`.
    129 - When preserving deferred Nix behavior, read `flake.nix` and the relevant
    130   implementation files under `build/nix/`, but do not install, invoke, or
    131   require Nix as part of current qualification.
    132 - Run `cargo extbuild doctor` before the first governed build, test, check,
    133   generation, package, artifact, or release-preflight command, then route the
    134   command through `cargo extbuild run --`.
    135 - Discover commands from checked-in repo surfaces; do not invent ad hoc workflows.
    136 - Read the current implementation and nearby tests before designing a change.
    137 - Inspect `git status --short` before broad edits or refactors.
    138 - Fail early when the task is blocked by missing prerequisites, contaminated scope, or unresolved public contract questions.
    139 
    140 ## 5. Canonical command surface
    141 
    142 - `cargo extbuild run -- cargo check --workspace --all-targets --locked`
    143 - `cargo extbuild run -- cargo test --workspace --all-targets --locked`
    144 - `cargo extbuild run -- cargo xtask contract validate`
    145 - `cargo extbuild run -- cargo xtask release preflight`
    146 - `cargo extbuild run -- cargo xtask architecture` for controlled deviation records and local spec
    147   anchors
    148 - Public API baselines live in `contracts/api_baselines/**`. Regenerate one
    149   with `cargo-public-api` `0.52.0` and rustdoc JSON from
    150   `nightly-2026-07-16`, writing the reviewed output back to that directory.
    151 - targeted `cargo check -p <crate>` and `cargo test -p <crate>` through
    152   `cargo extbuild run --`
    153 - `cargo xtask dto-roots --write` after changing configured DTO exports and
    154   `cargo xtask dto-roots --check` for exact generated-root freshness
    155 - targeted `cargo xtask contract ...`, `cargo xtask coverage ...`, `cargo xtask release ...`, or `cargo xtask hygiene ...` only when narrowing a repo-owned workflow
    156 - `cargo xtask hygiene prototype-contracts` for the governed report-only
    157   service-prototype census; use `--strict` only when the cleanup sequence has
    158   made every non-allowlisted finding release-blocking
    159 - if Beads is active, read `.beads/PRIME.md`
    160 
    161 ## 6. Rust engineering rules
    162 
    163 - Use exact stable Rust and MSRV `1.99.0`, edition `2024`, and resolver `3` as
    164   the approved successor target. Update active selectors, compiler acquisition,
    165   validators, generators and qualification together; the existing workspace
    166   metadata has not been declared migrated by adopting the target decision.
    167   Frozen receipts and dedicated nightly/SP1 toolchains retain their identities.
    168 - Preserve intended `no_std` portability; gate `std`, wasm, and runtime-specific behavior explicitly.
    169 - Keep core logic functional and composable: prefer pure transformations, explicit state, and narrow side-effect boundaries.
    170 - Prefer enums, newtypes, and typed domain models over stringly APIs, boolean mode switches, or loosely typed maps.
    171 - Avoid hidden panics in library code; reserve `unwrap` and `expect` for tests, build tooling, or proven internal invariants.
    172 - Prefer typed public error surfaces; do not expose opaque convenience errors as stable library contracts.
    173 - Avoid `unsafe` unless it is strictly necessary and documented by invariants close to the code.
    174 - Borrow first, clone late, and allocate intentionally.
    175 - Keep `lib.rs` thin as a module manifest and public re-export surface.
    176 - Treat generated bindings and generated type artifacts as generated; do not hand-edit them.
    177 - Add or update deterministic tests for new behavior, invariants, parsing, conversions, feature gates, and cross-target behavior where relevant.
    178 
    179 ## 7. Architecture, contract, and release discipline
    180 
    181 - `contracts/` and `tools/xtask` are authoritative for core-library contracts, conformance, coverage, hygiene, and release-candidate governance.
    182 - `contracts/crates/catalog.v2.toml` is the package-catalog authority. Preserve
    183   imported packages as `provenance_kind = "imported"` with their immutable
    184   repository, revision, path, and tree digest. New repository-native packages
    185   begin as active private `provenance_kind = "native"` entries; public eligibility
    186   requires the approved current release allocation. Native entries always
    187   store only `introduction_tree_sha256`; never embed a self-referential
    188   introducing commit OID.
    189 - Before validating a new native catalog entry, stage the complete package path
    190   and run `cargo xtask catalog check` or `cargo xtask catalog write`. The
    191   pre-commit digest is derived from stage-zero index records, not the mutable
    192   worktree. After the introducing commit, the same command derives the first
    193   adding commit from repository history and verifies its immutable tree. Do
    194   not rewrite that digest for later source changes.
    195 - Behavior changes that affect public surfaces must update the relevant contract metadata, conformance vectors, export rules, or validation flows in the same change.
    196 - Preserve deferred flake expressions as unqualified compatibility inputs;
    197   do not use their evaluation or outputs as evidence until an accepted
    198   contract explicitly reactivates them.
    199 - `contracts/crates/release.v2.toml` records the twenty-two current public Lib
    200   packages, including `radroots_sdk` and `radroots`. Release V1's earlier
    201   repository split remains history. The approved successor replaces old
    202   SDK/trade/model boundaries directly and retains ancillary capabilities;
    203   target package declarations do not create implemented or published packages.
    204 - Public packages have no dependency on private Radroots packages. Every
    205   Radroots dependency edge points downward in the approved graph.
    206 - Domain and protocol packages do not own storage, live networking, host UI,
    207   executors, schedulers, or process-global behavior.
    208 - Generic SPIs do not expose concrete SQLx, Tokio, Reqwest, Nostr SDK,
    209   keyring, or operating-system implementation types.
    210 - Preview, code-generation, fixture, binding-generator, coverage, xtask, and
    211   implementation-assembly packages remain private and absent from published
    212   feature closures.
    213 - Current public eligibility is governed by the catalog and Release V2,
    214   including exact `contracts/releases/publish_policy.toml` ownership. Package
    215   upload still requires its release gates and explicit authorization; current
    216   Release V2 keeps `publication_authorized = false`. Source publication and
    217   validation metadata never authorize a package upload.
    218 
    219 ## 8. Service hardening boundaries
    220 
    221 - Service hardening is clean-slate: do not add or preserve prototype
    222   configuration readers, environment-file configuration, prototype state
    223   importers, JSON/JSONL mutable state, fallback path searches, compatibility
    224   aliases, deprecated modules/APIs/re-exports, dual wire encodings, or old/new
    225   feature switches. Update affected consumers directly.
    226 - `radroots_service_host` owns reusable host mechanics only, and
    227   `radroots_service_sqlite` owns reusable SQLite mechanics only. Neither crate
    228   may contain Myc or RHI domain configuration, tables, policy, or business
    229   rules, and neither may become a broad lifecycle framework.
    230 - Each service instance has one live SQLite database. Keep its pool private to
    231   the owning store, keep live mutable state daemon-owned, and route live-state
    232   mutations from local tools through the typed, permissioned Unix-socket
    233   local-admin boundary.
    234 - `radroots_service_sqlite::ServiceSqliteHost` is the sole public owner of the
    235   private SQLx pool. Service code may execute typed SQLx queries only through
    236   the sealed `&mut ServiceSqliteTransaction` executor passed to
    237   `ServiceSqliteHost::transaction`; do not expose or reconstruct raw pools,
    238   pooled connections, SQLx transactions, commit/rollback handles, or inner
    239   accessors. Do not attach or detach secondary SQLite databases through the
    240   transaction executor. Writable host construction must finish governed
    241   migrations before returning, while read-only inspection must require current
    242   migration and schema state. Every host owner must explicitly await
    243   `ServiceSqliteHost::close`: close permanently stops admission, drains admitted
    244   work, applies the fixed unblocked `TRUNCATE` WAL checkpoint for writable
    245   hosts only, closes its private checkpoint connection, and explicitly releases
    246   writer or inspection authority. A cancelled close retains authority and must
    247   be resumed through the host-owned connect/checkpoint/connection-close driver;
    248   Drop is not an asynchronous close or completion proof. Do not add public
    249   checkpoint knobs, background close tasks, or Drop-based async cleanup.
    250 - `ServiceBackupManifest` is the sole v1 backup-manifest model. Preserve its
    251   exact 1,024-byte compact canonical JSON, raw canonical-byte SHA-256, typed
    252   service/instance/source-generation/schema/time binding, singleton
    253   `state.sqlite` inventory, exact `ok` integrity projection, and mandatory
    254   protected-material exclusion. Parsing is structural only and must not perform
    255   filesystem or SQLite work. Online capture belongs only to the writable
    256   `ServiceSqliteHost`: admit one capture at a time, use SQLite's incremental
    257   online-backup API, create a caller-selected new owner-only staging directory,
    258   return the manifest in memory, and retain host authority until success or
    259   exact-artifact cancellation cleanup completes. Do not expose raw backup
    260   handles, capture credentials, invent a manifest filename, read an ambient
    261   clock, or fold untrusted verification or restore behavior into capture.
    262 - Untrusted backup verification is the synchronous, task-free
    263   `verify_backup_bundle` boundary. Require an independently protected manifest
    264   digest, exact `ServiceDatabaseIdentity`, and caller-supplied positive member
    265   limit; retain the verified directory and member descriptors in the sealed
    266   non-cloneable proof. Do not expose paths or raw handles, treat pathname-only
    267   verification as restore authority, create an internal task/deadline, mutate
    268   the bundle, or introduce restore markers, staging, replacement, or recovery
    269   into verification. Later restore work must consume the retained member and
    270   reverify its staged copy.
    271 - Restore recovery markers are private `radroots_service_sqlite` mechanics.
    272   Preserve the fixed sibling names, exact 2,048-byte canonical v1 JSON,
    273   domain-separated self-checksum, typed database and backup intent, and the
    274   only legal durable sequence `prepared -> live_retained ->
    275   replacement_installed`. Marker creation and advancement require retained
    276   writer authority, descriptor-relative owner-only files, exact inode
    277   revalidation, file and parent synchronization, and create-new scratch plus
    278   atomic replacement. Reads never repair or remove evidence. Do not expose
    279   marker types or paths, truncate markers in place, accept caller-selected
    280   names, or move, copy, open, or delete a database in the marker checkpoint;
    281   restore staging, replacement, and open-time recovery remain separate steps.
    282 - Offline restore staging consumes a sealed `VerifiedServiceBackup`, acquires
    283   exclusive writer authority after every governed host has closed, and creates
    284   only the fixed adjacent `state.restore-staged.sqlite` file. It must copy from
    285   the retained source descriptor, reverify exact metadata, migration prefix,
    286   schema catalog, integrity, foreign keys, length, and digest through retained
    287   descriptors, and keep authority plus exact cleanup ownership across caller
    288   cancellation. The returned sealed capability owns the staged inode until
    289   finalization or an identity-checked drop cleanup attempt; failed cleanup must
    290   remain evidence that later admission rejects. Staging must not create a
    291   marker, rename live state, retain an old live database, or install a
    292   replacement; those are later finalization and recovery boundaries.
    293 - Atomic restore finalization consumes only a sealed `StagedServiceRestore`.
    294   Staging must bind the exact live inode, length, and digest that finalization
    295   will retain. The owned blocking worker creates and synchronizes `prepared`
    296   before disarming stage cleanup, then uses descriptor-relative no-replace
    297   renames and parent synchronization for live-to-backup and staged-to-live,
    298   advancing the marker only after each durable rename. Cancellation observed
    299   before the worker atomically claims commit ownership may cleanly stop;
    300   caller loss after that handoff is an unknown immediate outcome, including
    301   the interval before `prepared` is durable. Once `prepared` is durable, stage
    302   cleanup must remain disarmed after every later error so the marker never
    303   loses a bound artifact.
    304   Successful finalization returns no host and leaves the old live database and
    305   `replacement_installed` marker for the next writable open to recover. Other
    306   open modes reject that evidence as `Recovery`. Finalization itself must not
    307   roll back, delete recovery evidence, reopen SQLite, or expose paths,
    308   descriptors, marker controls, or rename controls.
    309 - Interrupted restore recovery is private and automatic only for
    310   read-write-existing open under exclusive `WriterAuthority`, before any
    311   SQLite connection or await point. Initialize, initialized-open, and
    312   read-only inspection must reject every fixed stage, backup, marker, or
    313   marker-scratch artifact without mutation. Recovery must bind the marker to
    314   the requested database identity, hash and revalidate exact owner-only
    315   single-link artifacts, reject sidecars, and let exact topology decide the
    316   sole action: roll back `prepared` while old live is still installed, then
    317   roll forward once old live is durably retained. Persist every inferred phase
    318   before the next destructive step; retire exact backup before marker; and
    319   admit marker scratch only as a canonical topology-consistent one-edge
    320   successor whose exact bound inode is removed and durably reproduced through
    321   the governed marker-advance path without overwriting the valid marker.
    322   Repeated recovery may
    323   finish already-absent stage or backup cleanup, but every other missing,
    324   replaced, linked, malformed, mismatched, or ambiguous artifact remains
    325   `Recovery` evidence. Do not expose recovery controls, add a background task
    326   or hidden timeout, repair without writer authority, or fold Step 070
    327   integrity/status APIs and the later process failpoint harness into recovery.
    328 - Explicit active integrity inspection belongs only to
    329   `ServiceSqliteHost::inspect_integrity`. It admits at most one check per host,
    330   uses one governed read snapshot, accepts an injected positive wall-clock
    331   timestamp, and returns only the closed SQLite/foreign-key outcomes plus at
    332   most two stable diagnostic codes in canonical order. Preserve authority
    333   precedence after every await. Do not expose raw SQLite diagnostics, paths,
    334   SQL, pool handles, or dependency errors; persist or cache the result; read an
    335   ambient clock; create a timer/task; or weaken the strict restore/backup
    336   integrity verifier. Callers own the monotonic deadline by cancelling the
    337   future. The host-owned integrity driver must retain a cancelled in-flight
    338   connection and its explicit close future until the SQLx worker terminates;
    339   retry and host close resume that cleanup before proceeding. A retry must
    340   inject a new timestamp.
    341 - State-filesystem capacity inspection is an explicit, synchronous,
    342   host-independent doctor and admission input. Callers must supply a positive
    343   `MinimumFreeBytes`; there is no default threshold. The platform adapter
    344   measures unprivileged available bytes through a retained owner-owned state
    345   directory descriptor that is not group/other writable, and the immutable
    346   result classifies exact equality as
    347   ready and anything below the policy as low disk. Measurement failure is a
    348   typed unavailable result, never fabricated low-disk evidence. Consumers may
    349   cache a successful snapshot and project low disk to the stable
    350   `database_low_disk` reason, but passive readiness handlers must never invoke
    351   the adapter. Keep inspection advisory: do not add a reservation, host/pool or
    352   SQLite dependency, ambient timer, background sampler, service default, or
    353   status persistence to this crate.
    354 - Durability failpoints are private, instance-scoped test mechanics only. Keep
    355   a closed before/after inventory across initialization, transaction commit,
    356   online backup, restore-marker persistence, restore rename/synchronization,
    357   and explicit close. One armed controller may fail one selected edge once;
    358   ordinary controllers have zero behavior. Never export failpoint types, use
    359   process-global failpoint state, select a point from environment or service
    360   configuration, or add a Cargo feature that alters production behavior.
    361   Process-level crash and signal qualification must remain in private Cargo
    362   test binaries. Pass only one bounded temporary root over stdin, require a
    363   fixed stdout token from an occurrence-aware failpoint barrier before
    364   `SIGKILL`, and retain a parent kill-on-drop watchdog. Cover writer-lock death
    365   and the exact pre-marker, prepared, marker-scratch, installed-replacement,
    366   and terminal-marker restore topologies under a permissive child umask.
    367   Require Linux x86_64 execution for OS-level qualification; macOS aarch64 on
    368   the current machine is developer evidence only. No other platform or
    369   architecture is an active qualification gate. Do not ship a helper binary,
    370   add production signal/process behavior, poll filesystem state for crash
    371   timing, or claim abrupt power-loss durability from process-death tests.
    372 - Runtime-management flows consume a sealed `RuntimeContext` for every service
    373   instance. They must not reconstruct service paths from raw identifiers,
    374   ambient selectors, or manager-owned roots, and registries must not persist
    375   duplicate config, state, logs, run, secrets, or binary paths. Manager-owned
    376   install and process-tracking artifacts remain separate; uninstall and
    377   cleanup must never recursively delete canonical service state or secrets.
    378   The manager has no credential read/write authority, executable artifact
    379   names are validated single path components, and ordinary manager errors and
    380   `Debug` output must not expose filesystem paths, file contents, or raw
    381   dependency-owned causes.
    382 - Runtime-path consumers must use the sole typed
    383   `services/<service>/<instance>` model through `RuntimeContext`. The generic
    384   app/service/worker/shared namespace, public raw root containers, path
    385   overrides, ambient process-environment selectors, bootstrap helpers, and
    386   duplicate service-instance path constructors are removed breaking surfaces;
    387   do not restore them or add compatibility aliases.
    388 - Runtime-distribution and runtime-management service metadata is the sealed
    389   exact Myc/RHI v1 inventory. Both services support multiple validated
    390   instances, one TOML config, explicit initialization with existing-only run,
    391   detailed HTTP/1.1-over-Unix local administration, cached
    392   `/livez`/`readyz`/`metrics`, and only Linux x86_64/aarch64 Tier-1 eligibility
    393   in `target` posture. This metadata does not authorize service registration,
    394   PID/config/log probing, lifecycle actions, artifact names, channels, archive
    395   resolution, or a `qualified` support claim.
    396 - Library code must not initialize a tracing subscriber, parse a process CLI,
    397   read service configuration from environment variables, install signal
    398   handlers, create a Tokio runtime, call `process::exit`, or spawn arbitrary
    399   signer executables.
    400 - Inject time, entropy, transport, providers, and failpoints. Bound queues,
    401   pools, retries, requests, responses, and collections; redact sensitive data
    402   from logs, status, metrics, fixtures, errors, and ordinary `Debug` output.
    403 - Preserve public Nostr interoperability while removing Radroots-owned
    404   prototype behavior; clean-slate rules never authorize protocol drift.
    405 
    406 ## 9. Irreversible actions
    407 
    408 Do not publish crates, create release tags, change crates.io ownership, merge
    409 or rename repositories, merge pull requests, rotate credentials, or mutate
    410 trusted-publisher configuration without explicit authorization.
    411 
    412 ## 10. Commit and deviation directives
    413 
    414 - Format commits as `<scope>: <imperative summary>`.
    415 - Use lowercase scopes that match the crate or subsystem being changed.
    416 - Leave a blank line after the summary when writing a multi-line commit.
    417 - Use `- ` bullets for notable changes, validations, or compatibility notes when a body is needed.
    418 - Split unrelated changes into separate commits.
    419 - If repository evidence proves a planned step obsolete or unsafe, record the
    420   evidence, affected specification anchor, disposition, and validation in
    421   `contracts/architecture/deviations.toml`. A normative architecture change
    422   also requires an approved machine decision under
    423   `contracts/architecture/decisions/**`. Never silently skip or reorder work.
    424 
    425 ## 11. Definition of done
    426 
    427 - The requested change is implemented.
    428 - Affected code, tests, docs, and contract surfaces are updated together.
    429 - Relevant canonical validation ran, or a concrete blocker is reported.
    430 - The handoff states what changed, what validations ran, and any follow-up risks or assumptions.