89 lines
4.2 KiB
Rust
89 lines
4.2 KiB
Rust
#![forbid(unsafe_code)]
|
|
//! # epiphany-testkit
|
|
//!
|
|
//! The Epiphany conformance testkit: the cross-cutting harness that proves the
|
|
//! architecture works end to end. This is Agent F's crate per
|
|
//! `spec/QUICKSTART.md`:
|
|
//!
|
|
//! > Builds: property-test generators for every public type in A through E; the
|
|
//! > canonical round-trip harness; the CRDT convergence harness; the
|
|
//! > equivocation harness; the crash-recovery harness (Agent D's gate); the
|
|
//! > manifest selection harness. … This is the agent whose work prevents you
|
|
//! > from finding regressions in weeks 12+. … The harness is the architecture's
|
|
//! > tripwire.
|
|
//!
|
|
//! ## What is real
|
|
//!
|
|
//! The QUICKSTART charters Agent F to *"build against A and stubs for the
|
|
//! others."* All five implementation crates have now shipped — Agents A
|
|
//! ([`epiphany_determinism`]), B ([`epiphany_core`]), C ([`epiphany_ops`]),
|
|
//! D ([`epiphany_bundle`]), and E ([`epiphany_layout_ir`]) — so **every**
|
|
//! harness drives the real crate:
|
|
//!
|
|
//! * [`roundtrip`] — the canonical round-trip harness, driving every
|
|
//! `CanonicalEncode`/`CanonicalDecode` type in A and B, the real
|
|
//! [`epiphany_bundle::Manifest`]/header/superblock encode/decode, and a real
|
|
//! [`epiphany_ops::MaterializedState`] serialize→load→deserialize→re-serialize
|
|
//! cycle through the bundle (v0 acceptance criterion 4).
|
|
//! * [`bundle_harness`] — the crash-recovery gate (criterion 2) and the
|
|
//! manifest-selection harness, driving the real [`epiphany_bundle`] through
|
|
//! its public API and re-exporting its in-crate gates.
|
|
//! * [`convergence`] — the CRDT convergence and reduction-determinism harnesses
|
|
//! (criteria 1 and 5), driving the real [`epiphany_ops::OperationSet`] /
|
|
//! [`epiphany_ops::canonical_reduction_order`] / reduce, and re-exporting Agent
|
|
//! C's own determinism gate.
|
|
//! * [`equivocation`] — the equivocation harness (criterion 3), driving the real
|
|
//! [`epiphany_ops::OperationSlot`] model and re-exporting Agent C's gate.
|
|
//!
|
|
//! * [`layout_stub`] — the layout round-trip harness (criterion 6). Agent E
|
|
//! (`epiphany-layout-ir`, Chapters 7 & 9) has landed, so this module — once a
|
|
//! faithful in-tree stub — now re-exports the **real** IR types (the four IR
|
|
//! stages, the `TimeAxisModel` tagged enum, the provenance back-references,
|
|
//! the engraving-decision and vertical-band models, the glyph-catalog
|
|
//! identity, and the real stub solver) behind the same
|
|
//! [`layout_stub::round_trip`] signature. The provenance-preservation contract
|
|
//! it asserts is implemented and tested inside `epiphany-layout-ir`; the
|
|
//! testkit retains deterministic generators for E's public types and exercises
|
|
//! the real round-trip on its hand-off fixtures. (The module name is kept so
|
|
//! the harness entry point stays `layout_stub::round_trip`.)
|
|
//!
|
|
//! ## Determinism of the harness itself
|
|
//!
|
|
//! Per Appendix D §"Randomness", platform entropy must never enter canonical
|
|
//! state — and the testkit goes further: **no platform entropy enters the
|
|
//! harness at all.** Every generator draws from the seeded [`rng::Rng`]
|
|
//! (a wrapper over Agent A's vendored SplitMix64), so any failing case
|
|
//! reproduces exactly from its seed. The harnesses are the strict
|
|
//! single-threaded baseline every accelerated implementation must reproduce
|
|
//! bit-for-bit.
|
|
//!
|
|
//! ## The six v0 acceptance criteria
|
|
//!
|
|
//! The QUICKSTART's six acceptance tests map onto this crate as follows; they
|
|
//! are asserted as integration tests in `tests/acceptance.rs` and runnable at
|
|
//! scale via `examples/conformance_suite.rs`.
|
|
//!
|
|
//! | # | Criterion | Entry point |
|
|
//! |---|-----------|-------------|
|
|
//! | 1 | Convergence | [`convergence::assert_convergence`] |
|
|
//! | 2 | Crash safety | [`bundle_harness::run_crash_recovery`] |
|
|
//! | 3 | Equivocation | [`equivocation::assert_equivocation_order_independent`] |
|
|
//! | 4 | Canonical serialization stability | [`roundtrip::run_roundtrip_corpus`] |
|
|
//! | 5 | Reduction determinism | [`convergence::assert_reduction_determinism`] |
|
|
//! | 6 | Layout round-trip | [`layout_stub::round_trip`] |
|
|
|
|
pub mod rng;
|
|
|
|
pub mod fixtures;
|
|
pub mod generators;
|
|
pub mod roundtrip;
|
|
|
|
pub mod convergence;
|
|
pub mod equivocation;
|
|
|
|
pub mod bundle_harness;
|
|
|
|
pub mod layout_stub;
|
|
|
|
pub use rng::Rng;
|