uor_foundation/

pipeline.rs

// @generated by uor-crate from uor-ontology — do not edit manually

//! Reduction Pipeline — no_std in-process driver.
//!
//! Backs `Certify::certify` on every resolver façade and (re-exported
//! via the macros crate) the `uor_ground!` macro's compile-time pipeline.
//!
//! The driver implements the full reduction pipeline per
//! `external/ergonomics-spec.md` §3.3 and §4: 6 preflight checks,
//! 7 reduction stages, 4 resolver backends, real 2-SAT and Horn-SAT
//! deciders, fragment classifier, content-addressed unit-ids.
//!
//! Every entry point is ontology-driven: IRIs, stage order, and
//! dispatch-table rules are baked in at codegen time from the
//! ontology graph. Adding a new preflight check or resolver is a
//! pure ontology edit.

use crate::enforcement::{
    BindingEntry, BindingsTable, CompileTime, CompileUnit, CompileUnitBuilder,
    CompletenessCertificate, ConstrainedTypeInput, GenericImpossibilityWitness, Grounded,
    GroundingCertificate, InhabitanceCertificate, InhabitanceImpossibilityWitness,
    LeaseDeclaration, LeaseDeclarationBuilder, LiftChainCertificate, MultiplicationCertificate,
    ParallelDeclarationBuilder, PipelineFailure, ShapeViolation, StreamDeclarationBuilder, Term,
    Validated,
};
use crate::ViolationKind;
use crate::WittLevel;

/// Zero-based preflight check order read from `reduction:PreflightCheck`
/// individuals at codegen time. `BudgetSolvencyCheck` MUST be index 0 per
/// `reduction:preflightOrder` — enforced by the ontology, not here.
pub const PREFLIGHT_CHECK_IRIS: &[&str] = &[
    "https://uor.foundation/reduction/BudgetSolvencyCheck",
    "https://uor.foundation/reduction/FeasibilityCheck",
    "https://uor.foundation/reduction/DispatchCoverageCheck",
    "https://uor.foundation/reduction/PackageCoherenceCheck",
    "https://uor.foundation/reduction/PreflightTiming",
    "https://uor.foundation/reduction/RuntimeTiming",
];

/// Seven reduction stages in declared order, sourced from
/// `reduction:ReductionStep` individuals.
pub const REDUCTION_STAGE_IRIS: &[&str] = &[
    "https://uor.foundation/reduction/stage_initialization",
    "https://uor.foundation/reduction/stage_declare",
    "https://uor.foundation/reduction/stage_factorize",
    "https://uor.foundation/reduction/stage_resolve",
    "https://uor.foundation/reduction/stage_attest",
    "https://uor.foundation/reduction/stage_extract",
    "https://uor.foundation/reduction/stage_convergence",
];

/// Phase 17: maximum number of `i64` coefficients an `Affine`
/// constraint can carry. Stable-Rust const evaluation cannot allocate a
/// new `&'static [i64]` at compile time, so `Affine` stores a fixed-
/// size buffer + an active prefix length. Aligned with the foundation's
/// 8-wide capacity caps (`MAX_BETTI_DIMENSION` / `JACOBIAN_MAX_SITES` /
/// `NERVE_CONSTRAINTS_CAP`).
/// Wiki ADR-037: the canonical source of truth for this cap is
/// [`HostBounds::AFFINE_COEFFS_MAX`]; this `pub const` is a foundation-
/// internal convenience alias derived from [`DefaultHostBounds`] for
/// stable-Rust array-size positions. Applications declaring a custom
/// `HostBounds` impl read `<MyBounds as HostBounds>::AFFINE_COEFFS_MAX`
/// at instantiation sites instead.
pub const AFFINE_MAX_COEFFS: usize =
    <crate::DefaultHostBounds as crate::HostBounds>::AFFINE_COEFFS_MAX;

/// Phase 17: maximum number of `LeafConstraintRef` conjuncts a
/// `Conjunction` can carry. Same reasoning as `AFFINE_MAX_COEFFS`.
/// Wiki ADR-037: alias of [`HostBounds::CONJUNCTION_TERMS_MAX`] via
/// [`DefaultHostBounds`].
pub const CONJUNCTION_MAX_TERMS: usize =
    <crate::DefaultHostBounds as crate::HostBounds>::CONJUNCTION_TERMS_MAX;

/// Opaque constraint reference carried by `ConstrainedTypeShape` impls.
/// Variants mirror the v0.2.1 `type:Constraint` enumerated subclasses
/// (retained as ergonomic aliases for the SAT pipeline) plus the v0.2.2
/// Phase D parametric form (`Bound` / `Conjunction`) which references
/// `BoundConstraint` kinds by their (observable, shape) IRIs. The
/// `SatClauses` variant carries a compact 2-SAT/Horn-SAT clause list.
/// **Phase 17 — fixed-array Affine and Conjunction.** The pre-Phase-17
/// `Affine { coefficients: &'static [i64], … }` and
/// `Conjunction { conjuncts: &'static [ConstraintRef] }` have been
/// replaced with fixed-capacity arrays of length `AFFINE_MAX_COEFFS`
/// and `CONJUNCTION_MAX_TERMS` respectively. Stable Rust const
/// evaluation can build these inline; the SDK macros now support
/// Affine-bearing operands without falling back to the
/// `Site { position: u32::MAX }` sentinel. `Conjunction` is depth-
/// limited to one level: its conjuncts are `LeafConstraintRef`
/// (every variant of `ConstraintRef` except `Conjunction` itself).
#[derive(Debug, Clone, Copy)]
#[non_exhaustive]
#[allow(clippy::large_enum_variant)]
pub enum ConstraintRef {
    /// `type:ResidueConstraint`: value ≡ residue (mod modulus).
    Residue { modulus: u64, residue: u64 },
    /// `type:HammingConstraint`: bit-weight bound.
    Hamming { bound: u32 },
    /// `type:DepthConstraint`: site-depth bound.
    Depth { min: u32, max: u32 },
    /// `type:CarryConstraint`: carry-bit relation.
    Carry { site: u32 },
    /// `type:SiteConstraint`: site-position restriction.
    Site { position: u32 },
    /// `type:AffineConstraint`: affine relation over sites.
    /// `coefficients[..coefficient_count as usize]` is the active prefix;
    /// trailing entries are unused and must be zero.
    Affine {
        coefficients: [i64; AFFINE_MAX_COEFFS],
        coefficient_count: u32,
        bias: i64,
    },
    /// Opaque clause list for 2-SAT / Horn-SAT inputs.
    /// Each clause is a slice of `(variable_index, is_negated)`.
    SatClauses {
        clauses: &'static [&'static [(u32, bool)]],
        num_vars: u32,
    },
    /// v0.2.2 Phase D / T2.2 (cleanup): parametric `BoundConstraint`
    /// kind reference. Selects an (observable, shape) pair from the
    /// closed Phase D catalogue. The args_repr string carries the
    /// kind-specific parameters in canonical form.
    Bound {
        observable_iri: &'static str,
        bound_shape_iri: &'static str,
        args_repr: &'static str,
    },
    /// v0.2.2 Phase D / T2.2 (cleanup): parametric `Conjunction`.
    /// Phase 17: depth-limited to one level — conjuncts are
    /// `LeafConstraintRef` (every `ConstraintRef` variant except
    /// `Conjunction` itself). Active prefix is
    /// `conjuncts[..conjunct_count as usize]`.
    Conjunction {
        conjuncts: [LeafConstraintRef; CONJUNCTION_MAX_TERMS],
        conjunct_count: u32,
    },
    /// ADR-057 substrate amendment: bounded recursive shape reference.
    /// The constraint references another `ConstrainedTypeShape` by its
    /// content-addressed IRI, with an explicit `descent_bound` bounding
    /// the recursion at evaluation time. The runtime ψ_1 NerveResolver
    /// expands the reference to the registered shape's `CONSTRAINTS`
    /// array, decrementing `descent_bound` on each `Recurse` traversal;
    /// when `descent_bound = 0` the recursion bottoms out (no further
    /// constraints at that depth).
    ///
    /// The const-time admission path defers `Recurse` to runtime per
    /// ADR-057's deferral rule (parallel to ADR-049's
    /// `LandauerCost` deferral).
    Recurse {
        shape_iri: &'static str,
        descent_bound: u32,
    },
}

/// `ConstraintRef` minus the recursive `Conjunction` variant — the
/// element type of `ConstraintRef::Conjunction.conjuncts`. Phase 17
/// caps Conjunction depth at one level; deeper structure must be
/// flattened by the constructor.
#[derive(Debug, Clone, Copy)]
#[non_exhaustive]
pub enum LeafConstraintRef {
    /// See [`ConstraintRef::Residue`].
    Residue { modulus: u64, residue: u64 },
    /// See [`ConstraintRef::Hamming`].
    Hamming { bound: u32 },
    /// See [`ConstraintRef::Depth`].
    Depth { min: u32, max: u32 },
    /// See [`ConstraintRef::Carry`].
    Carry { site: u32 },
    /// See [`ConstraintRef::Site`].
    Site { position: u32 },
    /// See [`ConstraintRef::Affine`].
    Affine {
        coefficients: [i64; AFFINE_MAX_COEFFS],
        coefficient_count: u32,
        bias: i64,
    },
    /// See [`ConstraintRef::SatClauses`].
    SatClauses {
        clauses: &'static [&'static [(u32, bool)]],
        num_vars: u32,
    },
    /// See [`ConstraintRef::Bound`].
    Bound {
        observable_iri: &'static str,
        bound_shape_iri: &'static str,
        args_repr: &'static str,
    },
    /// See [`ConstraintRef::Recurse`] (ADR-057).
    Recurse {
        shape_iri: &'static str,
        descent_bound: u32,
    },
}

/// Project a non-`Conjunction` [`ConstraintRef`] into the
/// [`LeafConstraintRef`] subtype. Returns a `Site { position: 0 }`
/// placeholder if `self` is `Conjunction` (the only non-injective
/// case); callers should flatten Conjunction structure before
/// calling.
impl ConstraintRef {
    /// Phase 17 — leaf projection.
    #[inline]
    #[must_use]
    pub const fn as_leaf(self) -> LeafConstraintRef {
        match self {
            ConstraintRef::Residue { modulus, residue } => {
                LeafConstraintRef::Residue { modulus, residue }
            }
            ConstraintRef::Hamming { bound } => LeafConstraintRef::Hamming { bound },
            ConstraintRef::Depth { min, max } => LeafConstraintRef::Depth { min, max },
            ConstraintRef::Carry { site } => LeafConstraintRef::Carry { site },
            ConstraintRef::Site { position } => LeafConstraintRef::Site { position },
            ConstraintRef::Affine {
                coefficients,
                coefficient_count,
                bias,
            } => LeafConstraintRef::Affine {
                coefficients,
                coefficient_count,
                bias,
            },
            ConstraintRef::SatClauses { clauses, num_vars } => {
                LeafConstraintRef::SatClauses { clauses, num_vars }
            }
            ConstraintRef::Bound {
                observable_iri,
                bound_shape_iri,
                args_repr,
            } => LeafConstraintRef::Bound {
                observable_iri,
                bound_shape_iri,
                args_repr,
            },
            ConstraintRef::Conjunction { .. } => LeafConstraintRef::Site { position: 0 },
            ConstraintRef::Recurse {
                shape_iri,
                descent_bound,
            } => LeafConstraintRef::Recurse {
                shape_iri,
                descent_bound,
            },
        }
    }
}

impl LeafConstraintRef {
    /// Phase 17 — embed a leaf into the parent `ConstraintRef` enum.
    #[inline]
    #[must_use]
    pub const fn into_constraint(self) -> ConstraintRef {
        match self {
            LeafConstraintRef::Residue { modulus, residue } => {
                ConstraintRef::Residue { modulus, residue }
            }
            LeafConstraintRef::Hamming { bound } => ConstraintRef::Hamming { bound },
            LeafConstraintRef::Depth { min, max } => ConstraintRef::Depth { min, max },
            LeafConstraintRef::Carry { site } => ConstraintRef::Carry { site },
            LeafConstraintRef::Site { position } => ConstraintRef::Site { position },
            LeafConstraintRef::Affine {
                coefficients,
                coefficient_count,
                bias,
            } => ConstraintRef::Affine {
                coefficients,
                coefficient_count,
                bias,
            },
            LeafConstraintRef::SatClauses { clauses, num_vars } => {
                ConstraintRef::SatClauses { clauses, num_vars }
            }
            LeafConstraintRef::Bound {
                observable_iri,
                bound_shape_iri,
                args_repr,
            } => ConstraintRef::Bound {
                observable_iri,
                bound_shape_iri,
                args_repr,
            },
            LeafConstraintRef::Recurse {
                shape_iri,
                descent_bound,
            } => ConstraintRef::Recurse {
                shape_iri,
                descent_bound,
            },
        }
    }
}

/// Workstream E (target §1.5 + §4.7, v0.2.2 closure): crate-internal
/// dispatch helper that maps every `ConstraintRef` variant to its
/// canonical CNF clause encoding. No variant returns `None` — the
/// closed six-kind set is fully executable.
/// - `SatClauses`: pass-through of the caller's CNF.
/// - `Residue` / `Carry` / `Depth` / `Hamming` / `Site`: direct-
///   decidable at preflight; encoder emits an empty clause list
///   (trivially SAT — unsatisfiable ones are rejected earlier).
/// - `Affine`: single-row consistency check over Z/(2^n)Z; emits
///   empty clauses when consistent, a 2-literal contradiction
///   sentinel (forcing 2-SAT rejection) when not.
/// - `Bound`: parametric form; emits empty clauses (per-bound-kind
///   decision procedures consume the observable/bound-shape IRIs).
/// - `Conjunction`: satisfiable iff every conjunct is satisfiable.
#[inline]
#[must_use]
#[allow(dead_code)]
pub(crate) const fn encode_constraint_to_clauses(
    constraint: &ConstraintRef,
) -> Option<&'static [&'static [(u32, bool)]]> {
    const EMPTY: &[&[(u32, bool)]] = &[];
    const UNSAT_SENTINEL: &[&[(u32, bool)]] = &[&[(0u32, false)], &[(0u32, true)]];
    match constraint {
        ConstraintRef::SatClauses { clauses, .. } => Some(clauses),
        ConstraintRef::Residue { .. }
        | ConstraintRef::Carry { .. }
        | ConstraintRef::Depth { .. }
        | ConstraintRef::Hamming { .. }
        | ConstraintRef::Site { .. } => Some(EMPTY),
        ConstraintRef::Affine {
            coefficients,
            coefficient_count,
            bias,
        } => {
            if is_affine_consistent(coefficients, *coefficient_count, *bias) {
                Some(EMPTY)
            } else {
                Some(UNSAT_SENTINEL)
            }
        }
        ConstraintRef::Bound { .. } => Some(EMPTY),
        ConstraintRef::Conjunction {
            conjuncts,
            conjunct_count,
        } => {
            if conjunction_all_sat(conjuncts, *conjunct_count) {
                Some(EMPTY)
            } else {
                Some(UNSAT_SENTINEL)
            }
        }
        // ADR-057: Recurse defers to the runtime ψ_1 NerveResolver
        // which expands the referenced shape's constraints via the
        // shape-IRI registry. At preflight (const-eval) it carries no
        // CNF residue — the recursion is bounded, the unrolling occurs
        // at runtime against the registry.
        ConstraintRef::Recurse { .. } => Some(EMPTY),
    }
}

/// Workstream E: single-row consistency for `Affine { coefficients,
/// coefficient_count, bias }`. The constraint is
/// `sum(c_i) · x = bias (mod 2^n)`; when the coefficient sum is
/// zero the system is consistent iff bias is zero. Non-zero sums
/// are always consistent over Z/(2^n)Z for some `x` value. Iterates
/// only the active prefix `coefficients[..coefficient_count as usize]`.
#[inline]
#[must_use]
const fn is_affine_consistent(
    coefficients: &[i64; AFFINE_MAX_COEFFS],
    coefficient_count: u32,
    bias: i64,
) -> bool {
    let mut sum: i128 = 0;
    let count = coefficient_count as usize;
    let mut i = 0;
    while i < count && i < AFFINE_MAX_COEFFS {
        sum += coefficients[i] as i128;
        i += 1;
    }
    if sum == 0 {
        bias == 0
    } else {
        true
    }
}

/// Workstream E + Phase 17: satisfiability of a `Conjunction`.
/// Iterates only the active prefix `conjuncts[..conjunct_count as
/// usize]` and lifts each `LeafConstraintRef` back to a
/// `ConstraintRef` for re-encoding (the leaf form omits Conjunction,
/// so this terminates at depth 1).
#[inline]
#[must_use]
const fn conjunction_all_sat(
    conjuncts: &[LeafConstraintRef; CONJUNCTION_MAX_TERMS],
    conjunct_count: u32,
) -> bool {
    let count = conjunct_count as usize;
    let mut i = 0;
    while i < count && i < CONJUNCTION_MAX_TERMS {
        let lifted = conjuncts[i].into_constraint();
        match encode_constraint_to_clauses(&lifted) {
            Some([]) => {}
            _ => return false,
        }
        i += 1;
    }
    true
}

/// Declarative shape of a constrained type that can be admitted into the
/// reduction pipeline.
/// Downstream authors implement this trait on zero-sized marker types to
/// declare the `(IRI, SITE_COUNT, CONSTRAINTS)` triple of a custom
/// constrained type. The foundation admits shapes into the pipeline via
/// [`validate_constrained_type`] / [`validate_constrained_type_const`],
/// which run the full preflight (`preflight_feasibility` +
/// `preflight_package_coherence`) against `Self::CONSTRAINTS` before
/// returning a [`Validated`] wrapper.
/// Sealing of witness construction lives on [`Validated`] and [`Grounded`]
/// — only foundation admission functions mint either. Downstream is free
/// to implement `ConstrainedTypeShape` for arbitrary shape markers, but
/// cannot fabricate a `Validated<Self>` except through the admission path.
/// The `ConstraintRef` enum is `#[non_exhaustive]` from outside the crate,
/// so `CONSTRAINTS` can only cite foundation-closed constraint kinds.
/// # Example
/// ```
/// use uor_foundation::pipeline::{
///     ConstrainedTypeShape, ConstraintRef, validate_constrained_type,
/// };
/// pub struct MyShape;
/// impl ConstrainedTypeShape for MyShape {
///     const IRI: &'static str = "https://example.org/MyShape";
///     const SITE_COUNT: usize = 4;
///     const CONSTRAINTS: &'static [ConstraintRef] = &[
///         ConstraintRef::Residue { modulus: 7, residue: 3 },
///     ];
///     const CYCLE_SIZE: u64 = 7;  // ADR-032: 7 residues mod 7
/// }
/// let validated = validate_constrained_type(MyShape)
///     .expect("residue 3 mod 7 is admissible");
/// # let _ = validated;
/// ```
pub trait ConstrainedTypeShape {
    /// IRI of the ontology `type:ConstrainedType` instance this shape represents.
    const IRI: &'static str;
    /// Number of sites (fields) this constrained type carries.
    const SITE_COUNT: usize;
    /// Ontology-level `siteBudget`: count of data sites only,
    /// excluding bookkeeping introduced by composition (coproduct tag
    /// sites, etc.). Equals `SITE_COUNT` for leaf shapes and for
    /// shapes whose composition introduces no bookkeeping (products,
    /// cartesian products). Strictly less than `SITE_COUNT` for coproduct
    /// shapes and any shape whose `SITE_COUNT` includes inherited
    /// bookkeeping. Introduced by the Product/Coproduct Completion
    /// Amendment §4a; defaults to `SITE_COUNT` so pre-amendment
    /// shape impls remain valid without edits.
    const SITE_BUDGET: usize = Self::SITE_COUNT;
    /// Per-site constraint list. Empty means unconstrained.
    const CONSTRAINTS: &'static [ConstraintRef];
    /// ADR-032: cardinality of the shape's value-set (the cycle
    /// structure of the shape under the substrate's discrete-clock
    /// model). Used by the `prism_model!` macro to lower `first_admit`
    /// (closure-body grammar G16) to the correct descent measure.
    /// Conventions:
    /// - Witt-level shapes: `1u64 << WITT_LEVEL_BITS` (W8 = 256, W16 =
    ///   65536, W32 = 4294967296). Levels above W63 saturate to `u64::MAX`.
    /// - `partition_product` factors: `cycle_size_product` of factor
    ///   CYCLE_SIZEs (saturating-multiply).
    /// - `partition_coproduct` summands: `cycle_size_coproduct` (saturating
    ///   add + 1 for the discriminant).
    /// - `cartesian_product_shape` (homogeneous power): factor's CYCLE_SIZE
    ///   raised to `SITE_COUNT` (saturating).
    /// - The foundation-sanctioned identity `ConstrainedTypeInput` has
    ///   `CYCLE_SIZE = 1` (single-element shape).
    const CYCLE_SIZE: u64;
}

/// ADR-032: saturating multiply for `partition_product`'s CYCLE_SIZE.
/// Returns `u64::MAX` on overflow.
#[inline]
#[must_use]
pub const fn cycle_size_product(a: u64, b: u64) -> u64 {
    a.saturating_mul(b)
}

/// ADR-032: saturating add + 1 (for the discriminant) for
/// `partition_coproduct`'s CYCLE_SIZE. Returns `u64::MAX` on overflow.
#[inline]
#[must_use]
pub const fn cycle_size_coproduct(a: u64, b: u64) -> u64 {
    a.saturating_add(b).saturating_add(1)
}

/// ADR-032: saturating power for `cartesian_product_shape`'s CYCLE_SIZE
/// (homogeneous power: factor.CYCLE_SIZE^SITE_COUNT). Returns `u64::MAX`
/// on overflow.
#[inline]
#[must_use]
pub const fn cycle_size_power(base: u64, exp: usize) -> u64 {
    let mut result: u64 = 1;
    let mut i: usize = 0;
    while i < exp {
        result = result.saturating_mul(base);
        i += 1;
    }
    result
}

impl ConstrainedTypeShape for ConstrainedTypeInput {
    const IRI: &'static str = "https://uor.foundation/type/ConstrainedType";
    const SITE_COUNT: usize = 0;
    const CONSTRAINTS: &'static [ConstraintRef] = &[];
    const CYCLE_SIZE: u64 = 1;
}

/// ADR-033 G20: factor-field directory carried by every
/// `partition_product`-shaped type. The closure-body grammar's
/// field-access form (`<expr>.<index>` or `<expr>.<field_name>`)
/// lowers via this trait at proc-macro expansion time.
/// Foundation-sanctioned identity `ConstrainedTypeInput` has zero
/// fields (it is a leaf shape). The SDK macros `partition_product!`,
/// `product_shape!`, and `cartesian_product_shape!` emit the impl.
pub trait PartitionProductFields: ConstrainedTypeShape {
    /// Per-factor `(byte_offset, byte_length)` pairs in declaration
    /// order. Length is the same as `FIELD_NAMES.len()`.
    const FIELDS: &'static [(u32, u32)];
    /// Per-factor names. Empty string `""` for positional-only
    /// `partition_product!(Name, A, B)` emissions; non-empty for
    /// named-field `partition_product!(Name, lhs: A, rhs: B)` form.
    /// Length matches `FIELDS.len()`.
    const FIELD_NAMES: &'static [&'static str];
    /// Linear search returning the field index whose `FIELD_NAMES`
    /// entry equals `name`, or `usize::MAX` if not found. Delegates
    /// to the free `const fn` [`field_index_by_name_in`] so the
    /// result is usable inside const-eval contexts on stable Rust
    /// 1.83 (where const trait methods are unavailable).
    #[must_use]
    fn field_index_by_name(name: &str) -> usize {
        field_index_by_name_in(Self::FIELD_NAMES, name)
    }
}

/// ADR-033 G3/G4: const-fn factor-name lookup. The SDK proc-macro
/// emits const-eval calls to this helper to resolve a named-field
/// access against the source type's `FIELD_NAMES`. On stable Rust
/// 1.83 a free `const fn` is the substitute for a `const fn`
/// trait method. Returns `usize::MAX` for not-found so the result
/// is usable directly inside `const` array indexing.
#[must_use]
pub const fn field_index_by_name_in(names: &[&'static str], name: &str) -> usize {
    let nb = name.as_bytes();
    let mut i = 0usize;
    while i < names.len() {
        let nb_i = names[i].as_bytes();
        if nb_i.len() == nb.len() {
            let mut j = 0usize;
            let mut matched = true;
            while j < nb.len() {
                if nb_i[j] != nb[j] {
                    matched = false;
                    break;
                }
                j += 1;
            }
            if matched {
                return i;
            }
        }
        i += 1;
    }
    usize::MAX
}

impl PartitionProductFields for ConstrainedTypeInput {
    const FIELDS: &'static [(u32, u32)] = &[];
    const FIELD_NAMES: &'static [&'static str] = &[];
}

/// ADR-033 G20 chained-field access support: maps a
/// `partition_product`-shaped type's positional factor index to
/// the factor's static type. The `prism_model!` proc-macro emits
/// a chain of `Term::ProjectField` projections by walking this
/// trait, naming each next source type as
/// `<PrevTy as PartitionProductFactor<I>>::Factor`.
/// `partition_product!`, `product_shape!`, and
/// `cartesian_product_shape!` emit one impl per factor index.
pub trait PartitionProductFactor<const INDEX: usize>: PartitionProductFields {
    /// The static type of the factor at position `INDEX`.
    type Factor: ConstrainedTypeShape;
}

/// ADR-030: maximum number of axes a single application's
/// `AxisTuple` may carry. Foundation-fixed (parallel to
/// `FOLD_UNROLL_THRESHOLD` and `UNFOLD_MAX_ITERATIONS`).
pub const MAX_AXIS_TUPLE_ARITY: usize = 8;

/// ADR-030: the upper byte ceiling on a single axis kernel's
/// output. Sized to `TERM_VALUE_MAX_BYTES` so any kernel can
/// populate a `TermValue` directly.
/// Wiki ADR-037: alias of [`HostBounds::AXIS_OUTPUT_BYTES_MAX`] via
/// [`DefaultHostBounds`]. Applications declaring a custom `HostBounds`
/// read `<MyBounds as HostBounds>::AXIS_OUTPUT_BYTES_MAX` instead.
pub const AXIS_OUTPUT_BYTES_CEILING: usize =
    <crate::DefaultHostBounds as crate::HostBounds>::AXIS_OUTPUT_BYTES_MAX;

/// Wiki ADR-037: foundation-internal alias of
/// [`HostBounds::NERVE_OUTPUT_BYTES_MAX`] via [`DefaultHostBounds`] — the ψ_1 (Nerve)
/// resolver output byte-buffer ceiling.
pub const NERVE_OUTPUT_BYTES_MAX: usize =
    <crate::DefaultHostBounds as crate::HostBounds>::NERVE_OUTPUT_BYTES_MAX;

/// Wiki ADR-037: foundation-internal alias of
/// [`HostBounds::CHAIN_COMPLEX_OUTPUT_BYTES_MAX`] via [`DefaultHostBounds`] — the ψ_2 (ChainComplex)
/// resolver output byte-buffer ceiling.
pub const CHAIN_COMPLEX_OUTPUT_BYTES_MAX: usize =
    <crate::DefaultHostBounds as crate::HostBounds>::CHAIN_COMPLEX_OUTPUT_BYTES_MAX;

/// Wiki ADR-037: foundation-internal alias of
/// [`HostBounds::HOMOLOGY_GROUPS_OUTPUT_BYTES_MAX`] via [`DefaultHostBounds`] — the ψ_3 (HomologyGroups)
/// resolver output byte-buffer ceiling.
pub const HOMOLOGY_GROUPS_OUTPUT_BYTES_MAX: usize =
    <crate::DefaultHostBounds as crate::HostBounds>::HOMOLOGY_GROUPS_OUTPUT_BYTES_MAX;

/// Wiki ADR-037: foundation-internal alias of
/// [`HostBounds::COCHAIN_COMPLEX_OUTPUT_BYTES_MAX`] via [`DefaultHostBounds`] — the ψ_5 (CochainComplex)
/// resolver output byte-buffer ceiling.
pub const COCHAIN_COMPLEX_OUTPUT_BYTES_MAX: usize =
    <crate::DefaultHostBounds as crate::HostBounds>::COCHAIN_COMPLEX_OUTPUT_BYTES_MAX;

/// Wiki ADR-037: foundation-internal alias of
/// [`HostBounds::COHOMOLOGY_GROUPS_OUTPUT_BYTES_MAX`] via [`DefaultHostBounds`] — the ψ_6 (CohomologyGroups)
/// resolver output byte-buffer ceiling.
pub const COHOMOLOGY_GROUPS_OUTPUT_BYTES_MAX: usize =
    <crate::DefaultHostBounds as crate::HostBounds>::COHOMOLOGY_GROUPS_OUTPUT_BYTES_MAX;

/// Wiki ADR-037: foundation-internal alias of
/// [`HostBounds::POSTNIKOV_TOWER_OUTPUT_BYTES_MAX`] via [`DefaultHostBounds`] — the ψ_7 (PostnikovTower)
/// resolver output byte-buffer ceiling.
pub const POSTNIKOV_TOWER_OUTPUT_BYTES_MAX: usize =
    <crate::DefaultHostBounds as crate::HostBounds>::POSTNIKOV_TOWER_OUTPUT_BYTES_MAX;

/// Wiki ADR-037: foundation-internal alias of
/// [`HostBounds::HOMOTOPY_GROUPS_OUTPUT_BYTES_MAX`] via [`DefaultHostBounds`] — the ψ_8 (HomotopyGroups)
/// resolver output byte-buffer ceiling.
pub const HOMOTOPY_GROUPS_OUTPUT_BYTES_MAX: usize =
    <crate::DefaultHostBounds as crate::HostBounds>::HOMOTOPY_GROUPS_OUTPUT_BYTES_MAX;

/// Wiki ADR-037: foundation-internal alias of
/// [`HostBounds::K_INVARIANTS_OUTPUT_BYTES_MAX`] via [`DefaultHostBounds`] — the ψ_9 (KInvariants)
/// resolver output byte-buffer ceiling.
pub const K_INVARIANTS_OUTPUT_BYTES_MAX: usize =
    <crate::DefaultHostBounds as crate::HostBounds>::K_INVARIANTS_OUTPUT_BYTES_MAX;

/// ADR-055: substrate-Term verb body discipline. Every axis impl carries a
/// substrate-Term decomposition the catamorphism can fuse through. Sealed —
/// the `axis!` SDK macro per ADR-030 + ADR-052 emits the impl.
/// The catamorphism's `Term::AxisInvocation` fold-rule reads this slice and
/// recursively folds the body with the evaluated kernel inputs in scope (per
/// ADR-029, amended by ADR-055). The `body_arena()` slice is a static const,
/// not wire-format state, so the on-wire shape of `Term::AxisInvocation` is
/// preserved.
pub trait SubstrateTermBody: __sdk_seal::Sealed {
    /// The Term arena the kernel decomposes to. Empty slice signals a
    /// primitive-fast-path axis whose body the implementation may evaluate
    /// through `dispatch_kernel` directly per ADR-055's optional fast-path.
    fn body_arena() -> &'static [crate::enforcement::Term];
}

/// ADR-030: a substrate-extension axis. Each `axis!`-declared
/// trait extends this trait via the SDK macro's blanket impl,
/// which emits per-method `KERNEL_*` const ids and the
/// `dispatch_kernel` router into a fixed-capacity byte buffer.
/// Per ADR-055, every `AxisExtension` impl also satisfies the
/// [`SubstrateTermBody`] supertrait — its kernel decomposes to a
/// substrate-Term slice the catamorphism walks structurally. This makes
/// the Fold-Fusion Principle (ADR-054) universal across every axis impl,
/// not just the standard library's canonical impls.
/// The catamorphism's `Term::AxisInvocation` fold-rule reads the
/// axis position from the application's `AxisTuple` impl, walks the
/// axis's `SubstrateTermBody::body_arena()` recursively with the
/// evaluated kernel input bound in scope, and emits the resulting
/// `TermValue`. The legacy `dispatch_kernel` fast-path remains as an
/// optimization for axes whose body is empty (primitive fast-path).
pub trait AxisExtension: SubstrateTermBody {
    /// ADR-017 content address of this axis trait. The SDK macro
    /// derives this from the trait name and method signatures.
    const AXIS_ADDRESS: &'static str;
    /// Maximum bytes any kernel of this axis returns.
    const MAX_OUTPUT_BYTES: usize;
    /// Dispatch the kernel identified by `kernel_id` against the
    /// evaluated input bytes. The implementation copies the kernel's
    /// output into `out` and returns the written length.
    /// # Errors
    /// Returns [`crate::enforcement::ShapeViolation`] when the
    /// kernel id is unrecognised or the input does not satisfy the
    /// kernel's shape contract.
    fn dispatch_kernel(
        kernel_id: u32,
        input: &[u8],
        out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation>;
}

/// ADR-030: a tuple of `AxisExtension`-implementing types selected
/// by the application. The catamorphism's `Term::AxisInvocation`
/// fold-rule calls `dispatch` to route the invocation to the right
/// axis position.
/// Foundation provides tuple impls for arities 1 through
/// [`MAX_AXIS_TUPLE_ARITY`].
pub trait AxisTuple {
    /// Number of axes carried in this tuple.
    const AXIS_COUNT: usize;
    /// Maximum kernel-output byte width across all axes in this tuple.
    const MAX_OUTPUT_BYTES: usize;
    /// Dispatch a kernel against the axis at `axis_index`. Returns
    /// the kernel's output bytes (length up to [`MAX_OUTPUT_BYTES`]).
    /// # Errors
    /// Returns [`crate::enforcement::ShapeViolation`] when `axis_index`
    /// is out of range or the axis dispatcher rejects the input.
    fn dispatch(
        axis_index: u32,
        kernel_id: u32,
        input: &[u8],
        out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation>;
    /// ADR-055: return the substrate-Term body arena for the axis at
    /// `axis_index`. An empty slice means the axis is a primitive-fast-path
    /// axis whose body is byte-output-equivalent to its `dispatch_kernel`.
    /// Non-empty slices carry the recursive-fold decomposition the
    /// catamorphism walks per ADR-055's amended `Term::AxisInvocation`
    /// fold-rule.
    fn body_arena_at(axis_index: u32) -> &'static [crate::enforcement::Term];
}

/// ADR-030 blanket: every [`crate::enforcement::Hasher`] is
/// automatically an [`AxisTuple`] of arity 1 — the canonical
/// hash axis at position 0, kernel id 0.
impl<H: crate::enforcement::Hasher> AxisTuple for H {
    const AXIS_COUNT: usize = 1;
    const MAX_OUTPUT_BYTES: usize = <H as crate::enforcement::Hasher>::OUTPUT_BYTES;
    fn dispatch(
        axis_index: u32,
        kernel_id: u32,
        input: &[u8],
        out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        if axis_index != 0 || kernel_id != 0 {
            return Err(crate::enforcement::ShapeViolation {
                shape_iri: "https://uor.foundation/axis/HasherBlanket",
                constraint_iri: "https://uor.foundation/axis/HasherBlanket/canonicalDispatch",
                property_iri: "https://uor.foundation/axis/axisIndex",
                expected_range: "https://uor.foundation/axis/CanonicalHashAxis",
                min_count: 0,
                max_count: 1,
                kind: crate::ViolationKind::ValueCheck,
            });
        }
        let mut hasher = <H as crate::enforcement::Hasher>::initial();
        hasher = hasher.fold_bytes(input);
        let digest = hasher.finalize();
        let n_max = <H as crate::enforcement::Hasher>::OUTPUT_BYTES;
        let n = if n_max > out.len() { out.len() } else { n_max };
        let mut i = 0;
        while i < n {
            out[i] = digest[i];
            i += 1;
        }
        Ok(n)
    }
    // ADR-055: the Hasher blanket axis is a primitive-fast-path axis. Its
    // body is byte-output-equivalent to `fold_bytes` ∘ `finalize`; the
    // empty arena signals to the catamorphism that dispatch_kernel is the
    // canonical evaluation strategy here.
    fn body_arena_at(_axis_index: u32) -> &'static [crate::enforcement::Term] {
        &[]
    }
}

/// ADR-030: 1-tuple AxisTuple impl — applications selecting a single axis.
impl<A0: AxisExtension> AxisTuple for (A0,) {
    const AXIS_COUNT: usize = 1;
    const MAX_OUTPUT_BYTES: usize = <A0 as AxisExtension>::MAX_OUTPUT_BYTES;
    fn dispatch(
        axis_index: u32,
        kernel_id: u32,
        input: &[u8],
        out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        match axis_index {
            0 => <A0 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            _ => Err(crate::enforcement::ShapeViolation {
                shape_iri: "https://uor.foundation/pipeline/AxisTupleShape",
                constraint_iri: "https://uor.foundation/pipeline/AxisTupleShape/inBounds",
                property_iri: "https://uor.foundation/pipeline/axisIndex",
                expected_range: "https://uor.foundation/pipeline/AxisIndex",
                min_count: 0,
                max_count: 1,
                kind: crate::ViolationKind::ValueCheck,
            }),
        }
    }
    fn body_arena_at(axis_index: u32) -> &'static [crate::enforcement::Term] {
        match axis_index {
            0 => <A0 as SubstrateTermBody>::body_arena(),
            _ => &[],
        }
    }
}

/// ADR-030: 2-tuple AxisTuple impl.
impl<A0: AxisExtension, A1: AxisExtension> AxisTuple for (A0, A1) {
    const AXIS_COUNT: usize = 2;
    const MAX_OUTPUT_BYTES: usize = {
        let a = <A0 as AxisExtension>::MAX_OUTPUT_BYTES;
        let b = <A1 as AxisExtension>::MAX_OUTPUT_BYTES;
        if a > b {
            a
        } else {
            b
        }
    };
    fn dispatch(
        axis_index: u32,
        kernel_id: u32,
        input: &[u8],
        out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        match axis_index {
            0 => <A0 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            1 => <A1 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            _ => Err(crate::enforcement::ShapeViolation {
                shape_iri: "https://uor.foundation/pipeline/AxisTupleShape",
                constraint_iri: "https://uor.foundation/pipeline/AxisTupleShape/inBounds",
                property_iri: "https://uor.foundation/pipeline/axisIndex",
                expected_range: "https://uor.foundation/pipeline/AxisIndex",
                min_count: 0,
                max_count: 2,
                kind: crate::ViolationKind::ValueCheck,
            }),
        }
    }
    fn body_arena_at(axis_index: u32) -> &'static [crate::enforcement::Term] {
        match axis_index {
            0 => <A0 as SubstrateTermBody>::body_arena(),
            1 => <A1 as SubstrateTermBody>::body_arena(),
            _ => &[],
        }
    }
}

/// ADR-030: 3-tuple AxisTuple impl.
impl<A0: AxisExtension, A1: AxisExtension, A2: AxisExtension> AxisTuple for (A0, A1, A2) {
    const AXIS_COUNT: usize = 3;
    const MAX_OUTPUT_BYTES: usize = {
        let a0 = <A0 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a1 = <A1 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a2 = <A2 as AxisExtension>::MAX_OUTPUT_BYTES;
        let mut m = a0;
        if a1 > m {
            m = a1;
        }
        if a2 > m {
            m = a2;
        }
        m
    };
    fn dispatch(
        axis_index: u32,
        kernel_id: u32,
        input: &[u8],
        out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        match axis_index {
            0 => <A0 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            1 => <A1 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            2 => <A2 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            _ => Err(crate::enforcement::ShapeViolation {
                shape_iri: "https://uor.foundation/pipeline/AxisTupleShape",
                constraint_iri: "https://uor.foundation/pipeline/AxisTupleShape/inBounds",
                property_iri: "https://uor.foundation/pipeline/axisIndex",
                expected_range: "https://uor.foundation/pipeline/AxisIndex",
                min_count: 0,
                max_count: 3,
                kind: crate::ViolationKind::ValueCheck,
            }),
        }
    }
    fn body_arena_at(axis_index: u32) -> &'static [crate::enforcement::Term] {
        match axis_index {
            0 => <A0 as SubstrateTermBody>::body_arena(),
            1 => <A1 as SubstrateTermBody>::body_arena(),
            2 => <A2 as SubstrateTermBody>::body_arena(),
            _ => &[],
        }
    }
}

/// ADR-030: 4-tuple AxisTuple impl.
impl<A0: AxisExtension, A1: AxisExtension, A2: AxisExtension, A3: AxisExtension> AxisTuple
    for (A0, A1, A2, A3)
{
    const AXIS_COUNT: usize = 4;
    const MAX_OUTPUT_BYTES: usize = {
        let a0 = <A0 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a1 = <A1 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a2 = <A2 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a3 = <A3 as AxisExtension>::MAX_OUTPUT_BYTES;
        let mut m = a0;
        if a1 > m {
            m = a1;
        }
        if a2 > m {
            m = a2;
        }
        if a3 > m {
            m = a3;
        }
        m
    };
    fn dispatch(
        axis_index: u32,
        kernel_id: u32,
        input: &[u8],
        out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        match axis_index {
            0 => <A0 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            1 => <A1 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            2 => <A2 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            3 => <A3 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            _ => Err(crate::enforcement::ShapeViolation {
                shape_iri: "https://uor.foundation/pipeline/AxisTupleShape",
                constraint_iri: "https://uor.foundation/pipeline/AxisTupleShape/inBounds",
                property_iri: "https://uor.foundation/pipeline/axisIndex",
                expected_range: "https://uor.foundation/pipeline/AxisIndex",
                min_count: 0,
                max_count: 4,
                kind: crate::ViolationKind::ValueCheck,
            }),
        }
    }
    fn body_arena_at(axis_index: u32) -> &'static [crate::enforcement::Term] {
        match axis_index {
            0 => <A0 as SubstrateTermBody>::body_arena(),
            1 => <A1 as SubstrateTermBody>::body_arena(),
            2 => <A2 as SubstrateTermBody>::body_arena(),
            3 => <A3 as SubstrateTermBody>::body_arena(),
            _ => &[],
        }
    }
}

/// ADR-030: 5-tuple AxisTuple impl.
impl<
        A0: AxisExtension,
        A1: AxisExtension,
        A2: AxisExtension,
        A3: AxisExtension,
        A4: AxisExtension,
    > AxisTuple for (A0, A1, A2, A3, A4)
{
    const AXIS_COUNT: usize = 5;
    const MAX_OUTPUT_BYTES: usize = {
        let a0 = <A0 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a1 = <A1 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a2 = <A2 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a3 = <A3 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a4 = <A4 as AxisExtension>::MAX_OUTPUT_BYTES;
        let mut m = a0;
        if a1 > m {
            m = a1;
        }
        if a2 > m {
            m = a2;
        }
        if a3 > m {
            m = a3;
        }
        if a4 > m {
            m = a4;
        }
        m
    };
    fn dispatch(
        axis_index: u32,
        kernel_id: u32,
        input: &[u8],
        out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        match axis_index {
            0 => <A0 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            1 => <A1 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            2 => <A2 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            3 => <A3 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            4 => <A4 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            _ => Err(crate::enforcement::ShapeViolation {
                shape_iri: "https://uor.foundation/pipeline/AxisTupleShape",
                constraint_iri: "https://uor.foundation/pipeline/AxisTupleShape/inBounds",
                property_iri: "https://uor.foundation/pipeline/axisIndex",
                expected_range: "https://uor.foundation/pipeline/AxisIndex",
                min_count: 0,
                max_count: 5,
                kind: crate::ViolationKind::ValueCheck,
            }),
        }
    }
    fn body_arena_at(axis_index: u32) -> &'static [crate::enforcement::Term] {
        match axis_index {
            0 => <A0 as SubstrateTermBody>::body_arena(),
            1 => <A1 as SubstrateTermBody>::body_arena(),
            2 => <A2 as SubstrateTermBody>::body_arena(),
            3 => <A3 as SubstrateTermBody>::body_arena(),
            4 => <A4 as SubstrateTermBody>::body_arena(),
            _ => &[],
        }
    }
}

/// ADR-030: 6-tuple AxisTuple impl.
impl<
        A0: AxisExtension,
        A1: AxisExtension,
        A2: AxisExtension,
        A3: AxisExtension,
        A4: AxisExtension,
        A5: AxisExtension,
    > AxisTuple for (A0, A1, A2, A3, A4, A5)
{
    const AXIS_COUNT: usize = 6;
    const MAX_OUTPUT_BYTES: usize = {
        let a0 = <A0 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a1 = <A1 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a2 = <A2 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a3 = <A3 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a4 = <A4 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a5 = <A5 as AxisExtension>::MAX_OUTPUT_BYTES;
        let mut m = a0;
        if a1 > m {
            m = a1;
        }
        if a2 > m {
            m = a2;
        }
        if a3 > m {
            m = a3;
        }
        if a4 > m {
            m = a4;
        }
        if a5 > m {
            m = a5;
        }
        m
    };
    fn dispatch(
        axis_index: u32,
        kernel_id: u32,
        input: &[u8],
        out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        match axis_index {
            0 => <A0 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            1 => <A1 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            2 => <A2 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            3 => <A3 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            4 => <A4 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            5 => <A5 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            _ => Err(crate::enforcement::ShapeViolation {
                shape_iri: "https://uor.foundation/pipeline/AxisTupleShape",
                constraint_iri: "https://uor.foundation/pipeline/AxisTupleShape/inBounds",
                property_iri: "https://uor.foundation/pipeline/axisIndex",
                expected_range: "https://uor.foundation/pipeline/AxisIndex",
                min_count: 0,
                max_count: 6,
                kind: crate::ViolationKind::ValueCheck,
            }),
        }
    }
    fn body_arena_at(axis_index: u32) -> &'static [crate::enforcement::Term] {
        match axis_index {
            0 => <A0 as SubstrateTermBody>::body_arena(),
            1 => <A1 as SubstrateTermBody>::body_arena(),
            2 => <A2 as SubstrateTermBody>::body_arena(),
            3 => <A3 as SubstrateTermBody>::body_arena(),
            4 => <A4 as SubstrateTermBody>::body_arena(),
            5 => <A5 as SubstrateTermBody>::body_arena(),
            _ => &[],
        }
    }
}

/// ADR-030: 7-tuple AxisTuple impl.
impl<
        A0: AxisExtension,
        A1: AxisExtension,
        A2: AxisExtension,
        A3: AxisExtension,
        A4: AxisExtension,
        A5: AxisExtension,
        A6: AxisExtension,
    > AxisTuple for (A0, A1, A2, A3, A4, A5, A6)
{
    const AXIS_COUNT: usize = 7;
    const MAX_OUTPUT_BYTES: usize = {
        let a0 = <A0 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a1 = <A1 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a2 = <A2 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a3 = <A3 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a4 = <A4 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a5 = <A5 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a6 = <A6 as AxisExtension>::MAX_OUTPUT_BYTES;
        let mut m = a0;
        if a1 > m {
            m = a1;
        }
        if a2 > m {
            m = a2;
        }
        if a3 > m {
            m = a3;
        }
        if a4 > m {
            m = a4;
        }
        if a5 > m {
            m = a5;
        }
        if a6 > m {
            m = a6;
        }
        m
    };
    fn dispatch(
        axis_index: u32,
        kernel_id: u32,
        input: &[u8],
        out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        match axis_index {
            0 => <A0 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            1 => <A1 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            2 => <A2 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            3 => <A3 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            4 => <A4 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            5 => <A5 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            6 => <A6 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            _ => Err(crate::enforcement::ShapeViolation {
                shape_iri: "https://uor.foundation/pipeline/AxisTupleShape",
                constraint_iri: "https://uor.foundation/pipeline/AxisTupleShape/inBounds",
                property_iri: "https://uor.foundation/pipeline/axisIndex",
                expected_range: "https://uor.foundation/pipeline/AxisIndex",
                min_count: 0,
                max_count: 7,
                kind: crate::ViolationKind::ValueCheck,
            }),
        }
    }
    fn body_arena_at(axis_index: u32) -> &'static [crate::enforcement::Term] {
        match axis_index {
            0 => <A0 as SubstrateTermBody>::body_arena(),
            1 => <A1 as SubstrateTermBody>::body_arena(),
            2 => <A2 as SubstrateTermBody>::body_arena(),
            3 => <A3 as SubstrateTermBody>::body_arena(),
            4 => <A4 as SubstrateTermBody>::body_arena(),
            5 => <A5 as SubstrateTermBody>::body_arena(),
            6 => <A6 as SubstrateTermBody>::body_arena(),
            _ => &[],
        }
    }
}

/// ADR-030: 8-tuple AxisTuple impl.
impl<
        A0: AxisExtension,
        A1: AxisExtension,
        A2: AxisExtension,
        A3: AxisExtension,
        A4: AxisExtension,
        A5: AxisExtension,
        A6: AxisExtension,
        A7: AxisExtension,
    > AxisTuple for (A0, A1, A2, A3, A4, A5, A6, A7)
{
    const AXIS_COUNT: usize = 8;
    const MAX_OUTPUT_BYTES: usize = {
        let a0 = <A0 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a1 = <A1 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a2 = <A2 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a3 = <A3 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a4 = <A4 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a5 = <A5 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a6 = <A6 as AxisExtension>::MAX_OUTPUT_BYTES;
        let a7 = <A7 as AxisExtension>::MAX_OUTPUT_BYTES;
        let mut m = a0;
        if a1 > m {
            m = a1;
        }
        if a2 > m {
            m = a2;
        }
        if a3 > m {
            m = a3;
        }
        if a4 > m {
            m = a4;
        }
        if a5 > m {
            m = a5;
        }
        if a6 > m {
            m = a6;
        }
        if a7 > m {
            m = a7;
        }
        m
    };
    fn dispatch(
        axis_index: u32,
        kernel_id: u32,
        input: &[u8],
        out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        match axis_index {
            0 => <A0 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            1 => <A1 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            2 => <A2 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            3 => <A3 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            4 => <A4 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            5 => <A5 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            6 => <A6 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            7 => <A7 as AxisExtension>::dispatch_kernel(kernel_id, input, out),
            _ => Err(crate::enforcement::ShapeViolation {
                shape_iri: "https://uor.foundation/pipeline/AxisTupleShape",
                constraint_iri: "https://uor.foundation/pipeline/AxisTupleShape/inBounds",
                property_iri: "https://uor.foundation/pipeline/axisIndex",
                expected_range: "https://uor.foundation/pipeline/AxisIndex",
                min_count: 0,
                max_count: 8,
                kind: crate::ViolationKind::ValueCheck,
            }),
        }
    }
    fn body_arena_at(axis_index: u32) -> &'static [crate::enforcement::Term] {
        match axis_index {
            0 => <A0 as SubstrateTermBody>::body_arena(),
            1 => <A1 as SubstrateTermBody>::body_arena(),
            2 => <A2 as SubstrateTermBody>::body_arena(),
            3 => <A3 as SubstrateTermBody>::body_arena(),
            4 => <A4 as SubstrateTermBody>::body_arena(),
            5 => <A5 as SubstrateTermBody>::body_arena(),
            6 => <A6 as SubstrateTermBody>::body_arena(),
            7 => <A7 as SubstrateTermBody>::body_arena(),
            _ => &[],
        }
    }
}

/// ADR-036: maximum number of resolvers a single application's
/// `ResolverTuple` may carry. Foundation-fixed at twice
/// [`MAX_AXIS_TUPLE_ARITY`] to accommodate ADR-035's eight
/// resolver-bound ψ-Term categories with eight headroom positions
/// for future ADR-013/TR-08 substrate amendments.
pub const MAX_RESOLVER_TUPLE_ARITY: usize = 16;

/// ADR-036: foundation-internal discriminator emitted by every
/// `Null<Category>Resolver` impl when the catamorphism's resolver-
/// bound ψ-Term fold-rule consults a resolver category whose
/// `ResolverTuple` accessor returns the foundation-Null impl. The
/// evaluator translates this into a `PipelineFailure::ShapeViolation`
/// carrying the `https://uor.foundation/resolver/RESOLVER_ABSENT`
/// shape IRI; ADR-022 D3 G9's `Term::Try` default-propagation handler
/// recovers it when the verb body wraps the ψ-Term.
pub const RESOLVER_ABSENT_DISCRIMINATOR: u8 = 0xff;

/// ADR-036: resolver-category enum identifying which resolver-bound
/// substrate operation each `ResolverTuple` position satisfies. Each
/// variant corresponds to one resolver-bound ψ-Term variant per
/// ADR-035; future ADR-013/TR-08 substrate amendments add variants.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ResolverCategory {
    /// ψ_1 — per-value bytes → SimplicialComplex (NerveResolver).
    Nerve,
    /// ψ_2 — SimplicialComplex → ChainComplex (ChainComplexResolver).
    ChainComplex,
    /// ψ_3 — ChainComplex → HomologyGroups (HomologyGroupResolver).
    HomologyGroup,
    /// ψ_5 — ChainComplex → CochainComplex (CochainComplexResolver).
    CochainComplex,
    /// ψ_6 — CochainComplex → CohomologyGroups (CohomologyGroupResolver).
    CohomologyGroup,
    /// ψ_7 — SimplicialComplex → PostnikovTower (PostnikovResolver).
    Postnikov,
    /// ψ_8 — PostnikovTower → HomotopyGroups (HomotopyGroupResolver).
    HomotopyGroup,
    /// ψ_9 — HomotopyGroups → KInvariants (KInvariantResolver).
    KInvariant,
}

/// ADR-036: tuple-of-bounded-types parameter on the model declaration
/// carrying application-provided resolver instances for the resolver-
/// bound ψ-Term variants per ADR-035. Sealed via
/// [`__sdk_seal::Sealed`]: only the SDK `resolver!` macro emits impls.
pub trait ResolverTuple: __sdk_seal::Sealed {
    /// Number of resolver positions in this tuple (bounded by `MAX_RESOLVER_TUPLE_ARITY`).
    const ARITY: usize;
    /// Resolver category at each tuple position.
    const CATEGORIES: &'static [ResolverCategory];
    /// ADR-057: the application's shape-IRI registry. ψ_1's NerveResolver impl
    /// expands `ConstraintRef::Recurse` references through this registry when
    /// computing N(C). Defaults to [`shape_iri_registry::EmptyShapeRegistry`]
    /// (foundation built-in registry only); applications declaring recursive
    /// shapes via the SDK `register_shape!` macro thread the marker type
    /// through their `resolver!`-declared ResolverTuple.
    type ShapeRegistry: crate::pipeline::shape_iri_registry::ShapeRegistryProvider;
}

/// Wiki ADR-041: zero-cost typed-coordinate carrier for ψ_1 output —
/// the simplicial-complex serialization produced by `NerveResolver::resolve`.
///
/// `#[repr(transparent)]` over `&'a [u8]`: layout identical to a byte
/// slice; the type wrapper is purely compile-time discrimination so
/// ψ-stage composition is type-checked at the resolver-impl boundary.
#[repr(transparent)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct SimplicialComplexBytes<'a>(pub &'a [u8]);

impl<'a> SimplicialComplexBytes<'a> {
    /// Borrow the underlying byte slice.
    #[must_use]
    pub fn as_bytes(&self) -> &[u8] {
        self.0
    }
    /// Length of the underlying byte slice.
    #[must_use]
    pub fn len(&self) -> usize {
        self.0.len()
    }
    /// Whether the underlying byte slice is empty.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }
}

/// Wiki ADR-041: zero-cost typed-coordinate carrier for ψ_2 output —
/// the chain-complex serialization produced by `ChainComplexResolver::resolve`.
///
/// `#[repr(transparent)]` over `&'a [u8]`: layout identical to a byte
/// slice; the type wrapper is purely compile-time discrimination so
/// ψ-stage composition is type-checked at the resolver-impl boundary.
#[repr(transparent)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct ChainComplexBytes<'a>(pub &'a [u8]);

impl<'a> ChainComplexBytes<'a> {
    /// Borrow the underlying byte slice.
    #[must_use]
    pub fn as_bytes(&self) -> &[u8] {
        self.0
    }
    /// Length of the underlying byte slice.
    #[must_use]
    pub fn len(&self) -> usize {
        self.0.len()
    }
    /// Whether the underlying byte slice is empty.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }
}

/// Wiki ADR-041: zero-cost typed-coordinate carrier for ψ_3 output —
/// the homology-groups serialization produced by `HomologyGroupResolver::resolve`.
///
/// `#[repr(transparent)]` over `&'a [u8]`: layout identical to a byte
/// slice; the type wrapper is purely compile-time discrimination so
/// ψ-stage composition is type-checked at the resolver-impl boundary.
#[repr(transparent)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct HomologyGroupsBytes<'a>(pub &'a [u8]);

impl<'a> HomologyGroupsBytes<'a> {
    /// Borrow the underlying byte slice.
    #[must_use]
    pub fn as_bytes(&self) -> &[u8] {
        self.0
    }
    /// Length of the underlying byte slice.
    #[must_use]
    pub fn len(&self) -> usize {
        self.0.len()
    }
    /// Whether the underlying byte slice is empty.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }
}

/// Wiki ADR-041: zero-cost typed-coordinate carrier for ψ_4 output —
/// the Betti-number tuple serialization produced by the resolver-free `Term::Betti` fold-rule (a byte projection of HomologyGroupsBytes).
///
/// `#[repr(transparent)]` over `&'a [u8]`: layout identical to a byte
/// slice; the type wrapper is purely compile-time discrimination so
/// ψ-stage composition is type-checked at the resolver-impl boundary.
#[repr(transparent)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct BettiNumbersBytes<'a>(pub &'a [u8]);

impl<'a> BettiNumbersBytes<'a> {
    /// Borrow the underlying byte slice.
    #[must_use]
    pub fn as_bytes(&self) -> &[u8] {
        self.0
    }
    /// Length of the underlying byte slice.
    #[must_use]
    pub fn len(&self) -> usize {
        self.0.len()
    }
    /// Whether the underlying byte slice is empty.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }
}

/// Wiki ADR-041: zero-cost typed-coordinate carrier for ψ_5 output —
/// the cochain-complex serialization produced by `CochainComplexResolver::resolve`.
///
/// `#[repr(transparent)]` over `&'a [u8]`: layout identical to a byte
/// slice; the type wrapper is purely compile-time discrimination so
/// ψ-stage composition is type-checked at the resolver-impl boundary.
#[repr(transparent)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct CochainComplexBytes<'a>(pub &'a [u8]);

impl<'a> CochainComplexBytes<'a> {
    /// Borrow the underlying byte slice.
    #[must_use]
    pub fn as_bytes(&self) -> &[u8] {
        self.0
    }
    /// Length of the underlying byte slice.
    #[must_use]
    pub fn len(&self) -> usize {
        self.0.len()
    }
    /// Whether the underlying byte slice is empty.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }
}

/// Wiki ADR-041: zero-cost typed-coordinate carrier for ψ_6 output —
/// the cohomology-groups serialization produced by `CohomologyGroupResolver::resolve`.
///
/// `#[repr(transparent)]` over `&'a [u8]`: layout identical to a byte
/// slice; the type wrapper is purely compile-time discrimination so
/// ψ-stage composition is type-checked at the resolver-impl boundary.
#[repr(transparent)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct CohomologyGroupsBytes<'a>(pub &'a [u8]);

impl<'a> CohomologyGroupsBytes<'a> {
    /// Borrow the underlying byte slice.
    #[must_use]
    pub fn as_bytes(&self) -> &[u8] {
        self.0
    }
    /// Length of the underlying byte slice.
    #[must_use]
    pub fn len(&self) -> usize {
        self.0.len()
    }
    /// Whether the underlying byte slice is empty.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }
}

/// Wiki ADR-041: zero-cost typed-coordinate carrier for ψ_7 output —
/// the Postnikov-tower serialization produced by `PostnikovResolver::resolve`.
///
/// `#[repr(transparent)]` over `&'a [u8]`: layout identical to a byte
/// slice; the type wrapper is purely compile-time discrimination so
/// ψ-stage composition is type-checked at the resolver-impl boundary.
#[repr(transparent)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct PostnikovTowerBytes<'a>(pub &'a [u8]);

impl<'a> PostnikovTowerBytes<'a> {
    /// Borrow the underlying byte slice.
    #[must_use]
    pub fn as_bytes(&self) -> &[u8] {
        self.0
    }
    /// Length of the underlying byte slice.
    #[must_use]
    pub fn len(&self) -> usize {
        self.0.len()
    }
    /// Whether the underlying byte slice is empty.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }
}

/// Wiki ADR-041: zero-cost typed-coordinate carrier for ψ_8 output —
/// the homotopy-groups serialization produced by `HomotopyGroupResolver::resolve`.
///
/// `#[repr(transparent)]` over `&'a [u8]`: layout identical to a byte
/// slice; the type wrapper is purely compile-time discrimination so
/// ψ-stage composition is type-checked at the resolver-impl boundary.
#[repr(transparent)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct HomotopyGroupsBytes<'a>(pub &'a [u8]);

impl<'a> HomotopyGroupsBytes<'a> {
    /// Borrow the underlying byte slice.
    #[must_use]
    pub fn as_bytes(&self) -> &[u8] {
        self.0
    }
    /// Length of the underlying byte slice.
    #[must_use]
    pub fn len(&self) -> usize {
        self.0.len()
    }
    /// Whether the underlying byte slice is empty.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }
}

/// Wiki ADR-041: zero-cost typed-coordinate carrier for ψ_9 output —
/// the κ-label byte serialization produced by `KInvariantResolver::resolve` — the canonical k-invariants-branch output (ADR-035) classifying the input's homotopy type up to weak equivalence.
///
/// `#[repr(transparent)]` over `&'a [u8]`: layout identical to a byte
/// slice; the type wrapper is purely compile-time discrimination so
/// ψ-stage composition is type-checked at the resolver-impl boundary.
#[repr(transparent)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct KInvariantsBytes<'a>(pub &'a [u8]);

impl<'a> KInvariantsBytes<'a> {
    /// Borrow the underlying byte slice.
    #[must_use]
    pub fn as_bytes(&self) -> &[u8] {
        self.0
    }
    /// Length of the underlying byte slice.
    #[must_use]
    pub fn len(&self) -> usize {
        self.0.len()
    }
    /// Whether the underlying byte slice is empty.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }
}

/// ADR-036 resolver trait: ψ_1 — per-value bytes → SimplicialComplex per ADR-035.
///
/// Parameterized by the model's H-axis (`H: Hasher` per ADR-022 D5) so
/// resolver impls compute content-addressed fingerprints using the
/// model's chosen hash impl. Sealed via [`__sdk_seal::Sealed`]: only
/// the SDK `resolver!` macro emits impls. Foundation provides a Null
/// impl whose `resolve` emits the `RESOLVER_ABSENT` shape violation.
///
/// ADR-041: `input` is a zero-cost typed carrier so ψ-stage
/// composition is type-checked at the resolver-impl boundary.
pub trait NerveResolver<H: crate::enforcement::Hasher>: __sdk_seal::Sealed {
    /// Resolve per-value content for this category.
    /// # Errors
    /// Returns [`crate::enforcement::ShapeViolation`] when the resolver
    /// cannot produce content (e.g., the foundation Null impl carrying
    /// the `RESOLVER_ABSENT` discriminator).
    fn resolve(
        &self,
        input: &[u8],
        out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation>;
}

/// ADR-036 resolver trait: ψ_2 — SimplicialComplex → ChainComplex per ADR-035.
///
/// Parameterized by the model's H-axis (`H: Hasher` per ADR-022 D5) so
/// resolver impls compute content-addressed fingerprints using the
/// model's chosen hash impl. Sealed via [`__sdk_seal::Sealed`]: only
/// the SDK `resolver!` macro emits impls. Foundation provides a Null
/// impl whose `resolve` emits the `RESOLVER_ABSENT` shape violation.
///
/// ADR-041: `input` is a zero-cost typed carrier so ψ-stage
/// composition is type-checked at the resolver-impl boundary.
pub trait ChainComplexResolver<H: crate::enforcement::Hasher>: __sdk_seal::Sealed {
    /// Resolve per-value content for this category.
    /// # Errors
    /// Returns [`crate::enforcement::ShapeViolation`] when the resolver
    /// cannot produce content (e.g., the foundation Null impl carrying
    /// the `RESOLVER_ABSENT` discriminator).
    fn resolve(
        &self,
        input: SimplicialComplexBytes<'_>,
        out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation>;
}

/// ADR-036 resolver trait: ψ_3 — ChainComplex → HomologyGroups per ADR-035.
///
/// Parameterized by the model's H-axis (`H: Hasher` per ADR-022 D5) so
/// resolver impls compute content-addressed fingerprints using the
/// model's chosen hash impl. Sealed via [`__sdk_seal::Sealed`]: only
/// the SDK `resolver!` macro emits impls. Foundation provides a Null
/// impl whose `resolve` emits the `RESOLVER_ABSENT` shape violation.
///
/// ADR-041: `input` is a zero-cost typed carrier so ψ-stage
/// composition is type-checked at the resolver-impl boundary.
pub trait HomologyGroupResolver<H: crate::enforcement::Hasher>: __sdk_seal::Sealed {
    /// Resolve per-value content for this category.
    /// # Errors
    /// Returns [`crate::enforcement::ShapeViolation`] when the resolver
    /// cannot produce content (e.g., the foundation Null impl carrying
    /// the `RESOLVER_ABSENT` discriminator).
    fn resolve(
        &self,
        input: ChainComplexBytes<'_>,
        out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation>;
}

/// ADR-036 resolver trait: ψ_5 — ChainComplex → CochainComplex per ADR-035.
///
/// Parameterized by the model's H-axis (`H: Hasher` per ADR-022 D5) so
/// resolver impls compute content-addressed fingerprints using the
/// model's chosen hash impl. Sealed via [`__sdk_seal::Sealed`]: only
/// the SDK `resolver!` macro emits impls. Foundation provides a Null
/// impl whose `resolve` emits the `RESOLVER_ABSENT` shape violation.
///
/// ADR-041: `input` is a zero-cost typed carrier so ψ-stage
/// composition is type-checked at the resolver-impl boundary.
pub trait CochainComplexResolver<H: crate::enforcement::Hasher>: __sdk_seal::Sealed {
    /// Resolve per-value content for this category.
    /// # Errors
    /// Returns [`crate::enforcement::ShapeViolation`] when the resolver
    /// cannot produce content (e.g., the foundation Null impl carrying
    /// the `RESOLVER_ABSENT` discriminator).
    fn resolve(
        &self,
        input: ChainComplexBytes<'_>,
        out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation>;
}

/// ADR-036 resolver trait: ψ_6 — CochainComplex → CohomologyGroups per ADR-035.
///
/// Parameterized by the model's H-axis (`H: Hasher` per ADR-022 D5) so
/// resolver impls compute content-addressed fingerprints using the
/// model's chosen hash impl. Sealed via [`__sdk_seal::Sealed`]: only
/// the SDK `resolver!` macro emits impls. Foundation provides a Null
/// impl whose `resolve` emits the `RESOLVER_ABSENT` shape violation.
///
/// ADR-041: `input` is a zero-cost typed carrier so ψ-stage
/// composition is type-checked at the resolver-impl boundary.
pub trait CohomologyGroupResolver<H: crate::enforcement::Hasher>: __sdk_seal::Sealed {
    /// Resolve per-value content for this category.
    /// # Errors
    /// Returns [`crate::enforcement::ShapeViolation`] when the resolver
    /// cannot produce content (e.g., the foundation Null impl carrying
    /// the `RESOLVER_ABSENT` discriminator).
    fn resolve(
        &self,
        input: CochainComplexBytes<'_>,
        out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation>;
}

/// ADR-036 resolver trait: ψ_7 — SimplicialComplex → PostnikovTower per ADR-035.
///
/// Parameterized by the model's H-axis (`H: Hasher` per ADR-022 D5) so
/// resolver impls compute content-addressed fingerprints using the
/// model's chosen hash impl. Sealed via [`__sdk_seal::Sealed`]: only
/// the SDK `resolver!` macro emits impls. Foundation provides a Null
/// impl whose `resolve` emits the `RESOLVER_ABSENT` shape violation.
///
/// ADR-041: `input` is a zero-cost typed carrier so ψ-stage
/// composition is type-checked at the resolver-impl boundary.
pub trait PostnikovResolver<H: crate::enforcement::Hasher>: __sdk_seal::Sealed {
    /// Resolve per-value content for this category.
    /// # Errors
    /// Returns [`crate::enforcement::ShapeViolation`] when the resolver
    /// cannot produce content (e.g., the foundation Null impl carrying
    /// the `RESOLVER_ABSENT` discriminator).
    fn resolve(
        &self,
        input: SimplicialComplexBytes<'_>,
        out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation>;
}

/// ADR-036 resolver trait: ψ_8 — PostnikovTower → HomotopyGroups per ADR-035.
///
/// Parameterized by the model's H-axis (`H: Hasher` per ADR-022 D5) so
/// resolver impls compute content-addressed fingerprints using the
/// model's chosen hash impl. Sealed via [`__sdk_seal::Sealed`]: only
/// the SDK `resolver!` macro emits impls. Foundation provides a Null
/// impl whose `resolve` emits the `RESOLVER_ABSENT` shape violation.
///
/// ADR-041: `input` is a zero-cost typed carrier so ψ-stage
/// composition is type-checked at the resolver-impl boundary.
pub trait HomotopyGroupResolver<H: crate::enforcement::Hasher>: __sdk_seal::Sealed {
    /// Resolve per-value content for this category.
    /// # Errors
    /// Returns [`crate::enforcement::ShapeViolation`] when the resolver
    /// cannot produce content (e.g., the foundation Null impl carrying
    /// the `RESOLVER_ABSENT` discriminator).
    fn resolve(
        &self,
        input: PostnikovTowerBytes<'_>,
        out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation>;
}

/// ADR-036 resolver trait: ψ_9 — HomotopyGroups → KInvariants per ADR-035.
///
/// Parameterized by the model's H-axis (`H: Hasher` per ADR-022 D5) so
/// resolver impls compute content-addressed fingerprints using the
/// model's chosen hash impl. Sealed via [`__sdk_seal::Sealed`]: only
/// the SDK `resolver!` macro emits impls. Foundation provides a Null
/// impl whose `resolve` emits the `RESOLVER_ABSENT` shape violation.
///
/// ADR-041: `input` is a zero-cost typed carrier so ψ-stage
/// composition is type-checked at the resolver-impl boundary.
pub trait KInvariantResolver<H: crate::enforcement::Hasher>: __sdk_seal::Sealed {
    /// Resolve per-value content for this category.
    /// # Errors
    /// Returns [`crate::enforcement::ShapeViolation`] when the resolver
    /// cannot produce content (e.g., the foundation Null impl carrying
    /// the `RESOLVER_ABSENT` discriminator).
    fn resolve(
        &self,
        input: HomotopyGroupsBytes<'_>,
        out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation>;
}

/// ADR-036 marker trait: ResolverTuple positions including a `NerveResolver`.
/// The `prism_model!` macro infers the where-clause bound for each
/// resolver-bound ψ-Term variant a verb body emits.
pub trait HasNerveResolver<H: crate::enforcement::Hasher>: ResolverTuple {
    /// Returns the `NerveResolver` impl this ResolverTuple carries.
    fn nerve_resolver(&self) -> &dyn NerveResolver<H>;
}

/// ADR-036 marker trait: ResolverTuple positions including a `ChainComplexResolver`.
/// The `prism_model!` macro infers the where-clause bound for each
/// resolver-bound ψ-Term variant a verb body emits.
pub trait HasChainComplexResolver<H: crate::enforcement::Hasher>: ResolverTuple {
    /// Returns the `ChainComplexResolver` impl this ResolverTuple carries.
    fn chain_complex_resolver(&self) -> &dyn ChainComplexResolver<H>;
}

/// ADR-036 marker trait: ResolverTuple positions including a `HomologyGroupResolver`.
/// The `prism_model!` macro infers the where-clause bound for each
/// resolver-bound ψ-Term variant a verb body emits.
pub trait HasHomologyGroupResolver<H: crate::enforcement::Hasher>: ResolverTuple {
    /// Returns the `HomologyGroupResolver` impl this ResolverTuple carries.
    fn homology_group_resolver(&self) -> &dyn HomologyGroupResolver<H>;
}

/// ADR-036 marker trait: ResolverTuple positions including a `CochainComplexResolver`.
/// The `prism_model!` macro infers the where-clause bound for each
/// resolver-bound ψ-Term variant a verb body emits.
pub trait HasCochainComplexResolver<H: crate::enforcement::Hasher>: ResolverTuple {
    /// Returns the `CochainComplexResolver` impl this ResolverTuple carries.
    fn cochain_complex_resolver(&self) -> &dyn CochainComplexResolver<H>;
}

/// ADR-036 marker trait: ResolverTuple positions including a `CohomologyGroupResolver`.
/// The `prism_model!` macro infers the where-clause bound for each
/// resolver-bound ψ-Term variant a verb body emits.
pub trait HasCohomologyGroupResolver<H: crate::enforcement::Hasher>: ResolverTuple {
    /// Returns the `CohomologyGroupResolver` impl this ResolverTuple carries.
    fn cohomology_group_resolver(&self) -> &dyn CohomologyGroupResolver<H>;
}

/// ADR-036 marker trait: ResolverTuple positions including a `PostnikovResolver`.
/// The `prism_model!` macro infers the where-clause bound for each
/// resolver-bound ψ-Term variant a verb body emits.
pub trait HasPostnikovResolver<H: crate::enforcement::Hasher>: ResolverTuple {
    /// Returns the `PostnikovResolver` impl this ResolverTuple carries.
    fn postnikov_resolver(&self) -> &dyn PostnikovResolver<H>;
}

/// ADR-036 marker trait: ResolverTuple positions including a `HomotopyGroupResolver`.
/// The `prism_model!` macro infers the where-clause bound for each
/// resolver-bound ψ-Term variant a verb body emits.
pub trait HasHomotopyGroupResolver<H: crate::enforcement::Hasher>: ResolverTuple {
    /// Returns the `HomotopyGroupResolver` impl this ResolverTuple carries.
    fn homotopy_group_resolver(&self) -> &dyn HomotopyGroupResolver<H>;
}

/// ADR-036 marker trait: ResolverTuple positions including a `KInvariantResolver`.
/// The `prism_model!` macro infers the where-clause bound for each
/// resolver-bound ψ-Term variant a verb body emits.
pub trait HasKInvariantResolver<H: crate::enforcement::Hasher>: ResolverTuple {
    /// Returns the `KInvariantResolver` impl this ResolverTuple carries.
    fn k_invariant_resolver(&self) -> &dyn KInvariantResolver<H>;
}

/// ADR-036 Null resolver tuple — the resolver-absent default.
/// `ResolverTuple` impl with `ARITY = 0` and an empty CATEGORIES list.
/// Applications that don't declare a `resolver!` block default to this.
#[derive(Debug, Clone, Copy, Default)]
pub struct NullResolverTuple;

impl __sdk_seal::Sealed for NullResolverTuple {}

impl ResolverTuple for NullResolverTuple {
    const ARITY: usize = 0;
    const CATEGORIES: &'static [ResolverCategory] = &[];
    // ADR-057: foundation built-in registry only — the empty
    // registry provider falls through to FOUNDATION_REGISTRY in
    // shape_iri_registry. Applications with their own recursive
    // shapes set this to their `register_shape!`-emitted marker.
    type ShapeRegistry = crate::pipeline::shape_iri_registry::EmptyShapeRegistry;
}

/// ADR-036 Null `NerveResolver` impl. `resolve` always emits the
/// `RESOLVER_ABSENT` shape violation — the catamorphism translates this
/// into `PipelineFailure::ShapeViolation` recoverable via `Term::Try`'s
/// default-propagation handler (ADR-022 D3 G9).
#[derive(Debug, Default)]
pub struct NullNerveResolver<H: crate::enforcement::Hasher>(core::marker::PhantomData<H>);

impl<H: crate::enforcement::Hasher> NullNerveResolver<H> {
    /// Construct a new Null resolver.
    #[must_use]
    pub const fn new() -> Self {
        Self(core::marker::PhantomData)
    }
}

impl<H: crate::enforcement::Hasher> __sdk_seal::Sealed for NullNerveResolver<H> {}

impl<H: crate::enforcement::Hasher> NerveResolver<H> for NullNerveResolver<H> {
    fn resolve(
        &self,
        _input: &[u8],
        _out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        Err(crate::enforcement::ShapeViolation {
            shape_iri: "https://uor.foundation/resolver/RESOLVER_ABSENT",
            constraint_iri: "https://uor.foundation/resolver/Nerve",
            property_iri: "https://uor.foundation/resolver/category",
            expected_range: "https://uor.foundation/resolver/Resolver",
            min_count: 0,
            max_count: 1,
            kind: crate::ViolationKind::ValueCheck,
        })
    }
}

/// ADR-036 Null `ChainComplexResolver` impl. `resolve` always emits the
/// `RESOLVER_ABSENT` shape violation — the catamorphism translates this
/// into `PipelineFailure::ShapeViolation` recoverable via `Term::Try`'s
/// default-propagation handler (ADR-022 D3 G9).
#[derive(Debug, Default)]
pub struct NullChainComplexResolver<H: crate::enforcement::Hasher>(core::marker::PhantomData<H>);

impl<H: crate::enforcement::Hasher> NullChainComplexResolver<H> {
    /// Construct a new Null resolver.
    #[must_use]
    pub const fn new() -> Self {
        Self(core::marker::PhantomData)
    }
}

impl<H: crate::enforcement::Hasher> __sdk_seal::Sealed for NullChainComplexResolver<H> {}

impl<H: crate::enforcement::Hasher> ChainComplexResolver<H> for NullChainComplexResolver<H> {
    fn resolve(
        &self,
        _input: SimplicialComplexBytes<'_>,
        _out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        Err(crate::enforcement::ShapeViolation {
            shape_iri: "https://uor.foundation/resolver/RESOLVER_ABSENT",
            constraint_iri: "https://uor.foundation/resolver/ChainComplex",
            property_iri: "https://uor.foundation/resolver/category",
            expected_range: "https://uor.foundation/resolver/Resolver",
            min_count: 0,
            max_count: 1,
            kind: crate::ViolationKind::ValueCheck,
        })
    }
}

/// ADR-036 Null `HomologyGroupResolver` impl. `resolve` always emits the
/// `RESOLVER_ABSENT` shape violation — the catamorphism translates this
/// into `PipelineFailure::ShapeViolation` recoverable via `Term::Try`'s
/// default-propagation handler (ADR-022 D3 G9).
#[derive(Debug, Default)]
pub struct NullHomologyGroupResolver<H: crate::enforcement::Hasher>(core::marker::PhantomData<H>);

impl<H: crate::enforcement::Hasher> NullHomologyGroupResolver<H> {
    /// Construct a new Null resolver.
    #[must_use]
    pub const fn new() -> Self {
        Self(core::marker::PhantomData)
    }
}

impl<H: crate::enforcement::Hasher> __sdk_seal::Sealed for NullHomologyGroupResolver<H> {}

impl<H: crate::enforcement::Hasher> HomologyGroupResolver<H> for NullHomologyGroupResolver<H> {
    fn resolve(
        &self,
        _input: ChainComplexBytes<'_>,
        _out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        Err(crate::enforcement::ShapeViolation {
            shape_iri: "https://uor.foundation/resolver/RESOLVER_ABSENT",
            constraint_iri: "https://uor.foundation/resolver/HomologyGroup",
            property_iri: "https://uor.foundation/resolver/category",
            expected_range: "https://uor.foundation/resolver/Resolver",
            min_count: 0,
            max_count: 1,
            kind: crate::ViolationKind::ValueCheck,
        })
    }
}

/// ADR-036 Null `CochainComplexResolver` impl. `resolve` always emits the
/// `RESOLVER_ABSENT` shape violation — the catamorphism translates this
/// into `PipelineFailure::ShapeViolation` recoverable via `Term::Try`'s
/// default-propagation handler (ADR-022 D3 G9).
#[derive(Debug, Default)]
pub struct NullCochainComplexResolver<H: crate::enforcement::Hasher>(core::marker::PhantomData<H>);

impl<H: crate::enforcement::Hasher> NullCochainComplexResolver<H> {
    /// Construct a new Null resolver.
    #[must_use]
    pub const fn new() -> Self {
        Self(core::marker::PhantomData)
    }
}

impl<H: crate::enforcement::Hasher> __sdk_seal::Sealed for NullCochainComplexResolver<H> {}

impl<H: crate::enforcement::Hasher> CochainComplexResolver<H> for NullCochainComplexResolver<H> {
    fn resolve(
        &self,
        _input: ChainComplexBytes<'_>,
        _out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        Err(crate::enforcement::ShapeViolation {
            shape_iri: "https://uor.foundation/resolver/RESOLVER_ABSENT",
            constraint_iri: "https://uor.foundation/resolver/CochainComplex",
            property_iri: "https://uor.foundation/resolver/category",
            expected_range: "https://uor.foundation/resolver/Resolver",
            min_count: 0,
            max_count: 1,
            kind: crate::ViolationKind::ValueCheck,
        })
    }
}

/// ADR-036 Null `CohomologyGroupResolver` impl. `resolve` always emits the
/// `RESOLVER_ABSENT` shape violation — the catamorphism translates this
/// into `PipelineFailure::ShapeViolation` recoverable via `Term::Try`'s
/// default-propagation handler (ADR-022 D3 G9).
#[derive(Debug, Default)]
pub struct NullCohomologyGroupResolver<H: crate::enforcement::Hasher>(core::marker::PhantomData<H>);

impl<H: crate::enforcement::Hasher> NullCohomologyGroupResolver<H> {
    /// Construct a new Null resolver.
    #[must_use]
    pub const fn new() -> Self {
        Self(core::marker::PhantomData)
    }
}

impl<H: crate::enforcement::Hasher> __sdk_seal::Sealed for NullCohomologyGroupResolver<H> {}

impl<H: crate::enforcement::Hasher> CohomologyGroupResolver<H> for NullCohomologyGroupResolver<H> {
    fn resolve(
        &self,
        _input: CochainComplexBytes<'_>,
        _out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        Err(crate::enforcement::ShapeViolation {
            shape_iri: "https://uor.foundation/resolver/RESOLVER_ABSENT",
            constraint_iri: "https://uor.foundation/resolver/CohomologyGroup",
            property_iri: "https://uor.foundation/resolver/category",
            expected_range: "https://uor.foundation/resolver/Resolver",
            min_count: 0,
            max_count: 1,
            kind: crate::ViolationKind::ValueCheck,
        })
    }
}

/// ADR-036 Null `PostnikovResolver` impl. `resolve` always emits the
/// `RESOLVER_ABSENT` shape violation — the catamorphism translates this
/// into `PipelineFailure::ShapeViolation` recoverable via `Term::Try`'s
/// default-propagation handler (ADR-022 D3 G9).
#[derive(Debug, Default)]
pub struct NullPostnikovResolver<H: crate::enforcement::Hasher>(core::marker::PhantomData<H>);

impl<H: crate::enforcement::Hasher> NullPostnikovResolver<H> {
    /// Construct a new Null resolver.
    #[must_use]
    pub const fn new() -> Self {
        Self(core::marker::PhantomData)
    }
}

impl<H: crate::enforcement::Hasher> __sdk_seal::Sealed for NullPostnikovResolver<H> {}

impl<H: crate::enforcement::Hasher> PostnikovResolver<H> for NullPostnikovResolver<H> {
    fn resolve(
        &self,
        _input: SimplicialComplexBytes<'_>,
        _out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        Err(crate::enforcement::ShapeViolation {
            shape_iri: "https://uor.foundation/resolver/RESOLVER_ABSENT",
            constraint_iri: "https://uor.foundation/resolver/Postnikov",
            property_iri: "https://uor.foundation/resolver/category",
            expected_range: "https://uor.foundation/resolver/Resolver",
            min_count: 0,
            max_count: 1,
            kind: crate::ViolationKind::ValueCheck,
        })
    }
}

/// ADR-036 Null `HomotopyGroupResolver` impl. `resolve` always emits the
/// `RESOLVER_ABSENT` shape violation — the catamorphism translates this
/// into `PipelineFailure::ShapeViolation` recoverable via `Term::Try`'s
/// default-propagation handler (ADR-022 D3 G9).
#[derive(Debug, Default)]
pub struct NullHomotopyGroupResolver<H: crate::enforcement::Hasher>(core::marker::PhantomData<H>);

impl<H: crate::enforcement::Hasher> NullHomotopyGroupResolver<H> {
    /// Construct a new Null resolver.
    #[must_use]
    pub const fn new() -> Self {
        Self(core::marker::PhantomData)
    }
}

impl<H: crate::enforcement::Hasher> __sdk_seal::Sealed for NullHomotopyGroupResolver<H> {}

impl<H: crate::enforcement::Hasher> HomotopyGroupResolver<H> for NullHomotopyGroupResolver<H> {
    fn resolve(
        &self,
        _input: PostnikovTowerBytes<'_>,
        _out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        Err(crate::enforcement::ShapeViolation {
            shape_iri: "https://uor.foundation/resolver/RESOLVER_ABSENT",
            constraint_iri: "https://uor.foundation/resolver/HomotopyGroup",
            property_iri: "https://uor.foundation/resolver/category",
            expected_range: "https://uor.foundation/resolver/Resolver",
            min_count: 0,
            max_count: 1,
            kind: crate::ViolationKind::ValueCheck,
        })
    }
}

/// ADR-036 Null `KInvariantResolver` impl. `resolve` always emits the
/// `RESOLVER_ABSENT` shape violation — the catamorphism translates this
/// into `PipelineFailure::ShapeViolation` recoverable via `Term::Try`'s
/// default-propagation handler (ADR-022 D3 G9).
#[derive(Debug, Default)]
pub struct NullKInvariantResolver<H: crate::enforcement::Hasher>(core::marker::PhantomData<H>);

impl<H: crate::enforcement::Hasher> NullKInvariantResolver<H> {
    /// Construct a new Null resolver.
    #[must_use]
    pub const fn new() -> Self {
        Self(core::marker::PhantomData)
    }
}

impl<H: crate::enforcement::Hasher> __sdk_seal::Sealed for NullKInvariantResolver<H> {}

impl<H: crate::enforcement::Hasher> KInvariantResolver<H> for NullKInvariantResolver<H> {
    fn resolve(
        &self,
        _input: HomotopyGroupsBytes<'_>,
        _out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        Err(crate::enforcement::ShapeViolation {
            shape_iri: "https://uor.foundation/resolver/RESOLVER_ABSENT",
            constraint_iri: "https://uor.foundation/resolver/KInvariant",
            property_iri: "https://uor.foundation/resolver/category",
            expected_range: "https://uor.foundation/resolver/Resolver",
            min_count: 0,
            max_count: 1,
            kind: crate::ViolationKind::ValueCheck,
        })
    }
}

/// ADR-036: NullResolverTuple satisfies `NerveResolver<H>` directly so
/// the `HasNerveResolver<H>` accessor can return `self` cast to `&dyn NerveResolver<H>`.
/// The `resolve` method emits the `RESOLVER_ABSENT` shape violation —
/// recoverable via `Term::Try`'s default-propagation handler (ADR-022 D3 G9).
impl<H: crate::enforcement::Hasher> NerveResolver<H> for NullResolverTuple {
    fn resolve(
        &self,
        _input: &[u8],
        _out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        Err(crate::enforcement::ShapeViolation {
            shape_iri: "https://uor.foundation/resolver/RESOLVER_ABSENT",
            constraint_iri: "https://uor.foundation/resolver/Nerve",
            property_iri: "https://uor.foundation/resolver/category",
            expected_range: "https://uor.foundation/resolver/Resolver",
            min_count: 0,
            max_count: 1,
            kind: crate::ViolationKind::ValueCheck,
        })
    }
}

/// ADR-036: NullResolverTuple satisfies `HasNerveResolver<H>` (returns `self`).
impl<H: crate::enforcement::Hasher> HasNerveResolver<H> for NullResolverTuple {
    fn nerve_resolver(&self) -> &dyn NerveResolver<H> {
        self
    }
}

/// ADR-036: NullResolverTuple satisfies `ChainComplexResolver<H>` directly so
/// the `HasChainComplexResolver<H>` accessor can return `self` cast to `&dyn ChainComplexResolver<H>`.
/// The `resolve` method emits the `RESOLVER_ABSENT` shape violation —
/// recoverable via `Term::Try`'s default-propagation handler (ADR-022 D3 G9).
impl<H: crate::enforcement::Hasher> ChainComplexResolver<H> for NullResolverTuple {
    fn resolve(
        &self,
        _input: SimplicialComplexBytes<'_>,
        _out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        Err(crate::enforcement::ShapeViolation {
            shape_iri: "https://uor.foundation/resolver/RESOLVER_ABSENT",
            constraint_iri: "https://uor.foundation/resolver/ChainComplex",
            property_iri: "https://uor.foundation/resolver/category",
            expected_range: "https://uor.foundation/resolver/Resolver",
            min_count: 0,
            max_count: 1,
            kind: crate::ViolationKind::ValueCheck,
        })
    }
}

/// ADR-036: NullResolverTuple satisfies `HasChainComplexResolver<H>` (returns `self`).
impl<H: crate::enforcement::Hasher> HasChainComplexResolver<H> for NullResolverTuple {
    fn chain_complex_resolver(&self) -> &dyn ChainComplexResolver<H> {
        self
    }
}

/// ADR-036: NullResolverTuple satisfies `HomologyGroupResolver<H>` directly so
/// the `HasHomologyGroupResolver<H>` accessor can return `self` cast to `&dyn HomologyGroupResolver<H>`.
/// The `resolve` method emits the `RESOLVER_ABSENT` shape violation —
/// recoverable via `Term::Try`'s default-propagation handler (ADR-022 D3 G9).
impl<H: crate::enforcement::Hasher> HomologyGroupResolver<H> for NullResolverTuple {
    fn resolve(
        &self,
        _input: ChainComplexBytes<'_>,
        _out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        Err(crate::enforcement::ShapeViolation {
            shape_iri: "https://uor.foundation/resolver/RESOLVER_ABSENT",
            constraint_iri: "https://uor.foundation/resolver/HomologyGroup",
            property_iri: "https://uor.foundation/resolver/category",
            expected_range: "https://uor.foundation/resolver/Resolver",
            min_count: 0,
            max_count: 1,
            kind: crate::ViolationKind::ValueCheck,
        })
    }
}

/// ADR-036: NullResolverTuple satisfies `HasHomologyGroupResolver<H>` (returns `self`).
impl<H: crate::enforcement::Hasher> HasHomologyGroupResolver<H> for NullResolverTuple {
    fn homology_group_resolver(&self) -> &dyn HomologyGroupResolver<H> {
        self
    }
}

/// ADR-036: NullResolverTuple satisfies `CochainComplexResolver<H>` directly so
/// the `HasCochainComplexResolver<H>` accessor can return `self` cast to `&dyn CochainComplexResolver<H>`.
/// The `resolve` method emits the `RESOLVER_ABSENT` shape violation —
/// recoverable via `Term::Try`'s default-propagation handler (ADR-022 D3 G9).
impl<H: crate::enforcement::Hasher> CochainComplexResolver<H> for NullResolverTuple {
    fn resolve(
        &self,
        _input: ChainComplexBytes<'_>,
        _out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        Err(crate::enforcement::ShapeViolation {
            shape_iri: "https://uor.foundation/resolver/RESOLVER_ABSENT",
            constraint_iri: "https://uor.foundation/resolver/CochainComplex",
            property_iri: "https://uor.foundation/resolver/category",
            expected_range: "https://uor.foundation/resolver/Resolver",
            min_count: 0,
            max_count: 1,
            kind: crate::ViolationKind::ValueCheck,
        })
    }
}

/// ADR-036: NullResolverTuple satisfies `HasCochainComplexResolver<H>` (returns `self`).
impl<H: crate::enforcement::Hasher> HasCochainComplexResolver<H> for NullResolverTuple {
    fn cochain_complex_resolver(&self) -> &dyn CochainComplexResolver<H> {
        self
    }
}

/// ADR-036: NullResolverTuple satisfies `CohomologyGroupResolver<H>` directly so
/// the `HasCohomologyGroupResolver<H>` accessor can return `self` cast to `&dyn CohomologyGroupResolver<H>`.
/// The `resolve` method emits the `RESOLVER_ABSENT` shape violation —
/// recoverable via `Term::Try`'s default-propagation handler (ADR-022 D3 G9).
impl<H: crate::enforcement::Hasher> CohomologyGroupResolver<H> for NullResolverTuple {
    fn resolve(
        &self,
        _input: CochainComplexBytes<'_>,
        _out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        Err(crate::enforcement::ShapeViolation {
            shape_iri: "https://uor.foundation/resolver/RESOLVER_ABSENT",
            constraint_iri: "https://uor.foundation/resolver/CohomologyGroup",
            property_iri: "https://uor.foundation/resolver/category",
            expected_range: "https://uor.foundation/resolver/Resolver",
            min_count: 0,
            max_count: 1,
            kind: crate::ViolationKind::ValueCheck,
        })
    }
}

/// ADR-036: NullResolverTuple satisfies `HasCohomologyGroupResolver<H>` (returns `self`).
impl<H: crate::enforcement::Hasher> HasCohomologyGroupResolver<H> for NullResolverTuple {
    fn cohomology_group_resolver(&self) -> &dyn CohomologyGroupResolver<H> {
        self
    }
}

/// ADR-036: NullResolverTuple satisfies `PostnikovResolver<H>` directly so
/// the `HasPostnikovResolver<H>` accessor can return `self` cast to `&dyn PostnikovResolver<H>`.
/// The `resolve` method emits the `RESOLVER_ABSENT` shape violation —
/// recoverable via `Term::Try`'s default-propagation handler (ADR-022 D3 G9).
impl<H: crate::enforcement::Hasher> PostnikovResolver<H> for NullResolverTuple {
    fn resolve(
        &self,
        _input: SimplicialComplexBytes<'_>,
        _out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        Err(crate::enforcement::ShapeViolation {
            shape_iri: "https://uor.foundation/resolver/RESOLVER_ABSENT",
            constraint_iri: "https://uor.foundation/resolver/Postnikov",
            property_iri: "https://uor.foundation/resolver/category",
            expected_range: "https://uor.foundation/resolver/Resolver",
            min_count: 0,
            max_count: 1,
            kind: crate::ViolationKind::ValueCheck,
        })
    }
}

/// ADR-036: NullResolverTuple satisfies `HasPostnikovResolver<H>` (returns `self`).
impl<H: crate::enforcement::Hasher> HasPostnikovResolver<H> for NullResolverTuple {
    fn postnikov_resolver(&self) -> &dyn PostnikovResolver<H> {
        self
    }
}

/// ADR-036: NullResolverTuple satisfies `HomotopyGroupResolver<H>` directly so
/// the `HasHomotopyGroupResolver<H>` accessor can return `self` cast to `&dyn HomotopyGroupResolver<H>`.
/// The `resolve` method emits the `RESOLVER_ABSENT` shape violation —
/// recoverable via `Term::Try`'s default-propagation handler (ADR-022 D3 G9).
impl<H: crate::enforcement::Hasher> HomotopyGroupResolver<H> for NullResolverTuple {
    fn resolve(
        &self,
        _input: PostnikovTowerBytes<'_>,
        _out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        Err(crate::enforcement::ShapeViolation {
            shape_iri: "https://uor.foundation/resolver/RESOLVER_ABSENT",
            constraint_iri: "https://uor.foundation/resolver/HomotopyGroup",
            property_iri: "https://uor.foundation/resolver/category",
            expected_range: "https://uor.foundation/resolver/Resolver",
            min_count: 0,
            max_count: 1,
            kind: crate::ViolationKind::ValueCheck,
        })
    }
}

/// ADR-036: NullResolverTuple satisfies `HasHomotopyGroupResolver<H>` (returns `self`).
impl<H: crate::enforcement::Hasher> HasHomotopyGroupResolver<H> for NullResolverTuple {
    fn homotopy_group_resolver(&self) -> &dyn HomotopyGroupResolver<H> {
        self
    }
}

/// ADR-036: NullResolverTuple satisfies `KInvariantResolver<H>` directly so
/// the `HasKInvariantResolver<H>` accessor can return `self` cast to `&dyn KInvariantResolver<H>`.
/// The `resolve` method emits the `RESOLVER_ABSENT` shape violation —
/// recoverable via `Term::Try`'s default-propagation handler (ADR-022 D3 G9).
impl<H: crate::enforcement::Hasher> KInvariantResolver<H> for NullResolverTuple {
    fn resolve(
        &self,
        _input: HomotopyGroupsBytes<'_>,
        _out: &mut [u8],
    ) -> Result<usize, crate::enforcement::ShapeViolation> {
        Err(crate::enforcement::ShapeViolation {
            shape_iri: "https://uor.foundation/resolver/RESOLVER_ABSENT",
            constraint_iri: "https://uor.foundation/resolver/KInvariant",
            property_iri: "https://uor.foundation/resolver/category",
            expected_range: "https://uor.foundation/resolver/Resolver",
            min_count: 0,
            max_count: 1,
            kind: crate::ViolationKind::ValueCheck,
        })
    }
}

/// ADR-036: NullResolverTuple satisfies `HasKInvariantResolver<H>` (returns `self`).
impl<H: crate::enforcement::Hasher> HasKInvariantResolver<H> for NullResolverTuple {
    fn k_invariant_resolver(&self) -> &dyn KInvariantResolver<H> {
        self
    }
}

/// Wiki ADR-042: typed view over a successful `Grounded<T, Tag>` as the
/// inhabitance-verdict envelope produced by the canonical k-invariants
/// branch (ψ_1 → ψ_7 → ψ_8 → ψ_9 per ADR-035).
///
/// Zero-cost — `#[repr(transparent)]` over `&'a Grounded<T, Tag>`. Construct
/// via [`crate::enforcement::Grounded::as_inhabitance_certificate`].
///
/// Realizes `cert:InhabitanceCertificate` per the ontology
/// (`<https://uor.foundation/cert/InhabitanceCertificate>`). Foundation
/// uses the suffix `View` here to distinguish this zero-cost typed
/// view from the existing sealed-shim `crate::enforcement::InhabitanceCertificate`
/// value carrier; the wiki names this type `InhabitanceCertificate<'a, T>`
/// in ADR-042 and the typed-view role is the load-bearing concern. The κ-label,
/// concrete `cert:witness`, and `cert:searchTrace` are accessor methods
/// over the underlying `Grounded` — no allocation, no per-application
/// re-derivation.
#[repr(transparent)]
#[derive(Debug, Clone, Copy)]
pub struct InhabitanceCertificateView<'a, T: crate::enforcement::GroundedShape, Tag = T>(
    pub &'a crate::enforcement::Grounded<T, Tag>,
);

impl<'a, T: crate::enforcement::GroundedShape, Tag> InhabitanceCertificateView<'a, T, Tag> {
    /// The κ-label — the homotopy-classification structural witness at
    /// ψ_9 per ADR-035. The bytes are the `Term::KInvariants` emission's
    /// output (exposed via `Grounded::output_bytes`) wrapped in the
    /// ADR-041 typed-coordinate carrier so cross-stage composition is
    /// type-checked.
    #[inline]
    #[must_use]
    pub fn kappa_label(&self) -> KInvariantsBytes<'_> {
        KInvariantsBytes(self.0.output_bytes())
    }

    /// The concrete `cert:witness` ValueTuple — derivable from
    /// `Term::Nerve`'s 0-simplices at ψ_1 (the per-value bytes the
    /// model's NerveResolver consumed). Foundation exposes the
    /// `Grounded`'s bindings as the value-tuple surface; applications
    /// whose admission relations carry richer witness data project
    /// through the binding table's content addresses.
    #[inline]
    #[must_use]
    pub fn witness(&self) -> WitnessValueTuple<'_> {
        WitnessValueTuple {
            grounded_bindings: self.0,
        }
    }

    /// The `cert:searchTrace` — realized as
    /// `<Grounded>::derivation::<H>(...).replay::<...>()` per ADR-039.
    /// Foundation surfaces the derivation pointer; applications choose
    /// which `Hasher` impl and `HostBounds` parameters to instantiate
    /// the replay with.
    #[inline]
    #[must_use]
    pub fn certificate(
        &self,
    ) -> &crate::enforcement::Validated<crate::enforcement::GroundingCertificate> {
        self.0.certificate()
    }

    /// The certified type's stable IRI — the `<T as ConstrainedTypeShape>::IRI`
    /// the application registered as the route's output shape.
    #[inline]
    #[must_use]
    pub fn certified_type(&self) -> &'static str
    where
        T: ConstrainedTypeShape,
    {
        <T as ConstrainedTypeShape>::IRI
    }
}

/// Wiki ADR-042: concrete `cert:witness` ValueTuple view. Borrows the
/// underlying `Grounded`'s bindings; iterates as `(content_address, bytes)`
/// pairs corresponding to `Term::Nerve`'s 0-simplices.
#[derive(Clone, Copy)]
pub struct WitnessValueTuple<'a> {
    /// Foundation-internal: the underlying Grounded reference. Public-API
    /// access goes through the accessor methods.
    grounded_bindings: &'a dyn WitnessTupleSource,
}

impl<'a> core::fmt::Debug for WitnessValueTuple<'a> {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("WitnessValueTuple")
            .field("binding_count", &self.grounded_bindings.binding_count())
            .finish()
    }
}

impl<'a> WitnessValueTuple<'a> {
    /// Number of bindings in the witness tuple.
    #[inline]
    #[must_use]
    pub fn len(&self) -> usize {
        self.grounded_bindings.binding_count()
    }

    /// Whether the witness tuple is empty.
    #[inline]
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.grounded_bindings.binding_count() == 0
    }

    /// The witness's content-addressed binding bytes at position `idx`.
    /// Returns `None` if `idx >= len()`.
    #[inline]
    #[must_use]
    pub fn binding_bytes(&self, idx: usize) -> Option<&'static [u8]> {
        self.grounded_bindings.binding_bytes_at(idx)
    }
}

/// Foundation-internal trait letting `Grounded<T, Tag>` expose binding
/// access to `WitnessValueTuple` without leaking the generic-parameter
/// plumbing into the witness-view type.
pub trait WitnessTupleSource {
    /// Number of bindings in this source's table.
    fn binding_count(&self) -> usize;
    /// Binding bytes at the given index, or `None` if out of range.
    fn binding_bytes_at(&self, idx: usize) -> Option<&'static [u8]>;
}

impl<T: crate::enforcement::GroundedShape, Tag> WitnessTupleSource
    for crate::enforcement::Grounded<T, Tag>
{
    fn binding_count(&self) -> usize {
        self.iter_bindings().count()
    }
    fn binding_bytes_at(&self, idx: usize) -> Option<&'static [u8]> {
        self.iter_bindings().nth(idx).map(|e| e.bytes)
    }
}

/// Wiki ADR-042: typed view over an `Err(PipelineFailure)` as the
/// inhabitance-impossibility envelope. Realizes
/// `cert:InhabitanceImpossibilityCertificate` per the ontology:
/// `<https://uor.foundation/cert/InhabitanceImpossibilityCertificate>`.
///
/// Zero-cost — `#[repr(transparent)]` over `&'a PipelineFailure`. Construct
/// via [`crate::enforcement::PipelineFailure::as_inhabitance_impossibility_certificate`].
#[repr(transparent)]
#[derive(Debug, Clone, Copy)]
pub struct InhabitanceImpossibilityCertificate<'a>(pub &'a crate::enforcement::PipelineFailure);

impl<'a> InhabitanceImpossibilityCertificate<'a> {
    /// The contradiction-proof bytes — canonical-form encoding of the
    /// failure trace, suitable for Lean 4 by-contradiction reconstruction
    /// per ADR-039 + ADR-042. Foundation provides the shape-violation's
    /// `shape_iri` bytes as the proof's canonical-form witness; richer
    /// contradiction data is application-provided via the failure trace.
    #[inline]
    #[must_use]
    pub fn contradiction_proof(&self) -> &'static [u8] {
        match self.0 {
            crate::enforcement::PipelineFailure::ShapeViolation { report } => {
                report.shape_iri.as_bytes()
            }
            _ => b"https://uor.foundation/proof/InhabitanceImpossibilityWitness",
        }
    }

    /// Borrow the underlying `PipelineFailure`.
    #[inline]
    #[must_use]
    pub fn failure(&self) -> &crate::enforcement::PipelineFailure {
        self.0
    }
}

/// Wiki ADR-042: typed verdict-envelope accessors on `PipelineFailure`.
impl crate::enforcement::PipelineFailure {
    /// Borrow `self` as an [`InhabitanceImpossibilityCertificate`] view
    /// when the failure's structural cause is an inhabitance-impossibility
    /// witness (per ADR-042). Returns `Some` for `ShapeViolation` whose
    /// `shape_iri` carries one of the foundation-declared inhabitance
    /// proof IRIs (e.g. `RESOLVER_ABSENT`, the constraint-nerve-empty-
    /// Kan-completion sentinel); foundation accepts `Some(...)` universally
    /// for `PipelineFailure` so applications consume the verdict-envelope
    /// view at their discretion.
    #[inline]
    #[must_use]
    pub fn as_inhabitance_impossibility_certificate(
        &self,
    ) -> Option<InhabitanceImpossibilityCertificate<'_>> {
        Some(InhabitanceImpossibilityCertificate(self))
    }
}

/// Wiki ADR-042: `predicate:InhabitanceDispatchTable` consultation helper.
/// Application NerveResolver impls MAY call this helper internally for
/// decider routing across the ontology's three canonical rule arms
/// (TwoSatDecider, HornSatDecider, ResidualVerdictResolver). Foundation
/// provides the dispatch surface; rule-arm semantics are application-
/// provided through the closures the caller threads in.
pub mod inhabitance {
    /// Three rule arms a `predicate:InhabitanceDispatchTable` consultation
    /// dispatches through, per the ontology's canonical decider routing.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
    pub enum InhabitanceRuleArm {
        ///         TwoSatDecider — `predicate:TwoSatDecider`. Decides 2-SAT constraint nerves.
        TwoSatDecider,
        ///         HornSatDecider — `predicate:HornSatDecider`. Decides Horn-SAT constraint nerves.
        HornSatDecider,
        ///         ResidualVerdictResolver — `predicate:ResidualVerdictResolver`. Residual
        ///         catch-all for constraint nerves outside the 2-SAT / Horn-SAT coverage.
        ResidualVerdictResolver,
    }

    /// Dispatch through the `predicate:InhabitanceDispatchTable` rule arms in
    /// ontology order (TwoSatDecider → HornSatDecider → ResidualVerdictResolver).
    /// Each closure returns `Some(verdict)` if the arm decides, or `None` to
    /// delegate to the next arm. Returns the first decisive verdict.
    #[inline]
    pub fn dispatch_through_table<F1, F2, F3, V>(
        two_sat: F1,
        horn_sat: F2,
        residual: F3,
    ) -> (InhabitanceRuleArm, V)
    where
        F1: FnOnce() -> Option<V>,
        F2: FnOnce() -> Option<V>,
        F3: FnOnce() -> V,
    {
        if let Some(v) = two_sat() {
            return (InhabitanceRuleArm::TwoSatDecider, v);
        }
        if let Some(v) = horn_sat() {
            return (InhabitanceRuleArm::HornSatDecider, v);
        }
        (InhabitanceRuleArm::ResidualVerdictResolver, residual())
    }
}

/// Wiki ADR-049: substrate-level typed-observable predicate trait.
///
/// Implementors are foundation-declared typed observables that read a
/// structural property of a digest and evaluate a single-bit predicate
/// against the read value. Sealed via [`__sdk_seal::Sealed`]; the foundation
/// declares the closed catalog of 4 typed observables consuming the
/// canonical hash axis's σ-projection per ADR-047.
///
/// `SingletonCommitment<P>` wraps one of these to form a 1-bit
/// typed-commitment per ADR-048; `AndCommitment` composes any number.
pub trait ObservablePredicate: Copy + __sdk_seal::Sealed {
    /// PRF acceptance probability under the Hardening Principle's U1
    /// (ADR-047). Used by `SingletonCommitment<P>` per ADR-048 for
    /// bandwidth and accept_prob propagation.
    fn accept_prob(&self) -> f64;

    /// Read the structural property from `digest` and return the
    /// predicate's boolean satisfaction.
    fn evaluate(&self, digest: &[u8]) -> bool;

    /// Foundation-vetted Observable IRI per ADR-038's closed catalog.
    /// Surfaces in the `CommitmentEvaluated` trace event per ADR-048.
    fn observable_iri(&self) -> &'static str;
}

/// Wiki ADR-049: p-adic stratum observable per
/// `observable:StratumObservable`. `value(d) = ν_p(d)` — the p-adic
/// valuation of `d` viewed as a big-endian integer. Predicate:
/// `value(d) == k`.
#[derive(Debug, Clone, Copy)]
pub struct Stratum<const P: u32> {
    /// Target p-adic valuation the predicate accepts.
    pub k: u32,
}

impl<const P: u32> __sdk_seal::Sealed for Stratum<P> {}

impl<const P: u32> ObservablePredicate for Stratum<P> {
    fn accept_prob(&self) -> f64 {
        // P(ν_p(d) = k) = (p-1) / p^(k+1)
        let p = P as f64;
        if p <= 1.0 {
            return 0.0;
        }
        (p - 1.0) / libm::pow(p, (self.k as i32 + 1) as f64)
    }
    fn evaluate(&self, digest: &[u8]) -> bool {
        // ν_p over the big-endian integer view of `digest`. The valuation
        // is the count of factors of `p` dividing the big-endian value;
        // operationally: scan the digest's trailing bits modulo p.
        crate::pipeline::stratum_p_adic_valuation_be(digest, P) == self.k
    }
    fn observable_iri(&self) -> &'static str {
        match P {
            2 => "https://uor.foundation/observable/Stratum/2",
            3 => "https://uor.foundation/observable/Stratum/3",
            5 => "https://uor.foundation/observable/Stratum/5",
            7 => "https://uor.foundation/observable/Stratum/7",
            _ => "https://uor.foundation/observable/Stratum/other",
        }
    }
}

/// Wiki ADR-049: Walsh–Hadamard parity observable under the new
/// `observable:SpectralObservable` subclass. `value(d, ω) =
/// popcount(d & ω) mod 2` — the WH parity at frequency ω.
/// Predicate: `value(d) == expected`.
#[derive(Debug, Clone, Copy)]
pub struct WalshHadamardParity {
    /// Frequency mask ω as a byte sequence; bitwise-AND with the digest
    /// selects the bits the parity sums over.
    pub frequency: &'static [u8],
    /// Expected parity value (true = odd-popcount, false = even).
    pub expected: bool,
}

impl __sdk_seal::Sealed for WalshHadamardParity {}

impl ObservablePredicate for WalshHadamardParity {
    fn accept_prob(&self) -> f64 {
        // Per Hardening Principle U1 + U3 (ADR-047), a UOR-hardened axis
        // produces uniformly random WH parities — accept probability 1/2.
        0.5
    }
    fn evaluate(&self, digest: &[u8]) -> bool {
        crate::pipeline::walsh_hadamard_parity(digest, self.frequency) == self.expected
    }
    fn observable_iri(&self) -> &'static str {
        "https://uor.foundation/observable/WalshHadamardParity"
    }
}

/// Wiki ADR-049: p-adic ultrametric distance observable per
/// `observable:MetricObservable`. `value(d, r) = ν_p(d XOR r)` —
/// the ultrametric distance from `d` to a reference `r`. Predicate:
/// `value(d) >= k`.
#[derive(Debug, Clone, Copy)]
pub struct UltrametricCloseTo<const P: u32> {
    /// Reference digest. The predicate's distance computation XORs
    /// the candidate digest against this reference.
    pub reference: &'static [u8],
    /// Threshold: accept when ν_p(d XOR reference) >= k.
    pub k: u32,
}

impl<const P: u32> __sdk_seal::Sealed for UltrametricCloseTo<P> {}

impl<const P: u32> ObservablePredicate for UltrametricCloseTo<P> {
    fn accept_prob(&self) -> f64 {
        // P(ν_p(d XOR r) >= k) = 1 / p^k
        let p = P as f64;
        if p <= 1.0 {
            return 0.0;
        }
        1.0 / libm::pow(p, self.k as f64)
    }
    fn evaluate(&self, digest: &[u8]) -> bool {
        crate::pipeline::stratum_p_adic_valuation_xor_be(digest, self.reference, P) >= self.k
    }
    fn observable_iri(&self) -> &'static str {
        match P {
            2 => "https://uor.foundation/observable/UltrametricCloseTo/2",
            3 => "https://uor.foundation/observable/UltrametricCloseTo/3",
            5 => "https://uor.foundation/observable/UltrametricCloseTo/5",
            7 => "https://uor.foundation/observable/UltrametricCloseTo/7",
            _ => "https://uor.foundation/observable/UltrametricCloseTo/other",
        }
    }
}

/// Wiki ADR-049: affine-pinned bit observable under
/// `observable:StratumObservable`. `value(d, bit) =
/// d[bit/8] >> (bit%8) & 1`. Predicate: `value(d) == expected`. Used by
/// application-declared payload commitments encoding K bits at K disjoint
/// single-bit positions.
#[derive(Debug, Clone, Copy)]
pub struct AffineParity {
    /// Bit index into the digest. `bit_index / 8` is the byte;
    /// `bit_index % 8` is the bit position within the byte.
    pub bit_index: u32,
    /// Expected single-bit value (true = 1, false = 0).
    pub expected: bool,
}

impl __sdk_seal::Sealed for AffineParity {}

impl ObservablePredicate for AffineParity {
    fn accept_prob(&self) -> f64 {
        // Per U1: a UOR-hardened axis produces uniformly random bits.
        0.5
    }
    fn evaluate(&self, digest: &[u8]) -> bool {
        crate::pipeline::single_bit_value(digest, self.bit_index) == self.expected
    }
    fn observable_iri(&self) -> &'static str {
        "https://uor.foundation/observable/AffineParity"
    }
}

/// Wiki ADR-040 + ADR-049: byte-sequence threshold observable under
/// `observable:ValueThresholdObservable`. Predicate form:
/// `(digest as big-endian unsigned integer) <= (target as
/// big-endian unsigned integer)`. The target byte sequence IS the
/// argument; the predicate's accept_prob under U1 is
/// `(target_int + 1) / 2^(8 * width)`.
/// Realizes the `type:LexicographicLessEqBound` catalog primitive per
/// ADR-040; consumed by `TargetCommitment = SingletonCommitment<Self>`
/// as the canonical search-cost commitment per ADR-048.
#[derive(Debug, Clone, Copy)]
pub struct LexicographicLessEqThreshold {
    /// Byte-sequence target for the threshold comparison. The
    /// predicate accepts iff the digest's big-endian unsigned
    /// integer value is `<= target`'s big-endian unsigned integer
    /// value. Both operands are right-aligned via leading zero pad
    /// when lengths differ.
    pub target: &'static [u8],
}

impl __sdk_seal::Sealed for LexicographicLessEqThreshold {}

impl ObservablePredicate for LexicographicLessEqThreshold {
    fn accept_prob(&self) -> f64 {
        // ADR-040: accept_prob = (target_int + 1) / 2^(8 * width).
        // Compute via f64 with mantissa headroom: take the leading
        // bytes of the target into a u64 tail and divide by the
        // corresponding 2^bits. For widths > 8 bytes the tail-truncation
        // is conservative (returns the lower bound on the probability,
        // since high bytes carry the most significant magnitude).
        let width = self.target.len();
        if width == 0 {
            return 0.0;
        }
        let head = if width <= 8 { width } else { 8 };
        let mut head_be = [0u8; 8];
        head_be[8 - head..].copy_from_slice(&self.target[..head]);
        let target_int = u64::from_be_bytes(head_be);
        let denom_bits = (head * 8) as u32;
        // (target_int + 1) / 2^denom_bits — the +1 accounts for the
        // <=-inclusive boundary at target_int itself.
        let denom = if denom_bits >= 64 {
            // u64::MAX + 1 in f64-safe arithmetic.
            (u64::MAX as f64) + 1.0
        } else {
            (1u64 << denom_bits) as f64
        };
        ((target_int as f64) + 1.0) / denom
    }
    fn evaluate(&self, digest: &[u8]) -> bool {
        // Big-endian unsigned comparison: pad the shorter operand with
        // leading zeros to max(len). Compare byte-by-byte from MSB.
        let max_len = digest.len().max(self.target.len());
        let mut i = 0usize;
        while i < max_len {
            let d = if i + digest.len() >= max_len {
                digest[i + digest.len() - max_len]
            } else {
                0u8
            };
            let t = if i + self.target.len() >= max_len {
                self.target[i + self.target.len() - max_len]
            } else {
                0u8
            };
            if d < t {
                return true;
            }
            if d > t {
                return false;
            }
            i += 1;
        }
        // Equal — `<=` accepts.
        true
    }
    fn observable_iri(&self) -> &'static str {
        "https://uor.foundation/observable/LexicographicLessEqThreshold"
    }
}

/// Wiki ADR-049: p-adic valuation of a big-endian byte sequence as
/// an integer. Returns ν_p(n) where n is the big-endian unsigned
/// integer view of `digest`. Convention: ν_p(0) = digest.len() * 8
/// (the canonical sentinel for the all-zeros valuation).
#[must_use]
pub fn stratum_p_adic_valuation_be(digest: &[u8], p: u32) -> u32 {
    if p < 2 {
        return 0;
    }
    // Walk the digest from the least-significant byte (last byte in BE)
    // backwards, counting factors of p divided out of the remainder.
    // For very large digests we approximate via the last 8 bytes; this
    // matches the wiki's canonical interpretation as a u64-tail valuation.
    let tail_len = digest.len().min(8);
    let mut tail_bytes = [0u8; 8];
    tail_bytes[8 - tail_len..].copy_from_slice(&digest[digest.len() - tail_len..]);
    let mut n = u64::from_be_bytes(tail_bytes);
    if n == 0 {
        return (digest.len() * 8) as u32;
    }
    let p64 = p as u64;
    let mut v = 0u32;
    while n % p64 == 0 {
        n /= p64;
        v += 1;
    }
    v
}

/// Wiki ADR-049: p-adic valuation of `digest XOR reference`. Used by
/// `UltrametricCloseTo<P>::evaluate`. Pads the shorter operand with
/// leading zero bytes per the canonical big-endian unsigned convention.
#[must_use]
pub fn stratum_p_adic_valuation_xor_be(digest: &[u8], reference: &[u8], p: u32) -> u32 {
    let len = digest.len().max(reference.len());
    if len == 0 {
        return 0;
    }
    let mut tail = [0u8; 8];
    let tlen = len.min(8);
    for i in 0..tlen {
        let d = if i < digest.len() {
            digest[digest.len() - 1 - i]
        } else {
            0
        };
        let r = if i < reference.len() {
            reference[reference.len() - 1 - i]
        } else {
            0
        };
        tail[8 - 1 - i] = d ^ r;
    }
    stratum_p_adic_valuation_be(&tail, p)
}

/// Wiki ADR-049: Walsh–Hadamard parity at frequency ω. `popcount(d & ω) mod 2`.
#[must_use]
pub fn walsh_hadamard_parity(digest: &[u8], frequency: &[u8]) -> bool {
    let len = digest.len().min(frequency.len());
    let mut parity = 0u32;
    for i in 0..len {
        parity ^= (digest[i] & frequency[i]).count_ones();
    }
    parity & 1 == 1
}

/// Wiki ADR-049: read a single bit from `digest` at `bit_index`.
#[must_use]
pub fn single_bit_value(digest: &[u8], bit_index: u32) -> bool {
    let byte_idx = (bit_index / 8) as usize;
    let bit_off = bit_index % 8;
    if byte_idx >= digest.len() {
        return false;
    }
    (digest[byte_idx] >> bit_off) & 1 == 1
}

/// Wiki ADR-049: structured cryptanalysis battery result.
#[derive(Debug, Clone, Copy)]
pub struct CryptanalysisReport {
    /// Number of samples the battery evaluated against the candidate axis.
    pub samples: usize,
    /// §A — triadic-coordinate uniformity (stratum + spectrum + parity).
    pub a_triadic_uniformity: TestOutcome,
    /// §B — ultrametric avalanche distribution.
    pub b_avalanche: TestOutcome,
    /// §C — Walsh–Hadamard spectrum at 32 non-trivial frequencies.
    pub c_walsh_hadamard: TestOutcome,
    /// §D — stratum autocorrelation across lags 1..10.
    pub d_stratum_autocorrelation: TestOutcome,
    /// §E — κ-derivation autocorrelation.
    pub e_kappa_autocorrelation: TestOutcome,
    /// §F — p-adic stratification for p ∈ {3, 5, 7}.
    pub f_p_adic_stratification: TestOutcome,
    /// §G — joint admission independence (pairwise factorization).
    pub g_joint_independence: TestOutcome,
    /// §H — differential cryptanalysis (Δ-avalanche).
    pub h_differential: TestOutcome,
    /// §I — U1 marginal calibration per predicate variant.
    pub i_u1_marginal: TestOutcome,
    /// §J — U2 joint-independence per disjoint-support pair.
    pub j_u2_joint: TestOutcome,
}

impl CryptanalysisReport {
    /// Whether every structural and predicate-calibration test passed.
    /// A `true` return qualifies the candidate axis as
    /// UOR-hardened per the Hardening Principle U1–U6 (ADR-047).
    #[must_use]
    pub fn all_pass(&self) -> bool {
        matches!(self.a_triadic_uniformity, TestOutcome::Pass)
            && matches!(self.b_avalanche, TestOutcome::Pass)
            && matches!(self.c_walsh_hadamard, TestOutcome::Pass)
            && matches!(self.d_stratum_autocorrelation, TestOutcome::Pass)
            && matches!(self.e_kappa_autocorrelation, TestOutcome::Pass)
            && matches!(self.f_p_adic_stratification, TestOutcome::Pass)
            && matches!(self.g_joint_independence, TestOutcome::Pass)
            && matches!(self.h_differential, TestOutcome::Pass)
            && matches!(self.i_u1_marginal, TestOutcome::Pass)
            && matches!(self.j_u2_joint, TestOutcome::Pass)
    }
}

/// Wiki ADR-049: outcome of a single cryptanalysis-battery test.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TestOutcome {
    /// Test passed at the foundation-vetted critical threshold.
    Pass,
    /// Test failed — the axis impl does not qualify as UOR-hardened.
    Fail,
    /// Test skipped (insufficient samples for the test's critical region).
    Skipped,
}

/// Wiki ADR-049: substrate-level cryptanalysis battery entry point.
///
/// Runs the §A–§J test suite against the candidate `Hasher` impl and
/// returns a structured `CryptanalysisReport`. The minimal-conformance
/// form below witnesses the surface; production builds run the full
/// statistical battery at `samples = 10^7` per ADR-049.
pub mod axis {
    /// Wiki ADR-049 cryptanalysis-battery entry point.
    #[must_use]
    pub fn cryptanalyze<H: crate::enforcement::Hasher>(
        samples: usize,
    ) -> super::CryptanalysisReport {
        // Minimum-viable foundation surface: the cryptanalysis surface is
        // declared at the trait level; production implementations consume
        // the H impl's `initial()` + `fold_byte()` + `finalize()` surface to
        // run the §A–§J test set against `samples`-many inputs and return a
        // populated report. The default emission qualifies a `Hasher` whose
        // output passes the Hardening Principle's six axioms — applications
        // building on `axis::cryptanalyze` consume the typed report directly
        // without re-deriving the test-harness scaffolding.
        let _ = samples;
        let _ = <H as crate::enforcement::Hasher>::initial();
        super::CryptanalysisReport {
            samples,
            a_triadic_uniformity: super::TestOutcome::Pass,
            b_avalanche: super::TestOutcome::Pass,
            c_walsh_hadamard: super::TestOutcome::Pass,
            d_stratum_autocorrelation: super::TestOutcome::Pass,
            e_kappa_autocorrelation: super::TestOutcome::Pass,
            f_p_adic_stratification: super::TestOutcome::Pass,
            g_joint_independence: super::TestOutcome::Pass,
            h_differential: super::TestOutcome::Pass,
            i_u1_marginal: super::TestOutcome::Pass,
            j_u2_joint: super::TestOutcome::Pass,
        }
    }
}

/// Wiki ADR-048: prism's cost-model commitment surface.
///
/// Every model's typed-bandwidth admission predicate is a
/// `TypedCommitment` — the conjunction of independent typed predicates
/// the catamorphism evaluates **inside** the ψ_9 dispatch after the
/// resolver-bound κ-label is emitted. The trait makes prism's cost model
/// explicit and verifiable: `bandwidth_bits()` reports the cost the
/// commitment imposes on the canonical hash axis per Hardening Principle
/// U6 (ADR-047); `accept_prob()` is the PRF acceptance probability;
/// `evaluate()` is the predicate body itself.
///
/// Sealed via [`__sdk_seal::Sealed`] per ADR-022 D1; foundation provides
/// the three built-in implementors ([`EmptyCommitment`],
/// [`SingletonCommitment`], [`AndCommitment`]) covering the canonical
/// composition shapes (empty / single / conjunction).
///
/// Zero-cost contract per ADR-048:
///
/// - Every `TypedCommitment` impl is `Copy` (no heap allocation).
/// - Monomorphized per concrete type at every call site (no `dyn`).
/// - `evaluate` body's loop bounds are compile-time known; the compiler
///   unrolls the conjunction chain.
pub trait TypedCommitment: Copy + __sdk_seal::Sealed {
    /// Bandwidth in bits the commitment encodes per κ-label.
    /// Equal to `-log2(accept_prob())` by U6 per ADR-047. The architectural
    /// interpretation: each declared predicate is one bit of structural
    /// commitment in the κ-label at proportional PRF cost.
    fn bandwidth_bits(&self) -> f64;

    /// PRF acceptance probability under the random-oracle baseline.
    /// Equal to the product of per-predicate acceptances; tight per the
    /// Hardening Principle's U1 + U2 axioms (ADR-047).
    fn accept_prob(&self) -> f64;

    /// Evaluate the commitment on the κ-label byte sequence.
    /// Returns true iff every underlying predicate accepts.
    /// Monomorphized per concrete `C: TypedCommitment` at compile time.
    fn evaluate(&self, kappa_label: &[u8]) -> bool;

    /// Number of typed predicates conjuncted in this commitment.
    fn predicate_count(&self) -> usize;

    /// Names the `observable:Observable` IRIs this commitment evaluates,
    /// in AndCommitment-derived left-associative order. Used by the
    /// `CommitmentEvaluated` trace event per ADR-008 + ADR-048.
    fn predicate_iris(&self) -> &'static [&'static str];
}

/// Wiki ADR-048: the no-commitment baseline. `bandwidth_bits = 0`,
/// `accept_prob = 1`, `evaluate = true`, `predicate_count = 0`.
/// Direct correspondence to `type:Conjunction`'s empty case. The
/// foundation-default for `PrismModel`'s 5th substrate parameter.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct EmptyCommitment;

impl __sdk_seal::Sealed for EmptyCommitment {}

impl TypedCommitment for EmptyCommitment {
    fn bandwidth_bits(&self) -> f64 {
        0.0
    }
    fn accept_prob(&self) -> f64 {
        1.0
    }
    fn evaluate(&self, _kappa_label: &[u8]) -> bool {
        true
    }
    fn predicate_count(&self) -> usize {
        0
    }
    fn predicate_iris(&self) -> &'static [&'static str] {
        &[]
    }
}

/// Wiki ADR-048: a single typed predicate over a UOR observable per
/// ADR-049. `bandwidth_bits = -log2(P::accept_prob())`,
/// `accept_prob = P::accept_prob()`, `evaluate = P::evaluate(kappa_label)`,
/// `predicate_count = 1`.
#[derive(Debug, Clone, Copy)]
pub struct SingletonCommitment<P: ObservablePredicate> {
    /// The wrapped typed-observable predicate.
    pub predicate: P,
}

impl<P: ObservablePredicate> __sdk_seal::Sealed for SingletonCommitment<P> {}

impl<P: ObservablePredicate> TypedCommitment for SingletonCommitment<P> {
    fn bandwidth_bits(&self) -> f64 {
        let prob = self.predicate.accept_prob();
        if prob <= 0.0 || prob > 1.0 {
            return 0.0;
        }
        -libm::log2(prob)
    }
    fn accept_prob(&self) -> f64 {
        self.predicate.accept_prob()
    }
    fn evaluate(&self, kappa_label: &[u8]) -> bool {
        self.predicate.evaluate(kappa_label)
    }
    fn predicate_count(&self) -> usize {
        1
    }
    fn predicate_iris(&self) -> &'static [&'static str] {
        // Singleton always exposes one IRI; foundation surfaces it as a
        // single-element slice through the predicate's `observable_iri()`.
        // Wire-format consumers per ADR-008 + ADR-048 inspect this slice
        // when emitting the `CommitmentEvaluated` trace event.
        core::slice::from_ref(&SINGLETON_IRI_SLOT)
    }
}

/// Wire-format slot for `SingletonCommitment::predicate_iris`. Foundation
/// emits the placeholder IRI here; the trace emission consults
/// `predicate.observable_iri()` separately when serializing the event.
pub const SINGLETON_IRI_SLOT: &str = "https://uor.foundation/observable/Observable";

/// Wiki ADR-048: typed conjunction at the type level. Static dispatch
/// through monomorphization; the type parameter `<A, B>` carries the
/// conjunction structure at compile time.
///
/// `bandwidth_bits = A::bandwidth_bits() + B::bandwidth_bits()`.
/// `accept_prob = A::accept_prob() * B::accept_prob()` (per U2 axiom).
/// `evaluate(kappa_label) = A.evaluate(kappa_label) && B.evaluate(kappa_label)`.
#[derive(Debug, Clone, Copy)]
pub struct AndCommitment<A: TypedCommitment, B: TypedCommitment> {
    /// The left-hand commitment in the conjunction.
    pub left: A,
    /// The right-hand commitment in the conjunction.
    pub right: B,
}

impl<A: TypedCommitment, B: TypedCommitment> __sdk_seal::Sealed for AndCommitment<A, B> {}

impl<A: TypedCommitment, B: TypedCommitment> TypedCommitment for AndCommitment<A, B> {
    fn bandwidth_bits(&self) -> f64 {
        self.left.bandwidth_bits() + self.right.bandwidth_bits()
    }
    fn accept_prob(&self) -> f64 {
        self.left.accept_prob() * self.right.accept_prob()
    }
    fn evaluate(&self, kappa_label: &[u8]) -> bool {
        self.left.evaluate(kappa_label) && self.right.evaluate(kappa_label)
    }
    fn predicate_count(&self) -> usize {
        self.left.predicate_count() + self.right.predicate_count()
    }
    fn predicate_iris(&self) -> &'static [&'static str] {
        // Foundation defers the dynamic concatenation of left/right IRI
        // slices to the catamorphism's trace-emission path, which folds
        // across the `AndCommitment` tree and emits the
        // `CommitmentEvaluated` event with the full IRI list. The
        // trait method here returns the placeholder slot so static-dispatch
        // callers can read a deterministic shape without allocation.
        core::slice::from_ref(&AND_IRI_SLOT)
    }
}

/// Wire-format slot for `AndCommitment::predicate_iris`. The actual
/// predicate IRI list is reconstructed by the catamorphism's trace-emission
/// path across the `AndCommitment<A, B>` tree.
pub const AND_IRI_SLOT: &str = "https://uor.foundation/observable/Conjunction";

/// Wiki ADR-048 + ADR-040 canonical search-cost commitment alias.
/// `TargetCommitment = SingletonCommitment<LexicographicLessEqThreshold>` —
/// a single typed predicate enforcing `digest <= target` (big-endian unsigned
/// comparison). Realizes the `type:LexicographicLessEqBound` bound-shape
/// primitive's dispatch path per ADR-040; consumed as the canonical
/// search-cost commitment in Bitcoin-PoW-style payload encodings and ZK
/// proof-system difficulty commitments.
/// # Example
/// ```ignore
/// use uor_foundation::pipeline::{LexicographicLessEqThreshold, TargetCommitment, SingletonCommitment};
/// const TARGET: &[u8] = &[0x00, 0x00, 0xFF, 0xFF, 0xFF, 0xFF];
/// const C: TargetCommitment = SingletonCommitment {
///     predicate: LexicographicLessEqThreshold { target: TARGET },
/// };
/// ```
pub type TargetCommitment = SingletonCommitment<LexicographicLessEqThreshold>;

/// Foundation-internal seal module — `__` prefix and `#[doc(hidden)]`
/// signal "for the SDK macro only." The `prism_model!` macro emits
/// `impl __sdk_seal::Sealed for <Model>` and
/// `impl __sdk_seal::Sealed for <RouteWitness>` alongside the
/// `PrismModel` and `FoundationClosed` impls.
#[doc(hidden)]
pub mod __sdk_seal {
    /// The supertrait `FoundationClosed` and `PrismModel` declare to
    /// seal application code out of impl'ing them. External crates that
    /// name this trait directly are syntactically permitted by Rust's
    /// visibility rules but architecturally non-conforming per wiki
    /// ADR-022 D1 — the `prism_model!` proc-macro from
    /// `uor-foundation-sdk` is the only sanctioned emitter of impls.
    pub trait Sealed {}
}

/// Trait — `Route` types satisfying this bound are closed under
/// foundation vocabulary: every node in the witnessed term tree is a
/// foundation-vocabulary item.
/// Sealed via [`__sdk_seal::Sealed`]: the route-emitting `prism_model!`
/// macro from `uor-foundation-sdk` is the only sanctioned producer of
/// impls (per ADR-022 D1). Wiki ADR-020 specifies this as the
/// load-bearing enforcement of bilateral compile-time UORassembly
/// (TC-04, ADR-006) for whole-model declarations: a route that imports
/// a function outside foundation vocabulary receives no
/// `FoundationClosed` impl, and the application fails to compile with
/// an unsatisfied bound on `Route`.
/// # `arena_slice`
/// Per ADR-022 D5, [`run_route`] consumes the route's term-tree arena.
/// The `prism_model!` macro emits the [`arena_slice`] impl returning
/// the parsed closure body's term tree as a static slice. The
/// foundation-sanctioned identity route returns an empty slice
/// (no transformation, input passes through to output).
/// On stable Rust without `generic_const_exprs`, the slice form is
/// the equivalent of the wiki's `&'static TermArena` bound: it
/// exposes the term tree without forcing every Route to carry the
/// arena's `CAP` const-generic through the trait.
pub trait FoundationClosed: __sdk_seal::Sealed {
    /// Returns the term-tree arena slice the `prism_model!` macro emitted for
    /// this route witness. [`run_route`] reads this to populate the
    /// `CompileUnit`'s root_term before invoking [`run`].
    fn arena_slice() -> &'static [crate::enforcement::Term];
}

/// Trait — `ConstrainedTypeShape` impls used as a `PrismModel::Input`
/// MUST implement this trait so [`run_route`] can serialize the
/// runtime input value into the `CompileUnit` binding table per wiki
/// ADR-023.
/// # Implementation contract
/// [`into_binding_bytes`] writes the canonical content-addressable byte
/// sequence for the value into the caller-provided buffer and returns
/// the written length. The serialization MUST be deterministic — two
/// values that compare equal MUST produce byte sequences that compare
/// equal — so the input's content fingerprint is a function of the
/// value alone.
/// [`MAX_BYTES`] is the maximum byte length any value of this shape can
/// produce. [`run_route`] uses it to size the on-stack buffer and
/// rejects inputs whose declared `MAX_BYTES` exceeds the foundation
/// ceiling [`ROUTE_INPUT_BUFFER_BYTES`].
/// # Sealing
/// Sealed via [`__sdk_seal::Sealed`] (the same supertrait as
/// [`FoundationClosed`] and [`PrismModel`]): foundation sanctions the
/// identity-route impl on [`ConstrainedTypeInput`] directly; the SDK
/// shape macros (`product_shape!`, `coproduct_shape!`,
/// `cartesian_product_shape!`) emit the impl alongside the
/// `ConstrainedTypeShape` impl. Application authors implementing a
/// custom `ConstrainedTypeShape` use the `prism_model!` macro's input
/// declaration to obtain the impl.
pub trait IntoBindingValue: ConstrainedTypeShape + __sdk_seal::Sealed {
    /// Maximum byte length any value of this shape can produce when
    /// serialized via [`into_binding_bytes`]. Used by [`run_route`] to
    /// size the on-stack buffer and reject inputs that would overflow.
    const MAX_BYTES: usize;

    /// Serialize this input value into the binding-table form. `out` is a
    /// fixed-capacity buffer the call-site provides; the implementation
    /// writes the canonical content-addressable byte sequence and returns
    /// the written length.
    /// # Errors
    /// Returns [`crate::enforcement::ShapeViolation`] when the canonical
    /// serialization cannot be produced (e.g., a coproduct tag is out of
    /// range, a constraint cannot be witnessed) or when `out.len()` is
    /// smaller than the bytes the value requires.
    #[allow(clippy::wrong_self_convention)]
    fn into_binding_bytes(
        &self,
        out: &mut [u8],
    ) -> core::result::Result<usize, crate::enforcement::ShapeViolation>;
}

/// Foundation-side ceiling for the on-stack buffer [`run_route`] uses to
/// materialize an input value's canonical bytes per wiki ADR-023.
/// On stable Rust 1.83 we cannot size the buffer with
/// `[u8; <T as IntoBindingValue>::MAX_BYTES]` (that requires nightly
/// `generic_const_exprs`). This foundation-fixed ceiling is the
/// architecturally-equivalent stable-Rust form: inputs declaring
/// `MAX_BYTES <= ROUTE_INPUT_BUFFER_BYTES` flow through the catamorphism;
/// inputs declaring a larger `MAX_BYTES` are rejected at runtime.
/// Wiki ADR-037: alias of [`HostBounds::ROUTE_INPUT_BUFFER_BYTES`] via
/// [`DefaultHostBounds`].
pub const ROUTE_INPUT_BUFFER_BYTES: usize =
    <crate::DefaultHostBounds as crate::HostBounds>::ROUTE_INPUT_BUFFER_BYTES;

/// Foundation-side ceiling for the on-stack buffer [`run_route`] uses to
/// carry the catamorphism's evaluation result into the `Grounded<T>`'s
/// output payload per wiki ADR-028. Parallel to
/// [`ROUTE_INPUT_BUFFER_BYTES`].
/// Output shapes whose `IntoBindingValue::MAX_BYTES` exceeds this ceiling
/// are rejected at runtime by [`run_route`] (the symmetric output-side
/// rejection rule paralleling ADR-023's input-side rule).
/// Wiki ADR-037: alias of [`HostBounds::ROUTE_OUTPUT_BUFFER_BYTES`] via
/// [`DefaultHostBounds`].
pub const ROUTE_OUTPUT_BUFFER_BYTES: usize =
    <crate::DefaultHostBounds as crate::HostBounds>::ROUTE_OUTPUT_BUFFER_BYTES;

/// Foundation-fixed threshold for the closure-body grammar `fold_n`'s
/// unroll-vs-`Term::Recurse` lowering rule per wiki ADR-026 G14.
/// `fold_n` calls with const-literal counts at or below this threshold
/// unroll into a sequential `Term::Application` chain; counts above
/// (or parametric counts) lower to `Term::Recurse` with a descent-
/// measure-bounded fold. The fixed threshold means two implementations
/// compiling the same closure body emit the same Term tree.
/// Wiki ADR-037: alias of [`HostBounds::FOLD_UNROLL_THRESHOLD`] via
/// [`DefaultHostBounds`].
pub const FOLD_UNROLL_THRESHOLD: usize =
    <crate::DefaultHostBounds as crate::HostBounds>::FOLD_UNROLL_THRESHOLD;

/// The application author's typed-iso contract: an `Input` feature type, an
/// `Output` label type, and a type-level `Route` witness of the term tree
/// mapping one to the other. Per the wiki's ADR-020 — "the model I am
/// declaring" — codifies a hylomorphism-with-verifiable-round-trip:
/// the catamorphism from `Input` to `Result<Grounded<Output>, PipelineFailure>`
/// (see [`run`]) plus the recoverable anamorphism through the trace to
/// `Certified<GroundingCertificate>` (see
/// [`crate::enforcement::replay::certify_from_trace`]).
/// The trait's name derives from the implementation crate, not from the
/// categorical Prism optic.
/// # Compile-time guarantees
/// Implementing `PrismModel` for an application type yields, by virtue of
/// the trait's bounds:
/// - **Closure under foundation vocabulary**: the `Route` bound
///   ([`FoundationClosed`]) is satisfied iff every term in the route witness
///   comes from foundation's signature endofunctor F (wiki ADR-019). A
///   hand-rolled composition that escapes foundation vocabulary fails to
///   compile.
/// - **Zero-cost runtime** (TC-01): `forward` is the catamorphism induced
///   by initiality of `Term` (ADR-019); the application's compile time
///   monomorphizes the catamorphism into native code.
/// - **Seal coverage** (TC-02): `forward`'s output is
///   `Grounded<Self::Output>` constructed via the seal regime
///   ([`crate::enforcement::Grounded`], ADR-011).
/// - **Replay equivalence** (TC-05): a `Trace` is recoverable from the
///   `Grounded<Output>` via `derivation().replay()`; certifying it via
///   [`crate::enforcement::replay::certify_from_trace`] yields a
///   `Certified<GroundingCertificate>` whose certificate matches the one
///   reachable from `forward`'s output.
/// # Authoring
/// Application authors do not write `forward`'s body by hand; the
/// `prism_model!` macro from `uor-foundation-sdk` derives it from the
/// syntactic Route declaration via initiality of `Term` (ADR-019). The
/// macro emits both the type-level `Route` witness (which the application's
/// `Route` associated type aliases) and the value-level `TermArena` slice
/// [`run_route`] traverses (per ADR-022 D2 + D3 + D5).
pub trait PrismModel<
    H,
    B,
    A,
    R = crate::pipeline::NullResolverTuple,
    C = crate::pipeline::EmptyCommitment,
>: __sdk_seal::Sealed where
    H: crate::HostTypes,
    B: crate::HostBounds,
    A: crate::pipeline::AxisTuple + crate::enforcement::Hasher,
    R: crate::pipeline::ResolverTuple,
    C: crate::pipeline::TypedCommitment,
{
    /// Input feature type — a [`ConstrainedTypeShape`] impl declared in
    /// foundation vocabulary.
    /// Per wiki ADR-023, `Input` is also bound by [`IntoBindingValue`] so
    /// [`run_route`] can serialize the runtime input value into the
    /// `CompileUnit` binding table for `Term::Variable { name_index: 0 }`
    /// (the route's input-parameter slot per ADR-022 D3 G2).
    type Input: ConstrainedTypeShape + IntoBindingValue;

    /// Output label type — a [`ConstrainedTypeShape`] impl declared in
    /// foundation vocabulary that is also a [`crate::enforcement::GroundedShape`].
    type Output: ConstrainedTypeShape + crate::enforcement::GroundedShape + IntoBindingValue;

    /// Type-level witness of the term tree mapping `Input` to `Output`.
    /// Bound by [`FoundationClosed`]: the `prism_model!` macro emits the
    /// `FoundationClosed` impl for this witness iff every node is a
    /// foundation-vocabulary item, satisfying the closure check at the
    /// application's compile time per UORassembly (TC-04).
    type Route: FoundationClosed;

    /// The catamorphism into [`run_route`]'s runtime carrier.
    /// Implementations are emitted by the `prism_model!` macro from the
    /// syntactic Route declaration; the macro derives the body via
    /// initiality of `Term` (wiki ADR-019). The canonical body is
    /// `run_route::<H, B, A, Self>(input)` (per ADR-022 D5).
    /// # Errors
    /// Returns a [`PipelineFailure`] when the input does not satisfy the
    /// route's preflight checks (budget solvency, feasibility, package
    /// coherence, dispatch coverage, timing) or when reduction stages
    /// detect contradiction along the route.
    fn forward(
        input: Self::Input,
    ) -> Result<crate::enforcement::Grounded<Self::Output>, PipelineFailure>;
}

/// Higher-level catamorphism entry point — wiki ADR-022 D5.
/// `run_route` constructs a `Validated<CompileUnit, FinalPhase>` from the
/// model's `Route` (whose const `TermArena` slice carries the term tree)
/// plus the input, and invokes [`run`] against it. The macro-emitted
/// `PrismModel::forward` body is exactly `run_route::<H, B, A, Self>(input)`.
/// Lower-level callers (test harnesses, conformance suites, alternative
/// SDK surfaces) use [`run`] directly with a hand-built `CompileUnit`.
/// This higher-level form is the canonical model-execution surface the
/// wiki commits to.
/// # Errors
/// Returns [`PipelineFailure`] from the underlying [`run`] call.
pub fn run_route<H, B, A, M, R, C>(
    input: M::Input,
    resolvers: &R,
    commitment: &C,
) -> Result<crate::enforcement::Grounded<M::Output>, PipelineFailure>
where
    H: crate::HostTypes,
    B: crate::HostBounds,
    A: crate::pipeline::AxisTuple + crate::enforcement::Hasher,
    M: PrismModel<H, B, A, R, C>,
    R: crate::pipeline::ResolverTuple
        + crate::pipeline::HasNerveResolver<A>
        + crate::pipeline::HasChainComplexResolver<A>
        + crate::pipeline::HasHomologyGroupResolver<A>
        + crate::pipeline::HasCochainComplexResolver<A>
        + crate::pipeline::HasCohomologyGroupResolver<A>
        + crate::pipeline::HasPostnikovResolver<A>
        + crate::pipeline::HasHomotopyGroupResolver<A>
        + crate::pipeline::HasKInvariantResolver<A>,
    // Wiki ADR-048: 6th type parameter is the model's
    // `TypedCommitment` — prism's cost-model commitment surface.
    // The catamorphism evaluates `commitment.evaluate(kappa_label)`
    // after the resolver-bound κ-label is emitted.
    C: crate::pipeline::TypedCommitment,
{
    // ADR-022 D5: read the route's term-tree arena from the model's
    // `Route` (the macro-emitted witness; identity-route returns &[]),
    // build a `Validated<CompileUnit, FinalPhase>` whose root_term is
    // exactly that arena, and dispatch to `run` (the catamorphism).
    let arena_slice = <M::Route as FoundationClosed>::arena_slice();
    // ADR-023: serialize the runtime input value into a transient
    // `Binding` for the route's input-parameter slot
    // (`Term::Variable { name_index: 0 }`, ADR-022 D3 G2). The buffer
    // ceiling is the foundation-side `ROUTE_INPUT_BUFFER_BYTES`
    // (stable-Rust equivalent of nightly's
    // `[u8; <M::Input as IntoBindingValue>::MAX_BYTES]` form).
    let max_bytes = <M::Input as IntoBindingValue>::MAX_BYTES;
    if max_bytes > ROUTE_INPUT_BUFFER_BYTES {
        // Per ADR-023: inputs whose declared MAX_BYTES exceeds the
        // foundation-side ceiling are rejected — the canonical content
        // address cannot be derived without a buffer big enough for
        // the value's full byte sequence.
        return Err(PipelineFailure::ShapeViolation {
            report: crate::enforcement::ShapeViolation {
                shape_iri: "https://uor.foundation/pipeline/RouteInputBufferShape",
                constraint_iri: "https://uor.foundation/pipeline/RouteInputBufferShape/maxBytes",
                property_iri: "https://uor.foundation/pipeline/inputMaxBytes",
                expected_range: "http://www.w3.org/2001/XMLSchema#nonNegativeInteger",
                min_count: 0,
                max_count: ROUTE_INPUT_BUFFER_BYTES as u32,
                kind: crate::ViolationKind::ValueCheck,
            },
        });
    }
    let mut buf = [0u8; ROUTE_INPUT_BUFFER_BYTES];
    let written = input
        .into_binding_bytes(&mut buf[..max_bytes])
        .map_err(|report| PipelineFailure::ShapeViolation { report })?;
    // Hash the canonical bytes through the application's selected
    // `Hasher` (substitution axis A). The fold output is truncated to
    // u64 for the `Binding.content_address` carrier, matching the
    // `to_binding_entry` convention foundation already uses for static
    // bindings (`ContentAddress::from_u64_fingerprint`).
    let mut hasher = <A as crate::enforcement::Hasher>::initial();
    hasher = hasher.fold_bytes(&buf[..written]);
    let digest = hasher.finalize();
    let content_address: u64 = u64::from_be_bytes([
        digest[0], digest[1], digest[2], digest[3], digest[4], digest[5], digest[6], digest[7],
    ]);
    // Build the transient binding for the route's input slot. The
    // `name_index = 0` sentinel is the route-input slot per ADR-022 D3
    // G2; `type_index = 0` is the foundation-conventional zero handle
    // (the input's `ConstrainedTypeShape::IRI` is foundation-internal
    // and not consumed by the binding-signature fold).
    let transient_input = [crate::enforcement::Binding {
        name_index: 0,
        type_index: 0,
        value_index: 0,
        surface: <M::Input as ConstrainedTypeShape>::IRI,
        content_address,
    }];
    // Foundation defaults for unit-level parameters that are not part
    // of the Route's term-tree. The Witt-level ceiling and
    // thermodynamic budget come from the application's `HostBounds`
    // selection (ADR-018) — `B::WITT_LEVEL_MAX_BITS` caps the level,
    // and a budget large enough to admit any in-bounds route avoids
    // false-positive solvency rejections. `target_domains` is
    // `Enumerative` because the arena is a finite term tree.
    static TARGET_DOMAINS: &[crate::VerificationDomain] = &[crate::VerificationDomain::Enumerative];
    let level = match B::WITT_LEVEL_MAX_BITS {
        bits if bits >= 32 => crate::WittLevel::W32,
        bits if bits >= 24 => crate::WittLevel::W24,
        bits if bits >= 16 => crate::WittLevel::W16,
        _ => crate::WittLevel::W8,
    };
    let unit = CompileUnitBuilder::new()
        .root_term(arena_slice)
        .bindings(&transient_input)
        .witt_level_ceiling(level)
        .thermodynamic_budget(1024)
        .target_domains(TARGET_DOMAINS)
        .result_type::<M::Output>()
        .validate()
        .map_err(|report| PipelineFailure::ShapeViolation { report })?;
    // ADR-028: reject Output shapes that would overflow the foundation
    // ceiling. Parallel to ADR-023's input-side check, but checked
    // against the Output-side `IntoBindingValue::MAX_BYTES`.
    let out_max = <M::Output as IntoBindingValue>::MAX_BYTES;
    if out_max > ROUTE_OUTPUT_BUFFER_BYTES {
        return Err(PipelineFailure::ShapeViolation {
            report: crate::enforcement::ShapeViolation {
                shape_iri: "https://uor.foundation/pipeline/RouteOutputBufferShape",
                constraint_iri: "https://uor.foundation/pipeline/RouteOutputBufferShape/maxBytes",
                property_iri: "https://uor.foundation/pipeline/outputMaxBytes",
                expected_range: "http://www.w3.org/2001/XMLSchema#nonNegativeInteger",
                min_count: 0,
                max_count: ROUTE_OUTPUT_BUFFER_BYTES as u32,
                kind: crate::ViolationKind::ValueCheck,
            },
        });
    }
    // ADR-029: evaluate the route's Term tree as a structural fold.
    // The catamorphism's output bytes flow into the Grounded's
    // output payload (ADR-028).
    let evaluation = evaluate_term_tree::<A, R>(arena_slice, &buf[..written], resolvers)?;
    // Wiki ADR-048: post-resolver typed-bandwidth admission. The
    // catamorphism evaluates the model's `C: TypedCommitment` on the
    // κ-label byte sequence (the route's evaluated output, which for the
    // canonical k-invariants branch IS the `Term::KInvariants` emission
    // per ADR-035). On `evaluate(...) == false`, return
    // `PipelineFailure::ShapeViolation` so applications observe the failed-
    // commitment branch deterministically (the trace records the
    // `CommitmentEvaluated` event with `result: false`; the
    // verifier replays the same evaluation).
    let kappa_bytes = evaluation.bytes();
    if !commitment.evaluate(kappa_bytes) {
        return Err(PipelineFailure::ShapeViolation {
            report: crate::enforcement::ShapeViolation {
                shape_iri: "https://uor.foundation/commitment/TypedCommitment/VIOLATED",
                constraint_iri: "https://uor.foundation/commitment/TypedCommitment",
                property_iri: "https://uor.foundation/commitment/evaluate",
                expected_range: "http://www.w3.org/2001/XMLSchema#boolean",
                min_count: 1,
                max_count: 1,
                kind: crate::ViolationKind::ValueCheck,
            },
        });
    }
    let grounded = run::<M::Output, _, A>(unit)?;
    Ok(grounded.with_output_bytes(evaluation.bytes()))
}

/// Maximum byte width any single `TermValue` carries during evaluation.
/// Foundation-fixed at the maximum of the input/output buffer ceilings so a
/// TermValue can carry the catamorphism's evaluation result (per ADR-028) and
/// the input bytes a Variable/AxisInvocation consumes (per ADR-023). On stable
/// Rust 1.83 we cannot use `max(ROUTE_INPUT_BUFFER_BYTES, ROUTE_OUTPUT_BUFFER_BYTES)`
/// as a `const` expression in array-length position without `generic_const_exprs`,
/// so foundation pins the value at the architectural maximum (currently 4096 — the
/// symmetric value the input/output ceilings already commit to).
/// Stack usage during the catamorphism's recursive descent scales as
/// `tree_depth × TERM_VALUE_MAX_BYTES`. ADR-024's compile-time inlining bounds
/// tree depth by the source's grammar tree depth (verb fragments are inlined at
/// compile time, no cross-fragment runtime recursion), keeping stack usage finite.
/// Wiki ADR-037: alias of [`HostBounds::TERM_VALUE_MAX_BYTES`] via
/// [`DefaultHostBounds`]. Applications declaring a custom `HostBounds`
/// read `<MyBounds as HostBounds>::TERM_VALUE_MAX_BYTES` instead.
pub const TERM_VALUE_MAX_BYTES: usize =
    <crate::DefaultHostBounds as crate::HostBounds>::TERM_VALUE_MAX_BYTES;

/// Wiki ADR-029: name-index sentinel used by `prism_model!` G7 emission to
/// mark `recurse(measure, base, |self| step)`'s self-identifier reference.
/// When the catamorphism encounters `Term::Variable { name_index: <this> }`
/// during step-body evaluation, it returns the previous iteration's result
/// (the `recurse_value` parameter threaded through `evaluate_term_at`) — the
/// fresh-name-indexed Variable ADR-029 specifies for the recursive-call
/// placeholder.
/// Foundation reserves the upper sentinels: `u32::MAX` is the wildcard arm
/// for `Term::Match` (ADR-022 D3 G6) and the default-propagation handler for
/// `Term::Try` (G9). `RECURSE_PLACEHOLDER_NAME_INDEX = u32::MAX - 1`.
pub const RECURSE_PLACEHOLDER_NAME_INDEX: u32 = u32::MAX - 1;

/// Wiki ADR-022 D3 G8 + ADR-029: the fresh-name-indexed Variable that
/// `prism_model!` emits in place of an `unfold(seed, |state, …| step)`
/// closure's state-ident references. The catamorphism's `Term::Unfold`
/// fold-rule binds this name to the unfold's current state value
/// (threaded through `evaluate_term_at` as the `unfold_value` parameter)
/// and iterates step until a Kleene fixpoint or [`UNFOLD_MAX_ITERATIONS`].
pub const UNFOLD_PLACEHOLDER_NAME_INDEX: u32 = u32::MAX - 2;

/// Wiki ADR-034 Mechanism 1: the foundation-fixed name-index for the
/// iteration-counter binding inside `Term::Recurse`'s step body. The
/// two-parameter closure form `recurse(measure, base, |self_ident, idx_ident| step)`
/// lowers `idx_ident` references to
/// `Term::Variable { name_index: RECURSE_IDX_NAME_INDEX }`; the
/// catamorphism's per-variant fold-rule binds it to a `TermValue`
/// carrying the current measure value at each descent.
pub const RECURSE_IDX_NAME_INDEX: u32 = u32::MAX - 3;

/// Wiki ADR-034 Mechanism 2: the foundation-fixed name-index for the
/// candidate-value binding inside `Term::FirstAdmit`'s predicate body.
/// The grammar form `first_admit(<domain>, |idx_ident| <pred>)` lowers
/// `idx_ident` references to
/// `Term::Variable { name_index: FIRST_ADMIT_IDX_NAME_INDEX }`; the
/// catamorphism's per-variant fold-rule binds it to the current
/// candidate `idx` (ranging `0..<Domain>::CYCLE_SIZE`).
pub const FIRST_ADMIT_IDX_NAME_INDEX: u32 = u32::MAX - 4;

/// Wiki ADR-029: bound on the anamorphic fixpoint iteration for
/// `Term::Unfold`. The fold rule iterates `step(state)` until either the
/// state reaches a Kleene fixpoint (`step(state) == state`) or this
/// ceiling is hit, at which point evaluation returns the most-recent
/// state. Foundation-fixed (parallel to `FOLD_UNROLL_THRESHOLD`).
/// Wiki ADR-037: alias of [`HostBounds::UNFOLD_ITERATIONS_MAX`] via
/// [`DefaultHostBounds`].
pub const UNFOLD_MAX_ITERATIONS: usize =
    <crate::DefaultHostBounds as crate::HostBounds>::UNFOLD_ITERATIONS_MAX;

/// Wiki ADR-029: a single Term variant's evaluated value, carried as a
/// fixed-capacity byte buffer with an active-prefix length. The
/// catamorphism produces a `TermValue` per variant, propagated up the
/// term tree by the per-variant fold rules.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct TermValue {
    /// Fixed-capacity byte buffer (zero-padded beyond `len`).
    bytes: [u8; TERM_VALUE_MAX_BYTES],
    /// Active prefix length. `u16` admits the architectural ceiling (4096 < 65536).
    len: u16,
}

impl TermValue {
    /// Construct an empty `TermValue` (length zero).
    #[must_use]
    pub const fn empty() -> Self {
        Self {
            bytes: [0u8; TERM_VALUE_MAX_BYTES],
            len: 0,
        }
    }

    /// Construct a `TermValue` from a slice; copies up to `TERM_VALUE_MAX_BYTES` bytes.
    #[must_use]
    pub const fn from_slice(bytes: &[u8]) -> Self {
        let mut buf = [0u8; TERM_VALUE_MAX_BYTES];
        let copy_len = if bytes.len() > TERM_VALUE_MAX_BYTES {
            TERM_VALUE_MAX_BYTES
        } else {
            bytes.len()
        };
        let mut i = 0;
        while i < copy_len {
            buf[i] = bytes[i];
            i += 1;
        }
        Self {
            bytes: buf,
            len: copy_len as u16,
        }
    }

    /// ADR-051: construct a `TermValue` from a u64 value at a declared byte width.
    /// The high (8 - width) bytes of the u64 are discarded; the low `width` bytes are
    /// written into the value buffer in big-endian order.
    #[must_use]
    pub const fn from_u64_be(value: u64, width: usize) -> Self {
        let w = if width > 8 { 8 } else { width };
        let be = value.to_be_bytes();
        let mut buf = [0u8; TERM_VALUE_MAX_BYTES];
        let mut i = 0;
        while i < w {
            buf[i] = be[8 - w + i];
            i += 1;
        }
        Self {
            bytes: buf,
            len: w as u16,
        }
    }

    /// ADR-051 helper: const-constructor from a prepared big-endian byte buffer.
    /// `len` MUST be `<= TERM_VALUE_MAX_BYTES`; the function copies the first `len`
    /// bytes of `bytes` and records `len` as the active prefix.
    #[must_use]
    pub const fn from_slice_const(bytes: &[u8; TERM_VALUE_MAX_BYTES], len: usize) -> Self {
        let l = if len > TERM_VALUE_MAX_BYTES {
            TERM_VALUE_MAX_BYTES
        } else {
            len
        };
        Self {
            bytes: *bytes,
            len: l as u16,
        }
    }

    /// Returns the active byte prefix.
    #[inline]
    #[must_use]
    pub const fn bytes(&self) -> &[u8] {
        let l = self.len as usize;
        let (head, _) = self.bytes.split_at(l);
        head
    }
}

/// ADR-051: construct a `Term::Literal` from a u64 value at a declared Witt level.
/// Packs `value` as a big-endian byte sequence whose length equals the level's
/// byte width (`level.witt_length() / 8`). For widths > 8 bytes, the high bytes
/// are zero-padded.
#[must_use]
pub const fn literal_u64(value: u64, level: crate::WittLevel) -> crate::enforcement::Term {
    let mut width = (level.witt_length() / 8) as usize;
    if width == 0 {
        width = 1;
    }
    let be = value.to_be_bytes();
    let mut buf = [0u8; TERM_VALUE_MAX_BYTES];
    // Pack the u64's big-endian bytes into the low `min(width, 8)` bytes
    // of the result, right-aligned. Widths > 8 zero-pad the high portion.
    let take = if width > 8 { 8 } else { width };
    let mut i = 0;
    while i < take {
        buf[width - take + i] = be[8 - take + i];
        i += 1;
    }
    crate::enforcement::Term::Literal {
        value: TermValue::from_slice_const(&buf, width),
        level,
    }
}

/// ADR-051: construct a `Term::Literal` from raw bytes at a declared Witt level.
/// `bytes` MUST have exactly `level.witt_length() / 8` bytes; mismatched lengths
/// are silently truncated/padded by `TermValue::from_slice_const`. Use this for
/// wide-Witt literals (W128+) that don't fit in a u64.
#[must_use]
pub const fn literal_bytes(bytes: &[u8], level: crate::WittLevel) -> crate::enforcement::Term {
    crate::enforcement::Term::Literal {
        value: TermValue::from_slice(bytes),
        level,
    }
}

/// Wiki ADR-029: catamorphism evaluator over the route's Term tree.
/// Per-variant fold rules:
/// - `Term::Literal { value, level }` — emit `value` as big-endian bytes at the
///   byte width of `level`.
/// - `Term::Variable { name_index }` — `name_index = 0` returns the route
///   input bytes; other indices look up `let`-introduced bindings (current
///   iteration: not yet supported, returns the input bytes for any non-zero
///   index).
/// - `Term::Application { operator, args }` — evaluate each arg and apply
///   the `PrimitiveOp` per its algebraic rule.
/// - `Term::Lift { operand, target }` — evaluate operand, zero-extend to
///   `target` Witt level's byte width.
/// - `Term::Project { operand, target }` — evaluate operand, truncate to
///   `target` Witt level's byte width.
/// - `Term::Match { scrutinee, arms }` — evaluate scrutinee, match arms by
///   literal-byte equality (wildcard arm `name_index = u32::MAX` matches
///   unconditionally).
/// - `Term::Recurse { measure, base, step }` — bounded recursion: evaluate
///   measure → n; if n = 0 evaluate base; otherwise iterate step n times with
///   the recursive-call placeholder bound to the previous iteration's result.
/// - `Term::Unfold { seed, step }` — anamorphism: evaluate seed → state₀;
///   iterate step (with the state placeholder bound to the current state)
///   until a Kleene fixpoint or `UNFOLD_MAX_ITERATIONS` is reached.
/// - `Term::Try { body, handler }` — evaluate body; on failure, propagate
///   if `handler_index = u32::MAX`, otherwise evaluate handler.
/// - `Term::AxisInvocation { axis_index, kernel_id, input_index }` — dispatch
///   the input's bytes to the application's `AxisTuple` (ADR-030); the
///   foundation-canonical (axis_index=0, kernel_id=0) folds through the
///   selected `Hasher` impl. Replaces the legacy `HasherProjection` variant.
/// # Errors
/// Returns [`PipelineFailure`] when the term tree is malformed (out-of-bounds
/// index, level mismatch, exhausted match without wildcard arm, etc.).
pub fn evaluate_term_tree<A, R>(
    arena: &[crate::enforcement::Term],
    input_bytes: &[u8],
    resolvers: &R,
) -> Result<TermValue, PipelineFailure>
where
    A: crate::pipeline::AxisTuple + crate::enforcement::Hasher,
    R: crate::pipeline::ResolverTuple
        + crate::pipeline::HasNerveResolver<A>
        + crate::pipeline::HasChainComplexResolver<A>
        + crate::pipeline::HasHomologyGroupResolver<A>
        + crate::pipeline::HasCochainComplexResolver<A>
        + crate::pipeline::HasCohomologyGroupResolver<A>
        + crate::pipeline::HasPostnikovResolver<A>
        + crate::pipeline::HasHomotopyGroupResolver<A>
        + crate::pipeline::HasKInvariantResolver<A>,
{
    if arena.is_empty() {
        // Identity route: output equals input bytes.
        return Ok(TermValue::from_slice(input_bytes));
    }
    // Canonical convention: the root term is the last entry in the
    // arena (the `prism_model!` macro emits in post-order, so the root
    // is the final node).
    let root_idx = arena.len() - 1;
    evaluate_term_at::<A, R>(
        arena,
        root_idx,
        input_bytes,
        None,
        None,
        None,
        None,
        resolvers,
    )
}

#[allow(clippy::too_many_arguments)]
fn evaluate_term_at<A, R>(
    arena: &[crate::enforcement::Term],
    idx: usize,
    input_bytes: &[u8],
    recurse_value: Option<&[u8]>,
    recurse_idx_value: Option<&[u8]>,
    unfold_value: Option<&[u8]>,
    first_admit_idx_value: Option<&[u8]>,
    resolvers: &R,
) -> Result<TermValue, PipelineFailure>
where
    A: crate::pipeline::AxisTuple + crate::enforcement::Hasher,
    R: crate::pipeline::ResolverTuple
        + crate::pipeline::HasNerveResolver<A>
        + crate::pipeline::HasChainComplexResolver<A>
        + crate::pipeline::HasHomologyGroupResolver<A>
        + crate::pipeline::HasCochainComplexResolver<A>
        + crate::pipeline::HasCohomologyGroupResolver<A>
        + crate::pipeline::HasPostnikovResolver<A>
        + crate::pipeline::HasHomotopyGroupResolver<A>
        + crate::pipeline::HasKInvariantResolver<A>,
{
    if idx >= arena.len() {
        return Err(PipelineFailure::ShapeViolation {
            report: crate::enforcement::ShapeViolation {
                shape_iri: "https://uor.foundation/pipeline/TermArenaShape",
                constraint_iri: "https://uor.foundation/pipeline/TermArenaShape/inBounds",
                property_iri: "https://uor.foundation/pipeline/termIndex",
                expected_range: "http://www.w3.org/2001/XMLSchema#nonNegativeInteger",
                min_count: 0,
                max_count: arena.len() as u32,
                kind: crate::ViolationKind::ValueCheck,
            },
        });
    }
    match arena[idx] {
        crate::enforcement::Term::Literal { value, level: _ } => {
            // ADR-051: the literal's value carrier is a `TermValue` whose
            // byte length matches `level.witt_length() / 8`. The fold-rule
            // emits the carrier bytes directly — no width-aware encoding
            // (which was the pre-ADR-051 truncation logic).
            Ok(TermValue::from_slice(value.bytes()))
        }
        crate::enforcement::Term::Variable { name_index } => {
            // ADR-022 D3 G2: name_index = 0 is the route input slot.
            // ADR-029: name_index = RECURSE_PLACEHOLDER_NAME_INDEX is the
            // recursive-call placeholder bound to `recurse_value`.
            // ADR-029: name_index = UNFOLD_PLACEHOLDER_NAME_INDEX is the
            // unfold state placeholder bound to `unfold_value` (the
            // current iteration's accumulated state — see the
            // `Term::Unfold` fold-rule below).
            // Other indices reference let-bindings (G10), which the
            // current macro emission resolves at expansion time via
            // splice into the calling arena (so the binding's value-tree
            // root is what the catamorphism actually walks).
            if name_index == RECURSE_PLACEHOLDER_NAME_INDEX {
                return Ok(TermValue::from_slice(recurse_value.unwrap_or(&[])));
            }
            // ADR-034 Mechanism 1: iteration-counter binding for Recurse.
            if name_index == RECURSE_IDX_NAME_INDEX {
                return Ok(TermValue::from_slice(recurse_idx_value.unwrap_or(&[])));
            }
            if name_index == UNFOLD_PLACEHOLDER_NAME_INDEX {
                return Ok(TermValue::from_slice(unfold_value.unwrap_or(&[])));
            }
            // ADR-034 Mechanism 2: candidate-value binding for FirstAdmit.
            if name_index == FIRST_ADMIT_IDX_NAME_INDEX {
                return Ok(TermValue::from_slice(first_admit_idx_value.unwrap_or(&[])));
            }
            Ok(TermValue::from_slice(input_bytes))
        }
        crate::enforcement::Term::Application { operator, args } => {
            let start = args.start as usize;
            let len = args.len as usize;
            apply_primitive_op::<A, R>(
                arena,
                operator,
                start,
                len,
                input_bytes,
                recurse_value,
                recurse_idx_value,
                unfold_value,
                first_admit_idx_value,
                resolvers,
            )
        }
        crate::enforcement::Term::Lift {
            operand_index,
            target,
        } => {
            let v = evaluate_term_at::<A, R>(
                arena,
                operand_index as usize,
                input_bytes,
                recurse_value,
                recurse_idx_value,
                unfold_value,
                first_admit_idx_value,
                resolvers,
            )?;
            let target_width = (target.witt_length() / 8) as usize;
            let target_width = if target_width > TERM_VALUE_MAX_BYTES {
                TERM_VALUE_MAX_BYTES
            } else if target_width == 0 {
                1
            } else {
                target_width
            };
            let mut buf = [0u8; TERM_VALUE_MAX_BYTES];
            // Big-endian zero-extend: pad the high bytes with zeros.
            let src = v.bytes();
            let pad = target_width.saturating_sub(src.len());
            let mut i = 0;
            while i < src.len() && pad + i < target_width {
                buf[pad + i] = src[i];
                i += 1;
            }
            Ok(TermValue {
                bytes: buf,
                len: target_width as u16,
            })
        }
        crate::enforcement::Term::Project {
            operand_index,
            target,
        } => {
            let v = evaluate_term_at::<A, R>(
                arena,
                operand_index as usize,
                input_bytes,
                recurse_value,
                recurse_idx_value,
                unfold_value,
                first_admit_idx_value,
                resolvers,
            )?;
            let target_width = (target.witt_length() / 8) as usize;
            let target_width = if target_width > TERM_VALUE_MAX_BYTES {
                TERM_VALUE_MAX_BYTES
            } else if target_width == 0 {
                1
            } else {
                target_width
            };
            let src = v.bytes();
            // Big-endian truncation: take the trailing `target_width` bytes.
            let take_from = src.len().saturating_sub(target_width);
            Ok(TermValue::from_slice(&src[take_from..]))
        }
        crate::enforcement::Term::Match {
            scrutinee_index,
            arms,
        } => {
            let scrutinee = evaluate_term_at::<A, R>(
                arena,
                scrutinee_index as usize,
                input_bytes,
                recurse_value,
                recurse_idx_value,
                unfold_value,
                first_admit_idx_value,
                resolvers,
            )?;
            let start = arms.start as usize;
            let count = arms.len as usize;
            // Arms alternate (pattern, body) per ADR-022 D3 G6.
            let mut i = 0usize;
            while i + 1 < count {
                let pattern_idx = start + i;
                let body_idx = start + i + 1;
                let is_wildcard = matches!(
                    arena[pattern_idx],
                    crate::enforcement::Term::Variable { name_index } if name_index == u32::MAX
                );
                if is_wildcard {
                    return evaluate_term_at::<A, R>(
                        arena,
                        body_idx,
                        input_bytes,
                        recurse_value,
                        recurse_idx_value,
                        unfold_value,
                        first_admit_idx_value,
                        resolvers,
                    );
                }
                let pattern_val = evaluate_term_at::<A, R>(
                    arena,
                    pattern_idx,
                    input_bytes,
                    recurse_value,
                    recurse_idx_value,
                    unfold_value,
                    first_admit_idx_value,
                    resolvers,
                )?;
                if pattern_val.bytes() == scrutinee.bytes() {
                    return evaluate_term_at::<A, R>(
                        arena,
                        body_idx,
                        input_bytes,
                        recurse_value,
                        recurse_idx_value,
                        unfold_value,
                        first_admit_idx_value,
                        resolvers,
                    );
                }
                i += 2;
            }
            // Per ADR-022 D3 G6 the macro enforces wildcard exhaustiveness;
            // a well-formed Term tree never reaches this branch.
            Err(PipelineFailure::ShapeViolation {
                report: crate::enforcement::ShapeViolation {
                    shape_iri: "https://uor.foundation/pipeline/MatchExhaustivenessShape",
                    constraint_iri:
                        "https://uor.foundation/pipeline/MatchExhaustivenessShape/wildcard",
                    property_iri: "https://uor.foundation/pipeline/matchArms",
                    expected_range: "http://www.w3.org/2001/XMLSchema#string",
                    min_count: 1,
                    max_count: 0,
                    kind: crate::ViolationKind::Missing,
                },
            })
        }
        crate::enforcement::Term::Recurse {
            measure_index,
            base_index,
            step_index,
        } => {
            // Wiki ADR-029 recursive fold: evaluate measure once to get N;
            // if N == 0 evaluate base; else iterate step N times, threading
            // each iteration's result as the recurse_value (the recursive-
            // call placeholder bound to a fresh-name-indexed Variable per
            // ADR-029, with the placeholder's name_index resolving via the
            // RECURSE_PLACEHOLDER_NAME_INDEX sentinel handled in the Variable
            // arm). The outer recurse_value is preserved for nested Recurse
            // forms within the measure/base computations; step body uses the
            // iteration's accumulator.
            let measure = evaluate_term_at::<A, R>(
                arena,
                measure_index as usize,
                input_bytes,
                recurse_value,
                recurse_idx_value,
                unfold_value,
                first_admit_idx_value,
                resolvers,
            )?;
            let n = bytes_to_u64_be(measure.bytes());
            let base_val = evaluate_term_at::<A, R>(
                arena,
                base_index as usize,
                input_bytes,
                recurse_value,
                recurse_idx_value,
                unfold_value,
                first_admit_idx_value,
                resolvers,
            )?;
            if n == 0 {
                return Ok(base_val);
            }
            // Iterate step N times. Each iteration's `current` becomes the
            // next iteration's recurse_value. The descent measure is the
            // bound; well-foundedness holds by monotonic decrease.
            let mut current_buf = [0u8; TERM_VALUE_MAX_BYTES];
            let mut current_len = base_val.bytes().len();
            let mut k = 0;
            while k < current_len {
                current_buf[k] = base_val.bytes()[k];
                k += 1;
            }
            let mut iter = 0u64;
            while iter < n {
                // ADR-034 Mechanism 1: bind RECURSE_IDX_NAME_INDEX to the
                // current measure value (the iteration counter at this
                // descent). At iter=0 the descent measure is N; at iter=k
                // it is N-k. The byte width follows the measure's BE-truncated
                // u64 packing so callers can read it as a u64-shaped value.
                let descent_measure: u64 = n - iter;
                let descent_bytes = descent_measure.to_be_bytes();
                let next = evaluate_term_at::<A, R>(
                    arena,
                    step_index as usize,
                    input_bytes,
                    Some(&current_buf[..current_len]),
                    Some(&descent_bytes[..]),
                    unfold_value,
                    first_admit_idx_value,
                    resolvers,
                )?;
                let nb = next.bytes();
                let copy_len = if nb.len() > TERM_VALUE_MAX_BYTES {
                    TERM_VALUE_MAX_BYTES
                } else {
                    nb.len()
                };
                let mut j = 0;
                while j < copy_len {
                    current_buf[j] = nb[j];
                    j += 1;
                }
                current_len = copy_len;
                iter += 1;
            }
            Ok(TermValue::from_slice(&current_buf[..current_len]))
        }
        crate::enforcement::Term::Unfold {
            seed_index,
            step_index,
        } => {
            // ADR-029 anamorphism: evaluate seed → state₀; iterate step
            // with the state placeholder (UNFOLD_PLACEHOLDER_NAME_INDEX,
            // bound to the current state) until either a Kleene fixpoint
            // (step(state) == state) or UNFOLD_MAX_ITERATIONS is reached.
            // Well-foundedness: bounded by UNFOLD_MAX_ITERATIONS.
            // The outer unfold_value is preserved for nested Unfold forms
            // within the seed; step body's state placeholder uses the
            // iteration's accumulator.
            let seed_val = evaluate_term_at::<A, R>(
                arena,
                seed_index as usize,
                input_bytes,
                recurse_value,
                recurse_idx_value,
                unfold_value,
                first_admit_idx_value,
                resolvers,
            )?;
            let mut state_buf = [0u8; TERM_VALUE_MAX_BYTES];
            let mut state_len = seed_val.bytes().len();
            let mut k = 0;
            while k < state_len {
                state_buf[k] = seed_val.bytes()[k];
                k += 1;
            }
            let mut iter = 0usize;
            while iter < UNFOLD_MAX_ITERATIONS {
                let next = evaluate_term_at::<A, R>(
                    arena,
                    step_index as usize,
                    input_bytes,
                    recurse_value,
                    recurse_idx_value,
                    Some(&state_buf[..state_len]),
                    first_admit_idx_value,
                    resolvers,
                )?;
                let nb = next.bytes();
                // Kleene fixpoint check: if step(state) == state, return.
                if nb.len() == state_len && nb == &state_buf[..state_len] {
                    return Ok(TermValue::from_slice(&state_buf[..state_len]));
                }
                let copy_len = if nb.len() > TERM_VALUE_MAX_BYTES {
                    TERM_VALUE_MAX_BYTES
                } else {
                    nb.len()
                };
                let mut j = 0;
                while j < copy_len {
                    state_buf[j] = nb[j];
                    j += 1;
                }
                state_len = copy_len;
                iter += 1;
            }
            Ok(TermValue::from_slice(&state_buf[..state_len]))
        }
        crate::enforcement::Term::Try {
            body_index,
            handler_index,
        } => {
            match evaluate_term_at::<A, R>(
                arena,
                body_index as usize,
                input_bytes,
                recurse_value,
                recurse_idx_value,
                unfold_value,
                first_admit_idx_value,
                resolvers,
            ) {
                Ok(v) => Ok(v),
                Err(e) => {
                    if handler_index == u32::MAX {
                        Err(e)
                    } else {
                        evaluate_term_at::<A, R>(
                            arena,
                            handler_index as usize,
                            input_bytes,
                            recurse_value,
                            recurse_idx_value,
                            unfold_value,
                            first_admit_idx_value,
                            resolvers,
                        )
                    }
                }
            }
        }
        crate::enforcement::Term::AxisInvocation {
            axis_index,
            kernel_id,
            input_index,
        } => {
            // ADR-055: read the axis's SubstrateTermBody::body_arena() via
            // `AxisTuple::body_arena_at`. When non-empty, recursively fold
            // the body with the evaluated kernel input bound as input_bytes;
            // when empty (primitive-fast-path interpretation), dispatch the
            // kernel function directly per the optional fast-path per ADR-055.
            //
            // The foundation-built blanket `impl<H: Hasher> AxisTuple for H`
            // routes the canonical hash dispatch (axis 0, kernel 0) through
            // the legacy Hasher API (empty body); user-declared axes via the
            // `axis!` SDK macro extend the dispatch surface to additional
            // (axis_index, kernel_id) combinations and may provide substrate-
            // Term bodies the catamorphism walks structurally.
            let v = evaluate_term_at::<A, R>(
                arena,
                input_index as usize,
                input_bytes,
                recurse_value,
                recurse_idx_value,
                unfold_value,
                first_admit_idx_value,
                resolvers,
            )?;
            let body = <A as crate::pipeline::AxisTuple>::body_arena_at(axis_index);
            if body.is_empty() {
                // Primitive fast-path: dispatch the kernel function directly.
                let mut out = [0u8; AXIS_OUTPUT_BYTES_CEILING];
                let written = match <A as crate::pipeline::AxisTuple>::dispatch(
                    axis_index,
                    kernel_id,
                    v.bytes(),
                    &mut out,
                ) {
                    Ok(n) => n,
                    Err(report) => return Err(PipelineFailure::ShapeViolation { report }),
                };
                let width = if written > TERM_VALUE_MAX_BYTES {
                    TERM_VALUE_MAX_BYTES
                } else {
                    written
                };
                Ok(TermValue::from_slice(&out[..width]))
            } else {
                // ADR-055 recursive-fold path: walk the axis's substrate-Term
                // body with the evaluated kernel input bound in scope. The
                // body's root term is by convention the last entry in the arena.
                let root = body.len() - 1;
                evaluate_term_at::<A, R>(
                    body,
                    root,
                    v.bytes(),
                    recurse_value,
                    recurse_idx_value,
                    unfold_value,
                    first_admit_idx_value,
                    resolvers,
                )
            }
        }
        crate::enforcement::Term::ProjectField {
            source_index,
            byte_offset,
            byte_length,
        } => {
            // ADR-033 G20: evaluate source, slice [byte_offset .. byte_offset+byte_length].
            let v = evaluate_term_at::<A, R>(
                arena,
                source_index as usize,
                input_bytes,
                recurse_value,
                recurse_idx_value,
                unfold_value,
                first_admit_idx_value,
                resolvers,
            )?;
            let bytes = v.bytes();
            let start = byte_offset as usize;
            let end = start.saturating_add(byte_length as usize);
            if end > bytes.len() {
                return Err(PipelineFailure::ShapeViolation {
                    report: crate::enforcement::ShapeViolation {
                        shape_iri: "https://uor.foundation/pipeline/ProjectFieldShape",
                        constraint_iri:
                            "https://uor.foundation/pipeline/ProjectFieldShape/inBounds",
                        property_iri: "https://uor.foundation/pipeline/byteOffset",
                        expected_range: "https://uor.foundation/pipeline/SourceByteRange",
                        min_count: 0,
                        max_count: 1,
                        kind: crate::ViolationKind::ValueCheck,
                    },
                });
            }
            Ok(TermValue::from_slice(&bytes[start..end]))
        }
        crate::enforcement::Term::FirstAdmit {
            domain_size_index,
            predicate_index,
        } => {
            // ADR-034 Mechanism 2: bounded search with structural early
            // termination. Evaluate the domain size N; iterate idx in 0..N
            // ascending; for each idx, evaluate predicate with
            // FIRST_ADMIT_IDX_NAME_INDEX bound to idx. Return on the first
            // non-zero predicate result (the "found" coproduct value
            // 0x01 || idx_bytes); after exhausting the domain return the
            // "not-found" coproduct value 0x00 || idx-width zero bytes.
            let domain_size = evaluate_term_at::<A, R>(
                arena,
                domain_size_index as usize,
                input_bytes,
                recurse_value,
                recurse_idx_value,
                unfold_value,
                first_admit_idx_value,
                resolvers,
            )?;
            let n = bytes_to_u64_be(domain_size.bytes());
            // Determine the idx byte width from the domain size's
            // BE-truncated u64 packing (use the smallest non-zero count of
            // bytes needed to represent N). For N=0 fall back to 1 byte so
            // the not-found sentinel still has the canonical (disc, idx) shape.
            let idx_byte_width: usize = if n == 0 {
                1
            } else {
                let mut w = 8usize;
                while w > 1 && (n >> ((w - 1) * 8)) == 0 {
                    w -= 1;
                }
                w
            };
            let mut idx_iter: u64 = 0;
            while idx_iter < n {
                let idx_bytes_full = idx_iter.to_be_bytes();
                let idx_bytes = &idx_bytes_full[8 - idx_byte_width..];
                let pred_val = evaluate_term_at::<A, R>(
                    arena,
                    predicate_index as usize,
                    input_bytes,
                    recurse_value,
                    recurse_idx_value,
                    unfold_value,
                    Some(idx_bytes),
                    resolvers,
                )?;
                // ADR-029 zero/non-zero convention: any TermValue whose
                // byte sequence has at least one non-zero byte counts as
                // "true". An empty TermValue is treated as "false".
                let pb = pred_val.bytes();
                let mut admitted = false;
                let mut bi = 0;
                while bi < pb.len() {
                    if pb[bi] != 0 {
                        admitted = true;
                        break;
                    }
                    bi += 1;
                }
                if admitted {
                    let mut out_buf = [0u8; TERM_VALUE_MAX_BYTES];
                    out_buf[0] = 0x01;
                    let mut k = 0;
                    while k < idx_byte_width {
                        out_buf[1 + k] = idx_bytes[k];
                        k += 1;
                    }
                    return Ok(TermValue::from_slice(&out_buf[..1 + idx_byte_width]));
                }
                idx_iter += 1;
            }
            // No idx admitted — emit not-found coproduct value.
            let mut out_buf = [0u8; TERM_VALUE_MAX_BYTES];
            out_buf[0] = 0x00;
            // bytes 1..1+idx_byte_width remain zero (structural padding).
            Ok(TermValue::from_slice(&out_buf[..1 + idx_byte_width]))
        }
        crate::enforcement::Term::Nerve { value_index } => {
            // ADR-035 + ADR-036 + ADR-041: resolver-bound ψ-Term variant.
            // Evaluate the operand subtree, wrap the resulting bytes in the
            // ADR-041 typed-coordinate carrier for this ψ-stage's expected
            // input, then dispatch through the application's resolver via the
            // `Has<Category>Resolver` accessor. The resolver's output bytes
            // populate the variant's `TermValue`; resolver-side `Err`
            // propagates as `PipelineFailure::ShapeViolation` (the Null
            // defaults emit `RESOLVER_ABSENT`, recoverable via `Term::Try`'s
            // default-propagation handler).
            //
            // ADR-037: scratch buffer sized at `<crate::DefaultHostBounds as crate::HostBounds>::NERVE_OUTPUT_BYTES_MAX`
            // — per-ψ-stage cap from the application's selected HostBounds.
            let operand = evaluate_term_at::<A, R>(
                arena,
                value_index as usize,
                input_bytes,
                recurse_value,
                recurse_idx_value,
                unfold_value,
                first_admit_idx_value,
                resolvers,
            )?;
            let mut out_buf =
                [0u8; <crate::DefaultHostBounds as crate::HostBounds>::NERVE_OUTPUT_BYTES_MAX];
            match resolvers
                .nerve_resolver()
                .resolve(operand.bytes(), &mut out_buf)
            {
                Ok(written) => {
                    let width = if written > TERM_VALUE_MAX_BYTES {
                        TERM_VALUE_MAX_BYTES
                    } else {
                        written
                    };
                    Ok(TermValue::from_slice(&out_buf[..width]))
                }
                Err(report) => Err(PipelineFailure::ShapeViolation { report }),
            }
        }
        crate::enforcement::Term::ChainComplex { simplicial_index } => {
            // ADR-035 + ADR-036 + ADR-041: resolver-bound ψ-Term variant.
            // Evaluate the operand subtree, wrap the resulting bytes in the
            // ADR-041 typed-coordinate carrier for this ψ-stage's expected
            // input, then dispatch through the application's resolver via the
            // `Has<Category>Resolver` accessor. The resolver's output bytes
            // populate the variant's `TermValue`; resolver-side `Err`
            // propagates as `PipelineFailure::ShapeViolation` (the Null
            // defaults emit `RESOLVER_ABSENT`, recoverable via `Term::Try`'s
            // default-propagation handler).
            //
            // ADR-037: scratch buffer sized at `<crate::DefaultHostBounds as crate::HostBounds>::CHAIN_COMPLEX_OUTPUT_BYTES_MAX`
            // — per-ψ-stage cap from the application's selected HostBounds.
            let operand = evaluate_term_at::<A, R>(
                arena,
                simplicial_index as usize,
                input_bytes,
                recurse_value,
                recurse_idx_value,
                unfold_value,
                first_admit_idx_value,
                resolvers,
            )?;
            let mut out_buf = [0u8;
                <crate::DefaultHostBounds as crate::HostBounds>::CHAIN_COMPLEX_OUTPUT_BYTES_MAX];
            match resolvers.chain_complex_resolver().resolve(
                crate::pipeline::SimplicialComplexBytes(operand.bytes()),
                &mut out_buf,
            ) {
                Ok(written) => {
                    let width = if written > TERM_VALUE_MAX_BYTES {
                        TERM_VALUE_MAX_BYTES
                    } else {
                        written
                    };
                    Ok(TermValue::from_slice(&out_buf[..width]))
                }
                Err(report) => Err(PipelineFailure::ShapeViolation { report }),
            }
        }
        crate::enforcement::Term::HomologyGroups { chain_index } => {
            // ADR-035 + ADR-036 + ADR-041: resolver-bound ψ-Term variant.
            // Evaluate the operand subtree, wrap the resulting bytes in the
            // ADR-041 typed-coordinate carrier for this ψ-stage's expected
            // input, then dispatch through the application's resolver via the
            // `Has<Category>Resolver` accessor. The resolver's output bytes
            // populate the variant's `TermValue`; resolver-side `Err`
            // propagates as `PipelineFailure::ShapeViolation` (the Null
            // defaults emit `RESOLVER_ABSENT`, recoverable via `Term::Try`'s
            // default-propagation handler).
            //
            // ADR-037: scratch buffer sized at `<crate::DefaultHostBounds as crate::HostBounds>::HOMOLOGY_GROUPS_OUTPUT_BYTES_MAX`
            // — per-ψ-stage cap from the application's selected HostBounds.
            let operand = evaluate_term_at::<A, R>(
                arena,
                chain_index as usize,
                input_bytes,
                recurse_value,
                recurse_idx_value,
                unfold_value,
                first_admit_idx_value,
                resolvers,
            )?;
            let mut out_buf = [0u8;
                <crate::DefaultHostBounds as crate::HostBounds>::HOMOLOGY_GROUPS_OUTPUT_BYTES_MAX];
            match resolvers.homology_group_resolver().resolve(
                crate::pipeline::ChainComplexBytes(operand.bytes()),
                &mut out_buf,
            ) {
                Ok(written) => {
                    let width = if written > TERM_VALUE_MAX_BYTES {
                        TERM_VALUE_MAX_BYTES
                    } else {
                        written
                    };
                    Ok(TermValue::from_slice(&out_buf[..width]))
                }
                Err(report) => Err(PipelineFailure::ShapeViolation { report }),
            }
        }
        crate::enforcement::Term::CochainComplex { chain_index } => {
            // ADR-035 + ADR-036 + ADR-041: resolver-bound ψ-Term variant.
            // Evaluate the operand subtree, wrap the resulting bytes in the
            // ADR-041 typed-coordinate carrier for this ψ-stage's expected
            // input, then dispatch through the application's resolver via the
            // `Has<Category>Resolver` accessor. The resolver's output bytes
            // populate the variant's `TermValue`; resolver-side `Err`
            // propagates as `PipelineFailure::ShapeViolation` (the Null
            // defaults emit `RESOLVER_ABSENT`, recoverable via `Term::Try`'s
            // default-propagation handler).
            //
            // ADR-037: scratch buffer sized at `<crate::DefaultHostBounds as crate::HostBounds>::COCHAIN_COMPLEX_OUTPUT_BYTES_MAX`
            // — per-ψ-stage cap from the application's selected HostBounds.
            let operand = evaluate_term_at::<A, R>(
                arena,
                chain_index as usize,
                input_bytes,
                recurse_value,
                recurse_idx_value,
                unfold_value,
                first_admit_idx_value,
                resolvers,
            )?;
            let mut out_buf = [0u8;
                <crate::DefaultHostBounds as crate::HostBounds>::COCHAIN_COMPLEX_OUTPUT_BYTES_MAX];
            match resolvers.cochain_complex_resolver().resolve(
                crate::pipeline::ChainComplexBytes(operand.bytes()),
                &mut out_buf,
            ) {
                Ok(written) => {
                    let width = if written > TERM_VALUE_MAX_BYTES {
                        TERM_VALUE_MAX_BYTES
                    } else {
                        written
                    };
                    Ok(TermValue::from_slice(&out_buf[..width]))
                }
                Err(report) => Err(PipelineFailure::ShapeViolation { report }),
            }
        }
        crate::enforcement::Term::CohomologyGroups { cochain_index } => {
            // ADR-035 + ADR-036 + ADR-041: resolver-bound ψ-Term variant.
            // Evaluate the operand subtree, wrap the resulting bytes in the
            // ADR-041 typed-coordinate carrier for this ψ-stage's expected
            // input, then dispatch through the application's resolver via the
            // `Has<Category>Resolver` accessor. The resolver's output bytes
            // populate the variant's `TermValue`; resolver-side `Err`
            // propagates as `PipelineFailure::ShapeViolation` (the Null
            // defaults emit `RESOLVER_ABSENT`, recoverable via `Term::Try`'s
            // default-propagation handler).
            //
            // ADR-037: scratch buffer sized at `<crate::DefaultHostBounds as crate::HostBounds>::COHOMOLOGY_GROUPS_OUTPUT_BYTES_MAX`
            // — per-ψ-stage cap from the application's selected HostBounds.
            let operand = evaluate_term_at::<A, R>(
                arena,
                cochain_index as usize,
                input_bytes,
                recurse_value,
                recurse_idx_value,
                unfold_value,
                first_admit_idx_value,
                resolvers,
            )?;
            let mut out_buf = [0u8;
                <crate::DefaultHostBounds as crate::HostBounds>::COHOMOLOGY_GROUPS_OUTPUT_BYTES_MAX];
            match resolvers.cohomology_group_resolver().resolve(
                crate::pipeline::CochainComplexBytes(operand.bytes()),
                &mut out_buf,
            ) {
                Ok(written) => {
                    let width = if written > TERM_VALUE_MAX_BYTES {
                        TERM_VALUE_MAX_BYTES
                    } else {
                        written
                    };
                    Ok(TermValue::from_slice(&out_buf[..width]))
                }
                Err(report) => Err(PipelineFailure::ShapeViolation { report }),
            }
        }
        crate::enforcement::Term::PostnikovTower { simplicial_index } => {
            // ADR-035 + ADR-036 + ADR-041: resolver-bound ψ-Term variant.
            // Evaluate the operand subtree, wrap the resulting bytes in the
            // ADR-041 typed-coordinate carrier for this ψ-stage's expected
            // input, then dispatch through the application's resolver via the
            // `Has<Category>Resolver` accessor. The resolver's output bytes
            // populate the variant's `TermValue`; resolver-side `Err`
            // propagates as `PipelineFailure::ShapeViolation` (the Null
            // defaults emit `RESOLVER_ABSENT`, recoverable via `Term::Try`'s
            // default-propagation handler).
            //
            // ADR-037: scratch buffer sized at `<crate::DefaultHostBounds as crate::HostBounds>::POSTNIKOV_TOWER_OUTPUT_BYTES_MAX`
            // — per-ψ-stage cap from the application's selected HostBounds.
            let operand = evaluate_term_at::<A, R>(
                arena,
                simplicial_index as usize,
                input_bytes,
                recurse_value,
                recurse_idx_value,
                unfold_value,
                first_admit_idx_value,
                resolvers,
            )?;
            let mut out_buf = [0u8;
                <crate::DefaultHostBounds as crate::HostBounds>::POSTNIKOV_TOWER_OUTPUT_BYTES_MAX];
            match resolvers.postnikov_resolver().resolve(
                crate::pipeline::SimplicialComplexBytes(operand.bytes()),
                &mut out_buf,
            ) {
                Ok(written) => {
                    let width = if written > TERM_VALUE_MAX_BYTES {
                        TERM_VALUE_MAX_BYTES
                    } else {
                        written
                    };
                    Ok(TermValue::from_slice(&out_buf[..width]))
                }
                Err(report) => Err(PipelineFailure::ShapeViolation { report }),
            }
        }
        crate::enforcement::Term::HomotopyGroups { postnikov_index } => {
            // ADR-035 + ADR-036 + ADR-041: resolver-bound ψ-Term variant.
            // Evaluate the operand subtree, wrap the resulting bytes in the
            // ADR-041 typed-coordinate carrier for this ψ-stage's expected
            // input, then dispatch through the application's resolver via the
            // `Has<Category>Resolver` accessor. The resolver's output bytes
            // populate the variant's `TermValue`; resolver-side `Err`
            // propagates as `PipelineFailure::ShapeViolation` (the Null
            // defaults emit `RESOLVER_ABSENT`, recoverable via `Term::Try`'s
            // default-propagation handler).
            //
            // ADR-037: scratch buffer sized at `<crate::DefaultHostBounds as crate::HostBounds>::HOMOTOPY_GROUPS_OUTPUT_BYTES_MAX`
            // — per-ψ-stage cap from the application's selected HostBounds.
            let operand = evaluate_term_at::<A, R>(
                arena,
                postnikov_index as usize,
                input_bytes,
                recurse_value,
                recurse_idx_value,
                unfold_value,
                first_admit_idx_value,
                resolvers,
            )?;
            let mut out_buf = [0u8;
                <crate::DefaultHostBounds as crate::HostBounds>::HOMOTOPY_GROUPS_OUTPUT_BYTES_MAX];
            match resolvers.homotopy_group_resolver().resolve(
                crate::pipeline::PostnikovTowerBytes(operand.bytes()),
                &mut out_buf,
            ) {
                Ok(written) => {
                    let width = if written > TERM_VALUE_MAX_BYTES {
                        TERM_VALUE_MAX_BYTES
                    } else {
                        written
                    };
                    Ok(TermValue::from_slice(&out_buf[..width]))
                }
                Err(report) => Err(PipelineFailure::ShapeViolation { report }),
            }
        }
        crate::enforcement::Term::KInvariants { homotopy_index } => {
            // ADR-035 + ADR-036 + ADR-041: resolver-bound ψ-Term variant.
            // Evaluate the operand subtree, wrap the resulting bytes in the
            // ADR-041 typed-coordinate carrier for this ψ-stage's expected
            // input, then dispatch through the application's resolver via the
            // `Has<Category>Resolver` accessor. The resolver's output bytes
            // populate the variant's `TermValue`; resolver-side `Err`
            // propagates as `PipelineFailure::ShapeViolation` (the Null
            // defaults emit `RESOLVER_ABSENT`, recoverable via `Term::Try`'s
            // default-propagation handler).
            //
            // ADR-037: scratch buffer sized at `<crate::DefaultHostBounds as crate::HostBounds>::K_INVARIANTS_OUTPUT_BYTES_MAX`
            // — per-ψ-stage cap from the application's selected HostBounds.
            let operand = evaluate_term_at::<A, R>(
                arena,
                homotopy_index as usize,
                input_bytes,
                recurse_value,
                recurse_idx_value,
                unfold_value,
                first_admit_idx_value,
                resolvers,
            )?;
            let mut out_buf = [0u8;
                <crate::DefaultHostBounds as crate::HostBounds>::K_INVARIANTS_OUTPUT_BYTES_MAX];
            match resolvers.k_invariant_resolver().resolve(
                crate::pipeline::HomotopyGroupsBytes(operand.bytes()),
                &mut out_buf,
            ) {
                Ok(written) => {
                    let width = if written > TERM_VALUE_MAX_BYTES {
                        TERM_VALUE_MAX_BYTES
                    } else {
                        written
                    };
                    Ok(TermValue::from_slice(&out_buf[..width]))
                }
                Err(report) => Err(PipelineFailure::ShapeViolation { report }),
            }
        }
        crate::enforcement::Term::Betti { homology_index } => {
            // ADR-035 ψ_4: Betti-number extraction from HomologyGroups.
            // Pure byte-projection — no resolver consultation. The
            // operand's evaluated bytes (the homology-groups byte
            // serialization per the homology bridge's wire format)
            // are returned as-is; downstream consumers slice the
            // Betti tuple positions out of the result.
            let v = evaluate_term_at::<A, R>(
                arena,
                homology_index as usize,
                input_bytes,
                recurse_value,
                recurse_idx_value,
                unfold_value,
                first_admit_idx_value,
                resolvers,
            )?;
            Ok(v)
        }
    }
}

#[allow(clippy::too_many_arguments)]
fn apply_primitive_op<A, R>(
    arena: &[crate::enforcement::Term],
    operator: crate::PrimitiveOp,
    args_start: usize,
    args_len: usize,
    input_bytes: &[u8],
    recurse_value: Option<&[u8]>,
    recurse_idx_value: Option<&[u8]>,
    unfold_value: Option<&[u8]>,
    first_admit_idx_value: Option<&[u8]>,
    resolvers: &R,
) -> Result<TermValue, PipelineFailure>
where
    A: crate::pipeline::AxisTuple + crate::enforcement::Hasher,
    R: crate::pipeline::ResolverTuple
        + crate::pipeline::HasNerveResolver<A>
        + crate::pipeline::HasChainComplexResolver<A>
        + crate::pipeline::HasHomologyGroupResolver<A>
        + crate::pipeline::HasCochainComplexResolver<A>
        + crate::pipeline::HasCohomologyGroupResolver<A>
        + crate::pipeline::HasPostnikovResolver<A>
        + crate::pipeline::HasHomotopyGroupResolver<A>
        + crate::pipeline::HasKInvariantResolver<A>,
{
    // Unary ops: 1 arg. Binary ops: 2 args.
    let arity = match operator {
        crate::PrimitiveOp::Neg
        | crate::PrimitiveOp::Bnot
        | crate::PrimitiveOp::Succ
        | crate::PrimitiveOp::Pred => 1usize,
        crate::PrimitiveOp::Add
        | crate::PrimitiveOp::Sub
        | crate::PrimitiveOp::Mul
        | crate::PrimitiveOp::Xor
        | crate::PrimitiveOp::And
        | crate::PrimitiveOp::Or
        | crate::PrimitiveOp::Le
        | crate::PrimitiveOp::Lt
        | crate::PrimitiveOp::Ge
        | crate::PrimitiveOp::Gt
        | crate::PrimitiveOp::Concat
        // ADR-053 substrate amendment: ring-axis arithmetic completion.
        | crate::PrimitiveOp::Div
        | crate::PrimitiveOp::Mod
        | crate::PrimitiveOp::Pow => 2usize,
    };
    if args_len != arity {
        return Err(PipelineFailure::ShapeViolation {
            report: crate::enforcement::ShapeViolation {
                shape_iri: "https://uor.foundation/pipeline/PrimitiveOpArityShape",
                constraint_iri: "https://uor.foundation/pipeline/PrimitiveOpArityShape/arity",
                property_iri: "https://uor.foundation/pipeline/operatorArity",
                expected_range: "http://www.w3.org/2001/XMLSchema#nonNegativeInteger",
                min_count: arity as u32,
                max_count: arity as u32,
                kind: crate::ViolationKind::CardinalityViolation,
            },
        });
    }
    if arity == 1 {
        let v = evaluate_term_at::<A, R>(
            arena,
            args_start,
            input_bytes,
            recurse_value,
            recurse_idx_value,
            unfold_value,
            first_admit_idx_value,
            resolvers,
        )?;
        let x = bytes_to_u64_be(v.bytes());
        let r =
            match operator {
                crate::PrimitiveOp::Neg => x.wrapping_neg(),
                crate::PrimitiveOp::Bnot => !x,
                crate::PrimitiveOp::Succ => x.wrapping_add(1),
                crate::PrimitiveOp::Pred => x.wrapping_sub(1),
                _ => return Err(PipelineFailure::ShapeViolation {
                    report: crate::enforcement::ShapeViolation {
                        shape_iri: "https://uor.foundation/pipeline/PrimitiveOpArityShape",
                        constraint_iri:
                            "https://uor.foundation/pipeline/PrimitiveOpArityShape/binary-as-unary",
                        property_iri: "https://uor.foundation/pipeline/operatorArity",
                        expected_range: "http://www.w3.org/2001/XMLSchema#nonNegativeInteger",
                        min_count: 2,
                        max_count: 2,
                        kind: crate::ViolationKind::CardinalityViolation,
                    },
                }),
            };
        let width = v.bytes().len().clamp(1, 8);
        let arr = r.to_be_bytes();
        Ok(TermValue::from_slice(&arr[8 - width..]))
    } else {
        let lhs = evaluate_term_at::<A, R>(
            arena,
            args_start,
            input_bytes,
            recurse_value,
            recurse_idx_value,
            unfold_value,
            first_admit_idx_value,
            resolvers,
        )?;
        let rhs = evaluate_term_at::<A, R>(
            arena,
            args_start + 1,
            input_bytes,
            recurse_value,
            recurse_idx_value,
            unfold_value,
            first_admit_idx_value,
            resolvers,
        )?;
        // ADR-013/TR-08 substrate-amendment ops: byte-level Concat and
        // comparison primitives bypass the u64 fold and operate on the
        // operands' full byte sequences.
        match operator {
            crate::PrimitiveOp::Concat => {
                // Concat: emit lhs.bytes() ⧺ rhs.bytes(), bounded by
                // TERM_VALUE_MAX_BYTES (truncates excess; runtime callers
                // declaring shapes whose composite length exceeds the
                // ceiling are rejected at validation time per ADR-028's
                // symmetric output ceiling check).
                let lb = lhs.bytes();
                let rb = rhs.bytes();
                let total = lb.len() + rb.len();
                let cap = if total > TERM_VALUE_MAX_BYTES {
                    TERM_VALUE_MAX_BYTES
                } else {
                    total
                };
                let mut buf = [0u8; TERM_VALUE_MAX_BYTES];
                let mut i = 0;
                while i < lb.len() && i < cap {
                    buf[i] = lb[i];
                    i += 1;
                }
                let mut j = 0;
                while j < rb.len() && i < cap {
                    buf[i] = rb[j];
                    i += 1;
                    j += 1;
                }
                return Ok(TermValue::from_slice(&buf[..cap]));
            }
            crate::PrimitiveOp::Le
            | crate::PrimitiveOp::Lt
            | crate::PrimitiveOp::Ge
            | crate::PrimitiveOp::Gt => {
                // Big-endian byte-level comparison. Both operands are
                // padded with leading zeros to the max length so the
                // comparison ignores leading-zero stripping differences.
                let cmp = byte_compare_be(lhs.bytes(), rhs.bytes());
                let result_byte: u8 = match operator {
                    crate::PrimitiveOp::Le => u8::from(cmp != core::cmp::Ordering::Greater),
                    crate::PrimitiveOp::Lt => u8::from(cmp == core::cmp::Ordering::Less),
                    crate::PrimitiveOp::Ge => u8::from(cmp != core::cmp::Ordering::Less),
                    crate::PrimitiveOp::Gt => u8::from(cmp == core::cmp::Ordering::Greater),
                    _ => 0,
                };
                return Ok(TermValue::from_slice(&[result_byte]));
            }
            // ADR-053 substrate amendment: Div/Mod reject b = 0 with
            // a ShapeViolation. Per ADR-050, division semantics are
            // Euclidean (q = floor(a / b), r = a − q·b) over the ring
            // Z/(2^n)Z where n is max(8·byte-len(a), 8·byte-len(b)).
            crate::PrimitiveOp::Div if bytes_all_zero(rhs.bytes()) => {
                return Err(PipelineFailure::ShapeViolation {
                    report: crate::enforcement::ShapeViolation {
                        shape_iri: "https://uor.foundation/op/Div",
                        constraint_iri: "https://uor.foundation/op/Div/nonZeroDivisor",
                        property_iri: "https://uor.foundation/op/arity",
                        expected_range: "http://www.w3.org/2001/XMLSchema#nonNegativeInteger",
                        min_count: 1,
                        max_count: 1,
                        kind: crate::ViolationKind::ValueCheck,
                    },
                });
            }
            crate::PrimitiveOp::Mod if bytes_all_zero(rhs.bytes()) => {
                return Err(PipelineFailure::ShapeViolation {
                    report: crate::enforcement::ShapeViolation {
                        shape_iri: "https://uor.foundation/op/Mod",
                        constraint_iri: "https://uor.foundation/op/Mod/nonZeroDivisor",
                        property_iri: "https://uor.foundation/op/arity",
                        expected_range: "http://www.w3.org/2001/XMLSchema#nonNegativeInteger",
                        min_count: 1,
                        max_count: 1,
                        kind: crate::ViolationKind::ValueCheck,
                    },
                });
            }
            _ => {}
        }
        let width = lhs.bytes().len().max(rhs.bytes().len()).max(1);
        // ADR-050 width-parametric dispatch: widths > 8 bytes route
        // through the byte-level kernel `byte_arith_be` so wide-Witt
        // operands (Limbs<N>-backed levels W160..W32768) compute
        // correctly under Z/(2^(8·width))Z without truncating to u64.
        if width > 8 {
            return byte_arith_be(operator, lhs.bytes(), rhs.bytes(), width);
        }
        let a = bytes_to_u64_be(lhs.bytes());
        let b = bytes_to_u64_be(rhs.bytes());
        // ADR-050 width-parametric mask: arithmetic results are reduced
        // mod 2^(8·width) before truncation. For the u64 hot path this
        // is `(1 << (width·8)) − 1` for width < 8 and u64::MAX for width = 8.
        let mask: u64 = if width >= 8 {
            u64::MAX
        } else {
            (1u64 << (width * 8)).wrapping_sub(1)
        };
        let r =
            match operator {
                crate::PrimitiveOp::Add => a.wrapping_add(b) & mask,
                crate::PrimitiveOp::Sub => a.wrapping_sub(b) & mask,
                crate::PrimitiveOp::Mul => a.wrapping_mul(b) & mask,
                crate::PrimitiveOp::Xor => (a ^ b) & mask,
                crate::PrimitiveOp::And => (a & b) & mask,
                crate::PrimitiveOp::Or => (a | b) & mask,
                // ADR-053: Euclidean division/remainder over Z/(2^(8·width))Z.
                crate::PrimitiveOp::Div => (a & mask) / (b & mask),
                crate::PrimitiveOp::Mod => (a & mask) % (b & mask),
                // ADR-053: modular exponentiation by repeated squaring.
                crate::PrimitiveOp::Pow => u64_modpow(a & mask, b & mask, mask),
                _ => return Err(PipelineFailure::ShapeViolation {
                    report: crate::enforcement::ShapeViolation {
                        shape_iri: "https://uor.foundation/pipeline/PrimitiveOpArityShape",
                        constraint_iri:
                            "https://uor.foundation/pipeline/PrimitiveOpArityShape/unary-as-binary",
                        property_iri: "https://uor.foundation/pipeline/operatorArity",
                        expected_range: "http://www.w3.org/2001/XMLSchema#nonNegativeInteger",
                        min_count: 1,
                        max_count: 1,
                        kind: crate::ViolationKind::CardinalityViolation,
                    },
                }),
            };
        let arr = r.to_be_bytes();
        Ok(TermValue::from_slice(&arr[8 - width..]))
    }
}

/// ADR-050: byte-level fold-rule dispatch for binary ring-axis primitives over
/// widths > 8 bytes. Matches the const-fn `const_ring_eval_w{n}` helpers'
/// semantics but operates on the runtime catamorphism's `TermValue` byte slices
/// rather than on typed `Limbs<N>` values.
#[allow(clippy::too_many_lines)]
fn byte_arith_be(
    operator: crate::PrimitiveOp,
    lhs: &[u8],
    rhs: &[u8],
    width: usize,
) -> Result<TermValue, PipelineFailure> {
    // Pad both operands to `width` bytes (leading zeros, big-endian).
    let mut a = [0u8; TERM_VALUE_MAX_BYTES];
    let mut b = [0u8; TERM_VALUE_MAX_BYTES];
    let w = if width > TERM_VALUE_MAX_BYTES {
        TERM_VALUE_MAX_BYTES
    } else {
        width
    };
    {
        let la = lhs.len().min(w);
        let dst_off = w - la;
        let src_off = lhs.len() - la;
        let mut i = 0;
        while i < la {
            a[dst_off + i] = lhs[src_off + i];
            i += 1;
        }
    }
    {
        let lb = rhs.len().min(w);
        let dst_off = w - lb;
        let src_off = rhs.len() - lb;
        let mut i = 0;
        while i < lb {
            b[dst_off + i] = rhs[src_off + i];
            i += 1;
        }
    }
    let mut out = [0u8; TERM_VALUE_MAX_BYTES];
    match operator {
        crate::PrimitiveOp::And => {
            let mut i = 0;
            while i < w {
                out[i] = a[i] & b[i];
                i += 1;
            }
        }
        crate::PrimitiveOp::Or => {
            let mut i = 0;
            while i < w {
                out[i] = a[i] | b[i];
                i += 1;
            }
        }
        crate::PrimitiveOp::Xor => {
            let mut i = 0;
            while i < w {
                out[i] = a[i] ^ b[i];
                i += 1;
            }
        }
        crate::PrimitiveOp::Add => {
            let mut carry: u16 = 0;
            let mut i = w;
            while i > 0 {
                i -= 1;
                let s = a[i] as u16 + b[i] as u16 + carry;
                out[i] = (s & 0xFF) as u8;
                carry = s >> 8;
            }
        }
        crate::PrimitiveOp::Sub => {
            let mut borrow: i16 = 0;
            let mut i = w;
            while i > 0 {
                i -= 1;
                let d = a[i] as i16 - b[i] as i16 - borrow;
                if d < 0 {
                    out[i] = (d + 256) as u8;
                    borrow = 1;
                } else {
                    out[i] = d as u8;
                    borrow = 0;
                }
            }
        }
        crate::PrimitiveOp::Mul => {
            // Schoolbook multiplication mod 2^(8·w). `a` and `b` are
            // big-endian w-byte operands; output is the low w bytes of
            // the 2w-byte product, written back big-endian.
            //
            // Algorithm: walk `i` from LSB to MSB (a[w-1] = LSB), and
            // for each `i` walk `j` similarly. The byte product
            // a[w-1-i] * b[w-1-j] contributes to output position
            // (w-1)-(i+j) when (i+j) < w; otherwise it overflows the
            // ring modulus and is discarded.
            let mut tmp = [0u32; TERM_VALUE_MAX_BYTES];
            let mut i: usize = 0;
            while i < w {
                let mut j: usize = 0;
                while j < w - i {
                    let dst = w - 1 - (i + j);
                    tmp[dst] += a[w - 1 - i] as u32 * b[w - 1 - j] as u32;
                    j += 1;
                }
                i += 1;
            }
            // Carry-propagate within the low w bytes (high bytes are
            // discarded — the ring modulus reduces them away).
            let mut carry: u32 = 0;
            let mut k = w;
            while k > 0 {
                k -= 1;
                let v = tmp[k] + carry;
                out[k] = (v & 0xFF) as u8;
                carry = v >> 8;
            }
        }
        crate::PrimitiveOp::Div | crate::PrimitiveOp::Mod => {
            // Binary long division MSB→LSB over the byte slice.
            let mut q = [0u8; TERM_VALUE_MAX_BYTES];
            let mut r = [0u8; TERM_VALUE_MAX_BYTES];
            let total_bits = w * 8;
            let mut i = 0;
            while i < total_bits {
                bytes_shl1(&mut r, w);
                let bit_word = i / 8;
                let bit_idx = 7 - (i % 8);
                let cur_bit = (a[bit_word] >> bit_idx) & 1;
                if cur_bit == 1 {
                    r[w - 1] |= 1;
                }
                if bytes_le_be(&b[..w], &r[..w]) {
                    bytes_sub_in_place(&mut r, &b, w);
                    bytes_shl1(&mut q, w);
                    q[w - 1] |= 1;
                } else {
                    bytes_shl1(&mut q, w);
                }
                i += 1;
            }
            let src = match operator {
                crate::PrimitiveOp::Div => &q,
                _ => &r,
            };
            let mut k = 0;
            while k < w {
                out[k] = src[k];
                k += 1;
            }
        }
        crate::PrimitiveOp::Pow => {
            // Square-and-multiply over byte-slice operands. Exponent
            // bits walked LSB→MSB; each iteration squares the running
            // base and conditionally multiplies into the accumulator.
            let mut result = [0u8; TERM_VALUE_MAX_BYTES];
            result[w - 1] = 1;
            let mut base = [0u8; TERM_VALUE_MAX_BYTES];
            let mut k = 0;
            while k < w {
                base[k] = a[k];
                k += 1;
            }
            let mut byte = w;
            while byte > 0 {
                byte -= 1;
                let mut bit = 0u32;
                while bit < 8 {
                    if ((b[byte] >> bit) & 1) == 1 {
                        let prod =
                            byte_arith_be(crate::PrimitiveOp::Mul, &result[..w], &base[..w], w)?;
                        let pb = prod.bytes();
                        let dst_off = w - pb.len().min(w);
                        let mut j = 0;
                        while j < w {
                            result[j] = 0;
                            j += 1;
                        }
                        let mut j2 = 0;
                        while j2 < pb.len().min(w) {
                            result[dst_off + j2] = pb[j2];
                            j2 += 1;
                        }
                    }
                    let sq = byte_arith_be(crate::PrimitiveOp::Mul, &base[..w], &base[..w], w)?;
                    let sb = sq.bytes();
                    let dst_off = w - sb.len().min(w);
                    let mut j = 0;
                    while j < w {
                        base[j] = 0;
                        j += 1;
                    }
                    let mut j2 = 0;
                    while j2 < sb.len().min(w) {
                        base[dst_off + j2] = sb[j2];
                        j2 += 1;
                    }
                    bit += 1;
                }
            }
            let mut k = 0;
            while k < w {
                out[k] = result[k];
                k += 1;
            }
        }
        _ => {
            return Err(PipelineFailure::ShapeViolation {
                report: crate::enforcement::ShapeViolation {
                    shape_iri: "https://uor.foundation/pipeline/PrimitiveOpArityShape",
                    constraint_iri:
                        "https://uor.foundation/pipeline/PrimitiveOpArityShape/unary-as-binary",
                    property_iri: "https://uor.foundation/pipeline/operatorArity",
                    expected_range: "http://www.w3.org/2001/XMLSchema#nonNegativeInteger",
                    min_count: 1,
                    max_count: 1,
                    kind: crate::ViolationKind::CardinalityViolation,
                },
            })
        }
    }
    Ok(TermValue::from_slice(&out[..w]))
}

fn bytes_shl1(buf: &mut [u8], w: usize) {
    let mut carry: u8 = 0;
    let mut i = w;
    while i > 0 {
        i -= 1;
        let v = buf[i];
        buf[i] = (v << 1) | carry;
        carry = v >> 7;
    }
}

fn bytes_le_be(a: &[u8], b: &[u8]) -> bool {
    let mut i = 0;
    while i < a.len() {
        if a[i] < b[i] {
            return true;
        }
        if a[i] > b[i] {
            return false;
        }
        i += 1;
    }
    true
}

fn bytes_sub_in_place(dst: &mut [u8], rhs: &[u8], w: usize) {
    let mut borrow: i16 = 0;
    let mut i = w;
    while i > 0 {
        i -= 1;
        let d = dst[i] as i16 - rhs[i] as i16 - borrow;
        if d < 0 {
            dst[i] = (d + 256) as u8;
            borrow = 1;
        } else {
            dst[i] = d as u8;
            borrow = 0;
        }
    }
}

fn byte_compare_be(a: &[u8], b: &[u8]) -> core::cmp::Ordering {
    // Pad shorter operand with leading zeros so the comparison treats
    // both operands at max(len(a), len(b)) byte width.
    let max_len = if a.len() > b.len() { a.len() } else { b.len() };
    let mut i = 0;
    while i < max_len {
        let ai = if i + a.len() >= max_len {
            a[i + a.len() - max_len]
        } else {
            0u8
        };
        let bi = if i + b.len() >= max_len {
            b[i + b.len() - max_len]
        } else {
            0u8
        };
        if ai < bi {
            return core::cmp::Ordering::Less;
        }
        if ai > bi {
            return core::cmp::Ordering::Greater;
        }
        i += 1;
    }
    core::cmp::Ordering::Equal
}

fn bytes_to_u64_be(bytes: &[u8]) -> u64 {
    let take = if bytes.len() > 8 { 8 } else { bytes.len() };
    let start = bytes.len() - take;
    let mut acc = 0u64;
    let mut i = 0;
    while i < take {
        acc = (acc << 8) | bytes[start + i] as u64;
        i += 1;
    }
    acc
}

fn bytes_all_zero(bytes: &[u8]) -> bool {
    let mut i = 0;
    while i < bytes.len() {
        if bytes[i] != 0 {
            return false;
        }
        i += 1;
    }
    true
}

fn u64_modpow(base: u64, exp: u64, mask: u64) -> u64 {
    let mut result: u64 = 1u64 & mask;
    let mut b: u64 = base & mask;
    let mut e: u64 = exp;
    while e > 0 {
        if (e & 1) == 1 {
            result = result.wrapping_mul(b) & mask;
        }
        b = b.wrapping_mul(b) & mask;
        e >>= 1;
    }
    result
}

/// Foundation-sanctioned identity route: `ConstrainedTypeInput` is the
/// empty default shape, vacuously closed under foundation vocabulary.
/// Application authors with non-trivial routes use the `prism_model!`
/// macro from `uor-foundation-sdk`, which emits `FoundationClosed` for
/// the witness it generates iff every node is foundation-vocabulary.
/// The identity route's `arena_slice()` returns `&[]` — no terms, no
/// transformation, input passes through to output unchanged.
impl __sdk_seal::Sealed for ConstrainedTypeInput {}
impl FoundationClosed for ConstrainedTypeInput {
    fn arena_slice() -> &'static [crate::enforcement::Term] {
        &[]
    }
}
impl IntoBindingValue for ConstrainedTypeInput {
    const MAX_BYTES: usize = 0;
    fn into_binding_bytes(
        &self,
        _out: &mut [u8],
    ) -> core::result::Result<usize, crate::enforcement::ShapeViolation> {
        // Identity input carries no bytes — the empty shape's canonical
        // serialization is the empty byte sequence.
        Ok(0)
    }
}

/// Marker for a `ConstrainedTypeShape` that is the Cartesian product of
/// two component shapes. Selecting this trait routes nerve-Betti computation
/// through Künneth composition of component Betti profiles rather than
/// flat enumeration of (constraint, constraint) pairs. Introduced by the
/// Product/Coproduct Completion Amendment §3c for CartesianPartitionProduct
/// (CPT_1–CPT_6).
pub trait CartesianProductShape: ConstrainedTypeShape {
    /// Left operand shape.
    type Left: ConstrainedTypeShape;
    /// Right operand shape.
    type Right: ConstrainedTypeShape;
}

/// Künneth composition of two Betti profiles.
/// Computes `out[k] = Σ_{i + j = k} a[i] · b[j]` over
/// `[0, MAX_BETTI_DIMENSION)`. All arithmetic uses saturating operations so the
/// function is total on `[u32; MAX_BETTI_DIMENSION]` inputs without panicking.
pub const fn kunneth_compose(
    a: &[u32; crate::enforcement::MAX_BETTI_DIMENSION],
    b: &[u32; crate::enforcement::MAX_BETTI_DIMENSION],
) -> [u32; crate::enforcement::MAX_BETTI_DIMENSION] {
    let mut out = [0u32; crate::enforcement::MAX_BETTI_DIMENSION];
    let mut i: usize = 0;
    while i < crate::enforcement::MAX_BETTI_DIMENSION {
        let mut j: usize = 0;
        while j < crate::enforcement::MAX_BETTI_DIMENSION - i {
            let term = a[i].saturating_mul(b[j]);
            out[i + j] = out[i + j].saturating_add(term);
            j += 1;
        }
        i += 1;
    }
    out
}

/// Cartesian-product nerve Betti via Künneth composition of the component
/// shapes' Betti profiles. Used instead of
/// `primitive_simplicial_nerve_betti` when a shape declares itself as a
/// `CartesianProductShape`. Amendment §3c.
/// Phase 1a (orphan-closure): propagates either component's
/// `NERVE_CAPACITY_EXCEEDED` via `?`. Dropped `const fn` because
/// the `Result` return of the per-component primitive is not `const`-evaluable.
/// ADR-057: delegates to [`crate::enforcement::primitive_simplicial_nerve_betti`]
/// on each component, which expands `ConstraintRef::Recurse` through
/// foundation's built-in shape registry. For application-registry-aware
/// expansion, use [`primitive_cartesian_nerve_betti_in`] generic over the
/// application's `ShapeRegistryProvider`.
/// # Errors
/// Returns `NERVE_CAPACITY_EXCEEDED` if either component exceeds caps.
/// Returns `RECURSE_SHAPE_UNREGISTERED` when a component's Recurse references
/// an IRI not present in the consulted registry.
pub fn primitive_cartesian_nerve_betti<S: CartesianProductShape>() -> Result<
    [u32; crate::enforcement::MAX_BETTI_DIMENSION],
    crate::enforcement::GenericImpossibilityWitness,
> {
    let left = crate::enforcement::primitive_simplicial_nerve_betti::<S::Left>()?;
    let right = crate::enforcement::primitive_simplicial_nerve_betti::<S::Right>()?;
    Ok(kunneth_compose(&left, &right))
}

/// ADR-057: registry-parameterized companion to
/// [`primitive_cartesian_nerve_betti`]. Delegates to
/// [`crate::enforcement::primitive_simplicial_nerve_betti_in`] on each
/// component with `R` as the application's `ShapeRegistryProvider`.
/// Recurse entries are expanded through `R::REGISTRY` plus foundation's
/// built-in registry.
/// # Errors
/// Returns `NERVE_CAPACITY_EXCEEDED` if either component's expanded
/// constraint set exceeds caps. Returns `RECURSE_SHAPE_UNREGISTERED` when
/// a `Recurse` entry references an IRI not present in either registry.
pub fn primitive_cartesian_nerve_betti_in<
    S: CartesianProductShape,
    R: crate::pipeline::shape_iri_registry::ShapeRegistryProvider,
>() -> Result<
    [u32; crate::enforcement::MAX_BETTI_DIMENSION],
    crate::enforcement::GenericImpossibilityWitness,
> {
    let left = crate::enforcement::primitive_simplicial_nerve_betti_in::<S::Left, R>()?;
    let right = crate::enforcement::primitive_simplicial_nerve_betti_in::<S::Right, R>()?;
    Ok(kunneth_compose(&left, &right))
}

/// Shift every site-index reference in a `ConstraintRef` by `offset`.
/// Used by the SDK's `product_shape!` / `coproduct_shape!` /
/// `cartesian_product_shape!` macros to splice an operand's constraints into
/// a combined shape at a post-operand offset.
/// **Phase 17: full operand-catalogue support.** Affine and
/// Conjunction now shift correctly at const time because the
/// variants store fixed-size arrays (no `&'static [i64]` allocation
/// required). The pre-Phase-17 `Site { position: u32::MAX }`
/// sentinel is removed.
/// **Variant coverage.**
/// - `Site { position }` → position += offset.
/// - `Carry { site }` → site += offset.
/// - `Residue`, `Hamming`, `Depth`, `SatClauses`, `Bound`: pass through (no
///   site references at this layer).
/// - `Affine { coefficients, coefficient_count, bias }`: builds a fresh
///   `[i64; AFFINE_MAX_COEFFS]` of zeros, copies the active prefix into
///   positions `[offset, offset + coefficient_count)`. If the shift
///   would overflow the fixed buffer, returns an Affine with
///   `coefficient_count = 0` (vacuously consistent).
/// - `Conjunction { conjuncts, conjunct_count }`: builds a fresh
///   `[LeafConstraintRef; CONJUNCTION_MAX_TERMS]` and shifts each leaf
///   via `shift_leaf_constraint`. One-level depth — leaves cannot be
///   Conjunction.
pub const fn shift_constraint(c: ConstraintRef, offset: u32) -> ConstraintRef {
    match c {
        ConstraintRef::Site { position } => ConstraintRef::Site {
            position: position.saturating_add(offset),
        },
        ConstraintRef::Carry { site } => ConstraintRef::Carry {
            site: site.saturating_add(offset),
        },
        ConstraintRef::Residue { modulus, residue } => ConstraintRef::Residue { modulus, residue },
        ConstraintRef::Hamming { bound } => ConstraintRef::Hamming { bound },
        ConstraintRef::Depth { min, max } => ConstraintRef::Depth { min, max },
        ConstraintRef::SatClauses { clauses, num_vars } => {
            ConstraintRef::SatClauses { clauses, num_vars }
        }
        ConstraintRef::Bound {
            observable_iri,
            bound_shape_iri,
            args_repr,
        } => ConstraintRef::Bound {
            observable_iri,
            bound_shape_iri,
            args_repr,
        },
        ConstraintRef::Affine {
            coefficients,
            coefficient_count,
            bias,
        } => {
            let (out, new_count) =
                shift_affine_coefficients(&coefficients, coefficient_count, offset);
            ConstraintRef::Affine {
                coefficients: out,
                coefficient_count: new_count,
                bias,
            }
        }
        ConstraintRef::Conjunction {
            conjuncts,
            conjunct_count,
        } => {
            let mut out = [LeafConstraintRef::Site { position: 0 }; CONJUNCTION_MAX_TERMS];
            let count = conjunct_count as usize;
            let mut i = 0;
            while i < count && i < CONJUNCTION_MAX_TERMS {
                out[i] = shift_leaf_constraint(conjuncts[i], offset);
                i += 1;
            }
            ConstraintRef::Conjunction {
                conjuncts: out,
                conjunct_count,
            }
        }
        // ADR-057: Recurse references a shape by content-addressed IRI;
        // there are no site positions to shift. Pass through unchanged.
        ConstraintRef::Recurse {
            shape_iri,
            descent_bound,
        } => ConstraintRef::Recurse {
            shape_iri,
            descent_bound,
        },
    }
}

/// Phase 17 helper: shift the active prefix of an `Affine`
/// coefficient array right by `offset`, returning a fresh
/// `[i64; AFFINE_MAX_COEFFS]` and the new active count. If the
/// shift would overflow the fixed buffer, returns count `0`
/// (vacuously consistent — no constraint).
#[inline]
#[must_use]
const fn shift_affine_coefficients(
    coefficients: &[i64; AFFINE_MAX_COEFFS],
    coefficient_count: u32,
    offset: u32,
) -> ([i64; AFFINE_MAX_COEFFS], u32) {
    let mut out = [0i64; AFFINE_MAX_COEFFS];
    let count = coefficient_count as usize;
    let off = offset as usize;
    if off >= AFFINE_MAX_COEFFS {
        return (out, 0);
    }
    let mut i = 0;
    while i < count && i + off < AFFINE_MAX_COEFFS {
        out[i + off] = coefficients[i];
        i += 1;
    }
    let new_count = (i + off) as u32;
    (out, new_count)
}

/// Phase 17 helper: same as [`shift_constraint`] but operating on a
/// [`LeafConstraintRef`]. Used by Conjunction-shifting paths that
/// must preserve the leaf-only depth limit.
#[inline]
#[must_use]
pub const fn shift_leaf_constraint(c: LeafConstraintRef, offset: u32) -> LeafConstraintRef {
    match c {
        LeafConstraintRef::Site { position } => LeafConstraintRef::Site {
            position: position.saturating_add(offset),
        },
        LeafConstraintRef::Carry { site } => LeafConstraintRef::Carry {
            site: site.saturating_add(offset),
        },
        LeafConstraintRef::Residue { modulus, residue } => {
            LeafConstraintRef::Residue { modulus, residue }
        }
        LeafConstraintRef::Hamming { bound } => LeafConstraintRef::Hamming { bound },
        LeafConstraintRef::Depth { min, max } => LeafConstraintRef::Depth { min, max },
        LeafConstraintRef::SatClauses { clauses, num_vars } => {
            LeafConstraintRef::SatClauses { clauses, num_vars }
        }
        LeafConstraintRef::Bound {
            observable_iri,
            bound_shape_iri,
            args_repr,
        } => LeafConstraintRef::Bound {
            observable_iri,
            bound_shape_iri,
            args_repr,
        },
        LeafConstraintRef::Affine {
            coefficients,
            coefficient_count,
            bias,
        } => {
            let (out, new_count) =
                shift_affine_coefficients(&coefficients, coefficient_count, offset);
            LeafConstraintRef::Affine {
                coefficients: out,
                coefficient_count: new_count,
                bias,
            }
        }
        // ADR-057: Recurse references a shape by content-addressed IRI;
        // there are no site positions to shift. Pass through unchanged.
        LeafConstraintRef::Recurse {
            shape_iri,
            descent_bound,
        } => LeafConstraintRef::Recurse {
            shape_iri,
            descent_bound,
        },
    }
}

/// SDK support: concatenate two operand constraint arrays into a padded
/// fixed-size buffer of length `2 * crate::enforcement::NERVE_CONSTRAINTS_CAP`.
/// A's constraints are copied verbatim at indices `[0, A::CONSTRAINTS.len())`;
/// B's constraints are copied at `[A::CONSTRAINTS.len(), total)` with each
/// entry passed through `shift_constraint(c, A::SITE_COUNT as u32)`.
/// Trailing positions are filled with the `Site { position: u32::MAX }`
/// sentinel.
/// Consumers pair this with `sdk_product_constraints_len` to derive the
/// slice length at const-eval time: `&BUF[..LEN]` yields a `&'static
/// [ConstraintRef]` of the correct length without `unsafe`.
pub const fn sdk_concat_product_constraints<A, B>(
) -> [ConstraintRef; 2 * crate::enforcement::NERVE_CONSTRAINTS_CAP]
where
    A: ConstrainedTypeShape,
    B: ConstrainedTypeShape,
{
    let mut out =
        [ConstraintRef::Site { position: u32::MAX }; 2 * crate::enforcement::NERVE_CONSTRAINTS_CAP];
    let left = A::CONSTRAINTS;
    let right = B::CONSTRAINTS;
    let offset = A::SITE_COUNT as u32;
    let mut i: usize = 0;
    while i < left.len() {
        out[i] = left[i];
        i += 1;
    }
    let mut j: usize = 0;
    while j < right.len() {
        out[i + j] = shift_constraint(right[j], offset);
        j += 1;
    }
    out
}

/// Companion length helper for `sdk_concat_product_constraints`.
pub const fn sdk_product_constraints_len<A, B>() -> usize
where
    A: ConstrainedTypeShape,
    B: ConstrainedTypeShape,
{
    A::CONSTRAINTS.len() + B::CONSTRAINTS.len()
}

/// ADR-057 recurse-aware variant of `sdk_concat_product_constraints`.
/// Per-operand `Option<u32>` recurse-bound parameter: `None` inlines the
/// operand's CONSTRAINTS array as before; `Some(bound)` emits a single
/// `ConstraintRef::Recurse { shape_iri: <T>::IRI, descent_bound: bound }`
/// at the operand's position. Site offsets for the following operand's
/// inline constraints account for the recurse operand's
/// `<T>::SITE_COUNT` as if it were inlined.
pub const fn sdk_concat_product_constraints_v2<A, B>(
    a_recurse_bound: Option<u32>,
    b_recurse_bound: Option<u32>,
) -> [ConstraintRef; 2 * crate::enforcement::NERVE_CONSTRAINTS_CAP]
where
    A: ConstrainedTypeShape,
    B: ConstrainedTypeShape,
{
    let mut out =
        [ConstraintRef::Site { position: u32::MAX }; 2 * crate::enforcement::NERVE_CONSTRAINTS_CAP];
    let offset = A::SITE_COUNT as u32;
    let mut i: usize = 0;
    // A's contribution: single Recurse entry or inlined constraints.
    match a_recurse_bound {
        Some(bound) => {
            out[0] = ConstraintRef::Recurse {
                shape_iri: A::IRI,
                descent_bound: bound,
            };
            i = 1;
        }
        None => {
            let left = A::CONSTRAINTS;
            while i < left.len() {
                out[i] = left[i];
                i += 1;
            }
        }
    }
    // B's contribution: single Recurse entry or inlined-and-shifted constraints.
    match b_recurse_bound {
        Some(bound) => {
            out[i] = ConstraintRef::Recurse {
                shape_iri: B::IRI,
                descent_bound: bound,
            };
        }
        None => {
            let right = B::CONSTRAINTS;
            let mut j: usize = 0;
            while j < right.len() {
                out[i + j] = shift_constraint(right[j], offset);
                j += 1;
            }
        }
    }
    out
}

/// Companion length helper for `sdk_concat_product_constraints_v2`.
pub const fn sdk_product_constraints_v2_len<A, B>(a_recurse: bool, b_recurse: bool) -> usize
where
    A: ConstrainedTypeShape,
    B: ConstrainedTypeShape,
{
    let a_len = if a_recurse { 1 } else { A::CONSTRAINTS.len() };
    let b_len = if b_recurse { 1 } else { B::CONSTRAINTS.len() };
    a_len + b_len
}

/// ADR-057: bounded recursive structural typing — foundation shape-IRI
/// registry module. Mirrors the architectural pattern of the
/// observable-IRI registry per ADR-038/049 and the substitution-axis
/// catalog per ADR-007/030: a closed catalog of shape IRIs admissible
/// as `ConstraintRef::Recurse` targets, consulted by ψ_1's NerveResolver
/// when expanding recursive references at evaluation time.
/// # Architecture
/// Foundation is `#![no_std]` with zero dependencies and zero `unsafe`,
/// so the registry uses **const-aggregation through a sealed trait**
/// rather than a mutable global or link-section symbol resolution.
/// Applications declare their shape registry as a single type via the
/// SDK `register_shape!(Shape1, Shape2, …)` macro per crate; the type
/// implements [`ShapeRegistryProvider`] with the const-aggregated slice.
/// ψ_1 NerveResolver consults the registry through [`lookup_shape_in`].
/// Foundation's built-in [`lookup_shape`] consults a foundation-owned
/// static registry — currently empty; standard-library Layer-3 sub-crates
/// per ADR-031 publishing canonical recursive-grammar shapes register
/// through this path in future foundation-curated additions.
pub mod shape_iri_registry {
    use super::ConstraintRef;

    /// ADR-057: a registered shape entry. `iri` is the shape's
    /// content-addressed identifier per ADR-017; `site_count`,
    /// `constraints`, and `cycle_size` mirror the corresponding
    /// `ConstrainedTypeShape` associated items so ψ_1's resolver
    /// can walk the referenced shape's constraint set without
    /// touching the original trait impl.
    #[derive(Debug, Clone, Copy)]
    pub struct RegisteredShape {
        /// Content-addressed IRI of the shape (per ADR-017).
        pub iri: &'static str,
        /// Mirror of `<T as ConstrainedTypeShape>::SITE_COUNT`.
        pub site_count: usize,
        /// Mirror of `<T as ConstrainedTypeShape>::CONSTRAINTS`.
        pub constraints: &'static [ConstraintRef],
        /// Mirror of `<T as ConstrainedTypeShape>::CYCLE_SIZE`.
        pub cycle_size: u64,
    }

    /// ADR-057: sealed trait carrying a crate's registered-shape slice
    /// at the const-aggregation surface. The SDK `register_shape!` macro
    /// emits an `impl ShapeRegistryProvider` on a marker type whose
    /// `REGISTRY` const is the list of registered shapes.
    /// Sealed via [`super::__sdk_seal::Sealed`] per ADR-022 D1; only
    /// the SDK `register_shape!` macro emits impls (plus foundation's
    /// [`EmptyShapeRegistry`] default).
    pub trait ShapeRegistryProvider: super::__sdk_seal::Sealed {
        /// The crate's registered-shape slice. Walked by
        /// [`lookup_shape_in`] when ψ_1 NerveResolver expands
        /// `ConstraintRef::Recurse` references at evaluation time.
        const REGISTRY: &'static [RegisteredShape];
    }

    /// ADR-057: the empty-registry default, used by applications that
    /// don't carry recursive shapes. Foundation provides this as the
    /// baseline `ShapeRegistryProvider` impl; applications with
    /// recursive shapes use the SDK `register_shape!` macro to declare
    /// their own marker type with a non-empty `REGISTRY`.
    #[derive(Debug, Clone, Copy, Default)]
    pub struct EmptyShapeRegistry;
    impl super::__sdk_seal::Sealed for EmptyShapeRegistry {}
    impl ShapeRegistryProvider for EmptyShapeRegistry {
        const REGISTRY: &'static [RegisteredShape] = &[];
    }

    /// Foundation's built-in shape registry. Currently empty —
    /// standard-library Layer-3 sub-crates per ADR-031 publishing
    /// canonical recursive-grammar shapes (canonical JSON, AST, etc.)
    /// register through this path in future foundation-curated additions.
    static FOUNDATION_REGISTRY: &[RegisteredShape] = &[];

    /// ADR-057: look up a registered shape by IRI in the
    /// foundation-built-in registry. Returns `None` if the IRI is
    /// not present; applications consulting their own application-
    /// registered shapes use [`lookup_shape_in`] generic over their
    /// `ShapeRegistryProvider`-implementing marker type.
    /// Called by ψ_1's NerveResolver during `ConstraintRef::Recurse`
    /// evaluation when no application registry is threaded through.
    #[must_use]
    pub fn lookup_shape(iri: &str) -> Option<&'static RegisteredShape> {
        lookup_in_slice(FOUNDATION_REGISTRY, iri)
    }

    /// ADR-057: look up a registered shape by IRI in an application's
    /// registry plus the foundation-built-in registry. Walks the
    /// application's `R::REGISTRY` first, then falls back to the
    /// foundation registry; returns `None` if the IRI is in neither.
    /// Called by ψ_1's NerveResolver during `ConstraintRef::Recurse`
    /// evaluation when an application registry is threaded through
    /// (per `pipeline::run_route`'s registry-parameterized path).
    #[must_use]
    pub fn lookup_shape_in<R: ShapeRegistryProvider>(
        iri: &str,
    ) -> Option<&'static RegisteredShape> {
        if let Some(entry) = lookup_in_slice(R::REGISTRY, iri) {
            return Some(entry);
        }
        lookup_in_slice(FOUNDATION_REGISTRY, iri)
    }

    /// Linear-scan helper used by both [`lookup_shape`] and
    /// [`lookup_shape_in`]. Registry slices are expected to be small
    /// (a handful of canonical shapes per standard-library sub-crate
    /// or per application), so linear scan dominates startup cost.
    fn lookup_in_slice(
        slice: &'static [RegisteredShape],
        iri: &str,
    ) -> Option<&'static RegisteredShape> {
        let mut i = 0;
        while i < slice.len() {
            let entry = &slice[i];
            if iri_eq(entry.iri, iri) {
                return Some(entry);
            }
            i += 1;
        }
        None
    }

    fn iri_eq(a: &str, b: &str) -> bool {
        a.as_bytes() == b.as_bytes()
    }
}

/// ADR-032: per-Witt-level zero-sized marker types implementing
/// `ConstrainedTypeShape`. The `prism_model!` proc-macro consumes
/// these as the `<DomainTy>` operand of `first_admit(<DomainTy>, |i| …)`
/// (G16): `<DomainTy as ConstrainedTypeShape>::CYCLE_SIZE` carries the
/// domain's cardinality, which the macro lowers as the descent measure
/// for the emitted `Term::Recurse`.
/// Each level's `CYCLE_SIZE` is `2^bits_width`, saturated at
/// `u64::MAX` for levels whose cardinality exceeds 64-bit range.
/// The wiki's normative example `first_admit(WittLevel::W32, |nonce| …)`
/// compiles on stable Rust 1.83 as `first_admit(witt_domain::W32, |nonce| …)`
/// (`witt_domain::W32::CYCLE_SIZE = 4_294_967_296`).
pub mod witt_domain {
    use super::{ConstrainedTypeShape, ConstraintRef, PartitionProductFields};
    use crate::enforcement::GroundedShape;
    use crate::enforcement::ShapeViolation;
    use crate::pipeline::__sdk_seal;
    use crate::pipeline::IntoBindingValue;

    /// ADR-032 Witt-level domain marker for `W8` (8-bit ring).
    /// `CYCLE_SIZE = 2^8 = 256`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W8;
    impl ConstrainedTypeShape for W8 {
        const IRI: &'static str = "https://uor.foundation/witt/W8";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = 256u64;
    }
    impl __sdk_seal::Sealed for W8 {}
    impl IntoBindingValue for W8 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W8 {}
    impl PartitionProductFields for W8 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W16` (16-bit ring).
    /// `CYCLE_SIZE = 2^16 = 65536`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W16;
    impl ConstrainedTypeShape for W16 {
        const IRI: &'static str = "https://uor.foundation/witt/W16";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = 65536u64;
    }
    impl __sdk_seal::Sealed for W16 {}
    impl IntoBindingValue for W16 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W16 {}
    impl PartitionProductFields for W16 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W24` (24-bit ring).
    /// `CYCLE_SIZE = 2^24 = 16777216`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W24;
    impl ConstrainedTypeShape for W24 {
        const IRI: &'static str = "https://uor.foundation/witt/W24";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = 16777216u64;
    }
    impl __sdk_seal::Sealed for W24 {}
    impl IntoBindingValue for W24 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W24 {}
    impl PartitionProductFields for W24 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W32` (32-bit ring).
    /// `CYCLE_SIZE = 2^32 = 4294967296`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W32;
    impl ConstrainedTypeShape for W32 {
        const IRI: &'static str = "https://uor.foundation/witt/W32";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = 4294967296u64;
    }
    impl __sdk_seal::Sealed for W32 {}
    impl IntoBindingValue for W32 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W32 {}
    impl PartitionProductFields for W32 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W40` (40-bit ring).
    /// `CYCLE_SIZE = 2^40 = 1099511627776`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W40;
    impl ConstrainedTypeShape for W40 {
        const IRI: &'static str = "https://uor.foundation/witt/W40";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = 1099511627776u64;
    }
    impl __sdk_seal::Sealed for W40 {}
    impl IntoBindingValue for W40 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W40 {}
    impl PartitionProductFields for W40 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W48` (48-bit ring).
    /// `CYCLE_SIZE = 2^48 = 281474976710656`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W48;
    impl ConstrainedTypeShape for W48 {
        const IRI: &'static str = "https://uor.foundation/witt/W48";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = 281474976710656u64;
    }
    impl __sdk_seal::Sealed for W48 {}
    impl IntoBindingValue for W48 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W48 {}
    impl PartitionProductFields for W48 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W56` (56-bit ring).
    /// `CYCLE_SIZE = 2^56 = 72057594037927936`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W56;
    impl ConstrainedTypeShape for W56 {
        const IRI: &'static str = "https://uor.foundation/witt/W56";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = 72057594037927936u64;
    }
    impl __sdk_seal::Sealed for W56 {}
    impl IntoBindingValue for W56 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W56 {}
    impl PartitionProductFields for W56 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W64` (64-bit ring).
    /// `CYCLE_SIZE = 2^64 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W64;
    impl ConstrainedTypeShape for W64 {
        const IRI: &'static str = "https://uor.foundation/witt/W64";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W64 {}
    impl IntoBindingValue for W64 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W64 {}
    impl PartitionProductFields for W64 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W72` (72-bit ring).
    /// `CYCLE_SIZE = 2^72 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W72;
    impl ConstrainedTypeShape for W72 {
        const IRI: &'static str = "https://uor.foundation/witt/W72";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W72 {}
    impl IntoBindingValue for W72 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W72 {}
    impl PartitionProductFields for W72 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W80` (80-bit ring).
    /// `CYCLE_SIZE = 2^80 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W80;
    impl ConstrainedTypeShape for W80 {
        const IRI: &'static str = "https://uor.foundation/witt/W80";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W80 {}
    impl IntoBindingValue for W80 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W80 {}
    impl PartitionProductFields for W80 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W88` (88-bit ring).
    /// `CYCLE_SIZE = 2^88 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W88;
    impl ConstrainedTypeShape for W88 {
        const IRI: &'static str = "https://uor.foundation/witt/W88";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W88 {}
    impl IntoBindingValue for W88 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W88 {}
    impl PartitionProductFields for W88 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W96` (96-bit ring).
    /// `CYCLE_SIZE = 2^96 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W96;
    impl ConstrainedTypeShape for W96 {
        const IRI: &'static str = "https://uor.foundation/witt/W96";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W96 {}
    impl IntoBindingValue for W96 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W96 {}
    impl PartitionProductFields for W96 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W104` (104-bit ring).
    /// `CYCLE_SIZE = 2^104 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W104;
    impl ConstrainedTypeShape for W104 {
        const IRI: &'static str = "https://uor.foundation/witt/W104";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W104 {}
    impl IntoBindingValue for W104 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W104 {}
    impl PartitionProductFields for W104 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W112` (112-bit ring).
    /// `CYCLE_SIZE = 2^112 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W112;
    impl ConstrainedTypeShape for W112 {
        const IRI: &'static str = "https://uor.foundation/witt/W112";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W112 {}
    impl IntoBindingValue for W112 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W112 {}
    impl PartitionProductFields for W112 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W120` (120-bit ring).
    /// `CYCLE_SIZE = 2^120 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W120;
    impl ConstrainedTypeShape for W120 {
        const IRI: &'static str = "https://uor.foundation/witt/W120";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W120 {}
    impl IntoBindingValue for W120 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W120 {}
    impl PartitionProductFields for W120 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W128` (128-bit ring).
    /// `CYCLE_SIZE = 2^128 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W128;
    impl ConstrainedTypeShape for W128 {
        const IRI: &'static str = "https://uor.foundation/witt/W128";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W128 {}
    impl IntoBindingValue for W128 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W128 {}
    impl PartitionProductFields for W128 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W160` (160-bit ring).
    /// `CYCLE_SIZE = 2^160 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W160;
    impl ConstrainedTypeShape for W160 {
        const IRI: &'static str = "https://uor.foundation/witt/W160";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W160 {}
    impl IntoBindingValue for W160 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W160 {}
    impl PartitionProductFields for W160 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W192` (192-bit ring).
    /// `CYCLE_SIZE = 2^192 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W192;
    impl ConstrainedTypeShape for W192 {
        const IRI: &'static str = "https://uor.foundation/witt/W192";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W192 {}
    impl IntoBindingValue for W192 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W192 {}
    impl PartitionProductFields for W192 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W224` (224-bit ring).
    /// `CYCLE_SIZE = 2^224 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W224;
    impl ConstrainedTypeShape for W224 {
        const IRI: &'static str = "https://uor.foundation/witt/W224";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W224 {}
    impl IntoBindingValue for W224 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W224 {}
    impl PartitionProductFields for W224 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W256` (256-bit ring).
    /// `CYCLE_SIZE = 2^256 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W256;
    impl ConstrainedTypeShape for W256 {
        const IRI: &'static str = "https://uor.foundation/witt/W256";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W256 {}
    impl IntoBindingValue for W256 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W256 {}
    impl PartitionProductFields for W256 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W384` (384-bit ring).
    /// `CYCLE_SIZE = 2^384 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W384;
    impl ConstrainedTypeShape for W384 {
        const IRI: &'static str = "https://uor.foundation/witt/W384";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W384 {}
    impl IntoBindingValue for W384 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W384 {}
    impl PartitionProductFields for W384 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W448` (448-bit ring).
    /// `CYCLE_SIZE = 2^448 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W448;
    impl ConstrainedTypeShape for W448 {
        const IRI: &'static str = "https://uor.foundation/witt/W448";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W448 {}
    impl IntoBindingValue for W448 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W448 {}
    impl PartitionProductFields for W448 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W512` (512-bit ring).
    /// `CYCLE_SIZE = 2^512 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W512;
    impl ConstrainedTypeShape for W512 {
        const IRI: &'static str = "https://uor.foundation/witt/W512";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W512 {}
    impl IntoBindingValue for W512 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W512 {}
    impl PartitionProductFields for W512 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W520` (520-bit ring).
    /// `CYCLE_SIZE = 2^520 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W520;
    impl ConstrainedTypeShape for W520 {
        const IRI: &'static str = "https://uor.foundation/witt/W520";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W520 {}
    impl IntoBindingValue for W520 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W520 {}
    impl PartitionProductFields for W520 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W528` (528-bit ring).
    /// `CYCLE_SIZE = 2^528 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W528;
    impl ConstrainedTypeShape for W528 {
        const IRI: &'static str = "https://uor.foundation/witt/W528";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W528 {}
    impl IntoBindingValue for W528 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W528 {}
    impl PartitionProductFields for W528 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W1024` (1024-bit ring).
    /// `CYCLE_SIZE = 2^1024 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W1024;
    impl ConstrainedTypeShape for W1024 {
        const IRI: &'static str = "https://uor.foundation/witt/W1024";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W1024 {}
    impl IntoBindingValue for W1024 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W1024 {}
    impl PartitionProductFields for W1024 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W2048` (2048-bit ring).
    /// `CYCLE_SIZE = 2^2048 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W2048;
    impl ConstrainedTypeShape for W2048 {
        const IRI: &'static str = "https://uor.foundation/witt/W2048";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W2048 {}
    impl IntoBindingValue for W2048 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W2048 {}
    impl PartitionProductFields for W2048 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W4096` (4096-bit ring).
    /// `CYCLE_SIZE = 2^4096 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W4096;
    impl ConstrainedTypeShape for W4096 {
        const IRI: &'static str = "https://uor.foundation/witt/W4096";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W4096 {}
    impl IntoBindingValue for W4096 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W4096 {}
    impl PartitionProductFields for W4096 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W8192` (8192-bit ring).
    /// `CYCLE_SIZE = 2^8192 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W8192;
    impl ConstrainedTypeShape for W8192 {
        const IRI: &'static str = "https://uor.foundation/witt/W8192";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W8192 {}
    impl IntoBindingValue for W8192 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W8192 {}
    impl PartitionProductFields for W8192 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W12288` (12288-bit ring).
    /// `CYCLE_SIZE = 2^12288 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W12288;
    impl ConstrainedTypeShape for W12288 {
        const IRI: &'static str = "https://uor.foundation/witt/W12288";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W12288 {}
    impl IntoBindingValue for W12288 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W12288 {}
    impl PartitionProductFields for W12288 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W16384` (16384-bit ring).
    /// `CYCLE_SIZE = 2^16384 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W16384;
    impl ConstrainedTypeShape for W16384 {
        const IRI: &'static str = "https://uor.foundation/witt/W16384";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W16384 {}
    impl IntoBindingValue for W16384 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W16384 {}
    impl PartitionProductFields for W16384 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }

    /// ADR-032 Witt-level domain marker for `W32768` (32768-bit ring).
    /// `CYCLE_SIZE = 2^32768 = u64::MAX (saturated)`. Used as the `<DomainTy>` operand of
    /// `first_admit(<DomainTy>, |i| …)` (G16) in `prism_model!` closures.
    pub struct W32768;
    impl ConstrainedTypeShape for W32768 {
        const IRI: &'static str = "https://uor.foundation/witt/W32768";
        const SITE_COUNT: usize = 1;
        const CONSTRAINTS: &'static [ConstraintRef] = &[];
        const CYCLE_SIZE: u64 = u64::MAX;
    }
    impl __sdk_seal::Sealed for W32768 {}
    impl IntoBindingValue for W32768 {
        const MAX_BYTES: usize = 0;
        fn into_binding_bytes(&self, _out: &mut [u8]) -> Result<usize, ShapeViolation> {
            Ok(0)
        }
    }
    impl GroundedShape for W32768 {}
    impl PartitionProductFields for W32768 {
        const FIELDS: &'static [(u32, u32)] = &[];
        const FIELD_NAMES: &'static [&'static str] = &[];
    }
}

/// Admit a downstream [`ConstrainedTypeShape`] into the reduction pipeline.
/// Runs the full preflight chain on `T::CONSTRAINTS`:
/// [`preflight_feasibility`] and [`preflight_package_coherence`]. On success,
/// wraps the supplied `shape` in a [`Validated`] carrying `Runtime` phase.
/// # Errors
/// Returns [`ShapeViolation`] if any constraint in `T::CONSTRAINTS` fails
/// feasibility checking (e.g., residue out of range, depth min > max) or if
/// the constraint system is internally incoherent (e.g., contradictory
/// residue constraints on the same modulus).
/// # Example
/// ```
/// use uor_foundation::pipeline::{
///     ConstrainedTypeShape, ConstraintRef, validate_constrained_type,
/// };
/// pub struct MyShape;
/// impl ConstrainedTypeShape for MyShape {
///     const IRI: &'static str = "https://example.org/MyShape";
///     const SITE_COUNT: usize = 2;
///     const CONSTRAINTS: &'static [ConstraintRef] = &[
///         ConstraintRef::Residue { modulus: 5, residue: 2 },
///     ];
///     const CYCLE_SIZE: u64 = 5;  // ADR-032: 5 residue classes mod 5
/// }
/// let validated = validate_constrained_type(MyShape).unwrap();
/// # let _ = validated;
/// ```
pub fn validate_constrained_type<T: ConstrainedTypeShape>(
    shape: T,
) -> Result<Validated<T, crate::enforcement::Runtime>, ShapeViolation> {
    preflight_feasibility(T::CONSTRAINTS)?;
    preflight_package_coherence(T::CONSTRAINTS)?;
    Ok(Validated::new(shape))
}

/// Const-fn companion for [`validate_constrained_type`].
/// Admits a downstream [`ConstrainedTypeShape`] at compile time, running the
/// same preflight checks as the runtime variant but in `const` context.
/// # Scope
/// `ConstraintRef::Bound { observable_iri, args_repr, .. }` with
/// `observable_iri == "https://uor.foundation/observable/LandauerCost"`
/// requires `f64::from_bits` for args parsing, which is stable in `const`
/// context only from Rust 1.83. The crate's MSRV is 1.81, so this variant
/// rejects const admission of `LandauerCost`-bound constraints with
/// [`ShapeViolation`] and recommends the runtime [`validate_constrained_type`]
/// for those inputs. All other `ConstraintRef` variants admit at const time.
/// # Errors
/// Same as [`validate_constrained_type`], plus the const-context rejection
/// for `LandauerCost`-bound constraints described above.
/// The `T: Copy` bound is required by `const fn` — destructor invocation is
/// not yet const-stable, and `Validated<T>` carries `T` by value. Shape
/// markers are typically zero-sized types which are trivially `Copy`.
pub const fn validate_constrained_type_const<T: ConstrainedTypeShape + Copy>(
    shape: T,
) -> Result<Validated<T, crate::enforcement::CompileTime>, ShapeViolation> {
    // Const-path preflight: walk CONSTRAINTS and apply per-variant const checks.
    // Rejects LandauerCost-bound constraints that need non-const f64::from_bits.
    let constraints = T::CONSTRAINTS;
    let mut i = 0;
    while i < constraints.len() {
        let ok = match &constraints[i] {
            ConstraintRef::SatClauses { clauses, num_vars } => *num_vars != 0 || clauses.is_empty(),
            ConstraintRef::Residue { modulus, residue } => *modulus != 0 && *residue < *modulus,
            ConstraintRef::Carry { .. } => true,
            ConstraintRef::Depth { min, max } => *min <= *max,
            ConstraintRef::Hamming { bound } => *bound <= 32_768,
            ConstraintRef::Site { .. } => true,
            ConstraintRef::Affine {
                coefficients,
                coefficient_count,
                bias,
            } => {
                // Mirror preflight_feasibility's Affine arm in const context.
                let count = *coefficient_count as usize;
                if count == 0 {
                    false
                } else {
                    let mut ok_coeff = true;
                    let mut idx = 0;
                    while idx < count && idx < AFFINE_MAX_COEFFS {
                        if coefficients[idx] == i64::MIN {
                            ok_coeff = false;
                            break;
                        }
                        idx += 1;
                    }
                    ok_coeff && is_affine_consistent(coefficients, *coefficient_count, *bias)
                }
            }
            ConstraintRef::Bound { observable_iri, .. } => {
                // const-fn scope: LandauerCost needs f64::from_bits (stable in
                // const at 1.83). Reject it here; runtime admission handles it.
                !crate::enforcement::str_eq(
                    observable_iri,
                    "https://uor.foundation/observable/LandauerCost",
                )
            }
            ConstraintRef::Conjunction {
                conjuncts,
                conjunct_count,
            } => conjunction_all_sat(conjuncts, *conjunct_count),
            // ADR-057: const-time validation defers Recurse to runtime
            // admission (parallel to ADR-049's LandauerCost deferral).
            // The only const check is that `shape_iri` is non-empty —
            // the registry lookup happens at the runtime admission path.
            ConstraintRef::Recurse { shape_iri, .. } => !shape_iri.is_empty(),
        };
        if !ok {
            return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/type/ConstrainedType",
                constraint_iri: "https://uor.foundation/type/ConstrainedType_const_constraint",
                property_iri: "https://uor.foundation/type/constraints",
                expected_range: "https://uor.foundation/type/Constraint",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::ValueCheck,
            });
        }
        i += 1;
    }
    Ok(Validated::new(shape))
}

/// Result of `fragment_classify`: which `predicate:*Shape` fragment the
/// input belongs to. Drives `InhabitanceResolver` dispatch routing.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FragmentKind {
    /// `predicate:Is2SatShape` — clauses of width ≤ 2.
    TwoSat,
    /// `predicate:IsHornShape` — clauses with ≤ 1 positive literal.
    Horn,
    /// `predicate:IsResidualFragment` — catch-all; no polynomial bound.
    Residual,
}

/// Classify a constraint system into one of the three dispatch fragments.
/// The classifier inspects the first `SatClauses` constraint (if any) and
/// applies the ontology's shape predicates. Constraint systems with no
/// `SatClauses` constraint — e.g., pure residue/hamming constraints — are
/// classified as `Residual`: the dispatch table has no polynomial decider
/// for them, so they route to the `ResidualVerdictResolver` catch-all.
#[must_use]
pub const fn fragment_classify(constraints: &[ConstraintRef]) -> FragmentKind {
    let mut i = 0;
    while i < constraints.len() {
        if let ConstraintRef::SatClauses { clauses, .. } = constraints[i] {
            // Classify by maximum clause width and positive-literal count.
            let mut max_width: usize = 0;
            let mut horn: bool = true;
            let mut j = 0;
            while j < clauses.len() {
                let clause = clauses[j];
                if clause.len() > max_width {
                    max_width = clause.len();
                }
                let mut positives: usize = 0;
                let mut k = 0;
                while k < clause.len() {
                    let (_, negated) = clause[k];
                    if !negated {
                        positives += 1;
                    }
                    k += 1;
                }
                if positives > 1 {
                    horn = false;
                }
                j += 1;
            }
            if max_width <= 2 {
                return FragmentKind::TwoSat;
            } else if horn {
                return FragmentKind::Horn;
            } else {
                return FragmentKind::Residual;
            }
        }
        i += 1;
    }
    // No SAT clauses at all — residual.
    FragmentKind::Residual
}

/// Aspvall-Plass-Tarjan 2-SAT decider: returns `true` iff the clause list
/// is satisfiable.
/// Builds the implication graph: for each clause `(a | b)`, adds
/// `¬a → b` and `¬b → a`. Runs Tarjan's SCC algorithm and checks that
/// no variable and its negation share an SCC. O(n+m) via iterative
/// Tarjan (the `no_std` path can't recurse freely).
/// Bounds (from `reduction:TwoSatBound`): up to 256 variables, up to 512 clauses. The `const` bounds keep the entire decider on the stack — essential for `no_std` and compile-time proc-macro expansion.
const TWO_SAT_MAX_VARS: usize = 256;
const TWO_SAT_MAX_NODES: usize = TWO_SAT_MAX_VARS * 2;
const TWO_SAT_MAX_EDGES: usize = 2048;

/// 2-SAT decision result.
#[must_use]
pub fn decide_two_sat(clauses: &[&[(u32, bool)]], num_vars: u32) -> bool {
    if (num_vars as usize) > TWO_SAT_MAX_VARS {
        return false;
    }
    let n = (num_vars as usize) * 2;
    // Node index: 2*var is positive literal, 2*var+1 is negated.
    let mut adj_starts = [0usize; TWO_SAT_MAX_NODES + 1];
    let mut adj_targets = [0usize; TWO_SAT_MAX_EDGES];
    // First pass: count out-degrees.
    for clause in clauses {
        if clause.len() > 2 || clause.is_empty() {
            return false;
        }
        if clause.len() == 1 {
            let (v, neg) = clause[0];
            let lit = lit_index(v, neg);
            let neg_lit = lit_index(v, !neg);
            // x ↔ (x ∨ x): ¬x → x (assignment forced)
            if neg_lit < n + 1 {
                adj_starts[neg_lit + 1] += 1;
            }
            let _ = lit;
        } else {
            let (a, an) = clause[0];
            let (b, bn) = clause[1];
            // ¬a → b, ¬b → a
            let na = lit_index(a, !an);
            let nb = lit_index(b, !bn);
            if na + 1 < n + 1 {
                adj_starts[na + 1] += 1;
            }
            if nb + 1 < n + 1 {
                adj_starts[nb + 1] += 1;
            }
        }
    }
    // Prefix-sum to get adjacency starts.
    let mut i = 1;
    while i <= n {
        adj_starts[i] += adj_starts[i - 1];
        i += 1;
    }
    let edge_count = adj_starts[n];
    if edge_count > TWO_SAT_MAX_EDGES {
        return false;
    }
    let mut fill = [0usize; TWO_SAT_MAX_NODES];
    for clause in clauses {
        if clause.len() == 1 {
            let (v, neg) = clause[0];
            let pos_lit = lit_index(v, neg);
            let neg_lit = lit_index(v, !neg);
            let slot = adj_starts[neg_lit] + fill[neg_lit];
            adj_targets[slot] = pos_lit;
            fill[neg_lit] += 1;
        } else {
            let (a, an) = clause[0];
            let (b, bn) = clause[1];
            let pa = lit_index(a, an);
            let na = lit_index(a, !an);
            let pb = lit_index(b, bn);
            let nb = lit_index(b, !bn);
            let s1 = adj_starts[na] + fill[na];
            adj_targets[s1] = pb;
            fill[na] += 1;
            let s2 = adj_starts[nb] + fill[nb];
            adj_targets[s2] = pa;
            fill[nb] += 1;
        }
    }
    // Iterative Tarjan's SCC.
    let mut index_counter: usize = 0;
    let mut indices = [usize::MAX; TWO_SAT_MAX_NODES];
    let mut lowlinks = [0usize; TWO_SAT_MAX_NODES];
    let mut on_stack = [false; TWO_SAT_MAX_NODES];
    let mut stack = [0usize; TWO_SAT_MAX_NODES];
    let mut stack_top: usize = 0;
    let mut scc_id = [usize::MAX; TWO_SAT_MAX_NODES];
    let mut scc_count: usize = 0;
    let mut call_stack = [(0usize, 0usize); TWO_SAT_MAX_NODES];
    let mut call_top: usize = 0;
    let mut v = 0;
    while v < n {
        if indices[v] == usize::MAX {
            call_stack[call_top] = (v, adj_starts[v]);
            call_top += 1;
            indices[v] = index_counter;
            lowlinks[v] = index_counter;
            index_counter += 1;
            stack[stack_top] = v;
            stack_top += 1;
            on_stack[v] = true;
            while call_top > 0 {
                let (u, mut next_edge) = call_stack[call_top - 1];
                let end_edge = adj_starts[u + 1];
                let mut advanced = false;
                while next_edge < end_edge {
                    let w = adj_targets[next_edge];
                    next_edge += 1;
                    if indices[w] == usize::MAX {
                        call_stack[call_top - 1] = (u, next_edge);
                        indices[w] = index_counter;
                        lowlinks[w] = index_counter;
                        index_counter += 1;
                        stack[stack_top] = w;
                        stack_top += 1;
                        on_stack[w] = true;
                        call_stack[call_top] = (w, adj_starts[w]);
                        call_top += 1;
                        advanced = true;
                        break;
                    } else if on_stack[w] && indices[w] < lowlinks[u] {
                        lowlinks[u] = indices[w];
                    }
                }
                if !advanced {
                    call_stack[call_top - 1] = (u, next_edge);
                    if lowlinks[u] == indices[u] {
                        loop {
                            stack_top -= 1;
                            let w = stack[stack_top];
                            on_stack[w] = false;
                            scc_id[w] = scc_count;
                            if w == u {
                                break;
                            }
                        }
                        scc_count += 1;
                    }
                    call_top -= 1;
                    if call_top > 0 {
                        let (parent, _) = call_stack[call_top - 1];
                        if lowlinks[u] < lowlinks[parent] {
                            lowlinks[parent] = lowlinks[u];
                        }
                    }
                }
            }
        }
        v += 1;
    }
    // Unsatisfiable iff x and ¬x are in the same SCC for any variable.
    let mut var = 0u32;
    while var < num_vars {
        let pos = lit_index(var, false);
        let neg = lit_index(var, true);
        if scc_id[pos] == scc_id[neg] {
            return false;
        }
        var += 1;
    }
    true
}

#[inline]
const fn lit_index(var: u32, negated: bool) -> usize {
    let base = (var as usize) * 2;
    if negated {
        base + 1
    } else {
        base
    }
}

/// Horn-SAT decider via unit propagation. Returns `true` iff the clause
/// list is satisfiable.
/// Algorithm: start with all variables false. Repeatedly find a clause
/// whose negative literals are all satisfied but whose positive literal
/// is unassigned/false; set the positive literal true. Fail if a clause
/// with no positive literal has all its negatives satisfied.
/// Bounds (from `reduction:HornSatBound`): up to 256 variables.
const HORN_MAX_VARS: usize = 256;

/// Horn-SAT decision result.
#[must_use]
pub fn decide_horn_sat(clauses: &[&[(u32, bool)]], num_vars: u32) -> bool {
    if (num_vars as usize) > HORN_MAX_VARS {
        return false;
    }
    let mut assignment = [false; HORN_MAX_VARS];
    let n = num_vars as usize;
    loop {
        let mut changed = false;
        for clause in clauses {
            // Count positive literals.
            let mut positive: Option<u32> = None;
            let mut positive_count = 0;
            for (_, negated) in clause.iter() {
                if !*negated {
                    positive_count += 1;
                }
            }
            if positive_count > 1 {
                return false;
            }
            for (var, negated) in clause.iter() {
                if !*negated {
                    positive = Some(*var);
                }
            }
            // Check whether all negative literals are satisfied (var=true).
            let mut all_neg_satisfied = true;
            for (var, negated) in clause.iter() {
                if *negated {
                    let idx = *var as usize;
                    if idx >= n {
                        return false;
                    }
                    if !assignment[idx] {
                        all_neg_satisfied = false;
                        break;
                    }
                }
            }
            if all_neg_satisfied {
                match positive {
                    None => return false,
                    Some(v) => {
                        let idx = v as usize;
                        if idx >= n {
                            return false;
                        }
                        if !assignment[idx] {
                            assignment[idx] = true;
                            changed = true;
                        }
                    }
                }
            }
        }
        if !changed {
            break;
        }
    }
    // Final verification pass.
    for clause in clauses {
        let mut satisfied = false;
        for (var, negated) in clause.iter() {
            let idx = *var as usize;
            if idx >= n {
                return false;
            }
            let val = assignment[idx];
            if (*negated && !val) || (!*negated && val) {
                satisfied = true;
                break;
            }
        }
        if !satisfied {
            return false;
        }
    }
    true
}

/// `BudgetSolvencyCheck` (preflightOrder 0): `thermodynamicBudget` must be
/// ≥ `bitsWidth(unitWittLevel) × ln 2` per `op:GS_7` / `op:OA_5`.
/// Takes the budget in `k_B T · ln 2` units and the target Witt level in
/// bit-width. Returns `Ok(())` if solvent, `Err` with the shape violation.
pub fn preflight_budget_solvency(budget_units: u64, witt_bits: u32) -> Result<(), ShapeViolation> {
    // Landauer bound: one bit requires k_B T · ln 2. Integer form.
    let minimum = witt_bits as u64;
    if budget_units >= minimum {
        Ok(())
    } else {
        Err(ShapeViolation {
            shape_iri: "https://uor.foundation/conformance/CompileUnitShape",
            constraint_iri:
                "https://uor.foundation/conformance/compileUnit_thermodynamicBudget_constraint",
            property_iri: "https://uor.foundation/reduction/thermodynamicBudget",
            expected_range: "http://www.w3.org/2001/XMLSchema#decimal",
            min_count: 1,
            max_count: 1,
            kind: ViolationKind::ValueCheck,
        })
    }
}

/// v0.2.2 Phase F: upper bound on `CarryDepthObservable` depth arguments.
/// Matches target §4.5's Witt-level tower ceiling (W16384).
pub const WITT_MAX_BITS: u16 = 16_384;

/// v0.2.2 Phase F: ASCII parser for a single unsigned decimal `u32`.
/// Returns 0 on malformed input; the caller's downstream comparison (`depth <= WITT_MAX_BITS`)
/// accepts 0 as the pass-through degenerate depth, so malformed input is rejected
/// by the enclosing feasibility check only if the parsed value exceeds the cap.
/// For stricter input discipline, the caller pre-validates `args_repr` at builder time.
#[must_use]
pub fn parse_u32(s: &str) -> u32 {
    let bytes = s.as_bytes();
    let mut out: u32 = 0;
    let mut i = 0;
    while i < bytes.len() {
        let b = bytes[i];
        if !b.is_ascii_digit() {
            return 0;
        }
        out = out.saturating_mul(10).saturating_add((b - b'0') as u32);
        i += 1;
    }
    out
}

/// v0.2.2 Phase F: ASCII parser for a single unsigned decimal `u64`.
#[must_use]
pub fn parse_u64(s: &str) -> u64 {
    let bytes = s.as_bytes();
    let mut out: u64 = 0;
    let mut i = 0;
    while i < bytes.len() {
        let b = bytes[i];
        if !b.is_ascii_digit() {
            return 0;
        }
        out = out.saturating_mul(10).saturating_add((b - b'0') as u64);
        i += 1;
    }
    out
}

/// v0.2.2 Phase F: parser for `"modulus|residue"` decimal pairs.
/// Split on the first ASCII `|`; ASCII-digit-parse each half via `parse_u64`.
#[must_use]
pub fn parse_u64_pair(s: &str) -> (u64, u64) {
    let bytes = s.as_bytes();
    let mut split = bytes.len();
    let mut i = 0;
    while i < bytes.len() {
        if bytes[i] == b'|' {
            split = i;
            break;
        }
        i += 1;
    }
    if split >= bytes.len() {
        return (0, 0);
    }
    let (left, right_with_pipe) = s.split_at(split);
    let (_, right) = right_with_pipe.split_at(1);
    (parse_u64(left), parse_u64(right))
}

/// v0.2.2 Phase F / Phase 9: parse a decimal `u64` representing an
/// IEEE-754 bit pattern. The bit pattern is content-deterministic; call sites
/// project to `H::Decimal` via `DecimalTranscendental::from_bits`.
#[must_use]
pub fn parse_u64_bits_str(s: &str) -> u64 {
    parse_u64(s)
}

/// v0.2.2 Phase F: dispatch a `ConstraintRef::Bound` arm on its `observable_iri`.
/// Canonical observables: `ValueModObservable`, `CarryDepthObservable`, `LandauerCost`.
/// Unknown IRIs are rejected so that an unaudited observable cannot be threaded
/// through the preflight surface silently.
fn check_bound_feasibility(
    observable_iri: &'static str,
    bound_shape_iri: &'static str,
    args_repr: &'static str,
) -> Result<(), ShapeViolation> {
    const VALUE_MOD_IRI: &str = "https://uor.foundation/observable/ValueModObservable";
    const CARRY_DEPTH_IRI: &str = "https://uor.foundation/observable/CarryDepthObservable";
    const LANDAUER_IRI: &str = "https://uor.foundation/observable/LandauerCost";
    let ok = if crate::enforcement::str_eq(observable_iri, VALUE_MOD_IRI) {
        let (modulus, residue) = parse_u64_pair(args_repr);
        modulus != 0 && residue < modulus
    } else if crate::enforcement::str_eq(observable_iri, CARRY_DEPTH_IRI) {
        let depth = parse_u32(args_repr);
        depth <= WITT_MAX_BITS as u32
    } else if crate::enforcement::str_eq(observable_iri, LANDAUER_IRI) {
        // Project the bit pattern to f64 (default-host) for the
        // finite/positive-nats sanity check. Polymorphic consumers
        // construct their own H::Decimal via DecimalTranscendental.
        let bits = parse_u64_bits_str(args_repr);
        let nats = <f64 as crate::DecimalTranscendental>::from_bits(bits);
        nats.is_finite() && nats > 0.0
    } else {
        false
    };
    if ok {
        Ok(())
    } else {
        Err(ShapeViolation {
            shape_iri: bound_shape_iri,
            constraint_iri: "https://uor.foundation/type/BoundConstraint",
            property_iri: observable_iri,
            expected_range: "https://uor.foundation/observable/BaseMetric",
            min_count: 1,
            max_count: 1,
            kind: ViolationKind::ValueCheck,
        })
    }
}

/// `FeasibilityCheck`: verify the constraint system isn't trivially
/// infeasible. Workstream E (target §1.5 + §4.7, v0.2.2 closure):
/// the closed six-kind constraint set is validated by direct per-kind
/// satisfiability checks; any variant that fails is rejected here so
/// downstream resolvers never see an unsatisfiable constraint system.
/// v0.2.2 Phase F: the `Bound` arm dispatches on `observable_iri` to per-observable
/// checks via `check_bound_feasibility`; `Carry` and `Site` remain `Ok(())` by
/// documented design — their constraint semantics are structural invariants of
/// ring arithmetic and site-index bounds respectively, enforced by construction
/// rather than by runtime feasibility checks.
pub fn preflight_feasibility(constraints: &[ConstraintRef]) -> Result<(), ShapeViolation> {
    for c in constraints {
        // v0.2.2 Phase F: Bound dispatches to observable-specific checks with its
        // own bound_shape_iri; early-return with that shape on failure.
        if let ConstraintRef::Bound {
            observable_iri,
            bound_shape_iri,
            args_repr,
        } = c
        {
            check_bound_feasibility(observable_iri, bound_shape_iri, args_repr)?;
            continue;
        }
        let ok = match c {
            ConstraintRef::SatClauses { clauses, num_vars } => *num_vars != 0 || clauses.is_empty(),
            ConstraintRef::Residue { modulus, residue } => *modulus != 0 && *residue < *modulus,
            // Structural invariant of ring arithmetic — carries cannot contradict by construction.
            ConstraintRef::Carry { .. } => true,
            ConstraintRef::Depth { min, max } => min <= max,
            ConstraintRef::Hamming { bound } => *bound <= 32_768,
            // Structural invariant of site indexing — bounds enforced by SITE_COUNT typing.
            ConstraintRef::Site { .. } => true,
            ConstraintRef::Affine {
                coefficients,
                coefficient_count,
                bias,
            } => {
                let count = *coefficient_count as usize;
                if count == 0 {
                    false
                } else {
                    let mut ok_coeff = true;
                    let mut idx = 0;
                    while idx < count && idx < AFFINE_MAX_COEFFS {
                        if coefficients[idx] == i64::MIN {
                            ok_coeff = false;
                            break;
                        }
                        idx += 1;
                    }
                    ok_coeff && is_affine_consistent(coefficients, *coefficient_count, *bias)
                }
            }
            // Handled above via early `if let`; unreachable here.
            ConstraintRef::Bound { .. } => true,
            ConstraintRef::Conjunction {
                conjuncts,
                conjunct_count,
            } => conjunction_all_sat(conjuncts, *conjunct_count),
            // ADR-057: Recurse defers to runtime ψ_1 NerveResolver
            // via the shape-IRI registry. Preflight feasibility
            // accepts on non-empty shape_iri; the registry lookup
            // happens at runtime admission.
            ConstraintRef::Recurse { shape_iri, .. } => !shape_iri.is_empty(),
        };
        if !ok {
            return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/conformance/CompileUnitShape",
                constraint_iri:
                    "https://uor.foundation/conformance/compileUnit_rootTerm_constraint",
                property_iri: "https://uor.foundation/reduction/rootTerm",
                expected_range: "https://uor.foundation/schema/Term",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::ValueCheck,
            });
        }
    }
    Ok(())
}

/// `DispatchCoverageCheck`: verify the inhabitance dispatch table covers the input.
/// The table is exhaustive by construction: Rule 3 (IsResidualFragment) is the catch-all.
pub fn preflight_dispatch_coverage() -> Result<(), ShapeViolation> {
    // Always covered: IsResidualFragment catches everything not in 2-SAT/Horn.
    Ok(())
}

/// `PackageCoherenceCheck`: verify each site's constraints are internally consistent.
pub fn preflight_package_coherence(constraints: &[ConstraintRef]) -> Result<(), ShapeViolation> {
    // Check residue constraints don't contradict (same modulus, different residues).
    let mut i = 0;
    while i < constraints.len() {
        if let ConstraintRef::Residue {
            modulus: m1,
            residue: r1,
        } = constraints[i]
        {
            let mut j = i + 1;
            while j < constraints.len() {
                if let ConstraintRef::Residue {
                    modulus: m2,
                    residue: r2,
                } = constraints[j]
                {
                    if m1 == m2 && r1 != r2 {
                        return Err(ShapeViolation {
                            shape_iri: "https://uor.foundation/conformance/CompileUnitShape",
                            constraint_iri:
                                "https://uor.foundation/conformance/compileUnit_rootTerm_constraint",
                            property_iri: "https://uor.foundation/reduction/rootTerm",
                            expected_range: "https://uor.foundation/schema/Term",
                            min_count: 1,
                            max_count: 1,
                            kind: ViolationKind::ValueCheck,
                        });
                    }
                }
                j += 1;
            }
        }
        i += 1;
    }
    Ok(())
}

/// v0.2.2 Phase B: a-priori `UorTime` estimator for preflight timing.
/// Derives a content-deterministic upper bound on the `UorTime` a reduction
/// over `shape` at `witt_bits` will consume, without a physical clock. The
/// bound is `witt_bits × constraint_count` rewrite steps and the matching
/// Landauer nats at `ln 2` per step. Preflight compares this via
/// [`UorTime::min_wall_clock`](crate::enforcement::UorTime::min_wall_clock) against the policy's Nanos budget — no
/// physical clock is consulted.
#[must_use]
pub fn estimate_preflight_uor_time<T: ConstrainedTypeShape + ?Sized>(
    witt_bits: u16,
) -> crate::enforcement::UorTime {
    let steps = (witt_bits as u64).saturating_mul((T::CONSTRAINTS.len() as u64).max(1));
    let nats = (steps as f64) * core::f64::consts::LN_2;
    crate::enforcement::UorTime::new(crate::enforcement::LandauerBudget::new(nats), steps)
}

/// `PreflightTiming`: timing-check preflight. v0.2.2 Phase B: parameterized over
/// a [`TimingPolicy`] carrying the Nanos budget and canonical `Calibration`.
/// The `expected` UorTime is derived a-priori from input shape via
/// [`estimate_preflight_uor_time`] — content-deterministic, no physical
/// clock consulted. Rejects when the Nanos lower bound exceeds the budget.
/// # Errors
/// Returns `ShapeViolation::ValueCheck` when the expected UorTime, converted
/// to Nanos under `P::CALIBRATION`, exceeds `P::PREFLIGHT_BUDGET_NS`.
#[allow(dead_code)]
pub(crate) const CANONICAL_PREFLIGHT_BUDGET_NS: u64 = 10000000;
pub fn preflight_timing<P: crate::enforcement::TimingPolicy>(
    expected: crate::enforcement::UorTime,
) -> Result<(), ShapeViolation> {
    let nanos = expected.min_wall_clock(P::CALIBRATION).as_u64();
    if nanos <= P::PREFLIGHT_BUDGET_NS {
        Ok(())
    } else {
        Err(ShapeViolation {
            shape_iri: "https://uor.foundation/conformance/CompileUnitShape",
            constraint_iri: "https://uor.foundation/reduction/PreflightTimingBound",
            property_iri: "https://uor.foundation/reduction/preflightBudgetNs",
            expected_range: "http://www.w3.org/2001/XMLSchema#nonNegativeInteger",
            min_count: 1,
            max_count: 1,
            kind: ViolationKind::ValueCheck,
        })
    }
}

/// `RuntimeTiming`: runtime timing-check preflight. v0.2.2 Phase B: parameterized
/// over a [`TimingPolicy`] carrying the Nanos budget and canonical `Calibration`.
/// Identical comparison shape as [`preflight_timing`], against the runtime budget.
/// # Errors
/// Returns `ShapeViolation::ValueCheck` when the expected UorTime, converted
/// to Nanos under `P::CALIBRATION`, exceeds `P::RUNTIME_BUDGET_NS`.
#[allow(dead_code)]
pub(crate) const CANONICAL_RUNTIME_BUDGET_NS: u64 = 10000000;
pub fn runtime_timing<P: crate::enforcement::TimingPolicy>(
    expected: crate::enforcement::UorTime,
) -> Result<(), ShapeViolation> {
    let nanos = expected.min_wall_clock(P::CALIBRATION).as_u64();
    if nanos <= P::RUNTIME_BUDGET_NS {
        Ok(())
    } else {
        Err(ShapeViolation {
            shape_iri: "https://uor.foundation/conformance/CompileUnitShape",
            constraint_iri: "https://uor.foundation/reduction/RuntimeTimingBound",
            property_iri: "https://uor.foundation/reduction/runtimeBudgetNs",
            expected_range: "http://www.w3.org/2001/XMLSchema#nonNegativeInteger",
            min_count: 1,
            max_count: 1,
            kind: ViolationKind::ValueCheck,
        })
    }
}

/// Reduction stage executor. Takes a classified input and runs the 7 stages
/// in order, producing a `StageOutcome` on success.
#[derive(Debug, Clone, Copy)]
pub struct StageOutcome {
    /// Witt level the compile unit was resolved at.
    pub witt_bits: u16,
    /// Fragment classification decided at `stage_resolve`.
    pub fragment: FragmentKind,
    /// Whether the input is satisfiable (carrier non-empty).
    pub satisfiable: bool,
}

/// Run the 7 reduction stages on a constrained-type input.
///
/// v0.2.2 T6.14: the `unit_address` field was removed. The substrate-
/// computed `ContentAddress` lives on `Grounded` and is derived at the
/// caller from the `H: Hasher` output buffer, not inside this stage
/// executor.
///
/// # Errors
///
/// Returns `PipelineFailure` with the `reduction:PipelineFailureReason` IRI
/// of whichever stage rejected the input.
pub fn run_reduction_stages<T: ConstrainedTypeShape + ?Sized>(
    witt_bits: u16,
) -> Result<StageOutcome, PipelineFailure> {
    // Stage 0 (initialization): content-addressed unit-id is computed by
    // the caller via the consumer-supplied substrate Hasher; nothing to
    // do here.
    // Stage 1 (declare): no-op; declarations already captured by the derive macro.
    // Stage 2 (factorize): no-op; ring factorization is not required for Boolean fragments.
    // Stage 3 (resolve): fragment classification.
    let fragment = fragment_classify(T::CONSTRAINTS);
    // Stage 4 (attest): run the decider associated with the fragment.
    let satisfiable = match fragment {
        FragmentKind::TwoSat => {
            let mut sat = true;
            for c in T::CONSTRAINTS {
                if let ConstraintRef::SatClauses { clauses, num_vars } = c {
                    sat = decide_two_sat(clauses, *num_vars);
                    break;
                }
            }
            sat
        }
        FragmentKind::Horn => {
            let mut sat = true;
            for c in T::CONSTRAINTS {
                if let ConstraintRef::SatClauses { clauses, num_vars } = c {
                    sat = decide_horn_sat(clauses, *num_vars);
                    break;
                }
            }
            sat
        }
        FragmentKind::Residual => {
            // No polynomial decider available. Residual constraint systems are
            // treated as vacuously satisfiable when they carry no SatClauses —
            // pure residue/hamming/etc. inputs always have some value satisfying
            // at least the trivial case. Non-trivial residuals yield
            // ConvergenceStall at stage_convergence below.
            let mut has_sat_clauses = false;
            for c in T::CONSTRAINTS {
                if matches!(c, ConstraintRef::SatClauses { .. }) {
                    has_sat_clauses = true;
                    break;
                }
            }
            !has_sat_clauses
        }
    };
    if matches!(fragment, FragmentKind::Residual) && !satisfiable {
        return Err(PipelineFailure::ConvergenceStall {
            stage_iri: "https://uor.foundation/reduction/stage_convergence",
            angle_milliradians: 0,
        });
    }
    // Stage 5 (extract): ConstrainedTypeShape inputs carry no term AST, so no
    // bindings flow through this path. CompileUnit-bearing callers retrieve the
    // declared bindings directly via `unit.bindings()` (Phase H1); runtime
    // `BindingsTable` materialization is not possible because `BindingsTable::entries`
    // is `&'static [BindingEntry]` by contract (compile-time-constructed catalogs
    // are the sole source of sorted-address binary-search tables).
    // Stage 6 (convergence): verify fixpoint reached. Trivially true for
    // classified fragments.
    Ok(StageOutcome {
        witt_bits,
        fragment,
        satisfiable,
    })
}

/// Run the `TowerCompletenessResolver` pipeline on a `ConstrainedTypeShape`
/// input at the requested Witt level. Emits a `LiftChainCertificate` on
/// success or a generic `ImpossibilityWitness` on failure.
/// # Errors
/// Returns `GenericImpossibilityWitness` when the input is unsatisfiable or
/// when any preflight / reduction stage rejects it.
pub fn run_tower_completeness<T: ConstrainedTypeShape + ?Sized, H: crate::enforcement::Hasher>(
    _input: &T,
    level: WittLevel,
) -> Result<Validated<LiftChainCertificate>, GenericImpossibilityWitness> {
    let witt_bits = level.witt_length() as u16;
    preflight_budget_solvency(witt_bits as u64, witt_bits as u32)
        .map_err(|_| GenericImpossibilityWitness::default())?;
    preflight_feasibility(T::CONSTRAINTS).map_err(|_| GenericImpossibilityWitness::default())?;
    preflight_package_coherence(T::CONSTRAINTS)
        .map_err(|_| GenericImpossibilityWitness::default())?;
    preflight_dispatch_coverage().map_err(|_| GenericImpossibilityWitness::default())?;
    let expected = estimate_preflight_uor_time::<T>(witt_bits);
    preflight_timing::<crate::enforcement::CanonicalTimingPolicy>(expected)
        .map_err(|_| GenericImpossibilityWitness::default())?;
    runtime_timing::<crate::enforcement::CanonicalTimingPolicy>(expected)
        .map_err(|_| GenericImpossibilityWitness::default())?;
    let outcome =
        run_reduction_stages::<T>(witt_bits).map_err(|_| GenericImpossibilityWitness::default())?;
    if outcome.satisfiable {
        // v0.2.2 T6.7: thread H: Hasher through fold_unit_digest to compute
        // a real substrate fingerprint. Witt level + budget=0 (no CompileUnit).
        let mut hasher = H::initial();
        hasher = crate::enforcement::fold_unit_digest(
            hasher,
            outcome.witt_bits,
            0,
            T::IRI,
            T::SITE_COUNT,
            T::CONSTRAINTS,
            crate::enforcement::CertificateKind::TowerCompleteness,
        );
        let buffer = hasher.finalize();
        let fp = crate::enforcement::ContentFingerprint::from_buffer(buffer, H::OUTPUT_BYTES as u8);
        let cert = LiftChainCertificate::with_level_and_fingerprint_const(outcome.witt_bits, fp);
        Ok(Validated::new(cert))
    } else {
        Err(GenericImpossibilityWitness::default())
    }
}

/// Workstream F (target ontology: `resolver:IncrementalCompletenessResolver`):
/// sealed `SpectralSequencePage` kernel type recording one step of the
/// `Q_n → Q_{n+1}` spectral-sequence walk. Each page carries its index,
/// the from/to Witt bit widths, and the differential-vanished flag
/// (true ⇒ page is trivial; false ⇒ obstruction present with class IRI).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct SpectralSequencePage {
    page_index: u32,
    source_bits: u16,
    target_bits: u16,
    differential_vanished: bool,
    obstruction_class_iri: &'static str,
    _sealed: (),
}

impl SpectralSequencePage {
    /// Crate-internal constructor. Minted only by the incremental walker.
    #[inline]
    #[must_use]
    pub(crate) const fn from_parts(
        page_index: u32,
        source_bits: u16,
        target_bits: u16,
        differential_vanished: bool,
        obstruction_class_iri: &'static str,
    ) -> Self {
        Self {
            page_index,
            source_bits,
            target_bits,
            differential_vanished,
            obstruction_class_iri,
            _sealed: (),
        }
    }

    /// Page index (0, 1, 2, …) along the spectral-sequence walk.
    #[inline]
    #[must_use]
    pub const fn page_index(&self) -> u32 {
        self.page_index
    }

    /// Witt bit width at the page's source level.
    #[inline]
    #[must_use]
    pub const fn source_bits(&self) -> u16 {
        self.source_bits
    }

    /// Witt bit width at the page's target level.
    #[inline]
    #[must_use]
    pub const fn target_bits(&self) -> u16 {
        self.target_bits
    }

    /// True iff the page's differential vanishes (no obstruction).
    #[inline]
    #[must_use]
    pub const fn differential_vanished(&self) -> bool {
        self.differential_vanished
    }

    /// Obstruction class IRI when the differential is non-trivial;
    /// empty string when the page is trivial.
    #[inline]
    #[must_use]
    pub const fn obstruction_class_iri(&self) -> &'static str {
        self.obstruction_class_iri
    }
}

/// Run the `IncrementalCompletenessResolver` (spectral-sequence walk)
/// at `target_level`.
///
/// Per `spec/src/namespaces/resolver.rs` (`IncrementalCompletenessResolver`),
/// the walk proceeds without re-running the full ψ-pipeline from
/// scratch. Workstream F (v0.2.2 closure) implements the canonical page
/// structure: iterate each `Q_n → Q_{n+1}` step from `W8` up to
/// `target_level`, compute each page's differential via
/// `run_reduction_stages` at the higher level, and record the
/// `SpectralSequencePage`. A non-vanishing differential halts with a
/// `GenericImpossibilityWitness` whose obstruction-class IRI is
/// `https://uor.foundation/type/LiftObstruction`. All trivial pages
/// produce a `LiftChainCertificate` stamped with
/// `CertificateKind::IncrementalCompleteness`, discriminable from
/// `run_tower_completeness`'s certificate by the kind byte.
///
/// # Errors
///
/// Returns `GenericImpossibilityWitness` when any page's differential
/// does not vanish, or when preflight checks reject the input.
pub fn run_incremental_completeness<
    T: ConstrainedTypeShape + ?Sized,
    H: crate::enforcement::Hasher,
>(
    _input: &T,
    target_level: WittLevel,
) -> Result<Validated<LiftChainCertificate>, GenericImpossibilityWitness> {
    let target_bits = target_level.witt_length() as u16;
    preflight_budget_solvency(target_bits as u64, target_bits as u32)
        .map_err(|_| GenericImpossibilityWitness::default())?;
    preflight_feasibility(T::CONSTRAINTS).map_err(|_| GenericImpossibilityWitness::default())?;
    preflight_package_coherence(T::CONSTRAINTS)
        .map_err(|_| GenericImpossibilityWitness::default())?;
    preflight_dispatch_coverage().map_err(|_| GenericImpossibilityWitness::default())?;
    let expected = estimate_preflight_uor_time::<T>(target_bits);
    preflight_timing::<crate::enforcement::CanonicalTimingPolicy>(expected)
        .map_err(|_| GenericImpossibilityWitness::default())?;
    runtime_timing::<crate::enforcement::CanonicalTimingPolicy>(expected)
        .map_err(|_| GenericImpossibilityWitness::default())?;

    // v0.2.2 Phase H4: Betti-driven spectral-sequence walk. At each page, compute
    // the constraint-nerve Betti tuple (via primitive_simplicial_nerve_betti)
    // and run reduction at both source and target levels. The differential at
    // page r with bidegree (p, q) vanishes iff the bidegree-q projection
    // `betti[q]` is unchanged between source and target AND both reductions
    // are satisfiable at their levels. A mismatch in any bidegree or a
    // non-satisfiable reduction produces a non-trivial differential →
    // `LiftObstruction` halt with `GenericImpossibilityWitness`.
    //
    // Betti-threading also produces content-distinct fingerprints for distinct
    // constraint topologies: two input shapes with different Betti profiles will
    // produce different certs even if both satisfy at every level.
    let betti = crate::enforcement::primitive_simplicial_nerve_betti::<T>()?;
    let mut page_index: u32 = 0;
    let mut from_bits: u16 = 8;
    let mut pages_hasher = H::initial();
    while from_bits < target_bits {
        let to_bits = if from_bits + 8 > target_bits {
            target_bits
        } else {
            from_bits + 8
        };
        // Reduce at source and target; both must be satisfiable for the
        // differential to have a chance of vanishing.
        let outcome_source = run_reduction_stages::<T>(from_bits)
            .map_err(|_| GenericImpossibilityWitness::default())?;
        let outcome_target = run_reduction_stages::<T>(to_bits)
            .map_err(|_| GenericImpossibilityWitness::default())?;
        // bidegree q = page_index + 1 (first non-trivial homological degree per page).
        let q: usize = ((page_index as usize) + 1).min(crate::enforcement::MAX_BETTI_DIMENSION - 1);
        let betti_q = betti[q];
        // Differential vanishes iff source ≡ target in Betti bidegree q
        // AND both reduction levels are satisfiable. Betti is shape-invariant
        // (level-independent); the bidegree check is trivially equal, but the
        // satisfiability conjunction captures the level-specific obstruction.
        let differential_vanishes = outcome_source.satisfiable && outcome_target.satisfiable;
        let page = SpectralSequencePage::from_parts(
            page_index,
            from_bits,
            to_bits,
            differential_vanishes,
            if differential_vanishes {
                ""
            } else {
                "https://uor.foundation/type/LiftObstruction"
            },
        );
        if !page.differential_vanished() {
            return Err(GenericImpossibilityWitness::default());
        }
        // Fold the per-page Betti/satisfiability contribution so distinct
        // constraint shapes yield distinct incremental-completeness certs.
        pages_hasher = pages_hasher.fold_bytes(&page_index.to_be_bytes());
        pages_hasher = pages_hasher.fold_bytes(&from_bits.to_be_bytes());
        pages_hasher = pages_hasher.fold_bytes(&to_bits.to_be_bytes());
        pages_hasher = pages_hasher.fold_bytes(&betti_q.to_be_bytes());
        page_index += 1;
        from_bits = to_bits;
    }
    // The accumulated pages_hasher is currently unused in the final fold;
    // the Betti primitive's full tuple is folded below via fold_betti_tuple
    // to keep the cert content-addressed over the whole spectral walk.
    let _ = pages_hasher;

    // Final reduction at the target level — the walk converges when
    // every page's differential has vanished; this guarantees the
    // target-level outcome is satisfiable.
    let outcome = run_reduction_stages::<T>(target_bits)
        .map_err(|_| GenericImpossibilityWitness::default())?;
    if !outcome.satisfiable {
        return Err(GenericImpossibilityWitness::default());
    }
    // v0.2.2 Phase H4: fold the Betti tuple into the cert alongside the
    // canonical unit digest so distinct constraint topologies produce distinct
    // incremental-completeness fingerprints.
    let mut hasher = H::initial();
    hasher = crate::enforcement::fold_betti_tuple(hasher, &betti);
    hasher = crate::enforcement::fold_unit_digest(
        hasher,
        outcome.witt_bits,
        page_index as u64,
        T::IRI,
        T::SITE_COUNT,
        T::CONSTRAINTS,
        crate::enforcement::CertificateKind::IncrementalCompleteness,
    );
    let buffer = hasher.finalize();
    let fp = crate::enforcement::ContentFingerprint::from_buffer(buffer, H::OUTPUT_BYTES as u8);
    let cert = LiftChainCertificate::with_level_and_fingerprint_const(outcome.witt_bits, fp);
    Ok(Validated::new(cert))
}

/// Run the `GroundingAwareResolver` on a `CompileUnit` input at `level`,
/// exploiting `state:GroundedContext` bindings for O(1) resolution per
/// `op:GS_5`.
///
/// v0.2.2 Phase H2: walks `unit.root_term()` enumerating every
/// `Term::Variable { name_index }` and resolves each via linear search
/// over `unit.bindings()`. Unresolved variables (declared in the term AST
/// but absent from the bindings slice) trigger a `GenericImpossibilityWitness`
/// corresponding to `SC5_UNBOUND_VARIABLE`. Resolved bindings are folded
/// into the fingerprint via `primitive_session_binding_signature` so the
/// cert content-addresses the full grounding context, not just the unit
/// shape — distinct binding sets yield distinct fingerprints.
///
/// # Errors
///
/// Returns `GenericImpossibilityWitness` on grounding failure: unresolved
/// variables, or any variable reference whose name index is absent from
/// `unit.bindings()`.
pub fn run_grounding_aware<H: crate::enforcement::Hasher>(
    unit: &CompileUnit,
    level: WittLevel,
) -> Result<Validated<GroundingCertificate>, GenericImpossibilityWitness> {
    let witt_bits = level.witt_length() as u16;
    // v0.2.2 Phase H2: walk root_term enumerating Term::Variable name_indices,
    // linear-search unit.bindings() for each, reject unresolved variables.
    let root_term = unit.root_term();
    let bindings = unit.bindings();
    let mut ti = 0;
    while ti < root_term.len() {
        if let crate::enforcement::Term::Variable { name_index } = root_term[ti] {
            let mut found = false;
            let mut bi = 0;
            while bi < bindings.len() {
                if bindings[bi].name_index == name_index {
                    found = true;
                    break;
                }
                bi += 1;
            }
            if !found {
                // SC_5 violation: variable referenced but no matching binding.
                return Err(GenericImpossibilityWitness::default());
            }
        }
        ti += 1;
    }
    // Fold: witt_bits / thermodynamic_budget / result_type_iri / session_signature / Grounding kind.
    let mut hasher = H::initial();
    hasher = hasher.fold_bytes(&witt_bits.to_be_bytes());
    hasher = hasher.fold_bytes(&unit.thermodynamic_budget().to_be_bytes());
    hasher = hasher.fold_bytes(unit.result_type_iri().as_bytes());
    hasher = hasher.fold_byte(0);
    let (binding_count, fold_addr) =
        crate::enforcement::primitive_session_binding_signature(bindings);
    hasher = crate::enforcement::fold_session_signature(hasher, binding_count, fold_addr);
    hasher = hasher.fold_byte(crate::enforcement::certificate_kind_discriminant(
        crate::enforcement::CertificateKind::Grounding,
    ));
    let buffer = hasher.finalize();
    let fp = crate::enforcement::ContentFingerprint::from_buffer(buffer, H::OUTPUT_BYTES as u8);
    let cert = GroundingCertificate::with_level_and_fingerprint_const(witt_bits, fp);
    Ok(Validated::new(cert))
}

/// Run the `InhabitanceResolver` dispatch on a `ConstrainedTypeShape`
/// input at `level`.
///
/// Routes to the 2-SAT / Horn-SAT / residual decider via
/// `predicate:InhabitanceDispatchTable` rules (ordered by priority).
///
/// # Errors
///
/// Returns `InhabitanceImpossibilityWitness` when the input is unsatisfiable.
pub fn run_inhabitance<T: ConstrainedTypeShape + ?Sized, H: crate::enforcement::Hasher>(
    _input: &T,
    level: WittLevel,
) -> Result<Validated<InhabitanceCertificate>, InhabitanceImpossibilityWitness> {
    let witt_bits = level.witt_length() as u16;
    preflight_budget_solvency(witt_bits as u64, witt_bits as u32)
        .map_err(|_| InhabitanceImpossibilityWitness::default())?;
    preflight_feasibility(T::CONSTRAINTS)
        .map_err(|_| InhabitanceImpossibilityWitness::default())?;
    preflight_package_coherence(T::CONSTRAINTS)
        .map_err(|_| InhabitanceImpossibilityWitness::default())?;
    preflight_dispatch_coverage().map_err(|_| InhabitanceImpossibilityWitness::default())?;
    let expected = estimate_preflight_uor_time::<T>(witt_bits);
    preflight_timing::<crate::enforcement::CanonicalTimingPolicy>(expected)
        .map_err(|_| InhabitanceImpossibilityWitness::default())?;
    runtime_timing::<crate::enforcement::CanonicalTimingPolicy>(expected)
        .map_err(|_| InhabitanceImpossibilityWitness::default())?;
    let outcome = run_reduction_stages::<T>(witt_bits)
        .map_err(|_| InhabitanceImpossibilityWitness::default())?;
    if outcome.satisfiable {
        // v0.2.2 T6.7: thread H: Hasher through fold_unit_digest.
        let mut hasher = H::initial();
        hasher = crate::enforcement::fold_unit_digest(
            hasher,
            outcome.witt_bits,
            0,
            T::IRI,
            T::SITE_COUNT,
            T::CONSTRAINTS,
            crate::enforcement::CertificateKind::Inhabitance,
        );
        let buffer = hasher.finalize();
        let fp = crate::enforcement::ContentFingerprint::from_buffer(buffer, H::OUTPUT_BYTES as u8);
        let cert = InhabitanceCertificate::with_level_and_fingerprint_const(outcome.witt_bits, fp);
        Ok(Validated::new(cert))
    } else {
        Err(InhabitanceImpossibilityWitness::default())
    }
}

/// v0.2.2 W14: the single typed pipeline entry point producing `Grounded<T>`
/// from a validated `CompileUnit`. The caller declares the expected shape `T`;
/// the pipeline verifies the unit's root term produces a value of that shape
/// and returns `Grounded<T>` on success or a typed `PipelineFailure`.
/// Replaces the v0.2.1 `run_pipeline(&datum, level: u8)` form whose bare
/// integer level argument was never type-safe.
/// # Errors
/// Returns `PipelineFailure` on preflight, reduction, or shape-mismatch failure.
/// # Example
/// ```no_run
/// use uor_foundation::enforcement::{
///     CompileUnitBuilder, ConstrainedTypeInput, Term,
/// };
/// use uor_foundation::pipeline::run;
/// use uor_foundation::{VerificationDomain, WittLevel};
/// # struct Fnv1aHasher16; // downstream substrate; see foundation/examples/custom_hasher_substrate.rs
/// # impl uor_foundation::enforcement::Hasher for Fnv1aHasher16 {
/// #     const OUTPUT_BYTES: usize = 16;
/// #     fn initial() -> Self { Self }
/// #     fn fold_byte(self, _: u8) -> Self { self }
/// #     fn finalize(self) -> [u8; 32] { [0; 32] }
/// # }
/// static TERMS: &[Term] = &[uor_foundation::pipeline::literal_u64(1, WittLevel::W8)];
/// static DOMAINS: &[VerificationDomain] = &[VerificationDomain::Enumerative];
/// let unit = CompileUnitBuilder::new()
///     .root_term(TERMS)
///     .witt_level_ceiling(WittLevel::W32)
///     .thermodynamic_budget(1024)
///     .target_domains(DOMAINS)
///     .result_type::<ConstrainedTypeInput>()
///     .validate()
///     .expect("unit well-formed");
/// let grounded = run::<ConstrainedTypeInput, _, Fnv1aHasher16>(unit)
///     .expect("pipeline admits");
/// # let _ = grounded;
/// ```
pub fn run<T, P, H>(unit: Validated<CompileUnit, P>) -> Result<Grounded<T>, PipelineFailure>
where
    T: ConstrainedTypeShape + crate::enforcement::GroundedShape,
    P: crate::enforcement::ValidationPhase,
    H: crate::enforcement::Hasher,
{
    let witt_bits = unit.inner().witt_level().witt_length() as u16;
    let budget = unit.inner().thermodynamic_budget();
    // v0.2.2 T6.11: ShapeMismatch detection. The unit declares its
    // result_type_iri at validation time; the caller's `T::IRI` must match.
    let unit_iri = unit.inner().result_type_iri();
    if !crate::enforcement::str_eq(unit_iri, T::IRI) {
        return Err(PipelineFailure::ShapeMismatch {
            expected: T::IRI,
            got: unit_iri,
        });
    }
    // Preflights. Each maps its ShapeViolation into a PipelineFailure.
    preflight_budget_solvency(witt_bits as u64, witt_bits as u32)
        .map_err(|report| PipelineFailure::ShapeViolation { report })?;
    preflight_feasibility(T::CONSTRAINTS)
        .map_err(|report| PipelineFailure::ShapeViolation { report })?;
    preflight_package_coherence(T::CONSTRAINTS)
        .map_err(|report| PipelineFailure::ShapeViolation { report })?;
    preflight_dispatch_coverage().map_err(|report| PipelineFailure::ShapeViolation { report })?;
    let expected = estimate_preflight_uor_time::<T>(witt_bits);
    preflight_timing::<crate::enforcement::CanonicalTimingPolicy>(expected)
        .map_err(|report| PipelineFailure::ShapeViolation { report })?;
    runtime_timing::<crate::enforcement::CanonicalTimingPolicy>(expected)
        .map_err(|report| PipelineFailure::ShapeViolation { report })?;
    // v0.2.2 T5 C1: actually call run_reduction_stages and propagate its
    // failure. The previous v0.2.2 path skipped this call entirely,
    // returning a degenerate Grounded with ContentAddress::zero(). The
    // typed `run` entry point now mirrors `run_pipeline`'s reduction-stage
    // sequence.
    let outcome = run_reduction_stages::<T>(witt_bits)?;
    if !outcome.satisfiable {
        return Err(PipelineFailure::ContradictionDetected {
            at_step: 0,
            trace_iri: "https://uor.foundation/trace/InhabitanceSearchTrace",
        });
    }
    // v0.2.2 T5 C3.f: thread the consumer-supplied substrate Hasher through
    // the canonical CompileUnit byte layout to compute the parametric
    // content fingerprint.
    let mut hasher = H::initial();
    hasher = crate::enforcement::fold_unit_digest(
        hasher,
        witt_bits,
        budget,
        T::IRI,
        T::SITE_COUNT,
        T::CONSTRAINTS,
        crate::enforcement::CertificateKind::Grounding,
    );
    let buffer = hasher.finalize();
    let content_fingerprint =
        crate::enforcement::ContentFingerprint::from_buffer(buffer, H::OUTPUT_BYTES as u8);
    let unit_address = crate::enforcement::unit_address_from_buffer(&buffer);
    let grounding = Validated::new(GroundingCertificate::with_level_and_fingerprint_const(
        witt_bits,
        content_fingerprint,
    ));
    let bindings = empty_bindings_table();
    Ok(Grounded::<T>::new_internal(
        grounding,
        bindings,
        outcome.witt_bits,
        unit_address,
        content_fingerprint,
    ))
}

/// Construct an empty `BindingsTable`.
/// v0.2.2 T6.9: the empty slice is vacuously sorted, so direct struct
/// construction is sound. Public callers with non-empty entries go
/// through `BindingsTable::try_new` (validating).
/// # Driver contract
/// Every pipeline driver (`run`, `run_const`, `run_parallel`, `run_stream`,
/// `run_interactive`, `run_inhabitance`) mints `Grounded<T>` with this
/// empty table today: runtime-dynamic binding materialization in
/// `Grounded<T>` requires widening `BindingsTable.entries: &'static [...]`
/// to a non-`'static` carrier (a separate architectural change).
/// Downstream that needs a compile-time binding catalog uses the pattern
/// shown in `foundation/examples/static_bindings_catalog.rs`:
/// `Binding::to_binding_entry()` (const-fn) + `BindingsTable::try_new(&[...])`.
#[must_use]
pub const fn empty_bindings_table() -> BindingsTable {
    BindingsTable { entries: &[] }
}

// Suppress warning: BindingEntry is re-exported via use but not used in
// this module directly; it's part of the public pipeline surface.
#[allow(dead_code)]
const _BINDING_ENTRY_REF: Option<BindingEntry> = None;
// Same for CompletenessCertificate — the pipeline does not mint this subclass
// directly; Phase D resolvers emit the canonical `GroundingCertificate` carrier
// and cert-subclass lifts happen in substrate-specific consumers.
#[allow(dead_code)]
const _COMPLETENESS_CERT_REF: Option<CompletenessCertificate> = None;

/// v0.2.2 Phase F / T2.7: parallel-declaration compile unit. Carries the
/// declared site partition cardinality plus (Phase A widening) the raw
/// partition slice and disjointness-witness IRI from the builder —
/// previously these were discarded at validate-time by a shadowed
/// enforcement-local `ParallelDeclaration` that nothing consumed.
/// v0.2.2 T6.11: also carries `result_type_iri` for ShapeMismatch detection.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct ParallelDeclaration<'a> {
    payload: u64,
    result_type_iri: &'static str,
    /// v0.2.2 Phase A: raw site-partition slice retained from the builder.
    /// Empty slice for declarations built via the site-count-only constructor.
    site_partition: &'a [u32],
    /// v0.2.2 Phase A: disjointness-witness IRI retained from the builder.
    /// Empty string for declarations built via the site-count-only constructor.
    disjointness_witness: &'a str,
    _sealed: (),
}

impl<'a> ParallelDeclaration<'a> {
    /// v0.2.2 Phase H3: construct a parallel declaration carrying the full
    /// partition slice and disjointness-witness IRI from the builder.
    /// This is the sole public constructor; the v0.2.2 Phase A site-count-only
    /// `new::<T>(site_count)` form was deleted in Phase H3 under the "no
    /// compatibility" discipline — every caller supplies a real partition.
    #[inline]
    #[must_use]
    pub const fn new_with_partition<T: ConstrainedTypeShape>(
        site_partition: &'a [u32],
        disjointness_witness: &'a str,
    ) -> Self {
        Self {
            payload: site_partition.len() as u64,
            result_type_iri: T::IRI,
            site_partition,
            disjointness_witness,
            _sealed: (),
        }
    }

    /// Returns the declared site partition cardinality.
    #[inline]
    #[must_use]
    pub const fn site_count(&self) -> u64 {
        self.payload
    }

    /// v0.2.2 T6.11: returns the result-type IRI.
    #[inline]
    #[must_use]
    pub const fn result_type_iri(&self) -> &'static str {
        self.result_type_iri
    }

    /// v0.2.2 Phase A: returns the raw site-partition slice.
    #[inline]
    #[must_use]
    pub const fn site_partition(&self) -> &'a [u32] {
        self.site_partition
    }

    /// v0.2.2 Phase A: returns the disjointness-witness IRI.
    #[inline]
    #[must_use]
    pub const fn disjointness_witness(&self) -> &'a str {
        self.disjointness_witness
    }
}

/// v0.2.2 Phase F / T2.7: stream-declaration compile unit. Carries a
/// payload field encoding the productivity-witness countdown.
/// v0.2.2 T6.11: also carries `result_type_iri` for ShapeMismatch detection.
/// v0.2.2 Phase A: also retains the builder's seed/step term slices and
/// the productivity-witness IRI so stream resolvers can walk declared
/// structure. Distinct from the enforcement-local `StreamDeclaration`
/// which records only the `StreamShape` validation surface.
/// Note: `Hash` is not derived because `Term` does not implement `Hash`;
/// downstream code that needs deterministic hashing should fold through
/// the substrate `Hasher` via the pipeline's `fold_stream_digest`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct StreamDeclaration<'a> {
    payload: u64,
    result_type_iri: &'static str,
    /// v0.2.2 Phase A: stream seed term slice retained from the builder.
    seed: &'a [Term],
    /// v0.2.2 Phase A: stream step term slice retained from the builder.
    step: &'a [Term],
    /// v0.2.2 Phase A: productivity-witness IRI retained from the builder.
    productivity_witness: &'a str,
    _sealed: (),
}

impl<'a> StreamDeclaration<'a> {
    /// v0.2.2 T6.11: construct a stream declaration with the given productivity
    /// bound and result type. Phase A: leaves seed/step/witness empty; use
    /// `new_full` to retain the full structure.
    #[inline]
    #[must_use]
    pub const fn new<T: ConstrainedTypeShape>(
        productivity_bound: u64,
    ) -> StreamDeclaration<'static> {
        StreamDeclaration {
            payload: productivity_bound,
            result_type_iri: T::IRI,
            seed: &[],
            step: &[],
            productivity_witness: "",
            _sealed: (),
        }
    }

    /// v0.2.2 Phase A: construct a stream declaration carrying the full
    /// seed/step/witness structure from the builder.
    #[inline]
    #[must_use]
    pub const fn new_full<T: ConstrainedTypeShape>(
        productivity_bound: u64,
        seed: &'a [Term],
        step: &'a [Term],
        productivity_witness: &'a str,
    ) -> Self {
        Self {
            payload: productivity_bound,
            result_type_iri: T::IRI,
            seed,
            step,
            productivity_witness,
            _sealed: (),
        }
    }

    /// Returns the declared productivity bound.
    #[inline]
    #[must_use]
    pub const fn productivity_bound(&self) -> u64 {
        self.payload
    }

    /// v0.2.2 T6.11: returns the result-type IRI.
    #[inline]
    #[must_use]
    pub const fn result_type_iri(&self) -> &'static str {
        self.result_type_iri
    }

    /// v0.2.2 Phase A: returns the seed term slice.
    #[inline]
    #[must_use]
    pub const fn seed(&self) -> &'a [Term] {
        self.seed
    }

    /// v0.2.2 Phase A: returns the step term slice.
    #[inline]
    #[must_use]
    pub const fn step(&self) -> &'a [Term] {
        self.step
    }

    /// v0.2.2 Phase A: returns the productivity-witness IRI.
    #[inline]
    #[must_use]
    pub const fn productivity_witness(&self) -> &'a str {
        self.productivity_witness
    }
}

/// v0.2.2 Phase F / T2.7: interaction-declaration compile unit. Carries a
/// payload field encoding the convergence-predicate seed.
/// v0.2.2 T6.11: also carries `result_type_iri` for ShapeMismatch detection.
/// v0.2.2 Phase A: lifetime-parameterized for consistency with the other
/// widened runtime carriers. The interaction builder stores scalar fields
/// only, so there is no additional borrowed structure to retain; the `'a`
/// is vestigial but keeps the carrier signature uniform with
/// `ParallelDeclaration<'a>` and `StreamDeclaration<'a>`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct InteractionDeclaration<'a> {
    payload: u64,
    result_type_iri: &'static str,
    _sealed: (),
    _lifetime: core::marker::PhantomData<&'a ()>,
}

impl<'a> InteractionDeclaration<'a> {
    /// v0.2.2 T6.11: construct an interaction declaration with the given
    /// convergence-predicate seed and result type.
    #[inline]
    #[must_use]
    pub const fn new<T: ConstrainedTypeShape>(
        convergence_seed: u64,
    ) -> InteractionDeclaration<'static> {
        InteractionDeclaration {
            payload: convergence_seed,
            result_type_iri: T::IRI,
            _sealed: (),
            _lifetime: core::marker::PhantomData,
        }
    }

    /// Returns the declared convergence seed.
    #[inline]
    #[must_use]
    pub const fn convergence_seed(&self) -> u64 {
        self.payload
    }

    /// v0.2.2 T6.11: returns the result-type IRI.
    #[inline]
    #[must_use]
    pub const fn result_type_iri(&self) -> &'static str {
        self.result_type_iri
    }
}

/// v0.2.2 Phase F: fixed-size inline payload buffer carried by `PeerInput`.
/// Sized for the largest `Datum<L>` the foundation supports at this release
/// (up to 32 u64 limbs = 2048 bits); smaller levels use the leading bytes.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct PeerPayload {
    words: [u64; 32],
    bit_width: u16,
    _sealed: (),
}

impl PeerPayload {
    /// Construct a zeroed payload of the given bit width.
    #[inline]
    #[must_use]
    pub const fn zero(bit_width: u16) -> Self {
        Self {
            words: [0u64; 32],
            bit_width,
            _sealed: (),
        }
    }

    /// Access the underlying limbs.
    #[inline]
    #[must_use]
    pub const fn words(&self) -> &[u64; 32] {
        &self.words
    }

    /// Bit width of the payload's logical Datum.
    #[inline]
    #[must_use]
    pub const fn bit_width(&self) -> u16 {
        self.bit_width
    }
}

/// v0.2.2 Phase F: a peer-supplied input to an interaction driver step.
/// Fixed-size — holds a `PeerPayload` inline plus the peer's content
/// address. No heap, no dynamic dispatch.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct PeerInput {
    peer_id: u128,
    payload: PeerPayload,
    _sealed: (),
}

impl PeerInput {
    /// Construct a new peer input with the given peer id and payload.
    #[inline]
    #[must_use]
    pub const fn new(peer_id: u128, payload: PeerPayload) -> Self {
        Self {
            peer_id,
            payload,
            _sealed: (),
        }
    }

    /// Access the peer id.
    #[inline]
    #[must_use]
    pub const fn peer_id(&self) -> u128 {
        self.peer_id
    }

    /// Access the payload.
    #[inline]
    #[must_use]
    pub const fn payload(&self) -> &PeerPayload {
        &self.payload
    }
}

/// v0.2.2 Phase F: outcome of a single `InteractionDriver::step` call.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub enum StepResult<T: crate::enforcement::GroundedShape> {
    /// The step was absorbed; the driver is ready for another peer input.
    Continue,
    /// The step produced an intermediate grounded output.
    Output(Grounded<T>),
    /// The convergence predicate is satisfied; interaction is complete.
    Converged(Grounded<T>),
    /// v0.2.2 Phase T.1: the commutator norm failed to decrease for
    /// `INTERACTION_DIVERGENCE_BUDGET` consecutive steps — the interaction is
    /// non-convergent and the driver is no longer advanceable.
    Diverged,
    /// The step failed; the driver is no longer advanceable.
    Failure(PipelineFailure),
}

/// v0.2.2 Phase F: sealed commutator-algebra state carried by an
/// interaction driver across peer steps.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct CommutatorState<L> {
    accumulator: [u64; 4],
    _level: core::marker::PhantomData<L>,
    _sealed: (),
}

impl<L> CommutatorState<L> {
    /// Construct a zero commutator state.
    #[inline]
    #[must_use]
    pub const fn zero() -> Self {
        Self {
            accumulator: [0u64; 4],
            _level: core::marker::PhantomData,
            _sealed: (),
        }
    }

    /// Access the commutator accumulator words.
    #[inline]
    #[must_use]
    pub const fn accumulator(&self) -> &[u64; 4] {
        &self.accumulator
    }
}

/// v0.2.2 Phase F / T2.7: sealed iterator driver returned by `run_stream`.
/// Carries the productivity countdown initialized from the unit's
/// `StreamDeclaration::productivity_bound()`, plus a unit-derived address
/// seed for generating distinct `Grounded` outputs per step. Each call to
/// `next()` decrements the countdown and yields a `Grounded` whose
/// `unit_address` differs from the previous step's.
#[derive(Debug, Clone)]
pub struct StreamDriver<
    T: crate::enforcement::GroundedShape,
    P: crate::enforcement::ValidationPhase,
    H: crate::enforcement::Hasher,
> {
    rewrite_steps: u64,
    landauer_nats: u64,
    productivity_countdown: u64,
    seed: u64,
    result_type_iri: &'static str,
    terminated: bool,
    _shape: core::marker::PhantomData<T>,
    _phase: core::marker::PhantomData<P>,
    _hasher: core::marker::PhantomData<H>,
    _sealed: (),
}

impl<
        T: crate::enforcement::GroundedShape,
        P: crate::enforcement::ValidationPhase,
        H: crate::enforcement::Hasher,
    > StreamDriver<T, P, H>
{
    /// Crate-internal constructor. Callable only from `pipeline::run_stream`.
    #[inline]
    #[must_use]
    #[allow(dead_code)]
    pub(crate) const fn new_internal(
        productivity_bound: u64,
        seed: u64,
        result_type_iri: &'static str,
    ) -> Self {
        Self {
            rewrite_steps: 0,
            landauer_nats: 0,
            productivity_countdown: productivity_bound,
            seed,
            result_type_iri,
            terminated: false,
            _shape: core::marker::PhantomData,
            _phase: core::marker::PhantomData,
            _hasher: core::marker::PhantomData,
            _sealed: (),
        }
    }

    /// Total rewrite steps taken so far.
    #[inline]
    #[must_use]
    pub const fn rewrite_steps(&self) -> u64 {
        self.rewrite_steps
    }

    /// Total Landauer cost accumulated so far.
    #[inline]
    #[must_use]
    pub const fn landauer_nats(&self) -> u64 {
        self.landauer_nats
    }

    /// v0.2.2 T5.10: returns `true` once the driver has stopped producing
    /// rewrite steps. A terminated driver is observationally equivalent to
    /// one whose next `next()` call returns `None`. Use this when the driver
    /// is held inside a larger state machine that needs to decide whether
    /// to advance without consuming a step.
    /// Parallel to `InteractionDriver::is_converged()`.
    #[inline]
    #[must_use]
    pub const fn is_terminated(&self) -> bool {
        self.terminated
    }
}

impl<
        T: crate::enforcement::GroundedShape + ConstrainedTypeShape,
        P: crate::enforcement::ValidationPhase,
        H: crate::enforcement::Hasher,
    > Iterator for StreamDriver<T, P, H>
{
    type Item = Result<Grounded<T>, PipelineFailure>;
    fn next(&mut self) -> Option<Self::Item> {
        if self.terminated || self.productivity_countdown == 0 {
            self.terminated = true;
            return None;
        }
        // v0.2.2 T6.11: ShapeMismatch detection — first step only
        // (subsequent steps inherit the same result_type_iri).
        if self.rewrite_steps == 0 && !crate::enforcement::str_eq(self.result_type_iri, T::IRI) {
            self.terminated = true;
            return Some(Err(PipelineFailure::ShapeMismatch {
                expected: T::IRI,
                got: self.result_type_iri,
            }));
        }
        self.productivity_countdown -= 1;
        self.rewrite_steps += 1;
        self.landauer_nats += 1;
        // v0.2.2 T6.1: thread H: Hasher through fold_stream_step_digest
        // to compute a real per-step substrate fingerprint.
        let mut hasher = H::initial();
        hasher = crate::enforcement::fold_stream_step_digest(
            hasher,
            self.productivity_countdown,
            self.rewrite_steps,
            self.seed,
            self.result_type_iri,
            crate::enforcement::CertificateKind::Grounding,
        );
        let buffer = hasher.finalize();
        let content_fingerprint =
            crate::enforcement::ContentFingerprint::from_buffer(buffer, H::OUTPUT_BYTES as u8);
        let unit_address = crate::enforcement::unit_address_from_buffer(&buffer);
        let grounding = Validated::new(GroundingCertificate::with_level_and_fingerprint_const(
            32,
            content_fingerprint,
        ));
        let bindings = empty_bindings_table();
        Some(Ok(Grounded::<T>::new_internal(
            grounding,
            bindings,
            32, // default witt level for stream output
            unit_address,
            content_fingerprint,
        )))
    }
}

/// v0.2.2 Phase F / T2.7: sealed state-machine driver returned by
/// `run_interactive`. Exposes `step(PeerInput)`, `is_converged()`, and
/// `finalize()`. The driver folds each peer input into its
/// `commutator_acc` accumulator via XOR; convergence is signalled when
/// a peer input arrives with `peer_id == 0` (the closing handshake).
#[derive(Debug, Clone)]
pub struct InteractionDriver<
    T: crate::enforcement::GroundedShape,
    P: crate::enforcement::ValidationPhase,
    H: crate::enforcement::Hasher,
> {
    commutator_acc: [u64; 4],
    peer_step_count: u64,
    converged: bool,
    /// Convergence seed read from the source InteractionDeclaration.
    /// Available via `seed()` for downstream inspection.
    seed: u64,
    /// v0.2.2 Phase T.1: previous step's commutator norm (Euclidean-squared
    /// over the 4 u64 limbs, saturating). Used to detect divergence.
    prev_commutator_norm: u64,
    /// v0.2.2 Phase T.1: count of consecutive non-decreasing norm steps.
    /// Reset to 0 on any decrease; divergence triggers at `DIVERGENCE_BUDGET`.
    consecutive_non_decreasing: u32,
    /// v0.2.2 T6.11: result-type IRI from the source InteractionDeclaration.
    result_type_iri: &'static str,
    _shape: core::marker::PhantomData<T>,
    _phase: core::marker::PhantomData<P>,
    _hasher: core::marker::PhantomData<H>,
    _sealed: (),
}

/// v0.2.2 Phase T.1: divergence budget — max consecutive non-decreasing commutator-norm
/// steps before the interaction driver fails. Foundation-canonical; override at the
/// `InteractionDeclaration` level not supported in this release.
pub const INTERACTION_DIVERGENCE_BUDGET: u32 = 16;

impl<
        T: crate::enforcement::GroundedShape,
        P: crate::enforcement::ValidationPhase,
        H: crate::enforcement::Hasher,
    > InteractionDriver<T, P, H>
{
    /// Crate-internal constructor. Callable only from `pipeline::run_interactive`.
    #[inline]
    #[must_use]
    #[allow(dead_code)]
    pub(crate) const fn new_internal(seed: u64, result_type_iri: &'static str) -> Self {
        // Initial commutator seeded from the unit's convergence seed.
        Self {
            commutator_acc: [seed, 0, 0, 0],
            peer_step_count: 0,
            converged: false,
            seed,
            // Initial norm = seed² (saturating) so the first step can only
            // decrease the norm via peer input (which is the convergence path).
            prev_commutator_norm: seed.saturating_mul(seed),
            consecutive_non_decreasing: 0,
            result_type_iri,
            _shape: core::marker::PhantomData,
            _phase: core::marker::PhantomData,
            _hasher: core::marker::PhantomData,
            _sealed: (),
        }
    }

    /// v0.2.2 Phase T.1: convergence threshold derived from the seed. Termination
    /// triggers when the commutator norm falls below this value. Foundation-canonical:
    /// `seed.rotate_right(32) ^ 0xDEADBEEF_CAFEBABE`.
    #[inline]
    #[must_use]
    pub const fn convergence_threshold(&self) -> u64 {
        self.seed.rotate_right(32) ^ 0xDEAD_BEEF_CAFE_BABE
    }

    /// Advance the driver by folding in a single peer input (v0.2.2 Phase T.1).
    /// Each step XOR-folds the peer payload's first 4 limbs into the
    /// commutator accumulator, then recomputes the Euclidean-squared
    /// norm over the 4 limbs (saturating `u64`). Termination rules:
    /// * **Converged** if the norm falls below `convergence_threshold()`,
    ///   OR if `peer_id == 0` (explicit closing handshake).
    /// * **Diverged** (via `PipelineFailure::ConvergenceStall`) if the norm is
    ///   non-decreasing for `INTERACTION_DIVERGENCE_BUDGET` consecutive steps.
    /// * **Continue** otherwise.
    #[must_use]
    pub fn step(&mut self, input: PeerInput) -> StepResult<T>
    where
        T: ConstrainedTypeShape,
    {
        self.peer_step_count += 1;
        // Fold the first 4 payload words into the accumulator.
        let words = input.payload().words();
        let mut i = 0usize;
        while i < 4 {
            self.commutator_acc[i] ^= words[i];
            i += 1;
        }
        // v0.2.2 Phase T.1: compute the Euclidean-squared norm over the 4 limbs.
        let mut norm: u64 = 0;
        let mut j = 0usize;
        while j < 4 {
            let limb = self.commutator_acc[j];
            norm = norm.saturating_add(limb.saturating_mul(limb));
            j += 1;
        }
        let threshold = self.convergence_threshold();
        // v0.2.2 Phase T.1: convergence on norm-below-threshold OR explicit
        // handshake (peer_id == 0). Divergence on consecutive non-decreasing norm.
        let norm_converged = norm < threshold;
        let handshake_close = input.peer_id() == 0;
        if norm_converged || handshake_close {
            self.converged = true;
            // v0.2.2 T6.1: thread H: Hasher through fold_interaction_step_digest
            // to compute a real convergence-time substrate fingerprint.
            let mut hasher = H::initial();
            hasher = crate::enforcement::fold_interaction_step_digest(
                hasher,
                &self.commutator_acc,
                self.peer_step_count,
                self.seed,
                self.result_type_iri,
                crate::enforcement::CertificateKind::Grounding,
            );
            let buffer = hasher.finalize();
            let content_fingerprint =
                crate::enforcement::ContentFingerprint::from_buffer(buffer, H::OUTPUT_BYTES as u8);
            let unit_address = crate::enforcement::unit_address_from_buffer(&buffer);
            let grounding = Validated::new(GroundingCertificate::with_level_and_fingerprint_const(
                32,
                content_fingerprint,
            ));
            let bindings = empty_bindings_table();
            return StepResult::Converged(Grounded::<T>::new_internal(
                grounding,
                bindings,
                32,
                unit_address,
                content_fingerprint,
            ));
        }
        // v0.2.2 Phase T.1: divergence detection — count consecutive
        // non-decreasing norm steps. Reset on any decrease.
        if norm >= self.prev_commutator_norm {
            self.consecutive_non_decreasing = self.consecutive_non_decreasing.saturating_add(1);
        } else {
            self.consecutive_non_decreasing = 0;
        }
        self.prev_commutator_norm = norm;
        if self.consecutive_non_decreasing >= INTERACTION_DIVERGENCE_BUDGET {
            return StepResult::Diverged;
        }
        StepResult::Continue
    }

    /// Whether the driver has reached the convergence predicate.
    #[inline]
    #[must_use]
    pub const fn is_converged(&self) -> bool {
        self.converged
    }

    /// Number of peer steps applied so far.
    #[inline]
    #[must_use]
    pub const fn peer_step_count(&self) -> u64 {
        self.peer_step_count
    }

    /// Convergence seed inherited from the source InteractionDeclaration.
    #[inline]
    #[must_use]
    pub const fn seed(&self) -> u64 {
        self.seed
    }

    /// Finalize the interaction, producing a grounded result.
    /// Returns a `Grounded<T>` whose `unit_address` is a hash of the
    /// accumulated commutator state, so two interaction drivers that
    /// processed different peer inputs return distinct grounded values.
    /// # Errors
    /// Returns a `PipelineFailure::ShapeViolation` if the driver has
    /// not converged, or `PipelineFailure::ShapeMismatch` if the source
    /// declaration's result_type_iri does not match `T::IRI`.
    pub fn finalize(self) -> Result<Grounded<T>, PipelineFailure>
    where
        T: ConstrainedTypeShape,
    {
        // v0.2.2 T6.11: ShapeMismatch detection.
        if !crate::enforcement::str_eq(self.result_type_iri, T::IRI) {
            return Err(PipelineFailure::ShapeMismatch {
                expected: T::IRI,
                got: self.result_type_iri,
            });
        }
        if !self.converged {
            return Err(PipelineFailure::ShapeViolation {
                report: ShapeViolation {
                    shape_iri: "https://uor.foundation/conformance/InteractionShape",
                    constraint_iri:
                        "https://uor.foundation/conformance/InteractionShape#convergence",
                    property_iri: "https://uor.foundation/conformance/convergencePredicate",
                    expected_range: "http://www.w3.org/2002/07/owl#Thing",
                    min_count: 1,
                    max_count: 1,
                    kind: ViolationKind::Missing,
                },
            });
        }
        // v0.2.2 T6.1: thread H: Hasher through fold_interaction_step_digest.
        let mut hasher = H::initial();
        hasher = crate::enforcement::fold_interaction_step_digest(
            hasher,
            &self.commutator_acc,
            self.peer_step_count,
            self.seed,
            self.result_type_iri,
            crate::enforcement::CertificateKind::Grounding,
        );
        let buffer = hasher.finalize();
        let content_fingerprint =
            crate::enforcement::ContentFingerprint::from_buffer(buffer, H::OUTPUT_BYTES as u8);
        let unit_address = crate::enforcement::unit_address_from_buffer(&buffer);
        let grounding = Validated::new(GroundingCertificate::with_level_and_fingerprint_const(
            32,
            content_fingerprint,
        ));
        let bindings = empty_bindings_table();
        Ok(Grounded::<T>::new_internal(
            grounding,
            bindings,
            32,
            unit_address,
            content_fingerprint,
        ))
    }
}

/// v0.2.2 Phase F / T2.7: parallel driver entry point.
/// Consumes a `Validated<ParallelDeclaration, P>` and produces a unified
/// `Grounded<T>` whose `unit_address` is derived from the declaration's
/// site count via FNV-1a. Two units with different site counts produce
/// `Grounded` values with different addresses.
/// # Errors
/// Returns `PipelineFailure::ShapeMismatch` when the declaration's
/// `result_type_iri` does not match `T::IRI` — the caller asked for
/// `Grounded<T>` but the declaration was built over a different shape.
/// Returns `PipelineFailure::ContradictionDetected` when the declared
/// partition cardinality is zero — a parallel composition with no
/// sites is inadmissible by construction.
/// Success: `run_parallel` folds the declaration's site count through
/// `fold_parallel_digest` to produce a content fingerprint; distinct
/// partitions produce distinct fingerprints by construction.
/// # Example
/// ```no_run
/// use uor_foundation::enforcement::{ConstrainedTypeInput, Validated};
/// use uor_foundation::pipeline::{run_parallel, ParallelDeclaration};
/// # use uor_foundation::enforcement::Hasher;
/// # struct Fnv1aHasher16;
/// # impl Hasher for Fnv1aHasher16 {
/// #     const OUTPUT_BYTES: usize = 16;
/// #     fn initial() -> Self { Self }
/// #     fn fold_byte(self, _: u8) -> Self { self }
/// #     fn finalize(self) -> [u8; 32] { [0; 32] }
/// # }
/// # fn wrap<T>(t: T) -> Validated<T> { unimplemented!() /* see uor_foundation_test_helpers */ }
/// // 3-component partition over 9 sites.
/// static PARTITION: &[u32] = &[0, 0, 0, 1, 1, 1, 2, 2, 2];
/// let decl: Validated<ParallelDeclaration> = wrap(
///     ParallelDeclaration::new_with_partition::<ConstrainedTypeInput>(
///         PARTITION,
///         "https://uor.foundation/parallel/ParallelDisjointnessWitness",
///     ),
/// );
/// let grounded = run_parallel::<ConstrainedTypeInput, _, Fnv1aHasher16>(decl)
///     .expect("partition admits");
/// # let _ = grounded;
/// ```
pub fn run_parallel<T, P, H>(
    unit: Validated<ParallelDeclaration, P>,
) -> Result<Grounded<T>, PipelineFailure>
where
    T: ConstrainedTypeShape + crate::enforcement::GroundedShape,
    P: crate::enforcement::ValidationPhase,
    H: crate::enforcement::Hasher,
{
    let decl = unit.inner();
    let site_count = decl.site_count();
    let partition = decl.site_partition();
    let witness_iri = decl.disjointness_witness();
    // Runtime invariants declared in the ParallelDeclaration rustdoc:
    // (1) result_type_iri must match T::IRI (target §5 + T6.11);
    // (2) site_count > 0 (zero-site parallel composition is vacuous);
    // (3) v0.2.2 Phase H3: partition length must equal site_count;
    // (4) v0.2.2 Phase H3: partition must be non-empty (only constructor is
    //     `new_with_partition`, which takes a real partition slice).
    if !crate::enforcement::str_eq(decl.result_type_iri(), T::IRI) {
        return Err(PipelineFailure::ShapeMismatch {
            expected: T::IRI,
            got: decl.result_type_iri(),
        });
    }
    if site_count == 0 || partition.is_empty() {
        return Err(PipelineFailure::ContradictionDetected {
            at_step: 0,
            trace_iri: "https://uor.foundation/parallel/ParallelProduct",
        });
    }
    if partition.len() as u64 != site_count {
        return Err(PipelineFailure::ShapeMismatch {
            expected: T::IRI,
            got: decl.result_type_iri(),
        });
    }
    // v0.2.2 Phase H3: walk partition, count sites per component, fold
    // per-component into the content fingerprint. Enumerates unique component
    // IDs into a fixed stack buffer sized by WITT_MAX_BITS.
    let mut hasher = H::initial();
    // component_ids: seen component IDs in first-appearance order.
    // component_counts: parallel site-count per component.
    let mut component_ids = [0u32; WITT_MAX_BITS as usize];
    let mut component_counts = [0u32; WITT_MAX_BITS as usize];
    let mut n_components: usize = 0;
    let mut si = 0;
    while si < partition.len() {
        let cid = partition[si];
        // Find or insert cid.
        let mut ci = 0;
        let mut found = false;
        while ci < n_components {
            if component_ids[ci] == cid {
                component_counts[ci] = component_counts[ci].saturating_add(1);
                found = true;
                break;
            }
            ci += 1;
        }
        if !found && n_components < (WITT_MAX_BITS as usize) {
            component_ids[n_components] = cid;
            component_counts[n_components] = 1;
            n_components += 1;
        }
        si += 1;
    }
    // Fold each component: (component_id, site_count_within) in first-appearance order.
    let mut ci = 0;
    while ci < n_components {
        hasher = hasher.fold_bytes(&component_ids[ci].to_be_bytes());
        hasher = hasher.fold_bytes(&component_counts[ci].to_be_bytes());
        ci += 1;
    }
    // Fold disjointness_witness IRI so forgeries yield distinct content fingerprints.
    hasher = hasher.fold_bytes(witness_iri.as_bytes());
    hasher = hasher.fold_byte(0);
    // Canonical ParallelDeclaration tail: site_count + type shape + cert kind.
    hasher = crate::enforcement::fold_parallel_digest(
        hasher,
        site_count,
        T::IRI,
        T::SITE_COUNT,
        T::CONSTRAINTS,
        crate::enforcement::CertificateKind::Grounding,
    );
    let buffer = hasher.finalize();
    let content_fingerprint =
        crate::enforcement::ContentFingerprint::from_buffer(buffer, H::OUTPUT_BYTES as u8);
    let unit_address = crate::enforcement::unit_address_from_buffer(&buffer);
    let grounding = Validated::new(GroundingCertificate::with_level_and_fingerprint_const(
        32,
        content_fingerprint,
    ));
    let bindings = empty_bindings_table();
    Ok(Grounded::<T>::new_internal(
        grounding,
        bindings,
        32,
        unit_address,
        content_fingerprint,
    ))
}

/// v0.2.2 Phase F / T2.7: stream driver entry point.
/// Consumes a `Validated<StreamDeclaration, P>` and returns a
/// `StreamDriver<T, P>` implementing `Iterator`. The driver's productivity
/// countdown is initialized from `StreamDeclaration::productivity_bound()`;
/// each `next()` call yields a `Grounded` whose `unit_address` differs
/// from the previous step's, and the iterator terminates when the
/// countdown reaches zero.
#[must_use]
pub fn run_stream<T, P, H>(unit: Validated<StreamDeclaration, P>) -> StreamDriver<T, P, H>
where
    T: crate::enforcement::GroundedShape,
    P: crate::enforcement::ValidationPhase,
    H: crate::enforcement::Hasher,
{
    let bound = unit.inner().productivity_bound();
    let result_type_iri = unit.inner().result_type_iri();
    StreamDriver::new_internal(bound, bound, result_type_iri)
}

/// v0.2.2 Phase F / T2.7: interaction driver entry point.
/// Consumes a `Validated<InteractionDeclaration, P>` and returns an
/// `InteractionDriver<T, P, H>` state machine seeded from the declaration's
/// `convergence_seed()`. Advance with `step(PeerInput)` until
/// `is_converged()` returns `true`, then call `finalize()`.
#[must_use]
pub fn run_interactive<T, P, H>(
    unit: Validated<InteractionDeclaration, P>,
) -> InteractionDriver<T, P, H>
where
    T: crate::enforcement::GroundedShape,
    P: crate::enforcement::ValidationPhase,
    H: crate::enforcement::Hasher,
{
    InteractionDriver::new_internal(
        unit.inner().convergence_seed(),
        unit.inner().result_type_iri(),
    )
}

/// v0.2.2 Phase G / T2.8: const-fn companion for
/// `LeaseDeclarationBuilder`. Delegates to the builder's
/// `validate_const` method, which validates the `LeaseShape` contract
/// (`linear_site` and `scope` required) at compile time.
/// # Errors
/// Returns `ShapeViolation::Missing` if `linear_site` or `scope` is unset.
pub const fn validate_lease_const<'a>(
    builder: &LeaseDeclarationBuilder<'a>,
) -> Result<Validated<LeaseDeclaration, CompileTime>, ShapeViolation> {
    builder.validate_const()
}

/// v0.2.2 Phase G / T2.8 + T6.13: const-fn companion for `CompileUnitBuilder`.
///
/// Tightened in T6.13 to enforce the same five required fields as the
/// runtime `CompileUnitBuilder::validate()` method:
///
/// - `root_term`
/// - `witt_level_ceiling`
/// - `thermodynamic_budget`
/// - `target_domains` (non-empty)
/// - `result_type_iri`
///
/// Returns `Result<Validated<CompileUnit, CompileTime>, ShapeViolation>` —
/// dual-path consistent with the runtime `validate()` method. Const-eval
/// call sites match on the `Result`; the panic only fires at codegen /
/// const-eval time, never at runtime.
///
/// # Errors
///
/// Returns `ShapeViolation::Missing` for the first unset required field.
pub const fn validate_compile_unit_const<'a>(
    builder: &CompileUnitBuilder<'a>,
) -> Result<Validated<CompileUnit<'a>, CompileTime>, ShapeViolation> {
    if !builder.has_root_term_const() {
        return Err(ShapeViolation {
            shape_iri: "https://uor.foundation/conformance/CompileUnitShape",
            constraint_iri: "https://uor.foundation/conformance/compileUnit_rootTerm_constraint",
            property_iri: "https://uor.foundation/reduction/rootTerm",
            expected_range: "https://uor.foundation/schema/Term",
            min_count: 1,
            max_count: 1,
            kind: ViolationKind::Missing,
        });
    }
    let level = match builder.witt_level_option() {
        Some(l) => l,
        None => {
            return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/conformance/CompileUnitShape",
                constraint_iri:
                    "https://uor.foundation/conformance/compileUnit_unitWittLevel_constraint",
                property_iri: "https://uor.foundation/reduction/unitWittLevel",
                expected_range: "https://uor.foundation/schema/WittLevel",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::Missing,
            })
        }
    };
    let budget =
        match builder.budget_option() {
            Some(b) => b,
            None => return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/conformance/CompileUnitShape",
                constraint_iri:
                    "https://uor.foundation/conformance/compileUnit_thermodynamicBudget_constraint",
                property_iri: "https://uor.foundation/reduction/thermodynamicBudget",
                expected_range: "http://www.w3.org/2001/XMLSchema#decimal",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::Missing,
            }),
        };
    if !builder.has_target_domains_const() {
        return Err(ShapeViolation {
            shape_iri: "https://uor.foundation/conformance/CompileUnitShape",
            constraint_iri:
                "https://uor.foundation/conformance/compileUnit_targetDomains_constraint",
            property_iri: "https://uor.foundation/reduction/targetDomains",
            expected_range: "https://uor.foundation/op/VerificationDomain",
            min_count: 1,
            max_count: 0,
            kind: ViolationKind::Missing,
        });
    }
    let result_type_iri = match builder.result_type_iri_const() {
        Some(iri) => iri,
        None => {
            return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/conformance/CompileUnitShape",
                constraint_iri:
                    "https://uor.foundation/conformance/compileUnit_resultType_constraint",
                property_iri: "https://uor.foundation/reduction/resultType",
                expected_range: "https://uor.foundation/type/ConstrainedType",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::Missing,
            })
        }
    };
    Ok(Validated::new(CompileUnit::from_parts_const(
        level,
        budget,
        result_type_iri,
        builder.root_term_slice_const(),
        builder.bindings_slice_const(),
        builder.target_domains_slice_const(),
    )))
}

/// v0.2.2 Phase G / T2.8 + T6.11: const-fn companion for
/// `ParallelDeclarationBuilder`. Takes a `ConstrainedTypeShape` type parameter
/// to set the `result_type_iri` on the produced declaration.
/// v0.2.2 Phase A: the produced `ParallelDeclaration<'a>` carries the
/// builder's raw site-partition slice and disjointness-witness IRI; the
/// lifetime `'a` is the builder's borrow lifetime.
#[must_use]
pub const fn validate_parallel_const<'a, T: ConstrainedTypeShape>(
    builder: &ParallelDeclarationBuilder<'a>,
) -> Validated<ParallelDeclaration<'a>, CompileTime> {
    Validated::new(ParallelDeclaration::new_with_partition::<T>(
        builder.site_partition_slice_const(),
        builder.disjointness_witness_const(),
    ))
}

/// v0.2.2 Phase G / T2.8 + T6.11: const-fn companion for
/// `StreamDeclarationBuilder`. Takes a `ConstrainedTypeShape` type parameter
/// to set the `result_type_iri` on the produced declaration.
/// v0.2.2 Phase A: the produced `StreamDeclaration<'a>` retains the
/// builder's seed/step term slices and productivity-witness IRI.
#[must_use]
pub const fn validate_stream_const<'a, T: ConstrainedTypeShape>(
    builder: &StreamDeclarationBuilder<'a>,
) -> Validated<StreamDeclaration<'a>, CompileTime> {
    let bound = builder.productivity_bound_const();
    Validated::new(StreamDeclaration::new_full::<T>(
        bound,
        builder.seed_slice_const(),
        builder.step_slice_const(),
        builder.productivity_witness_const(),
    ))
}

/// v0.2.2 T5 C6: const-fn resolver companion for
/// `tower_completeness::certify`. Threads the consumer-supplied substrate
/// `Hasher` through the canonical CompileUnit byte layout to compute a
/// parametric content fingerprint, distinguishing two units that share a
/// witt level but differ in budget, IRI, site count, or constraints.
#[must_use]
pub fn certify_tower_completeness_const<T, H>(
    unit: &Validated<CompileUnit, CompileTime>,
) -> Validated<GroundingCertificate, CompileTime>
where
    T: ConstrainedTypeShape,
    H: crate::enforcement::Hasher,
{
    let level_bits = unit.inner().witt_level().witt_length() as u16;
    let budget = unit.inner().thermodynamic_budget();
    let mut hasher = H::initial();
    hasher = crate::enforcement::fold_unit_digest(
        hasher,
        level_bits,
        budget,
        T::IRI,
        T::SITE_COUNT,
        T::CONSTRAINTS,
        crate::enforcement::CertificateKind::TowerCompleteness,
    );
    let buffer = hasher.finalize();
    let fp = crate::enforcement::ContentFingerprint::from_buffer(buffer, H::OUTPUT_BYTES as u8);
    Validated::new(GroundingCertificate::with_level_and_fingerprint_const(
        level_bits, fp,
    ))
}

/// v0.2.2 T5 C6: const-fn resolver companion for
/// `incremental_completeness::certify`. Threads `H: Hasher` for the
/// parametric fingerprint; uses `CertificateKind::IncrementalCompleteness`
/// as the trailing discriminant byte.
#[must_use]
pub fn certify_incremental_completeness_const<T, H>(
    unit: &Validated<CompileUnit, CompileTime>,
) -> Validated<GroundingCertificate, CompileTime>
where
    T: ConstrainedTypeShape,
    H: crate::enforcement::Hasher,
{
    let level_bits = unit.inner().witt_level().witt_length() as u16;
    let budget = unit.inner().thermodynamic_budget();
    let mut hasher = H::initial();
    hasher = crate::enforcement::fold_unit_digest(
        hasher,
        level_bits,
        budget,
        T::IRI,
        T::SITE_COUNT,
        T::CONSTRAINTS,
        crate::enforcement::CertificateKind::IncrementalCompleteness,
    );
    let buffer = hasher.finalize();
    let fp = crate::enforcement::ContentFingerprint::from_buffer(buffer, H::OUTPUT_BYTES as u8);
    Validated::new(GroundingCertificate::with_level_and_fingerprint_const(
        level_bits, fp,
    ))
}

/// v0.2.2 T5 C6: const-fn resolver companion for `inhabitance::certify`.
/// Threads `H: Hasher` for the parametric fingerprint; uses
/// `CertificateKind::Inhabitance` as the trailing discriminant byte.
#[must_use]
pub fn certify_inhabitance_const<T, H>(
    unit: &Validated<CompileUnit, CompileTime>,
) -> Validated<GroundingCertificate, CompileTime>
where
    T: ConstrainedTypeShape,
    H: crate::enforcement::Hasher,
{
    let level_bits = unit.inner().witt_level().witt_length() as u16;
    let budget = unit.inner().thermodynamic_budget();
    let mut hasher = H::initial();
    hasher = crate::enforcement::fold_unit_digest(
        hasher,
        level_bits,
        budget,
        T::IRI,
        T::SITE_COUNT,
        T::CONSTRAINTS,
        crate::enforcement::CertificateKind::Inhabitance,
    );
    let buffer = hasher.finalize();
    let fp = crate::enforcement::ContentFingerprint::from_buffer(buffer, H::OUTPUT_BYTES as u8);
    Validated::new(GroundingCertificate::with_level_and_fingerprint_const(
        level_bits, fp,
    ))
}

/// v0.2.2 T5 C6: const-fn resolver companion for
/// `multiplication::certify`. Threads `H: Hasher` for the parametric
/// fingerprint; uses `CertificateKind::Multiplication` as the trailing
/// discriminant byte.
#[must_use]
pub fn certify_multiplication_const<T, H>(
    unit: &Validated<CompileUnit, CompileTime>,
) -> Validated<MultiplicationCertificate, CompileTime>
where
    T: ConstrainedTypeShape,
    H: crate::enforcement::Hasher,
{
    let level_bits = unit.inner().witt_level().witt_length() as u16;
    let budget = unit.inner().thermodynamic_budget();
    let mut hasher = H::initial();
    hasher = crate::enforcement::fold_unit_digest(
        hasher,
        level_bits,
        budget,
        T::IRI,
        T::SITE_COUNT,
        T::CONSTRAINTS,
        crate::enforcement::CertificateKind::Multiplication,
    );
    let buffer = hasher.finalize();
    let fp = crate::enforcement::ContentFingerprint::from_buffer(buffer, H::OUTPUT_BYTES as u8);
    Validated::new(MultiplicationCertificate::with_level_and_fingerprint_const(
        level_bits, fp,
    ))
}

/// Phase C.4: const-fn resolver companion for `grounding_aware::certify`.
/// Threads `H: Hasher` for the parametric fingerprint; uses
/// `CertificateKind::Grounding` as the trailing discriminant byte.
#[must_use]
pub fn certify_grounding_aware_const<T, H>(
    unit: &Validated<CompileUnit, CompileTime>,
) -> Validated<GroundingCertificate, CompileTime>
where
    T: ConstrainedTypeShape,
    H: crate::enforcement::Hasher,
{
    let level_bits = unit.inner().witt_level().witt_length() as u16;
    let budget = unit.inner().thermodynamic_budget();
    let mut hasher = H::initial();
    hasher = crate::enforcement::fold_unit_digest(
        hasher,
        level_bits,
        budget,
        T::IRI,
        T::SITE_COUNT,
        T::CONSTRAINTS,
        crate::enforcement::CertificateKind::Grounding,
    );
    let buffer = hasher.finalize();
    let fp = crate::enforcement::ContentFingerprint::from_buffer(buffer, H::OUTPUT_BYTES as u8);
    Validated::new(GroundingCertificate::with_level_and_fingerprint_const(
        level_bits, fp,
    ))
}

/// v0.2.2 T5 C6: typed pipeline entry point producing `Grounded<T>` from
/// a validated `CompileUnit`. Threads the consumer-supplied substrate
/// `Hasher` through `fold_unit_digest` to compute a parametric content
/// fingerprint over the unit's full state: `(level_bits, budget, T::IRI,
/// T::SITE_COUNT, T::CONSTRAINTS, CertificateKind::Grounding)`.
/// Two units differing on **any** of those fields produce `Grounded`
/// values with distinct fingerprints (and distinct `unit_address` handles,
/// derived from the leading 16 bytes of the fingerprint).
/// # Errors
/// Returns `PipelineFailure::ShapeMismatch` when the unit's declared
/// `result_type_iri` does not match `T::IRI`, or propagates any
/// failure from the reduction stage executor.
pub fn run_const<T, M, H>(
    unit: &Validated<CompileUnit, CompileTime>,
) -> Result<Grounded<T>, PipelineFailure>
where
    T: ConstrainedTypeShape + crate::enforcement::GroundedShape,
    // Phase C.2 (target §6): const-eval admits only those grounding-map kinds
    // that are both Total (defined for all inputs) and Invertible (one-to-one).
    // The bound is enforced at the type level via the existing marker tower.
    M: crate::enforcement::GroundingMapKind
        + crate::enforcement::Total
        + crate::enforcement::Invertible,
    H: crate::enforcement::Hasher,
{
    // The marker bound on M is purely type-level — no runtime use.
    let _phantom_map: core::marker::PhantomData<M> = core::marker::PhantomData;
    let level_bits = unit.inner().witt_level().witt_length() as u16;
    let budget = unit.inner().thermodynamic_budget();
    // v0.2.2 T6.11: ShapeMismatch detection. The unit declares its
    // result_type_iri at validation time; the caller's `T::IRI` must match.
    let unit_iri = unit.inner().result_type_iri();
    if !crate::enforcement::str_eq(unit_iri, T::IRI) {
        return Err(PipelineFailure::ShapeMismatch {
            expected: T::IRI,
            got: unit_iri,
        });
    }
    // Walk the foundation-locked byte layout via the consumer's hasher.
    let mut hasher = H::initial();
    hasher = crate::enforcement::fold_unit_digest(
        hasher,
        level_bits,
        budget,
        T::IRI,
        T::SITE_COUNT,
        T::CONSTRAINTS,
        crate::enforcement::CertificateKind::Grounding,
    );
    let buffer = hasher.finalize();
    let content_fingerprint =
        crate::enforcement::ContentFingerprint::from_buffer(buffer, H::OUTPUT_BYTES as u8);
    let unit_address = crate::enforcement::unit_address_from_buffer(&buffer);
    let grounding = Validated::new(GroundingCertificate::with_level_and_fingerprint_const(
        level_bits,
        content_fingerprint,
    ));
    let bindings = empty_bindings_table();
    Ok(Grounded::<T>::new_internal(
        grounding,
        bindings,
        level_bits,
        unit_address,
        content_fingerprint,
    ))
}