cordance_cortex/lib.rs
1//! Cortex adapter. Emits `cordance-cortex-receipt-v1-candidate` JSON only.
2//!
3//! ADR 0005: Cordance never writes to the cortex repo or runtime. It produces
4//! a receipt; the operator hands the receipt to Cortex via Cortex's own
5//! acceptance flow.
6//!
7//! Every receipt's `AuthorityBoundary` is constructed via
8//! `AuthorityBoundary::candidate_only()`, which sets every authority-grant
9//! flag to `false`. Receipts re-validate through `validate_invariants()`
10//! on the deserialise path so a tampered JSON that flips a flag is caught
11//! even if `serde` accepts it.
12//!
13//! # Golden path
14//!
15//! ```no_run
16//! use cordance_core::advise::AdviseReport;
17//! use cordance_core::lock::SourceLock;
18//! use cordance_core::pack::{CordancePack, PackTargets, ProjectIdentity};
19//! use cordance_core::schema;
20//!
21//! let pack = CordancePack {
22//! schema: schema::CORDANCE_PACK_V1.into(),
23//! project: ProjectIdentity {
24//! name: "my-project".into(),
25//! repo_root: ".".into(),
26//! kind: "rust-workspace".into(),
27//! host_os: "linux".into(),
28//! axiom_pin: Some("v3.1.1-axiom".into()),
29//! },
30//! sources: vec![],
31//! doctrine_pins: vec![],
32//! targets: PackTargets::all(),
33//! outputs: vec![],
34//! source_lock: SourceLock::empty(),
35//! advise: AdviseReport::empty(),
36//! residual_risk: vec!["claim_ceiling=candidate".into()],
37//! };
38//!
39//! let receipt = cordance_cortex::build_receipt(&pack).expect("build receipt");
40//! receipt.validate_invariants().expect("invariants hold");
41//!
42//! let json = serde_json::to_string_pretty(&receipt).expect("serialise");
43//! println!("{json}");
44//! ```
45
46#![forbid(unsafe_code)]
47#![deny(clippy::unwrap_used, clippy::expect_used)]
48
49use cordance_core::pack::CordancePack;
50use cordance_core::receipt::{AuthorityBoundary, CortexReceiptV1Candidate};
51
52pub mod builder;
53pub mod validator;
54
55#[derive(Debug, thiserror::Error)]
56pub enum CortexError {
57 #[error("receipt validation error: {0}")]
58 Validation(String),
59 #[error("serialisation error: {0}")]
60 Serde(#[from] serde_json::Error),
61}
62
63/// Build a candidate receipt from a compiled pack.
64///
65/// # Errors
66/// Returns `CortexError::Validation` if the assembled receipt fails structural
67/// validation.
68#[allow(clippy::missing_errors_doc)]
69pub fn build_receipt(pack: &CordancePack) -> Result<CortexReceiptV1Candidate, CortexError> {
70 builder::build_receipt(pack)
71}
72
73/// Quick check: a fresh `AuthorityBoundary::candidate_only()` is always safe.
74#[must_use]
75pub const fn safe_boundary() -> AuthorityBoundary {
76 AuthorityBoundary::candidate_only()
77}
78
79#[cfg(test)]
80mod tests {
81 use super::*;
82
83 #[test]
84 fn safe_boundary_grants_nothing() {
85 let b = safe_boundary();
86 assert!(b.candidate_only);
87 assert!(!b.cortex_truth_allowed);
88 }
89}