antigen 0.3.0

Structural memory of failure-classes for Rust. Make implicit immunity explicit.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196

//! Oracle lifecycle example — declare → complete → attest → deprecate.
//! (ADR-021 oracle-as-artifact-class with stewardship + state machine.)
//!
//! # The story
//!
//! Your methodology depends on an external reference — Higham 2002 §6.3
//! ("Accuracy and Stability of Numerical Algorithms," 2nd edition,
//! Section 6.3 on triangular linear systems backward error). You want
//! signers to be able to attest "I reviewed my code against this exact
//! reference" with a structural pointer to the reference — not a free-text
//! URL that goes stale, not a copy-pasted excerpt that drifts, but a
//! first-class workspace artifact with stewardship and lifecycle.
//!
//! That's the oracle artifact-class (ADR-021 §D3 Model B):
//!
//! - **Oracle**: a typed reference (`LocalFile` / `Url` / `Doi` / `Arxiv`
//!   / `GitHubIssue` / `Other`) bound to a 5-state lifecycle
//!   (`Draft → Complete → Deprecated / Retired / Revoked`)
//! - **Stewards**: appointed reviewers who authorize state transitions.
//!   Minimum 2 per oracle (ATK-021-13 succession mitigation). Stewards are
//!   categorically distinct from signers — the math-researcher who attests
//!   against an oracle is NOT necessarily its steward.
//! - **State machine**: monotonic. Backward transitions prohibited. Draft
//!   blocks signer attestation (`oracles_complete(...)` predicate rejects);
//!   Complete admits; Deprecated/Retired preserve prior attestations at
//!   `Execution` tier; Revoked with `invalidates_prior_attestations=true`
//!   retroactively demotes priors to `Reachability`.
//! - **Sign-time validity** (§D4): an attestation's tier is determined by
//!   the oracle's state AT SIGN TIME, not at audit time. Stewards changing
//!   state after attestation produce audit HINTS, not tier degradation
//!   (except `Revoked(invalidates_prior=true)`).
//!
//! # What this example demonstrates
//!
//! This file is mostly NARRATIVE — the oracle lifecycle is CLI-driven, so
//! the example is a walkable script of `cargo antigen oracle ...` invocations
//! with explanations of what each one means and what happens on disk. The
//! Rust code at the bottom is a small fixture that prints the workflow.
//!
//! Run:
//!
//! ```sh
//! cargo run --example oracle_lifecycle --package antigen
//!
//! # Then walk the lifecycle yourself in a tempdir:
//! mkdir /tmp/oracle-demo && cd /tmp/oracle-demo
//! cargo run --manifest-path R:/antigen/Cargo.toml --bin cargo-antigen -- antigen oracle list
//! ```

#![allow(dead_code, unused_imports)]

/// Walkthrough script. Each step lists a single `cargo antigen oracle`
/// invocation + what changes on disk + what the audit/scan would report.
const ORACLE_LIFECYCLE_SCRIPT: &str = r#"
ORACLE LIFECYCLE WALKTHROUGH
============================

The oracle artifact-class lives at workspace-level: `.antigen/oracles/<id>.oracle.json`.
Each step below mutates that file via a stewardship-authorized CLI verb.

──────────────────────────────────────────────────────────────────────────────
STEP 1: DECLARE — create an oracle in Draft state
──────────────────────────────────────────────────────────────────────────────

  cargo antigen oracle declare \
    --id higham-2002-section-6-3 \
    --kind doi \
    --reference "10.1137/1.9780898718027" \
    --steward alice \
    --steward bob \
    --rationale "Higham 2002 §6.3 (triangular system backward error) chosen as \
                 the authoritative methodology reference for our numeric linear \
                 solver. Alice + Bob appointed as stewards per team-lead 2026-03-01."

What happens:
  - File created at `.antigen/oracles/higham-2002-section-6-3.oracle.json`
  - state = "draft"
  - stewards = [{ name: "alice", authorization_basis: <rationale> },
                 { name: "bob",   authorization_basis: <rationale> }]
  - transitions = [] (creation event captured by Provenance, NOT as a transition)

Schema enforcement: < 2 stewards rejected at save time (ATK-021-13).
The CLI emits a warning for single-steward declares; save_oracle's
Oracle::validate() refuses to write.

──────────────────────────────────────────────────────────────────────────────
STEP 2: ATTEMPT EARLY ATTESTATION — should be REJECTED while Draft
──────────────────────────────────────────────────────────────────────────────

If a signer tries to attest against the DRAFT oracle via a predicate like:

  requires = oracles_complete(files = ["higham-2002-section-6-3"])

