commit f552be2c411340e59b7308b0e1bce256324659b1
parent 42cc31a996f713549b8b51c1f04c9572543ae85e
Author: triesap <tyson@radroots.org>
Date: Thu, 15 Oct 2026 20:42:39 +0000
docs: align shared SDK ownership and compiler guidance
- Follow the standalone approved SDK target decision.
- Correct current Lib ownership of the SDK and facade packages.
- Distinguish exact compiler targets from completed migration evidence.
- Preserve historical contracts and fix the root README reference.
Diffstat:
3 files changed, 38 insertions(+), 14 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
@@ -22,6 +22,13 @@ This file exists for compatibility with tools that look for AGENTS.md.
specifications, decisions, runbooks, and qualification evidence belong
under the parent monorepo's `docs/oss/lib/**` authority and must never become
a standalone build, test, package, or release input.
+- The approved shared SDK target is
+ `contracts/architecture/decisions/shared_sdk_refactor.v1.json`.
+ Lib owns shared domain, execution, persistence, signing, transport and recovery;
+ `radroots` is the ordinary facade. The SDK repository consumes source-owned
+ generators and artifacts. Its target graph, roles, limits and host matrix are
+ prospective requirements, not current implementation or qualification claims.
+ Preserve the exact source and proving inputs at each migration checkpoint.
- The pre-implementation service-event reservation is
`contracts/architecture/decisions/services_hardening_events.v1.json`.
Service-event source, registry, generated, and consumer work must implement
@@ -76,7 +83,8 @@ This file exists for compatibility with tools that look for AGENTS.md.
shell, NixOS-module, and Nix-produced OCI outputs are explicitly deferred
and are not qualified by that contract.
- Current source and tests are implementation evidence. They do not silently
- override `radroots.crates.release.v1`.
+ override machine contracts. Release V2 preserves Release V1 as historical
+ authority; the approved shared SDK decision governs the successor target.
- Record any evidence-based plan deviation in
`contracts/architecture/deviations.toml` before proceeding. Validate it with
`cargo xtask architecture`; a normative architecture exception also requires
@@ -109,7 +117,7 @@ This file exists for compatibility with tools that look for AGENTS.md.
Before editing code:
-- Read this file, `AGENT_INSTRUCTIONS.md`, and `README`.
+- Read this file, `AGENT_INSTRUCTIONS.md`, and `README.md`.
- When preserving deferred Nix behavior, read `flake.nix` and the relevant
implementation files under `build/nix/`, but do not install, invoke, or
require Nix as part of current qualification.
@@ -144,9 +152,11 @@ Before editing code:
## 6. Rust engineering rules
-- Use Rust `1.99.0` for development, retaining minimum supported Rust `1.97.1`,
- edition `2024`, resolver `3`, and workspace dependency
- versions from the root `Cargo.toml` after the release-v1 workspace cutover.
+- Use exact stable Rust and MSRV `1.99.0`, edition `2024`, and resolver `3` as
+ the approved successor target. Update active selectors, compiler acquisition,
+ validators, generators and qualification together; the existing workspace
+ metadata has not been declared migrated by adopting the target decision.
+ Frozen receipts and dedicated nightly/SP1 toolchains retain their identities.
- 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.
@@ -177,9 +187,11 @@ Before editing code:
- Preserve deferred flake expressions as unqualified compatibility inputs;
do not use their evaluation or outputs as evidence until an accepted
contract explicitly reactivates them.
-- This repository owns packages 1-17 in `radroots.crates.release.v1`, from
- `radroots_core` through `radroots_geonames`. `radroots_sdk` and `radroots`
- remain owned by the standalone SDK repository.
+- `contracts/crates/release.v2.toml` records the nineteen current public Lib
+ packages, including `radroots_sdk` and `radroots`. Release V1's earlier
+ repository split remains history. The approved successor replaces old
+ SDK/trade/model boundaries directly and retains ancillary capabilities;
+ target package declarations do not create implemented or published packages.
- Public packages have no dependency on private Radroots packages. Every
Radroots dependency edge points downward in the approved graph.
- Domain and protocol packages do not own storage, live networking, host UI,
diff --git a/AGENT_INSTRUCTIONS.md b/AGENT_INSTRUCTIONS.md
@@ -1,6 +1,6 @@
# Radroots Core Libraries - Agent Instructions
-**For repository overview and setup, see [README](README). For repository rules, see [AGENTS.md](AGENTS.md).**
+**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.
@@ -43,7 +43,7 @@ Before editing code:
- Read `AGENTS.md`.
- Read this file.
-- Read `README` when the change touches workflow or public surfaces.
+- Read `README.md` when the change touches workflow or public surfaces.
- When preserving deferred Nix behavior, read `flake.nix` and the relevant
implementation files under `build/nix/`, but do not install, invoke, or
require Nix as part of current qualification.
@@ -88,6 +88,14 @@ Use this mental model:
Do not duplicate contract knowledge between crates when `contracts/`, `contracts/conformance/`, or `tools/xtask` already owns it.
+The approved successor authority is
+`contracts/architecture/decisions/shared_sdk_refactor.v1.json`. Shared reusable
+semantics and execution belong in Lib, with `radroots` as the facade; the SDK
+repository consumes the owning generators and artifacts. Its complete actor,
+host, budget and provenance requirements govern direct replacement. Target
+metadata does not qualify current APIs, artifacts, compiler migration or a
+consumer. Preserve original release evidence and bind actual changed inputs.
+
Do not add or retain tracked `docs/**`, `.github/**`, or `.act/**`. Root
`README.md`, `AGENTS.md`, `AGENT_INSTRUCTIONS.md`, conventional public project
files, package READMEs, and Rustdoc carry concise standalone guidance. Extended
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -10,10 +10,14 @@ reviewable. Before editing, read these files in order:
crate-surface work
5. the affected manifests, implementation, contracts, and tests
-The release-v1 architecture identifier is `radroots.crates.release.v1`. This
-repository owns its first 17 public packages, from `radroots_core` through
-`radroots_geonames`; the standalone SDK repository owns `radroots_sdk` and
-`radroots`.
+Release V2 records the nineteen current public Lib packages, including
+`radroots_sdk` and `radroots`. The earlier `radroots.crates.release.v1`
+repository split remains immutable history. The approved successor is
+`contracts/architecture/decisions/shared_sdk_refactor.v1.json`: Lib owns shared
+semantics and execution, `radroots` remains the facade, and the SDK repository
+consumes source-owned generators and artifacts. Its target package graph is
+prospective; implementation, compiler migration and qualification require
+their actual source-bound checks before acceptance.
## Workflow