Skip to main content

proof_verify/
report.rs

1// Copyright 2026 Proof Engine Contributors
2// SPDX-License-Identifier: MIT OR Apache-2.0
3//! Verification report: three distinct outcomes, never collapsed.
4//! Every record is derived from actual verification state (explainability basis).
5
6use proof_core::{ErrorCode, LifecycleStatus};
7
8/// One outcome dimension: valid or invalid. There is no "unknown-as-valid":
9/// stages that cannot establish validity record `ok: false`.
10#[derive(Debug, Clone, Copy, PartialEq, Eq)]
11pub enum Validity {
12    Valid,
13    Invalid,
14}
15
16/// Policy decision. Phase 4 always yields `Indeterminate` (no policy engine yet).
17#[derive(Debug, Clone, Copy, PartialEq, Eq)]
18pub enum PolicyDecision {
19    Pass,
20    Fail,
21    Indeterminate,
22}
23
24impl PolicyDecision {
25    pub fn as_str(self) -> &'static str {
26        match self {
27            Self::Pass => "pass",
28            Self::Fail => "fail",
29            Self::Indeterminate => "indeterminate",
30        }
31    }
32}
33
34/// One stage check. Machine-readable (`stage` + `code`) first, human text last.
35#[derive(Debug, Clone)]
36pub struct CheckRecord {
37    /// Pipeline stage, e.g. "SIGNATURES".
38    pub stage: &'static str,
39    /// Object the check concerns (`proof:<id>`, `att:<id>`, stage name if global).
40    pub object: String,
41    pub ok: bool,
42    /// Stable code for failures; `None` for passing/informational records.
43    pub code: Option<ErrorCode>,
44    pub message: String,
45}
46
47impl CheckRecord {
48    pub fn ok(stage: &'static str, object: impl Into<String>, message: impl Into<String>) -> Self {
49        Self {
50            stage,
51            object: object.into(),
52            ok: true,
53            code: None,
54            message: message.into(),
55        }
56    }
57
58    pub fn fail(
59        stage: &'static str,
60        object: impl Into<String>,
61        code: ErrorCode,
62        message: impl Into<String>,
63    ) -> Self {
64        Self {
65            stage,
66            object: object.into(),
67            ok: false,
68            code: Some(code),
69            message: message.into(),
70        }
71    }
72
73    /// Informational record: true statement about the run, not a check result.
74    pub fn note(
75        stage: &'static str,
76        object: impl Into<String>,
77        message: impl Into<String>,
78    ) -> Self {
79        Self {
80            stage,
81            object: object.into(),
82            ok: true,
83            code: None,
84            message: message.into(),
85        }
86    }
87}
88
89/// Per-attestation lifecycle outcome (TIME/REVOCATION stages). Exists so the
90/// ACTIVE/EXPIRED/REVOKED/SUPERSEDED/UNKNOWN state machine is inspectable
91/// without re-deriving it from check text.
92#[derive(Debug, Clone)]
93pub struct LifecycleRecord {
94    /// Attestation id (`att:<id>`) the status concerns.
95    pub object: String,
96    pub status: LifecycleStatus,
97    /// Failure code for `Expired`/`Revoked`/`Unknown`; `None` for `Active`
98    /// and `Superseded` (historical note preserved).
99    pub code: Option<ErrorCode>,
100    pub message: String,
101}
102
103/// Full verification output.
104#[derive(Debug, Clone)]
105pub struct VerifyReport {
106    /// Recomputed proof id, or `None` when the envelope never parsed.
107    pub proof_id: Option<String>,
108    /// "Is the cryptographic material internally valid?"
109    pub cryptographic_validity: Validity,
110    /// "Is the evidence consistent, connected, and timely?" — timeliness and
111    /// revocation are stages TIME/REVOCATION (Phase 6): `Expired`/`Revoked`/
112    /// `Unknown` flip this to `Invalid`; `Superseded` keeps it `Valid` with a
113    /// historical note.
114    pub evidence_validity: Validity,
115    /// "Does the evidence satisfy the requested policy?" The pipeline never
116    /// evaluates policy itself; it reports `Indeterminate` and the caller runs
117    /// `proof-policy::evaluate_policy` on the verified state.
118    pub policy_decision: PolicyDecision,
119    /// True once stages TIME+REVOCATION ran (Phase 6). Early exits (parse/
120    /// schema/canonical failures) leave it false.
121    pub lifecycle_checked: bool,
122    /// Per-attestation lifecycle status, one entry per signature-verified
123    /// statement attestation.
124    pub lifecycle: Vec<LifecycleRecord>,
125    /// Ids of signature-verified embedded *status* attestations (revoke/
126    /// supersede claims), in proof order. Caller-supplied status objects are
127    /// not proof members and never appear here. Consumers (e.g. policy state
128    /// projection) must never treat a status attestation as a statement.
129    pub status_objects: Vec<String>,
130    pub checks: Vec<CheckRecord>,
131}
132
133impl VerifyReport {
134    /// All failure codes in stage order (convenience for tests and CLI).
135    pub fn failure_codes(&self) -> Vec<ErrorCode> {
136        self.checks
137            .iter()
138            .filter(|c| !c.ok)
139            .filter_map(|c| c.code)
140            .collect()
141    }
142
143    pub fn passed_crypto(&self) -> bool {
144        self.cryptographic_validity == Validity::Valid
145    }
146}