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
197
198
199
200
201

//! Example: antigen-category taxonomy (ADR-028).
//!
//! Every antigen declaration carries a `category` field that classifies HOW
//! the failure-class fires. Two categories:
//!
//! - `SubstrateAlignment` — the failure-class fires when a REPRESENTATION
//!   diverges from actual state. The thing that's wrong is what the system
//!   SAYS, not what it COMPUTES. Evidence lives outside the code: a sign-off,
//!   a ratified doc, an un-reviewed discipline record. Use `requires =`.
//!
//! - `FunctionalCorrectness` — the failure-class fires when a VERB produces
//!   the wrong output. The thing that's wrong is what the code DOES. Evidence
//!   is behavioral: a test, proptest, formal proof, or lint exercises the verb.
//!   Use `witness =`.
//!
//! ## The quick choice test
//!
//! **Can a test execute the thing you're defending?**
//! - Yes → `FunctionalCorrectness` + `witness = some_test`
//! - No (the failure-class is about substrate state that code execution can't
//!   verify) → `SubstrateAlignment` + `requires = ratified_doc(...)` or
//!   `requires = signers(...)`
//!
//! ## CLI: filter by category
//!
//! ```sh
//! # Show only substrate-alignment presentations:
//! cargo run --bin cargo-antigen -- antigen scan --root antigen/examples \
//!     --category substrate-alignment
//!
//! # Show only functional-correctness presentations:
//! cargo run --bin cargo-antigen -- antigen scan --root antigen/examples \
//!     --category functional-correctness
//! ```
//!
//! ## Run this example
//!
//! ```sh
//! cargo run --example antigen_category --package antigen
//! ```

#![allow(dead_code, unused_variables)]

#[allow(unused_imports)]
use antigen::{antigen, defended_by, presents};

// ============================================================================
// FunctionalCorrectness: a verb that can be wrong
//
// Scenario: a data-cleaning function that must not produce NaN values. The
// failure is behavioral — "clean_values() returned NaN when it shouldn't."
// A test that exercises clean_values() and checks the output is the natural
// witness. This is FunctionalCorrectness.
// ============================================================================

#[antigen(
    name = "nan-in-cleaned-output",
    category = AntigenCategory::FunctionalCorrectness,
    fingerprint = r#"name = matches("DataCleaner")"#,
    family = "numeric-correctness",
    summary = "DataCleaner::clean_values() returned NaN values — the output representation diverges from the claimed invariant (no NaN in cleaned data).",
    references = []
)]
pub struct NanInCleanedOutput;

/// A data cleaner that should never produce NaN.
///
/// VULNERABLE: missing NaN guard — `f64::sqrt(-1.0)` produces NaN silently.
#[presents(NanInCleanedOutput)]
pub struct DataCleaner {
    /// Raw float values to clean.
    pub data: Vec<f64>,
}

impl DataCleaner {
    /// Clean values without NaN guard — vulnerable path.
    pub fn clean_values(&self) -> Vec<f64> {
        // BUG: no NaN guard — negative sqrt silently produces NaN
        self.data.iter().map(|&x| x.sqrt()).collect()
    }
}

/// A corrected cleaner with a NaN guard.
///
/// DEFENDED: `#[presents(NanInCleanedOutput)]` marks the site as presenting the
/// failure-class. The test `test_clean_values_no_nan` carries `#[defended_by]`
/// to declare its intent toward `NanInCleanedOutput` — audit observes the circuit.
pub struct DataCleanerSafe {
    /// Raw float values to clean; negatives are filtered before sqrt.
    pub data: Vec<f64>,
}

#[presents(NanInCleanedOutput)]
impl DataCleanerSafe {
    /// Clean values with NaN guard — defended path.
    pub fn clean_values_safe(&self) -> Vec<f64> {
        self.data
            .iter()
            .filter(|&&x| x >= 0.0)
            .map(|&x| x.sqrt())
            .collect()
    }
}

