From 6a109d94bcf8e7bbb4fd0c34611cecbd414713cb Mon Sep 17 00:00:00 2001 From: Bradley Hilton Date: Wed, 1 Jul 2026 14:28:31 -0500 Subject: [PATCH 01/21] =?UTF-8?q?feat(canonical):=20add=20atomic-canonical?= =?UTF-8?q?=20crate=20=E2=80=94=20Recording-the-Why=20engine=20(M0)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Introduces the canonical-record layer that proves the "record the why" round trip in isolation, without yet touching the vault store: author (frontmatter + container directives) -> lift -> canonical JSON-LD node -> JCS (RFC 8785) + BLAKE3 content hash -> Ed25519 Data Integrity proof (did:atomic, eddsa-jcs-2022) -> SHACL-style gate -> render projection Modules: vocab (closed registry, single source of truth), jcs (single canonicalization entry point for hash + sign), hash, did, proof, directive (container/leaf parser — type from name, not heading position), lift, gate (IntentShape: presence enforced, content honest, closed-world), render (pure projection; status regenerated from the spine — single authoring site). 21 tests (13 unit + 8 integration) green; clippy clean. Signing uses a non-production dev identity (plaintext keys — see crate docs). Vault wiring, CLI verbs, Memory, W3C PROV, and a real SHACL engine are later milestones. Spec: docs/recording-the-why.md. Plan + adversarial critique: docs/recording-the-why-plan.md. --- Cargo.lock | 13 + Cargo.toml | 2 + atomic-canonical/Cargo.toml | 18 + atomic-canonical/src/did.rs | 71 ++++ atomic-canonical/src/directive.rs | 237 ++++++++++++ atomic-canonical/src/error.rs | 26 ++ atomic-canonical/src/gate.rs | 143 +++++++ atomic-canonical/src/hash.rs | 41 ++ atomic-canonical/src/jcs.rs | 98 +++++ atomic-canonical/src/lib.rs | 68 ++++ atomic-canonical/src/lift.rs | 213 +++++++++++ atomic-canonical/src/node.rs | 145 ++++++++ atomic-canonical/src/proof.rs | 110 ++++++ atomic-canonical/src/render.rs | 98 +++++ atomic-canonical/src/vocab.rs | 80 ++++ atomic-canonical/tests/roundtrip.rs | 161 ++++++++ docs/recording-the-why-plan.md | 225 +++++++++++ docs/recording-the-why.md | 556 ++++++++++++++++++++++++++++ 18 files changed, 2305 insertions(+) create mode 100644 atomic-canonical/Cargo.toml create mode 100644 atomic-canonical/src/did.rs create mode 100644 atomic-canonical/src/directive.rs create mode 100644 atomic-canonical/src/error.rs create mode 100644 atomic-canonical/src/gate.rs create mode 100644 atomic-canonical/src/hash.rs create mode 100644 atomic-canonical/src/jcs.rs create mode 100644 atomic-canonical/src/lib.rs create mode 100644 atomic-canonical/src/lift.rs create mode 100644 atomic-canonical/src/node.rs create mode 100644 atomic-canonical/src/proof.rs create mode 100644 atomic-canonical/src/render.rs create mode 100644 atomic-canonical/src/vocab.rs create mode 100644 atomic-canonical/tests/roundtrip.rs create mode 100644 docs/recording-the-why-plan.md create mode 100644 docs/recording-the-why.md diff --git a/Cargo.lock b/Cargo.lock index f7dccf85..00883ba6 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -141,6 +141,19 @@ dependencies = [ "zstd", ] +[[package]] +name = "atomic-canonical" +version = "0.8.0" +dependencies = [ + "atomic-identity", + "blake3", + "chrono", + "data-encoding", + "serde", + "serde_json", + "thiserror 1.0.69", +] + [[package]] name = "atomic-cli" version = "0.9.1" diff --git a/Cargo.toml b/Cargo.toml index 72a9fcf7..7ff0371e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -2,6 +2,7 @@ resolver = "2" members = [ "atomic-agent", + "atomic-canonical", "atomic-cli", "atomic-core", "atomic-config", @@ -24,6 +25,7 @@ rust-version = "1.90" [workspace.dependencies] # Core atomic-agent = { path = "atomic-agent" } +atomic-canonical = { path = "atomic-canonical" } atomic-core = { path = "atomic-core" } atomic-config = { path = "atomic-config" } atomic-identity = { path = "atomic-identity" } diff --git a/atomic-canonical/Cargo.toml b/atomic-canonical/Cargo.toml new file mode 100644 index 00000000..526fa1e7 --- /dev/null +++ b/atomic-canonical/Cargo.toml @@ -0,0 +1,18 @@ +[package] +name = "atomic-canonical" +description = "Recording the Why — canonical typed nodes (JSON-LD), JCS+BLAKE3 hashing, Data Integrity proofs, the lift, and the SHACL-style gate" +version.workspace = true +edition.workspace = true +authors.workspace = true +license.workspace = true +repository.workspace = true +rust-version.workspace = true + +[dependencies] +serde = { workspace = true } +serde_json = { workspace = true } +blake3 = { workspace = true } +chrono = { workspace = true } +thiserror = { workspace = true } +data-encoding = { workspace = true } +atomic-identity = { workspace = true } diff --git a/atomic-canonical/src/did.rs b/atomic-canonical/src/did.rs new file mode 100644 index 00000000..225a30bf --- /dev/null +++ b/atomic-canonical/src/did.rs @@ -0,0 +1,71 @@ +//! The `did:atomic` method (in-tree, per the M0 decision). +//! +//! An identity's DID is derived from its Ed25519 public key exactly the way +//! atomic already derives `IdentityId`: `blake3(pubkey)`, base32-encoded. This +//! keeps the DID consistent with the rest of atomic's identity model. +//! +//! `did:atomic:` is a *fingerprint* of the key, so the +//! public key cannot be recovered from the DID alone — verification needs a +//! resolver (an `IdentityStore` lookup). For the self-contained M0 crate, +//! `verify` takes the `PublicKey` directly and `did_matches_public_key` +//! confirms the DID belongs to that key. The store-backed resolver arrives in +//! M1 when this wires into the vault. +//! +//! NOTE (open question, deferred): PROV / Data-Integrity tooling generally +//! assumes `did:key` (multibase+multicodec). `did:atomic` is chosen for M0 for +//! simplicity and in-tree consistency; `proof.rs` keeps the method swappable. + +use atomic_identity::keypair::PublicKey; + +pub const DID_ATOMIC_PREFIX: &str = "did:atomic:"; + +/// Build the `did:atomic:...` identifier for a public key. +pub fn did_for_public_key(public_key: &PublicKey) -> String { + let fingerprint = blake3::hash(public_key.as_bytes()); + format!( + "{}{}", + DID_ATOMIC_PREFIX, + data_encoding::BASE32_NOPAD.encode(fingerprint.as_bytes()) + ) +} + +/// The verification method id used in a proof (`#key-1`). +pub fn verification_method(did: &str) -> String { + format!("{did}#key-1") +} + +/// The DID out of a `#fragment` verification method string. +pub fn did_from_verification_method(vm: &str) -> &str { + vm.split('#').next().unwrap_or(vm) +} + +/// Does this DID correspond to the given public key? +pub fn did_matches_public_key(did: &str, public_key: &PublicKey) -> bool { + did == did_for_public_key(public_key) +} + +#[cfg(test)] +mod tests { + use super::*; + use atomic_identity::keypair::KeyPair; + + #[test] + fn did_is_stable_and_key_bound() { + let kp = KeyPair::generate(); + let did = did_for_public_key(&kp.public); + assert!(did.starts_with("did:atomic:")); + assert_eq!(did, did_for_public_key(&kp.public)); + assert!(did_matches_public_key(&did, &kp.public)); + + let other = KeyPair::generate(); + assert!(!did_matches_public_key(&did, &other.public)); + } + + #[test] + fn verification_method_roundtrips_to_did() { + let kp = KeyPair::generate(); + let did = did_for_public_key(&kp.public); + let vm = verification_method(&did); + assert_eq!(did_from_verification_method(&vm), did); + } +} diff --git a/atomic-canonical/src/directive.rs b/atomic-canonical/src/directive.rs new file mode 100644 index 00000000..57a9b21b --- /dev/null +++ b/atomic-canonical/src/directive.rs @@ -0,0 +1,237 @@ +//! Container/leaf directive parser. +//! +//! The body's typed structure is explicit and local: the lift reads a node's +//! type off the directive name, never off heading position (the fragile +//! "positional lift" the doc rejects). M0 supports: +//! - container: `:::name{#id key=value ...}` … prose … `:::` +//! - leaf: `::name{key=value ...}` (edges only, no body) +//! +//! Inline directives are deferred (not needed for the Intent slice). + +use std::collections::BTreeMap; + +use crate::error::{CanonicalError, Result}; +use crate::vocab; + +/// A parsed directive block. +#[derive(Debug, Clone, PartialEq)] +pub struct Directive { + pub name: String, + pub id: Option, + pub attrs: BTreeMap, + /// Prose inside a container directive (trimmed). Empty for leaf directives. + pub body: String, + /// Leaf directives nested inside this container (e.g. `::file-ref`). + pub children: Vec, +} + +impl Directive { + pub fn attr(&self, key: &str) -> Option<&str> { + self.attrs.get(key).map(|s| s.as_str()) + } +} + +/// Parse all top-level directives out of a markdown body. Prose outside any +/// directive is ignored by the lift (it stays as unlifted narrative). +pub fn parse(body: &str) -> Result> { + let lines: Vec<&str> = body.lines().collect(); + let mut out = Vec::new(); + let mut i = 0; + while i < lines.len() { + let trimmed = lines[i].trim_start(); + if let Some(rest) = trimmed.strip_prefix(":::") { + // Container open (a bare "):::" close is handled inside). + let (name, attrs_src) = split_name_attrs(rest); + if name.is_empty() { + // stray close or empty — skip + i += 1; + continue; + } + check_known(&name)?; + let (id, attrs) = parse_attrs(attrs_src)?; + // Gather body lines until a line that is exactly ":::". + let mut body_lines: Vec<&str> = Vec::new(); + let mut children = Vec::new(); + i += 1; + let mut closed = false; + while i < lines.len() { + let lt = lines[i].trim(); + if lt == ":::" { + closed = true; + i += 1; + break; + } + // A leaf directive nested in the container body. + if lt.starts_with("::") && !lt.starts_with(":::") { + if let Some(leaf) = parse_leaf(lt)? { + children.push(leaf); + i += 1; + continue; + } + } + body_lines.push(lines[i]); + i += 1; + } + if !closed { + return Err(CanonicalError::Directive(format!( + "unterminated container directive ':::{name}' (missing closing ':::')" + ))); + } + out.push(Directive { + name, + id, + attrs, + body: body_lines.join("\n").trim().to_string(), + children, + }); + } else if trimmed.starts_with("::") { + if let Some(leaf) = parse_leaf(trimmed)? { + out.push(leaf); + } + i += 1; + } else { + i += 1; + } + } + Ok(out) +} + +fn parse_leaf(line: &str) -> Result> { + let rest = match line.trim().strip_prefix("::") { + Some(r) => r, + None => return Ok(None), + }; + let (name, attrs_src) = split_name_attrs(rest); + if name.is_empty() { + return Ok(None); + } + check_known(&name)?; + let (id, attrs) = parse_attrs(attrs_src)?; + Ok(Some(Directive { + name, + id, + attrs, + body: String::new(), + children: Vec::new(), + })) +} + +fn check_known(name: &str) -> Result<()> { + if !vocab::is_known_directive(name) { + return Err(CanonicalError::Directive(format!( + "unknown directive ':{name}' — not in the closed registry" + ))); + } + Ok(()) +} + +/// Split "name{attrs}" (or "name") into (name, attrs-source-without-braces). +fn split_name_attrs(s: &str) -> (String, &str) { + let s = s.trim(); + if let Some(open) = s.find('{') { + let name = s[..open].trim().to_string(); + let attrs = if let Some(close) = s.rfind('}') { + &s[open + 1..close] + } else { + &s[open + 1..] + }; + (name, attrs) + } else { + (s.to_string(), "") + } +} + +/// Parse `#id key=value key2="quoted value"` into (id, attrs). +fn parse_attrs(src: &str) -> Result<(Option, BTreeMap)> { + let mut id = None; + let mut attrs = BTreeMap::new(); + for token in tokenize(src) { + if let Some(rest) = token.strip_prefix('#') { + id = Some(rest.to_string()); + } else if let Some(eq) = token.find('=') { + let key = token[..eq].trim().to_string(); + let mut val = token[eq + 1..].trim().to_string(); + if val.len() >= 2 && val.starts_with('"') && val.ends_with('"') { + val = val[1..val.len() - 1].to_string(); + } + attrs.insert(key, val); + } + // bare tokens with neither # nor = are ignored + } + Ok((id, attrs)) +} + +/// Whitespace tokenizer that keeps double-quoted values intact. +fn tokenize(src: &str) -> Vec { + let mut tokens = Vec::new(); + let mut cur = String::new(); + let mut in_quotes = false; + for c in src.chars() { + match c { + '"' => { + in_quotes = !in_quotes; + cur.push(c); + } + c if c.is_whitespace() && !in_quotes => { + if !cur.is_empty() { + tokens.push(std::mem::take(&mut cur)); + } + } + c => cur.push(c), + } + } + if !cur.is_empty() { + tokens.push(cur); + } + tokens +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn parses_container_with_attrs_and_prose() { + let body = ":::acceptance-criterion{#WORD-5-ac-1 status=met verifiedBy=did:atomic:lee evidence=urn:atomic:change:01J8}\nOn first load, the app presents a modal.\n:::"; + let ds = parse(body).unwrap(); + assert_eq!(ds.len(), 1); + let d = &ds[0]; + assert_eq!(d.name, "acceptance-criterion"); + assert_eq!(d.id.as_deref(), Some("WORD-5-ac-1")); + assert_eq!(d.attr("status"), Some("met")); + assert_eq!(d.attr("verifiedBy"), Some("did:atomic:lee")); + assert_eq!(d.body, "On first load, the app presents a modal."); + } + + #[test] + fn parses_task_with_nested_file_ref() { + let body = ":::task{#t1 status=done satisfies=WORD-5-ac-1}\nAdd modal.\n::file-ref{path=src/App.tsx}\n:::"; + let ds = parse(body).unwrap(); + let t = &ds[0]; + assert_eq!(t.name, "task"); + assert_eq!(t.children.len(), 1); + assert_eq!(t.children[0].name, "file-ref"); + assert_eq!(t.children[0].attr("path"), Some("src/App.tsx")); + assert_eq!(t.body, "Add modal."); + } + + #[test] + fn quoted_values_keep_spaces() { + let body = ":::why{}\nprose\n:::"; + let ds = parse(body).unwrap(); + assert_eq!(ds[0].name, "why"); + assert_eq!(ds[0].body, "prose"); + } + + #[test] + fn unknown_directive_is_error() { + let body = ":::whatever{}\nx\n:::"; + assert!(parse(body).is_err()); + } + + #[test] + fn unterminated_container_is_error() { + let body = ":::why{}\nno close here"; + assert!(parse(body).is_err()); + } +} diff --git a/atomic-canonical/src/error.rs b/atomic-canonical/src/error.rs new file mode 100644 index 00000000..dff93241 --- /dev/null +++ b/atomic-canonical/src/error.rs @@ -0,0 +1,26 @@ +//! Error type for the canonical layer. + +use thiserror::Error; + +#[derive(Debug, Error)] +pub enum CanonicalError { + #[error("lift error: {0}")] + Lift(String), + + #[error("directive parse error: {0}")] + Directive(String), + + #[error("proof error: {0}")] + Proof(String), + + #[error("content hash mismatch: node says {expected}, recomputed {actual}")] + HashMismatch { expected: String, actual: String }, + + #[error("signature verification failed: {0}")] + Verification(String), + + #[error("identity error: {0}")] + Identity(#[from] atomic_identity::IdentityError), +} + +pub type Result = std::result::Result; diff --git a/atomic-canonical/src/gate.rs b/atomic-canonical/src/gate.rs new file mode 100644 index 00000000..cb7930c5 --- /dev/null +++ b/atomic-canonical/src/gate.rs @@ -0,0 +1,143 @@ +//! The gate — a SHACL-style validator that decides whether a node may enter +//! the graph. M0 hand-codes the shapes in Rust; a real SHACL evaluator over +//! Turtle shapes arrives in a later milestone. The *semantics* are what matter +//! here and they match the doc: +//! +//! - **Presence is enforced, content is left honest.** The gate requires the +//! reason *exists* (a `why`), authorship is present, and the proof is +//! present. It never grades the reason's prose. +//! - **`status: done` is granted, not written.** A caller advancing an intent +//! to `done` must pass the gate first. +//! - **A met acceptance criterion must carry evidence.** `acStatus = met` +//! without `verifiedBy` + `evidence` is rejected (a checked box with no +//! proof fails). +//! - **Closed world.** Unknown status values are rejected. +//! +//! The gate never auto-fixes a load-bearing fact — it only reports. + +use crate::node::CanonicalNode; +use crate::vocab; + +/// A single shape violation. +#[derive(Debug, Clone, PartialEq)] +pub struct Violation { + /// The `@id` of the focus node (or sub-node) that failed. + pub focus_node: String, + /// The shape that was violated. + pub shape: String, + /// The property path at fault (if any). + pub path: Option, + /// Human-readable message. + pub message: String, +} + +/// The result of validating a node. +#[derive(Debug, Clone, PartialEq)] +pub struct ValidationReport { + pub conforms: bool, + pub results: Vec, +} + +impl ValidationReport { + fn from(results: Vec) -> Self { + ValidationReport { + conforms: results.is_empty(), + results, + } + } +} + +impl std::fmt::Display for ValidationReport { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + if self.conforms { + return write!(f, "conforms: yes"); + } + writeln!(f, "conforms: no ({} violation(s))", self.results.len())?; + for v in &self.results { + let path = v.path.as_deref().unwrap_or("-"); + writeln!(f, " ✗ [{}] {} ({}): {}", v.shape, v.focus_node, path, v.message)?; + } + Ok(()) + } +} + +/// Validate a canonical Intent node against `IntentShape` (+ sub-shapes). +pub fn validate_intent(node: &CanonicalNode) -> ValidationReport { + let mut out = Vec::new(); + let focus = &node.id; + + // status ∈ closed set, exactly one (it is a single field, so cardinality holds). + if !vocab::is_known_intent_status(&node.status) { + out.push(Violation { + focus_node: focus.clone(), + shape: "IntentShape".into(), + path: Some("status".into()), + message: format!( + "status '{}' is not one of {:?}", + node.status, + vocab::INTENT_STATUS + ), + }); + } + + // attributedTo must be present (sh:class prov:Agent deferred — see M0 notes). + if node.attributed_to.as_deref().unwrap_or("").is_empty() { + out.push(Violation { + focus_node: focus.clone(), + shape: "IntentShape".into(), + path: Some("attributedTo".into()), + message: "author (attributedTo) must be present as a DID".into(), + }); + } + + // proof must be present. + if node.proof.is_none() { + out.push(Violation { + focus_node: focus.clone(), + shape: "IntentShape".into(), + path: Some("proof".into()), + message: "intent must carry a Data Integrity proof".into(), + }); + } + + // presence-enforced: a reason must exist (content left honest). + match &node.why { + Some(w) if !w.trim().is_empty() => {} + _ => out.push(Violation { + focus_node: focus.clone(), + shape: "IntentShape".into(), + path: Some("why".into()), + message: "a reason (why) must be present — its content is not graded".into(), + }), + } + + // Each acceptance criterion satisfies AcceptanceCriterionShape. + for ac in &node.has_acceptance_criterion { + if !vocab::is_known_ac_status(&ac.ac_status) { + out.push(Violation { + focus_node: ac.id.clone(), + shape: "AcceptanceCriterionShape".into(), + path: Some("acStatus".into()), + message: format!( + "acStatus '{}' is not one of {:?}", + ac.ac_status, + vocab::AC_STATUS + ), + }); + } + if ac.ac_status == "met" { + let has_verifier = !ac.verified_by.as_deref().unwrap_or("").is_empty(); + let has_evidence = !ac.evidence.as_deref().unwrap_or("").is_empty(); + if !has_verifier || !has_evidence { + out.push(Violation { + focus_node: ac.id.clone(), + shape: "AcceptanceCriterionShape".into(), + path: Some("acStatus".into()), + message: "a met acceptance criterion must carry verifiedBy and evidence".into(), + }); + } + } + } + + ValidationReport::from(out) +} diff --git a/atomic-canonical/src/hash.rs b/atomic-canonical/src/hash.rs new file mode 100644 index 00000000..cfd3a009 --- /dev/null +++ b/atomic-canonical/src/hash.rs @@ -0,0 +1,41 @@ +//! Content hashing over the canonical node. +//! +//! The hash is `blake3(JCS(node))`, not `blake3(markdown body)`. This is the +//! load-bearing change from atomic's current vault (which hashes the raw body +//! and so attests an unstructured surface). Hashing the canonical typed node +//! is what makes the content hash a hash *of the meaning*. +//! +//! Goes through the single `jcs::canonicalize` entry point so it can never +//! drift from what `proof.rs` signs. + +use serde_json::Value; + +use crate::jcs; + +/// The `blake3:` content hash of a JSON value's canonical form. +pub fn content_hash(value: &Value) -> String { + let canonical = jcs::canonicalize(value); + let digest = blake3::hash(canonical.as_bytes()); + format!("blake3:{}", digest.to_hex()) +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + + #[test] + fn hash_is_deterministic_and_key_order_independent() { + let a = json!({ "b": 1, "a": 2 }); + let b = json!({ "a": 2, "b": 1 }); + assert_eq!(content_hash(&a), content_hash(&b)); + assert!(content_hash(&a).starts_with("blake3:")); + } + + #[test] + fn hash_changes_with_content() { + let a = json!({ "status": "backlog" }); + let b = json!({ "status": "done" }); + assert_ne!(content_hash(&a), content_hash(&b)); + } +} diff --git a/atomic-canonical/src/jcs.rs b/atomic-canonical/src/jcs.rs new file mode 100644 index 00000000..d1158f7b --- /dev/null +++ b/atomic-canonical/src/jcs.rs @@ -0,0 +1,98 @@ +//! JSON Canonicalization Scheme (RFC 8785), the subset RtW needs. +//! +//! We hash and sign over canonical bytes, not over the authored markdown, so +//! the content hash attests the *typed node* rather than an unstructured +//! surface. Canonicalization must be deterministic: object keys sorted, no +//! insignificant whitespace, stable string/number encoding. +//! +//! This is the **single canonicalization entry point** — both the content +//! hash (`hash.rs`) and the Data Integrity proof (`proof.rs`) go through +//! `canonicalize`, so the two can never drift. +//! +//! Scope note (M0): object-key sorting is by UTF-8 byte order. RFC 8785 +//! specifies sorting by UTF-16 code units; for the ASCII property names in +//! our vocabulary the two orderings are identical. Numbers are emitted via +//! `serde_json`'s formatter, which is exact for the integer/simple values we +//! use. Both are revisited if the vocabulary ever admits non-ASCII keys or +//! floating-point payloads. + +use serde_json::Value; + +/// Canonicalize a JSON value into its RFC-8785 string form. +pub fn canonicalize(value: &Value) -> String { + let mut out = String::new(); + write_value(&mut out, value); + out +} + +fn write_value(out: &mut String, value: &Value) { + match value { + Value::Null => out.push_str("null"), + Value::Bool(true) => out.push_str("true"), + Value::Bool(false) => out.push_str("false"), + Value::Number(n) => out.push_str(&n.to_string()), + Value::String(s) => write_json_string(out, s), + Value::Array(items) => { + out.push('['); + for (i, item) in items.iter().enumerate() { + if i > 0 { + out.push(','); + } + write_value(out, item); + } + out.push(']'); + } + Value::Object(map) => { + let mut keys: Vec<&String> = map.keys().collect(); + keys.sort_by(|a, b| a.as_bytes().cmp(b.as_bytes())); + out.push('{'); + for (i, key) in keys.iter().enumerate() { + if i > 0 { + out.push(','); + } + write_json_string(out, key); + out.push(':'); + write_value(out, &map[*key]); + } + out.push('}'); + } + } +} + +/// Emit a JSON string with standard escaping. `serde_json` produces a valid, +/// minimally-escaped JSON string literal (quotes included), which matches JCS +/// for the ASCII content in our records. +fn write_json_string(out: &mut String, s: &str) { + out.push_str(&serde_json::to_string(s).expect("string serialization is infallible")); +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + + #[test] + fn sorts_object_keys() { + let v = json!({ "b": 1, "a": 2, "c": 3 }); + assert_eq!(canonicalize(&v), r#"{"a":2,"b":1,"c":3}"#); + } + + #[test] + fn no_insignificant_whitespace_and_nesting() { + let v = json!({ "z": [1, 2, { "y": "x" }], "a": true }); + assert_eq!(canonicalize(&v), r#"{"a":true,"z":[1,2,{"y":"x"}]}"#); + } + + #[test] + fn key_order_is_input_independent() { + let a = json!({ "one": 1, "two": 2 }); + let b = json!({ "two": 2, "one": 1 }); + assert_eq!(canonicalize(&a), canonicalize(&b)); + } + + #[test] + fn escapes_strings() { + let v = json!({ "k": "a\"b\nc" }); + assert_eq!(canonicalize(&v), r#"{"k":"a\"b\nc"}"#); + } +} diff --git a/atomic-canonical/src/lib.rs b/atomic-canonical/src/lib.rs new file mode 100644 index 00000000..1f633410 --- /dev/null +++ b/atomic-canonical/src/lib.rs @@ -0,0 +1,68 @@ +//! # atomic-canonical — Recording the Why +//! +//! The canonical-record layer for Atomic's "record the why" design. It turns an +//! authored surface (markdown frontmatter + container directives) into a +//! **canonical typed node** (JSON-LD), hashes it deterministically +//! (JCS + BLAKE3), signs it (Ed25519 Data Integrity proof), gates it +//! (SHACL-style, closed-world), and renders it back (a pure projection). +//! +//! Three layers, kept apart: +//! - **surface** — markdown the author writes (frontmatter spine + directives) +//! - **canonical** — the typed node that gets hashed and signed ([`node`]) +//! - **render** — the read-time projection ([`render`]) +//! +//! Load-bearing principles enforced here: *presence is enforced, content is +//! left honest* (the `why` is never schematized); *the vocabulary is closed* +//! ([`vocab`]); *the fact is singular* (status lives only in the spine and is +//! regenerated on render). +//! +//! ## M0 scope +//! This crate proves the Intent round trip **in isolation**. Wiring it into the +//! vault store — redefining `content_hash`, re-plumbing drift detection and the +//! manifest merkle, the CLI verbs — is M1 and deliberately not done here, so the +//! existing vault stays stable while the engine is validated. +//! +//! ## Security caveat (M0) +//! Signing uses atomic's existing Ed25519 identities, whose secret keys are +//! currently stored **unencrypted** on disk. M0 treats signing identities as +//! **non-production dev identities**. Key-at-rest encryption must land before +//! any attested node is trusted in a real/shared setting. + +pub mod did; +pub mod directive; +pub mod error; +pub mod gate; +pub mod hash; +pub mod jcs; +pub mod lift; +pub mod node; +pub mod proof; +pub mod render; +pub mod vocab; + +pub use error::{CanonicalError, Result}; +pub use gate::{validate_intent, ValidationReport, Violation}; +pub use node::{AcceptanceCriterion, CanonicalNode, Proof, Task}; +pub use render::{render, Target}; + +use atomic_identity::identity::Identity; +use atomic_identity::keypair::KeyPair; +use serde_json::{Map, Value}; + +/// Lift an authored intent (frontmatter + body) into a canonical node, +/// attest it (hash + sign) with the given identity, and return the node. +/// The node is *not* gated here — call [`validate_intent`] to gate it. +pub fn lift_and_attest( + frontmatter: &Map, + body: &str, + identity: &Identity, + keypair: &KeyPair, +) -> Result { + let node = lift::lift_intent(frontmatter, body)?; + Ok(proof::attest(node, identity, keypair)) +} + +/// Verify an attested node's content hash and signature against a public key. +pub fn verify(node: &CanonicalNode, public_key: &atomic_identity::keypair::PublicKey) -> Result<()> { + proof::verify(node, public_key) +} diff --git a/atomic-canonical/src/lift.rs b/atomic-canonical/src/lift.rs new file mode 100644 index 00000000..6a9f877f --- /dev/null +++ b/atomic-canonical/src/lift.rs @@ -0,0 +1,213 @@ +//! The lift — the typed extractor that turns the authored surface (frontmatter +//! spine + directive body) into a canonical node. +//! +//! Frontmatter keys → spine properties. Directive names → node/sub-node types. +//! Directive attributes → typed properties and edges. Directive prose → the +//! unconstrained text slot. Anything without a lift rule stays as narrative and +//! is *not* lifted — in particular the `why` prose is never schematized. +//! +//! M0 lifts: spine, `:::why`, `:::acceptance-criterion`, `:::task` (+ nested +//! `::file-ref`). `scope-in/out`, `constraint`, and `ref` are recognized by the +//! parser (closed vocabulary) but lifted in a later milestone. + +use serde_json::{Map, Value}; + +use crate::directive::{self, Directive}; +use crate::error::{CanonicalError, Result}; +use crate::node::{AcceptanceCriterion, CanonicalNode, Task, CONTEXT_URL}; +use crate::vocab::NodeType; + +/// Lift an intent from its frontmatter spine and markdown body. +pub fn lift_intent(frontmatter: &Map, body: &str) -> Result { + let human_key = require_str(frontmatter, "id")?; + let uid = opt_str(frontmatter, "uid").unwrap_or_else(|| slug(&human_key)); + let node_id = format!("urn:atomic:intent:{uid}"); + + let directives = directive::parse(body)?; + + let mut why = None; + let mut acs = Vec::new(); + let mut tasks = Vec::new(); + let mut ac_n = 0usize; + let mut task_n = 0usize; + + for d in &directives { + match d.name.as_str() { + "why" => { + // Single authoring site: first `:::why` wins; the reason is + // unconstrained prose, lifted verbatim, never inspected. + if why.is_none() { + why = Some(d.body.clone()); + } + } + "acceptance-criterion" => { + ac_n += 1; + acs.push(lift_ac(d, &human_key, ac_n)?); + } + "task" => { + task_n += 1; + tasks.push(lift_task(d, &human_key, task_n)); + } + // Recognized but not lifted in M0. + "scope-in" | "scope-out" | "constraint" | "ref" | "file-ref" => {} + other => { + return Err(CanonicalError::Lift(format!( + "directive ':{other}' has no lift rule" + ))) + } + } + } + + Ok(CanonicalNode { + context: CONTEXT_URL.to_string(), + type_: NodeType::Intent.as_str().to_string(), + id: node_id, + human_key, + title: opt_str(frontmatter, "title").unwrap_or_default(), + status: opt_str(frontmatter, "status").unwrap_or_else(|| "backlog".to_string()), + priority: opt_str(frontmatter, "priority"), + view: opt_str(frontmatter, "view"), + motivated_by: opt_str(frontmatter, "motivatedBy"), + informed_by: str_array(frontmatter, "informedBy"), + has_acceptance_criterion: acs, + has_task: tasks, + why, + content_hash: None, + attributed_to: opt_str(frontmatter, "attributedTo"), + created_at: opt_str(frontmatter, "created_at").unwrap_or_default(), + proof: None, + }) +} + +fn lift_ac(d: &Directive, human_key: &str, n: usize) -> Result { + let local = d + .id + .clone() + .unwrap_or_else(|| format!("{}-ac-{n}", slug(human_key))); + Ok(AcceptanceCriterion { + type_: NodeType::AcceptanceCriterion.as_str().to_string(), + id: as_urn("ac", &local), + text: d.body.clone(), + ac_status: d.attr("status").unwrap_or("open").to_string(), + verified_by: d.attr("verifiedBy").map(str::to_string), + evidence: d.attr("evidence").map(str::to_string), + }) +} + +fn lift_task(d: &Directive, human_key: &str, n: usize) -> Task { + let local = d + .id + .clone() + .unwrap_or_else(|| format!("{}-{n}", slug(human_key))); + let mut touches: Vec = Vec::new(); + if let Some(f) = d.attr("touchesFile") { + touches.push(f.to_string()); + } + for child in &d.children { + if child.name == "file-ref" { + if let Some(path) = child.attr("path") { + touches.push(path.to_string()); + } + } + } + let satisfies = d + .attr("satisfies") + .or_else(|| d.attr("criteria")) + .map(|v| as_urn("ac", v)); + Task { + type_: NodeType::Task.as_str().to_string(), + id: as_urn("task", &local), + text: d.body.clone(), + task_status: d.attr("status").unwrap_or("open").to_string(), + touches_file: touches, + satisfies, + } +} + +/// Wrap a local id into `urn:atomic::` unless already a urn. +fn as_urn(kind: &str, local: &str) -> String { + if local.starts_with("urn:atomic:") { + local.to_string() + } else { + format!("urn:atomic:{kind}:{local}") + } +} + +fn slug(s: &str) -> String { + s.to_lowercase() +} + +fn require_str(fm: &Map, key: &str) -> Result { + opt_str(fm, key).ok_or_else(|| CanonicalError::Lift(format!("frontmatter missing '{key}'"))) +} + +fn opt_str(fm: &Map, key: &str) -> Option { + match fm.get(key) { + Some(Value::String(s)) if !s.is_empty() => Some(s.clone()), + Some(Value::Number(n)) => Some(n.to_string()), + _ => None, + } +} + +fn str_array(fm: &Map, key: &str) -> Vec { + match fm.get(key) { + Some(Value::Array(items)) => items + .iter() + .filter_map(|v| v.as_str().map(str::to_string)) + .collect(), + Some(Value::String(s)) if !s.is_empty() => { + s.split(',').map(|p| p.trim().to_string()).filter(|p| !p.is_empty()).collect() + } + _ => Vec::new(), + } +} + +/// Minimal frontmatter splitter for a full markdown document: +/// `---\n\n---\n`. Enough for templates and the CLI; +/// values may be quoted strings or `[a, b]` arrays. Not a full YAML parser. +pub fn parse_markdown(doc: &str) -> Result<(Map, String)> { + let doc = doc.strip_prefix('\u{feff}').unwrap_or(doc); + let rest = match doc.strip_prefix("---\n") { + Some(r) => r, + None => return Ok((Map::new(), doc.to_string())), + }; + let end = rest + .find("\n---") + .ok_or_else(|| CanonicalError::Lift("unterminated frontmatter block".into()))?; + let fm_src = &rest[..end]; + // body starts after the closing --- line + let after = &rest[end + 1..]; // at "---..." + let body = after + .strip_prefix("---") + .map(|b| b.trim_start_matches(['\n', '\r']).to_string()) + .unwrap_or_default(); + + let mut fm = Map::new(); + for line in fm_src.lines() { + let line = line.trim(); + if line.is_empty() { + continue; + } + if let Some(colon) = line.find(':') { + let key = line[..colon].trim().to_string(); + let raw = line[colon + 1..].trim(); + fm.insert(key, parse_scalar(raw)); + } + } + Ok((fm, body)) +} + +fn parse_scalar(raw: &str) -> Value { + if raw.starts_with('[') && raw.ends_with(']') { + let inner = &raw[1..raw.len() - 1]; + let arr: Vec = inner + .split(',') + .map(|s| s.trim().trim_matches(['"', '\'']).to_string()) + .filter(|s| !s.is_empty()) + .map(Value::String) + .collect(); + return Value::Array(arr); + } + let unquoted = raw.trim_matches(['"', '\'']); + Value::String(unquoted.to_string()) +} diff --git a/atomic-canonical/src/node.rs b/atomic-canonical/src/node.rs new file mode 100644 index 00000000..c9d29d00 --- /dev/null +++ b/atomic-canonical/src/node.rs @@ -0,0 +1,145 @@ +//! The canonical typed node — RtW's canonical form, serialized as JSON-LD. +//! +//! This is a *compile target*, not a hand-authored artifact (the lift produces +//! it from markdown+directives). JSON-LD because `@type` gives node types, +//! `@id` gives stable identity, reference properties are first-class edges, and +//! it is RDF the PROV/regulator toolchain already speaks. +//! +//! The `why` is an unconstrained prose slot: the gate checks that it is +//! present, never what it says ("presence enforced, content honest"). + +use serde::{Deserialize, Serialize}; + +use crate::hash::content_hash; +use crate::jcs; + +pub const CONTEXT_URL: &str = "https://atomic.dev/ns/ctx.jsonld"; + +/// A single acceptance criterion, lifted from a `:::acceptance-criterion` directive. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub struct AcceptanceCriterion { + #[serde(rename = "@type")] + pub type_: String, + #[serde(rename = "@id")] + pub id: String, + pub text: String, + #[serde(rename = "acStatus")] + pub ac_status: String, + #[serde(rename = "verifiedBy", skip_serializing_if = "Option::is_none")] + pub verified_by: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub evidence: Option, +} + +/// A decomposed task, lifted from a `:::task` directive. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub struct Task { + #[serde(rename = "@type")] + pub type_: String, + #[serde(rename = "@id")] + pub id: String, + pub text: String, + #[serde(rename = "taskStatus")] + pub task_status: String, + #[serde(rename = "touchesFile", skip_serializing_if = "Vec::is_empty")] + pub touches_file: Vec, + #[serde(skip_serializing_if = "Option::is_none")] + pub satisfies: Option, +} + +/// A Data Integrity proof (`eddsa-jcs-2022`). +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub struct Proof { + #[serde(rename = "@type")] + pub type_: String, + pub cryptosuite: String, + #[serde(rename = "verificationMethod")] + pub verification_method: String, + #[serde(rename = "proofPurpose")] + pub proof_purpose: String, + #[serde(rename = "proofValue")] + pub proof_value: String, +} + +/// The canonical Intent node. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub struct CanonicalNode { + #[serde(rename = "@context")] + pub context: String, + #[serde(rename = "@type")] + pub type_: String, + #[serde(rename = "@id")] + pub id: String, + + /// Human-facing key (e.g. "WORD-5"); a display alias over `@id`. + #[serde(rename = "humanKey")] + pub human_key: String, + pub title: String, + pub status: String, + #[serde(skip_serializing_if = "Option::is_none")] + pub priority: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub view: Option, + + #[serde(rename = "motivatedBy", skip_serializing_if = "Option::is_none")] + pub motivated_by: Option, + #[serde(rename = "informedBy", skip_serializing_if = "Vec::is_empty")] + pub informed_by: Vec, + + #[serde(rename = "hasAcceptanceCriterion", skip_serializing_if = "Vec::is_empty")] + pub has_acceptance_criterion: Vec, + #[serde(rename = "hasTask", skip_serializing_if = "Vec::is_empty")] + pub has_task: Vec, + + /// The unconstrained reason. Presence enforced by the gate; content honest. + #[serde(skip_serializing_if = "Option::is_none")] + pub why: Option, + + #[serde(rename = "contentHash", skip_serializing_if = "Option::is_none")] + pub content_hash: Option, + #[serde(rename = "attributedTo", skip_serializing_if = "Option::is_none")] + pub attributed_to: Option, + #[serde(rename = "createdAt")] + pub created_at: String, + + #[serde(skip_serializing_if = "Option::is_none")] + pub proof: Option, +} + +impl CanonicalNode { + /// The node as a JSON value (JSON-LD object). + pub fn to_value(&self) -> serde_json::Value { + serde_json::to_value(self).expect("canonical node serialization is infallible") + } + + /// The value used for signing: everything except the `proof` (a Data + /// Integrity signature covers the document minus the proof). `contentHash` + /// is included so the signature also commits to the hash. + pub fn signing_value(&self) -> serde_json::Value { + let mut value = self.to_value(); + if let Some(obj) = value.as_object_mut() { + obj.remove("proof"); + } + value + } + + /// The value used for the content hash: excludes both `proof` and + /// `contentHash` (you cannot hash the hash). + pub fn hashing_value(&self) -> serde_json::Value { + let mut value = self.signing_value(); + if let Some(obj) = value.as_object_mut() { + obj.remove("contentHash"); + } + value + } + + /// Canonical bytes for signing (JCS of `signing_value`). + pub fn signing_bytes(&self) -> Vec { + jcs::canonicalize(&self.signing_value()).into_bytes() + } + + /// Recompute the content hash from the current node state. + pub fn compute_content_hash(&self) -> String { + content_hash(&self.hashing_value()) + } +} diff --git a/atomic-canonical/src/proof.rs b/atomic-canonical/src/proof.rs new file mode 100644 index 00000000..a878f107 --- /dev/null +++ b/atomic-canonical/src/proof.rs @@ -0,0 +1,110 @@ +//! Data Integrity proofs over canonical nodes (`eddsa-jcs-2022`). +//! +//! Signing covers the JCS-canonical node minus its `proof` (the standard Data +//! Integrity shape). We reuse atomic's existing Ed25519 `Signer`/`PublicKey` +//! and sign over the same canonical bytes the content hash uses, via the one +//! `jcs` entry point — so hash and signature can never disagree. +//! +//! `proofValue` is a multibase string. We use base32-upper (`B`) via +//! `data-encoding` (already in-tree) rather than base58btc (`z`) to avoid an +//! extra dependency; it is a valid multibase encoding and the prefix is +//! swappable when a base58 dependency is admitted. + +use atomic_identity::identity::Identity; +use atomic_identity::keypair::{KeyPair, PublicKey}; +use atomic_identity::signing::{Signature, Signer}; + +use crate::did; +use crate::error::{CanonicalError, Result}; +use crate::node::{CanonicalNode, Proof}; + +pub const CRYPTOSUITE: &str = "eddsa-jcs-2022"; +pub const PROOF_TYPE: &str = "DataIntegrityProof"; +pub const PROOF_PURPOSE: &str = "assertionMethod"; +/// Multibase prefix for base32-upper, no padding. +const MULTIBASE_BASE32_UPPER: char = 'B'; + +/// Produce a fully attested node: fill `attributedTo` (from the identity's +/// `did:atomic`), compute the content hash, sign, and attach the proof. +pub fn attest(mut node: CanonicalNode, identity: &Identity, keypair: &KeyPair) -> CanonicalNode { + let did = did::did_for_public_key(&identity.public_key); + if node.attributed_to.is_none() { + node.attributed_to = Some(did.clone()); + } + + // Hash first (over node without proof/contentHash), then sign (over node + // with contentHash, without proof). + node.content_hash = Some(node.compute_content_hash()); + + let signature = Signer::new(keypair).sign(&node.signing_bytes()); + let proof_value = encode_proof_value(&signature); + + node.proof = Some(Proof { + type_: PROOF_TYPE.to_string(), + cryptosuite: CRYPTOSUITE.to_string(), + verification_method: did::verification_method(&did), + proof_purpose: PROOF_PURPOSE.to_string(), + proof_value, + }); + node +} + +/// Verify an attested node against a public key: the content hash must +/// recompute, and the signature must verify over the canonical signing bytes. +pub fn verify(node: &CanonicalNode, public_key: &PublicKey) -> Result<()> { + // 1. Content hash integrity. + let expected = node + .content_hash + .as_ref() + .ok_or_else(|| CanonicalError::Proof("node carries no contentHash".into()))?; + let actual = node.compute_content_hash(); + if *expected != actual { + return Err(CanonicalError::HashMismatch { + expected: expected.clone(), + actual, + }); + } + + // 2. Signature over the canonical signing bytes. + let proof = node + .proof + .as_ref() + .ok_or_else(|| CanonicalError::Proof("node carries no proof".into()))?; + let signature = decode_proof_value(&proof.proof_value)?; + signature + .verify(&node.signing_bytes(), public_key) + .map_err(|e| CanonicalError::Verification(e.to_string()))?; + + // 3. The proof's verificationMethod DID must belong to this key. + let did = did::did_from_verification_method(&proof.verification_method); + if !did::did_matches_public_key(did, public_key) { + return Err(CanonicalError::Verification( + "verificationMethod DID does not match the public key".into(), + )); + } + Ok(()) +} + +fn encode_proof_value(signature: &Signature) -> String { + let mut s = String::new(); + s.push(MULTIBASE_BASE32_UPPER); + s.push_str(&data_encoding::BASE32_NOPAD.encode(signature.as_bytes())); + s +} + +fn decode_proof_value(value: &str) -> Result { + let mut chars = value.chars(); + match chars.next() { + Some(MULTIBASE_BASE32_UPPER) => {} + _ => { + return Err(CanonicalError::Proof(format!( + "unsupported multibase prefix in proofValue: {value:.4}…" + ))) + } + } + let body = &value[MULTIBASE_BASE32_UPPER.len_utf8()..]; + let bytes = data_encoding::BASE32_NOPAD + .decode(body.as_bytes()) + .map_err(|e| CanonicalError::Proof(format!("bad base32 proofValue: {e}")))?; + Signature::from_slice(&bytes).map_err(|e| CanonicalError::Proof(e.to_string())) +} diff --git a/atomic-canonical/src/render.rs b/atomic-canonical/src/render.rs new file mode 100644 index 00000000..a51a8018 --- /dev/null +++ b/atomic-canonical/src/render.rs @@ -0,0 +1,98 @@ +//! The render projection — a canonical node → a human-readable view. +//! +//! A read is a pure function of the node. Crucially, projected fields like the +//! status line are **regenerated from the spine**, never read from a body the +//! author wrote. This is the single-authoring-site principle made real: there +//! is no second place status can live, so it can never contradict the spine. +//! +//! M0 implements the CLI text target. The editor-panel and web-HTML targets and +//! reference-at-render resolution arrive in a later milestone; the `Target` +//! enum leaves room for them. + +use crate::node::CanonicalNode; + +/// Render output target. Only `Cli` is implemented in M0. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Target { + Cli, +} + +/// Project a canonical node to a rendered string for the given target. +pub fn render(node: &CanonicalNode, target: Target) -> String { + match target { + Target::Cli => render_cli(node), + } +} + +fn render_cli(node: &CanonicalNode) -> String { + let mut s = String::new(); + + // Header: human key + title. + s.push_str(&format!("{} {}\n", node.human_key, node.title)); + s.push_str(&"─".repeat(48)); + s.push('\n'); + + // Spine fields — status is REGENERATED here from the spine, not authored. + s.push_str(&format!("Status: {}\n", node.status)); + if let Some(p) = &node.priority { + s.push_str(&format!("Priority: {p}\n")); + } + if let Some(v) = &node.view { + s.push_str(&format!("View: {v}\n")); + } + if let Some(m) = &node.motivated_by { + s.push_str(&format!("Motivated: {m}\n")); + } + if !node.informed_by.is_empty() { + s.push_str(&format!("InformedBy: {}\n", node.informed_by.join(", "))); + } + + // Why (unconstrained prose). + if let Some(why) = &node.why { + s.push_str("\nWhy\n"); + s.push_str(why); + s.push('\n'); + } + + // Acceptance criteria. + if !node.has_acceptance_criterion.is_empty() { + s.push_str("\nAcceptance Criteria\n"); + for ac in &node.has_acceptance_criterion { + let mark = if ac.ac_status == "met" { "x" } else { " " }; + s.push_str(&format!(" [{mark}] {}\n", ac.text)); + if ac.ac_status == "met" { + if let (Some(by), Some(ev)) = (&ac.verified_by, &ac.evidence) { + s.push_str(&format!(" verified by {by} · {ev}\n")); + } + } + } + } + + // Tasks. + if !node.has_task.is_empty() { + s.push_str("\nTasks\n"); + for t in &node.has_task { + let mark = if t.task_status == "done" { "x" } else { " " }; + s.push_str(&format!(" [{mark}] {}\n", t.text)); + if !t.touches_file.is_empty() { + s.push_str(&format!(" touches: {}\n", t.touches_file.join(", "))); + } + } + } + + // Provenance footer. + s.push('\n'); + s.push_str(&format!("id: {}\n", node.id)); + if let Some(a) = &node.attributed_to { + s.push_str(&format!("author: {a}\n")); + } + if let Some(h) = &node.content_hash { + s.push_str(&format!("hash: {h}\n")); + } + s.push_str(&format!( + "signed: {}\n", + if node.proof.is_some() { "yes" } else { "no" } + )); + + s +} diff --git a/atomic-canonical/src/vocab.rs b/atomic-canonical/src/vocab.rs new file mode 100644 index 00000000..61c35930 --- /dev/null +++ b/atomic-canonical/src/vocab.rs @@ -0,0 +1,80 @@ +//! The closed vocabulary registry — the single source of truth. +//! +//! Per "Recording the Why": node types, edge types, status value sets, +//! directive names, and memory kinds come from a fixed registry. An +//! unrecognized member is a gate error, not a type the system quietly +//! absorbs. Every other layer (the lift, the directive parser, the gate +//! shapes, the templates) derives its accepted names from here so they +//! cannot diverge. +//! +//! This is the M0 stub of the registry — enough to prove the Intent round +//! trip. It grows (Memory kinds, PROV edges, full directive set) in later +//! milestones, but the closure property holds from day one. + +/// Canonical node types (`@type` values). +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum NodeType { + Intent, + AcceptanceCriterion, + Task, +} + +impl NodeType { + pub fn as_str(&self) -> &'static str { + match self { + NodeType::Intent => "Intent", + NodeType::AcceptanceCriterion => "AcceptanceCriterion", + NodeType::Task => "Task", + } + } +} + +/// Intent status value set (mirrors the doc's `IntentShape` `sh:in`). +pub const INTENT_STATUS: &[&str] = &["backlog", "todo", "in_progress", "done"]; + +/// Acceptance-criterion status value set. +pub const AC_STATUS: &[&str] = &["open", "met"]; + +/// Directive names recognized by the parser + lift (closed set). +/// Container directives wrap prose; leaf directives carry only edges. +pub const DIRECTIVE_NAMES: &[&str] = &[ + "why", // container: the unconstrained reason (presence enforced, content honest) + "acceptance-criterion", // container + "task", // container + "scope-in", // container + "scope-out", // container + "constraint", // container + "ref", // leaf: a typed dependency edge + "file-ref", // leaf: a file the task touches +]; + +/// Edge (property) names that carry typed references between nodes. +pub const EDGE_NAMES: &[&str] = &[ + "motivatedBy", + "informedBy", + "supersedes", + "previousRevision", + "about", + "satisfies", + "touchesFile", + "depends", + "blockedBy", + "verifiedBy", + "evidence", + "attributedTo", +]; + +/// Is this a directive name the system recognizes? Unknown ⇒ gate error. +pub fn is_known_directive(name: &str) -> bool { + DIRECTIVE_NAMES.contains(&name) +} + +/// Is this a valid intent status value? +pub fn is_known_intent_status(value: &str) -> bool { + INTENT_STATUS.contains(&value) +} + +/// Is this a valid acceptance-criterion status value? +pub fn is_known_ac_status(value: &str) -> bool { + AC_STATUS.contains(&value) +} diff --git a/atomic-canonical/tests/roundtrip.rs b/atomic-canonical/tests/roundtrip.rs new file mode 100644 index 00000000..cd9e3468 --- /dev/null +++ b/atomic-canonical/tests/roundtrip.rs @@ -0,0 +1,161 @@ +//! M0 end-to-end proof: author → lift → JCS/BLAKE3 hash → Ed25519 proof → +//! gate → render, entirely in-crate (no vault wiring). + +use atomic_canonical::lift::{lift_intent, parse_markdown}; +use atomic_canonical::{lift_and_attest, render, validate_intent, verify, Target}; +use atomic_identity::identity::Identity; +use atomic_identity::keypair::KeyPair; +use serde_json::{json, Map, Value}; + +fn dev_identity() -> (Identity, KeyPair) { + // M0 non-production dev identity (plaintext keys — see crate docs). + let kp = KeyPair::generate(); + let id = Identity::new("lee", &kp); + (id, kp) +} + +fn frontmatter() -> Map { + json!({ + "id": "WORD-5", + "title": "Add name prompt modal", + "status": "todo", + "priority": "medium", + "view": "proud-moon-a08a" + }) + .as_object() + .unwrap() + .clone() +} + +const BODY: &str = "\ +:::why{} +We're choosing a local-only modal over a persisted profile. The name doesn't +need to survive a reload yet. +::: + +:::acceptance-criterion{#WORD-5-ac-1 status=met verifiedBy=did:atomic:lee evidence=urn:atomic:change:01J8ZE7G2W} +On first load, the app presents a modal asking for the player's name. +::: + +:::task{#WORD-5-1 status=done satisfies=WORD-5-ac-1} +Add name capture state, submit handling, modal markup, and top-of-page display. +::file-ref{path=src/App.tsx} +:::"; + +#[test] +fn full_round_trip_lifts_attests_gates_verifies_renders() { + let (id, kp) = dev_identity(); + let node = lift_and_attest(&frontmatter(), BODY, &id, &kp).unwrap(); + + // Lifted structure. + assert_eq!(node.type_, "Intent"); + assert_eq!(node.id, "urn:atomic:intent:word-5"); + assert_eq!(node.human_key, "WORD-5"); + assert_eq!(node.has_acceptance_criterion.len(), 1); + assert_eq!(node.has_task.len(), 1); + assert_eq!(node.has_acceptance_criterion[0].id, "urn:atomic:ac:WORD-5-ac-1"); + assert_eq!(node.has_task[0].touches_file, vec!["src/App.tsx".to_string()]); + assert!(node.why.as_deref().unwrap().contains("local-only modal")); + + // Attested. + assert!(node.content_hash.as_deref().unwrap().starts_with("blake3:")); + assert!(node.proof.is_some()); + assert_eq!(node.proof.as_ref().unwrap().cryptosuite, "eddsa-jcs-2022"); + + // Gate passes (met AC carries verifiedBy + evidence). + let report = validate_intent(&node); + assert!(report.conforms, "expected conforms, got:\n{report}"); + + // Signature + hash verify. + verify(&node, &kp.public).expect("verification should succeed"); + + // Render regenerates the status line from the spine. + let text = render(&node, Target::Cli); + assert!(text.contains("Status: todo"), "render:\n{text}"); + assert!(text.contains("[x] On first load")); +} + +#[test] +fn gate_rejects_met_criterion_without_evidence() { + let (id, kp) = dev_identity(); + let body = "\ +:::why{} +reason exists +::: + +:::acceptance-criterion{#ac-1 status=met} +Checked but unproven. +:::"; + let node = lift_and_attest(&frontmatter(), body, &id, &kp).unwrap(); + let report = validate_intent(&node); + assert!(!report.conforms); + assert!(report + .results + .iter() + .any(|v| v.shape == "AcceptanceCriterionShape" + && v.message.contains("verifiedBy and evidence"))); +} + +#[test] +fn gate_requires_a_reason_to_be_present() { + let (id, kp) = dev_identity(); + // No :::why directive. + let body = ":::acceptance-criterion{#ac-1 status=open}\nsomething\n:::"; + let node = lift_and_attest(&frontmatter(), body, &id, &kp).unwrap(); + let report = validate_intent(&node); + assert!(!report.conforms); + assert!(report.results.iter().any(|v| v.path.as_deref() == Some("why"))); +} + +#[test] +fn gate_rejects_unknown_status() { + let (id, kp) = dev_identity(); + let mut fm = frontmatter(); + fm.insert("status".into(), Value::String("shipped".into())); + let node = lift_and_attest(&fm, ":::why{}\nr\n:::", &id, &kp).unwrap(); + let report = validate_intent(&node); + assert!(!report.conforms); + assert!(report.results.iter().any(|v| v.path.as_deref() == Some("status"))); +} + +#[test] +fn content_hash_is_deterministic() { + let a = lift_intent(&frontmatter(), BODY).unwrap(); + let b = lift_intent(&frontmatter(), BODY).unwrap(); + assert_eq!(a.compute_content_hash(), b.compute_content_hash()); +} + +#[test] +fn tampering_a_signed_field_breaks_verification() { + let (id, kp) = dev_identity(); + let mut node = lift_and_attest(&frontmatter(), BODY, &id, &kp).unwrap(); + + // Flip status after signing — the stored contentHash no longer matches. + node.status = "done".to_string(); + let err = verify(&node, &kp.public).unwrap_err(); + assert!( + matches!(err, atomic_canonical::CanonicalError::HashMismatch { .. }), + "expected HashMismatch, got {err:?}" + ); +} + +#[test] +fn wrong_key_fails_verification() { + let (id, kp) = dev_identity(); + let node = lift_and_attest(&frontmatter(), BODY, &id, &kp).unwrap(); + let other = KeyPair::generate(); + assert!(verify(&node, &other.public).is_err()); +} + +#[test] +fn parse_markdown_then_lift() { + let doc = format!( + "---\nid: WORD-9\ntitle: \"Doc parse\"\nstatus: backlog\n---\n{BODY}" + ); + let (fm, body) = parse_markdown(&doc).unwrap(); + assert_eq!(fm.get("id").unwrap().as_str(), Some("WORD-9")); + let node = lift_intent(&fm, &body).unwrap(); + assert_eq!(node.human_key, "WORD-9"); + assert_eq!(node.id, "urn:atomic:intent:word-9"); + assert_eq!(node.has_acceptance_criterion.len(), 1); +} diff --git a/docs/recording-the-why-plan.md b/docs/recording-the-why-plan.md new file mode 100644 index 00000000..a45eb0cd --- /dev/null +++ b/docs/recording-the-why-plan.md @@ -0,0 +1,225 @@ +I'm on the correct branch and the workspace layout matches the findings. I have everything I need to produce the plan. + +# Recording the Why — Implementation Plan + +Branch: `feat/recording-the-why` (atomic core + CLI). Grounded in the design doc `docs/recording-the-why.md` and the six research findings. + +--- + +## 1. Architecture summary + +RtW is **~65% a re-typing + lifting exercise over substrate that already ships, and ~35% net-new cryptographic-canonical + semantic-web machinery.** + +**Reused / extended (do not rebuild):** +- **Round-trip engine.** The path-keyed redb `VAULT_ENTRIES` store plus the `vault_materialize` (redb→disk) / `vault_scan_working_copy` + `vault_record_working_copy` (disk→redb) cycle in `atomic-repository/src/repository/vault.rs` *is* RtW's "markdown in, canonical stored, render out, edits reconciled back." The lift slots into the scan/record path; the render into `render_entry_to_markdown`. +- **Hash primitive.** `Hash = Merkle` over BLAKE3 (`atomic-core/src/types/hash.rs:51,113`) is exactly RtW's `blake3:` — only the *input* changes (JCS-canonical node bytes instead of raw body). +- **Closed vocabulary seed.** `atomic-core/src/pristine/ontology.rs` already holds PROV/SKOS/DC prefixes, PROV-O predicate strings, vault entity types, and `is_known_predicate`/`all_predicates`. RtW hardens this from advisory into the single source of truth. +- **Identity/signing.** `atomic-identity` (`keypair.rs`, `signing.rs`, `identity.rs`) gives Ed25519 + `IdentityId = blake3(pubkey)` — the exact primitive for `eddsa-jcs-2022`. We add only a canonicalization + multibase + `did:atomic` adapter layer on top. +- **Provenance capture.** `atomic-agent/src/provenance/*` + `atomic-core/src/change/provenance_graph/*` already capture a content-addressed, chained, per-change causal DAG with turn boundaries across 14 agent adapters. RtW re-projects this into W3C PROV JSON-LD rather than inventing capture. +- **Projection tier.** The `(KgNode, KgEdge)` property graph + `kg_neighbors` BFS + `query_plan.rs` executor are the ready-made flywheel-query surface. + +**Net-new (nothing exists — grep-confirmed zero hits):** JSON-LD typed-node type + `@context`; JCS (RFC 8785) canonicalizer; content-hash-over-canonical-node (today's hash is BODY-only, `vault.rs:99` — the exact bug the doc warns of); Data Integrity `proof` object + `did:atomic` method/resolver; container/leaf/inline **directive parser**; the **lift** (surface→typed node); a **SHACL gate** (closed-world) + validation-report-as-graph; typed **collection sub-nodes** (AC/task/scope/constraint/dep); append-only **Memory** revisions with stable id ≠ path; the render **projection function**; and the new CLI verbs (`intent new/validate`, `memory new`, `provenance trace`). + +**The single biggest structural change:** `content_hash` moves from `blake3(body-bytes)` to `blake3(JCS(canonical JSON-LD node))`. This is a format break requiring migration of every existing entry, and it is the load-bearing decision the rest of the plan hangs off. + +--- + +## 2. The thin vertical slice (M0) — one node type, end to end + +**Goal:** `atomic intent new WORD-5 --template feature` → author frontmatter + two container directives → lift → canonical JSON-LD Intent + JCS/BLAKE3 hash + Ed25519 Data Integrity proof → minimal `IntentShape` gate → `atomic intent show WORD-5` renders text back. No Memory, no PROV, no web render, no full directive grammar — just enough to prove the three-layer round trip on Intent. + +**New crate: `atomic-canonical`** (new workspace member; keeps JSON-LD/JCS/proof logic out of `atomic-core`'s hot path and out of `atomic-repository`). Depends on `atomic-identity`, `blake3`, `serde_json`. + +Files to **add**: +- `atomic-canonical/src/vocab.rs` — the closed registry *stub* for the slice: `NodeType::{Intent, AcceptanceCriterion, Task}`, `Status`, directive names `acceptance-criterion`/`task`. (Grows into the full registry in Phase 3a.) +- `atomic-canonical/src/node.rs` — `CanonicalNode` typed struct + serde to JSON-LD (`@context`, `@type`, `@id: urn:atomic:intent:`, spine fields, `hasAcceptanceCriterion[]`, `why`, `contentHash`, `attributedTo`, `createdAt`, `proof`). +- `atomic-canonical/src/jcs.rs` — RFC 8785 canonicalizer (lexicographic key sort, canonical number/string encoding). Prefer wrapping an existing `serde_jcs` crate; if none acceptable, implement over `serde_json::Value`. +- `atomic-canonical/src/hash.rs` — `content_hash(node) = "blake3:" + hex(blake3(jcs(node_without_proof_or_hash)))`. Reuses `atomic-core` `Hash::of` semantics but over JCS bytes. +- `atomic-canonical/src/proof.rs` — `DataIntegrityProof` (`type=DataIntegrityProof`, `cryptosuite=eddsa-jcs-2022`, `verificationMethod=did:atomic:...#key-1`, `proofPurpose=assertionMethod`, `proofValue=z...`); sign/verify wrapping `atomic-identity::Signer`/`PublicKey::verify` over JCS bytes; multibase `z` (base58btc) encoding of the 64-byte sig. +- `atomic-canonical/src/did.rs` — minimal `did:atomic:` construction + resolve-to-pubkey (local `IdentityStore` lookup for the slice). +- `atomic-canonical/src/lift.rs` — slice lift: frontmatter map → spine; `:::acceptance-criterion{...}` and `:::task{...}` containers → sub-nodes. Reuses/replaces the flat parser. +- `atomic-canonical/src/gate.rs` — hand-coded `IntentShape` for the slice: `status ∈ {backlog,todo,in_progress,done}` (min1/max1); `attributedTo` present + resolves to an agent; `proof` present; `hasAcceptanceCriterion` items satisfy AC rule (`acStatus=met ⇒ verifiedBy ∧ evidence`). Returns a structured `ValidationReport` (Rust struct, JSON-LD-serializable). **Hand-coded now; a real SHACL engine arrives in Phase 3f.** +- `atomic-canonical/src/render.rs` — projection `render(node, target=Cli) -> String`; regenerates the body status header from the spine (kills the dual-authoring bug). + +Files to **modify**: +- `atomic-repository/src/repository/vault_intent.rs` — `vault_intent_create` calls the directive-stub template (Phase 3h wiring, minimal here); on write, run lift → gate → compute canonical `content_hash` → sign → store. Delete the `**Status:** backlog` body-header authoring site (line ~3 of template). +- `atomic-repository/vault/templates/intent.md` — replace positional headings with `:::acceptance-criterion` / `:::task` directive stubs; remove the body status line. +- `atomic-core/src/pristine/vault.rs` — add optional `proof: Option` and `canonical_json: Option` to `VaultEntry` (postcard-compatible additive fields); keep `content_hash` but redefine what it hashes. Add a `format_version` discriminator for migration. +- `atomic-repository/src/repository/vault.rs` — `render_entry_to_markdown` delegates to `atomic-canonical::render` for intents; `vault_store` computes canonical hash + attaches proof. +- `atomic-cli/src/commands/vault/intent.rs` — add `Show` rendering via `atomic-canonical::render`; add `Validate` verb printing the `ValidationReport`. +- `Cargo.toml` (workspace) + `atomic-repository/Cargo.toml`, `atomic-cli/Cargo.toml` — add `atomic-canonical` dependency. + +**Slice exit criteria:** create → lift → hash → sign → gate-pass → `show` renders with a spine-derived status header; tampering the body does not change `content_hash` in a way that hides a spine change; a `status=done` intent with an unmet AC (met-without-evidence) is *rejected* by the gate. + +--- + +## 3. Phased plan for the rest + +### Phase 3a — Closed-vocabulary registry as the single source (P0, blocks everything) +The doc's primary integration risk: five consumers (lift, directive parser, SHACL shapes, templates, CLI scaffolds) must not diverge. Make `atomic-canonical/src/vocab.rs` the *one* registry and derive the rest. +- **Add:** `atomic-canonical/src/vocab.rs` — enums/const tables for node types, edge types (`motivatedBy, informedBy, supersedes, previousRevision, about, hasAcceptanceCriterion, hasTask, satisfies, touchesFile, criteria, depends, blockedBy, verifiedBy, evidence, attributedTo` + PROV `used/generated/associatedWith/actedOnBehalfOf/turnParent`), status value sets, memory kinds, directive names. `unknown ⇒ error`. +- **Add:** `atomic-canonical/ns/ctx.jsonld` (checked-in `@context` for `https://atomic.dev/ns/ctx.jsonld`) generated from vocab; `atomic-canonical/shapes/*.ttl` generated from vocab (or generated at build time via `build.rs`). +- **Modify:** `atomic-core/src/pristine/ontology.rs` — re-export / align its predicate registry with `atomic-canonical::vocab` so KG extraction and the gate share one vocabulary (resolves the "advisory, largely unused" gap). Ontology becomes a thin view over the canonical registry. +- **Deliverable:** a single test that asserts every SHACL shape target, every directive name, every template stub, and every lift rule references a registry member. + +### Phase 3b — Full directive grammar + lift (P0) +- **Add:** `atomic-canonical/src/directive.rs` — parser for container `:::name{attrs}...:::`, leaf `::name{attrs}`, inline `:name[label]{attrs}`; attribute grammar (`#id`, `key=value`, edge `to=`/`edge=`); nesting (`::file-ref` inside `:::task`). +- **Expand:** `atomic-canonical/src/lift.rs` — full typed extractor: frontmatter→spine, directive-name→`@type`, attrs→typed props/edges, fence prose→text slot, unmatched prose→unlifted body. Enforce the **single-authoring-site rule** (lift one site, ignore duplicates). +- **Replace:** the hand-rolled `yaml_frontmatter_to_json`/`parse_markdown_frontmatter` in `atomic-repository/src/repository/vault.rs:800,847` with a proper YAML parser feeding the lift (the flat parser can't hold nested AC/task arrays or reference lists — findings gap #4/#5). Keep the disk-first re-parse hook in `vault_intent.rs:432-443,573-584`. + +### Phase 3c — Collection sub-nodes (P0 for Intent completeness) +- **Modify:** `atomic-canonical/src/node.rs` — nested `AcceptanceCriterion`, `Task`, `ScopeIn/ScopeOut`, `Constraint`, `Ref` sub-node types with `@id` (`urn:atomic:ac|task:...`). +- **Stable sub-node identity on edit (the critical risk):** the lift must reconcile sub-node `@id`s per AC/task on every write rather than treat the body as an opaque blob (findings intent-model RISK). Add `atomic-canonical/src/reconcile.rs` — match existing sub-node ids by `#id` attribute, allocate new ones only for new directives, so per-AC/task attestations survive edits. +- **Modify:** `atomic-core/src/pristine/vault.rs` `IntentSummary` — carry/reference sub-node collections (or a count + hash) so `intent list` can filter by AC/task status. +- **Add:** `TaskShape` (doc leaves it unspecified — see open questions) incl. `depends` cycle detection over `atomic-canonical`'s edge model. + +### Phase 3d — Memory node type (P1; highest-risk data-model change) +- **Add:** `atomic-repository/src/repository/vault_memory.rs` (mirror `vault_goal.rs`/`vault_intent.rs` structure — none exists today; memory is generic-entry-only). +- **Stable id ≠ path (P0 within this phase):** introduce `urn:atomic:memory:` as identity; keep the path as a materialized view only. This breaks the current path-as-key overwrite model and `entry_subject` (`vault_triples.rs:539-546`) — a genuine migration, not additive. +- **Append-only + supersede:** new revision writes a new entry referencing `previousRevision`/`supersedes`; old stays queryable; status `active|superseded|retracted`. Requires manifest keying by id (findings memory gap #2/#6). +- **Typed fields:** `memoryKind ∈ {constraint,preference,lesson,context}` (gate-enforced; replaces free-text `--type`); `about[]` edges to modules/domains. +- **Directionality rule:** `informedBy` lives on the **intent** side; memory never lists consumers. Do **not** copy the symmetric `blocked_by/blocks` pattern from `vault_triples.rs:648-663` (the exact anti-pattern the doc forbids). +- **Modify:** `MemorySummary` (`vault.rs:143-149`) to carry kind/status/id/about. + +### Phase 3e — W3C PROV provenance + `provenance trace` (P1) +- **Add:** `atomic-canonical/src/prov.rs` — project the existing accumulator DAG (`atomic-agent/src/provenance/*`) and `atomic-core/src/change/provenance_graph/*` into a named JSON-LD `@graph` keyed `urn:atomic:provgraph:` with `prov:Activity/SoftwareAgent/Person`, `used/generated/actedOnBehalfOf/turnParent`. +- **Modify:** `atomic-agent/src/provenance/accumulator/` — **capture `used` edges** (which intent/memory URNs the turn consumed). This is the flywheel's load-bearing edge and it is entirely missing today (findings prov gap #4). Turn boundaries (`event.rs:116`, `HookType::TurnStart/TurnEnd`) already fire where an Activity starts/ends. +- **Modify:** `atomic-agent/src/turn/orchestrator/provenance.rs:395` + `atomic-repository/src/repository/changes.rs:636,704-792` — the content-address/register/dep-link plumbing is reused; swap postcard for JCS-canonicalized JSON-LD as the addressed form, sign the graph. +- **Add:** `atomic-cli/src/commands/provenance/` (new top-level) — `provenance trace ` walking `load_provenance_graph` + dep lookup: change → activity → intent → memories → agent + person. + +### Phase 3f — SHACL gate hardening + agent validation loop (P1) +- **Replace** the hand-coded `gate.rs` with a real closed-world SHACL evaluator in `atomic-canonical/src/shacl.rs` consuming the generated `shapes/*.ttl`: `sh:in`, `sh:minCount/maxCount`, `sh:class`, `sh:node`, `sh:equals`, and a **rationed** `sh:sparql` (AC `met ⇒ verifiedBy ∧ evidence`; task `depends` cycle). Prefer declarative rules; sparql only where conditional (doc NON-GOAL: don't grow a query engine). +- **Validation-report-as-graph:** define its shape/vocab in `vocab.rs` (doc leaves it unspecified) — failing node, source shape, offending value, message. +- **Gate semantics:** `status:done` is *granted* by the gate when shapes pass, never auto-fixing a load-bearing/attested fact; may only regenerate a projected field (doc lines 452-454, 541). Wire the gate to run automatically at the `→ done` transition in `vault_intent.rs`, and `intent validate` for manual authoring. + +### Phase 3g — Render projection: CLI / editor / web (P2) +- **Expand** `atomic-canonical/src/render.rs` into one projection function with three targets (CLI text, editor-panel JSON, web HTML), **zero files on disk**, lazy per-read (doc line 531). +- **Reference-not-transclusion:** resolve `:::ref`/`informedBy`/`about` edges *inline at render time*; store only the edge (doc lines 61, 189-193). Add resolve-at-render machinery (absent today — findings semantic gap #9). + +### Phase 3h — CLI verbs + templates (P1, incremental) +- **Modify:** `atomic-cli/src/commands/vault/intent.rs` — `new WORD-5 --template feature|bugfix` (add `--template`, absent today); a **template registry** keyed by node-type/use-case replaces the single `INTENT_TEMPLATE` (`vault_intent.rs:16`). Templates scaffold spine + directive blocks only, never body prose, and can only emit registry types. +- **Modify:** `atomic-cli/src/commands/vault/memory.rs` — `memory new --kind --about` (none exist today; `--type` vocab is wrong). +- **Decision (see §6):** whether these live at top-level `atomic intent/memory/provenance` (doc) or stay under `atomic vault` (codebase). Prior art for aliasing exists (`vault query` re-exports top-level `Query`, `mod.rs:68`). + +### Phase 3i — Flywheel edges/queries (P2) +- **Modify:** `atomic-repository/src/repository/vault_triples.rs` — extend the proven Intent frontmatter→edge extractor (`:627-691`) to emit `informedBy` (intent→memory), `about` (memory→module), `motivatedBy` (intent→decision), and the PROV edges — as a *pure projection* recomputed from canonical node ids (see §4). +- **Reuse:** `vault_kg_neighbors` + `query_plan.rs` for flywheel queries ("what must I know before changing this module" = `about` traversal; "AC met but no evidence" = graph query). + +--- + +## 4. Reconciliation with existing atomic architecture + +**Do the doc and `vault_triples.rs` agree? Partially — with one required reframing.** + +- **Agreement:** The doc says "patch graph stays canonical, the triple view is a projection we compute and discard, no triplestore" (lines 533). Atomic already treats the KG as a *derived* index built by `vault_auto_index`/`kg_enrich`, not a source of truth, and does **not** run SPARQL storage. The `(KgNode,KgEdge)` redb tables are analogized to "regional redb materializations vs the S3 log" — exactly the doc's framing. So the *spirit* aligns. +- **Conflict to fix:** Today the KG is a **separately materialized, manually (re)enriched, persisted** store that can **drift** from vault entries and is keyed by **path-derived** ids (`intent:PIMO-1`, `entry_subject` on filename). The doc wants a **deterministic pure function** of the canonical records, keyed by **stable `@id` URNs** (`urn:atomic:intent:`). **Reframe** (Phase 3i): rebuild KG extraction as a pure recompute over canonical node ids, not paths, so it honors "the patch graph stays canonical" and drift becomes impossible-by-construction. Reconcile `humanKey` (WORD-5) as a display alias over the URN `@id`. + +**How the SHACL/JSON-LD layer coexists with patch-theory storage:** +- **Canonical source of truth stays the patch/change graph + redb `VAULT_ENTRIES`.** JSON-LD is a **compile target** (like a TS AST), never authored or stored as the primary artifact. RtW stores the postcard `VaultEntry` as today, plus (decision §6) either the canonical JSON-LD bytes alongside it or recompute-on-demand. +- **The gate sits between lift and `put_vault_entry`** (a chokepoint that accepts any bytes today — findings storage gap #3). No node enters the store unless it passes SHACL; `status:done` is granted there. +- **Signing anchors to identity, not to changes' own provenance section.** Vault entries gain a `proof` field (absent today); the per-change PROV graph is signed separately and hangs off the existing content-addressed provenance sidecar (`node_type::PROVENANCE=3`). +- **No new storage tier.** SHACL shapes are just Turtle files; JSON-LD is transient; the projection is discarded. This directly satisfies the doc's NON-GOALS (no triplestore, no pre-rendered HTML files, no OWL). + +--- + +## 5. Sequenced milestones + +| Milestone | Content | Priority | Depends on | +|---|---|---|---| +| **M0** | Thin vertical slice (§2): Intent create→lift→JCS/BLAKE3→proof→minimal IntentShape→CLI render. `atomic-canonical` crate born. | **P0** | — | +| **M1** | Registry as single source (3a) + full directive grammar & lift (3b). Migration of existing intents to canonical hashing. | **P0** | M0 | +| **M2** | Collection sub-nodes + stable-id reconciliation + TaskShape (3c). Intent is now feature-complete per doc. | **P0** | M1 | +| **M3** | SHACL gate hardening + validation-report-as-graph + auto-gate at `→done` (3f). | **P1** | M1, M2 | +| **M4** | Memory node type: stable id≠path, append-only/supersede, kinds, `about`, directionality (3d). Data-model migration. | **P1** | M1, M3 | +| **M5** | CLI verbs + template registry (`intent new --template`, `memory new --kind --about`) (3h). | **P1** | M2, M4 | +| **M6** | W3C PROV projection + `used`-edge capture + `provenance trace` (3e). | **P1** | M4 (memory URNs), M0 (proof/JCS) | +| **M7** | Render projection three targets + reference-at-render resolution (3g). | **P2** | M2, M4 | +| **M8** | Flywheel edges as pure projection + KG reframe to canonical ids + queries (3i). | **P2** | M4, M6 | + +**P0 (must land first, load-bearing):** M0, M1, M2 — the Intent round trip and the canonical hash-format break. **P1:** M3–M6 — gate, memory, CLI, provenance. **P2:** M7–M8 — render targets and full flywheel query. + +**Critical-path note:** the `content_hash` semantics change (M0/M1) gates a migration of every existing vault entry; do it early and behind a `format_version` so old entries verify under old rules until re-signed. + +--- + +## 6. Open questions needing a human decision + +1. **DID method: `did:atomic` vs `did:key`.** `IdentityId = blake3(pubkey)` (base32, no multicodec context) will *not* match standard `did:key` ids (which need multibase base58btc + multicodec `0xed01`). Adopt a custom `did:atomic:` method (simpler, in-tree) or conform to `did:key` (interoperable with regulator tooling)? The doc uses `did:atomic:*` but PROV/Data-Integrity ecosystems assume `did:key`-style multibase. **This choice ripples through `proof.rs`, `did.rs`, and every `attributedTo`.** + +2. **Store canonical JSON-LD bytes, or recompute on demand?** (findings storage gap #9.) Storing alongside the postcard `VaultEntry` gives stable proof re-verification but grows storage and duplicates state; recomputing risks JCS/serialization drift silently breaking a stored proof. Recommend storing canonical bytes for signed nodes; needs sign-off. + +3. **CLI surface: top-level `atomic intent/memory/provenance` vs nested `atomic vault *`.** The doc uses top-level; the codebase nests under `atomic vault` (with aliasing prior art at `mod.rs:68`). Decision affects `main.rs` command tree and every example in the doc. + +4. **Undefined node/shape types the doc references but never specifies:** `TaskShape` (only referenced, line 380), and the `Change` / `Decision` node types (used as URN/edge targets `urn:atomic:decision|change`, `motivatedBy→decision`, `generated/evidence→change`) have no record type, shape, or authoring surface. Are these authored records or system-minted (Change ≈ existing change hash, Decision ≈ ?)? Also unspecified: `ScopeIn/ScopeOut/Constraint/Ref` have directives but **no `@type` names or SHACL shapes** in any example. + +5. **Secret-key-at-rest security.** `IdentityStore` writes signing keys **unencrypted** (`store.rs:459-463`; argon2id+chacha20poly1305 is a TODO). RtW makes these keys load-bearing for every attested node. Fix before shipping signing, or accept plaintext keys for the initial milestones? + +6. **The `status:done` granting tension.** The gate "grants" `status:done` when shapes pass (line 342), yet "never auto-fixes a load-bearing fact" (line 454). Concrete rule needed for the boundary between *granting a transition* (writing status) and *mutating an attested field*. Proposal: gate writes status only on the spine, only forward through the state machine, only when all shapes pass, and never rewrites any other attested field — needs confirmation. + +7. **`@context` + `atom:` namespace authorship.** `https://atomic.dev/ns/ctx.jsonld` and `https://atomic.dev/ns#` must be authored and hosted (or embedded/checked-in). Who owns publishing the context doc, and is it served or vendored? + +8. **Memory identity migration scope.** Moving memory from path-as-identity to `urn:atomic:memory:` (M4) touches the storage key model, manifest keying, `entry_subject`, and every existing memory on disk. Is a one-shot migration acceptable, or must old path-keyed memories keep resolving indefinitely via an alias table? + +--- + +**Key files referenced (all under `/Users/bradleyhilton/Documents/workspace/atomic-projects/atomic`):** `atomic-core/src/pristine/vault.rs` (VaultEntry/summaries), `.../ontology.rs` (vocab seed), `.../tables.rs:550-595` (redb tables), `.../types/hash.rs` (BLAKE3), `atomic-repository/src/repository/vault.rs` (materialize/scan/record/render/parse), `.../vault_intent.rs` (intent CRUD + template wiring + status bug), `.../vault_triples.rs` (KG lift + edge patterns), `.../vault_kg_enrich.rs`, `.../changes.rs:636,704-792` (provenance registration), `atomic-agent/src/provenance/*` + `.../turn/orchestrator/provenance.rs:395` + `.../event.rs` (turn DAG/hooks), `atomic-core/src/change/provenance_graph/*`, `atomic-identity/src/{keypair,signing,identity,store}.rs`, `atomic-cli/src/commands/vault/{mod,intent,memory,goal}.rs` + `.../main.rs`. New crate to add: **`atomic-canonical`** (`vocab, node, jcs, hash, proof, did, directive, lift, reconcile, gate, shacl, prov, render` + `ns/ctx.jsonld` + `shapes/*.ttl`). + +--- + +# Adversarial Critique & Required Corrections + +> Produced by an independent reviewer against the doc + the atomic substrate. The plan is sound; these are the corrections that MUST be folded into M0/M1 before it truly round-trips. + +## Thin-slice assessment +The M0 slice is well-chosen (Intent over Memory) and covers the right conceptual span (create -> lift -> JCS/BLAKE3 -> proof -> gate -> render), but as specified it does NOT work end-to-end and does not fully prove the concept. Two blockers: (1) redefining content_hash breaks vault_scan_working_copy's drift classification (vault.rs:483-488 compares Hash::of(body) to stored hash) and the manifest merkle (vault.rs:625-628) — the round-trip the slice claims to prove is silently severed, and the slice's own exit criterion about body-tampering-not-hiding-spine-changes becomes untestable because scan can no longer classify changes correctly. (2) The slice claims render 'regenerates the body status header from the spine,' but no body-projection engine exists (render_entry_to_markdown appends content_bytes verbatim), so the single-authoring-site proof — the doc's whole thesis in miniature (lines 436-450) — is not actually demonstrated unless that projection is built in M0. It is also under-scoped on reference-at-render (deferred to M7) and validation-report-as-graph (deferred to 3f), both of which are part of the doc's minimal render/gate contract. Recommendation: M0 must additionally (a) re-plumb scan/merkle to operate on canonical-node hashes, and (b) build minimal spine->body projection for the status header. With those two additions the slice becomes genuinely end-to-end and demoable. Without them it is a compile-and-store demo, not a round-trip proof. + +## Confirmed solid +- Correctly diagnoses the load-bearing decision: content_hash moving from blake3(body) to blake3(JCS(canonical node)). Verified at atomic-core/src/pristine/vault.rs:99 (VaultEntry::new hashes content only) and the doc's own status-lesson (lines 440-442) names this exact failure. This is the right center of gravity. +- The three-layer separation (surface/canonical/render) maps cleanly and honestly onto the existing substrate: VAULT_ENTRIES path-keyed redb + vault_materialize (render) + vault_scan/record_working_copy (lift) genuinely is a round-trip engine. Reuse framing is accurate, not hand-waving. +- Honors reference-not-embed: Phase 3g explicitly stores only the edge and resolves at render time (doc lines 61, 189-193), and the plan never proposes transclusion into the canonical node. +- Honors no-triplestore / patch-graph-canonical: JSON-LD is treated as a compile target (like a TS AST), SHACL shapes as Turtle files, projection discarded. Section 4 correctly reconciles this with the doc's line-533 'regional redb materialization vs S3 log' analogy. +- Honors closed-vocabulary: Phase 3a makes vocab.rs the single source and adds a test asserting every SHACL target/directive/template/lift rule references a registry member — directly attacking the doc's stated primary integration risk (five diverging consumers). +- Honors no-auto-fix: Phase 3f and open-question 6 keep 'status:done is granted, never written' and forbid mutating attested fields, only regenerating projected fields (doc lines 452-454, 541). +- Honors presence-not-content: the plan never schematizes the 'why' prose; gate checks presence of proof/attributedTo/verifiedBy+evidence, not reason quality (doc line 57). +- Honors single-authoring-site: M0 exit criteria explicitly deletes the body '**Status:** backlog' authoring site (verified live at atomic-repository/vault/templates/intent.md line 3) and regenerates it from spine on render. +- Correctly identifies the 8 genuinely undefined items in the doc (TaskShape, Change/Decision node types, Scope/Constraint/Ref @types, @context contents, DID resolution, validation-report shape) as open questions rather than silently inventing them. +- The thin-slice choice of Intent (not Memory) is right: Intent already ships as entry_type and avoids the hardest data-model migration (memory id != path) in M0. + +## Risks +- CRITICAL / UNADDRESSED: the hash-semantics change breaks drift detection. vault_scan_working_copy computes Hash::of(body_bytes) and compares it against the stored content_hash to classify New/Modified/Unchanged (atomic-repository/src/repository/vault.rs:483-488). If content_hash becomes blake3(JCS(node)), a body-hash will NEVER equal a canonical-node-hash, so every entry classifies as Modified on every scan and the disk->redb sync loop is corrupted. The plan changes 'what content_hash hashes' but is silent on this comparison site — the M0 slice as written will not round-trip. +- CRITICAL / UNADDRESSED: the manifest merkle chain is derived from content_hash (update_manifest_for_store, vault.rs:625-628, prev.next(&content_hash)). Redefining content_hash silently redefines the vault-wide merkle used for sync/selective-fetch across peers. The plan's 'format_version so old entries verify under old rules' does not cover the merkle, which is a single incremental root, not per-entry — mixed old/new entries produce a merkle that is neither. This is a distributed-sync break, not just a local migration. +- M0 claims render 'regenerates the body status header from the spine' but render_entry_to_markdown currently appends entry.content_bytes verbatim (vault.rs:706-711) — there is NO body-templating engine. Regenerating a spine-derived body is net-new projection work that the plan buries as a one-line render.rs deliverable; it is actually the mechanism the whole single-authoring-site principle depends on and deserves M0 first-class scope. +- Sub-node stable-id reconciliation (Phase 3c reconcile.rs) is scheduled AFTER the M0/M1 lift, but intent update already does whole-body replace (vault_intent.rs:503, new_content = body). If the lift runs on every write before reconcile.rs exists (M1/M2), per-AC/task @ids and their attestations are reallocated and destroyed on the first edit. The dependency ordering understates that reconciliation is a correctness prerequisite for ANY multi-write Intent, not a Phase-3c nicety. +- eddsa-jcs-2022 requires signing over JCS-canonicalized bytes, but atomic-identity signs arbitrary caller bytes with no canonicalization (signing.rs). If proof.rs and hash.rs canonicalize independently (two JCS call sites), any serialization drift between them silently invalidates proofs. The plan splits jcs.rs/hash.rs/proof.rs without mandating a single canonicalization entry point. +- Open-question 5 (unencrypted secret keys at rest, store.rs:459-463) is correctly flagged but the plan still schedules signing in M0 as non-blocking. Making Ed25519 keys load-bearing for every attested node while they sit in plaintext is a ship-blocker that M0 normalizes rather than gates. +- Storing canonical JSON-LD bytes vs recompute-on-demand (open question 2) is deferred, but M0 both signs a proof AND needs re-verification. Without deciding storage first, M0 will implicitly pick recompute, and any future serde/serde_json ordering change breaks every stored proof — the exact drift risk the doc warns about with transclusion, reintroduced at the serialization layer. +- The plan asserts ~65% reuse / ~35% net-new as a confidence signal, but the 35% (JCS, JSON-LD, SHACL closed-world engine, Data Integrity proofs, DID method, directive parser, validation-report-as-graph) is the entire hard core and every piece is greenfield with no in-tree precedent. The percentage framing understates schedule risk on the parts that actually gate the concept. + +## Missing +- Migration of the manifest merkle is omitted. The plan migrates per-entry content_hash behind format_version but never says how the single incremental merkle root (VaultManifest.merkle) is recomputed or how peers with old-merkle vaults reconcile. This is a NON-additive change to a sync primitive the doc implicitly relies on. +- Drift-detection re-plumbing is missing entirely. To keep round-trip working, scan must compare a canonical-node-hash to a canonical-node-hash (re-lift disk file -> canonical -> hash), not Hash::of(body). No task covers rewriting vault.rs:483-488. Without it M0's exit criterion ('tampering the body does not change content_hash in a way that hides a spine change') is untestable because the scan can't even detect changes correctly. +- The doc's 'render resolves reference edges inline at read time' (lines 61, 191-193) is deferred to Phase 3g/M7 (P2), but the M0/M1 Intent already carries informedBy/motivatedBy edges. An intent show that cannot inline a referenced memory is not the doc's render; M0's 'show renders text back' quietly omits the reference-resolution half of the render contract. +- No task addresses the doc's requirement that attributedTo must resolve to a prov:Agent via sh:class (doc lines 366, 427). M0's gate.rs checks 'attributedTo present + resolves to an agent' but there is no prov:Agent node type, no agent record, and no resolver in the M0 scope — the DID resolves to a pubkey, not a typed prov:Agent. The gate cannot enforce sh:class prov:Agent as specified. +- The validation-report-as-graph (doc step 4, lines 508-519) is the doc's stated agent-facing contract, but the plan only produces a Rust ValidationReport struct in M0 and defers the graph form to 3f. If the report is not itself a graph from the start, the agent validation loop the doc centers on is not demonstrated by the P0 milestones. +- Provenance 'used' edge capture (Phase 3e/M6) is correctly called the flywheel's load-bearing edge, but it is P1 and depends on M4. The doc's entire thesis (line 43: 'the flywheel only works if every link is a real edge') means without used-capture there is no closed flywheel. Scheduling the one edge that closes the loop as a late P1 risks shipping intents+memories+provenance that never actually connect. +- No non-goal is violated, but the plan does not explicitly guard against the 'schema on the reason' non-goal (doc line 539) in the lift design — the lift must leave 'why' as an unconstrained text slot. Worth an explicit test that the gate never inspects why content. + +## Conflicts with existing atomic architecture +- content_hash redefinition conflicts with vault_scan_working_copy drift classification (vault.rs:483-488), which is the disk->redb half of the round-trip. The two cannot coexist without re-plumbing scan to hash the canonical node. +- content_hash redefinition conflicts with the incremental manifest merkle (vault.rs:625-628) and thus with cross-peer vault sync/selective-fetch, which chains off content_hash. This touches distributed state, not just local entries. +- Memory id != path (Phase 3d) conflicts with the fundamental storage key model: VAULT_ENTRIES is keyed by vault-relative path (tables.rs:550) and vault_store overwrites by path (last-writer-wins). entry_subject derives KG identity from filename (vault_triples.rs:539-546). Append-only revisions with stable ULID ids conflict with path-as-key at the storage, manifest, and KG layers simultaneously — the plan acknowledges this but schedules it as one P1 milestone (M4) when it is arguably a storage-primitive change. +- The plan proposes ontology.rs becomes 'a thin view over atomic-canonical::vocab' (Phase 3a). But ontology.rs lives in atomic-core and atomic-canonical depends on atomic-identity, not the reverse; atomic-core cannot depend on atomic-canonical without a dependency cycle (atomic-repository/atomic-core are lower in the stack). The single-source-of-truth direction likely has to be atomic-core owning the registry and atomic-canonical consuming it, inverting the plan's proposed ownership. +- Symmetric BLOCKED_BY/BLOCKS edge emission (vault_triples.rs:648-663) conflicts with the doc's directionality rule (line 81, references-inputs-never-uses). The plan correctly forbids copying this for memory but does not schedule fixing the existing symmetric intent edges, which will remain in the KG as a live anti-pattern alongside the new directional model. +- No conflict with patch-theory storage itself: the plan correctly keeps the change/patch graph canonical and JSON-LD as a discarded projection, consistent with doc line 533. This is aligned, not a conflict. + +## Recommendations +- Pull two tasks into M0 that the plan omits or defers: (a) re-plumb vault_scan_working_copy (vault.rs:483-488) to re-lift the disk file to a canonical node and hash THAT for drift classification, and (b) build minimal spine->body projection so the status header is rendered, not stored. These are the actual mechanisms that make the round-trip and single-authoring-site claims true; without them M0 does not prove the concept. +- Add an explicit manifest-merkle migration/versioning task alongside the content_hash change. Decide whether the merkle is recomputed wholesale at migration or namespaced by format_version, and how peers reconcile. Treat this as a distributed-sync change, not a local-entry migration. +- Mandate a single JCS canonicalization entry point used by BOTH hash.rs and proof.rs (one function, one call site each). Add a round-trip test: sign -> serialize -> deserialize -> reverify, and a test that reordering serde map keys does not change the canonical bytes. This closes the silent proof-drift risk. +- Resolve open-question 2 (store canonical bytes vs recompute) BEFORE M0 ships signing. Recommend storing canonical JSON-LD bytes for any signed node so proofs re-verify independent of serializer changes; the doc's transclusion-staleness argument applies equally to recompute drift. +- Invert the registry ownership: put the closed vocabulary in atomic-core (where ontology.rs already lives, low in the dependency stack) and have atomic-canonical consume it. The plan's 'ontology becomes a thin view over atomic-canonical' creates a dependency cycle since atomic-core cannot depend on atomic-canonical. +- Gate signing on the identity-key-at-rest fix (open question 5, store.rs:459-463). Do not make Ed25519 keys load-bearing for every attested node while they persist in plaintext; either implement argon2id+chacha20poly1305 first or explicitly scope M0 to a throwaway/dev identity with a documented non-production caveat. +- Move minimal 'used'-edge capture earlier or at least de-risk it: the flywheel does not close without it (doc line 43). Consider a P1-early stub that records intent/memory URNs consumed per turn even before the full PROV projection, so the chain is traversable when memory lands. +- Pin down the prov:Agent resolution story for M0's gate. Either add a minimal prov:SoftwareAgent/prov:Person node type in M0 so attributedTo can satisfy sh:class prov:Agent as the doc requires (lines 366, 427), or explicitly downgrade M0's gate to 'attributedTo resolves to a DID' and note the sh:class check is deferred — do not claim IntentShape parity when it is not enforced. +- Add an explicit test/guardrail that the lift never schematizes 'why' (doc non-goal, line 539) and that render inlines referenced memories (doc lines 61, 191-193) before declaring intent show complete. Reference-at-render is half the render contract and should not be a P2 afterthought. +- Schedule removal/reframing of the existing symmetric BLOCKED_BY/BLOCKS edges (vault_triples.rs:648-663) as part of the directionality work, not just avoidance for memory — otherwise the KG carries both the old bidirectional anti-pattern and the new directional model simultaneously. diff --git a/docs/recording-the-why.md b/docs/recording-the-why.md new file mode 100644 index 00000000..eee209e3 --- /dev/null +++ b/docs/recording-the-why.md @@ -0,0 +1,556 @@ +# **Recording the Why** + +*A foundation is defined by the metadata it can hold.* + +--- + +## **The problem** + +Git's own manual calls it a stupid content tracker. That's accurate. It records what bytes changed and understands none of it. For twenty years that was fine, because a person read every change and held the reason in their head. The diff was a reminder, and the understanding lived in the author. + +Your agents work at machine speed, and they don't hold anything in their heads between turns. When the person left the loop, the understanding left with them. So now you have a history that records what changed and has no idea why, generated by something that can't tell you later. + +You can ask git what a line says. You can't ask it why the line exists, who decided it should, or what an agent did to put it there. + +We record the why. Every intent carries the reason behind it. Every change carries proof of who made it and the decision that motivated it. Every agent action carries a step-by-step ledger you can question after the fact and hand to a regulator without reconstructing anything. That's the whole job. This document is how we do it. + +--- + +## **Where this comes from** + +The shape we landed on isn't new. We rederived it from first principles, and then realized we'd been here before. + +In the late 1990s, Peter Coad introduced color modeling as part of Feature-Driven Development. The central idea was deceptively simple: classify every object in a domain model into one of four archetypes, each color-coded. The one that carried the most weight was the pink archetype, the moment-interval. A moment-interval records that something happened, when it happened, and who was involved. It's the thing the business needs to remember. + +Read our Decision node back. It's a moment-interval. A thing that happened, at a timestamp, with an author and a reason you're obligated to keep. We didn't borrow that from Coad. We built it by asking what a semantic change graph has to capture to make agent-speed development trustworthy, and arrived at the same structure. That's usually the sign the underlying shape is real. + +FDD's deeper contribution was the feature template: ` `. That template is a tiny schema. It's a forcing function on how you're allowed to express a unit of work, and a malformed feature was supposed to get rejected at the modeling stage. Coad was reaching for structure-as-discipline thirty years ago. What he never had was a validator that enforced it. FDD's structure was advisory. A person read the feature, a person decided it was well-formed, and the structure lived in a document and a progress spreadsheet rather than in anything that could reject. That's the entire delta. We're making load-bearing the thing FDD could only ask someone to honor. + +There's a second piece of Coad's lineage that closes the circle more tightly. Coad founded TogetherSoft, and Together's signature trick was round-trip engineering: keeping the model and the code as two synchronized projections of one truth. That is exactly the problem at the center of this document. Markdown in, typed node canonical, rendered view out, edits reconciling back. We spent months rediscovering round-trip engineering, except our canonical artifact is the change graph instead of a UML model, and the surface is markdown with directives instead of a class diagram. + +The discipline FDD could only ask people to follow is the discipline agents structurally require. That's the through-line. The colored model was a typed semantic node two decades before the industry had the phrase, and agents need exactly that typing because they can't carry meaning between turns the way the person reading every diff used to. + +--- + +## **The Knowledge Flywheel** + +Intents, memories, and provenance aren't three features. They're a cycle. + +A memory captures durable context: a constraint, a prior decision, a lesson. When someone (or an agent) starts a new piece of work, the relevant memories inform the intent. The intent records what we're going to do, why, and what we rejected. The intent motivates a change. The change generates provenance: who did it, what they used, what they produced, step by step. And the provenance, once reviewed, produces new memories. The constraint held. The assumption was wrong. The approach worked for this case but won't generalize. Those observations become memories that inform the next intent. + +That's the flywheel. Memories inform decisions, decisions motivate changes, changes produce provenance, provenance generates memories. Each revolution makes the next one smarter because the graph carries what was learned, where it was learned, and why the learning was trusted. The system remembers for you instead of relying on whoever happened to be in the room. + +The flywheel only works if every link is a real edge in the graph, traversable and queryable. If memories float as documents unconnected to the intents they informed, the cycle breaks and you're back to a pile of files someone has to reconstruct meaning from. And it only works if the nodes are honest. A faked reason breaks the cycle the same way a corrupted input breaks a feedback loop: everything downstream of it is built on something false, and nothing in the system can tell you where the contamination started unless the provenance chain is intact enough to trace back through. + +The flywheel is also the reason memory and intent have to be separate node types with separate revision histories, rather than sections of one big document. Memories live longer than any single intent. A constraint like "no single ordering authority for multi-region writes" will inform dozens of intents over the life of the system. If that memory is embedded in the first intent that captured it, every subsequent intent either duplicates it or links to a section inside a document that's really about something else. Keeping them as independent nodes with their own ids, their own revision chains, and their own proofs means the flywheel's edges are clean and the cost of reuse is one reference, not a copy. + +--- + +## **What we believe** + +We arrived at these positions by building, not by theory. They're load-bearing, so they're worth stating plainly. + +**The why is a typed node, not a text field.** A free-text comment can say anything, link to nothing, and contradict the change it describes. A typed node has an id you can resolve, edges you can traverse, and a shape a validator can reject. The reason becomes queryable because it's a node in the graph. + +**There are three layers, and we keep them apart.** There's an authoring surface someone writes into, a canonical form that gets hashed and signed, and a render someone reads. Markdown is a surface. The typed node is canonical. HTML, CLI text, and editor panels are renders. Most confusion in this space comes from collapsing these. We don't collapse them. + +**Presence is enforced. Content is left honest.** The gate requires that a reason exists, that authorship is proven, that the change links to its decision. The gate never grades the reason itself. The moment you put a shape on the prose, agents fill the shape and the reason becomes a box that's checked rather than a reason that's given. An empty why we can see beats a fake why we trust. We'd rather the field be visibly missing than convincingly faked. + +**Every fact has one authoring site.** A fact written in two places can disagree, and the copy that stays as prose is invisible to a graph check. So status is written once, in the spine, and everywhere else it appears it's rendered from that one source. Contradiction stops being a thing we catch and becomes a thing that can't be represented. + +**We reference, we don't embed.** A linked memory is a node with an id, and an intent points at it with a typed edge. We don't copy the memory's bytes into the intent. Copying freezes a snapshot that goes stale the moment the source revises. The link names a node and pins it to a revision. The reader sees the linked content inline because the render resolves the edge at read time. We store the edge. We inline at the render. + +**The vocabulary is closed.** Node types, edge types, status values, and directive names come from a fixed registry. An unrecognized type is a gate error, not a new type the system quietly absorbs. Open vocabularies rot into something you can query syntactically and can't trust semantically. Closure is what makes this an ontology instead of a pile of typed JSON. + +--- + +## **The three things we record** + +### **Intent** + +An intent is a decision and the reason behind it. What you want to happen, why, what you considered and rejected, and what proves you're the one who decided. It's the `entry_type: intent` we already ship. The intent is the moment-interval, in Coad's terms. The pink box. It records that someone decided, when they decided, what they decided, and why. + +An intent carries collection data as typed sub-nodes: acceptance criteria, tasks, scope boundaries, constraints, and dependencies. These aren't prose sections, they're nodes in the graph, lifted from container directives in the body. Each one is individually addressable, individually attestable, and individually queryable. "Show me every acceptance criterion that's met but has no evidence link" is a graph query, not a grep. + +### **Memory** + +A memory is durable, reusable context. A constraint, a preference, an architectural decision worth carrying forward, a lesson learned from a previous change. Memories are append-only. You supersede a memory with a new revision, you don't mutate it, so the chain of what was believed when stays intact. + +Memories are typed by kind: `constraint`, `preference`, `lesson`, `context`. The kind is part of the vocabulary and the gate rejects an unrecognized kind. Each memory carries `about` edges that link it to the modules, services, or domains it's relevant to. Those edges are what the flywheel resolves when an agent asks "what do I need to know before changing this module." + +The directionality rule keeps the graph clean: a node references its inputs, never its future uses. An intent names the memories that informed it through an `informedBy` edge. A memory never lists the intents that will consume it. This is what lets memories stay stable while intents accrete around them. + +### **Provenance** + +Provenance is the record of who did what, and it's the layer that makes the other two trustworthy. Without provenance, an intent is a claim. With provenance, it's a claim you can verify by walking the chain. + +We use the W3C PROV vocabulary because a regulator's tooling already speaks it. Every agent action is a `prov:Activity` (a turn), associated with a `prov:SoftwareAgent` that `actedOnBehalfOf` a `prov:Person`. The activity records what it `used` (the memories, the intent, the vault state) and what it `generated` (the change). Each turn's `turnParent` points at the prior turn, so the session is a hash-linked sequence, the journey rather than the endpoint. + +The provenance graph for a change is a named subgraph, one addressable, signable unit you can hand to an auditor whole. It answers "what did the agent do, what did it rely on, and who was it acting for" without anyone reconstructing it after the fact. + +--- + +## **Collection data on the graph** + +Intents carry structured collections as first-class sub-nodes. These are the acceptance criteria, tasks, scope items, constraints, and dependencies that live inside an intent today as markdown sections with checkboxes. We lift them to typed nodes because the checkbox alone can't carry the weight they need to carry. + +### **Acceptance criteria** + +A criterion starts as a prose statement of what "done" means. When it's satisfied, it has to carry who verified it, when, and what evidence links to the change that proves it. A bare `[x]` records none of that. So the directive form carries the claim as an attribute, and the lift turns it into a node the gate can check. + +``` +:::acceptance-criterion{#WORD-5-ac-1 status=met verifiedBy=did:atomic:lee evidence=urn:atomic:change:01J8ZE7G2W} +On first load, the app presents a modal asking for the player's name. +::: +``` + +The prose inside the fences is the criterion's text, unconstrained. The attributes are the spine. The SHACL shape says: if `status=met`, then `verifiedBy` and `evidence` must be present and resolve to real nodes. A checked box without evidence fails the gate. + +### **Tasks** + +Tasks are the decomposed work items inside an intent. Each one names the files it touches, the criteria it addresses, and any dependency on other tasks. Today these are the `WORD-5/1`, `WORD-5/2` items in the TODOs section. As nodes, they carry typed edges to the files, the criteria, and each other. + +``` +:::task{#WORD-5-1 status=done criteria=WORD-5-ac-1} +Add name capture state, submit handling, modal markup, and top-of-page display. + +::file-ref{path=src/App.tsx} +::: +``` + +The `criteria` edge links this task to the acceptance criterion it satisfies. The `::file-ref` is a leaf directive (no prose body) naming the file touched. `depends` edges between tasks are explicit and the gate can check for cycles. + +### **Scope** + +Scope records what's in and what's explicitly out. The "out" items are as important as the "in" items, because they're the decisions the agent is supposed to respect as boundaries. Today these are prose under a `## Scope` heading. As nodes, the gate can enforce that an out-of-scope declaration exists and that changes don't touch modules explicitly excluded. + +``` +:::scope-in +`src/App.tsx` React state and markup for the name modal and header display. +::: + +:::scope-out +Persisting the name across browser reloads. Server-side user accounts or multiplayer identity. +::: +``` + +### **Constraints** + +Constraints are rules the implementation must respect. They're authored as prose but typed as a collection so the graph knows how many there are and the render can present them as a checklist an agent can verify against. + +``` +:::constraint +Keep the implementation local to the existing React/Tailwind app. +::: + +:::constraint +The modal should avoid interfering with global game keyboard handling by stopping +form keyboard events from bubbling to the window listener. +::: +``` + +### **Dependencies** + +External dependencies (other intents, other systems, blocking decisions) are reference edges. They use the `:::ref` directive with a typed edge name so the graph can traverse the dependency chain and the gate can check that the target resolves. + +``` +:::ref{to=urn:atomic:intent:019efe80-1234 edge=blockedBy} +::: +``` + +### **The rule across all collections** + +Every collection item is either a container directive (carries prose) or a leaf directive (carries only edges). The directive name is the type, the attributes are the spine, and the prose is the narrative. A type not in the registry is a gate error. This is the closed-vocabulary rule applied at the sub-node level. + +--- + +## **The authoring surface** + +Someone (or an agent) writes markdown. Frontmatter is the spine. The body is the narrative. Typed sub-nodes inside the body are container directives, not positional guesses inferred from heading structure. + +### **Why markdown** + +Agents emit markdown well under load. It's the one format where both people and machines have fluency, and fluency at the authoring surface is what decides whether the forcing function gets real input or gets gamed. A format the author fights is a format the author fakes. + +### **Why frontmatter** + +The spine lives in YAML frontmatter at the top of the file. It holds the facts the gate checks and the graph indexes: id, entry type, status, priority, authorship, the content hash, timestamps, and the edges to other nodes (motivated by, informed by, supersedes). Every spine field has exactly one authoring site, the frontmatter, and everywhere else it appears it's rendered from that source. + +### **Why container directives** + +Before directives, the body's structure was positional. A `- [x]` line under a `## Acceptance Criteria` header became a criterion because of where it sat. That positional lift is fragile. Rename the header, reorder the sections, nest something, and the parser silently mislifts or drops. + +A container directive makes the type explicit and local at the point of authoring. The lift reads the type off the directive name instead of inferring it from position. That's the same move we keep making everywhere else: turn a convention the agent is supposed to honor into structure the system can read directly. + +The three directive forms correspond to three node situations. Container directives (`:::name{...} ... :::`) wrap prose, a criterion with its description, a memory with its body. Leaf directives (`::name{...}`) carry only edges, a file reference, a dependency link. Inline directives (`:name[...]{...}`) name a node inside running prose, like referencing another decision mid-sentence in the why. The directive shape mirrors whether the node carries narrative or not. + +Directive names are drawn from the closed registry. `:::acceptance-criterion`, `:::task`, `:::scope-in`, `:::scope-out`, `:::constraint`, `:::ref`, `::file-ref`. An unrecognized directive name is a gate error. The authoring surface is exactly as closed as the ontology behind it. + +### **Why references instead of transclusion** + +A `:::ref` directive points at another node by id and optionally pins it to a content-hash revision. It does not splice the target's bytes into the host file. Transclusion (copying the target's content into the host at parse time) freezes a snapshot. The memory revises, the host's embedded copy goes stale, and the content hash now attests a document whose included content no longer matches the source. That's the status-contradiction bug one layer up, and it's worse because the staleness is invisible. + +The link names a node. The render inlines the content at read time. We store the edge. We show the content. They're not the same operation, and keeping them apart is the whole point. + +--- + +## **The canonical form** + +The authored markdown lifts to typed nodes in JSON-LD. JSON-LD is RDF serialized as JSON, so the nodes are triples the graph indexes, the linked-data toolchain understands, and a regulator's tooling can process. Nobody hand-writes the canonical form. It's a compile target, the same way nobody hand-writes the AST of their TypeScript. + +### **Why JSON-LD and not the other options** + +We evaluated markdown alone, XML, HTML, and HTML with custom elements. + +Markdown has no schema, no canonicalization standard, and trailing-whitespace variation changes bytes without changing meaning. It's a poor thing to Merkle-hash. It's a good authoring surface and a bad canonical form. + +HTML's parser is specified to never reject. Unclosed tags, misnested elements, and missing close tags all get silently fixed into a DOM. A browser will never refuse a malformed intent record; it renders something. That's the opposite of a forcing function. When we said "it's a file like a TypeScript file," the property we were actually reaching for was a compiler that rejects ill-typed input. HTML is the only option with no rejecting compiler. Its compiler is the browser, and the browser is engineered to never reject. + +XML has the properties we need (draconian parsing, XSD schemas, C14N canonicalization, XML-DSig), but agents emit XML less reliably than JSON, and the verbosity invites box-checking. + +JSON-LD gives us `@type` for node types, `@id` for stable identity, typed references as first-class edges, JSON Schema for validation, and JCS (RFC 8785\) for deterministic bytes to hash. Agents emit JSON well under load. And because JSON-LD is RDF, we get the PROV vocabulary for provenance and the Data Integrity proof standard for signing, both of which are native to the linked-data ecosystem. + +### **The lift** + +The lift is a typed extractor that reads the authored markdown and produces canonical nodes. Frontmatter keys map to spine properties. Directive names map to node types. Directive attributes map to typed properties and edges. Prose inside directive fences becomes the unconstrained text slot. Everything the lift doesn't have a rule for stays in the body as unlifted narrative, and that's correct, because the moment you try to schematize the why you're back to the Copilot Summary failure. + +The lift has one overriding rule: a fact is lifted from exactly one site. If it appears in two places in the surface (like status in both the frontmatter and a body header), only the authoritative site is lifted. The other is ignored during the lift and regenerated during the projection back out. This is how we make contradiction unrepresentable rather than catchable. + +### **An intent as a canonical node** + +The full node for the WORD-5 example, lifted from the authored surface: + +```json +{ + "@context": "https://atomic.dev/ns/ctx.jsonld", + "@type": "Intent", + "@id": "urn:atomic:intent:019efe85-5650-7430-a794-5ab6ade7a4bc", + + "humanKey": "WORD-5", + "title": "Add name prompt modal", + "status": "done", + "priority": "medium", + "view": "proud-moon-a08a", + "motivatedBy": "urn:atomic:decision:01J8Z9K2QF", + "informedBy": ["urn:atomic:memory:01J8ZC4R8T"], + + "hasAcceptanceCriterion": [ + { + "@type": "AcceptanceCriterion", + "@id": "urn:atomic:ac:WORD-5-ac-1", + "text": "On first load, the app presents a modal asking for the player's name.", + "acStatus": "met", + "verifiedBy": "did:atomic:lee", + "evidence": "urn:atomic:change:01J8ZE7G2W" + } + ], + + "hasTask": [ + { + "@type": "Task", + "@id": "urn:atomic:task:WORD-5-1", + "text": "Add name capture state, submit handling, modal markup, and top-of-page display.", + "taskStatus": "done", + "touchesFile": ["src/App.tsx"], + "satisfies": "urn:atomic:ac:WORD-5-ac-1" + } + ], + + "why": "We're choosing a local-only modal over a persisted profile. The name doesn't need to survive a reload yet, and a profile system would pull in storage and identity work we don't want in this change.", + + "contentHash": "blake3:4af1b0...", + "attributedTo": "did:atomic:lee", + "createdAt": "2026-06-25T11:24:25.642584+00:00", + + "proof": { + "@type": "sec:DataIntegrityProof", + "sec:cryptosuite": "eddsa-jcs-2022", + "sec:verificationMethod": "did:atomic:lee#key-1", + "sec:proofPurpose": "assertionMethod", + "sec:proofValue": "z3FXQ..." + } +} +``` + +### **A memory as a canonical node** + +```json +{ + "@context": "https://atomic.dev/ns/ctx.jsonld", + "@type": "Memory", + "@id": "urn:atomic:memory:01J8ZC4R8T", + + "memoryKind": "constraint", + "text": "Multi-region writes must converge with no single ordering authority. Anything that reintroduces a writer-of-record is off the table.", + "about": ["urn:atomic:module:storage", "urn:atomic:module:replication"], + "status": "active", + "supersedes": null, + "previousRevision": null, + + "contentHash": "blake3:9c2e7a...", + "attributedTo": "did:atomic:lee", + "createdAt": "2026-05-02T09:14:00Z", + + "proof": { + "@type": "sec:DataIntegrityProof", + "sec:cryptosuite": "eddsa-jcs-2022", + "sec:proofValue": "z..." + } +} +``` + +### **A provenance graph** + +The provenance for a change is a named subgraph keyed to the change id. Inside it live the activity (a turn), the agent, and the person. The activity's `used` edge is what the turn pulled from the vault. Its `generated` edge is what it wrote back. The `turnParent` edge links to the prior turn, making the session a hash-linked sequence. + +```json +{ + "@context": "https://atomic.dev/ns/ctx.jsonld", + "@id": "urn:atomic:provgraph:01J8ZE7G2W", + "@graph": [ + { + "@type": "prov:Activity", + "@id": "urn:atomic:activity:01J8ZD9X5K", + "prov:startedAtTime": "2026-06-30T13:58:02Z", + "prov:endedAtTime": "2026-06-30T14:02:09Z", + "associatedWith": "did:atomic:agent:claude", + "actedOnBehalfOf": "did:atomic:lee", + "used": [ + "urn:atomic:intent:019efe85-5650-7430-a794-5ab6ade7a4bc", + "urn:atomic:memory:01J8ZC4R8T" + ], + "generated": "urn:atomic:change:01J8ZE7G2W", + "turnParent": "urn:atomic:activity:01J8ZD8W1H" + }, + { + "@type": "prov:SoftwareAgent", + "@id": "did:atomic:agent:claude", + "actedOnBehalfOf": "did:atomic:lee" + }, + { + "@type": "prov:Person", + "@id": "did:atomic:lee" + } + ] +} +``` + +--- + +## **The gate** + +A SHACL shape decides whether a node may enter the graph. This is the forcing function in the literal sense. `status: done` isn't a value an agent writes, it's a state the system grants when the shapes pass. + +SHACL is written in Turtle, the same RDF the graph serializes to. The shapes live in the same data model as the nodes they check. The vocabulary you'll use most of the time is small: `sh:in` for closed value sets, `sh:minCount` and `sh:maxCount` for cardinality, `sh:class` to require that a reference resolves to a node of the right type, `sh:node` to say a referenced node must itself satisfy another shape, and `sh:sparql` for the conditional rules core SHACL can't express. + +### **The intent shape** + +``` +@prefix sh: . +@prefix atom: . +@prefix prov: . +@prefix sec: . + +atom:IntentShape + a sh:NodeShape ; + sh:targetClass atom:Intent ; + + sh:property [ + sh:path atom:status ; + sh:in ( "backlog" "todo" "in_progress" "done" ) ; + sh:minCount 1 ; sh:maxCount 1 ; + sh:message "status must be exactly one of the known states" ] ; + + sh:property [ + sh:path atom:attributedTo ; + sh:minCount 1 ; sh:class prov:Agent ; + sh:message "author must resolve to a known agent identity, not a string" ] ; + + sh:property [ + sh:path sec:proof ; + sh:minCount 1 ; + sh:message "intent must carry a Data Integrity proof" ] ; + + sh:property [ + sh:path atom:hasAcceptanceCriterion ; + sh:node atom:AcceptanceCriterionShape ] ; + + sh:property [ + sh:path atom:hasTask ; + sh:node atom:TaskShape ] . +``` + +### **The acceptance criterion shape** + +``` +atom:AcceptanceCriterionShape + a sh:NodeShape ; + + sh:property [ + sh:path atom:acStatus ; + sh:in ( "open" "met" ) ; + sh:maxCount 1 ] ; + + sh:sparql [ + sh:message "a met acceptance criterion must carry verifiedBy and evidence" ; + sh:select """ + PREFIX atom: + SELECT $this WHERE { + $this atom:acStatus "met" . + FILTER NOT EXISTS { + $this atom:verifiedBy ?who . + $this atom:evidence ?ev . + } + }""" ] . +``` + +### **The memory shape** + +``` +atom:MemoryShape + a sh:NodeShape ; + sh:targetClass atom:Memory ; + + sh:property [ + sh:path atom:memoryKind ; + sh:in ( "constraint" "preference" "lesson" "context" ) ; + sh:minCount 1 ; sh:maxCount 1 ; + sh:message "memory kind must be one of the known types" ] ; + + sh:property [ + sh:path atom:status ; + sh:in ( "active" "superseded" "retracted" ) ; + sh:minCount 1 ; sh:maxCount 1 ] ; + + sh:property [ + sh:path atom:attributedTo ; + sh:minCount 1 ; sh:class prov:Agent ; + sh:message "author must resolve to a known agent identity" ] ; + + sh:property [ + sh:path sec:proof ; + sh:minCount 1 ; + sh:message "memory must carry a Data Integrity proof" ] . +``` + +### **The status lesson, because it's the whole thesis in miniature** + +We found this bug in our own demo and it's worth walking through in detail, because every design choice in this document traces back to it. + +An agent was given a task: implement a feature, then update the intent file to reflect completion. The intent file had status recorded in two places. The YAML frontmatter at the top carried `status: done`. And the body of the markdown, in a human-readable header line, carried `**Status:** backlog`. Below both of those, every acceptance criterion was checked and every TODO was marked complete. The agent had finished the work, updated the frontmatter to `done`, and left the body header untouched at `backlog`. + +The file was internally contradictory, and nothing caught it. The frontmatter was valid YAML. The body was valid markdown. The content hash was computed over the whole file, so it faithfully attested a document that said two different things about the same fact. The contradiction shipped, cryptographically signed. + +The first instinct is "add a rule that says there can be only one status." That's `sh:maxCount 1` in SHACL. It doesn't work. When the lift pulls the frontmatter status into the graph as one property and the body-header status into the graph as a different property, each property genuinely holds one value. The count is satisfied. The contradiction passes. + +The second instinct is smarter: check agreement. SHACL's `sh:equals` says two properties must hold the same value. That catches the disagreement, because `done` is not equal to `backlog`, and the gate rejects the file. + +But the third option is the one we chose, and it's the one that matters. We removed the second authoring site entirely. Status is authored once, in the frontmatter spine. The body-header line that used to say `**Status:** backlog` is no longer written by the agent or the person. It's rendered from the spine value when someone reads the file. The agent can't set it to a contradictory value because the agent doesn't write it at all. Contradiction stops being a thing we catch and becomes a thing that can't be represented. + +Make the fact singular where you can. Check agreement where you can't. That's the principle that runs under every design choice in this document. + +### **What the gate refuses to do** + +The gate will never auto-fix a load-bearing fact. It may regenerate a projected field (a rendered body header) because nothing's invented there. It will never reconcile a contradiction in an attested fact by picking a winner. A gate that repairs the agreement it was meant to verify is manufacturing the thing we're trying to prove. + +--- + +## **How you use it** + +### **From the CLI** + +**Scaffold a new intent from a template:** + +``` +atomic intent new WORD-5 --template feature +``` + +Produces a markdown file with the frontmatter spine pre-filled (id, view, author, timestamps) and the directive blocks stubbed for the template's expected collection types. The template is how the closed vocabulary reaches the author. You can only scaffold types that exist in the registry. + +**Read an intent:** + +``` +atomic intent show WORD-5 +``` + +Resolves the node and prints a rendered view as formatted text. Referenced memories are pulled in inline. No file is written, no browser is opened. The render is a pure function of the node, the way `git show` turns a stored object into a readable diff. + +**Validate an intent:** + +``` +atomic intent validate WORD-5 +``` + +Runs the SHACL gate against the lifted node and prints the report. On failure you get the failing node, the shape it broke, and the message. The same check runs automatically at the transition to `done`, so validate-by-hand is for authoring. The gate is for the system. + +**Show the flywheel chain for a change:** + +``` +atomic provenance trace urn:atomic:change:01J8ZE7G2W +``` + +Walks the provenance graph: the change, the activity that generated it, the intent that motivated it, the memories that informed the intent, and the agent and person involved. This is the "prove the full chain without reconstructing it" claim from the pitch, made into a command. + +**Scaffold a new memory:** + +``` +atomic memory new --kind constraint --about storage,replication +``` + +Produces a memory file with the kind, about edges, and authorship pre-filled. The body is open for the constraint text. + +### **Templates** + +A template is a directive scaffold tied to a node type and a use case. The `feature` template for an intent stubs acceptance criteria, tasks, scope, and constraint blocks. A `bugfix` template might stub a reproduction section and a root-cause memory reference. Templates are where authoring convenience and the closed vocabulary meet: the author gets a head start, and the head start can only contain types the ontology recognizes. + +Templates don't constrain the body. They constrain the spine and the directive blocks. The prose inside each block is always unconstrained, because the moment you template the reason you're templating the fake. + +### **The validation loop for agents** + +The agent is the main consumer of a failed gate, so failures come back as a graph, not as prose the agent has to parse. The loop is: + +1. Agent proposes a node (writes or updates the markdown). +2. The lift extracts the canonical node. +3. The gate runs SHACL shapes against the lifted node. +4. On failure, the validation report (itself a graph: failing node, source shape, offending value, message) returns to the agent as structured input. +5. The agent fixes the surface and resubmits. +6. Only a passing node transitions. + +No person sits in the inner loop unless a shape is written to demand one. The gate decides. The agent responds to the gate's structured output. The person authors the shapes that define what "right" means, and the system enforces them at machine speed. + +--- + +## **What we are not building** + +Saying no here is as load-bearing as anything above. Each of these is a road we looked down and refused. + +**HTML as a source of truth.** HTML's parser is built to never reject. It recovers from malformed input and renders something, which is the opposite of a forcing function. We render to HTML for reading. We never store the canonical record as HTML. + +**Hand-authored JSON-LD or XML on disk.** The canonical form is a compile target. People and agents author markdown with directives, because that's what they emit cleanly. JSON-LD is what the graph, the regulator, and the control plane consume. We don't ask anyone to hand-write the canonical node. + +**Pre-rendered HTML files for every node.** We don't eagerly materialize renders. A system with 10,000 intents and 5,000 memories doesn't generate 15,000 HTML files. The render runs at the moment of a read, for the one node someone opened, and it's thrown away after. The CLI renders to text, the editor renders to a panel, the web view renders to HTML. One projection function, three output targets, zero files on disk. + +**A triplestore as our storage tier.** The semantic-web stack wants us to land everything in a triplestore and query with SPARQL. That fights our patch-theory storage primitive head-on. The patch graph stays canonical. The triple view is a projection we compute and discard, the same relationship the regional redb materializations have to the S3 log. + +**OWL reasoning and open-world inference.** OWL is where teams disappear into ontology engineering and never ship. Our gate is closed-world by nature: if the why is absent, we reject. SHACL validates what's present. We don't run a reasoner that invents facts we never asserted. + +**Transclusion of linked content into the canonical form.** We reference by id and resolve at the render. We never splice another node's bytes into a host and then hash the host, because that freezes a snapshot that goes stale and makes our proof attest something that's no longer true. + +**A schema on the reason itself.** The why is unconstrained prose, and it stays that way. Required structure on a reason produces a filled box that fakes the reason. That's the Copilot Summary problem: a reverse-engineered rationale that suppresses further inquiry by pretending the why was recorded when it was generated. An empty field is better than a convincing fake, because the empty field is at least visibly incomplete. + +**Auto-fixing of load-bearing facts at the gate.** The gate may regenerate a projected field. It will never reconcile a contradiction in an attested fact by picking a winner. A gate that repairs the agreement it was meant to verify is manufacturing the thing we're trying to prove. + +**An open directive or edge vocabulary.** An agent being able to invent `:::whatever` and have it lift to a node is how the graph rots. Unknown names are gate errors. The directive surface is exactly as closed as the ontology behind it. + +**`maxCount` as a contradiction check.** A cardinality constraint ("there can be only one status") rejects redundancy, not disagreement. Two properties can each hold one value and still contradict each other. The rule passes a file that says `done` in one place and `backlog` in another. Where two sources must match, we check agreement. Where we can, we make the fact singular so there's nothing to disagree with and no rule is needed. + +**SPARQL as a general-purpose constraint language.** The SPARQL escape hatch in SHACL is powerful and it's the part to ration. Every rule we can express with `sh:in`, `sh:class`, or `sh:equals` stays declarative, portable, and cheap to reason about. We reach for `sh:sparql` only for genuinely conditional rules and resist letting the gate grow into a query engine. + +--- + +## **The one rule, if you remember nothing else** + +Make the fact singular where you can, so contradiction can't be expressed. Check agreement where you can't. Reference, don't embed. Enforce that the reason exists, and leave what it says alone. + +The discipline FDD could only ask someone to follow is the discipline agents structurally require. We're making load-bearing the thing that used to be advisory. That's the pink box, thirty years later, with a validator that finally rejects. + From ed6ac14fae671cc4f4629f9beaa7d4e9fdbb9e5d Mon Sep 17 00:00:00 2001 From: Bradley Hilton Date: Wed, 1 Jul 2026 14:57:32 -0500 Subject: [PATCH 02/21] feat(canonical): collection sub-nodes, generalized attestation, and the Memory node (P1+P2) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds on the M0 engine. Two phases, plus fixes from an adversarial review pass. P1 — generalized attestation + full collections: - Attestation now flows through ONE Value-based path (proof::attest_value / verify_value); Intent and Memory sign/verify through the same code and the single jcs entry point, so hash and signature can never fork. - Lift/gate/render the remaining collection sub-nodes: scope-in, scope-out, constraint, and :::ref dependency edges. The gate requires an explicit scope-out when scope is declared (presence, not content). - Registry closure test: every lift-handled directive is a known vocab member. P2 — Memory node type: - MemoryNode with closed memoryKind {constraint,preference,lesson,context} and status {active,superseded,retracted}, about[] input edges, and an append-only revision chain (supersedes / previousRevision). lift_memory + MemoryShape gate. - Directionality: a memory names its inputs, never its consumers. Adversarial-review fixes (2 blockers, 1 major, 3 minor), each with a regression test: - BLOCKER: add #[serde(deny_unknown_fields)] to every deserialized node/sub-node so an injected key on a signed record is rejected on load instead of being silently stripped before verification. - BLOCKER: drop the "superseded => supersedes present" gate rule — it inverted directionality (forced a retired node to point forward at its successor). - MAJOR: lift_memory no longer runs the closed-vocabulary parser over the open memory body (a lenient :::memory fence scan), so prose containing :: / ::: (a Rust turbofish, or discussing :::why) is valid content, not a parse error. - MINOR: :::ref edge= is restricted to a dependency subset {depends, blockedBy}. - MINOR: verify_value enforces the proof's declared cryptosuite/purpose/type. - MINOR: parse_markdown normalizes CRLF. 51 tests pass (33 unit + 18 integration); clippy clean. Still crate-level only — vault wiring and CLI verbs remain a later milestone. --- atomic-canonical/src/gate.rs | 282 +++++++++++++++++++++++++ atomic-canonical/src/lib.rs | 32 ++- atomic-canonical/src/lift.rs | 238 ++++++++++++++++++++- atomic-canonical/src/memory.rs | 308 ++++++++++++++++++++++++++++ atomic-canonical/src/node.rs | 110 +++++++--- atomic-canonical/src/proof.rs | 248 +++++++++++++++++++--- atomic-canonical/src/render.rs | 198 +++++++++++++++++- atomic-canonical/src/vocab.rs | 46 +++++ atomic-canonical/tests/roundtrip.rs | 234 ++++++++++++++++++++- 9 files changed, 1628 insertions(+), 68 deletions(-) create mode 100644 atomic-canonical/src/memory.rs diff --git a/atomic-canonical/src/gate.rs b/atomic-canonical/src/gate.rs index cb7930c5..549050d7 100644 --- a/atomic-canonical/src/gate.rs +++ b/atomic-canonical/src/gate.rs @@ -15,6 +15,7 @@ //! //! The gate never auto-fixes a load-bearing fact — it only reports. +use crate::memory::MemoryNode; use crate::node::CanonicalNode; use crate::vocab; @@ -111,6 +112,21 @@ pub fn validate_intent(node: &CanonicalNode) -> ValidationReport { }), } + // Scope-out presence: if scope is being declared (scope-in present), the + // intent must also state what is out of scope — the boundaries the agent + // must respect. This is presence-enforced (we never read the prose). An + // intent with no scope section at all is not forced to declare scope-out. + if !node.has_scope_in.is_empty() && node.has_scope_out.is_empty() { + out.push(Violation { + focus_node: focus.clone(), + shape: "IntentShape".into(), + path: Some("hasScopeOut".into()), + message: + "a scope declaration must state what is out of scope (the boundaries the agent must respect)" + .into(), + }); + } + // Each acceptance criterion satisfies AcceptanceCriterionShape. for ac in &node.has_acceptance_criterion { if !vocab::is_known_ac_status(&ac.ac_status) { @@ -141,3 +157,269 @@ pub fn validate_intent(node: &CanonicalNode) -> ValidationReport { ValidationReport::from(out) } + +/// Validate a canonical Memory node against `MemoryShape`. Mirrors the doc's +/// shape: `memoryKind` and `status` are closed value sets (exactly one each), +/// `attributedTo` and `proof` must be present, and the `text` must be present +/// and non-empty. As everywhere, presence is enforced and content left honest — +/// no rule reads the memory prose. +pub fn validate_memory(node: &MemoryNode) -> ValidationReport { + let mut out = Vec::new(); + let focus = &node.id; + + // memoryKind ∈ closed set, exactly one (single field ⇒ cardinality holds). + if !vocab::is_known_memory_kind(&node.memory_kind) { + out.push(Violation { + focus_node: focus.clone(), + shape: "MemoryShape".into(), + path: Some("memoryKind".into()), + message: format!( + "memoryKind '{}' is not one of {:?}", + node.memory_kind, + vocab::MEMORY_KIND + ), + }); + } + + // status ∈ closed set, exactly one. + if !vocab::is_known_memory_status(&node.status) { + out.push(Violation { + focus_node: focus.clone(), + shape: "MemoryShape".into(), + path: Some("status".into()), + message: format!( + "status '{}' is not one of {:?}", + node.status, + vocab::MEMORY_STATUS + ), + }); + } + + // attributedTo must be present (sh:class prov:Agent deferred — see M0 notes). + if node.attributed_to.as_deref().unwrap_or("").is_empty() { + out.push(Violation { + focus_node: focus.clone(), + shape: "MemoryShape".into(), + path: Some("attributedTo".into()), + message: "author (attributedTo) must be present as a DID".into(), + }); + } + + // proof must be present. + if node.proof.is_none() { + out.push(Violation { + focus_node: focus.clone(), + shape: "MemoryShape".into(), + path: Some("proof".into()), + message: "memory must carry a Data Integrity proof".into(), + }); + } + + // presence-enforced: the memory text must exist (content left honest). + if node.text.trim().is_empty() { + out.push(Violation { + focus_node: focus.clone(), + shape: "MemoryShape".into(), + path: Some("text".into()), + message: "a memory must carry text — its content is not graded".into(), + }); + } + + // Directionality (load-bearing): `supersedes` / `previousRevision` are + // BACKWARD edges — a NEWER memory names what it replaced. A retired + // (superseded) memory therefore gains NO new edge; "what replaced me" is + // found by traversing INBOUND supersedes edges from the newer active + // memory, never by a forward pointer on the old node. So there is + // deliberately no `superseded ⇒ supersedes present` rule here: enforcing + // one would force the retired node to point forward at its successor, + // which is exactly the "references its future uses" anti-pattern the doc + // forbids (and re-introduces the symmetric-edge contradiction risk). + + ValidationReport::from(out) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::node::{ScopeItem, CONTEXT_URL}; + use crate::proof; + use crate::vocab::NodeType; + use atomic_identity::identity::Identity; + use atomic_identity::keypair::KeyPair; + + fn scope_item(id: &str, text: &str) -> ScopeItem { + ScopeItem { + type_: NodeType::ScopeItem.as_str().to_string(), + id: id.to_string(), + text: text.to_string(), + } + } + + /// A minimal, fully attested Intent that conforms — the base for mutation. + fn attested_base() -> CanonicalNode { + let kp = KeyPair::generate(); + let id = Identity::new("lee", &kp); + let node = CanonicalNode { + context: CONTEXT_URL.to_string(), + type_: NodeType::Intent.as_str().to_string(), + id: "urn:atomic:intent:gate-1".to_string(), + human_key: "GATE-1".to_string(), + title: "Gate base".to_string(), + status: "todo".to_string(), + priority: None, + view: None, + motivated_by: None, + informed_by: Vec::new(), + has_acceptance_criterion: Vec::new(), + has_task: Vec::new(), + has_scope_in: Vec::new(), + has_scope_out: Vec::new(), + has_constraint: Vec::new(), + depends_on: Vec::new(), + why: Some("a reason".to_string()), + content_hash: None, + attributed_to: None, + created_at: "2026-06-25T00:00:00Z".to_string(), + proof: None, + }; + proof::attest(node, &id, &kp) + } + + #[test] + fn gate_requires_scope_out_when_scope_in_present() { + let mut node = attested_base(); + node.has_scope_in = vec![scope_item("urn:atomic:scope:gate-1-scope-in-1", "in")]; + + // Scope-in declared but no scope-out → non-conforming on hasScopeOut. + let report = validate_intent(&node); + assert!(!report.conforms); + assert!(report + .results + .iter() + .any(|v| v.path.as_deref() == Some("hasScopeOut"))); + + // Adding scope-out satisfies the rule. + node.has_scope_out = vec![scope_item("urn:atomic:scope:gate-1-scope-out-1", "out")]; + assert!(validate_intent(&node).conforms); + } + + #[test] + fn gate_does_not_force_scope_out_without_scope_in() { + // No scope section at all: a minimal intent is not forced to declare it. + let node = attested_base(); + assert!(validate_intent(&node).conforms); + } + + /// A minimal, fully attested Memory that conforms — the base for mutation. + fn attested_memory() -> MemoryNode { + let kp = KeyPair::generate(); + let id = Identity::new("lee", &kp); + let node = MemoryNode { + context: CONTEXT_URL.to_string(), + type_: NodeType::Memory.as_str().to_string(), + id: "urn:atomic:memory:gate-1".to_string(), + memory_kind: "constraint".to_string(), + text: "a durable constraint".to_string(), + about: vec!["urn:atomic:module:storage".to_string()], + status: "active".to_string(), + supersedes: None, + previous_revision: None, + content_hash: None, + attributed_to: None, + created_at: "2026-05-02T09:14:00Z".to_string(), + proof: None, + }; + proof::attest_memory(node, &id, &kp) + } + + #[test] + fn memory_gate_rejects_unknown_kind() { + let mut node = attested_memory(); + node.memory_kind = "architecture".to_string(); + let report = validate_memory(&node); + assert!(!report.conforms); + assert!(report + .results + .iter() + .any(|v| v.shape == "MemoryShape" && v.path.as_deref() == Some("memoryKind"))); + } + + #[test] + fn memory_gate_rejects_unknown_status() { + let mut node = attested_memory(); + node.status = "archived".to_string(); + let report = validate_memory(&node); + assert!(!report.conforms); + assert!(report + .results + .iter() + .any(|v| v.shape == "MemoryShape" && v.path.as_deref() == Some("status"))); + } + + #[test] + fn memory_gate_requires_proof_and_attributed_to_and_text() { + // An un-attested, empty-text memory violates all three presence rules. + let node = MemoryNode { + context: CONTEXT_URL.to_string(), + type_: NodeType::Memory.as_str().to_string(), + id: "urn:atomic:memory:bare".to_string(), + memory_kind: "lesson".to_string(), + text: " ".to_string(), + about: Vec::new(), + status: "active".to_string(), + supersedes: None, + previous_revision: None, + content_hash: None, + attributed_to: None, + created_at: "2026-05-02T09:14:00Z".to_string(), + proof: None, + }; + let report = validate_memory(&node); + assert!(!report.conforms); + for path in ["proof", "attributedTo", "text"] { + assert!( + report.results.iter().any(|v| v.path.as_deref() == Some(path)), + "expected a violation on {path}" + ); + } + + // A fully attested memory with text conforms. + assert!(validate_memory(&attested_memory()).conforms); + } + + #[test] + fn superseded_memory_gains_no_forward_edge() { + // Directionality: flipping status to `superseded` must NOT require (or + // add) a forward pointer to the successor. A first-revision memory + // (supersedes: none) that is later retired still conforms — the retired + // node references nothing new; the successor points back at it instead. + let mut node = attested_memory(); + node.status = "superseded".to_string(); + node.supersedes = None; + node.previous_revision = None; + assert!( + validate_memory(&node).conforms, + "a retired memory must not be forced to name its successor" + ); + } + + #[test] + fn memory_serialization_has_no_intent_backedge() { + // Directionality: a memory names its inputs (`about`) and revision chain, + // never the intents that consume it. Assert no consuming-edge key leaks. + let node = attested_memory(); + let value = node.to_value(); + let obj = value.as_object().unwrap(); + for key in obj.keys() { + let k = key.to_ascii_lowercase(); + assert!( + !k.contains("intent") && !k.contains("usedby") && !k.contains("consumedby"), + "memory carries a consuming back-edge key: {key}" + ); + } + // Only the allowed memory edges appear (about here; revision chain omitted). + assert!(obj.contains_key("about")); + assert!(!obj.contains_key("supersedes")); + assert!(!obj.contains_key("previousRevision")); + } +} diff --git a/atomic-canonical/src/lib.rs b/atomic-canonical/src/lib.rs index 1f633410..8cb16915 100644 --- a/atomic-canonical/src/lib.rs +++ b/atomic-canonical/src/lib.rs @@ -35,15 +35,19 @@ pub mod gate; pub mod hash; pub mod jcs; pub mod lift; +pub mod memory; pub mod node; pub mod proof; pub mod render; pub mod vocab; pub use error::{CanonicalError, Result}; -pub use gate::{validate_intent, ValidationReport, Violation}; -pub use node::{AcceptanceCriterion, CanonicalNode, Proof, Task}; -pub use render::{render, Target}; +pub use gate::{validate_intent, validate_memory, ValidationReport, Violation}; +pub use memory::MemoryNode; +pub use node::{ + AcceptanceCriterion, CanonicalNode, Constraint, Proof, Ref, ScopeItem, Task, +}; +pub use render::{render, render_memory, Target}; use atomic_identity::identity::Identity; use atomic_identity::keypair::KeyPair; @@ -66,3 +70,25 @@ pub fn lift_and_attest( pub fn verify(node: &CanonicalNode, public_key: &atomic_identity::keypair::PublicKey) -> Result<()> { proof::verify(node, public_key) } + +/// Lift an authored memory (frontmatter + body) into a canonical node, attest +/// it (hash + sign) with the given identity, and return the node. Mirrors +/// [`lift_and_attest`] and signs through the same single path. The node is +/// *not* gated here — call [`validate_memory`] to gate it. +pub fn lift_and_attest_memory( + frontmatter: &Map, + body: &str, + identity: &Identity, + keypair: &KeyPair, +) -> Result { + let node = memory::lift_memory(frontmatter, body)?; + Ok(proof::attest_memory(node, identity, keypair)) +} + +/// Verify an attested memory's content hash and signature against a public key. +pub fn verify_memory( + node: &MemoryNode, + public_key: &atomic_identity::keypair::PublicKey, +) -> Result<()> { + proof::verify_memory(node, public_key) +} diff --git a/atomic-canonical/src/lift.rs b/atomic-canonical/src/lift.rs index 6a9f877f..42a3343e 100644 --- a/atomic-canonical/src/lift.rs +++ b/atomic-canonical/src/lift.rs @@ -14,8 +14,26 @@ use serde_json::{Map, Value}; use crate::directive::{self, Directive}; use crate::error::{CanonicalError, Result}; -use crate::node::{AcceptanceCriterion, CanonicalNode, Task, CONTEXT_URL}; -use crate::vocab::NodeType; +use crate::node::{ + AcceptanceCriterion, CanonicalNode, Constraint, Ref, ScopeItem, Task, CONTEXT_URL, +}; +use crate::vocab::{self, NodeType}; + +/// The exact set of directive names `lift_intent` branches on. The match and +/// the closed-vocabulary test both read this const so the test cannot rot when +/// the lift gains or loses a branch (bidirectional closure). Every name here +/// must be a member of [`vocab::DIRECTIVE_NAMES`]; nothing in the registry may +/// be a name the lift cannot handle. +pub(crate) const LIFTED_INTENT_DIRECTIVES: &[&str] = &[ + "why", + "acceptance-criterion", + "task", + "scope-in", + "scope-out", + "constraint", + "ref", + "file-ref", +]; /// Lift an intent from its frontmatter spine and markdown body. pub fn lift_intent(frontmatter: &Map, body: &str) -> Result { @@ -28,8 +46,15 @@ pub fn lift_intent(frontmatter: &Map, body: &str) -> Result, body: &str) -> Result {} + "scope-in" => { + scope_in_n += 1; + scope_in.push(lift_scope(d, &human_key, "scope-in", scope_in_n)); + } + "scope-out" => { + scope_out_n += 1; + scope_out.push(lift_scope(d, &human_key, "scope-out", scope_out_n)); + } + "constraint" => { + constraint_n += 1; + constraints.push(lift_constraint(d, &human_key, constraint_n)); + } + "ref" => { + deps.push(lift_ref(d)?); + } + // `file-ref` is nested-only (consumed inside `task`); at top level + // it carries no meaning, so it is a recognized no-op. + "file-ref" => {} other => { + debug_assert!( + !LIFTED_INTENT_DIRECTIVES.contains(&other), + "'{other}' is in LIFTED_INTENT_DIRECTIVES but has no match arm" + ); return Err(CanonicalError::Lift(format!( - "directive ':{other}' has no lift rule" - ))) + "directive ':{other}' has no lift rule (lift handles: {})", + LIFTED_INTENT_DIRECTIVES.join(", ") + ))); } } } @@ -71,6 +117,10 @@ pub fn lift_intent(frontmatter: &Map, body: &str) -> Result Task { } } +/// Lift a `:::scope-in` / `:::scope-out` container into a `ScopeItem`. +/// `kind` is "scope-in" or "scope-out" and drives the generated id slug. +/// Prose body is the unconstrained narrative (never graded). +fn lift_scope(d: &Directive, human_key: &str, kind: &str, n: usize) -> ScopeItem { + let local = d + .id + .clone() + .unwrap_or_else(|| format!("{}-{kind}-{n}", slug(human_key))); + ScopeItem { + type_: NodeType::ScopeItem.as_str().to_string(), + id: as_urn("scope", &local), + text: d.body.clone(), + } +} + +/// Lift a `:::constraint` container into a `Constraint`. +fn lift_constraint(d: &Directive, human_key: &str, n: usize) -> Constraint { + let local = d + .id + .clone() + .unwrap_or_else(|| format!("{}-constraint-{n}", slug(human_key))); + Constraint { + type_: NodeType::Constraint.as_str().to_string(), + id: as_urn("constraint", &local), + text: d.body.clone(), + } +} + +/// Lift a `:::ref{to= edge=}` leaf into a typed dependency edge. Both `to` and +/// `edge` are required (a dependency with no target or no edge type is a lift +/// error), and `edge` must be a known *dependency* edge — a `:::ref` sits on the +/// dependency chain, so edges like `verifiedBy`/`about` are rejected even though +/// they are valid edges elsewhere. +fn lift_ref(d: &Directive) -> Result { + let to = d + .attr("to") + .ok_or_else(|| CanonicalError::Lift("':::ref' is missing required 'to'".into()))? + .to_string(); + let edge = d + .attr("edge") + .ok_or_else(|| CanonicalError::Lift("':::ref' is missing required 'edge'".into()))? + .to_string(); + if !vocab::is_known_dependency_edge(&edge) { + return Err(CanonicalError::Lift(format!( + "':::ref' edge '{edge}' is not a dependency edge {:?}", + vocab::DEPENDENCY_EDGES + ))); + } + Ok(Ref { + type_: d.id.as_ref().map(|_| NodeType::Ref.as_str().to_string()), + id: d.id.as_ref().map(|id| as_urn("ref", id)), + to, + edge, + }) +} + /// Wrap a local id into `urn:atomic::` unless already a urn. fn as_urn(kind: &str, local: &str) -> String { if local.starts_with("urn:atomic:") { @@ -166,7 +272,11 @@ fn str_array(fm: &Map, key: &str) -> Vec { /// `---\n\n---\n`. Enough for templates and the CLI; /// values may be quoted strings or `[a, b]` arrays. Not a full YAML parser. pub fn parse_markdown(doc: &str) -> Result<(Map, String)> { - let doc = doc.strip_prefix('\u{feff}').unwrap_or(doc); + // Normalize CRLF so a Windows-authored file parses identically to LF — + // otherwise the "---\n" prefix match fails and the whole doc is silently + // treated as body with empty frontmatter. + let normalized = doc.strip_prefix('\u{feff}').unwrap_or(doc).replace("\r\n", "\n"); + let doc = normalized.as_str(); let rest = match doc.strip_prefix("---\n") { Some(r) => r, None => return Ok((Map::new(), doc.to_string())), @@ -211,3 +321,117 @@ fn parse_scalar(raw: &str) -> Value { let unquoted = raw.trim_matches(['"', '\'']); Value::String(unquoted.to_string()) } + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + + fn fm() -> Map { + json!({ "id": "WORD-5", "title": "t", "status": "todo" }) + .as_object() + .unwrap() + .clone() + } + + #[test] + fn lifts_scope_in_out_and_constraints() { + let body = "\ +:::scope-in +`src/App.tsx` state and markup. +::: + +:::scope-out +Persisting the name across reloads. +::: + +:::constraint +Keep it local to the existing app. +::: + +:::constraint +Do not touch the global keyboard handler. +:::"; + let node = lift_intent(&fm(), body).unwrap(); + assert_eq!(node.has_scope_in.len(), 1); + assert_eq!(node.has_scope_out.len(), 1); + assert_eq!(node.has_constraint.len(), 2); + + // Ids are well-formed urns generated from the slug + ordinal. + assert_eq!(node.has_scope_in[0].id, "urn:atomic:scope:word-5-scope-in-1"); + assert_eq!(node.has_scope_out[0].id, "urn:atomic:scope:word-5-scope-out-1"); + assert_eq!(node.has_constraint[0].id, "urn:atomic:constraint:word-5-constraint-1"); + assert_eq!(node.has_constraint[1].id, "urn:atomic:constraint:word-5-constraint-2"); + assert!(node.has_scope_in[0].text.contains("src/App.tsx")); + } + + #[test] + fn lifts_ref_dependency() { + let body = ":::ref{to=urn:atomic:intent:xyz edge=blockedBy}\n:::"; + let node = lift_intent(&fm(), body).unwrap(); + assert_eq!(node.depends_on.len(), 1); + assert_eq!(node.depends_on[0].to, "urn:atomic:intent:xyz"); + assert_eq!(node.depends_on[0].edge, "blockedBy"); + // No @type/@id emitted when the directive carries no #id. + assert!(node.depends_on[0].type_.is_none()); + assert!(node.depends_on[0].id.is_none()); + } + + #[test] + fn ref_with_unknown_edge_is_error() { + let body = ":::ref{to=urn:atomic:intent:xyz edge=wat}\n:::"; + assert!(lift_intent(&fm(), body).is_err()); + } + + #[test] + fn ref_missing_to_is_error() { + let body = ":::ref{edge=blockedBy}\n:::"; + assert!(lift_intent(&fm(), body).is_err()); + } + + #[test] + fn ref_missing_edge_is_error() { + let body = ":::ref{to=urn:atomic:intent:xyz}\n:::"; + assert!(lift_intent(&fm(), body).is_err()); + } + + /// Bidirectional closure over the whole directive registry: every name a + /// lift branches on is a known directive, and every registry directive is + /// handled by exactly one lift (the intent lift or the memory lift). This + /// keeps the closed vocabulary and the lifts from diverging — a new + /// directive with no lift, or a lift branch outside the registry, fails. + #[test] + fn every_lifted_directive_is_known() { + use crate::memory::LIFTED_MEMORY_DIRECTIVES; + + for name in LIFTED_INTENT_DIRECTIVES { + assert!( + vocab::is_known_directive(name), + "intent lift branches on '{name}' but it is not in the closed registry" + ); + } + for name in LIFTED_MEMORY_DIRECTIVES { + assert!( + vocab::is_known_directive(name), + "memory lift branches on '{name}' but it is not in the closed registry" + ); + } + // The two lift sets are disjoint (a directive belongs to one node type). + for name in LIFTED_MEMORY_DIRECTIVES { + assert!( + !LIFTED_INTENT_DIRECTIVES.contains(name), + "'{name}' is claimed by both the intent lift and the memory lift" + ); + } + // Every registry directive is handled by exactly one lift. + for name in vocab::DIRECTIVE_NAMES { + let intent = LIFTED_INTENT_DIRECTIVES.contains(name); + let memory = LIFTED_MEMORY_DIRECTIVES.contains(name); + assert!( + intent ^ memory, + "registry lists '{name}' but it is handled by {} lift(s), not exactly one", + intent as u8 + memory as u8 + ); + } + } +} diff --git a/atomic-canonical/src/memory.rs b/atomic-canonical/src/memory.rs new file mode 100644 index 00000000..65c00fbc --- /dev/null +++ b/atomic-canonical/src/memory.rs @@ -0,0 +1,308 @@ +//! The canonical Memory node — durable, reusable context (a constraint, a +//! preference, a lesson, or a piece of context) serialized as JSON-LD. +//! +//! Like [`crate::node::CanonicalNode`], a Memory is a *compile target*, not a +//! hand-authored artifact: [`lift_memory`] produces it from frontmatter + body. +//! It hashes and signs through the **same** single canonicalization path every +//! node type shares ([`crate::proof::signing_view`] / [`crate::proof::hashing_view`] +//! → [`crate::jcs`] → [`crate::hash`]), so a Memory's hash and signature can +//! never drift from an Intent's. +//! +//! ## Directionality (load-bearing) +//! A memory references its *inputs*, never its future uses. The only outward +//! edges are `about` (the modules/domains it is relevant to) and the revision +//! chain (`supersedes` / `previousRevision`). There is deliberately **no** +//! field for the intents that consume it — an intent names the memories that +//! informed it via `informedBy`; a memory never lists its consumers. That +//! absence is what lets memories stay stable while intents accrete around them. +//! +//! ## Single authoring site +//! The memory text has exactly one source. If the body contains a `:::memory` +//! container directive its body is authoritative and the surrounding prose is +//! ignored; only when no container is present does the whole trimmed body +//! become the text. The two are never concatenated, so the same fact can never +//! acquire two sites. + +use serde::{Deserialize, Serialize}; +use serde_json::{Map, Value}; + +use crate::error::{CanonicalError, Result}; +use crate::hash::content_hash; +use crate::jcs; +use crate::node::{Proof, CONTEXT_URL}; +use crate::vocab::NodeType; + +/// The exact set of directive names `lift_memory` consumes. The lift and the +/// closed-vocabulary closure test both read this const (as [`crate::lift`] does +/// for the intent lift) so the test cannot rot when the memory lift gains or +/// loses a branch. Every name here must be a member of +/// [`crate::vocab::DIRECTIVE_NAMES`]. +pub(crate) const LIFTED_MEMORY_DIRECTIVES: &[&str] = &["memory"]; + +/// The canonical Memory node (mirrors the doc's Memory example). +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct MemoryNode { + #[serde(rename = "@context")] + pub context: String, + #[serde(rename = "@type")] + pub type_: String, + #[serde(rename = "@id")] + pub id: String, + + #[serde(rename = "memoryKind")] + pub memory_kind: String, + /// The open, unconstrained memory body. Presence enforced by the gate; + /// content left honest (never graded). + pub text: String, + /// INPUT edges only — the modules/services/domains this memory is about. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub about: Vec, + pub status: String, + + // Revision chain (the only edges besides `about`). Omitted when absent so + // no empty JSON-LD keys leak into the hash. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub supersedes: Option, + #[serde(rename = "previousRevision", default, skip_serializing_if = "Option::is_none")] + pub previous_revision: Option, + + #[serde(rename = "contentHash", default, skip_serializing_if = "Option::is_none")] + pub content_hash: Option, + #[serde(rename = "attributedTo", default, skip_serializing_if = "Option::is_none")] + pub attributed_to: Option, + #[serde(rename = "createdAt")] + pub created_at: String, + + #[serde(default, skip_serializing_if = "Option::is_none")] + pub proof: Option, +} + +impl MemoryNode { + /// The node as a JSON value (JSON-LD object). + pub fn to_value(&self) -> Value { + serde_json::to_value(self).expect("memory node serialization is infallible") + } + + /// The value used for signing: everything except the `proof`. Delegates to + /// [`crate::proof::signing_view`] so the excluded key-set lives in one + /// place, shared by every node type. + pub fn signing_value(&self) -> Value { + crate::proof::signing_view(&self.to_value()) + } + + /// The value used for the content hash: excludes both `proof` and + /// `contentHash`. Delegates to [`crate::proof::hashing_view`]. + pub fn hashing_value(&self) -> Value { + crate::proof::hashing_view(&self.to_value()) + } + + /// Canonical bytes for signing (JCS of `signing_value`). + pub fn signing_bytes(&self) -> Vec { + jcs::canonicalize(&self.signing_value()).into_bytes() + } + + /// Recompute the content hash from the current node state. + pub fn compute_content_hash(&self) -> String { + content_hash(&self.hashing_value()) + } +} + +/// Lift a memory from its frontmatter spine and markdown body. +/// +/// `memoryKind`, `status`, `about`, `supersedes`, and `previousRevision` are +/// read from the frontmatter. The text is lifted from the FIRST `:::memory` +/// container directive if present (single authoring site), else falls back to +/// the whole trimmed body. +pub fn lift_memory(frontmatter: &Map, body: &str) -> Result { + let uid = opt_str(frontmatter, "uid") + .or_else(|| opt_str(frontmatter, "id")) + .ok_or_else(|| CanonicalError::Lift("memory frontmatter missing 'uid' (or 'id')".into()))?; + let node_id = as_memory_urn(&uid); + + let memory_kind = require_str(frontmatter, "memoryKind") + .or_else(|_| require_str(frontmatter, "kind"))?; + let status = + opt_str(frontmatter, "status").unwrap_or_else(|| "active".to_string()); + + // Single authoring site: the first `:::memory` container's body is + // authoritative; the surrounding prose is ignored. Only when no container + // is present does the whole trimmed body become the text — never both. + // + // The memory text is OPEN prose (presence enforced, content honest), so we + // must NOT run it through the closed-vocabulary directive parser: a body + // that legitimately begins a line with `::` (a Rust turbofish `::`, or + // prose discussing `:::why`) is valid memory content, not a directive + // error. We do a lenient fence scan instead, which never rejects. + let text = extract_memory_container(body).unwrap_or_else(|| body.trim().to_string()); + + Ok(MemoryNode { + context: CONTEXT_URL.to_string(), + type_: NodeType::Memory.as_str().to_string(), + id: node_id, + memory_kind, + text, + about: str_array(frontmatter, "about"), + status, + supersedes: opt_str(frontmatter, "supersedes"), + previous_revision: opt_str(frontmatter, "previousRevision"), + content_hash: None, + attributed_to: opt_str(frontmatter, "attributedTo"), + created_at: opt_str(frontmatter, "createdAt") + .or_else(|| opt_str(frontmatter, "created_at")) + .unwrap_or_default(), + proof: None, + }) +} + +/// Lenient scan for a single `:::memory` container fence, returning its inner +/// body if present. Unlike the closed-vocabulary [`crate::directive`] parser, +/// this never errors on unrelated `::`/`:::` tokens in the open memory prose — +/// only a recognized fence (a name in [`LIFTED_MEMORY_DIRECTIVES`]) is treated +/// as structure; everything else is content. An unterminated fence falls back +/// to the whole body (fail-open, preserving content). +fn extract_memory_container(body: &str) -> Option { + let lines: Vec<&str> = body.lines().collect(); + let mut i = 0; + while i < lines.len() { + if let Some(name) = container_open_name(lines[i].trim_start()) { + if LIFTED_MEMORY_DIRECTIVES.contains(&name) { + let mut collected: Vec<&str> = Vec::new(); + i += 1; + while i < lines.len() { + if lines[i].trim() == ":::" { + return Some(collected.join("\n").trim().to_string()); + } + collected.push(lines[i]); + i += 1; + } + return None; // unterminated → fall back to whole body + } + } + i += 1; + } + None +} + +/// If `line` opens a container directive (`:::name` optionally with `{...}`), +/// return the directive name. A bare `:::` (a close) yields `None`. +fn container_open_name(line: &str) -> Option<&str> { + let rest = line.strip_prefix(":::")?; + let end = rest + .find(|c: char| c == '{' || c.is_whitespace()) + .unwrap_or(rest.len()); + let name = &rest[..end]; + if name.is_empty() { + None + } else { + Some(name) + } +} + +/// Wrap a local id into `urn:atomic:memory:` unless already a urn. +fn as_memory_urn(local: &str) -> String { + if local.starts_with("urn:atomic:") { + local.to_string() + } else { + format!("urn:atomic:memory:{local}") + } +} + +fn require_str(fm: &Map, key: &str) -> Result { + opt_str(fm, key).ok_or_else(|| CanonicalError::Lift(format!("memory frontmatter missing '{key}'"))) +} + +fn opt_str(fm: &Map, key: &str) -> Option { + match fm.get(key) { + Some(Value::String(s)) if !s.is_empty() => Some(s.clone()), + Some(Value::Number(n)) => Some(n.to_string()), + _ => None, + } +} + +fn str_array(fm: &Map, key: &str) -> Vec { + match fm.get(key) { + Some(Value::Array(items)) => items + .iter() + .filter_map(|v| v.as_str().map(str::to_string)) + .collect(), + Some(Value::String(s)) if !s.is_empty() => s + .split(',') + .map(|p| p.trim().to_string()) + .filter(|p| !p.is_empty()) + .collect(), + _ => Vec::new(), + } +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + + fn fm() -> Map { + json!({ + "uid": "01J8ZC4R8T", + "memoryKind": "constraint", + "status": "active", + "about": ["urn:atomic:module:storage", "urn:atomic:module:replication"] + }) + .as_object() + .unwrap() + .clone() + } + + #[test] + fn lift_memory_from_frontmatter_and_body() { + let body = "Multi-region writes must converge with no single ordering authority."; + let node = lift_memory(&fm(), body).unwrap(); + assert_eq!(node.type_, "Memory"); + assert_eq!(node.id, "urn:atomic:memory:01J8ZC4R8T"); + assert_eq!(node.memory_kind, "constraint"); + assert_eq!(node.status, "active"); + assert_eq!( + node.about, + vec![ + "urn:atomic:module:storage".to_string(), + "urn:atomic:module:replication".to_string() + ] + ); + assert!(node.text.contains("no single ordering authority")); + } + + #[test] + fn lift_memory_prefers_memory_container() { + // With a :::memory container, its body is authoritative and the + // surrounding prose is ignored (single authoring site). + let body = "\ +ignored surrounding prose + +:::memory{} +The constraint text that is authoritative. +::: + +more ignored prose"; + let node = lift_memory(&fm(), body).unwrap(); + assert_eq!(node.text, "The constraint text that is authoritative."); + assert!(!node.text.contains("ignored")); + + // Without a container, the whole trimmed body is the text. + let plain = lift_memory(&fm(), " just a plain body ").unwrap(); + assert_eq!(plain.text, "just a plain body"); + } + + #[test] + fn lift_memory_accepts_kind_alias_and_defaults_status() { + let mut m = json!({ "uid": "abc", "kind": "lesson" }) + .as_object() + .unwrap() + .clone(); + let node = lift_memory(&m, "a lesson").unwrap(); + assert_eq!(node.memory_kind, "lesson"); + assert_eq!(node.status, "active"); // defaulted when absent + + // Missing kind entirely is a lift error. + m.remove("kind"); + assert!(lift_memory(&m, "x").is_err()); + } +} diff --git a/atomic-canonical/src/node.rs b/atomic-canonical/src/node.rs index c9d29d00..c81dad13 100644 --- a/atomic-canonical/src/node.rs +++ b/atomic-canonical/src/node.rs @@ -17,6 +17,7 @@ pub const CONTEXT_URL: &str = "https://atomic.dev/ns/ctx.jsonld"; /// A single acceptance criterion, lifted from a `:::acceptance-criterion` directive. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] pub struct AcceptanceCriterion { #[serde(rename = "@type")] pub type_: String, @@ -25,14 +26,54 @@ pub struct AcceptanceCriterion { pub text: String, #[serde(rename = "acStatus")] pub ac_status: String, - #[serde(rename = "verifiedBy", skip_serializing_if = "Option::is_none")] + #[serde(rename = "verifiedBy", default, skip_serializing_if = "Option::is_none")] pub verified_by: Option, - #[serde(skip_serializing_if = "Option::is_none")] + #[serde(default, skip_serializing_if = "Option::is_none")] pub evidence: Option, } +/// A scope boundary item, lifted from a `:::scope-in` / `:::scope-out` +/// directive. The prose is the unconstrained narrative; the gate enforces +/// presence, never content. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct ScopeItem { + #[serde(rename = "@type")] + pub type_: String, + #[serde(rename = "@id")] + pub id: String, + pub text: String, +} + +/// A constraint the implementation must respect, lifted from a `:::constraint` +/// directive. Prose body; typed so the graph knows how many there are. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct Constraint { + #[serde(rename = "@type")] + pub type_: String, + #[serde(rename = "@id")] + pub id: String, + pub text: String, +} + +/// A typed dependency edge leaf, lifted from a `:::ref{to= edge=}` directive. +/// `@type`/`@id` are omitted when absent (the doc's `:::ref` carries only +/// `to`/`edge`), so no empty JSON-LD keys leak into the hash. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct Ref { + #[serde(rename = "@type", default, skip_serializing_if = "Option::is_none")] + pub type_: Option, + #[serde(rename = "@id", default, skip_serializing_if = "Option::is_none")] + pub id: Option, + pub to: String, + pub edge: String, +} + /// A decomposed task, lifted from a `:::task` directive. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] pub struct Task { #[serde(rename = "@type")] pub type_: String, @@ -41,14 +82,15 @@ pub struct Task { pub text: String, #[serde(rename = "taskStatus")] pub task_status: String, - #[serde(rename = "touchesFile", skip_serializing_if = "Vec::is_empty")] + #[serde(rename = "touchesFile", default, skip_serializing_if = "Vec::is_empty")] pub touches_file: Vec, - #[serde(skip_serializing_if = "Option::is_none")] + #[serde(default, skip_serializing_if = "Option::is_none")] pub satisfies: Option, } /// A Data Integrity proof (`eddsa-jcs-2022`). #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] pub struct Proof { #[serde(rename = "@type")] pub type_: String, @@ -63,6 +105,7 @@ pub struct Proof { /// The canonical Intent node. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] pub struct CanonicalNode { #[serde(rename = "@context")] pub context: String, @@ -76,33 +119,52 @@ pub struct CanonicalNode { pub human_key: String, pub title: String, pub status: String, - #[serde(skip_serializing_if = "Option::is_none")] + // Every field that is omitted when empty carries `default` so the + // serde round trip (`to_value` → `from_value`) the typed attest/verify + // wrappers rely on is symmetric: an omitted key deserializes back to its + // empty value rather than erroring on a "missing field". + #[serde(default, skip_serializing_if = "Option::is_none")] pub priority: Option, - #[serde(skip_serializing_if = "Option::is_none")] + #[serde(default, skip_serializing_if = "Option::is_none")] pub view: Option, - #[serde(rename = "motivatedBy", skip_serializing_if = "Option::is_none")] + #[serde(rename = "motivatedBy", default, skip_serializing_if = "Option::is_none")] pub motivated_by: Option, - #[serde(rename = "informedBy", skip_serializing_if = "Vec::is_empty")] + #[serde(rename = "informedBy", default, skip_serializing_if = "Vec::is_empty")] pub informed_by: Vec, - #[serde(rename = "hasAcceptanceCriterion", skip_serializing_if = "Vec::is_empty")] + #[serde( + rename = "hasAcceptanceCriterion", + default, + skip_serializing_if = "Vec::is_empty" + )] pub has_acceptance_criterion: Vec, - #[serde(rename = "hasTask", skip_serializing_if = "Vec::is_empty")] + #[serde(rename = "hasTask", default, skip_serializing_if = "Vec::is_empty")] pub has_task: Vec, + // Collection sub-nodes. Empty collections are omitted (skip_serializing_if), + // so adding these fields does NOT change the hash of existing fixtures. + #[serde(rename = "hasScopeIn", default, skip_serializing_if = "Vec::is_empty")] + pub has_scope_in: Vec, + #[serde(rename = "hasScopeOut", default, skip_serializing_if = "Vec::is_empty")] + pub has_scope_out: Vec, + #[serde(rename = "hasConstraint", default, skip_serializing_if = "Vec::is_empty")] + pub has_constraint: Vec, + #[serde(rename = "dependsOn", default, skip_serializing_if = "Vec::is_empty")] + pub depends_on: Vec, + /// The unconstrained reason. Presence enforced by the gate; content honest. - #[serde(skip_serializing_if = "Option::is_none")] + #[serde(default, skip_serializing_if = "Option::is_none")] pub why: Option, - #[serde(rename = "contentHash", skip_serializing_if = "Option::is_none")] + #[serde(rename = "contentHash", default, skip_serializing_if = "Option::is_none")] pub content_hash: Option, - #[serde(rename = "attributedTo", skip_serializing_if = "Option::is_none")] + #[serde(rename = "attributedTo", default, skip_serializing_if = "Option::is_none")] pub attributed_to: Option, #[serde(rename = "createdAt")] pub created_at: String, - #[serde(skip_serializing_if = "Option::is_none")] + #[serde(default, skip_serializing_if = "Option::is_none")] pub proof: Option, } @@ -112,25 +174,17 @@ impl CanonicalNode { serde_json::to_value(self).expect("canonical node serialization is infallible") } - /// The value used for signing: everything except the `proof` (a Data - /// Integrity signature covers the document minus the proof). `contentHash` - /// is included so the signature also commits to the hash. + /// The value used for signing: everything except the `proof`. Delegates to + /// [`crate::proof::signing_view`] so the excluded key-set is defined once, + /// at the Value level, shared by every node type. pub fn signing_value(&self) -> serde_json::Value { - let mut value = self.to_value(); - if let Some(obj) = value.as_object_mut() { - obj.remove("proof"); - } - value + crate::proof::signing_view(&self.to_value()) } /// The value used for the content hash: excludes both `proof` and - /// `contentHash` (you cannot hash the hash). + /// `contentHash`. Delegates to [`crate::proof::hashing_view`]. pub fn hashing_value(&self) -> serde_json::Value { - let mut value = self.signing_value(); - if let Some(obj) = value.as_object_mut() { - obj.remove("contentHash"); - } - value + crate::proof::hashing_view(&self.to_value()) } /// Canonical bytes for signing (JCS of `signing_value`). diff --git a/atomic-canonical/src/proof.rs b/atomic-canonical/src/proof.rs index a878f107..34c18424 100644 --- a/atomic-canonical/src/proof.rs +++ b/atomic-canonical/src/proof.rs @@ -13,9 +13,13 @@ use atomic_identity::identity::Identity; use atomic_identity::keypair::{KeyPair, PublicKey}; use atomic_identity::signing::{Signature, Signer}; +use serde_json::Value; use crate::did; use crate::error::{CanonicalError, Result}; +use crate::hash; +use crate::jcs; +use crate::memory::MemoryNode; use crate::node::{CanonicalNode, Proof}; pub const CRYPTOSUITE: &str = "eddsa-jcs-2022"; @@ -24,55 +28,125 @@ pub const PROOF_PURPOSE: &str = "assertionMethod"; /// Multibase prefix for base32-upper, no padding. const MULTIBASE_BASE32_UPPER: char = 'B'; -/// Produce a fully attested node: fill `attributedTo` (from the identity's -/// `did:atomic`), compute the content hash, sign, and attach the proof. -pub fn attest(mut node: CanonicalNode, identity: &Identity, keypair: &KeyPair) -> CanonicalNode { - let did = did::did_for_public_key(&identity.public_key); - if node.attributed_to.is_none() { - node.attributed_to = Some(did.clone()); +/// Canonical property names. Hardcoded because the closed vocabulary +/// standardizes them across *all* node types (Intent, Memory, and any future +/// PROV `@graph`), so the "which keys are excluded from signing/hashing" rule +/// has exactly one owner — these consts and the two views below. +pub const PROP_PROOF: &str = "proof"; +pub const PROP_CONTENT_HASH: &str = "contentHash"; +pub const PROP_ATTRIBUTED_TO: &str = "attributedTo"; + +/// The value covered by a signature: the document minus its `proof` (the +/// standard Data Integrity shape). `contentHash` is retained so the signature +/// also commits to the hash. This is the single site that owns the exclusion. +pub fn signing_view(value: &Value) -> Value { + let mut value = value.clone(); + if let Some(obj) = value.as_object_mut() { + obj.remove(PROP_PROOF); } + value +} - // Hash first (over node without proof/contentHash), then sign (over node - // with contentHash, without proof). - node.content_hash = Some(node.compute_content_hash()); +/// The value covered by the content hash: excludes both `proof` and +/// `contentHash` (you cannot hash the hash). +pub fn hashing_view(value: &Value) -> Value { + let mut value = signing_view(value); + if let Some(obj) = value.as_object_mut() { + obj.remove(PROP_CONTENT_HASH); + } + value +} - let signature = Signer::new(keypair).sign(&node.signing_bytes()); - let proof_value = encode_proof_value(&signature); +/// Generic attest over a JSON-LD value — the *one* canonicalization/signing +/// path all typed nodes share. Fills `attributedTo` (from the identity's +/// `did:atomic`) when absent, computes the content hash over `hashing_view`, +/// signs `jcs(signing_view)`, and attaches the proof. Returns the value. +pub fn attest_value(mut value: Value, identity: &Identity, keypair: &KeyPair) -> Value { + let did = did::did_for_public_key(&identity.public_key); + + if let Some(obj) = value.as_object_mut() { + // Fill attributedTo only if there is no non-empty value already. + let has_author = obj + .get(PROP_ATTRIBUTED_TO) + .and_then(Value::as_str) + .map(|s| !s.is_empty()) + .unwrap_or(false); + if !has_author { + obj.insert(PROP_ATTRIBUTED_TO.to_string(), Value::String(did.clone())); + } + } + + // Hash first (over the value without proof/contentHash), then sign (over + // the value with contentHash, without proof). + let content_hash = hash::content_hash(&hashing_view(&value)); + if let Some(obj) = value.as_object_mut() { + obj.insert(PROP_CONTENT_HASH.to_string(), Value::String(content_hash)); + } - node.proof = Some(Proof { + let signing_bytes = jcs::canonicalize(&signing_view(&value)).into_bytes(); + let signature = Signer::new(keypair).sign(&signing_bytes); + let proof = Proof { type_: PROOF_TYPE.to_string(), cryptosuite: CRYPTOSUITE.to_string(), verification_method: did::verification_method(&did), proof_purpose: PROOF_PURPOSE.to_string(), - proof_value, - }); - node + proof_value: encode_proof_value(&signature), + }; + if let Some(obj) = value.as_object_mut() { + obj.insert( + PROP_PROOF.to_string(), + serde_json::to_value(proof).expect("proof serialization is infallible"), + ); + } + value } -/// Verify an attested node against a public key: the content hash must -/// recompute, and the signature must verify over the canonical signing bytes. -pub fn verify(node: &CanonicalNode, public_key: &PublicKey) -> Result<()> { +/// Generic verify over a JSON-LD value — the same three checks as the typed +/// path: (1) the content hash recomputes over `hashing_view`, (2) the signature +/// verifies over `jcs(signing_view)`, (3) the proof's verificationMethod DID +/// belongs to this key. +pub fn verify_value(value: &Value, public_key: &PublicKey) -> Result<()> { + let obj = value + .as_object() + .ok_or_else(|| CanonicalError::Proof("value is not a JSON object".into()))?; + // 1. Content hash integrity. - let expected = node - .content_hash - .as_ref() + let expected = obj + .get(PROP_CONTENT_HASH) + .and_then(Value::as_str) .ok_or_else(|| CanonicalError::Proof("node carries no contentHash".into()))?; - let actual = node.compute_content_hash(); - if *expected != actual { + let actual = hash::content_hash(&hashing_view(value)); + if expected != actual { return Err(CanonicalError::HashMismatch { - expected: expected.clone(), + expected: expected.to_string(), actual, }); } // 2. Signature over the canonical signing bytes. - let proof = node - .proof - .as_ref() + let proof: Proof = obj + .get(PROP_PROOF) + .cloned() + .and_then(|p| serde_json::from_value(p).ok()) .ok_or_else(|| CanonicalError::Proof("node carries no proof".into()))?; + + // The proof's own metadata is stripped by `signing_view`, so it is not + // covered by the signature. Enforce the suite/purpose/type we expect here, + // otherwise a stored node's declared cryptosuite is silently mutable. + if proof.type_ != PROOF_TYPE + || proof.cryptosuite != CRYPTOSUITE + || proof.proof_purpose != PROOF_PURPOSE + { + return Err(CanonicalError::Verification(format!( + "unexpected proof metadata: type='{}' cryptosuite='{}' proofPurpose='{}'", + proof.type_, proof.cryptosuite, proof.proof_purpose + ))); + } + let signature = decode_proof_value(&proof.proof_value)?; + let signing_bytes = jcs::canonicalize(&signing_view(value)).into_bytes(); signature - .verify(&node.signing_bytes(), public_key) + .verify(&signing_bytes, public_key) .map_err(|e| CanonicalError::Verification(e.to_string()))?; // 3. The proof's verificationMethod DID must belong to this key. @@ -85,6 +159,33 @@ pub fn verify(node: &CanonicalNode, public_key: &PublicKey) -> Result<()> { Ok(()) } +/// Produce a fully attested Intent node — a thin wrapper over +/// [`attest_value`] so hash and signature can never drift from any other node +/// type. The round trip through serde is lossless for an already-constructed +/// node (all fields are symmetric), so `from_value` cannot fail. +pub fn attest(node: CanonicalNode, identity: &Identity, keypair: &KeyPair) -> CanonicalNode { + let value = attest_value(node.to_value(), identity, keypair); + serde_json::from_value(value).expect("attested intent re-deserializes") +} + +/// Verify an attested Intent node — thin wrapper over [`verify_value`]. +pub fn verify(node: &CanonicalNode, public_key: &PublicKey) -> Result<()> { + verify_value(&node.to_value(), public_key) +} + +/// Produce a fully attested Memory node — the same thin wrapper over +/// [`attest_value`] the Intent path uses, so both node types sign through one +/// canonicalization path and their hashes/signatures cannot drift. +pub fn attest_memory(node: MemoryNode, identity: &Identity, keypair: &KeyPair) -> MemoryNode { + let value = attest_value(node.to_value(), identity, keypair); + serde_json::from_value(value).expect("attested memory re-deserializes") +} + +/// Verify an attested Memory node — thin wrapper over [`verify_value`]. +pub fn verify_memory(node: &MemoryNode, public_key: &PublicKey) -> Result<()> { + verify_value(&node.to_value(), public_key) +} + fn encode_proof_value(signature: &Signature) -> String { let mut s = String::new(); s.push(MULTIBASE_BASE32_UPPER); @@ -108,3 +209,94 @@ fn decode_proof_value(value: &str) -> Result { .map_err(|e| CanonicalError::Proof(format!("bad base32 proofValue: {e}")))?; Signature::from_slice(&bytes).map_err(|e| CanonicalError::Proof(e.to_string())) } + +#[cfg(test)] +mod tests { + use super::*; + use crate::node::CONTEXT_URL; + use serde_json::json; + + fn dev_identity() -> (Identity, KeyPair) { + let kp = KeyPair::generate(); + let id = Identity::new("lee", &kp); + (id, kp) + } + + fn minimal_value() -> Value { + json!({ + "@context": CONTEXT_URL, + "@type": "Intent", + "@id": "urn:atomic:intent:generic-1", + "title": "A generic value node", + "status": "todo" + }) + } + + #[test] + fn attest_value_then_verify_value_roundtrips() { + let (id, kp) = dev_identity(); + let attested = attest_value(minimal_value(), &id, &kp); + + // The generic path filled the excluded-later fields. + let obj = attested.as_object().unwrap(); + assert!(obj.get(PROP_CONTENT_HASH).unwrap().as_str().unwrap().starts_with("blake3:")); + assert!(obj.get(PROP_PROOF).is_some()); + assert!(obj.get(PROP_ATTRIBUTED_TO).unwrap().as_str().unwrap().starts_with("did:atomic:")); + + // Verifies with the right key, independent of CanonicalNode. + verify_value(&attested, &kp.public).expect("generic verify should succeed"); + + // Tamper a signed field → the stored contentHash no longer matches. + let mut tampered = attested.clone(); + tampered.as_object_mut().unwrap().insert("status".into(), Value::String("done".into())); + let err = verify_value(&tampered, &kp.public).unwrap_err(); + assert!( + matches!(err, CanonicalError::HashMismatch { .. }), + "expected HashMismatch, got {err:?}" + ); + + // Wrong key → verification error. + let other = KeyPair::generate(); + assert!(verify_value(&attested, &other.public).is_err()); + } + + #[test] + fn typed_wrapper_matches_value_core() { + let (id, kp) = dev_identity(); + let node = CanonicalNode { + context: CONTEXT_URL.to_string(), + type_: "Intent".to_string(), + id: "urn:atomic:intent:wrapper-1".to_string(), + human_key: "W-1".to_string(), + title: "Wrapper equivalence".to_string(), + status: "todo".to_string(), + priority: None, + view: None, + motivated_by: None, + informed_by: Vec::new(), + has_acceptance_criterion: Vec::new(), + has_task: Vec::new(), + has_scope_in: Vec::new(), + has_scope_out: Vec::new(), + has_constraint: Vec::new(), + depends_on: Vec::new(), + why: Some("a reason".to_string()), + content_hash: None, + attributed_to: None, + created_at: "2026-06-25T00:00:00Z".to_string(), + proof: None, + }; + + // The typed wrapper must add nothing over the value core: attesting the + // node equals from_value(attest_value(node.to_value())). + let via_wrapper = attest(node.clone(), &id, &kp); + let via_core: CanonicalNode = + serde_json::from_value(attest_value(node.to_value(), &id, &kp)).unwrap(); + + assert_eq!(via_wrapper.content_hash, via_core.content_hash); + assert_eq!( + via_wrapper.proof.as_ref().map(|p| &p.proof_value), + via_core.proof.as_ref().map(|p| &p.proof_value) + ); + } +} diff --git a/atomic-canonical/src/render.rs b/atomic-canonical/src/render.rs index a51a8018..307da899 100644 --- a/atomic-canonical/src/render.rs +++ b/atomic-canonical/src/render.rs @@ -9,6 +9,7 @@ //! reference-at-render resolution arrive in a later milestone; the `Target` //! enum leaves room for them. +use crate::memory::MemoryNode; use crate::node::CanonicalNode; /// Render output target. Only `Cli` is implemented in M0. @@ -17,13 +18,25 @@ pub enum Target { Cli, } -/// Project a canonical node to a rendered string for the given target. +/// Project a canonical Intent node to a rendered string for the given target. pub fn render(node: &CanonicalNode, target: Target) -> String { match target { Target::Cli => render_cli(node), } } +/// Project a canonical Memory node to a rendered string. Kept as a separate +/// entry (rather than a `Target::Memory` variant) so each `render*` stays typed +/// to the node it can actually hold — `render` cannot receive a Memory it has +/// no fields for, and this cannot receive an Intent. Same pure-projection +/// contract: no second authoring site, and the status line is regenerated from +/// the spine. +pub fn render_memory(node: &MemoryNode, target: Target) -> String { + match target { + Target::Cli => render_memory_cli(node), + } +} + fn render_cli(node: &CanonicalNode) -> String { let mut s = String::new(); @@ -80,6 +93,88 @@ fn render_cli(node: &CanonicalNode) -> String { } } + // Scope — a pure projection of the scope sub-nodes; no new authoring site. + if !node.has_scope_in.is_empty() { + s.push_str("\nIn Scope\n"); + for item in &node.has_scope_in { + s.push_str(&format!(" • {}\n", item.text)); + } + } + if !node.has_scope_out.is_empty() { + s.push_str("\nOut of Scope\n"); + for item in &node.has_scope_out { + s.push_str(&format!(" • {}\n", item.text)); + } + } + + // Constraints — the checklist the doc describes (numbered). + if !node.has_constraint.is_empty() { + s.push_str("\nConstraints\n"); + for (i, c) in node.has_constraint.iter().enumerate() { + s.push_str(&format!(" {}. {}\n", i + 1, c.text)); + } + } + + // Dependencies — each ref rendered as 'edge -> to'. + if !node.depends_on.is_empty() { + s.push_str("\nDependencies\n"); + for r in &node.depends_on { + s.push_str(&format!(" {} -> {}\n", r.edge, r.to)); + } + } + + // Provenance footer. + s.push('\n'); + s.push_str(&format!("id: {}\n", node.id)); + if let Some(a) = &node.attributed_to { + s.push_str(&format!("author: {a}\n")); + } + if let Some(h) = &node.content_hash { + s.push_str(&format!("hash: {h}\n")); + } + s.push_str(&format!( + "signed: {}\n", + if node.proof.is_some() { "yes" } else { "no" } + )); + + s +} + +fn render_memory_cli(node: &MemoryNode) -> String { + let mut s = String::new(); + + // Header: memory kind + @id. + s.push_str(&format!("Memory ({}) {}\n", node.memory_kind, node.id)); + s.push_str(&"─".repeat(48)); + s.push('\n'); + + // Status is REGENERATED here from the spine, never read from prose. + s.push_str(&format!("Status: {}\n", node.status)); + + // About — the INPUT edges (modules/domains this memory is relevant to). + if !node.about.is_empty() { + s.push_str("\nAbout\n"); + for a in &node.about { + s.push_str(&format!(" • {a}\n")); + } + } + + // Revision chain (only if present). + if node.supersedes.is_some() || node.previous_revision.is_some() { + s.push_str("\nRevision\n"); + if let Some(sup) = &node.supersedes { + s.push_str(&format!(" supersedes: {sup}\n")); + } + if let Some(prev) = &node.previous_revision { + s.push_str(&format!(" previousRevision: {prev}\n")); + } + } + + // The open text body (never graded). + s.push('\n'); + s.push_str(&node.text); + s.push('\n'); + // Provenance footer. s.push('\n'); s.push_str(&format!("id: {}\n", node.id)); @@ -96,3 +191,104 @@ fn render_cli(node: &CanonicalNode) -> String { s } + +#[cfg(test)] +mod tests { + use super::*; + use crate::node::{Constraint, Ref, ScopeItem, CONTEXT_URL}; + use crate::vocab::NodeType; + + fn scope(id: &str, text: &str) -> ScopeItem { + ScopeItem { + type_: NodeType::ScopeItem.as_str().to_string(), + id: id.to_string(), + text: text.to_string(), + } + } + + #[test] + fn render_includes_scope_and_constraints() { + let node = CanonicalNode { + context: CONTEXT_URL.to_string(), + type_: NodeType::Intent.as_str().to_string(), + id: "urn:atomic:intent:render-1".to_string(), + human_key: "R-1".to_string(), + title: "Render".to_string(), + status: "todo".to_string(), + priority: None, + view: None, + motivated_by: None, + informed_by: Vec::new(), + has_acceptance_criterion: Vec::new(), + has_task: Vec::new(), + has_scope_in: vec![scope("urn:atomic:scope:r-1-scope-in-1", "the modal markup")], + has_scope_out: vec![scope( + "urn:atomic:scope:r-1-scope-out-1", + "persisting across reloads", + )], + has_constraint: vec![ + Constraint { + type_: NodeType::Constraint.as_str().to_string(), + id: "urn:atomic:constraint:r-1-constraint-1".to_string(), + text: "keep it local".to_string(), + }, + Constraint { + type_: NodeType::Constraint.as_str().to_string(), + id: "urn:atomic:constraint:r-1-constraint-2".to_string(), + text: "do not touch the keyboard handler".to_string(), + }, + ], + depends_on: vec![Ref { + type_: None, + id: None, + to: "urn:atomic:intent:xyz".to_string(), + edge: "blockedBy".to_string(), + }], + why: Some("a reason".to_string()), + content_hash: None, + attributed_to: None, + created_at: "2026-06-25T00:00:00Z".to_string(), + proof: None, + }; + + let text = render(&node, Target::Cli); + assert!(text.contains("Out of Scope"), "render:\n{text}"); + assert!(text.contains("persisting across reloads")); + assert!(text.contains("keep it local")); + assert!(text.contains("do not touch the keyboard handler")); + // Dependency rendered as 'edge -> to'. + assert!(text.contains("blockedBy")); + assert!(text.contains("blockedBy -> urn:atomic:intent:xyz")); + } + + #[test] + fn render_memory_regenerates_status_from_spine() { + let node = MemoryNode { + context: CONTEXT_URL.to_string(), + type_: NodeType::Memory.as_str().to_string(), + id: "urn:atomic:memory:render-1".to_string(), + memory_kind: "constraint".to_string(), + text: "no single ordering authority for multi-region writes".to_string(), + about: vec![ + "urn:atomic:module:storage".to_string(), + "urn:atomic:module:replication".to_string(), + ], + status: "active".to_string(), + supersedes: None, + previous_revision: None, + content_hash: None, + attributed_to: None, + created_at: "2026-05-02T09:14:00Z".to_string(), + proof: None, + }; + + let text = render_memory(&node, Target::Cli); + // Status regenerated from the spine. + assert!(text.contains("Status: active"), "render:\n{text}"); + // Kind + about entries + the text body all project. + assert!(text.contains("constraint")); + assert!(text.contains("urn:atomic:module:storage")); + assert!(text.contains("urn:atomic:module:replication")); + assert!(text.contains("no single ordering authority for multi-region writes")); + } +} diff --git a/atomic-canonical/src/vocab.rs b/atomic-canonical/src/vocab.rs index 61c35930..415d2b32 100644 --- a/atomic-canonical/src/vocab.rs +++ b/atomic-canonical/src/vocab.rs @@ -17,6 +17,10 @@ pub enum NodeType { Intent, AcceptanceCriterion, Task, + ScopeItem, + Constraint, + Ref, + Memory, } impl NodeType { @@ -25,6 +29,10 @@ impl NodeType { NodeType::Intent => "Intent", NodeType::AcceptanceCriterion => "AcceptanceCriterion", NodeType::Task => "Task", + NodeType::ScopeItem => "ScopeItem", + NodeType::Constraint => "Constraint", + NodeType::Ref => "Ref", + NodeType::Memory => "Memory", } } } @@ -37,6 +45,9 @@ pub const AC_STATUS: &[&str] = &["open", "met"]; /// Directive names recognized by the parser + lift (closed set). /// Container directives wrap prose; leaf directives carry only edges. +/// +/// NOTE: `lift.rs` must only branch on these names. A directive name not in +/// this list is a parse/gate error, never a new type the lift absorbs. pub const DIRECTIVE_NAMES: &[&str] = &[ "why", // container: the unconstrained reason (presence enforced, content honest) "acceptance-criterion", // container @@ -46,8 +57,15 @@ pub const DIRECTIVE_NAMES: &[&str] = &[ "constraint", // container "ref", // leaf: a typed dependency edge "file-ref", // leaf: a file the task touches + "memory", // container: carries a memory's body text ]; +/// Memory kinds (closed set; mirrors `MemoryShape` `sh:in`). Exactly one. +pub const MEMORY_KIND: &[&str] = &["constraint", "preference", "lesson", "context"]; + +/// Memory status value set (closed; mirrors `MemoryShape` `sh:in`). Exactly one. +pub const MEMORY_STATUS: &[&str] = &["active", "superseded", "retracted"]; + /// Edge (property) names that carry typed references between nodes. pub const EDGE_NAMES: &[&str] = &[ "motivatedBy", @@ -69,6 +87,24 @@ pub fn is_known_directive(name: &str) -> bool { DIRECTIVE_NAMES.contains(&name) } +/// The subset of edges a `:::ref` dependency may declare. A `:::ref` names a +/// *dependency* on the traversable dependency chain, so its `edge=` is +/// restricted to these — not the full [`EDGE_NAMES`] set (a `:::ref` claiming +/// `edge=verifiedBy` or `edge=about` would put a semantically bogus edge on the +/// dependency chain the gate keeps traversable). +pub const DEPENDENCY_EDGES: &[&str] = &["depends", "blockedBy"]; + +/// Is this a typed edge name the system recognizes at all? +pub fn is_known_edge(name: &str) -> bool { + EDGE_NAMES.contains(&name) +} + +/// Is this a valid `:::ref` dependency edge? The lift validates `edge=` against +/// this subset — an out-of-subset (even if otherwise known) edge is a lift error. +pub fn is_known_dependency_edge(name: &str) -> bool { + DEPENDENCY_EDGES.contains(&name) +} + /// Is this a valid intent status value? pub fn is_known_intent_status(value: &str) -> bool { INTENT_STATUS.contains(&value) @@ -78,3 +114,13 @@ pub fn is_known_intent_status(value: &str) -> bool { pub fn is_known_ac_status(value: &str) -> bool { AC_STATUS.contains(&value) } + +/// Is this a valid memory kind? Unknown ⇒ gate error (closed vocabulary). +pub fn is_known_memory_kind(value: &str) -> bool { + MEMORY_KIND.contains(&value) +} + +/// Is this a valid memory status value? Unknown ⇒ gate error. +pub fn is_known_memory_status(value: &str) -> bool { + MEMORY_STATUS.contains(&value) +} diff --git a/atomic-canonical/tests/roundtrip.rs b/atomic-canonical/tests/roundtrip.rs index cd9e3468..2b038372 100644 --- a/atomic-canonical/tests/roundtrip.rs +++ b/atomic-canonical/tests/roundtrip.rs @@ -2,7 +2,11 @@ //! gate → render, entirely in-crate (no vault wiring). use atomic_canonical::lift::{lift_intent, parse_markdown}; -use atomic_canonical::{lift_and_attest, render, validate_intent, verify, Target}; +use atomic_canonical::memory::lift_memory; +use atomic_canonical::{ + lift_and_attest, lift_and_attest_memory, render, render_memory, validate_intent, + validate_memory, verify, verify_memory, Target, +}; use atomic_identity::identity::Identity; use atomic_identity::keypair::KeyPair; use serde_json::{json, Map, Value}; @@ -147,6 +151,154 @@ fn wrong_key_fails_verification() { assert!(verify(&node, &other.public).is_err()); } +#[test] +fn empty_new_collections_do_not_appear_in_canonical_form() { + // Regression guard for the hash-safety of the added Vec fields: the WORD-5 + // fixture declares no scope/constraint/ref, so those keys must be OMITTED + // from the canonical value (skip_serializing_if = Vec::is_empty). If any + // leaked as an empty array it would silently change the contentHash and + // break the existing signature tests. + let node = lift_intent(&frontmatter(), BODY).unwrap(); + let value = node.to_value(); + let obj = value.as_object().unwrap(); + assert!(!obj.contains_key("hasScopeIn")); + assert!(!obj.contains_key("hasScopeOut")); + assert!(!obj.contains_key("hasConstraint")); + assert!(!obj.contains_key("dependsOn")); +} + +#[test] +fn lifts_scope_constraints_and_ref_end_to_end() { + use atomic_canonical::{Constraint, Ref, ScopeItem}; + + let (id, kp) = dev_identity(); + let body = "\ +:::why{} +reason exists +::: + +:::scope-in +`src/App.tsx` state and markup. +::: + +:::scope-out +Server-side accounts. +::: + +:::constraint +Keep it local. +::: + +:::ref{to=urn:atomic:intent:019efe80-1234 edge=blockedBy} +:::"; + let node = lift_and_attest(&frontmatter(), body, &id, &kp).unwrap(); + + let _scope: &Vec = &node.has_scope_in; + let _c: &Vec = &node.has_constraint; + let _r: &Vec = &node.depends_on; + assert_eq!(node.has_scope_in.len(), 1); + assert_eq!(node.has_scope_out.len(), 1); + assert_eq!(node.has_constraint.len(), 1); + assert_eq!(node.depends_on.len(), 1); + assert_eq!(node.depends_on[0].edge, "blockedBy"); + + // Gate conforms (scope-in present, scope-out present) and verify roundtrips. + assert!(validate_intent(&node).conforms); + verify(&node, &kp.public).expect("verification should succeed"); + + // Render surfaces the new sections. + let text = render(&node, Target::Cli); + assert!(text.contains("Out of Scope"), "render:\n{text}"); + assert!(text.contains("blockedBy -> urn:atomic:intent:019efe80-1234")); +} + +fn memory_frontmatter() -> Map { + json!({ + "uid": "01J8ZC4R8T", + "memoryKind": "constraint", + "status": "active", + "about": ["urn:atomic:module:storage", "urn:atomic:module:replication"] + }) + .as_object() + .unwrap() + .clone() +} + +const MEMORY_BODY: &str = "\ +:::memory{} +Multi-region writes must converge with no single ordering authority. Anything +that reintroduces a writer-of-record is off the table. +:::"; + +#[test] +fn memory_lift_gate_attest_verify_render_end_to_end() { + let (id, kp) = dev_identity(); + + // Lift structure. + let lifted = lift_memory(&memory_frontmatter(), MEMORY_BODY).unwrap(); + assert_eq!(lifted.type_, "Memory"); + assert_eq!(lifted.id, "urn:atomic:memory:01J8ZC4R8T"); + assert_eq!(lifted.memory_kind, "constraint"); + assert_eq!(lifted.status, "active"); + assert_eq!(lifted.about.len(), 2); + assert!(lifted.text.contains("no single ordering authority")); + // Single authoring site: the :::memory container body is the text, without + // its wrapper directive lines. + assert!(!lifted.text.contains(":::")); + + // Attest through the shared path. + let node = lift_and_attest_memory(&memory_frontmatter(), MEMORY_BODY, &id, &kp).unwrap(); + assert!(node.content_hash.as_deref().unwrap().starts_with("blake3:")); + assert!(node.proof.is_some()); + assert_eq!(node.proof.as_ref().unwrap().cryptosuite, "eddsa-jcs-2022"); + + // Gate conforms. + assert!(validate_memory(&node).conforms, "gate:\n{}", validate_memory(&node)); + + // Verify. + verify_memory(&node, &kp.public).expect("memory verification should succeed"); + + // Render regenerates the status from the spine and shows about + text. + let text = render_memory(&node, Target::Cli); + assert!(text.contains("Status: active"), "render:\n{text}"); + assert!(text.contains("urn:atomic:module:storage")); + assert!(text.contains("no single ordering authority")); +} + +#[test] +fn memory_tampering_and_wrong_key_break_verification() { + let (id, kp) = dev_identity(); + let mut node = lift_and_attest_memory(&memory_frontmatter(), MEMORY_BODY, &id, &kp).unwrap(); + + // Tamper the text after signing → the stored contentHash no longer matches. + node.text = "a different, forged memory".to_string(); + let err = verify_memory(&node, &kp.public).unwrap_err(); + assert!( + matches!(err, atomic_canonical::CanonicalError::HashMismatch { .. }), + "expected HashMismatch, got {err:?}" + ); + + // A pristine memory verifies with the right key but not with the wrong one. + let pristine = lift_and_attest_memory(&memory_frontmatter(), MEMORY_BODY, &id, &kp).unwrap(); + let other = KeyPair::generate(); + assert!(verify_memory(&pristine, &other.public).is_err()); + verify_memory(&pristine, &kp.public).expect("right key verifies"); +} + +#[test] +fn memory_falls_back_to_whole_body_without_container() { + let (id, kp) = dev_identity(); + let node = lift_and_attest_memory( + &memory_frontmatter(), + " a plain constraint with no directive ", + &id, + &kp, + ) + .unwrap(); + assert_eq!(node.text, "a plain constraint with no directive"); + assert!(validate_memory(&node).conforms); +} + #[test] fn parse_markdown_then_lift() { let doc = format!( @@ -159,3 +311,83 @@ fn parse_markdown_then_lift() { assert_eq!(node.id, "urn:atomic:intent:word-9"); assert_eq!(node.has_acceptance_criterion.len(), 1); } + +// ── Regression tests for the adversarial-review fixes ──────────────────────── + +#[test] +fn injected_unknown_field_is_rejected_on_load_intent() { + // BLOCKER fix: a signed node with an injected key must NOT silently load + // (deny_unknown_fields), so an attacker can't smuggle a field past verify by + // relying on serde to strip it before the hash is recomputed. + let (id, kp) = dev_identity(); + let node = lift_and_attest(&frontmatter(), BODY, &id, &kp).unwrap(); + let mut v = serde_json::to_value(&node).unwrap(); + v.as_object_mut() + .unwrap() + .insert("actualStatus".into(), Value::String("done-but-forged".into())); + let reload: Result = serde_json::from_value(v); + assert!(reload.is_err(), "an unknown field must be rejected on load"); +} + +#[test] +fn injected_unknown_field_is_rejected_on_load_memory() { + let (id, kp) = dev_identity(); + let node = lift_and_attest_memory(&memory_frontmatter(), "a constraint", &id, &kp).unwrap(); + let mut v = serde_json::to_value(&node).unwrap(); + v.as_object_mut() + .unwrap() + .insert("forged".into(), Value::String("x".into())); + let reload: Result = serde_json::from_value(v); + assert!(reload.is_err(), "an unknown field must be rejected on load"); +} + +#[test] +fn tampered_proof_metadata_fails_verification() { + // MINOR fix: cryptosuite/purpose/type are enforced in verify_value even + // though signing_view strips the proof object from the signed bytes. + let (id, kp) = dev_identity(); + let node = lift_and_attest_memory(&memory_frontmatter(), "a constraint", &id, &kp).unwrap(); + let mut v = serde_json::to_value(&node).unwrap(); + v.as_object_mut() + .unwrap() + .get_mut("proof") + .unwrap() + .as_object_mut() + .unwrap() + .insert("cryptosuite".into(), Value::String("bogus-suite".into())); + assert!( + atomic_canonical::proof::verify_value(&v, &kp.public).is_err(), + "a mutated cryptosuite must fail verification" + ); +} + +#[test] +fn ref_edge_is_restricted_to_dependency_subset() { + // MINOR fix: a :::ref sits on the dependency chain, so a non-dependency edge + // (e.g. verifiedBy) must be rejected even though it is a valid edge elsewhere. + let good = format!( + "{BODY}\n\n:::ref{{to=urn:atomic:intent:other edge=blockedBy}}\n:::" + ); + let node = lift_intent(&frontmatter(), &good).unwrap(); + assert_eq!(node.depends_on.len(), 1); + assert_eq!(node.depends_on[0].edge, "blockedBy"); + + let bad = format!( + "{BODY}\n\n:::ref{{to=urn:atomic:intent:other edge=verifiedBy}}\n:::" + ); + assert!( + lift_intent(&frontmatter(), &bad).is_err(), + "verifiedBy is not a dependency edge" + ); +} + +#[test] +fn memory_body_with_directive_like_prose_lifts_verbatim() { + // MAJOR fix: open memory prose may begin a line with :: / ::: without being + // rejected by the closed-vocabulary directive parser. + let body = + "Prefer explicit types.\n:: turbofish is required here.\nWe discussed :::why once."; + let node = lift_memory(&memory_frontmatter(), body).unwrap(); + assert!(node.text.contains("turbofish"), "text: {}", node.text); + assert!(node.text.contains(":::why")); +} From 9a2e38a9e3454756442b8e51cf5c5db0328b1f01 Mon Sep 17 00:00:00 2001 From: Bradley Hilton Date: Wed, 1 Jul 2026 18:04:50 -0500 Subject: [PATCH 03/21] feat(cli): add top-level `atomic intent` verbs backed by atomic-canonical (M1a) Wires the Recording-the-Why engine to the CLI, ADDITIVELY: the attested canonical node + proof are written as a sidecar under `.atomic/canonical/`, and nothing in atomic-core / VaultEntry / content_hash / the manifest merkle / vault_scan is touched. Verified with `git diff` + the additivity audit. Verbs (top-level, coexisting with `atomic vault intent`): - intent validate lift + SHACL-style gate; nonzero if non-conforming - intent show render the canonical projection (status from spine) - intent new scaffold a directive-based intent (why/AC/task/scope/constraint) - intent attest <ID> gate, sign (did:atomic Ed25519), write the sidecar - intent verify <ID> read the sidecar, check freshness + verify hash/signature Adversarial-review fixes folded in (each verified end-to-end): - MAJOR: the sidecar was write-only. validate/show/verify now read it back (fresh -> gate/render the attested node; stale -> warn + fall back), so attest -> validate actually reports `conforms: yes`. Added the `verify` verb and a freshness check keyed on a recorded source hash. - MINOR: `validate --json` no longer prints the diagnostic Hint to stdout (the error-path hint is routed to stderr, aligning with the error itself); a path-shaped argument that does not exist reports FileNotFound rather than "invalid ID"; the feature scaffold now includes the `:::task` stub the doc names; the `new` positional is documented as the title (id is vault-allocated). Signing uses a non-production dev identity (plaintext keys). Storing the canonical hash AS the record hash (redefining content_hash + re-plumbing the merkle/scan) remains the deliberately-deferred invasive M1b. Verified: end-to-end new -> validate(no) -> attest -> validate(yes) -> verify(ok) with an isolated HOME; sidecar under .atomic/; atomic-cli builds, clippy clean, 1543 atomic-cli tests pass, atomic-canonical's 51 tests stay green. --- Cargo.lock | 2 + atomic-cli/Cargo.toml | 4 + atomic-cli/src/commands/intent/attest.rs | 176 ++++++++++++++++++ atomic-cli/src/commands/intent/bridge.rs | 202 +++++++++++++++++++++ atomic-cli/src/commands/intent/mod.rs | 160 ++++++++++++++++ atomic-cli/src/commands/intent/new.rs | 123 +++++++++++++ atomic-cli/src/commands/intent/show.rs | 59 ++++++ atomic-cli/src/commands/intent/validate.rs | 114 ++++++++++++ atomic-cli/src/commands/intent/verify.rs | 100 ++++++++++ atomic-cli/src/commands/mod.rs | 2 + atomic-cli/src/main.rs | 38 +++- 11 files changed, 976 insertions(+), 4 deletions(-) create mode 100644 atomic-cli/src/commands/intent/attest.rs create mode 100644 atomic-cli/src/commands/intent/bridge.rs create mode 100644 atomic-cli/src/commands/intent/mod.rs create mode 100644 atomic-cli/src/commands/intent/new.rs create mode 100644 atomic-cli/src/commands/intent/show.rs create mode 100644 atomic-cli/src/commands/intent/validate.rs create mode 100644 atomic-cli/src/commands/intent/verify.rs diff --git a/Cargo.lock b/Cargo.lock index 00883ba6..fc78d6d4 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -160,6 +160,7 @@ version = "0.9.1" dependencies = [ "anyhow", "atomic-agent", + "atomic-canonical", "atomic-config", "atomic-core", "atomic-identity", @@ -167,6 +168,7 @@ dependencies = [ "atomic-repository", "atomic-semantic", "atomic-teams", + "blake3", "bytes", "chrono", "clap", diff --git a/atomic-cli/Cargo.toml b/atomic-cli/Cargo.toml index aab9c8ae..031297f7 100644 --- a/atomic-cli/Cargo.toml +++ b/atomic-cli/Cargo.toml @@ -23,6 +23,7 @@ path = "src/main.rs" [dependencies] # Internal crates atomic-agent = { workspace = true } +atomic-canonical = { workspace = true } atomic-core = { workspace = true } atomic-config = { workspace = true } atomic-identity = { workspace = true } @@ -60,6 +61,9 @@ dirs = "5" # Base32/Base64 encoding data-encoding = "2.6" +# Hashing (source-content digest for canonical intent sidecars) +blake3 = { workspace = true } + # Open URLs in default browser (for device auth flow) open = "5" diff --git a/atomic-cli/src/commands/intent/attest.rs b/atomic-cli/src/commands/intent/attest.rs new file mode 100644 index 00000000..8c29be15 --- /dev/null +++ b/atomic-cli/src/commands/intent/attest.rs @@ -0,0 +1,176 @@ +//! `atomic intent attest <ID>` — sign an intent into a canonical sidecar. + +use clap::Parser; + +use atomic_canonical::{lift_and_attest, validate_intent, verify}; +use atomic_identity::IdentityStore; +use atomic_repository::Repository; + +use crate::commands::intent::bridge; +use crate::commands::intent::validation_failed; +use crate::commands::{find_repository_root, Command}; +use crate::error::{CliError, CliResult}; + +/// Attest an intent: gate it, sign it, and write the attested node to a sidecar. +#[derive(Parser, Debug)] +#[command(name = "attest")] +pub struct IntentAttest { + /// Intent ID (e.g. "PIMO-1" or "1"). + pub id: String, + + /// Identity to sign with. Defaults to the current default identity. + #[arg(long)] + pub identity: Option<String>, + + /// Output the attested node as JSON-LD. + #[arg(long)] + pub json: bool, +} + +impl Command for IntentAttest { + fn run(&self) -> CliResult<()> { + let root = find_repository_root()?; + let repo = Repository::open(&root).map_err(CliError::Repository)?; + + let inputs = bridge::read_intent(&repo, &self.id)?; + + // FIRST gate WITHOUT signing: refuse to sign a node that fails for a + // reason attestation cannot fix (unknown status, missing why, a scope + // declaration with no scope-out). Missing proof/attributedTo are the + // expected pre-attest violations — those are exactly what signing + // fills, so we only refuse on violations OUTSIDE that fillable set. + let unattested = bridge::lift(&inputs)?; + let pre = validate_intent(&unattested); + let blocking: Vec<_> = pre + .results + .iter() + .filter(|v| !is_fillable_by_attest(v.path.as_deref())) + .collect(); + if !blocking.is_empty() { + eprintln!("Cannot attest {}: the intent does not conform.", self.id); + eprint!("{pre}"); + return Err(validation_failed(format!( + "intent {} does not conform; fix the violations above before attesting \ + (run `atomic intent validate {}`)", + self.id, self.id + ))); + } + + // Resolve identity + keypair the way `atomic identity sign` does. + let store = IdentityStore::open_default().map_err(|e| { + CliError::Internal(anyhow::anyhow!("Failed to open identity store: {}", e)) + })?; + let identity = if let Some(name) = &self.identity { + store + .load_by_name(name) + .map_err(|_| CliError::IdentityNotFound(name.clone()))? + } else { + store + .get_default() + .map_err(|e| { + CliError::Internal(anyhow::anyhow!("Failed to load default identity: {}", e)) + })? + .ok_or_else(|| { + CliError::Internal(anyhow::anyhow!( + "No default identity set. Create one first:\n \ + atomic identity new <name> --email <email> --set-default" + )) + })? + }; + let keypair = store.load_keypair(&identity.id, None).map_err(|e| { + CliError::Internal(anyhow::anyhow!( + "Failed to load keypair for '{}': {}", + identity.name, + e + )) + })?; + + // Attest: lift + fill attributedTo (from the identity's did:atomic when + // absent) + hash + sign. + let node = lift_and_attest(&inputs.frontmatter, &inputs.body, &identity, &keypair) + .map_err(|e| CliError::InvalidArgument { + message: format!("could not attest intent: {e}"), + })?; + + // Belt-and-suspenders: re-gate the ATTESTED node — proof + attributedTo + // must now satisfy the gate. + let post = validate_intent(&node); + if !post.conforms { + eprint!("{post}"); + return Err(validation_failed(format!( + "attested intent {} still does not conform; refusing to persist", + self.id + ))); + } + + // Self-check: the proof verifies against the signing key before we + // write anything to disk. + verify(&node, &keypair.public).map_err(|e| CliError::InvalidArgument { + message: format!("attested intent failed self-verification: {e}"), + })?; + + // Persist the attested node as a sidecar under `.atomic/` — NOT into + // redb, NOT into the .vault/ tree, NOT via any VaultEntry write. This + // never touches content_hash or the manifest merkle. + let sidecar_path = bridge::attested_sidecar_path(&repo, &self.id); + if let Some(parent) = sidecar_path.parent() { + std::fs::create_dir_all(parent).map_err(CliError::Io)?; + } + // Record source anchors alongside the node for staleness detection: the + // vault path + the source content hash the sidecar attests. The node + // itself is stored under "node"; the anchors under "source". + let mut artifact = serde_json::Map::new(); + artifact.insert("node".to_string(), node.to_value()); + let mut source = serde_json::Map::new(); + if let Some(vault_path) = bridge::vault_path_for(&repo, &self.id)? { + source.insert("vaultPath".to_string(), serde_json::Value::String(vault_path)); + } + source.insert( + "sourceContentHash".to_string(), + serde_json::Value::String(bridge::source_content_hash(&inputs)), + ); + artifact.insert("source".to_string(), serde_json::Value::Object(source)); + let artifact = serde_json::Value::Object(artifact); + std::fs::write( + &sidecar_path, + serde_json::to_string_pretty(&artifact).unwrap(), + ) + .map_err(CliError::Io)?; + + let did = node + .attributed_to + .as_deref() + .unwrap_or("(unknown)"); + let proof_prefix = node + .proof + .as_ref() + .map(|p| { + let v = &p.proof_value; + v.chars().take(12).collect::<String>() + }) + .unwrap_or_default(); + + if self.json { + println!("{}", serde_json::to_string_pretty(&node.to_value()).unwrap()); + } else { + println!("Attested intent: {}", self.id); + println!(" sidecar: {}", sidecar_path.display()); + println!(" author: {did}"); + println!(" proof: {proof_prefix}…"); + eprintln!( + "note: signing keys are stored unencrypted on disk; treat this \ + attestation as a non-production dev signature until key-at-rest \ + encryption lands." + ); + } + + Ok(()) + } +} + +/// Is a pre-attest violation on this property path one that attestation fills +/// (and therefore not a reason to refuse signing)? Only `proof` and +/// `attributedTo` are filled by `lift_and_attest`. +fn is_fillable_by_attest(path: Option<&str>) -> bool { + matches!(path, Some("proof") | Some("attributedTo")) +} diff --git a/atomic-cli/src/commands/intent/bridge.rs b/atomic-cli/src/commands/intent/bridge.rs new file mode 100644 index 00000000..c94cf09e --- /dev/null +++ b/atomic-cli/src/commands/intent/bridge.rs @@ -0,0 +1,202 @@ +//! The read→lift bridge and sidecar plumbing shared by the `atomic intent` +//! verbs. +//! +//! # Read bridge +//! +//! A stored intent is read via [`Repository::vault_intent_show`], which returns +//! a `VaultEntry` carrying the two lift inputs: +//! +//! - `frontmatter_json: String` — a JSON *object* string (empty entries are +//! `"{}"`). This is the pre-parsed frontmatter spine; we feed it straight to +//! the lift. We do NOT route the body through `parse_markdown` for the vault +//! path, because the stored `content_bytes` is the body WITHOUT any +//! frontmatter block and `parse_markdown` would return an empty map. +//! - `content_bytes: Vec<u8>` — the markdown body. +//! +//! The `--path` branch of `validate` reads a full markdown file instead and +//! splits it with [`atomic_canonical::lift::parse_markdown`]. +//! +//! # Sidecar persistence (additive) +//! +//! Attestations are written as plain files under +//! `<repo.dot_dir()>/canonical/intents/<sanitized-id>/attested.jsonld`. That is +//! the engine-internal `.atomic/` metadata dir — outside the `.vault/` +//! materialized tree, outside redb, and never part of the manifest merkle. It +//! is therefore invisible to `vault_scan_working_copy`, to drift detection, and +//! to the `atomic view switch` untracked-file wipe (which only clears the +//! working tree). No `VaultEntry` is mutated to store an attestation. + +use std::path::PathBuf; + +use serde_json::{Map, Value}; + +use atomic_canonical::lift::lift_intent; +use atomic_canonical::CanonicalNode; +use atomic_core::pristine::VaultEntry; +use atomic_repository::Repository; + +use crate::error::{CliError, CliResult}; + +/// The two lift inputs pulled off a stored `VaultEntry`. +pub struct LiftInputs { + /// The parsed frontmatter spine (a JSON object). + pub frontmatter: Map<String, Value>, + /// The markdown body (without any frontmatter block). + pub body: String, +} + +/// Parse a `VaultEntry` into the frontmatter map + body the lift consumes. +/// +/// `frontmatter_json` is parsed exactly as the repository itself parses it +/// (`serde_json::from_str` into a `Map`). A malformed frontmatter string is a +/// clean argument error rather than an internal panic. +pub fn inputs_from_entry(entry: &VaultEntry) -> CliResult<LiftInputs> { + let frontmatter: Map<String, Value> = serde_json::from_str(&entry.frontmatter_json) + .map_err(|e| CliError::InvalidArgument { + message: format!("intent frontmatter is not valid JSON: {e}"), + })?; + let body = String::from_utf8_lossy(&entry.content_bytes).into_owned(); + Ok(LiftInputs { frontmatter, body }) +} + +/// Read an intent by ID from the vault and return its lift inputs. +/// +/// `vault_intent_show` normalizes the ID (`"PIMO-1"` / `"pimo-1"` / `"1"`) and +/// resolves the stored entry. +pub fn read_intent(repo: &Repository, id: &str) -> CliResult<LiftInputs> { + let entry = repo.vault_intent_show(id).map_err(CliError::Repository)?; + inputs_from_entry(&entry) +} + +/// Lift the given inputs into a canonical node, mapping a lift failure (unknown +/// directive, missing `id`, malformed `:::ref`, …) to a clean argument error so +/// the CLI reports it gracefully instead of surfacing an internal error. +pub fn lift(inputs: &LiftInputs) -> CliResult<CanonicalNode> { + lift_intent(&inputs.frontmatter, &inputs.body).map_err(|e| CliError::InvalidArgument { + message: format!("could not lift intent: {e}"), + }) +} + +/// Sanitize an intent id/key for use as a directory name in the sidecar path. +/// Keeps ASCII alphanumerics, `-` and `_`; everything else becomes `_`. +fn sanitize_id(id: &str) -> String { + id.chars() + .map(|c| { + if c.is_ascii_alphanumeric() || c == '-' || c == '_' { + c + } else { + '_' + } + }) + .collect() +} + +/// The directory that holds an intent's canonical sidecar artifacts: +/// `<dot_dir>/canonical/intents/<sanitized-id>/`. +pub fn sidecar_dir(repo: &Repository, id: &str) -> PathBuf { + repo.dot_dir() + .join("canonical") + .join("intents") + .join(sanitize_id(id)) +} + +/// The attested-node sidecar file for an intent. +pub fn attested_sidecar_path(repo: &Repository, id: &str) -> PathBuf { + sidecar_dir(repo, id).join("attested.jsonld") +} + +/// A hash of the source lift inputs, recorded in the sidecar so a later edit to +/// the intent can be detected as making the attestation stale. This is a +/// standalone digest of (frontmatter + body); it is NOT the vault's +/// `content_hash` and never feeds it. `attest` writes it; `validate`/`show`/ +/// `verify` recompute it to decide whether a sidecar is still fresh. +pub fn source_content_hash(inputs: &LiftInputs) -> String { + let fm = serde_json::to_string(&inputs.frontmatter).unwrap_or_default(); + let mut hasher = blake3::Hasher::new(); + hasher.update(fm.as_bytes()); + hasher.update(b"\0"); + hasher.update(inputs.body.as_bytes()); + format!("blake3:{}", hasher.finalize().to_hex()) +} + +/// The state of an intent's attestation sidecar relative to the current source. +pub enum Attestation { + /// No sidecar on disk. + None, + /// Sidecar present and its recorded source hash matches the current intent. + Fresh(Box<CanonicalNode>), + /// Sidecar present but the intent changed since it was signed. + Stale(Box<CanonicalNode>), +} + +/// Load an intent's attestation sidecar and classify it against the current +/// source (`inputs`). A missing sidecar is `None`; a corrupt/malformed one is +/// treated as `None` with a warning (so a read still works on the raw node). +/// This is what makes an attestation observable: `validate`/`show`/`verify` +/// consult it instead of always re-lifting the un-attested vault entry. +pub fn load_attestation( + repo: &Repository, + id: &str, + inputs: &LiftInputs, +) -> CliResult<Attestation> { + let path = attested_sidecar_path(repo, id); + if !path.exists() { + return Ok(Attestation::None); + } + let raw = std::fs::read_to_string(&path).map_err(CliError::Io)?; + let artifact: Value = match serde_json::from_str(&raw) { + Ok(v) => v, + Err(e) => { + eprintln!( + "warning: ignoring unreadable attestation sidecar {}: {e}", + path.display() + ); + return Ok(Attestation::None); + } + }; + let node_val = match artifact.get("node") { + Some(n) => n.clone(), + None => { + eprintln!( + "warning: attestation sidecar {} has no 'node' — ignoring", + path.display() + ); + return Ok(Attestation::None); + } + }; + let node: CanonicalNode = match serde_json::from_value(node_val) { + Ok(n) => n, + Err(e) => { + eprintln!( + "warning: ignoring malformed attestation node in {}: {e}", + path.display() + ); + return Ok(Attestation::None); + } + }; + let recorded = artifact + .get("source") + .and_then(|s| s.get("sourceContentHash")) + .and_then(Value::as_str); + let current = source_content_hash(inputs); + match recorded { + Some(h) if h == current => Ok(Attestation::Fresh(Box::new(node))), + _ => Ok(Attestation::Stale(Box::new(node))), + } +} + +/// Resolve the vault-relative path of a stored intent via the manifest. +/// +/// `vault_intent_show` normalizes and confirms existence but does not return a +/// path; `normalize_intent_id` is private, so we match the manifest keys +/// case-insensitively (the manifest keys are the normalized IDs, e.g. +/// `"PIMO-1"`). Returns `None` if the intent has no manifest entry / path. +pub fn vault_path_for(repo: &Repository, id: &str) -> CliResult<Option<String>> { + let manifest = repo.vault_manifest().map_err(CliError::Repository)?; + Ok(manifest + .intents + .iter() + .find(|(key, _)| key.eq_ignore_ascii_case(id)) + .map(|(_, summary)| summary.vault_path.clone()) + .filter(|p| !p.is_empty())) +} diff --git a/atomic-cli/src/commands/intent/mod.rs b/atomic-cli/src/commands/intent/mod.rs new file mode 100644 index 00000000..00208216 --- /dev/null +++ b/atomic-cli/src/commands/intent/mod.rs @@ -0,0 +1,160 @@ +//! `atomic intent` — the canonical "record the why" engine surface. +//! +//! This is a NEW top-level command, a sibling of `atomic vault` (see +//! [`crate::commands::vault`]). It is distinct from the existing vault-scoped +//! `atomic vault intent ...` tree ([`crate::commands::vault::intent`]): that +//! tree manages the raw vault entries (create/list/show/update/delete/link), +//! while this one drives the `atomic-canonical` engine — lifting a stored intent +//! into a canonical JSON-LD node, gating it, attesting it, and rendering it. +//! +//! # Verbs +//! +//! ```text +//! atomic intent validate <ID|path> Gate an intent against the canonical shapes +//! atomic intent show <ID> Render an intent as a read-time projection +//! atomic intent new <TITLE> Scaffold a directive-based intent +//! atomic intent attest <ID> Sign an intent into a canonical sidecar +//! atomic intent verify <ID> Verify a signed intent's attestation +//! ``` +//! +//! # Persistence — additive by construction +//! +//! Attestation NEVER mutates the stored `VaultEntry`, its `content_hash`, or the +//! manifest merkle. The attested node + proof are written as a plain file under +//! `.atomic/canonical/intents/<id>/` (the engine-internal metadata dir), outside +//! the `.vault/` materialized tree and outside redb. See [`bridge`]. + +use clap::{Parser, Subcommand}; + +use crate::commands::Command; +use crate::error::CliResult; + +pub mod attest; +pub mod bridge; +pub mod new; +pub mod show; +pub mod validate; +pub mod verify; + +pub use attest::IntentAttest; +pub use new::IntentNew; +pub use show::IntentShow; +pub use validate::IntentValidate; +pub use verify::IntentVerify; + +/// Subcommands for the canonical intent engine. +#[derive(Subcommand, Debug)] +pub enum IntentCommands { + /// Validate an intent against the canonical shapes (the authoring gate). + /// + /// Lifts the intent (by ID from the vault, or from a markdown file path) + /// into a canonical node and runs the SHACL-style gate. An un-attested + /// vault intent will report violations for the missing proof and (because + /// the vault stores `created_by`, not `attributedTo`) the missing author — + /// this is correct: `validate` is the authoring check, `attest` is what + /// makes it conform. Exits nonzero if the report does not conform. + /// + /// # Examples + /// + /// ```text + /// atomic intent validate PIMO-1 + /// atomic intent validate ./plan.md + /// atomic intent validate PIMO-1 --json + /// ``` + Validate(IntentValidate), + + /// Show an intent as a rendered read-time projection. + /// + /// Lifts the intent and renders it via the canonical projection. This is a + /// pure read: it does not gate and does not require a proof, so it works on + /// a plain (un-attested) intent. + /// + /// # Examples + /// + /// ```text + /// atomic intent show PIMO-1 + /// atomic intent show PIMO-1 --json + /// ``` + Show(IntentShow), + + /// Scaffold a new directive-based intent into the vault. + /// + /// Emits a body built from the closed directive vocabulary + /// (`:::why`, `:::acceptance-criterion`, `:::scope-in`, `:::scope-out`, + /// `:::constraint`) so it round-trips cleanly through + /// lift → validate → attest. + /// + /// # Examples + /// + /// ```text + /// atomic intent new "Fix the login flow" + /// atomic intent new "Add OAuth" --template feature + /// ``` + New(IntentNew), + + /// Attest an intent: sign it into a canonical sidecar. + /// + /// Gates the intent first (refusing to sign a non-conforming node), + /// fills `attributedTo` from the signing identity's `did:atomic`, signs + /// the canonical node, re-gates the attested result, and writes the node + /// (with embedded contentHash + proof) to a sidecar under `.atomic/`. + /// No `VaultEntry`, `content_hash`, or merkle is touched. + /// + /// # Examples + /// + /// ```text + /// atomic intent attest PIMO-1 + /// atomic intent attest PIMO-1 --identity alice-work + /// atomic intent attest PIMO-1 --json + /// ``` + Attest(IntentAttest), + + /// Verify a signed intent's attestation. + /// + /// Reads the attestation sidecar written by `attest`, confirms it is still + /// fresh (the intent hasn't changed since it was signed), and verifies its + /// content hash + Ed25519 Data Integrity proof. Exits nonzero if there is + /// no attestation, it is stale, or the signature does not verify. + /// + /// # Examples + /// + /// ```text + /// atomic intent verify PIMO-1 + /// atomic intent verify PIMO-1 --identity alice-work + /// ``` + Verify(IntentVerify), +} + +/// Record the "why": lift, validate, attest, and render canonical intents. +/// +/// A sibling of `atomic vault`. The verbs operate on real vault intents through +/// the `atomic-canonical` engine, persisting attestations additively as +/// sidecar files under `.atomic/` — the stored vault entries are never mutated. +#[derive(Debug, clap::Args)] +#[command(name = "intent")] +pub struct Intent { + #[command(subcommand)] + pub command: IntentCommands, +} + +impl Command for Intent { + fn run(&self) -> CliResult<()> { + match &self.command { + IntentCommands::Validate(cmd) => cmd.run(), + IntentCommands::Show(cmd) => cmd.run(), + IntentCommands::New(cmd) => cmd.run(), + IntentCommands::Attest(cmd) => cmd.run(), + IntentCommands::Verify(cmd) => cmd.run(), + } + } +} + +/// A validation-failure error: the canonical gate reported a non-conforming +/// node. Kept as a `Parser`-free helper so `main.rs`'s `err.exit_code()` fires +/// with a distinct, user-fixable exit code (2, a usage/authoring error) rather +/// than the internal-bug code. +pub(crate) fn validation_failed(message: impl Into<String>) -> crate::error::CliError { + crate::error::CliError::InvalidArgument { + message: message.into(), + } +} diff --git a/atomic-cli/src/commands/intent/new.rs b/atomic-cli/src/commands/intent/new.rs new file mode 100644 index 00000000..8d9c5bad --- /dev/null +++ b/atomic-cli/src/commands/intent/new.rs @@ -0,0 +1,123 @@ +//! `atomic intent new <KEY> [--template feature]` — scaffold a directive-based +//! intent into the vault. + +use clap::Parser; + +use atomic_repository::{IntentCreateOptions, IntentUpdateOptions, Repository}; + +use crate::commands::{find_repository_root, Command}; +use crate::error::{CliError, CliResult}; + +/// The directive scaffold emitted for a new intent. +/// +/// This is DISTINCT from the legacy positional template shipped at +/// `atomic-repository/vault/templates/intent.md` (Problem / `- [ ]` checkboxes / +/// Scope headings), which is not directive-based and lifts to nothing. This +/// scaffold is built from the closed directive vocabulary the lift understands +/// (`atomic-canonical/src/lift.rs`: `why`, `acceptance-criterion`, `scope-in`, +/// `scope-out`, `constraint`) so it round-trips cleanly through +/// lift → validate → attest. +/// +/// `{id}` is replaced with the allocated intent ID so the acceptance-criterion +/// gets a stable, prefixed local id. A `:::why` stub is mandatory (the gate +/// hard-requires a non-empty `why`), and because it emits a `:::scope-in` it +/// must also emit a `:::scope-out` (the gate requires the out-of-scope boundary +/// whenever scope is declared). +const FEATURE_SCAFFOLD: &str = "\ +:::why +<!-- Why does this intent exist? State the reason this work matters. The + content is never graded — but it must be present. Replace this stub. --> +::: + +:::acceptance-criterion{#{id}-ac-1 status=open} +<!-- A single, checkable outcome that means this intent is done. --> +::: + +:::task{#{id}-1 status=open criteria={id}-ac-1} +<!-- A concrete work item toward the criterion above. Name the file(s) it + touches with one or more ::file-ref leaves. --> +::file-ref{path=path/to/file} +::: + +:::scope-in +<!-- What this intent will change. --> +::: + +:::scope-out +<!-- What this intent will deliberately NOT change (the boundaries the agent + must respect). --> +::: + +:::constraint +<!-- A rule the implementation must respect. --> +::: +"; + +/// Scaffold a new directive-based intent into the vault. +#[derive(Parser, Debug)] +#[command(name = "new")] +pub struct IntentNew { + /// The intent's title (a short summary of the work). NOTE: the human key / + /// id (e.g. PIMO-1) is allocated by the vault — this positional is the title, + /// not the id. + pub title: String, + + /// Scaffold template to emit. Only "feature" is implemented. + #[arg(long, default_value = "feature")] + pub template: String, +} + +impl Command for IntentNew { + fn run(&self) -> CliResult<()> { + if self.template != "feature" { + return Err(CliError::InvalidArgument { + message: format!( + "unknown template '{}' (only 'feature' is implemented)", + self.template + ), + }); + } + + let root = find_repository_root()?; + let repo = Repository::open(&root).map_err(CliError::Repository)?; + + // Create through the EXISTING vault write path so the intent enters + // redb normally and joins the merkle exactly as `atomic vault intent + // create` does — we do NOT invent a new redb write. + let created = repo + .vault_intent_create(IntentCreateOptions { + title: self.title.clone(), + priority: None, + assignee: None, + labels: Vec::new(), + session_id: None, + turn_id: None, + }) + .map_err(CliError::Repository)?; + + // Overwrite the (legacy positional) scaffold body with the directive + // scaffold, again through the existing update path. `force` is set + // because this runs immediately after create; the intent is a fresh + // backlog draft with no linked goal, so force is a no-op guard-skip. + let scaffold = FEATURE_SCAFFOLD.replace("{id}", &created.id.to_lowercase()); + repo.vault_intent_update( + &created.id, + IntentUpdateOptions { + content: Some(scaffold), + force: true, + ..Default::default() + }, + ) + .map_err(CliError::Repository)?; + + println!("Created intent: {}", created.id); + println!(" file: .vault/{}", created.intent_file); + println!(" template: {}", self.template); + println!(); + println!("Edit the directive stubs, then:"); + println!(" atomic intent validate {}", created.id); + println!(" atomic intent attest {}", created.id); + + Ok(()) + } +} diff --git a/atomic-cli/src/commands/intent/show.rs b/atomic-cli/src/commands/intent/show.rs new file mode 100644 index 00000000..7cb8ab1b --- /dev/null +++ b/atomic-cli/src/commands/intent/show.rs @@ -0,0 +1,59 @@ +//! `atomic intent show <ID>` — render an intent as a read-time projection. + +use clap::Parser; + +use atomic_canonical::{render, Target}; +use atomic_repository::Repository; + +use crate::commands::intent::bridge; +use crate::commands::{find_repository_root, Command}; +use crate::error::{CliError, CliResult}; + +/// Show an intent as a rendered read-time projection. +/// +/// Distinct from [`crate::commands::vault::intent::IntentShow`], which dumps the +/// raw stored body. This projects the lifted canonical node. +#[derive(Parser, Debug)] +#[command(name = "show")] +pub struct IntentShow { + /// Intent ID (e.g. "PIMO-1" or "1"). + pub id: String, + + /// Output the canonical node as JSON-LD instead of the rendered view. + #[arg(long)] + pub json: bool, +} + +impl Command for IntentShow { + fn run(&self) -> CliResult<()> { + let root = find_repository_root()?; + let repo = Repository::open(&root).map_err(CliError::Repository)?; + + // Pure read-time projection: lift then render. No gate, no proof + // requirement — this must work on a plain (un-attested) intent. The + // status line is regenerated from the spine by the renderer. If a FRESH + // attestation sidecar exists we project that (so `show` reflects the + // attested author/proof); a stale one warns and falls back to the raw node. + let inputs = bridge::read_intent(&repo, &self.id)?; + let node = match bridge::load_attestation(&repo, &self.id, &inputs)? { + bridge::Attestation::Fresh(node) => *node, + bridge::Attestation::Stale(_) => { + eprintln!( + "warning: the attestation for {} is stale; showing the current \ + (un-attested) intent.", + self.id + ); + bridge::lift(&inputs)? + } + bridge::Attestation::None => bridge::lift(&inputs)?, + }; + + if self.json { + println!("{}", serde_json::to_string_pretty(&node.to_value()).unwrap()); + } else { + print!("{}", render(&node, Target::Cli)); + } + + Ok(()) + } +} diff --git a/atomic-cli/src/commands/intent/validate.rs b/atomic-cli/src/commands/intent/validate.rs new file mode 100644 index 00000000..6630a4ca --- /dev/null +++ b/atomic-cli/src/commands/intent/validate.rs @@ -0,0 +1,114 @@ +//! `atomic intent validate <ID|path>` — gate an intent against the canonical +//! shapes. + +use std::path::Path; + +use clap::Parser; + +use atomic_canonical::lift::{lift_intent, parse_markdown}; +use atomic_canonical::{validate_intent, ValidationReport}; +use atomic_repository::Repository; + +use crate::commands::intent::bridge; +use crate::commands::intent::validation_failed; +use crate::commands::{find_repository_root, Command}; +use crate::error::{CliError, CliResult}; + +/// Validate an intent against the canonical shapes. +#[derive(Parser, Debug)] +#[command(name = "validate")] +pub struct IntentValidate { + /// Intent ID (e.g. "PIMO-1" or "1"), or a path to an intent markdown file. + pub id_or_path: String, + + /// Output the validation report as JSON. + #[arg(long)] + pub json: bool, +} + +impl Command for IntentValidate { + fn run(&self) -> CliResult<()> { + // Resolve the argument. A path-shaped argument (ends in `.md` or + // contains a separator) is loaded as a file — and if it doesn't exist + // we report FileNotFound rather than misreporting it as a bad ID. + // Otherwise the argument is an intent ID read through the vault bridge; + // if a FRESH attestation sidecar exists we gate the attested node (so a + // previously-attested intent reports conforms), a STALE one warns and + // falls back to the raw node. + let node = if is_path_shaped(&self.id_or_path) { + let path = Path::new(&self.id_or_path); + if !path.is_file() { + return Err(CliError::FileNotFound { + path: path.to_path_buf(), + }); + } + let doc = std::fs::read_to_string(path).map_err(CliError::Io)?; + let (fm, body) = parse_markdown(&doc).map_err(|e| CliError::InvalidArgument { + message: format!("could not parse markdown frontmatter: {e}"), + })?; + lift_intent(&fm, &body).map_err(|e| CliError::InvalidArgument { + message: format!("could not lift intent: {e}"), + })? + } else { + let root = find_repository_root()?; + let repo = Repository::open(&root).map_err(CliError::Repository)?; + let inputs = bridge::read_intent(&repo, &self.id_or_path)?; + match bridge::load_attestation(&repo, &self.id_or_path, &inputs)? { + bridge::Attestation::Fresh(node) => *node, + bridge::Attestation::Stale(_) => { + eprintln!( + "warning: the attestation for {} is stale (the intent changed since it \ + was signed); re-run `atomic intent attest {}`.", + self.id_or_path, self.id_or_path + ); + bridge::lift(&inputs)? + } + bridge::Attestation::None => bridge::lift(&inputs)?, + } + }; + + let report = validate_intent(&node); + + if self.json { + println!("{}", serde_json::to_string_pretty(&report_json(&report)).unwrap()); + } else { + print!("{report}"); + } + + if report.conforms { + Ok(()) + } else { + Err(validation_failed(format!( + "intent does not conform ({} violation(s))", + report.results.len() + ))) + } + } +} + +/// Is the argument *shaped* like a filesystem path (rather than an intent ID)? +/// True when it ends in `.md` or contains a path separator. We decide path-vs-ID +/// on shape, not existence, so a mistyped `./plan.md` is reported as a missing +/// file (FileNotFound) instead of misleadingly falling through to "invalid ID". +/// Intent IDs are `PREFIX-N` / `N` — no `.md` suffix, no separator. +fn is_path_shaped(arg: &str) -> bool { + arg.ends_with(".md") || arg.contains('/') || arg.contains(std::path::MAIN_SEPARATOR) +} + +/// Serialize a [`ValidationReport`] to the documented JSON shape: +/// `{conforms, results: [{focus_node, shape, path, message}]}`. +fn report_json(report: &ValidationReport) -> serde_json::Value { + serde_json::json!({ + "conforms": report.conforms, + "results": report + .results + .iter() + .map(|v| serde_json::json!({ + "focus_node": v.focus_node, + "shape": v.shape, + "path": v.path, + "message": v.message, + })) + .collect::<Vec<_>>(), + }) +} diff --git a/atomic-cli/src/commands/intent/verify.rs b/atomic-cli/src/commands/intent/verify.rs new file mode 100644 index 00000000..5a562656 --- /dev/null +++ b/atomic-cli/src/commands/intent/verify.rs @@ -0,0 +1,100 @@ +//! `atomic intent verify <ID>` — verify an intent's attestation sidecar. +//! +//! Reads the attested node written by `attest`, checks it is still fresh (the +//! intent hasn't changed since it was signed), and cryptographically verifies +//! its content hash + Ed25519 Data Integrity proof. This is the read-back that +//! makes the sidecar observable: `attest` writes it, `verify` proves it. + +use clap::Parser; + +use atomic_canonical::verify; +use atomic_identity::IdentityStore; +use atomic_repository::Repository; + +use crate::commands::intent::bridge; +use crate::commands::{find_repository_root, Command}; +use crate::error::{CliError, CliResult}; + +/// Verify an intent's attestation (hash + signature) against a public key. +#[derive(Parser, Debug)] +#[command(name = "verify")] +pub struct IntentVerify { + /// Intent ID (e.g. "PIMO-1" or "1"). + pub id: String, + + /// Identity whose public key to verify against. Defaults to the current + /// default identity. Pass this if the intent was attested by someone else. + #[arg(long)] + pub identity: Option<String>, +} + +impl Command for IntentVerify { + fn run(&self) -> CliResult<()> { + let root = find_repository_root()?; + let repo = Repository::open(&root).map_err(CliError::Repository)?; + + let inputs = bridge::read_intent(&repo, &self.id)?; + let node = match bridge::load_attestation(&repo, &self.id, &inputs)? { + bridge::Attestation::None => { + return Err(CliError::InvalidArgument { + message: format!( + "no attestation found for {}; run `atomic intent attest {}` first", + self.id, self.id + ), + }) + } + bridge::Attestation::Stale(_) => { + return Err(CliError::InvalidArgument { + message: format!( + "the attestation for {} is stale (the intent changed since it was \ + signed); re-run `atomic intent attest {}`", + self.id, self.id + ), + }) + } + bridge::Attestation::Fresh(node) => *node, + }; + + // Resolve the public key to verify against. `did:atomic` is a key + // fingerprint (not recoverable to a key), so a store-backed resolver is + // needed; for now we verify against the default (or named) identity and + // let atomic_canonical::verify's DID check catch a mismatch. + let store = IdentityStore::open_default().map_err(|e| { + CliError::Internal(anyhow::anyhow!("Failed to open identity store: {}", e)) + })?; + let identity = if let Some(name) = &self.identity { + store + .load_by_name(name) + .map_err(|_| CliError::IdentityNotFound(name.clone()))? + } else { + store + .get_default() + .map_err(|e| { + CliError::Internal(anyhow::anyhow!("Failed to load default identity: {}", e)) + })? + .ok_or_else(|| { + CliError::Internal(anyhow::anyhow!( + "No default identity set. Create one first:\n \ + atomic identity new <name> --email <email> --set-default" + )) + })? + }; + + verify(&node, &identity.public_key).map_err(|e| CliError::InvalidArgument { + message: format!( + "verification failed: {e} (if this intent was attested by a different \ + identity, pass --identity <name>)" + ), + })?; + + println!("Verified intent: {}", self.id); + println!( + " author: {}", + node.attributed_to.as_deref().unwrap_or("(unknown)") + ); + if let Some(h) = &node.content_hash { + println!(" hash: {h}"); + } + Ok(()) + } +} diff --git a/atomic-cli/src/commands/mod.rs b/atomic-cli/src/commands/mod.rs index 00841d89..70c2aeda 100644 --- a/atomic-cli/src/commands/mod.rs +++ b/atomic-cli/src/commands/mod.rs @@ -73,6 +73,7 @@ pub mod diff; pub mod doctor; pub mod init; pub mod insert; +pub mod intent; pub mod log; pub mod mv; pub mod record; @@ -132,6 +133,7 @@ pub use git::Git; pub use identity::Identity; pub use init::Init; pub use insert::Insert; +pub use intent::Intent; pub use log::Log; pub use mv::Move; pub use project::ProjectCmd; diff --git a/atomic-cli/src/main.rs b/atomic-cli/src/main.rs index 328b46d9..1b10e403 100644 --- a/atomic-cli/src/main.rs +++ b/atomic-cli/src/main.rs @@ -66,6 +66,7 @@ use commands::{ Identity, Init, Insert, + Intent, Log, Move, ProjectCmd, @@ -94,7 +95,7 @@ use commands::{ // Team features (conditional) #[cfg(feature = "teams")] use commands::{OrgCmd, TeamCmd}; -use output::{print_error, print_hint}; +use output::{hint, print_error}; // CLI Argument Definitions @@ -694,6 +695,31 @@ enum Commands { /// ``` Vault(Vault), + /// Record the "why": lift, validate, attest, and render canonical intents. + /// + /// A sibling of `atomic vault`. Drives the `atomic-canonical` engine over + /// real vault intents, persisting attestations additively as sidecar files + /// under `.atomic/` — the stored vault entries are never mutated. Distinct + /// from the vault-scoped `atomic vault intent ...` tree. + /// + /// # Examples + /// + /// ```text + /// # Scaffold a directive-based intent + /// atomic intent new "Fix the login flow" + /// + /// # Validate it against the canonical shapes + /// atomic intent validate PIMO-1 + /// + /// # Render the canonical projection + /// atomic intent show PIMO-1 + /// + /// # Sign it into a canonical sidecar + /// atomic intent attest PIMO-1 + /// ``` + #[command(name = "intent")] + Intent(Intent), + /// Remove the last change from the current view. /// /// The change is removed from the view's change log but NOT deleted @@ -815,16 +841,20 @@ fn main() { Commands::Query(query) => query.run(), Commands::Vault(vault) => vault.run(), + + Commands::Intent(intent) => intent.run(), }; // Handle errors with user-friendly output if let Err(err) = result { print_error(&err.to_string()); - // Print suggestion if available + // Print suggestion if available — to STDERR, alongside the error itself, + // so a command's stdout (e.g. `--json` output on an erroring path) is + // never polluted by a diagnostic hint. if let Some(suggestion) = err.suggestion() { - println!(); - print_hint(&format!("Hint: {}", suggestion)); + eprintln!(); + eprintln!("{}", hint(&format!("Hint: {}", suggestion))); } // Exit with appropriate code From dba537031f6ee56af2f617ba210779e2052a88cc Mon Sep 17 00:00:00 2001 From: Bradley Hilton <graywolf336@craftyn.com> Date: Thu, 2 Jul 2026 10:32:10 -0500 Subject: [PATCH 04/21] feat(vault): store RtW attestations as tracked vault entries (existing hashing, additive) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Attestations become a first-class TRACKED vault entry instead of a local `.atomic/` sidecar, so signed "why" is durable and travels via the ordinary change graph — with ZERO change to the vault's hashing. This is the additive path chosen after reverting the M1b content_hash redefinition. - New append-only `VaultEntryType::Attestation` (index 6; postcard encodes discriminants positionally, so appending is back-compatible with existing rows — never reorder/delete). `infer_entry_type` maps `attestations/` → it; `vault_triples.rs` gets explicit (non-`_`) arms emitting no KG nodes/edges; the embedding path already skips it — signed blobs never pollute search. - `atomic intent attest` writes the signed JSON-LD node to `attestations/<intent-id>/attested.md` via the existing `vault_store` (storage hash stays blake3(body); the node's own contentHash + eddsa-jcs-2022 proof live inside the opaque body — two hashes, two jobs). A trailing newline is appended so materialize is a byte-identity transform and the first scan sees Unchanged (no false-Modified, no double-merkle-advance). It does NOT route through intent_dir_for (avoids the collapse bug) and does NOT auto-record. - `validate`/`show`/`verify` read the tracked entry; staleness reuses the existing `source_content_hash`. During transition, attest dual-writes the legacy sidecar and readers fall back to it — probing BOTH the normalized-id and the raw-arg legacy path so pre-upgrade M1a sidecars still resolve. - content_hash semantics, hash.rs, the manifest merkle, and vault_scan's comparison are UNTOUCHED (verified). Verified end-to-end (isolated HOME): attest → tracked `attestation` entry at attestations/REPO-1/attested.md → validate conforms → verify passes. Tests: atomic-canonical 51, atomic-cli 1538+9 (incl. tracked/legacy/raw-arg-fallback/ staleness bridge tests), atomic-core + atomic-repository green; clippy clean (only pre-existing provenance_summary warnings). Plan + adversarial critique drove the design (GO-WITH-CHANGES; the trailing-newline + dual-read fixes were the required changes). --- atomic-cli/src/commands/intent/attest.rs | 51 ++- atomic-cli/src/commands/intent/bridge.rs | 398 +++++++++++++++++- atomic-core/src/pristine/vault.rs | 50 ++- atomic-repository/src/repository/vault.rs | 85 +++- .../src/repository/vault_triples.rs | 35 ++ docs/recording-the-why.md | 6 + 6 files changed, 597 insertions(+), 28 deletions(-) diff --git a/atomic-cli/src/commands/intent/attest.rs b/atomic-cli/src/commands/intent/attest.rs index 8c29be15..4fcacfcb 100644 --- a/atomic-cli/src/commands/intent/attest.rs +++ b/atomic-cli/src/commands/intent/attest.rs @@ -2,7 +2,10 @@ use clap::Parser; +use serde_json::Value; + use atomic_canonical::{lift_and_attest, validate_intent, verify}; +use atomic_core::pristine::VaultEntryType; use atomic_identity::IdentityStore; use atomic_repository::Repository; @@ -109,10 +112,13 @@ impl Command for IntentAttest { message: format!("attested intent failed self-verification: {e}"), })?; + // --- Legacy sidecar dual-write (transition) --------------------------- // Persist the attested node as a sidecar under `.atomic/` — NOT into // redb, NOT into the .vault/ tree, NOT via any VaultEntry write. This - // never touches content_hash or the manifest merkle. - let sidecar_path = bridge::attested_sidecar_path(&repo, &self.id); + // never touches content_hash or the manifest merkle. Kept during the + // transition so pre-upgrade readers keep working; `load_attestation` + // prefers the tracked entry below and shadows this copy. + let sidecar_path = bridge::attested_sidecar_path(&repo, &self.id)?; if let Some(parent) = sidecar_path.parent() { std::fs::create_dir_all(parent).map_err(CliError::Io)?; } @@ -137,6 +143,46 @@ impl Command for IntentAttest { ) .map_err(CliError::Io)?; + // --- Tracked vault entry (new authoritative source) ------------------- + // Store JUST the attested node (not the {node,source} wrapper) as the + // body, so it parses straight back to a CanonicalNode on read. + let mut body = serde_json::to_string_pretty(&node.to_value()) + .expect("canonical node serialization is infallible"); + // serde pretty JSON has NO trailing newline; render_entry_to_markdown + // appends one to any body not ending in '\n'. Pre-appending it here makes + // materialize a byte-identity transform on the body, so the first + // vault_scan sees Hash::of(body) == stored blake3(content) == Unchanged. + body.push('\n'); + let content_bytes = body.into_bytes(); + + // Frontmatter anchors — FLAT SCALAR strings only, so they survive + // yaml_frontmatter_to_json (which only round-trips `key: scalar/array` + // lines; a nested object would be mangled). sourceContentHash/vaultPath + // contain ':' and '/' but no ": " (colon-space), so write_frontmatter_field + // emits them bare and they round-trip cleanly. + let mut fm = serde_json::Map::new(); + fm.insert( + "intentId".into(), + Value::String(bridge::normalized_id(&repo, &self.id)?), + ); + fm.insert( + "sourceContentHash".into(), + Value::String(bridge::source_content_hash(&inputs)), + ); + if let Some(vp) = bridge::vault_path_for(&repo, &self.id)? { + fm.insert("vaultPath".into(), Value::String(vp)); + } + let frontmatter_json = serde_json::to_string(&fm).unwrap(); + + let vault_path = bridge::attestation_vault_path(&repo, &self.id)?; + repo.vault_store( + &vault_path, + VaultEntryType::Attestation, + content_bytes, + frontmatter_json, + ) + .map_err(CliError::Repository)?; + let did = node .attributed_to .as_deref() @@ -154,6 +200,7 @@ impl Command for IntentAttest { println!("{}", serde_json::to_string_pretty(&node.to_value()).unwrap()); } else { println!("Attested intent: {}", self.id); + println!(" vault: .vault/{vault_path}"); println!(" sidecar: {}", sidecar_path.display()); println!(" author: {did}"); println!(" proof: {proof_prefix}…"); diff --git a/atomic-cli/src/commands/intent/bridge.rs b/atomic-cli/src/commands/intent/bridge.rs index c94cf09e..5857a4c5 100644 --- a/atomic-cli/src/commands/intent/bridge.rs +++ b/atomic-cli/src/commands/intent/bridge.rs @@ -16,15 +16,24 @@ //! The `--path` branch of `validate` reads a full markdown file instead and //! splits it with [`atomic_canonical::lift::parse_markdown`]. //! -//! # Sidecar persistence (additive) +//! # Attestation persistence (tracked vault entry, dual-read) //! -//! Attestations are written as plain files under -//! `<repo.dot_dir()>/canonical/intents/<sanitized-id>/attested.jsonld`. That is -//! the engine-internal `.atomic/` metadata dir — outside the `.vault/` -//! materialized tree, outside redb, and never part of the manifest merkle. It -//! is therefore invisible to `vault_scan_working_copy`, to drift detection, and -//! to the `atomic view switch` untracked-file wipe (which only clears the -//! working tree). No `VaultEntry` is mutated to store an attestation. +//! Attestations are now written as a FIRST-CLASS TRACKED vault entry at +//! `attestations/<sanitized-id>/attested.md` (entry_type `attestation`). The +//! body is the signed JSON-LD node (pretty-printed + a trailing `\n`); the +//! vault's storage hash stays `blake3(body)` exactly as for every other entry, +//! and the node's own `contentHash` + `eddsa-jcs-2022` proof live INSIDE that +//! opaque body. The trailing newline makes materialize a byte-identity +//! transform, so the first `vault_scan_working_copy` sees the entry as +//! Unchanged (no false Modified, no double-merkle advance). +//! +//! During the transition, `attest` also DUAL-WRITES the legacy sidecar under +//! `<repo.dot_dir()>/canonical/intents/<sanitized-id>/attested.jsonld` (the +//! engine-internal `.atomic/` metadata dir, outside the `.vault/` tree, outside +//! redb, invisible to scan/drift/view-switch-wipe). [`load_attestation`] PREFERS +//! the tracked entry and falls back to the legacy sidecar, so pre-upgrade +//! attestations keep working. Both paths key off the SAME normalized/sanitized +//! id so the fallback lines up. use std::path::PathBuf; @@ -77,8 +86,8 @@ pub fn lift(inputs: &LiftInputs) -> CliResult<CanonicalNode> { }) } -/// Sanitize an intent id/key for use as a directory name in the sidecar path. -/// Keeps ASCII alphanumerics, `-` and `_`; everything else becomes `_`. +/// Sanitize an intent id/key for use as a directory name in the sidecar/vault +/// path. Keeps ASCII alphanumerics, `-` and `_`; everything else becomes `_`. fn sanitize_id(id: &str) -> String { id.chars() .map(|c| { @@ -91,18 +100,94 @@ fn sanitize_id(id: &str) -> String { .collect() } +/// The normalized intent id used to key BOTH the tracked vault attestation path +/// and the legacy `.atomic` sidecar dir, so the dual-read fallback lines up +/// (critic #4). Resolution mirrors the repository's private `normalize_intent_id` +/// closely enough that `attest 1`, `attest pimo-1`, and `attest PIMO-1` all +/// collapse to the SAME `<sanitized>` on both the tracked and the legacy paths: +/// +/// 1. A case-insensitive match against a manifest key wins (handles `pimo-1` / +/// `PIMO-1`, identical to `vault_path_for`'s resolution). +/// 2. A bare number is expanded with the manifest's `intent_prefix` +/// (`1` -> `PIMO-1`), matching `normalize_intent_id`'s bare-number branch, and +/// that expansion is confirmed against a manifest key when present. +/// 3. Otherwise fall back to the raw arg uppercased (numeric ids missing from the +/// manifest stay as the bare number — the same on both paths, so reconciliation +/// still holds). +pub fn normalized_id(repo: &Repository, id: &str) -> CliResult<String> { + let manifest = repo.vault_manifest().map_err(CliError::Repository)?; + + // (1) direct case-insensitive manifest-key match (PREFIX-N / prefix-n forms). + if let Some(key) = manifest.intents.keys().find(|k| k.eq_ignore_ascii_case(id)) { + return Ok(key.clone()); + } + + // (2) bare number -> expand with the manifest prefix, then confirm against a + // manifest key (case-insensitively) so we return the canonical key form. + if id.parse::<u32>().is_ok() { + let prefix = if manifest.intent_prefix.is_empty() { + "VAULT".to_string() + } else { + manifest.intent_prefix.clone() + }; + let expanded = format!("{prefix}-{id}"); + if let Some(key) = manifest + .intents + .keys() + .find(|k| k.eq_ignore_ascii_case(&expanded)) + { + return Ok(key.clone()); + } + return Ok(expanded); + } + + // (3) fallback: raw arg uppercased. + Ok(id.to_uppercase()) +} + +/// The tracked-vault path for an intent's attestation: +/// `attestations/<sanitized-normalized-id>/attested.md`. +pub fn attestation_vault_path(repo: &Repository, id: &str) -> CliResult<String> { + Ok(format!( + "attestations/{}/attested.md", + sanitize_id(&normalized_id(repo, id)?) + )) +} + /// The directory that holds an intent's canonical sidecar artifacts: -/// `<dot_dir>/canonical/intents/<sanitized-id>/`. -pub fn sidecar_dir(repo: &Repository, id: &str) -> PathBuf { - repo.dot_dir() +/// `<dot_dir>/canonical/intents/<sanitized-normalized-id>/`. Keyed off the SAME +/// normalized id as the tracked vault path (critic #4). +pub fn sidecar_dir(repo: &Repository, id: &str) -> CliResult<PathBuf> { + Ok(repo + .dot_dir() .join("canonical") .join("intents") - .join(sanitize_id(id)) + .join(sanitize_id(&normalized_id(repo, id)?))) } /// The attested-node sidecar file for an intent. -pub fn attested_sidecar_path(repo: &Repository, id: &str) -> PathBuf { - sidecar_dir(repo, id).join("attested.jsonld") +pub fn attested_sidecar_path(repo: &Repository, id: &str) -> CliResult<PathBuf> { + Ok(sidecar_dir(repo, id)?.join("attested.jsonld")) +} + +/// Candidate legacy-sidecar paths, most-preferred first: the normalized-id path +/// (what the current `attest` writes) and the raw-arg path an M1a-era build +/// wrote (it sanitized the RAW CLI arg, un-normalized). Probing both lets the +/// dual-read fallback find pre-upgrade sidecars regardless of the id form the +/// original `attest` was invoked with. De-dups when the two coincide. +fn attested_sidecar_candidates(repo: &Repository, id: &str) -> CliResult<Vec<PathBuf>> { + let normalized = attested_sidecar_path(repo, id)?; + let raw = repo + .dot_dir() + .join("canonical") + .join("intents") + .join(sanitize_id(id)) + .join("attested.jsonld"); + let mut candidates = vec![normalized]; + if !candidates.contains(&raw) { + candidates.push(raw); + } + Ok(candidates) } /// A hash of the source lift inputs, recorded in the sidecar so a later edit to @@ -139,10 +224,47 @@ pub fn load_attestation( id: &str, inputs: &LiftInputs, ) -> CliResult<Attestation> { - let path = attested_sidecar_path(repo, id); - if !path.exists() { - return Ok(Attestation::None); + // 1) Tracked vault entry (new authoritative source). The body is the pretty + // JSON-LD node (+ a trailing '\n'); parse it straight to a CanonicalNode. + let vpath = attestation_vault_path(repo, id)?; + if let Some(entry) = repo.vault_retrieve(&vpath).map_err(CliError::Repository)? { + let raw = String::from_utf8_lossy(&entry.content_bytes); + match serde_json::from_str::<CanonicalNode>(raw.trim_end()) { + Ok(node) => { + // Staleness: prefer the frontmatter anchor `sourceContentHash`; + // frontmatter_json round-trips as a flat-scalar JSON object. + let recorded = serde_json::from_str::<Value>(&entry.frontmatter_json) + .ok() + .and_then(|v| { + v.get("sourceContentHash") + .and_then(Value::as_str) + .map(str::to_owned) + }); + let current = source_content_hash(inputs); + return Ok(match recorded { + Some(h) if h == current => Attestation::Fresh(Box::new(node)), + _ => Attestation::Stale(Box::new(node)), + }); + } + Err(e) => { + eprintln!("warning: ignoring malformed tracked attestation {vpath}: {e}"); + // fall through to the legacy sidecar + } + } } + + // 2) Legacy sidecar fallback (pre-upgrade attestations). Probe the + // normalized-id path first (what the current `attest` writes), then the + // raw-arg path an M1a-era build used (it sanitized the RAW CLI arg without + // normalizing), so a sidecar written via `attest 1` / `attest pimo-1` is + // still found after upgrade regardless of the id form (critic #4). + let path = match attested_sidecar_candidates(repo, id)? + .into_iter() + .find(|p| p.exists()) + { + Some(p) => p, + None => return Ok(Attestation::None), + }; let raw = std::fs::read_to_string(&path).map_err(CliError::Io)?; let artifact: Value = match serde_json::from_str(&raw) { Ok(v) => v, @@ -200,3 +322,241 @@ pub fn vault_path_for(repo: &Repository, id: &str) -> CliResult<Option<String>> .map(|(_, summary)| summary.vault_path.clone()) .filter(|p| !p.is_empty())) } + +#[cfg(test)] +mod tests { + use super::*; + use atomic_canonical::lift_and_attest; + use atomic_core::pristine::VaultEntryType; + use atomic_identity::identity::Identity; + use atomic_identity::keypair::KeyPair; + use atomic_repository::IntentCreateOptions; + use tempfile::tempdir; + + /// Build inputs for a minimal, liftable intent and attest them into a node. + fn attested_node(inputs: &LiftInputs) -> (CanonicalNode, KeyPair) { + let kp = KeyPair::generate(); + let id = Identity::new("tester", &kp); + let node = lift_and_attest(&inputs.frontmatter, &inputs.body, &id, &kp) + .expect("lift_and_attest on a minimal intent should succeed"); + (node, kp) + } + + /// Create a repo+vault and a single intent; return (repo, normalized id, + /// lift inputs for the stored intent). + fn repo_with_intent() -> (Repository, String, LiftInputs, tempfile::TempDir) { + let dir = tempdir().unwrap(); + let repo = Repository::init(dir.path()).unwrap(); + repo.init_vault().unwrap(); + let result = repo + .vault_intent_create(IntentCreateOptions { + title: "Test intent".to_string(), + priority: Some("medium".to_string()), + assignee: None, + labels: Vec::new(), + session_id: None, + turn_id: None, + }) + .unwrap(); + let id = result.id; + let inputs = read_intent(&repo, &id).unwrap(); + (repo, id, inputs, dir) + } + + /// Mirror `attest`'s tracked-vault write exactly (body = pretty JSON + '\n', + /// flat-string frontmatter anchors). + fn write_tracked(repo: &Repository, id: &str, node: &CanonicalNode, inputs: &LiftInputs) { + let mut body = serde_json::to_string_pretty(&node.to_value()).unwrap(); + body.push('\n'); + let mut fm = serde_json::Map::new(); + fm.insert("intentId".into(), Value::String(normalized_id(repo, id).unwrap())); + fm.insert( + "sourceContentHash".into(), + Value::String(source_content_hash(inputs)), + ); + let frontmatter_json = serde_json::to_string(&fm).unwrap(); + let vpath = attestation_vault_path(repo, id).unwrap(); + repo.vault_store( + &vpath, + VaultEntryType::Attestation, + body.into_bytes(), + frontmatter_json, + ) + .unwrap(); + } + + /// Mirror `attest`'s legacy sidecar write exactly ({node, source} wrapper). + fn write_legacy_sidecar(repo: &Repository, id: &str, node: &CanonicalNode, inputs: &LiftInputs) { + let path = attested_sidecar_path(repo, id).unwrap(); + std::fs::create_dir_all(path.parent().unwrap()).unwrap(); + let mut artifact = serde_json::Map::new(); + artifact.insert("node".to_string(), node.to_value()); + let mut source = serde_json::Map::new(); + source.insert( + "sourceContentHash".to_string(), + Value::String(source_content_hash(inputs)), + ); + artifact.insert("source".to_string(), Value::Object(source)); + std::fs::write( + &path, + serde_json::to_string_pretty(&Value::Object(artifact)).unwrap(), + ) + .unwrap(); + } + + #[test] + fn test_load_attestation_prefers_tracked_then_legacy() { + let (repo, id, inputs, _dir) = repo_with_intent(); + let (node, _kp) = attested_node(&inputs); + + // (a) Only a legacy sidecar present -> dual-read fallback returns Fresh. + write_legacy_sidecar(&repo, &id, &node, &inputs); + assert!(matches!( + load_attestation(&repo, &id, &inputs).unwrap(), + Attestation::Fresh(_) + )); + + // (b) A tracked entry present -> it is used (still Fresh). + write_tracked(&repo, &id, &node, &inputs); + assert!(matches!( + load_attestation(&repo, &id, &inputs).unwrap(), + Attestation::Fresh(_) + )); + + // (c) ID reconciliation (critic #4): `1`, `pimo-1`, `PIMO-1` all resolve + // the same attestation. The normalized manifest key is e.g. "NONA-1" + // (derived from the temp dir name); the bare number and lowercase + // forms must all resolve to it. + let lower = id.to_lowercase(); + let num = id.rsplit('-').next().unwrap().to_string(); + for alias in [id.as_str(), lower.as_str(), num.as_str()] { + assert_eq!( + attestation_vault_path(&repo, alias).unwrap(), + attestation_vault_path(&repo, &id).unwrap(), + "alias {alias} must resolve to the same tracked path" + ); + assert_eq!( + attested_sidecar_path(&repo, alias).unwrap(), + attested_sidecar_path(&repo, &id).unwrap(), + "alias {alias} must resolve to the same legacy sidecar path" + ); + assert!( + matches!( + load_attestation(&repo, alias, &inputs).unwrap(), + Attestation::Fresh(_) + ), + "alias {alias} must load the same Fresh attestation" + ); + } + } + + #[test] + fn test_tracked_entry_parses_and_verifies() { + // End-to-end at the persistence layer: writing the tracked entry + legacy + // sidecar exactly the way `attest` does, then (a) the tracked entry's body + // parses back to a CanonicalNode carrying a proof, (b) the legacy sidecar + // is also present (dual-write), (c) load_attestation reads the TRACKED + // entry, and (d) the parsed node cryptographically verifies against the + // signing key. + let (repo, id, inputs, _dir) = repo_with_intent(); + let (node, kp) = attested_node(&inputs); + write_tracked(&repo, &id, &node, &inputs); + write_legacy_sidecar(&repo, &id, &node, &inputs); + + // (a) tracked entry exists; body parses to a CanonicalNode with a proof. + let vpath = attestation_vault_path(&repo, &id).unwrap(); + let entry = repo.vault_retrieve(&vpath).unwrap().expect("tracked entry"); + assert_eq!(entry.entry_type, VaultEntryType::Attestation); + let raw = String::from_utf8_lossy(&entry.content_bytes); + let parsed: CanonicalNode = serde_json::from_str(raw.trim_end()).unwrap(); + assert!(parsed.proof.is_some(), "tracked node must carry a proof"); + assert!(parsed.content_hash.is_some()); + // Body ends in exactly one trailing newline (critic #1 invariant). + assert!(raw.ends_with('\n') && !raw.ends_with("\n\n")); + + // (b) legacy sidecar also written. + assert!(attested_sidecar_path(&repo, &id).unwrap().exists()); + + // (c) load_attestation returns the tracked node as Fresh. + let loaded = match load_attestation(&repo, &id, &inputs).unwrap() { + Attestation::Fresh(n) => *n, + Attestation::Stale(_) => panic!("expected Fresh, got Stale"), + Attestation::None => panic!("expected Fresh, got None"), + }; + + // (d) the loaded node verifies against the signing key. + atomic_canonical::verify(&loaded, &kp.public).expect("tracked node must verify"); + } + + #[test] + fn test_attestation_staleness() { + let (repo, id, inputs, _dir) = repo_with_intent(); + let (node, _kp) = attested_node(&inputs); + write_tracked(&repo, &id, &node, &inputs); + + // Fresh against the original inputs. + assert!(matches!( + load_attestation(&repo, &id, &inputs).unwrap(), + Attestation::Fresh(_) + )); + + // Simulate an edit to the intent body: the current source hash no longer + // matches the recorded anchor -> Stale. + let edited = LiftInputs { + frontmatter: inputs.frontmatter.clone(), + body: format!("{}\n<!-- edited -->", inputs.body), + }; + assert!(matches!( + load_attestation(&repo, &id, &edited).unwrap(), + Attestation::Stale(_) + )); + } + + #[test] + fn test_legacy_sidecar_raw_arg_fallback_is_found() { + // An M1a-era `attest <raw-arg>` sanitized the RAW arg without normalizing, + // so a bare-number/lowercase invocation wrote the sidecar under that + // literal form (e.g. .atomic/canonical/intents/1/attested.jsonld). After + // upgrade the reader normalizes ids; the raw-arg candidate probe must + // still find such a pre-upgrade sidecar. + let (repo, id, inputs, _dir) = repo_with_intent(); + let (node, _kp) = attested_node(&inputs); + + // The bare-number alias (e.g. "1" for "NONA-1"). + let num = id.rsplit('-').next().unwrap().to_string(); + let normalized = attested_sidecar_path(&repo, &num).unwrap(); + + // Write the sidecar at the RAW-arg location an M1a build used. + let raw_dir = repo + .dot_dir() + .join("canonical") + .join("intents") + .join(sanitize_id(&num)); + std::fs::create_dir_all(&raw_dir).unwrap(); + let raw_path = raw_dir.join("attested.jsonld"); + assert_ne!( + raw_path, normalized, + "raw-arg path must differ from the normalized path for this test to be meaningful" + ); + let mut artifact = serde_json::Map::new(); + artifact.insert("node".to_string(), node.to_value()); + let mut source = serde_json::Map::new(); + source.insert( + "sourceContentHash".to_string(), + Value::String(source_content_hash(&inputs)), + ); + artifact.insert("source".to_string(), Value::Object(source)); + std::fs::write( + &raw_path, + serde_json::to_string_pretty(&Value::Object(artifact)).unwrap(), + ) + .unwrap(); + + // No tracked entry and no normalized-path sidecar exist; the raw-arg + // probe must still find it -> Fresh. + assert!(matches!( + load_attestation(&repo, &num, &inputs).unwrap(), + Attestation::Fresh(_) + )); + } +} diff --git a/atomic-core/src/pristine/vault.rs b/atomic-core/src/pristine/vault.rs index 27a324a7..a9aa929f 100644 --- a/atomic-core/src/pristine/vault.rs +++ b/atomic-core/src/pristine/vault.rs @@ -11,12 +11,18 @@ use std::collections::HashMap; #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum VaultEntryType { - Session, - ToolResult, - Memory, - Intent, - Skill, - Scratch, + Session, // 0 + ToolResult, // 1 + Memory, // 2 + Intent, // 3 + Skill, // 4 + Scratch, // 5 + /// Signed Recording-the-Why attestation (JSON-LD body). Index 6 — APPEND-ONLY. + /// postcard encodes enum discriminants positionally, so this MUST stay last and + /// MUST NOT be reordered/inserted/deleted. Mixed-version sync caveat: an older + /// binary that predates this variant cannot postcard-decode an Attestation row + /// and will error on that entry; newer readers are unaffected. + Attestation, // 6 } impl VaultEntryType { @@ -28,6 +34,7 @@ impl VaultEntryType { Self::Intent => "intent", Self::Skill => "skill", Self::Scratch => "scratch", + Self::Attestation => "attestation", } } @@ -47,6 +54,7 @@ impl std::str::FromStr for VaultEntryType { "intent" => Ok(Self::Intent), "skill" => Ok(Self::Skill), "scratch" => Ok(Self::Scratch), + "attestation" => Ok(Self::Attestation), _ => Err(format!("unknown vault entry type: {s}")), } } @@ -490,6 +498,7 @@ mod tests { (VaultEntryType::Intent, "intent"), (VaultEntryType::Skill, "skill"), (VaultEntryType::Scratch, "scratch"), + (VaultEntryType::Attestation, "attestation"), ]; for (ty, expected_str) in &types { @@ -501,6 +510,35 @@ mod tests { assert_eq!(VaultEntryType::parse("unknown"), None); } + #[test] + fn test_vault_entry_type_roundtrip() { + // as_str / from_str / Display round-trip for the appended Attestation + // variant. + assert_eq!(VaultEntryType::Attestation.as_str(), "attestation"); + assert_eq!(VaultEntryType::Attestation.to_string(), "attestation"); + assert_eq!( + "attestation".parse::<VaultEntryType>().unwrap(), + VaultEntryType::Attestation + ); + + // postcard encodes the enum discriminant positionally: Attestation is + // index 6 (last). Round-trip a full VaultEntry through postcard and + // confirm the discriminant decodes back to Attestation. + let entry = VaultEntry::new( + VaultEntryType::Attestation, + b"{\"@id\":\"x\"}\n".to_vec(), + "{}".to_string(), + "2025-01-15T12:00:00Z".to_string(), + ); + let bytes = postcard::to_allocvec(&entry).expect("serialize"); + let decoded: VaultEntry = postcard::from_bytes(&bytes).expect("deserialize"); + assert_eq!(decoded.entry_type, VaultEntryType::Attestation); + // Positional discriminant sanity: the first byte encodes the variant + // index (6) for this small enum. + let ty_bytes = postcard::to_allocvec(&VaultEntryType::Attestation).expect("serialize ty"); + assert_eq!(ty_bytes, vec![6]); + } + #[test] fn vault_manifest_default() { let manifest = VaultManifest::default(); diff --git a/atomic-repository/src/repository/vault.rs b/atomic-repository/src/repository/vault.rs index 10ee8151..0b6b2cad 100644 --- a/atomic-repository/src/repository/vault.rs +++ b/atomic-repository/src/repository/vault.rs @@ -231,11 +231,24 @@ impl Repository { /// Called as a side effect of `vault_store` and `vault_store_entry`. /// Best-effort — logs on failure but never fails the parent operation. fn vault_auto_index(&self, path: &str) { - // KG indexing + // Signed attestation blobs must not pollute semantic search, and they + // contribute no KG triples (vault_extract_kg early-returns empty for + // Attestation). Skip embedding entirely for them. + let is_attestation = matches!( + self.vault_retrieve(path), + Ok(Some(e)) if e.entry_type == VaultEntryType::Attestation + ); + + // KG indexing — safe: extract_kg returns empty for Attestation, so + // vault_store_kg deletes any stale rows and stores nothing. if let Err(e) = self.vault_index_kg(path) { log::debug!("Auto KG index for {}: {}", path, e); } + if is_attestation { + return; // do NOT embed + } + // Embedding let provider = crate::ai::resolve_embedding_provider(); let config = EmbedConfig { @@ -948,6 +961,8 @@ fn infer_entry_type(path: &str) -> VaultEntryType { VaultEntryType::Skill } else if path.starts_with("intents/") { VaultEntryType::Intent + } else if path.starts_with("attestations/") { + VaultEntryType::Attestation } else { // scratch/ prefix or any unknown path VaultEntryType::Scratch @@ -1446,6 +1461,74 @@ mod tests { ); assert_eq!(infer_entry_type("scratch/idea.md"), VaultEntryType::Scratch); assert_eq!(infer_entry_type("unknown/file.md"), VaultEntryType::Scratch); + assert_eq!( + infer_entry_type("attestations/PIMO-1/attested.md"), + VaultEntryType::Attestation + ); + } + + #[test] + fn test_attestation_entry_scan_unchanged() { + // The trailing-newline byte-identity invariant (critic #1): the stored + // content_bytes end in exactly one '\n', so render_entry_to_markdown + // appends NO extra newline and the first vault_scan sees the + // materialized body's hash == the stored blake3(content) == Unchanged. + let dir = tempdir().unwrap(); + let repo = Repository::init(dir.path()).unwrap(); + repo.init_vault().unwrap(); + + // Body = pretty JSON + a single trailing '\n' (exactly how attest builds it). + let node_json = + serde_json::to_string_pretty(&serde_json::json!({"@id": "atomic:intent:PIMO-1"})) + .unwrap(); + let mut body = node_json; + body.push('\n'); + let body_bytes = body.clone().into_bytes(); + + let path = "attestations/PIMO-1/attested.md"; + let stored_hash = repo + .vault_store( + path, + VaultEntryType::Attestation, + body_bytes.clone(), + r#"{"intentId":"PIMO-1"}"#.to_string(), + ) + .unwrap(); + + // The stored content hash is blake3 of the body-with-newline (unchanged + // storage-hash semantics). + assert_eq!(stored_hash, Hash::of(&body_bytes)); + let retrieved = repo.vault_retrieve(path).unwrap().unwrap(); + assert_eq!(Hash::from_bytes(retrieved.content_hash), Hash::of(&body_bytes)); + + // Materialize to disk, then scan: the materialized body must hash back to + // the exact same value, so the entry is Unchanged (no change reported). + repo.vault_materialize(path).unwrap(); + let changes = repo.vault_scan_working_copy().unwrap(); + assert!( + !changes.iter().any(|c| c.path == path), + "attestation entry must scan as Unchanged; got changes: {changes:?}" + ); + } + + #[test] + fn test_attestation_not_embedded() { + // The guard in vault_auto_index must skip embedding for Attestation + // entries (signed blobs must not pollute semantic search). + let dir = tempdir().unwrap(); + let repo = Repository::init(dir.path()).unwrap(); + repo.init_vault().unwrap(); + + let before = repo.vault_embedding_count().unwrap(); + repo.vault_store( + "attestations/PIMO-1/attested.md", + VaultEntryType::Attestation, + b"{\n \"@id\": \"atomic:intent:PIMO-1\"\n}\n".to_vec(), + r#"{"intentId":"PIMO-1"}"#.to_string(), + ) + .unwrap(); + let after = repo.vault_embedding_count().unwrap(); + assert_eq!(before, after, "attestation entry must not be embedded"); } #[test] diff --git a/atomic-repository/src/repository/vault_triples.rs b/atomic-repository/src/repository/vault_triples.rs index d0855ebe..4f1e9a41 100644 --- a/atomic-repository/src/repository/vault_triples.rs +++ b/atomic-repository/src/repository/vault_triples.rs @@ -45,6 +45,7 @@ impl Repository { VaultEntryType::Skill => "skill", VaultEntryType::ToolResult => "tool_result", VaultEntryType::Scratch => return Ok((nodes, edges)), // no KG data for scratch + VaultEntryType::Attestation => return Ok((nodes, edges)), // signed blob: no KG data }; // Derive a label from the subject (the part after the colon) @@ -557,6 +558,14 @@ fn entry_subject(path: &str, entry_type: VaultEntryType) -> String { VaultEntryType::Scratch => { format!("scratch:{}", path.replace('/', ":")) } + VaultEntryType::Attestation => { + // attestations/<sanitized-intent-id>/attested.md -> attestation:<sanitized-intent-id> + let name = path + .strip_prefix("attestations/") + .and_then(|s| s.strip_suffix("/attested.md")) + .unwrap_or(path); + format!("attestation:{}", name) + } } } @@ -1011,6 +1020,10 @@ mod tests { entry_subject("skills/run-tests.md", VaultEntryType::Skill), "skill:run-tests" ); + assert_eq!( + entry_subject("attestations/PIMO-1/attested.md", VaultEntryType::Attestation), + "attestation:PIMO-1" + ); } #[test] @@ -1092,6 +1105,28 @@ mod tests { assert!(edges.is_empty()); } + #[test] + fn test_extract_attestation_returns_empty() { + let dir = tempdir().unwrap(); + let repo = Repository::init(dir.path()).unwrap(); + repo.init_vault().unwrap(); + + // A signed attestation blob contributes ZERO KG nodes/edges (the kind + // match early-returns empty, mirroring Scratch). + let entry = VaultEntry::new( + VaultEntryType::Attestation, + b"{\"@id\":\"atomic:intent:PIMO-1\"}\n".to_vec(), + r#"{"intentId":"PIMO-1"}"#.to_string(), + "2025-01-01T00:00:00Z".to_string(), + ); + + let (nodes, edges) = repo + .vault_extract_kg("attestations/PIMO-1/attested.md", &entry) + .unwrap(); + assert!(nodes.is_empty()); + assert!(edges.is_empty()); + } + #[test] fn test_frontmatter_intent_blocked_by() { let mut node = KgNode::new("intent:PIMO-1", "intent", "PIMO-1", "vault"); diff --git a/docs/recording-the-why.md b/docs/recording-the-why.md index eee209e3..b17b8cb5 100644 --- a/docs/recording-the-why.md +++ b/docs/recording-the-why.md @@ -210,6 +210,12 @@ XML has the properties we need (draconian parsing, XSD schemas, C14N canonicaliz JSON-LD gives us `@type` for node types, `@id` for stable identity, typed references as first-class edges, JSON Schema for validation, and JCS (RFC 8785\) for deterministic bytes to hash. Agents emit JSON well under load. And because JSON-LD is RDF, we get the PROV vocabulary for provenance and the Data Integrity proof standard for signing, both of which are native to the linked-data ecosystem. +### **Where an attestation lives** + +An attestation is now a first-class **tracked vault entry** (entry_type `attestation`) at `attestations/<intent-id>/attested.md`, not a loose sidecar. Its body is the signed JSON-LD node exactly as produced by the lift-and-sign step. The vault's storage hash over that entry stays `blake3(body)` — the same content-addressed primitive every other vault entry uses — and the node's own `contentHash` and `eddsa-jcs-2022` proof live *inside* that body, opaque to the storage hash. Two independent digests, two independent jobs: the storage hash tells the vault whether the bytes on disk match what was recorded, and the node's `contentHash` + proof tell a verifier whether the signed facts are intact and who signed them. + +Because it's a tracked entry, an attestation flows through the ordinary `atomic record` path and lands in the change graph like anything else — the patch graph stays canonical, and there is no triplestore. The triple view remains a projection we compute and discard. During the transition an attestation is dual-written to the legacy `.atomic/canonical/intents/<intent-id>/attested.jsonld` sidecar as well, and readers prefer the tracked entry, falling back to the sidecar so pre-upgrade attestations keep verifying. + ### **The lift** The lift is a typed extractor that reads the authored markdown and produces canonical nodes. Frontmatter keys map to spine properties. Directive names map to node types. Directive attributes map to typed properties and edges. Prose inside directive fences becomes the unconstrained text slot. Everything the lift doesn't have a rule for stays in the body as unlifted narrative, and that's correct, because the moment you try to schematize the why you're back to the Copilot Summary failure. From 4fd2f33ea45431b999f5fbfa92b6d75454750353 Mon Sep 17 00:00:00 2001 From: Bradley Hilton <graywolf336@craftyn.com> Date: Thu, 2 Jul 2026 10:57:15 -0500 Subject: [PATCH 05/21] feat(cli): add top-level `atomic memory` verbs (canonical RtW surface) Mirrors `atomic intent` for memories: `atomic memory {new,show,validate,attest, verify}`, driving the atomic-canonical engine (lift_memory / validate_memory / verify_memory / render_memory) and REUSING the tracked-attestation entry mechanism from d63713c. The raw `atomic vault memory {list,show,write}` is left untouched as the legacy layer (preserves the agent stdin write flow); this is the two-layer design decided for the CLI surface. - New command family under atomic-cli/src/commands/memory/ (mod/new/show/ validate/attest/verify/bridge), registered top-level in main.rs + commands/mod.rs. - Memories have no PREFIX-N id and no dedicated repository create method, so `memory new` writes directly via the generic vault_store + vault_materialize (same path as raw `vault memory write`) at `memory/<id>.md`, with a fresh lowercased ULID id and a STABLE `createdAt` in the spine (load-bearing: it is signed, so re-lift must reproduce byte-identical signing bytes). --kind and --status are both validated early against their closed sets. - attest signs a MemoryNode and writes the tracked attestation entry, namespaced at `attestations/memory/<id>/attested.md` (avoids intent/memory id collisions), dual-writing the legacy sidecar; validate/show/verify read it back (tracked preferred, sidecar fallback), staleness via the existing source_content_hash. No content_hash / merkle / hashing change; no intent_dir_for (collapse bug). Verified end-to-end (isolated HOME): memory new -> validate(no) -> attest -> validate(yes) -> verify(ok); tracked `attestation` + `memory` entries both in `vault list`. Tests: atomic-cli 1550 + 9 (12 new memory tests), atomic-canonical 51 unchanged; clippy clean. atomic-canonical, atomic-core, and the raw `atomic vault memory` are untouched. --- atomic-cli/src/commands/memory/attest.rs | 258 ++++++++++++ atomic-cli/src/commands/memory/bridge.rs | 467 +++++++++++++++++++++ atomic-cli/src/commands/memory/mod.rs | 344 +++++++++++++++ atomic-cli/src/commands/memory/new.rs | 235 +++++++++++ atomic-cli/src/commands/memory/show.rs | 59 +++ atomic-cli/src/commands/memory/validate.rs | 159 +++++++ atomic-cli/src/commands/memory/verify.rs | 98 +++++ atomic-cli/src/commands/mod.rs | 2 + atomic-cli/src/main.rs | 25 ++ 9 files changed, 1647 insertions(+) create mode 100644 atomic-cli/src/commands/memory/attest.rs create mode 100644 atomic-cli/src/commands/memory/bridge.rs create mode 100644 atomic-cli/src/commands/memory/mod.rs create mode 100644 atomic-cli/src/commands/memory/new.rs create mode 100644 atomic-cli/src/commands/memory/show.rs create mode 100644 atomic-cli/src/commands/memory/validate.rs create mode 100644 atomic-cli/src/commands/memory/verify.rs diff --git a/atomic-cli/src/commands/memory/attest.rs b/atomic-cli/src/commands/memory/attest.rs new file mode 100644 index 00000000..6680f8ff --- /dev/null +++ b/atomic-cli/src/commands/memory/attest.rs @@ -0,0 +1,258 @@ +//! `atomic memory attest <ID>` — sign a memory into a tracked vault entry +//! (dual-written to a legacy sidecar during the transition). + +use clap::Parser; + +use serde_json::Value; + +use atomic_canonical::{lift_and_attest_memory, validate_memory, verify_memory}; +use atomic_core::pristine::VaultEntryType; +use atomic_identity::IdentityStore; +use atomic_repository::Repository; + +use crate::commands::memory::bridge; +use crate::commands::memory::validation_failed; +use crate::commands::{find_repository_root, Command}; +use crate::error::{CliError, CliResult}; + +/// Attest a memory: gate it, sign it, and write the attested node. +#[derive(Parser, Debug)] +#[command(name = "attest")] +pub struct MemoryAttest { + /// Memory id (or `memory/<id>.md` path). + pub id: String, + + /// Identity to sign with. Defaults to the current default identity. + #[arg(long)] + pub identity: Option<String>, + + /// Output the attested node as JSON-LD. + #[arg(long)] + pub json: bool, +} + +impl Command for MemoryAttest { + fn run(&self) -> CliResult<()> { + let root = find_repository_root()?; + let repo = Repository::open(&root).map_err(CliError::Repository)?; + + let inputs = bridge::read_memory(&repo, &self.id)?; + + // FIRST gate WITHOUT signing: refuse to sign a node that fails for a + // reason attestation cannot fix (unknown memoryKind/status, empty text). + // Missing proof/attributedTo are the expected pre-attest violations — + // exactly what signing fills — so we only refuse on violations OUTSIDE + // that fillable set. + let unattested = bridge::lift(&inputs)?; + let pre = validate_memory(&unattested); + let blocking: Vec<_> = pre + .results + .iter() + .filter(|v| !is_fillable_by_attest(v.path.as_deref())) + .collect(); + if !blocking.is_empty() { + eprintln!("Cannot attest {}: the memory does not conform.", self.id); + eprint!("{pre}"); + return Err(validation_failed(format!( + "memory {} does not conform; fix the violations above before attesting \ + (run `atomic memory validate {}`)", + self.id, self.id + ))); + } + + // Resolve identity + keypair the way `atomic identity sign` does. + let store = IdentityStore::open_default().map_err(|e| { + CliError::Internal(anyhow::anyhow!("Failed to open identity store: {}", e)) + })?; + let identity = if let Some(name) = &self.identity { + store + .load_by_name(name) + .map_err(|_| CliError::IdentityNotFound(name.clone()))? + } else { + store + .get_default() + .map_err(|e| { + CliError::Internal(anyhow::anyhow!("Failed to load default identity: {}", e)) + })? + .ok_or_else(|| { + CliError::Internal(anyhow::anyhow!( + "No default identity set. Create one first:\n \ + atomic identity new <name> --email <email> --set-default" + )) + })? + }; + let keypair = store.load_keypair(&identity.id, None).map_err(|e| { + CliError::Internal(anyhow::anyhow!( + "Failed to load keypair for '{}': {}", + identity.name, + e + )) + })?; + + // Attest: lift + fill attributedTo (from the identity's did:atomic when + // absent) + hash + sign. + let node = lift_and_attest_memory(&inputs.frontmatter, &inputs.body, &identity, &keypair) + .map_err(|e| CliError::InvalidArgument { + message: format!("could not attest memory: {e}"), + })?; + + // Belt-and-suspenders: re-gate the ATTESTED node — proof + attributedTo + // must now satisfy the gate. + let post = validate_memory(&node); + if !post.conforms { + eprint!("{post}"); + return Err(validation_failed(format!( + "attested memory {} still does not conform; refusing to persist", + self.id + ))); + } + + // Self-check: the proof verifies against the signing key before we write. + verify_memory(&node, &keypair.public).map_err(|e| CliError::InvalidArgument { + message: format!("attested memory failed self-verification: {e}"), + })?; + + // --- Legacy sidecar dual-write (transition) --------------------------- + // Persist the attested node under `.atomic/canonical/memory/<id>/` — NOT + // into redb, NOT into the .vault/ tree. Never touches content_hash or + // the manifest merkle. `load_attestation` prefers the tracked entry + // below and shadows this copy. + let sidecar_path = bridge::attested_sidecar_path(&repo, &self.id); + if let Some(parent) = sidecar_path.parent() { + std::fs::create_dir_all(parent).map_err(CliError::Io)?; + } + let mut artifact = serde_json::Map::new(); + artifact.insert("node".to_string(), node.to_value()); + let mut source = serde_json::Map::new(); + source.insert( + "sourceContentHash".to_string(), + Value::String(bridge::source_content_hash(&inputs)), + ); + artifact.insert("source".to_string(), Value::Object(source)); + std::fs::write( + &sidecar_path, + serde_json::to_string_pretty(&Value::Object(artifact)).unwrap(), + ) + .map_err(CliError::Io)?; + + // --- Tracked vault entry (new authoritative source) ------------------- + // Store JUST the attested node (not the {node,source} wrapper) as the + // body, so it parses straight back to a MemoryNode on read. + let mut body = serde_json::to_string_pretty(&node.to_value()) + .expect("memory node serialization is infallible"); + // Pre-append the trailing newline so materialize is a byte-identity + // transform on the body (the first vault_scan sees Unchanged). + body.push('\n'); + let content_bytes = body.into_bytes(); + + // Frontmatter anchors — FLAT SCALAR strings only, so they survive + // yaml_frontmatter_to_json. `sourceContentHash` contains ':' but no + // ": " (colon-space), so it round-trips cleanly. + let mut fm = serde_json::Map::new(); + fm.insert("memoryId".into(), Value::String(bridge::memory_id(&self.id))); + fm.insert( + "sourceContentHash".into(), + Value::String(bridge::source_content_hash(&inputs)), + ); + let frontmatter_json = serde_json::to_string(&fm).unwrap(); + + let vault_path = bridge::attestation_vault_path(&self.id); + repo.vault_store( + &vault_path, + VaultEntryType::Attestation, + content_bytes, + frontmatter_json, + ) + .map_err(CliError::Repository)?; + + let did = node.attributed_to.as_deref().unwrap_or("(unknown)"); + let proof_prefix = node + .proof + .as_ref() + .map(|p| p.proof_value.chars().take(12).collect::<String>()) + .unwrap_or_default(); + + if self.json { + println!("{}", serde_json::to_string_pretty(&node.to_value()).unwrap()); + } else { + println!("Attested memory: {}", self.id); + println!(" vault: .vault/{vault_path}"); + println!(" sidecar: {}", sidecar_path.display()); + println!(" author: {did}"); + println!(" proof: {proof_prefix}…"); + eprintln!( + "note: signing keys are stored unencrypted on disk; treat this \ + attestation as a non-production dev signature until key-at-rest \ + encryption lands." + ); + } + + Ok(()) + } +} + +/// Is a pre-attest violation on this property path one that attestation fills +/// (and therefore not a reason to refuse signing)? Only `proof` and +/// `attributedTo` are filled by `lift_and_attest_memory` — the SAME fillable set +/// as intent. +fn is_fillable_by_attest(path: Option<&str>) -> bool { + matches!(path, Some("proof") | Some("attributedTo")) +} + +#[cfg(test)] +mod tests { + use super::*; + use atomic_canonical::memory::lift_memory; + use serde_json::{Map, Value}; + use tempfile::tempdir; + + /// A memory with a NON-fillable violation (bad memoryKind) must be refused + /// by the pre-gate, and NO attestation entry should be written. + #[test] + fn test_attest_refuses_non_fillable_violation() { + let dir = tempdir().unwrap(); + let repo = Repository::init(dir.path()).unwrap(); + repo.init_vault().unwrap(); + + // A bad memoryKind is a non-fillable violation. + let fm: Map<String, Value> = serde_json::json!({ + "uid": "badkind01", + "memoryKind": "not-a-kind", + "status": "active", + "createdAt": "2026-07-01T00:00:00+00:00", + }) + .as_object() + .unwrap() + .clone(); + let body = ":::memory\nThe durable fact.\n:::"; + let vault_path = bridge::normalize_memory_path("badkind01"); + repo.vault_store( + &vault_path, + VaultEntryType::Memory, + body.as_bytes().to_vec(), + serde_json::to_string(&fm).unwrap(), + ) + .unwrap(); + + // Simulate the pre-gate directly (the CLI resolves the repo via + // find_repository_root; here we exercise the same refusal logic). + let node = lift_memory(&fm, body).unwrap(); + let report = validate_memory(&node); + let blocking: Vec<_> = report + .results + .iter() + .filter(|v| !is_fillable_by_attest(v.path.as_deref())) + .collect(); + assert!( + !blocking.is_empty(), + "a bad memoryKind is a blocking (non-fillable) violation" + ); + + // No attestation entry was written. + let apath = bridge::attestation_vault_path("badkind01"); + assert!( + repo.vault_retrieve(&apath).unwrap().is_none(), + "attest must not persist an attestation for a non-conforming memory" + ); + } +} diff --git a/atomic-cli/src/commands/memory/bridge.rs b/atomic-cli/src/commands/memory/bridge.rs new file mode 100644 index 00000000..a272b4fe --- /dev/null +++ b/atomic-cli/src/commands/memory/bridge.rs @@ -0,0 +1,467 @@ +//! The read→lift bridge and attestation plumbing shared by the `atomic memory` +//! verbs — the memory sibling of [`crate::commands::intent::bridge`]. +//! +//! # Read bridge +//! +//! Memories have NO dedicated repository create/show/update method (unlike +//! intents, which have `vault_intent_create`/`vault_intent_show`/ +//! `vault_intent_update`). A stored memory is read via the GENERIC vault path +//! [`Repository::vault_retrieve`] by its exact path `memory/<id>.md` — the same +//! path the raw `atomic vault memory write/show` uses. The returned `VaultEntry` +//! carries the two lift inputs: +//! +//! - `frontmatter_json: String` — a JSON *object* string (empty entries are +//! `"{}"`). This is the pre-parsed frontmatter spine; it is fed straight to +//! the lift. The body is NOT routed through `parse_markdown` for the vault +//! path, because the stored `content_bytes` is the body WITHOUT any +//! frontmatter block and `lift_memory` does its own lenient `:::memory` scan. +//! - `content_bytes: Vec<u8>` — the markdown body. +//! +//! # Id / path scheme (memory-local, NOT the intent normalizer) +//! +//! Memories are NOT `PREFIX-N` and have no prefix allocator. The id is the +//! filename stem and the vault path is `memory/<id>.md`. There is NO manifest +//! lookup / case-folding / prefix expansion — the manifest key IS the path. +//! [`normalize_memory_path`] is the single resolver; it deliberately does NOT +//! reuse the intent `normalize_intent_id`/`intent_dir_for` machinery (which +//! would reintroduce the 0.8.0 intent-collapse bug). +//! +//! # Attestation persistence (tracked vault entry, dual-read) +//! +//! Identical mechanism to the intent bridge (d63713c): the attestation is a +//! FIRST-CLASS TRACKED vault entry at `attestations/memory/<id>/attested.md` +//! (entry_type `attestation`), namespaced under `attestations/memory/` so a +//! memory id can never collide with an intent human key at +//! `attestations/<ID>/attested.md`. The body is the signed JSON-LD `MemoryNode` +//! (pretty-printed + a trailing `\n` so materialize is a byte-identity +//! transform); the vault's storage hash stays `blake3(body)`. `attest` also +//! DUAL-WRITES the legacy sidecar under +//! `<repo.dot_dir()>/canonical/memory/<id>/attested.jsonld`. [`load_attestation`] +//! PREFERS the tracked entry and falls back to the legacy sidecar. + +use std::path::PathBuf; + +use serde_json::{Map, Value}; + +use atomic_canonical::memory::lift_memory; +use atomic_canonical::MemoryNode; +use atomic_core::pristine::VaultEntry; +use atomic_repository::Repository; + +use crate::error::{CliError, CliResult}; + +/// The two lift inputs pulled off a stored memory `VaultEntry`. +pub struct MemLiftInputs { + /// The parsed frontmatter spine (a JSON object). + pub frontmatter: Map<String, Value>, + /// The markdown body (without any frontmatter block). + pub body: String, +} + +/// Normalize a bare id, a `memory/<id>` path, an `<id>.md` name, or a full +/// `memory/<id>.md` path all to the canonical vault path `memory/<id>.md`. +/// +/// This is the SINGLE memory id/path resolver: no manifest lookup, no prefix, +/// no case-folding — the manifest key IS the path (contrast the intent +/// normalizer, which is deliberately NOT reused). A memory is a single flat +/// file per id, never a directory. +pub fn normalize_memory_path(id_or_path: &str) -> String { + let without_prefix = id_or_path.strip_prefix("memory/").unwrap_or(id_or_path); + let stem = without_prefix.strip_suffix(".md").unwrap_or(without_prefix); + format!("memory/{stem}.md") +} + +/// The `<id>` stem for a bare id or any accepted path form. Used both to build +/// the human-facing messages and (sanitized) to KEY the attestation path. +pub fn memory_id(id_or_path: &str) -> String { + let path = normalize_memory_path(id_or_path); + path.strip_prefix("memory/") + .and_then(|s| s.strip_suffix(".md")) + .unwrap_or(&path) + .to_string() +} + +/// Parse a memory `VaultEntry` into the frontmatter map + body the lift consumes. +/// +/// `frontmatter_json` is parsed exactly as the repository parses it +/// (`serde_json::from_str` into a `Map`). A malformed frontmatter string is a +/// clean argument error rather than an internal panic. +pub fn inputs_from_entry(entry: &VaultEntry) -> CliResult<MemLiftInputs> { + let frontmatter: Map<String, Value> = serde_json::from_str(&entry.frontmatter_json) + .map_err(|e| CliError::InvalidArgument { + message: format!("memory frontmatter is not valid JSON: {e}"), + })?; + let body = String::from_utf8_lossy(&entry.content_bytes).into_owned(); + Ok(MemLiftInputs { frontmatter, body }) +} + +/// Read a memory by id (or path) from the vault and return its lift inputs. +pub fn read_memory(repo: &Repository, id_or_path: &str) -> CliResult<MemLiftInputs> { + let path = normalize_memory_path(id_or_path); + let entry = repo + .vault_retrieve(&path) + .map_err(CliError::Repository)? + .ok_or_else(|| CliError::InvalidArgument { + message: format!( + "memory not found: {id_or_path} (create with `atomic memory new`)" + ), + })?; + inputs_from_entry(&entry) +} + +/// Lift the given inputs into a canonical `MemoryNode`, mapping a lift failure +/// (missing `uid`, missing `memoryKind`, …) to a clean argument error. +pub fn lift(inputs: &MemLiftInputs) -> CliResult<MemoryNode> { + lift_memory(&inputs.frontmatter, &inputs.body).map_err(|e| CliError::InvalidArgument { + message: format!("could not lift memory: {e}"), + }) +} + +/// Sanitize a memory id for use as a directory name in the sidecar/vault path. +/// Keeps ASCII alphanumerics, `-` and `_`; everything else becomes `_`. +/// Copied verbatim from `intent/bridge.rs::sanitize_id`. +fn sanitize_id(id: &str) -> String { + id.chars() + .map(|c| { + if c.is_ascii_alphanumeric() || c == '-' || c == '_' { + c + } else { + '_' + } + }) + .collect() +} + +/// The tracked-vault path for a memory's attestation: +/// `attestations/memory/<sanitized-id>/attested.md`. +/// +/// NOTE the `attestations/memory/` sub-namespace: a memory id can therefore +/// never collide with an intent human key at `attestations/<ID>/attested.md`. +/// `infer_entry_type` maps any `attestations/` prefix to `Attestation`, so this +/// needs no atomic-repository change. +pub fn attestation_vault_path(id_or_path: &str) -> String { + format!( + "attestations/memory/{}/attested.md", + sanitize_id(&memory_id(id_or_path)) + ) +} + +/// The directory that holds a memory's canonical sidecar artifacts: +/// `<dot_dir>/canonical/memory/<sanitized-id>/`. +pub fn sidecar_dir(repo: &Repository, id_or_path: &str) -> PathBuf { + repo.dot_dir() + .join("canonical") + .join("memory") + .join(sanitize_id(&memory_id(id_or_path))) +} + +/// The attested-node sidecar file for a memory. +pub fn attested_sidecar_path(repo: &Repository, id_or_path: &str) -> PathBuf { + sidecar_dir(repo, id_or_path).join("attested.jsonld") +} + +/// A hash of the source lift inputs, recorded so a later edit to the memory can +/// be detected as making the attestation stale. Standalone digest of +/// (frontmatter + body); NOT the vault's `content_hash`. Copied verbatim from +/// `intent/bridge.rs::source_content_hash`. +pub fn source_content_hash(inputs: &MemLiftInputs) -> String { + let fm = serde_json::to_string(&inputs.frontmatter).unwrap_or_default(); + let mut hasher = blake3::Hasher::new(); + hasher.update(fm.as_bytes()); + hasher.update(b"\0"); + hasher.update(inputs.body.as_bytes()); + format!("blake3:{}", hasher.finalize().to_hex()) +} + +/// The state of a memory's attestation relative to the current source. +pub enum Attestation { + /// No attestation on disk (tracked or legacy). + None, + /// Attestation present and its recorded source hash matches the current memory. + Fresh(Box<MemoryNode>), + /// Attestation present but the memory changed since it was signed. + Stale(Box<MemoryNode>), +} + +/// Load a memory's attestation and classify it against the current source +/// (`inputs`). Prefers the tracked vault entry, falling back to the legacy +/// sidecar. A missing attestation is `None`; a corrupt/malformed one is treated +/// as `None`/skipped with a warning (fail-open, so a read still works on the +/// raw node). Same mechanism as the intent bridge. +pub fn load_attestation( + repo: &Repository, + id_or_path: &str, + inputs: &MemLiftInputs, +) -> CliResult<Attestation> { + // 1) Tracked vault entry (authoritative). The body is the pretty JSON-LD + // node (+ trailing '\n'); parse it straight to a MemoryNode. + let vpath = attestation_vault_path(id_or_path); + if let Some(entry) = repo.vault_retrieve(&vpath).map_err(CliError::Repository)? { + let raw = String::from_utf8_lossy(&entry.content_bytes); + match serde_json::from_str::<MemoryNode>(raw.trim_end()) { + Ok(node) => { + let recorded = serde_json::from_str::<Value>(&entry.frontmatter_json) + .ok() + .and_then(|v| { + v.get("sourceContentHash") + .and_then(Value::as_str) + .map(str::to_owned) + }); + let current = source_content_hash(inputs); + return Ok(match recorded { + Some(h) if h == current => Attestation::Fresh(Box::new(node)), + _ => Attestation::Stale(Box::new(node)), + }); + } + Err(e) => { + eprintln!("warning: ignoring malformed tracked attestation {vpath}: {e}"); + // fall through to the legacy sidecar + } + } + } + + // 2) Legacy sidecar fallback (pre-upgrade attestations). Memory has no + // PREFIX-N ambiguity, so there is exactly ONE candidate path. + let path = attested_sidecar_path(repo, id_or_path); + if !path.exists() { + return Ok(Attestation::None); + } + let raw = std::fs::read_to_string(&path).map_err(CliError::Io)?; + let artifact: Value = match serde_json::from_str(&raw) { + Ok(v) => v, + Err(e) => { + eprintln!( + "warning: ignoring unreadable attestation sidecar {}: {e}", + path.display() + ); + return Ok(Attestation::None); + } + }; + let node_val = match artifact.get("node") { + Some(n) => n.clone(), + None => { + eprintln!( + "warning: attestation sidecar {} has no 'node' — ignoring", + path.display() + ); + return Ok(Attestation::None); + } + }; + let node: MemoryNode = match serde_json::from_value(node_val) { + Ok(n) => n, + Err(e) => { + eprintln!( + "warning: ignoring malformed attestation node in {}: {e}", + path.display() + ); + return Ok(Attestation::None); + } + }; + let recorded = artifact + .get("source") + .and_then(|s| s.get("sourceContentHash")) + .and_then(Value::as_str); + let current = source_content_hash(inputs); + match recorded { + Some(h) if h == current => Ok(Attestation::Fresh(Box::new(node))), + _ => Ok(Attestation::Stale(Box::new(node))), + } +} + +#[cfg(test)] +mod tests { + use super::*; + use atomic_canonical::lift_and_attest_memory; + use atomic_core::pristine::VaultEntryType; + use atomic_identity::identity::Identity; + use atomic_identity::keypair::KeyPair; + use tempfile::tempdir; + + /// A minimal, liftable memory spine (uid + kind + stable createdAt). + fn memory_inputs() -> MemLiftInputs { + let frontmatter = serde_json::json!({ + "uid": "01j8zc4r8t", + "memoryKind": "constraint", + "status": "active", + "createdAt": "2026-07-01T00:00:00+00:00", + }) + .as_object() + .unwrap() + .clone(); + MemLiftInputs { + frontmatter, + body: ":::memory\nThe durable fact.\n:::".to_string(), + } + } + + fn attested_node(inputs: &MemLiftInputs) -> (MemoryNode, KeyPair) { + let kp = KeyPair::generate(); + let id = Identity::new("tester", &kp); + let node = lift_and_attest_memory(&inputs.frontmatter, &inputs.body, &id, &kp) + .expect("lift_and_attest_memory on a minimal memory should succeed"); + (node, kp) + } + + /// Create a repo+vault and a single memory via the GENERIC vault path. + fn repo_with_memory() -> (Repository, String, MemLiftInputs, tempfile::TempDir) { + let dir = tempdir().unwrap(); + let repo = Repository::init(dir.path()).unwrap(); + repo.init_vault().unwrap(); + let inputs = memory_inputs(); + let id = "01j8zc4r8t".to_string(); + let path = normalize_memory_path(&id); + repo.vault_store( + &path, + VaultEntryType::Memory, + inputs.body.clone().into_bytes(), + serde_json::to_string(&inputs.frontmatter).unwrap(), + ) + .unwrap(); + (repo, id, inputs, dir) + } + + /// Mirror `attest`'s tracked-vault write exactly. + fn write_tracked(repo: &Repository, id: &str, node: &MemoryNode, inputs: &MemLiftInputs) { + let mut body = serde_json::to_string_pretty(&node.to_value()).unwrap(); + body.push('\n'); + let mut fm = serde_json::Map::new(); + fm.insert("memoryId".into(), Value::String(memory_id(id))); + fm.insert( + "sourceContentHash".into(), + Value::String(source_content_hash(inputs)), + ); + let frontmatter_json = serde_json::to_string(&fm).unwrap(); + let vpath = attestation_vault_path(id); + repo.vault_store( + &vpath, + VaultEntryType::Attestation, + body.into_bytes(), + frontmatter_json, + ) + .unwrap(); + } + + /// Mirror `attest`'s legacy sidecar write exactly ({node, source} wrapper). + fn write_legacy_sidecar( + repo: &Repository, + id: &str, + node: &MemoryNode, + inputs: &MemLiftInputs, + ) { + let path = attested_sidecar_path(repo, id); + std::fs::create_dir_all(path.parent().unwrap()).unwrap(); + let mut artifact = serde_json::Map::new(); + artifact.insert("node".to_string(), node.to_value()); + let mut source = serde_json::Map::new(); + source.insert( + "sourceContentHash".to_string(), + Value::String(source_content_hash(inputs)), + ); + artifact.insert("source".to_string(), Value::Object(source)); + std::fs::write( + &path, + serde_json::to_string_pretty(&Value::Object(artifact)).unwrap(), + ) + .unwrap(); + } + + #[test] + fn test_normalize_memory_path_all_forms() { + for form in ["x", "memory/x", "x.md", "memory/x.md"] { + assert_eq!(normalize_memory_path(form), "memory/x.md"); + } + assert_eq!(memory_id("memory/x.md"), "x"); + assert_eq!(memory_id("x"), "x"); + } + + #[test] + fn test_attestation_vault_path_stable_and_namespaced() { + // Stable across all accepted id/path forms. + for form in ["x", "memory/x", "x.md", "memory/x.md"] { + assert_eq!( + attestation_vault_path(form), + "attestations/memory/x/attested.md" + ); + } + // Collision guard: the memory namespace differs from an intent + // attestation path for the same literal id. + let intent_path = format!("attestations/{}/attested.md", "x"); + assert_ne!(attestation_vault_path("x"), intent_path); + } + + #[test] + fn test_load_attestation_prefers_tracked_then_legacy() { + let (repo, id, inputs, _dir) = repo_with_memory(); + let (node, _kp) = attested_node(&inputs); + + // (a) Only a legacy sidecar present -> dual-read fallback returns Fresh. + write_legacy_sidecar(&repo, &id, &node, &inputs); + assert!(matches!( + load_attestation(&repo, &id, &inputs).unwrap(), + Attestation::Fresh(_) + )); + + // (b) A tracked entry present -> it is used (still Fresh, tracked wins). + write_tracked(&repo, &id, &node, &inputs); + assert!(matches!( + load_attestation(&repo, &id, &inputs).unwrap(), + Attestation::Fresh(_) + )); + } + + #[test] + fn test_tracked_entry_parses_and_verifies() { + let (repo, id, inputs, _dir) = repo_with_memory(); + let (node, kp) = attested_node(&inputs); + write_tracked(&repo, &id, &node, &inputs); + write_legacy_sidecar(&repo, &id, &node, &inputs); + + // (a) tracked entry exists; body parses to a MemoryNode with a proof. + let vpath = attestation_vault_path(&id); + let entry = repo.vault_retrieve(&vpath).unwrap().expect("tracked entry"); + assert_eq!(entry.entry_type, VaultEntryType::Attestation); + let raw = String::from_utf8_lossy(&entry.content_bytes); + let parsed: MemoryNode = serde_json::from_str(raw.trim_end()).unwrap(); + assert!(parsed.proof.is_some(), "tracked node must carry a proof"); + assert!(parsed.content_hash.is_some()); + // Body ends in exactly one trailing newline. + assert!(raw.ends_with('\n') && !raw.ends_with("\n\n")); + + // (b) legacy sidecar also written. + assert!(attested_sidecar_path(&repo, &id).exists()); + + // (c) load_attestation returns the tracked node as Fresh. + let loaded = match load_attestation(&repo, &id, &inputs).unwrap() { + Attestation::Fresh(n) => *n, + Attestation::Stale(_) => panic!("expected Fresh, got Stale"), + Attestation::None => panic!("expected Fresh, got None"), + }; + + // (d) the loaded node verifies against the signing key. + atomic_canonical::verify_memory(&loaded, &kp.public) + .expect("tracked memory node must verify"); + } + + #[test] + fn test_attestation_staleness() { + let (repo, id, inputs, _dir) = repo_with_memory(); + let (node, _kp) = attested_node(&inputs); + write_tracked(&repo, &id, &node, &inputs); + + // Fresh against the original inputs. + assert!(matches!( + load_attestation(&repo, &id, &inputs).unwrap(), + Attestation::Fresh(_) + )); + + // Edit the body -> current source hash no longer matches -> Stale. + let edited = MemLiftInputs { + frontmatter: inputs.frontmatter.clone(), + body: format!("{}\n<!-- edited -->", inputs.body), + }; + assert!(matches!( + load_attestation(&repo, &id, &edited).unwrap(), + Attestation::Stale(_) + )); + } +} diff --git a/atomic-cli/src/commands/memory/mod.rs b/atomic-cli/src/commands/memory/mod.rs new file mode 100644 index 00000000..7d821079 --- /dev/null +++ b/atomic-cli/src/commands/memory/mod.rs @@ -0,0 +1,344 @@ +//! `atomic memory` — the canonical "record the why" engine surface for MEMORIES. +//! +//! This is a NEW top-level command, a sibling of the raw `atomic vault memory` +//! tree ([`crate::commands::vault::memory`]): that tree manages the raw/legacy +//! vault memory entries (the agent stdin `write` flow, plus `list`/`show`), +//! while this one drives the `atomic-canonical` engine — lifting a stored +//! memory into a canonical JSON-LD [`MemoryNode`](atomic_canonical::MemoryNode), +//! gating it, attesting it, and rendering it. It is the memory analogue of the +//! `atomic intent` family. +//! +//! # Verbs +//! +//! ```text +//! atomic memory new --kind <k> Scaffold a directive/frontmatter memory +//! atomic memory show <id> Render a memory as a read-time projection +//! atomic memory validate <id|path> Gate a memory against the canonical shapes +//! atomic memory attest <id> Sign a memory into a tracked attestation +//! atomic memory verify <id> Verify a signed memory's attestation +//! ``` +//! +//! # Persistence — additive by construction +//! +//! A memory is a single flat tracked vault entry at `memory/<id>.md` (created +//! via the GENERIC `vault_store` path, exactly like the raw `vault memory +//! write`). Attestation NEVER mutates the stored memory entry, its +//! `content_hash`, or the manifest merkle: the attested node + proof are written +//! as a first-class tracked `attestation` entry at +//! `attestations/memory/<id>/attested.md` (dual-written to a legacy +//! `.atomic/canonical/memory/<id>/` sidecar during the transition). See +//! [`bridge`]. + +use clap::Subcommand; + +use crate::commands::Command; +use crate::error::CliResult; + +pub mod attest; +pub mod bridge; +pub mod new; +pub mod show; +pub mod validate; +pub mod verify; + +pub use attest::MemoryAttest; +pub use new::MemoryNew; +pub use show::MemoryShow; +pub use validate::MemoryValidate; +pub use verify::MemoryVerify; + +/// Subcommands for the canonical memory engine. +#[derive(Subcommand, Debug)] +pub enum MemoryCommands { + /// Scaffold a new directive-based memory into the vault. + /// + /// Writes a `memory/<id>.md` entry with a frontmatter spine + /// (`uid`/`memoryKind`/`status`/`createdAt`/`about`) and a `:::memory` + /// container body so it round-trips cleanly through + /// lift → validate → attest. + /// + /// # Examples + /// + /// ```text + /// atomic memory new --kind constraint + /// atomic memory new --kind lesson --about urn:atomic:module:storage + /// ``` + New(MemoryNew), + + /// Show a memory as a rendered read-time projection. + /// + /// Lifts the memory and renders it via the canonical projection. This is a + /// pure read: it does not gate and does not require a proof, so it works on + /// a plain (un-attested) memory. + /// + /// # Examples + /// + /// ```text + /// atomic memory show 01j8zc4r8t + /// atomic memory show 01j8zc4r8t --json + /// ``` + Show(MemoryShow), + + /// Validate a memory against the canonical shapes (the authoring gate). + /// + /// Lifts the memory (by id from the vault, or from a markdown file path) + /// into a canonical node and runs the SHACL-style gate. An un-attested + /// memory reports violations for the missing proof and author + /// (`attributedTo`) — this is correct: `validate` is the authoring check, + /// `attest` is what makes it conform. Exits nonzero if the report does not + /// conform. + /// + /// # Examples + /// + /// ```text + /// atomic memory validate 01j8zc4r8t + /// atomic memory validate ./note.md + /// atomic memory validate 01j8zc4r8t --json + /// ``` + Validate(MemoryValidate), + + /// Attest a memory: sign it into a tracked attestation entry. + /// + /// Gates the memory first (refusing to sign a node that fails for a reason + /// signing cannot fix), fills `attributedTo` from the signing identity, + /// signs the canonical node, re-gates the attested result, and writes the + /// node (with embedded contentHash + proof) to a tracked vault entry + /// (dual-written to a legacy sidecar). No memory entry, `content_hash`, or + /// merkle is touched. + /// + /// # Examples + /// + /// ```text + /// atomic memory attest 01j8zc4r8t + /// atomic memory attest 01j8zc4r8t --identity alice-work + /// ``` + Attest(MemoryAttest), + + /// Verify a signed memory's attestation. + /// + /// Reads the attestation written by `attest`, confirms it is still fresh + /// (the memory hasn't changed since it was signed), and verifies its content + /// hash + Ed25519 Data Integrity proof. Exits nonzero if there is no + /// attestation, it is stale, or the signature does not verify. + /// + /// # Examples + /// + /// ```text + /// atomic memory verify 01j8zc4r8t + /// atomic memory verify 01j8zc4r8t --identity alice-work + /// ``` + Verify(MemoryVerify), +} + +/// Record the "why" for durable context: lift, validate, attest, and render +/// canonical memories. +/// +/// A sibling of the raw `atomic vault memory` tree. The verbs operate on real +/// vault memories through the `atomic-canonical` engine, persisting attestations +/// additively as tracked vault entries — the stored memory entries are never +/// mutated. +#[derive(Debug, clap::Args)] +#[command(name = "memory")] +pub struct Memory { + #[command(subcommand)] + pub command: MemoryCommands, +} + +impl Command for Memory { + fn run(&self) -> CliResult<()> { + match &self.command { + MemoryCommands::New(cmd) => cmd.run(), + MemoryCommands::Show(cmd) => cmd.run(), + MemoryCommands::Validate(cmd) => cmd.run(), + MemoryCommands::Attest(cmd) => cmd.run(), + MemoryCommands::Verify(cmd) => cmd.run(), + } + } +} + +/// A validation-failure error: the canonical gate reported a non-conforming +/// node. Kept as a `Parser`-free helper so `main.rs`'s `err.exit_code()` fires +/// with a distinct, user-fixable exit code (2, a usage/authoring error) rather +/// than the internal-bug code. Copied verbatim from `intent/mod.rs`. +pub(crate) fn validation_failed(message: impl Into<String>) -> crate::error::CliError { + crate::error::CliError::InvalidArgument { + message: message.into(), + } +} + +#[cfg(test)] +mod tests { + use super::*; + use atomic_canonical::memory::lift_memory; + use atomic_canonical::{validate_memory, verify_memory}; + use atomic_core::pristine::VaultEntryType; + use atomic_identity::identity::Identity; + use atomic_identity::keypair::KeyPair; + use atomic_repository::Repository; + use serde_json::{Map, Value}; + use tempfile::tempdir; + + /// END-TO-END at the persistence + engine layer, exercising the exact writes + /// and reads the CLI verbs perform (the CLI resolves identity via a global + /// IdentityStore, which we cannot mutate in a unit test, so here we sign with + /// an in-test keypair; the tracked/sidecar plumbing is otherwise identical). + /// + /// Chain: new -> validate (2 fillable violations, nonzero) -> attest (tracked + /// entry + legacy sidecar, self-verify) -> validate again (Fresh CONFORMS) -> + /// verify (Fresh, OK) -> show (attested node). Asserts createdAt stability so + /// the re-lift signing bytes stay identical across the whole chain. + #[test] + fn end_to_end_new_validate_attest_verify_show() { + let dir = tempdir().unwrap(); + let repo = Repository::init(dir.path()).unwrap(); + repo.init_vault().unwrap(); + + // --- new: write memory/<id>.md with a stable createdAt spine ---------- + let id = "01j8zc4r8t".to_string(); + let created_at = "2026-07-01T12:00:00+00:00"; + let vault_path = bridge::normalize_memory_path(&id); + let mut spine = Map::new(); + spine.insert("uid".into(), Value::String(id.clone())); + spine.insert("memoryKind".into(), Value::String("constraint".into())); + spine.insert("status".into(), Value::String("active".into())); + spine.insert("createdAt".into(), Value::String(created_at.into())); + let scaffold_body = ":::memory\nThe durable fact.\n:::\n"; + repo.vault_store( + &vault_path, + VaultEntryType::Memory, + scaffold_body.as_bytes().to_vec(), + serde_json::to_string(&spine).unwrap(), + ) + .unwrap(); + repo.vault_materialize(&vault_path).unwrap(); + + // --- validate (unattested): EXACTLY the two fillable violations ------- + let inputs = bridge::read_memory(&repo, &id).unwrap(); + assert!( + matches!( + bridge::load_attestation(&repo, &id, &inputs).unwrap(), + bridge::Attestation::None + ), + "no attestation yet" + ); + let unattested = bridge::lift(&inputs).unwrap(); + // createdAt survived the round-trip and is present on the lifted node. + assert_eq!(unattested.created_at, created_at); + let report = validate_memory(&unattested); + assert!(!report.conforms, "un-attested memory does not conform"); + let mut paths: Vec<_> = report + .results + .iter() + .map(|v| v.path.clone().unwrap_or_default()) + .collect(); + paths.sort(); + assert_eq!(paths, vec!["attributedTo".to_string(), "proof".to_string()]); + + // --- attest: sign + write tracked entry + legacy sidecar ------------- + let kp = KeyPair::generate(); + let identity = Identity::new("tester", &kp); + let node = + atomic_canonical::lift_and_attest_memory(&inputs.frontmatter, &inputs.body, &identity, &kp) + .unwrap(); + assert!(validate_memory(&node).conforms, "attested node conforms"); + verify_memory(&node, &kp.public).expect("self-verify"); + assert_eq!(node.created_at, created_at, "createdAt stable through attest"); + + // legacy sidecar + let sidecar_path = bridge::attested_sidecar_path(&repo, &id); + std::fs::create_dir_all(sidecar_path.parent().unwrap()).unwrap(); + let mut artifact = Map::new(); + artifact.insert("node".into(), node.to_value()); + let mut source = Map::new(); + source.insert( + "sourceContentHash".into(), + Value::String(bridge::source_content_hash(&inputs)), + ); + artifact.insert("source".into(), Value::Object(source)); + std::fs::write( + &sidecar_path, + serde_json::to_string_pretty(&Value::Object(artifact)).unwrap(), + ) + .unwrap(); + + // tracked entry + let mut body = serde_json::to_string_pretty(&node.to_value()).unwrap(); + body.push('\n'); + let mut fm = Map::new(); + fm.insert("memoryId".into(), Value::String(bridge::memory_id(&id))); + fm.insert( + "sourceContentHash".into(), + Value::String(bridge::source_content_hash(&inputs)), + ); + let apath = bridge::attestation_vault_path(&id); + assert_eq!(apath, "attestations/memory/01j8zc4r8t/attested.md"); + repo.vault_store( + &apath, + VaultEntryType::Attestation, + body.into_bytes(), + serde_json::to_string(&fm).unwrap(), + ) + .unwrap(); + + // --- validate again: Fresh attested node CONFORMS -------------------- + let inputs2 = bridge::read_memory(&repo, &id).unwrap(); + let fresh = match bridge::load_attestation(&repo, &id, &inputs2).unwrap() { + bridge::Attestation::Fresh(n) => *n, + other => panic!("expected Fresh, got {}", attestation_label(&other)), + }; + assert!(validate_memory(&fresh).conforms, "attested memory conforms"); + assert_eq!(fresh.created_at, created_at, "createdAt stable through re-read"); + + // --- verify: Fresh, verify_memory OK --------------------------------- + verify_memory(&fresh, &kp.public).expect("verify Fresh attested node"); + + // --- show: renders the attested node with author + proof ------------- + let rendered = atomic_canonical::render_memory(&fresh, atomic_canonical::Target::Cli); + assert!(rendered.contains("Memory (constraint)")); + assert!( + rendered.contains("The durable fact."), + "rendered text present" + ); + assert!(fresh.attributed_to.is_some(), "author present on attested node"); + assert!(fresh.proof.is_some(), "proof present on attested node"); + + // --- regression: `vault memory list` (prefix memory/) does NOT surface + // the attestation entry (it lives under attestations/memory/). ------ + let listed = repo.vault_list("memory/", None).unwrap(); + assert!( + listed.iter().all(|e| !e.path.starts_with("attestations/")), + "attestation entries must not appear under the memory/ prefix" + ); + assert!( + listed.iter().any(|e| e.path == vault_path), + "the memory entry itself is listed under memory/" + ); + } + + fn attestation_label(a: &bridge::Attestation) -> &'static str { + match a { + bridge::Attestation::None => "None", + bridge::Attestation::Fresh(_) => "Fresh", + bridge::Attestation::Stale(_) => "Stale", + } + } + + /// Guard: the scaffold body lifts to non-empty text (attest-ready). + #[test] + fn scaffold_lifts_to_nonempty_text() { + let fm: Map<String, Value> = serde_json::json!({ + "uid": "x", + "memoryKind": "context", + "createdAt": "2026-07-01T00:00:00+00:00", + }) + .as_object() + .unwrap() + .clone(); + let node = lift_memory( + &fm, + ":::memory\n<!-- stub comment counts as text -->\n:::", + ) + .unwrap(); + assert!(!node.text.trim().is_empty()); + } +} diff --git a/atomic-cli/src/commands/memory/new.rs b/atomic-cli/src/commands/memory/new.rs new file mode 100644 index 00000000..5c3bd858 --- /dev/null +++ b/atomic-cli/src/commands/memory/new.rs @@ -0,0 +1,235 @@ +//! `atomic memory new --kind <k> [--about m1,m2]` — scaffold a directive-based +//! memory into the vault. +//! +//! Unlike `atomic intent new` (which delegates to `vault_intent_create`), there +//! is NO dedicated repository create method for memories. This writes directly +//! through the GENERIC vault path (`vault_store` + `vault_materialize`) — the +//! same path the raw `atomic vault memory write` uses — so the memory enters +//! redb, the manifest, and the merkle exactly as a first-class tracked entry. + +use clap::Parser; +use serde_json::{Map, Value}; + +use atomic_canonical::vocab::{MEMORY_KIND, MEMORY_STATUS}; +use atomic_core::pristine::VaultEntryType; +use atomic_repository::Repository; + +use crate::commands::memory::bridge; +use crate::commands::{find_repository_root, Command}; +use crate::error::{CliError, CliResult}; + +/// The directive scaffold emitted for a new memory. +/// +/// A single `:::memory` container (the closed, lift-recognized directive from +/// `LIFTED_MEMORY_DIRECTIVES`) wrapping a stub comment. `lift_memory` takes the +/// container's body as the authoritative single authoring site; the comment +/// counts as text, so a freshly-scaffolded memory lifts to non-empty text and +/// its ONLY validate violations are the fillable `attributedTo` + `proof` +/// (attest-ready), mirroring intent-new behavior. +const MEMORY_SCAFFOLD: &str = "\ +:::memory +<!-- The durable fact. State the constraint / preference / lesson / context. + Its content is never graded — but it must be present. Replace this stub. --> +::: +"; + +/// Scaffold a new directive-based memory into the vault. +#[derive(Parser, Debug)] +#[command(name = "new")] +pub struct MemoryNew { + /// Memory kind: one of `constraint`, `preference`, `lesson`, `context`. + #[arg(long)] + pub kind: String, + + /// Module/domain urns this memory is about (comma-separated, optional). + #[arg(long, value_delimiter = ',')] + pub about: Vec<String>, + + /// Explicit memory id (the filename stem). Defaults to a freshly generated + /// lowercased ULID. + #[arg(long)] + pub id: Option<String>, + + /// Lifecycle status. One of `active`, `superseded`, `retracted`. + #[arg(long, default_value = "active")] + pub status: String, +} + +impl Command for MemoryNew { + fn run(&self) -> CliResult<()> { + // Reject a bad --kind EARLY (before touching the vault) so `new` never + // writes a non-liftable / non-conforming spine. + if !MEMORY_KIND.contains(&self.kind.as_str()) { + return Err(CliError::InvalidArgument { + message: format!( + "unknown memory kind '{}' (one of {:?})", + self.kind, MEMORY_KIND + ), + }); + } + // status is an equally-closed vocabulary — reject a bad one early too, + // so `new` never persists a non-conforming spine (the gate would only + // catch it later at validate/attest). + if !MEMORY_STATUS.contains(&self.status.as_str()) { + return Err(CliError::InvalidArgument { + message: format!( + "unknown memory status '{}' (one of {:?})", + self.status, MEMORY_STATUS + ), + }); + } + + let root = find_repository_root()?; + let repo = Repository::open(&root).map_err(CliError::Repository)?; + + let id = self + .id + .clone() + .unwrap_or_else(generate_ulid_lowercased); + let vault_path = bridge::normalize_memory_path(&id); + + // Build the frontmatter SPINE as FLAT SCALAR/array fields only (so it + // survives yaml_frontmatter_to_json round-trip). Do NOT write + // attributedTo/proof/contentHash — attest fills those. createdAt is + // STABLE (load-bearing: it is signed, so every re-lift must reproduce + // byte-identical signing bytes). + let mut spine = Map::new(); + spine.insert("uid".into(), Value::String(id.clone())); + spine.insert("memoryKind".into(), Value::String(self.kind.clone())); + spine.insert("status".into(), Value::String(self.status.clone())); + spine.insert( + "createdAt".into(), + Value::String(chrono::Utc::now().to_rfc3339()), + ); + if !self.about.is_empty() { + spine.insert( + "about".into(), + Value::Array(self.about.iter().cloned().map(Value::String).collect()), + ); + } + let frontmatter_json = serde_json::to_string(&spine) + .expect("frontmatter spine serialization is infallible"); + + // Store the body WITHOUT a frontmatter block; the spine goes through the + // frontmatter_json arg. Enters redb + manifest.memory + merkle exactly + // like the raw `vault memory write` path. + repo.vault_store( + &vault_path, + VaultEntryType::Memory, + MEMORY_SCAFFOLD.as_bytes().to_vec(), + frontmatter_json, + ) + .map_err(CliError::Repository)?; + repo.vault_materialize(&vault_path) + .map_err(CliError::Repository)?; + + println!("Created memory: {id}"); + println!(" file: .vault/{vault_path}"); + println!(" kind: {}", self.kind); + println!(); + println!("Edit the :::memory stub, then:"); + println!(" atomic memory validate {id}"); + println!(" atomic memory attest {id}"); + + Ok(()) + } +} + +/// Generate a fresh lowercased ULID-style stem: a 48-bit millisecond timestamp +/// followed by 80 bits of randomness, encoded in Crockford base32 (26 chars), +/// lowercased. No ULID crate is a workspace dependency, so this is a +/// self-contained generator using the existing `chrono` + `uuid` deps — +/// deliberately NOT a `PREFIX-N` scheme (memories have no prefix allocator). +fn generate_ulid_lowercased() -> String { + const CROCKFORD: &[u8; 32] = b"0123456789abcdefghjkmnpqrstvwxyz"; + + let now_ms = chrono::Utc::now().timestamp_millis().max(0) as u128; + // 80 bits of randomness from a v4 UUID. + let rand = uuid::Uuid::new_v4().as_u128(); + + // A ULID is a 128-bit value: 48-bit time (high) + 80-bit randomness (low). + let value: u128 = (now_ms << 80) | (rand & ((1u128 << 80) - 1)); + + // Encode the 128-bit value as 26 Crockford base32 chars (130 bits, so the + // top 2 bits of the first symbol are always 0 — standard ULID layout). + let mut out = [0u8; 26]; + let mut v = value; + for slot in out.iter_mut().rev() { + *slot = CROCKFORD[(v & 0x1f) as usize]; + v >>= 5; + } + String::from_utf8(out.to_vec()).expect("crockford alphabet is valid ASCII") +} + +#[cfg(test)] +mod tests { + use super::*; + use atomic_canonical::memory::lift_memory; + use tempfile::tempdir; + + #[test] + fn test_generate_ulid_shape() { + let id = generate_ulid_lowercased(); + assert_eq!(id.len(), 26, "ULID stem is 26 chars"); + assert!( + id.chars() + .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit()), + "ULID stem is lowercased Crockford base32: {id}" + ); + // Two consecutive generations differ (randomness in the low bits). + assert_ne!(generate_ulid_lowercased(), generate_ulid_lowercased()); + } + + #[test] + fn test_new_writes_liftable_memory() { + let dir = tempdir().unwrap(); + let repo = Repository::init(dir.path()).unwrap(); + repo.init_vault().unwrap(); + + // Drive `new`'s storage logic directly (the CLI resolves the repo via + // find_repository_root; here we exercise the same writes on a known repo). + let id = "memtest01".to_string(); + let vault_path = bridge::normalize_memory_path(&id); + let mut spine = Map::new(); + spine.insert("uid".into(), Value::String(id.clone())); + spine.insert("memoryKind".into(), Value::String("constraint".into())); + spine.insert("status".into(), Value::String("active".into())); + spine.insert( + "createdAt".into(), + Value::String("2026-07-01T00:00:00+00:00".into()), + ); + spine.insert( + "about".into(), + Value::Array(vec![Value::String("a".into()), Value::String("b".into())]), + ); + let fm_json = serde_json::to_string(&spine).unwrap(); + repo.vault_store( + &vault_path, + VaultEntryType::Memory, + MEMORY_SCAFFOLD.as_bytes().to_vec(), + fm_json, + ) + .unwrap(); + repo.vault_materialize(&vault_path).unwrap(); + + // The stored entry is a Memory entry keyed on the path, and lifts cleanly. + let entry = repo.vault_retrieve(&vault_path).unwrap().expect("entry"); + assert_eq!(entry.entry_type, VaultEntryType::Memory); + let fm: Map<String, Value> = serde_json::from_str(&entry.frontmatter_json).unwrap(); + assert_eq!(fm.get("createdAt").and_then(Value::as_str), Some("2026-07-01T00:00:00+00:00")); + assert_eq!( + fm.get("about").unwrap(), + &Value::Array(vec![Value::String("a".into()), Value::String("b".into())]) + ); + let body = String::from_utf8_lossy(&entry.content_bytes); + assert!(body.contains(":::memory"), "body carries the :::memory container"); + let node = lift_memory(&fm, &body).expect("scaffold lifts cleanly"); + assert_eq!(node.memory_kind, "constraint"); + assert_eq!(node.about, vec!["a".to_string(), "b".to_string()]); + assert!(!node.text.trim().is_empty(), "stub comment counts as text"); + + // Materialized to disk. + let on_disk = repo.vault_dir().join(&vault_path); + assert!(on_disk.exists(), "materialized at {}", on_disk.display()); + } +} diff --git a/atomic-cli/src/commands/memory/show.rs b/atomic-cli/src/commands/memory/show.rs new file mode 100644 index 00000000..202d1307 --- /dev/null +++ b/atomic-cli/src/commands/memory/show.rs @@ -0,0 +1,59 @@ +//! `atomic memory show <ID>` — render a memory as a read-time projection. + +use clap::Parser; + +use atomic_canonical::{render_memory, Target}; +use atomic_repository::Repository; + +use crate::commands::memory::bridge; +use crate::commands::{find_repository_root, Command}; +use crate::error::{CliError, CliResult}; + +/// Show a memory as a rendered read-time projection. +/// +/// Distinct from [`crate::commands::vault::memory::MemoryShow`], which dumps the +/// raw stored body. This projects the lifted canonical node. +#[derive(Parser, Debug)] +#[command(name = "show")] +pub struct MemoryShow { + /// Memory id (or `memory/<id>.md` path). + pub id: String, + + /// Output the canonical node as JSON-LD instead of the rendered view. + #[arg(long)] + pub json: bool, +} + +impl Command for MemoryShow { + fn run(&self) -> CliResult<()> { + let root = find_repository_root()?; + let repo = Repository::open(&root).map_err(CliError::Repository)?; + + // Pure read-time projection: lift then render. No gate, no proof + // requirement — this must work on a plain (un-attested) memory. If a + // FRESH attestation exists we project that (so `show` reflects the + // attested author/proof); a stale one warns and falls back to the raw + // node. + let inputs = bridge::read_memory(&repo, &self.id)?; + let node = match bridge::load_attestation(&repo, &self.id, &inputs)? { + bridge::Attestation::Fresh(node) => *node, + bridge::Attestation::Stale(_) => { + eprintln!( + "warning: the attestation for {} is stale; showing the current \ + (un-attested) memory.", + self.id + ); + bridge::lift(&inputs)? + } + bridge::Attestation::None => bridge::lift(&inputs)?, + }; + + if self.json { + println!("{}", serde_json::to_string_pretty(&node.to_value()).unwrap()); + } else { + print!("{}", render_memory(&node, Target::Cli)); + } + + Ok(()) + } +} diff --git a/atomic-cli/src/commands/memory/validate.rs b/atomic-cli/src/commands/memory/validate.rs new file mode 100644 index 00000000..9262c59a --- /dev/null +++ b/atomic-cli/src/commands/memory/validate.rs @@ -0,0 +1,159 @@ +//! `atomic memory validate <ID|path>` — gate a memory against the canonical +//! shapes. + +use std::path::Path; + +use clap::Parser; + +use atomic_canonical::lift::parse_markdown; +use atomic_canonical::memory::lift_memory; +use atomic_canonical::{validate_memory, ValidationReport}; +use atomic_repository::Repository; + +use crate::commands::memory::bridge; +use crate::commands::memory::validation_failed; +use crate::commands::{find_repository_root, Command}; +use crate::error::{CliError, CliResult}; + +/// Validate a memory against the canonical shapes. +#[derive(Parser, Debug)] +#[command(name = "validate")] +pub struct MemoryValidate { + /// Memory id (or a path to a memory markdown file). + pub id_or_path: String, + + /// Output the validation report as JSON. + #[arg(long)] + pub json: bool, +} + +impl Command for MemoryValidate { + fn run(&self) -> CliResult<()> { + // A path-shaped argument (ends in `.md` or contains a separator) is + // loaded as a file; a missing file is reported as FileNotFound rather + // than misreported as a bad id. Otherwise it is a memory id read + // through the vault bridge; a FRESH attestation gates the attested node + // (so a previously-attested memory reports conforms), a STALE one warns + // and falls back to the raw node. + let node = if is_path_shaped(&self.id_or_path) { + let path = Path::new(&self.id_or_path); + if !path.is_file() { + return Err(CliError::FileNotFound { + path: path.to_path_buf(), + }); + } + let doc = std::fs::read_to_string(path).map_err(CliError::Io)?; + let (fm, body) = parse_markdown(&doc).map_err(|e| CliError::InvalidArgument { + message: format!("could not parse markdown frontmatter: {e}"), + })?; + lift_memory(&fm, &body).map_err(|e| CliError::InvalidArgument { + message: format!("could not lift memory: {e}"), + })? + } else { + let root = find_repository_root()?; + let repo = Repository::open(&root).map_err(CliError::Repository)?; + let inputs = bridge::read_memory(&repo, &self.id_or_path)?; + match bridge::load_attestation(&repo, &self.id_or_path, &inputs)? { + bridge::Attestation::Fresh(node) => *node, + bridge::Attestation::Stale(_) => { + eprintln!( + "warning: the attestation for {} is stale (the memory changed since it \ + was signed); re-run `atomic memory attest {}`.", + self.id_or_path, self.id_or_path + ); + bridge::lift(&inputs)? + } + bridge::Attestation::None => bridge::lift(&inputs)?, + } + }; + + let report = validate_memory(&node); + + if self.json { + println!("{}", serde_json::to_string_pretty(&report_json(&report)).unwrap()); + } else { + print!("{report}"); + } + + if report.conforms { + Ok(()) + } else { + Err(validation_failed(format!( + "memory does not conform ({} violation(s))", + report.results.len() + ))) + } + } +} + +/// Is the argument *shaped* like a filesystem path (rather than a memory id)? +/// True when it ends in `.md` or contains a path separator. A `memory/<id>` +/// (no `.md`) form is NOT path-shaped — it is a valid id form the bridge +/// normalizes. A bare `memory/<id>.md` IS path-shaped, so `validate` would try +/// to read it as a file; callers wanting the vault entry use the bare `<id>`. +fn is_path_shaped(arg: &str) -> bool { + arg.ends_with(".md") +} + +/// Serialize a [`ValidationReport`] to the documented JSON shape: +/// `{conforms, results: [{focus_node, shape, path, message}]}`. +fn report_json(report: &ValidationReport) -> serde_json::Value { + serde_json::json!({ + "conforms": report.conforms, + "results": report + .results + .iter() + .map(|v| serde_json::json!({ + "focus_node": v.focus_node, + "shape": v.shape, + "path": v.path, + "message": v.message, + })) + .collect::<Vec<_>>(), + }) +} + +#[cfg(test)] +mod tests { + use super::*; + use atomic_canonical::memory::lift_memory; + use serde_json::{Map, Value}; + + fn unattested_node() -> atomic_canonical::MemoryNode { + let fm: Map<String, Value> = serde_json::json!({ + "uid": "01j8zc4r8t", + "memoryKind": "constraint", + "status": "active", + "createdAt": "2026-07-01T00:00:00+00:00", + }) + .as_object() + .unwrap() + .clone(); + lift_memory(&fm, ":::memory\nThe durable fact.\n:::").unwrap() + } + + #[test] + fn test_unattested_reports_exactly_two_fillable_violations() { + let report = validate_memory(&unattested_node()); + assert!(!report.conforms); + let mut paths: Vec<_> = report + .results + .iter() + .map(|v| v.path.clone().unwrap_or_default()) + .collect(); + paths.sort(); + assert_eq!( + paths, + vec!["attributedTo".to_string(), "proof".to_string()], + "an un-attested memory reports EXACTLY the two fillable violations" + ); + } + + #[test] + fn test_is_path_shaped() { + assert!(is_path_shaped("plan.md")); + assert!(is_path_shaped("memory/x.md")); + assert!(!is_path_shaped("x")); + assert!(!is_path_shaped("memory/x")); + } +} diff --git a/atomic-cli/src/commands/memory/verify.rs b/atomic-cli/src/commands/memory/verify.rs new file mode 100644 index 00000000..6fe25e90 --- /dev/null +++ b/atomic-cli/src/commands/memory/verify.rs @@ -0,0 +1,98 @@ +//! `atomic memory verify <ID>` — verify a memory's attestation. +//! +//! Reads the attested node written by `attest`, checks it is still fresh (the +//! memory hasn't changed since it was signed), and cryptographically verifies +//! its content hash + Ed25519 Data Integrity proof. + +use clap::Parser; + +use atomic_canonical::verify_memory; +use atomic_identity::IdentityStore; +use atomic_repository::Repository; + +use crate::commands::memory::bridge; +use crate::commands::{find_repository_root, Command}; +use crate::error::{CliError, CliResult}; + +/// Verify a memory's attestation (hash + signature) against a public key. +#[derive(Parser, Debug)] +#[command(name = "verify")] +pub struct MemoryVerify { + /// Memory id (or `memory/<id>.md` path). + pub id: String, + + /// Identity whose public key to verify against. Defaults to the current + /// default identity. Pass this if the memory was attested by someone else. + #[arg(long)] + pub identity: Option<String>, +} + +impl Command for MemoryVerify { + fn run(&self) -> CliResult<()> { + let root = find_repository_root()?; + let repo = Repository::open(&root).map_err(CliError::Repository)?; + + let inputs = bridge::read_memory(&repo, &self.id)?; + let node = match bridge::load_attestation(&repo, &self.id, &inputs)? { + bridge::Attestation::None => { + return Err(CliError::InvalidArgument { + message: format!( + "no attestation found for {}; run `atomic memory attest {}` first", + self.id, self.id + ), + }) + } + bridge::Attestation::Stale(_) => { + return Err(CliError::InvalidArgument { + message: format!( + "the attestation for {} is stale (the memory changed since it was \ + signed); re-run `atomic memory attest {}`", + self.id, self.id + ), + }) + } + bridge::Attestation::Fresh(node) => *node, + }; + + // Resolve the public key. `did:atomic` is a key fingerprint (not + // recoverable to a key), so we verify against the default (or named) + // identity and let verify_memory's DID check catch a mismatch. + let store = IdentityStore::open_default().map_err(|e| { + CliError::Internal(anyhow::anyhow!("Failed to open identity store: {}", e)) + })?; + let identity = if let Some(name) = &self.identity { + store + .load_by_name(name) + .map_err(|_| CliError::IdentityNotFound(name.clone()))? + } else { + store + .get_default() + .map_err(|e| { + CliError::Internal(anyhow::anyhow!("Failed to load default identity: {}", e)) + })? + .ok_or_else(|| { + CliError::Internal(anyhow::anyhow!( + "No default identity set. Create one first:\n \ + atomic identity new <name> --email <email> --set-default" + )) + })? + }; + + verify_memory(&node, &identity.public_key).map_err(|e| CliError::InvalidArgument { + message: format!( + "verification failed: {e} (if this memory was attested by a different \ + identity, pass --identity <name>)" + ), + })?; + + println!("Verified memory: {}", self.id); + println!( + " author: {}", + node.attributed_to.as_deref().unwrap_or("(unknown)") + ); + if let Some(h) = &node.content_hash { + println!(" hash: {h}"); + } + Ok(()) + } +} diff --git a/atomic-cli/src/commands/mod.rs b/atomic-cli/src/commands/mod.rs index 70c2aeda..6d22904a 100644 --- a/atomic-cli/src/commands/mod.rs +++ b/atomic-cli/src/commands/mod.rs @@ -75,6 +75,7 @@ pub mod init; pub mod insert; pub mod intent; pub mod log; +pub mod memory; pub mod mv; pub mod record; pub mod remove; @@ -135,6 +136,7 @@ pub use init::Init; pub use insert::Insert; pub use intent::Intent; pub use log::Log; +pub use memory::Memory; pub use mv::Move; pub use project::ProjectCmd; pub use pull::Pull; diff --git a/atomic-cli/src/main.rs b/atomic-cli/src/main.rs index 1b10e403..1af1b54d 100644 --- a/atomic-cli/src/main.rs +++ b/atomic-cli/src/main.rs @@ -68,6 +68,7 @@ use commands::{ Insert, Intent, Log, + Memory, Move, ProjectCmd, Pull, @@ -720,6 +721,28 @@ enum Commands { #[command(name = "intent")] Intent(Intent), + /// Record the "why" for durable context: lift, validate, attest, and render + /// canonical memories. + /// + /// A sibling of the raw `atomic vault memory` tree, driving the + /// `atomic-canonical` engine for MEMORIES. Attestations are persisted + /// additively as tracked vault entries. + /// + /// # Examples + /// + /// ```text + /// # Scaffold a directive-based memory + /// atomic memory new --kind constraint + /// + /// # Gate it against the canonical shapes + /// atomic memory validate 01j8zc4r8t + /// + /// # Sign it into a tracked attestation + /// atomic memory attest 01j8zc4r8t + /// ``` + #[command(name = "memory")] + Memory(Memory), + /// Remove the last change from the current view. /// /// The change is removed from the view's change log but NOT deleted @@ -843,6 +866,8 @@ fn main() { Commands::Vault(vault) => vault.run(), Commands::Intent(intent) => intent.run(), + + Commands::Memory(memory) => memory.run(), }; // Handle errors with user-friendly output From 0b6ba0a17e142ffa149f3d7fb69d6ddb164f5462 Mon Sep 17 00:00:00 2001 From: Bradley Hilton <graywolf336@craftyn.com> Date: Thu, 2 Jul 2026 11:32:56 -0500 Subject: [PATCH 06/21] feat(cli): add attestation-aware `atomic intent list` and `atomic memory list` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rounds out the canonical CLI families with a `list` verb that surfaces what the raw `atomic vault list --type X` cannot: canonical + attestation state. - intent list: humanKey · status · attested(fresh|stale|–) · verifies(✓|✗|–) - memory list: id · kind · status · about(count) · attested · verifies · (--json) Attestation-aware via the existing bridges (no new machinery): `attested` is classified from load_attestation (Fresh/Stale/None); `verifies` runs the engine's verify/verify_memory against the identity resolved ONCE up front, and — to avoid false negatives — shows `–` (not `✗`) when there's no attestation, the attestation is stale, or the signer DID isn't the resolvable identity; `✗` only on a real hash/signature failure. No identity resolvable ⇒ all `verifies` are `–` (the list still renders). A single bad row degrades to `–`, never aborts the list. Enumeration reuses the same sources as the raw verbs: vault_intent_list for intents; vault_list("memory/", None) for memories. Attestation entries (attestations/…) and the `memory/MEMORY.md` index scaffold are excluded. Review fixes folded in: stale rows show the CURRENT source's kind/status/about (matching `memory show`, drift still flagged by attested=stale), and column widths measure chars not bytes (aligned output with multibyte ids/status). atomic-cli only — atomic-canonical, atomic-core, and the raw `atomic vault` commands untouched. Verified end-to-end (attested vs un-attested rows + --json); 1564 atomic-cli tests (incl. 7 intent::list + 8 memory::list), atomic-canonical 51, clippy clean. --- atomic-cli/src/commands/intent/list.rs | 510 ++++++++++++++++++++++ atomic-cli/src/commands/intent/mod.rs | 21 + atomic-cli/src/commands/memory/list.rs | 576 +++++++++++++++++++++++++ atomic-cli/src/commands/memory/mod.rs | 19 + 4 files changed, 1126 insertions(+) create mode 100644 atomic-cli/src/commands/intent/list.rs create mode 100644 atomic-cli/src/commands/memory/list.rs diff --git a/atomic-cli/src/commands/intent/list.rs b/atomic-cli/src/commands/intent/list.rs new file mode 100644 index 00000000..a9124781 --- /dev/null +++ b/atomic-cli/src/commands/intent/list.rs @@ -0,0 +1,510 @@ +//! `atomic intent list` — an ATTESTATION-AWARE listing of the vault's intents. +//! +//! This is the canonical-family analogue of `atomic vault intent list` / +//! `atomic vault list --type intent`: those render a plain path/size/status +//! table, while this one adds the two columns that only the canonical engine can +//! answer — whether each intent carries a *fresh* attestation, and whether that +//! attestation cryptographically *verifies* against the resolving identity. +//! +//! # Columns +//! +//! ```text +//! humanKey status attested verifies +//! PIMO-1 todo fresh ✓ +//! PIMO-2 doing – – +//! PIMO-3 done stale – +//! ``` +//! +//! - `humanKey` — the `IntentInfo.id` (e.g. `PIMO-1`), the manifest key. +//! - `status` — the raw status column from the intent manifest. +//! - `attested` — `fresh` / `stale` / `–` via [`bridge::load_attestation`]. +//! - `verifies` — `✓` / `✗` / `–` via the DID-match-then-verify rule (see +//! [`compute_verifies`]): `–` when there is no attestation, when it is stale, +//! when there is no resolvable identity, or when the attestation was signed by +//! a *different* identity (a merely-unresolvable signer is NOT a failure); +//! `✗` only when a same-signer node fails its hash/signature check. +//! +//! Enumeration reuses [`Repository::vault_intent_list`] — the exact source +//! `atomic vault intent list` uses. Attestation entries live under +//! `attestations/…` and are never in `manifest.intents`, so they can never +//! surface as a row. + +use clap::Parser; + +use atomic_canonical::did::did_for_public_key; +use atomic_identity::keypair::PublicKey; +use atomic_identity::IdentityStore; +use atomic_repository::Repository; + +use crate::commands::intent::bridge; +use crate::commands::{find_repository_root, Command}; +use crate::error::{CliError, CliResult}; + +/// The EN DASH used everywhere for a "not applicable" cell. +const NA: &str = "–"; + +/// List the vault's intents with attestation + verification status. +#[derive(Parser, Debug)] +#[command(name = "list")] +pub struct IntentList { + /// Identity whose public key to verify attestations against. Defaults to the + /// current default identity. If no identity can be resolved at all, every + /// `verifies` cell is `–` rather than the whole command erroring. + #[arg(long)] + pub identity: Option<String>, + + /// Output as JSON (an array of {id,status,attested,verifies}). + #[arg(long)] + pub json: bool, +} + +/// The classification of one intent's attestation, for a table/JSON row. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum Attested { + Fresh, + Stale, + None, +} + +impl Attested { + /// The lowercase table token. + fn table(self) -> &'static str { + match self { + Attested::Fresh => "fresh", + Attested::Stale => "stale", + Attested::None => NA, + } + } + + /// The machine-consumable JSON token. + fn json(self) -> &'static str { + match self { + Attested::Fresh => "fresh", + Attested::Stale => "stale", + Attested::None => "none", + } + } +} + +/// The result of the DID-match-then-verify rule for one row. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum Verifies { + /// Same-signer, fresh attestation that cryptographically verified. + Yes, + /// Same-signer, fresh attestation whose hash/signature FAILED. + No, + /// No attestation, stale, no resolvable identity, or a different signer. + Na, +} + +impl Verifies { + /// The human-table glyph. + fn table(self) -> &'static str { + match self { + Verifies::Yes => "✓", + Verifies::No => "✗", + Verifies::Na => NA, + } + } + + /// The machine-consumable JSON token. + fn json(self) -> &'static str { + match self { + Verifies::Yes => "yes", + Verifies::No => "no", + Verifies::Na => "na", + } + } +} + +/// A fully-computed intent row. +struct Row { + human_key: String, + status: String, + attested: Attested, + verifies: Verifies, +} + +/// The verifying identity resolved ONCE for the whole list: its public key and +/// its `did:atomic`. `None` means no identity could be resolved (soft-fail), in +/// which case every `verifies` cell is `–`. +struct Verifier { + public_key: PublicKey, + did: String, +} + +/// Resolve the verifying identity exactly as the verify verb does, but SOFT: a +/// missing default (or no store) yields `Ok(None)` so the list still renders +/// with all-`–` verifies. A `--identity <name>` that does not exist IS a hard +/// error (`IdentityNotFound`), matching the verify verb. +fn resolve_verifier(name: &Option<String>) -> CliResult<Option<Verifier>> { + let store = match IdentityStore::open_default() { + Ok(s) => s, + // No store at all ⇒ soft-fail to "no identity" (all verifies '–'). + Err(_) => return Ok(None), + }; + let identity = if let Some(name) = name { + // A named-but-missing identity is a hard error (parity with verify). + Some( + store + .load_by_name(name) + .map_err(|_| CliError::IdentityNotFound(name.clone()))?, + ) + } else { + // No default resolvable ⇒ soft-fail, don't abort the list. + store.get_default().ok().flatten() + }; + Ok(identity.map(|id| Verifier { + did: did_for_public_key(&id.public_key), + public_key: id.public_key, + })) +} + +/// The DID-match-then-verify rule for an intent. Pure over its inputs so it can +/// be unit-tested without a global `IdentityStore`. +/// +/// - `attested` None ⇒ `Na`. +/// - `attested` Stale ⇒ `Na` (staleness is surfaced by the attested column; +/// there is nothing fresh to cryptographically verify — do NOT feed a Stale +/// node to `verify`, which would report `✗` on a changed-but-validly-signed +/// node). +/// - `attested` Fresh: +/// - no resolvable identity ⇒ `Na`; +/// - the attestation's signer DID does not match the resolving key ⇒ `Na` +/// (a legitimately other-signed node, NOT a failure — showing `✗` here +/// would be a false negative); +/// - same signer ⇒ run `verify`: `Ok` ⇒ `Yes`, `Err` ⇒ `No`. +fn compute_verifies( + attested: &bridge::Attestation, + verifier: Option<&Verifier>, +) -> Verifies { + let node = match attested { + bridge::Attestation::Fresh(node) => node, + bridge::Attestation::Stale(_) | bridge::Attestation::None => return Verifies::Na, + }; + let verifier = match verifier { + Some(v) => v, + None => return Verifies::Na, + }; + // DID pre-check FIRST: a different (or absent) signer is `–`, not `✗`. + match node.attributed_to.as_deref() { + Some(signer) if signer == verifier.did => {} + _ => return Verifies::Na, + } + // Same signer ⇒ the only path that can yield `✗` is a real hash/sig failure. + match atomic_canonical::verify(node, &verifier.public_key) { + Ok(()) => Verifies::Yes, + Err(_) => Verifies::No, + } +} + +/// Classify a loaded attestation into the `attested` column token. +fn classify(attested: &bridge::Attestation) -> Attested { + match attested { + bridge::Attestation::Fresh(_) => Attested::Fresh, + bridge::Attestation::Stale(_) => Attested::Stale, + bridge::Attestation::None => Attested::None, + } +} + +/// Compute one intent's row. A read/lift/attestation failure for a SINGLE intent +/// degrades that row's attested/verifies to `–` rather than aborting the whole +/// list. +fn compute_row( + repo: &Repository, + info: &atomic_repository::IntentInfo, + verifier: Option<&Verifier>, +) -> Row { + // read_intent → inputs → load_attestation. Any failure ⇒ '–' columns. + let attestation = bridge::read_intent(repo, &info.id) + .and_then(|inputs| bridge::load_attestation(repo, &info.id, &inputs)); + let (attested, verifies) = match attestation { + Ok(a) => (classify(&a), compute_verifies(&a, verifier)), + Err(_) => (Attested::None, Verifies::Na), + }; + Row { + human_key: info.id.clone(), + status: info.status.clone(), + attested, + verifies, + } +} + +impl Command for IntentList { + fn run(&self) -> CliResult<()> { + let root = find_repository_root()?; + let repo = Repository::open(&root).map_err(CliError::Repository)?; + + // Resolve the verifying identity ONCE (soft-fail to "no identity"). + let verifier = resolve_verifier(&self.identity)?; + + // Enumerate via the SAME source `atomic vault intent list` uses; already + // sorted by id. Attestation entries are never in `manifest.intents`. + let intents = repo + .vault_intent_list(None) + .map_err(CliError::Repository)?; + + let rows: Vec<Row> = intents + .iter() + .map(|info| compute_row(&repo, info, verifier.as_ref())) + .collect(); + + if self.json { + let json: Vec<serde_json::Value> = rows + .iter() + .map(|r| { + serde_json::json!({ + "id": r.human_key, + "status": r.status, + "attested": r.attested.json(), + "verifies": r.verifies.json(), + }) + }) + .collect(); + println!("{}", serde_json::to_string_pretty(&json).unwrap()); + return Ok(()); + } + + if rows.is_empty() { + println!("No intents found."); + return Ok(()); + } + + // Fixed-width, left-aligned columns with a header row. + let key_w = rows + .iter() + .map(|r| r.human_key.chars().count()) + .chain(std::iter::once("humanKey".chars().count())) + .max() + .unwrap_or(8); + let status_w = rows + .iter() + .map(|r| r.status.chars().count()) + .chain(std::iter::once("status".chars().count())) + .max() + .unwrap_or(6); + + println!( + " {:<key_w$} {:<status_w$} {:<8} verifies", + "humanKey", "status", "attested", + ); + for r in &rows { + println!( + " {:<key_w$} {:<status_w$} {:<8} {}", + r.human_key, + r.status, + r.attested.table(), + r.verifies.table(), + ); + } + + Ok(()) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use atomic_canonical::{lift_and_attest, CanonicalNode}; + use atomic_core::pristine::VaultEntryType; + use atomic_identity::identity::Identity; + use atomic_identity::keypair::KeyPair; + use atomic_repository::IntentCreateOptions; + use serde_json::Value; + use tempfile::tempdir; + + /// Create a repo+vault and N intents; return (repo, sorted ids, tempdir). + fn repo_with_intents(n: usize) -> (Repository, Vec<String>, tempfile::TempDir) { + let dir = tempdir().unwrap(); + let repo = Repository::init(dir.path()).unwrap(); + repo.init_vault().unwrap(); + let mut ids = Vec::new(); + for i in 0..n { + let result = repo + .vault_intent_create(IntentCreateOptions { + title: format!("Intent {i}"), + priority: Some("medium".to_string()), + assignee: None, + labels: Vec::new(), + session_id: None, + turn_id: None, + }) + .unwrap(); + ids.push(result.id); + } + ids.sort(); + (repo, ids, dir) + } + + /// Lift+attest a stored intent with a given keypair, returning the node. + fn attest_with(repo: &Repository, id: &str, kp: &KeyPair) -> CanonicalNode { + let inputs = bridge::read_intent(repo, id).unwrap(); + let identity = Identity::new("tester", kp); + lift_and_attest(&inputs.frontmatter, &inputs.body, &identity, kp).unwrap() + } + + /// Mirror `attest`'s tracked-vault write (body = pretty JSON + '\n'). + fn write_tracked(repo: &Repository, id: &str, node: &CanonicalNode) { + let inputs = bridge::read_intent(repo, id).unwrap(); + let mut body = serde_json::to_string_pretty(&node.to_value()).unwrap(); + body.push('\n'); + let mut fm = serde_json::Map::new(); + fm.insert( + "intentId".into(), + Value::String(bridge::normalized_id(repo, id).unwrap()), + ); + fm.insert( + "sourceContentHash".into(), + Value::String(bridge::source_content_hash(&inputs)), + ); + let vpath = bridge::attestation_vault_path(repo, id).unwrap(); + repo.vault_store( + &vpath, + VaultEntryType::Attestation, + body.into_bytes(), + serde_json::to_string(&fm).unwrap(), + ) + .unwrap(); + } + + /// Compute a single row using an explicit verifier keypair (no global store). + fn row_for(repo: &Repository, id: &str, kp: Option<&KeyPair>) -> Row { + let verifier = kp.map(|kp| Verifier { + did: did_for_public_key(&kp.public), + public_key: kp.public.clone(), + }); + let info = repo + .vault_intent_list(None) + .unwrap() + .into_iter() + .find(|i| i.id == id) + .unwrap(); + compute_row(repo, &info, verifier.as_ref()) + } + + #[test] + fn unattested_row_is_na_na() { + let (repo, ids, _dir) = repo_with_intents(1); + let kp = KeyPair::generate(); + let row = row_for(&repo, &ids[0], Some(&kp)); + assert_eq!(row.attested, Attested::None); + assert_eq!(row.verifies, Verifies::Na); + assert_eq!(row.attested.table(), "–"); + assert_eq!(row.verifies.table(), "–"); + } + + #[test] + fn fresh_same_signer_verifies() { + let (repo, ids, _dir) = repo_with_intents(1); + let kp = KeyPair::generate(); + let node = attest_with(&repo, &ids[0], &kp); + write_tracked(&repo, &ids[0], &node); + + let row = row_for(&repo, &ids[0], Some(&kp)); + assert_eq!(row.attested, Attested::Fresh); + assert_eq!(row.verifies, Verifies::Yes); + assert_eq!(row.verifies.table(), "✓"); + } + + #[test] + fn stale_is_stale_and_na() { + let (repo, ids, _dir) = repo_with_intents(1); + let kp = KeyPair::generate(); + let node = attest_with(&repo, &ids[0], &kp); + write_tracked(&repo, &ids[0], &node); + + // Edit the stored intent body so the recorded source hash no longer + // matches ⇒ load_attestation returns Stale. + let path = bridge::vault_path_for(&repo, &ids[0]).unwrap().unwrap(); + let entry = repo.vault_retrieve(&path).unwrap().unwrap(); + let mut body = String::from_utf8_lossy(&entry.content_bytes).into_owned(); + body.push_str("\n<!-- edited after attest -->\n"); + repo.vault_store( + &path, + VaultEntryType::Intent, + body.into_bytes(), + entry.frontmatter_json.clone(), + ) + .unwrap(); + + let row = row_for(&repo, &ids[0], Some(&kp)); + assert_eq!(row.attested, Attested::Stale); + assert_eq!(row.verifies, Verifies::Na, "stale ⇒ verifies '–', not '✗'"); + assert_eq!(row.attested.table(), "stale"); + } + + #[test] + fn tampered_same_signer_is_x() { + // A fresh attestation whose stored body was mutated after signing, with a + // DID that MATCHES the resolving key ⇒ DID-match passes, verify() returns + // a hash mismatch ⇒ '✗'. Distinguishes ✗ (real failure) from '–'. + let (repo, ids, _dir) = repo_with_intents(1); + let kp = KeyPair::generate(); + let mut node = attest_with(&repo, &ids[0], &kp); + write_tracked(&repo, &ids[0], &node); + // Confirm untampered verifies. + assert_eq!(row_for(&repo, &ids[0], Some(&kp)).verifies, Verifies::Yes); + + // Tamper a signed field (the title/text) AFTER signing but keep the same + // attributedTo DID and the same recorded sourceContentHash (so it stays + // Fresh). The content hash / signature no longer match the body. + node.title = "tampered title".to_string(); + write_tracked(&repo, &ids[0], &node); + + let row = row_for(&repo, &ids[0], Some(&kp)); + assert_eq!(row.attested, Attested::Fresh, "still fresh (hash anchor kept)"); + assert_eq!(row.verifies, Verifies::No, "tampered same-signer ⇒ '✗'"); + assert_eq!(row.verifies.table(), "✗"); + } + + #[test] + fn other_signer_is_na_not_x() { + // Attest with K1 but resolve the list identity as K2 (different DID). + // attested='fresh' but node.attributed_to != did(K2) ⇒ verifies='–' + // (the core false-negative guard), NOT '✗'. + let (repo, ids, _dir) = repo_with_intents(1); + let k1 = KeyPair::generate(); + let k2 = KeyPair::generate(); + let node = attest_with(&repo, &ids[0], &k1); + write_tracked(&repo, &ids[0], &node); + + let row = row_for(&repo, &ids[0], Some(&k2)); + assert_eq!(row.attested, Attested::Fresh); + assert_eq!( + row.verifies, + Verifies::Na, + "other-signer ⇒ '–' (false-negative guard), never '✗'" + ); + } + + #[test] + fn no_identity_soft_fails_to_na() { + // A fresh attested row still lists with verifies='–' when NO identity is + // resolvable (verifier = None), rather than erroring. + let (repo, ids, _dir) = repo_with_intents(1); + let kp = KeyPair::generate(); + let node = attest_with(&repo, &ids[0], &kp); + write_tracked(&repo, &ids[0], &node); + + let row = row_for(&repo, &ids[0], None); + assert_eq!(row.attested, Attested::Fresh); + assert_eq!(row.verifies, Verifies::Na); + } + + #[test] + fn attestation_entry_never_a_row() { + // After attesting, the attestation entry (attestations/…) NEVER appears as + // its own intent row: vault_intent_list yields exactly the N intents. + let (repo, ids, _dir) = repo_with_intents(3); + let kp = KeyPair::generate(); + let node = attest_with(&repo, &ids[0], &kp); + write_tracked(&repo, &ids[0], &node); + + let listed = repo.vault_intent_list(None).unwrap(); + assert_eq!(listed.len(), 3, "exactly the 3 intents, no attestation row"); + assert!( + listed.iter().all(|i| !i.id.starts_with("attestations/")), + "no attestations/ path leaks into the intent listing" + ); + } +} diff --git a/atomic-cli/src/commands/intent/mod.rs b/atomic-cli/src/commands/intent/mod.rs index 00208216..92a4fe3c 100644 --- a/atomic-cli/src/commands/intent/mod.rs +++ b/atomic-cli/src/commands/intent/mod.rs @@ -31,12 +31,14 @@ use crate::error::CliResult; pub mod attest; pub mod bridge; +pub mod list; pub mod new; pub mod show; pub mod validate; pub mod verify; pub use attest::IntentAttest; +pub use list::IntentList; pub use new::IntentNew; pub use show::IntentShow; pub use validate::IntentValidate; @@ -123,6 +125,24 @@ pub enum IntentCommands { /// atomic intent verify PIMO-1 --identity alice-work /// ``` Verify(IntentVerify), + + /// List the vault's intents, attestation-aware. + /// + /// The canonical-family analogue of `atomic vault intent list`: alongside the + /// human key and status it adds an `attested` column (fresh / stale / –) and + /// a `verifies` column (✓ / ✗ / –). `verifies` is `✓` only when a fresh + /// attestation signed by the resolving identity cryptographically checks out, + /// `✗` when a same-signer node fails its hash/signature, and `–` otherwise + /// (no attestation, stale, no resolvable identity, or a different signer). + /// + /// # Examples + /// + /// ```text + /// atomic intent list + /// atomic intent list --identity alice-work + /// atomic intent list --json + /// ``` + List(IntentList), } /// Record the "why": lift, validate, attest, and render canonical intents. @@ -145,6 +165,7 @@ impl Command for Intent { IntentCommands::New(cmd) => cmd.run(), IntentCommands::Attest(cmd) => cmd.run(), IntentCommands::Verify(cmd) => cmd.run(), + IntentCommands::List(cmd) => cmd.run(), } } } diff --git a/atomic-cli/src/commands/memory/list.rs b/atomic-cli/src/commands/memory/list.rs new file mode 100644 index 00000000..8430431b --- /dev/null +++ b/atomic-cli/src/commands/memory/list.rs @@ -0,0 +1,576 @@ +//! `atomic memory list` — an ATTESTATION-AWARE listing of the vault's memories. +//! +//! The canonical-family analogue of `atomic vault memory list` / +//! `atomic vault list --type memory`: those render a plain path/size table, +//! while this one adds the columns only the canonical engine can answer — the +//! memory's kind/status/about count (lifted, never graded), whether it carries a +//! *fresh* attestation, and whether that attestation *verifies* against the +//! resolving identity. +//! +//! # Columns +//! +//! ```text +//! id kind status about attested verifies +//! 01j8zc4r8t constraint active 2 fresh ✓ +//! 01j9aa11bb lesson active 0 – – +//! ``` +//! +//! - `id` — the filename stem of `memory/<id>.md`. +//! - `kind` — `memory_kind` (from the attested node when Fresh/Stale, else a +//! lift of the raw memory; NEVER a closed-vocab grade of the prose). +//! - `status` — the memory's status (same source as `kind`). +//! - `about` — the number of `about` input edges. +//! - `attested` — `fresh` / `stale` / `–` via [`bridge::load_attestation`]. +//! - `verifies` — `✓` / `✗` / `–` via the DID-match-then-verify rule (identical +//! to the intent list; see [`compute_verifies`]). +//! +//! Enumeration reuses `repo.vault_list("memory/", None)` — the exact call +//! `atomic vault memory list` makes; the `memory/` prefix already excludes +//! attestation entries (which live under `attestations/memory/…`), and a +//! belt-and-suspenders `!starts_with("attestations/")` filter guards it. + +use clap::Parser; + +use atomic_canonical::did::did_for_public_key; +use atomic_canonical::MemoryNode; +use atomic_identity::keypair::PublicKey; +use atomic_identity::IdentityStore; +use atomic_repository::Repository; + +use crate::commands::memory::bridge; +use crate::commands::{find_repository_root, Command}; +use crate::error::{CliError, CliResult}; + +/// The EN DASH used everywhere for a "not applicable" cell. +const NA: &str = "–"; + +/// List the vault's memories with attestation + verification status. +#[derive(Parser, Debug)] +#[command(name = "list")] +pub struct MemoryList { + /// Identity whose public key to verify attestations against. Defaults to the + /// current default identity. If no identity can be resolved at all, every + /// `verifies` cell is `–` rather than the whole command erroring. + #[arg(long)] + pub identity: Option<String>, + + /// Output as JSON (an array of {id,kind,status,about,attested,verifies}). + #[arg(long)] + pub json: bool, +} + +/// The classification of one memory's attestation, for a table/JSON row. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum Attested { + Fresh, + Stale, + None, +} + +impl Attested { + fn table(self) -> &'static str { + match self { + Attested::Fresh => "fresh", + Attested::Stale => "stale", + Attested::None => NA, + } + } + + fn json(self) -> &'static str { + match self { + Attested::Fresh => "fresh", + Attested::Stale => "stale", + Attested::None => "none", + } + } +} + +/// The result of the DID-match-then-verify rule for one row. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum Verifies { + Yes, + No, + Na, +} + +impl Verifies { + fn table(self) -> &'static str { + match self { + Verifies::Yes => "✓", + Verifies::No => "✗", + Verifies::Na => NA, + } + } + + fn json(self) -> &'static str { + match self { + Verifies::Yes => "yes", + Verifies::No => "no", + Verifies::Na => "na", + } + } +} + +/// A fully-computed memory row. +struct Row { + id: String, + kind: String, + status: String, + about: usize, + attested: Attested, + verifies: Verifies, +} + +/// The verifying identity resolved ONCE for the whole list. +struct Verifier { + public_key: PublicKey, + did: String, +} + +/// Resolve the verifying identity exactly as `memory verify` does, but SOFT: a +/// missing default (or no store) yields `Ok(None)` (all verifies `–`); a +/// `--identity <name>` that does not exist IS a hard error. +fn resolve_verifier(name: &Option<String>) -> CliResult<Option<Verifier>> { + let store = match IdentityStore::open_default() { + Ok(s) => s, + Err(_) => return Ok(None), + }; + let identity = if let Some(name) = name { + Some( + store + .load_by_name(name) + .map_err(|_| CliError::IdentityNotFound(name.clone()))?, + ) + } else { + store.get_default().ok().flatten() + }; + Ok(identity.map(|id| Verifier { + did: did_for_public_key(&id.public_key), + public_key: id.public_key, + })) +} + +/// The DID-match-then-verify rule for a memory. Pure over its inputs so it can be +/// unit-tested without a global `IdentityStore`. See the intent list's +/// `compute_verifies` for the full rationale — identical rule, `verify_memory`. +fn compute_verifies( + attested: &bridge::Attestation, + verifier: Option<&Verifier>, +) -> Verifies { + let node = match attested { + bridge::Attestation::Fresh(node) => node, + bridge::Attestation::Stale(_) | bridge::Attestation::None => return Verifies::Na, + }; + let verifier = match verifier { + Some(v) => v, + None => return Verifies::Na, + }; + match node.attributed_to.as_deref() { + Some(signer) if signer == verifier.did => {} + _ => return Verifies::Na, + } + match atomic_canonical::verify_memory(node, &verifier.public_key) { + Ok(()) => Verifies::Yes, + Err(_) => Verifies::No, + } +} + +/// The `(kind, status, about)` display columns for a memory. Prefers the attested +/// node when Fresh/Stale; falls back to a lenient lift of the raw memory when +/// there is no attestation. NEVER runs closed-vocab directive parsing over the +/// prose — `lift_memory` does the lenient `:::memory` scan. A lift failure +/// degrades to the raw frontmatter `memoryKind`/`status` (or `–`) and about 0. +fn kind_status_about( + node: Option<&MemoryNode>, + inputs: &bridge::MemLiftInputs, +) -> (String, String, usize) { + if let Some(node) = node { + return ( + node.memory_kind.clone(), + node.status.clone(), + node.about.len(), + ); + } + match bridge::lift(inputs) { + Ok(node) => (node.memory_kind, node.status, node.about.len()), + Err(_) => { + let fm = |k: &str| { + inputs + .frontmatter + .get(k) + .and_then(|v| v.as_str()) + .map(str::to_owned) + .unwrap_or_else(|| NA.to_string()) + }; + (fm("memoryKind"), fm("status"), 0) + } + } +} + +/// The node whose fields drive the display columns (kind/status/about) — only a +/// FRESH attestation. A Stale attestation is treated like None here so those +/// columns come from the CURRENT source (via `bridge::lift`), matching +/// `memory show`; the drift is still surfaced by the `attested` column ("stale"). +/// (The `verifies` column reads the full `Attestation` separately.) +fn attested_node(attested: &bridge::Attestation) -> Option<&MemoryNode> { + match attested { + bridge::Attestation::Fresh(n) => Some(n), + bridge::Attestation::Stale(_) | bridge::Attestation::None => None, + } +} + +/// Classify a loaded attestation into the `attested` column token. +fn classify(attested: &bridge::Attestation) -> Attested { + match attested { + bridge::Attestation::Fresh(_) => Attested::Fresh, + bridge::Attestation::Stale(_) => Attested::Stale, + bridge::Attestation::None => Attested::None, + } +} + +/// Compute one memory's row. A read/lift/attestation failure for a SINGLE memory +/// degrades that row's computed columns to `–`/0 rather than aborting the list. +fn compute_row(repo: &Repository, id: &str, verifier: Option<&Verifier>) -> Row { + let inputs = match bridge::read_memory(repo, id) { + Ok(i) => i, + Err(_) => { + return Row { + id: id.to_string(), + kind: NA.to_string(), + status: NA.to_string(), + about: 0, + attested: Attested::None, + verifies: Verifies::Na, + } + } + }; + let attestation = bridge::load_attestation(repo, id, &inputs); + let (attested, verifies, node_owned) = match attestation { + Ok(a) => { + let verifies = compute_verifies(&a, verifier); + (classify(&a), verifies, Some(a)) + } + Err(_) => (Attested::None, Verifies::Na, None), + }; + let node = node_owned.as_ref().and_then(attested_node); + let (kind, status, about) = kind_status_about(node, &inputs); + Row { + id: id.to_string(), + kind, + status, + about, + attested, + verifies, + } +} + +impl Command for MemoryList { + fn run(&self) -> CliResult<()> { + let root = find_repository_root()?; + let repo = Repository::open(&root).map_err(CliError::Repository)?; + + let verifier = resolve_verifier(&self.identity)?; + + // Enumerate via the SAME call `atomic vault memory list` makes; the + // `memory/` prefix already excludes attestation entries, and the filter + // is a belt-and-suspenders guard (mirrors memory/mod.rs' invariant test). + let entries = repo + .vault_list("memory/", None) + .map_err(CliError::Repository)?; + let mut ids: Vec<String> = entries + .iter() + .filter(|e| !e.path.starts_with("attestations/")) + // The default `memory/MEMORY.md` index scaffold is NOT a canonical + // memory (no `uid`/`memoryKind`; its frontmatter is `type:index`). + // Skip it so the attestation-aware list only shows real memories. + .filter(|e| !is_index_scaffold(&repo, &e.path)) + .map(|e| bridge::memory_id(&e.path)) + .collect(); + // vault_list is prefix-scan order, not sorted: sort by id for stability. + ids.sort(); + + let rows: Vec<Row> = ids + .iter() + .map(|id| compute_row(&repo, id, verifier.as_ref())) + .collect(); + + if self.json { + let json: Vec<serde_json::Value> = rows + .iter() + .map(|r| { + serde_json::json!({ + "id": r.id, + "kind": r.kind, + "status": r.status, + "about": r.about, + "attested": r.attested.json(), + "verifies": r.verifies.json(), + }) + }) + .collect(); + println!("{}", serde_json::to_string_pretty(&json).unwrap()); + return Ok(()); + } + + if rows.is_empty() { + println!("No memories found."); + return Ok(()); + } + + // Fixed-width, left-aligned columns with a header row. + let id_w = col_width(rows.iter().map(|r| r.id.chars().count()), "id"); + let kind_w = col_width(rows.iter().map(|r| r.kind.chars().count()), "kind"); + let status_w = col_width(rows.iter().map(|r| r.status.chars().count()), "status"); + + println!( + " {:<id_w$} {:<kind_w$} {:<status_w$} {:>5} {:<8} verifies", + "id", "kind", "status", "about", "attested", + ); + for r in &rows { + println!( + " {:<id_w$} {:<kind_w$} {:<status_w$} {:>5} {:<8} {}", + r.id, + r.kind, + r.status, + r.about, + r.attested.table(), + r.verifies.table(), + ); + } + + Ok(()) + } +} + +/// The width of a column: the widest row cell, but at least the header width. +fn col_width(cell_lens: impl Iterator<Item = usize>, header: &str) -> usize { + let header_w = header.chars().count(); + cell_lens.chain(std::iter::once(header_w)).max().unwrap_or(header_w) +} + +/// Is this `memory/…` entry the vault's index scaffold rather than a real +/// canonical memory? The default `memory/MEMORY.md` installed by `init_vault` +/// carries frontmatter `{"name":"MEMORY","type":"index"}` — it has no +/// `uid`/`memoryKind` and is not attestable, so it must not appear as a row in +/// the canonical, attestation-aware list. Detection reads the entry's declared +/// `type == "index"` frontmatter (fail-open: a read error is treated as "not an +/// index" so a genuine memory is never silently hidden). +fn is_index_scaffold(repo: &Repository, path: &str) -> bool { + let Ok(Some(entry)) = repo.vault_retrieve(path) else { + return false; + }; + serde_json::from_str::<serde_json::Value>(&entry.frontmatter_json) + .ok() + .and_then(|v| v.get("type").and_then(|t| t.as_str()).map(str::to_owned)) + .as_deref() + == Some("index") +} + +#[cfg(test)] +mod tests { + use super::*; + use atomic_canonical::lift_and_attest_memory; + use atomic_core::pristine::VaultEntryType; + use atomic_identity::identity::Identity; + use atomic_identity::keypair::KeyPair; + use serde_json::{Map, Value}; + use tempfile::tempdir; + + /// A fresh repo+vault. + fn repo() -> (Repository, tempfile::TempDir) { + let dir = tempdir().unwrap(); + let repo = Repository::init(dir.path()).unwrap(); + repo.init_vault().unwrap(); + (repo, dir) + } + + /// Store a memory via the GENERIC vault path (as `memory write`/attest do). + fn store_memory(repo: &Repository, id: &str, kind: &str, about: &[&str], body: &str) { + let mut spine = Map::new(); + spine.insert("uid".into(), Value::String(id.to_string())); + spine.insert("memoryKind".into(), Value::String(kind.to_string())); + spine.insert("status".into(), Value::String("active".into())); + spine.insert( + "createdAt".into(), + Value::String("2026-07-01T00:00:00+00:00".into()), + ); + if !about.is_empty() { + spine.insert( + "about".into(), + Value::Array(about.iter().map(|a| Value::String(a.to_string())).collect()), + ); + } + let path = bridge::normalize_memory_path(id); + repo.vault_store( + &path, + VaultEntryType::Memory, + body.as_bytes().to_vec(), + serde_json::to_string(&spine).unwrap(), + ) + .unwrap(); + } + + /// Lift+attest a stored memory with the given keypair. + fn attest_with(repo: &Repository, id: &str, kp: &KeyPair) -> MemoryNode { + let inputs = bridge::read_memory(repo, id).unwrap(); + let identity = Identity::new("tester", kp); + lift_and_attest_memory(&inputs.frontmatter, &inputs.body, &identity, kp).unwrap() + } + + /// Mirror `attest`'s tracked-vault write (body = pretty JSON + '\n'). + fn write_tracked(repo: &Repository, id: &str, node: &MemoryNode) { + let inputs = bridge::read_memory(repo, id).unwrap(); + let mut body = serde_json::to_string_pretty(&node.to_value()).unwrap(); + body.push('\n'); + let mut fm = Map::new(); + fm.insert("memoryId".into(), Value::String(bridge::memory_id(id))); + fm.insert( + "sourceContentHash".into(), + Value::String(bridge::source_content_hash(&inputs)), + ); + let vpath = bridge::attestation_vault_path(id); + repo.vault_store( + &vpath, + VaultEntryType::Attestation, + body.into_bytes(), + serde_json::to_string(&fm).unwrap(), + ) + .unwrap(); + } + + /// Compute a row with an explicit verifier keypair (no global store). + fn row_for(repo: &Repository, id: &str, kp: Option<&KeyPair>) -> Row { + let verifier = kp.map(|kp| Verifier { + did: did_for_public_key(&kp.public), + public_key: kp.public.clone(), + }); + compute_row(repo, id, verifier.as_ref()) + } + + #[test] + fn unattested_memory_lists_columns_from_lift() { + let (repo, _dir) = repo(); + store_memory(&repo, "m1", "constraint", &[], ":::memory\nA fact.\n:::"); + let row = row_for(&repo, "m1", Some(&KeyPair::generate())); + assert_eq!(row.kind, "constraint"); + assert_eq!(row.status, "active"); + assert_eq!(row.about, 0); + assert_eq!(row.attested, Attested::None); + assert_eq!(row.verifies, Verifies::Na); + } + + #[test] + fn attested_fresh_populates_about_and_verifies() { + let (repo, _dir) = repo(); + store_memory( + &repo, + "m2", + "lesson", + &["urn:atomic:module:a", "urn:atomic:module:b"], + ":::memory\nThe durable lesson.\n:::", + ); + let kp = KeyPair::generate(); + let node = attest_with(&repo, "m2", &kp); + write_tracked(&repo, "m2", &node); + + let row = row_for(&repo, "m2", Some(&kp)); + assert_eq!(row.kind, "lesson"); + assert_eq!(row.about, 2, "about count = node.about.len()"); + assert_eq!(row.attested, Attested::Fresh); + assert_eq!(row.verifies, Verifies::Yes); + } + + #[test] + fn other_signer_is_na_not_x() { + let (repo, _dir) = repo(); + store_memory(&repo, "m3", "context", &[], ":::memory\nX.\n:::"); + let k1 = KeyPair::generate(); + let k2 = KeyPair::generate(); + let node = attest_with(&repo, "m3", &k1); + write_tracked(&repo, "m3", &node); + + let row = row_for(&repo, "m3", Some(&k2)); + assert_eq!(row.attested, Attested::Fresh); + assert_eq!(row.verifies, Verifies::Na, "other-signer ⇒ '–', not '✗'"); + } + + #[test] + fn no_identity_soft_fails_to_na() { + let (repo, _dir) = repo(); + store_memory(&repo, "m4", "context", &[], ":::memory\nX.\n:::"); + let kp = KeyPair::generate(); + let node = attest_with(&repo, "m4", &kp); + write_tracked(&repo, "m4", &node); + + let row = row_for(&repo, "m4", None); + assert_eq!(row.attested, Attested::Fresh); + assert_eq!(row.verifies, Verifies::Na); + } + + #[test] + fn never_grades_prose() { + // A memory whose body legitimately contains ':::why' text or a Rust + // turbofish '::<T>' still lists cleanly because lift_memory does the + // lenient scan (no closed-vocab grading of prose). + let (repo, _dir) = repo(); + let body = ":::memory\nUse ::<T> and note the :::why here is prose.\n:::"; + store_memory(&repo, "m5", "preference", &[], body); + + let row = row_for(&repo, "m5", Some(&KeyPair::generate())); + assert_eq!(row.kind, "preference"); + assert_eq!(row.status, "active"); + assert_eq!(row.about, 0); + assert_eq!(row.attested, Attested::None); + } + + #[test] + fn default_memory_index_scaffold_is_excluded() { + // A fresh vault installs `memory/MEMORY.md` (type:index). It must NOT + // appear as a memory row in the canonical list; only real memories do. + let (repo, _dir) = repo(); + assert!( + is_index_scaffold(&repo, "memory/MEMORY.md"), + "the default index scaffold is detected" + ); + store_memory(&repo, "real1", "context", &[], ":::memory\nX.\n:::"); + let ids: Vec<String> = repo + .vault_list("memory/", None) + .unwrap() + .iter() + .filter(|e| !e.path.starts_with("attestations/")) + .filter(|e| !is_index_scaffold(&repo, &e.path)) + .map(|e| bridge::memory_id(&e.path)) + .collect(); + assert_eq!(ids, vec!["real1".to_string()], "only the real memory lists"); + } + + #[test] + fn attestation_entry_never_a_row() { + // Mirror memory/mod.rs: after attesting, vault_list("memory/") contains the + // memory entry but no path under attestations/. + let (repo, _dir) = repo(); + store_memory(&repo, "m6", "context", &[], ":::memory\nX.\n:::"); + let kp = KeyPair::generate(); + let node = attest_with(&repo, "m6", &kp); + write_tracked(&repo, "m6", &node); + + let listed = repo.vault_list("memory/", None).unwrap(); + assert!( + listed.iter().all(|e| !e.path.starts_with("attestations/")), + "attestation entries must not appear under the memory/ prefix" + ); + assert!( + listed.iter().any(|e| e.path == "memory/m6.md"), + "the memory entry itself is listed" + ); + // And it never becomes its own row id (applying the same production + // filters: no attestations/, no index scaffold). + let ids: Vec<String> = listed + .iter() + .filter(|e| !e.path.starts_with("attestations/")) + .filter(|e| !is_index_scaffold(&repo, &e.path)) + .map(|e| bridge::memory_id(&e.path)) + .collect(); + assert_eq!(ids, vec!["m6".to_string()]); + } +} diff --git a/atomic-cli/src/commands/memory/mod.rs b/atomic-cli/src/commands/memory/mod.rs index 7d821079..cef04edc 100644 --- a/atomic-cli/src/commands/memory/mod.rs +++ b/atomic-cli/src/commands/memory/mod.rs @@ -36,12 +36,14 @@ use crate::error::CliResult; pub mod attest; pub mod bridge; +pub mod list; pub mod new; pub mod show; pub mod validate; pub mod verify; pub use attest::MemoryAttest; +pub use list::MemoryList; pub use new::MemoryNew; pub use show::MemoryShow; pub use validate::MemoryValidate; @@ -128,6 +130,22 @@ pub enum MemoryCommands { /// atomic memory verify 01j8zc4r8t --identity alice-work /// ``` Verify(MemoryVerify), + + /// List the vault's memories, attestation-aware. + /// + /// The canonical-family analogue of `atomic vault memory list`: alongside the + /// id it adds the memory's kind/status/about-count (lifted, never graded), an + /// `attested` column (fresh / stale / –) and a `verifies` column (✓ / ✗ / –) + /// with the same DID-match-then-verify rule as `atomic intent list`. + /// + /// # Examples + /// + /// ```text + /// atomic memory list + /// atomic memory list --identity alice-work + /// atomic memory list --json + /// ``` + List(MemoryList), } /// Record the "why" for durable context: lift, validate, attest, and render @@ -152,6 +170,7 @@ impl Command for Memory { MemoryCommands::Validate(cmd) => cmd.run(), MemoryCommands::Attest(cmd) => cmd.run(), MemoryCommands::Verify(cmd) => cmd.run(), + MemoryCommands::List(cmd) => cmd.run(), } } } From 2d8ce04c38187e5d792e5e71623b66e07bcb8373 Mon Sep 17 00:00:00 2001 From: Bradley Hilton <graywolf336@craftyn.com> Date: Thu, 2 Jul 2026 12:08:38 -0500 Subject: [PATCH 07/21] fix(cli): materialize attestations on attest; reclassify no-default-identity; doc/help accuracy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Follow-ups from the acceptance-test pass (48/48 then 51/51, 0 fails): - W1: `intent attest` / `memory attest` now `vault_materialize` the tracked attestation entry after storing it, so it exists in the `.vault/` working tree (matching the printed path) and is captured by a subsequent `atomic record` (i.e. it travels via the change graph). Previously the entry was in redb but never materialized to disk. - W3: a missing default identity in attest/verify was wrongly wrapped in CliError::Internal (exit 128 + "this is a bug, report it"). It is a normal user-recoverable state — reclassified to CliError::InvalidArgument (exit 2) with the same actionable "create one first" message. Applied to intent+memory attest and verify. - Docs/help accuracy: `attest` help/comments said "No VaultEntry is touched" / "canonical sidecar", which predated the tracked-entry change and now said the opposite of the behavior — corrected to describe the tracked attestation entry (existing blake3(body) storage hash; the source's own content_hash is never redefined). Added a spec note that id-based verbs read the vault DB (run `atomic vault sync` after hand-edits) and that `vault sync` detects changes by body only, so frontmatter-only edits may not be picked up. Not changed: W2 (alleged memory stale-body/hash "bug") was a test-harness artifact (DB-vs-disk + body-only storage hash), verified — no code change. The frontmatter-only-sync limitation is pre-existing atomic behavior (content_hash = blake3(body)); documented, not modified here. atomic-cli + docs only; engine/core/raw-vault untouched. 1564 atomic-cli tests + 51 atomic-canonical pass; clippy clean; both fixes verified end-to-end and by a fresh 51/51 acceptance re-run. --- atomic-cli/src/commands/intent/attest.rs | 16 ++++++++++------ atomic-cli/src/commands/intent/mod.rs | 11 +++++++---- atomic-cli/src/commands/intent/verify.rs | 9 ++++----- atomic-cli/src/commands/memory/attest.rs | 14 +++++++++----- atomic-cli/src/commands/memory/mod.rs | 7 ++++--- atomic-cli/src/commands/memory/verify.rs | 9 ++++----- docs/recording-the-why.md | 4 ++++ 7 files changed, 42 insertions(+), 28 deletions(-) diff --git a/atomic-cli/src/commands/intent/attest.rs b/atomic-cli/src/commands/intent/attest.rs index 4fcacfcb..f96f8904 100644 --- a/atomic-cli/src/commands/intent/attest.rs +++ b/atomic-cli/src/commands/intent/attest.rs @@ -1,4 +1,4 @@ -//! `atomic intent attest <ID>` — sign an intent into a canonical sidecar. +//! `atomic intent attest <ID>` — sign an intent into a tracked attestation entry. use clap::Parser; @@ -73,11 +73,10 @@ impl Command for IntentAttest { .map_err(|e| { CliError::Internal(anyhow::anyhow!("Failed to load default identity: {}", e)) })? - .ok_or_else(|| { - CliError::Internal(anyhow::anyhow!( - "No default identity set. Create one first:\n \ - atomic identity new <name> --email <email> --set-default" - )) + .ok_or_else(|| CliError::InvalidArgument { + message: "No default identity set. Create one first:\n \ + atomic identity new <name> --email <email> --set-default" + .to_string(), })? }; let keypair = store.load_keypair(&identity.id, None).map_err(|e| { @@ -182,6 +181,11 @@ impl Command for IntentAttest { frontmatter_json, ) .map_err(CliError::Repository)?; + // Materialize the tracked attestation into the .vault/ working tree so it + // exists on disk (matching the printed path) and is captured by a later + // `atomic record` — i.e. it travels via the change graph like any entry. + repo.vault_materialize(&vault_path) + .map_err(CliError::Repository)?; let did = node .attributed_to diff --git a/atomic-cli/src/commands/intent/mod.rs b/atomic-cli/src/commands/intent/mod.rs index 92a4fe3c..ca8758d8 100644 --- a/atomic-cli/src/commands/intent/mod.rs +++ b/atomic-cli/src/commands/intent/mod.rs @@ -13,7 +13,7 @@ //! atomic intent validate <ID|path> Gate an intent against the canonical shapes //! atomic intent show <ID> Render an intent as a read-time projection //! atomic intent new <TITLE> Scaffold a directive-based intent -//! atomic intent attest <ID> Sign an intent into a canonical sidecar +//! atomic intent attest <ID> Sign an intent into a tracked attestation entry //! atomic intent verify <ID> Verify a signed intent's attestation //! ``` //! @@ -94,13 +94,16 @@ pub enum IntentCommands { /// ``` New(IntentNew), - /// Attest an intent: sign it into a canonical sidecar. + /// Attest an intent: sign it into a tracked attestation entry. /// /// Gates the intent first (refusing to sign a non-conforming node), /// fills `attributedTo` from the signing identity's `did:atomic`, signs /// the canonical node, re-gates the attested result, and writes the node - /// (with embedded contentHash + proof) to a sidecar under `.atomic/`. - /// No `VaultEntry`, `content_hash`, or merkle is touched. + /// (with embedded contentHash + proof) as a tracked vault entry at + /// `attestations/<id>/attested.md` (dual-written to a legacy `.atomic/` + /// sidecar during transition). The attestation entry uses the vault's + /// existing `blake3(body)` storage hash; the intent's own `content_hash` + /// is never redefined. /// /// # Examples /// diff --git a/atomic-cli/src/commands/intent/verify.rs b/atomic-cli/src/commands/intent/verify.rs index 5a562656..0adc7a9e 100644 --- a/atomic-cli/src/commands/intent/verify.rs +++ b/atomic-cli/src/commands/intent/verify.rs @@ -72,11 +72,10 @@ impl Command for IntentVerify { .map_err(|e| { CliError::Internal(anyhow::anyhow!("Failed to load default identity: {}", e)) })? - .ok_or_else(|| { - CliError::Internal(anyhow::anyhow!( - "No default identity set. Create one first:\n \ - atomic identity new <name> --email <email> --set-default" - )) + .ok_or_else(|| CliError::InvalidArgument { + message: "No default identity set. Create one first:\n \ + atomic identity new <name> --email <email> --set-default" + .to_string(), })? }; diff --git a/atomic-cli/src/commands/memory/attest.rs b/atomic-cli/src/commands/memory/attest.rs index 6680f8ff..70b33711 100644 --- a/atomic-cli/src/commands/memory/attest.rs +++ b/atomic-cli/src/commands/memory/attest.rs @@ -74,11 +74,10 @@ impl Command for MemoryAttest { .map_err(|e| { CliError::Internal(anyhow::anyhow!("Failed to load default identity: {}", e)) })? - .ok_or_else(|| { - CliError::Internal(anyhow::anyhow!( - "No default identity set. Create one first:\n \ - atomic identity new <name> --email <email> --set-default" - )) + .ok_or_else(|| CliError::InvalidArgument { + message: "No default identity set. Create one first:\n \ + atomic identity new <name> --email <email> --set-default" + .to_string(), })? }; let keypair = store.load_keypair(&identity.id, None).map_err(|e| { @@ -164,6 +163,11 @@ impl Command for MemoryAttest { frontmatter_json, ) .map_err(CliError::Repository)?; + // Materialize the tracked attestation into the .vault/ working tree so it + // exists on disk (matching the printed path) and is captured by a later + // `atomic record` — i.e. it travels via the change graph like any entry. + repo.vault_materialize(&vault_path) + .map_err(CliError::Repository)?; let did = node.attributed_to.as_deref().unwrap_or("(unknown)"); let proof_prefix = node diff --git a/atomic-cli/src/commands/memory/mod.rs b/atomic-cli/src/commands/memory/mod.rs index cef04edc..03e1ba60 100644 --- a/atomic-cli/src/commands/memory/mod.rs +++ b/atomic-cli/src/commands/memory/mod.rs @@ -104,9 +104,10 @@ pub enum MemoryCommands { /// Gates the memory first (refusing to sign a node that fails for a reason /// signing cannot fix), fills `attributedTo` from the signing identity, /// signs the canonical node, re-gates the attested result, and writes the - /// node (with embedded contentHash + proof) to a tracked vault entry - /// (dual-written to a legacy sidecar). No memory entry, `content_hash`, or - /// merkle is touched. + /// node (with embedded contentHash + proof) to a tracked vault entry at + /// `attestations/memory/<id>/attested.md` (dual-written to a legacy sidecar). + /// The source memory is unchanged and the vault's hashing scheme is + /// untouched — a new attestation entry is simply added. /// /// # Examples /// diff --git a/atomic-cli/src/commands/memory/verify.rs b/atomic-cli/src/commands/memory/verify.rs index 6fe25e90..ffdc64f4 100644 --- a/atomic-cli/src/commands/memory/verify.rs +++ b/atomic-cli/src/commands/memory/verify.rs @@ -70,11 +70,10 @@ impl Command for MemoryVerify { .map_err(|e| { CliError::Internal(anyhow::anyhow!("Failed to load default identity: {}", e)) })? - .ok_or_else(|| { - CliError::Internal(anyhow::anyhow!( - "No default identity set. Create one first:\n \ - atomic identity new <name> --email <email> --set-default" - )) + .ok_or_else(|| CliError::InvalidArgument { + message: "No default identity set. Create one first:\n \ + atomic identity new <name> --email <email> --set-default" + .to_string(), })? }; diff --git a/docs/recording-the-why.md b/docs/recording-the-why.md index b17b8cb5..822675f4 100644 --- a/docs/recording-the-why.md +++ b/docs/recording-the-why.md @@ -489,6 +489,10 @@ atomic intent validate WORD-5 Runs the SHACL gate against the lifted node and prints the report. On failure you get the failing node, the shape it broke, and the message. The same check runs automatically at the transition to `done`, so validate-by-hand is for authoring. The gate is for the system. +> **Editing note — sync after you edit, and edit the body.** The id-based verbs (`validate`/`show`/`attest`/`verify <id>`) read the *recorded* entry from the vault DB, not the raw `.vault/…/*.md` file on disk. If you hand-edit an entry's markdown, run `atomic vault sync` first (or those commands will silently act on the pre-edit state). To gate an unrecorded file directly, `atomic intent validate ./path.md` reads the file itself and skips the DB. +> +> Caveat: `vault sync` detects changes by the entry **body** (the vault's storage hash is `blake3(body)`, frontmatter excluded), so a *frontmatter-only* hand-edit — e.g. flipping `status` — may not be picked up ("Vault is up to date"). Change status/metadata through the workflow (the gate grants `status` on transition) rather than by hand-editing frontmatter. + **Show the flywheel chain for a change:** ``` From de557f8f6870beccca6af856e241a6ea92c4c3b8 Mon Sep 17 00:00:00 2001 From: Bradley Hilton <graywolf336@craftyn.com> Date: Thu, 2 Jul 2026 13:43:28 -0500 Subject: [PATCH 08/21] feat(canonical,cli): W3C PROV provenance projection (spine slice) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Project a change's ProvenanceGraph into a signed W3C PROV-O JSON-LD subgraph on demand — the third core record ("why did this change happen"), read-only and off the capture path. atomic-canonical (atomic-core independent): - prov.rs: project(ProvActivityInput) -> PROV-O @graph (prov:Activity / SoftwareAgent / Person, generated / wasAssociatedWith / actedOnBehalfOf / turnParent), named subgraph urn:atomic:provgraph:<changeid>; attest_prov / verify_prov over the Data Integrity eddsa-jcs-2022 envelope. - Agent @id is a non-verifiable label (urn:atomic:agent:<slug>); only the Person's did:atomic signs. used-edge deferred (emitted empty). atomic-cli: - `atomic provenance {trace,show}`: trace prints the human flywheel chain, show emits signed JSON-LD (--json). Compute-on-demand: writes nothing. mapping.rs is the sole atomic-core boundary; activity id is graph-stable (<session>#<first-explained-change>) so turnParent joins. - atomic-repository: find_provenance_for_change with disk-scan fallback for changes never made internal (invisible to REV_DEPS). Integration test drives the real binary end-to-end: save a real graph -> show -> parse -> verify_prov against the resolved key -> trace -> assert nothing written. Capture path (atomic-agent) and atomic-core content hashing untouched. --- atomic-canonical/src/lib.rs | 2 + atomic-canonical/src/prov.rs | 368 ++++++++++++++++++ atomic-cli/src/commands/mod.rs | 2 + atomic-cli/src/commands/provenance/command.rs | 346 ++++++++++++++++ atomic-cli/src/commands/provenance/mapping.rs | 86 ++++ atomic-cli/src/commands/provenance/mod.rs | 91 +++++ atomic-cli/src/main.rs | 22 ++ .../tests/provenance_integration_test.rs | 301 ++++++++++++++ atomic-repository/src/repository/changes.rs | 36 ++ docs/recording-the-why.md | 7 +- 10 files changed, 1259 insertions(+), 2 deletions(-) create mode 100644 atomic-canonical/src/prov.rs create mode 100644 atomic-cli/src/commands/provenance/command.rs create mode 100644 atomic-cli/src/commands/provenance/mapping.rs create mode 100644 atomic-cli/src/commands/provenance/mod.rs create mode 100644 atomic-cli/tests/provenance_integration_test.rs diff --git a/atomic-canonical/src/lib.rs b/atomic-canonical/src/lib.rs index 8cb16915..c49bab50 100644 --- a/atomic-canonical/src/lib.rs +++ b/atomic-canonical/src/lib.rs @@ -38,6 +38,7 @@ pub mod lift; pub mod memory; pub mod node; pub mod proof; +pub mod prov; pub mod render; pub mod vocab; @@ -47,6 +48,7 @@ pub use memory::MemoryNode; pub use node::{ AcceptanceCriterion, CanonicalNode, Constraint, Proof, Ref, ScopeItem, Task, }; +pub use prov::{attest_prov, project, verify_prov, ProvActivityInput}; pub use render::{render, render_memory, Target}; use atomic_identity::identity::Identity; diff --git a/atomic-canonical/src/prov.rs b/atomic-canonical/src/prov.rs new file mode 100644 index 00000000..653d2af9 --- /dev/null +++ b/atomic-canonical/src/prov.rs @@ -0,0 +1,368 @@ +//! W3C PROV projection — a signed PROV JSON-LD named subgraph over one turn's +//! provenance. +//! +//! This is a **projection** of provenance atomic already captures (a per-turn +//! `ProvenanceGraph`), NOT new capture. Given a plain input struct describing a +//! turn's activity, [`project`] builds the named-subgraph JSON-LD described in +//! `docs/recording-the-why.md` §"A provenance graph", and [`attest_prov`] / +//! [`verify_prov`] sign and verify it through the *same* canonicalization/signing +//! path every other node type uses ([`crate::proof::attest_value`]). +//! +//! ## Layering +//! This module — like the rest of `atomic-canonical` — is **`atomic-core` +//! independent**. The projector takes a fully-owned plain [`ProvActivityInput`] +//! (no `atomic-core` types, no `Hash`); the `atomic-core::ProvenanceGraph -> +//! ProvActivityInput` mapping (and all base32/`Hash` handling) lives at the +//! `atomic-cli` boundary. Do not add `use atomic_core::` here. +//! +//! ## Two deliberate divergences from the doc example +//! 1. **Agent id is a URN, not a DID.** The doc example (recording-the-why.md +//! lines 322/333) shows `did:atomic:agent:claude`. That is illustrative and +//! *wrong* per the hard scope: `did:atomic:<..>` is a key **fingerprint**, not +//! a name (see [`crate::did`]). The `SoftwareAgent` here is a NON-VERIFIABLE +//! descriptive label, so its `@id` is `urn:atomic:agent:<slug>`. Only the +//! **person's** key signs the whole `@graph`; nothing about the agent is +//! signed-as-an-identity. +//! 2. **A top-level `attributedTo` (+ `contentHash`/`proof`) envelope.** The +//! doc `@graph` has no top-level `attributedTo`; [`crate::proof::attest_value`] +//! injects one from the signer's `did:atomic` (the Person), and we ACCEPT it +//! rather than build a bespoke signing path that skips the injection. It is +//! semantically correct (that is who signed and on whose behalf the activity +//! ran), consistent with Intent/Memory nodes, and — being inside the +//! hashing/signing view — strengthens the artifact by binding the whole +//! subgraph to the signer. The signed artifact's top level therefore carries +//! `@context`, `@id`, `@graph`, `attributedTo`, `contentHash`, `proof`, with +//! the PROV nodes inside `@graph`. +//! +//! ## The flywheel `used` edge is DEFERRED +//! The activity's `used` edge (what the turn pulled from the vault) is emitted as +//! an EMPTY array literal (`"used": []`). It is intentionally not populated in +//! this slice and is not an input field. + +use atomic_identity::identity::Identity; +use atomic_identity::keypair::{KeyPair, PublicKey}; +use serde_json::{json, Map, Value}; + +use crate::node::CONTEXT_URL; +use crate::proof; +use crate::Result; + +/// Plain, fully-owned input to [`project`]. Carries no `atomic-core` types so the +/// projector stays `atomic-core` independent — the mapping from +/// `atomic_core::change::ProvenanceGraph` (and all `Hash::to_base32()` handling) +/// is done at the `atomic-cli` boundary. +#[derive(Debug, Clone, PartialEq)] +pub struct ProvActivityInput { + /// Base32 of the change hash this graph explains. Names the subgraph + /// (`urn:atomic:provgraph:<change_id_base32>`). REQUIRED. + pub change_id_base32: String, + /// Stable id for the turn activity (`urn:atomic:activity:<activity_id>`). + /// Use `session_id` (or `session_id#<change_id_base32>` when a session has + /// multiple turn-graphs) so distinct turn-activities never collide. + pub activity_id: String, + /// RFC3339 start time, or `None` to omit `prov:startedAtTime`. + pub started_at: Option<String>, + /// RFC3339 end time, or `None` to omit `prov:endedAtTime`. + pub ended_at: Option<String>, + /// Agent slug (`urn:atomic:agent:<slug>`) — a LABEL, non-DID. + pub agent_slug: String, + /// Human label for the `SoftwareAgent` (`prov:label`). + pub agent_display_name: String, + /// Optional vendor label on the `SoftwareAgent`. + pub agent_vendor: Option<String>, + /// The real signer's `did:atomic:<base32(blake3(pubkey))>` (the Person and + /// the `actedOnBehalfOf` target). + pub person_did: String, + /// `urn:atomic:change:<base32>` for each explained change (PROV `generated`). + pub generated: Vec<String>, + /// `urn:atomic:activity:<parent-activity-id>` (PROV `wasInformedBy` / + /// `turnParent`), or `None` to omit the key entirely. + pub turn_parent: Option<String>, + // `used: []` is DEFERRED — intentionally NOT a field. +} + +/// `urn:atomic:change:<base32>` for a change hash's base32 form. +pub fn change_urn(change_id_base32: &str) -> String { + format!("urn:atomic:change:{change_id_base32}") +} + +/// `urn:atomic:provgraph:<base32>` — the named-subgraph `@id`. +pub fn provgraph_urn(change_id_base32: &str) -> String { + format!("urn:atomic:provgraph:{change_id_base32}") +} + +/// `urn:atomic:activity:<activity_id>` — the `prov:Activity` `@id`. +pub fn activity_urn(activity_id: &str) -> String { + format!("urn:atomic:activity:{activity_id}") +} + +/// `urn:atomic:agent:<slug>` — the `prov:SoftwareAgent` `@id` (a LABEL, non-DID). +pub fn agent_urn(slug: &str) -> String { + format!("urn:atomic:agent:{slug}") +} + +/// Normalize an agent registry name into a slug: lowercase, first hyphen +/// segment (e.g. `"Claude-Code" -> "claude"`). Mirrors the *shape* of +/// `atomic_agent::identity::normalize_agent_name`, implemented locally so this +/// crate does not depend on `atomic-agent`. +pub fn normalize_agent_slug(agent_name: &str) -> String { + agent_name + .split('-') + .next() + .unwrap_or(agent_name) + .to_lowercase() +} + +/// Project a turn's provenance into the named-subgraph JSON-LD. +/// +/// Builds `urn:atomic:provgraph:<change_id_base32>` with +/// `@graph = [prov:Activity, prov:SoftwareAgent, prov:Person]`, exactly per the +/// doc §"A provenance graph" but with the hard-scope agent-id override +/// (`urn:atomic:agent:<slug>`, never a DID) and `used: []` (flywheel deferred). +/// +/// Deterministic: fixed key insertion order + JCS canonicalization at sign time +/// make the signed bytes stable across calls. +pub fn project(input: &ProvActivityInput) -> Value { + let agent_id = agent_urn(&input.agent_slug); + + // --- prov:Activity --------------------------------------------------- + let mut activity = Map::new(); + activity.insert("@type".into(), json!("prov:Activity")); + activity.insert("@id".into(), json!(activity_urn(&input.activity_id))); + if let Some(started) = &input.started_at { + activity.insert("prov:startedAtTime".into(), json!(started)); + } + if let Some(ended) = &input.ended_at { + activity.insert("prov:endedAtTime".into(), json!(ended)); + } + // wasAssociatedWith (the agent) / actedOnBehalfOf (the person). + activity.insert("associatedWith".into(), json!(agent_id)); + activity.insert("actedOnBehalfOf".into(), json!(input.person_did)); + activity.insert("generated".into(), json!(input.generated)); + // Flywheel `used` edge DEFERRED — emit an explicit empty array literal. + activity.insert("used".into(), json!([])); + // wasInformedBy — omit the key entirely when there is no parent turn. + if let Some(parent) = &input.turn_parent { + activity.insert("turnParent".into(), json!(parent)); + } + + // --- prov:SoftwareAgent (NON-VERIFIABLE descriptive label) ----------- + let mut agent = Map::new(); + agent.insert("@type".into(), json!("prov:SoftwareAgent")); + agent.insert("@id".into(), json!(agent_id)); + agent.insert("actedOnBehalfOf".into(), json!(input.person_did)); + agent.insert("prov:label".into(), json!(input.agent_display_name)); + if let Some(vendor) = &input.agent_vendor { + agent.insert("vendor".into(), json!(vendor)); + } + + // --- prov:Person (the real did:atomic signer) ------------------------ + let mut person = Map::new(); + person.insert("@type".into(), json!("prov:Person")); + person.insert("@id".into(), json!(input.person_did)); + + let mut root = Map::new(); + root.insert("@context".into(), json!(CONTEXT_URL)); + root.insert("@id".into(), json!(provgraph_urn(&input.change_id_base32))); + root.insert( + "@graph".into(), + json!([ + Value::Object(activity), + Value::Object(agent), + Value::Object(person), + ]), + ); + Value::Object(root) +} + +/// Project + attest a turn's provenance: the PERSON's identity + keypair sign the +/// named subgraph through the shared [`crate::proof::attest_value`] path (fills a +/// top-level `attributedTo` from the signer's `did:atomic`, computes +/// `contentHash`, attaches an `eddsa-jcs-2022` Data Integrity proof). +pub fn attest_prov(input: &ProvActivityInput, identity: &Identity, keypair: &KeyPair) -> Value { + proof::attest_value(project(input), identity, keypair) +} + +/// Verify a signed PROV subgraph against a public key — thin wrapper over +/// [`crate::proof::verify_value`] (content-hash integrity + signature + the +/// proof's verificationMethod DID belonging to the key). +pub fn verify_prov(value: &Value, public_key: &PublicKey) -> Result<()> { + proof::verify_value(value, public_key) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::error::CanonicalError; + use crate::proof::{PROP_ATTRIBUTED_TO, PROP_CONTENT_HASH, PROP_PROOF}; + use atomic_identity::keypair::KeyPair; + + fn dev_identity() -> (Identity, KeyPair) { + let kp = KeyPair::generate(); + let id = Identity::new("lee", &kp); + (id, kp) + } + + fn sample_input(person_did: &str) -> ProvActivityInput { + ProvActivityInput { + change_id_base32: "CHANGEBASE32".into(), + activity_id: "session-123".into(), + started_at: None, + ended_at: None, + agent_slug: "claude".into(), + agent_display_name: "Claude Code".into(), + agent_vendor: Some("anthropic".into()), + person_did: person_did.into(), + generated: vec![change_urn("CHANGEBASE32")], + turn_parent: Some(activity_urn("session-000")), + } + } + + fn graph_nodes(value: &Value) -> &Vec<Value> { + value + .get("@graph") + .and_then(Value::as_array) + .expect("@graph is an array") + } + + fn node_of_type<'a>(value: &'a Value, ty: &str) -> &'a Value { + graph_nodes(value) + .iter() + .find(|n| n.get("@type").and_then(Value::as_str) == Some(ty)) + .unwrap_or_else(|| panic!("no @graph node of @type {ty}")) + } + + #[test] + fn project_emits_expected_shape() { + let person = "did:atomic:PERSONFINGERPRINT"; + let value = project(&sample_input(person)); + + // Top-level named subgraph. + assert_eq!( + value.get("@id").and_then(Value::as_str), + Some("urn:atomic:provgraph:CHANGEBASE32") + ); + assert_eq!( + value.get("@context").and_then(Value::as_str), + Some(CONTEXT_URL) + ); + + // Exactly Activity + SoftwareAgent + Person. + assert_eq!(graph_nodes(&value).len(), 3); + + let activity = node_of_type(&value, "prov:Activity"); + assert_eq!( + activity.get("@id").and_then(Value::as_str), + Some("urn:atomic:activity:session-123") + ); + assert_eq!( + activity.get("associatedWith").and_then(Value::as_str), + Some("urn:atomic:agent:claude") + ); + assert_eq!( + activity.get("actedOnBehalfOf").and_then(Value::as_str), + Some(person) + ); + assert_eq!( + activity.get("generated"), + Some(&json!(["urn:atomic:change:CHANGEBASE32"])) + ); + // `used` is present and an EMPTY array (flywheel deferred). + assert_eq!( + activity.get("used").and_then(Value::as_array).map(Vec::len), + Some(0) + ); + assert_eq!( + activity.get("turnParent").and_then(Value::as_str), + Some("urn:atomic:activity:session-000") + ); + + // SoftwareAgent @id is a URN, NEVER a did:. + let agent = node_of_type(&value, "prov:SoftwareAgent"); + let agent_id = agent.get("@id").and_then(Value::as_str).unwrap(); + assert!(agent_id.starts_with("urn:atomic:agent:")); + assert!(!agent_id.starts_with("did:")); + assert_eq!(agent.get("prov:label").and_then(Value::as_str), Some("Claude Code")); + assert_eq!(agent.get("vendor").and_then(Value::as_str), Some("anthropic")); + + // Person @id == the real did:atomic. + let person_node = node_of_type(&value, "prov:Person"); + assert_eq!(person_node.get("@id").and_then(Value::as_str), Some(person)); + } + + #[test] + fn project_omits_absent_optional_keys() { + let mut input = sample_input("did:atomic:PERSON"); + input.turn_parent = None; + input.agent_vendor = None; + input.started_at = None; + input.ended_at = None; + + let value = project(&input); + let activity = node_of_type(&value, "prov:Activity"); + // Omitted, not null. + assert!(activity.get("turnParent").is_none()); + assert!(activity.get("prov:startedAtTime").is_none()); + assert!(activity.get("prov:endedAtTime").is_none()); + // But `used` is still present as an empty array. + assert!(activity.get("used").is_some()); + + let agent = node_of_type(&value, "prov:SoftwareAgent"); + assert!(agent.get("vendor").is_none()); + } + + #[test] + fn project_is_deterministic_over_signing_bytes() { + let input = sample_input("did:atomic:PERSON"); + let a = crate::jcs::canonicalize(&proof::signing_view(&project(&input))); + let b = crate::jcs::canonicalize(&proof::signing_view(&project(&input))); + assert_eq!(a, b); + } + + #[test] + fn attest_prov_then_verify_prov_roundtrips() { + let (id, kp) = dev_identity(); + let person = crate::did::did_for_public_key(&id.public_key); + let attested = attest_prov(&sample_input(&person), &id, &kp); + + let obj = attested.as_object().unwrap(); + assert!(obj + .get(PROP_CONTENT_HASH) + .and_then(Value::as_str) + .unwrap() + .starts_with("blake3:")); + assert!(obj.get(PROP_PROOF).is_some()); + // Accepted injection: top-level attributedTo == the signer's Person did. + assert_eq!( + obj.get(PROP_ATTRIBUTED_TO).and_then(Value::as_str), + Some(person.as_str()) + ); + + // Verifies with the right key. + verify_prov(&attested, &kp.public).expect("verify should succeed"); + + // Tamper a signed field -> HashMismatch. + let mut tampered = attested.clone(); + tampered + .as_object_mut() + .unwrap() + .insert("@id".into(), Value::String("urn:atomic:provgraph:EVIL".into())); + let err = verify_prov(&tampered, &kp.public).unwrap_err(); + assert!( + matches!(err, CanonicalError::HashMismatch { .. }), + "expected HashMismatch, got {err:?}" + ); + + // Wrong key -> verify error. + let other = KeyPair::generate(); + assert!(verify_prov(&attested, &other.public).is_err()); + } + + #[test] + fn slug_normalizes_like_agent_name() { + assert_eq!(normalize_agent_slug("claude-code"), "claude"); + assert_eq!(normalize_agent_slug("Claude-Code"), "claude"); + assert_eq!(normalize_agent_slug("codex"), "codex"); + assert_eq!(normalize_agent_slug(""), ""); + } +} diff --git a/atomic-cli/src/commands/mod.rs b/atomic-cli/src/commands/mod.rs index 6d22904a..ec50aebb 100644 --- a/atomic-cli/src/commands/mod.rs +++ b/atomic-cli/src/commands/mod.rs @@ -77,6 +77,7 @@ pub mod intent; pub mod log; pub mod memory; pub mod mv; +pub mod provenance; pub mod record; pub mod remove; pub mod restore; @@ -139,6 +140,7 @@ pub use log::Log; pub use memory::Memory; pub use mv::Move; pub use project::ProjectCmd; +pub use provenance::Provenance; pub use pull::Pull; pub use push::Push; pub use query::Query; diff --git a/atomic-cli/src/commands/provenance/command.rs b/atomic-cli/src/commands/provenance/command.rs new file mode 100644 index 00000000..5b267fcf --- /dev/null +++ b/atomic-cli/src/commands/provenance/command.rs @@ -0,0 +1,346 @@ +//! `atomic provenance {trace,show}` subcommand implementations. +//! +//! Both are READ-ONLY and COMPUTE-ON-DEMAND: they load the per-turn +//! `ProvenanceGraph` atomic already captured, project it into a W3C PROV JSON-LD +//! named subgraph, and (for `show`/`--json`) sign it on the fly with the person's +//! identity. NOTHING is written — no vault entry, no sidecar, no +//! `save_provenance_graph`, no content-hash/merkle touch. + +use clap::Parser; + +use atomic_canonical::did::did_for_public_key; +use atomic_canonical::prov::{activity_urn, attest_prov, project, ProvActivityInput}; +use atomic_core::change::ProvenanceGraph; +use atomic_core::types::{Base32, Hash}; +use atomic_identity::IdentityStore; +use atomic_repository::Repository; + +use crate::commands::provenance::mapping::{activity_id_for, map_graph_to_input}; +use crate::commands::{find_repository_root, Command}; +use crate::error::{CliError, CliResult}; +use crate::output::{emphasis, hint, info}; + +/// Show the flywheel chain for a change. +/// +/// Walks the provenance graph for a change — the activity that generated it, the +/// changes it generated, the agent and person involved, and the parent turn — +/// and prints the human-readable chain. `--json` emits the signed PROV JSON-LD +/// named subgraph instead (identical to `show --json`). +#[derive(Parser, Debug)] +#[command(name = "trace")] +pub struct ProvenanceTrace { + /// Change hash, hash prefix, or `urn:atomic:change:<base32>`. + pub target: String, + + /// Identity whose key signs the projection (for `--json`). Defaults to the + /// current default identity. + #[arg(long)] + pub identity: Option<String>, + + /// Emit the signed PROV JSON-LD `@graph` instead of the human chain. + #[arg(long)] + pub json: bool, +} + +/// Project (and sign) the PROV JSON-LD named subgraph for a change. +/// +/// Default (and `--json`) prints the SIGNED PROV JSON-LD `@graph` — the +/// verifiable artifact you hand an auditor. It carries a top-level +/// `attributedTo`/`contentHash`/`proof` envelope injected by the shared signing +/// path (the person's `did:atomic` signs the whole subgraph); this one-line +/// divergence from the doc example is intentional and documented in +/// `atomic-canonical`'s `prov` module. +#[derive(Parser, Debug)] +#[command(name = "show")] +pub struct ProvenanceShow { + /// Change hash, hash prefix, or `urn:atomic:change:<base32>`. + pub target: String, + + /// Identity whose key signs the projection. Defaults to the current default + /// identity. + #[arg(long)] + pub identity: Option<String>, + + /// Emit the signed PROV JSON-LD `@graph` (the default for `show`). + #[arg(long)] + pub json: bool, +} + +impl Command for ProvenanceTrace { + fn run(&self) -> CliResult<()> { + let root = find_repository_root()?; + let repo = Repository::open(&root).map_err(CliError::Repository)?; + let change_hash = resolve_change_target(&repo, &self.target)?; + let graphs = load_graphs(&repo, &change_hash)?; + + if self.json { + // Sign and emit, exactly like `show --json`. + let (identity, keypair) = resolve_person(self.identity.as_deref())?; + let person_did = did_for_public_key(&identity.public_key); + let signed = graphs + .iter() + .map(|(_, g)| { + let input = map_graph_to_input(&repo, g, &change_hash, &person_did); + attest_prov(&input, &identity, &keypair) + }) + .collect::<Vec<_>>(); + print_signed(&signed); + return Ok(()); + } + + // Plain trace: no identity/key required. Use the graph's own person + // slot as "(unresolved)" — the human chain does not need a signature. + // We still resolve a Person did if one is available so the chain shows + // the real signer; otherwise the actedOnBehalfOf target is left blank. + let person_did = resolve_person(self.identity.as_deref()) + .ok() + .map(|(id, _)| did_for_public_key(&id.public_key)) + .unwrap_or_else(|| "(no signing identity)".to_string()); + + print_trace(&repo, &graphs, &change_hash, &person_did); + Ok(()) + } +} + +impl Command for ProvenanceShow { + fn run(&self) -> CliResult<()> { + let root = find_repository_root()?; + let repo = Repository::open(&root).map_err(CliError::Repository)?; + let change_hash = resolve_change_target(&repo, &self.target)?; + let graphs = load_graphs(&repo, &change_hash)?; + + let (identity, keypair) = resolve_person(self.identity.as_deref())?; + let person_did = did_for_public_key(&identity.public_key); + + let signed = graphs + .iter() + .map(|(_, g)| { + let input = map_graph_to_input(&repo, g, &change_hash, &person_did); + attest_prov(&input, &identity, &keypair) + }) + .collect::<Vec<_>>(); + + // `show` always emits the signed JSON-LD artifact; `--json` is accepted + // as an explicit synonym so the two verbs share a flag. + let _ = self.json; + print_signed(&signed); + Ok(()) + } +} + +/// Load a change's provenance graphs: REV_DEPS-backed lookup, with a disk-scan +/// fallback when REV_DEPS registration missed the change. Errors if no graph +/// explains the change. +fn load_graphs( + repo: &Repository, + change_hash: &Hash, +) -> CliResult<Vec<(Hash, ProvenanceGraph)>> { + let mut graphs = repo + .find_provenance_for_change(change_hash) + .map_err(CliError::Repository)?; + if graphs.is_empty() { + graphs = repo + .find_provenance_for_change_scan(change_hash) + .map_err(CliError::Repository)?; + } + if graphs.is_empty() { + return Err(CliError::InvalidArgument { + message: format!( + "no provenance graph explains change {}", + change_hash.to_base32() + ), + }); + } + // Most-recent first (a change explained by >1 graph shows all; the newest + // leads). Both loaders sort/return unspecified order, so sort here. + graphs.sort_by(|(_, a), (_, b)| b.timestamp.cmp(&a.timestamp)); + Ok(graphs) +} + +/// Resolve the CLI target (bare hash, hash prefix, or `urn:atomic:change:<b32>`) +/// to a change `Hash`. +fn resolve_change_target(repo: &Repository, target: &str) -> CliResult<Hash> { + const URN_PREFIX: &str = "urn:atomic:change:"; + if let Some(b32) = target.strip_prefix(URN_PREFIX) { + return Hash::from_base32(b32.as_bytes()).ok_or_else(|| CliError::InvalidArgument { + message: format!("invalid change base32 in URN: {target}"), + }); + } + + // Bare full hash or prefix: match against the change store by base32 prefix + // (mirrors ChangeCmd::resolve_hash_prefix). + let mut matches: Vec<Hash> = Vec::new(); + for result in repo.iter_changes() { + let hash = result.map_err(|e| CliError::Internal(anyhow::anyhow!("{}", e)))?; + if hash.to_base32().starts_with(target) { + matches.push(hash); + } + } + match matches.len() { + 0 => { + // No recorded change matched. A graph can explain a change that was + // never recorded/made internal (the REV_DEPS fallback case), so try + // parsing the target as a full base32 change hash directly. + Hash::from_base32(target.as_bytes()).ok_or_else(|| CliError::ChangeNotFound { + hash: target.to_string(), + }) + } + 1 => Ok(matches[0]), + _ => { + let list: Vec<String> = matches.iter().map(|h| h.to_base32()).collect(); + Err(CliError::AmbiguousHash { + hash: format!("{} (matches: {})", target, list.join(", ")), + }) + } + } +} + +/// Resolve the PERSON's signing identity + keypair, exactly as +/// `atomic intent attest` does. +fn resolve_person( + identity: Option<&str>, +) -> CliResult<(atomic_identity::identity::Identity, atomic_identity::keypair::KeyPair)> { + let store = IdentityStore::open_default().map_err(|e| { + CliError::Internal(anyhow::anyhow!("Failed to open identity store: {}", e)) + })?; + let identity = if let Some(name) = identity { + store + .load_by_name(name) + .map_err(|_| CliError::IdentityNotFound(name.to_string()))? + } else { + store + .get_default() + .map_err(|e| { + CliError::Internal(anyhow::anyhow!("Failed to load default identity: {}", e)) + })? + .ok_or_else(|| CliError::InvalidArgument { + message: "No default identity set. Create one first:\n \ + atomic identity new <name> --email <email> --set-default" + .to_string(), + })? + }; + let keypair = store.load_keypair(&identity.id, None).map_err(|e| { + CliError::Internal(anyhow::anyhow!( + "Failed to load keypair for '{}': {}", + identity.name, + e + )) + })?; + Ok((identity, keypair)) +} + +/// Print the signed PROV JSON-LD artifact(s) to stdout. +fn print_signed(signed: &[serde_json::Value]) { + let out = if signed.len() == 1 { + serde_json::to_string_pretty(&signed[0]) + } else { + serde_json::to_string_pretty(&signed) + } + .expect("signed PROV value serialization is infallible"); + println!("{out}"); + eprintln!( + "note: signing keys are stored unencrypted on disk; treat this \ + projection as a non-production dev signature until key-at-rest \ + encryption lands." + ); +} + +/// Print the human-readable flywheel chain: change -> activity -> generated -> +/// agent -> person -> turnParent -> ... (walking `previous`). +fn print_trace( + repo: &Repository, + graphs: &[(Hash, ProvenanceGraph)], + change_hash: &Hash, + person_did: &str, +) { + println!( + "{} {}", + emphasis("Provenance for change"), + info(&change_hash.to_base32()) + ); + for (i, (_, graph)) in graphs.iter().enumerate() { + if graphs.len() > 1 { + println!("{}", hint(&format!(" [graph {} of {}]", i + 1, graphs.len()))); + } + let input = map_graph_to_input(repo, graph, change_hash, person_did); + print_activity_chain(repo, &input, graph); + } +} + +/// Print one activity and walk its `turnParent` chain via `previous`. +fn print_activity_chain(repo: &Repository, input: &ProvActivityInput, graph: &ProvenanceGraph) { + // The projected (unsigned) value is the source of truth for the shape. + let value = project(input); + let activity = value + .get("@graph") + .and_then(|g| g.as_array()) + .and_then(|nodes| { + nodes + .iter() + .find(|n| n.get("@type").and_then(|t| t.as_str()) == Some("prov:Activity")) + }); + + let indent = " "; + if let Some(act) = activity { + println!( + "{indent}{} {}", + emphasis("activity"), + info(act.get("@id").and_then(|v| v.as_str()).unwrap_or("?")) + ); + if let Some(gen) = act.get("generated").and_then(|v| v.as_array()) { + for g in gen { + println!( + "{indent} {} {}", + hint("generated"), + info(g.as_str().unwrap_or("?")) + ); + } + } + println!( + "{indent} {} {}", + hint("agent"), + info(act.get("associatedWith").and_then(|v| v.as_str()).unwrap_or("?")) + ); + println!( + "{indent} {} {} ({})", + hint("agent label"), + info(&input.agent_display_name), + input.agent_vendor.as_deref().unwrap_or("no vendor") + ); + println!( + "{indent} {} {}", + hint("person"), + info(act.get("actedOnBehalfOf").and_then(|v| v.as_str()).unwrap_or("?")) + ); + if let Some(parent) = act.get("turnParent").and_then(|v| v.as_str()) { + println!("{indent} {} {}", hint("turnParent"), info(parent)); + } else { + println!("{indent} {}", hint("turnParent: (root turn)")); + } + } + + // Walk `previous` to render the prior turn (one level; recursion via loop). + let mut cursor = graph.previous; + let mut depth = 0usize; + while let Some(prev_hash) = cursor { + depth += 1; + if depth > 64 { + println!("{indent} {}", hint("(chain truncated)")); + break; + } + match repo.load_provenance_graph(&prev_hash) { + Ok(prev) => { + println!( + "{indent} {} activity {}", + hint("↑ prior turn"), + activity_urn(&activity_id_for(&prev)), + ); + cursor = prev.previous; + } + Err(_) => { + println!("{indent} {}", hint("↑ prior turn (graph unavailable)")); + break; + } + } + } +} diff --git a/atomic-cli/src/commands/provenance/mapping.rs b/atomic-cli/src/commands/provenance/mapping.rs new file mode 100644 index 00000000..ba4095d5 --- /dev/null +++ b/atomic-cli/src/commands/provenance/mapping.rs @@ -0,0 +1,86 @@ +//! `atomic_core::change::ProvenanceGraph` -> `ProvActivityInput` mapping. +//! +//! This is the ONLY site that touches `atomic-core` types on the provenance +//! path: `atomic-canonical` is `atomic-core` independent, so all `Hash`/base32 +//! handling and the graph->input conversion live here at the CLI boundary. +//! +//! Read-only, compute-on-demand: mapping never writes anything. + +use atomic_canonical::prov::{ + activity_urn, change_urn, normalize_agent_slug, ProvActivityInput, +}; +use atomic_core::change::ProvenanceGraph; +use atomic_core::types::{Base32, Hash}; +use atomic_repository::Repository; + +/// Build a unique activity id for a turn's graph. +/// +/// All turns of one session share `session_id`, so keying the activity purely on +/// `session_id` would collide across turns. We disambiguate with the explained +/// change's base32 so each turn-activity is uniquely addressable (and +/// `turnParent` resolution stays consistent with this scheme). +/// +/// The id is keyed on the GRAPH itself — `<session_id>#<first-explained-change>` +/// (or just `<session_id>` if it explains none) — NOT on the user-traced change. +/// This is what makes turnParent join: a graph has ONE activity @id regardless +/// of which of its explained changes was traced, so a child turn's `turnParent` +/// reference to it always matches. +pub fn activity_id_for(graph: &ProvenanceGraph) -> String { + match graph.changes_explained.first() { + Some(h) => format!("{}#{}", graph.session_id, h.to_base32()), + None => graph.session_id.clone(), + } +} + +/// Map a loaded `ProvenanceGraph` into the plain projector input. +/// +/// `change_hash` is the change the user asked to trace (it names the subgraph and +/// the projected activity). `person_did` is the real signer's `did:atomic`, +/// resolved from the signing identity by the caller — it is NOT in the graph. +/// +/// `graph.previous` is a hash of the PREVIOUS PROVENANCE GRAPH (not an activity +/// id): we load that graph and use ITS activity id for `turnParent`. If it can't +/// be loaded, `turnParent` is omitted (best-effort) rather than fabricated. +pub fn map_graph_to_input( + repo: &Repository, + graph: &ProvenanceGraph, + change_hash: &Hash, + person_did: &str, +) -> ProvActivityInput { + let change_id_base32 = change_hash.to_base32(); + let activity_id = activity_id_for(graph); + + let generated = graph + .changes_explained + .iter() + .map(|h| change_urn(&h.to_base32())) + .collect(); + + // `previous` is a hash of the previous PROVENANCE GRAPH — load it and use + // ITS own activity id (session_id # first-explained-change). Best-effort. + let turn_parent = graph.previous.and_then(|prev_hash| { + repo.load_provenance_graph(&prev_hash) + .ok() + // The parent activity is keyed the same graph-stable way as this one + // (activity_id_for), so trace walks a consistent, joinable chain. + .map(|prev| activity_urn(&activity_id_for(&prev))) + }); + + let agent_vendor = (!graph.agent_vendor.is_empty()).then(|| graph.agent_vendor.clone()); + + ProvActivityInput { + change_id_base32, + activity_id, + // Timestamp is Unix SECONDS on the graph but MILLISECONDS on nodes; + // to avoid mixing units the thin slice leaves times as None (the shape + // simply omits absent times). + started_at: None, + ended_at: None, + agent_slug: normalize_agent_slug(&graph.agent_name), + agent_display_name: graph.agent_display_name.clone(), + agent_vendor, + person_did: person_did.to_string(), + generated, + turn_parent, + } +} diff --git a/atomic-cli/src/commands/provenance/mod.rs b/atomic-cli/src/commands/provenance/mod.rs new file mode 100644 index 00000000..6a63215d --- /dev/null +++ b/atomic-cli/src/commands/provenance/mod.rs @@ -0,0 +1,91 @@ +//! `atomic provenance` — project & sign W3C PROV over captured provenance. +//! +//! A top-level command (a sibling of `atomic intent` / `atomic memory`) that +//! PROJECTS the per-turn `ProvenanceGraph` atomic already captures into a signed +//! W3C PROV JSON-LD named subgraph. This is a PROJECTION, not new capture: the +//! agent's capture path is never touched. +//! +//! # Verbs +//! +//! ```text +//! atomic provenance trace <CHANGE> Walk the flywheel chain for a change +//! atomic provenance show <CHANGE> Emit the signed PROV JSON-LD @graph +//! ``` +//! +//! # Compute-on-demand — writes nothing +//! +//! Both verbs only READ (`find_provenance_for_change` + disk-scan fallback + +//! `load_provenance_graph`) and project+sign in memory. No new `VaultEntryType`, +//! no stored entry, no sidecar, no `save_provenance_graph`, no `content_hash` / +//! manifest-merkle change. The person's real `did:atomic` signs the projection; +//! the `SoftwareAgent` is a NON-VERIFIABLE descriptive label +//! (`urn:atomic:agent:<slug>`, never a DID). + +use clap::{Parser, Subcommand}; + +use crate::commands::Command; +use crate::error::CliResult; + +pub mod command; +pub mod mapping; + +pub use command::{ProvenanceShow, ProvenanceTrace}; + +/// Subcommands for projecting/tracing W3C PROV over captured provenance. +#[derive(Subcommand, Debug)] +pub enum ProvenanceCommands { + /// Walk the human-readable flywheel chain for a change. + /// + /// Loads the change's per-turn provenance graph, projects it, and prints the + /// chain: the activity that generated the change, what it generated, the + /// agent label and person, and the parent turn (walking `previous`). No + /// identity is required for the plain chain; `--json` emits the signed + /// PROV JSON-LD `@graph` (identical to `show --json`). + /// + /// # Examples + /// + /// ```text + /// atomic provenance trace ABCDEF + /// atomic provenance trace urn:atomic:change:<base32> + /// atomic provenance trace ABCDEF --json + /// ``` + Trace(ProvenanceTrace), + + /// Emit the signed W3C PROV JSON-LD named subgraph for a change. + /// + /// Projects the change's provenance graph and signs it on the fly with the + /// person's identity — the verifiable artifact you hand an auditor. It + /// carries a top-level `attributedTo`/`contentHash`/`proof` envelope (the + /// person's `did:atomic` signs the whole subgraph); this one-line divergence + /// from the doc example is intentional and documented in `atomic-canonical`'s + /// `prov` module. + /// + /// # Examples + /// + /// ```text + /// atomic provenance show ABCDEF + /// atomic provenance show ABCDEF --identity alice-work + /// ``` + Show(ProvenanceShow), +} + +/// Project & trace W3C PROV over the provenance atomic already captures. +/// +/// A sibling of `atomic intent` / `atomic memory`. Read-only and +/// compute-on-demand: it projects the per-turn `ProvenanceGraph` into signed +/// PROV JSON-LD without ever touching the capture path or writing anything. +#[derive(Debug, clap::Args)] +#[command(name = "provenance")] +pub struct Provenance { + #[command(subcommand)] + pub command: ProvenanceCommands, +} + +impl Command for Provenance { + fn run(&self) -> CliResult<()> { + match &self.command { + ProvenanceCommands::Trace(cmd) => cmd.run(), + ProvenanceCommands::Show(cmd) => cmd.run(), + } + } +} diff --git a/atomic-cli/src/main.rs b/atomic-cli/src/main.rs index 1af1b54d..44954eb8 100644 --- a/atomic-cli/src/main.rs +++ b/atomic-cli/src/main.rs @@ -71,6 +71,7 @@ use commands::{ Memory, Move, ProjectCmd, + Provenance, Pull, Push, Query, @@ -743,6 +744,25 @@ enum Commands { #[command(name = "memory")] Memory(Memory), + /// Project & trace W3C PROV over the provenance atomic already captures. + /// + /// Read-only, compute-on-demand: projects the per-turn `ProvenanceGraph` + /// into a signed W3C PROV JSON-LD named subgraph. The capture path is never + /// touched and nothing is written. The person's real `did:atomic` signs the + /// projection; the agent is a non-verifiable descriptive label. + /// + /// # Examples + /// + /// ```text + /// # Walk the flywheel chain for a change + /// atomic provenance trace <change> + /// + /// # Emit the signed PROV JSON-LD artifact + /// atomic provenance show <change> + /// ``` + #[command(name = "provenance")] + Provenance(Provenance), + /// Remove the last change from the current view. /// /// The change is removed from the view's change log but NOT deleted @@ -868,6 +888,8 @@ fn main() { Commands::Intent(intent) => intent.run(), Commands::Memory(memory) => memory.run(), + + Commands::Provenance(provenance) => provenance.run(), }; // Handle errors with user-friendly output diff --git a/atomic-cli/tests/provenance_integration_test.rs b/atomic-cli/tests/provenance_integration_test.rs new file mode 100644 index 00000000..31f952f6 --- /dev/null +++ b/atomic-cli/tests/provenance_integration_test.rs @@ -0,0 +1,301 @@ +//! Integration tests for `atomic provenance {trace,show}`, driving the real CLI +//! binary end-to-end against a temporary repository with a real, in-process +//! `ProvenanceGraph` saved via `atomic-repository` (NOT the forbidden +//! `atomic-agent` capture path). +//! +//! These prove the PROJECTION path end-to-end: +//! 1. a REAL `ProvenanceGraph` is persisted with `repo.save_provenance_graph`, +//! 2. `atomic provenance show --json` projects + signs it on the fly, +//! 3. the emitted PROV JSON-LD parses and its proof verifies via `verify_prov` +//! against the resolved identity's public key, +//! 4. `atomic provenance trace` prints the human flywheel chain, and +//! 5. compute-on-demand: no new files appear and the provenance-graph count is +//! unchanged after trace/show. +//! +//! The REV_DEPS fallback is exercised too: a graph whose explained change was +//! never made internal is invisible to REV_DEPS, and the disk-scan fallback +//! still finds it. + +use std::collections::BTreeSet; +use std::path::Path; +use std::process::{Command, Output}; + +use atomic_canonical::did::did_for_public_key; +use atomic_canonical::prov::verify_prov; +use atomic_core::change::provenance_graph::{ProvenanceNode, ProvenanceNodeKind}; +use atomic_core::change::ProvenanceGraph; +use atomic_core::types::{Base32, Hash}; +use atomic_identity::IdentityStore; +use atomic_repository::Repository; +use serde_json::Value; +use tempfile::TempDir; + +const ATOMIC_BIN: &str = env!("CARGO_BIN_EXE_atomic"); + +/// Run `atomic <args>` inside `repo_dir` with `HOME` pointed at `home_dir` so the +/// identity store resolves to a test-owned location. +fn atomic(repo_dir: &Path, home_dir: &Path, args: &[&str]) -> Output { + Command::new(ATOMIC_BIN) + .args(args) + .current_dir(repo_dir) + .env("HOME", home_dir) + .output() + .expect("run atomic") +} + +/// A prov node so the graph is non-trivial (the projection ignores nodes, but a +/// real graph carries them). +fn goal_node() -> ProvenanceNode { + ProvenanceNode { + id: "s-1".into(), + kind: ProvenanceNodeKind::Goal, + timestamp: 1_735_689_600_000, + summary: "Fix the auth bug".into(), + detail: None, + change_hash: None, + tool_name: None, + tool_call_id: None, + duration_ms: None, + classified: false, + confidence: None, + consolidated_from: Vec::new(), + } +} + +/// Recursively collect every file path under `root` (relative), for a +/// before/after "nothing was written" assertion. +fn snapshot_files(root: &Path) -> BTreeSet<String> { + let mut set = BTreeSet::new(); + fn walk(dir: &Path, base: &Path, set: &mut BTreeSet<String>) { + let Ok(entries) = std::fs::read_dir(dir) else { + return; + }; + for entry in entries.flatten() { + let path = entry.path(); + if path.is_dir() { + walk(&path, base, set); + } else if let Ok(rel) = path.strip_prefix(base) { + set.insert(rel.to_string_lossy().to_string()); + } + } + } + walk(root, root, &mut set); + set +} + +/// Create a default identity in a test-owned identity store rooted under +/// `home_dir/.atomic/identities`, matching `IdentityStore::open_default()` when +/// `HOME=home_dir`. Returns the identity's public key for verification. +fn create_default_identity(home_dir: &Path) -> atomic_identity::keypair::PublicKey { + let store_root = home_dir.join(".atomic").join("identities"); + let mut store = IdentityStore::open(&store_root).expect("open identity store"); + let keypair = atomic_identity::keypair::KeyPair::generate(); + let identity = atomic_identity::identity::Identity::new("tester", &keypair); + store + .save_with_keypair(&identity, &keypair, None) + .expect("save identity"); + store.set_default(&identity.id).expect("set default"); + keypair.public +} + +/// Record a file into a fresh repo and return a real, internal change `Hash`. +/// +/// `atomic init` itself records baseline changes ("Initialize repository", +/// "Initialize vault"), so the repo has several internal changes; any one of +/// them is a valid target for the projection (REV_DEPS works because it is +/// internal). We take the first. +fn repo_with_internal_change(repo_dir: &Path, home_dir: &Path) -> Hash { + assert!(atomic(repo_dir, home_dir, &["init"]).status.success()); + std::fs::write(repo_dir.join("file.txt"), b"v1\n").unwrap(); + assert!(atomic(repo_dir, home_dir, &["add", "file.txt"]).status.success()); + assert!(atomic(repo_dir, home_dir, &["record", "-m", "rec"]).status.success()); + + let repo = Repository::open(repo_dir).expect("open repo"); + let mut changes = repo.iter_changes(); + changes + .next() + .expect("at least one recorded change") + .expect("iter change") +} + +#[test] +fn provenance_show_projects_signs_and_verifies_and_writes_nothing() { + let repo_tmp = TempDir::new().unwrap(); + let home_tmp = TempDir::new().unwrap(); + let repo_dir = repo_tmp.path(); + let home_dir = home_tmp.path(); + + let pubkey = create_default_identity(home_dir); + let change_hash = repo_with_internal_change(repo_dir, home_dir); + + // Save a REAL ProvenanceGraph explaining the recorded change, via the + // repository path (NOT the atomic-agent capture path). + { + let repo = Repository::open(repo_dir).expect("open repo"); + let graph = ProvenanceGraph::builder("session-abc", "claude-code") + .agent_display_name("Claude Code") + .agent_vendor("anthropic") + .add_node(goal_node()) + .add_change_explained(change_hash) + .build(); + repo.save_provenance_graph(&graph).expect("save graph"); + } + + // Snapshot the repo tree; trace/show must not add or remove any files. + let before = snapshot_files(repo_dir); + let graphs_before = { + let repo = Repository::open(repo_dir).expect("open repo"); + repo.find_provenance_for_change_scan(&change_hash) + .expect("scan") + .len() + }; + + // `show` — emits the signed PROV JSON-LD to stdout. + let show = atomic( + repo_dir, + home_dir, + &["provenance", "show", &change_hash.to_base32()], + ); + assert!( + show.status.success(), + "provenance show failed: {}", + String::from_utf8_lossy(&show.stderr) + ); + let stdout = String::from_utf8(show.stdout).unwrap(); + let value: Value = serde_json::from_str(&stdout).expect("show emits valid JSON-LD"); + + // Shape assertions. + assert_eq!( + value.get("@id").and_then(Value::as_str), + Some(format!("urn:atomic:provgraph:{}", change_hash.to_base32()).as_str()) + ); + let graph_nodes = value.get("@graph").and_then(Value::as_array).unwrap(); + assert_eq!(graph_nodes.len(), 3); + let activity = graph_nodes + .iter() + .find(|n| n.get("@type").and_then(Value::as_str) == Some("prov:Activity")) + .unwrap(); + assert_eq!( + activity.get("generated"), + Some(&serde_json::json!([format!( + "urn:atomic:change:{}", + change_hash.to_base32() + )])) + ); + // used is present and EMPTY (flywheel deferred). + assert_eq!( + activity.get("used").and_then(Value::as_array).map(Vec::len), + Some(0) + ); + let agent = graph_nodes + .iter() + .find(|n| n.get("@type").and_then(Value::as_str) == Some("prov:SoftwareAgent")) + .unwrap(); + let agent_id = agent.get("@id").and_then(Value::as_str).unwrap(); + assert_eq!(agent_id, "urn:atomic:agent:claude"); + assert!(!agent_id.starts_with("did:"), "agent id must NOT be a did"); + assert_eq!( + agent.get("prov:label").and_then(Value::as_str), + Some("Claude Code") + ); + + // The proof verifies against the resolved identity's public key. + verify_prov(&value, &pubkey).expect("emitted PROV proof must verify"); + // Top-level attributedTo == the signer's Person did (accepted injection). + assert_eq!( + value.get("attributedTo").and_then(Value::as_str), + Some(did_for_public_key(&pubkey).as_str()) + ); + + // `trace` — prints the human chain (change -> activity -> generated -> ...). + let trace = atomic( + repo_dir, + home_dir, + &["provenance", "trace", &change_hash.to_base32()], + ); + assert!( + trace.status.success(), + "provenance trace failed: {}", + String::from_utf8_lossy(&trace.stderr) + ); + let trace_out = String::from_utf8(trace.stdout).unwrap(); + assert!(trace_out.contains("activity"), "trace shows the activity"); + assert!(trace_out.contains("generated"), "trace shows generated edge"); + assert!( + trace_out.contains(&format!("urn:atomic:change:{}", change_hash.to_base32())), + "trace shows the generated change urn" + ); + + // Compute-on-demand: nothing was written. + let after = snapshot_files(repo_dir); + assert_eq!(before, after, "trace/show must not write any files"); + let graphs_after = { + let repo = Repository::open(repo_dir).expect("open repo"); + repo.find_provenance_for_change_scan(&change_hash) + .expect("scan") + .len() + }; + assert_eq!( + graphs_before, graphs_after, + "provenance-graph count must be unchanged after trace/show" + ); +} + +#[test] +fn provenance_trace_uses_scan_fallback_when_rev_deps_missing() { + let repo_tmp = TempDir::new().unwrap(); + let home_tmp = TempDir::new().unwrap(); + let repo_dir = repo_tmp.path(); + let home_dir = home_tmp.path(); + + create_default_identity(home_dir); + // Init a real repo (needed so `provenance` finds a repository root), but do + // NOT record the change the graph explains — so it is never internal and + // REV_DEPS is empty for it. + assert!(atomic(repo_dir, home_dir, &["init"]).status.success()); + + // A change hash that was never recorded => not internal => invisible to + // REV_DEPS. The graph is still saved to the change store on disk. + let phantom_change = Hash::of(b"never-recorded-change"); + { + let repo = Repository::open(repo_dir).expect("open repo"); + let graph = ProvenanceGraph::builder("session-scan", "opencode") + .agent_display_name("OpenCode") + .add_node(goal_node()) + .add_change_explained(phantom_change) + .build(); + repo.save_provenance_graph(&graph).expect("save graph"); + + // Confirm the premise: REV_DEPS finds nothing, the scan finds it. + assert!( + repo.find_provenance_for_change(&phantom_change) + .expect("rev_deps lookup") + .is_empty(), + "REV_DEPS must be empty for a non-internal change" + ); + assert_eq!( + repo.find_provenance_for_change_scan(&phantom_change) + .expect("scan") + .len(), + 1, + "the disk scan must find the graph" + ); + } + + // The CLI must find it via the fallback and print the chain. + let trace = atomic( + repo_dir, + home_dir, + &["provenance", "trace", &phantom_change.to_base32()], + ); + assert!( + trace.status.success(), + "provenance trace (fallback) failed: {}", + String::from_utf8_lossy(&trace.stderr) + ); + let out = String::from_utf8(trace.stdout).unwrap(); + assert!( + out.contains(&format!("urn:atomic:change:{}", phantom_change.to_base32())), + "fallback trace shows the generated change urn" + ); +} diff --git a/atomic-repository/src/repository/changes.rs b/atomic-repository/src/repository/changes.rs index bce8e8a9..6cb1454a 100644 --- a/atomic-repository/src/repository/changes.rs +++ b/atomic-repository/src/repository/changes.rs @@ -766,6 +766,42 @@ impl Repository { Ok(graphs) } + /// Find all provenance graphs that explain a change by scanning disk. + /// + /// A read-only fallback for [`find_provenance_for_change`]: REV_DEPS + /// registration is best-effort (`save_provenance_graph` records the reverse + /// dependency only when the explained change is already internal), so a graph + /// whose change was not yet internal is invisible to REV_DEPS. This iterates + /// every provenance graph file and keeps those whose `changes_explained` + /// contains `change_hash`. It writes nothing — pure compute-on-demand. + /// + /// # Returns + /// + /// A vector of `(Hash, ProvenanceGraph)` pairs explaining this change, + /// ordered by timestamp (oldest first). + pub fn find_provenance_for_change_scan( + &self, + change_hash: &Hash, + ) -> Result<Vec<(Hash, atomic_core::change::ProvenanceGraph)>, RepositoryError> { + let mut graphs = Vec::new(); + + for result in self.change_store.iter_provenance_graphs() { + let hash = result.map_err(|e| RepositoryError::Database(e.to_string()))?; + + match self.load_provenance_graph(&hash) { + Ok(graph) if graph.explains_change(change_hash) => { + graphs.push((hash, graph)); + } + _ => continue, + } + } + + // Sort by timestamp (oldest first) for stable ordering. + graphs.sort_by_key(|(_, g)| g.timestamp); + + Ok(graphs) + } + /// Find all provenance graphs for a session by scanning disk. /// /// Iterates over all provenance graph files and filters by session ID. diff --git a/docs/recording-the-why.md b/docs/recording-the-why.md index 822675f4..47e2de30 100644 --- a/docs/recording-the-why.md +++ b/docs/recording-the-why.md @@ -319,7 +319,7 @@ The provenance for a change is a named subgraph keyed to the change id. Inside i "@id": "urn:atomic:activity:01J8ZD9X5K", "prov:startedAtTime": "2026-06-30T13:58:02Z", "prov:endedAtTime": "2026-06-30T14:02:09Z", - "associatedWith": "did:atomic:agent:claude", + "associatedWith": "urn:atomic:agent:claude", "actedOnBehalfOf": "did:atomic:lee", "used": [ "urn:atomic:intent:019efe85-5650-7430-a794-5ab6ade7a4bc", @@ -330,7 +330,8 @@ The provenance for a change is a named subgraph keyed to the change id. Inside i }, { "@type": "prov:SoftwareAgent", - "@id": "did:atomic:agent:claude", + "@id": "urn:atomic:agent:claude", + "prov:label": "Claude Code", "actedOnBehalfOf": "did:atomic:lee" }, { @@ -341,6 +342,8 @@ The provenance for a change is a named subgraph keyed to the change id. Inside i } ``` +The `SoftwareAgent` `@id` is a **`urn:atomic:agent:<slug>` label, not a DID** — `did:atomic:<x>` is a key fingerprint (`base32(blake3(pubkey))`), so a name like `claude` cannot be a verifiable `did:atomic`. Only the **Person** is a real `did:atomic`, and the Person's key is what **signs** the graph; the SoftwareAgent is descriptive attribution with no key behind it (until agents are issued their own keypairs). The signed subgraph the projector emits also carries, at the top level (outside `@graph`), an `attributedTo` (= the signing Person's `did:atomic`), a `contentHash`, and an `eddsa-jcs-2022` `proof` — injected by the same Data-Integrity signing path Intent and Memory use. + --- ## **The gate** From dd67820be1da956c7e2f1cfb37242625c9bc1126 Mon Sep 17 00:00:00 2001 From: Bradley Hilton <graywolf336@craftyn.com> Date: Thu, 2 Jul 2026 16:25:21 -0500 Subject: [PATCH 09/21] spike(shacl): evaluate oxirs-shacl as the gate's engine (verdict: unfit) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add atomic-shacl, a feature-gated spike that runs the real oxirs-shacl 0.3.1 engine over real Turtle shapes and diffs it against the hand-coded gate (atomic-canonical/src/gate.rs) via an adversarial differential corpus. Verdict (see atomic-shacl/SPIKE-FINDINGS.md; all 13 tests green): - oxirs 0.3.1 silently does NOT enforce sh:node (nested AcceptanceCriterion) or sh:sparql (the two conditional rules INTENT-5 / INTENT-7) — 3 of 12 rules become signing-path false-negatives. strict_mode does not catch it (fail-open). - result_path is always None, so violations can't be mapped to the failing property and distinct violations collapse. - The feature pulls ~432 crates (scirs2/ndarray BLAS, full icu, reqwest/rustls); the crate's own README calls the API "under development." What works and is retained: sh:minCount + sh:in match the gate on every Core-rule fixture, including the trim asymmetry (why/text trimmed; attributedTo/verifiedBy/ evidence not) and the load-bearing memory directionality ABSENCE. The .ttl shapes and the JSON-LD->RDF shim are correct standard SHACL — only the engine is unfit. The blocker tests assert the defects as passing tests today; if a future oxirs release fixes them the assertions flip and the tests fail, signalling re-evaluation. Isolation: nothing is on the signing path (the gate stays sole authority); atomic-canonical does not depend on this crate and the oxirs stack never reaches it; the whole stack is behind the off-by-default `oxirs-engine` feature so routine builds/CI never compile it. Removing this crate is a no-op for atomic's behavior. --- Cargo.toml | 12 ++ atomic-shacl/Cargo.toml | 40 +++++ atomic-shacl/SPIKE-FINDINGS.md | 70 ++++++++ atomic-shacl/src/engine.rs | 238 +++++++++++++++++++++++++ atomic-shacl/src/lib.rs | 22 +++ atomic-shacl/src/shapes.rs | 13 ++ atomic-shacl/src/shapes/intent.ttl | 88 +++++++++ atomic-shacl/src/shapes/memory.ttl | 56 ++++++ atomic-shacl/src/shim.rs | 250 ++++++++++++++++++++++++++ atomic-shacl/tests/differential.rs | 277 +++++++++++++++++++++++++++++ 10 files changed, 1066 insertions(+) create mode 100644 atomic-shacl/Cargo.toml create mode 100644 atomic-shacl/SPIKE-FINDINGS.md create mode 100644 atomic-shacl/src/engine.rs create mode 100644 atomic-shacl/src/lib.rs create mode 100644 atomic-shacl/src/shapes.rs create mode 100644 atomic-shacl/src/shapes/intent.ttl create mode 100644 atomic-shacl/src/shapes/memory.ttl create mode 100644 atomic-shacl/src/shim.rs create mode 100644 atomic-shacl/tests/differential.rs diff --git a/Cargo.toml b/Cargo.toml index 7ff0371e..20146898 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -5,6 +5,7 @@ members = [ "atomic-canonical", "atomic-cli", "atomic-core", + "atomic-shacl", "atomic-config", "atomic-identity", "atomic-remote", @@ -34,6 +35,17 @@ atomic-repository = { path = "atomic-repository" } atomic-semantic = { path = "atomic-semantic" } atomic-teams = { path = "atomic-teams" } +# SHACL — Recording the Why. A real SHACL engine over Turtle shapes. This +# pre-1.0 RDF/SHACL stack (oxirs) pulls a large transitive tree, so it is +# ISOLATED to atomic-shacl only, gated behind that crate's off-by-default +# `oxirs-engine` feature, and must never appear under atomic-canonical (enforced +# by a purity check). Pinned exactly so an oxirs point release cannot silently +# change validation semantics. oxirs-core provides both the RDF model and the +# store, so oxrdf/oxttl are not needed as direct dependencies. +atomic-shacl = { path = "atomic-shacl" } +oxirs-shacl = "=0.3.1" +oxirs-core = "=0.3.1" + # Serialization serde = { version = "1.0", features = ["derive"] } serde_json = "1.0" diff --git a/atomic-shacl/Cargo.toml b/atomic-shacl/Cargo.toml new file mode 100644 index 00000000..2fda937b --- /dev/null +++ b/atomic-shacl/Cargo.toml @@ -0,0 +1,40 @@ +[package] +name = "atomic-shacl" +description = "Recording the Why — a real SHACL engine (oxirs) over Turtle shapes, run in shadow against the hand-coded gate. The pre-1.0 RDF/SHACL stack is gated behind the off-by-default `oxirs-engine` feature and isolated here; atomic-canonical never depends on this crate." +version.workspace = true +edition.workspace = true +authors.workspace = true +license.workspace = true +repository.workspace = true +rust-version.workspace = true + +[dependencies] +# The canonical node types + the Violation/ValidationReport vocab we mirror and +# diff against. The dependency arrow is strictly one-directional: +# atomic-cli -> atomic-shacl -> atomic-canonical. atomic-canonical NEVER depends back. +atomic-canonical = { workspace = true } + +serde = { workspace = true } +serde_json = { workspace = true } +thiserror = { workspace = true } + +# The isolated, pre-1.0 SHACL/RDF stack (oxirs). OPTIONAL and OFF by default: +# only the `oxirs-engine` feature pulls the ~430-crate transitive tree, so +# routine workspace builds and CI never compile it. oxirs-core provides both the +# RDF model (NamedNode/Literal/Quad) and the validation Store (ConcreteStore); +# oxirs-shacl provides the shape loader + validation engine (both synchronous). +oxirs-shacl = { workspace = true, optional = true } +oxirs-core = { workspace = true, optional = true } +# oxirs-shacl's ValidationEngine::new wants an IndexMap<ShapeId, Shape>; matched +# to the version oxirs-shacl itself uses (2.14) to avoid a duplicate indexmap. +indexmap = { version = "2.14", optional = true } + +[features] +default = [] +# Enables the real oxirs SHACL engine and its large transitive dependency tree. +# OFF by default (see the crate description). The differential-corpus tests and +# any real validation require this feature: `cargo test -p atomic-shacl --features oxirs-engine`. +oxirs-engine = ["dep:oxirs-shacl", "dep:oxirs-core", "dep:indexmap"] + +[dev-dependencies] +atomic-identity = { workspace = true } diff --git a/atomic-shacl/SPIKE-FINDINGS.md b/atomic-shacl/SPIKE-FINDINGS.md new file mode 100644 index 00000000..7b657b9d --- /dev/null +++ b/atomic-shacl/SPIKE-FINDINGS.md @@ -0,0 +1,70 @@ +# SHACL engine spike — findings (oxirs-shacl 0.3.1) + +**Question:** can a real SHACL engine (`oxirs-shacl`) over real Turtle shapes +reproduce the hand-coded gate (`atomic-canonical/src/gate.rs`), so intent/memory +policy becomes team-editable data? + +**Verdict: No — not with oxirs-shacl 0.3.1.** It silently fails to enforce 3 of +the 12 rules (a signing-path false-negative class), loses property-path detail on +the rest, and costs a ~430-crate dependency tree. The shapes and the JSON-LD→RDF +shim are correct standard SHACL and are retained; only the *engine* is unfit. + +Everything below is reproduced by executable tests: +`cargo test -p atomic-shacl --features oxirs-engine` (13 tests, all green). + +## What works +`sh:minCount` (presence) and `sh:in` (closed value sets) fire correctly. oxirs +matches the gate's `conforms` verdict on every Core-rule fixture, **including**: +- the **trim asymmetry** — whitespace-only `why`/`text` rejected, whitespace-only + `attributedTo`/`verifiedBy`/`evidence` accepted (reproduced by the shim, not the + shapes; `src/shim.rs::should_emit`); +- present-empty vs omitted string fields (both project to nothing); +- the load-bearing **directionality ABSENCE** (a `superseded` memory with no + forward edge conforms — no forward-edge rule was authored). + +## Confirmed blockers (silent false-negatives) +oxirs 0.3.1 reports `conforms: true` where the gate correctly rejects: + +| Rule | SHACL construct | Observed | +|------|-----------------|----------| +| AC closed-set (rule 6) | `sh:node` (nested AcceptanceCriterionShape) | **not enforced** — unknown `acStatus` passes | +| INTENT-5 (scope-in ⇒ scope-out) | `sh:sparql` | **not enforced** — passes | +| INTENT-7 (met AC ⇒ verifiedBy+evidence) | `sh:sparql` | **not enforced** — passes | + +`strict_mode(true)` did **not** error on these unsupported constructs — they are +dropped silently (fail-open, the worst posture for a signing gate). + +## Fidelity gap (even on working rules) +`ValidationViolation.result_path` is always `None`, so a violation cannot be +mapped to the property that failed, and multiple distinct violations on one node +collapse (a node missing both `attributedTo` and `proof` yields two gate +violations but one SHACL finding). + +## Cost / maturity +- `--features oxirs-engine` pulls **~432 crates**, including `scirs2-*` / + `ndarray` / `oxiblas-ndarray` (BLAS), the full `icu_*` suite, and + `reqwest`/`hyper-rustls`/`rustls` (HTTP + TLS). +- oxirs-shacl's own README: "API is still under development and subject to + change"; core validation example commented out. + +## The blocker tests are tripwires +`tests/differential.rs` asserts these defects **as passing tests today**. If a +future oxirs release fixes `sh:node`/`sh:sparql`/`result_path`, the corresponding +assertion flips and the test FAILS — the signal to re-evaluate promotion. + +## Isolation (verified) +- `atomic-canonical` never depends on this crate; the oxirs stack does not reach + it (`cargo tree -p atomic-canonical` is clean). +- oxirs is behind the **off-by-default** `oxirs-engine` feature: routine + workspace builds/CI do not compile it. +- Nothing here is on the signing path. The hand-coded gate remains the sole + authority. Removing this crate is a no-op for `atomic`'s behavior. + +## Options from here +1. **Pivot to an in-house evaluator over these same shapes** (parse with `oxttl`, + ~20 mature crates; own the `sh:node`/`sh:sparql`/conditional evaluation). Gets + policy-as-Turtle-data at ~5% of the dependency cost, with correctness we own + and prove against the gate via this same differential corpus. +2. **Shelve oxirs**: keep the gate authoritative, keep this crate as a documented + negative result + tripwires, revisit if oxirs matures. +3. Keep digging on oxirs (unlikely to pay off given the maturity signal). diff --git a/atomic-shacl/src/engine.rs b/atomic-shacl/src/engine.rs new file mode 100644 index 00000000..ef07222b --- /dev/null +++ b/atomic-shacl/src/engine.rs @@ -0,0 +1,238 @@ +//! The synchronous SHACL bridge over the pre-1.0 oxirs engine. +//! +//! oxirs's validation path is fully synchronous — `ShapeLoaderBuilder::build` +//! (not just `build_async`), `ValidationEngine::new`, and `validate_store` all +//! run on the calling thread — so no async runtime is needed. This module owns +//! the three primitives the higher layers (shim, shapes, differential corpus) +//! build on: +//! +//! 1. [`load_shapes`] — parse Turtle shape text into oxirs `Shape`s. +//! 2. [`validate`] — run the shapes over an oxirs [`ConcreteStore`]. +//! +//! It is deliberately thin: the JSON-LD→RDF projection (the shim) and the +//! violation→`Violation` mapping live in their own modules so this file stays a +//! faithful, testable wrapper around the raw oxirs API. + +use std::collections::BTreeSet; + +use atomic_canonical::memory::MemoryNode; +use atomic_canonical::node::CanonicalNode; +use indexmap::IndexMap; +use oxirs_core::model::Term; +use oxirs_core::ConcreteStore; +use oxirs_shacl::{Shape, ShapeId, ValidationConfig, ValidationEngine, ValidationReport}; + +use crate::shapes::{INTENT_SHAPES_TTL, MEMORY_SHAPES_TTL}; +use crate::shim::node_to_store; + +/// Errors from the oxirs bridge. Kept small; the differential corpus treats any +/// engine error as "shadow unavailable" and never lets it affect authority. +#[derive(Debug, thiserror::Error)] +pub enum ShaclError { + /// A Turtle shape graph failed to parse / load. + #[error("failed to load SHACL shapes: {0}")] + ShapeLoad(String), + /// The validation run itself failed. + #[error("SHACL validation failed: {0}")] + Validate(String), + /// The RDF store could not be created or populated. + #[error("RDF store error: {0}")] + Store(String), +} + +/// Parse a Turtle shapes graph into oxirs `Shape`s, keyed by `ShapeId` as +/// `ValidationEngine` requires. +/// +/// `strict` maps to oxirs's `strict_mode`: when set, a shape graph the loader +/// cannot fully understand is an error rather than a silently-dropped shape — +/// the fail-closed posture a security gate needs. +pub fn load_shapes(turtle: &str, strict: bool) -> Result<IndexMap<ShapeId, Shape>, ShaclError> { + let shapes = oxirs_shacl::ShapeLoaderBuilder::new() + .from_rdf_data(turtle.to_string(), "turtle".to_string(), None) + .strict_mode(strict) + .build() + .map_err(|e| ShaclError::ShapeLoad(e.to_string()))?; + + Ok(shapes.into_iter().map(|s| (s.id.clone(), s)).collect()) +} + +/// Run `shapes` over `store` and return the raw oxirs report. +pub fn validate( + shapes: &IndexMap<ShapeId, Shape>, + store: &ConcreteStore, +) -> Result<ValidationReport, ShaclError> { + let mut engine = ValidationEngine::new(shapes, ValidationConfig::default()); + engine + .validate_store(store) + .map_err(|e| ShaclError::Validate(e.to_string())) +} + +/// A finding key for differential comparison against the hand-coded gate: +/// `(focus_node_iri, path_short_name)`. The gate produces at most one violation +/// per such pair, so a set of these is the right comparison granularity. +pub type FindingKey = (String, Option<String>); + +/// A SHACL report normalized so it can be diffed against the gate's +/// `ValidationReport`. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct NormalizedReport { + pub conforms: bool, + /// Order-independent set of `(focus, path)` findings. + pub findings: BTreeSet<FindingKey>, + /// `(focus, path, message)` triples, retained for diagnostics/divergence reports. + pub raw: Vec<(String, Option<String>, String)>, +} + +/// Validate a canonical Intent node through the real SHACL engine. +pub fn validate_intent_shacl(node: &CanonicalNode) -> Result<NormalizedReport, ShaclError> { + let shapes = load_shapes(INTENT_SHAPES_TTL, true)?; + let store = node_to_store(&node.to_value())?; + Ok(normalize(&validate(&shapes, &store)?)) +} + +/// Validate a canonical Memory node through the real SHACL engine. +pub fn validate_memory_shacl(node: &MemoryNode) -> Result<NormalizedReport, ShaclError> { + let shapes = load_shapes(MEMORY_SHAPES_TTL, true)?; + let store = node_to_store(&node.to_value())?; + Ok(normalize(&validate(&shapes, &store)?)) +} + +/// Normalize a raw oxirs report into `(focus, path)` findings. +/// +/// `result_path` is present for Core property constraints (sh:minCount, sh:in); +/// for SHACL-SPARQL constraints it is typically absent, so we recover the gate's +/// path from the (shape-authored) message — the only place the two conditionals' +/// paths (`hasScopeOut`, `acStatus`) are pinned. +pub fn normalize(report: &ValidationReport) -> NormalizedReport { + let mut findings = BTreeSet::new(); + let mut raw = Vec::new(); + for v in report.violations() { + let focus = term_iri(&v.focus_node); + let message = v.result_message.clone().unwrap_or_default(); + let path = match &v.result_path { + Some(p) => Some(short_name(&p.to_string())), + None => path_from_message(&message), + }; + findings.insert((focus.clone(), path.clone())); + raw.push((focus, path, message)); + } + NormalizedReport { + conforms: report.conforms(), + findings, + raw, + } +} + +/// The IRI string of a focus node (no angle brackets), matching the gate's +/// `focus_node` (`node.id` / `ac.id`). +fn term_iri(t: &Term) -> String { + match t { + Term::NamedNode(n) => n.as_str().to_string(), + other => other.to_string().trim_matches(|c| c == '<' || c == '>').to_string(), + } +} + +/// The local name of an IRI (everything after the last `#` or `/`). +fn short_name(iri: &str) -> String { + iri.rsplit(['#', '/']).next().unwrap_or(iri).to_string() +} + +/// Recover the gate's path for a SHACL-SPARQL constraint from its message. +fn path_from_message(message: &str) -> Option<String> { + if message.contains("out of scope") { + Some("hasScopeOut".to_string()) + } else if message.contains("verifiedBy and evidence") { + Some("acStatus".to_string()) + } else { + None + } +} + +#[cfg(test)] +mod smoke { + //! Physical proof (M1) that the real oxirs 0.3.1 API works end-to-end in our + //! toolchain: parse a Turtle NodeShape, build a store, validate, and read the + //! report both ways (violating and conforming). + + use super::*; + use oxirs_core::model::{Literal, NamedNode, Quad}; + + const SHAPE_TTL: &str = r#" +@prefix sh: <http://www.w3.org/ns/shacl#> . +@prefix ex: <http://example.org/> . +@prefix xsd: <http://www.w3.org/2001/XMLSchema#> . + +ex:ThingShape a sh:NodeShape ; + sh:targetClass ex:Thing ; + sh:property [ + sh:path ex:name ; + sh:minCount 1 ; + sh:datatype xsd:string ; + ] . +"#; + + fn thing_typed_quad() -> Quad { + Quad::new( + NamedNode::new("http://example.org/t1").unwrap(), + NamedNode::new("http://www.w3.org/1999/02/22-rdf-syntax-ns#type").unwrap(), + NamedNode::new("http://example.org/Thing").unwrap(), + oxirs_core::model::GraphName::DefaultGraph, + ) + } + + #[test] + fn oxirs_flags_missing_required_property() { + let shapes = load_shapes(SHAPE_TTL, true).expect("shapes load"); + let store = ConcreteStore::new().expect("store"); + // An ex:Thing with NO ex:name violates sh:minCount 1. + store.insert_quad(thing_typed_quad()).expect("insert"); + + let report = validate(&shapes, &store).expect("validate"); + assert!( + !report.conforms(), + "a Thing missing its required ex:name must not conform" + ); + assert!( + !report.violations().is_empty(), + "the missing-property violation must be reported" + ); + } + + #[test] + fn real_intent_and_memory_shapes_load_under_strict_mode() { + // M2/M4 gate: our real shapes exercise sh:in, sh:node, and sh:sparql. + // If oxirs's strict loader rejects any of these, load fails here and the + // whole approach is blocked — so this is the earliest hard checkpoint. + let intent = load_shapes(crate::shapes::INTENT_SHAPES_TTL, true) + .expect("intent shapes must load under strict mode"); + assert!( + !intent.is_empty(), + "intent shape graph produced no shapes (sh:in/sh:node/sh:sparql may not parse)" + ); + let memory = load_shapes(crate::shapes::MEMORY_SHAPES_TTL, true) + .expect("memory shapes must load under strict mode"); + assert!(!memory.is_empty(), "memory shape graph produced no shapes"); + } + + #[test] + fn oxirs_passes_when_required_property_present() { + let shapes = load_shapes(SHAPE_TTL, true).expect("shapes load"); + let store = ConcreteStore::new().expect("store"); + store.insert_quad(thing_typed_quad()).expect("insert type"); + store + .insert_quad(Quad::new( + NamedNode::new("http://example.org/t1").unwrap(), + NamedNode::new("http://example.org/name").unwrap(), + Literal::new_simple_literal("hello"), + oxirs_core::model::GraphName::DefaultGraph, + )) + .expect("insert name"); + + let report = validate(&shapes, &store).expect("validate"); + assert!( + report.conforms(), + "a Thing with its required ex:name present must conform (got {:?})", + report.violations() + ); + } +} diff --git a/atomic-shacl/src/lib.rs b/atomic-shacl/src/lib.rs new file mode 100644 index 00000000..866e7ff3 --- /dev/null +++ b/atomic-shacl/src/lib.rs @@ -0,0 +1,22 @@ +//! Recording the Why — a real SHACL engine over Turtle shapes, run in **shadow**. +//! +//! This crate wraps the pre-1.0 `oxirs-shacl` engine and validates canonical +//! Intent/Memory nodes against real Turtle shapes. During the spike it is +//! **non-authoritative**: nothing here gates a signature or a persist. Its job +//! is to answer, measurably, "can oxirs reproduce the hand-coded gate?" via a +//! differential corpus (see `tests/`). +//! +//! ## Isolation charter +//! The oxirs stack (a large, pre-1.0 transitive tree) lives behind the +//! off-by-default `oxirs-engine` feature and is named ONLY in this crate. +//! `atomic-canonical` stays pure and sync and never depends on this crate. +//! Enforced by a CI purity check. + +#![forbid(unsafe_code)] + +#[cfg(feature = "oxirs-engine")] +pub mod engine; +#[cfg(feature = "oxirs-engine")] +pub mod shapes; +#[cfg(feature = "oxirs-engine")] +pub mod shim; diff --git a/atomic-shacl/src/shapes.rs b/atomic-shacl/src/shapes.rs new file mode 100644 index 00000000..1621dfff --- /dev/null +++ b/atomic-shacl/src/shapes.rs @@ -0,0 +1,13 @@ +//! The embedded Turtle shape graphs. +//! +//! The `.ttl` files under `src/shapes/` are the team-editable, standard-SHACL +//! source of truth for Intent/Memory policy. They are compiled into the binary +//! here via `include_str!` — the compiled bytes are the trusted artifact that +//! actually runs, while the on-disk file stays the reviewable/diffable source +//! (and remains loadable by any external SHACL validator). + +/// IntentShape + AcceptanceCriterionShape (Core rules + the two SHACL-SPARQL conditionals). +pub const INTENT_SHAPES_TTL: &str = include_str!("shapes/intent.ttl"); + +/// MemoryShape (Core rules; the directionality absence is structural — no forward-edge rule). +pub const MEMORY_SHAPES_TTL: &str = include_str!("shapes/memory.ttl"); diff --git a/atomic-shacl/src/shapes/intent.ttl b/atomic-shacl/src/shapes/intent.ttl new file mode 100644 index 00000000..53e20403 --- /dev/null +++ b/atomic-shacl/src/shapes/intent.ttl @@ -0,0 +1,88 @@ +# IntentShape — the SHACL rendering of the hand-coded gate's `validate_intent`. +# +# This is the team-editable, standard-SHACL source of truth for intent policy. +# It is compiled into the binary via include_str! (the compiled bytes are the +# trusted artifact) but stays valid Turtle that any real SHACL validator can load. +# +# Trim semantics (load-bearing): the hand-coded gate rejects a WHITESPACE-ONLY +# `why` (it uses .trim()) but accepts a whitespace-only `attributedTo` (no trim). +# The shim reproduces this by emitting the a:why triple ONLY when the trimmed +# value is non-empty, and the a:attributedTo triple whenever the raw value is +# non-empty. So both rules below are plain sh:minCount 1 — the asymmetry lives in +# the shim (and is pinned by the differential corpus), not in these shapes. + +@prefix sh: <http://www.w3.org/ns/shacl#> . +@prefix a: <https://atomic.dev/ns#> . + +a:IntentShape a sh:NodeShape ; + sh:targetClass a:Intent ; + + # status ∈ closed set (single field ⇒ exactly one). + sh:property [ + sh:path a:status ; + sh:minCount 1 ; + sh:in ( "backlog" "todo" "in_progress" "done" ) ; + sh:message "status is not one of backlog/todo/in_progress/done" ; + ] ; + + # author present (shim emits iff raw value non-empty — untrimmed, matching the gate). + sh:property [ + sh:path a:attributedTo ; + sh:minCount 1 ; + sh:message "author (attributedTo) must be present as a DID" ; + ] ; + + # Data Integrity proof present. + sh:property [ + sh:path a:proof ; + sh:minCount 1 ; + sh:message "intent must carry a Data Integrity proof" ; + ] ; + + # reason present (shim emits iff trimmed value non-empty — content never graded). + sh:property [ + sh:path a:why ; + sh:minCount 1 ; + sh:message "a reason (why) must be present — its content is not graded" ; + ] ; + + # each acceptance criterion must satisfy AcceptanceCriterionShape. + sh:property [ + sh:path a:hasAcceptanceCriterion ; + sh:node a:AcceptanceCriterionShape ; + ] ; + + # INTENT-5 (conditional, SHACL-SPARQL): if scope-in is declared, scope-out must be too. + sh:sparql [ + a sh:SPARQLConstraint ; + sh:message "a scope declaration must state what is out of scope (the boundaries the agent must respect)" ; + sh:select """ + SELECT $this WHERE { + $this <https://atomic.dev/ns#hasScopeIn> ?in . + FILTER NOT EXISTS { $this <https://atomic.dev/ns#hasScopeOut> ?out . } + } + """ ; + ] . + +a:AcceptanceCriterionShape a sh:NodeShape ; + + # acStatus ∈ closed set. + sh:property [ + sh:path a:acStatus ; + sh:minCount 1 ; + sh:in ( "open" "met" ) ; + sh:message "acStatus is not one of open/met" ; + ] ; + + # INTENT-7 (conditional, SHACL-SPARQL): a met criterion must carry verifiedBy AND evidence. + sh:sparql [ + a sh:SPARQLConstraint ; + sh:message "a met acceptance criterion must carry verifiedBy and evidence" ; + sh:select """ + SELECT $this WHERE { + $this <https://atomic.dev/ns#acStatus> "met" . + FILTER ( NOT EXISTS { $this <https://atomic.dev/ns#verifiedBy> ?v } || + NOT EXISTS { $this <https://atomic.dev/ns#evidence> ?e } ) + } + """ ; + ] . diff --git a/atomic-shacl/src/shapes/memory.ttl b/atomic-shacl/src/shapes/memory.ttl new file mode 100644 index 00000000..4344ce56 --- /dev/null +++ b/atomic-shacl/src/shapes/memory.ttl @@ -0,0 +1,56 @@ +# MemoryShape — the SHACL rendering of the hand-coded gate's `validate_memory`. +# +# Standard SHACL; compiled in via include_str! but loadable by any real validator. +# +# Directionality (load-bearing ABSENCE): there is deliberately NO forward-edge +# rule (no "status = superseded ⇒ supersedes present"). supersedes/previousRevision +# are BACKWARD edges only; a retired memory gains no new edge. Adding a forward-edge +# property shape here would re-introduce the "references its future uses" anti-pattern +# and MUST fail the differential corpus's superseded-no-forward-edge anti-fixture. +# +# Trim semantics: `text` presence is enforced by the shim emitting the a:text triple +# ONLY when the trimmed value is non-empty (matching the gate's .trim()); the rule +# below is therefore plain sh:minCount 1. + +@prefix sh: <http://www.w3.org/ns/shacl#> . +@prefix a: <https://atomic.dev/ns#> . + +a:MemoryShape a sh:NodeShape ; + sh:targetClass a:Memory ; + + # memoryKind ∈ closed set (single field ⇒ exactly one). + sh:property [ + sh:path a:memoryKind ; + sh:minCount 1 ; + sh:in ( "constraint" "preference" "lesson" "context" ) ; + sh:message "memoryKind is not one of constraint/preference/lesson/context" ; + ] ; + + # status ∈ closed set. + sh:property [ + sh:path a:status ; + sh:minCount 1 ; + sh:in ( "active" "superseded" "retracted" ) ; + sh:message "status is not one of active/superseded/retracted" ; + ] ; + + # author present (shim emits iff raw value non-empty — untrimmed, matching the gate). + sh:property [ + sh:path a:attributedTo ; + sh:minCount 1 ; + sh:message "author (attributedTo) must be present as a DID" ; + ] ; + + # Data Integrity proof present. + sh:property [ + sh:path a:proof ; + sh:minCount 1 ; + sh:message "memory must carry a Data Integrity proof" ; + ] ; + + # text present (shim emits iff trimmed value non-empty — content never graded). + sh:property [ + sh:path a:text ; + sh:minCount 1 ; + sh:message "a memory must carry text — its content is not graded" ; + ] . diff --git a/atomic-shacl/src/shim.rs b/atomic-shacl/src/shim.rs new file mode 100644 index 00000000..e4588627 --- /dev/null +++ b/atomic-shacl/src/shim.rs @@ -0,0 +1,250 @@ +//! The deterministic JSON-LD → RDF projection (the "shim"). +//! +//! SHACL validates RDF, so a canonical node's JSON-LD value must first become +//! triples. The single most important correctness surface here is faithfully +//! reproducing the hand-coded gate's presence semantics — including its +//! deliberate **trim asymmetry**: +//! +//! * `why` / `text` are rejected when WHITESPACE-ONLY (the gate uses `.trim()`), +//! so the shim emits their triple only when the trimmed value is non-empty. +//! * `attributedTo` / `verifiedBy` / `evidence` are accepted when whitespace-only +//! (the gate uses `.unwrap_or("").is_empty()` — no trim), so the shim emits +//! their triple whenever the raw value is non-empty (present-empty `""` and an +//! omitted key both project to nothing — matching the gate). +//! +//! Everything else (closed-set values like `status`/`memoryKind`/`acStatus`) is +//! projected verbatim so `sh:in` can match. Nested typed sub-nodes +//! (`hasAcceptanceCriterion`, `hasScopeIn/Out`, …) become edges to child subjects +//! keyed on the child's `@id`, so `verifiedBy`/`evidence` land on the AC child — +//! not the parent — exactly where the AcceptanceCriterionShape looks for them. + +use oxirs_core::model::{GraphName, Literal, NamedNode, Quad}; +use oxirs_core::ConcreteStore; +use serde_json::{Map, Value}; + +use crate::engine::ShaclError; + +/// The Atomic vocabulary namespace. Every JSON-LD short key `k` projects to the +/// IRI `NS + k`, and every `@type` value `T` projects to the class IRI `NS + T`. +/// This is the term→IRI table the shapes target; keeping it a single constant is +/// what lets shim and shapes agree. +pub const NS: &str = "https://atomic.dev/ns#"; + +const RDF_TYPE: &str = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type"; + +/// Build an RDF store from a canonical node's JSON-LD value. +pub fn node_to_store(node: &Value) -> Result<ConcreteStore, ShaclError> { + let store = ConcreteStore::new().map_err(|e| ShaclError::Store(e.to_string()))?; + for quad in node_to_quads(node)? { + store + .insert_quad(quad) + .map_err(|e| ShaclError::Store(e.to_string()))?; + } + Ok(store) +} + +/// Project a canonical node's JSON-LD value into a deterministic set of quads. +/// Pure (no store), so the projection can be unit-tested quad-for-quad. +pub fn node_to_quads(node: &Value) -> Result<Vec<Quad>, ShaclError> { + let obj = node + .as_object() + .ok_or_else(|| ShaclError::Store("node is not a JSON object".into()))?; + let mut quads = Vec::new(); + add_node(obj, &mut quads)?; + Ok(quads) +} + +/// Whether a string field is projected, given the gate's per-field semantics. +/// Exposed so the differential corpus can assert the asymmetry directly. +pub fn should_emit(key: &str, value: &str) -> bool { + match key { + // Trimmed presence (whitespace-only is absent). + "why" | "text" => !value.trim().is_empty(), + // Untrimmed presence (whitespace-only counts as present). + "attributedTo" | "verifiedBy" | "evidence" => !value.is_empty(), + // Closed-set / other scalars: project verbatim (empty is harmless — no + // rule references these except via sh:in, which an empty value fails). + _ => true, + } +} + +fn iri(s: &str) -> Result<NamedNode, ShaclError> { + NamedNode::new(s).map_err(|e| ShaclError::Store(format!("invalid IRI {s:?}: {e}"))) +} + +fn subject_of(obj: &Map<String, Value>) -> Result<NamedNode, ShaclError> { + let id = obj + .get("@id") + .and_then(Value::as_str) + .ok_or_else(|| ShaclError::Store("node/sub-node missing @id".into()))?; + iri(id) +} + +/// Emit all triples for one node (or sub-node), recursing into typed children. +fn add_node(obj: &Map<String, Value>, quads: &mut Vec<Quad>) -> Result<(), ShaclError> { + let subject = subject_of(obj)?; + + // @type -> rdf:type -> the class IRI (so sh:targetClass / sh:node match). + if let Some(t) = obj.get("@type").and_then(Value::as_str) { + quads.push(Quad::new( + subject.clone(), + iri(RDF_TYPE)?, + iri(&format!("{NS}{t}"))?, + GraphName::DefaultGraph, + )); + } + + for (key, val) in obj { + if key == "@context" || key == "@id" || key == "@type" { + continue; + } + let pred = iri(&format!("{NS}{key}"))?; + + match val { + // A present proof (object) projects to a single presence triple; an + // absent proof projects to nothing, so sh:minCount 1 fires. + Value::Object(_) if key == "proof" => { + quads.push(Quad::new( + subject.clone(), + pred, + Literal::new_simple_literal("present"), + GraphName::DefaultGraph, + )); + } + Value::String(s) => { + if should_emit(key, s) { + quads.push(Quad::new( + subject.clone(), + pred, + Literal::new_simple_literal(s.as_str()), + GraphName::DefaultGraph, + )); + } + } + Value::Array(items) => { + for item in items { + match item { + Value::String(s) => { + quads.push(Quad::new( + subject.clone(), + pred.clone(), + Literal::new_simple_literal(s.as_str()), + GraphName::DefaultGraph, + )); + } + // A typed sub-node: edge to the child @id, then recurse so + // the child's own fields (acStatus/verifiedBy/evidence, …) + // land on the CHILD subject. + Value::Object(child) if child.contains_key("@id") => { + quads.push(Quad::new( + subject.clone(), + pred.clone(), + subject_of(child)?, + GraphName::DefaultGraph, + )); + add_node(child, quads)?; + } + // Objects without an @id (e.g. a bare dependsOn Ref) are + // ungated; skip them rather than mint a synthetic subject. + _ => {} + } + } + } + // Numbers/bools/null: none of our gated fields use them. Skip. + _ => {} + } + } + + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + + /// Render quads to sorted "S P O" strings for order-independent assertions. + fn triples(node: &Value) -> Vec<String> { + let mut out: Vec<String> = node_to_quads(node) + .expect("project") + .iter() + .map(|q| { + format!( + "{} {} {}", + q.subject(), + q.predicate(), + q.object() + ) + }) + .collect(); + out.sort(); + out + } + + fn has(node: &Value, needle: &str) -> bool { + triples(node).iter().any(|t| t.contains(needle)) + } + + #[test] + fn trim_asymmetry_why_whitespace_only_is_absent() { + // why is whitespace-only -> NOT projected (gate rejects it). + let n = json!({"@id":"urn:i:1","@type":"Intent","why":" ","status":"todo"}); + assert!(!has(&n, "#why"), "whitespace-only why must not be projected"); + // a real why IS projected. + let n2 = json!({"@id":"urn:i:1","@type":"Intent","why":"because","status":"todo"}); + assert!(has(&n2, "#why"), "a real why must be projected"); + } + + #[test] + fn trim_asymmetry_attributed_to_whitespace_only_is_present() { + // attributedTo whitespace-only -> IS projected (gate accepts it, no trim). + let n = json!({"@id":"urn:i:1","@type":"Intent","attributedTo":" "}); + assert!( + has(&n, "#attributedTo"), + "whitespace-only attributedTo must be projected (untrimmed)" + ); + // present-empty "" -> NOT projected (matches .is_empty()). + let n2 = json!({"@id":"urn:i:1","@type":"Intent","attributedTo":""}); + assert!( + !has(&n2, "#attributedTo"), + "empty attributedTo must project to nothing" + ); + } + + #[test] + fn proof_presence_projects_one_triple_when_present_none_when_absent() { + let present = json!({"@id":"urn:i:1","@type":"Intent","proof":{"proofValue":"z1"}}); + assert!(has(&present, "#proof"), "present proof must project a triple"); + let absent = json!({"@id":"urn:i:1","@type":"Intent"}); + assert!(!has(&absent, "#proof"), "absent proof projects nothing"); + } + + #[test] + fn ac_child_fields_land_on_the_child_subject_not_the_parent() { + let n = json!({ + "@id":"urn:i:1","@type":"Intent", + "hasAcceptanceCriterion":[{ + "@id":"urn:ac:1","@type":"AcceptanceCriterion", + "text":"t","acStatus":"met","verifiedBy":"lee","evidence":"pr#1" + }] + }); + let ts = triples(&n); + // parent -> child edge + assert!(ts.iter().any(|t| t.contains("urn:i:1") + && t.contains("#hasAcceptanceCriterion") + && t.contains("urn:ac:1"))); + // verifiedBy/evidence/acStatus are on the CHILD subject + assert!(ts.iter().any(|t| t.starts_with("<urn:ac:1>") && t.contains("#verifiedBy"))); + assert!(ts.iter().any(|t| t.starts_with("<urn:ac:1>") && t.contains("#evidence"))); + assert!(ts.iter().any(|t| t.starts_with("<urn:ac:1>") && t.contains("#acStatus"))); + // and NOT on the parent + assert!(!ts.iter().any(|t| t.starts_with("<urn:i:1>") && t.contains("#verifiedBy"))); + } + + #[test] + fn omitted_empty_collections_project_no_edges() { + let n = json!({"@id":"urn:i:1","@type":"Intent","status":"todo"}); + assert!(!has(&n, "#hasScopeIn")); + assert!(!has(&n, "#hasAcceptanceCriterion")); + } +} diff --git a/atomic-shacl/tests/differential.rs b/atomic-shacl/tests/differential.rs new file mode 100644 index 00000000..ddfb3778 --- /dev/null +++ b/atomic-shacl/tests/differential.rs @@ -0,0 +1,277 @@ +//! The adversarial differential corpus — the spike's actual deliverable. +//! +//! For each fixture we run the trusted hand-coded gate (the oracle) AND the real +//! oxirs SHACL path over the SAME node, and compare `conforms` + the set of +//! `(focus_node, path)` findings. The corpus targets the verified divergence +//! traps (trim asymmetry, present-empty vs omitted, nested AC via sh:node, the +//! two SHACL-SPARQL conditionals, the superseded-no-forward-edge anti-fixture). +//! +//! This file compiles only with `--features oxirs-engine`. +#![cfg(feature = "oxirs-engine")] + +use std::collections::BTreeSet; + +use atomic_canonical::gate::{validate_intent, validate_memory, ValidationReport}; +use atomic_canonical::memory::MemoryNode; +use atomic_canonical::node::{AcceptanceCriterion, CanonicalNode, Proof, ScopeItem, CONTEXT_URL}; +use atomic_shacl::engine::{validate_intent_shacl, validate_memory_shacl, FindingKey}; + +// ---------- fixture builders (dummy proof: the gate only checks presence) ---------- + +fn dummy_proof() -> Proof { + Proof { + type_: "DataIntegrityProof".into(), + cryptosuite: "eddsa-jcs-2022".into(), + verification_method: "did:atomic:x#k".into(), + proof_purpose: "assertionMethod".into(), + proof_value: "zStub".into(), + } +} + +fn base_intent() -> CanonicalNode { + CanonicalNode { + context: CONTEXT_URL.into(), + type_: "Intent".into(), + id: "urn:atomic:intent:c".into(), + human_key: "C-1".into(), + title: "t".into(), + status: "todo".into(), + priority: None, + view: None, + motivated_by: None, + informed_by: vec![], + has_acceptance_criterion: vec![], + has_task: vec![], + has_scope_in: vec![], + has_scope_out: vec![], + has_constraint: vec![], + depends_on: vec![], + why: Some("a reason".into()), + content_hash: None, + attributed_to: Some("did:atomic:lee".into()), + created_at: "2026-06-25T00:00:00Z".into(), + proof: Some(dummy_proof()), + } +} + +fn ac(id: &str, status: &str, vby: Option<&str>, ev: Option<&str>) -> AcceptanceCriterion { + AcceptanceCriterion { + type_: "AcceptanceCriterion".into(), + id: id.into(), + text: "t".into(), + ac_status: status.into(), + verified_by: vby.map(Into::into), + evidence: ev.map(Into::into), + } +} + +fn scope(id: &str) -> ScopeItem { + ScopeItem { + type_: "ScopeItem".into(), + id: id.into(), + text: "s".into(), + } +} + +fn base_memory() -> MemoryNode { + MemoryNode { + context: CONTEXT_URL.into(), + type_: "Memory".into(), + id: "urn:atomic:memory:c".into(), + memory_kind: "constraint".into(), + text: "a durable constraint".into(), + about: vec![], + status: "active".into(), + supersedes: None, + previous_revision: None, + content_hash: None, + attributed_to: Some("did:atomic:lee".into()), + created_at: "2026-05-02T09:14:00Z".into(), + proof: Some(dummy_proof()), + } +} + +// ---------- normalization of the gate's report to the same key space ---------- + +fn gate_keys(report: &ValidationReport) -> BTreeSet<FindingKey> { + report + .results + .iter() + .map(|v| (v.focus_node.clone(), v.path.clone())) + .collect() +} + +fn shacl_conforms_intent(node: &CanonicalNode) -> bool { + validate_intent_shacl(node).expect("shacl intent").conforms +} +fn shacl_conforms_memory(node: &MemoryNode) -> bool { + validate_memory_shacl(node).expect("shacl memory").conforms +} + +// ============================================================================ +// WHAT WORKS: Core presence (sh:minCount) + closed-set (sh:in) rules. +// oxirs 0.3.1 reproduces the gate's `conforms` verdict on every one of these, +// INCLUDING the trim asymmetry and the load-bearing directionality ABSENCE. +// ============================================================================ + +#[test] +fn core_presence_and_closed_set_rules_match_gate_on_conformance() { + // (label, mutate, ) — each asserts gate.conforms == shacl.conforms. + let mut cases: Vec<(&str, CanonicalNode)> = Vec::new(); + + cases.push(("baseline conforms", base_intent())); + + let mut n = base_intent(); + n.status = "shipped".into(); + cases.push(("unknown status rejected", n)); + + let mut n = base_intent(); + n.status = String::new(); + cases.push(("empty status rejected", n)); + + // Trim asymmetry: whitespace-only why is REJECTED (gate .trim()). + let mut n = base_intent(); + n.why = Some(" ".into()); + cases.push(("whitespace-only why rejected", n)); + + let mut n = base_intent(); + n.why = None; + cases.push(("missing why rejected", n)); + + // Trim asymmetry: whitespace-only attributedTo is ACCEPTED (gate no trim). + let mut n = base_intent(); + n.attributed_to = Some(" ".into()); + cases.push(("whitespace-only attributedTo accepted", n)); + + // present-empty attributedTo is rejected (== omitted). + let mut n = base_intent(); + n.attributed_to = Some(String::new()); + cases.push(("present-empty attributedTo rejected", n)); + + let mut n = base_intent(); + n.attributed_to = None; + n.proof = None; + cases.push(("unattested rejected", n)); + + for (label, node) in &cases { + let gate = validate_intent(node).conforms; + let shacl = shacl_conforms_intent(node); + assert_eq!( + gate, shacl, + "INTENT conformance divergence on '{label}': gate={gate} shacl={shacl}" + ); + // Where non-conforming, the focus node must at least match. + if !gate { + let g = gate_keys(&validate_intent(node)); + let s = &validate_intent_shacl(node).unwrap().findings; + let g_focus: BTreeSet<_> = g.iter().map(|(f, _)| f.clone()).collect(); + let s_focus: BTreeSet<_> = s.iter().map(|(f, _)| f.clone()).collect(); + assert_eq!(g_focus, s_focus, "INTENT focus-node divergence on '{label}'"); + } + } + + // Memory Core rules + the directionality ABSENCE anti-fixture. + let mut m_cases: Vec<(&str, MemoryNode)> = Vec::new(); + m_cases.push(("baseline conforms", base_memory())); + let mut m = base_memory(); + m.memory_kind = "architecture".into(); + m_cases.push(("unknown memoryKind rejected", m)); + let mut m = base_memory(); + m.status = "archived".into(); + m_cases.push(("unknown status rejected", m)); + let mut m = base_memory(); + m.text = " ".into(); + m_cases.push(("whitespace-only text rejected", m)); + let mut m = base_memory(); + m.attributed_to = None; + m.proof = None; + m.text = " ".into(); + m_cases.push(("bare memory rejected", m)); + // ANTI-FIXTURE (directionality): a retired memory with no forward edge conforms. + let mut m = base_memory(); + m.status = "superseded".into(); + m.supersedes = None; + m.previous_revision = None; + m_cases.push(("superseded no-forward-edge conforms", m)); + + for (label, node) in &m_cases { + let gate = validate_memory(node).conforms; + let shacl = shacl_conforms_memory(node); + assert_eq!( + gate, shacl, + "MEMORY conformance divergence on '{label}': gate={gate} shacl={shacl}" + ); + } +} + +// ============================================================================ +// CONFIRMED BLOCKERS: rules oxirs 0.3.1 SILENTLY DOES NOT ENFORCE. +// Each asserts the gate REJECTS but SHACL wrongly CONFORMS — a signing-path +// false-negative. These tests PASS today (they lock in the defect). If a future +// oxirs release fixes the construct, the corresponding assert flips and the test +// FAILS, signalling "re-evaluate: this rule can now be promoted." +// ============================================================================ + +#[test] +fn blocker_sh_node_nested_acceptance_criterion_not_enforced() { + // AC with an unknown acStatus: gate rejects, oxirs ignores sh:node → conforms. + let mut n = base_intent(); + n.has_acceptance_criterion = vec![ac("urn:atomic:ac:1", "not-a-status", None, None)]; + assert!(!validate_intent(&n).conforms, "gate must reject unknown acStatus"); + assert!( + shacl_conforms_intent(&n), + "BLOCKER FIXED? oxirs now enforces sh:node nested AC validation — re-evaluate" + ); +} + +#[test] +fn blocker_sparql_intent5_scope_in_implies_scope_out_not_enforced() { + let mut n = base_intent(); + n.has_scope_in = vec![scope("urn:atomic:scope:in1")]; + // no scope-out + assert!( + !validate_intent(&n).conforms, + "gate must reject scope-in without scope-out" + ); + assert!( + shacl_conforms_intent(&n), + "BLOCKER FIXED? oxirs now enforces sh:sparql INTENT-5 — re-evaluate" + ); +} + +#[test] +fn blocker_sparql_intent7_met_ac_requires_evidence_not_enforced() { + let mut n = base_intent(); + n.has_acceptance_criterion = vec![ac("urn:atomic:ac:1", "met", None, None)]; + assert!( + !validate_intent(&n).conforms, + "gate must reject a met AC without evidence" + ); + assert!( + shacl_conforms_intent(&n), + "BLOCKER FIXED? oxirs now enforces sh:sparql INTENT-7 — re-evaluate" + ); +} + +#[test] +fn fidelity_gap_oxirs_leaves_result_path_unpopulated() { + // The gate names the failing property; oxirs 0.3.1 reports result_path=None, + // so distinct violations on one node collapse and cannot be mapped 1:1. + let mut n = base_intent(); + n.attributed_to = None; + n.proof = None; + let shacl = validate_intent_shacl(&n).expect("shacl"); + assert!(!shacl.conforms); + assert!( + shacl.findings.iter().all(|(_, path)| path.is_none()), + "BLOCKER FIXED? oxirs now populates result_path — path mapping can tighten" + ); + // Two distinct gate violations (attributedTo, proof) collapse to one SHACL key. + let gate = gate_keys(&validate_intent(&n)); + assert_eq!(gate.len(), 2, "gate distinguishes attributedTo vs proof"); + assert_eq!( + shacl.findings.len(), + 1, + "oxirs collapses both missing-property violations into one (focus, None) key" + ); +} From 34ed8bc2cd8b578733ee8d18755eae2f2f9cde26 Mon Sep 17 00:00:00 2001 From: Bradley Hilton <graywolf336@craftyn.com> Date: Mon, 6 Jul 2026 11:24:07 -0500 Subject: [PATCH 10/21] =?UTF-8?q?fix(canonical):=20W3C=20spec=20conformanc?= =?UTF-8?q?e=20=E2=80=94=20base58btc=20proofValue,=20UTF-16=20JCS,=20did:k?= =?UTF-8?q?ey?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adopt the three canonicalization/crypto spec fixes from the team's feat/canonical-standards branch (5e4c7b8), code only — not its bundled docs, PROV, CLI, or pyshacl work, which remain separate reconciliations. - proof.rs: proofValue is now multibase base58btc ('z') via bs58, as the eddsa-jcs-2022 cryptosuite specifies (was base32-upper 'B', an M0 shortcut). proofValue is excluded from both the signing and hashing views, so this is a pure output-encoding change — the ed25519 signature bytes and content hash are unchanged; only the string encoding differs. - jcs.rs: object keys now sort by UTF-16 code units per RFC 8785 §3.2.3 (was UTF-8 byte order). A no-op for the all-ASCII closed vocabulary (identical canonical bytes, hash, and signature), correct for any future supplementary-plane key. - did.rs: add did:key (multicodec ed25519-pub + base58btc) alongside the in-tree did:atomic. Additive — did:atomic stays the default and still verifies; did:key is now also accepted, for Data-Integrity/PROV interop. The design doc already showed base58btc proofValues, so code now matches the doc. All canonical + cli + provenance tests green; clippy clean. --- Cargo.toml | 1 + atomic-canonical/Cargo.toml | 1 + atomic-canonical/src/did.rs | 48 +++++++++++++++++++++++++++++++---- atomic-canonical/src/jcs.rs | 29 ++++++++++++++++----- atomic-canonical/src/proof.rs | 24 ++++++++---------- 5 files changed, 78 insertions(+), 25 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 20146898..89f600ad 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -59,6 +59,7 @@ rayon = "1.10" fastcdc = "3.1" # Hashing & Crypto +bs58 = "0.5" blake3 = "1.5" ed25519-dalek = { version = "2.1", features = ["serde"] } rand = "0.8" diff --git a/atomic-canonical/Cargo.toml b/atomic-canonical/Cargo.toml index 526fa1e7..58ceac78 100644 --- a/atomic-canonical/Cargo.toml +++ b/atomic-canonical/Cargo.toml @@ -12,6 +12,7 @@ rust-version.workspace = true serde = { workspace = true } serde_json = { workspace = true } blake3 = { workspace = true } +bs58 = { workspace = true } chrono = { workspace = true } thiserror = { workspace = true } data-encoding = { workspace = true } diff --git a/atomic-canonical/src/did.rs b/atomic-canonical/src/did.rs index 225a30bf..57665472 100644 --- a/atomic-canonical/src/did.rs +++ b/atomic-canonical/src/did.rs @@ -11,13 +11,19 @@ //! confirms the DID belongs to that key. The store-backed resolver arrives in //! M1 when this wires into the vault. //! -//! NOTE (open question, deferred): PROV / Data-Integrity tooling generally -//! assumes `did:key` (multibase+multicodec). `did:atomic` is chosen for M0 for -//! simplicity and in-tree consistency; `proof.rs` keeps the method swappable. +//! `did:atomic` stays the in-tree method (it matches atomic's identity +//! model), and [`did_key_for_public_key`] additionally provides the standard +//! `did:key` representation of the same key — multicodec `ed25519-pub` +//! (0xed 0x01) + the 32-byte key, multibase base58btc — for interop with +//! Data-Integrity tooling that resolves `did:key` natively. Verification +//! accepts either method for the same key. use atomic_identity::keypair::PublicKey; pub const DID_ATOMIC_PREFIX: &str = "did:atomic:"; +pub const DID_KEY_PREFIX: &str = "did:key:"; +/// Multicodec prefix for an Ed25519 public key (varint 0xed01). +const MULTICODEC_ED25519_PUB: [u8; 2] = [0xed, 0x01]; /// Build the `did:atomic:...` identifier for a public key. pub fn did_for_public_key(public_key: &PublicKey) -> String { @@ -29,6 +35,16 @@ pub fn did_for_public_key(public_key: &PublicKey) -> String { ) } +/// Build the standard `did:key` identifier for an Ed25519 public key +/// (multicodec `ed25519-pub` + key bytes, base58btc multibase). Always +/// starts `did:key:z6Mk` for Ed25519 keys. +pub fn did_key_for_public_key(public_key: &PublicKey) -> String { + let mut bytes = Vec::with_capacity(2 + public_key.as_bytes().len()); + bytes.extend_from_slice(&MULTICODEC_ED25519_PUB); + bytes.extend_from_slice(public_key.as_bytes()); + format!("{}z{}", DID_KEY_PREFIX, bs58::encode(bytes).into_string()) +} + /// The verification method id used in a proof (`<did>#key-1`). pub fn verification_method(did: &str) -> String { format!("{did}#key-1") @@ -39,9 +55,10 @@ pub fn did_from_verification_method(vm: &str) -> &str { vm.split('#').next().unwrap_or(vm) } -/// Does this DID correspond to the given public key? +/// Does this DID correspond to the given public key? Accepts either the +/// in-tree `did:atomic` fingerprint or the standard `did:key` form. pub fn did_matches_public_key(did: &str, public_key: &PublicKey) -> bool { - did == did_for_public_key(public_key) + did == did_for_public_key(public_key) || did == did_key_for_public_key(public_key) } #[cfg(test)] @@ -61,6 +78,27 @@ mod tests { assert!(!did_matches_public_key(&did, &other.public)); } + #[test] + fn did_key_has_ed25519_multicodec_shape_and_verifies() { + let kp = KeyPair::generate(); + let did_key = did_key_for_public_key(&kp.public); + // Ed25519 multicodec + base58btc always yields the z6Mk prefix. + assert!( + did_key.starts_with("did:key:z6Mk"), + "unexpected did:key form: {did_key}" + ); + assert_eq!(did_key, did_key_for_public_key(&kp.public), "stable"); + // Either representation of the same key verifies. + assert!(did_matches_public_key(&did_key, &kp.public)); + assert!(did_matches_public_key( + &did_for_public_key(&kp.public), + &kp.public + )); + + let other = KeyPair::generate(); + assert!(!did_matches_public_key(&did_key, &other.public)); + } + #[test] fn verification_method_roundtrips_to_did() { let kp = KeyPair::generate(); diff --git a/atomic-canonical/src/jcs.rs b/atomic-canonical/src/jcs.rs index d1158f7b..b1ec4d09 100644 --- a/atomic-canonical/src/jcs.rs +++ b/atomic-canonical/src/jcs.rs @@ -9,12 +9,14 @@ //! hash (`hash.rs`) and the Data Integrity proof (`proof.rs`) go through //! `canonicalize`, so the two can never drift. //! -//! Scope note (M0): object-key sorting is by UTF-8 byte order. RFC 8785 -//! specifies sorting by UTF-16 code units; for the ASCII property names in -//! our vocabulary the two orderings are identical. Numbers are emitted via -//! `serde_json`'s formatter, which is exact for the integer/simple values we -//! use. Both are revisited if the vocabulary ever admits non-ASCII keys or -//! floating-point payloads. +//! Object keys are sorted by UTF-16 code units as RFC 8785 §3.2.3 specifies +//! (not by UTF-8 bytes — the two differ once keys leave the BMP, e.g. an +//! emoji key sorts after `\u{ff61}` in UTF-8 but before it in UTF-16). +//! +//! Scope note: numbers are emitted via `serde_json`'s formatter, which +//! matches RFC 8785 for the integer values our vocabulary admits; the full +//! ECMAScript number-to-string algorithm is only needed if floating-point +//! payloads are ever admitted. use serde_json::Value; @@ -44,7 +46,7 @@ fn write_value(out: &mut String, value: &Value) { } Value::Object(map) => { let mut keys: Vec<&String> = map.keys().collect(); - keys.sort_by(|a, b| a.as_bytes().cmp(b.as_bytes())); + keys.sort_by(|a, b| a.encode_utf16().cmp(b.encode_utf16())); out.push('{'); for (i, key) in keys.iter().enumerate() { if i > 0 { @@ -95,4 +97,17 @@ mod tests { let v = json!({ "k": "a\"b\nc" }); assert_eq!(canonicalize(&v), r#"{"k":"a\"b\nc"}"#); } + + /// RFC 8785 §3.2.3: keys sort by UTF-16 code units. A supplementary-plane + /// key (😀, surrogate pair D83D DE00) must sort BEFORE U+FF61 (。) — the + /// opposite of UTF-8 byte order, where 😀 (F0 9F …) follows 。 (EF BD A1). + #[test] + fn keys_sort_by_utf16_code_units_not_utf8_bytes() { + let v = json!({ "\u{ff61}": 1, "😀": 2 }); + assert_eq!( + canonicalize(&v), + "{\"😀\":2,\"\u{ff61}\":1}", + "supplementary-plane keys must sort by UTF-16 code units" + ); + } } diff --git a/atomic-canonical/src/proof.rs b/atomic-canonical/src/proof.rs index 34c18424..04782d46 100644 --- a/atomic-canonical/src/proof.rs +++ b/atomic-canonical/src/proof.rs @@ -5,10 +5,8 @@ //! and sign over the same canonical bytes the content hash uses, via the one //! `jcs` entry point — so hash and signature can never disagree. //! -//! `proofValue` is a multibase string. We use base32-upper (`B`) via -//! `data-encoding` (already in-tree) rather than base58btc (`z`) to avoid an -//! extra dependency; it is a valid multibase encoding and the prefix is -//! swappable when a base58 dependency is admitted. +//! `proofValue` is a multibase string in base58btc (`z`), as the +//! `eddsa-jcs-2022` cryptosuite specifies. use atomic_identity::identity::Identity; use atomic_identity::keypair::{KeyPair, PublicKey}; @@ -25,8 +23,8 @@ use crate::node::{CanonicalNode, Proof}; pub const CRYPTOSUITE: &str = "eddsa-jcs-2022"; pub const PROOF_TYPE: &str = "DataIntegrityProof"; pub const PROOF_PURPOSE: &str = "assertionMethod"; -/// Multibase prefix for base32-upper, no padding. -const MULTIBASE_BASE32_UPPER: char = 'B'; +/// Multibase prefix for base58btc — the encoding `eddsa-jcs-2022` specifies. +const MULTIBASE_BASE58_BTC: char = 'z'; /// Canonical property names. Hardcoded because the closed vocabulary /// standardizes them across *all* node types (Intent, Memory, and any future @@ -188,25 +186,25 @@ pub fn verify_memory(node: &MemoryNode, public_key: &PublicKey) -> Result<()> { fn encode_proof_value(signature: &Signature) -> String { let mut s = String::new(); - s.push(MULTIBASE_BASE32_UPPER); - s.push_str(&data_encoding::BASE32_NOPAD.encode(signature.as_bytes())); + s.push(MULTIBASE_BASE58_BTC); + s.push_str(&bs58::encode(signature.as_bytes()).into_string()); s } fn decode_proof_value(value: &str) -> Result<Signature> { let mut chars = value.chars(); match chars.next() { - Some(MULTIBASE_BASE32_UPPER) => {} + Some(MULTIBASE_BASE58_BTC) => {} _ => { return Err(CanonicalError::Proof(format!( "unsupported multibase prefix in proofValue: {value:.4}…" ))) } } - let body = &value[MULTIBASE_BASE32_UPPER.len_utf8()..]; - let bytes = data_encoding::BASE32_NOPAD - .decode(body.as_bytes()) - .map_err(|e| CanonicalError::Proof(format!("bad base32 proofValue: {e}")))?; + let body = &value[MULTIBASE_BASE58_BTC.len_utf8()..]; + let bytes = bs58::decode(body) + .into_vec() + .map_err(|e| CanonicalError::Proof(format!("bad base58btc proofValue: {e}")))?; Signature::from_slice(&bytes).map_err(|e| CanonicalError::Proof(e.to_string())) } From 52938f87f0b1b35d1f0742a48fd82452569c49fa Mon Sep 17 00:00:00 2001 From: Bradley Hilton <graywolf336@craftyn.com> Date: Mon, 6 Jul 2026 12:17:31 -0500 Subject: [PATCH 11/21] feat(canonical,cli): align PROV projection to the Recording-the-Why baseline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bring the PROV slice in line with the baseline (which is change-primary, and treats the provenance graph as "signable, not signed"): - Unsigned by default, signable on demand. `project()` was already unsigned; the CLI `show` (and `trace --json`) now emit the UNSIGNED projection by default and gain a `--sign` flag for the signable standalone artifact (top-level attributedTo/contentHash/proof). Provenance is a derived view of already-signed primaries whose chain integrity comes from turnParent hash-linking, so it carries no proof envelope unless asked. - `used` flywheel edge is now a first-class, populated field on ProvActivityInput, emitted only when non-empty (unknown links omitted, never invented). The current atomic_core capture records no structured inputs, so the mapping supplies an empty set for now; full population is gated on a separate capture-path change. (Was hardcoded `used: []`.) - Ship the real @context: atomic-canonical/ns/ctx.jsonld + a `context` module (embedded, with defined_terms/undefined_terms helpers) + a coverage test asserting every key the signed PROV graph emits resolves to a prov:/atom:/ sec:/rdfs:/xsd: IRI. Closes the bare-URL gap; makes the JSON real RDF. - Agent @id stays urn:atomic:agent:<slug> (NOT the baseline example's did:atomic:agent:) on W3C DID-Core grounds: a DID must resolve to a DID Document with verification material; a keyless SoftwareAgent has none, so a did:atomic:agent: label is a non-resolvable fake (and not a valid did:atomic fingerprint). A urn: is the honest, PROV-O-valid identifier; a real did:key is the future path once agents hold keys. Doc reframed accordingly. - Agent human label emitted as rdfs:label (via the `label` ctx term), not the non-existent prov:label. Change-primary addressing (provgraph:<changeid>) and the turn+turnParent activity model are unchanged — both already match the baseline. All canonical + cli + provenance tests green; clippy clean. --- atomic-canonical/ns/ctx.jsonld | 85 +++++++++++++ atomic-canonical/src/context.rs | 67 ++++++++++ atomic-canonical/src/lib.rs | 1 + atomic-canonical/src/prov.rs | 114 ++++++++++++------ atomic-cli/src/commands/provenance/command.rs | 99 ++++++++------- atomic-cli/src/commands/provenance/mapping.rs | 6 + .../tests/provenance_integration_test.rs | 48 +++++--- 7 files changed, 327 insertions(+), 93 deletions(-) create mode 100644 atomic-canonical/ns/ctx.jsonld create mode 100644 atomic-canonical/src/context.rs diff --git a/atomic-canonical/ns/ctx.jsonld b/atomic-canonical/ns/ctx.jsonld new file mode 100644 index 00000000..161d42a3 --- /dev/null +++ b/atomic-canonical/ns/ctx.jsonld @@ -0,0 +1,85 @@ +{ + "@context": { + "@version": 1.1, + "atom": "https://atomic.dev/ns#", + "prov": "http://www.w3.org/ns/prov#", + "sec": "https://w3id.org/security#", + "rdfs": "http://www.w3.org/2000/01/rdf-schema#", + "xsd": "http://www.w3.org/2001/XMLSchema#", + + "Intent": "atom:Intent", + "AcceptanceCriterion": "atom:AcceptanceCriterion", + "Task": "atom:Task", + "ScopeItem": "atom:ScopeItem", + "Constraint": "atom:Constraint", + "Ref": "atom:Ref", + "Memory": "atom:Memory", + + "humanKey": "atom:humanKey", + "title": "atom:title", + "status": "atom:status", + "priority": "atom:priority", + "view": "atom:view", + "why": "atom:why", + "text": "atom:text", + "contentHash": "atom:contentHash", + "createdAt": { "@id": "atom:createdAt", "@type": "xsd:dateTime" }, + "attributedTo": { "@id": "atom:attributedTo", "@type": "@id" }, + + "motivatedBy": { "@id": "atom:motivatedBy", "@type": "@id" }, + "informedBy": { "@id": "atom:informedBy", "@type": "@id" }, + "hasAcceptanceCriterion": "atom:hasAcceptanceCriterion", + "hasTask": "atom:hasTask", + "hasScopeIn": "atom:hasScopeIn", + "hasScopeOut": "atom:hasScopeOut", + "hasConstraint": "atom:hasConstraint", + "dependsOn": "atom:dependsOn", + + "acStatus": "atom:acStatus", + "verifiedBy": { "@id": "atom:verifiedBy", "@type": "@id" }, + "evidence": { "@id": "atom:evidence", "@type": "@id" }, + + "taskStatus": "atom:taskStatus", + "touchesFile": "atom:touchesFile", + "satisfies": { "@id": "atom:satisfies", "@type": "@id" }, + + "to": { "@id": "atom:to", "@type": "@id" }, + "edge": "atom:edge", + + "memoryKind": "atom:memoryKind", + "about": { "@id": "atom:about", "@type": "@id" }, + "supersedes": { "@id": "atom:supersedes", "@type": "@id" }, + "previousRevision": { "@id": "atom:previousRevision", "@type": "@id" }, + + "proof": "sec:proof", + "DataIntegrityProof": "sec:DataIntegrityProof", + "cryptosuite": "sec:cryptosuite", + "verificationMethod": { "@id": "sec:verificationMethod", "@type": "@id" }, + "proofPurpose": "sec:proofPurpose", + "proofValue": "sec:proofValue", + + "Activity": "prov:Activity", + "SoftwareAgent": "prov:SoftwareAgent", + "Person": "prov:Person", + "label": "rdfs:label", + "associatedWith": { "@id": "prov:wasAssociatedWith", "@type": "@id" }, + "wasAssociatedWith": { "@id": "prov:wasAssociatedWith", "@type": "@id" }, + "actedOnBehalfOf": { "@id": "prov:actedOnBehalfOf", "@type": "@id" }, + "used": { "@id": "prov:used", "@type": "@id" }, + "generated": { "@id": "prov:generated", "@type": "@id" }, + "startedAtTime": { "@id": "prov:startedAtTime", "@type": "xsd:dateTime" }, + "endedAtTime": { "@id": "prov:endedAtTime", "@type": "xsd:dateTime" }, + + "sessionId": "atom:sessionId", + "runId": "atom:runId", + "agentName": "atom:agentName", + "agentDisplayName": "atom:agentDisplayName", + "model": "atom:model", + "vendor": "atom:vendor", + "turnCount": { "@id": "atom:turnCount", "@type": "xsd:integer" }, + "turnParent": { "@id": "atom:turnParent", "@type": "@id" }, + "partOfRun": { "@id": "atom:partOfRun", "@type": "@id" }, + "ownerSessionId": "atom:ownerSessionId", + "workItem": { "@id": "atom:workItem", "@type": "@id" } + } +} diff --git a/atomic-canonical/src/context.rs b/atomic-canonical/src/context.rs new file mode 100644 index 00000000..3c12256e --- /dev/null +++ b/atomic-canonical/src/context.rs @@ -0,0 +1,67 @@ +//! The JSON-LD `@context` document — the real term→IRI table served at +//! [`crate::node::CONTEXT_URL`]. +//! +//! Every canonical node (Intent, Memory) and the PROV projection name this one +//! context by URL. Shipping the actual document (rather than a bare URL) makes +//! the emitted JSON genuine, offline-processable RDF: each short key maps to a +//! `prov:`/`atom:`/`sec:`/`rdfs:`/`xsd:` IRI, object properties are `@type:@id`, +//! and timestamps are `xsd:dateTime`. The compiled bytes are the trusted +//! artifact; the file under `ns/` is the reviewable source. + +use std::collections::BTreeSet; + +use serde_json::Value; + +/// The embedded `@context` document (the bytes served at `CONTEXT_URL`). +pub const CONTEXT_JSONLD: &str = include_str!("../ns/ctx.jsonld"); + +/// The set of term keys defined by the context (terms + namespace prefixes). +/// Parsed from the embedded document. +pub fn defined_terms() -> BTreeSet<String> { + let doc: Value = serde_json::from_str(CONTEXT_JSONLD).expect("ctx.jsonld is valid JSON"); + doc.get("@context") + .and_then(Value::as_object) + .map(|m| m.keys().cloned().collect()) + .unwrap_or_default() +} + +/// Collect every object key appearing anywhere in `value`. +pub fn collect_keys(value: &Value, out: &mut BTreeSet<String>) { + match value { + Value::Object(map) => { + for (k, v) in map { + out.insert(k.clone()); + collect_keys(v, out); + } + } + Value::Array(items) => items.iter().for_each(|v| collect_keys(v, out)), + _ => {} + } +} + +/// The keys in `value` that the context must define: bare terms only — +/// JSON-LD keywords (`@id`, `@type`, …) need no term, and CURIEs (`prov:Activity`) +/// resolve through their namespace prefix. +pub fn undefined_terms(value: &Value) -> BTreeSet<String> { + let defined = defined_terms(); + let mut keys = BTreeSet::new(); + collect_keys(value, &mut keys); + keys.into_iter() + .filter(|k| !k.starts_with('@') && !k.contains(':')) + .filter(|k| !defined.contains(k)) + .collect() +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn context_document_is_valid_and_nonempty() { + assert!(defined_terms().len() > 20, "context should define the vocabulary"); + assert!(defined_terms().contains("prov")); + assert!(defined_terms().contains("used")); + assert!(defined_terms().contains("associatedWith")); + assert!(defined_terms().contains("label")); + } +} diff --git a/atomic-canonical/src/lib.rs b/atomic-canonical/src/lib.rs index c49bab50..0b98fb86 100644 --- a/atomic-canonical/src/lib.rs +++ b/atomic-canonical/src/lib.rs @@ -28,6 +28,7 @@ //! **non-production dev identities**. Key-at-rest encryption must land before //! any attested node is trusted in a real/shared setting. +pub mod context; pub mod did; pub mod directive; pub mod error; diff --git a/atomic-canonical/src/prov.rs b/atomic-canonical/src/prov.rs index 653d2af9..7967e2f6 100644 --- a/atomic-canonical/src/prov.rs +++ b/atomic-canonical/src/prov.rs @@ -1,12 +1,21 @@ -//! W3C PROV projection — a signed PROV JSON-LD named subgraph over one turn's -//! provenance. +//! W3C PROV projection — a PROV JSON-LD named subgraph over one turn's provenance. //! //! This is a **projection** of provenance atomic already captures (a per-turn //! `ProvenanceGraph`), NOT new capture. Given a plain input struct describing a //! turn's activity, [`project`] builds the named-subgraph JSON-LD described in -//! `docs/recording-the-why.md` §"A provenance graph", and [`attest_prov`] / -//! [`verify_prov`] sign and verify it through the *same* canonicalization/signing -//! path every other node type uses ([`crate::proof::attest_value`]). +//! the "Recording the Why" baseline §"A provenance graph". +//! +//! ## Unsigned by default; **signable** on demand +//! Per the baseline, the provenance graph is "one addressable, **signable** unit +//! you can hand to an auditor whole" — *signable*, not *signed*. It is a derived +//! view whose `used`/`generated` edges point at already-signed primaries +//! (intents, memories, changes), and its own chain integrity comes from +//! `turnParent` hash-linking — so the default projection carries **no** proof +//! envelope. [`attest_prov`] / [`verify_prov`] are the opt-in "signable" path: +//! when you need a standalone, tamper-evident bundle, they sign/verify the graph +//! through the *same* canonicalization/signing path every other node type uses +//! ([`crate::proof::attest_value`]), which injects a top-level +//! `attributedTo`/`contentHash`/`proof` bound to the signing Person. //! //! ## Layering //! This module — like the rest of `atomic-canonical` — is **`atomic-core` @@ -15,29 +24,25 @@ //! ProvActivityInput` mapping (and all base32/`Hash` handling) lives at the //! `atomic-cli` boundary. Do not add `use atomic_core::` here. //! -//! ## Two deliberate divergences from the doc example -//! 1. **Agent id is a URN, not a DID.** The doc example (recording-the-why.md -//! lines 322/333) shows `did:atomic:agent:claude`. That is illustrative and -//! *wrong* per the hard scope: `did:atomic:<..>` is a key **fingerprint**, not -//! a name (see [`crate::did`]). The `SoftwareAgent` here is a NON-VERIFIABLE -//! descriptive label, so its `@id` is `urn:atomic:agent:<slug>`. Only the -//! **person's** key signs the whole `@graph`; nothing about the agent is -//! signed-as-an-identity. -//! 2. **A top-level `attributedTo` (+ `contentHash`/`proof`) envelope.** The -//! doc `@graph` has no top-level `attributedTo`; [`crate::proof::attest_value`] -//! injects one from the signer's `did:atomic` (the Person), and we ACCEPT it -//! rather than build a bespoke signing path that skips the injection. It is -//! semantically correct (that is who signed and on whose behalf the activity -//! ran), consistent with Intent/Memory nodes, and — being inside the -//! hashing/signing view — strengthens the artifact by binding the whole -//! subgraph to the signer. The signed artifact's top level therefore carries -//! `@context`, `@id`, `@graph`, `attributedTo`, `contentHash`, `proof`, with -//! the PROV nodes inside `@graph`. +//! ## Agent id is a URN, not a DID (W3C DID-Core compliance) +//! The baseline example writes the `SoftwareAgent` as `did:atomic:agent:claude`. +//! We deliberately emit `urn:atomic:agent:<slug>` instead. A `did:` identifier +//! must resolve to a DID Document with verification material (DID-Core); a +//! keyless agent has none, so a `did:atomic:agent:<name>` would be a +//! non-resolvable *fake* DID — and it is not even a valid `did:atomic`, which is +//! a key fingerprint `base32(blake3(pubkey))` (see [`crate::did`]). PROV-O admits +//! any IRI for an agent, so a `urn:` is the honest, spec-compliant choice for a +//! non-verifiable descriptive label. When agents are issued their own keypairs, +//! the correct `@id` becomes a real resolvable `did:key` — never +//! `did:atomic:agent:`. Only the **Person's** key signs (in the signable path). //! -//! ## The flywheel `used` edge is DEFERRED -//! The activity's `used` edge (what the turn pulled from the vault) is emitted as -//! an EMPTY array literal (`"used": []`). It is intentionally not populated in -//! this slice and is not an input field. +//! ## The flywheel `used` edge +//! The activity's `used` edge (the intents/memories/vault state the turn pulled) +//! is a first-class, populated field ([`ProvActivityInput::used`]). Following the +//! baseline's "unknown links are omitted, never invented", it is emitted only +//! when non-empty. Today the `atomic-core` capture records no structured inputs, +//! so the mapping supplies an empty set until the capture records them (a +//! separate capture-path change); the projection itself is ready. use atomic_identity::identity::Identity; use atomic_identity::keypair::{KeyPair, PublicKey}; @@ -75,10 +80,14 @@ pub struct ProvActivityInput { pub person_did: String, /// `urn:atomic:change:<base32>` for each explained change (PROV `generated`). pub generated: Vec<String>, + /// What the turn `used` — `urn:atomic:intent:<..>` / `urn:atomic:memory:<..>` + /// (and, eventually, vault-state refs) the activity pulled in. The flywheel + /// input edge. Emitted only when non-empty (unknown links are omitted, never + /// invented); empty until the capture records structured inputs. + pub used: Vec<String>, /// `urn:atomic:activity:<parent-activity-id>` (PROV `wasInformedBy` / /// `turnParent`), or `None` to omit the key entirely. pub turn_parent: Option<String>, - // `used: []` is DEFERRED — intentionally NOT a field. } /// `urn:atomic:change:<base32>` for a change hash's base32 form. @@ -139,9 +148,12 @@ pub fn project(input: &ProvActivityInput) -> Value { activity.insert("associatedWith".into(), json!(agent_id)); activity.insert("actedOnBehalfOf".into(), json!(input.person_did)); activity.insert("generated".into(), json!(input.generated)); - // Flywheel `used` edge DEFERRED — emit an explicit empty array literal. - activity.insert("used".into(), json!([])); - // wasInformedBy — omit the key entirely when there is no parent turn. + // Flywheel `used` edge — emitted only when non-empty (unknown omitted, never + // invented). Empty until the capture records structured inputs. + if !input.used.is_empty() { + activity.insert("used".into(), json!(input.used)); + } + // turnParent — omit the key entirely when there is no parent turn. if let Some(parent) = &input.turn_parent { activity.insert("turnParent".into(), json!(parent)); } @@ -151,7 +163,9 @@ pub fn project(input: &ProvActivityInput) -> Value { agent.insert("@type".into(), json!("prov:SoftwareAgent")); agent.insert("@id".into(), json!(agent_id)); agent.insert("actedOnBehalfOf".into(), json!(input.person_did)); - agent.insert("prov:label".into(), json!(input.agent_display_name)); + // Human label as rdfs:label (there is no prov:label in PROV-O); the ctx maps + // the `label` term to rdfs:label. + agent.insert("label".into(), json!(input.agent_display_name)); if let Some(vendor) = &input.agent_vendor { agent.insert("vendor".into(), json!(vendor)); } @@ -214,6 +228,10 @@ mod tests { agent_vendor: Some("anthropic".into()), person_did: person_did.into(), generated: vec![change_urn("CHANGEBASE32")], + used: vec![ + "urn:atomic:intent:019efe85".into(), + "urn:atomic:memory:01J8ZC4R8T".into(), + ], turn_parent: Some(activity_urn("session-000")), } } @@ -267,10 +285,13 @@ mod tests { activity.get("generated"), Some(&json!(["urn:atomic:change:CHANGEBASE32"])) ); - // `used` is present and an EMPTY array (flywheel deferred). + // `used` is populated (the flywheel input edge). assert_eq!( - activity.get("used").and_then(Value::as_array).map(Vec::len), - Some(0) + activity.get("used"), + Some(&json!([ + "urn:atomic:intent:019efe85", + "urn:atomic:memory:01J8ZC4R8T" + ])) ); assert_eq!( activity.get("turnParent").and_then(Value::as_str), @@ -282,7 +303,7 @@ mod tests { let agent_id = agent.get("@id").and_then(Value::as_str).unwrap(); assert!(agent_id.starts_with("urn:atomic:agent:")); assert!(!agent_id.starts_with("did:")); - assert_eq!(agent.get("prov:label").and_then(Value::as_str), Some("Claude Code")); + assert_eq!(agent.get("label").and_then(Value::as_str), Some("Claude Code")); assert_eq!(agent.get("vendor").and_then(Value::as_str), Some("anthropic")); // Person @id == the real did:atomic. @@ -297,6 +318,7 @@ mod tests { input.agent_vendor = None; input.started_at = None; input.ended_at = None; + input.used = Vec::new(); let value = project(&input); let activity = node_of_type(&value, "prov:Activity"); @@ -304,8 +326,8 @@ mod tests { assert!(activity.get("turnParent").is_none()); assert!(activity.get("prov:startedAtTime").is_none()); assert!(activity.get("prov:endedAtTime").is_none()); - // But `used` is still present as an empty array. - assert!(activity.get("used").is_some()); + // `used` is omitted when empty (unknown links omitted, never invented). + assert!(activity.get("used").is_none()); let agent = node_of_type(&value, "prov:SoftwareAgent"); assert!(agent.get("vendor").is_none()); @@ -365,4 +387,20 @@ mod tests { assert_eq!(normalize_agent_slug("codex"), "codex"); assert_eq!(normalize_agent_slug(""), ""); } + + /// Every bare key the projection emits — including the signed envelope + /// (`attributedTo`/`contentHash`/`proof`/…) — must be defined in the shipped + /// `@context`, so the emitted JSON is real, resolvable RDF (the closed-registry + /// discipline applied to the PROV projection). + #[test] + fn every_projected_key_is_defined_in_the_context() { + let (id, kp) = dev_identity(); + let person = crate::did::did_for_public_key(&id.public_key); + let signed = attest_prov(&sample_input(&person), &id, &kp); + let undefined = crate::context::undefined_terms(&signed); + assert!( + undefined.is_empty(), + "these projected keys have no @context term: {undefined:?}" + ); + } } diff --git a/atomic-cli/src/commands/provenance/command.rs b/atomic-cli/src/commands/provenance/command.rs index 5b267fcf..7a47086b 100644 --- a/atomic-cli/src/commands/provenance/command.rs +++ b/atomic-cli/src/commands/provenance/command.rs @@ -1,10 +1,13 @@ //! `atomic provenance {trace,show}` subcommand implementations. //! //! Both are READ-ONLY and COMPUTE-ON-DEMAND: they load the per-turn -//! `ProvenanceGraph` atomic already captured, project it into a W3C PROV JSON-LD -//! named subgraph, and (for `show`/`--json`) sign it on the fly with the person's -//! identity. NOTHING is written — no vault entry, no sidecar, no -//! `save_provenance_graph`, no content-hash/merkle touch. +//! `ProvenanceGraph` atomic already captured and project it into a W3C PROV +//! JSON-LD named subgraph. Per the baseline the graph is **signable, not signed** +//! — the default JSON output is the unsigned projection; `--sign` produces the +//! signable standalone artifact (a top-level `attributedTo`/`contentHash`/`proof` +//! bound to the person's identity) for handing to an auditor. NOTHING is written +//! either way — no vault entry, no sidecar, no `save_provenance_graph`, no +//! content-hash/merkle touch. use clap::Parser; @@ -24,46 +27,51 @@ use crate::output::{emphasis, hint, info}; /// /// Walks the provenance graph for a change — the activity that generated it, the /// changes it generated, the agent and person involved, and the parent turn — -/// and prints the human-readable chain. `--json` emits the signed PROV JSON-LD -/// named subgraph instead (identical to `show --json`). +/// and prints the human-readable chain. `--json` emits the PROV JSON-LD named +/// subgraph instead (unsigned by default; add `--sign` for the signable artifact). #[derive(Parser, Debug)] #[command(name = "trace")] pub struct ProvenanceTrace { /// Change hash, hash prefix, or `urn:atomic:change:<base32>`. pub target: String, - /// Identity whose key signs the projection (for `--json`). Defaults to the - /// current default identity. + /// Identity whose key signs the projection (with `--json --sign`, and to + /// resolve the Person). Defaults to the current default identity. #[arg(long)] pub identity: Option<String>, - /// Emit the signed PROV JSON-LD `@graph` instead of the human chain. + /// Emit the PROV JSON-LD `@graph` instead of the human chain. #[arg(long)] pub json: bool, + + /// With `--json`, emit the SIGNABLE artifact — sign the graph (top-level + /// `attributedTo`/`contentHash`/`proof`) instead of the plain projection. + #[arg(long)] + pub sign: bool, } -/// Project (and sign) the PROV JSON-LD named subgraph for a change. +/// Project the PROV JSON-LD named subgraph for a change. /// -/// Default (and `--json`) prints the SIGNED PROV JSON-LD `@graph` — the -/// verifiable artifact you hand an auditor. It carries a top-level -/// `attributedTo`/`contentHash`/`proof` envelope injected by the shared signing -/// path (the person's `did:atomic` signs the whole subgraph); this one-line -/// divergence from the doc example is intentional and documented in -/// `atomic-canonical`'s `prov` module. +/// Prints the UNSIGNED projection by default — the baseline's "signable" unit, +/// a derived view whose integrity comes from `turnParent` hash-linking and the +/// already-signed primaries it references. `--sign` emits the SIGNABLE standalone +/// artifact instead: a top-level `attributedTo`/`contentHash`/`proof` envelope +/// injected by the shared signing path (the person's `did:atomic` signs the whole +/// subgraph), for handing to an auditor as a self-verifying bundle. #[derive(Parser, Debug)] #[command(name = "show")] pub struct ProvenanceShow { /// Change hash, hash prefix, or `urn:atomic:change:<base32>`. pub target: String, - /// Identity whose key signs the projection. Defaults to the current default - /// identity. + /// Identity used to resolve the Person (and to sign with `--sign`). Defaults + /// to the current default identity. #[arg(long)] pub identity: Option<String>, - /// Emit the signed PROV JSON-LD `@graph` (the default for `show`). + /// Emit the SIGNABLE artifact — sign the graph instead of the plain projection. #[arg(long)] - pub json: bool, + pub sign: bool, } impl Command for ProvenanceTrace { @@ -74,17 +82,22 @@ impl Command for ProvenanceTrace { let graphs = load_graphs(&repo, &change_hash)?; if self.json { - // Sign and emit, exactly like `show --json`. + // Emit the JSON-LD, exactly like `show` (unsigned by default; `--sign` + // for the signable artifact). let (identity, keypair) = resolve_person(self.identity.as_deref())?; let person_did = did_for_public_key(&identity.public_key); - let signed = graphs + let values = graphs .iter() .map(|(_, g)| { let input = map_graph_to_input(&repo, g, &change_hash, &person_did); - attest_prov(&input, &identity, &keypair) + if self.sign { + attest_prov(&input, &identity, &keypair) + } else { + project(&input) + } }) .collect::<Vec<_>>(); - print_signed(&signed); + print_value(&values, self.sign); return Ok(()); } @@ -112,18 +125,19 @@ impl Command for ProvenanceShow { let (identity, keypair) = resolve_person(self.identity.as_deref())?; let person_did = did_for_public_key(&identity.public_key); - let signed = graphs + let values = graphs .iter() .map(|(_, g)| { let input = map_graph_to_input(&repo, g, &change_hash, &person_did); - attest_prov(&input, &identity, &keypair) + if self.sign { + attest_prov(&input, &identity, &keypair) + } else { + project(&input) + } }) .collect::<Vec<_>>(); - // `show` always emits the signed JSON-LD artifact; `--json` is accepted - // as an explicit synonym so the two verbs share a flag. - let _ = self.json; - print_signed(&signed); + print_value(&values, self.sign); Ok(()) } } @@ -229,20 +243,23 @@ fn resolve_person( Ok((identity, keypair)) } -/// Print the signed PROV JSON-LD artifact(s) to stdout. -fn print_signed(signed: &[serde_json::Value]) { - let out = if signed.len() == 1 { - serde_json::to_string_pretty(&signed[0]) +/// Print the PROV JSON-LD artifact(s) to stdout. When `signed`, add the +/// dev-signature caveat (the signing path was used). +fn print_value(values: &[serde_json::Value], signed: bool) { + let out = if values.len() == 1 { + serde_json::to_string_pretty(&values[0]) } else { - serde_json::to_string_pretty(&signed) + serde_json::to_string_pretty(&values) } - .expect("signed PROV value serialization is infallible"); + .expect("PROV value serialization is infallible"); println!("{out}"); - eprintln!( - "note: signing keys are stored unencrypted on disk; treat this \ - projection as a non-production dev signature until key-at-rest \ - encryption lands." - ); + if signed { + eprintln!( + "note: signing keys are stored unencrypted on disk; treat this \ + signed projection as a non-production dev signature until key-at-rest \ + encryption lands." + ); + } } /// Print the human-readable flywheel chain: change -> activity -> generated -> diff --git a/atomic-cli/src/commands/provenance/mapping.rs b/atomic-cli/src/commands/provenance/mapping.rs index ba4095d5..748ed401 100644 --- a/atomic-cli/src/commands/provenance/mapping.rs +++ b/atomic-cli/src/commands/provenance/mapping.rs @@ -81,6 +81,12 @@ pub fn map_graph_to_input( agent_vendor, person_did: person_did.to_string(), generated, + // The flywheel `used` edge (intents/memories the turn pulled). The current + // `atomic_core::ProvenanceGraph` capture records no structured inputs — + // only `nodes`/`edges`/`changes_explained` — so we supply an empty set + // (the projection omits `used` rather than inventing edges). Populating it + // is gated on the capture recording inputs (a separate capture-path change). + used: Vec::new(), turn_parent, } } diff --git a/atomic-cli/tests/provenance_integration_test.rs b/atomic-cli/tests/provenance_integration_test.rs index 31f952f6..3afa0c66 100644 --- a/atomic-cli/tests/provenance_integration_test.rs +++ b/atomic-cli/tests/provenance_integration_test.rs @@ -5,9 +5,10 @@ //! //! These prove the PROJECTION path end-to-end: //! 1. a REAL `ProvenanceGraph` is persisted with `repo.save_provenance_graph`, -//! 2. `atomic provenance show --json` projects + signs it on the fly, -//! 3. the emitted PROV JSON-LD parses and its proof verifies via `verify_prov` -//! against the resolved identity's public key, +//! 2. `atomic provenance show` projects it UNSIGNED on the fly (the baseline's +//! "signable, not signed" default), +//! 3. `atomic provenance show --sign` emits the signable artifact, and its proof +//! verifies via `verify_prov` against the resolved identity's public key, //! 4. `atomic provenance trace` prints the human flywheel chain, and //! 5. compute-on-demand: no new files appear and the provenance-graph count is //! unchanged after trace/show. @@ -119,7 +120,7 @@ fn repo_with_internal_change(repo_dir: &Path, home_dir: &Path) -> Hash { } #[test] -fn provenance_show_projects_signs_and_verifies_and_writes_nothing() { +fn provenance_show_defaults_unsigned_and_sign_flag_verifies_and_writes_nothing() { let repo_tmp = TempDir::new().unwrap(); let home_tmp = TempDir::new().unwrap(); let repo_dir = repo_tmp.path(); @@ -182,11 +183,8 @@ fn provenance_show_projects_signs_and_verifies_and_writes_nothing() { change_hash.to_base32() )])) ); - // used is present and EMPTY (flywheel deferred). - assert_eq!( - activity.get("used").and_then(Value::as_array).map(Vec::len), - Some(0) - ); + // `used` is omitted when empty (unknown links omitted, never invented). + assert!(activity.get("used").is_none()); let agent = graph_nodes .iter() .find(|n| n.get("@type").and_then(Value::as_str) == Some("prov:SoftwareAgent")) @@ -195,17 +193,39 @@ fn provenance_show_projects_signs_and_verifies_and_writes_nothing() { assert_eq!(agent_id, "urn:atomic:agent:claude"); assert!(!agent_id.starts_with("did:"), "agent id must NOT be a did"); assert_eq!( - agent.get("prov:label").and_then(Value::as_str), + agent.get("label").and_then(Value::as_str), Some("Claude Code") ); - // The proof verifies against the resolved identity's public key. - verify_prov(&value, &pubkey).expect("emitted PROV proof must verify"); - // Top-level attributedTo == the signer's Person did (accepted injection). + // Default `show` is UNSIGNED — the baseline's "signable, not signed" unit. + assert!(value.get("proof").is_none(), "default show must be unsigned"); + assert!(value.get("attributedTo").is_none()); + assert!(value.get("contentHash").is_none()); + + // `show --sign` emits the SIGNABLE artifact: it verifies against the resolved + // key and carries the top-level attributedTo/contentHash/proof envelope. + let signed_out = atomic( + repo_dir, + home_dir, + &["provenance", "show", "--sign", &change_hash.to_base32()], + ); + assert!( + signed_out.status.success(), + "provenance show --sign failed: {}", + String::from_utf8_lossy(&signed_out.stderr) + ); + let signed: Value = serde_json::from_str(&String::from_utf8(signed_out.stdout).unwrap()) + .expect("show --sign emits valid JSON-LD"); + verify_prov(&signed, &pubkey).expect("signed PROV proof must verify"); assert_eq!( - value.get("attributedTo").and_then(Value::as_str), + signed.get("attributedTo").and_then(Value::as_str), Some(did_for_public_key(&pubkey).as_str()) ); + assert!(signed.get("proof").is_some()); + assert!(signed + .get("contentHash") + .and_then(Value::as_str) + .is_some_and(|h| h.starts_with("blake3:"))); // `trace` — prints the human chain (change -> activity -> generated -> ...). let trace = atomic( From f72cb69048a31cfd14b0a5479cc4217c4d64e7e7 Mon Sep 17 00:00:00 2001 From: Bradley Hilton <graywolf336@craftyn.com> Date: Mon, 6 Jul 2026 13:22:32 -0500 Subject: [PATCH 12/21] =?UTF-8?q?chore(shacl):=20remove=20atomic-shacl=20s?= =?UTF-8?q?pike=20=E2=80=94=20SHACL=20runs=20in=20Circuit=20Breaker,=20not?= =?UTF-8?q?=20atomic?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Owner decision (Lee): the SHACL formal validation is a Circuit Breaker (CB) workflow, not built into atomic. So no SHACL engine ships in the atomic binary. - Delete the atomic-shacl crate (the oxirs 0.3.1 spike) and drop it from the workspace members + [workspace.dependencies]. This prunes the entire ~432-crate oxirs/scirs/ndarray/icu/rustls transitive tree from Cargo.lock. - Preserve the spike's conclusion as docs/shacl-oxirs-spike-findings.md (why oxirs / an in-atomic engine was rejected), with a status banner recording the CB decision. atomic keeps the fast in-process hand-coded tier-1 gate, emits canonical JSON-LD (intent/memory/provenance) with a real @context, and will ship the shape .ttl as data for CB to validate against. The SHACL engine choice now lives in CB, free of atomic's hermeticity constraints. bs58 (base58btc proofValue) stays — it is used by the spec-conformance work, not by the removed crate. canonical + cli tests unaffected (they never depended on atomic-shacl); clippy clean. --- Cargo.toml | 12 - atomic-shacl/Cargo.toml | 40 --- atomic-shacl/src/engine.rs | 238 --------------- atomic-shacl/src/lib.rs | 22 -- atomic-shacl/src/shapes.rs | 13 - atomic-shacl/src/shapes/intent.ttl | 88 ------ atomic-shacl/src/shapes/memory.ttl | 56 ---- atomic-shacl/src/shim.rs | 250 ---------------- atomic-shacl/tests/differential.rs | 277 ------------------ .../shacl-oxirs-spike-findings.md | 9 + 10 files changed, 9 insertions(+), 996 deletions(-) delete mode 100644 atomic-shacl/Cargo.toml delete mode 100644 atomic-shacl/src/engine.rs delete mode 100644 atomic-shacl/src/lib.rs delete mode 100644 atomic-shacl/src/shapes.rs delete mode 100644 atomic-shacl/src/shapes/intent.ttl delete mode 100644 atomic-shacl/src/shapes/memory.ttl delete mode 100644 atomic-shacl/src/shim.rs delete mode 100644 atomic-shacl/tests/differential.rs rename atomic-shacl/SPIKE-FINDINGS.md => docs/shacl-oxirs-spike-findings.md (86%) diff --git a/Cargo.toml b/Cargo.toml index 89f600ad..cf34ea82 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -5,7 +5,6 @@ members = [ "atomic-canonical", "atomic-cli", "atomic-core", - "atomic-shacl", "atomic-config", "atomic-identity", "atomic-remote", @@ -35,17 +34,6 @@ atomic-repository = { path = "atomic-repository" } atomic-semantic = { path = "atomic-semantic" } atomic-teams = { path = "atomic-teams" } -# SHACL — Recording the Why. A real SHACL engine over Turtle shapes. This -# pre-1.0 RDF/SHACL stack (oxirs) pulls a large transitive tree, so it is -# ISOLATED to atomic-shacl only, gated behind that crate's off-by-default -# `oxirs-engine` feature, and must never appear under atomic-canonical (enforced -# by a purity check). Pinned exactly so an oxirs point release cannot silently -# change validation semantics. oxirs-core provides both the RDF model and the -# store, so oxrdf/oxttl are not needed as direct dependencies. -atomic-shacl = { path = "atomic-shacl" } -oxirs-shacl = "=0.3.1" -oxirs-core = "=0.3.1" - # Serialization serde = { version = "1.0", features = ["derive"] } serde_json = "1.0" diff --git a/atomic-shacl/Cargo.toml b/atomic-shacl/Cargo.toml deleted file mode 100644 index 2fda937b..00000000 --- a/atomic-shacl/Cargo.toml +++ /dev/null @@ -1,40 +0,0 @@ -[package] -name = "atomic-shacl" -description = "Recording the Why — a real SHACL engine (oxirs) over Turtle shapes, run in shadow against the hand-coded gate. The pre-1.0 RDF/SHACL stack is gated behind the off-by-default `oxirs-engine` feature and isolated here; atomic-canonical never depends on this crate." -version.workspace = true -edition.workspace = true -authors.workspace = true -license.workspace = true -repository.workspace = true -rust-version.workspace = true - -[dependencies] -# The canonical node types + the Violation/ValidationReport vocab we mirror and -# diff against. The dependency arrow is strictly one-directional: -# atomic-cli -> atomic-shacl -> atomic-canonical. atomic-canonical NEVER depends back. -atomic-canonical = { workspace = true } - -serde = { workspace = true } -serde_json = { workspace = true } -thiserror = { workspace = true } - -# The isolated, pre-1.0 SHACL/RDF stack (oxirs). OPTIONAL and OFF by default: -# only the `oxirs-engine` feature pulls the ~430-crate transitive tree, so -# routine workspace builds and CI never compile it. oxirs-core provides both the -# RDF model (NamedNode/Literal/Quad) and the validation Store (ConcreteStore); -# oxirs-shacl provides the shape loader + validation engine (both synchronous). -oxirs-shacl = { workspace = true, optional = true } -oxirs-core = { workspace = true, optional = true } -# oxirs-shacl's ValidationEngine::new wants an IndexMap<ShapeId, Shape>; matched -# to the version oxirs-shacl itself uses (2.14) to avoid a duplicate indexmap. -indexmap = { version = "2.14", optional = true } - -[features] -default = [] -# Enables the real oxirs SHACL engine and its large transitive dependency tree. -# OFF by default (see the crate description). The differential-corpus tests and -# any real validation require this feature: `cargo test -p atomic-shacl --features oxirs-engine`. -oxirs-engine = ["dep:oxirs-shacl", "dep:oxirs-core", "dep:indexmap"] - -[dev-dependencies] -atomic-identity = { workspace = true } diff --git a/atomic-shacl/src/engine.rs b/atomic-shacl/src/engine.rs deleted file mode 100644 index ef07222b..00000000 --- a/atomic-shacl/src/engine.rs +++ /dev/null @@ -1,238 +0,0 @@ -//! The synchronous SHACL bridge over the pre-1.0 oxirs engine. -//! -//! oxirs's validation path is fully synchronous — `ShapeLoaderBuilder::build` -//! (not just `build_async`), `ValidationEngine::new`, and `validate_store` all -//! run on the calling thread — so no async runtime is needed. This module owns -//! the three primitives the higher layers (shim, shapes, differential corpus) -//! build on: -//! -//! 1. [`load_shapes`] — parse Turtle shape text into oxirs `Shape`s. -//! 2. [`validate`] — run the shapes over an oxirs [`ConcreteStore`]. -//! -//! It is deliberately thin: the JSON-LD→RDF projection (the shim) and the -//! violation→`Violation` mapping live in their own modules so this file stays a -//! faithful, testable wrapper around the raw oxirs API. - -use std::collections::BTreeSet; - -use atomic_canonical::memory::MemoryNode; -use atomic_canonical::node::CanonicalNode; -use indexmap::IndexMap; -use oxirs_core::model::Term; -use oxirs_core::ConcreteStore; -use oxirs_shacl::{Shape, ShapeId, ValidationConfig, ValidationEngine, ValidationReport}; - -use crate::shapes::{INTENT_SHAPES_TTL, MEMORY_SHAPES_TTL}; -use crate::shim::node_to_store; - -/// Errors from the oxirs bridge. Kept small; the differential corpus treats any -/// engine error as "shadow unavailable" and never lets it affect authority. -#[derive(Debug, thiserror::Error)] -pub enum ShaclError { - /// A Turtle shape graph failed to parse / load. - #[error("failed to load SHACL shapes: {0}")] - ShapeLoad(String), - /// The validation run itself failed. - #[error("SHACL validation failed: {0}")] - Validate(String), - /// The RDF store could not be created or populated. - #[error("RDF store error: {0}")] - Store(String), -} - -/// Parse a Turtle shapes graph into oxirs `Shape`s, keyed by `ShapeId` as -/// `ValidationEngine` requires. -/// -/// `strict` maps to oxirs's `strict_mode`: when set, a shape graph the loader -/// cannot fully understand is an error rather than a silently-dropped shape — -/// the fail-closed posture a security gate needs. -pub fn load_shapes(turtle: &str, strict: bool) -> Result<IndexMap<ShapeId, Shape>, ShaclError> { - let shapes = oxirs_shacl::ShapeLoaderBuilder::new() - .from_rdf_data(turtle.to_string(), "turtle".to_string(), None) - .strict_mode(strict) - .build() - .map_err(|e| ShaclError::ShapeLoad(e.to_string()))?; - - Ok(shapes.into_iter().map(|s| (s.id.clone(), s)).collect()) -} - -/// Run `shapes` over `store` and return the raw oxirs report. -pub fn validate( - shapes: &IndexMap<ShapeId, Shape>, - store: &ConcreteStore, -) -> Result<ValidationReport, ShaclError> { - let mut engine = ValidationEngine::new(shapes, ValidationConfig::default()); - engine - .validate_store(store) - .map_err(|e| ShaclError::Validate(e.to_string())) -} - -/// A finding key for differential comparison against the hand-coded gate: -/// `(focus_node_iri, path_short_name)`. The gate produces at most one violation -/// per such pair, so a set of these is the right comparison granularity. -pub type FindingKey = (String, Option<String>); - -/// A SHACL report normalized so it can be diffed against the gate's -/// `ValidationReport`. -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct NormalizedReport { - pub conforms: bool, - /// Order-independent set of `(focus, path)` findings. - pub findings: BTreeSet<FindingKey>, - /// `(focus, path, message)` triples, retained for diagnostics/divergence reports. - pub raw: Vec<(String, Option<String>, String)>, -} - -/// Validate a canonical Intent node through the real SHACL engine. -pub fn validate_intent_shacl(node: &CanonicalNode) -> Result<NormalizedReport, ShaclError> { - let shapes = load_shapes(INTENT_SHAPES_TTL, true)?; - let store = node_to_store(&node.to_value())?; - Ok(normalize(&validate(&shapes, &store)?)) -} - -/// Validate a canonical Memory node through the real SHACL engine. -pub fn validate_memory_shacl(node: &MemoryNode) -> Result<NormalizedReport, ShaclError> { - let shapes = load_shapes(MEMORY_SHAPES_TTL, true)?; - let store = node_to_store(&node.to_value())?; - Ok(normalize(&validate(&shapes, &store)?)) -} - -/// Normalize a raw oxirs report into `(focus, path)` findings. -/// -/// `result_path` is present for Core property constraints (sh:minCount, sh:in); -/// for SHACL-SPARQL constraints it is typically absent, so we recover the gate's -/// path from the (shape-authored) message — the only place the two conditionals' -/// paths (`hasScopeOut`, `acStatus`) are pinned. -pub fn normalize(report: &ValidationReport) -> NormalizedReport { - let mut findings = BTreeSet::new(); - let mut raw = Vec::new(); - for v in report.violations() { - let focus = term_iri(&v.focus_node); - let message = v.result_message.clone().unwrap_or_default(); - let path = match &v.result_path { - Some(p) => Some(short_name(&p.to_string())), - None => path_from_message(&message), - }; - findings.insert((focus.clone(), path.clone())); - raw.push((focus, path, message)); - } - NormalizedReport { - conforms: report.conforms(), - findings, - raw, - } -} - -/// The IRI string of a focus node (no angle brackets), matching the gate's -/// `focus_node` (`node.id` / `ac.id`). -fn term_iri(t: &Term) -> String { - match t { - Term::NamedNode(n) => n.as_str().to_string(), - other => other.to_string().trim_matches(|c| c == '<' || c == '>').to_string(), - } -} - -/// The local name of an IRI (everything after the last `#` or `/`). -fn short_name(iri: &str) -> String { - iri.rsplit(['#', '/']).next().unwrap_or(iri).to_string() -} - -/// Recover the gate's path for a SHACL-SPARQL constraint from its message. -fn path_from_message(message: &str) -> Option<String> { - if message.contains("out of scope") { - Some("hasScopeOut".to_string()) - } else if message.contains("verifiedBy and evidence") { - Some("acStatus".to_string()) - } else { - None - } -} - -#[cfg(test)] -mod smoke { - //! Physical proof (M1) that the real oxirs 0.3.1 API works end-to-end in our - //! toolchain: parse a Turtle NodeShape, build a store, validate, and read the - //! report both ways (violating and conforming). - - use super::*; - use oxirs_core::model::{Literal, NamedNode, Quad}; - - const SHAPE_TTL: &str = r#" -@prefix sh: <http://www.w3.org/ns/shacl#> . -@prefix ex: <http://example.org/> . -@prefix xsd: <http://www.w3.org/2001/XMLSchema#> . - -ex:ThingShape a sh:NodeShape ; - sh:targetClass ex:Thing ; - sh:property [ - sh:path ex:name ; - sh:minCount 1 ; - sh:datatype xsd:string ; - ] . -"#; - - fn thing_typed_quad() -> Quad { - Quad::new( - NamedNode::new("http://example.org/t1").unwrap(), - NamedNode::new("http://www.w3.org/1999/02/22-rdf-syntax-ns#type").unwrap(), - NamedNode::new("http://example.org/Thing").unwrap(), - oxirs_core::model::GraphName::DefaultGraph, - ) - } - - #[test] - fn oxirs_flags_missing_required_property() { - let shapes = load_shapes(SHAPE_TTL, true).expect("shapes load"); - let store = ConcreteStore::new().expect("store"); - // An ex:Thing with NO ex:name violates sh:minCount 1. - store.insert_quad(thing_typed_quad()).expect("insert"); - - let report = validate(&shapes, &store).expect("validate"); - assert!( - !report.conforms(), - "a Thing missing its required ex:name must not conform" - ); - assert!( - !report.violations().is_empty(), - "the missing-property violation must be reported" - ); - } - - #[test] - fn real_intent_and_memory_shapes_load_under_strict_mode() { - // M2/M4 gate: our real shapes exercise sh:in, sh:node, and sh:sparql. - // If oxirs's strict loader rejects any of these, load fails here and the - // whole approach is blocked — so this is the earliest hard checkpoint. - let intent = load_shapes(crate::shapes::INTENT_SHAPES_TTL, true) - .expect("intent shapes must load under strict mode"); - assert!( - !intent.is_empty(), - "intent shape graph produced no shapes (sh:in/sh:node/sh:sparql may not parse)" - ); - let memory = load_shapes(crate::shapes::MEMORY_SHAPES_TTL, true) - .expect("memory shapes must load under strict mode"); - assert!(!memory.is_empty(), "memory shape graph produced no shapes"); - } - - #[test] - fn oxirs_passes_when_required_property_present() { - let shapes = load_shapes(SHAPE_TTL, true).expect("shapes load"); - let store = ConcreteStore::new().expect("store"); - store.insert_quad(thing_typed_quad()).expect("insert type"); - store - .insert_quad(Quad::new( - NamedNode::new("http://example.org/t1").unwrap(), - NamedNode::new("http://example.org/name").unwrap(), - Literal::new_simple_literal("hello"), - oxirs_core::model::GraphName::DefaultGraph, - )) - .expect("insert name"); - - let report = validate(&shapes, &store).expect("validate"); - assert!( - report.conforms(), - "a Thing with its required ex:name present must conform (got {:?})", - report.violations() - ); - } -} diff --git a/atomic-shacl/src/lib.rs b/atomic-shacl/src/lib.rs deleted file mode 100644 index 866e7ff3..00000000 --- a/atomic-shacl/src/lib.rs +++ /dev/null @@ -1,22 +0,0 @@ -//! Recording the Why — a real SHACL engine over Turtle shapes, run in **shadow**. -//! -//! This crate wraps the pre-1.0 `oxirs-shacl` engine and validates canonical -//! Intent/Memory nodes against real Turtle shapes. During the spike it is -//! **non-authoritative**: nothing here gates a signature or a persist. Its job -//! is to answer, measurably, "can oxirs reproduce the hand-coded gate?" via a -//! differential corpus (see `tests/`). -//! -//! ## Isolation charter -//! The oxirs stack (a large, pre-1.0 transitive tree) lives behind the -//! off-by-default `oxirs-engine` feature and is named ONLY in this crate. -//! `atomic-canonical` stays pure and sync and never depends on this crate. -//! Enforced by a CI purity check. - -#![forbid(unsafe_code)] - -#[cfg(feature = "oxirs-engine")] -pub mod engine; -#[cfg(feature = "oxirs-engine")] -pub mod shapes; -#[cfg(feature = "oxirs-engine")] -pub mod shim; diff --git a/atomic-shacl/src/shapes.rs b/atomic-shacl/src/shapes.rs deleted file mode 100644 index 1621dfff..00000000 --- a/atomic-shacl/src/shapes.rs +++ /dev/null @@ -1,13 +0,0 @@ -//! The embedded Turtle shape graphs. -//! -//! The `.ttl` files under `src/shapes/` are the team-editable, standard-SHACL -//! source of truth for Intent/Memory policy. They are compiled into the binary -//! here via `include_str!` — the compiled bytes are the trusted artifact that -//! actually runs, while the on-disk file stays the reviewable/diffable source -//! (and remains loadable by any external SHACL validator). - -/// IntentShape + AcceptanceCriterionShape (Core rules + the two SHACL-SPARQL conditionals). -pub const INTENT_SHAPES_TTL: &str = include_str!("shapes/intent.ttl"); - -/// MemoryShape (Core rules; the directionality absence is structural — no forward-edge rule). -pub const MEMORY_SHAPES_TTL: &str = include_str!("shapes/memory.ttl"); diff --git a/atomic-shacl/src/shapes/intent.ttl b/atomic-shacl/src/shapes/intent.ttl deleted file mode 100644 index 53e20403..00000000 --- a/atomic-shacl/src/shapes/intent.ttl +++ /dev/null @@ -1,88 +0,0 @@ -# IntentShape — the SHACL rendering of the hand-coded gate's `validate_intent`. -# -# This is the team-editable, standard-SHACL source of truth for intent policy. -# It is compiled into the binary via include_str! (the compiled bytes are the -# trusted artifact) but stays valid Turtle that any real SHACL validator can load. -# -# Trim semantics (load-bearing): the hand-coded gate rejects a WHITESPACE-ONLY -# `why` (it uses .trim()) but accepts a whitespace-only `attributedTo` (no trim). -# The shim reproduces this by emitting the a:why triple ONLY when the trimmed -# value is non-empty, and the a:attributedTo triple whenever the raw value is -# non-empty. So both rules below are plain sh:minCount 1 — the asymmetry lives in -# the shim (and is pinned by the differential corpus), not in these shapes. - -@prefix sh: <http://www.w3.org/ns/shacl#> . -@prefix a: <https://atomic.dev/ns#> . - -a:IntentShape a sh:NodeShape ; - sh:targetClass a:Intent ; - - # status ∈ closed set (single field ⇒ exactly one). - sh:property [ - sh:path a:status ; - sh:minCount 1 ; - sh:in ( "backlog" "todo" "in_progress" "done" ) ; - sh:message "status is not one of backlog/todo/in_progress/done" ; - ] ; - - # author present (shim emits iff raw value non-empty — untrimmed, matching the gate). - sh:property [ - sh:path a:attributedTo ; - sh:minCount 1 ; - sh:message "author (attributedTo) must be present as a DID" ; - ] ; - - # Data Integrity proof present. - sh:property [ - sh:path a:proof ; - sh:minCount 1 ; - sh:message "intent must carry a Data Integrity proof" ; - ] ; - - # reason present (shim emits iff trimmed value non-empty — content never graded). - sh:property [ - sh:path a:why ; - sh:minCount 1 ; - sh:message "a reason (why) must be present — its content is not graded" ; - ] ; - - # each acceptance criterion must satisfy AcceptanceCriterionShape. - sh:property [ - sh:path a:hasAcceptanceCriterion ; - sh:node a:AcceptanceCriterionShape ; - ] ; - - # INTENT-5 (conditional, SHACL-SPARQL): if scope-in is declared, scope-out must be too. - sh:sparql [ - a sh:SPARQLConstraint ; - sh:message "a scope declaration must state what is out of scope (the boundaries the agent must respect)" ; - sh:select """ - SELECT $this WHERE { - $this <https://atomic.dev/ns#hasScopeIn> ?in . - FILTER NOT EXISTS { $this <https://atomic.dev/ns#hasScopeOut> ?out . } - } - """ ; - ] . - -a:AcceptanceCriterionShape a sh:NodeShape ; - - # acStatus ∈ closed set. - sh:property [ - sh:path a:acStatus ; - sh:minCount 1 ; - sh:in ( "open" "met" ) ; - sh:message "acStatus is not one of open/met" ; - ] ; - - # INTENT-7 (conditional, SHACL-SPARQL): a met criterion must carry verifiedBy AND evidence. - sh:sparql [ - a sh:SPARQLConstraint ; - sh:message "a met acceptance criterion must carry verifiedBy and evidence" ; - sh:select """ - SELECT $this WHERE { - $this <https://atomic.dev/ns#acStatus> "met" . - FILTER ( NOT EXISTS { $this <https://atomic.dev/ns#verifiedBy> ?v } || - NOT EXISTS { $this <https://atomic.dev/ns#evidence> ?e } ) - } - """ ; - ] . diff --git a/atomic-shacl/src/shapes/memory.ttl b/atomic-shacl/src/shapes/memory.ttl deleted file mode 100644 index 4344ce56..00000000 --- a/atomic-shacl/src/shapes/memory.ttl +++ /dev/null @@ -1,56 +0,0 @@ -# MemoryShape — the SHACL rendering of the hand-coded gate's `validate_memory`. -# -# Standard SHACL; compiled in via include_str! but loadable by any real validator. -# -# Directionality (load-bearing ABSENCE): there is deliberately NO forward-edge -# rule (no "status = superseded ⇒ supersedes present"). supersedes/previousRevision -# are BACKWARD edges only; a retired memory gains no new edge. Adding a forward-edge -# property shape here would re-introduce the "references its future uses" anti-pattern -# and MUST fail the differential corpus's superseded-no-forward-edge anti-fixture. -# -# Trim semantics: `text` presence is enforced by the shim emitting the a:text triple -# ONLY when the trimmed value is non-empty (matching the gate's .trim()); the rule -# below is therefore plain sh:minCount 1. - -@prefix sh: <http://www.w3.org/ns/shacl#> . -@prefix a: <https://atomic.dev/ns#> . - -a:MemoryShape a sh:NodeShape ; - sh:targetClass a:Memory ; - - # memoryKind ∈ closed set (single field ⇒ exactly one). - sh:property [ - sh:path a:memoryKind ; - sh:minCount 1 ; - sh:in ( "constraint" "preference" "lesson" "context" ) ; - sh:message "memoryKind is not one of constraint/preference/lesson/context" ; - ] ; - - # status ∈ closed set. - sh:property [ - sh:path a:status ; - sh:minCount 1 ; - sh:in ( "active" "superseded" "retracted" ) ; - sh:message "status is not one of active/superseded/retracted" ; - ] ; - - # author present (shim emits iff raw value non-empty — untrimmed, matching the gate). - sh:property [ - sh:path a:attributedTo ; - sh:minCount 1 ; - sh:message "author (attributedTo) must be present as a DID" ; - ] ; - - # Data Integrity proof present. - sh:property [ - sh:path a:proof ; - sh:minCount 1 ; - sh:message "memory must carry a Data Integrity proof" ; - ] ; - - # text present (shim emits iff trimmed value non-empty — content never graded). - sh:property [ - sh:path a:text ; - sh:minCount 1 ; - sh:message "a memory must carry text — its content is not graded" ; - ] . diff --git a/atomic-shacl/src/shim.rs b/atomic-shacl/src/shim.rs deleted file mode 100644 index e4588627..00000000 --- a/atomic-shacl/src/shim.rs +++ /dev/null @@ -1,250 +0,0 @@ -//! The deterministic JSON-LD → RDF projection (the "shim"). -//! -//! SHACL validates RDF, so a canonical node's JSON-LD value must first become -//! triples. The single most important correctness surface here is faithfully -//! reproducing the hand-coded gate's presence semantics — including its -//! deliberate **trim asymmetry**: -//! -//! * `why` / `text` are rejected when WHITESPACE-ONLY (the gate uses `.trim()`), -//! so the shim emits their triple only when the trimmed value is non-empty. -//! * `attributedTo` / `verifiedBy` / `evidence` are accepted when whitespace-only -//! (the gate uses `.unwrap_or("").is_empty()` — no trim), so the shim emits -//! their triple whenever the raw value is non-empty (present-empty `""` and an -//! omitted key both project to nothing — matching the gate). -//! -//! Everything else (closed-set values like `status`/`memoryKind`/`acStatus`) is -//! projected verbatim so `sh:in` can match. Nested typed sub-nodes -//! (`hasAcceptanceCriterion`, `hasScopeIn/Out`, …) become edges to child subjects -//! keyed on the child's `@id`, so `verifiedBy`/`evidence` land on the AC child — -//! not the parent — exactly where the AcceptanceCriterionShape looks for them. - -use oxirs_core::model::{GraphName, Literal, NamedNode, Quad}; -use oxirs_core::ConcreteStore; -use serde_json::{Map, Value}; - -use crate::engine::ShaclError; - -/// The Atomic vocabulary namespace. Every JSON-LD short key `k` projects to the -/// IRI `NS + k`, and every `@type` value `T` projects to the class IRI `NS + T`. -/// This is the term→IRI table the shapes target; keeping it a single constant is -/// what lets shim and shapes agree. -pub const NS: &str = "https://atomic.dev/ns#"; - -const RDF_TYPE: &str = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type"; - -/// Build an RDF store from a canonical node's JSON-LD value. -pub fn node_to_store(node: &Value) -> Result<ConcreteStore, ShaclError> { - let store = ConcreteStore::new().map_err(|e| ShaclError::Store(e.to_string()))?; - for quad in node_to_quads(node)? { - store - .insert_quad(quad) - .map_err(|e| ShaclError::Store(e.to_string()))?; - } - Ok(store) -} - -/// Project a canonical node's JSON-LD value into a deterministic set of quads. -/// Pure (no store), so the projection can be unit-tested quad-for-quad. -pub fn node_to_quads(node: &Value) -> Result<Vec<Quad>, ShaclError> { - let obj = node - .as_object() - .ok_or_else(|| ShaclError::Store("node is not a JSON object".into()))?; - let mut quads = Vec::new(); - add_node(obj, &mut quads)?; - Ok(quads) -} - -/// Whether a string field is projected, given the gate's per-field semantics. -/// Exposed so the differential corpus can assert the asymmetry directly. -pub fn should_emit(key: &str, value: &str) -> bool { - match key { - // Trimmed presence (whitespace-only is absent). - "why" | "text" => !value.trim().is_empty(), - // Untrimmed presence (whitespace-only counts as present). - "attributedTo" | "verifiedBy" | "evidence" => !value.is_empty(), - // Closed-set / other scalars: project verbatim (empty is harmless — no - // rule references these except via sh:in, which an empty value fails). - _ => true, - } -} - -fn iri(s: &str) -> Result<NamedNode, ShaclError> { - NamedNode::new(s).map_err(|e| ShaclError::Store(format!("invalid IRI {s:?}: {e}"))) -} - -fn subject_of(obj: &Map<String, Value>) -> Result<NamedNode, ShaclError> { - let id = obj - .get("@id") - .and_then(Value::as_str) - .ok_or_else(|| ShaclError::Store("node/sub-node missing @id".into()))?; - iri(id) -} - -/// Emit all triples for one node (or sub-node), recursing into typed children. -fn add_node(obj: &Map<String, Value>, quads: &mut Vec<Quad>) -> Result<(), ShaclError> { - let subject = subject_of(obj)?; - - // @type -> rdf:type -> the class IRI (so sh:targetClass / sh:node match). - if let Some(t) = obj.get("@type").and_then(Value::as_str) { - quads.push(Quad::new( - subject.clone(), - iri(RDF_TYPE)?, - iri(&format!("{NS}{t}"))?, - GraphName::DefaultGraph, - )); - } - - for (key, val) in obj { - if key == "@context" || key == "@id" || key == "@type" { - continue; - } - let pred = iri(&format!("{NS}{key}"))?; - - match val { - // A present proof (object) projects to a single presence triple; an - // absent proof projects to nothing, so sh:minCount 1 fires. - Value::Object(_) if key == "proof" => { - quads.push(Quad::new( - subject.clone(), - pred, - Literal::new_simple_literal("present"), - GraphName::DefaultGraph, - )); - } - Value::String(s) => { - if should_emit(key, s) { - quads.push(Quad::new( - subject.clone(), - pred, - Literal::new_simple_literal(s.as_str()), - GraphName::DefaultGraph, - )); - } - } - Value::Array(items) => { - for item in items { - match item { - Value::String(s) => { - quads.push(Quad::new( - subject.clone(), - pred.clone(), - Literal::new_simple_literal(s.as_str()), - GraphName::DefaultGraph, - )); - } - // A typed sub-node: edge to the child @id, then recurse so - // the child's own fields (acStatus/verifiedBy/evidence, …) - // land on the CHILD subject. - Value::Object(child) if child.contains_key("@id") => { - quads.push(Quad::new( - subject.clone(), - pred.clone(), - subject_of(child)?, - GraphName::DefaultGraph, - )); - add_node(child, quads)?; - } - // Objects without an @id (e.g. a bare dependsOn Ref) are - // ungated; skip them rather than mint a synthetic subject. - _ => {} - } - } - } - // Numbers/bools/null: none of our gated fields use them. Skip. - _ => {} - } - } - - Ok(()) -} - -#[cfg(test)] -mod tests { - use super::*; - use serde_json::json; - - /// Render quads to sorted "S P O" strings for order-independent assertions. - fn triples(node: &Value) -> Vec<String> { - let mut out: Vec<String> = node_to_quads(node) - .expect("project") - .iter() - .map(|q| { - format!( - "{} {} {}", - q.subject(), - q.predicate(), - q.object() - ) - }) - .collect(); - out.sort(); - out - } - - fn has(node: &Value, needle: &str) -> bool { - triples(node).iter().any(|t| t.contains(needle)) - } - - #[test] - fn trim_asymmetry_why_whitespace_only_is_absent() { - // why is whitespace-only -> NOT projected (gate rejects it). - let n = json!({"@id":"urn:i:1","@type":"Intent","why":" ","status":"todo"}); - assert!(!has(&n, "#why"), "whitespace-only why must not be projected"); - // a real why IS projected. - let n2 = json!({"@id":"urn:i:1","@type":"Intent","why":"because","status":"todo"}); - assert!(has(&n2, "#why"), "a real why must be projected"); - } - - #[test] - fn trim_asymmetry_attributed_to_whitespace_only_is_present() { - // attributedTo whitespace-only -> IS projected (gate accepts it, no trim). - let n = json!({"@id":"urn:i:1","@type":"Intent","attributedTo":" "}); - assert!( - has(&n, "#attributedTo"), - "whitespace-only attributedTo must be projected (untrimmed)" - ); - // present-empty "" -> NOT projected (matches .is_empty()). - let n2 = json!({"@id":"urn:i:1","@type":"Intent","attributedTo":""}); - assert!( - !has(&n2, "#attributedTo"), - "empty attributedTo must project to nothing" - ); - } - - #[test] - fn proof_presence_projects_one_triple_when_present_none_when_absent() { - let present = json!({"@id":"urn:i:1","@type":"Intent","proof":{"proofValue":"z1"}}); - assert!(has(&present, "#proof"), "present proof must project a triple"); - let absent = json!({"@id":"urn:i:1","@type":"Intent"}); - assert!(!has(&absent, "#proof"), "absent proof projects nothing"); - } - - #[test] - fn ac_child_fields_land_on_the_child_subject_not_the_parent() { - let n = json!({ - "@id":"urn:i:1","@type":"Intent", - "hasAcceptanceCriterion":[{ - "@id":"urn:ac:1","@type":"AcceptanceCriterion", - "text":"t","acStatus":"met","verifiedBy":"lee","evidence":"pr#1" - }] - }); - let ts = triples(&n); - // parent -> child edge - assert!(ts.iter().any(|t| t.contains("urn:i:1") - && t.contains("#hasAcceptanceCriterion") - && t.contains("urn:ac:1"))); - // verifiedBy/evidence/acStatus are on the CHILD subject - assert!(ts.iter().any(|t| t.starts_with("<urn:ac:1>") && t.contains("#verifiedBy"))); - assert!(ts.iter().any(|t| t.starts_with("<urn:ac:1>") && t.contains("#evidence"))); - assert!(ts.iter().any(|t| t.starts_with("<urn:ac:1>") && t.contains("#acStatus"))); - // and NOT on the parent - assert!(!ts.iter().any(|t| t.starts_with("<urn:i:1>") && t.contains("#verifiedBy"))); - } - - #[test] - fn omitted_empty_collections_project_no_edges() { - let n = json!({"@id":"urn:i:1","@type":"Intent","status":"todo"}); - assert!(!has(&n, "#hasScopeIn")); - assert!(!has(&n, "#hasAcceptanceCriterion")); - } -} diff --git a/atomic-shacl/tests/differential.rs b/atomic-shacl/tests/differential.rs deleted file mode 100644 index ddfb3778..00000000 --- a/atomic-shacl/tests/differential.rs +++ /dev/null @@ -1,277 +0,0 @@ -//! The adversarial differential corpus — the spike's actual deliverable. -//! -//! For each fixture we run the trusted hand-coded gate (the oracle) AND the real -//! oxirs SHACL path over the SAME node, and compare `conforms` + the set of -//! `(focus_node, path)` findings. The corpus targets the verified divergence -//! traps (trim asymmetry, present-empty vs omitted, nested AC via sh:node, the -//! two SHACL-SPARQL conditionals, the superseded-no-forward-edge anti-fixture). -//! -//! This file compiles only with `--features oxirs-engine`. -#![cfg(feature = "oxirs-engine")] - -use std::collections::BTreeSet; - -use atomic_canonical::gate::{validate_intent, validate_memory, ValidationReport}; -use atomic_canonical::memory::MemoryNode; -use atomic_canonical::node::{AcceptanceCriterion, CanonicalNode, Proof, ScopeItem, CONTEXT_URL}; -use atomic_shacl::engine::{validate_intent_shacl, validate_memory_shacl, FindingKey}; - -// ---------- fixture builders (dummy proof: the gate only checks presence) ---------- - -fn dummy_proof() -> Proof { - Proof { - type_: "DataIntegrityProof".into(), - cryptosuite: "eddsa-jcs-2022".into(), - verification_method: "did:atomic:x#k".into(), - proof_purpose: "assertionMethod".into(), - proof_value: "zStub".into(), - } -} - -fn base_intent() -> CanonicalNode { - CanonicalNode { - context: CONTEXT_URL.into(), - type_: "Intent".into(), - id: "urn:atomic:intent:c".into(), - human_key: "C-1".into(), - title: "t".into(), - status: "todo".into(), - priority: None, - view: None, - motivated_by: None, - informed_by: vec![], - has_acceptance_criterion: vec![], - has_task: vec![], - has_scope_in: vec![], - has_scope_out: vec![], - has_constraint: vec![], - depends_on: vec![], - why: Some("a reason".into()), - content_hash: None, - attributed_to: Some("did:atomic:lee".into()), - created_at: "2026-06-25T00:00:00Z".into(), - proof: Some(dummy_proof()), - } -} - -fn ac(id: &str, status: &str, vby: Option<&str>, ev: Option<&str>) -> AcceptanceCriterion { - AcceptanceCriterion { - type_: "AcceptanceCriterion".into(), - id: id.into(), - text: "t".into(), - ac_status: status.into(), - verified_by: vby.map(Into::into), - evidence: ev.map(Into::into), - } -} - -fn scope(id: &str) -> ScopeItem { - ScopeItem { - type_: "ScopeItem".into(), - id: id.into(), - text: "s".into(), - } -} - -fn base_memory() -> MemoryNode { - MemoryNode { - context: CONTEXT_URL.into(), - type_: "Memory".into(), - id: "urn:atomic:memory:c".into(), - memory_kind: "constraint".into(), - text: "a durable constraint".into(), - about: vec![], - status: "active".into(), - supersedes: None, - previous_revision: None, - content_hash: None, - attributed_to: Some("did:atomic:lee".into()), - created_at: "2026-05-02T09:14:00Z".into(), - proof: Some(dummy_proof()), - } -} - -// ---------- normalization of the gate's report to the same key space ---------- - -fn gate_keys(report: &ValidationReport) -> BTreeSet<FindingKey> { - report - .results - .iter() - .map(|v| (v.focus_node.clone(), v.path.clone())) - .collect() -} - -fn shacl_conforms_intent(node: &CanonicalNode) -> bool { - validate_intent_shacl(node).expect("shacl intent").conforms -} -fn shacl_conforms_memory(node: &MemoryNode) -> bool { - validate_memory_shacl(node).expect("shacl memory").conforms -} - -// ============================================================================ -// WHAT WORKS: Core presence (sh:minCount) + closed-set (sh:in) rules. -// oxirs 0.3.1 reproduces the gate's `conforms` verdict on every one of these, -// INCLUDING the trim asymmetry and the load-bearing directionality ABSENCE. -// ============================================================================ - -#[test] -fn core_presence_and_closed_set_rules_match_gate_on_conformance() { - // (label, mutate, ) — each asserts gate.conforms == shacl.conforms. - let mut cases: Vec<(&str, CanonicalNode)> = Vec::new(); - - cases.push(("baseline conforms", base_intent())); - - let mut n = base_intent(); - n.status = "shipped".into(); - cases.push(("unknown status rejected", n)); - - let mut n = base_intent(); - n.status = String::new(); - cases.push(("empty status rejected", n)); - - // Trim asymmetry: whitespace-only why is REJECTED (gate .trim()). - let mut n = base_intent(); - n.why = Some(" ".into()); - cases.push(("whitespace-only why rejected", n)); - - let mut n = base_intent(); - n.why = None; - cases.push(("missing why rejected", n)); - - // Trim asymmetry: whitespace-only attributedTo is ACCEPTED (gate no trim). - let mut n = base_intent(); - n.attributed_to = Some(" ".into()); - cases.push(("whitespace-only attributedTo accepted", n)); - - // present-empty attributedTo is rejected (== omitted). - let mut n = base_intent(); - n.attributed_to = Some(String::new()); - cases.push(("present-empty attributedTo rejected", n)); - - let mut n = base_intent(); - n.attributed_to = None; - n.proof = None; - cases.push(("unattested rejected", n)); - - for (label, node) in &cases { - let gate = validate_intent(node).conforms; - let shacl = shacl_conforms_intent(node); - assert_eq!( - gate, shacl, - "INTENT conformance divergence on '{label}': gate={gate} shacl={shacl}" - ); - // Where non-conforming, the focus node must at least match. - if !gate { - let g = gate_keys(&validate_intent(node)); - let s = &validate_intent_shacl(node).unwrap().findings; - let g_focus: BTreeSet<_> = g.iter().map(|(f, _)| f.clone()).collect(); - let s_focus: BTreeSet<_> = s.iter().map(|(f, _)| f.clone()).collect(); - assert_eq!(g_focus, s_focus, "INTENT focus-node divergence on '{label}'"); - } - } - - // Memory Core rules + the directionality ABSENCE anti-fixture. - let mut m_cases: Vec<(&str, MemoryNode)> = Vec::new(); - m_cases.push(("baseline conforms", base_memory())); - let mut m = base_memory(); - m.memory_kind = "architecture".into(); - m_cases.push(("unknown memoryKind rejected", m)); - let mut m = base_memory(); - m.status = "archived".into(); - m_cases.push(("unknown status rejected", m)); - let mut m = base_memory(); - m.text = " ".into(); - m_cases.push(("whitespace-only text rejected", m)); - let mut m = base_memory(); - m.attributed_to = None; - m.proof = None; - m.text = " ".into(); - m_cases.push(("bare memory rejected", m)); - // ANTI-FIXTURE (directionality): a retired memory with no forward edge conforms. - let mut m = base_memory(); - m.status = "superseded".into(); - m.supersedes = None; - m.previous_revision = None; - m_cases.push(("superseded no-forward-edge conforms", m)); - - for (label, node) in &m_cases { - let gate = validate_memory(node).conforms; - let shacl = shacl_conforms_memory(node); - assert_eq!( - gate, shacl, - "MEMORY conformance divergence on '{label}': gate={gate} shacl={shacl}" - ); - } -} - -// ============================================================================ -// CONFIRMED BLOCKERS: rules oxirs 0.3.1 SILENTLY DOES NOT ENFORCE. -// Each asserts the gate REJECTS but SHACL wrongly CONFORMS — a signing-path -// false-negative. These tests PASS today (they lock in the defect). If a future -// oxirs release fixes the construct, the corresponding assert flips and the test -// FAILS, signalling "re-evaluate: this rule can now be promoted." -// ============================================================================ - -#[test] -fn blocker_sh_node_nested_acceptance_criterion_not_enforced() { - // AC with an unknown acStatus: gate rejects, oxirs ignores sh:node → conforms. - let mut n = base_intent(); - n.has_acceptance_criterion = vec![ac("urn:atomic:ac:1", "not-a-status", None, None)]; - assert!(!validate_intent(&n).conforms, "gate must reject unknown acStatus"); - assert!( - shacl_conforms_intent(&n), - "BLOCKER FIXED? oxirs now enforces sh:node nested AC validation — re-evaluate" - ); -} - -#[test] -fn blocker_sparql_intent5_scope_in_implies_scope_out_not_enforced() { - let mut n = base_intent(); - n.has_scope_in = vec![scope("urn:atomic:scope:in1")]; - // no scope-out - assert!( - !validate_intent(&n).conforms, - "gate must reject scope-in without scope-out" - ); - assert!( - shacl_conforms_intent(&n), - "BLOCKER FIXED? oxirs now enforces sh:sparql INTENT-5 — re-evaluate" - ); -} - -#[test] -fn blocker_sparql_intent7_met_ac_requires_evidence_not_enforced() { - let mut n = base_intent(); - n.has_acceptance_criterion = vec![ac("urn:atomic:ac:1", "met", None, None)]; - assert!( - !validate_intent(&n).conforms, - "gate must reject a met AC without evidence" - ); - assert!( - shacl_conforms_intent(&n), - "BLOCKER FIXED? oxirs now enforces sh:sparql INTENT-7 — re-evaluate" - ); -} - -#[test] -fn fidelity_gap_oxirs_leaves_result_path_unpopulated() { - // The gate names the failing property; oxirs 0.3.1 reports result_path=None, - // so distinct violations on one node collapse and cannot be mapped 1:1. - let mut n = base_intent(); - n.attributed_to = None; - n.proof = None; - let shacl = validate_intent_shacl(&n).expect("shacl"); - assert!(!shacl.conforms); - assert!( - shacl.findings.iter().all(|(_, path)| path.is_none()), - "BLOCKER FIXED? oxirs now populates result_path — path mapping can tighten" - ); - // Two distinct gate violations (attributedTo, proof) collapse to one SHACL key. - let gate = gate_keys(&validate_intent(&n)); - assert_eq!(gate.len(), 2, "gate distinguishes attributedTo vs proof"); - assert_eq!( - shacl.findings.len(), - 1, - "oxirs collapses both missing-property violations into one (focus, None) key" - ); -} diff --git a/atomic-shacl/SPIKE-FINDINGS.md b/docs/shacl-oxirs-spike-findings.md similarity index 86% rename from atomic-shacl/SPIKE-FINDINGS.md rename to docs/shacl-oxirs-spike-findings.md index 7b657b9d..35e5a827 100644 --- a/atomic-shacl/SPIKE-FINDINGS.md +++ b/docs/shacl-oxirs-spike-findings.md @@ -1,5 +1,14 @@ # SHACL engine spike — findings (oxirs-shacl 0.3.1) +> **STATUS (2026-07-06): the `atomic-shacl` spike crate has been removed.** +> Decision (Lee, owner): SHACL validation runs as a **Circuit Breaker (CB) +> workflow**, not built into `atomic`. So no SHACL engine ships in the atomic +> binary. This document is retained as the record of *why* oxirs (and, more +> broadly, an in-atomic engine) was rejected: the ~432-crate footprint, the +> silently-dropped `sh:node`/`sh:sparql`, and the pre-1.0 maturity. atomic keeps +> the fast hand-coded tier-1 gate, emits canonical JSON-LD, and ships the shape +> `.ttl` as data for CB to validate against. + **Question:** can a real SHACL engine (`oxirs-shacl`) over real Turtle shapes reproduce the hand-coded gate (`atomic-canonical/src/gate.rs`), so intent/memory policy becomes team-editable data? From 623c7d3d74c8c98b03491603bc110de503171d80 Mon Sep 17 00:00:00 2001 From: Vincent <wenxuan.blockchain@gmail.com> Date: Thu, 2 Jul 2026 08:44:46 -0400 Subject: [PATCH 13/21] feat(canonical): inline directive form :name[label]{attrs} MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Completes the third directive form from Recording the Why. Inline directives are recognized inside container prose and surface as children of the container while the prose keeps the mention verbatim (store the edge, render resolves it). Recognition is word-boundary + label-bracket + registry gated, so DIDs, URNs, and unregistered colon-patterns in a reason stay prose instead of erroring — prose remains the unconstrained slot. Inline and nested-leaf :ref children lift onto the intent's dependency chain with the same to/edge validation as :::ref. --- atomic-canonical/src/directive.rs | 149 +++++++++++++++++++++++++++++- atomic-canonical/src/lift.rs | 26 ++++++ atomic-canonical/src/vocab.rs | 15 +++ 3 files changed, 186 insertions(+), 4 deletions(-) diff --git a/atomic-canonical/src/directive.rs b/atomic-canonical/src/directive.rs index 57a9b21b..6219ce22 100644 --- a/atomic-canonical/src/directive.rs +++ b/atomic-canonical/src/directive.rs @@ -2,11 +2,17 @@ //! //! The body's typed structure is explicit and local: the lift reads a node's //! type off the directive name, never off heading position (the fragile -//! "positional lift" the doc rejects). M0 supports: +//! "positional lift" the doc rejects). All three directive forms are supported: //! - container: `:::name{#id key=value ...}` … prose … `:::` //! - leaf: `::name{key=value ...}` (edges only, no body) +//! - inline: `:name[label]{key=value ...}` (names a node inside prose) //! -//! Inline directives are deferred (not needed for the Intent slice). +//! Inline directives are recognized *inside container prose* and surface as +//! children of the container while the prose keeps them verbatim — the graph +//! stores the edge, the render resolves it (reference, don't embed). Because +//! prose is the unconstrained slot, an inline pattern whose name is not in +//! [`vocab::INLINE_DIRECTIVE_NAMES`] stays prose instead of erroring (a reason +//! mentioning `did:atomic:lee` or `foo:bar[0]` must never fail the lift). use std::collections::BTreeMap; @@ -21,7 +27,9 @@ pub struct Directive { pub attrs: BTreeMap<String, String>, /// Prose inside a container directive (trimmed). Empty for leaf directives. pub body: String, - /// Leaf directives nested inside this container (e.g. `::file-ref`). + /// The `[label]` of an inline directive. `None` for container/leaf forms. + pub label: Option<String>, + /// Leaf and inline directives nested inside this container. pub children: Vec<Directive>, } @@ -77,11 +85,16 @@ pub fn parse(body: &str) -> Result<Vec<Directive>> { "unterminated container directive ':::{name}' (missing closing ':::')" ))); } + let body = body_lines.join("\n").trim().to_string(); + // Inline directives inside the prose surface as children; the + // prose keeps them verbatim (store the edge, render resolves it). + children.extend(parse_inline(&body)?); out.push(Directive { name, id, attrs, - body: body_lines.join("\n").trim().to_string(), + body, + label: None, children, }); } else if trimmed.starts_with("::") { @@ -112,10 +125,87 @@ fn parse_leaf(line: &str) -> Result<Option<Directive>> { id, attrs, body: String::new(), + label: None, children: Vec::new(), })) } +/// Extract inline directives (`:name[label]{attrs}`) from running prose. +/// +/// Recognition rules keep prose safe: +/// - the `:` must sit at a word boundary (start of text, or after a +/// non-alphanumeric character) — so `did:atomic:lee` never matches; +/// - the name must be immediately followed by `[label]` — a bare `:word` +/// is prose; +/// - the name must be in the inline registry — `:unknown[x]` stays prose, +/// because prose is the unconstrained slot. +pub fn parse_inline(text: &str) -> Result<Vec<Directive>> { + let bytes = text.as_bytes(); + let mut out = Vec::new(); + let mut i = 0; + while i < bytes.len() { + if bytes[i] != b':' { + i += 1; + continue; + } + // Word boundary: previous byte must not be alphanumeric or ':' (which + // would make this the tail of a URN/DID or a block-directive marker). + if i > 0 { + let prev = bytes[i - 1] as char; + if prev.is_ascii_alphanumeric() || prev == ':' { + i += 1; + continue; + } + } + // Read the name: [a-z0-9-]+ immediately after ':'. + let name_start = i + 1; + let mut j = name_start; + while j < bytes.len() && (bytes[j].is_ascii_alphanumeric() || bytes[j] == b'-') { + j += 1; + } + if j == name_start || j >= bytes.len() || bytes[j] != b'[' { + i += 1; + continue; + } + let name = &text[name_start..j]; + if !vocab::is_known_inline_directive(name) { + i += 1; + continue; + } + // Label: up to the matching ']' (no nesting in labels). + let label_start = j + 1; + let Some(label_len) = text[label_start..].find(']') else { + return Err(CanonicalError::Directive(format!( + "unterminated inline directive ':{name}[' (missing closing ']')" + ))); + }; + let label = text[label_start..label_start + label_len].to_string(); + let mut end = label_start + label_len + 1; + // Optional immediate `{attrs}`. + let mut attrs_src = ""; + if bytes.get(end) == Some(&b'{') { + let Some(close) = text[end + 1..].find('}') else { + return Err(CanonicalError::Directive(format!( + "unterminated inline directive ':{name}[…]{{' (missing closing '}}')" + ))); + }; + attrs_src = &text[end + 1..end + 1 + close]; + end = end + 1 + close + 1; + } + let (id, attrs) = parse_attrs(attrs_src)?; + out.push(Directive { + name: name.to_string(), + id, + attrs, + body: String::new(), + label: Some(label), + children: Vec::new(), + }); + i = end; + } + Ok(out) +} + fn check_known(name: &str) -> Result<()> { if !vocab::is_known_directive(name) { return Err(CanonicalError::Directive(format!( @@ -234,4 +324,55 @@ mod tests { let body = ":::why{}\nno close here"; assert!(parse(body).is_err()); } + + // Inline directives + + #[test] + fn inline_ref_in_container_prose_becomes_child() { + let body = ":::why\nWe follow :ref[the storage decision]{to=urn:atomic:memory:01J edge=depends} here.\n:::"; + let ds = parse(body).unwrap(); + let why = &ds[0]; + // Prose keeps the inline verbatim (reference, don't embed). + assert!(why.body.contains(":ref[the storage decision]")); + assert_eq!(why.children.len(), 1); + let r = &why.children[0]; + assert_eq!(r.name, "ref"); + assert_eq!(r.label.as_deref(), Some("the storage decision")); + assert_eq!(r.attr("to"), Some("urn:atomic:memory:01J")); + assert_eq!(r.attr("edge"), Some("depends")); + } + + #[test] + fn inline_parse_extracts_multiple() { + let text = "see :ref[a]{to=urn:atomic:intent:1 edge=depends} and :ref[b]{to=urn:atomic:intent:2 edge=blockedBy}"; + let ds = parse_inline(text).unwrap(); + assert_eq!(ds.len(), 2); + assert_eq!(ds[0].label.as_deref(), Some("a")); + assert_eq!(ds[1].attr("edge"), Some("blockedBy")); + } + + #[test] + fn dids_urns_and_unregistered_names_stay_prose() { + // Colons inside identifiers must never match (word boundary), and an + // unregistered inline name is prose, not an error. + let text = "did:atomic:lee wrote urn:atomic:intent:x; :unknown[thing]{a=b} and foo:bar[0] stay prose"; + let ds = parse_inline(text).unwrap(); + assert!(ds.is_empty(), "got {ds:?}"); + } + + #[test] + fn inline_without_label_bracket_is_prose() { + let ds = parse_inline("a plain :ref mention with no bracket").unwrap(); + assert!(ds.is_empty()); + } + + #[test] + fn unterminated_inline_label_is_error() { + assert!(parse_inline("bad :ref[never closed").is_err()); + } + + #[test] + fn unterminated_inline_attrs_is_error() { + assert!(parse_inline("bad :ref[x]{to=urn:atomic:intent:1").is_err()); + } } diff --git a/atomic-canonical/src/lift.rs b/atomic-canonical/src/lift.rs index 42a3343e..e0299609 100644 --- a/atomic-canonical/src/lift.rs +++ b/atomic-canonical/src/lift.rs @@ -57,6 +57,14 @@ pub fn lift_intent(frontmatter: &Map<String, Value>, body: &str) -> Result<Canon let mut constraint_n = 0usize; for d in &directives { + // Inline (and nested-leaf) `:ref` children of any container sit on the + // intent's dependency chain, same rules as a top-level `:::ref`. The + // container prose keeps the inline mention verbatim. + for child in &d.children { + if child.name == "ref" { + deps.push(lift_ref(child)?); + } + } match d.name.as_str() { "why" => { // Single authoring site: first `:::why` wins; the reason is @@ -377,6 +385,24 @@ Do not touch the global keyboard handler. assert!(node.depends_on[0].id.is_none()); } + #[test] + fn lifts_inline_ref_from_why_prose() { + let body = ":::why\nLocal-only per :ref[the storage constraint]{to=urn:atomic:memory:01J8ZC edge=depends}, not a profile system.\n:::"; + let node = lift_intent(&fm(), body).unwrap(); + // The reason keeps the inline mention verbatim… + assert!(node.why.as_deref().unwrap().contains(":ref[the storage constraint]")); + // …and the edge lands on the dependency chain, typed and validated. + assert_eq!(node.depends_on.len(), 1); + assert_eq!(node.depends_on[0].to, "urn:atomic:memory:01J8ZC"); + assert_eq!(node.depends_on[0].edge, "depends"); + } + + #[test] + fn inline_ref_with_bad_edge_is_error() { + let body = ":::why\nsee :ref[x]{to=urn:atomic:memory:1 edge=verifiedBy}\n:::"; + assert!(lift_intent(&fm(), body).is_err()); + } + #[test] fn ref_with_unknown_edge_is_error() { let body = ":::ref{to=urn:atomic:intent:xyz edge=wat}\n:::"; diff --git a/atomic-canonical/src/vocab.rs b/atomic-canonical/src/vocab.rs index 415d2b32..39f77a23 100644 --- a/atomic-canonical/src/vocab.rs +++ b/atomic-canonical/src/vocab.rs @@ -60,6 +60,21 @@ pub const DIRECTIVE_NAMES: &[&str] = &[ "memory", // container: carries a memory's body text ]; +/// Inline directive names (`:name[label]{attrs}` inside running prose). +/// +/// Inline recognition is registry-gated the *other* way around from block +/// directives: prose is the unconstrained slot, so a colon-pattern whose name +/// is not registered here stays prose (never an error) — otherwise writing +/// `did:atomic:lee[sic]` in a reason would be a parse failure. Only registered +/// names lift; the closed-vocabulary property still holds for everything that +/// reaches the graph. +pub const INLINE_DIRECTIVE_NAMES: &[&str] = &["ref"]; + +/// Is this an inline directive name the system lifts from prose? +pub fn is_known_inline_directive(name: &str) -> bool { + INLINE_DIRECTIVE_NAMES.contains(&name) +} + /// Memory kinds (closed set; mirrors `MemoryShape` `sh:in`). Exactly one. pub const MEMORY_KIND: &[&str] = &["constraint", "preference", "lesson", "context"]; From 87fa7d93610877d308fb4ccb892c77f438bf4674 Mon Sep 17 00:00:00 2001 From: Bradley Hilton <graywolf336@craftyn.com> Date: Mon, 6 Jul 2026 13:38:13 -0500 Subject: [PATCH 14/21] feat(canonical,cli): reject embedded directives in prose; resolve evidence URNs Ports the two authoring/lift correctness fixes from PR #102 (canonical part of 872a070, by Vincent), adapted to our top-level `intent validate`: - Reject registered directives embedded mid-sentence. `::file-ref{...}` inside a task's prose was silently kept as prose and the edge was lost; the lift now errors ("must start their own line"). Unregistered names stay prose (the inline rule), and rust paths / template comments / fenced code are exempt. `check_embedded_directives` in directive.rs, called from lift_intent + lift_memory. - Resolve acceptance-criterion evidence URNs. `evidence=urn:atomic:change:<hash>` was presence-checked only; `atomic intent validate` now, when run inside a repo, requires every such URN to resolve in the change store (skipped with a note outside a repo). Ported into our intent/validate.rs (their version lived in the canonical/ CLI we don't use). Excludes 872a070's shacl.rs touch (SHACL moved to Circuit Breaker). Canonical 54 tests, cli 1567+2+9, clippy clean. --- atomic-canonical/src/directive.rs | 104 +++++++++++++++++++++ atomic-canonical/src/lift.rs | 1 + atomic-canonical/src/memory.rs | 1 + atomic-cli/src/commands/intent/validate.rs | 95 ++++++++++++++++++- 4 files changed, 199 insertions(+), 2 deletions(-) diff --git a/atomic-canonical/src/directive.rs b/atomic-canonical/src/directive.rs index 6219ce22..1fde07a1 100644 --- a/atomic-canonical/src/directive.rs +++ b/atomic-canonical/src/directive.rs @@ -206,6 +206,84 @@ pub fn parse_inline(text: &str) -> Result<Vec<Directive>> { Ok(out) } +/// Reject a REGISTERED directive name embedded mid-prose with an attrs +/// brace (e.g. `… ::file-ref{path=x} …` inside a sentence). The block +/// parser only reads directives at line start, so an embedded one would +/// silently stay prose and its edge would be lost. Unregistered names stay +/// prose (the inline rule); `std::fs` and `foo::ref{...}` never match — the +/// colon run must not follow an identifier character. +pub fn check_embedded_directives(text: &str) -> Result<()> { + let mut in_fence = false; + for raw_line in text.lines() { + let line = strip_html_comments(raw_line); + let t = line.trim_start(); + if t.starts_with("```") { + in_fence = !in_fence; + continue; + } + // Lines the block parser handles itself (directive opens/closes). + if in_fence || t.starts_with(':') { + continue; + } + let bytes = line.as_bytes(); + let mut i = 0; + while i < bytes.len() { + if bytes[i] != b':' { + i += 1; + continue; + } + let start = i; + while i < bytes.len() && bytes[i] == b':' { + i += 1; + } + let run = i - start; + if !(2..=3).contains(&run) { + continue; + } + if start > 0 { + let prev = bytes[start - 1]; + if prev.is_ascii_alphanumeric() || prev == b'_' { + continue; + } + } + let name_start = i; + while i < bytes.len() + && (bytes[i].is_ascii_lowercase() || bytes[i].is_ascii_digit() || bytes[i] == b'-') + { + i += 1; + } + if i == name_start || i >= bytes.len() || bytes[i] != b'{' { + continue; + } + let name = &line[name_start..i]; + if vocab::is_known_directive(name) { + return Err(CanonicalError::Directive(format!( + "directive '{}{name}' is embedded in prose — block \ + directives must start their own line", + ":".repeat(run) + ))); + } + } + } + Ok(()) +} + +/// Drop `<!-- … -->` spans so template guidance comments never trip the +/// embedded-directive check. +fn strip_html_comments(line: &str) -> String { + let mut out = String::with_capacity(line.len()); + let mut rest = line; + while let Some(open) = rest.find("<!--") { + out.push_str(&rest[..open]); + match rest[open..].find("-->") { + Some(close) => rest = &rest[open + close + 3..], + None => return out, + } + } + out.push_str(rest); + out +} + fn check_known(name: &str) -> Result<()> { if !vocab::is_known_directive(name) { return Err(CanonicalError::Directive(format!( @@ -375,4 +453,30 @@ mod tests { fn unterminated_inline_attrs_is_error() { assert!(parse_inline("bad :ref[x]{to=urn:atomic:intent:1").is_err()); } + + #[test] + fn embedded_known_leaf_in_prose_is_error() { + let body = ":::task{#t1 status=open}\nUpdate ::file-ref{path=Cargo.toml} early.\n:::"; + let err = check_embedded_directives(body).unwrap_err(); + assert!( + err.to_string().contains("must start their own line"), + "{err}" + ); + } + + #[test] + fn rust_paths_and_suffixed_names_stay_prose() { + check_embedded_directives("use std::fs::read; also foo::ref{x} stays.").unwrap(); + } + + #[test] + fn unregistered_embedded_name_stays_prose() { + check_embedded_directives("try ::made-up{x=1} here").unwrap(); + } + + #[test] + fn template_comments_and_fences_are_exempt() { + check_embedded_directives("<!-- Name touched files with ::file-ref{path=...} -->").unwrap(); + check_embedded_directives("```\n::file-ref{path=x}\n```").unwrap(); + } } diff --git a/atomic-canonical/src/lift.rs b/atomic-canonical/src/lift.rs index e0299609..842ef84b 100644 --- a/atomic-canonical/src/lift.rs +++ b/atomic-canonical/src/lift.rs @@ -37,6 +37,7 @@ pub(crate) const LIFTED_INTENT_DIRECTIVES: &[&str] = &[ /// Lift an intent from its frontmatter spine and markdown body. pub fn lift_intent(frontmatter: &Map<String, Value>, body: &str) -> Result<CanonicalNode> { + directive::check_embedded_directives(body)?; let human_key = require_str(frontmatter, "id")?; let uid = opt_str(frontmatter, "uid").unwrap_or_else(|| slug(&human_key)); let node_id = format!("urn:atomic:intent:{uid}"); diff --git a/atomic-canonical/src/memory.rs b/atomic-canonical/src/memory.rs index 65c00fbc..5b6f7e41 100644 --- a/atomic-canonical/src/memory.rs +++ b/atomic-canonical/src/memory.rs @@ -115,6 +115,7 @@ impl MemoryNode { /// container directive if present (single authoring site), else falls back to /// the whole trimmed body. pub fn lift_memory(frontmatter: &Map<String, Value>, body: &str) -> Result<MemoryNode> { + crate::directive::check_embedded_directives(body)?; let uid = opt_str(frontmatter, "uid") .or_else(|| opt_str(frontmatter, "id")) .ok_or_else(|| CanonicalError::Lift("memory frontmatter missing 'uid' (or 'id')".into()))?; diff --git a/atomic-cli/src/commands/intent/validate.rs b/atomic-cli/src/commands/intent/validate.rs index 6630a4ca..96ed7c3d 100644 --- a/atomic-cli/src/commands/intent/validate.rs +++ b/atomic-cli/src/commands/intent/validate.rs @@ -6,7 +6,8 @@ use std::path::Path; use clap::Parser; use atomic_canonical::lift::{lift_intent, parse_markdown}; -use atomic_canonical::{validate_intent, ValidationReport}; +use atomic_canonical::{validate_intent, ValidationReport, Violation}; +use atomic_core::types::{Base32, Hash}; use atomic_repository::Repository; use crate::commands::intent::bridge; @@ -67,7 +68,21 @@ impl Command for IntentValidate { } }; - let report = validate_intent(&node); + let mut report = validate_intent(&node); + + // Evidence URNs must RESOLVE to real changes when a repository is + // reachable — the gate only checks presence. (Recording the Why: a met + // acceptance criterion's evidence must resolve, not just exist.) + let evidence: Vec<(String, String)> = node + .has_acceptance_criterion + .iter() + .filter_map(|ac| ac.evidence.clone().map(|e| (ac.id.clone(), e))) + .collect(); + let extra = check_evidence_resolution(&evidence, find_repository_root().ok().as_deref()); + if !extra.is_empty() { + report.conforms = false; + report.results.extend(extra); + } if self.json { println!("{}", serde_json::to_string_pretty(&report_json(&report)).unwrap()); @@ -95,6 +110,45 @@ fn is_path_shaped(arg: &str) -> bool { arg.ends_with(".md") || arg.contains('/') || arg.contains(std::path::MAIN_SEPARATOR) } +/// Resolve `urn:atomic:change:<hash>` evidence URNs against the change store at +/// `repo_root`. One violation per URN that does not resolve. With no repository +/// the check is skipped — the gate still enforces presence; resolution needs a +/// change store. (Ported from PR #102, adapted to the top-level `intent validate`.) +fn check_evidence_resolution(evidence: &[(String, String)], repo_root: Option<&Path>) -> Vec<Violation> { + let mut violations = Vec::new(); + if evidence.is_empty() { + return violations; + } + let Some(root) = repo_root else { + eprintln!("note: evidence resolution skipped — not inside an Atomic repository"); + return violations; + }; + let repo = match Repository::open_readonly(root) { + Ok(repo) => repo, + Err(e) => { + eprintln!("note: evidence resolution skipped — cannot open repository: {e}"); + return violations; + } + }; + for (focus, urn) in evidence { + let Some(hash_str) = urn.strip_prefix("urn:atomic:change:") else { + continue; // non-change URNs are out of scope here + }; + let resolved = Hash::from_base32(hash_str.as_bytes()) + .map(|h| repo.has_change(&h)) + .unwrap_or(false); + if !resolved { + violations.push(Violation { + focus_node: focus.clone(), + shape: "EvidenceResolution".to_string(), + path: Some("evidence".to_string()), + message: format!("evidence {urn} does not resolve to a change in this repository"), + }); + } + } + violations +} + /// Serialize a [`ValidationReport`] to the documented JSON shape: /// `{conforms, results: [{focus_node, shape, path, message}]}`. fn report_json(report: &ValidationReport) -> serde_json::Value { @@ -112,3 +166,40 @@ fn report_json(report: &ValidationReport) -> serde_json::Value { .collect::<Vec<_>>(), }) } + +#[cfg(test)] +mod evidence_tests { + use super::check_evidence_resolution; + + fn ev(urn: &str) -> Vec<(String, String)> { + vec![("urn:atomic:ac:x-ac-1".to_string(), urn.to_string())] + } + + #[test] + fn no_repo_skips_without_violations() { + // No repository → presence is still gated elsewhere; resolution is skipped. + let v = check_evidence_resolution(&ev("urn:atomic:change:AAAA"), None); + assert!(v.is_empty()); + } + + #[test] + fn unresolvable_urn_in_repo_is_a_violation() { + let dir = tempfile::tempdir().unwrap(); + atomic_repository::Repository::init(dir.path()).unwrap(); + let v = check_evidence_resolution( + &ev("urn:atomic:change:XXX5YG4CV4XJL7JV3RRK6RHLJRTA4BW5ET4AACFDTKZQEMYJYGCQ"), + Some(dir.path()), + ); + assert_eq!(v.len(), 1); + assert!(v[0].message.contains("does not resolve"), "{}", v[0].message); + } + + #[test] + fn non_change_urn_is_ignored() { + let dir = tempfile::tempdir().unwrap(); + atomic_repository::Repository::init(dir.path()).unwrap(); + // A non-change evidence URN is out of scope for resolution. + let v = check_evidence_resolution(&ev("urn:atomic:memory:whatever"), Some(dir.path())); + assert!(v.is_empty()); + } +} From 413b73ea75c11f0fd6c802292a3a91316a42be90 Mon Sep 17 00:00:00 2001 From: Bradley Hilton <graywolf336@craftyn.com> Date: Tue, 7 Jul 2026 12:34:51 -0500 Subject: [PATCH 15/21] style: cargo fmt across the Recording-the-Why crates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Run rustfmt over the RtW work area (atomic-canonical, atomic-cli, and the three vault files in atomic-core/atomic-repository the attestation-entry work touched). The RtW code was authored with custom hand-formatting; this brings it to rustfmt so `cargo fmt --all --check` is clean before further work. Whitespace/layout only — no behavior change (canonical 54+18, cli 1567+2+9 tests green; clippy clean). The rest of the workspace was already fmt-clean and is untouched. --- atomic-canonical/src/context.rs | 5 +- atomic-canonical/src/gate.rs | 11 ++- atomic-canonical/src/lib.rs | 9 +-- atomic-canonical/src/lift.rs | 67 ++++++++++++------- atomic-canonical/src/memory.rs | 28 +++++--- atomic-canonical/src/node.rs | 30 +++++++-- atomic-canonical/src/proof.rs | 19 +++++- atomic-canonical/src/prov.rs | 18 +++-- atomic-canonical/src/vocab.rs | 16 ++--- atomic-canonical/tests/roundtrip.rs | 45 ++++++++----- atomic-cli/src/commands/intent/attest.rs | 15 +++-- atomic-cli/src/commands/intent/bridge.rs | 16 +++-- atomic-cli/src/commands/intent/list.rs | 15 ++--- atomic-cli/src/commands/intent/show.rs | 5 +- atomic-cli/src/commands/intent/validate.rs | 16 ++++- atomic-cli/src/commands/memory/attest.rs | 14 ++-- atomic-cli/src/commands/memory/bridge.rs | 8 +-- atomic-cli/src/commands/memory/list.rs | 10 +-- atomic-cli/src/commands/memory/mod.rs | 32 ++++++--- atomic-cli/src/commands/memory/new.rs | 19 +++--- atomic-cli/src/commands/memory/show.rs | 5 +- atomic-cli/src/commands/memory/validate.rs | 5 +- atomic-cli/src/commands/provenance/command.rs | 32 ++++++--- atomic-cli/src/commands/provenance/mapping.rs | 4 +- .../tests/provenance_integration_test.rs | 18 +++-- atomic-core/src/pristine/vault.rs | 12 ++-- atomic-repository/src/repository/vault.rs | 5 +- .../src/repository/vault_triples.rs | 5 +- 28 files changed, 322 insertions(+), 162 deletions(-) diff --git a/atomic-canonical/src/context.rs b/atomic-canonical/src/context.rs index 3c12256e..a76335ce 100644 --- a/atomic-canonical/src/context.rs +++ b/atomic-canonical/src/context.rs @@ -58,7 +58,10 @@ mod tests { #[test] fn context_document_is_valid_and_nonempty() { - assert!(defined_terms().len() > 20, "context should define the vocabulary"); + assert!( + defined_terms().len() > 20, + "context should define the vocabulary" + ); assert!(defined_terms().contains("prov")); assert!(defined_terms().contains("used")); assert!(defined_terms().contains("associatedWith")); diff --git a/atomic-canonical/src/gate.rs b/atomic-canonical/src/gate.rs index 549050d7..1b443af0 100644 --- a/atomic-canonical/src/gate.rs +++ b/atomic-canonical/src/gate.rs @@ -56,7 +56,11 @@ impl std::fmt::Display for ValidationReport { writeln!(f, "conforms: no ({} violation(s))", self.results.len())?; for v in &self.results { let path = v.path.as_deref().unwrap_or("-"); - writeln!(f, " ✗ [{}] {} ({}): {}", v.shape, v.focus_node, path, v.message)?; + writeln!( + f, + " ✗ [{}] {} ({}): {}", + v.shape, v.focus_node, path, v.message + )?; } Ok(()) } @@ -378,7 +382,10 @@ mod tests { assert!(!report.conforms); for path in ["proof", "attributedTo", "text"] { assert!( - report.results.iter().any(|v| v.path.as_deref() == Some(path)), + report + .results + .iter() + .any(|v| v.path.as_deref() == Some(path)), "expected a violation on {path}" ); } diff --git a/atomic-canonical/src/lib.rs b/atomic-canonical/src/lib.rs index 0b98fb86..2c73dacd 100644 --- a/atomic-canonical/src/lib.rs +++ b/atomic-canonical/src/lib.rs @@ -46,9 +46,7 @@ pub mod vocab; pub use error::{CanonicalError, Result}; pub use gate::{validate_intent, validate_memory, ValidationReport, Violation}; pub use memory::MemoryNode; -pub use node::{ - AcceptanceCriterion, CanonicalNode, Constraint, Proof, Ref, ScopeItem, Task, -}; +pub use node::{AcceptanceCriterion, CanonicalNode, Constraint, Proof, Ref, ScopeItem, Task}; pub use prov::{attest_prov, project, verify_prov, ProvActivityInput}; pub use render::{render, render_memory, Target}; @@ -70,7 +68,10 @@ pub fn lift_and_attest( } /// Verify an attested node's content hash and signature against a public key. -pub fn verify(node: &CanonicalNode, public_key: &atomic_identity::keypair::PublicKey) -> Result<()> { +pub fn verify( + node: &CanonicalNode, + public_key: &atomic_identity::keypair::PublicKey, +) -> Result<()> { proof::verify(node, public_key) } diff --git a/atomic-canonical/src/lift.rs b/atomic-canonical/src/lift.rs index 842ef84b..009756c6 100644 --- a/atomic-canonical/src/lift.rs +++ b/atomic-canonical/src/lift.rs @@ -139,10 +139,9 @@ pub fn lift_intent(frontmatter: &Map<String, Value>, body: &str) -> Result<Canon } fn lift_ac(d: &Directive, human_key: &str, n: usize) -> Result<AcceptanceCriterion> { - let local = d - .id - .clone() - .unwrap_or_else(|| format!("{}-ac-{n}", slug(human_key))); + let local = + d.id.clone() + .unwrap_or_else(|| format!("{}-ac-{n}", slug(human_key))); Ok(AcceptanceCriterion { type_: NodeType::AcceptanceCriterion.as_str().to_string(), id: as_urn("ac", &local), @@ -154,10 +153,9 @@ fn lift_ac(d: &Directive, human_key: &str, n: usize) -> Result<AcceptanceCriteri } fn lift_task(d: &Directive, human_key: &str, n: usize) -> Task { - let local = d - .id - .clone() - .unwrap_or_else(|| format!("{}-{n}", slug(human_key))); + let local = + d.id.clone() + .unwrap_or_else(|| format!("{}-{n}", slug(human_key))); let mut touches: Vec<String> = Vec::new(); if let Some(f) = d.attr("touchesFile") { touches.push(f.to_string()); @@ -187,10 +185,9 @@ fn lift_task(d: &Directive, human_key: &str, n: usize) -> Task { /// `kind` is "scope-in" or "scope-out" and drives the generated id slug. /// Prose body is the unconstrained narrative (never graded). fn lift_scope(d: &Directive, human_key: &str, kind: &str, n: usize) -> ScopeItem { - let local = d - .id - .clone() - .unwrap_or_else(|| format!("{}-{kind}-{n}", slug(human_key))); + let local = + d.id.clone() + .unwrap_or_else(|| format!("{}-{kind}-{n}", slug(human_key))); ScopeItem { type_: NodeType::ScopeItem.as_str().to_string(), id: as_urn("scope", &local), @@ -200,10 +197,9 @@ fn lift_scope(d: &Directive, human_key: &str, kind: &str, n: usize) -> ScopeItem /// Lift a `:::constraint` container into a `Constraint`. fn lift_constraint(d: &Directive, human_key: &str, n: usize) -> Constraint { - let local = d - .id - .clone() - .unwrap_or_else(|| format!("{}-constraint-{n}", slug(human_key))); + let local = + d.id.clone() + .unwrap_or_else(|| format!("{}-constraint-{n}", slug(human_key))); Constraint { type_: NodeType::Constraint.as_str().to_string(), id: as_urn("constraint", &local), @@ -270,9 +266,11 @@ fn str_array(fm: &Map<String, Value>, key: &str) -> Vec<String> { .iter() .filter_map(|v| v.as_str().map(str::to_string)) .collect(), - Some(Value::String(s)) if !s.is_empty() => { - s.split(',').map(|p| p.trim().to_string()).filter(|p| !p.is_empty()).collect() - } + Some(Value::String(s)) if !s.is_empty() => s + .split(',') + .map(|p| p.trim().to_string()) + .filter(|p| !p.is_empty()) + .collect(), _ => Vec::new(), } } @@ -284,7 +282,10 @@ pub fn parse_markdown(doc: &str) -> Result<(Map<String, Value>, String)> { // Normalize CRLF so a Windows-authored file parses identically to LF — // otherwise the "---\n" prefix match fails and the whole doc is silently // treated as body with empty frontmatter. - let normalized = doc.strip_prefix('\u{feff}').unwrap_or(doc).replace("\r\n", "\n"); + let normalized = doc + .strip_prefix('\u{feff}') + .unwrap_or(doc) + .replace("\r\n", "\n"); let doc = normalized.as_str(); let rest = match doc.strip_prefix("---\n") { Some(r) => r, @@ -367,10 +368,22 @@ Do not touch the global keyboard handler. assert_eq!(node.has_constraint.len(), 2); // Ids are well-formed urns generated from the slug + ordinal. - assert_eq!(node.has_scope_in[0].id, "urn:atomic:scope:word-5-scope-in-1"); - assert_eq!(node.has_scope_out[0].id, "urn:atomic:scope:word-5-scope-out-1"); - assert_eq!(node.has_constraint[0].id, "urn:atomic:constraint:word-5-constraint-1"); - assert_eq!(node.has_constraint[1].id, "urn:atomic:constraint:word-5-constraint-2"); + assert_eq!( + node.has_scope_in[0].id, + "urn:atomic:scope:word-5-scope-in-1" + ); + assert_eq!( + node.has_scope_out[0].id, + "urn:atomic:scope:word-5-scope-out-1" + ); + assert_eq!( + node.has_constraint[0].id, + "urn:atomic:constraint:word-5-constraint-1" + ); + assert_eq!( + node.has_constraint[1].id, + "urn:atomic:constraint:word-5-constraint-2" + ); assert!(node.has_scope_in[0].text.contains("src/App.tsx")); } @@ -391,7 +404,11 @@ Do not touch the global keyboard handler. let body = ":::why\nLocal-only per :ref[the storage constraint]{to=urn:atomic:memory:01J8ZC edge=depends}, not a profile system.\n:::"; let node = lift_intent(&fm(), body).unwrap(); // The reason keeps the inline mention verbatim… - assert!(node.why.as_deref().unwrap().contains(":ref[the storage constraint]")); + assert!(node + .why + .as_deref() + .unwrap() + .contains(":ref[the storage constraint]")); // …and the edge lands on the dependency chain, typed and validated. assert_eq!(node.depends_on.len(), 1); assert_eq!(node.depends_on[0].to, "urn:atomic:memory:01J8ZC"); diff --git a/atomic-canonical/src/memory.rs b/atomic-canonical/src/memory.rs index 5b6f7e41..5526484b 100644 --- a/atomic-canonical/src/memory.rs +++ b/atomic-canonical/src/memory.rs @@ -64,12 +64,24 @@ pub struct MemoryNode { // no empty JSON-LD keys leak into the hash. #[serde(default, skip_serializing_if = "Option::is_none")] pub supersedes: Option<String>, - #[serde(rename = "previousRevision", default, skip_serializing_if = "Option::is_none")] + #[serde( + rename = "previousRevision", + default, + skip_serializing_if = "Option::is_none" + )] pub previous_revision: Option<String>, - #[serde(rename = "contentHash", default, skip_serializing_if = "Option::is_none")] + #[serde( + rename = "contentHash", + default, + skip_serializing_if = "Option::is_none" + )] pub content_hash: Option<String>, - #[serde(rename = "attributedTo", default, skip_serializing_if = "Option::is_none")] + #[serde( + rename = "attributedTo", + default, + skip_serializing_if = "Option::is_none" + )] pub attributed_to: Option<String>, #[serde(rename = "createdAt")] pub created_at: String, @@ -121,10 +133,9 @@ pub fn lift_memory(frontmatter: &Map<String, Value>, body: &str) -> Result<Memor .ok_or_else(|| CanonicalError::Lift("memory frontmatter missing 'uid' (or 'id')".into()))?; let node_id = as_memory_urn(&uid); - let memory_kind = require_str(frontmatter, "memoryKind") - .or_else(|_| require_str(frontmatter, "kind"))?; - let status = - opt_str(frontmatter, "status").unwrap_or_else(|| "active".to_string()); + let memory_kind = + require_str(frontmatter, "memoryKind").or_else(|_| require_str(frontmatter, "kind"))?; + let status = opt_str(frontmatter, "status").unwrap_or_else(|| "active".to_string()); // Single authoring site: the first `:::memory` container's body is // authoritative; the surrounding prose is ignored. Only when no container @@ -210,7 +221,8 @@ fn as_memory_urn(local: &str) -> String { } fn require_str(fm: &Map<String, Value>, key: &str) -> Result<String> { - opt_str(fm, key).ok_or_else(|| CanonicalError::Lift(format!("memory frontmatter missing '{key}'"))) + opt_str(fm, key) + .ok_or_else(|| CanonicalError::Lift(format!("memory frontmatter missing '{key}'"))) } fn opt_str(fm: &Map<String, Value>, key: &str) -> Option<String> { diff --git a/atomic-canonical/src/node.rs b/atomic-canonical/src/node.rs index c81dad13..23c11a50 100644 --- a/atomic-canonical/src/node.rs +++ b/atomic-canonical/src/node.rs @@ -26,7 +26,11 @@ pub struct AcceptanceCriterion { pub text: String, #[serde(rename = "acStatus")] pub ac_status: String, - #[serde(rename = "verifiedBy", default, skip_serializing_if = "Option::is_none")] + #[serde( + rename = "verifiedBy", + default, + skip_serializing_if = "Option::is_none" + )] pub verified_by: Option<String>, #[serde(default, skip_serializing_if = "Option::is_none")] pub evidence: Option<String>, @@ -128,7 +132,11 @@ pub struct CanonicalNode { #[serde(default, skip_serializing_if = "Option::is_none")] pub view: Option<String>, - #[serde(rename = "motivatedBy", default, skip_serializing_if = "Option::is_none")] + #[serde( + rename = "motivatedBy", + default, + skip_serializing_if = "Option::is_none" + )] pub motivated_by: Option<String>, #[serde(rename = "informedBy", default, skip_serializing_if = "Vec::is_empty")] pub informed_by: Vec<String>, @@ -148,7 +156,11 @@ pub struct CanonicalNode { pub has_scope_in: Vec<ScopeItem>, #[serde(rename = "hasScopeOut", default, skip_serializing_if = "Vec::is_empty")] pub has_scope_out: Vec<ScopeItem>, - #[serde(rename = "hasConstraint", default, skip_serializing_if = "Vec::is_empty")] + #[serde( + rename = "hasConstraint", + default, + skip_serializing_if = "Vec::is_empty" + )] pub has_constraint: Vec<Constraint>, #[serde(rename = "dependsOn", default, skip_serializing_if = "Vec::is_empty")] pub depends_on: Vec<Ref>, @@ -157,9 +169,17 @@ pub struct CanonicalNode { #[serde(default, skip_serializing_if = "Option::is_none")] pub why: Option<String>, - #[serde(rename = "contentHash", default, skip_serializing_if = "Option::is_none")] + #[serde( + rename = "contentHash", + default, + skip_serializing_if = "Option::is_none" + )] pub content_hash: Option<String>, - #[serde(rename = "attributedTo", default, skip_serializing_if = "Option::is_none")] + #[serde( + rename = "attributedTo", + default, + skip_serializing_if = "Option::is_none" + )] pub attributed_to: Option<String>, #[serde(rename = "createdAt")] pub created_at: String, diff --git a/atomic-canonical/src/proof.rs b/atomic-canonical/src/proof.rs index 04782d46..191276c0 100644 --- a/atomic-canonical/src/proof.rs +++ b/atomic-canonical/src/proof.rs @@ -237,16 +237,29 @@ mod tests { // The generic path filled the excluded-later fields. let obj = attested.as_object().unwrap(); - assert!(obj.get(PROP_CONTENT_HASH).unwrap().as_str().unwrap().starts_with("blake3:")); + assert!(obj + .get(PROP_CONTENT_HASH) + .unwrap() + .as_str() + .unwrap() + .starts_with("blake3:")); assert!(obj.get(PROP_PROOF).is_some()); - assert!(obj.get(PROP_ATTRIBUTED_TO).unwrap().as_str().unwrap().starts_with("did:atomic:")); + assert!(obj + .get(PROP_ATTRIBUTED_TO) + .unwrap() + .as_str() + .unwrap() + .starts_with("did:atomic:")); // Verifies with the right key, independent of CanonicalNode. verify_value(&attested, &kp.public).expect("generic verify should succeed"); // Tamper a signed field → the stored contentHash no longer matches. let mut tampered = attested.clone(); - tampered.as_object_mut().unwrap().insert("status".into(), Value::String("done".into())); + tampered + .as_object_mut() + .unwrap() + .insert("status".into(), Value::String("done".into())); let err = verify_value(&tampered, &kp.public).unwrap_err(); assert!( matches!(err, CanonicalError::HashMismatch { .. }), diff --git a/atomic-canonical/src/prov.rs b/atomic-canonical/src/prov.rs index 7967e2f6..14c210ae 100644 --- a/atomic-canonical/src/prov.rs +++ b/atomic-canonical/src/prov.rs @@ -303,8 +303,14 @@ mod tests { let agent_id = agent.get("@id").and_then(Value::as_str).unwrap(); assert!(agent_id.starts_with("urn:atomic:agent:")); assert!(!agent_id.starts_with("did:")); - assert_eq!(agent.get("label").and_then(Value::as_str), Some("Claude Code")); - assert_eq!(agent.get("vendor").and_then(Value::as_str), Some("anthropic")); + assert_eq!( + agent.get("label").and_then(Value::as_str), + Some("Claude Code") + ); + assert_eq!( + agent.get("vendor").and_then(Value::as_str), + Some("anthropic") + ); // Person @id == the real did:atomic. let person_node = node_of_type(&value, "prov:Person"); @@ -365,10 +371,10 @@ mod tests { // Tamper a signed field -> HashMismatch. let mut tampered = attested.clone(); - tampered - .as_object_mut() - .unwrap() - .insert("@id".into(), Value::String("urn:atomic:provgraph:EVIL".into())); + tampered.as_object_mut().unwrap().insert( + "@id".into(), + Value::String("urn:atomic:provgraph:EVIL".into()), + ); let err = verify_prov(&tampered, &kp.public).unwrap_err(); assert!( matches!(err, CanonicalError::HashMismatch { .. }), diff --git a/atomic-canonical/src/vocab.rs b/atomic-canonical/src/vocab.rs index 39f77a23..228d6650 100644 --- a/atomic-canonical/src/vocab.rs +++ b/atomic-canonical/src/vocab.rs @@ -49,15 +49,15 @@ pub const AC_STATUS: &[&str] = &["open", "met"]; /// NOTE: `lift.rs` must only branch on these names. A directive name not in /// this list is a parse/gate error, never a new type the lift absorbs. pub const DIRECTIVE_NAMES: &[&str] = &[ - "why", // container: the unconstrained reason (presence enforced, content honest) + "why", // container: the unconstrained reason (presence enforced, content honest) "acceptance-criterion", // container - "task", // container - "scope-in", // container - "scope-out", // container - "constraint", // container - "ref", // leaf: a typed dependency edge - "file-ref", // leaf: a file the task touches - "memory", // container: carries a memory's body text + "task", // container + "scope-in", // container + "scope-out", // container + "constraint", // container + "ref", // leaf: a typed dependency edge + "file-ref", // leaf: a file the task touches + "memory", // container: carries a memory's body text ]; /// Inline directive names (`:name[label]{attrs}` inside running prose). diff --git a/atomic-canonical/tests/roundtrip.rs b/atomic-canonical/tests/roundtrip.rs index 2b038372..e748c14f 100644 --- a/atomic-canonical/tests/roundtrip.rs +++ b/atomic-canonical/tests/roundtrip.rs @@ -57,8 +57,14 @@ fn full_round_trip_lifts_attests_gates_verifies_renders() { assert_eq!(node.human_key, "WORD-5"); assert_eq!(node.has_acceptance_criterion.len(), 1); assert_eq!(node.has_task.len(), 1); - assert_eq!(node.has_acceptance_criterion[0].id, "urn:atomic:ac:WORD-5-ac-1"); - assert_eq!(node.has_task[0].touches_file, vec!["src/App.tsx".to_string()]); + assert_eq!( + node.has_acceptance_criterion[0].id, + "urn:atomic:ac:WORD-5-ac-1" + ); + assert_eq!( + node.has_task[0].touches_file, + vec!["src/App.tsx".to_string()] + ); assert!(node.why.as_deref().unwrap().contains("local-only modal")); // Attested. @@ -108,7 +114,10 @@ fn gate_requires_a_reason_to_be_present() { let node = lift_and_attest(&frontmatter(), body, &id, &kp).unwrap(); let report = validate_intent(&node); assert!(!report.conforms); - assert!(report.results.iter().any(|v| v.path.as_deref() == Some("why"))); + assert!(report + .results + .iter() + .any(|v| v.path.as_deref() == Some("why"))); } #[test] @@ -119,7 +128,10 @@ fn gate_rejects_unknown_status() { let node = lift_and_attest(&fm, ":::why{}\nr\n:::", &id, &kp).unwrap(); let report = validate_intent(&node); assert!(!report.conforms); - assert!(report.results.iter().any(|v| v.path.as_deref() == Some("status"))); + assert!(report + .results + .iter() + .any(|v| v.path.as_deref() == Some("status"))); } #[test] @@ -253,7 +265,11 @@ fn memory_lift_gate_attest_verify_render_end_to_end() { assert_eq!(node.proof.as_ref().unwrap().cryptosuite, "eddsa-jcs-2022"); // Gate conforms. - assert!(validate_memory(&node).conforms, "gate:\n{}", validate_memory(&node)); + assert!( + validate_memory(&node).conforms, + "gate:\n{}", + validate_memory(&node) + ); // Verify. verify_memory(&node, &kp.public).expect("memory verification should succeed"); @@ -301,9 +317,7 @@ fn memory_falls_back_to_whole_body_without_container() { #[test] fn parse_markdown_then_lift() { - let doc = format!( - "---\nid: WORD-9\ntitle: \"Doc parse\"\nstatus: backlog\n---\n{BODY}" - ); + let doc = format!("---\nid: WORD-9\ntitle: \"Doc parse\"\nstatus: backlog\n---\n{BODY}"); let (fm, body) = parse_markdown(&doc).unwrap(); assert_eq!(fm.get("id").unwrap().as_str(), Some("WORD-9")); let node = lift_intent(&fm, &body).unwrap(); @@ -322,9 +336,10 @@ fn injected_unknown_field_is_rejected_on_load_intent() { let (id, kp) = dev_identity(); let node = lift_and_attest(&frontmatter(), BODY, &id, &kp).unwrap(); let mut v = serde_json::to_value(&node).unwrap(); - v.as_object_mut() - .unwrap() - .insert("actualStatus".into(), Value::String("done-but-forged".into())); + v.as_object_mut().unwrap().insert( + "actualStatus".into(), + Value::String("done-but-forged".into()), + ); let reload: Result<atomic_canonical::CanonicalNode, _> = serde_json::from_value(v); assert!(reload.is_err(), "an unknown field must be rejected on load"); } @@ -365,16 +380,12 @@ fn tampered_proof_metadata_fails_verification() { fn ref_edge_is_restricted_to_dependency_subset() { // MINOR fix: a :::ref sits on the dependency chain, so a non-dependency edge // (e.g. verifiedBy) must be rejected even though it is a valid edge elsewhere. - let good = format!( - "{BODY}\n\n:::ref{{to=urn:atomic:intent:other edge=blockedBy}}\n:::" - ); + let good = format!("{BODY}\n\n:::ref{{to=urn:atomic:intent:other edge=blockedBy}}\n:::"); let node = lift_intent(&frontmatter(), &good).unwrap(); assert_eq!(node.depends_on.len(), 1); assert_eq!(node.depends_on[0].edge, "blockedBy"); - let bad = format!( - "{BODY}\n\n:::ref{{to=urn:atomic:intent:other edge=verifiedBy}}\n:::" - ); + let bad = format!("{BODY}\n\n:::ref{{to=urn:atomic:intent:other edge=verifiedBy}}\n:::"); assert!( lift_intent(&frontmatter(), &bad).is_err(), "verifiedBy is not a dependency edge" diff --git a/atomic-cli/src/commands/intent/attest.rs b/atomic-cli/src/commands/intent/attest.rs index f96f8904..d879adc0 100644 --- a/atomic-cli/src/commands/intent/attest.rs +++ b/atomic-cli/src/commands/intent/attest.rs @@ -128,7 +128,10 @@ impl Command for IntentAttest { artifact.insert("node".to_string(), node.to_value()); let mut source = serde_json::Map::new(); if let Some(vault_path) = bridge::vault_path_for(&repo, &self.id)? { - source.insert("vaultPath".to_string(), serde_json::Value::String(vault_path)); + source.insert( + "vaultPath".to_string(), + serde_json::Value::String(vault_path), + ); } source.insert( "sourceContentHash".to_string(), @@ -187,10 +190,7 @@ impl Command for IntentAttest { repo.vault_materialize(&vault_path) .map_err(CliError::Repository)?; - let did = node - .attributed_to - .as_deref() - .unwrap_or("(unknown)"); + let did = node.attributed_to.as_deref().unwrap_or("(unknown)"); let proof_prefix = node .proof .as_ref() @@ -201,7 +201,10 @@ impl Command for IntentAttest { .unwrap_or_default(); if self.json { - println!("{}", serde_json::to_string_pretty(&node.to_value()).unwrap()); + println!( + "{}", + serde_json::to_string_pretty(&node.to_value()).unwrap() + ); } else { println!("Attested intent: {}", self.id); println!(" vault: .vault/{vault_path}"); diff --git a/atomic-cli/src/commands/intent/bridge.rs b/atomic-cli/src/commands/intent/bridge.rs index 5857a4c5..e6f8a106 100644 --- a/atomic-cli/src/commands/intent/bridge.rs +++ b/atomic-cli/src/commands/intent/bridge.rs @@ -60,8 +60,8 @@ pub struct LiftInputs { /// (`serde_json::from_str` into a `Map`). A malformed frontmatter string is a /// clean argument error rather than an internal panic. pub fn inputs_from_entry(entry: &VaultEntry) -> CliResult<LiftInputs> { - let frontmatter: Map<String, Value> = serde_json::from_str(&entry.frontmatter_json) - .map_err(|e| CliError::InvalidArgument { + let frontmatter: Map<String, Value> = + serde_json::from_str(&entry.frontmatter_json).map_err(|e| CliError::InvalidArgument { message: format!("intent frontmatter is not valid JSON: {e}"), })?; let body = String::from_utf8_lossy(&entry.content_bytes).into_owned(); @@ -369,7 +369,10 @@ mod tests { let mut body = serde_json::to_string_pretty(&node.to_value()).unwrap(); body.push('\n'); let mut fm = serde_json::Map::new(); - fm.insert("intentId".into(), Value::String(normalized_id(repo, id).unwrap())); + fm.insert( + "intentId".into(), + Value::String(normalized_id(repo, id).unwrap()), + ); fm.insert( "sourceContentHash".into(), Value::String(source_content_hash(inputs)), @@ -386,7 +389,12 @@ mod tests { } /// Mirror `attest`'s legacy sidecar write exactly ({node, source} wrapper). - fn write_legacy_sidecar(repo: &Repository, id: &str, node: &CanonicalNode, inputs: &LiftInputs) { + fn write_legacy_sidecar( + repo: &Repository, + id: &str, + node: &CanonicalNode, + inputs: &LiftInputs, + ) { let path = attested_sidecar_path(repo, id).unwrap(); std::fs::create_dir_all(path.parent().unwrap()).unwrap(); let mut artifact = serde_json::Map::new(); diff --git a/atomic-cli/src/commands/intent/list.rs b/atomic-cli/src/commands/intent/list.rs index a9124781..d44c96b4 100644 --- a/atomic-cli/src/commands/intent/list.rs +++ b/atomic-cli/src/commands/intent/list.rs @@ -174,10 +174,7 @@ fn resolve_verifier(name: &Option<String>) -> CliResult<Option<Verifier>> { /// (a legitimately other-signed node, NOT a failure — showing `✗` here /// would be a false negative); /// - same signer ⇒ run `verify`: `Ok` ⇒ `Yes`, `Err` ⇒ `No`. -fn compute_verifies( - attested: &bridge::Attestation, - verifier: Option<&Verifier>, -) -> Verifies { +fn compute_verifies(attested: &bridge::Attestation, verifier: Option<&Verifier>) -> Verifies { let node = match attested { bridge::Attestation::Fresh(node) => node, bridge::Attestation::Stale(_) | bridge::Attestation::None => return Verifies::Na, @@ -240,9 +237,7 @@ impl Command for IntentList { // Enumerate via the SAME source `atomic vault intent list` uses; already // sorted by id. Attestation entries are never in `manifest.intents`. - let intents = repo - .vault_intent_list(None) - .map_err(CliError::Repository)?; + let intents = repo.vault_intent_list(None).map_err(CliError::Repository)?; let rows: Vec<Row> = intents .iter() @@ -452,7 +447,11 @@ mod tests { write_tracked(&repo, &ids[0], &node); let row = row_for(&repo, &ids[0], Some(&kp)); - assert_eq!(row.attested, Attested::Fresh, "still fresh (hash anchor kept)"); + assert_eq!( + row.attested, + Attested::Fresh, + "still fresh (hash anchor kept)" + ); assert_eq!(row.verifies, Verifies::No, "tampered same-signer ⇒ '✗'"); assert_eq!(row.verifies.table(), "✗"); } diff --git a/atomic-cli/src/commands/intent/show.rs b/atomic-cli/src/commands/intent/show.rs index 7cb8ab1b..cc220879 100644 --- a/atomic-cli/src/commands/intent/show.rs +++ b/atomic-cli/src/commands/intent/show.rs @@ -49,7 +49,10 @@ impl Command for IntentShow { }; if self.json { - println!("{}", serde_json::to_string_pretty(&node.to_value()).unwrap()); + println!( + "{}", + serde_json::to_string_pretty(&node.to_value()).unwrap() + ); } else { print!("{}", render(&node, Target::Cli)); } diff --git a/atomic-cli/src/commands/intent/validate.rs b/atomic-cli/src/commands/intent/validate.rs index 96ed7c3d..154b9692 100644 --- a/atomic-cli/src/commands/intent/validate.rs +++ b/atomic-cli/src/commands/intent/validate.rs @@ -85,7 +85,10 @@ impl Command for IntentValidate { } if self.json { - println!("{}", serde_json::to_string_pretty(&report_json(&report)).unwrap()); + println!( + "{}", + serde_json::to_string_pretty(&report_json(&report)).unwrap() + ); } else { print!("{report}"); } @@ -114,7 +117,10 @@ fn is_path_shaped(arg: &str) -> bool { /// `repo_root`. One violation per URN that does not resolve. With no repository /// the check is skipped — the gate still enforces presence; resolution needs a /// change store. (Ported from PR #102, adapted to the top-level `intent validate`.) -fn check_evidence_resolution(evidence: &[(String, String)], repo_root: Option<&Path>) -> Vec<Violation> { +fn check_evidence_resolution( + evidence: &[(String, String)], + repo_root: Option<&Path>, +) -> Vec<Violation> { let mut violations = Vec::new(); if evidence.is_empty() { return violations; @@ -191,7 +197,11 @@ mod evidence_tests { Some(dir.path()), ); assert_eq!(v.len(), 1); - assert!(v[0].message.contains("does not resolve"), "{}", v[0].message); + assert!( + v[0].message.contains("does not resolve"), + "{}", + v[0].message + ); } #[test] diff --git a/atomic-cli/src/commands/memory/attest.rs b/atomic-cli/src/commands/memory/attest.rs index 70b33711..38fccdb9 100644 --- a/atomic-cli/src/commands/memory/attest.rs +++ b/atomic-cli/src/commands/memory/attest.rs @@ -92,8 +92,8 @@ impl Command for MemoryAttest { // absent) + hash + sign. let node = lift_and_attest_memory(&inputs.frontmatter, &inputs.body, &identity, &keypair) .map_err(|e| CliError::InvalidArgument { - message: format!("could not attest memory: {e}"), - })?; + message: format!("could not attest memory: {e}"), + })?; // Belt-and-suspenders: re-gate the ATTESTED node — proof + attributedTo // must now satisfy the gate. @@ -148,7 +148,10 @@ impl Command for MemoryAttest { // yaml_frontmatter_to_json. `sourceContentHash` contains ':' but no // ": " (colon-space), so it round-trips cleanly. let mut fm = serde_json::Map::new(); - fm.insert("memoryId".into(), Value::String(bridge::memory_id(&self.id))); + fm.insert( + "memoryId".into(), + Value::String(bridge::memory_id(&self.id)), + ); fm.insert( "sourceContentHash".into(), Value::String(bridge::source_content_hash(&inputs)), @@ -177,7 +180,10 @@ impl Command for MemoryAttest { .unwrap_or_default(); if self.json { - println!("{}", serde_json::to_string_pretty(&node.to_value()).unwrap()); + println!( + "{}", + serde_json::to_string_pretty(&node.to_value()).unwrap() + ); } else { println!("Attested memory: {}", self.id); println!(" vault: .vault/{vault_path}"); diff --git a/atomic-cli/src/commands/memory/bridge.rs b/atomic-cli/src/commands/memory/bridge.rs index a272b4fe..aa3ca727 100644 --- a/atomic-cli/src/commands/memory/bridge.rs +++ b/atomic-cli/src/commands/memory/bridge.rs @@ -87,8 +87,8 @@ pub fn memory_id(id_or_path: &str) -> String { /// (`serde_json::from_str` into a `Map`). A malformed frontmatter string is a /// clean argument error rather than an internal panic. pub fn inputs_from_entry(entry: &VaultEntry) -> CliResult<MemLiftInputs> { - let frontmatter: Map<String, Value> = serde_json::from_str(&entry.frontmatter_json) - .map_err(|e| CliError::InvalidArgument { + let frontmatter: Map<String, Value> = + serde_json::from_str(&entry.frontmatter_json).map_err(|e| CliError::InvalidArgument { message: format!("memory frontmatter is not valid JSON: {e}"), })?; let body = String::from_utf8_lossy(&entry.content_bytes).into_owned(); @@ -102,9 +102,7 @@ pub fn read_memory(repo: &Repository, id_or_path: &str) -> CliResult<MemLiftInpu .vault_retrieve(&path) .map_err(CliError::Repository)? .ok_or_else(|| CliError::InvalidArgument { - message: format!( - "memory not found: {id_or_path} (create with `atomic memory new`)" - ), + message: format!("memory not found: {id_or_path} (create with `atomic memory new`)"), })?; inputs_from_entry(&entry) } diff --git a/atomic-cli/src/commands/memory/list.rs b/atomic-cli/src/commands/memory/list.rs index 8430431b..e73bc960 100644 --- a/atomic-cli/src/commands/memory/list.rs +++ b/atomic-cli/src/commands/memory/list.rs @@ -153,10 +153,7 @@ fn resolve_verifier(name: &Option<String>) -> CliResult<Option<Verifier>> { /// The DID-match-then-verify rule for a memory. Pure over its inputs so it can be /// unit-tested without a global `IdentityStore`. See the intent list's /// `compute_verifies` for the full rationale — identical rule, `verify_memory`. -fn compute_verifies( - attested: &bridge::Attestation, - verifier: Option<&Verifier>, -) -> Verifies { +fn compute_verifies(attested: &bridge::Attestation, verifier: Option<&Verifier>) -> Verifies { let node = match attested { bridge::Attestation::Fresh(node) => node, bridge::Attestation::Stale(_) | bridge::Attestation::None => return Verifies::Na, @@ -345,7 +342,10 @@ impl Command for MemoryList { /// The width of a column: the widest row cell, but at least the header width. fn col_width(cell_lens: impl Iterator<Item = usize>, header: &str) -> usize { let header_w = header.chars().count(); - cell_lens.chain(std::iter::once(header_w)).max().unwrap_or(header_w) + cell_lens + .chain(std::iter::once(header_w)) + .max() + .unwrap_or(header_w) } /// Is this `memory/…` entry the vault's index scaffold rather than a real diff --git a/atomic-cli/src/commands/memory/mod.rs b/atomic-cli/src/commands/memory/mod.rs index 03e1ba60..de7919e3 100644 --- a/atomic-cli/src/commands/memory/mod.rs +++ b/atomic-cli/src/commands/memory/mod.rs @@ -257,12 +257,19 @@ mod tests { // --- attest: sign + write tracked entry + legacy sidecar ------------- let kp = KeyPair::generate(); let identity = Identity::new("tester", &kp); - let node = - atomic_canonical::lift_and_attest_memory(&inputs.frontmatter, &inputs.body, &identity, &kp) - .unwrap(); + let node = atomic_canonical::lift_and_attest_memory( + &inputs.frontmatter, + &inputs.body, + &identity, + &kp, + ) + .unwrap(); assert!(validate_memory(&node).conforms, "attested node conforms"); verify_memory(&node, &kp.public).expect("self-verify"); - assert_eq!(node.created_at, created_at, "createdAt stable through attest"); + assert_eq!( + node.created_at, created_at, + "createdAt stable through attest" + ); // legacy sidecar let sidecar_path = bridge::attested_sidecar_path(&repo, &id); @@ -307,7 +314,10 @@ mod tests { other => panic!("expected Fresh, got {}", attestation_label(&other)), }; assert!(validate_memory(&fresh).conforms, "attested memory conforms"); - assert_eq!(fresh.created_at, created_at, "createdAt stable through re-read"); + assert_eq!( + fresh.created_at, created_at, + "createdAt stable through re-read" + ); // --- verify: Fresh, verify_memory OK --------------------------------- verify_memory(&fresh, &kp.public).expect("verify Fresh attested node"); @@ -319,7 +329,10 @@ mod tests { rendered.contains("The durable fact."), "rendered text present" ); - assert!(fresh.attributed_to.is_some(), "author present on attested node"); + assert!( + fresh.attributed_to.is_some(), + "author present on attested node" + ); assert!(fresh.proof.is_some(), "proof present on attested node"); // --- regression: `vault memory list` (prefix memory/) does NOT surface @@ -354,11 +367,8 @@ mod tests { .as_object() .unwrap() .clone(); - let node = lift_memory( - &fm, - ":::memory\n<!-- stub comment counts as text -->\n:::", - ) - .unwrap(); + let node = + lift_memory(&fm, ":::memory\n<!-- stub comment counts as text -->\n:::").unwrap(); assert!(!node.text.trim().is_empty()); } } diff --git a/atomic-cli/src/commands/memory/new.rs b/atomic-cli/src/commands/memory/new.rs index 5c3bd858..23641996 100644 --- a/atomic-cli/src/commands/memory/new.rs +++ b/atomic-cli/src/commands/memory/new.rs @@ -82,10 +82,7 @@ impl Command for MemoryNew { let root = find_repository_root()?; let repo = Repository::open(&root).map_err(CliError::Repository)?; - let id = self - .id - .clone() - .unwrap_or_else(generate_ulid_lowercased); + let id = self.id.clone().unwrap_or_else(generate_ulid_lowercased); let vault_path = bridge::normalize_memory_path(&id); // Build the frontmatter SPINE as FLAT SCALAR/array fields only (so it @@ -107,8 +104,8 @@ impl Command for MemoryNew { Value::Array(self.about.iter().cloned().map(Value::String).collect()), ); } - let frontmatter_json = serde_json::to_string(&spine) - .expect("frontmatter spine serialization is infallible"); + let frontmatter_json = + serde_json::to_string(&spine).expect("frontmatter spine serialization is infallible"); // Store the body WITHOUT a frontmatter block; the spine goes through the // frontmatter_json arg. Enters redb + manifest.memory + merkle exactly @@ -216,13 +213,19 @@ mod tests { let entry = repo.vault_retrieve(&vault_path).unwrap().expect("entry"); assert_eq!(entry.entry_type, VaultEntryType::Memory); let fm: Map<String, Value> = serde_json::from_str(&entry.frontmatter_json).unwrap(); - assert_eq!(fm.get("createdAt").and_then(Value::as_str), Some("2026-07-01T00:00:00+00:00")); + assert_eq!( + fm.get("createdAt").and_then(Value::as_str), + Some("2026-07-01T00:00:00+00:00") + ); assert_eq!( fm.get("about").unwrap(), &Value::Array(vec![Value::String("a".into()), Value::String("b".into())]) ); let body = String::from_utf8_lossy(&entry.content_bytes); - assert!(body.contains(":::memory"), "body carries the :::memory container"); + assert!( + body.contains(":::memory"), + "body carries the :::memory container" + ); let node = lift_memory(&fm, &body).expect("scaffold lifts cleanly"); assert_eq!(node.memory_kind, "constraint"); assert_eq!(node.about, vec!["a".to_string(), "b".to_string()]); diff --git a/atomic-cli/src/commands/memory/show.rs b/atomic-cli/src/commands/memory/show.rs index 202d1307..9c5b533c 100644 --- a/atomic-cli/src/commands/memory/show.rs +++ b/atomic-cli/src/commands/memory/show.rs @@ -49,7 +49,10 @@ impl Command for MemoryShow { }; if self.json { - println!("{}", serde_json::to_string_pretty(&node.to_value()).unwrap()); + println!( + "{}", + serde_json::to_string_pretty(&node.to_value()).unwrap() + ); } else { print!("{}", render_memory(&node, Target::Cli)); } diff --git a/atomic-cli/src/commands/memory/validate.rs b/atomic-cli/src/commands/memory/validate.rs index 9262c59a..50ebbe7a 100644 --- a/atomic-cli/src/commands/memory/validate.rs +++ b/atomic-cli/src/commands/memory/validate.rs @@ -70,7 +70,10 @@ impl Command for MemoryValidate { let report = validate_memory(&node); if self.json { - println!("{}", serde_json::to_string_pretty(&report_json(&report)).unwrap()); + println!( + "{}", + serde_json::to_string_pretty(&report_json(&report)).unwrap() + ); } else { print!("{report}"); } diff --git a/atomic-cli/src/commands/provenance/command.rs b/atomic-cli/src/commands/provenance/command.rs index 7a47086b..1fb88649 100644 --- a/atomic-cli/src/commands/provenance/command.rs +++ b/atomic-cli/src/commands/provenance/command.rs @@ -145,10 +145,7 @@ impl Command for ProvenanceShow { /// Load a change's provenance graphs: REV_DEPS-backed lookup, with a disk-scan /// fallback when REV_DEPS registration missed the change. Errors if no graph /// explains the change. -fn load_graphs( - repo: &Repository, - change_hash: &Hash, -) -> CliResult<Vec<(Hash, ProvenanceGraph)>> { +fn load_graphs(repo: &Repository, change_hash: &Hash) -> CliResult<Vec<(Hash, ProvenanceGraph)>> { let mut graphs = repo .find_provenance_for_change(change_hash) .map_err(CliError::Repository)?; @@ -213,10 +210,12 @@ fn resolve_change_target(repo: &Repository, target: &str) -> CliResult<Hash> { /// `atomic intent attest` does. fn resolve_person( identity: Option<&str>, -) -> CliResult<(atomic_identity::identity::Identity, atomic_identity::keypair::KeyPair)> { - let store = IdentityStore::open_default().map_err(|e| { - CliError::Internal(anyhow::anyhow!("Failed to open identity store: {}", e)) - })?; +) -> CliResult<( + atomic_identity::identity::Identity, + atomic_identity::keypair::KeyPair, +)> { + let store = IdentityStore::open_default() + .map_err(|e| CliError::Internal(anyhow::anyhow!("Failed to open identity store: {}", e)))?; let identity = if let Some(name) = identity { store .load_by_name(name) @@ -277,7 +276,10 @@ fn print_trace( ); for (i, (_, graph)) in graphs.iter().enumerate() { if graphs.len() > 1 { - println!("{}", hint(&format!(" [graph {} of {}]", i + 1, graphs.len()))); + println!( + "{}", + hint(&format!(" [graph {} of {}]", i + 1, graphs.len())) + ); } let input = map_graph_to_input(repo, graph, change_hash, person_did); print_activity_chain(repo, &input, graph); @@ -316,7 +318,11 @@ fn print_activity_chain(repo: &Repository, input: &ProvActivityInput, graph: &Pr println!( "{indent} {} {}", hint("agent"), - info(act.get("associatedWith").and_then(|v| v.as_str()).unwrap_or("?")) + info( + act.get("associatedWith") + .and_then(|v| v.as_str()) + .unwrap_or("?") + ) ); println!( "{indent} {} {} ({})", @@ -327,7 +333,11 @@ fn print_activity_chain(repo: &Repository, input: &ProvActivityInput, graph: &Pr println!( "{indent} {} {}", hint("person"), - info(act.get("actedOnBehalfOf").and_then(|v| v.as_str()).unwrap_or("?")) + info( + act.get("actedOnBehalfOf") + .and_then(|v| v.as_str()) + .unwrap_or("?") + ) ); if let Some(parent) = act.get("turnParent").and_then(|v| v.as_str()) { println!("{indent} {} {}", hint("turnParent"), info(parent)); diff --git a/atomic-cli/src/commands/provenance/mapping.rs b/atomic-cli/src/commands/provenance/mapping.rs index 748ed401..eb7e9771 100644 --- a/atomic-cli/src/commands/provenance/mapping.rs +++ b/atomic-cli/src/commands/provenance/mapping.rs @@ -6,9 +6,7 @@ //! //! Read-only, compute-on-demand: mapping never writes anything. -use atomic_canonical::prov::{ - activity_urn, change_urn, normalize_agent_slug, ProvActivityInput, -}; +use atomic_canonical::prov::{activity_urn, change_urn, normalize_agent_slug, ProvActivityInput}; use atomic_core::change::ProvenanceGraph; use atomic_core::types::{Base32, Hash}; use atomic_repository::Repository; diff --git a/atomic-cli/tests/provenance_integration_test.rs b/atomic-cli/tests/provenance_integration_test.rs index 3afa0c66..375b3ffd 100644 --- a/atomic-cli/tests/provenance_integration_test.rs +++ b/atomic-cli/tests/provenance_integration_test.rs @@ -108,8 +108,12 @@ fn create_default_identity(home_dir: &Path) -> atomic_identity::keypair::PublicK fn repo_with_internal_change(repo_dir: &Path, home_dir: &Path) -> Hash { assert!(atomic(repo_dir, home_dir, &["init"]).status.success()); std::fs::write(repo_dir.join("file.txt"), b"v1\n").unwrap(); - assert!(atomic(repo_dir, home_dir, &["add", "file.txt"]).status.success()); - assert!(atomic(repo_dir, home_dir, &["record", "-m", "rec"]).status.success()); + assert!(atomic(repo_dir, home_dir, &["add", "file.txt"]) + .status + .success()); + assert!(atomic(repo_dir, home_dir, &["record", "-m", "rec"]) + .status + .success()); let repo = Repository::open(repo_dir).expect("open repo"); let mut changes = repo.iter_changes(); @@ -198,7 +202,10 @@ fn provenance_show_defaults_unsigned_and_sign_flag_verifies_and_writes_nothing() ); // Default `show` is UNSIGNED — the baseline's "signable, not signed" unit. - assert!(value.get("proof").is_none(), "default show must be unsigned"); + assert!( + value.get("proof").is_none(), + "default show must be unsigned" + ); assert!(value.get("attributedTo").is_none()); assert!(value.get("contentHash").is_none()); @@ -240,7 +247,10 @@ fn provenance_show_defaults_unsigned_and_sign_flag_verifies_and_writes_nothing() ); let trace_out = String::from_utf8(trace.stdout).unwrap(); assert!(trace_out.contains("activity"), "trace shows the activity"); - assert!(trace_out.contains("generated"), "trace shows generated edge"); + assert!( + trace_out.contains("generated"), + "trace shows generated edge" + ); assert!( trace_out.contains(&format!("urn:atomic:change:{}", change_hash.to_base32())), "trace shows the generated change urn" diff --git a/atomic-core/src/pristine/vault.rs b/atomic-core/src/pristine/vault.rs index a9aa929f..24b1657e 100644 --- a/atomic-core/src/pristine/vault.rs +++ b/atomic-core/src/pristine/vault.rs @@ -11,12 +11,12 @@ use std::collections::HashMap; #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum VaultEntryType { - Session, // 0 - ToolResult, // 1 - Memory, // 2 - Intent, // 3 - Skill, // 4 - Scratch, // 5 + Session, // 0 + ToolResult, // 1 + Memory, // 2 + Intent, // 3 + Skill, // 4 + Scratch, // 5 /// Signed Recording-the-Why attestation (JSON-LD body). Index 6 — APPEND-ONLY. /// postcard encodes enum discriminants positionally, so this MUST stay last and /// MUST NOT be reordered/inserted/deleted. Mixed-version sync caveat: an older diff --git a/atomic-repository/src/repository/vault.rs b/atomic-repository/src/repository/vault.rs index 0b6b2cad..a844f6b0 100644 --- a/atomic-repository/src/repository/vault.rs +++ b/atomic-repository/src/repository/vault.rs @@ -1499,7 +1499,10 @@ mod tests { // storage-hash semantics). assert_eq!(stored_hash, Hash::of(&body_bytes)); let retrieved = repo.vault_retrieve(path).unwrap().unwrap(); - assert_eq!(Hash::from_bytes(retrieved.content_hash), Hash::of(&body_bytes)); + assert_eq!( + Hash::from_bytes(retrieved.content_hash), + Hash::of(&body_bytes) + ); // Materialize to disk, then scan: the materialized body must hash back to // the exact same value, so the entry is Unchanged (no change reported). diff --git a/atomic-repository/src/repository/vault_triples.rs b/atomic-repository/src/repository/vault_triples.rs index 4f1e9a41..640c983c 100644 --- a/atomic-repository/src/repository/vault_triples.rs +++ b/atomic-repository/src/repository/vault_triples.rs @@ -1021,7 +1021,10 @@ mod tests { "skill:run-tests" ); assert_eq!( - entry_subject("attestations/PIMO-1/attested.md", VaultEntryType::Attestation), + entry_subject( + "attestations/PIMO-1/attested.md", + VaultEntryType::Attestation + ), "attestation:PIMO-1" ); } From 03651bf11b4ab62d647ea6b1648891836fdc0f71 Mon Sep 17 00:00:00 2001 From: Bradley Hilton <graywolf336@craftyn.com> Date: Thu, 9 Jul 2026 11:27:49 -0500 Subject: [PATCH 16/21] fix(ci): clippy sort_by_key, ambiguous render doc link, Windows test gate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - provenance command: sort_by → sort_by_key(Reverse) (clippy -D warnings). - atomic-canonical lib docs: [`render`] was ambiguous (module vs re-exported fn) — disambiguate with mod@ (rustdoc -D broken-intra-doc-links). - provenance integration tests: excluded on Windows — they isolate the identity store via the HOME env var, which dirs::home_dir() ignores on Windows (FOLDERID_Profile), so the store cannot be redirected from a test. An explicit identity-store override would lift this. --- atomic-canonical/src/lib.rs | 2 +- atomic-cli/src/commands/provenance/command.rs | 2 +- atomic-cli/tests/provenance_integration_test.rs | 6 ++++++ 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/atomic-canonical/src/lib.rs b/atomic-canonical/src/lib.rs index 2c73dacd..49a98b73 100644 --- a/atomic-canonical/src/lib.rs +++ b/atomic-canonical/src/lib.rs @@ -9,7 +9,7 @@ //! Three layers, kept apart: //! - **surface** — markdown the author writes (frontmatter spine + directives) //! - **canonical** — the typed node that gets hashed and signed ([`node`]) -//! - **render** — the read-time projection ([`render`]) +//! - **render** — the read-time projection ([`render`](mod@render)) //! //! Load-bearing principles enforced here: *presence is enforced, content is //! left honest* (the `why` is never schematized); *the vocabulary is closed* diff --git a/atomic-cli/src/commands/provenance/command.rs b/atomic-cli/src/commands/provenance/command.rs index 1fb88649..431f757b 100644 --- a/atomic-cli/src/commands/provenance/command.rs +++ b/atomic-cli/src/commands/provenance/command.rs @@ -164,7 +164,7 @@ fn load_graphs(repo: &Repository, change_hash: &Hash) -> CliResult<Vec<(Hash, Pr } // Most-recent first (a change explained by >1 graph shows all; the newest // leads). Both loaders sort/return unspecified order, so sort here. - graphs.sort_by(|(_, a), (_, b)| b.timestamp.cmp(&a.timestamp)); + graphs.sort_by_key(|(_, g)| std::cmp::Reverse(g.timestamp)); Ok(graphs) } diff --git a/atomic-cli/tests/provenance_integration_test.rs b/atomic-cli/tests/provenance_integration_test.rs index 375b3ffd..10967a95 100644 --- a/atomic-cli/tests/provenance_integration_test.rs +++ b/atomic-cli/tests/provenance_integration_test.rs @@ -16,6 +16,12 @@ //! The REV_DEPS fallback is exercised too: a graph whose explained change was //! never made internal is invisible to REV_DEPS, and the disk-scan fallback //! still finds it. +//! +//! Windows is excluded: the tests isolate the identity store by pointing `HOME` +//! at a temp dir, but on Windows `dirs::home_dir()` resolves via the system API +//! (FOLDERID_Profile) and ignores the env var, so the store cannot be redirected +//! from a test. An explicit identity-store override (env/flag) would lift this. +#![cfg(not(windows))] use std::collections::BTreeSet; use std::path::Path; From 97affec2c7d6a04bb510e97a4a5ddbbc34b436a1 Mon Sep 17 00:00:00 2001 From: Bradley Hilton <graywolf336@craftyn.com> Date: Thu, 9 Jul 2026 11:45:26 -0500 Subject: [PATCH 17/21] fix(ci): remaining clippy/doc failures across the merged tree - changes.rs: qualify the find_provenance_for_change intra-doc link with Self:: (rustdoc -D broken-intra-doc-links). - atomic-semantic java parser: drop redundant &name refs in format! args (clippy redundant reference; pre-existing on dev, but CI halts the workspace clippy run on it). - atomic-repository provenance_summary tests: struct-init instead of mutating a Default::default() instance (clippy field_reassign_with_default; also pre-existing on dev, surfaced once the workspace run got past atomic-semantic). Full-workspace cargo clippy --all-targets -D warnings, rustdoc -D warnings, and fmt --check are now clean locally; affected crates' tests pass. --- atomic-repository/src/repository/changes.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/atomic-repository/src/repository/changes.rs b/atomic-repository/src/repository/changes.rs index 6cb1454a..34910d07 100644 --- a/atomic-repository/src/repository/changes.rs +++ b/atomic-repository/src/repository/changes.rs @@ -768,7 +768,7 @@ impl Repository { /// Find all provenance graphs that explain a change by scanning disk. /// - /// A read-only fallback for [`find_provenance_for_change`]: REV_DEPS + /// A read-only fallback for [`Self::find_provenance_for_change`]: REV_DEPS /// registration is best-effort (`save_provenance_graph` records the reverse /// dependency only when the explained change is already internal), so a graph /// whose change was not yet internal is invisible to REV_DEPS. This iterates From b937f155c7bd2d51e6ba591dab172bedf26cd797 Mon Sep 17 00:00:00 2001 From: Bradley Hilton <graywolf336@craftyn.com> Date: Thu, 9 Jul 2026 11:57:45 -0500 Subject: [PATCH 18/21] fix(ci): rust 1.97 clippy lints (question_mark, redundant format! refs) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CI's dtolnay/rust-toolchain@stable is rustc 1.97, whose clippy carries lints older toolchains don't — updated the local toolchain to match and cleaned the whole workspace in one pass: - changestore/iterators.rs: the if-let-else-return-None over current_files in both next_from_files impls becomes current_files.as_mut()? (question_mark; clippy's own suggestion would move out of self — as_mut is the correct form). - git/parallel.rs: drop redundant &info.short_sha refs in format! args. Both pre-existing on dev; each failing crate halted the workspace clippy run and hid the next, so this pass was verified with the full workspace + --all-targets on 1.97: clippy -D warnings, rustdoc -D warnings, and fmt --check all clean; atomic-repository/atomic-cli tests pass. --- Cargo.lock | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Cargo.lock b/Cargo.lock index fc78d6d4..5643161c 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -143,7 +143,7 @@ dependencies = [ [[package]] name = "atomic-canonical" -version = "0.8.0" +version = "0.9.0" dependencies = [ "atomic-identity", "blake3", From e6ceea603825d40ade0e425c76a90b5c21e915ef Mon Sep 17 00:00:00 2001 From: Bradley Hilton <graywolf336@craftyn.com> Date: Tue, 14 Jul 2026 15:55:33 -0500 Subject: [PATCH 19/21] chore: sync Cargo.lock after rebase onto dev (0.9.1) --- Cargo.lock | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/Cargo.lock b/Cargo.lock index 5643161c..bb5e0ca0 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -143,10 +143,11 @@ dependencies = [ [[package]] name = "atomic-canonical" -version = "0.9.0" +version = "0.9.1" dependencies = [ "atomic-identity", "blake3", + "bs58", "chrono", "data-encoding", "serde", @@ -410,6 +411,15 @@ dependencies = [ "generic-array", ] +[[package]] +name = "bs58" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bf88ba1141d185c399bee5288d850d63b8369520c1eafc32a0430b5b6c287bf4" +dependencies = [ + "tinyvec", +] + [[package]] name = "bstr" version = "1.12.3" From 3d54e6378516699c7049b3184881e557471864bf Mon Sep 17 00:00:00 2001 From: Bradley Hilton <graywolf336@craftyn.com> Date: Wed, 15 Jul 2026 15:35:06 -0500 Subject: [PATCH 20/21] feat(cli): deprecate `atomic vault intent` in favor of `atomic intent` --- atomic-cli/src/commands/vault/intent.rs | 55 +++++++++++++++++++++---- atomic-cli/src/commands/vault/mod.rs | 6 ++- 2 files changed, 53 insertions(+), 8 deletions(-) diff --git a/atomic-cli/src/commands/vault/intent.rs b/atomic-cli/src/commands/vault/intent.rs index 1e92f1c5..7a5dbe28 100644 --- a/atomic-cli/src/commands/vault/intent.rs +++ b/atomic-cli/src/commands/vault/intent.rs @@ -1,5 +1,12 @@ //! `atomic vault intent` — manage vault intents (tasks). //! +//! DEPRECATED: this command family is superseded by the canonical +//! `atomic intent` commands (`atomic intent new/show/list/validate/ +//! attest/verify`), which scaffold the full acceptance-criteria / why / +//! tasks template. `atomic vault intent create` only produces a bare, +//! title-only intent. These commands still work but emit a deprecation +//! warning; prefer `atomic intent` for new work. +//! //! Intents represent planned work items that can be linked to goals. //! They track status, priority, assignee, and related goals. //! @@ -81,7 +88,11 @@ fn resolve_active_session(repo: &Repository) -> Option<(String, u32)> { /// Subcommands for intent management. #[derive(Subcommand, Debug)] pub enum IntentCommands { - /// Create a new intent. + /// [DEPRECATED: use `atomic intent new`] Create a new intent. + /// + /// Deprecated: `atomic vault intent create` produces a bare, + /// title-only intent. Use `atomic intent new`, which scaffolds the + /// full acceptance-criteria / why / tasks template. /// /// Creates an intent (task) with a title and optional metadata. /// Intents can be linked to goals to track which work addresses them. @@ -94,7 +105,7 @@ pub enum IntentCommands { /// ``` Create(IntentCreate), - /// List intents. + /// [DEPRECATED: use `atomic intent list`] List intents. /// /// Shows intents filtered by status. Defaults to showing all intents. /// @@ -106,7 +117,7 @@ pub enum IntentCommands { /// ``` List(IntentList), - /// Show an intent's content. + /// [DEPRECATED: use `atomic intent show`] Show an intent's content. /// /// Displays the full content of an intent by its ID. /// @@ -118,7 +129,7 @@ pub enum IntentCommands { /// ``` Show(IntentShow), - /// Update an intent's fields. + /// [DEPRECATED: use the `atomic intent` family] Update an intent's fields. /// /// Modifies the status, assignee, priority, title, or Markdown body /// of an existing intent. The body can be set inline with `--body` @@ -134,7 +145,7 @@ pub enum IntentCommands { /// ``` Update(IntentUpdate), - /// Delete an unstarted backlog intent. + /// [DEPRECATED: use the `atomic intent` family] Delete an unstarted backlog intent. /// /// Removes an accidental draft intent from the vault. Only backlog /// intents with no linked goals can be deleted. Use --force to skip the @@ -148,7 +159,7 @@ pub enum IntentCommands { /// ``` Delete(IntentDelete), - /// Link a goal to an intent. + /// [DEPRECATED: use the `atomic intent` family] Link a goal to an intent. /// /// Associates a goal with an intent so that the work done in the goal /// is tracked against the intent. @@ -163,7 +174,11 @@ pub enum IntentCommands { // Intent Command -/// Manage vault intents (tasks). +/// [DEPRECATED: use `atomic intent`] Manage vault intents (tasks). +/// +/// Deprecated in favor of the canonical `atomic intent` family +/// (`atomic intent new/show/list/validate/attest/verify`), which +/// scaffolds the full acceptance-criteria / why / tasks template. /// /// Intents represent planned work items that can be linked to goals. /// They track status, priority, assignee, and related goals. @@ -176,6 +191,32 @@ pub struct Intent { impl Command for Intent { fn run(&self) -> CliResult<()> { + // Emit a one-time deprecation notice steering users to the + // canonical `atomic intent` family (Recording the Why), which + // scaffolds the full acceptance-criteria / why / tasks template. + let msg = match &self.command { + IntentCommands::Create(_) => { + "`atomic vault intent create` is deprecated; use `atomic intent new` instead \ + (it scaffolds acceptance criteria / why / tasks)." + } + IntentCommands::List(_) => { + "`atomic vault intent list` is deprecated; use `atomic intent list` instead." + } + IntentCommands::Show(_) => { + "`atomic vault intent show` is deprecated; use `atomic intent show` instead." + } + IntentCommands::Update(_) => { + "`atomic vault intent update` is deprecated; use the `atomic intent` family instead." + } + IntentCommands::Delete(_) => { + "`atomic vault intent delete` is deprecated; use the `atomic intent` family instead." + } + IntentCommands::Link(_) => { + "`atomic vault intent link` is deprecated; use the `atomic intent` family instead." + } + }; + eprintln!("warning: {msg}"); + match &self.command { IntentCommands::Create(cmd) => cmd.run(), IntentCommands::List(cmd) => cmd.run(), diff --git a/atomic-cli/src/commands/vault/mod.rs b/atomic-cli/src/commands/vault/mod.rs index 9423a946..cba52033 100644 --- a/atomic-cli/src/commands/vault/mod.rs +++ b/atomic-cli/src/commands/vault/mod.rs @@ -156,7 +156,11 @@ pub enum VaultCommands { /// ``` Goal(Goal), - /// Manage vault intents (tasks). + /// [DEPRECATED: use `atomic intent`] Manage vault intents (tasks). + /// + /// Deprecated in favor of the canonical `atomic intent` family + /// (`atomic intent new/show/list/validate/attest/verify`), which + /// scaffolds the full acceptance-criteria / why / tasks template. /// /// Intents are lightweight task descriptions that can be linked /// to goals. From 06f0a95506dec9fd5deb5233ee66cc63af37048c Mon Sep 17 00:00:00 2001 From: Bradley Hilton <graywolf336@craftyn.com> Date: Wed, 15 Jul 2026 16:31:22 -0500 Subject: [PATCH 21/21] feat(cli): complete the atomic intent family (update/delete/link) Add the update, delete, and link verbs to the canonical `atomic intent` command family so it fully supersedes `atomic vault intent`. Each new verb delegates to the same atomic-repository write path as its vault counterpart (vault_intent_update / vault_intent_delete / vault_intent_link), so behavior is identical; the flags mirror the vault versions exactly. Now that direct replacements exist, sharpen the vault-intent deprecation help text and runtime warnings for update/delete/link to name the specific new commands instead of the vague "atomic intent family". --- atomic-cli/src/commands/intent/delete.rs | 74 ++++++++++++++ atomic-cli/src/commands/intent/link.rs | 40 ++++++++ atomic-cli/src/commands/intent/mod.rs | 59 +++++++++++ atomic-cli/src/commands/intent/update.rs | 120 +++++++++++++++++++++++ atomic-cli/src/commands/vault/intent.rs | 12 +-- 5 files changed, 299 insertions(+), 6 deletions(-) create mode 100644 atomic-cli/src/commands/intent/delete.rs create mode 100644 atomic-cli/src/commands/intent/link.rs create mode 100644 atomic-cli/src/commands/intent/update.rs diff --git a/atomic-cli/src/commands/intent/delete.rs b/atomic-cli/src/commands/intent/delete.rs new file mode 100644 index 00000000..a4a03843 --- /dev/null +++ b/atomic-cli/src/commands/intent/delete.rs @@ -0,0 +1,74 @@ +//! `atomic intent delete <ID>` — discard an unstarted backlog intent. +//! +//! The canonical-family analogue of `atomic vault intent delete`. It delegates +//! to the exact same [`Repository::vault_intent_delete`] path (and the same +//! "unstarted backlog, no linked goals" guard it enforces), so its behavior is +//! byte-for-byte identical to the vault verb it supersedes. + +use clap::Parser; + +use atomic_repository::Repository; + +use crate::commands::{find_repository_root, Command}; +use crate::error::{CliError, CliResult}; + +/// Delete an unstarted backlog intent. +/// +/// Removes an intent that has not left backlog and has no linked goals. Use this +/// for accidental drafts only; started work should be closed or superseded +/// instead of deleted. Without `--force`, prompts for confirmation. +#[derive(Parser, Debug)] +#[command(name = "delete")] +pub struct IntentDelete { + /// Intent ID (e.g. "PIMO-1" or "1"). + pub id: String, + + /// Skip the confirmation prompt. + #[arg(long, short = 'f')] + pub force: bool, + + /// Output as JSON. + #[arg(long)] + pub json: bool, +} + +impl Command for IntentDelete { + fn run(&self) -> CliResult<()> { + let root = find_repository_root()?; + let repo = Repository::open(&root).map_err(CliError::Repository)?; + + if !self.force { + let prompt = format!( + "Discard intent '{}'? This removes the unstarted draft from the vault.", + self.id + ); + let confirmed = dialoguer::Confirm::new() + .with_prompt(&prompt) + .default(false) + .interact() + .map_err(|e| CliError::Internal(anyhow::anyhow!("Prompt failed: {}", e)))?; + + if !confirmed { + return Err(CliError::Cancelled); + } + } + + let result = repo + .vault_intent_delete(&self.id) + .map_err(CliError::Repository)?; + + if self.json { + let json = serde_json::json!({ + "id": result.id, + "intent_file": result.intent_file, + "deleted": true, + }); + println!("{}", serde_json::to_string_pretty(&json).unwrap()); + } else { + println!("Deleted intent: {}", result.id); + println!(" file: .vault/{}", result.intent_file); + } + + Ok(()) + } +} diff --git a/atomic-cli/src/commands/intent/link.rs b/atomic-cli/src/commands/intent/link.rs new file mode 100644 index 00000000..7dc70364 --- /dev/null +++ b/atomic-cli/src/commands/intent/link.rs @@ -0,0 +1,40 @@ +//! `atomic intent link <ID> --goal <GOAL>` — link a goal to a stored intent. +//! +//! The canonical-family analogue of `atomic vault intent link`. It delegates to +//! the exact same [`Repository::vault_intent_link`] path, so its behavior is +//! byte-for-byte identical to the vault verb it supersedes. + +use clap::Parser; + +use atomic_repository::Repository; + +use crate::commands::{find_repository_root, Command}; +use crate::error::{CliError, CliResult}; + +/// Link a goal to an intent. +/// +/// Associates a goal with an intent so that the work done in the goal is tracked +/// against the intent. +#[derive(Parser, Debug)] +#[command(name = "link")] +pub struct IntentLink { + /// Intent ID (e.g. "PIMO-1" or "1"). + pub id: String, + + /// Goal name to link. + #[arg(long)] + pub goal: String, +} + +impl Command for IntentLink { + fn run(&self) -> CliResult<()> { + let root = find_repository_root()?; + let repo = Repository::open(&root).map_err(CliError::Repository)?; + + repo.vault_intent_link(&self.id, &self.goal) + .map_err(CliError::Repository)?; + println!("Linked goal '{}' to intent '{}'", self.goal, self.id); + + Ok(()) + } +} diff --git a/atomic-cli/src/commands/intent/mod.rs b/atomic-cli/src/commands/intent/mod.rs index ca8758d8..a0ddfa58 100644 --- a/atomic-cli/src/commands/intent/mod.rs +++ b/atomic-cli/src/commands/intent/mod.rs @@ -15,6 +15,10 @@ //! atomic intent new <TITLE> Scaffold a directive-based intent //! atomic intent attest <ID> Sign an intent into a tracked attestation entry //! atomic intent verify <ID> Verify a signed intent's attestation +//! atomic intent list List the vault's intents (attestation-aware) +//! atomic intent update <ID> Update a stored intent's fields +//! atomic intent delete <ID> Delete an unstarted backlog intent +//! atomic intent link <ID> --goal <G> Link a goal to a stored intent //! ``` //! //! # Persistence — additive by construction @@ -31,16 +35,22 @@ use crate::error::CliResult; pub mod attest; pub mod bridge; +pub mod delete; +pub mod link; pub mod list; pub mod new; pub mod show; +pub mod update; pub mod validate; pub mod verify; pub use attest::IntentAttest; +pub use delete::IntentDelete; +pub use link::IntentLink; pub use list::IntentList; pub use new::IntentNew; pub use show::IntentShow; +pub use update::IntentUpdate; pub use validate::IntentValidate; pub use verify::IntentVerify; @@ -146,6 +156,52 @@ pub enum IntentCommands { /// atomic intent list --json /// ``` List(IntentList), + + /// Update a stored intent's fields (status, priority, title, body). + /// + /// The canonical-family replacement for `atomic vault intent update`. It + /// delegates to the same repository write path, so the frontmatter/body + /// updates and the started-or-linked guard (behind `--force`) behave + /// identically. The body can be set inline with `--body` or piped via + /// `--body-stdin`. + /// + /// # Examples + /// + /// ```text + /// atomic intent update PIMO-1 --status in-progress + /// atomic intent update PIMO-1 --assignee bob --priority critical + /// atomic intent update PIMO-1 --body "# Fix auth\n\n## Problem\n..." + /// cat plan.md | atomic intent update PIMO-1 --body-stdin + /// ``` + Update(IntentUpdate), + + /// Delete an unstarted backlog intent. + /// + /// The canonical-family replacement for `atomic vault intent delete`. It + /// delegates to the same repository path and enforces the same guard: only + /// backlog intents with no linked goals can be deleted. Use `--force` to + /// skip the confirmation prompt. + /// + /// # Examples + /// + /// ```text + /// atomic intent delete PIMO-1 + /// atomic intent delete PIMO-1 --force + /// ``` + Delete(IntentDelete), + + /// Link a goal to a stored intent. + /// + /// The canonical-family replacement for `atomic vault intent link`. It + /// delegates to the same repository path, associating a goal with an intent + /// so the work done in the goal is tracked against the intent. + /// + /// # Examples + /// + /// ```text + /// atomic intent link PIMO-1 --goal swift-meadow-a3f2 + /// ``` + Link(IntentLink), } /// Record the "why": lift, validate, attest, and render canonical intents. @@ -169,6 +225,9 @@ impl Command for Intent { IntentCommands::Attest(cmd) => cmd.run(), IntentCommands::Verify(cmd) => cmd.run(), IntentCommands::List(cmd) => cmd.run(), + IntentCommands::Update(cmd) => cmd.run(), + IntentCommands::Delete(cmd) => cmd.run(), + IntentCommands::Link(cmd) => cmd.run(), } } } diff --git a/atomic-cli/src/commands/intent/update.rs b/atomic-cli/src/commands/intent/update.rs new file mode 100644 index 00000000..58adb409 --- /dev/null +++ b/atomic-cli/src/commands/intent/update.rs @@ -0,0 +1,120 @@ +//! `atomic intent update <ID>` — update a stored intent's fields. +//! +//! The canonical-family analogue of `atomic vault intent update`. It delegates +//! to the exact same [`Repository::vault_intent_update`] write path, so its +//! behavior (frontmatter/status/priority/title updates, body replacement, the +//! started-or-linked guard behind `--force`) is byte-for-byte identical to the +//! vault verb it supersedes. + +use clap::Parser; + +use atomic_repository::{IntentUpdateOptions, Repository}; + +use crate::commands::{find_repository_root, Command}; +use crate::error::{CliError, CliResult}; + +/// Update an intent's fields. +/// +/// Modifies the status, assignee, priority, title, or Markdown body of an +/// existing intent. The body can be set inline with `--body` or piped via +/// `--body-stdin`. +#[derive(Parser, Debug)] +#[command(name = "update")] +pub struct IntentUpdate { + /// Intent ID (e.g. "PIMO-1" or "1"). + pub id: String, + + /// New status. + #[arg(long)] + pub status: Option<String>, + + /// New assignee. + #[arg(long)] + pub assignee: Option<String>, + + /// New priority. + #[arg(long)] + pub priority: Option<String>, + + /// New title. + #[arg(long)] + pub title: Option<String>, + + /// New Markdown body content, provided inline. + #[arg(long, conflicts_with = "body_stdin")] + pub body: Option<String>, + + /// Read the new Markdown body content from standard input. + #[arg(long)] + pub body_stdin: bool, + + /// Rewrite the body even if the intent has started or is linked to a goal. + #[arg(long, short = 'f')] + pub force: bool, +} + +impl IntentUpdate { + fn resolve_body(&self) -> CliResult<Option<String>> { + if let Some(ref body) = self.body { + return Ok(Some(body.clone())); + } + if self.body_stdin { + use std::io::Read; + let mut content = String::new(); + std::io::stdin() + .read_to_string(&mut content) + .map_err(CliError::Io)?; + return Ok(Some(content)); + } + Ok(None) + } +} + +impl Command for IntentUpdate { + fn run(&self) -> CliResult<()> { + let root = find_repository_root()?; + let repo = Repository::open(&root).map_err(CliError::Repository)?; + + let content = self.resolve_body()?; + if self.status.is_none() + && self.assignee.is_none() + && self.priority.is_none() + && self.title.is_none() + && content.is_none() + { + return Err(CliError::InvalidArgument { + message: "Nothing to update. Provide at least one of \ + --status, --assignee, --priority, --title, --body, \ + or --body-stdin." + .to_string(), + }); + } + + let body_updated = content.is_some(); + let info = repo + .vault_intent_update( + &self.id, + IntentUpdateOptions { + status: self.status.clone(), + assignee: self.assignee.clone(), + priority: self.priority.clone(), + title: self.title.clone(), + content, + force: self.force, + }, + ) + .map_err(CliError::Repository)?; + + println!("Updated intent: {}", info.id); + println!(" status: {}", info.status); + println!(" priority: {}", info.priority); + if let Some(ref assignee) = info.assignee { + println!(" assignee: {}", assignee); + } + if body_updated { + println!(" body: updated"); + } + + Ok(()) + } +} diff --git a/atomic-cli/src/commands/vault/intent.rs b/atomic-cli/src/commands/vault/intent.rs index 7a5dbe28..70542f8c 100644 --- a/atomic-cli/src/commands/vault/intent.rs +++ b/atomic-cli/src/commands/vault/intent.rs @@ -129,7 +129,7 @@ pub enum IntentCommands { /// ``` Show(IntentShow), - /// [DEPRECATED: use the `atomic intent` family] Update an intent's fields. + /// [DEPRECATED: use `atomic intent update`] Update an intent's fields. /// /// Modifies the status, assignee, priority, title, or Markdown body /// of an existing intent. The body can be set inline with `--body` @@ -145,7 +145,7 @@ pub enum IntentCommands { /// ``` Update(IntentUpdate), - /// [DEPRECATED: use the `atomic intent` family] Delete an unstarted backlog intent. + /// [DEPRECATED: use `atomic intent delete`] Delete an unstarted backlog intent. /// /// Removes an accidental draft intent from the vault. Only backlog /// intents with no linked goals can be deleted. Use --force to skip the @@ -159,7 +159,7 @@ pub enum IntentCommands { /// ``` Delete(IntentDelete), - /// [DEPRECATED: use the `atomic intent` family] Link a goal to an intent. + /// [DEPRECATED: use `atomic intent link`] Link a goal to an intent. /// /// Associates a goal with an intent so that the work done in the goal /// is tracked against the intent. @@ -206,13 +206,13 @@ impl Command for Intent { "`atomic vault intent show` is deprecated; use `atomic intent show` instead." } IntentCommands::Update(_) => { - "`atomic vault intent update` is deprecated; use the `atomic intent` family instead." + "`atomic vault intent update` is deprecated; use `atomic intent update` instead." } IntentCommands::Delete(_) => { - "`atomic vault intent delete` is deprecated; use the `atomic intent` family instead." + "`atomic vault intent delete` is deprecated; use `atomic intent delete` instead." } IntentCommands::Link(_) => { - "`atomic vault intent link` is deprecated; use the `atomic intent` family instead." + "`atomic vault intent link` is deprecated; use `atomic intent link` instead." } }; eprintln!("warning: {msg}");