From 2eab9c69ac00862bedcfb5e07f7c8962d3b5abd8 Mon Sep 17 00:00:00 2001 From: Lee Faus Date: Fri, 13 Nov 2026 08:06:48 -0400 Subject: [PATCH 1/2] fix the review process with new ontology --- Cargo.lock | 1 + atomic-canonical/src/lib.rs | 1 + atomic-canonical/src/publication_review.rs | 195 ++++++ atomic-canonical/src/vocab.rs | 6 +- atomic-cli/Cargo.toml | 2 +- atomic-cli/src/commands/intent/graph.rs | 53 +- atomic-cli/src/commands/query/mod.rs | 9 + atomic-cli/src/commands/rpc.rs | 57 +- atomic-cli/src/commands/triage/mod.rs | 5 + atomic-cli/src/commands/triage/output.rs | 64 +- .../src/commands/triage/publication_review.rs | 230 +++++++ atomic-core/ontology/review-1.0.0.ttl | 61 ++ atomic-core/ontology/shapes/review-1.0.0.ttl | 217 +++++++ atomic-core/src/kg/ontology.rs | 45 +- atomic-core/tests/kg_ontology.rs | 30 + atomic-repository/Cargo.toml | 4 + atomic-repository/src/apply/types.rs | 4 +- atomic-repository/src/intent_graph.rs | 109 +++- atomic-repository/src/repository/changes.rs | 6 + atomic-repository/src/repository/history.rs | 2 + atomic-repository/src/repository/insert.rs | 10 +- atomic-repository/src/repository/locks.rs | 25 + atomic-repository/src/repository/mod.rs | 1 + .../src/repository/provenance_gate.rs | 46 +- .../repository/publication_review/artifact.rs | 65 ++ .../repository/publication_review/graph.rs | 468 ++++++++++++++ .../src/repository/publication_review/mod.rs | 591 ++++++++++++++++++ .../publication_review/observations.rs | 225 +++++++ .../publication_review/references.rs | 198 ++++++ .../repository/publication_review/snapshot.rs | 238 +++++++ .../repository/publication_review/subject.rs | 262 ++++++++ .../repository/publication_review/tests.rs | 445 +++++++++++++ .../publication_review/tests/boundaries.rs | 355 +++++++++++ .../publication_review/tests/observations.rs | 563 +++++++++++++++++ .../publication_review/tests/snapshot.rs | 131 ++++ atomic-repository/src/repository/vault.rs | 30 + .../src/repository/vault_triples.rs | 36 ++ atomic-repository/src/repository/views.rs | 8 + atomic-repository/src/triage/model.rs | 4 + atomic-repository/src/triage/report.rs | 112 +++- atomic-repository/tests/it/intent_graph.rs | 137 ++++ atomic-shacl/Cargo.toml | 2 +- atomic-shacl/src/adapter.rs | 50 ++ atomic-shacl/src/lib.rs | 13 + atomic-shacl/tests/publication_review.rs | 157 +++++ docs/README.md | 1 + docs/retrospective-publication-review.md | 335 ++++++++++ .../knowledge/knowledge_messages.proto | 11 +- libatomic/src/daemon/services_agent.rs | 10 +- libatomic/tests/signer_refresh.rs | 14 +- 50 files changed, 5592 insertions(+), 52 deletions(-) create mode 100644 atomic-canonical/src/publication_review.rs create mode 100644 atomic-cli/src/commands/triage/publication_review.rs create mode 100644 atomic-core/ontology/review-1.0.0.ttl create mode 100644 atomic-core/ontology/shapes/review-1.0.0.ttl create mode 100644 atomic-repository/src/repository/publication_review/artifact.rs create mode 100644 atomic-repository/src/repository/publication_review/graph.rs create mode 100644 atomic-repository/src/repository/publication_review/mod.rs create mode 100644 atomic-repository/src/repository/publication_review/observations.rs create mode 100644 atomic-repository/src/repository/publication_review/references.rs create mode 100644 atomic-repository/src/repository/publication_review/snapshot.rs create mode 100644 atomic-repository/src/repository/publication_review/subject.rs create mode 100644 atomic-repository/src/repository/publication_review/tests.rs create mode 100644 atomic-repository/src/repository/publication_review/tests/boundaries.rs create mode 100644 atomic-repository/src/repository/publication_review/tests/observations.rs create mode 100644 atomic-repository/src/repository/publication_review/tests/snapshot.rs create mode 100644 atomic-shacl/tests/publication_review.rs create mode 100644 docs/retrospective-publication-review.md 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..3d51c6df --- /dev/null +++ b/atomic-core/ontology/shapes/review-1.0.0.ttl @@ -0,0 +1,217 @@ +@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 } + } + """ + ] ; + sh:sparql [ + sh:message "Include the observed work intent in the original review intent's reviews references, 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 . ?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..665d7e51 --- /dev/null +++ b/atomic-repository/src/repository/publication_review/tests.rs @@ -0,0 +1,445 @@ +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 { + serde_json::from_value(json!({ + "id":"fixture-receipt", "kind":"execution", "timestamp":0, + "summary":"Retained lifecycle receipt", "classified":false, + "detail":json!({"command":format!("atomic intent attest {work}"), + "output_summary":format!("Attested intent: {work}\n")}).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 { + 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 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(&work)) + .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, + } + } + 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..26456fbd --- /dev/null +++ b/atomic-repository/src/repository/publication_review/tests/observations.rs @@ -0,0 +1,563 @@ +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 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..f735f4f9 --- /dev/null +++ b/docs/retrospective-publication-review.md @@ -0,0 +1,335 @@ +# 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. +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() From e0b0d17725277bfd737c31fe4fa7d39278438d7c Mon Sep 17 00:00:00 2001 From: Vincent Date: Sun, 15 Nov 2026 13:04:37 -0500 Subject: [PATCH 2/2] fix: accept reviewed set-aside intents as complete review scope (#338) The subject scope-completeness rule only recognized includesIntent, but the resolver pins icebox intents under includesSetAside. A change whose retained receipts observe an intent that was later set aside could never pass validation, even when the review intent explicitly reviews it. Accept either relation for scope completeness. Managed-change coverage still requires includesIntent, so a set-aside intent cannot stand in as implementation evidence (covered by the existing retired_intent_cannot_supply_managed_change_coverage test). Note: the shapes file participates in profile_hash, so previously signed reviews will read as stale and need a superseding signature. --- atomic-core/ontology/shapes/review-1.0.0.ttl | 11 +++- .../repository/publication_review/tests.rs | 62 ++++++++++++++----- .../publication_review/tests/observations.rs | 57 +++++++++++++++++ docs/retrospective-publication-review.md | 3 + 4 files changed, 117 insertions(+), 16 deletions(-) diff --git a/atomic-core/ontology/shapes/review-1.0.0.ttl b/atomic-core/ontology/shapes/review-1.0.0.ttl index 3d51c6df..86884c81 100644 --- a/atomic-core/ontology/shapes/review-1.0.0.ttl +++ b/atomic-core/ontology/shapes/review-1.0.0.ttl @@ -76,13 +76,20 @@ shape:Subject a sh:NodeShape ; } """ ] ; + # 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 work intent in the original review intent's reviews references, then re-run review. Selected-review lifecycle receipts are context, not work requiring self-review." ; + 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 . ?review atomic:reviewsClosure $this ; atomic:reviewIntent ?intent . ?intent atomic:reviews ?value } + FILTER NOT EXISTS { + { $this atomic:includesIntent ?value } UNION { $this atomic:includesSetAside ?value } + ?review atomic:reviewsClosure $this ; atomic:reviewIntent ?intent . ?intent atomic:reviews ?value + } } """ ] ; diff --git a/atomic-repository/src/repository/publication_review/tests.rs b/atomic-repository/src/repository/publication_review/tests.rs index 665d7e51..9e7d81fe 100644 --- a/atomic-repository/src/repository/publication_review/tests.rs +++ b/atomic-repository/src/repository/publication_review/tests.rs @@ -81,11 +81,25 @@ fn signed_intent( } 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":format!("atomic intent attest {work}"), - "output_summary":format!("Attested intent: {work}\n")}).to_string() + "detail":json!({"command":command,"output_summary":output}).to_string() })) .unwrap() } @@ -105,6 +119,17 @@ fn sign_intent(repo: &Repository, id: &str, signer: &Identity, pair: &KeyPair) { 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(); @@ -120,6 +145,8 @@ impl Fixture { 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(); @@ -139,7 +166,11 @@ impl Fixture { .unwrap(); let change = repo.save_change(&change).unwrap(); let graph = ProvenanceGraphBuilder::new(SESSION, "fixture") - .add_node(receipt_node(&work)) + .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(); @@ -149,17 +180,20 @@ impl Fixture { ) .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, - } + ( + 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] diff --git a/atomic-repository/src/repository/publication_review/tests/observations.rs b/atomic-repository/src/repository/publication_review/tests/observations.rs index 26456fbd..3e6865a0 100644 --- a/atomic-repository/src/repository/publication_review/tests/observations.rs +++ b/atomic-repository/src/repository/publication_review/tests/observations.rs @@ -534,6 +534,63 @@ fn terminal_disposition_does_not_approve_historical_implementation_goals() { 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(); diff --git a/docs/retrospective-publication-review.md b/docs/retrospective-publication-review.md index f735f4f9..ff3a302a 100644 --- a/docs/retrospective-publication-review.md +++ b/docs/retrospective-publication-review.md @@ -183,6 +183,9 @@ 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.