lib

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

commit 8929943c6efde01499921c0e3f879b693252494b
parent 65c09c2517de9765892ed4eeab093ce5aef141b2
Author: triesap <tyson@radroots.org>
Date:   Fri, 16 Oct 2026 13:33:56 +0000

xtask: Prepare service source locks from exact staged inputs

- Add explicit preparation without relaxing clean committed checking.
- Bind generated locks to stable index and artifact contract bytes.
- Reject unstaged inputs and concurrent source movement.
- Verify all tooling tests with retained concurrency findings.

Diffstat:
MAGENTS.md | 7++++++-
Mcontracts/architecture/deviations.toml | 15+++++++++++++++
Mtools/xtask/src/main.rs | 32++++++++++++++++++--------------
Mtools/xtask/src/service_source_lock_command.rs | 188++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-------------
4 files changed, 198 insertions(+), 44 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md @@ -60,7 +60,12 @@ This file exists for compatibility with tools that look for AGENTS.md. the lock binds its canonical exact-tree archive, never its Git history. Every Lib dependency, Cargo/Nix input and public remote must agree. The service-owned V4 artifact contract must be committed in that service revision. - Reject every source-tree change except the exact generated lock path. + Ordinary write/check rejects every source-tree change except the exact + generated lock path. For an atomic migration before a green commit, use + `--mode prepare`: stage the complete intended candidate first. Preparation + requires no other unstaged/untracked inputs, a resolved stable index and + HEAD, and exact index/live artifact-contract bytes. It grants no acceptance; + verify and commit the complete candidate, then run clean-source check. - Current unsigned artifact preparation is governed by `contracts/architecture/decisions/services_hardening_release_artifacts.v5.json`. Bound source and generated outputs require separate executed platform and diff --git a/contracts/architecture/deviations.toml b/contracts/architecture/deviations.toml @@ -1,6 +1,21 @@ schema_version = 1 architecture_id = "radroots.crates.release.v1" +[[deviation]] +id = "RCRV1-DEV-041" +date = "2026-10-16" +status = "closed" +approval = "The user authorizes the complete shared SDK and Rust 1.99 migration, verified local commits, source pushes and master integration." +affected_steps = ["030", "130"] +spec_anchors = ["contracts/crates/release_v1/radroots_crates_release_v1.toml#release_policy"] +source_evidence = ["V4 source-lock generation rejects staged source changes, while service compilation requires the matching generated lock before the migration can be committed green."] +replacement_action = "Add an explicit prepare mode for exact staged service inputs. Retain clean-source write/check, reject unstaged/untracked inputs and unresolved indexes, bind stable HEAD/index and exact index/live contract bytes, and require clean committed checking after candidate verification. Keep V4 bytes, public provider reachability and existing source/compiler/lock validation unchanged." +verification = ["Exercise staged generation and committed checking, refusal of unstaged and untracked inputs, artifact index binding and concurrent index/HEAD changes.", "Run locked xtask checking/tests, strict Clippy, formatting, architecture and contract validation before committing and pushing the provider."] +unresolved_risk = "Preparation is not source or artifact qualification. Actual consumer generation, clean committed checking, platform evidence and final supported adoption remain required." +normative_architecture_change = false +adr_required = false +closure_evidence = ["Exact staged contract generation and subsequent clean committed checking pass; unstaged/untracked inputs and concurrent index/HEAD changes are rejected before output creation. Ordinary write/check admission and V4 canonical bytes are retained.", "Rust 1.99 locked xtask checking and all 625 tests pass with serialized execution and the two original ignored annotations. Strict Clippy, formatting, architecture and contract validation pass. An unchanged advisory fixture failed in the initial concurrent run and passed alone and in the complete serialized suite; its concurrency reliability remains a qualification obligation, not a claimed repair."] + [[deviation]] id = "RCRV1-DEV-040" diff --git a/tools/xtask/src/main.rs b/tools/xtask/src/main.rs @@ -332,6 +332,7 @@ enum SourceMode { enum ServiceSourceLockMode { Check, Write, + Prepare, } #[derive(Clone, Copy, Debug, ValueEnum)] @@ -471,7 +472,7 @@ fn usage() { ); eprintln!(" cargo xtask source-lock --consumer-root <absolute-directory>"); eprintln!( - " cargo xtask service-source-lock --mode <check|write> --service-root <absolute-directory> --source-archive <absolute-bundle>" + " cargo xtask service-source-lock --mode <check|write|prepare> --service-root <absolute-directory> --source-archive <absolute-bundle>" ); eprintln!( " cargo xtask service-release-artifacts --mode <check|write> --service-root <absolute-directory> --lib-root <absolute-directory> --input-root <absolute-directory> --output-root <absolute-directory> --target <rust-target> --source-date-epoch <seconds> --candidate-digest <sha256>" @@ -794,6 +795,7 @@ fn run(args: &[String]) -> Result<(), String> { match mode { ServiceSourceLockMode::Check => service_source_lock_command::CommandMode::Check, ServiceSourceLockMode::Write => service_source_lock_command::CommandMode::Write, + ServiceSourceLockMode::Prepare => service_source_lock_command::CommandMode::Prepare, }, &service_root, &source_archive, @@ -1004,19 +1006,21 @@ mod tests { ]) .is_err() ); - assert!( - Cli::try_parse_from([ - "xtask", - "service-source-lock", - "--mode", - "write", - "--service-root", - "/tmp/service", - "--source-archive", - "/tmp/lib.bundle", - ]) - .is_ok() - ); + for mode in ["write", "prepare"] { + assert!( + Cli::try_parse_from([ + "xtask", + "service-source-lock", + "--mode", + mode, + "--service-root", + "/tmp/service", + "--source-archive", + "/tmp/lib.bundle", + ]) + .is_ok() + ); + } assert!( Cli::try_parse_from([ "xtask", diff --git a/tools/xtask/src/service_source_lock_command.rs b/tools/xtask/src/service_source_lock_command.rs @@ -46,6 +46,7 @@ const MAX_MANIFESTS: usize = 512; pub(crate) enum CommandMode { Check, Write, + Prepare, } #[derive(Clone, Copy, Debug, Eq, PartialEq)] @@ -172,7 +173,13 @@ fn run_with( } } let initial_head = service_head(&service_root)?; - validate_service_cleanliness(&service_root)?; + let prepared = mode == CommandMode::Prepare; + validate_service_cleanliness(&service_root, prepared)?; + let initial_index = if prepared { + Some(service_index(&service_root)?) + } else { + None + }; let root_manifest = read_bounded_regular( &service_root.join(CARGO_MANIFEST), @@ -206,13 +213,19 @@ fn run_with( "contracts/release/{}-artifact-contract.v4.json", metadata.service ); - let artifact_contract = exact_tree_archive::read_blob( - &service_root, - &initial_head, - &artifact_path, - MAX_MANIFEST_BYTES, - ) - .map_err(|_| CommandError::InvalidArtifactContract)?; + let artifact_contract = if prepared { + let specification = format!(":{artifact_path}"); + git_stdout(&service_root, ["show", &specification], MAX_MANIFEST_BYTES) + .map_err(|_| CommandError::InvalidArtifactContract)? + } else { + exact_tree_archive::read_blob( + &service_root, + &initial_head, + &artifact_path, + MAX_MANIFEST_BYTES, + ) + .map_err(|_| CommandError::InvalidArtifactContract)? + }; let live_contract = read_bounded_regular( &service_root.join(&artifact_path), MAX_MANIFEST_BYTES, @@ -222,10 +235,7 @@ fn run_with( return Err(CommandError::InvalidArtifactContract); } let artifact_contract_sha256 = sha256(&artifact_contract); - validate_service_cleanliness(&service_root)?; - if service_head(&service_root)? != initial_head { - return Err(CommandError::DirtyServiceSource); - } + validate_service_snapshot(&service_root, &initial_head, initial_index.as_deref())?; let desired = ServiceSourceLockV4::new(ServiceSourceLockV4Parts { service: &metadata.service, @@ -252,7 +262,7 @@ fn run_with( Err(CommandError::StaleSourceLock) } } - CommandMode::Write => { + CommandMode::Write | CommandMode::Prepare => { atomic_write_lock(&service_root, &lock_path, desired.canonical_bytes())?; let current = read_bounded_regular(&lock_path, MAX_LOCK_BYTES, CommandError::WriteFailure)?; @@ -266,14 +276,36 @@ fn run_with( } }; result?; - validate_service_cleanliness(&service_root)?; - if service_head(&service_root)? == initial_head { - Ok(()) + validate_service_snapshot(&service_root, &initial_head, initial_index.as_deref()) +} + +fn service_index(root: &Path) -> Result<String, CommandError> { + let bytes = + git_stdout(root, ["write-tree"], 128).map_err(|_| CommandError::DirtyServiceSource)?; + let tree = std::str::from_utf8(&bytes) + .map_err(|_| CommandError::DirtyServiceSource)? + .trim(); + if valid_lower_hex(tree, 40) { + Ok(tree.to_owned()) } else { Err(CommandError::DirtyServiceSource) } } +fn validate_service_snapshot( + root: &Path, + head: &str, + index: Option<&str>, +) -> Result<(), CommandError> { + validate_service_cleanliness(root, index.is_some())?; + if service_head(root)? != head + || index.is_some_and(|expected| service_index(root).as_deref() != Ok(expected)) + { + return Err(CommandError::DirtyServiceSource); + } + Ok(()) +} + fn service_head(root: &Path) -> Result<String, CommandError> { let bytes = git_stdout(root, ["rev-parse", "HEAD"], 128) .map_err(|_| CommandError::InvalidServiceRoot)?; @@ -311,23 +343,11 @@ fn validate_service_root(path: &Path) -> Result<PathBuf, CommandError> { } } -fn validate_service_cleanliness(root: &Path) -> Result<(), CommandError> { - git_status( - root, - [ - "diff", - "--quiet", - "--", - ".", - ":(exclude)radroots.service.source_lock.v4.toml", - ], - ) - .map_err(|_| CommandError::DirtyServiceSource)?; +fn validate_service_cleanliness(root: &Path, prepared: bool) -> Result<(), CommandError> { git_status( root, [ "diff", - "--cached", "--quiet", "--", ".", @@ -335,6 +355,20 @@ fn validate_service_cleanliness(root: &Path) -> Result<(), CommandError> { ], ) .map_err(|_| CommandError::DirtyServiceSource)?; + if !prepared { + git_status( + root, + [ + "diff", + "--cached", + "--quiet", + "--", + ".", + ":(exclude)radroots.service.source_lock.v4.toml", + ], + ) + .map_err(|_| CommandError::DirtyServiceSource)?; + } let untracked = git_stdout( root, ["ls-files", "--others", "--exclude-standard", "-z"], @@ -926,6 +960,18 @@ mod tests { service: PathBuf, } + struct IndexOnVerify { + service: PathBuf, + } + + impl RevisionReachability for IndexOnVerify { + fn verify(&self, _revision: &str) -> Result<(), CommandError> { + fs::write(self.service.join("concurrent"), b"staged").expect("concurrent file"); + git(&self.service, &["add", "concurrent"]); + Ok(()) + } + } + impl RevisionReachability for CommitOnVerify { fn verify(&self, _revision: &str) -> Result<(), CommandError> { fs::write(self.service.join("concurrent"), b"changed").expect("concurrent file"); @@ -1216,6 +1262,90 @@ radroots_service_host = {{ git = "{LIB_REPOSITORY}", rev = "{revision}", version } #[test] + fn prepared_candidate_binds_index_and_requires_committed_checking() { + let fixture = Fixture::new(); + let path = "contracts/release/myc-artifact-contract.v4.json"; + let contract = b"{\"candidate\":true}\n"; + fs::write(fixture.service.join(path), contract).expect("candidate contract"); + git(&fixture.service, &["add", path]); + assert_eq!( + run_with( + CommandMode::Write, + &fixture.service, + &fixture.archive, + &fixture.reachable() + ), + Err(CommandError::DirtyServiceSource) + ); + run_with( + CommandMode::Prepare, + &fixture.service, + &fixture.archive, + &fixture.reachable(), + ) + .expect("prepare staged candidate"); + let bytes = fs::read(fixture.service.join(LOCK_FILENAME)).expect("prepared lock"); + let lock = ServiceSourceLockV4::from_canonical_bytes(&bytes).expect("canonical lock"); + assert_eq!(lock.artifact_contract_sha256(), sha256(contract)); + assert_eq!( + run_with( + CommandMode::Check, + &fixture.service, + &fixture.archive, + &fixture.reachable() + ), + Err(CommandError::DirtyServiceSource) + ); + git(&fixture.service, &["add", LOCK_FILENAME]); + git( + &fixture.service, + &["commit", "--quiet", "-m", "verified candidate"], + ); + run_with( + CommandMode::Check, + &fixture.service, + &fixture.archive, + &fixture.reachable(), + ) + .expect("check complete committed candidate"); + } + + #[test] + fn preparation_refuses_unstaged_untracked_and_changed_index_inputs() { + for case in ["unstaged", "untracked", "index", "head"] { + let fixture = Fixture::new(); + if case == "unstaged" { + fs::write(fixture.service.join(CARGO_MANIFEST), b"changed").expect("unstaged"); + } else if case == "untracked" { + fs::write(fixture.service.join("unexpected"), b"changed").expect("untracked"); + } + let index = IndexOnVerify { + service: fixture.service.clone(), + }; + let head = CommitOnVerify { + service: fixture.service.clone(), + }; + let normal = fixture.reachable(); + let remote: &dyn RevisionReachability = match case { + "index" => &index, + "head" => &head, + _ => &normal, + }; + assert_eq!( + run_with( + CommandMode::Prepare, + &fixture.service, + &fixture.archive, + remote + ), + Err(CommandError::DirtyServiceSource), + "{case}" + ); + assert!(!fixture.service.join(LOCK_FILENAME).exists(), "{case}"); + } + } + + #[test] fn cargo_flake_toolchain_and_archive_drift_are_distinct() { let cases = [ (