From b6e5512a4131016827e0d07da765ab256c17d6c3 Mon Sep 17 00:00:00 2001 From: Vincent Date: Mon, 16 Nov 2026 15:34:22 -0500 Subject: [PATCH] perf: resolve each stored review once per publication gate run For every managed change without an attestation, the publication gate asks whether a stored review covers it. Each of those questions re-read the whole review inventory and then verified and validated the review again, although none of that depends on which change is asking. Validation rebuilds the review's retained source view, so a batch of M changes covered by one review cost M full validations. One gate evaluation now reads the inventory once and resolves each review once: its signature and supersession chain, and its SHACL outcome. Later changes reuse the result. The decision for each change and the limitation text it reports are unchanged: a review that fails still blocks, and explains, every change it covers. --- .../src/repository/provenance_gate.rs | 7 +- .../src/repository/publication_review/mod.rs | 162 ++++++++++++------ .../repository/publication_review/tests.rs | 1 + .../publication_review/tests/boundaries.rs | 6 +- .../publication_review/tests/gate.rs | 160 +++++++++++++++++ 5 files changed, 280 insertions(+), 56 deletions(-) create mode 100644 atomic-repository/src/repository/publication_review/tests/gate.rs diff --git a/atomic-repository/src/repository/provenance_gate.rs b/atomic-repository/src/repository/provenance_gate.rs index ca4a25cc..7e461327 100644 --- a/atomic-repository/src/repository/provenance_gate.rs +++ b/atomic-repository/src/repository/provenance_gate.rs @@ -511,6 +511,8 @@ impl Repository { let mut ledger_cache: BTreeMap = BTreeMap::new(); let mut mac_key_cache: BTreeMap> = BTreeMap::new(); let mut did_key_cache: BTreeMap> = BTreeMap::new(); + // Stored reviews are resolved once for the whole evaluation. + let mut review_cache = super::publication_review::ReviewGateCache::default(); for hash in changes { let change_b32 = hash.to_base32(); @@ -797,6 +799,7 @@ impl Repository { &session, config, did_key_provider, + &mut review_cache, ) { Ok(Some(review_hash)) => { verdict.retrospective_reviews.push(RetrospectiveApproval { @@ -806,8 +809,8 @@ impl Repository { }); } outcome => { - if let Err(error) = outcome { - verdict.limitations.push(error.to_string()); + if let Err(limitation) = outcome { + verdict.limitations.push(limitation); } verdict.blocks.push(GateBlocker::MissingAttestation { change: change_b32.clone(), diff --git a/atomic-repository/src/repository/publication_review/mod.rs b/atomic-repository/src/repository/publication_review/mod.rs index 0ca9c729..856ec5d2 100644 --- a/atomic-repository/src/repository/publication_review/mod.rs +++ b/atomic-repository/src/repository/publication_review/mod.rs @@ -15,6 +15,8 @@ use super::provenance_gate::{DidKeyProvider, PublicationGateConfig}; use super::{Repository, RepositoryError}; use atomic_canonical::publication_review::{PublicationReview, SCHEMA}; use atomic_core::types::{Base32, Hash}; +#[cfg(feature = "review-shacl")] +use std::collections::{BTreeMap, BTreeSet}; pub const PREFIX: &str = "publication-reviews/"; @@ -42,6 +44,28 @@ pub fn profile_hash() -> String { hash.finalize().to_hex().to_string() } +/// Stored reviews and, at the same index, their content addresses. +struct ReviewInventory { + reviews: Vec, + addresses: Vec, +} + +/// What one gate evaluation has already resolved about the stored reviews. +/// None of it depends on which covered change asks, so the inventory is read +/// once and each review is authenticated and validated at most once. A failure +/// is kept as the text the gate reports and repeated for every change it +/// affects. +#[derive(Default)] +pub(super) struct ReviewGateCache { + inventory: Option>, + /// Per review address: its signature holds and these reviews precede it. + #[cfg(feature = "review-shacl")] + ancestry: BTreeMap, String>>, + /// Per review address: whether it conforms, and its violation count. + #[cfg(feature = "review-shacl")] + validation: BTreeMap>, +} + impl Repository { /// Writers affecting review evidence participate in the common operation /// boundary once retrospective artifacts exist. No feature means no bypass. @@ -330,7 +354,14 @@ impl Repository { /// 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> { + Ok(self.review_inventory()?.reviews) + } + + /// The inventory together with each review's content address, which is + /// derived while checking where the review is stored. + fn review_inventory(&self) -> Result { let mut reviews = Vec::new(); + let mut addresses = Vec::new(); for entry in self.vault_list(PREFIX, None)? { if reviews.len() >= 4096 { return Err(refused("review inventory exceeds 4096 artifacts")); @@ -339,29 +370,40 @@ impl Repository { .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()) { + let address = review.artifact_hash(); + if entry.path != format!("{PREFIX}{address}/review.md") { return Err(refused( "stored artifact address does not match signed bytes", )); } reviews.push(review); + addresses.push(address); } - Ok(reviews) + Ok(ReviewInventory { reviews, addresses }) } + /// The stored review that discharges this change's missing attestation, + /// if one does. An error is the limitation the gate reports for the change. 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 + resolved: &mut ReviewGateCache, + ) -> Result, String> { + let inventory = match resolved + .inventory + .get_or_insert_with(|| self.review_inventory().map_err(|error| error.to_string())) + { + Ok(inventory) => &*inventory, + Err(error) => return Err(error.clone()), + }; + let relevant: Vec<_> = inventory + .reviews .iter() - .filter(|review| { + .zip(&inventory.addresses) + .filter(|(review, _)| { review .subject .changes @@ -369,57 +411,68 @@ impl Repository { .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); - } + #[cfg(not(feature = "review-shacl"))] + { + let _ = (config, keys); + if relevant.is_empty() { + return Ok(None); } + Err( + refused("review-shacl feature is required to evaluate retrospective evidence") + .to_string(), + ) } - 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")] + { + let resolver = + || keys.ok_or_else(|| refused("review key resolver unavailable").to_string()); + let mut validated = |review: &PublicationReview, address: &String, keys| { + resolved + .validation + .entry(address.clone()) + .or_insert_with(|| { + self.validate_publication_review(review, config, keys) + .map(|report| (report.conforms, report.results.len())) + .map_err(|error| error.to_string()) + }) + .clone() + }; + let mut superseded = BTreeSet::new(); + for &(review, address) in &relevant { + let keys = resolver()?; + // A renewal cannot suppress signature corruption, even in old rows. + let ancestors = resolved + .ancestry + .entry(address.clone()) + .or_insert_with(|| { + self.verify_review_signature(review, keys) + .and_then(|()| { + self.review_supersession(review, &inventory.reviews, keys) + }) + .map_err(|error| error.to_string()) + }) + .as_ref() + .map_err(String::clone)?; + if !review.supersedes.is_empty() && validated(review, address, keys)?.0 { + superseded.extend(ancestors.iter().cloned()); + } } - #[cfg(feature = "review-shacl")] - { - if superseded.contains(&review.artifact_hash()) { + let mut accepted = None; + for (review, address) in relevant { + if superseded.contains(address) { continue; } - let report = self.validate_publication_review( - review, - config, - keys.ok_or_else(|| refused("review key resolver unavailable"))?, - )?; - if !report.conforms { + let (conforms, violations) = validated(review, address, resolver()?)?; + if !conforms { return Err(refused(format!( - "stored review fails SHACL ({} violations)", - report.results.len() - ))); + "stored review fails SHACL ({violations} violations)" + )) + .to_string()); } - accepted = Some(review.artifact_hash()); + accepted = Some(address.clone()); } + Ok(accepted) } - Ok(accepted) } #[cfg(feature = "review-shacl")] @@ -577,7 +630,13 @@ mod unsupported { trust: Default::default(), repository_identity: None, }; - let result = repo.retrospective_review_for(&change, "legacy", &config, None); + let result = repo.retrospective_review_for( + &change, + "legacy", + &config, + None, + &mut ReviewGateCache::default(), + ); assert!(repo .workflow_snapshot_with_review(&serde_json::to_vec(&review).unwrap()) .unwrap_err() @@ -585,7 +644,6 @@ mod unsupported { .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/tests.rs b/atomic-repository/src/repository/publication_review/tests.rs index 9e7d81fe..3b8879a7 100644 --- a/atomic-repository/src/repository/publication_review/tests.rs +++ b/atomic-repository/src/repository/publication_review/tests.rs @@ -13,6 +13,7 @@ use atomic_core::{ use atomic_identity::{Identity, KeyPair}; use serde_json::json; mod boundaries; +mod gate; mod observations; mod snapshot; diff --git a/atomic-repository/src/repository/publication_review/tests/boundaries.rs b/atomic-repository/src/repository/publication_review/tests/boundaries.rs index 6341e5db..01eead3b 100644 --- a/atomic-repository/src/repository/publication_review/tests/boundaries.rs +++ b/atomic-repository/src/repository/publication_review/tests/boundaries.rs @@ -161,7 +161,8 @@ fn approval_is_exact_and_does_not_clear_incomplete_sessions() { &Hash::of(b"another change").to_base32(), SESSION, &f.config(), - Some(&|did| f.keys(did)) + Some(&|did| f.keys(did)), + &mut ReviewGateCache::default(), ) .unwrap() .is_none()); @@ -171,7 +172,8 @@ fn approval_is_exact_and_does_not_clear_incomplete_sessions() { &f.change.to_base32(), "another-session", &f.config(), - Some(&|did| f.keys(did)) + Some(&|did| f.keys(did)), + &mut ReviewGateCache::default(), ) .unwrap() .is_none()); diff --git a/atomic-repository/src/repository/publication_review/tests/gate.rs b/atomic-repository/src/repository/publication_review/tests/gate.rs new file mode 100644 index 00000000..5e1a5ff4 --- /dev/null +++ b/atomic-repository/src/repository/publication_review/tests/gate.rs @@ -0,0 +1,160 @@ +use super::*; +use std::cell::Cell; + +/// One more managed original from the fixture session, explained by the same +/// retained receipt as the fixture's own change. +fn managed_original(f: &Fixture, message: &str) -> Hash { + let mut change = Change::empty(ChangeHeader::new(message)); + 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 change = f.repo.save_change(&change).unwrap(); + let graph = ProvenanceGraphBuilder::new(SESSION, "fixture") + .add_node(receipt_node(&f.work)) + .changes_explained(vec![change]) + .build(); + f.repo.save_provenance_graph(&graph).unwrap(); + f.repo + .insert_change_rec( + &change, + crate::InsertOptions::default().view("review-source"), + ) + .unwrap(); + change +} + +/// Three managed originals of one session, all covered by one recorded review. +fn three_changes_under_one_review(f: &Fixture) -> (Vec, String) { + let changes = vec![ + f.change, + managed_original(f, "second managed original"), + managed_original(f, "third managed original"), + ]; + // The review intent has to observe the view once all three are in it. + let review = signed_intent( + &f.repo, + &f.reviewer, + &f.reviewer_key, + "review", + Some(&f.work), + ); + let prepared = f + .repo + .prepare_publication_review(&review, &changes, &|did| f.keys(did)) + .unwrap(); + let signed = f.sign(prepared); + f.repo + .record_publication_review(&signed, &f.config(), &|did| f.keys(did)) + .unwrap(); + (changes, signed.artifact_hash()) +} + +fn gate( + f: &Fixture, + changes: &[Hash], + config: &PublicationGateConfig, +) -> super::super::super::provenance_gate::GateVerdict { + f.repo + .evaluate_publication_gate(changes, config, None, Some(&|did| f.keys(did))) + .unwrap() +} + +/// Nothing the gate learns about a stored review depends on which of its +/// changes asks, so a batch must not authenticate and validate it per change. +/// Key lookups are the work a caller can see: every signature the review +/// resolver checks goes through the injected provider. +#[test] +fn gate_resolves_a_stored_review_once_for_every_change_it_covers() { + let f = Fixture::new(); + let (changes, review) = three_changes_under_one_review(&f); + let lookups = Cell::new(0usize); + let counted = |did: &str| { + lookups.set(lookups.get() + 1); + f.keys(did) + }; + let run = |changes: &[Hash]| { + lookups.set(0); + let verdict = f + .repo + .evaluate_publication_gate(changes, &f.config(), None, Some(&counted)) + .unwrap(); + (verdict, lookups.get()) + }; + + let (one, lookups_for_one) = run(&changes[..1]); + assert!(one.allowed(), "{}", one.refusal_report()); + assert!(lookups_for_one > 0, "the review must have been resolved"); + + let (all, lookups_for_all) = run(&changes); + assert!(all.allowed(), "{}", all.refusal_report()); + assert_eq!(all.retrospective_reviews.len(), 3); + assert!(all + .retrospective_reviews + .iter() + .all(|approval| approval.review_hash == review)); + assert_eq!( + lookups_for_all, lookups_for_one, + "three changes under one review must cost what one does" + ); +} + +/// Reusing an outcome must not turn one refusal into one diagnosed change and +/// two silent ones: each covered change is blocked and says why. +#[test] +fn a_stored_review_that_stopped_conforming_blocks_every_change_it_covers() { + let f = Fixture::new(); + let (changes, _) = three_changes_under_one_review(&f); + let mut revoked = f.config(); + revoked.trust.revoked = revoked.trust.signers.clone(); + + let verdict = gate(&f, &changes, &revoked); + assert!(!verdict.allowed()); + assert!(verdict.retrospective_reviews.is_empty()); + assert_eq!(verdict.blocks.len(), 3, "{}", verdict.refusal_report()); + assert_eq!( + verdict + .limitations + .iter() + .filter(|limitation| limitation.contains("stored review fails SHACL")) + .count(), + 3 + ); +} + +/// The same holds when the inventory itself cannot be read. +#[test] +fn an_unreadable_review_inventory_blocks_every_managed_change() { + let f = Fixture::new(); + let (changes, _) = three_changes_under_one_review(&f); + f.repo + .vault_store( + &format!("{PREFIX}not-a-review/review.md"), + VaultEntryType::Attestation, + b"{}".to_vec(), + "{}".into(), + ) + .unwrap(); + let unreadable = f.repo.publication_reviews().unwrap_err().to_string(); + + let verdict = gate(&f, &changes, &f.config()); + assert!(!verdict.allowed()); + assert_eq!(verdict.blocks.len(), 3, "{}", verdict.refusal_report()); + assert_eq!( + verdict + .limitations + .iter() + .filter(|limitation| **limitation == unreadable) + .count(), + 3 + ); +}