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}