#[test]
#[defended_by(NanInCleanedOutput)]
fn test_clean_values_no_nan() {
    let cleaner = DataCleanerSafe {
        data: vec![-1.0, 0.0, 4.0, 9.0, 16.0],
    };
    let result = cleaner.clean_values_safe();
    for val in &result {
        assert!(!val.is_nan(), "clean_values_safe() produced NaN: {val}");
    }
    // Negative inputs are filtered, not NaN-ified
    assert_eq!(result.len(), 4, "expected 4 non-negative values cleaned");
}

// ============================================================================
// SubstrateAlignment: a representation that can be stale
//
// Scenario: a security policy document must be reviewed and signed by the
// security team before each release. The failure-class fires when the policy
// doc is out-of-date or unsigned — not because any code ran incorrectly, but
// because a REPRESENTATION (the signed doc record) diverges from the required
// state (signed, current). A test can't verify this; the `.attest/` sidecar
// carries the evidence. This is SubstrateAlignment.
// ============================================================================

#[antigen(
    name = "unsigned-security-policy",
    category = AntigenCategory::SubstrateAlignment,
    fingerprint = r#"doc_contains("security_policy")"#,
    family = "governance-compliance",
    summary = "A security policy document that must be reviewed and signed before release was not attested — the attestation record diverges from the required signed state.",
    references = ["SECURITY.md"]
)]
pub struct UnsignedSecurityPolicy;

/// Placeholder for release-gating logic that depends on a signed security policy.
///
/// VULNERABLE: no attestation check — policy sign-off is assumed, not verified.
#[presents(UnsignedSecurityPolicy)]
pub fn gate_release_unverified(version: &str) -> Result<(), String> {
    println!("[GATE] Releasing {version} — security policy assumed signed");
    Ok(())
}

/// Release gate with a substrate-witness that verifies the sign-off record.
///
/// DEFENDED: the `requires = ratified_doc(...)` predicate evaluates whether the
/// security policy sidecar in `.attest/` was signed by the `security-team` role
/// before this release gate is crossed. `cargo antigen audit` evaluates the
/// predicate; unsigned = `DisciplinePredicateFailed`.
///
/// The defense is `SubstrateAlignment`: the thing being checked is not whether
/// `gate_release` *computes* correctly, but whether the *sign-off record*
/// (a substrate artifact) is present and current. No test can run the
/// security team's sign-off; only `cargo antigen audit` can check the sidecar.
///
/// ADR-029: substrate-witness evidence moves to `#[presents(X, requires=...)]`.
/// The `requires=` predicate is evaluated by `cargo antigen audit` against the
/// `.attest/` sidecar; unsigned = `DisciplinePredicateFailed`.
#[presents(
    UnsignedSecurityPolicy,
    requires = all_of([
        ratified_doc(path = "docs/security-policy.md", min_version = "1.0"),
        signers(required = ["security-team"]),
        fresh_within_days(days = 90),
    ])
)]
pub fn gate_release_verified(version: &str) -> Result<(), String> {
    println!("[GATE] Releasing {version} — security policy attested");
    Ok(())
}

// ============================================================================
// Main: show both patterns
// ============================================================================

fn main() {
    println!("=== antigen-category example ===");
    println!();
    println!("Pattern 1: FunctionalCorrectness — NanInCleanedOutput");
    println!("  Vulnerable: DataCleaner::clean_values() (no NaN guard)");
    println!("  Defended:   DataCleanerSafe::clean_values_safe() (witnessed by test)");
    println!("  Witness:    test_clean_values_no_nan — a test *executes* the defense");
    println!();
    println!("Pattern 2: SubstrateAlignment — UnsignedSecurityPolicy");
    println!("  Vulnerable: gate_release_unverified() (assumes policy signed)");
    println!("  Defended:   gate_release_verified() (requires = signers(...))");
    println!("  Witness:    cargo antigen audit evaluates .attest/ sidecar record");
    println!();
    println!("The quick test: can a *test* execute the thing you're defending?");
    println!("  NaN guard: yes → FunctionalCorrectness + witness=");
    println!("  Policy sign-off: no → SubstrateAlignment + requires=");
    println!();
    println!("Filter by category:");
    println!("  cargo run --bin cargo-antigen -- antigen scan --root antigen/examples \\");
    println!("      --category substrate-alignment");
}