Crate engenho_diff 

engenho-diff

A differential integration-test harness: detect where engenho’s Kubernetes surface diverges from k3s, using a live k3s cluster as the reference oracle. This is engenho’s mechanical path to CNCF conformance — every divergence it surfaces is a typed, attributed gap to close.

Shape

One authored set of typed Operations is fired at TWO DiffTargets — engenho (EngenhoTarget, booted in-process) and k3s (K3sTarget, the oracle) — and each paired Observation is folded through a typed Normalizer into a recursive JSON differ that yields a typed Verdict:

           ┌──────────── Operation ────────────┐
           ▼                                    ▼
    EngenhoTarget.raw()                  K3sTarget.raw()
           │                                    │
        Observation ───┐          ┌─── Observation
                       ▼          ▼
                   Normalizer (mask volatile fields)
                       │          │
                       ▼          ▼
                cotejo::diff_observations  → Verdict
                { Parity | Divergent(..) | ReferenceUnreachable }

Verdict::Parity is proof-by-absence — no code outside this crate can construct one (★★ UNREPRESENTABILITY). JsonPath is a typed value, rendered only through Display (★★ TYPED EMISSION).

Re-exports

pub use cotejo::diff_observations;

pub use cotejo::run;

pub use cotejo::run_strict;

pub use junkyo::DivergenceClass;

pub use junkyo::Expect;

pub use junkyo::MatrixReport;

pub use junkyo::Outcome;

pub use junkyo::adjudicate;

pub use normalize::Mask;

pub use normalize::Normalizer;

pub use normalize::volatile_meta;

pub use observe::DiffError;

pub use observe::HttpMethod;

pub use observe::Observation;

pub use op::OpKind;

pub use op::Operation;

pub use op::RestPath;

pub use oracle::ORACLE_KUBECONFIG_ENV;

pub use oracle::ORACLE_KUBECONFIG_FALLBACK;

pub use oracle::OracleKubeconfig;

pub use oracle::OracleUnreachable;

pub use oracle::OracleUnresolved;

pub use path::JsonPath;

pub use path::PathSeg;

pub use target::DiffTarget;

pub use target::EngenhoTarget;

pub use target::K3sTarget;

pub use verdict::Divergence;

pub use verdict::Gvr;

pub use verdict::ParityWitness;

pub use verdict::Severity;

pub use verdict::Side;

pub use verdict::StatusCause;

pub use verdict::Verb;

pub use verdict::Verdict;

Modules

butai

The OCI-runtime differential — butai (or any runtime) against a reference binary, over the same bundle.

cotejo

cotejo (Portuguese: a collation / side-by-side comparison) — the diff interpreter. It executes an Operation against two DiffTargets and folds the paired Observations through the Normalizer into a typed Verdict. The core differ (diff_observations) is a pure function over two Observations + a Normalizer — unit-testable with zero clusters.

junkyo

junkyo (準拠) — adherence to a standard

normalize

The Normalizer — a typed, ordered list of Masks that strips legitimately-varying fields BEFORE the differ runs. Without it every diff is ~100% noise (uid/resourceVersion/timestamps differ on every object). The masks are auditable: strict mode (see crate::cotejo) re-diffs the RAW objects and re-reports whatever a mask suppressed as Severity::Cosmetic, so a mask can never silently hide a real gap.

observe

The response half of the harness — a typed Observation captured from a DiffTarget, plus the HttpMethod verb and the DiffError failure taxonomy.

op

The stimulus half of the harness — a typed Operation fired at both targets. Constructors build the K8s REST path from typed segments (a RestPath, rendered via Display), never a format!()-composed URL.

oracle

Where the reference oracle lives, and what to say when it does not answer.

path

JsonPath — the typed coordinate a divergence lives at.

target

The two ends of the diff — the DiffTarget trait and its concrete impls: EngenhoTarget (booted in-process, the r7 seam) and K3sTarget (the live reference oracle from a kubeconfig).

verdict

The typed verdict + divergence taxonomy.