Crate antigen

Expand description

§Antigen

Structural memory of failure-classes for Rust. Make implicit immunity explicit.

This crate is the main library entry point for the antigen ecosystem. It re-exports the five attribute macros from antigen-macros and provides the scan and audit modules consumed by cargo-antigen and available for custom integrations (CI harnesses, IDE plugins, programmatic audit tooling).

See https://github.com/antigen-rs/antigen for the project documentation, design substrate, and origin story.

§Quick start

Antigen meets you at any discipline level (per ADR-009 — adoption gradient). Layer 1 — the minimum-viable form — has just name and fingerprint:

use antigen::antigen;

#[antigen(
    name = "panicking-in-drop",
    fingerprint = r#"
        item = impl,
        any_of([
            body_contains_macro("panic"),
            body_contains_macro("unreachable"),
        ])
    "#,
)]
pub struct PanickingInDrop;

Layer 2 enriches with family, summary, and references:

#[antigen(
    name = "panicking-in-drop",
    family = "boundary-violation",
    fingerprint = r#"item = impl, body_contains_macro("panic")"#,
    summary = "Drop impls must not panic; panic-during-unwind aborts the process.",
    references = ["https://doc.rust-lang.org/std/ops/trait.Drop.html#panics"],
)]
pub struct PanickingInDrop;

Mark code as vulnerable:

use antigen::presents;

#[presents(PanickingInDrop)]
impl Drop for MyType { ... }

Defend the site by registering a witness (ADR-029 — immunity is observed, not declared). Put #[defended_by] on the test that is the defense:

use antigen::defended_by;

#[test]
#[defended_by(PanickingInDrop)]
fn drop_never_panics() {
    // exercise the Drop path and assert no panic
}

When the evidence lives outside the code (a ratified doc, a pinned dep, a signed discipline), attach it on the site instead with a substrate-witness predicate: #[presents(PanickingInDrop, requires = ratified_doc(...))]. (The old #[immune] form is deprecated — it declared a verdict with no witness cargo antigen audit could validate; see immune.)

Then run cargo antigen scan to find unaddressed presentations and cargo antigen audit to observe each site’s defense. See the examples/ directory for worked examples covering each macro family plus inheritance, tolerance, phantom-type witnesses, and the marked-unknown markers.

§Macros (re-exported from `antigen-macros`)

#[antigen(...)] — declare a named failure-class with a structural fingerprint (ADR-001, ADR-010)
#[presents(...)] — mark code as exhibiting a failure-class’s structural pattern (vulnerability declaration)
#[defended_by(...)] — register a test/proptest as the observed code-tier witness for a failure-class (ADR-029; the canonical way to defend a site)
#[immune(...)] — deprecated (ADR-029): declared immunity at the vulnerable site without a witness audit could validate. Use #[defended_by] on a test, or #[presents(..., requires = ...)] for substrate evidence, instead.
#[descended_from(...)] — propagate antigen markers through an inheritance chain (ADR-013, ADR-018 §propagation)
#[antigen_tolerance(...)] — document an intentional opt-out with rationale on the page (ADR-011)

§Deferred-Defense Family (ADR-023)

#[anergy(...)] — deferred-but-muted posture; until REQUIRED; aging escalation via anergy-active / anergy-stale hints
#[immunosuppress(...)] — surgical silencing with hard duration cap enforced at parse time (A4)
#[poxparty(...)] — intentional exposure with structural compile-time isolation (A3; antigen-poxparty feature)
#[orient(...)] — see-also context; lightest-weight deferred-defense primitive; all fields optional

§Modules

scan — workspace scanner. scan_workspace() walks .rs files, extracts antigen-related attributes, builds scan::ScanReport. Includes the propagation walk (ADR-018) for #[descended_from] chains and the cross-crate enumeration path (ADR-017) via enumerate_dep_crate_roots().
audit — witness validation. audit() consumes a scan::ScanReport and validates each immunity’s witness identifier against the workspace’s function index, producing per-witness audit::WitnessStatus + audit::WitnessTier classifications (ADR-001 Amendment 1, ADR-013).

§What this crate IS

The five core attribute macros (re-exported from antigen-macros)
The scan module: scanner library + propagation walk + cross-crate enumeration
The audit module: witness resolution + tier classification
Future: witness module with phantom-type witness templates
Future: stdlib feature flag re-exporting antigen-stdlib’s seed antigens

§What this crate is NOT

Not a documentation system. Documentation drifts; antigen declarations are checked by tooling.
Not a replacement for tests, lints, deprecations, or formal verification. Antigen composes existing Rust ecosystem tools into a coherent immune-system surface (ADR-002).
Not a logic-bug catcher. Antigen catches failure-classes that have been named; it does not detect novel logic errors.

See the docs/expedition/ directory in the repository for the full design intent.

Re-exports§

pub use convergent::SeedKind;
pub use convergent::WitnessClass;
pub use mucosal::MucosalKind;
pub use vcs::ServerSideEnforcementMode;
pub use vcs::TriageDecision;
pub use category::AntigenCategory;

