engenho_diff/lib.rs
1//! # engenho-diff
2//!
3//! A differential integration-test harness: detect **where engenho's
4//! Kubernetes surface diverges from k3s**, using a live k3s cluster as the
5//! reference oracle. This is engenho's mechanical path to CNCF conformance —
6//! every divergence it surfaces is a typed, attributed gap to close.
7//!
8//! ## Shape
9//!
10//! One authored set of typed [`Operation`]s is fired at TWO [`DiffTarget`]s
11//! — engenho ([`EngenhoTarget`], booted in-process) and k3s
12//! ([`K3sTarget`], the oracle) — and each paired [`Observation`] is folded
13//! through a typed [`Normalizer`] into a recursive JSON differ that yields a
14//! typed [`Verdict`]:
15//!
16//! ```text
17//! ┌──────────── Operation ────────────┐
18//! ▼ ▼
19//! EngenhoTarget.raw() K3sTarget.raw()
20//! │ │
21//! Observation ───┐ ┌─── Observation
22//! ▼ ▼
23//! Normalizer (mask volatile fields)
24//! │ │
25//! ▼ ▼
26//! cotejo::diff_observations → Verdict
27//! { Parity | Divergent(..) | ReferenceUnreachable }
28//! ```
29//!
30//! [`Verdict::Parity`] is proof-by-absence — no code outside this crate can
31//! construct one (★★ UNREPRESENTABILITY). [`JsonPath`] is a typed value,
32//! rendered only through `Display` (★★ TYPED EMISSION).
33
34pub mod cotejo;
35pub mod normalize;
36pub mod observe;
37pub mod op;
38pub mod path;
39pub mod target;
40pub mod verdict;
41
42pub use cotejo::{diff_observations, run, run_strict};
43pub use normalize::{Mask, Normalizer, volatile_meta};
44pub use observe::{DiffError, HttpMethod, Observation};
45pub use op::{OpKind, Operation, RestPath};
46pub use path::{JsonPath, PathSeg};
47pub use target::{DiffTarget, EngenhoTarget, K3sTarget};
48pub use verdict::{Divergence, Gvr, ParityWitness, Severity, Side, StatusCause, Verb, Verdict};