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
8 changes: 8 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
version: 2
updates:
# The release the optional evidence replay checker runs on.
- package-ecosystem: pip
directory: /docs/examples/evidence-replay
target-branch: dev
schedule:
interval: weekly
18 changes: 18 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -155,3 +155,21 @@ jobs:

- name: cargo check (MSRV)
run: cargo check --workspace

evidence-checker:
name: Evidence replay checker
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- uses: actions/setup-python@v5
with:
python-version: "3.12"

# The optional checker's release is pinned, with hashes, in
# requirements.txt; Dependabot proposes each new release.
- name: Install the pinned checker release
run: python -m pip install --require-hashes -r docs/examples/evidence-replay/requirements.txt

- name: Run the checker controls
run: python -m unittest discover -s docs/examples/evidence-replay -p test_checker.py -v
21 changes: 21 additions & 0 deletions atomic-canonical/src/triage_ref.rs
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,11 @@ pub struct TriagePins {
pub candidate_changes: Vec<String>,
/// Intent id → `intentSubstanceHash` at review time.
pub intent_substance_hashes: BTreeMap<String, String>,
/// Content hashes of attached retained evidence-replay reports. Sorted
/// before hashing; omitted from the canonical form when empty so existing
/// triage references stay stable.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub evidence_report_hashes: Vec<String>,
}