…then `cargo antigen attest check` reports `discipline-predicate-failed`
at `WitnessTier::None`. Draft oracles BLOCK the `oracles_complete` leaf —
this is the load-bearing structural guarantee: no signer can attest
against an oracle whose stewards haven't authorized it as authoritative.

──────────────────────────────────────────────────────────────────────────────
STEP 3: COMPLETE — steward authorizes Draft → Complete
──────────────────────────────────────────────────────────────────────────────

  cargo antigen oracle complete \
    --id higham-2002-section-6-3 \
    --steward alice \
    --version "2nd-edition-2002" \
    --rationale "Reviewed §6.3 in full; methodology applies cleanly to our \
                 triangular solver implementation; bob co-reviewed and concurs."

What happens:
  - state = "complete"
  - transitions = [{ from: "draft", to: "complete", authorized_by: "alice", at: <today>,
                     rationale: <rationale> }]
  - version.pinned = "2nd-edition-2002" (load-bearing: stewards pin the
    version of the reference at the moment of completion; signers attest
    against this pinned snapshot, not the live reference)

Schema enforcement: authorized_by must appear in stewards[*].name (ATK-021-15).
A non-steward authorizing the transition is rejected at validation time.

──────────────────────────────────────────────────────────────────────────────
STEP 4: ATTEST AGAINST THE COMPLETE ORACLE
──────────────────────────────────────────────────────────────────────────────

Now signers can attest. The `oracles_complete` leaf accepts the Complete
oracle; the audit reports `discipline-predicate-passed-substrate-current`
at `WitnessTier::Execution` with `EvidenceKind::SubstrateState`.

In practice this is the same `cargo antigen attest scaffold/sign` flow
from substrate_witness.rs — the difference is the predicate includes
`oracles_complete(files = [<oracle-id>])` and the audit reads from the
canonical oracle store at `.antigen/oracles/`.

──────────────────────────────────────────────────────────────────────────────
STEP 5: DEPRECATE — Complete → Deprecated when superseded
──────────────────────────────────────────────────────────────────────────────

  cargo antigen oracle deprecate \
    --id higham-2002-section-6-3 \
    --steward bob \
    --superseded-by higham-2002-section-6-4 \
    --rationale "Section 6.4 (block-triangular solvers) covers our v0.2 algorithm \
                 cleanly; 6.3 is still correct for v0.1 but no longer the canonical \
                 reference for new work."

What happens:
  - state = "deprecated" with superseded_by = "higham-2002-section-6-4"
  - transitions = [{ from: "draft", to: "complete", ... },
                    { from: "complete", to: "deprecated", authorized_by: "bob", ... }]
  - SIGN-TIME VALIDITY (§D4): existing attestations against the Complete state
    REMAIN HONORED at Execution tier. The audit emits an informational hint
    ("oracle-deprecated") on those attestations but does NOT demote them.
    Signers cannot be held responsible for post-sign-time state changes.

The Deprecated/Retired/Revoked distinction matters:
  - Retired: oracle is gone but the discipline was correct. Use when an
    oracle is no longer maintained but the underlying methodology stands.
  - Deprecated(superseded_by): same-trust replacement available; soft handoff.
  - Revoked(invalidates_prior=true): oracle was INCORRECT or fraudulent.
    Retroactively demotes prior attestations to Reachability. Use only when
    the methodology itself was wrong.

──────────────────────────────────────────────────────────────────────────────
STEP 6: INSPECT VIA STATUS + LIST
──────────────────────────────────────────────────────────────────────────────

  cargo antigen oracle status --id higham-2002-section-6-3

Reports current state + steward list + transition log (append-only,
time-ordered). Each transition entry preserves WHO authorized + WHEN +
WHY — the full institutional memory of the discipline's evolution.

  cargo antigen oracle list [--format json]

Walks `.antigen/oracles/` and inventories every declared oracle with id +
current state + steward count. JSON format for scripting; human format
for terminals.

──────────────────────────────────────────────────────────────────────────────
SUMMARY
──────────────────────────────────────────────────────────────────────────────

Oracle as artifact-class gives discipline references the same structural
treatment that #[immune] gives function bodies: the WHY lives at a stable
address, stewardship is explicit, transitions are auditable, and signer
attestations are pinned to a specific reviewed version. The biology rhyme
that grounds this (per B-021-4): follicular dendritic cells (FDCs) are of
stromal origin distinct from B-cells — stewardship and attestation are
biology-predicted to be structurally separated, not just convention.
"#;

fn main() {
    println!("antigen oracle lifecycle example — walkable CLI script.");
    println!();
    println!("{ORACLE_LIFECYCLE_SCRIPT}");
}