diff --git a/Cargo.lock b/Cargo.lock index ab22a2bd..de5645aa 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -453,6 +453,7 @@ dependencies = [ "atomic-identity", "atomic-objects", "atomic-semantic", + "atomic-shacl", "blake3", "chrono", "data-encoding", diff --git a/atomic-canonical/src/lib.rs b/atomic-canonical/src/lib.rs index ddfcb90a..a7b6b60a 100644 --- a/atomic-canonical/src/lib.rs +++ b/atomic-canonical/src/lib.rs @@ -104,3 +104,4 @@ pub fn verify_memory( ) -> Result<()> { proof::verify_memory(node, public_key) } +pub mod publication_review; diff --git a/atomic-canonical/src/publication_review.rs b/atomic-canonical/src/publication_review.rs new file mode 100644 index 00000000..9c8e3ab7 --- /dev/null +++ b/atomic-canonical/src/publication_review.rs @@ -0,0 +1,195 @@ +//! Present-day review of retained evidence, never an original capture claim. +use crate::node::Proof; +use serde::{Deserialize, Serialize}; + +pub const LEGACY_SCHEMA: &str = "atomic.publication-review.v1"; +pub const SCHEMA: &str = "atomic.publication-review.v2"; +pub const MAX_BYTES: usize = 1024 * 1024; + +/// Exact signed intent revision and the source inputs it must still describe. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct IntentPin { + pub id: String, + pub source_hash: String, + pub signed_hash: String, + pub public_key: String, +} + +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct ChangePin { + pub hash: String, + pub session: Option, + /// Reserved legacy field. The review resolver never derives authority from it. + pub governing_intents: Vec, + pub provenance: Vec, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub observations: Vec, +} + +/// A source-pinned observation, not a claim of original governing authority. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct IntentObservationPin { + #[serde(default, skip_serializing_if = "ObservationRole::is_work")] + pub role: ObservationRole, + pub provenance: String, + pub node: String, + pub session: String, + pub turns: Vec, + pub kind: String, + /// Exact receipt identifier; not a filename or timestamp inference. + pub reference: String, + pub intent: Option, + /// resolved, unresolved, or ambiguous; none means no generating-turn binding. + pub resolution: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub diagnostic: Option, + /// Independently verified retained signed document. Historical does not mean + /// fresh current source, and this is not an implementation authorization. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub retained_revision: Option, +} + +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct SignedRevisionPin { + pub signed_hash: String, + pub public_key: String, + pub source_relation: String, +} + +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "kebab-case")] +pub enum ObservationRole { + #[default] + Work, + /// Only the exact selected review intent, never arbitrary observed work. + ReviewContext, +} + +impl ObservationRole { + fn is_work(&self) -> bool { + matches!(self, Self::Work) + } +} + +/// Immutable approval scope. Every digest participates in the outer signature. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct ReviewSubject { + pub project: String, + pub roots: Vec, + pub changes: Vec, + pub review: IntentPin, + pub work: Vec, + /// Independently reviewed terminal dispositions, not approved implementations. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub set_aside: Vec, + pub profile_hash: String, + /// Selected perspective and all inherited state pins; unrelated reviewer + /// artifact records should live on a separate review view. + pub view_chain: Vec, + /// Effective membership identity, including inherited changes. + pub effective_set_id: String, + /// Signed, view-independent source context. Names above are historical + /// labels; this evidence, not continued view existence, proves the context. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub snapshot: Option, +} + +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct ReviewSnapshot { + pub version: u32, + /// Ordered own-log hashes corresponding one-for-one to view_chain. + pub view_logs: Vec>, + /// Sorted unique full effective projection closure, including ancestors. + pub membership: Vec, + pub intent_revisions: Vec, +} + +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct RetainedIntentRevision { + pub id: String, + pub frontmatter: serde_json::Map, + pub body: String, + pub document: serde_json::Value, +} + +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct ReviewViewPin { + pub name: String, + pub state: String, + pub scope: String, +} + +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct PublicationReview { + pub schema: String, + /// This timestamp means review now, not capture in the original session. + pub reviewed_at: String, + pub subject: ReviewSubject, + /// Authenticated renewal; old signed objects remain retained and inspectable. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub supersedes: Vec, + #[serde(rename = "attributedTo")] + pub attributed_to: String, + #[serde( + rename = "contentHash", + default, + skip_serializing_if = "Option::is_none" + )] + pub content_hash: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub proof: Option, +} + +impl PublicationReview { + /// Admit untrusted bytes before parsing, including duplicate-key/depth checks. + pub fn parse(bytes: &[u8]) -> crate::Result { + if bytes.len() > MAX_BYTES { + return Err(crate::CanonicalError::Proof( + "publication review exceeds 1 MiB".into(), + )); + } + let review: Self = + serde_json::from_value(crate::jcs::admit_document(bytes)?).map_err(|error| { + crate::CanonicalError::Proof(format!("invalid publication review: {error}")) + })?; + if review.schema != SCHEMA && review.schema != LEGACY_SCHEMA { + return Err(crate::CanonicalError::Proof( + "unsupported publication review schema".into(), + )); + } + if review.schema == SCHEMA && review.subject.snapshot.is_none() { + return Err(crate::CanonicalError::Proof( + "v2 publication review requires retained source evidence".into(), + )); + } + if review.schema == LEGACY_SCHEMA && review.subject.snapshot.is_some() { + return Err(crate::CanonicalError::Proof( + "legacy publication review cannot claim v2 snapshot semantics".into(), + )); + } + Ok(review) + } + + /// The exact document passed through Atomic's common signing path. + pub fn value(&self) -> serde_json::Value { + serde_json::to_value(self).expect("review serialization") + } + + /// Content address of the entire signed artifact, including its proof. + pub fn artifact_hash(&self) -> String { + let mut hash = blake3::Hasher::new(); + hash.update(self.schema.as_bytes()); + hash.update(b"\0"); + hash.update(crate::jcs::canonicalize(&self.value()).as_bytes()); + hash.finalize().to_hex().to_string() + } +} diff --git a/atomic-canonical/src/vocab.rs b/atomic-canonical/src/vocab.rs index ac632610..3a85ecb7 100644 --- a/atomic-canonical/src/vocab.rs +++ b/atomic-canonical/src/vocab.rs @@ -40,8 +40,10 @@ impl NodeType { /// Intent status value set (mirrors the doc's `IntentShape` `sh:in`). /// `needs-review` is the review handoff — implementation complete (every /// task done, every criterion met) and signed, awaiting independent review; -/// `done` is granted by that review. `icebox` is a terminal state (an intent -/// reviewed and set aside — not built). +/// `done` is granted by that review. `icebox` is a terminal disposition: reviewed +/// and set aside, not an active delivery requirement. Historical implementation +/// and execution evidence remain history; this does not assert those goals hold +/// in the current product. pub const INTENT_STATUS: &[&str] = &[ "backlog", "todo", diff --git a/atomic-cli/Cargo.toml b/atomic-cli/Cargo.toml index 5ca6a61f..3d6bb7b9 100644 --- a/atomic-cli/Cargo.toml +++ b/atomic-cli/Cargo.toml @@ -36,7 +36,7 @@ atomic-config = { workspace = true } atomic-identity = { workspace = true } atomic-objects = { workspace = true } atomic-remote = { workspace = true } -atomic-repository = { workspace = true } +atomic-repository = { workspace = true, features = ["review-shacl"] } libatomic = { workspace = true } atomic-client = { workspace = true } tonic = { workspace = true } diff --git a/atomic-cli/src/commands/intent/graph.rs b/atomic-cli/src/commands/intent/graph.rs index d8bc7f69..bf0b7055 100644 --- a/atomic-cli/src/commands/intent/graph.rs +++ b/atomic-cli/src/commands/intent/graph.rs @@ -38,11 +38,20 @@ pub struct IntentGraph { /// Write output to this file (HTML also opens it unless --no-open is set). #[arg(short, long)] pub output: Option, + /// Include an unsigned/signed prepared review as diagnostic intent-graph + /// context. Evidence is resolved by the repository service; never approval. + #[arg(long)] + pub review_file: Option, } impl Command for IntentGraph { fn run(&self) -> CliResult<()> { - let graph = crate::commands::rpc::intent_graph(&self.id, self.max_nodes as usize) + let review = self + .review_file + .as_deref() + .map(crate::commands::triage::read_publication_review) + .transpose()?; + let graph = crate::commands::rpc::intent_graph(&self.id, self.max_nodes as usize, review.as_ref()) .map_err(|error| { if error.to_string().contains("KgNeedsRebuild") { CliError::InvalidArgument { @@ -158,6 +167,8 @@ fn annotate(graph: &Graph, nodes: &mut [atomic_core::KgNode]) { "selected intent's recorded artifact (matched by stored vault_path)" } else if graph.dependency_changes.contains(&node.id) { "dependency-only change" + } else if graph.reviewed_changes.contains(&node.id) { + "reviewed change; not inferred implementation" } else { "context" }; @@ -230,6 +241,11 @@ fn render_tree(graph: &Graph, details: bool) -> String { (1, "Intent recording evidence (not implementation)".into()) } else if graph.dependency_changes.contains(&node.id) { (2, "Dependency-only changes".into()) + } else if graph.reviewed_changes.contains(&node.id) { + ( + 2, + "Review scope and evidence (not implementation attribution)".into(), + ) } else if graph.intent_artifact.as_ref() == Some(&node.id) { (3, "Intent artifact".into()) } else if node.has_type(Class::Task) { @@ -464,6 +480,7 @@ mod tests { intent_artifact: None, recording_changes: vec!["urn:change:RECORD".into()], dependency_changes: vec!["urn:change:DEPEND".into()], + reviewed_changes: vec![], truncated: false, missing_resources: vec![], diagnostics: vec![], @@ -492,6 +509,40 @@ mod tests { ); } + #[test] + fn review_context_uses_existing_exports_and_distinct_change_role() { + for export in ["--json", "--dot", "--html", "--details"] { + assert!(IntentGraph::try_parse_from([ + "graph", + "ATOM::test::1", + "--review-file", + "prepared.json", + export + ]) + .is_ok()); + } + let mut graph = fixture(); + graph.nodes.push(atomic_core::KgNode::new( + "urn:change:REVIEWED", + Class::Change, + "Inspect retained work", + "test", + )); + graph.reviewed_changes.push("urn:change:REVIEWED".into()); + let text = render_text(&graph); + assert!(text.contains("Review scope and evidence (not implementation attribution)")); + let mut nodes = graph.nodes.clone(); + annotate(&graph, &mut nodes); + assert!(nodes + .iter() + .find(|node| node.id == "urn:change:REVIEWED") + .unwrap() + .summary + .as_deref() + .unwrap() + .contains("not inferred implementation")); + } + #[test] fn change_hash_labels_are_shown_only_once() { use atomic_core::KgNode; diff --git a/atomic-cli/src/commands/query/mod.rs b/atomic-cli/src/commands/query/mod.rs index 69975d4d..37d24dd2 100644 --- a/atomic-cli/src/commands/query/mod.rs +++ b/atomic-cli/src/commands/query/mod.rs @@ -675,6 +675,15 @@ fn html_node_color(kind: &str) -> String { Class::Project => "#adcbe7", Class::ProjectIdentity => "#bba2a0", Class::VerificationStatus => "#d4d8e3", + Class::PublicationReview => "#c49bff", + Class::ReviewSubject => "#93b4e8", + Class::ReviewEvaluation => "#7fdeb6", + Class::VerificationRecord => "#efb788", + Class::SigningKey => "#d0ce73", + Class::ReviewEvidence => "#a3dec8", + Class::IntentObservation => "#e6a6ce", + Class::CriterionJudgment => "#a7cf77", + Class::ReviewFinding => "#f5ba98", } .to_owned() } diff --git a/atomic-cli/src/commands/rpc.rs b/atomic-cli/src/commands/rpc.rs index 0c79a8e3..aa513c25 100644 --- a/atomic-cli/src/commands/rpc.rs +++ b/atomic-cli/src/commands/rpc.rs @@ -7111,6 +7111,7 @@ pub(crate) fn workflow_snapshot( })?; let response = session.get_workflow_snapshot(pb::GetWorkflowSnapshotRequest { repository: Some(session.reference.clone()), + review_document: None, })?; decode_workflow_snapshot(response) } @@ -7144,6 +7145,7 @@ fn decode_workflow_snapshot( pub(crate) fn intent_graph( id: &str, max_nodes: usize, + review: Option<&atomic_canonical::publication_review::PublicationReview>, ) -> CliResult { let root = super::find_repository_root()?; let session = Service::open_root(&root)?.ok_or_else(|| CliError::InvalidArgument { @@ -7183,11 +7185,19 @@ pub(crate) fn intent_graph( } else { None }; - let snapshot = decode_workflow_snapshot(session.get_workflow_snapshot( - pb::GetWorkflowSnapshotRequest { - repository: Some(session.reference.clone()), - }, - )?)?; + let response = session.get_workflow_snapshot(pb::GetWorkflowSnapshotRequest { + repository: Some(session.reference.clone()), + review_document: review + .map(serde_json::to_vec) + .transpose() + .map_err(|e| CliError::Internal(e.into()))?, + })?; + let expected_preview = review.map(|review| review.artifact_hash()); + require_review_preview_identity( + expected_preview.as_deref(), + response.review_preview_identity.as_deref(), + )?; + let snapshot = decode_workflow_snapshot(response)?; let canonical = match canonical { Some(id) => id, None => { @@ -7206,8 +7216,41 @@ pub(crate) fn intent_graph( candidates[0].id.clone() } }; - atomic_repository::intent_graph::IntentGraph::from_snapshot(&snapshot, &canonical, max_nodes) - .map_err(CliError::Repository) + let graph = atomic_repository::intent_graph::IntentGraph::from_snapshot( + &snapshot, &canonical, max_nodes, + ) + .map_err(CliError::Repository)?; + if let Some(review) = review { + let evaluation = format!("urn:atomic:review:evaluation:{}", review.artifact_hash()); + if !graph.truncated && !graph.nodes.iter().any(|node| node.id == evaluation) { + return Err(CliError::InvalidArgument { + message: "prepared review is not connected to the selected intent".into(), + }); + } + } + Ok(graph) +} + +fn require_review_preview_identity( + expected: Option<&str>, + returned: Option<&str>, +) -> CliResult<()> { + if expected.is_some() && expected != returned { + return Err(CliError::InvalidArgument { message: "the repository service did not resolve the requested review preview; update/restart it before retrying".into() }); + } + Ok(()) +} + +#[cfg(test)] +mod intent_review_preview_tests { + use super::*; + #[test] + fn old_or_wrong_service_preview_response_is_not_silent_success() { + assert!(require_review_preview_identity(None, None).is_ok()); + assert!(require_review_preview_identity(Some("exact"), Some("exact")).is_ok()); + assert!(require_review_preview_identity(Some("exact"), None).is_err()); + assert!(require_review_preview_identity(Some("exact"), Some("other")).is_err()); + } } // --------------------------------------------------------------------------- diff --git a/atomic-cli/src/commands/triage/mod.rs b/atomic-cli/src/commands/triage/mod.rs index 6b1a27e2..330b0f3c 100644 --- a/atomic-cli/src/commands/triage/mod.rs +++ b/atomic-cli/src/commands/triage/mod.rs @@ -24,6 +24,8 @@ pub mod model { pub use atomic_repository::triage::model::*; } pub mod output; +mod publication_review; +pub(crate) use publication_review::read as read_publication_review; pub mod project { pub use atomic_repository::triage::report::{build_report, build_walkthrough, TaskFact}; } @@ -48,6 +50,7 @@ impl Command for Triage { match &self.command { TriageCommands::Candidates(cmd) => cmd.run(), TriageCommands::Review(cmd) => cmd.run(), + TriageCommands::PublicationReview(cmd) => cmd.run(), } } } @@ -68,6 +71,8 @@ pub enum TriageCommands { /// gates each reached intent, and emits a bounded CLI dashboard (default) /// or the full JSON worklist (`--json`). See this subcommand's examples. Review(TriageReview), + /// Prepare, sign, record or inspect an exact-scope retrospective review. + PublicationReview(publication_review::PublicationReviewCommand), } /// Compute the triage candidate set for a view relative to a target. diff --git a/atomic-cli/src/commands/triage/output.rs b/atomic-cli/src/commands/triage/output.rs index 85159f89..5a76223f 100644 --- a/atomic-cli/src/commands/triage/output.rs +++ b/atomic-cli/src/commands/triage/output.rs @@ -70,6 +70,27 @@ pub fn print_report(report: &TriageReport) { .to_string() }; println!(" {} [{}]", emphasis(&intent.id), conform); + if intent.status == "icebox" { + println!( + " {}", + hint("set aside: historical criteria, not current implementation approval") + ); + if let Some(reviewer) = &intent.reviewed_by { + println!( + " {}", + info(&format!("disposition reviewed by {reviewer}")) + ); + } + for c in &intent.criteria { + println!( + " historical [{}] {} {}", + c.status, + hint(&c.id), + first_line(&c.text) + ); + } + continue; + } if let Some(reviewer) = &intent.reviewed_by { println!(" {}", info(&format!("reviewed by {reviewer}"))); } @@ -471,8 +492,13 @@ fn render_intent(intent: &IntentReport) -> String { html_escape(&conform) )); if let Some(reviewer) = &intent.reviewed_by { + let label = if intent.status == "icebox" { + "set-aside disposition reviewed by" + } else { + "reviewed by" + }; d.push_str(&format!( - "
reviewed by {}
\n", + "
{label} {}
\n", html_escape(reviewer) )); } @@ -487,11 +513,24 @@ fn render_intent(intent: &IntentReport) -> String { d.push_str("\n"); } if !intent.criteria.is_empty() { - d.push_str("
    \n"); - for c in &intent.criteria { - d.push_str(&render_criterion(c)); + if intent.status == "icebox" { + d.push_str("

    Historical criteria — not evaluated as current implementation approval.

      \n"); + for c in &intent.criteria { + d.push_str(&format!( + "
    • historical [{}] {}: {}
    • \n", + html_escape(&c.status), + html_escape(&c.id), + html_escape(&c.text) + )); + } + d.push_str("
    \n"); + } else { + d.push_str("
      \n"); + for c in &intent.criteria { + d.push_str(&render_criterion(c)); + } + d.push_str("
    \n"); } - d.push_str("
\n"); } d.push_str("\n"); d @@ -880,6 +919,7 @@ mod tests { findings_info: 0, }, intents: vec![IntentReport { + status: "needs-review".into(), id: "intent:DEMO-A".to_string(), why: Some("Because matters & more".to_string()), conforms: false, @@ -1005,6 +1045,20 @@ mod tests { /// The HTML chapter tour: nav anchors, numbered chapters (first open), /// depends_on links, escaped rationale, and layer-scoped diffs. + #[test] + fn set_aside_criteria_are_history_not_green_implementation_checks() { + let mut report = sample_report(); + let intent = &mut report.intents[0]; + intent.status = "icebox".into(); + intent.criteria[0].status = "met".into(); + let html = render_intent(intent); + assert!(html.contains("Historical criteria")); + assert!(html.contains("disposition reviewed by")); + assert!(html.contains("historical [met]")); + assert!(!html.contains("mark met")); + assert!(!html.contains("")); + } + #[test] fn render_html_walkthrough_chapter_tour() { let html = render_html(&sample_report()); diff --git a/atomic-cli/src/commands/triage/publication_review.rs b/atomic-cli/src/commands/triage/publication_review.rs new file mode 100644 index 00000000..b77e49e3 --- /dev/null +++ b/atomic-cli/src/commands/triage/publication_review.rs @@ -0,0 +1,230 @@ +//! Explicit external/local signing of a present-day review. No trust grants, +//! session repair, implicit ownership claims, or automatic promotion. +use crate::{ + commands::{find_repository_root, Command}, + error::{CliError, CliResult}, +}; +use atomic_canonical::publication_review::PublicationReview; +use atomic_core::types::{Base32, Hash}; +use atomic_identity::IdentityStore; +use atomic_repository::{ + repository::provenance_gate::{local_did_key_provider, PublicationGateConfig}, + Repository, +}; +use clap::{Parser, Subcommand}; +use std::path::{Path, PathBuf}; + +#[derive(Debug, Parser)] +pub struct PublicationReviewCommand { + #[command(subcommand)] + action: Action, +} + +#[derive(Debug, Subcommand)] +enum Action { + /// Print the pinned review document and exact bytes for external signing. + Prepare { + #[arg(long)] + review: String, + /// The source view whose state and inherited perspective were reviewed. + #[arg(long)] + view: Option, + /// Full canonical change hashes; the dependency closure is pinned too. + #[arg(long = "change", required = true)] + changes: Vec, + /// Retained artifact hashes explicitly renewed by this new signature. + #[arg(long)] + supersedes: Vec, + }, + /// Sign a prepared document with an explicitly selected local identity. + Sign { + #[arg(long)] + file: PathBuf, + #[arg(long)] + identity: String, + }, + /// Verify and store an externally signed document; never signs as its author. + Record { + #[arg(long)] + file: PathBuf, + }, + /// Revalidate retained reviews against current evidence and trust policy. + Inspect, +} + +fn invalid(error: impl std::fmt::Display) -> CliError { + CliError::InvalidArgument { + message: error.to_string(), + } +} + +pub(crate) fn read(path: &Path) -> CliResult { + use std::io::Read; + let mut bytes = Vec::new(); + std::fs::File::open(path)? + .take((atomic_canonical::publication_review::MAX_BYTES + 1) as u64) + .read_to_end(&mut bytes)?; + if bytes.len() > atomic_canonical::publication_review::MAX_BYTES { + return Err(invalid("review exceeds 1 MiB")); + } + let value = atomic_canonical::jcs::admit_document(&bytes).map_err(invalid)?; + let document = value.get("document").unwrap_or(&value); + PublicationReview::parse(&serde_json::to_vec(document).map_err(invalid)?).map_err(invalid) +} + +impl Command for PublicationReviewCommand { + fn run(&self) -> CliResult<()> { + let root = find_repository_root()?; + let repo = Repository::open(&root).map_err(CliError::Repository)?; + let keys = local_did_key_provider(&repo); + let config = PublicationGateConfig::from_repo(&repo).map_err(CliError::Repository)?; + match &self.action { + Action::Prepare { + review, + view, + changes, + supersedes, + } => { + let changes = changes + .iter() + .map(|value| { + Hash::from_base32(value.as_bytes()) + .filter(|hash| hash.to_base32() == *value) + .ok_or_else(|| invalid("--change requires a full canonical hash")) + }) + .collect::>>()?; + let mut review = repo + .prepare_publication_review_on_view( + review, + &changes, + view.as_deref().unwrap_or(repo.current_view()), + &keys, + ) + .map_err(CliError::Repository)?; + review.supersedes = supersedes.clone(); + let key = atomic_identity::keypair::PublicKey::from_base32( + &review.subject.review.public_key, + ) + .map_err(invalid)?; + let prepared = atomic_canonical::proof::prepare_attestation(review.value(), &key); + println!("{}", serde_json::to_string_pretty(&serde_json::json!({ + "document":prepared.value,"signingBytes":data_encoding::BASE64.encode(&prepared.signing_bytes), + "requiredVerification":{"observedAtMerkle":review.subject.view_chain[0].state, + "ref":format!("urn:atomic:view-set:{}",review.subject.effective_set_id)} + })).map_err(invalid)?); + } + Action::Sign { file, identity } => { + let review = read(file)?; + let store = IdentityStore::open_default().map_err(invalid)?; + let identity = store.load_by_name(identity).map_err(invalid)?; + if atomic_canonical::did::did_for_public_key(&identity.public_key) + != review.attributed_to + { + return Err(invalid("selected signer is not the prepared review author")); + } + if review.proof.is_some() { + return Err(invalid( + "prepared document already has a proof; use record or prepare again", + )); + } + let pair = store.load_keypair(&identity.id, None).map_err(invalid)?; + let signed = + atomic_canonical::proof::attest_value(review.value(), &identity, &pair); + let signed: PublicationReview = serde_json::from_value(signed).map_err(invalid)?; + let path = repo + .record_publication_review(&signed, &config, &keys) + .map_err(CliError::Repository)?; + println!( + "{}", + serde_json::json!({"path":path,"review":signed.artifact_hash(),"meaning":"present-day retrospective review; not original capture"}) + ); + } + Action::Record { file } => { + let review = read(file)?; + let path = repo + .record_publication_review(&review, &config, &keys) + .map_err(CliError::Repository)?; + println!( + "{}", + serde_json::json!({"path":path,"review":review.artifact_hash()}) + ); + } + Action::Inspect => { + let mut results = Vec::new(); + for review in repo.publication_reviews().map_err(CliError::Repository)? { + let validation = match repo.validate_publication_review(&review, &config, &keys) + { + Ok(report) => serde_json::to_value(report).map_err(invalid)?, + Err(error) => { + serde_json::json!({"conforms":false,"error":error.to_string()}) + } + }; + results.push(serde_json::json!({"review":review.artifact_hash(),"subject":review.subject,"document":review,"validation":validation})); + } + println!( + "{}", + serde_json::to_string_pretty(&results).map_err(invalid)? + ); + } + } + Ok(()) + } +} + +#[cfg(test)] +mod tests { + use super::*; + #[test] + fn publication_review_cli_requires_explicit_subject_and_signer() { + assert!(PublicationReviewCommand::try_parse_from([ + "publication-review", + "prepare", + "--review", + "work" + ]) + .is_err()); + assert!(PublicationReviewCommand::try_parse_from([ + "publication-review", + "sign", + "--file", + "prepared.json" + ]) + .is_err()); + assert!(PublicationReviewCommand::try_parse_from([ + "publication-review", + "prepare", + "--review", + "work", + "--change", + "full-hash", + "--view", + "feature", + "--supersedes", + "old-artifact" + ]) + .is_ok()); + assert!( + PublicationReviewCommand::try_parse_from(["publication-review", "inspect"]).is_ok() + ); + assert!(PublicationReviewCommand::try_parse_from([ + "publication-review", + "graph", + "--file", + "prepared.json" + ]) + .is_err()); + } + #[test] + fn publication_review_file_admission_rejects_ambiguous_or_oversized_json() { + let dir = tempfile::tempdir().unwrap(); + let file = dir.path().join("review.json"); + std::fs::write(&file, br#"{"schema":"x","schema":"y"}"#).unwrap(); + assert!(read(&file).is_err()); + std::fs::write( + &file, + vec![b' '; atomic_canonical::publication_review::MAX_BYTES + 1], + ) + .unwrap(); + assert!(read(&file).is_err()); + } +} diff --git a/atomic-core/ontology/review-1.0.0.ttl b/atomic-core/ontology/review-1.0.0.ttl new file mode 100644 index 00000000..15640bbe --- /dev/null +++ b/atomic-core/ontology/review-1.0.0.ttl @@ -0,0 +1,61 @@ +@prefix atomic: . +@prefix rdfs: . +@prefix owl: . +@prefix xsd: . + + a owl:Ontology ; + owl:versionIRI ; + owl:imports ; + rdfs:label "Atomic review ontology" ; + rdfs:comment "Exact-scope review of retained per-change knowledge. Reuses workflow identities, intents, sessions, turns and changes. Observations are not governing authority or original execution signatures. SHACL defines executable readiness policy; imports are bundled offline." . + +atomic:PublicationReview a owl:Class ; rdfs:subClassOf atomic:Attestation ; + rdfs:comment "Present-day signed conclusion over an exact subject, distinct from an original session attestation. An unsigned projection is a preview, never approval." . +atomic:ReviewSubject a owl:Class ; rdfs:subClassOf owl:Thing ; + rdfs:comment "Pinned project, changes and dependency closure, source perspective, intent revisions and policy bundle." . +atomic:ReviewEvaluation a owl:Class ; rdfs:subClassOf owl:Thing . +atomic:VerificationRecord a owl:Class ; rdfs:subClassOf owl:Thing . +atomic:SigningKey a owl:Class ; rdfs:subClassOf owl:Thing . +atomic:ReviewEvidence a owl:Class ; rdfs:subClassOf owl:Thing ; + rdfs:comment "Source-addressed retained evidence. Authentic bytes do not by themselves prove the semantic truth of a recorded statement." . +atomic:IntentObservation a owl:Class ; rdfs:subClassOf atomic:ReviewEvidence ; + rdfs:comment "A retained lifecycle receipt mentioning an intent, pinned to provenance hash, node and matching session/turn. Never implies hasPlan or implements." . +atomic:CriterionJudgment a owl:Class ; rdfs:subClassOf owl:Thing ; + rdfs:comment "Reviewer conclusion about an acceptance criterion, backed by exact verification records. Distinct from observing a historical CLI receipt." . +atomic:ReviewFinding a owl:Class ; rdfs:subClassOf atomic:Finding ; + rdfs:comment "Missing, unresolved or ambiguous evidence or other review blocker. Retained in graph previews rather than erased by discovery." . + +atomic:hasReviewEvidence a owl:ObjectProperty ; rdfs:domain atomic:Change ; rdfs:range atomic:ReviewEvidence . +atomic:subjectEvidence a owl:ObjectProperty ; rdfs:domain atomic:ReviewSubject ; rdfs:range atomic:ReviewEvidence ; + rdfs:comment "Evidence within this exact review subject. A shared change or dependency is not a route to another subject's scope." . +atomic:sourceNode a owl:DatatypeProperty ; rdfs:domain atomic:ReviewEvidence ; rdfs:range xsd:string . +atomic:observationKind a owl:DatatypeProperty ; rdfs:domain atomic:IntentObservation ; rdfs:range xsd:string . +atomic:observationRole a owl:DatatypeProperty ; rdfs:domain atomic:IntentObservation ; rdfs:range xsd:string ; + rdfs:comment "work or review-context. Only observations of the exact selected review intent are review-context; its metadata lifecycle does not require a recursive independent review of itself." . +atomic:sourceReference a owl:DatatypeProperty ; rdfs:domain atomic:IntentObservation ; rdfs:range xsd:string . +atomic:observedIntent a owl:ObjectProperty ; rdfs:domain atomic:IntentObservation ; rdfs:range atomic:WorkIntent . +atomic:evidenceSource a owl:ObjectProperty ; rdfs:domain atomic:ReviewEvidence ; rdfs:range atomic:ProvenanceGraph . +atomic:evidenceTurn a owl:ObjectProperty ; rdfs:domain atomic:ReviewEvidence ; rdfs:range atomic:SessionTurn . +atomic:hasJudgment a owl:ObjectProperty ; rdfs:domain atomic:PublicationReview ; rdfs:range atomic:CriterionJudgment . +atomic:judgesCriterion a owl:ObjectProperty ; rdfs:domain atomic:CriterionJudgment ; rdfs:range atomic:AcceptanceCriterion . +atomic:supportedBy a owl:ObjectProperty ; rdfs:domain atomic:CriterionJudgment . +atomic:reviewsClosure a owl:ObjectProperty ; rdfs:range atomic:ReviewSubject . +atomic:reviewsChange a owl:ObjectProperty ; rdfs:range atomic:Change . +atomic:includesIntent a owl:ObjectProperty ; rdfs:domain atomic:ReviewSubject ; rdfs:range atomic:WorkIntent . +atomic:includesSetAside a owl:ObjectProperty ; rdfs:domain atomic:ReviewSubject ; rdfs:range atomic:WorkIntent ; + rdfs:comment "An exact signed terminal intent disposition independently reviewed as set aside. This is not approval that its historical implementation criteria hold in the current product, and cannot supply managed-change implementation coverage." . +atomic:evaluatesReview a owl:ObjectProperty ; rdfs:domain atomic:ReviewEvaluation ; rdfs:range atomic:PublicationReview . +atomic:reviewIntent a owl:ObjectProperty ; rdfs:domain atomic:PublicationReview ; rdfs:range atomic:ReviewIntent . +atomic:authorityResult a owl:ObjectProperty ; rdfs:range atomic:VerificationStatus . +atomic:freshnessResult a owl:ObjectProperty ; rdfs:range atomic:VerificationStatus . +atomic:canonicalConformance a owl:ObjectProperty ; rdfs:range atomic:VerificationStatus ; rdfs:comment "Canonical schema conformance, not cryptographic verification or a reviewer judgment." . +atomic:signingKey a owl:ObjectProperty ; rdfs:domain atomic:Identity ; rdfs:range atomic:SigningKey . +atomic:hasVerification a owl:ObjectProperty ; rdfs:domain atomic:AcceptanceCriterion ; rdfs:range atomic:VerificationRecord . +atomic:requiredKind a owl:DatatypeProperty ; rdfs:domain atomic:AcceptanceCriterion ; rdfs:range xsd:string . +atomic:verificationKind a owl:DatatypeProperty ; rdfs:domain atomic:VerificationRecord ; rdfs:range xsd:string . +atomic:observedState a owl:DatatypeProperty ; rdfs:domain atomic:VerificationRecord ; rdfs:range xsd:string . +atomic:reviewedState a owl:DatatypeProperty ; rdfs:domain atomic:ReviewSubject ; rdfs:range xsd:string . +atomic:reviewedContext a owl:DatatypeProperty ; rdfs:domain atomic:ReviewSubject ; rdfs:range xsd:string . +atomic:verificationReference a owl:DatatypeProperty ; rdfs:domain atomic:VerificationRecord ; rdfs:range xsd:string . +atomic:evidenceText a owl:DatatypeProperty ; rdfs:domain atomic:AcceptanceCriterion ; rdfs:range xsd:string . +atomic:verifiedByText a owl:DatatypeProperty ; rdfs:domain atomic:AcceptanceCriterion ; rdfs:range xsd:string . diff --git a/atomic-core/ontology/shapes/review-1.0.0.ttl b/atomic-core/ontology/shapes/review-1.0.0.ttl new file mode 100644 index 00000000..86884c81 --- /dev/null +++ b/atomic-core/ontology/shapes/review-1.0.0.ttl @@ -0,0 +1,224 @@ +@prefix atomic: . +@prefix shape: . +@prefix sh: . +@prefix xsd: . +@prefix rdf: . + +# Review does not assert the legacy projection's hasPlan/implements equivalence. +# Ordinary publication and projection policy remain unchanged. +shape:FullHashIdentity a sh:NodeShape ; + sh:targetClass atomic:Change, atomic:ProvenanceGraph, atomic:Attestation ; + sh:nodeKind sh:IRI ; + sh:pattern "^urn:atomic:(change|provenance|attestation):blake3-256:[A-Z2-7]{51}[AQ]$" . + +shape:ReferencedResource a sh:NodeShape ; + sh:targetObjectsOf atomic:hasReviewEvidence, atomic:subjectEvidence, atomic:observedIntent, + atomic:evidenceSource, atomic:evidenceTurn, atomic:hasJudgment, + atomic:judgesCriterion, atomic:supportedBy, atomic:reviewsChange, + atomic:includesIntent, atomic:includesSetAside, atomic:reviewsClosure, atomic:reviewIntent, + atomic:hasTurn, atomic:generatedChange, atomic:changeExplainedBy, + atomic:turnExplainedBy, atomic:directlyDependsOnChange, + atomic:reviews, atomic:authoredBy, atomic:signedBy, atomic:signingKey, + atomic:coversChange, atomic:attestedBy, atomic:aboutResource, + atomic:hasAcceptanceCriterion, atomic:hasVerification ; + sh:nodeKind sh:IRI ; + sh:property [ sh:path rdf:type ; sh:minCount 1 ] . + +# The fixed evaluation target prevents an empty or truncated graph from passing. +shape:Evaluation a sh:NodeShape ; + sh:targetNode ; + sh:property [ sh:path atomic:evaluatesReview ; sh:minCount 1 ; sh:maxCount 1 ; sh:class atomic:PublicationReview ] . + +shape:Approval a sh:NodeShape ; + sh:targetClass atomic:PublicationReview ; + sh:property [ sh:path atomic:verificationResult ; sh:hasValue atomic:Verified ; sh:maxCount 1 ] ; + sh:property [ sh:path atomic:authorityResult ; sh:hasValue atomic:Verified ; sh:maxCount 1 ] ; + sh:property [ sh:path atomic:freshnessResult ; sh:hasValue atomic:Verified ; sh:maxCount 1 ] ; + sh:property [ sh:path atomic:signedBy ; sh:minCount 1 ; sh:maxCount 1 ; sh:class atomic:Identity ] ; + sh:property [ sh:path atomic:reviewsClosure ; sh:minCount 1 ; sh:maxCount 1 ; sh:class atomic:ReviewSubject ] ; + sh:property [ sh:path atomic:reviewIntent ; sh:minCount 1 ; sh:maxCount 1 ; sh:class atomic:ReviewIntent ] ; + sh:sparql [ + sh:message "The approval must be signed by the authenticated review-intent author." ; + sh:select """ + PREFIX atomic: + SELECT $this WHERE { + $this atomic:signedBy ?signer ; atomic:reviewIntent ?review . + FILTER NOT EXISTS { ?review atomic:authoredBy ?signer } + } + """ + ] ; + sh:sparql [ + sh:message "Reviewer and every work author must have different authenticated keys." ; + sh:select """ + PREFIX atomic: + SELECT $this WHERE { + $this atomic:signedBy ?reviewer ; atomic:reviewsClosure ?subject . + { ?subject atomic:includesIntent ?work } UNION { ?subject atomic:includesSetAside ?work } + ?work atomic:authoredBy ?author . + ?reviewer atomic:signingKey ?key . ?author atomic:signingKey ?key . + } + """ + ] . + +shape:Subject a sh:NodeShape ; + sh:targetClass atomic:ReviewSubject ; + sh:property [ sh:path atomic:reviewedState ; sh:minCount 1 ; sh:maxCount 1 ; sh:minLength 1 ] ; + sh:property [ sh:path atomic:reviewedContext ; sh:minCount 1 ; sh:maxCount 1 ; sh:minLength 1 ] ; + sh:property [ sh:path atomic:reviewsChange ; sh:minCount 1 ; sh:class atomic:Change ] ; + sh:property [ sh:path atomic:includesIntent ; sh:minCount 1 ; sh:class atomic:WorkIntent ] ; + sh:sparql [ + sh:message "The subject must contain the full dependency closure." ; + sh:select """ + PREFIX atomic: + SELECT $this WHERE { + $this atomic:reviewsChange ?change . ?change atomic:directlyDependsOnChange ?dep . + FILTER NOT EXISTS { $this atomic:reviewsChange ?dep } + } + """ + ] ; + # Scope completeness: every intent a reviewed change observed must be in the + # review scope, either as current work (includesIntent) or as an explicitly + # reviewed set-aside disposition (includesSetAside). Only includesIntent can + # supply managed-change coverage below; set-aside membership never does. + sh:sparql [ + sh:message "Include the observed intent in the original review intent's reviews references (as current work or an explicitly reviewed set-aside disposition), then re-run review. Selected-review lifecycle receipts are context, not work requiring self-review." ; + sh:select """ + PREFIX atomic: + SELECT DISTINCT $this ?value WHERE { + $this atomic:reviewsChange ?change . ?change atomic:hasReviewEvidence ?evidence . ?evidence atomic:observedIntent ?value ; atomic:observationRole "work" . + FILTER NOT EXISTS { + { $this atomic:includesIntent ?value } UNION { $this atomic:includesSetAside ?value } + ?review atomic:reviewsClosure $this ; atomic:reviewIntent ?intent . ?intent atomic:reviews ?value + } + } + """ + ] ; + sh:sparql [ + sh:message "A managed change needs resolved source-backed intent evidence or an exact signed implementation declaration." ; + sh:select """ + PREFIX atomic: + SELECT DISTINCT $this ?value WHERE { + $this atomic:reviewsChange ?value . ?value atomic:status "managed" . + FILTER NOT EXISTS { $this atomic:includesIntent ?work . ?value atomic:hasReviewEvidence ?evidence . ?evidence atomic:observedIntent ?work ; atomic:observationRole "work" ; atomic:status "resolved" ; atomic:freshnessResult atomic:Verified } + FILTER NOT EXISTS { ?approval atomic:reviewsClosure $this ; atomic:reviewIntent ?review . $this atomic:subjectEvidence ?context . ?value atomic:hasReviewEvidence ?context . ?context atomic:observationRole "review-context" ; atomic:observedIntent ?review ; atomic:status "resolved" ; atomic:freshnessResult atomic:Verified } + FILTER NOT EXISTS { $this atomic:includesIntent ?work . ?work atomic:declaresImplementation ?value } + } + """ + ] . + +shape:IntentObservation a sh:NodeShape ; + sh:targetClass atomic:IntentObservation ; + sh:property [ sh:path atomic:observationRole ; sh:minCount 1 ; sh:maxCount 1 ; sh:in ("work" "review-context") ] ; + sh:property [ sh:path atomic:sourceNode ; sh:minCount 1 ; sh:maxCount 1 ; sh:minLength 1 ] ; + sh:property [ sh:path atomic:sourceReference ; sh:minCount 1 ; sh:maxCount 1 ; sh:minLength 1 ] ; + sh:property [ sh:path atomic:observationKind ; sh:minCount 1 ; sh:maxCount 1 ; sh:in ("created" "updated" "attested-receipt" "verified-receipt") ] ; + sh:property [ sh:path atomic:status ; sh:hasValue "resolved" ; sh:maxCount 1 ] ; + sh:property [ sh:path atomic:freshnessResult ; sh:hasValue atomic:Verified ; sh:maxCount 1 ] ; + sh:property [ sh:path atomic:observedIntent ; sh:minCount 1 ; sh:maxCount 1 ; sh:class atomic:WorkIntent ] ; + sh:property [ sh:path atomic:evidenceSource ; sh:minCount 1 ; sh:maxCount 1 ; sh:class atomic:ProvenanceGraph ] ; + sh:property [ sh:path atomic:evidenceTurn ; sh:minCount 1 ; sh:maxCount 1 ; sh:class atomic:SessionTurn ] ; + sh:sparql [ + sh:message "Observation source and ledger turn must be the same retained provenance, explaining the reviewed change." ; + sh:select """ + PREFIX atomic: + SELECT $this WHERE { + ?change atomic:hasReviewEvidence $this . + $this atomic:evidenceSource ?source ; atomic:evidenceTurn ?turn . + FILTER NOT EXISTS { ?turn atomic:turnExplainedBy ?source . ?change atomic:changeExplainedBy ?source } + } + """ + ] ; + sh:sparql [ + sh:message "Review-context must reference the exact selected review intent, never unrelated work." ; + sh:select """ + PREFIX atomic: + SELECT $this WHERE { + $this atomic:observationRole "review-context" ; atomic:observedIntent ?intent . + FILTER NOT EXISTS { ?approval atomic:reviewIntent ?intent ; atomic:reviewsClosure ?subject . ?subject atomic:subjectEvidence $this } + } + """ + ] . + +shape:CriterionJudgment a sh:NodeShape ; + sh:targetClass atomic:CriterionJudgment ; + sh:property [ sh:path atomic:status ; sh:hasValue "met" ; sh:maxCount 1 ] ; + sh:property [ sh:path atomic:judgesCriterion ; sh:minCount 1 ; sh:maxCount 1 ; sh:class atomic:AcceptanceCriterion ] ; + sh:property [ sh:path atomic:supportedBy ; sh:minCount 1 ; sh:class atomic:VerificationRecord ] . + +shape:ReviewIntent a sh:NodeShape ; + sh:targetObjectsOf atomic:reviewIntent ; + sh:property [ sh:path atomic:verificationResult ; sh:hasValue atomic:Verified ; sh:maxCount 1 ] ; + sh:property [ sh:path atomic:freshnessResult ; sh:hasValue atomic:Verified ; sh:maxCount 1 ] ; + sh:property [ sh:path atomic:canonicalConformance ; sh:hasValue atomic:Verified ; sh:maxCount 1 ] ; + sh:property [ sh:path atomic:status ; sh:hasValue "done" ; sh:maxCount 1 ; sh:message "Complete the original review intent after addressing its findings and recording current-state verification." ] ; + sh:property [ sh:path atomic:hasAcceptanceCriterion ; sh:minCount 1 ; sh:class atomic:AcceptanceCriterion ; sh:node shape:ExactReviewCriterion ] ; + sh:property [ sh:path atomic:reviews ; sh:minCount 1 ; sh:class atomic:WorkIntent ] . + +shape:ExactReviewCriterion a sh:NodeShape ; + sh:node shape:Criterion ; + sh:property [ sh:path atomic:hasVerification ; sh:minCount 1 ] ; + sh:sparql [ + sh:message "Reviewer verification must pass against the exact reviewed source state." ; + sh:select """ + PREFIX atomic: + SELECT $this WHERE { + ?review atomic:hasAcceptanceCriterion $this . + ?approval atomic:reviewIntent ?review ; atomic:reviewsClosure ?subject . + ?subject atomic:reviewedState ?state ; atomic:reviewedContext ?context . + FILTER NOT EXISTS { $this atomic:hasVerification ?record . ?record atomic:status "pass" ; atomic:observedState ?state ; atomic:verificationReference ?context } + } + """ + ] ; + sh:sparql [ + sh:message "Every required reviewer check must pass at the reviewed state, not an unrelated revision." ; + sh:select """ + PREFIX atomic: + SELECT $this WHERE { + $this atomic:requiredKind ?kind . ?review atomic:hasAcceptanceCriterion $this . + ?approval atomic:reviewIntent ?review ; atomic:reviewsClosure ?subject . + ?subject atomic:reviewedState ?state ; atomic:reviewedContext ?context . + FILTER NOT EXISTS { $this atomic:hasVerification ?record . ?record atomic:verificationKind ?kind ; atomic:status "pass" ; atomic:observedState ?state ; atomic:verificationReference ?context } + } + """ + ] . + +shape:Work a sh:NodeShape ; + sh:targetObjectsOf atomic:includesIntent ; + sh:property [ sh:path atomic:freshnessResult ; sh:hasValue atomic:Verified ; sh:maxCount 1 ] ; + sh:property [ sh:path atomic:verificationResult ; sh:hasValue atomic:Verified ; sh:maxCount 1 ] ; + sh:property [ sh:path atomic:canonicalConformance ; sh:hasValue atomic:Verified ; sh:maxCount 1 ] ; + sh:property [ sh:path atomic:hasAcceptanceCriterion ; sh:minCount 1 ; sh:class atomic:AcceptanceCriterion ; sh:node shape:Criterion ] . + +shape:Criterion a sh:NodeShape ; + sh:property [ sh:path atomic:status ; sh:hasValue "met" ; sh:maxCount 1 ] ; + sh:property [ sh:path atomic:evidenceText ; sh:minCount 1 ; sh:minLength 1 ] ; + sh:property [ sh:path atomic:verifiedByText ; sh:minCount 1 ; sh:minLength 1 ] ; + sh:sparql [ + sh:message "Each required verification kind needs a passing, state-pinned execution record." ; + sh:select """ + PREFIX atomic: + SELECT $this WHERE { + $this atomic:requiredKind ?kind . + FILTER NOT EXISTS { $this atomic:hasVerification ?record . ?record atomic:verificationKind ?kind ; atomic:status "pass" ; atomic:observedState ?state . FILTER(STRLEN(?state) > 0) } + } + """ + ] . + +# Archival disposition is still authenticated and independently reviewed. It is +# deliberately NOT evaluated as a current implementation/criterion approval. +shape:SetAside a sh:NodeShape ; + sh:targetObjectsOf atomic:includesSetAside ; + sh:property [ sh:path atomic:status ; sh:hasValue "icebox" ; sh:maxCount 1 ] ; + sh:property [ sh:path atomic:freshnessResult ; sh:hasValue atomic:Verified ; sh:maxCount 1 ] ; + sh:property [ sh:path atomic:verificationResult ; sh:hasValue atomic:Verified ; sh:maxCount 1 ] ; + sh:property [ sh:path atomic:canonicalConformance ; sh:hasValue atomic:Verified ; sh:maxCount 1 ] ; + sh:sparql [ + sh:message "The completed review must explicitly review each set-aside disposition; inactive status alone is not approval." ; + sh:select """ + PREFIX atomic: + SELECT $this WHERE { + ?subject atomic:includesSetAside $this . + FILTER NOT EXISTS { ?approval atomic:reviewsClosure ?subject ; atomic:reviewIntent ?review . ?review atomic:reviews $this } + } + """ + ] . diff --git a/atomic-core/src/kg/ontology.rs b/atomic-core/src/kg/ontology.rs index 3fe1079d..368f708d 100644 --- a/atomic-core/src/kg/ontology.rs +++ b/atomic-core/src/kg/ontology.rs @@ -7,7 +7,15 @@ use serde::{Deserialize, Serialize}; pub const NAMESPACE: &str = "https://atomic.dev/ns/workflow#"; pub const VERSION_IRI: &str = "https://atomic.dev/ns/workflow/1.0.0"; -pub const TTL: &str = include_str!("../../ontology/workflow-1.0.0.ttl"); +pub const WORKFLOW_TTL: &str = include_str!("../../ontology/workflow-1.0.0.ttl"); +pub const REVIEW_VERSION_IRI: &str = "https://atomic.dev/ns/review/1.0.0"; +pub const REVIEW_TTL: &str = include_str!("../../ontology/review-1.0.0.ttl"); +/// Offline bundle: imports are pinned locally, never resolved over the network. +pub const TTL: &str = concat!( + include_str!("../../ontology/workflow-1.0.0.ttl"), + "\n", + include_str!("../../ontology/review-1.0.0.ttl") +); pub const PREFIXES: &[(&str, &str)] = &[ ("atomic", NAMESPACE), ("prov", "http://www.w3.org/ns/prov#"), @@ -109,6 +117,10 @@ classes! { View => E(OwlThing), File => E(OwlThing), Identity => E(OwlThing), Concept => E(SkosConcept), Project => E(OwlThing), ProjectIdentity => E(OwlThing), VerificationStatus => E(OwlThing), + PublicationReview => A(Class::Attestation), ReviewSubject => E(OwlThing), + ReviewEvaluation => E(OwlThing), VerificationRecord => E(OwlThing), SigningKey => E(OwlThing), + ReviewEvidence => E(OwlThing), IntentObservation => A(Class::ReviewEvidence), + CriterionJudgment => E(OwlThing), ReviewFinding => A(Class::Finding), } macro_rules! predicates { @@ -138,6 +150,19 @@ const fn range(class: Class) -> Option { use Class::*; use Predicate::*; predicates! { + IncludesSetAside => ("https://atomic.dev/ns/workflow#includesSetAside", "atomic:includesSetAside", domain(ReviewSubject), range(WorkIntent), None, None), + ObservationRole => ("https://atomic.dev/ns/workflow#observationRole", "atomic:observationRole", domain(IntentObservation), Some(Range::Datatype(Datatype::String)), None, None), + SubjectEvidence => ("https://atomic.dev/ns/workflow#subjectEvidence", "atomic:subjectEvidence", domain(ReviewSubject), range(ReviewEvidence), None, None), + SourceNode => ("https://atomic.dev/ns/workflow#sourceNode", "atomic:sourceNode", domain(ReviewEvidence), Some(Range::Datatype(Datatype::String)), None, None), + ObservationKind => ("https://atomic.dev/ns/workflow#observationKind", "atomic:observationKind", domain(IntentObservation), Some(Range::Datatype(Datatype::String)), None, None), + SourceReference => ("https://atomic.dev/ns/workflow#sourceReference", "atomic:sourceReference", domain(IntentObservation), Some(Range::Datatype(Datatype::String)), None, None), + HasReviewEvidence => ("https://atomic.dev/ns/workflow#hasReviewEvidence", "atomic:hasReviewEvidence", domain(Change), range(ReviewEvidence), None, None), + ObservedIntent => ("https://atomic.dev/ns/workflow#observedIntent", "atomic:observedIntent", domain(IntentObservation), range(WorkIntent), None, None), + EvidenceSource => ("https://atomic.dev/ns/workflow#evidenceSource", "atomic:evidenceSource", domain(ReviewEvidence), range(ProvenanceGraph), None, None), + EvidenceTurn => ("https://atomic.dev/ns/workflow#evidenceTurn", "atomic:evidenceTurn", domain(ReviewEvidence), range(SessionTurn), None, None), + HasJudgment => ("https://atomic.dev/ns/workflow#hasJudgment", "atomic:hasJudgment", domain(PublicationReview), range(CriterionJudgment), None, None), + JudgesCriterion => ("https://atomic.dev/ns/workflow#judgesCriterion", "atomic:judgesCriterion", domain(CriterionJudgment), range(AcceptanceCriterion), None, None), + SupportedBy => ("https://atomic.dev/ns/workflow#supportedBy", "atomic:supportedBy", domain(CriterionJudgment), None, None, None), HasTurn => ("https://atomic.dev/ns/workflow#hasTurn", "atomic:hasTurn", domain(Session), range(SessionTurn), Some(TurnOfSession), None), HasPlan => ("https://atomic.dev/ns/workflow#hasPlan", "atomic:hasPlan", domain(SessionTurn), range(WorkIntent), Some(GovernsTurn), None), GeneratedChange => ("https://atomic.dev/ns/workflow#generatedChange", "atomic:generatedChange", domain(SessionTurn), range(Change), Some(GeneratedBy), Some(ProvGenerated)), @@ -162,6 +187,24 @@ predicates! { ScopeOutFile => ("https://atomic.dev/ns/workflow#scopeOutFile", "atomic:scopeOutFile", domain(WorkIntent), range(File), None, None), Remediates => ("https://atomic.dev/ns/workflow#remediates", "atomic:remediates", domain(WorkIntent), range(WorkIntent), None, None), Reviews => ("https://atomic.dev/ns/workflow#reviews", "atomic:reviews", domain(ReviewIntent), range(WorkIntent), Some(ReviewedBy), None), + ReviewsClosure => ("https://atomic.dev/ns/workflow#reviewsClosure", "atomic:reviewsClosure", None, range(ReviewSubject), None, None), + ReviewsChange => ("https://atomic.dev/ns/workflow#reviewsChange", "atomic:reviewsChange", None, range(Change), None, None), + IncludesIntent => ("https://atomic.dev/ns/workflow#includesIntent", "atomic:includesIntent", domain(ReviewSubject), range(WorkIntent), None, None), + EvaluatesReview => ("https://atomic.dev/ns/workflow#evaluatesReview", "atomic:evaluatesReview", domain(ReviewEvaluation), range(PublicationReview), None, None), + HasReviewIntent => ("https://atomic.dev/ns/workflow#reviewIntent", "atomic:reviewIntent", domain(PublicationReview), range(ReviewIntent), None, None), + AuthorityResult => ("https://atomic.dev/ns/workflow#authorityResult", "atomic:authorityResult", None, range(VerificationStatus), None, None), + FreshnessResult => ("https://atomic.dev/ns/workflow#freshnessResult", "atomic:freshnessResult", None, range(VerificationStatus), None, None), + CanonicalConformance => ("https://atomic.dev/ns/workflow#canonicalConformance", "atomic:canonicalConformance", None, range(VerificationStatus), None, None), + SigningKey => ("https://atomic.dev/ns/workflow#signingKey", "atomic:signingKey", domain(Identity), range(Class::SigningKey), None, None), + HasVerification => ("https://atomic.dev/ns/workflow#hasVerification", "atomic:hasVerification", domain(AcceptanceCriterion), range(VerificationRecord), None, None), + RequiredKind => ("https://atomic.dev/ns/workflow#requiredKind", "atomic:requiredKind", domain(AcceptanceCriterion), Some(Range::Datatype(Datatype::String)), None, None), + VerificationKind => ("https://atomic.dev/ns/workflow#verificationKind", "atomic:verificationKind", domain(VerificationRecord), Some(Range::Datatype(Datatype::String)), None, None), + ObservedState => ("https://atomic.dev/ns/workflow#observedState", "atomic:observedState", domain(VerificationRecord), Some(Range::Datatype(Datatype::String)), None, None), + ReviewedState => ("https://atomic.dev/ns/workflow#reviewedState", "atomic:reviewedState", domain(ReviewSubject), Some(Range::Datatype(Datatype::String)), None, None), + ReviewedContext => ("https://atomic.dev/ns/workflow#reviewedContext", "atomic:reviewedContext", domain(ReviewSubject), Some(Range::Datatype(Datatype::String)), None, None), + VerificationReference => ("https://atomic.dev/ns/workflow#verificationReference", "atomic:verificationReference", domain(VerificationRecord), Some(Range::Datatype(Datatype::String)), None, None), + EvidenceText => ("https://atomic.dev/ns/workflow#evidenceText", "atomic:evidenceText", domain(AcceptanceCriterion), Some(Range::Datatype(Datatype::String)), None, None), + VerifiedByText => ("https://atomic.dev/ns/workflow#verifiedByText", "atomic:verifiedByText", domain(AcceptanceCriterion), Some(Range::Datatype(Datatype::String)), None, None), DirectlyDependsOnChange => ("https://atomic.dev/ns/workflow#directlyDependsOnChange", "atomic:directlyDependsOnChange", domain(Change), range(Change), None, Some(DependsOn)), DependsOnIntent => ("https://atomic.dev/ns/workflow#dependsOnIntent", "atomic:dependsOnIntent", domain(WorkIntent), range(WorkIntent), None, Some(DependsOn)), ModifiesFile => ("https://atomic.dev/ns/workflow#modifiesFile", "atomic:modifiesFile", domain(Change), range(File), None, Some(Modifies)), diff --git a/atomic-core/tests/kg_ontology.rs b/atomic-core/tests/kg_ontology.rs index 8b377575..576b3285 100644 --- a/atomic-core/tests/kg_ontology.rs +++ b/atomic-core/tests/kg_ontology.rs @@ -150,6 +150,7 @@ fn ontology_uses_only_the_declared_rl_constructs() { "owl:propertyChainAxiom", "rdfs:isDefinedBy", "owl:versionIRI", + "owl:imports", "rdfs:label", "rdfs:comment", ]; @@ -195,3 +196,32 @@ fn legacy_inventory_is_unique_and_all_targets_exist() { // 81 former constants, plus 20 bare node kinds. assert_eq!(old.len(), 101); } + +#[test] +fn review_is_a_versioned_module_without_governing_authority_inference() { + let review = TurtleParser::new() + .for_reader(REVIEW_TTL.as_bytes()) + .collect::, _>>() + .unwrap(); + assert!(objects( + &review, + "https://atomic.dev/ns/review", + "http://www.w3.org/2002/07/owl#imports" + ) + .contains(VERSION_IRI)); + assert!(objects( + &review, + "https://atomic.dev/ns/review", + "http://www.w3.org/2002/07/owl#versionIRI" + ) + .contains(REVIEW_VERSION_IRI)); + assert!(!WORKFLOW_TTL.contains("atomic:PublicationReview a owl:Class")); + for predicate in [ + Predicate::ObservedIntent, + Predicate::HasReviewEvidence, + Predicate::EvidenceSource, + ] { + assert!(predicate.property_chain().is_empty()); + assert!(predicate.super_predicate().is_none()); + } +} diff --git a/atomic-repository/Cargo.toml b/atomic-repository/Cargo.toml index 5d3b753f..a8a0384b 100644 --- a/atomic-repository/Cargo.toml +++ b/atomic-repository/Cargo.toml @@ -17,11 +17,15 @@ rust-version.workspace = true adoption-test-injection = [] # Request-local deterministic resource counters for query tests/benchmarks only. query-test-instrumentation = [] +# Full review policy evaluation needs the existing PurRDF engine (Rust 1.98). +# Consumers that keep the repository's lower MSRV do not accept this exception. +review-shacl = ["dep:atomic-shacl"] [dependencies] unicode-normalization = "0.1" atomic-core = { workspace = true } atomic-canonical = { workspace = true } +atomic-shacl = { workspace = true, optional = true } blake3 = { workspace = true } atomic-config = { workspace = true } atomic-identity = { workspace = true } diff --git a/atomic-repository/src/apply/types.rs b/atomic-repository/src/apply/types.rs index 76d97d76..4766a5be 100644 --- a/atomic-repository/src/apply/types.rs +++ b/atomic-repository/src/apply/types.rs @@ -149,7 +149,9 @@ pub struct InsertOptions { /// Internal escape hatch for callers that have ALREADY gated the complete /// reachable closure once (e.g. `insert_change_rec` gates the closure /// before looping). This never bypasses the gate for external callers: - /// the default is `false`, and every closure entry point re-gates. + /// the default is `false`, and external callers cannot set this field. + /// Nested closure entry points preserve a previously authorized batch so + /// inserting its first dependency does not invalidate its own review pin. /// Default: `false` pub(crate) skip_publication_gate: bool, } diff --git a/atomic-repository/src/intent_graph.rs b/atomic-repository/src/intent_graph.rs index 6fea26af..471038d1 100644 --- a/atomic-repository/src/intent_graph.rs +++ b/atomic-repository/src/intent_graph.rs @@ -42,6 +42,8 @@ pub struct IntentGraph { /// Recording an intent is evidence, not an implementation assertion. pub recording_changes: Vec, pub dependency_changes: Vec, + /// Exact review scope, never an implementation-attribution shortcut. + pub reviewed_changes: Vec, pub truncated: bool, pub missing_resources: Vec, pub diagnostics: Vec, @@ -88,6 +90,13 @@ enum Role { Turn, Attestation, View, + ReviewIntent, + Review, + ReviewSubject, + ReviewChange, + ReviewEvidence, + Judgment, + Evaluation, } impl IntentGraph { @@ -159,6 +168,7 @@ impl IntentGraph { let mut declared = BTreeSet::new(); let mut recording = BTreeSet::new(); let mut dependencies = BTreeSet::new(); + let mut reviewed = BTreeSet::new(); let mut truncated = false; // Join two facts already present in the snapshot: the vault entry's // repository path and a recorded File node. Do not use task file refs, @@ -186,6 +196,77 @@ impl IntentGraph { let next = if forward { &edge.to_id } else { &edge.from_id }; let predicate = edge.kind; let transition: Option> = match (role, forward, predicate) { + (Role::Root, false, P::Reviews) | (Role::Root, true, P::ReviewedBy) => { + Some(Some(Role::ReviewIntent)) + } + (Role::Root, false, P::HasReviewIntent) => Some(Some(Role::Review)), + (Role::Root, false, P::IncludesIntent | P::IncludesSetAside) => { + Some(Some(Role::ReviewSubject)) + } + (Role::Root, false, P::ObservedIntent) => Some(Some(Role::ReviewEvidence)), + (Role::ReviewIntent, false, P::HasReviewIntent) => Some(Some(Role::Review)), + ( + Role::ReviewIntent, + true, + P::HasTask | P::HasAcceptanceCriterion | P::HasConstraint, + ) => Some(Some(Role::Detail)), + (Role::ReviewIntent, true, P::Reviews | P::AuthoredBy) => Some(None), + (Role::Review, true, P::ReviewsClosure) => Some(Some(Role::ReviewSubject)), + (Role::Review, true, P::HasReviewIntent) => Some(Some(Role::ReviewIntent)), + (Role::Review, true, P::HasJudgment) => Some(Some(Role::Judgment)), + ( + Role::Review, + true, + P::SignedBy + | P::AuthoredBy + | P::VerificationResult + | P::FreshnessResult + | P::AuthorityResult, + ) => Some(None), + (Role::Review, false, P::EvaluatesReview) => Some(Some(Role::Evaluation)), + (Role::ReviewSubject, false, P::ReviewsClosure) => Some(Some(Role::Review)), + (Role::ReviewSubject, true, P::ReviewsChange) => Some(Some(Role::ReviewChange)), + ( + Role::ReviewSubject, + true, + P::IncludesIntent | P::IncludesSetAside | P::References, + ) => Some(None), + (Role::ReviewChange, true, P::DirectlyDependsOnChange) => { + Some(Some(Role::ReviewChange)) + } + (Role::ReviewEvidence, false, P::SubjectEvidence) => { + Some(Some(Role::ReviewSubject)) + } + (Role::ReviewSubject, true, P::SubjectEvidence) => { + Some(Some(Role::ReviewEvidence)) + } + (Role::Change, true, P::HasReviewEvidence) + if implementing.contains(&id) || recording.contains(&id) => + { + Some(Some(Role::ReviewEvidence)) + } + ( + Role::ReviewChange, + true, + P::ChangeExplainedBy | P::ModifiesFile | P::GeneratedBy, + ) => Some(None), + (Role::ReviewEvidence, true, P::References) => Some(Some(Role::ReviewEvidence)), + ( + Role::ReviewEvidence, + true, + P::EvidenceSource + | P::EvidenceTurn + | P::ObservedIntent + | P::FreshnessResult, + ) => Some(None), + (Role::ReviewEvidence, false, P::HasReviewEvidence) => { + Some(Some(Role::ReviewChange)) + } + (Role::Judgment, true, P::JudgesCriterion) => Some(Some(Role::Detail)), + (Role::Judgment, true, P::SupportedBy) => Some(None), + (Role::Detail, true, P::HasVerification) => Some(None), + (Role::Detail, false, P::JudgesCriterion) => Some(Some(Role::Judgment)), + (Role::Judgment, false, P::HasJudgment) => Some(Some(Role::Review)), (Role::IntentArtifact, false, P::ModifiesFile) if nodes .get(next.as_str()) @@ -212,8 +293,7 @@ impl IntentGraph { ( Role::Root, false, - P::Reviews - | P::ReviewedBy + P::ReviewedBy | P::Remediates | P::LinkedIntent | P::LinkedGoal @@ -309,6 +389,9 @@ impl IntentGraph { dependencies.insert(next.clone()); } } + if next_role == Some(Role::ReviewChange) { + reviewed.insert(next.clone()); + } if let Some(next_role) = next_role { queue.push_back((next.clone(), next_role)); } @@ -354,6 +437,21 @@ impl IntentGraph { if !declared.is_empty() { diagnostics.push(format!("{} implementing change(s) have explicit author declarations. Declarations do not repair or prove missing original plan_id/generating-turn provenance.", declared.len())); } + if !reviewed.is_empty() { + diagnostics.push(format!("{} change(s) are connected as review scope/evidence, not inferred implementation. Displayed review references and previews never authorize publication; SHACL evaluates the exact bounded subject separately.", reviewed.len())); + } + for node in &selected_nodes { + if node.has_type(C::ReviewEvaluation) { + diagnostics.push(node.label.clone()); + } + if node.has_type(C::PublicationReview) + && node.metadata.as_ref().is_some_and(|m| { + m.get("review_reference").and_then(|v| v.as_bool()) == Some(true) + }) + { + diagnostics.push("Retained review document references are shown without revalidation; this is not a current approval verdict.".into()); + } + } if truncated { diagnostics.push("Node limit reached: selection and dependency closure are incomplete. Increase --max-nodes.".into()); } @@ -388,7 +486,11 @@ impl IntentGraph { snapshot_identity: snapshot.identity.clone(), generation: snapshot.generation, ontology_version: snapshot.ontology_version.into(), - scope: "intent_asserted_lineage_and_recording_evidence_with_dependency_closure", + scope: if reviewed.is_empty() { + "intent_asserted_lineage_and_recording_evidence_with_dependency_closure" + } else { + "intent_asserted_lineage_recording_and_review_evidence_with_dependency_closure" + }, nodes: selected_nodes, edges, implementing_changes: implementing.into_iter().collect(), @@ -397,6 +499,7 @@ impl IntentGraph { intent_artifact, recording_changes: recording.into_iter().collect(), dependency_changes: dependencies.into_iter().collect(), + reviewed_changes: reviewed.into_iter().collect(), truncated, missing_resources: missing.into_iter().collect(), diagnostics, diff --git a/atomic-repository/src/repository/changes.rs b/atomic-repository/src/repository/changes.rs index 1343576c..a063790e 100644 --- a/atomic-repository/src/repository/changes.rs +++ b/atomic-repository/src/repository/changes.rs @@ -484,6 +484,7 @@ impl Repository { &self, attestation: &atomic_core::change::Attestation, ) -> Result { + let _review_boundary = self.review_evidence_lock()?; self.ensure_project_identity(atomic_core::kg::project_id::MintReason::Upgrade)?; use atomic_core::pristine::MutTxnT; @@ -613,6 +614,7 @@ impl Repository { &self, manifest: &atomic_core::change::session::SessionManifest, ) -> Result { + let _review_boundary = self.review_evidence_lock()?; self.ensure_project_identity(atomic_core::kg::project_id::MintReason::Upgrade)?; let mut txn = self .pristine @@ -633,6 +635,7 @@ impl Repository { /// files are reported in the result rather than aborting the rebuild. /// Returns `(indexed_count, skipped_existing, corrupt_count)`. pub fn rebuild_session_index(&self) -> Result<(usize, usize, usize), RepositoryError> { + let _review_boundary = self.review_evidence_lock()?; self.ensure_project_identity(atomic_core::kg::project_id::MintReason::Upgrade)?; let mut indexed = 0usize; let mut skipped = 0usize; @@ -826,6 +829,7 @@ impl Repository { parent_view: Option, ended_at: Option, ) -> Result<(), RepositoryError> { + let _review_boundary = self.review_evidence_lock()?; self.ensure_project_identity(atomic_core::kg::project_id::MintReason::Upgrade)?; let json_path = self .dot_dir @@ -855,6 +859,7 @@ impl Repository { parent_view: Option, incomplete: &atomic_core::change::session::IncompleteSession, ) -> Result { + let _review_boundary = self.review_evidence_lock()?; self.ensure_project_identity(atomic_core::kg::project_id::MintReason::Upgrade)?; let json_path = self .dot_dir @@ -1439,6 +1444,7 @@ impl Repository { &self, graph: &atomic_core::change::ProvenanceGraph, ) -> Result { + let _review_boundary = self.review_evidence_lock()?; self.ensure_project_identity(atomic_core::kg::project_id::MintReason::Upgrade)?; use atomic_core::pristine::MutTxnT; diff --git a/atomic-repository/src/repository/history.rs b/atomic-repository/src/repository/history.rs index 042615b3..29b52a5e 100644 --- a/atomic-repository/src/repository/history.rs +++ b/atomic-repository/src/repository/history.rs @@ -660,6 +660,7 @@ impl Repository { hash: &Hash, at_sequence: Option, ) -> Result<(Merkle, u64), RepositoryError> { + let _review_boundary = self.review_evidence_lock()?; let view = self.authoritative_working_copy_view_name()?; self.reinsert_change_on_view(&view, hash, at_sequence) } @@ -758,6 +759,7 @@ impl Repository { view_name: &str, target: &HashSet, ) -> Result, RepositoryError> { + let _review_boundary = self.review_evidence_lock()?; let mut txn = self .pristine .write_txn() diff --git a/atomic-repository/src/repository/insert.rs b/atomic-repository/src/repository/insert.rs index c40f8882..93718244 100644 --- a/atomic-repository/src/repository/insert.rs +++ b/atomic-repository/src/repository/insert.rs @@ -2422,6 +2422,7 @@ impl Repository { hash: &Hash, options: InsertOptions, ) -> Result { + let _review_boundary = self.review_evidence_lock()?; let change = self.load_change(hash)?; let view_name = options .view @@ -2858,6 +2859,7 @@ impl Repository { hash: &Hash, mut options: InsertOptions, ) -> Result { + let _review_boundary = self.review_evidence_lock()?; let _span_lock = if self.span_in_closure(std::slice::from_ref(hash))? { let lock = self.try_lock_workspace_operation(self.require_working_copy_id()?)?; self.preflight_span_references( @@ -2942,7 +2944,7 @@ impl Repository { // closure, so coverage is complete and diagnostics are exact. if !to_insert.is_empty() { let shared_target = view.kind == atomic_core::pristine::ViewScope::Shared; - if shared_target { + if shared_target && !options.skip_publication_gate { let closure = super::provenance_gate::reachable_closure(self, &to_insert)?; let provider = super::provenance_gate::local_session_mac_key_provider(self); let did_provider = super::provenance_gate::local_did_key_provider(self); @@ -3055,6 +3057,7 @@ impl Repository { mut options: InsertOptions, removal: Option<(&str, Hash)>, ) -> Result { + let _review_boundary = self.review_evidence_lock()?; if self.is_remote_sandbox() { return self.submit_recorded(outcome); } @@ -3404,6 +3407,11 @@ impl Repository { &self, options: CrossViewInsertOptions, ) -> Result { + let _review_boundary = if options.dry_run { + None + } else { + self.review_evidence_lock()? + }; let trace_insert = std::env::var_os("ATOMIC_TRACE_INSERT").is_some(); let t0 = std::time::Instant::now(); diff --git a/atomic-repository/src/repository/locks.rs b/atomic-repository/src/repository/locks.rs index df9e43ab..8f1dabd2 100644 --- a/atomic-repository/src/repository/locks.rs +++ b/atomic-repository/src/repository/locks.rs @@ -322,6 +322,31 @@ impl Repository { self.try_lock_common_operation_with_reentrancy(false) } + /// Participate in an existing same-thread operation for evidence writes, + /// without turning a non-reentrant operation into a reentrant one. This is + /// an alias of an already-held boundary, not a new independent operation. + pub(super) fn review_evidence_common_lock( + &self, + ) -> Result { + let path = self.common_operation_lock_path(); + let alias = HELD_LOCKS.with(|held| { + let mut held = held.borrow_mut(); + let (count, file, reentrant) = held.get_mut(&path)?; + let file = file.upgrade()?; + *count += 1; + Some((file, *reentrant)) + }); + if let Some((file, reentrant)) = alias { + return Ok(RepositoryCommonLockGuard { + _common_lock: AdvisoryFileLock { file, path }, + dot_dir: self.dot_dir.clone(), + pristine: Arc::clone(&self.pristine), + reentrant, + }); + } + self.try_lock_common_operation_with_reentrancy(true) + } + pub(super) fn try_lock_common_operation_with_reentrancy( &self, reentrant: bool, diff --git a/atomic-repository/src/repository/mod.rs b/atomic-repository/src/repository/mod.rs index f5cb2fef..f6e2b3ad 100644 --- a/atomic-repository/src/repository/mod.rs +++ b/atomic-repository/src/repository/mod.rs @@ -260,6 +260,7 @@ mod kg_rebuild; mod project_identity; pub mod provenance_gate; mod provenance_summary; +pub mod publication_review; pub use project_identity::{ build_project_identity, project_identity_hash, verify_project_identity, IdentityAdoption, }; diff --git a/atomic-repository/src/repository/provenance_gate.rs b/atomic-repository/src/repository/provenance_gate.rs index 1c3d0347..ca4a25cc 100644 --- a/atomic-repository/src/repository/provenance_gate.rs +++ b/atomic-repository/src/repository/provenance_gate.rs @@ -291,6 +291,15 @@ pub struct GateVerdict { /// Honest statement of what this verdict does NOT prove (CB-12A open /// findings, policy-dependent gaps). Never empty for a managed gate run. pub limitations: Vec, + /// Present-day exact-change approvals; never original-session attestations. + pub retrospective_reviews: Vec, +} + +#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)] +pub struct RetrospectiveApproval { + pub change: String, + pub session: String, + pub review_hash: String, } impl GateVerdict { @@ -494,6 +503,7 @@ impl Repository { managed_changes: 0, blocks: Vec::new(), limitations: default_limitations(), + retrospective_reviews: Vec::new(), }; // Per-session caches: ledger status and MAC keys are session-scoped; @@ -675,7 +685,14 @@ impl Repository { // signature, trusted signer. EVERY same-session attestation must // verify: a second attestation that fails under the session key // is tamper/forgery evidence, never an alternative to trust. - let attestations = self.find_attestations_for_change(hash).unwrap_or_default(); + let attestations = if self + .vault_list(super::publication_review::PREFIX, None)? + .is_empty() + { + self.find_attestations_for_change(hash).unwrap_or_default() + } else { + self.review_original_attestations(hash)? + }; let same_session: Vec<_> = attestations .iter() .filter(|(_, attest)| attest.session_id == session) @@ -775,10 +792,29 @@ impl Repository { match check { None => { - verdict.blocks.push(GateBlocker::MissingAttestation { - change: change_b32.clone(), - session: session.clone(), - }); + match self.retrospective_review_for( + &change_b32, + &session, + config, + did_key_provider, + ) { + Ok(Some(review_hash)) => { + verdict.retrospective_reviews.push(RetrospectiveApproval { + change: change_b32.clone(), + session: session.clone(), + review_hash, + }); + } + outcome => { + if let Err(error) = outcome { + verdict.limitations.push(error.to_string()); + } + verdict.blocks.push(GateBlocker::MissingAttestation { + change: change_b32.clone(), + session: session.clone(), + }); + } + } } Some(AttestationCheck { hash: attest_b32, diff --git a/atomic-repository/src/repository/publication_review/artifact.rs b/atomic-repository/src/repository/publication_review/artifact.rs new file mode 100644 index 00000000..18d8d7db --- /dev/null +++ b/atomic-repository/src/repository/publication_review/artifact.rs @@ -0,0 +1,65 @@ +//! Materialize without following pre-existing symlinks or overwriting user files. +use super::*; +use std::{ + io::Write, + path::{Path, PathBuf}, +}; + +pub(super) fn destination(repo: &Repository, hash: &str) -> Result { + let mut path = repo.vault_dir(); + for component in [None, Some("publication-reviews"), Some(hash)] { + if let Some(component) = component { + path.push(component); + } + match std::fs::symlink_metadata(&path) { + Ok(metadata) if metadata.file_type().is_dir() => {} + Ok(_) => { + return Err(refused( + "review materialization parent is not a regular directory", + )) + } + Err(error) if error.kind() == std::io::ErrorKind::NotFound => { + std::fs::create_dir(&path)? + } + Err(error) => return Err(error.into()), + } + } + Ok(path.join("review.md")) +} + +pub(super) fn write( + repo: &Repository, + vault_path: &str, + disk_path: &Path, +) -> Result<(), RepositoryError> { + let entry = repo + .vault_retrieve(vault_path)? + .ok_or_else(|| refused("stored review disappeared"))?; + let expected = super::super::vault::render_entry_to_markdown(&entry); + match std::fs::symlink_metadata(disk_path) { + Ok(metadata) + if metadata.file_type().is_file() + && std::fs::read(disk_path)? == expected.as_bytes() => + { + return Ok(()) + } + Ok(_) => { + return Err(refused( + "refusing to overwrite a modified or non-regular review file", + )) + } + Err(error) if error.kind() == std::io::ErrorKind::NotFound => {} + Err(error) => return Err(error.into()), + } + let parent = disk_path + .parent() + .ok_or_else(|| refused("review has no destination parent"))?; + let mut file = tempfile::NamedTempFile::new_in(parent)?; + file.write_all(expected.as_bytes())?; + file.as_file().sync_all()?; + file.persist_noclobber(disk_path) + .map_err(|error| refused(error.error))?; + #[cfg(unix)] + std::fs::File::open(parent)?.sync_all()?; + Ok(()) +} diff --git a/atomic-repository/src/repository/publication_review/graph.rs b/atomic-repository/src/repository/publication_review/graph.rs new file mode 100644 index 00000000..e9212d3c --- /dev/null +++ b/atomic-repository/src/repository/publication_review/graph.rs @@ -0,0 +1,468 @@ +//! A verifier-owned, request-scoped dataset. Caller-supplied graph assertions +//! never enter this path. Policy lives in review-1.0.0.ttl. +use super::*; +use atomic_canonical::{node::CanonicalNode, publication_review::IntentPin}; +use atomic_core::{ + kg::{ + iri, + ontology::{Class as C, Predicate as P}, + }, + KgEdge, KgNode, +}; +use serde_json::json; + +struct Graph { + nodes: Vec, + edges: Vec, +} +impl Graph { + fn node(&mut self, id: &str, class: C) { + if let Some(node) = self.nodes.iter_mut().find(|node| node.id == id) { + if !node.types.iter().any(|kind| kind == class.iri()) { + node.types.push(class.iri().to_owned()); + } + } else { + self.nodes.push(KgNode::new( + id, + class, + format!( + "{} {}", + class.curie(), + id.rsplit(':') + .next() + .unwrap_or(id) + .chars() + .take(28) + .collect::() + ), + "publication-review", + )); + } + } + fn edge(&mut self, from: &str, to: &str, predicate: P) { + self.edges.push(KgEdge::new(from, to, predicate)); + } + fn result(&mut self, id: &str, predicate: P, passed: bool) { + let status = format!( + "https://atomic.dev/ns/workflow#{}", + if passed { "Verified" } else { "Failed" } + ); + self.node(&status, C::VerificationStatus); + self.edge(id, &status, predicate); + } + fn metadata(&mut self, id: &str, metadata: serde_json::Value) { + if let Some(node) = self.nodes.iter_mut().find(|node| node.id == id) { + node.metadata = Some(metadata); + } + } +} + +fn intent_iri(repo: &Repository, id: &str) -> Result { + iri::mint_intent( + &repo.project_id()?, + id.strip_prefix("urn:atomic:intent:").unwrap_or(id), + ) + .map_err(refused) +} + +fn add_intent( + repo: &Repository, + graph: &mut Graph, + node: &CanonicalNode, + pin: &IntentPin, + keys: DidKeyProvider<'_>, + preview: bool, +) -> Result { + let id = intent_iri(repo, &node.id)?; + graph.node( + &id, + if node.kind == "review" { + C::ReviewIntent + } else { + C::WorkIntent + }, + ); + graph.metadata( + &id, + json!({"status":node.status,"title":node.title, + "source_hash":pin.source_hash,"signed_hash":pin.signed_hash, + "public_key":pin.public_key}), + ); + if let Some(projected) = graph.nodes.iter_mut().find(|projected| projected.id == id) { + projected.label = node.title.clone(); + } + graph.result(&id, P::VerificationResult, true); // subject::intent authenticated the signature + graph.result( + &id, + P::FreshnessResult, + subject::intent(repo, &node.id, keys).is_ok(), + ); + graph.result( + &id, + P::CanonicalConformance, + atomic_canonical::validate_intent(node).conforms, + ); + let did = node + .attributed_to + .as_deref() + .ok_or_else(|| refused("missing intent author"))?; + graph.node(did, C::Identity); + let key_id = format!("urn:atomic:signing-key:{}", pin.public_key); + graph.node(&key_id, C::SigningKey); + graph.edge(did, &key_id, P::SigningKey); + graph.edge(&id, did, P::AuthoredBy); + for (i, ac) in node.has_acceptance_criterion.iter().enumerate() { + let criterion = format!("{id}:criterion:{i}"); + graph.node(&criterion, C::AcceptanceCriterion); + graph.metadata( + &criterion, + json!({"status":ac.ac_status,"evidence":ac.evidence, + "verified_by":ac.verified_by,"required_kinds":ac.required_kinds}), + ); + graph.edge(&id, &criterion, P::HasAcceptanceCriterion); + for (j, record) in ac.verifications.iter().enumerate() { + let verification = format!("{criterion}:verification:{j}"); + graph.node(&verification, C::VerificationRecord); + graph.metadata( + &verification, + json!({"status":record.outcome, + "verification_kind":record.kind,"observed_state":record.observed_at_merkle, + "verification_reference":record.reference}), + ); + graph.edge(&criterion, &verification, P::HasVerification); + } + } + for reference in &node.depends_on { + if reference.edge == "reviews" { + let (work, _) = subject::read_intent(repo, &reference.to, keys, preview)?; + graph.edge(&id, &intent_iri(repo, &work.id)?, P::Reviews); + } + if reference.edge == "implementsChange" + && reference + .declaration_evidence + .as_deref() + .is_some_and(|e| !e.trim().is_empty()) + { + let hash = iri::parse_change(&reference.to).map_err(refused)?; + graph.edge(&id, &iri::mint_change(&hash), P::DeclaresImplementation); + } + } + Ok(id) +} + +pub(super) fn build( + repo: &Repository, + review: &PublicationReview, + config: &PublicationGateConfig, + keys: DidKeyProvider<'_>, + preview: bool, +) -> Result<(Vec, Vec), RepositoryError> { + PublicationReview::parse(&serde_json::to_vec(review).map_err(refused)?).map_err(refused)?; + if review.schema != SCHEMA + && review.schema != atomic_canonical::publication_review::LEGACY_SCHEMA + { + return Err(refused("unsupported review schema")); + } + chrono::DateTime::parse_from_rfc3339(&review.reviewed_at).map_err(refused)?; + let bytes = + keys(&review.attributed_to).ok_or_else(|| refused("review signing key unavailable"))?; + let key = key(bytes)?; + if !atomic_canonical::did::did_matches_public_key(&review.attributed_to, &key) { + return Err(refused("review identity does not match its key")); + } + let signed = review.proof.is_some(); + if signed || !preview { + atomic_canonical::proof::verify_value(&review.value(), &key).map_err(refused)?; + } + let roots = review + .subject + .roots + .iter() + .map(|hash| { + Hash::from_base32(hash.as_bytes()) + .filter(|parsed| parsed.to_base32() == *hash) + .ok_or_else(|| refused("review roots must be full canonical hashes")) + }) + .collect::, _>>()?; + let selected = review + .subject + .view_chain + .first() + .ok_or_else(|| refused("review source perspective is missing"))?; + let retained = if review.schema == SCHEMA { + super::snapshot::verify(repo, &review.subject)?; + Some(&review.subject) + } else { + None + }; + let current = subject::build_with_mode( + repo, + review + .subject + .review + .id + .strip_prefix("urn:atomic:intent:") + .unwrap_or(&review.subject.review.id), + &roots, + &selected.name, + keys, + preview, + retained, + )?; + let fresh = current == review.subject; + let mut graph = Graph { + nodes: Vec::new(), + edges: Vec::new(), + }; + let artifact = super::references::artifact_id(review)?; + let subject_id = super::references::subject_id(review)?; + graph.node("urn:atomic:review:evaluation", C::ReviewEvaluation); + graph.node(&artifact, C::PublicationReview); + graph.metadata( + &artifact, + json!({"status":if signed {"signed"} else {"unsigned-preview"}, + "review_ontology":atomic_core::kg::ontology::REVIEW_VERSION_IRI}), + ); + graph.node(&subject_id, C::ReviewSubject); + graph.metadata( + &subject_id, + json!({"reviewed_state":current.view_chain[0].state, + "reviewed_context":format!("urn:atomic:view-set:{}",current.effective_set_id), + "pinned_source":review.subject.view_chain, + "pinned_effective_set_id":review.subject.effective_set_id, + "source_context":if retained.is_some() {"retained-immutable"} else {"legacy-live-view"}, + "current_intent_revisions_match":fresh, + "current_source":current.view_chain,"fresh":fresh}), + ); + for pin in ¤t.view_chain { + let view = iri::mint_view(&repo.project_id()?, &pin.name); + graph.node(&view, C::View); + graph.metadata( + &view, + json!({"name":pin.name,"state":pin.state, + "historical_reference":retained.is_some(),"requires_live_view":retained.is_none()}), + ); + graph.edge(&subject_id, &view, P::References); + } + graph.edge( + "urn:atomic:review:evaluation", + &artifact, + P::EvaluatesReview, + ); + graph.edge(&artifact, &subject_id, P::ReviewsClosure); + if let Some(snapshot) = &review.subject.snapshot { + let evidence = format!("{subject_id}:retained-source"); + graph.node(&evidence, C::ReviewEvidence); + graph.metadata(&evidence,json!({"kind":"retained-source-snapshot", + "membership":snapshot.membership,"effective_set_id":review.subject.effective_set_id, + "authenticated_intent_revisions":snapshot.intent_revisions.iter().map(|revision|&revision.id).collect::>(), + "requires_live_view":false})); + graph.edge(&subject_id, &evidence, P::References); + } + graph.result(&artifact, P::VerificationResult, signed); + graph.result(&artifact, P::FreshnessResult, fresh); + graph.result( + &artifact, + P::AuthorityResult, + config + .trust + .evaluate(&review.attributed_to, config.repository_identity.as_deref()) + == atomic_config::SignerTrust::Trusted, + ); + graph.node(&review.attributed_to, C::Identity); + if signed { + graph.edge(&artifact, &review.attributed_to, P::SignedBy); + } else { + graph.edge(&artifact, &review.attributed_to, P::AuthoredBy); + } + let key_id = format!("urn:atomic:signing-key:{}", key.to_base32()); + graph.node(&key_id, C::SigningKey); + graph.edge(&review.attributed_to, &key_id, P::SigningKey); + let (review_node, review_pin) = subject::read_intent(repo, ¤t.review.id, keys, preview)?; + let review_id = add_intent(repo, &mut graph, &review_node, &review_pin, keys, preview)?; + graph.edge(&artifact, &review_id, P::HasReviewIntent); + for (i, ac) in review_node.has_acceptance_criterion.iter().enumerate() { + let criterion = format!("{review_id}:criterion:{i}"); + let judgment = format!("{artifact}:judgment:{i}"); + graph.node(&judgment, C::CriterionJudgment); + graph.metadata( + &judgment, + json!({"status":ac.ac_status,"meaning":"reviewer assertion, not original execution"}), + ); + graph.edge(&artifact, &judgment, P::HasJudgment); + graph.edge(&judgment, &criterion, P::JudgesCriterion); + for j in 0..ac.verifications.len() { + graph.edge( + &judgment, + &format!("{criterion}:verification:{j}"), + P::SupportedBy, + ); + } + } + for work in ¤t.work { + let (node, pin) = subject::read_intent(repo, &work.id, keys, preview)?; + let work_id = add_intent(repo, &mut graph, &node, &pin, keys, preview)?; + graph.edge(&subject_id, &work_id, P::IncludesIntent); + } + for disposition in ¤t.set_aside { + let (node, pin) = subject::read_intent(repo, &disposition.id, keys, preview)?; + let id = add_intent(repo, &mut graph, &node, &pin, keys, preview)?; + graph.edge(&subject_id, &id, P::IncludesSetAside); + } + let mut projected_intents: std::collections::BTreeSet<_> = current + .work + .iter() + .chain(current.set_aside.iter()) + .map(|pin| pin.id.clone()) + .chain(std::iter::once(current.review.id.clone())) + .collect(); + for pin in ¤t.changes { + let hash = + Hash::from_base32(pin.hash.as_bytes()).ok_or_else(|| refused("bad change hash"))?; + let id = iri::mint_change(&hash); + graph.node(&id, C::Change); + graph.metadata( + &id, + json!({"status":if pin.session.is_some() {"managed"} else {"unmanaged"}, + "review_role":if current.roots.contains(&pin.hash) {"selected-root"} else {"dependency"}, + "object_availability":"available","projection_completeness":"projected"}), + ); + graph.edge(&subject_id, &id, P::ReviewsChange); + graph.edge(&artifact, &id, P::CoversChange); + graph.edge(&id, &artifact, P::AttestedBy); + if let Some(session_id) = &pin.session { + let project = repo.project_id()?; + let session = iri::mint_session(&project, session_id); + graph.node(&session, C::Session); + let turns = repo + .get_session_ledger(session_id)? + .map(|(_, turns)| turns) + .unwrap_or_default(); + let matching: Vec<_> = turns + .iter() + .filter(|turn| turn.change_hashes.contains(&hash)) + .collect(); + for row in matching { + let turn = iri::mint_turn(&project, session_id, row.turn_number); + graph.node(&turn, C::SessionTurn); + graph.edge(&session, &turn, P::HasTurn); + graph.edge(&turn, &id, P::GeneratedChange); + for evidence in &pin.provenance { + let hash = Hash::from_base32(evidence.as_bytes()) + .ok_or_else(|| refused("invalid provenance hash"))?; + let provenance = iri::mint_provenance(&hash); + graph.node(&provenance, C::ProvenanceGraph); + if row.provenance_hash == hash { + graph.edge(&turn, &provenance, P::TurnExplainedBy); + } + graph.edge(&id, &provenance, P::ChangeExplainedBy); + } + } + for code in [ + "MissingIntentEvidence", + "MissingProvenance", + "MissingAttestation", + ] { + let missing = match code { + "MissingIntentEvidence" => pin.observations.is_empty(), + "MissingProvenance" => pin.provenance.is_empty(), + _ => repo.review_original_attestations(&hash)?.is_empty(), + }; + if missing { + let finding = format!("{artifact}:change:{}:review-gap:{code}", pin.hash); + graph.node(&finding, C::ReviewFinding); + graph.metadata(&finding, json!({"finding_code":code})); + graph.edge(&finding, &id, P::AboutResource); + } + } + } + for (i, observation) in pin.observations.iter().enumerate() { + let evidence = format!("{artifact}:change:{}:observation:{i}", pin.hash); + graph.node(&evidence, C::IntentObservation); + graph.node(&evidence, C::ReviewEvidence); + if let Some(node) = graph.nodes.iter_mut().find(|node| node.id == evidence) { + node.label = format!( + "{}: {} ({})", + observation.kind, observation.reference, observation.resolution + ); + } + graph.metadata( + &evidence, + json!({"status":observation.resolution, + "observation_kind":observation.kind,"source_node":observation.node, + "observation_role":observation.role, + "source_hash":observation.provenance,"session":observation.session, + "source_reference":observation.reference, + "diagnostic":observation.diagnostic, + "meaning":"retained receipt, not governing authority or execution verification"}), + ); + graph.edge(&id, &evidence, P::HasReviewEvidence); + graph.edge(&subject_id, &evidence, P::SubjectEvidence); + if let Some(revision) = &observation.retained_revision { + let revision_id = format!( + "urn:atomic:review-revision:{}", + revision.signed_hash.replace(':', "-") + ); + graph.node(&revision_id, C::ReviewEvidence); + graph.metadata( + &revision_id, + json!({"signed_hash":revision.signed_hash, + "public_key":revision.public_key,"source_relation":revision.source_relation, + "signature_verified":true, + "meaning":"retained signed document; does not authorize current work"}), + ); + graph.edge(&evidence, &revision_id, P::References); + } + let hash = Hash::from_base32(observation.provenance.as_bytes()) + .ok_or_else(|| refused("invalid observation provenance hash"))?; + let provenance = iri::mint_provenance(&hash); + graph.node(&provenance, C::ProvenanceGraph); + graph.edge(&evidence, &provenance, P::EvidenceSource); + graph.edge(&id, &provenance, P::ChangeExplainedBy); + let project = repo.project_id()?; + let session = iri::mint_session(&project, &observation.session); + graph.node(&session, C::Session); + for number in &observation.turns { + let turn = iri::mint_turn(&project, &observation.session, *number); + graph.node(&turn, C::SessionTurn); + graph.edge(&session, &turn, P::HasTurn); + graph.edge(&turn, &provenance, P::TurnExplainedBy); + graph.edge(&evidence, &turn, P::EvidenceTurn); + } + if let Some(target) = &observation.intent { + let target_id = intent_iri(repo, target)?; + if projected_intents.insert(target.clone()) { + match subject::read_intent(repo, target, keys, true) { + Ok((node, pin)) => { + add_intent(repo, &mut graph, &node, &pin, keys, true)?; + } + Err(error) => { + graph.node(&target_id, C::WorkIntent); + graph.metadata(&target_id,json!({"projection_error":error.to_string(),"meaning":"unresolved intent reference, not absent historical evidence"})); + } + } + } + graph.node(&target_id, C::WorkIntent); + graph.edge(&evidence, &target_id, P::ObservedIntent); + } + if observation.resolution != "resolved" + || pin + .session + .as_ref() + .is_some_and(|s| s != &observation.session) + { + graph.result(&evidence, P::FreshnessResult, false); + let finding = format!("{evidence}:finding"); + graph.node(&finding, C::ReviewFinding); + graph.metadata(&finding, json!({"finding_code":"UnresolvedIntentEvidence","status":observation.resolution})); + graph.edge(&finding, &evidence, P::AboutResource); + } else { + graph.result(&evidence, P::FreshnessResult, true); + } + } + for dep in repo.load_change(&hash)?.dependencies() { + graph.edge(&id, &iri::mint_change(dep), P::DirectlyDependsOnChange); + } + } + Ok((graph.nodes, graph.edges)) +} diff --git a/atomic-repository/src/repository/publication_review/mod.rs b/atomic-repository/src/repository/publication_review/mod.rs new file mode 100644 index 00000000..0ca9c729 --- /dev/null +++ b/atomic-repository/src/repository/publication_review/mod.rs @@ -0,0 +1,591 @@ +//! Exact-scope retrospective publication reviews. Canonical objects are the +//! authority; verifier-owned graph observations and SHACL are rebuilt on use. +#[cfg(feature = "review-shacl")] +mod artifact; +#[cfg(feature = "review-shacl")] +mod graph; +mod observations; +pub(crate) mod references; +mod snapshot; +mod subject; +#[cfg(all(test, feature = "review-shacl"))] +mod tests; + +use super::provenance_gate::{DidKeyProvider, PublicationGateConfig}; +use super::{Repository, RepositoryError}; +use atomic_canonical::publication_review::{PublicationReview, SCHEMA}; +use atomic_core::types::{Base32, Hash}; + +pub const PREFIX: &str = "publication-reviews/"; + +pub(super) fn refused(error: impl std::fmt::Display) -> RepositoryError { + RepositoryError::InvalidOperation { + message: format!("publication review: {error}"), + } +} + +/// Pin the actual executable shapes and ontology, not a caller-chosen version label. +pub fn profile_hash() -> String { + let mut hash = blake3::Hasher::new(); + for bytes in [ + b"atomic.review-policy.v3\0".as_slice(), + atomic_core::kg::ontology::TTL.as_bytes(), + include_bytes!("../../../../atomic-core/ontology/shapes/review-1.0.0.ttl").as_slice(), + ] { + hash.update(&(bytes.len() as u64).to_be_bytes()); + hash.update(bytes); + } + #[cfg(feature = "review-shacl")] + hash.update(atomic_shacl::ENGINE_VERSION.as_bytes()); + #[cfg(not(feature = "review-shacl"))] + hash.update(b"unavailable-validator"); + hash.finalize().to_hex().to_string() +} + +impl Repository { + /// Writers affecting review evidence participate in the common operation + /// boundary once retrospective artifacts exist. No feature means no bypass. + pub(super) fn review_evidence_lock( + &self, + ) -> Result, RepositoryError> { + if self.vault_list(PREFIX, None)?.is_empty() { + return Ok(None); + } + self.review_evidence_common_lock().map(Some) + } + /// Prepare a present-day review from fresh signed intents and exact original + /// changes. This does not grant trust, sign, store, or publish anything. + pub fn prepare_publication_review( + &self, + review_id: &str, + roots: &[Hash], + keys: DidKeyProvider<'_>, + ) -> Result { + self.prepare_publication_review_on_view(review_id, roots, self.current_view(), keys) + } + + pub fn prepare_publication_review_on_view( + &self, + review_id: &str, + roots: &[Hash], + view: &str, + keys: DidKeyProvider<'_>, + ) -> Result { + let subject = subject::build(self, review_id, roots, view, keys)?; + let (node, _) = subject::intent(self, review_id, keys)?; + let review = PublicationReview { + schema: SCHEMA.into(), + reviewed_at: chrono::Utc::now().to_rfc3339(), + subject, + supersedes: Vec::new(), + attributed_to: node + .attributed_to + .ok_or_else(|| refused("missing reviewer"))?, + content_hash: None, + proof: None, + }; + PublicationReview::parse(&serde_json::to_vec(&review).map_err(refused)?) + .map_err(refused)?; + Ok(review) + } + + /// Rebuild authenticated observations and evaluate the complete pinned review + /// dataset. No supplied RDF or `Verified` assertion is an authorization input. + #[cfg(feature = "review-shacl")] + pub fn validate_publication_review( + &self, + review: &PublicationReview, + config: &PublicationGateConfig, + keys: DidKeyProvider<'_>, + ) -> Result { + let snapshot = self.publication_review_snapshot(review, config, keys)?; + let data = + atomic_shacl::snapshot_ntriples(&snapshot.nodes, &snapshot.edges).map_err(refused)?; + atomic_shacl::validate_ntriples( + &data, + &review.artifact_hash(), + &atomic_shacl::ValidationRequest { + profile: atomic_shacl::Profile::Review, + ..Default::default() + }, + ) + .map_err(refused) + } + + /// A rebuildable, review-subject-scoped KG projection over canonical signed + /// originals. It is not a new project-wide knowledge base or an authority + /// store. Signature, source and policy observations are recomputed each time. + #[cfg(feature = "review-shacl")] + pub fn publication_review_snapshot( + &self, + review: &PublicationReview, + config: &PublicationGateConfig, + keys: DidKeyProvider<'_>, + ) -> Result { + self.review_snapshot(review, config, keys, false) + } + + /// Inspect unsigned evidence with the same resolver and executable policy. + /// Never used by the publication gate; absent proof stays a failing check. + #[cfg(feature = "review-shacl")] + pub fn preview_publication_review( + &self, + review: &PublicationReview, + config: &PublicationGateConfig, + keys: DidKeyProvider<'_>, + ) -> Result<(super::WorkflowSnapshot, atomic_shacl::ValidationOutput), RepositoryError> { + let mut snapshot = self.review_snapshot(review, config, keys, true)?; + let data = + atomic_shacl::snapshot_ntriples(&snapshot.nodes, &snapshot.edges).map_err(refused)?; + let validation = atomic_shacl::validate_ntriples( + &data, + &review.artifact_hash(), + &atomic_shacl::ValidationRequest { + profile: atomic_shacl::Profile::Review, + ..Default::default() + }, + ) + .map_err(refused)?; + // Put executable-policy diagnostics into the exported graph as well, so + // DOT/HTML and JSON show the same blockers. This never feeds validation. + for (i, result) in validation.results.iter().enumerate() { + use atomic_core::kg::ontology::{Class, Predicate}; + let id = format!("urn:atomic:review:preview-finding:{i}"); + let message = result + .get("result_messages") + .and_then(|messages| messages.as_array()) + .and_then(|messages| messages.first()) + .and_then(|message| message.get("value")) + .and_then(|value| value.as_str()) + .or_else(|| { + result + .get("source_constraint_component") + .and_then(|value| value.as_str()) + }) + .unwrap_or("Review policy violation"); + let mut node = atomic_core::KgNode::new( + &id, + Class::ReviewFinding, + format!("SHACL: {message}"), + "publication-review-preview", + ); + node.metadata = Some(result.clone()); + snapshot.nodes.push(node); + snapshot.edges.push(atomic_core::KgEdge::new( + &id, + "urn:atomic:review:evaluation", + Predicate::AboutResource, + )); + } + snapshot.identity = + Hash::of(&serde_json::to_vec(&(&snapshot.nodes, &snapshot.edges)).map_err(refused)?) + .to_base32(); + Ok((snapshot, validation)) + } + + /// Add an authenticated, bounded review preview to the existing workflow + /// snapshot for intent-graph selection. Never a publication authorization. + /// Unsupported consumers fail closed instead of displaying an unvalidated + /// caller-supplied graph as verifier evidence. + pub fn workflow_snapshot_with_review( + &self, + bytes: &[u8], + ) -> Result<(super::WorkflowSnapshot, String), RepositoryError> { + #[cfg(not(feature = "review-shacl"))] + { + let _ = bytes; + Err(refused( + "review-shacl feature is required for review preview", + )) + } + #[cfg(feature = "review-shacl")] + { + let review = PublicationReview::parse(bytes).map_err(refused)?; + let config = PublicationGateConfig::from_repo(self)?; + let keys = super::provenance_gate::local_did_key_provider(self); + let (mut preview, validation) = + self.preview_publication_review(&review, &config, &keys)?; + let context = review.artifact_hash(); + // Evaluation and report identities are request-local in validation, + // but must be review-scoped when connected to the intent graph. + let scoped = |id: &str| { + if id == "urn:atomic:review:evaluation" + || id.starts_with("urn:atomic:review:preview-finding:") + { + format!("{id}:{context}") + } else { + id.to_owned() + } + }; + for node in &mut preview.nodes { + node.id = scoped(&node.id); + if node.has_type(atomic_core::kg::ontology::Class::ReviewEvaluation) { + node.label = format!( + "Review preview: {} ({} SHACL findings); not publication approval", + if validation.conforms { + "conforms" + } else { + "blocked" + }, + validation.results.len() + ); + node.metadata = Some(serde_json::json!({"preview":true, + "authorizes_publication":false,"validation":validation})); + } + } + for edge in &mut preview.edges { + edge.from_id = scoped(&edge.from_id); + edge.to_id = scoped(&edge.to_id); + } + let mut snapshot = self.workflow_snapshot()?; + references::extend( + &mut snapshot.nodes, + &mut snapshot.edges, + (preview.nodes, preview.edges), + &context, + ); + snapshot.nodes.sort_by(|a, b| a.id.cmp(&b.id)); + snapshot.identity = Hash::of( + &serde_json::to_vec(&( + snapshot.generation, + snapshot.ontology_version, + &snapshot.nodes, + &snapshot.edges, + )) + .map_err(refused)?, + ) + .to_base32(); + Ok((snapshot, context)) + } + } + + #[cfg(feature = "review-shacl")] + fn review_snapshot( + &self, + review: &PublicationReview, + config: &PublicationGateConfig, + keys: DidKeyProvider<'_>, + preview: bool, + ) -> Result { + let (nodes, edges) = graph::build(self, review, config, keys, preview)?; + let bytes = serde_json::to_vec(&(&nodes, &edges)).map_err(refused)?; + Ok(super::WorkflowSnapshot { + generation: atomic_core::kg::KG_GENERATION, + ontology_version: atomic_core::kg::ontology::REVIEW_VERSION_IRI, + identity: Hash::of(&bytes).to_base32(), + nodes, + edges, + }) + } + + /// Persist a verified immutable artifact in the tracked vault. Existing + /// entries at a content address must have identical bytes. No trust changes. + #[cfg(feature = "review-shacl")] + pub fn record_publication_review( + &self, + review: &PublicationReview, + config: &PublicationGateConfig, + keys: DidKeyProvider<'_>, + ) -> Result { + let _lock = self.review_evidence_common_lock()?; + let report = self.validate_publication_review(review, config, keys)?; + if !report.conforms { + return Err(refused(format!( + "SHACL refused review: {} violation(s): {}", + report.results.len(), + serde_json::to_string(&report.results.iter().take(4).collect::>()) + .map_err(refused)? + ))); + } + let existing = self.publication_reviews()?; + self.review_supersession(review, &existing, keys)?; + let path = format!("{PREFIX}{}/review.md", review.artifact_hash()); + let disk_path = artifact::destination(self, &review.artifact_hash())?; + let bytes = format!( + "{}\n", + serde_json::to_string_pretty(review).map_err(refused)? + ) + .into_bytes(); + if let Some(existing) = self.vault_retrieve(&path)? { + if existing.content_bytes != bytes { + return Err(refused("content-address collision")); + } + } else { + if std::fs::symlink_metadata(&disk_path).is_ok() { + return Err(refused( + "an unregistered working file occupies this review address", + )); + } + self.vault_store( + &path, + atomic_core::pristine::VaultEntryType::Attestation, + bytes, + "{}".into(), + )?; + } + artifact::write(self, &path, &disk_path)?; + Ok(path) + } + + /// Strictly inspect stored artifacts. Corruption cannot disappear behind a + /// best-effort filter. Stale approvals are retained and refused, not erased. + pub fn publication_reviews(&self) -> Result, RepositoryError> { + let mut reviews = Vec::new(); + for entry in self.vault_list(PREFIX, None)? { + if reviews.len() >= 4096 { + return Err(refused("review inventory exceeds 4096 artifacts")); + } + let stored = self + .vault_retrieve(&entry.path)? + .ok_or_else(|| refused("registered review unavailable"))?; + let review = PublicationReview::parse(&stored.content_bytes).map_err(refused)?; + if entry.path != format!("{PREFIX}{}/review.md", review.artifact_hash()) { + return Err(refused( + "stored artifact address does not match signed bytes", + )); + } + reviews.push(review); + } + Ok(reviews) + } + + pub(super) fn retrospective_review_for( + &self, + change: &str, + session: &str, + config: &PublicationGateConfig, + keys: Option>, + ) -> Result, RepositoryError> { + #[allow(unused_mut)] + let mut accepted = None; + let reviews = self.publication_reviews()?; + let relevant: Vec<_> = reviews + .iter() + .filter(|review| { + review + .subject + .changes + .iter() + .any(|pin| pin.hash == change && pin.session.as_deref() == Some(session)) + }) + .collect(); + #[cfg(feature = "review-shacl")] + let mut superseded = std::collections::BTreeSet::new(); + #[cfg(feature = "review-shacl")] + for review in &relevant { + let keys = keys.ok_or_else(|| refused("review key resolver unavailable"))?; + self.verify_review_signature(review, keys)?; + // A renewal cannot suppress signature corruption, even in old rows. + let ancestors = self.review_supersession(review, &reviews, keys)?; + if !review.supersedes.is_empty() { + let report = self.validate_publication_review(review, config, keys)?; + if report.conforms { + superseded.extend(ancestors); + } + } + } + for review in relevant { + if !review + .subject + .changes + .iter() + .any(|pin| pin.hash == change && pin.session.as_deref() == Some(session)) + { + continue; + } + #[cfg(not(feature = "review-shacl"))] + { + let _ = (config, keys); + return Err(refused( + "review-shacl feature is required to evaluate retrospective evidence", + )); + } + #[cfg(feature = "review-shacl")] + { + if superseded.contains(&review.artifact_hash()) { + continue; + } + let report = self.validate_publication_review( + review, + config, + keys.ok_or_else(|| refused("review key resolver unavailable"))?, + )?; + if !report.conforms { + return Err(refused(format!( + "stored review fails SHACL ({} violations)", + report.results.len() + ))); + } + accepted = Some(review.artifact_hash()); + } + } + Ok(accepted) + } + + #[cfg(feature = "review-shacl")] + fn verify_review_signature( + &self, + review: &PublicationReview, + keys: DidKeyProvider<'_>, + ) -> Result<(), RepositoryError> { + let public = + key(keys(&review.attributed_to) + .ok_or_else(|| refused("review signing key unavailable"))?)?; + if !atomic_canonical::did::did_matches_public_key(&review.attributed_to, &public) { + return Err(refused("review DID is not key-bound")); + } + atomic_canonical::proof::verify_value(&review.value(), &public).map_err(refused) + } + + #[cfg(feature = "review-shacl")] + fn review_supersession( + &self, + review: &PublicationReview, + all: &[PublicationReview], + keys: DidKeyProvider<'_>, + ) -> Result, RepositoryError> { + let mut visited = std::collections::BTreeSet::new(); + let mut pending = review.supersedes.clone(); + while let Some(hash) = pending.pop() { + if hash == review.artifact_hash() { + return Err(refused("cyclic review supersession")); + } + if !visited.insert(hash.clone()) { + continue; + } + if visited.len() > 256 { + return Err(refused("review supersession exceeds budget")); + } + let old = all + .iter() + .find(|old| old.artifact_hash() == hash) + .ok_or_else(|| refused("superseded review is unavailable"))?; + self.verify_review_signature(old, keys)?; + let scope = |r: &PublicationReview| { + ( + r.subject.project.clone(), + r.subject.roots.clone(), + r.subject + .changes + .iter() + .map(|p| (p.hash.clone(), p.session.clone())) + .collect::>(), + ) + }; + if scope(old) != scope(review) || old.artifact_hash() == review.artifact_hash() { + return Err(refused( + "supersession must retain the exact original project/change/session scope", + )); + } + pending.extend(old.supersedes.iter().cloned()); + } + Ok(visited) + } + + /// Unlike the legacy best-effort discovery, this includes unindexed originals + /// and refuses registered missing or corrupt originals before any exception. + pub(super) fn review_original_attestations( + &self, + change: &Hash, + ) -> Result, RepositoryError> { + use atomic_core::pristine::{node_type, GraphTxnT}; + let mut hashes = std::collections::BTreeSet::new(); + let txn = self.pristine().read_txn()?; + if let Some(id) = txn.get_internal(change)? { + for dependent in txn.get_rev_deps(id)? { + if txn.get_node_type(dependent)? == Some(node_type::ATTESTATION) { + hashes.insert( + txn.get_external(dependent)? + .ok_or_else(|| refused("attestation registration has no hash"))?, + ); + } + } + } + drop(txn); + for hash in self.change_store().iter_attestations() { + hashes.insert(hash.map_err(refused)?); + if hashes.len() > 16384 { + return Err(refused("attestation inventory exceeds review budget")); + } + } + let mut result = Vec::new(); + for hash in hashes { + let attestation = self.load_attestation(&hash)?; + if attestation.changes_covered.contains(change) { + result.push((hash, attestation)); + } + } + Ok(result) + } +} + +#[cfg(feature = "review-shacl")] +fn key(bytes: [u8; 32]) -> Result { + atomic_identity::keypair::PublicKey::from_bytes(&bytes).map_err(refused) +} + +#[cfg(all(test, not(feature = "review-shacl")))] +mod unsupported { + use super::*; + #[test] + fn publication_review_requires_the_full_policy_engine() { + use atomic_canonical::publication_review::{ChangePin, IntentPin, ReviewSubject}; + let dir = tempfile::tempdir().unwrap(); + let repo = Repository::init(dir.path()).unwrap(); + repo.init_vault().unwrap(); + let change = Hash::of(b"unsupported-engine").to_base32(); + let pin = IntentPin { + id: "untrusted-input".into(), + source_hash: String::new(), + signed_hash: String::new(), + public_key: String::new(), + }; + let review = PublicationReview { + schema: atomic_canonical::publication_review::LEGACY_SCHEMA.into(), + reviewed_at: chrono::Utc::now().to_rfc3339(), + subject: ReviewSubject { + project: repo.project_id().unwrap().to_urn(), + roots: vec![change.clone()], + changes: vec![ChangePin { + hash: change.clone(), + session: Some("legacy".into()), + governing_intents: vec![], + provenance: vec![], + observations: vec![], + }], + review: pin, + work: vec![], + set_aside: vec![], + profile_hash: profile_hash(), + view_chain: vec![], + effective_set_id: String::new(), + snapshot: None, + }, + supersedes: vec![], + attributed_to: "untrusted-input".into(), + content_hash: None, + proof: None, + }; + repo.vault_store( + &format!("{PREFIX}{}/review.md", review.artifact_hash()), + atomic_core::pristine::VaultEntryType::Attestation, + serde_json::to_vec(&review).unwrap(), + "{}".into(), + ) + .unwrap(); + let config = PublicationGateConfig { + trust: Default::default(), + repository_identity: None, + }; + let result = repo.retrospective_review_for(&change, "legacy", &config, None); + assert!(repo + .workflow_snapshot_with_review(&serde_json::to_vec(&review).unwrap()) + .unwrap_err() + .to_string() + .contains("review-shacl feature is required")); + assert!(result + .unwrap_err() + .to_string() + .contains("review-shacl feature is required")); + } +} diff --git a/atomic-repository/src/repository/publication_review/observations.rs b/atomic-repository/src/repository/publication_review/observations.rs new file mode 100644 index 00000000..b248ed9b --- /dev/null +++ b/atomic-repository/src/repository/publication_review/observations.rs @@ -0,0 +1,225 @@ +//! Conservative receipt extraction from hash-verified retained provenance. +//! This recognizes observations, never successful execution or governing intent. +use super::*; +use atomic_canonical::publication_review::IntentObservationPin; +use atomic_core::change::{provenance_graph::ProvenanceNodeKind, ProvenanceGraph}; +use std::collections::BTreeSet; + +pub(super) fn resolve( + repo: &Repository, + hash: &Hash, + graph: &ProvenanceGraph, + keys: DidKeyProvider<'_>, +) -> Result, RepositoryError> { + let ledger = repo.get_session_ledger(&graph.session_id)?; + let mut turns: Vec<_> = ledger + .iter() + .flat_map(|(_, turns)| turns) + .filter(|turn| turn.provenance_hash == *hash) + .map(|turn| turn.turn_number) + .collect(); + turns.sort_unstable(); + turns.dedup(); + let mut ids = BTreeSet::new(); + let mut result = Vec::new(); + for node in &graph.nodes { + if !ids.insert(&node.id) { + return Err(refused("duplicate provenance node identity")); + } + if node.kind != ProvenanceNodeKind::Execution { + continue; + } + let Some(detail) = node.detail.as_deref() else { + continue; + }; + // Duplicate JSON keys are uncertainty, not a last-key-wins authority. + let detail = atomic_canonical::jcs::admit_document(detail.as_bytes()).map_err(refused)?; + let command = detail.get("command").and_then(|v| v.as_str()).unwrap_or(""); + let output = detail + .get("output_summary") + .and_then(|v| v.as_str()) + .unwrap_or(""); + for (kind, reference) in receipts(command, output) { + let (target, retained_revision, diagnostic) = match crate::intent_bridge::read_intent( + repo, + reference + .strip_prefix("urn:atomic:intent:") + .unwrap_or(&reference), + ) + .and_then(|inputs| { + // The ordinary authoring CLI accepts prefixes and local + // shorthand. Historical evidence must name an exact key or + // UID, independent of the inspecting user's defaults. + let bare = reference + .strip_prefix("urn:atomic:intent:") + .unwrap_or(&reference); + if !["id", "uid"].iter().any(|field| { + inputs + .frontmatter + .get(*field) + .and_then(|value| value.as_str()) + .is_some_and(|value| value.eq_ignore_ascii_case(bare)) + }) { + return Err(refused( + "receipt reference is not an exact intent key or UID", + )); + } + let current = crate::intent_bridge::lift(&inputs)?; + let revision = retained_revision(repo, &reference, &inputs, ¤t.id, keys); + Ok((current, revision)) + }) { + Ok((intent, Ok(revision))) => (Some(intent.id), revision, None), + Ok((intent, Err(error))) => (Some(intent.id), None, Some(error.to_string())), + Err(error) => (None, None, Some(error.to_string())), + }; + result.push(IntentObservationPin { + role: Default::default(), + provenance: hash.to_base32(), + node: node.id.clone(), + session: graph.session_id.clone(), + turns: turns.clone(), + kind: kind.into(), + reference, + resolution: match (target.is_some(), turns.len()) { + (true, 1) => "resolved", + (_, n) if n > 1 => "ambiguous", + _ => "unresolved", + } + .into(), + intent: target, + retained_revision, + diagnostic: diagnostic.or_else(|| match turns.len() { + 1 => None, + 0 => Some("No ledger turn pins this provenance hash".into()), + _ => Some("Multiple ledger turns pin this provenance hash".into()), + }), + }); + if result.len() > 4096 { + return Err(refused("intent observations exceed review budget")); + } + } + } + Ok(result) +} + +fn retained_revision( + repo: &Repository, + reference: &str, + inputs: &crate::intent_bridge::LiftInputs, + expected_id: &str, + keys: DidKeyProvider<'_>, +) -> Result, RepositoryError> { + use crate::intent_bridge::Attestation; + let (node, relation) = match crate::intent_bridge::load_attestation(repo, reference, inputs)? { + Attestation::None => return Ok(None), + Attestation::Fresh(node) | Attestation::Stale(node) => { + // Mutable freshness sidecars never authenticate the source relation. + let did = node + .attributed_to + .as_deref() + .ok_or_else(|| refused("retained revision has no author"))?; + let key = atomic_identity::keypair::PublicKey::from_bytes( + &keys(did).ok_or_else(|| refused("retained revision key unavailable"))?, + ) + .map_err(refused)?; + if node.id != expected_id || !atomic_canonical::did::did_matches_public_key(did, &key) { + return Err(refused("retained signed revision identity mismatch")); + } + atomic_canonical::verify(&node, &key).map_err(refused)?; + let expected = atomic_canonical::proof::prepare_attestation( + crate::intent_bridge::lift(inputs)?.to_value(), + &key, + ) + .value; + let relation = if atomic_canonical::proof::signing_view(&node.to_value()) == expected { + "current-source" + } else { + "retained-not-current" + }; + (node, (key, relation)) + } + }; + Ok(Some( + atomic_canonical::publication_review::SignedRevisionPin { + signed_hash: atomic_canonical::hash::content_hash(&node.to_value()), + public_key: relation.0.to_base32(), + source_relation: relation.1.into(), + }, + )) +} + +/// Deliberately not a shell interpreter. Only exact lifecycle receipt lines +/// paired with the corresponding CLI command are recognized. Quoted examples, +/// arbitrary mentions, filename matches and timestamps do not resolve evidence. +fn receipts(command: &str, output: &str) -> Vec<(&'static str, String)> { + let mut result = BTreeSet::new(); + for (verb, prefix, kind) in [ + ("new", "Created intent: ", "created"), + ("update", "Updated intent: ", "updated"), + ("attest", "Attested intent: ", "attested-receipt"), + ("verify", "Verified intent: ", "verified-receipt"), + ] { + // Segments permit retained multi-command invocations, but do not infer + // success of any segment or execute anything in the transcript. + let commands: Vec<_> = command + .split([';', '\n']) + .filter_map(|segment| { + let words: Vec<_> = segment.split_whitespace().collect(); + (words.len() >= 4 + && words[0].rsplit('/').next() == Some("atomic") + && words[1] == "intent" + && words[2] == verb) + .then_some(words) + }) + .collect(); + for line in output.lines() { + if let Some(reference) = line.trim().strip_prefix(prefix) { + let reference = reference.trim(); + if reference.is_empty() || reference.contains(char::is_whitespace) { + continue; + } + if commands + .iter() + .any(|words| verb == "new" || words[3] == reference) + { + result.insert((kind, reference.to_owned())); + } + } + } + } + result.into_iter().collect() +} + +#[cfg(test)] +mod tests { + use super::*; + #[test] + fn receipt_extraction_does_not_promote_mentions_or_failure_to_truth() { + assert_eq!( + receipts( + "atomic intent new \"work\"; atomic vault sync", + "Created intent: REAC::lee::22\n file: .vault/intents/uid/intent.md" + ), + vec![("created", "REAC::lee::22".into())] + ); + assert!(receipts( + "echo 'atomic intent attest REAC::lee::22'", + "Attested intent: REAC::lee::22" + ) + .is_empty()); + assert!(receipts( + "atomic intent attest REAC::lee::23", + "Attested intent: REAC::lee::22" + ) + .is_empty()); + assert!(receipts("atomic intent verify REAC::lee::22", "attestation is stale").is_empty()); + assert_eq!( + receipts( + "atomic intent attest REAC::lee::22", + "Attested intent: REAC::lee::22" + )[0] + .0, + "attested-receipt" + ); + } +} diff --git a/atomic-repository/src/repository/publication_review/references.rs b/atomic-repository/src/repository/publication_review/references.rs new file mode 100644 index 00000000..52c27c31 --- /dev/null +++ b/atomic-repository/src/repository/publication_review/references.rs @@ -0,0 +1,198 @@ +//! Reference topology for the existing workflow/intent graph. These are claims +//! in a retained document, not verifier observations or a publication verdict. +use super::*; +use atomic_core::{ + kg::{ + iri, + ontology::{Class as C, Predicate as P}, + project_id::ProjectId, + }, + KgEdge, KgNode, +}; +use std::collections::BTreeMap; + +pub(super) fn artifact_id(review: &PublicationReview) -> Result { + let bytes = data_encoding::HEXLOWER + .decode(review.artifact_hash().as_bytes()) + .map_err(refused)?; + let bytes: [u8; 32] = bytes + .try_into() + .map_err(|_| refused("invalid review hash"))?; + Ok(iri::mint_attestation(&Hash::from_bytes(bytes))) +} + +pub(super) fn subject_id(review: &PublicationReview) -> Result { + Ok(format!( + "urn:atomic:review-subject:{}", + atomic_canonical::hash::content_hash( + &serde_json::to_value(&review.subject).map_err(refused)? + ) + .replace(':', "-") + )) +} + +pub(crate) fn project( + project: &ProjectId, + review: &PublicationReview, +) -> Result<(Vec, Vec), RepositoryError> { + if review.schema != SCHEMA + && review.schema != atomic_canonical::publication_review::LEGACY_SCHEMA + { + return Err(refused("unsupported review reference schema")); + } + if review.subject.project != project.to_urn() { + return Err(refused("review reference belongs to another project")); + } + let artifact = artifact_id(review)?; + let subject = subject_id(review)?; + let mut nodes = BTreeMap::new(); + let mut edges = Vec::new(); + let mut node = |id: &str, class: C, label: &str| { + nodes.entry(id.to_owned()).or_insert_with(|| { + let mut node = KgNode::new(id, class, label, "publication-review-reference"); + node.metadata = Some(serde_json::json!({"review_reference":true,"validation":"not-evaluated","authorizes_publication":false})); + node + }); + }; + let intent = |id: &str| { + iri::mint_intent(project, id.strip_prefix("urn:atomic:intent:").unwrap_or(id)) + .map_err(refused) + }; + let change = |id: &str| { + Hash::from_base32(id.as_bytes()) + .filter(|h| h.to_base32() == id) + .map(|h| iri::mint_change(&h)) + .ok_or_else(|| refused("invalid review change reference")) + }; + node( + &artifact, + C::PublicationReview, + "Retained review (not revalidated)", + ); + node(&subject, C::ReviewSubject, "Exact retained review subject"); + let review_intent = intent(&review.subject.review.id)?; + node(&review_intent, C::ReviewIntent, "Review intent reference"); + edges.push(KgEdge::new(&artifact, &subject, P::ReviewsClosure)); + edges.push(KgEdge::new(&artifact, &review_intent, P::HasReviewIntent)); + for pin in &review.subject.work { + let work = intent(&pin.id)?; + node(&work, C::WorkIntent, "Reviewed intent reference"); + edges.push(KgEdge::new(&subject, &work, P::IncludesIntent)); + } + for pin in &review.subject.set_aside { + let id = intent(&pin.id)?; + node( + &id, + C::WorkIntent, + "Reviewed set-aside disposition (not current implementation)", + ); + edges.push(KgEdge::new(&subject, &id, P::IncludesSetAside)); + } + for pin in &review.subject.changes { + let id = change(&pin.hash)?; + node(&id, C::Change, &pin.hash); + edges.push(KgEdge::new(&subject, &id, P::ReviewsChange)); + for (i, observation) in pin.observations.iter().enumerate() { + let evidence = format!("{artifact}:change:{}:observation:{i}", pin.hash); + node( + &evidence, + C::IntentObservation, + &format!("{}: {}", observation.kind, observation.reference), + ); + edges.push(KgEdge::new(&id, &evidence, P::HasReviewEvidence)); + edges.push(KgEdge::new(&subject, &evidence, P::SubjectEvidence)); + if let Some(target) = &observation.intent { + let target = intent(target)?; + node(&target, C::WorkIntent, &observation.reference); + edges.push(KgEdge::new(&evidence, &target, P::ObservedIntent)); + } + let source = Hash::from_base32(observation.provenance.as_bytes()) + .filter(|h| h.to_base32() == observation.provenance) + .ok_or_else(|| refused("invalid review provenance reference"))?; + let source = iri::mint_provenance(&source); + node(&source, C::ProvenanceGraph, "Retained provenance reference"); + edges.push(KgEdge::new(&evidence, &source, P::EvidenceSource)); + let session = iri::mint_session(project, &observation.session); + node(&session, C::Session, &observation.session); + for number in &observation.turns { + let turn = iri::mint_turn(project, &observation.session, *number); + node(&turn, C::SessionTurn, &format!("Retained turn {number}")); + edges.push(KgEdge::new(&session, &turn, P::HasTurn)); + edges.push(KgEdge::new(&evidence, &turn, P::EvidenceTurn)); + } + } + } + for pin in &review.subject.changes { + for (i, observation) in pin.observations.iter().enumerate() { + let id = format!("{artifact}:change:{}:observation:{i}", pin.hash); + if let Some(node) = nodes.get_mut(&id) { + node.metadata = Some( + serde_json::json!({"review_reference":true,"validation":"not-evaluated", + "authorizes_publication":false,"pinned_observation":observation}), + ); + } + } + } + if let Some(node) = nodes.get_mut(&artifact) { + let mut display_subject = serde_json::to_value(&review.subject).map_err(refused)?; + if let Some(snapshot) = &review.subject.snapshot { + display_subject["snapshot"] = serde_json::json!({"version":snapshot.version, + "membership":snapshot.membership,"view_logs":snapshot.view_logs, + "intent_documents_omitted_from_display":true, + "intent_revisions":snapshot.intent_revisions.iter().map(|revision|serde_json::json!({ + "id":revision.id,"document_hash":atomic_canonical::hash::content_hash(&revision.document)})).collect::>()}); + } + node.metadata = Some( + serde_json::json!({"review_reference":true,"validation":"not-evaluated", + "authorizes_publication":false,"pinned_subject":display_subject,"claimed_signer":review.attributed_to, + "has_proof":review.proof.is_some()}), + ); + } + Ok((nodes.into_values().collect(), edges)) +} + +/// Merge display context without replacing current intent metadata or treating +/// a retrospective source revision as the current intent. Validation happens +/// before this merge, on the bounded dataset, never on the combined display. +pub(crate) fn extend( + nodes: &mut Vec, + edges: &mut Vec, + additions: (Vec, Vec), + context: &str, +) { + let mut positions: BTreeMap<_, _> = nodes + .iter() + .enumerate() + .map(|(i, n)| (n.id.clone(), i)) + .collect(); + for node in additions.0 { + if let Some(index) = positions.get(&node.id) { + let current = &mut nodes[*index]; + if current.source == "publication-review-reference" && node.source != current.source { + *current = node; + continue; + } + // Current canonical types win as well: a historical signed kind + // must not reclassify the live intent during display composition. + if let Some(metadata) = node.metadata { + let current_metadata = current + .metadata + .get_or_insert_with(|| serde_json::json!({})); + if let Some(current_metadata) = current_metadata.as_object_mut() { + let contexts = current_metadata + .entry("review_contexts") + .or_insert_with(|| serde_json::json!({})); + if let Some(contexts) = contexts.as_object_mut() { + contexts.insert(context.into(), metadata); + } + } + } + } else { + positions.insert(node.id.clone(), nodes.len()); + nodes.push(node); + } + } + edges.extend(additions.1); + edges.sort_by(|a, b| (&a.from_id, a.kind, &a.to_id).cmp(&(&b.from_id, b.kind, &b.to_id))); + edges.dedup_by(|a, b| a.from_id == b.from_id && a.kind == b.kind && a.to_id == b.to_id); +} diff --git a/atomic-repository/src/repository/publication_review/snapshot.rs b/atomic-repository/src/repository/publication_review/snapshot.rs new file mode 100644 index 00000000..31d694ad --- /dev/null +++ b/atomic-repository/src/repository/publication_review/snapshot.rs @@ -0,0 +1,238 @@ +//! Immutable source evidence. View names are provenance labels, never resources +//! that must be kept alive to revalidate a signed approval. +use super::*; +use atomic_canonical::publication_review::{RetainedIntentRevision, ReviewSnapshot, ReviewSubject}; +use atomic_core::pristine::{EffectiveProjectionClosure, GraphTxnT, ViewMembershipSet, ViewTxnT}; +use atomic_core::types::SetId; +use std::collections::BTreeSet; + +const MAX_MEMBERS: usize = 16384; +const MAX_LOG_REFS: usize = 65536; + +fn hash(value: &str) -> Result { + Hash::from_base32(value.as_bytes()) + .filter(|h| h.to_base32() == value) + .ok_or_else(|| refused("snapshot requires full canonical change hashes")) +} + +pub(super) fn capture( + repo: &Repository, + subject: &ReviewSubject, + keys: DidKeyProvider<'_>, +) -> Result { + let txn = repo.pristine().read_txn()?; + let mut view_logs = Vec::new(); + let mut refs = 0; + for pin in &subject.view_chain { + let view = txn + .get_view(&pin.name)? + .ok_or_else(|| refused("source view disappeared during capture"))?; + if view.state.to_base32() != pin.state { + return Err(refused("source view changed during capture")); + } + let mut log = Vec::new(); + for row in txn.iter_changes(&view, 0)? { + let (_, id, _) = row?; + log.push( + txn.get_external(id)? + .ok_or_else(|| refused("source member has no external hash"))? + .to_base32(), + ); + refs += 1; + if refs > MAX_LOG_REFS { + return Err(refused("source log snapshot exceeds budget")); + } + } + view_logs.push(log); + } + let selected = subject + .view_chain + .first() + .ok_or_else(|| refused("source context missing"))?; + let view = txn + .get_view(&selected.name)? + .ok_or_else(|| refused("source view disappeared"))?; + let closure = super::super::effective_projection_closure(&txn, &view)?; + if closure.len() > MAX_MEMBERS { + return Err(refused("source membership snapshot exceeds budget")); + } + let mut membership = BTreeSet::new(); + for id in closure.iter_dependency_first() { + membership.insert( + txn.get_external(*id)? + .ok_or_else(|| refused("snapshot member has no hash"))? + .to_base32(), + ); + } + drop(txn); + let mut revisions = Vec::new(); + for pin in std::iter::once(&subject.review) + .chain(subject.work.iter()) + .chain(subject.set_aside.iter()) + { + let bare = pin.id.strip_prefix("urn:atomic:intent:").unwrap_or(&pin.id); + let inputs = crate::intent_bridge::read_intent(repo, bare)?; + let (node, current) = subject::intent(repo, bare, keys)?; + if current != *pin { + return Err(refused("intent changed during source capture")); + } + revisions.push(RetainedIntentRevision { + id: pin.id.clone(), + frontmatter: inputs.frontmatter, + body: inputs.body, + document: node.to_value(), + }); + } + revisions.sort_by(|a, b| a.id.cmp(&b.id)); + Ok(ReviewSnapshot { + version: 1, + view_logs, + membership: membership.into_iter().collect(), + intent_revisions: revisions, + }) +} + +pub(super) fn verify(repo: &Repository, subject: &ReviewSubject) -> Result<(), RepositoryError> { + let snapshot = subject + .snapshot + .as_ref() + .ok_or_else(|| refused("retained source snapshot missing"))?; + if snapshot.version != 1 + || subject.view_chain.is_empty() + || subject.view_chain.len() > 256 + || snapshot.view_logs.len() != subject.view_chain.len() + || snapshot.membership.len() > MAX_MEMBERS + { + return Err(refused("invalid or unsupported retained source context")); + } + let mut names = BTreeSet::new(); + let mut total = 0; + let mut direct = Vec::new(); + let txn = repo.pristine().read_txn()?; + // Traverse root-to-leaf, exactly like canonical live view membership. + for (pin, log) in subject.view_chain.iter().zip(&snapshot.view_logs).rev() { + if !names.insert(&pin.name) || !matches!(pin.scope.as_str(), "draft" | "shared") { + return Err(refused("invalid retained view labels")); + } + let mut state = Hash::ZERO; + let mut seen = BTreeSet::new(); + for entry in log { + total += 1; + if total > MAX_LOG_REFS { + return Err(refused("retained source logs exceed budget")); + } + let h = hash(entry)?; + if !seen.insert(h) { + return Err(refused("duplicate change in retained view log")); + } + state = state.next(&h); + direct.push( + txn.get_internal(&h)? + .ok_or_else(|| refused("retained change registration missing"))?, + ); + } + if state.to_base32() != pin.state { + return Err(refused("retained view log does not prove its Merkle state")); + } + } + let closure = EffectiveProjectionClosure::try_from_membership( + &txn, + &ViewMembershipSet::from_ordered(direct), + )?; + if closure.len() > MAX_MEMBERS { + return Err(refused("retained dependency closure exceeds budget")); + } + let mut actual = BTreeSet::new(); + for id in closure.iter_dependency_first() { + actual.insert( + txn.get_external(*id)? + .ok_or_else(|| refused("retained change hash missing"))? + .to_base32(), + ); + } + let declared: BTreeSet<_> = snapshot.membership.iter().cloned().collect(); + if declared.len() != snapshot.membership.len() + || snapshot.membership.iter().ne(declared.iter()) + || declared != actual + { + return Err(refused( + "retained membership is not the exact effective source closure", + )); + } + let mut set = SetId::ZERO; + for entry in &snapshot.membership { + let h = hash(entry)?; + let change = repo.load_change(&h)?; + if change.hash().map_err(refused)? != h { + return Err(refused("retained source change hash mismatch")); + } + // An authenticated store object and its dependency index must agree. + let id = txn + .get_internal(&h)? + .ok_or_else(|| refused("retained source change is unregistered"))?; + let indexed: BTreeSet<_> = txn.get_indexed_change_deps(id)?.into_iter().collect(); + let stored: BTreeSet<_> = change.dependencies().iter().copied().collect(); + if indexed != stored { + return Err(refused( + "retained source dependency index disagrees with immutable change", + )); + } + set = set.add(&h); + } + if set.to_base32() != subject.effective_set_id + || subject.roots.iter().any(|root| !declared.contains(root)) + { + return Err(refused( + "retained source membership does not prove the reviewed SetId or roots", + )); + } + drop(txn); + let pins: Vec<_> = std::iter::once(&subject.review) + .chain(subject.work.iter()) + .chain(subject.set_aside.iter()) + .collect(); + if pins.len() != snapshot.intent_revisions.len() || pins.len() > 257 { + return Err(refused("retained intent revision inventory mismatch")); + } + let mut ids = BTreeSet::new(); + for revision in &snapshot.intent_revisions { + if !ids.insert(&revision.id) { + return Err(refused("duplicate retained intent revision")); + } + let pin = pins + .iter() + .find(|pin| pin.id == revision.id) + .ok_or_else(|| refused("unscoped retained intent revision"))?; + let inputs = crate::intent_bridge::LiftInputs { + frontmatter: revision.frontmatter.clone(), + body: revision.body.clone(), + }; + let node: atomic_canonical::node::CanonicalNode = + serde_json::from_value(revision.document.clone()).map_err(refused)?; + let key = + atomic_identity::keypair::PublicKey::from_base32(&pin.public_key).map_err(refused)?; + let did = node + .attributed_to + .as_deref() + .ok_or_else(|| refused("retained intent has no author"))?; + if node.id != pin.id + || !atomic_canonical::did::did_matches_public_key(did, &key) + || crate::intent_bridge::source_content_hash(&inputs) != pin.source_hash + || atomic_canonical::hash::content_hash(&node.to_value()) != pin.signed_hash + { + return Err(refused("retained intent source/signature pin mismatch")); + } + atomic_canonical::verify(&node, &key).map_err(refused)?; + let expected = atomic_canonical::proof::prepare_attestation( + crate::intent_bridge::lift(&inputs)?.to_value(), + &key, + ) + .value; + if atomic_canonical::proof::signing_view(&node.to_value()) != expected { + return Err(refused( + "retained signed intent does not match its source inputs", + )); + } + } + Ok(()) +} diff --git a/atomic-repository/src/repository/publication_review/subject.rs b/atomic-repository/src/repository/publication_review/subject.rs new file mode 100644 index 00000000..5fb57cf1 --- /dev/null +++ b/atomic-repository/src/repository/publication_review/subject.rs @@ -0,0 +1,262 @@ +//! Read canonical evidence, not best-effort KG/file-overlap attribution. +use super::*; +use atomic_canonical::{ + node::CanonicalNode, + publication_review::{ChangePin, IntentPin, ReviewSubject}, +}; +use atomic_core::pristine::{node_type, GraphTxnT}; +use std::collections::{BTreeMap, BTreeSet}; + +pub(super) fn intent( + repo: &Repository, + id: &str, + keys: DidKeyProvider<'_>, +) -> Result<(CanonicalNode, IntentPin), RepositoryError> { + read_intent(repo, id, keys, false) +} + +pub(super) fn read_intent( + repo: &Repository, + id: &str, + keys: DidKeyProvider<'_>, + preview: bool, +) -> Result<(CanonicalNode, IntentPin), RepositoryError> { + let id = id.strip_prefix("urn:atomic:intent:").unwrap_or(id); + let inputs = crate::intent_bridge::read_intent(repo, id)?; + let node = match crate::intent_bridge::load_attestation(repo, id, &inputs)? { + crate::intent_bridge::Attestation::Fresh(node) => *node, + crate::intent_bridge::Attestation::Stale(node) if preview => *node, + _ => { + return Err(refused( + "review and work intents require fresh signed revisions", + )) + } + }; + let did = node + .attributed_to + .as_deref() + .ok_or_else(|| refused("intent has no signing identity"))?; + let bytes = keys(did).ok_or_else(|| refused("intent signing key unavailable"))?; + let key = atomic_identity::keypair::PublicKey::from_bytes(&bytes).map_err(refused)?; + if !atomic_canonical::did::did_matches_public_key(did, &key) { + return Err(refused("intent author is not bound to its signing key")); + } + atomic_canonical::verify(&node, &key).map_err(refused)?; + // A mutable sourceContentHash in a sidecar is not an authenticated freshness + // anchor. Compare the actual current lift with the signed document as well. + let expected = atomic_canonical::proof::prepare_attestation( + crate::intent_bridge::lift(&inputs)?.to_value(), + &key, + ) + .value; + if node.id != crate::intent_bridge::lift(&inputs)?.id { + return Err(refused( + "signed intent identity does not match source identity", + )); + } + if !preview && atomic_canonical::proof::signing_view(&node.to_value()) != expected { + return Err(refused( + "signed intent does not match current source inputs", + )); + } + let pin = IntentPin { + id: node.id.clone(), + source_hash: crate::intent_bridge::source_content_hash(&inputs), + signed_hash: atomic_canonical::hash::content_hash(&node.to_value()), + public_key: key.to_base32(), + }; + Ok((node, pin)) +} + +/// Scan both registrations and available sidecars. A registered missing/corrupt +/// original or any unreadable unindexed sidecar is uncertainty, never absence. +fn provenance( + repo: &Repository, + changes: &[Hash], +) -> Result, RepositoryError> { + let mut hashes = BTreeSet::new(); + let txn = repo.pristine().read_txn()?; + for hash in changes { + if let Some(id) = txn.get_internal(hash)? { + for dependent in txn.get_rev_deps(id)? { + if txn.get_node_type(dependent)? == Some(node_type::PROVENANCE) { + hashes + .insert(txn.get_external(dependent)?.ok_or_else(|| { + refused("registered provenance has no external hash") + })?); + } + } + } + } + drop(txn); + for hash in repo.change_store().iter_provenance_graphs() { + hashes.insert(hash.map_err(refused)?); + if hashes.len() > 16384 { + return Err(refused("provenance inventory exceeds review budget")); + } + } + hashes + .into_iter() + .map(|hash| { + let graph = repo.load_provenance_graph(&hash)?; + Ok((hash, graph)) + }) + .collect() +} + +pub(super) fn build( + repo: &Repository, + review_id: &str, + roots: &[Hash], + view: &str, + keys: DidKeyProvider<'_>, +) -> Result { + let mut subject = build_with_mode(repo, review_id, roots, view, keys, false, None)?; + subject.snapshot = Some(super::snapshot::capture(repo, &subject, keys)?); + super::snapshot::verify(repo, &subject)?; + Ok(subject) +} + +pub(super) fn build_with_mode( + repo: &Repository, + review_id: &str, + roots: &[Hash], + view: &str, + keys: DidKeyProvider<'_>, + preview: bool, + retained: Option<&ReviewSubject>, +) -> Result { + if roots.is_empty() || roots.len() > 64 { + return Err(refused("review requires 1 to 64 root changes")); + } + let (review, review_pin) = read_intent(repo, review_id, keys, preview)?; + if review.kind != "review" { + return Err(refused("review subject must name a review intent")); + } + let mut work = BTreeMap::new(); + let mut set_aside = BTreeMap::new(); + for reference in &review.depends_on { + if reference.edge == "reviews" { + let id = reference + .to + .strip_prefix("urn:atomic:intent:") + .unwrap_or(&reference.to); + let (node, pin) = read_intent(repo, id, keys, preview)?; + if node.status == "icebox" { + set_aside.insert(pin.id.clone(), pin); + } else { + work.insert(pin.id.clone(), pin); + } + } + } + if work.len() + set_aside.len() > 256 { + return Err(refused("review exceeds 256 work intents")); + } + let mut view_chain = retained + .map(|subject| subject.view_chain.clone()) + .unwrap_or_default(); + let mut cursor = if retained.is_some() { + None + } else { + Some(view.to_string()) + }; + let mut seen_views = BTreeSet::new(); + while let Some(name) = cursor { + if !seen_views.insert(name.clone()) || view_chain.len() >= 256 { + return Err(refused("cyclic or excessive view ancestry")); + } + let info = repo.get_view_info(&name)?; + view_chain.push(atomic_canonical::publication_review::ReviewViewPin { + name, + state: info.state_base32(), + scope: info.kind_label().to_string(), + }); + cursor = info.parent_name; + } + if retained.is_none() && !repo.view_contains_changes(view, roots)? { + return Err(refused("selected view does not contain the review roots")); + } + let mut closure = BTreeSet::new(); + let mut pending = roots.to_vec(); + while let Some(hash) = pending.pop() { + if !closure.insert(hash) { + continue; + } + if closure.len() > 4096 { + return Err(refused("review closure exceeds 4096 changes")); + } + let change = repo.load_change(&hash)?; + if change.hash().map_err(refused)? != hash { + return Err(refused("review change hash mismatch")); + } + pending.extend_from_slice(change.dependencies()); + if pending.len() > 65536 { + return Err(refused("review dependency queue exceeds budget")); + } + } + let closure: Vec<_> = closure.into_iter().collect(); + let graphs = provenance(repo, &closure)?; + let mut changes = Vec::new(); + for hash in closure { + let change = repo.load_change(&hash)?; + if change.hash().map_err(refused)? != hash { + return Err(refused("review change hash mismatch")); + } + let mut sessions: BTreeSet<_> = change + .provenance() + .iter() + .filter_map(|p| p.session_id.clone()) + .collect(); + if atomic_core::change::envelope::SessionEnvelope::is_session_envelope( + &change.hashed.metadata, + ) { + sessions.insert( + atomic_core::change::envelope::SessionEnvelope::decode(&change.hashed.metadata) + .map_err(refused)? + .session_id, + ); + } + if sessions.len() > 1 { + return Err(refused("conflicting change session identities")); + } + let session = sessions.into_iter().next(); + let mut evidence = Vec::new(); + let mut observations = Vec::new(); + for (graph_hash, graph) in &graphs { + if graph.explains_change(&hash) { + evidence.push(graph_hash.to_base32()); + observations.extend(super::observations::resolve(repo, graph_hash, graph, keys)?); + } + } + for observation in &mut observations { + if observation.intent.as_deref() == Some(review_pin.id.as_str()) { + observation.role = + atomic_canonical::publication_review::ObservationRole::ReviewContext; + } + } + changes.push(ChangePin { + hash: hash.to_base32(), + session, + governing_intents: Vec::new(), + provenance: evidence, + observations, + }); + } + changes.sort_by(|a, b| a.hash.cmp(&b.hash)); + let roots: BTreeSet<_> = roots.iter().map(Base32::to_base32).collect(); + Ok(ReviewSubject { + project: repo.project_id()?.to_urn(), + roots: roots.into_iter().collect(), + changes, + review: review_pin, + work: work.into_values().collect(), + set_aside: set_aside.into_values().collect(), + profile_hash: profile_hash(), + view_chain, + effective_set_id: match retained { + Some(subject) => subject.effective_set_id.clone(), + None => repo.view_set_id(view)?.to_base32(), + }, + snapshot: retained.and_then(|subject| subject.snapshot.clone()), + }) +} diff --git a/atomic-repository/src/repository/publication_review/tests.rs b/atomic-repository/src/repository/publication_review/tests.rs new file mode 100644 index 00000000..9e7d81fe --- /dev/null +++ b/atomic-repository/src/repository/publication_review/tests.rs @@ -0,0 +1,479 @@ +use super::*; +use crate::intent_bridge as bridge; +use crate::{IntentCreateOptions, IntentUpdateOptions}; +use atomic_canonical::publication_review::PublicationReview; +use atomic_core::{ + change::{ + attestation::{AttestAgent, Attestation}, + provenance_graph::ProvenanceGraphBuilder, + AITool, AIVendor, Change, ChangeHeader, Provenance, + }, + pristine::VaultEntryType, +}; +use atomic_identity::{Identity, KeyPair}; +use serde_json::json; +mod boundaries; +mod observations; +mod snapshot; + +const SESSION: &str = "retained-legacy-session"; + +struct Fixture { + _dir: tempfile::TempDir, + repo: Repository, + change: Hash, + author: Identity, + author_key: KeyPair, + reviewer: Identity, + reviewer_key: KeyPair, + work: String, + review: String, +} + +fn signed_intent( + repo: &Repository, + signer: &Identity, + pair: &KeyPair, + kind: &str, + target: Option<&str>, +) -> String { + let created = repo + .vault_intent_create(IntentCreateOptions { + title: format!("{kind} fixture"), + priority: None, + assignee: None, + labels: vec![], + session_id: None, + turn_id: None, + kind: Some(kind.into()), + }) + .unwrap(); + let uid = &created.uid; + let observed = repo + .get_view_info(repo.current_view()) + .unwrap() + .state_base32(); + let reference = target + // Full source-context identity is independent of the review document, + // avoiding a circular pin while observing inherited membership. + .map(|target| format!(":::ref{{to=urn:atomic:intent:{target} edge=reviews}}\n:::\n")) + .unwrap_or_default(); + let set_id = repo.view_set_id(repo.current_view()).unwrap().to_base32(); + let body = format!(":::why\nVerify exact retained work.\n:::\n\ + :::acceptance-criterion{{#{uid}-ac-1 status=met verifiedBy=fixture evidence=inspected requiredKinds=manual}}\n\ + Exact fixture bytes and provenance have been inspected.\n\ + ::verification{{kind=manual outcome=pass scope=ac observedAtMerkle={observed} ref=urn:atomic:view-set:{set_id} observation=checked}}\n:::\n\ + :::task{{#{uid}-1 status=done criteria={uid}-ac-1}}\nInspect retained originals.\n:::\n\ + {reference}:::scope-in\nFixture evidence.\n:::\n\ + :::scope-out\nLive repositories.\n:::\n:::constraint\nDo not invent original signatures.\n:::\n"); + repo.vault_intent_update( + &created.id, + IntentUpdateOptions { + status: Some("done".into()), + content: Some(body), + force: true, + ..Default::default() + }, + ) + .unwrap(); + sign_intent(repo, &created.uid, signer, pair); + created.uid +} + +fn receipt_node(work: &str) -> atomic_core::change::provenance_graph::ProvenanceNode { + receipt_node_for(&[work]) +} + +/// One retained receipt node attesting every listed intent in a single +/// multi-command invocation, exactly as a session transcript would retain it. +fn receipt_node_for(intents: &[&str]) -> atomic_core::change::provenance_graph::ProvenanceNode { + let command = intents + .iter() + .map(|id| format!("atomic intent attest {id}")) + .collect::>() + .join("; "); + let output = intents + .iter() + .map(|id| format!("Attested intent: {id}\n")) + .collect::(); + serde_json::from_value(json!({ + "id":"fixture-receipt", "kind":"execution", "timestamp":0, + "summary":"Retained lifecycle receipt", "classified":false, + "detail":json!({"command":command,"output_summary":output}).to_string() + })) + .unwrap() +} + +fn sign_intent(repo: &Repository, id: &str, signer: &Identity, pair: &KeyPair) { + let inputs = bridge::read_intent(repo, id).unwrap(); + let node = atomic_canonical::proof::attest(bridge::lift(&inputs).unwrap(), signer, pair); + let path = bridge::attestation_vault_path(repo, id).unwrap(); + repo.vault_store( + &path, + VaultEntryType::Attestation, + format!("{}\n", serde_json::to_string_pretty(&node).unwrap()).into_bytes(), + json!({"sourceContentHash":bridge::source_content_hash(&inputs)}).to_string(), + ) + .unwrap(); +} + +impl Fixture { + fn new() -> Self { + Self::build(false).0 + } + + /// Like `new`, but the retained receipt also observes a second, independent + /// work intent by the same author. Returns that intent's UID. + fn with_second_observed_intent() -> (Self, String) { + let (fixture, second) = Self::build(true); + (fixture, second.expect("second observed intent")) + } + + fn build(second_observed: bool) -> (Self, Option) { + let dir = tempfile::tempdir().unwrap(); + let mut repo = Repository::init(dir.path()).unwrap(); + repo.init_vault().unwrap(); + repo.create_draft_view("review-source", "dev").unwrap(); + repo.switch_view(repo.require_working_copy_id().unwrap(), "review-source") + .unwrap(); + let author_key = KeyPair::generate(); + let author = Identity::new("original-author", &author_key); + let reviewer_key = KeyPair::generate(); + let reviewer = Identity::new("present-reviewer", &reviewer_key); + let store = + atomic_identity::IdentityStore::open(&repo.dot_dir().join("identities")).unwrap(); + store.save(&author).unwrap(); + store.save(&reviewer).unwrap(); + let work = signed_intent(&repo, &author, &author_key, "feature", None); + let second = + second_observed.then(|| signed_intent(&repo, &author, &author_key, "feature", None)); + let dependency = repo + .save_change(&Change::empty(ChangeHeader::new("unmanaged dependency"))) + .unwrap(); + let mut change = Change::empty(ChangeHeader::new("legacy managed original")); + change.hashed.dependencies.push(dependency); + let mut provenance = Provenance::new( + AIVendor::default(), + "fixture", + AITool::Cli("fixture".into()), + ); + provenance.session_id = Some(SESSION.into()); + change.hashed.provenance.push(provenance); + change.hashed.metadata = + atomic_core::change::envelope::SessionEnvelope::builder(SESSION, "fixture") + .build() + .encode() + .unwrap(); + let change = repo.save_change(&change).unwrap(); + let graph = ProvenanceGraphBuilder::new(SESSION, "fixture") + .add_node(receipt_node_for( + &std::iter::once(work.as_str()) + .chain(second.as_deref()) + .collect::>(), + )) + .changes_explained(vec![change]) + .build(); + repo.save_provenance_graph(&graph).unwrap(); + repo.insert_change_rec( + &change, + crate::InsertOptions::default().view("review-source"), + ) + .unwrap(); + let review = signed_intent(&repo, &reviewer, &reviewer_key, "review", Some(&work)); + ( + Self { + _dir: dir, + repo, + change, + author, + author_key, + reviewer, + reviewer_key, + work, + review, + }, + second, + ) + } + fn keys(&self, did: &str) -> Option<[u8; 32]> { + [&self.author, &self.reviewer] + .into_iter() + .find(|identity| { + atomic_canonical::did::did_matches_public_key(did, &identity.public_key) + }) + .map(|identity| *identity.public_key.as_bytes()) + } + fn config(&self) -> PublicationGateConfig { + PublicationGateConfig { + trust: atomic_config::GitTrustConfig { + signers: vec![atomic_canonical::did::did_for_public_key( + &self.reviewer.public_key, + )], + revoked: vec![], + }, + repository_identity: None, + } + } + fn signed(&self) -> PublicationReview { + let prepared = self + .repo + .prepare_publication_review(&self.review, &[self.change], &|did| self.keys(did)) + .unwrap(); + self.sign(prepared) + } + fn sign(&self, mut review: PublicationReview) -> PublicationReview { + review.proof = None; + review.content_hash = None; + serde_json::from_value(atomic_canonical::proof::attest_value( + review.value(), + &self.reviewer, + &self.reviewer_key, + )) + .unwrap() + } + fn conforms(&self, review: &PublicationReview, config: &PublicationGateConfig) -> bool { + self.repo + .validate_publication_review(review, config, &|did| self.keys(did)) + .map(|r| r.conforms) + .unwrap_or(false) + } + fn verdict(&self) -> super::super::provenance_gate::GateVerdict { + self.repo + .evaluate_publication_gate( + &[self.change], + &self.config(), + None, + Some(&|did| self.keys(did)), + ) + .unwrap() + } +} + +#[test] +fn exact_signed_shacl_review_discharges_only_missing_attestation() { + let fixture = Fixture::new(); + assert!(!fixture.verdict().allowed()); + let review = fixture.signed(); + let report = fixture + .repo + .validate_publication_review(&review, &fixture.config(), &|did| fixture.keys(did)) + .unwrap(); + assert!(report.conforms, "{:#?}", report.results); + assert!(report + .target_coverage + .iter() + .any(|c| c.evaluated > 0 && c.shape.ends_with("Evaluation"))); + assert_eq!( + review.subject.changes.len(), + 2, + "full dependency closure is pinned" + ); + let mut original = Vec::new(); + fixture + .repo + .load_change(&fixture.change) + .unwrap() + .serialize(&mut original) + .unwrap(); + let path = fixture + .repo + .record_publication_review(&review, &fixture.config(), &|did| fixture.keys(did)) + .unwrap(); + let verdict = fixture.verdict(); + assert!(verdict.allowed(), "{}", verdict.refusal_report()); + assert_eq!(verdict.retrospective_reviews.len(), 1); + let mut after = Vec::new(); + fixture + .repo + .load_change(&fixture.change) + .unwrap() + .serialize(&mut after) + .unwrap(); + assert_eq!(after, original); + assert!(fixture + .repo + .find_attestations_for_change(&fixture.change) + .unwrap() + .is_empty()); + assert_eq!( + fixture + .repo + .record_publication_review(&review, &fixture.config(), &|did| fixture.keys(did)) + .unwrap(), + path + ); +} + +#[test] +fn stale_wrong_scope_and_truncated_subjects_fail_even_when_resigned() { + let f = Fixture::new(); + let original = f.signed(); + let mut variants = vec![]; + let mut r = original.clone(); + r.subject.project = "urn:atomic:project:another".into(); + variants.push(r); + let mut r = original.clone(); + r.subject.changes[0].session = Some("other-session".into()); + variants.push(r); + let mut r = original.clone(); + r.subject.changes.pop(); + variants.push(r); + let mut r = original.clone(); + r.subject.work.clear(); + variants.push(r); + let mut r = original.clone(); + r.subject.profile_hash = "old-profile".into(); + variants.push(r); + for review in variants { + assert!(!f.conforms(&f.sign(review), &f.config())); + } +} + +#[test] +fn signature_trust_and_revocation_are_not_self_asserted() { + let f = Fixture::new(); + let signed = f.signed(); + let mut changed = signed.clone(); + changed.reviewed_at = "2026-01-01T00:00:00Z".into(); + assert!(!f.conforms(&changed, &f.config())); + let mut config = f.config(); + config.trust.signers.clear(); + assert!(!f.conforms(&signed, &config)); + config = f.config(); + config.trust.revoked = config.trust.signers.clone(); + assert!(!f.conforms(&signed, &config)); + assert!(!f + .repo + .validate_publication_review(&signed, &f.config(), &|_| None) + .is_ok()); +} + +#[test] +fn self_review_with_the_work_authors_key_is_rejected() { + let mut f = Fixture::new(); + f.review = signed_intent(&f.repo, &f.author, &f.author_key, "review", Some(&f.work)); + let prepared = f + .repo + .prepare_publication_review(&f.review, &[f.change], &|did| f.keys(did)) + .unwrap(); + let signed: PublicationReview = serde_json::from_value(atomic_canonical::proof::attest_value( + prepared.value(), + &f.author, + &f.author_key, + )) + .unwrap(); + let mut config = f.config(); + config + .trust + .signers + .push(atomic_canonical::did::did_for_public_key( + &f.author.public_key, + )); + assert!(!f.conforms(&signed, &config)); +} + +#[test] +fn later_intent_edit_and_forged_freshness_anchor_are_rejected() { + let f = Fixture::new(); + let signed = f.signed(); + f.repo + .vault_intent_update( + &f.work, + IntentUpdateOptions { + title: Some("changed meaning".into()), + force: true, + ..Default::default() + }, + ) + .unwrap(); + assert!(!f.conforms(&signed, &f.config())); + // Forge the unprotected sidecar anchor while retaining the old valid signature. + let inputs = bridge::read_intent(&f.repo, &f.work).unwrap(); + let path = bridge::attestation_vault_path(&f.repo, &f.work).unwrap(); + let entry = f.repo.vault_retrieve(&path).unwrap().unwrap(); + f.repo + .vault_store( + &path, + VaultEntryType::Attestation, + entry.content_bytes, + json!({"sourceContentHash":bridge::source_content_hash(&inputs)}).to_string(), + ) + .unwrap(); + assert!(!f.conforms(&signed, &f.config())); +} + +#[test] +fn incomplete_review_and_missing_required_verification_are_rejected() { + for replacement in ["status=unmet", "status=met"] { + let f = Fixture::new(); + let inputs = bridge::read_intent(&f.repo, &f.review).unwrap(); + let body = if replacement == "status=unmet" { + inputs.body.replace("status=met", replacement) + } else { + inputs + .body + .lines() + .filter(|line| !line.starts_with("::verification")) + .collect::>() + .join("\n") + }; + // The normal lifecycle refuses this edit. Model a signed but invalid + // artifact arriving through the low-level vault/transport boundary. + let path = f + .repo + .vault_list("intents/", Some(VaultEntryType::Intent)) + .unwrap() + .into_iter() + .find(|meta| { + let entry = f.repo.vault_retrieve(&meta.path).unwrap().unwrap(); + serde_json::from_str::(&entry.frontmatter_json).unwrap()["uid"] + == f.review + }) + .unwrap() + .path; + f.repo + .vault_store( + &path, + VaultEntryType::Intent, + body.into_bytes(), + serde_json::to_string(&inputs.frontmatter).unwrap(), + ) + .unwrap(); + sign_intent(&f.repo, &f.review, &f.reviewer, &f.reviewer_key); + assert!(!f.conforms(&f.signed(), &f.config())); + } +} + +#[test] +fn bad_original_attestation_is_not_replaced_by_a_good_review() { + let f = Fixture::new(); + let review = f.signed(); + f.repo + .record_publication_review(&review, &f.config(), &|did| f.keys(did)) + .unwrap(); + let mut original = + Attestation::builder(SESSION, AttestAgent::new("fixture", "fixture", "fixture")) + .changes_covered(vec![f.change]) + .build(); + let did = atomic_canonical::did::did_for_public_key(&f.reviewer.public_key); + original.sign_with_did(&did, f.reviewer_key.secret.as_bytes()); + original.changes_covered.push(Hash::of(b"tampered")); + f.repo.save_attestation(&original).unwrap(); + assert!(!f.verdict().allowed()); + assert!(f.verdict().retrospective_reviews.is_empty()); +} + +#[test] +fn malformed_registered_reviews_fail_closed_and_duplicate_json_is_refused() { + let f = Fixture::new(); + f.repo + .vault_store( + "publication-reviews/broken/review.md", + VaultEntryType::Attestation, + b"{}".to_vec(), + "{}".into(), + ) + .unwrap(); + assert!(!f.verdict().allowed()); + assert!(PublicationReview::parse(br#"{"schema":"x","schema":"y"}"#).is_err()); +} diff --git a/atomic-repository/src/repository/publication_review/tests/boundaries.rs b/atomic-repository/src/repository/publication_review/tests/boundaries.rs new file mode 100644 index 00000000..6341e5db --- /dev/null +++ b/atomic-repository/src/repository/publication_review/tests/boundaries.rs @@ -0,0 +1,355 @@ +use super::*; + +#[test] +fn evidence_writes_reuse_an_existing_nonreentrant_boundary_without_widening_it() { + let f = Fixture::new(); + f.repo + .record_publication_review(&f.signed(), &f.config(), &|did| f.keys(did)) + .unwrap(); + let _outer = f.repo.try_lock_common_operation().unwrap(); + f.repo + .vault_store( + "scratch/outer-operation.md", + VaultEntryType::Scratch, + b"metadata write".to_vec(), + "{}".into(), + ) + .unwrap(); + assert!( + f.repo.try_lock_common_operation().is_err(), + "metadata alias must not enable independent nested operations" + ); +} + +#[test] +fn review_materialization_preserves_unregistered_working_files() { + let f = Fixture::new(); + let signed = f.signed(); + let parent = f + .repo + .vault_dir() + .join("publication-reviews") + .join(signed.artifact_hash()); + std::fs::create_dir_all(&parent).unwrap(); + let file = parent.join("review.md"); + std::fs::write(&file, b"user work").unwrap(); + assert!(f + .repo + .record_publication_review(&signed, &f.config(), &|did| f.keys(did)) + .is_err()); + assert_eq!(std::fs::read(&file).unwrap(), b"user work"); + assert!(f.repo.publication_reviews().unwrap().is_empty()); +} + +#[cfg(unix)] +#[test] +fn review_materialization_refuses_symlinked_parents() { + let f = Fixture::new(); + let signed = f.signed(); + let outside = tempfile::tempdir().unwrap(); + std::os::unix::fs::symlink( + outside.path(), + f.repo.vault_dir().join("publication-reviews"), + ) + .unwrap(); + assert!(f + .repo + .record_publication_review(&signed, &f.config(), &|did| f.keys(did)) + .is_err()); + assert_eq!(std::fs::read_dir(outside.path()).unwrap().count(), 0); + assert!(f.repo.publication_reviews().unwrap().is_empty()); +} + +#[test] +fn preparing_after_parent_advance_does_not_refresh_old_test_evidence() { + let f = Fixture::new(); + let original_own_state = f + .repo + .get_view_info("review-source") + .unwrap() + .state_base32(); + let other = f + .repo + .save_change(&Change::empty(ChangeHeader::new("new inherited context"))) + .unwrap(); + f.repo + .insert_change_rec(&other, crate::InsertOptions::default().view("dev")) + .unwrap(); + assert_eq!( + f.repo + .get_view_info("review-source") + .unwrap() + .state_base32(), + original_own_state + ); + assert!( + !f.conforms(&f.signed(), &f.config()), + "a fresh subject cannot refresh a check against old inherited context" + ); +} + +#[test] +fn source_and_inherited_state_advances_do_not_change_reviewed_content() { + for view in ["review-source", "dev"] { + let f = Fixture::new(); + f.repo + .record_publication_review(&f.signed(), &f.config(), &|did| f.keys(did)) + .unwrap(); + let other = f + .repo + .save_change(&Change::empty(ChangeHeader::new("new view state"))) + .unwrap(); + f.repo + .insert_change_rec(&other, crate::InsertOptions::default().view(view)) + .unwrap(); + assert!( + f.verdict().allowed(), + "an immutable review must survive live view/ancestor advancement" + ); + let stored = f.repo.publication_reviews().unwrap(); + assert!(!stored[0] + .subject + .changes + .iter() + .any(|pin| pin.hash == other.to_base32())); + assert!(!stored[0] + .subject + .snapshot + .as_ref() + .unwrap() + .membership + .contains(&other.to_base32())); + } +} + +#[test] +fn review_checks_at_an_unrelated_state_cannot_authorize_current_changes() { + let f = Fixture::new(); + let inputs = bridge::read_intent(&f.repo, &f.review).unwrap(); + let state = f + .repo + .get_view_info("review-source") + .unwrap() + .state_base32(); + let body = inputs.body.replace( + &format!("observedAtMerkle={state}"), + "observedAtMerkle=unrelated-state", + ); + f.repo + .vault_intent_update( + &f.review, + IntentUpdateOptions { + content: Some(body), + force: true, + ..Default::default() + }, + ) + .unwrap(); + sign_intent(&f.repo, &f.review, &f.reviewer, &f.reviewer_key); + assert!(!f.conforms(&f.signed(), &f.config())); +} + +#[test] +fn approval_is_exact_and_does_not_clear_incomplete_sessions() { + let f = Fixture::new(); + f.repo + .record_publication_review(&f.signed(), &f.config(), &|did| f.keys(did)) + .unwrap(); + assert!(f + .repo + .retrospective_review_for( + &Hash::of(b"another change").to_base32(), + SESSION, + &f.config(), + Some(&|did| f.keys(did)) + ) + .unwrap() + .is_none()); + assert!(f + .repo + .retrospective_review_for( + &f.change.to_base32(), + "another-session", + &f.config(), + Some(&|did| f.keys(did)) + ) + .unwrap() + .is_none()); + let incomplete = atomic_core::change::session::IncompleteSession::new( + "retained incomplete original", + Vec::::new(), + "refs/atomic/wip/fixture", + atomic_core::change::session::SessionIncompleteOrigin::UnattributedGitOperation, + ); + f.repo + .mark_session_incomplete(SESSION, None, None, &incomplete) + .unwrap(); + let verdict = f.verdict(); + assert!(!verdict.allowed()); + assert!(verdict.blocks.iter().any(|block| matches!( + block, + super::super::super::provenance_gate::GateBlocker::SessionIncomplete { .. } + ))); +} + +#[test] +fn actual_shared_insertion_revalidates_the_exact_retained_subject() { + let f = Fixture::new(); + let path = f.repo.dot_dir().join("config.toml"); + let mut config = atomic_config::RepoConfig::load(&path).unwrap(); + config.git.trust = f.config().trust; + config.save(&path).unwrap(); + let before = f.repo.get_view_changes(Some("dev")).unwrap(); + assert!(!before.iter().any(|(_, hash)| *hash == f.change)); + f.repo + .record_publication_review(&f.signed(), &f.config(), &|did| f.keys(did)) + .unwrap(); + f.repo + .insert_from_view(crate::CrossViewInsertOptions::new("review-source", "dev")) + .unwrap(); + assert!(f + .repo + .get_view_changes(Some("dev")) + .unwrap() + .iter() + .any(|(_, hash)| *hash == f.change)); + assert_eq!(f.repo.current_view(), "review-source"); +} + +#[test] +fn renewal_retains_history_and_cannot_suppress_a_different_scope() { + let f = Fixture::new(); + let old = f.signed(); + let old_path = f + .repo + .record_publication_review(&old, &f.config(), &|did| f.keys(did)) + .unwrap(); + assert!(f.repo.vault_delete(&old_path).is_err()); + assert!(f + .repo + .vault_store( + &old_path, + VaultEntryType::Attestation, + b"{}".to_vec(), + "{}".into() + ) + .is_err()); + f.repo + .vault_intent_update( + &f.review, + IntentUpdateOptions { + title: Some("renewed exact review".into()), + status: Some("done".into()), + force: true, + ..Default::default() + }, + ) + .unwrap(); + sign_intent(&f.repo, &f.review, &f.reviewer, &f.reviewer_key); + let mut renewed = f.signed(); + renewed.supersedes = vec![old.artifact_hash()]; + renewed = f.sign(renewed); + f.repo + .record_publication_review(&renewed, &f.config(), &|did| f.keys(did)) + .unwrap(); + assert!(f.verdict().allowed(), "{}", f.verdict().refusal_report()); + assert_eq!(f.repo.publication_reviews().unwrap().len(), 2); + assert!(f.repo.vault_retrieve(&old_path).unwrap().is_some()); + let mut wrong = renewed.clone(); + wrong.supersedes = vec!["missing-review".into()]; + wrong = f.sign(wrong); + assert!(f + .repo + .record_publication_review(&wrong, &f.config(), &|did| f.keys(did)) + .is_err()); +} + +#[test] +fn unindexed_bad_original_and_missing_registered_provenance_fail_closed() { + let f = Fixture::new(); + let signed = f.signed(); + f.repo + .record_publication_review(&signed, &f.config(), &|did| f.keys(did)) + .unwrap(); + let original = Attestation::builder(SESSION, AttestAgent::new("fixture", "fixture", "fixture")) + .changes_covered(vec![f.change]) + .build(); + f.repo.change_store().save_attestation(&original).unwrap(); // deliberately unindexed + assert!(!f.verdict().allowed()); + let f = Fixture::new(); + let signed = f.signed(); + f.repo + .record_publication_review(&signed, &f.config(), &|did| f.keys(did)) + .unwrap(); + let hash = Hash::from_base32( + signed + .subject + .changes + .iter() + .find(|c| c.hash == f.change.to_base32()) + .unwrap() + .provenance[0] + .as_bytes(), + ) + .unwrap(); + std::fs::remove_file(f.repo.change_store().provenance_path(&hash)).unwrap(); + assert!(!f.verdict().allowed()); +} + +#[test] +fn unrelated_observed_intent_cannot_be_excluded_by_the_review_author() { + let f = Fixture::new(); + let owner = signed_intent(&f.repo, &f.author, &f.author_key, "feature", None); + let graph = ProvenanceGraphBuilder::new(SESSION, "fixture") + .add_node(receipt_node(&owner)) + .changes_explained(vec![f.change]) + .build(); + f.repo.save_provenance_graph(&graph).unwrap(); + assert!(!f.conforms(&f.signed(), &f.config())); +} + +#[test] +fn evidence_writer_contends_with_the_promotion_boundary() { + let f = Fixture::new(); + f.repo + .record_publication_review(&f.signed(), &f.config(), &|did| f.keys(did)) + .unwrap(); + std::thread::scope(|scope| { + let (ready_send, ready_receive) = std::sync::mpsc::channel(); + let (release_send, release_receive) = std::sync::mpsc::channel(); + let path = f.repo.root().to_path_buf(); + let pristine = std::sync::Arc::clone(&f.repo.pristine); + let worker = scope.spawn(move || { + let repo = Repository::open_with_pristine(&path, pristine).unwrap(); + let _guard = repo + .try_lock_common_operation_with_reentrancy(true) + .unwrap(); + ready_send.send(()).unwrap(); + release_receive.recv().unwrap(); + }); + ready_receive.recv().unwrap(); + let attempt = f.repo.vault_intent_update( + &f.review, + IntentUpdateOptions { + title: Some("racing update".into()), + force: true, + ..Default::default() + }, + ); + let view_attempt = f.repo.set_view_identity( + "review-source", + atomic_core::pristine::ViewScope::Draft, + None, + ); + release_send.send(()).unwrap(); + worker.join().unwrap(); + assert!( + attempt.is_err(), + "evidence must not mutate under another operation's publication lease" + ); + assert!( + view_attempt.is_err(), + "view identity must not change during publication either" + ); + }); +} diff --git a/atomic-repository/src/repository/publication_review/tests/observations.rs b/atomic-repository/src/repository/publication_review/tests/observations.rs new file mode 100644 index 00000000..3e6865a0 --- /dev/null +++ b/atomic-repository/src/repository/publication_review/tests/observations.rs @@ -0,0 +1,620 @@ +use super::*; +use atomic_core::kg::ontology::{Class, Predicate}; + +#[test] +fn null_plan_fields_resolve_receipts_without_fabricating_governance() { + let f = Fixture::new(); + let signed = f.signed(); + let pin = signed + .subject + .changes + .iter() + .find(|pin| pin.hash == f.change.to_base32()) + .unwrap(); + assert!(pin.governing_intents.is_empty()); + assert_eq!(pin.observations.len(), 1); + assert_eq!(pin.observations[0].resolution, "resolved"); + assert_eq!(pin.observations[0].turns, vec![0]); + assert_eq!( + pin.observations[0].intent.as_deref(), + Some(format!("urn:atomic:intent:{}", f.work).as_str()) + ); + assert!(f.conforms(&signed, &f.config())); + let graph = f + .repo + .publication_review_snapshot(&signed, &f.config(), &|did| f.keys(did)) + .unwrap(); + assert!(graph + .edges + .iter() + .any(|edge| edge.kind == Predicate::ObservedIntent)); + assert!(!graph.edges.iter().any(|edge| matches!( + edge.kind, + Predicate::HasPlan | Predicate::Implements | Predicate::AttestsSession + ))); +} + +#[test] +fn conflicting_legacy_plan_fields_are_not_consulted() { + let f = Fixture::new(); + let graph = ProvenanceGraphBuilder::new(SESSION, "fixture") + .plan_id("not-an-intent-and-not-a-review-authority") + .add_node(receipt_node(&f.work)) + .changes_explained(vec![f.change]) + .build(); + f.repo.save_provenance_graph(&graph).unwrap(); + let signed = f.signed(); + assert!(f.conforms(&signed, &f.config())); + assert!(signed + .subject + .changes + .iter() + .all(|pin| pin.governing_intents.is_empty())); +} + +#[test] +fn unsigned_preview_reports_blockers_and_cannot_be_recorded() { + let f = Fixture::new(); + let unsigned = f + .repo + .prepare_publication_review(&f.review, &[f.change], &|did| f.keys(did)) + .unwrap(); + let (graph, report) = f + .repo + .preview_publication_review(&unsigned, &f.config(), &|did| f.keys(did)) + .unwrap(); + assert!(!report.conforms); + assert!(graph + .nodes + .iter() + .any(|node| node.types.contains(&Class::ReviewFinding.iri().into()))); + assert!(graph + .nodes + .iter() + .any(|node| node.types.contains(&Class::IntentObservation.iri().into()))); + assert!(!graph + .edges + .iter() + .any(|edge| edge.kind == Predicate::SignedBy)); + assert!(f + .repo + .record_publication_review(&unsigned, &f.config(), &|did| f.keys(did)) + .is_err()); + assert!(f.repo.publication_reviews().unwrap().is_empty()); + let mut forged = f.signed(); + forged.reviewed_at = "2000-01-01T00:00:00Z".into(); + assert!(f + .repo + .preview_publication_review(&forged, &f.config(), &|did| f.keys(did)) + .is_err()); +} + +#[test] +fn unresolved_and_tampered_receipts_remain_blocking() { + let f = Fixture::new(); + let graph = ProvenanceGraphBuilder::new(SESSION, "fixture") + .add_node(receipt_node("REAC::missing::999")) + .changes_explained(vec![f.change]) + .build(); + let hash = f.repo.save_provenance_graph(&graph).unwrap(); + let signed = f.signed(); + assert!(!f.conforms(&signed, &f.config())); + let pin = signed + .subject + .changes + .iter() + .find(|pin| pin.hash == f.change.to_base32()) + .unwrap(); + assert!(pin + .observations + .iter() + .any(|o| o.resolution == "unresolved" && o.diagnostic.is_some())); + let mut tampered = graph; + tampered.nodes[0] = receipt_node(&f.work); + std::fs::write( + f.repo.change_store().provenance_path(&hash), + tampered.serialize().unwrap(), + ) + .unwrap(); + assert!(f + .repo + .preview_publication_review(&signed, &f.config(), &|did| f.keys(did)) + .is_err()); +} + +#[test] +fn historical_signed_revision_is_visible_but_not_treated_as_current() { + let f = Fixture::new(); + let signed = f.signed(); + f.repo + .vault_intent_update( + &f.work, + IntentUpdateOptions { + title: Some("Changed after the historical signature".into()), + force: true, + ..Default::default() + }, + ) + .unwrap(); + let (graph, report) = f + .repo + .preview_publication_review(&signed, &f.config(), &|did| f.keys(did)) + .unwrap(); + assert!(!report.conforms); + assert!(graph + .nodes + .iter() + .filter_map(|node| node.metadata.as_ref()) + .any( + |metadata| metadata.get("source_relation").and_then(|v| v.as_str()) + == Some("retained-not-current") + && metadata.get("signature_verified").and_then(|v| v.as_bool()) == Some(true) + )); + assert!(!f.conforms(&signed, &f.config())); +} + +#[test] +fn unindexed_provenance_is_not_silently_assigned_to_a_turn() { + let f = Fixture::new(); + let graph = ProvenanceGraphBuilder::new("unindexed-session", "fixture") + .add_node(receipt_node(&f.work)) + .changes_explained(vec![f.change]) + .build(); + f.repo.change_store().save_provenance_graph(&graph).unwrap(); + let signed = f.signed(); + let pin = signed + .subject + .changes + .iter() + .find(|pin| pin.hash == f.change.to_base32()) + .unwrap(); + assert!(pin + .observations + .iter() + .any(|o| o.session == "unindexed-session" + && o.turns.is_empty() + && o.resolution == "unresolved")); + assert!(!f.conforms(&signed, &f.config())); +} + +#[test] +fn stored_review_nodes_extend_the_existing_intent_graph_without_authority_claims() { + let f = Fixture::new(); + f.repo + .record_publication_review(&f.signed(), &f.config(), &|did| f.keys(did)) + .unwrap(); + for id in [&f.work, &f.review] { + let graph = f.repo.intent_graph(id, 1000).unwrap(); + assert!(graph + .nodes + .iter() + .any(|node| node.has_type(Class::PublicationReview))); + assert!(graph + .nodes + .iter() + .any(|node| node.has_type(Class::ReviewSubject))); + assert!(graph + .nodes + .iter() + .any(|node| node.has_type(Class::IntentObservation))); + assert!(graph + .reviewed_changes + .contains(&atomic_core::kg::iri::mint_change(&f.change))); + assert!(graph.implementing_changes.is_empty()); + assert!(!graph + .edges + .iter() + .any(|edge| matches!(edge.kind, Predicate::HasPlan | Predicate::Implements))); + let artifact = graph + .nodes + .iter() + .find(|node| node.has_type(Class::PublicationReview)) + .unwrap(); + assert_eq!( + artifact.metadata.as_ref().unwrap()["validation"], + "not-evaluated" + ); + assert!(!graph + .edges + .iter() + .any(|edge| edge.from_id == artifact.id && edge.kind == Predicate::VerificationResult)); + } +} + +#[test] +fn preview_extends_intent_graph_but_preserves_current_intent_state() { + let f = Fixture::new(); + let prepared = f + .repo + .prepare_publication_review(&f.review, &[f.change], &|did| f.keys(did)) + .unwrap(); + f.repo + .vault_intent_update( + &f.work, + IntentUpdateOptions { + title: Some( + "Current title must not be overwritten by a signed historical title".into(), + ), + force: true, + ..Default::default() + }, + ) + .unwrap(); + let (snapshot, identity) = f + .repo + .workflow_snapshot_with_review(&serde_json::to_vec(&prepared).unwrap()) + .unwrap(); + assert_eq!(identity, prepared.artifact_hash()); + let baseline = f.repo.intent_graph(&f.work, 1000).unwrap(); + let graph = + crate::intent_graph::IntentGraph::from_snapshot(&snapshot, &baseline.root, 1000).unwrap(); + let root = graph + .nodes + .iter() + .find(|node| node.id == graph.root) + .unwrap(); + assert!(root.label.starts_with("Current title must not")); + assert!(root + .metadata + .as_ref() + .unwrap() + .get("review_contexts") + .is_some()); + assert!(graph + .nodes + .iter() + .any(|node| node.has_type(Class::ReviewEvaluation))); + assert!(graph + .nodes + .iter() + .any(|node| node.has_type(Class::ReviewFinding))); + assert!(graph + .nodes + .iter() + .any(|node| node.has_type(Class::CriterionJudgment))); + assert!(graph + .nodes + .iter() + .any(|node| node.has_type(Class::VerificationRecord))); + assert!(graph + .diagnostics + .iter() + .any(|d| d.contains("Review preview: blocked"))); + assert!(graph.implementing_changes.is_empty()); + assert!(f.repo.publication_reviews().unwrap().is_empty()); + assert!(!graph.truncated); +} + +#[test] +fn feedback_updates_the_original_review_instead_of_creating_replacement_intents() { + let f = Fixture::new(); + let other = signed_intent(&f.repo, &f.author, &f.author_key, "feature", None); + let mut first = receipt_node(&other); + first.id = "receipt-1".into(); + let mut second = receipt_node(&other); + second.id = "receipt-2".into(); + let graph = ProvenanceGraphBuilder::new(SESSION, "fixture") + .nodes(vec![first, second]) + .changes_explained(vec![f.change]) + .build(); + f.repo.save_provenance_graph(&graph).unwrap(); + let before = f.signed(); + let report = f + .repo + .validate_publication_review(&before, &f.config(), &|did| f.keys(did)) + .unwrap(); + assert!(!report.conforms); + assert_eq!( + report.results.len(), + 1, + "Repeated receipts must produce one actionable work-scope finding: {:?}", + report.results + ); + assert!(report.results[0]["value"] + .as_str() + .unwrap() + .ends_with(&other)); + let mut body = bridge::read_intent(&f.repo, &f.review).unwrap().body; + body.push_str(&format!( + "\n:::ref{{to=urn:atomic:intent:{other} edge=reviews}}\n:::\n" + )); + f.repo + .vault_intent_update( + &f.review, + IntentUpdateOptions { + content: Some(body), + force: true, + ..Default::default() + }, + ) + .unwrap(); + f.repo + .vault_intent_update( + &f.review, + IntentUpdateOptions { + status: Some("done".into()), + force: true, + ..Default::default() + }, + ) + .unwrap(); + sign_intent(&f.repo, &f.review, &f.reviewer, &f.reviewer_key); + let after = f.signed(); + assert_eq!(before.subject.review.id, after.subject.review.id); + let report = f + .repo + .validate_publication_review(&after, &f.config(), &|did| f.keys(did)) + .unwrap(); + assert!(report.conforms, "{:?}", report.results); + let snapshot = f + .repo + .publication_review_snapshot(&after, &f.config(), &|did| f.keys(did)) + .unwrap(); + let other_id = + atomic_core::kg::iri::mint_intent(&f.repo.project_id().unwrap(), &other).unwrap(); + assert!(snapshot + .edges + .iter() + .any(|edge| edge.from_id == other_id && edge.kind == Predicate::HasAcceptanceCriterion)); +} + +#[test] +fn selected_review_lifecycle_is_context_not_work_requiring_self_review() { + let f = Fixture::new(); + let before = f.signed(); + let mut change = Change::empty(ChangeHeader::new("review metadata only")); + change.hashed.dependencies.push(f.change); + let mut provenance = Provenance::new( + AIVendor::default(), + "fixture", + AITool::Cli("fixture".into()), + ); + provenance.session_id = Some(SESSION.into()); + change.hashed.provenance.push(provenance); + change.hashed.metadata = + atomic_core::change::envelope::SessionEnvelope::builder(SESSION, "fixture") + .build() + .encode() + .unwrap(); + let hash = f.repo.save_change(&change).unwrap(); + f.repo + .save_provenance_graph( + &ProvenanceGraphBuilder::new(SESSION, "fixture") + .add_node(receipt_node(&f.review)) + .changes_explained(vec![hash]) + .build(), + ) + .unwrap(); + f.repo + .insert_change_rec(&hash, crate::InsertOptions::default().view("review-source")) + .unwrap(); + let state = f + .repo + .get_view_info("review-source") + .unwrap() + .state_base32(); + let set = f.repo.view_set_id("review-source").unwrap().to_base32(); + let body = bridge::read_intent(&f.repo, &f.review) + .unwrap() + .body + .replace(&before.subject.view_chain[0].state, &state) + .replace(&before.subject.effective_set_id, &set); + f.repo + .vault_intent_update( + &f.review, + IntentUpdateOptions { + content: Some(body), + force: true, + ..Default::default() + }, + ) + .unwrap(); + sign_intent(&f.repo, &f.review, &f.reviewer, &f.reviewer_key); + let prepared = f + .repo + .prepare_publication_review(&f.review, &[hash], &|did| f.keys(did)) + .unwrap(); + let signed = f.sign(prepared); + let pin = signed + .subject + .changes + .iter() + .find(|pin| pin.hash == hash.to_base32()) + .unwrap(); + assert_eq!( + pin.observations[0].role, + atomic_canonical::publication_review::ObservationRole::ReviewContext + ); + assert!(!signed + .subject + .work + .iter() + .any(|work| work.id == signed.subject.review.id)); + assert!(f.conforms(&signed, &f.config())); + let mut forged = signed; + forged + .subject + .changes + .iter_mut() + .find(|pin| pin.hash == f.change.to_base32()) + .unwrap() + .observations[0] + .role = atomic_canonical::publication_review::ObservationRole::ReviewContext; + assert!( + !f.conforms(&f.sign(forged), &f.config()), + "Work cannot be relabeled as review context" + ); +} + +#[test] +fn additive_observation_roles_do_not_readdress_retained_work_documents() { + let f = Fixture::new(); + let signed = f.signed(); + let value = signed.value(); + for pin in value["subject"]["changes"].as_array().unwrap() { + if let Some(observations) = pin.get("observations").and_then(|v| v.as_array()) { + for observation in observations { + assert!(observation.get("role").is_none()); + } + } + } + let retained = PublicationReview::parse(&serde_json::to_vec(&value).unwrap()).unwrap(); + assert_eq!(retained.artifact_hash(), signed.artifact_hash()); + assert!(f.conforms(&retained, &f.config())); +} + +fn retire_fixture_work(f: &Fixture, id: &str, signer: &Identity, pair: &KeyPair) { + let body = bridge::read_intent(&f.repo, id) + .unwrap() + .body + .replace("status=met", "status=unmet"); + f.repo + .vault_intent_update( + id, + IntentUpdateOptions { + status: Some("icebox".into()), + content: Some(body), + force: true, + ..Default::default() + }, + ) + .unwrap(); + sign_intent(&f.repo, id, signer, pair); +} + +fn extend_fixture_review(f: &Fixture, id: &str) { + let mut body = bridge::read_intent(&f.repo, &f.review).unwrap().body; + body.push_str(&format!( + "\n:::ref{{to=urn:atomic:intent:{id} edge=reviews}}\n:::\n" + )); + f.repo + .vault_intent_update( + &f.review, + IntentUpdateOptions { + content: Some(body), + force: true, + ..Default::default() + }, + ) + .unwrap(); + f.repo + .vault_intent_update( + &f.review, + IntentUpdateOptions { + status: Some("done".into()), + force: true, + ..Default::default() + }, + ) + .unwrap(); + sign_intent(&f.repo, &f.review, &f.reviewer, &f.reviewer_key); +} + +#[test] +fn terminal_disposition_does_not_approve_historical_implementation_goals() { + let f = Fixture::new(); + let retired = signed_intent(&f.repo, &f.author, &f.author_key, "feature", None); + retire_fixture_work(&f, &retired, &f.author, &f.author_key); + extend_fixture_review(&f, &retired); + let signed = f.signed(); + assert_eq!(signed.subject.set_aside.len(), 1); + assert_eq!(signed.subject.work.len(), 1); + assert!(f.conforms(&signed,&f.config()),"An independently reviewed terminal disposition need not pretend unmet historical goals are met"); + let snapshot = f + .repo + .publication_review_snapshot(&signed, &f.config(), &|did| f.keys(did)) + .unwrap(); + assert!(snapshot + .edges + .iter() + .any(|edge| edge.kind == Predicate::IncludesSetAside)); + let mut forged = signed; + let pin = forged.subject.set_aside.pop().unwrap(); + forged.subject.work.push(pin); + assert!(!f.conforms(&f.sign(forged), &f.config())); +} + +#[test] +fn reviewed_set_aside_intent_observed_by_a_change_does_not_block() { + let (f, retired) = Fixture::with_second_observed_intent(); + retire_fixture_work(&f, &retired, &f.author, &f.author_key); + extend_fixture_review(&f, &retired); + let signed = f.signed(); + assert_eq!(signed.subject.work.len(), 1); + assert_eq!(signed.subject.set_aside.len(), 1); + let observed: Vec<_> = signed + .subject + .changes + .iter() + .flat_map(|pin| pin.observations.iter()) + .filter_map(|observation| observation.intent.clone()) + .collect(); + assert!( + observed.contains(&format!("urn:atomic:intent:{retired}")), + "the retained receipt observes the set-aside intent" + ); + let report = f + .repo + .validate_publication_review(&signed, &f.config(), &|did| f.keys(did)) + .unwrap(); + assert!( + report.conforms, + "an explicitly reviewed set-aside intent is complete review scope: {:#?}", + report.results + ); +} + +#[test] +fn unreviewed_set_aside_intent_observed_by_a_change_still_blocks() { + let (f, retired) = Fixture::with_second_observed_intent(); + retire_fixture_work(&f, &retired, &f.author, &f.author_key); + // The review never references the retired intent, so the resolver pins + // nothing for it: inactive status alone must not complete the scope. + let signed = f.signed(); + assert!(signed.subject.set_aside.is_empty()); + let report = f + .repo + .validate_publication_review(&signed, &f.config(), &|did| f.keys(did)) + .unwrap(); + assert!(!report.conforms); + let retired_iri = + atomic_core::kg::iri::mint_intent(&f.repo.project_id().unwrap(), &retired).unwrap(); + assert!( + report.results.iter().any(|r| { + r["value"].as_str() == Some(retired_iri.as_str()) + && r["source_shape"] + .as_str() + .is_some_and(|shape| shape.ends_with("#Subject")) + }), + "the scope rule names the unreviewed set-aside intent: {:#?}", + report.results + ); +} + +#[test] +fn terminal_disposition_still_requires_an_independent_key() { + let f = Fixture::new(); + let retired = signed_intent(&f.repo, &f.reviewer, &f.reviewer_key, "feature", None); + retire_fixture_work(&f, &retired, &f.reviewer, &f.reviewer_key); + extend_fixture_review(&f, &retired); + assert!(!f.conforms(&f.signed(), &f.config())); +} + +#[test] +fn retired_intent_cannot_supply_managed_change_coverage() { + let f = Fixture::new(); + let active = signed_intent(&f.repo, &f.author, &f.author_key, "feature", None); + retire_fixture_work(&f, &f.work, &f.author, &f.author_key); + extend_fixture_review(&f, &active); + let signed = f.signed(); + assert_eq!(signed.subject.set_aside.len(), 1); + assert_eq!(signed.subject.work.len(), 1); + let report = f + .repo + .validate_publication_review(&signed, &f.config(), &|did| f.keys(did)) + .unwrap(); + assert!(!report.conforms); + assert!(report.results.iter().any( + |r| r["value"].as_str() == Some(atomic_core::kg::iri::mint_change(&f.change).as_str()) + )); +} diff --git a/atomic-repository/src/repository/publication_review/tests/snapshot.rs b/atomic-repository/src/repository/publication_review/tests/snapshot.rs new file mode 100644 index 00000000..f8af552a --- /dev/null +++ b/atomic-repository/src/repository/publication_review/tests/snapshot.rs @@ -0,0 +1,131 @@ +use super::*; + +fn store_trusted(f: &Fixture, signed: &PublicationReview) { + let path = f.repo.dot_dir().join("config.toml"); + let mut config = atomic_config::RepoConfig::load(&path).unwrap(); + config.git.trust = f.config().trust; + config.save(&path).unwrap(); + f.repo + .record_publication_review(signed, &f.config(), &|did| f.keys(did)) + .unwrap(); +} + +#[test] +fn stored_approval_survives_source_view_deletion_and_name_reuse() { + let mut f = Fixture::new(); + let signed = f.signed(); + assert_eq!(signed.schema, SCHEMA); + store_trusted(&f, &signed); + f.repo + .insert_change_rec(&f.change, crate::InsertOptions::default().view("dev")) + .unwrap(); + let wc = f.repo.require_working_copy_id().unwrap(); + f.repo.switch_view(wc, "dev").unwrap(); + f.repo.delete_view("review-source").unwrap(); + assert!(f.conforms(&signed, &f.config())); + assert!(f.verdict().allowed()); + f.repo.create_draft_view("review-source", "dev").unwrap(); + let other = f + .repo + .save_change(&Change::empty(ChangeHeader::new( + "unrelated replacement view", + ))) + .unwrap(); + f.repo + .insert_change_rec( + &other, + crate::InsertOptions::default().view("review-source"), + ) + .unwrap(); + assert!( + f.conforms(&signed, &f.config()), + "historical labels must not bind to a newly reused view name" + ); +} + +#[test] +fn retained_membership_logs_and_intent_documents_cannot_be_forged() { + let f = Fixture::new(); + let original = f.signed(); + let mut variants = Vec::new(); + let mut bad = original.clone(); + bad.subject.snapshot.as_mut().unwrap().membership.pop(); + variants.push(bad); + let mut bad = original.clone(); + bad.subject.snapshot.as_mut().unwrap().view_logs[0].pop(); + variants.push(bad); + let mut bad = original.clone(); + bad.subject.snapshot.as_mut().unwrap().intent_revisions[0].document["title"] = + json!("forged retained document"); + variants.push(bad); + let mut bad = original.clone(); + bad.subject.snapshot.as_mut().unwrap().intent_revisions[0] + .frontmatter + .insert("title".into(), json!("forged source inputs")); + variants.push(bad); + let mut bad = original.clone(); + bad.subject + .snapshot + .as_mut() + .unwrap() + .intent_revisions + .pop(); + variants.push(bad); + let mut bad = original.clone(); + bad.subject.snapshot.as_mut().unwrap().version = 99; + variants.push(bad); + for bad in variants { + assert!( + !f.conforms(&f.sign(bad), &f.config()), + "even a new outer signature cannot repair broken source evidence" + ); + } + let mut missing = original; + missing.subject.snapshot = None; + assert!(PublicationReview::parse(&serde_json::to_vec(&missing).unwrap()).is_err()); +} + +#[test] +fn deletion_does_not_disable_trust_revocation_or_current_intent_freshness() { + let mut f = Fixture::new(); + let signed = f.signed(); + store_trusted(&f, &signed); + f.repo + .insert_change_rec(&f.change, crate::InsertOptions::default().view("dev")) + .unwrap(); + f.repo + .switch_view(f.repo.require_working_copy_id().unwrap(), "dev") + .unwrap(); + f.repo.delete_view("review-source").unwrap(); + assert!(f.conforms(&signed, &f.config())); + let mut revoked = f.config(); + revoked.trust.revoked.push(signed.attributed_to.clone()); + assert!(!f.conforms(&signed, &revoked)); + f.repo + .vault_intent_update( + &f.work, + IntentUpdateOptions { + title: Some("changed intent still requires review".into()), + force: true, + ..Default::default() + }, + ) + .unwrap(); + assert!(!f.conforms(&signed, &f.config())); +} + +#[test] +fn legacy_documents_keep_addresses_and_do_not_inherit_snapshot_semantics() { + let f = Fixture::new(); + let mut legacy = f.signed(); + legacy.schema = atomic_canonical::publication_review::LEGACY_SCHEMA.into(); + legacy.subject.snapshot = None; + let legacy = f.sign(legacy); + let bytes = serde_json::to_vec(&legacy).unwrap(); + let parsed = PublicationReview::parse(&bytes).unwrap(); + assert_eq!(parsed.artifact_hash(), legacy.artifact_hash()); + assert!(f.conforms(&parsed, &f.config())); + let mut invalid = parsed; + invalid.subject.snapshot = f.signed().subject.snapshot; + assert!(PublicationReview::parse(&serde_json::to_vec(&invalid).unwrap()).is_err()); +} diff --git a/atomic-repository/src/repository/vault.rs b/atomic-repository/src/repository/vault.rs index f952e147..97e5f43e 100644 --- a/atomic-repository/src/repository/vault.rs +++ b/atomic-repository/src/repository/vault.rs @@ -207,6 +207,7 @@ impl Repository { content: Vec, frontmatter_json: String, ) -> Result { + let _review_boundary = self.review_evidence_lock()?; self.ensure_project_identity(atomic_core::kg::project_id::MintReason::Upgrade)?; let now = chrono::Utc::now().to_rfc3339(); let entry = VaultEntry::new(entry_type, content, frontmatter_json, now.clone()); @@ -221,6 +222,17 @@ impl Repository { let previous_entry = txn .get_vault_entry(path) .map_err(|e| RepositoryError::Database(e.to_string()))?; + if path.starts_with(super::publication_review::PREFIX) + && previous_entry.as_ref().is_some_and(|old| { + old.content_bytes != entry.content_bytes + || old.frontmatter_json != entry.frontmatter_json + || old.entry_type != entry.entry_type + }) + { + return Err(super::publication_review::refused( + "stored reviews are immutable; use signed supersession", + )); + } let cascade_updates = match previous_entry.as_ref() { Some(previous) if previous.entry_type != entry_type => { unlink_goal_from_intent_entries(&mut txn, path, previous, &now)? @@ -277,6 +289,7 @@ impl Repository { path: &str, entry: &VaultEntry, ) -> Result { + let _review_boundary = self.review_evidence_lock()?; self.ensure_project_identity(atomic_core::kg::project_id::MintReason::Upgrade)?; let content_hash = Hash::from_bytes(entry.content_hash); let now = chrono::Utc::now().to_rfc3339(); @@ -290,6 +303,17 @@ impl Repository { let previous_entry = txn .get_vault_entry(path) .map_err(|e| RepositoryError::Database(e.to_string()))?; + if path.starts_with(super::publication_review::PREFIX) + && previous_entry.as_ref().is_some_and(|old| { + old.content_bytes != entry.content_bytes + || old.frontmatter_json != entry.frontmatter_json + || old.entry_type != entry.entry_type + }) + { + return Err(super::publication_review::refused( + "stored reviews are immutable; use signed supersession", + )); + } let cascade_updates = match previous_entry.as_ref() { Some(previous) if previous.entry_type != entry.entry_type => { unlink_goal_from_intent_entries(&mut txn, path, previous, &now)? @@ -406,6 +430,12 @@ impl Repository { /// Delete a vault entry by path. Also updates the manifest. pub fn vault_delete(&self, path: &str) -> Result { + let _review_boundary = self.review_evidence_lock()?; + if path.starts_with(super::publication_review::PREFIX) { + return Err(super::publication_review::refused( + "review history is retained; use signed supersession", + )); + } self.ensure_project_identity(atomic_core::kg::project_id::MintReason::Upgrade)?; let mut txn = self .pristine diff --git a/atomic-repository/src/repository/vault_triples.rs b/atomic-repository/src/repository/vault_triples.rs index 2fbcce60..e9506112 100644 --- a/atomic-repository/src/repository/vault_triples.rs +++ b/atomic-repository/src/repository/vault_triples.rs @@ -170,6 +170,42 @@ impl Repository { .project_id() .map_err(|error| RepositoryError::Serialization(error.to_string()))?; let view_scopes = crate::workflow_usage::view_scopes(self, &txn, &project)?; + // Retained review documents contribute reference topology to the same + // snapshot. No policy pass or original-session authenticity is inferred. + let review_entries = txn.list_vault_entries(super::publication_review::PREFIX, None)?; + if review_entries.len() > 4096 { + return Err(super::publication_review::refused( + "review reference inventory exceeds 4096 artifacts", + )); + } + for meta in review_entries { + let entry = txn.get_vault_entry(&meta.path)?.ok_or_else(|| { + RepositoryError::InvalidOperation { + message: "retained review disappeared within snapshot".into(), + } + })?; + let review = atomic_canonical::publication_review::PublicationReview::parse( + &entry.content_bytes, + ) + .map_err(super::publication_review::refused)?; + if meta.path + != format!( + "{}{}/review.md", + super::publication_review::PREFIX, + review.artifact_hash() + ) + { + return Err(super::publication_review::refused( + "stored review address mismatch", + )); + } + super::publication_review::references::extend( + &mut nodes, + &mut edges, + super::publication_review::references::project(&project, &review)?, + &review.artifact_hash(), + ); + } drop(txn); self.hydrate_workflow_usage(&mut nodes)?; crate::workflow_usage::annotate_with_views(&mut nodes, &edges, Some(&view_scopes))?; diff --git a/atomic-repository/src/repository/views.rs b/atomic-repository/src/repository/views.rs index 918847ef..24273782 100644 --- a/atomic-repository/src/repository/views.rs +++ b/atomic-repository/src/repository/views.rs @@ -115,6 +115,7 @@ impl Repository { parent_name: Option<&str>, seed_from: Option<&str>, ) -> Result<(), RepositoryError> { + let _review_boundary = self.review_evidence_lock()?; self.ensure_project_identity(atomic_core::kg::project_id::MintReason::Upgrade)?; // The overlay chain is anchored on the nearest Shared ancestor of the // current view unless a parent is given. Using the nearest SHARED @@ -216,6 +217,7 @@ impl Repository { /// /// Returns `ViewAlreadyExists` if the view already exists. pub fn create_shared_view(&mut self, name: &str) -> Result<(), RepositoryError> { + let _review_boundary = self.review_evidence_lock()?; self.ensure_project_identity(atomic_core::kg::project_id::MintReason::Upgrade)?; ensure_workspace_dir(&self.dot_dir, name)?; @@ -252,6 +254,7 @@ impl Repository { /// This is useful after `git import` which creates Draft views by /// default. pub fn set_view_scope(&self, name: &str, scope: ViewScope) -> Result<(), RepositoryError> { + let _review_boundary = self.review_evidence_lock()?; self.ensure_project_identity(atomic_core::kg::project_id::MintReason::Upgrade)?; let mut txn = self .pristine @@ -307,6 +310,7 @@ impl Repository { scope: ViewScope, parent_name: Option<&str>, ) -> Result<(), RepositoryError> { + let _review_boundary = self.review_evidence_lock()?; self.ensure_project_identity(atomic_core::kg::project_id::MintReason::Upgrade)?; let mut txn = self .pristine @@ -594,6 +598,7 @@ impl Repository { /// - The view is the current view (cannot delete current view) /// - The database operation fails pub fn delete_view(&mut self, name: &str) -> Result<(), RepositoryError> { + let _review_boundary = self.review_evidence_lock()?; self.ensure_project_identity(atomic_core::kg::project_id::MintReason::Upgrade)?; // Cannot delete the current view if name == self.current_view { @@ -787,6 +792,7 @@ impl Repository { scope: ViewScope, parent_name: Option<&str>, ) -> Result<(), RepositoryError> { + let _review_boundary = self.review_evidence_lock()?; self.ensure_project_identity(atomic_core::kg::project_id::MintReason::Upgrade)?; ensure_workspace_dir(&self.dot_dir, name)?; @@ -930,6 +936,7 @@ impl Repository { &mut self, manifest: &ViewManifest, ) -> Result { + let _review_boundary = self.review_evidence_lock()?; manifest.verify()?; for hash in &manifest.changes { @@ -1038,6 +1045,7 @@ impl Repository { &mut self, manifest: &ViewManifest, ) -> Result { + let _review_boundary = self.review_evidence_lock()?; // 1. Structural integrity: declared state == fold of the log. manifest.verify()?; diff --git a/atomic-repository/src/triage/model.rs b/atomic-repository/src/triage/model.rs index 5ae7b4b6..0a288e4b 100644 --- a/atomic-repository/src/triage/model.rs +++ b/atomic-repository/src/triage/model.rs @@ -117,6 +117,10 @@ pub struct Summary { /// An intent reached by the candidate set (a "testsuite"). #[derive(Debug, Clone, Serialize, Deserialize)] pub struct IntentReport { + /// Current source status. Icebox criteria are historical, not satisfied by + /// candidate changes merely because a task once inspected the same file. + #[serde(default)] + pub status: String, pub id: String, pub why: Option, pub conforms: bool, diff --git a/atomic-repository/src/triage/report.rs b/atomic-repository/src/triage/report.rs index 2bb96f9f..5d03515e 100644 --- a/atomic-repository/src/triage/report.rs +++ b/atomic-repository/src/triage/report.rs @@ -101,6 +101,7 @@ pub fn build_report( let mut intent_to_changes: BTreeMap> = BTreeMap::new(); let mut ac_to_changes: BTreeMap> = BTreeMap::new(); let mut reached_any_intent: HashMap = HashMap::new(); + let mut set_aside_status: HashMap = HashMap::new(); let mut all_modified_files: HashSet = HashSet::new(); // Raw modified paths per candidate hash (for the actionable orphan message). let mut change_raw_paths: HashMap> = HashMap::new(); @@ -168,36 +169,37 @@ pub fn build_report( .filter(|entity| paths.contains(&entity.file)) .map(|entity| format!("{}#{}", entity.file, entity.name)) .collect(); - let mut covered = false; for file_id in &modifies { let Ok(fsub) = repo.vault_kg_neighbors(file_id, 1) else { continue; }; for e in &fsub.edges { if e.to_id == *file_id && kind_is(&e.kind, P::Touches) { - covered = true; touching_tasks.insert(e.from_id.clone()); } } } - // Coverage: no files → unknown; else covered iff some file is touched. - let coverage = if modifies.is_empty() { - "unknown" - } else if covered { - "covered" - } else { - "uncovered" - } - .to_string(); - // Second hop: each task's parent intent (HAS_TASK) and satisfied ACs. let mut reached = false; for task in &touching_tasks { let tsub = repo.vault_kg_neighbors(task, 1)?; for e in &tsub.edges { if e.to_id == *task && kind_is(&e.kind, P::HasTask) { - reached = true; + let inactive = + *set_aside_status + .entry(e.from_id.clone()) + .or_insert_with(|| { + iri::parse_intent(&e.from_id) + .ok() + .and_then(|(_, uid)| load_intent_node(repo, &uid).ok()) + .is_some_and(|node| node.status == "icebox") + }); + // Keep terminal intents in the report for authenticated + // disposition review, but never use them as active coverage. + if !inactive { + reached = true; + } intent_to_changes .entry(e.from_id.clone()) .or_default() @@ -212,6 +214,14 @@ pub fn build_report( } } reached_any_intent.insert(full.clone(), reached); + let coverage = if modifies.is_empty() { + "unknown" + } else if reached { + "covered" + } else { + "uncovered" + } + .to_string(); entities.sort(); entities.dedup(); @@ -415,10 +425,14 @@ pub fn build_report( .map_err(|e| RepositoryError::InvalidOperation { message: e.to_string(), })?; - let satisfied_by: Vec = ac_to_changes - .get(&ac_kg) - .map(|s| s.iter().cloned().collect()) - .unwrap_or_default(); + let satisfied_by: Vec = if node.status == "icebox" { + Vec::new() + } else { + ac_to_changes + .get(&ac_kg) + .map(|s| s.iter().cloned().collect()) + .unwrap_or_default() + }; let is_met = ac.ac_status == "met"; let judgment_required = !satisfied_by.is_empty() && !is_met; @@ -481,7 +495,10 @@ pub fn build_report( // baseline. Among this intent's ACs, if any carries a // view-scoped verification whose LATEST such record failed, the // view baseline is red. Deduped to one finding per intent. - if let Some(kind) = failing_view_verification(&node) { + if let Some(kind) = (node.status != "icebox") + .then(|| failing_view_verification(&node)) + .flatten() + { findings.push( Finding::new( F_VIEW_VERIFY_FAIL, @@ -502,7 +519,7 @@ pub fn build_report( // Task facts for the walkthrough: intent iteration order is a // BTreeMap key walk and tasks keep their directive order, so // this collection is deterministic. - for t in &node.has_task { + for t in node.has_task.iter().filter(|_| node.status != "icebox") { task_facts.push(TaskFact { id: t.id.clone(), text: t.text.clone(), @@ -515,6 +532,7 @@ pub fn build_report( report.results.iter().map(|v| v.message.clone()).collect(); intent_reports.push(IntentReport { + status: node.status.clone(), id: intent_kg_id.clone(), why: node.why.clone(), conforms: report.conforms, @@ -537,6 +555,7 @@ pub fn build_report( .with_remedy("ensure the intent exists in the vault and re-run"), ); intent_reports.push(IntentReport { + status: "unknown".into(), id: intent_kg_id.clone(), why: None, conforms: false, @@ -621,6 +640,9 @@ pub fn build_report( // targets, so the overlap is a direct set intersection. let mut scope_breaches: HashSet<(String, String, String)> = HashSet::new(); for intent_kg_id in intent_to_changes.keys() { + if set_aside_status.get(intent_kg_id).copied().unwrap_or(false) { + continue; // Historical scope is not an active delivery constraint. + } let Ok(isub) = repo.vault_kg_neighbors(intent_kg_id, 1) else { continue; }; @@ -718,6 +740,12 @@ pub fn build_report( Some(&did_provider), ) { Ok(verdict) => { + for approval in &verdict.retrospective_reviews { + findings.push(Finding::new( + F_PUBLICATION_GATE, SEV_INFO, approval.change.clone(), + format!("present-day retrospective review {} covers session {}; original session attestation remains absent", approval.review_hash, approval.session), + ).with_remedy("inspect the signed subject with atomic triage publication-review inspect --graph; ordinary intent/review findings remain enforced")); + } for blocker in &verdict.blocks { findings.push( Finding::new( @@ -736,7 +764,7 @@ pub fn build_report( Err(error) => { findings.push(Finding::new( F_PUBLICATION_GATE, - SEV_WARN, + SEV_BLOCK, "publication-gate".to_string(), format!("gate evaluation failed (surface this to review): {error}"), )); @@ -757,11 +785,13 @@ pub fn build_report( // 9. Summary counts. let criteria_met = intent_reports .iter() + .filter(|i| i.status != "icebox") .flat_map(|i| &i.criteria) .filter(|c| c.status == "met") .count(); let criteria_unmet = intent_reports .iter() + .filter(|i| i.status != "icebox") .flat_map(|i| &i.criteria) .filter(|c| c.status != "met") .count(); @@ -1997,6 +2027,13 @@ Edit bar. /// `a.txt`) is optionally covered by a review intent R. `review` is /// `(review_author, review_done)`. Target is the shared `dev` view. fn review_gate_report(review: Option<(&str, bool)>) -> (TriageReport, String) { + review_gate_report_with_status(review, "in-progress") + } + + fn review_gate_report_with_status( + review: Option<(&str, bool)>, + status: &str, + ) -> (TriageReport, String) { let temp = TempDir::new().unwrap(); let mut repo = Repository::init(temp.path()).unwrap(); repo.init_vault().unwrap(); @@ -2028,7 +2065,7 @@ Edit a.txt. &repo, &a.intent_file, body_a, - &[("attributedTo", WORK_AUTHOR), ("status", "in-progress")], + &[("attributedTo", WORK_AUTHOR), ("status", status)], ); let a_node_id = iri::mint_intent(&repo.project_id().unwrap(), &a.uid).unwrap(); @@ -2163,6 +2200,39 @@ Reviewed A independently. assert!(f[0].message.contains("self-authored or not yet done")); } + #[test] + fn set_aside_history_is_not_candidate_satisfaction_or_active_coverage() { + let (report, id) = review_gate_report_with_status(Some(("did:atomic:bob", true)), "icebox"); + let intent = report + .intents + .iter() + .find(|intent| intent.id == id) + .unwrap(); + assert_eq!(intent.status, "icebox"); + assert!(intent + .criteria + .iter() + .all(|ac| ac.satisfied_by.is_empty() && !ac.judgment_required)); + assert_eq!(report.summary.criteria_unmet, 0); + assert!( + report.findings.iter().any(|f| f.code == F_ORPHAN_CHANGE), + "Archival decisions cannot cover actual code changes" + ); + assert!( + report + .findings + .iter() + .any(|f| f.code == F_GATE_VIOLATION && f.focus == id), + "Missing proof is not waived for inactive documents" + ); + } + + #[test] + fn set_aside_status_alone_does_not_waive_independent_review() { + let (report, id) = review_gate_report_with_status(None, "icebox"); + assert_eq!(unreviewed_findings(&report, &id).len(), 1); + } + // ── build_walkthrough (pure projection) ─────────────────────────────── fn tf(id: &str, text: &str, touches: &[&str], satisfies: &[&str]) -> TaskFact { diff --git a/atomic-repository/tests/it/intent_graph.rs b/atomic-repository/tests/it/intent_graph.rs index 374f5cf0..1c0b2d29 100644 --- a/atomic-repository/tests/it/intent_graph.rs +++ b/atomic-repository/tests/it/intent_graph.rs @@ -174,6 +174,143 @@ fn authoritative_turn_path_seeds_changes_without_requiring_shortcuts() { assert_eq!(graph.dependency_changes, vec![dependency]); } +fn review_fixture() -> (WorkflowSnapshot, String, String, String) { + let (mut snapshot, root, _, _, unrelated) = fixture(); + let (project, _) = iri::parse_intent(&root).unwrap(); + let reviewer_intent = iri::mint_intent(&project, "01ARZ3NDEKTSV4RRFFQ69G5FAX").unwrap(); + let reviewed_change = iri::mint_change(&Hash::of(b"reviewed but not implemented by root")); + for (id, class) in [ + (reviewer_intent.as_str(), C::ReviewIntent), + (reviewed_change.as_str(), C::Change), + ("urn:review:one", C::PublicationReview), + ("urn:subject:one", C::ReviewSubject), + ("urn:observation:one", C::IntentObservation), + ("urn:judgment:one", C::CriterionJudgment), + ("urn:verification:one", C::VerificationRecord), + ("urn:evaluation:one", C::ReviewEvaluation), + ("urn:finding:review", C::ReviewFinding), + ("urn:review:unrelated", C::PublicationReview), + ("urn:subject:unrelated", C::ReviewSubject), + ("urn:observation:unrelated", C::IntentObservation), + ] { + snapshot.nodes.push(KgNode::new(id, class, id, "fixture")); + } + for (from, to, p) in [ + (reviewer_intent.as_str(), root.as_str(), P::Reviews), + ( + "urn:review:one", + reviewer_intent.as_str(), + P::HasReviewIntent, + ), + ("urn:review:one", "urn:subject:one", P::ReviewsClosure), + ("urn:subject:one", root.as_str(), P::IncludesIntent), + ( + "urn:subject:one", + reviewed_change.as_str(), + P::ReviewsChange, + ), + ( + reviewed_change.as_str(), + "urn:observation:one", + P::HasReviewEvidence, + ), + ("urn:observation:one", root.as_str(), P::ObservedIntent), + ("urn:subject:one", "urn:observation:one", P::SubjectEvidence), + ( + "urn:subject:unrelated", + "urn:observation:unrelated", + P::SubjectEvidence, + ), + ( + reviewed_change.as_str(), + "urn:observation:unrelated", + P::HasReviewEvidence, + ), + // A common dependency/change must not route into another review scope. + ( + "urn:subject:unrelated", + reviewed_change.as_str(), + P::ReviewsChange, + ), + ( + "urn:observation:one", + "urn:provenance:one", + P::EvidenceSource, + ), + ("urn:observation:one", "urn:turn:one", P::EvidenceTurn), + ("urn:review:one", "urn:judgment:one", P::HasJudgment), + ("urn:judgment:one", "urn:ac:one", P::JudgesCriterion), + ("urn:judgment:one", "urn:verification:one", P::SupportedBy), + ("urn:ac:one", "urn:verification:one", P::HasVerification), + ("urn:evaluation:one", "urn:review:one", P::EvaluatesReview), + ("urn:finding:review", "urn:evaluation:one", P::AboutResource), + ("urn:review:one", "urn:author:shared", P::SignedBy), + ("urn:review:unrelated", "urn:author:shared", P::SignedBy), + ( + "urn:review:unrelated", + "urn:subject:unrelated", + P::ReviewsClosure, + ), + ( + "urn:subject:unrelated", + unrelated.as_str(), + P::ReviewsChange, + ), + ] { + snapshot.edges.push(KgEdge::new(from, to, p)); + } + (snapshot, root, reviewer_intent, reviewed_change) +} + +#[test] +fn review_evidence_extends_intent_selection_without_shared_resource_expansion() { + let (snapshot, root, reviewer, reviewed_change) = review_fixture(); + for root in [&root, &reviewer] { + let graph = IntentGraph::from_snapshot(&snapshot, root, 1000).unwrap(); + for id in [ + "urn:review:one", + "urn:subject:one", + "urn:observation:one", + "urn:judgment:one", + "urn:verification:one", + "urn:evaluation:one", + "urn:finding:review", + ] { + assert!(graph.nodes.iter().any(|node| node.id == id), "missing {id}"); + } + assert_eq!(graph.reviewed_changes, vec![reviewed_change.clone()]); + assert!(!graph.implementing_changes.contains(&reviewed_change)); + assert!(!graph + .nodes + .iter() + .any(|node| node.id == "urn:review:unrelated" + || node.id == "urn:subject:unrelated" + || node.id == "urn:turn:two")); + assert!(graph.missing_resources.is_empty()); + } +} + +#[test] +fn review_selection_keeps_deterministic_caps_and_missing_evidence_diagnostics() { + let (mut snapshot, root, _, _) = review_fixture(); + let graph = IntentGraph::from_snapshot(&snapshot, &root, 12).unwrap(); + assert!(graph.truncated); + snapshot.nodes.reverse(); + snapshot.edges.reverse(); + let reverse = IntentGraph::from_snapshot(&snapshot, &root, 12).unwrap(); + assert_eq!( + serde_json::to_value(graph).unwrap(), + serde_json::to_value(reverse).unwrap() + ); + snapshot + .nodes + .retain(|node| node.id != "urn:provenance:one"); + let graph = IntentGraph::from_snapshot(&snapshot, &root, 1000).unwrap(); + assert!(graph + .missing_resources + .contains(&"urn:provenance:one".into())); +} + fn recording_fixture() -> (WorkflowSnapshot, String, String, String, String, String) { let (mut snapshot, root, change, dependency, unrelated) = fixture(); snapshot diff --git a/atomic-shacl/Cargo.toml b/atomic-shacl/Cargo.toml index 9ee9f6e1..d427b90a 100644 --- a/atomic-shacl/Cargo.toml +++ b/atomic-shacl/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "atomic-shacl" -description = "CLI-only RDF snapshot adaptation and PurRDF SHACL validation" +description = "Versioned RDF snapshot adaptation and PurRDF SHACL validation (Rust 1.98)" version.workspace = true edition.workspace = true license.workspace = true diff --git a/atomic-shacl/src/adapter.rs b/atomic-shacl/src/adapter.rs index 344f2d52..79eefe3c 100644 --- a/atomic-shacl/src/adapter.rs +++ b/atomic-shacl/src/adapter.rs @@ -62,9 +62,59 @@ pub fn snapshot_ntriples(nodes: &[KgNode], edges: &[KgEdge]) -> Result String { + let change = Hash::of(b"reviewed change").to_base32(); + let artifact = Hash::of(b"review artifact").to_base32(); + format!( + r#" + . + . + . + . + . + . + . + . + . + "pinned-state" . + "urn:atomic:view-set:pinned-set" . + . + . + . + "done" . + . + . + . + . + . + . + . + . + . + . + . + . + . + . + . + . + . + . + . + . + "met" . + "test artifact" . + "independent fixture" . + "manual" . + . + "manual" . + . + "pass" . + "pinned-state" . + "urn:atomic:view-set:pinned-set" . + . + "managed" . + . +"# + ) +} + +fn report(data: &str) -> atomic_shacl::ValidationOutput { + validate_ntriples( + data, + "fixture", + &ValidationRequest { + profile: Profile::Review, + ..Default::default() + }, + ) + .unwrap() +} + +#[test] +fn empty_or_partial_review_dataset_cannot_pass_vacuously() { + assert!(!report("").conforms); + assert!( + !report( + &dataset() + .lines() + .filter(|line| !line.contains("evaluatesReview")) + .collect::>() + .join("\n") + ) + .conforms + ); +} + +#[test] +fn review_policy_is_executable_shacl_not_a_rust_status_check() { + let data = dataset(); + let good = report(&data); + assert!(good.conforms, "{:#?}", good.results); + for bad in [ + data.replace("\"done\"", "\"in_progress\""), + data.replace("\"met\"", "\"unmet\""), + data.replace("\"pass\"", "\"fail\""), + data.replace("", ""), + data.replace( + "#observedState> \"pinned-state\"", + "#observedState> \"unrelated-state\"", + ), + data.lines() + .filter(|line| !line.contains("declaresImplementation")) + .collect::>() + .join("\n"), + ] { + assert!( + !report(&bad).conforms, + "accepted incomplete or unauthorized review" + ); + } +} + +#[test] +fn review_evidence_paths_replace_plan_shortcuts_and_reject_ambiguity() { + let change = Hash::of(b"reviewed change").to_base32(); + let provenance = Hash::of(b"retained provenance").to_base32(); + let data = dataset() + .lines() + .filter(|line| !line.contains("declaresImplementation")) + .collect::>() + .join("\n"); + let evidence = format!( + r#" + . + . + . + . + "node-4" . + "REAC::lee::22" . + "attested-receipt" . + "work" . + "resolved" . + . + . + . + . + . + . + . +"# + ); + let data = format!("{data}\n{evidence}"); + let good = report(&data); + assert!(good.conforms, "{:#?}", good.results); + for bad in [ + data.replace("\"resolved\"", "\"ambiguous\""), + data.replace("#observationRole> \"work\"", "#observationRole> \"review-context\""), + data.replace("#evidenceTurn> ", "#evidenceTurn> "), + data.lines().filter(|line| !line.contains("#sourceNode>")).collect::>().join("\n"), + format!("{data}\n ."), + ] { + assert!(!report(&bad).conforms); + } +} diff --git a/docs/README.md b/docs/README.md index 6d648d93..ead1c9c9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,6 +12,7 @@ Welcome to the Atomic VCS documentation. This directory contains comprehensive d | [Shim Operating Guide](./shim-operating-guide.md) | Git shim enable/disable, vault projection policy, trust, recovery, privacy, and observability (CB-13C; exercised against the shipping CLI) | Users, Agents | | [Stack Walkthrough](./walkthrough-stacks.md) | Hands-on tutorial for stacks, apply, and stash | Users, Contributors | | [Attestation Design](./attestation-design.md) | Graph-level audit nodes for AI cost, tokens, and compliance | Developers, Contributors | +| [Retrospective Publication Review](./retrospective-publication-review.md) | Exact-change signed review, SHACL policy, renewal, and publication boundaries | Reviewers, Contributors | | [Software Supply Chain Checks](./software-supply-chain.md) | The standards behind canonical bytes, proofs and signatures, and the CI jobs that hold them | Developers, Contributors | | [Intent Identity](./intent-identity.md) | ULID + `PROJECT::author::seq` intent identity and reference resolution | Users, Contributors | | [Intent Knowledge Graph](./intent-graph.md) | How intents become a queryable graph and the `atomic vault query` commands | Users, Contributors | diff --git a/docs/retrospective-publication-review.md b/docs/retrospective-publication-review.md new file mode 100644 index 00000000..ff3a302a --- /dev/null +++ b/docs/retrospective-publication-review.md @@ -0,0 +1,338 @@ +# SHACL-backed retrospective publication review + +This is an explicit native Atomic workflow for **present-day review of retained +evidence**. It does not manufacture an original session attestation, recover a +session MAC, alter a managed change, or grant reviewer trust automatically. + +## Signed scope and executable policy + +`atomic.publication-review.v2` pins: + +- stable project identity; +- full root change hashes and their complete dependency closure; +- original session identities and available provenance object hashes; +- source-pinned intent lifecycle observations and retained signed revision evidence; +- exact signed/source revisions and authenticated keys of work and review intents; +- source view, ancestor state pins, and effective change-set identity; +- ordered source-view logs, the full effective membership/dependency closure, + and complete signed intent/source documents in retained evidence; +- the executable ontology, shape content and validator version fingerprint. + +The review intent must explicitly `reviews` the covered work intents. A managed +change needs resolved source-backed intent observations or an exact, +evidence-bearing, signed `implementsChange` declaration from a work intent; +a shared filename is not implementation attribution. Observed intent evidence +cannot be excluded by such a declaration. No historical TypeScript intent is blanket-approved merely because +it touches files also used by a restored Rust implementation. + +Native code loads and authenticates canonical sources, checks signatures and +key bindings, and supplies current trust/freshness observations. The existing +canonical intent/schema gate remains enforced and its conformance observation is +distinct from cryptographic verification. New review policy is evaluated by the +existing PurRDF SHACL engine, using +`atomic-core/ontology/shapes/review-1.0.0.ttl`: + +- nonempty, complete exact-change subjects; +- completed review and met criteria with verification evidence; +- each required reviewer check passing at the **reviewed source state**; +- coverage of observed work intents and dependency closure; +- authenticated signing-key independence, current reviewer authority and freshness. + +An empty dataset fails the fixed evaluation target. Production validation rebuilds +the dataset from originals; callers cannot supply RDF `Verified` or `Trusted` +assertions as an authorization input. Different keys do not prove different +humans or meaningful review; substantive review remains the reviewer's duty. + +## Retained evidence has no live-view dependency + +V2 source view names and scopes are historical provenance labels, not resources +that must stay alive. Preparation captures each view's ordered own log, the +complete effective dependency closure, and the exact signed intent documents +with their source lift inputs. The outer review signature binds that bundle. +Validation recomputes each log Merkle and the membership SetId, checks canonical +dependency-index closure against immutable change objects, and authenticates +every retained intent revision/source/signature pin. It never substitutes an +unchecked `Verified` assertion or simply ignores a missing source view. + +Deleting a source view, changing its scope, reusing its name or advancing it or +an ancestor does not change the content already reviewed. The approval still +covers only its exact original change hashes; later changes do not acquire that +approval. A newly prepared review of an expanded context still needs verification +records for that new context. Current intent-source freshness, signing-key +independence, current reviewer trust/revocation and ordinary original-evidence +refusals remain policy requirements; this fix does not freeze or waive them. + +No permanent cleanup/review view is needed. Retained source documents and +membership are evidence inside the signed artifact, not another knowledge base +or a mutable workspace. Intent graph display summarizes these bundles rather +than duplicating full source documents into every graph node. + +Legacy v1 documents retain their exact serialization and content addresses. +They retain their original live-view semantics and never silently acquire v2 +snapshot authority. While the legacy view still exists, prepare/sign a v2 +replacement with explicit `--supersedes` links, verify it, then remove the old +workspace through normal native APIs. Old signed artifacts remain retained. + +## Operator flow + +Use a CLI built from this branch, not a previously installed `atomic` binary. +These new administrative commands currently use the local repository API. They +do not introduce new network RPC methods or bypass a daemon's database ownership; +if another process owns redb, use an isolated checkout/offline administration +window rather than opening a competing writer. RPC/agent-host orchestration is a +follow-up integration. + +1. Inspect the actual change closure and perform the content review and tests. + Use a separate reviewer execution and signing identity. Create a review intent + referencing the work intent(s); include passing `::verification` records pinned + to the source view's Merkle for each required kind. Also set each passing + review record's `ref=urn:atomic:view-set:FULL_SET_ID` using the effective SetId + shown by `atomic view show SOURCE`. Own-log Merkle alone cannot observe a + parent changing beneath a draft. Complete and sign the review + intent under that reviewer identity, without changing its definition afterward. +2. Ensure the review and work signer public keys resolve locally and that the + reviewer already has explicit authorization in the repository trust policy. + Revocation wins. Do not add trust simply to make a failing gate pass. +3. Prepare the exact subject, selecting the source view explicitly: + + ```sh + atomic triage publication-review prepare \ + --review REVIEW_INTENT_ID --view feature \ + --change FULL_CHANGE_HASH > prepared-review.json + ``` + + Repeat `--change` for multiple roots. The JSON contains `document` and base64 + `signingBytes` for external signing. Root hashes are never abbreviated. + Inspect the unsigned graph and blockers before proceeding (see below). +4. Sign and record locally with the explicitly selected reviewer key: + + ```sh + atomic triage publication-review sign \ + --file prepared-review.json --identity reviewer + ``` + + Or attach a standard Atomic Data Integrity proof externally over the prepared + bytes, then submit the signed document without any private-key handoff: + + ```sh + atomic triage publication-review record --file signed-review.json + ``` + +5. Inspect the current validation report and the connected intent graph: + + ```sh + atomic triage publication-review inspect + atomic intent graph REVIEW_INTENT_ID --html + atomic triage review feature --into dev --json + ``` + +6. Promote only after all applicable gates pass. The existing native insertion + interface is `atomic insert from-view feature --to-view dev`. Promotion retains + original change hashes; it does not create a surrogate squash change. + +Signed artifacts live at `.vault/publication-reviews//review.md` +as tracked attestation entries with a JSON body. That artifact is not an original +binary `.attest` sidecar and is never installed as one. Recording the artifact on +a separate review view avoids invalidating the source view's own review pin. +The review evidence connects to the existing intent graph. Its reference +projection is rebuildable over retained documents, not a second knowledge base. + +The `review` profile validates the present-day review claim. The existing +repository-wide `publication` diagnostic profile continues to describe original +capture coverage; a retrospective review does not rewrite those historical +facts or turn missing original evidence into an original-session signature. + +## Gate behavior and renewal + +### Findings feed the original intent + +Review is a feedback loop, not a terminal list of blockers. Before promotion, +put an actionable finding on the original work/review intent, leave the relevant +criterion unmet, correct the code, documentation or metadata, run its checks, +update evidence and re-attest the current revision, then prepare and validate +again. Reuse the same intent identities; do not create replacement/adoption +intents merely to sidestep an incomplete checklist. An actual post-promotion +defect instead needs a provenance-linked remediation. + +Do not confuse an approved review with an already executed merge. Insertion, +working-copy verification and deletion belong to explicit post-approval tasks; +they cannot also be preconditions for approving that same insertion. Leave those +tasks open until their operations actually succeed. A work intent with an open +execution task stays in progress; the separate content review may be completed. + +Only lifecycle observations of the exact selected review are `review-context`. +They remain source-verified evidence but do not require the review to review +itself. Other work still requires explicit coverage and key independence. +Incidental reference nodes do not fail the full-work conformance shape simply +because they are outside the selected scope; missing scope is reported once per +distinct intent/change, with its canonical identity in the finding's value. +Unsigned preview checks and genuine signer-authorization decisions are reported +separately from actionable content/metadata failures. Never turn a failed test +into a passing record, rewrite original signatures or grant trust automatically. + +### Active work versus terminal dispositions + +A single existing review may cover multiple relevant intents; a missing-review +count is a count of missing relationships, not a demand for that many new review +intents. Reconcile each original intent against actual source and verification. +Repair stale task/status/path metadata only when its work is evidenced. Preserve +dated execution claims as history rather than calling old runs new tests. + +When the product decision genuinely supersedes an old objective, its author may +attest a current `icebox` disposition with an explanation and retained originals. +The completed independent review must explicitly reference that intent. The +resolver pins it in `ReviewSubject.set_aside`, separate from `work`, and the +ontology projects `includesSetAside`, not active `includesIntent` coverage. +A reviewed change whose retained receipts observe that set-aside intent is +still complete review scope; only `includesIntent` can supply managed-change +coverage. +SHACL requires fresh, valid, canonically conforming source, the explicit completed +review and different authenticated signing keys for these dispositions too. It +does **not** assert that historical implementation goals hold in today's product. + +Setting `icebox` alone never clears canonical or independent-review failures. +Inactive documents remain visible in triage with their source status, but their +criteria are historical: not counted as current met/unmet criteria, not joined +to candidates as satisfaction, and not used as current walkthrough motivation +or active code coverage. A real code candidate with only inactive task links +remains orphaned. Terminal dispositions also cannot supply native managed-change +coverage. The CLI labels their historical criteria without green implementation +checkmarks, preserving evidence without pretending a retired goal shipped. + +The optional empty `set_aside` field is omitted canonically, so retained older +documents keep their original content addresses. A changed executable ontology/ +shape profile still requires a fresh, explicitly superseding approval; original +signed artifacts remain retained. + +The repository publication gate uses a valid review **only when the original +same-session attestation is absent**. It retains the ordinary envelope, provenance, +ledger, incomplete-session, original-signature and signer-trust checks. A corrupt, +unsigned, unverifiable or untrusted existing original cannot be replaced by a +good retrospective review. Strict discovery includes unindexed originals and +refuses registered missing/corrupt evidence instead of treating it as absent. + +The verdict exposes exact retrospective artifact/change/session references. +Triage reports those as informational findings, without clearing unrelated intent, +scope, content-review or historical-attribution blockers. Evaluation errors block +shared-target readiness rather than degrading to a warning. + +Stale reviews remain retained. For a genuine renewal, complete and freshly sign +the new review intent, prepare the same original project/root/change/session +scope with `--supersedes OLD_ARTIFACT_HASH`, and sign the new document. Supersession +is authenticated and transitive; missing predecessors, changed scope and corrupt +predecessor signatures fail closed. Old artifacts are inspectable, not overwritten +or deleted. A separate invalid active sibling is not hidden by a valid approval. + +Final revalidation and the insertion batch share the repository-common operation +boundary. Participating vault, view/membership and evidence writers contend on it. +Metadata writes can alias an existing same-thread boundary without converting a +non-reentrant operation into a reentrant one. The already-checked +batch does not invalidate itself by rechecking its old ancestor pin after inserting +the first dependency. A failed preflight writes no membership. This is not a new +claim that the existing multi-change insertion implementation is globally ACID +against every storage failure, nor protection against privileged out-of-band +database/config/file tampering. Source/ancestor advances after promotion can make +the historical approval stale for future reuse; its signed historical meaning +does not change. + +## Compatibility and limits + +- `atomic-repository` has an opt-in `review-shacl` feature, requiring Rust 1.98 + through the existing validator. The CLI enables it. Default library consumers + retain their lower MSRV and cannot accept retrospective exceptions without it. +- No automatic trust changes, historical signatures, owner-exclusion overrides, + daemon fallback writers, or agent/model-independence claims are introduced. +- Admission is bounded: 1 MiB signed documents, 64 roots, 4096 closure changes, + 256 work intents/ancestor views/supersession ancestors, and bounded strict + sidecar inventories, with at most 4096 retained review artifacts per inventory. + Exceeding a budget is an error, not partial conformance. +- Signed objects require their original source revisions and public keys to be + available. Unavailable evidence blocks validation; a signature is not proof + that all historical execution evidence exists. +- Existing file/task-overlap triage attribution and independent work-review + findings remain in force. This feature alone is not a declaration that live + Reactor promotion is ready. No live Reactor data is used as a test fixture. + +## Review ontology in the existing intent graph + +The review module is versioned independently at +`https://atomic.dev/ns/review/1.0.0` in +`atomic-core/ontology/review-1.0.0.ttl`. It imports the workflow ontology and +reuses its intents, changes, sessions, turns, identities and attestations. +Both modules are bundled locally; validation does not fetch ontology imports. +`ReviewSubject`, `IntentObservation`, `ReviewEvidence`, `CriterionJudgment` +and `ReviewFinding` describe scope, evidence, judgments and blockers. SHACL +defines readiness, not the OWL domain/range declarations. + +Review subjects, observations, judgments, verification records and findings are +nodes and relationships in **`atomic intent graph`**, using its existing +renderer, output controls and text/JSON/DOT/HTML exports. Stored review documents +appear automatically as reference topology connected to the work and review +intents. Those references are explicitly **not revalidated approval verdicts**. +Their presence never grants authority or invents implementation attribution. + +After preparing an unsigned document, inspect it **before signing** using the +same command with an optional review context: + +```sh +atomic intent graph REVIEW_INTENT_ID --review-file prepared.json +atomic intent graph WORK_INTENT_ID --review-file prepared.json --json +atomic intent graph REVIEW_INTENT_ID --review-file prepared.json --dot > review.dot +atomic intent graph REVIEW_INTENT_ID --review-file prepared.json --html +atomic intent graph REVIEW_INTENT_ID --review-file prepared.json --html --no-open --output review.html +``` + +All formats use the same intent-rooted selection. JSON includes canonical nodes +and edges; the review evaluation node carries the complete SHACL report, and +findings also appear as graph nodes. HTML retains the existing node inspector +and browser opening behavior. Reviewed changes are labeled separately from +implementation and recording evidence. Shared sessions, identities and files +remain traversal boundaries; `--max-nodes` and truncation diagnostics still apply. + +The existing workflow snapshot service endpoint accepts the bounded canonical +review document, rebuilds/authenticates its evidence, evaluates SHACL against +the **exact bounded subject**, and connects the resulting nodes to the intent +graph for display. It does not validate the combined display graph as a review +approval. A document-hash acknowledgement prevents an older Reactor from silently +ignoring the preview request. Unsupported validators fail closed, with no local +database fallback or trust changes. No separate graph command, renderer or +cross-project knowledge base is introduced. + +An unsigned review has a failed signature check and no review `signedBy` edge. +Existing original attestations elsewhere in the intent graph retain their own +signer edges. Preview never stores evidence, +grants trust or authorizes publication. An invalid supplied signature is still +an error, not treated as unsigned. Stale signed source documents can be shown +in preview with failed freshness, but cannot pass the publication gate. + +The review resolver **does not read `plan_id`** from either provenance or the +session ledger. Null or conflicting legacy values do not create missing-plan +findings, `hasPlan`, or `implements` assertions. It recognizes exact lifecycle +receipt lines (create/update/attest/verify) paired with matching CLI commands +in retained execution nodes. These remain **recorded observations**, not proof +that a command ran successfully or that the intent governed the work. A CLI +validation result without an exact intent receipt is not guessed from nearby +text. Other evidence formats require explicit adapters, not shell execution. + +Each observation pins the full provenance hash, source node ID, exact receipt +reference, session ID, matching ledger turn numbers, resolution and diagnostics. +The provenance must explicitly explain the change and a turn must pin that +same provenance hash. Missing or multiple turn bindings remain unresolved or +ambiguous; no filename, timestamp or view-context heuristic substitutes for +them. Parsed observations and verified retained revision hashes are included +in the signed subject and re-resolved on use. + +A retained signed intent document is cryptographically verified separately +from current-source freshness. `retained-not-current` means its signature is +valid but it does not describe the current lift. It is visible historical +evidence, **not absent evidence and not authorization for current work**. Work +selected for approval still requires a fresh, independently authenticated +revision; automatic historical-revision selection is not implemented. + +The review profile validates evidence paths directly, including explicit +inclusion/review of observed intents, source/turn consistency, exact closure, +criterion verification, freshness, key independence and signer trust. Its +shapes do not inherit the legacy projection profile's governing-plan shortcut +rule. Ordinary projection/publication profiles and original-session signature +requirements are unchanged. A receipt is not automatically a criterion +judgment; reviewer verification must still cover the exact source context. diff --git a/libatomic/proto/atomic/services/knowledge/knowledge_messages.proto b/libatomic/proto/atomic/services/knowledge/knowledge_messages.proto index 6bd5b9fa..6cc3f473 100644 --- a/libatomic/proto/atomic/services/knowledge/knowledge_messages.proto +++ b/libatomic/proto/atomic/services/knowledge/knowledge_messages.proto @@ -30,8 +30,13 @@ message GetProjectIdentityResponse { } message GetWorkflowSnapshotRequest { RepositoryRef repository = 1; + // Optional canonical publication-review document for a read-only intent-graph + // preview. The server rebuilds/authenticates evidence; caller RDF is not used. + optional bytes review_document = 2; } -// One consistent, repository-wide asserted snapshot. SHACL runs client-side. +// The existing asserted workflow graph. Ordinary SHACL profiles run client-side. +// With review_document, authenticated preview evidence and the bounded review's +// validation report are connected as graph nodes; the display is not approval. message GetWorkflowSnapshotResponse { uint32 api_version = 1; uint32 generation = 2; @@ -39,6 +44,10 @@ message GetWorkflowSnapshotResponse { string identity = 4; repeated KGNode nodes = 5; repeated KGEdge edges = 6; + // Echo of the exact document artifact hash, only after preview resolution. + // Clients must require this when requesting review_document: old servers must + // not silently ignore a preview request and return ordinary graph success. + optional string review_preview_identity = 7; } diff --git a/libatomic/src/daemon/services_agent.rs b/libatomic/src/daemon/services_agent.rs index 52ff50d9..7dec9cdc 100644 --- a/libatomic/src/daemon/services_agent.rs +++ b/libatomic/src/daemon/services_agent.rs @@ -3839,12 +3839,20 @@ impl knowledge_service_server::KnowledgeService for KnowledgeImpl { let response = tokio::task::spawn_blocking(move || { let _gate = gate; let repo = handle.repository_readonly()?; - let snapshot = repo.workflow_snapshot().map_err(repository_error)?; + let (snapshot, review_preview_identity) = if let Some(bytes) = request.review_document { + let (snapshot, identity) = repo + .workflow_snapshot_with_review(&bytes) + .map_err(repository_error)?; + (snapshot, Some(identity)) + } else { + (repo.workflow_snapshot().map_err(repository_error)?, None) + }; Ok::<_, Status>(GetWorkflowSnapshotResponse { api_version: 1, generation: snapshot.generation, ontology_version: snapshot.ontology_version.to_owned(), identity: snapshot.identity, + review_preview_identity, nodes: snapshot .nodes .into_iter() diff --git a/libatomic/tests/signer_refresh.rs b/libatomic/tests/signer_refresh.rs index 64711363..0477c731 100644 --- a/libatomic/tests/signer_refresh.rs +++ b/libatomic/tests/signer_refresh.rs @@ -167,11 +167,23 @@ async fn reindex_rpc_refreshes_signers_with_url_bound_client_credentials() { server.join().unwrap(); let snapshot = service .get_workflow_snapshot(Request::new(GetWorkflowSnapshotRequest { - repository: Some(reference), + review_document: None, + repository: Some(reference.clone()), })) .await .unwrap() .into_inner(); + assert!(snapshot.review_preview_identity.is_none()); + assert!( + service + .get_workflow_snapshot(Request::new(GetWorkflowSnapshotRequest { + repository: Some(reference), + review_document: Some(b"{}".to_vec()), + })) + .await + .is_err(), + "unresolved review documents must not silently return ordinary snapshot success" + ); assert!(snapshot.edges.iter().any(|edge| { edge.source == atomic_core::kg::iri::mint_attestation(&hash) && edge.relation == atomic_core::kg::ontology::Predicate::VerificationResult.iri()