/// The `urn:atomic:triage:<blake3-hex>` reference for a set of pins.
Expand All @@ -45,6 +50,7 @@ pub struct TriagePins {
pub fn triage_reference(pins: &TriagePins) -> String {
let mut canonical_pins = pins.clone();
canonical_pins.candidate_changes.sort();
canonical_pins.evidence_report_hashes.sort();
let value =
serde_json::to_value(&canonical_pins).expect("TriagePins serialization is infallible");
let canonical = jcs::canonicalize(&value);
Expand Down Expand Up @@ -72,6 +78,7 @@ mod tests {
view_merkle: "MERKLEBASE32".to_string(),
candidate_changes: vec!["CH2".to_string(), "CH1".to_string(), "CH3".to_string()],
intent_substance_hashes: substance,
evidence_report_hashes: Vec::new(),
}
}

Expand Down Expand Up @@ -117,6 +124,20 @@ mod tests {
.intent_substance_hashes
.insert("urn:atomic:intent:a".to_string(), "blake3:zzz".to_string());
assert_ne!(triage_reference(&substance), base);

let mut evidence = pins();
evidence
.evidence_report_hashes
.push("blake3:report".to_string());
assert_ne!(triage_reference(&evidence), base);
evidence.evidence_report_hashes = vec!["blake3:b".to_string(), "blake3:a".to_string()];
let mut reordered = evidence.clone();
reordered.evidence_report_hashes.reverse();
assert_eq!(
triage_reference(&evidence),
triage_reference(&reordered),
"report hashes are a set"
);
}

#[test]
Expand Down
5 changes: 5 additions & 0 deletions atomic-canonical/src/vocab.rs
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,11 @@ pub const FINDING_CODE: &[&str] = &[
"OPEN_REMEDIATION",
"UNREVIEWED_CHANGE",
"PUBLICATION_GATE",
"EVIDENCE_REPLAY_SUPPORTED",
"EVIDENCE_REPLAY_CONTRADICTED",
"EVIDENCE_REPLAY_NOT_ESTABLISHED",
"EVIDENCE_REPLAY_STALE",
"EVIDENCE_REPLAY_UNRELATED",
];

/// Directive names recognized by the parser + lift (closed set).
Expand Down
13 changes: 13 additions & 0 deletions atomic-cli/src/commands/rpc.rs
Original file line number Diff line number Diff line change
Expand Up @@ -6834,11 +6834,24 @@ pub(crate) fn triage_review(
let Some(session) = Service::open()? else {
return Ok(None);
};
let evidence_reports = args
.evidence_reports
.iter()
.map(|path| {
intent_evidence::read_report_bytes(path)
.map(|payload| pb::VersionedBytes {
schema: intent_evidence::REPORT_DOCUMENT_SCHEMA.to_string(),
payload,
})
.map_err(evidence_cli_error)
})
.collect::<CliResult<Vec<_>>>()?;
let request = pb::GenerateTriageReviewRequest {
repository: Some(session.reference.clone()),
from_view: args.feature.clone().unwrap_or_default(),
to_view: args.into.clone().unwrap_or_default(),
report: None,
evidence_reports,
};
let response = session.generate_triage_review(request)?;
let Some(bundle) = response
Expand Down
43 changes: 41 additions & 2 deletions atomic-cli/src/commands/triage/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ use std::process::{Command as ProcessCommand, Stdio};
use clap::{Parser, Subcommand};
use clap_complete::engine::ArgValueCompleter;

use atomic_repository::intent_evidence;
use atomic_repository::{Repository, RepositoryError};

use crate::commands::complete::complete_view_names;
Expand All @@ -25,7 +26,9 @@ pub mod model {
}
pub mod output;
pub mod project {
pub use atomic_repository::triage::report::{build_report, build_walkthrough, TaskFact};
pub use atomic_repository::triage::report::{
build_report, build_report_with_evidence, build_walkthrough, TaskFact,
};
}

/// Triage a feature view against a target before insert.
Expand Down Expand Up @@ -299,6 +302,12 @@ pub struct TriageReview {
#[arg(long)]
pub json: bool,

/// Attach a retained evidence-replay report produced by
/// `atomic intent validate --json --replay-evidence ...`. Repeatable; the
/// report's pins must still match the current intent/view state.
#[arg(long = "evidence-report", value_name = "PATH")]
pub evidence_reports: Vec<PathBuf>,

/// Print the guided walkthrough: the candidate changes grouped into
/// ordered semantic layers (foundations first), with each layer's
/// rationale, files, and inspect commands. Bounded — never a diff dump.
Expand Down Expand Up @@ -343,11 +352,28 @@ impl Command for TriageReview {
let repo = Repository::open(&root).map_err(CliError::Repository)?;
let (feature, into) = resolve_views(&repo, self.feature.as_deref(), self.into.as_deref())?;

let report = project::build_report(&repo, &feature, &into)?;
let evidence_reports = self
.evidence_reports
.iter()
.map(|path| intent_evidence::read_report(path).map_err(evidence_error))
.collect::<CliResult<Vec<_>>>()?;
let report =
project::build_report_with_evidence(&repo, &feature, &into, &evidence_reports)?;
render_report(self, &report)
}
}

/// Map a retained-report failure into the CLI's exit-code surface.
fn evidence_error(error: intent_evidence::EvidenceError) -> CliError {
match error {
intent_evidence::EvidenceError::Repository(error) => CliError::Repository(error),
intent_evidence::EvidenceError::Io(error) => CliError::Io(error),
other => CliError::InvalidArgument {
message: other.to_string(),
},
}
}

/// The output selection, shared by the routed and the local body: attest >
/// html > json > walkthrough > CLI dashboard.
fn render_report(
Expand Down Expand Up @@ -559,6 +585,19 @@ mod tests {
assert!(msg.contains("omit --into"), "unexpected: {msg}");
}

#[test]
fn evidence_report_flag_is_repeatable() {
let review = TriageReview::try_parse_from([
"review",
"--evidence-report",
"one.json",
"--evidence-report",
"two.json",
])
.unwrap();
assert_eq!(review.evidence_reports.len(), 2);
}

#[test]
fn candidates_parses_the_same_optional_pair_as_review() {
let cmd = TriageCandidates::try_parse_from(["candidates"]).unwrap();
Expand Down
2 changes: 2 additions & 0 deletions atomic-cli/src/commands/triage/output.rs
Original file line number Diff line number Diff line change
Expand Up @@ -860,6 +860,7 @@ mod tests {
candidate_changes: vec!["HASH1".to_string()],
closure_additions: vec![],
intent_substance_hashes: BTreeMap::new(),
evidence_reports: Vec::new(),
},
summary: Summary {
changes: 1,
Expand All @@ -884,6 +885,7 @@ mod tests {
satisfied_by: vec!["HASH1".to_string()],
}],
reviewed_by: Some("did:atomic:<reviewer>&co".to_string()),
evidence_replays: Vec::new(),
}],
changes: vec![ChangeReport {
id: "HASH1".to_string(),
Expand Down
113 changes: 107 additions & 6 deletions atomic-repository/src/intent_evidence.rs
Original file line number Diff line number Diff line change
Expand Up @@ -85,12 +85,25 @@ pub struct EvidenceDecision {
pub details: Value,
}

#[derive(Debug, Serialize)]
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct EvidenceReport {
pub schema_version: &'static str,
pub schema_version: String,
pub decisions: Vec<EvidenceDecision>,
}

/// The retained report document produced by
/// `atomic intent validate --json --replay-evidence ...`. Unknown top-level
/// fields (`conforms`, `results`) are ignored so the full validate output is a
/// valid input.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct EvidenceReportDocument {
pub evidence_context: EvidenceContext,
pub evidence_replay: EvidenceReport,
}

/// Wire/schema name for a retained replay report payload.
pub const REPORT_DOCUMENT_SCHEMA: &str = "atomic.intent.evidence-replay.v1";

impl EvidenceReport {
/// Map every non-supported decision to a canonical-gate violation.
pub fn violations(&self) -> Vec<Violation> {
Expand Down Expand Up @@ -122,6 +135,14 @@ pub enum EvidenceError {
ViewCycle,
#[error("evidence replay manifest exceeds 1 MiB")]
ManifestTooLarge,
#[error("evidence replay report exceeds 1 MiB")]
ReportTooLarge,
#[error("evidence replay report admission refused: {0}")]
ReportAdmission(String),
#[error("invalid evidence replay report: {0}")]
InvalidReport(String),
#[error("unsupported evidence replay report schema: {0}")]
UnsupportedReportSchema(String),
#[error("evidence replay manifest admission refused: {0}")]
ManifestAdmission(String),
#[error("invalid evidence replay manifest: {0}")]
Expand Down Expand Up @@ -212,6 +233,48 @@ pub fn read_manifest(path: &Path) -> Result<Vec<u8>, EvidenceError> {
Ok(bytes)
}

/// Parse a retained `atomic intent validate --json --replay-evidence` report.
/// Unknown top-level validate fields are ignored; the replay document itself is
/// strict.
pub fn parse_report(bytes: &[u8]) -> Result<EvidenceReportDocument, EvidenceError> {
if bytes.len() as u64 > MANIFEST_LIMIT {
return Err(EvidenceError::ReportTooLarge);
}
let value = atomic_canonical::jcs::admit_document(bytes)
.map_err(|error| EvidenceError::ReportAdmission(error.to_string()))?;
let document: EvidenceReportDocument = serde_json::from_value(value)
.map_err(|error| EvidenceError::InvalidReport(error.to_string()))?;
if document.evidence_replay.schema_version != "atomic-evidence-replay-report/v1" {
return Err(EvidenceError::UnsupportedReportSchema(
document.evidence_replay.schema_version,
));
}
Ok(document)
}

/// Read a retained report within the protocol ceiling.
pub fn read_report_bytes(path: &Path) -> Result<Vec<u8>, EvidenceError> {
let file = std::fs::File::open(path)?;
let mut bytes = Vec::new();
file.take(MANIFEST_LIMIT + 1).read_to_end(&mut bytes)?;
if bytes.len() as u64 > MANIFEST_LIMIT {
return Err(EvidenceError::ReportTooLarge);
}
Ok(bytes)
}

/// Read and parse a retained report within the protocol ceiling.
pub fn read_report(path: &Path) -> Result<EvidenceReportDocument, EvidenceError> {
parse_report(&read_report_bytes(path)?)
}

/// Canonical content hash of a retained report document. Triage binds this hash
/// into its reference and signed report.
pub fn report_hash(document: &EvidenceReportDocument) -> Result<String, EvidenceError> {
let value = serde_json::to_value(document)?;
Ok(atomic_canonical::hash::content_hash(&value))
}

/// Read and replay a manifest file. Relative artifact roots resolve against the
/// manifest's parent directory.
pub fn replay(
Expand Down Expand Up @@ -292,7 +355,7 @@ pub fn replay_bytes(
decisions.push(decision);
}
Ok(EvidenceReport {
schema_version: "atomic-evidence-replay-report/v1",
schema_version: "atomic-evidence-replay-report/v1".into(),
decisions,
})
}
Expand Down Expand Up @@ -508,7 +571,7 @@ mod tests {
assert!(!valid_decision(&decision, &claim, "request-2"));
assert_eq!(
EvidenceReport {
schema_version: "test",
schema_version: "test".into(),
decisions: vec![decision]
}
.violations()
Expand All @@ -519,7 +582,7 @@ mod tests {
decision.decision = "contradicted".into();
assert_eq!(
EvidenceReport {
schema_version: "test",
schema_version: "test".into(),
decisions: vec![decision]
}
.violations()
Expand All @@ -529,7 +592,7 @@ mod tests {
decision = unknown(&claim, "request-1", "all_selected_spans_present");
decision.decision = "supported".into();
assert!(EvidenceReport {
schema_version: "test",
schema_version: "test".into(),
decisions: vec![decision]
}
.violations()
Expand Down Expand Up @@ -564,6 +627,44 @@ mod tests {
assert_eq!(current.view_chain[1].name, parent);
}

#[test]
fn retained_report_parses_hashes_and_ignores_validate_skins() {
let node = node();
let current = context(&node);
let claim = manifest(&node).claims.remove(0);
let document = EvidenceReportDocument {
evidence_context: current.clone(),
evidence_replay: EvidenceReport {
schema_version: "atomic-evidence-replay-report/v1".into(),
decisions: vec![unknown(&claim, "request-1", "missing_artifact")],
},
};
let bytes = serde_json::to_vec(&document).unwrap();
assert_eq!(parse_report(&bytes).unwrap(), document);
let hash = report_hash(&document).unwrap();
assert!(hash.starts_with("blake3:"));
let mut changed = document.clone();
changed.evidence_replay.decisions[0].reason = "different".into();
assert_ne!(hash, report_hash(&changed).unwrap());

// The full `intent validate --json` document is accepted; its
// conforms/results fields are outside the replay document.
let wrapped = json!({
"conforms": false,
"results": [{"message": "unattested"}],
"evidence_context": current,
"evidence_replay": document.evidence_replay,
});
assert!(parse_report(&serde_json::to_vec(&wrapped).unwrap()).is_ok());

let mut unsupported = serde_json::to_value(&document).unwrap();
unsupported["evidence_replay"]["schema_version"] = json!("other");
assert!(matches!(
parse_report(&serde_json::to_vec(&unsupported).unwrap()),
Err(EvidenceError::UnsupportedReportSchema(_))
));
}

#[cfg(unix)]
fn checker(script: &str) -> tempfile::TempPath {
use std::os::unix::fs::PermissionsExt;
Expand Down
5 changes: 4 additions & 1 deletion atomic-repository/src/triage/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -13,4 +13,7 @@ pub mod model;
pub mod report;

pub use model::*;
pub use report::{build_report, count_hunk_atoms, hunk_display_summaries, HunkDisplaySummary};
pub use report::{
build_report, build_report_with_evidence, count_hunk_atoms, hunk_display_summaries,
HunkDisplaySummary,
};
Loading