Crate prism_verify

Expand description

prism_verify — the Prism replay façade.

This crate is the Rust realization of the prism-verify container of the Prism system specified by the UOR-Framework wiki. It is a thin verification surface that re-exports certify_from_trace from prism, Certified from prism, and the trace and certificate wire-format types from uor_foundation. Verification consumers depend on this crate alone, never on the runtime; this preserves TC-06 (no application-author infrastructure) and minimizes the verifier’s attack surface and dependency footprint.

The façade is genuinely thin: every item in this crate’s API is a re-export of an item defined elsewhere in the architecture. The crate adds zero behavior; it adds a namespace.

The crate is published to crates.io under the package name uor-prism-verify; the library name is prism_verify so that import paths track wiki nomenclature (use prism_verify::certify_from_trace;).

§See also

Wiki: 01 Introduction and Goals
Wiki: 03 Context and Scope
Wiki: 05 Building Block View § Whitebox prism-verify
Wiki: 06 Runtime View § Scenario 2: Trace-Replay Verification
Wiki: 12 Glossary § Term Definitions
Wiki: Conceptual Model § SD3 Verification — OPM statement of the verification process this façade enacts
Wiki: Conceptual Model § SD5 Distribute And Run — Verification is the second of the two user-handled processes in SD5 (after Execution); this façade is the user-side surface that realizes it

§Constraints

This crate is normatively bound by:

TC-05 — replayability of the principal data path without invoking author deciders or hash functions; this façade is the user-facing surface of that property
TC-06 — verification proceeds without any application-author infrastructure
QS-03 — local verification: this crate is the dependency verification consumers pin, exposing nothing beyond the surface needed to re-derive a Certified<GroundingCertificate> from a Trace
QS-05 — replay equivalence: the round-trip produces a bit-identical certificate
ADR-019 — this façade exposes the anamorphism dual to pipeline::run’s catamorphism. Together the catamorphism + anamorphism form Prism’s hylomorphism (per ADR-021), and the trace is the round-trip witness object

§C4 placement

Container prism-verify (Level 2) of the Prism system. Its components mirror the Level 2 building blocks described in the wiki’s Building Block View § Whitebox prism-verify: the re-export of certify_from_trace, the re-export of Certified, and the re-exports of foundation wire-format types.

§Behavior

// Given: an empty Trace (the simplest deterministic verifier input)
// When:  certify_from_trace is invoked on it
// Then:  the structural validator rejects with ReplayError::EmptyTrace,
//        proving that the façade's certify_from_trace, ReplayError,
//        and Trace re-exports are wired correctly together
use prism_verify::{certify_from_trace, ReplayError, Trace};
let trace: Trace = Trace::empty();
assert!(matches!(certify_from_trace(&trace), Err(ReplayError::EmptyTrace)));

Re-exports§

pub use prism;
pub use uor_foundation;

Structs§

Certified: v0.2.2 W11: parametric carrier for any foundation-supplied certificate. Replaces the v0.2.1 per-class shim duplication. The Certificate trait is sealed and the _private field prevents external construction; only the foundation’s pipeline / resolver paths produce Certified<C> values.
ContentFingerprint: Sealed parametric content fingerprint. Wraps a fixed-capacity byte buffer of FP_MAX bytes plus the active width in bytes. FP_MAX is the const-generic that carries the application’s selected HostBounds::FINGERPRINT_MAX_BYTES (default = 32, matching DefaultHostBounds). The active width is set by the producing Hasher::OUTPUT_BYTES and recorded so downstream can distinguish “this is a 128-bit fingerprint” from “this is a 256-bit fingerprint” without inspecting trailing zeros. Equality is bit-equality on the full buffer + width tag, so two fingerprints from different hashers (different widths) are never equal even if their leading bytes happen to coincide. This prevents silent collisions when downstream consumers mix substrate hashers.
DefaultHostBounds: Canonical default impl of HostBounds. Carries the values the default const-generic on Hasher, ContentFingerprint, and Trace resolves to. Use as type B = uor_foundation::DefaultHostBounds; to inherit; replace with a downstream marker struct when an application needs different capacity bounds (per ADR-018, this is the only sanctioned way to vary).
GroundingCertificate: Sealed shim for cert:GroundingCertificate. Produced by GroundingAwareResolver.
Trace: Fixed-capacity derivation trace. Holds up to TR_MAX events inline; no heap. Produced by Derivation::replay() and consumed by uor-foundation-verify. TR_MAX is the const-generic that carries the application’s selected <MyBounds as HostBounds>::TRACE_MAX_EVENTS; the default const-generic resolves to DefaultHostBounds’s 256. Carries witt_level_bits and content_fingerprint so verify_trace can reconstruct the source GroundingCertificate via structural- validation + fingerprint passthrough (no hash recomputation).
TraceEvent: v0.2.2 Phase E: a single event in a derivation Trace. Fixed-size event; content-addressed so Trace replays are stable across builds. The verifier in uor-foundation-verify (Phase H) reconstructs the witness chain by walking a Trace iterator.

Enums§

ReplayError: v0.2.2 T5: errors emitted by the trace-replay re-derivation path.

Constants§

TRACE_REPLAY_FORMAT_VERSION: Trace wire-format identifier. Per the wiki’s ADR-018, wire-format identifiers are explicitly carved out of the HostBounds rule because cross-implementation interop requires a single shared format identifier. Increment when the layout changes (event ordering, trailing fields, primitive-op discriminant table, certificate-kind discriminant table). Pinned by the rust/trace_byte_layout_pinned conformance validator.
WIKI: Canonical URL of the UOR-Framework wiki, the normative source for the Prism architecture realized by this façade.

Traits§

HostBounds: Substitution axis 2 of 3 (per the UOR-Framework wiki). Carries every capacity bound that varies along the principal data path: the fingerprint output width range, the trace event-count ceiling, and the algebraic-level bit-width ceiling. The application author selects an impl; the foundation (this trait) declares the contract. Per the wiki’s ADR-018, the architecture admits no capacity bound outside HostBounds. Foundation’s Hasher, ContentFingerprint, and Trace are const-generic over their capacity bounds; applications populate each type’s const-generic with <MyBounds as HostBounds>::CONST. There are no free-standing capacity constants on the public surface — collapsing the substitution axis is exactly what ADR-018 rejects.

Functions§

certify_from_trace: Re-derive the Certified<GroundingCertificate> that the foundation grounding path produced for the source unit. Validates the trace’s structural invariants (monotonic, contiguous step indices; no zero targets; no None slots in the populated prefix) and re-packages the trace’s stored ContentFingerprint and witt_level_bits into a fresh certificate. The verifier does NOT invoke a hash function: the fingerprint is data carried by the Trace, computed at mint time by the consumer-supplied Hasher and passed through unchanged.