feat(federation): verify materialised parent corpora

Signed-off-by: Tom Ballard <tom@armytage.co>

Author: tcballard

docs/cli.md

@@ -34,6 +34,44 @@ These apply across every command.
 
 ---
 
+## corpus digest
+
+Calculate the canonical pin for a parent corpus that is already materialised
+on disk. The command is read-only: it does not clone, fetch, update, write, or
+repin the parent.
+
+```bash
+decided corpus digest --root vendor/standards --corpus decisions
+```
+
+`--root` is the parent repository root and bounds configuration discovery to
+exactly `<root>/.decided/config.yaml`; the command never inherits a config from
+an ancestor. `--corpus` is a relative directory below that root. The config
+must declare an explicit valid `corpus.source`. On success stdout is exactly a
+full lowercase pin followed by a newline:
+
+```text
+sha256:899d5cdfa52b90a157b018dceb20f4f2901e0d56c91b089c12286c0b8b7b3325
+```
+
+Digest version 1 hashes the fixed domain bytes
+`asdecided-corpus-digest-v1\0`, then length-framed records. Each record is a
+one-byte tag, an unsigned 64-bit big-endian byte length, and the raw payload:
+
+1. tag `0x01`: parent `corpus.source` UTF-8 bytes;
+2. tag `0x02`: exact governing `.decided/config.yaml` bytes; then
+3. for every discovered Markdown file in corpus-relative POSIX UTF-8 path
+   order, tag `0x03` for the path bytes and tag `0x04` for its exact content
+   bytes.
+
+Checkout location, timestamps, filesystem iteration order, hidden paths, and
+non-`.md` files do not enter the digest. Absolute or `..` corpus paths, path
+escape, and traversed symlinks are rejected with stable `parent-corpus-*`
+errors. Exit `0` means the digest was calculated; exit `1` means the bounded
+materialisation could not be safely snapshotted.
+
+---
+
 ## validate
 
 Validate an artifact — or every artifact in a directory — for structural and

rust/decided-mcp/tests/docs_contract.rs

