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 butai;
35pub mod cotejo;
36pub mod junkyo;
37pub mod normalize;
38pub mod observe;
39pub mod op;
40pub mod oracle;
41pub mod path;
42pub mod target;
43pub mod verdict;
44
45pub use cotejo::{diff_observations, run, run_strict};
46pub use junkyo::{DivergenceClass, Expect, MatrixReport, Outcome, adjudicate};
47pub use normalize::{Mask, Normalizer, volatile_meta};
48pub use observe::{DiffError, HttpMethod, Observation};
49pub use op::{OpKind, Operation, RestPath};
50pub use oracle::{
51 ORACLE_KUBECONFIG_ENV, ORACLE_KUBECONFIG_FALLBACK, OracleKubeconfig, OracleUnreachable,
52 OracleUnresolved,
53};
54pub use path::{JsonPath, PathSeg};
55pub use target::{DiffTarget, EngenhoTarget, K3sTarget};
56pub use verdict::{Divergence, Gvr, ParityWitness, Severity, Side, StatusCause, Verb, Verdict};