Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions atomic-canonical/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -104,3 +104,4 @@ pub fn verify_memory(
) -> Result<()> {
proof::verify_memory(node, public_key)
}
pub mod publication_review;
195 changes: 195 additions & 0 deletions atomic-canonical/src/publication_review.rs
Original file line number Diff line number Diff line change
@@ -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<String>,
/// Reserved legacy field. The review resolver never derives authority from it.
pub governing_intents: Vec<String>,
pub provenance: Vec<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub observations: Vec<IntentObservationPin>,
}

/// 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<u32>,
pub kind: String,
/// Exact receipt identifier; not a filename or timestamp inference.
pub reference: String,
pub intent: Option<String>,
/// resolved, unresolved, or ambiguous; none means no generating-turn binding.
pub resolution: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub diagnostic: Option<String>,
/// 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<SignedRevisionPin>,
}

#[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<String>,
pub changes: Vec<ChangePin>,
pub review: IntentPin,
pub work: Vec<IntentPin>,
/// Independently reviewed terminal dispositions, not approved implementations.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub set_aside: Vec<IntentPin>,
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<ReviewViewPin>,
/// 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<ReviewSnapshot>,
}

#[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<Vec<String>>,
/// Sorted unique full effective projection closure, including ancestors.
pub membership: Vec<String>,
pub intent_revisions: Vec<RetainedIntentRevision>,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RetainedIntentRevision {
pub id: String,
pub frontmatter: serde_json::Map<String, serde_json::Value>,
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<String>,
#[serde(rename = "attributedTo")]
pub attributed_to: String,
#[serde(
rename = "contentHash",
default,
skip_serializing_if = "Option::is_none"
)]
pub content_hash: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub proof: Option<Proof>,
}

impl PublicationReview {
/// Admit untrusted bytes before parsing, including duplicate-key/depth checks.
pub fn parse(bytes: &[u8]) -> crate::Result<Self> {
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()
}
}
6 changes: 4 additions & 2 deletions atomic-canonical/src/vocab.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
2 changes: 1 addition & 1 deletion atomic-cli/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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 }
Expand Down
53 changes: 52 additions & 1 deletion atomic-cli/src/commands/intent/graph.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<std::path::PathBuf>,
/// 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<std::path::PathBuf>,
}

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 {
Expand Down Expand Up @@ -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"
};
Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -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![],
Expand Down Expand Up @@ -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;
Expand Down
9 changes: 9 additions & 0 deletions atomic-cli/src/commands/query/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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()
}
Expand Down
Loading
Loading