@@ -54,6 +54,7 @@ const SUPPORTED_DECIDED_COMMANDS: &[&str] = &[
     "retrieve",
     "sentry",
     "herald",
+    "corpus",
 ];
 
 fn documented_decided_command(line: &str) -> Option<&str> {

rust/decided/tests/cli.rs

@@ -171,3 +171,87 @@ fn export_rejects_an_invalid_configured_corpus_source() {
 
     fs::remove_dir_all(root).expect("remove CLI smoke corpus");
 }
+
+#[test]
+fn corpus_digest_prints_the_canonical_read_only_pin() {
+    let root = scratch_root();
+    fs::create_dir_all(root.join(".decided")).unwrap();
+    fs::create_dir_all(root.join("decisions/sub")).unwrap();
+    fs::write(
+        root.join(".decided/config.yaml"),
+        b"repository_key: STD\ncorpus:\n  source: acme/standards\n",
+    )
+    .unwrap();
+    fs::write(root.join("decisions/a.md"), b"alpha\n").unwrap();
+    fs::write(root.join("decisions/sub/b.md"), b"beta\r\n").unwrap();
+    fs::write(root.join("decisions/ignored.MD"), b"ignored\n").unwrap();
+    let before_config = fs::read(root.join(".decided/config.yaml")).unwrap();
+    let before_a = fs::read(root.join("decisions/a.md")).unwrap();
+    let root_text = root.to_string_lossy().into_owned();
+
+    let output = run(&[
+        "corpus",
+        "digest",
+        "--root",
+        &root_text,
+        "--corpus",
+        "decisions",
+    ]);
+    assert!(
+        output.status.success(),
+        "stdout={}, stderr={}",
+        String::from_utf8_lossy(&output.stdout),
+        String::from_utf8_lossy(&output.stderr)
+    );
+    assert_eq!(
+        output.stdout,
+        b"sha256:899d5cdfa52b90a157b018dceb20f4f2901e0d56c91b089c12286c0b8b7b3325\n"
+    );
+    assert!(output.stderr.is_empty());
+    assert_eq!(fs::read(root.join(".decided/config.yaml")).unwrap(), before_config);
+    assert_eq!(fs::read(root.join("decisions/a.md")).unwrap(), before_a);
+
+    fs::remove_dir_all(root).expect("remove CLI digest corpus");
+}
+
+#[test]
+fn corpus_digest_bounds_config_and_rejects_escaping_corpus_paths() {
+    let root = scratch_root();
+    fs::create_dir_all(root.join("parent/decisions")).unwrap();
+    fs::write(root.join("parent/decisions/a.md"), b"alpha\n").unwrap();
+    fs::create_dir_all(root.join(".decided")).unwrap();
+    fs::write(
+        root.join(".decided/config.yaml"),
+        b"repository_key: CHILD\ncorpus:\n  source: acme/child\n",
+    )
+    .unwrap();
+    let parent = root.join("parent").to_string_lossy().into_owned();
+
+    let missing = run(&[
+        "corpus",
+        "digest",
+        "--root",
+        &parent,
+        "--corpus",
+        "decisions",
+    ]);
+    assert_eq!(missing.status.code(), Some(1));
+    assert!(
+        String::from_utf8_lossy(&missing.stderr).contains("parent-corpus-config-missing")
+    );
+
+    let escaping = run(&[
+        "corpus",
+        "digest",
+        "--root",
+        &parent,
+        "--corpus",
+        "../decisions",
+    ]);
+    assert_eq!(escaping.status.code(), Some(1));
+    assert!(
+        String::from_utf8_lossy(&escaping.stderr).contains("parent-corpus-path-escape")
+    );
+
+    fs::remove_dir_all(root).expect("remove CLI digest corpus");
+}

rust/rac-engine/src/cli.rs

@@ -5,16 +5,16 @@
 //! (decision 9) — stdout stays byte-identical (empty on errors).
 
 use crate::commands::{
-    cmd_coverage, cmd_decisions_for, cmd_diagnose, cmd_diff, cmd_doctor, cmd_eval, cmd_export,
-    cmd_find, cmd_gate, cmd_herald, cmd_hook, cmd_improve, cmd_index, cmd_init, cmd_inspect,
-    cmd_mcp_stats, cmd_migrate, cmd_new, cmd_portfolio, cmd_quickstart, cmd_relationships,
-    cmd_rename, cmd_resolve, cmd_retrieve, cmd_review, cmd_schema, cmd_sentry, cmd_skill,
-    cmd_stats, cmd_telemetry, cmd_templates, cmd_usage, cmd_validate, CoverageArgs,
-    DecisionsForArgs, DiagnoseArgs, DiffArgs, DoctorArgs, EvalArgs, ExportArgs, FindArgs,
-    GateArgs, HeraldArgs, HookArgs, ImproveArgs, IndexArgs, InitArgs, InspectArgs, McpStatsArgs,
-    MigrateArgs, NewArgs, PortfolioArgs, QuickstartArgs, RelationshipsArgs, RenameArgs,
-    ResolveArgs, RetrieveArgs, ReviewArgs, SchemaArgs, SentryArgs, SkillArgs, StatsArgs,
-    TelemetryArgs, TemplatesArgs, UsageArgs, ValidateArgs, WatchkeeperArgs,
+    cmd_corpus_digest, cmd_coverage, cmd_decisions_for, cmd_diagnose, cmd_diff, cmd_doctor,
+    cmd_eval, cmd_export, cmd_find, cmd_gate, cmd_herald, cmd_hook, cmd_improve, cmd_index,
+    cmd_init, cmd_inspect, cmd_mcp_stats, cmd_migrate, cmd_new, cmd_portfolio, cmd_quickstart,
+    cmd_relationships, cmd_rename, cmd_resolve, cmd_retrieve, cmd_review, cmd_schema, cmd_sentry,
+    cmd_skill, cmd_stats, cmd_telemetry, cmd_templates, cmd_usage, cmd_validate,
+    CorpusDigestArgs, CoverageArgs, DecisionsForArgs, DiagnoseArgs, DiffArgs, DoctorArgs, EvalArgs,
+    ExportArgs, FindArgs, GateArgs, HeraldArgs, HookArgs, ImproveArgs, IndexArgs, InitArgs,
+    InspectArgs, McpStatsArgs, MigrateArgs, NewArgs, PortfolioArgs, QuickstartArgs,
+    RelationshipsArgs, RenameArgs, ResolveArgs, RetrieveArgs, ReviewArgs, SchemaArgs, SentryArgs,
+    SkillArgs, StatsArgs, TelemetryArgs, TemplatesArgs, UsageArgs, ValidateArgs, WatchkeeperArgs,
 };
 use crate::commands::cmd_watchkeeper;
 use crate::output::rac_version;
@@ -156,7 +156,10 @@ fn run_dispatch(args: &[String]) -> u8 {
     // Native-only additions dispatch but are deliberately NOT in SUBCOMMANDS:
     // the retired Python oracle's `invalid choice` bytes remain pinned by the
     // bounded compatibility suite.
-    if !matches!(first.as_str(), "retrieve" | "sentry" | "herald" | "diagnose")
+    if !matches!(
+        first.as_str(),
+        "retrieve" | "sentry" | "herald" | "diagnose" | "corpus"
+    )
         && !SUBCOMMANDS.contains(&first.as_str())
     {
         return argparse_error("decided", &invalid_choice_message(first));
@@ -232,6 +235,7 @@ fn run_dispatch(args: &[String]) -> u8 {
         "quickstart" => run_quickstart(&rest),
         "rename" => run_rename(&rest),
         "migrate" => run_migrate(&rest),
+        "corpus" => run_corpus(&rest),
         other => {
             eprintln!("decided-rs: subcommand '{other}' is not yet implemented");
             2
@@ -278,6 +282,78 @@ fn take_opt_value(
     }
 }
 
+fn run_corpus(rest: &[&String]) -> u8 {
+    let prog = "decided corpus";
+    let mut action: Option<String> = None;
+    let mut root: Option<String> = None;
+    let mut corpus: Option<String> = None;
+    let mut extras: Vec<String> = Vec::new();
+    let mut positional_only = false;
+
+    let mut i = 0;
+    while i < rest.len() {
+        let arg = rest[i].as_str();
+        if positional_only || arg == "-" || !arg.starts_with('-') {
+            if action.is_none() {
+                if arg != "digest" {
+                    return argparse_error(
+                        prog,
+                        &format!(
+                            "argument action: invalid choice: '{arg}' (choose from 'digest')"
+                        ),
+                    );
+                }
+                action = Some(arg.to_string());
+            } else {
+                extras.push(arg.to_string());
+            }
+            i += 1;
+            continue;
+        }
+        match arg {
+            "--" => positional_only = true,
+            other if other == "--root" || other.starts_with("--root=") => {
+                match take_opt_value(prog, "--root", other, rest, &mut i) {
+                    Ok(value) => root = Some(value),
+                    Err(code) => return code,
+                }
+            }
+            other if other == "--corpus" || other.starts_with("--corpus=") => {
+                match take_opt_value(prog, "--corpus", other, rest, &mut i) {
+                    Ok(value) => corpus = Some(value),
+                    Err(code) => return code,
+                }
+            }
+            other => extras.push(other.to_string()),
+        }
+        i += 1;
+    }
+
+    if action.is_none() {
+        return argparse_error(prog, "the following arguments are required: action");
+    }
+    if root.is_none() || corpus.is_none() {
+        let missing = match (root.is_none(), corpus.is_none()) {
+            (true, true) => "--root, --corpus",
+            (true, false) => "--root",
+            (false, true) => "--corpus",
+            (false, false) => unreachable!(),
+        };
+        return argparse_error(
+            prog,
+            &format!("the following arguments are required: {missing}"),
+        );
+    }
+    if !extras.is_empty() {
+        return unrecognized(&extras);
+    }
+
+    cmd_corpus_digest(&CorpusDigestArgs {
+        root: root.expect("checked above"),
+        corpus: corpus.expect("checked above"),
+    }) as u8
+}
+
 fn run_validate(rest: &[&String]) -> u8 {
     let prog = "decided validate";
     let mut file: Option<String> = None;

rust/rac-engine/src/commands.rs

@@ -2244,6 +2244,27 @@ pub fn cmd_rename(args: &RenameArgs) -> i32 {
     EXIT_OK
 }
 
+pub struct CorpusDigestArgs {
+    pub root: String,
+    pub corpus: String,
+}
+
+/// Read-only operator calculation for the canonical parent corpus pin. The
+/// implementation consumes only local bytes below `root` and cannot write,
+/// fetch, refresh, or repin anything.
+pub fn cmd_corpus_digest(args: &CorpusDigestArgs) -> i32 {
+    match crate::federation::calculate_parent_digest(&args.root, &args.corpus) {
+        Ok(result) => {
+            emit(result.digest);
+            EXIT_OK
+        }
+        Err(error) => {
+            eprintln!("decided: {error}");
+            EXIT_VALIDATION_FAILED
+        }
+    }
+}
+
 pub struct TelemetryArgs {
     /// Validated positional choice; argparse default is `status`.
     pub action: String,