Modules§

audit: Witness validation and immunity audit.
category: Antigen-Category taxonomy (ADR-028).
convergent: Public types for the Convergent-Evidence Family (ADR-024).
finding: The ONE typed Finding / event schema (ADR-039 §C — sole owner).
mucosal: Public types for the Mucosal Boundary Family (ADR-027 + Amendment 1).
pipeline: The pipeline coordinator (ADR-036) — the single-conductor host.
scan: Source-AST scanner for antigen declarations.
stdlib: Stdlib of curated, ratified antigen declarations.
supply_chain: Runtime substrate for the Supply-Chain Defense Family (ADR-025).
vcs: Public types for the VCS-Information-Loss Family (ADR-026).
vcs_witness: Substrate-witness evaluators for the VCS-Information-Loss Family (ADR-026 §M6).

Attribute Macros§

adcc: Declare ADCC (antibody-dependent cellular cytotoxicity) — multi- mechanism convergent defense.
anergy: Declare an anergy posture: deferred-but-muted, with required time-bound and aging escalation.
antigen: Declare a named failure-class with a structural fingerprint.
antigen_generates: Declare that a proc-macro / macro_rules emits code presenting an antigen. Per ADR-014 — the fifth core macro.
antigen_tolerance: Mark a site as a deliberate, non-vulnerable match against an antigen’s fingerprint. Per ADR-011.
aura: #[aura(trigger = "...")] — the light marked-unknown (low magnitude): “something may be off here, can’t name it, check later.” (ADR-041.)
biopsy: Declare a deep-investigation work-need at a sub-site (ADR-033 S1 Role-workflow).
chronic: Declare a low-level persistent failure-class signal (ADR-024 recurrent family).
clonal: Declare iterated witness evaluation (B-cell clonal expansion analog).
crossreactive: Declare crossreactive coverage — one defense covers related antigens.
crystallize: Declare the promotion event from itch-cluster to formal failure-class (ADR-024 recurrent family).
culture: Declare a time-boxed test/observation work-need (ADR-033 S4 Frame-only).
ddx: Declare a differential-diagnosis work-need: a set of alternatives to rule out (ADR-033 S2 Elimination).
defended_by: Register a code-tier witness: declare that this test/proptest function defends against a known failure-class (ADR-029).
descended_from: Propagate antigen markers from a parent function/type/method to a derived one.
diagnostic: Declare convergent multi-modality evidence backing a defense claim.
dread: #[dread(trigger = "...")] — high magnitude, low existence-certainty (the angor animi corner): “something is wrong here, I can’t name it, look now.” Scared-but-unsure. (ADR-041.)
igg: Declare IgG-class affinity-matured evidence (re-attestation history).
immune: Declare immunity to a known antigen, backed by evidence that proves it.
immunosuppress: Declare surgical immunosuppression with a hard duration cap enforced at parse time.
itch: Declare a below-threshold noticing of a pattern (ADR-024 recurrent family).
monoclonal: Declare monoclonal evidence — single independent lineage.
mucosal: Declare a trust boundary is actively defended at this site (ADR-027).
mucosal_delegate: Declare boundary discipline is delegated to a named handler (ADR-027 + Amendment 1).
mucosal_tolerant: Declare a boundary is INTENTIONALLY permitted — active tolerance, not absence of defense (ADR-027 Amendment 1 Change 6).
orient: Declare an orientation period — a time-bounded acknowledged absence of immunity.
panel: Declare a battery of work-needs to be filled + reviewed at this site (ADR-033 S1 Role-workflow).
polyclonal: Declare polyclonal evidence — many independent lineages converge.
poxparty: Declare an intentional exposure exercise with structural isolation.
presents: Mark code as exhibiting a known antigen’s structural pattern (vulnerability declaration).
quarantine: Declare an isolated region under a time-boxed hold (ADR-033 S4 Frame-only).
recurrence_anchor: Declare formal recognition of a cross-substrate recurrent failure-class (ADR-024 recurrent family).
red_flag: #[red_flag(trigger = "...")] — high existence-certainty, unnameable.
refer: Declare a referral of work to an external owner (ADR-033 S1 Role-workflow).
rx: Declare a prescribed treatment work-need at this site (ADR-033 S1 Role-workflow).
saturate: Declare a saturation-evidence contribution toward a recurrence threshold (ADR-024 recurrent family).
strand: Declare a thread of related noticing across substrates (ADR-024 recurrent family).
triage: Declare a re-validatable priority ordering over code sites (ADR-033 S3 Ordering).
triage_commit: Declare a rollback-as-triage commit: classify system state + commit to rollback within a tight time-bound (ADR-026 §Rollback-as-triage).

Crate antigen

Crate antigen Copy item path

§Antigen

§Quick start

§Macros (re-exported from antigen-macros)

§Deferred-Defense Family (ADR-023)

§Modules

§What this crate IS

§What this crate is NOT

Re-exports§

Modules§

Attribute Macros§

Crate antigen

§Macros (re-exported from `antigen-macros`)