uor-foundation 0.2.1

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

//! Declarative enforcement types.
//!
//! This module contains the opaque witness types, declarative builders,
//! the Term AST, and the v0.2.1 ergonomics surface (sealed `Grounded<T>`,
//! the `Certify` trait, `PipelineFailure`, ring-op phantom wrappers,
//! fragment markers, dispatch tables, and the `prelude` module).
//!
//! # Layers
//!
//! - **Layer 1** \[Opaque Witnesses\]: `Datum`, `Validated<T>`, `Derivation`,
//!   `FreeRank` \[private fields, no public constructors\]
//! - **Layer 2** \[Declarative Builders\]: `CompileUnitBuilder`,
//!   `EffectDeclarationBuilder`, etc. \[produce `Validated<T>` on success\]
//! - **Term AST**: `Term`, `TermArena`, `Binding`, `Assertion`, etc.
//! - **v0.2.1 Ergonomics**: `OntologyTarget`, `GroundedShape`, `Grounded<T>`,
//!   `Certify`, `PipelineFailure`, `RingOp<L>`, fragment markers,
//!   `INHABITANCE_DISPATCH_TABLE`, and the `prelude` module.

use crate::{PrimitiveOp, VerificationDomain, ViolationKind, WittLevel};
use core::marker::PhantomData;

/// Private sealed module preventing downstream implementations.
/// Only `GroundedCoord` and `GroundedTuple<N>` implement `Sealed`.
mod sealed {
    /// Sealed trait. Not publicly implementable because this module is private.
    pub trait Sealed {}
    impl Sealed for super::GroundedCoord {}
    impl<const N: usize> Sealed for super::GroundedTuple<N> {}
}

/// Internal level-tagged ring value. Width determined by the Witt level.
/// Variants are emitted parametrically from `schema:WittLevel` individuals
/// in the ontology; adding a new level to the ontology regenerates this enum.
/// Not publicly constructible \[sealed within the crate\].
#[derive(Debug, Clone, PartialEq, Eq)]
#[allow(clippy::large_enum_variant, dead_code)]
pub(crate) enum DatumInner {
    /// W8: 8-bit ring Z/(2^8)Z.
    W8([u8; 1]),
    /// W16: 16-bit ring Z/(2^16)Z.
    W16([u8; 2]),
    /// W24: 24-bit ring Z/(2^24)Z.
    W24([u8; 3]),
    /// W32: 32-bit ring Z/(2^32)Z.
    W32([u8; 4]),
}

/// A ring element at its minting Witt level.
/// Cannot be constructed outside the `uor_foundation` crate.
/// The only way to obtain a `Datum` is through reduction evaluation
/// or the two-phase minting boundary (`validate_and_mint_coord` /
/// `validate_and_mint_tuple`).
/// # Examples
/// ```rust,ignore
/// // A Datum is produced by reduction evaluation or the minting boundary —
/// // you never construct one directly.
/// fn inspect_datum(d: &uor_foundation::enforcement::Datum) {
///     // Query its Witt level (W8 = 8-bit, W32 = 32-bit, etc.)
///     let level = d.level();
///     // Datum width is determined by its level:
///     //   W8 → 1 byte,  W16 → 2 bytes,  W24 → 3 bytes,  W32 → 4 bytes.
///     let bytes = d.as_bytes();
/// }
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Datum {
    /// Level-tagged ring value \[sealed\].
    inner: DatumInner,
}

impl Datum {
    /// Returns the Witt level at which this datum was minted.
    #[inline]
    #[must_use]
    pub const fn level(&self) -> WittLevel {
        match self.inner {
            DatumInner::W8(_) => WittLevel::W8,
            DatumInner::W16(_) => WittLevel::W16,
            DatumInner::W24(_) => WittLevel::new(24),
            DatumInner::W32(_) => WittLevel::new(32),
        }
    }

    /// Returns the raw byte representation of this datum.
    #[inline]
    #[must_use]
    pub fn as_bytes(&self) -> &[u8] {
        match &self.inner {
            DatumInner::W8(b) => b,
            DatumInner::W16(b) => b,
            DatumInner::W24(b) => b,
            DatumInner::W32(b) => b,
        }
    }
}

/// Internal level-tagged coordinate value for grounding intermediates.
/// Variant set mirrors `DatumInner`: one per `schema:WittLevel`.
#[derive(Debug, Clone, PartialEq, Eq)]
#[allow(clippy::large_enum_variant, dead_code)]
pub(crate) enum GroundedCoordInner {
    /// W8: 8-bit coordinate.
    W8([u8; 1]),
    /// W16: 16-bit coordinate.
    W16([u8; 2]),
    /// W24: 24-bit coordinate.
    W24([u8; 3]),
    /// W32: 32-bit coordinate.
    W32([u8; 4]),
}

/// A single grounded coordinate value.
/// Not a `Datum` \[this is the narrow intermediate that a `Grounding`
/// impl produces\]. The foundation validates and mints it into a `Datum`.
/// Uses the same closed level-tagged family as `Datum`, ensuring that
/// coordinate width matches the target Witt level.
/// # Examples
/// ```rust
/// use uor_foundation::enforcement::GroundedCoord;
///
/// // W8: 8-bit ring Z/256Z — lightweight, exhaustive-verification baseline
/// let byte_coord = GroundedCoord::w8(42);
///
/// // W16: 16-bit ring Z/65536Z — audio samples, small indices
/// let short_coord = GroundedCoord::w16(1000);
///
/// // W32: 32-bit ring Z/2^32Z — pixel data, general-purpose integers
/// let word_coord = GroundedCoord::w32(70_000);
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct GroundedCoord {
    /// Level-tagged coordinate bytes.
    pub(crate) inner: GroundedCoordInner,
}

impl GroundedCoord {
    /// Construct a W8 coordinate from a `u8` value (little-endian).
    #[inline]
    #[must_use]
    pub const fn w8(value: u8) -> Self {
        Self {
            inner: GroundedCoordInner::W8(value.to_le_bytes()),
        }
    }

    /// Construct a W16 coordinate from a `u16` value (little-endian).
    #[inline]
    #[must_use]
    pub const fn w16(value: u16) -> Self {
        Self {
            inner: GroundedCoordInner::W16(value.to_le_bytes()),
        }
    }

    /// Construct a W24 coordinate from a `u32` value (little-endian).
    #[inline]
    #[must_use]
    pub const fn w24(value: u32) -> Self {
        let full = value.to_le_bytes();
        let mut out = [0u8; 3];
        let mut i = 0;
        while i < 3 {
            out[i] = full[i];
            i += 1;
        }
        Self {
            inner: GroundedCoordInner::W24(out),
        }
    }

    /// Construct a W32 coordinate from a `u32` value (little-endian).
    #[inline]
    #[must_use]
    pub const fn w32(value: u32) -> Self {
        Self {
            inner: GroundedCoordInner::W32(value.to_le_bytes()),
        }
    }
}

/// A grounded tuple: a fixed-size array of `GroundedCoord` values.
/// Represents a structured type (e.g., the 8 coordinates of an E8
/// lattice point). Not a `Datum` until the foundation validates and
/// mints it. Stack-resident, no heap allocation.
/// # Examples
/// ```rust
/// use uor_foundation::enforcement::{GroundedCoord, GroundedTuple};
///
/// // A 2D pixel: (red, green) at W8 (8-bit per channel)
/// let pixel = GroundedTuple::new([
///     GroundedCoord::w8(255), // red channel
///     GroundedCoord::w8(128), // green channel
/// ]);
///
/// // An E8 lattice point: 8 coordinates at W8
/// let lattice_point = GroundedTuple::new([
///     GroundedCoord::w8(2), GroundedCoord::w8(0),
///     GroundedCoord::w8(0), GroundedCoord::w8(0),
///     GroundedCoord::w8(0), GroundedCoord::w8(0),
///     GroundedCoord::w8(0), GroundedCoord::w8(0),
/// ]);
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct GroundedTuple<const N: usize> {
    /// The coordinate array.
    pub(crate) coords: [GroundedCoord; N],
}

impl<const N: usize> GroundedTuple<N> {
    /// Construct a tuple from a fixed-size array of coordinates.
    #[inline]
    #[must_use]
    pub const fn new(coords: [GroundedCoord; N]) -> Self {
        Self { coords }
    }
}

/// Sealed marker trait for grounded intermediates.
/// Implemented only for `GroundedCoord` and `GroundedTuple<N>`.
/// Prism code cannot implement this \[the sealed module pattern
/// prevents it\].
pub trait GroundedValue: sealed::Sealed {}
impl GroundedValue for GroundedCoord {}
impl<const N: usize> GroundedValue for GroundedTuple<N> {}

/// Open trait for boundary crossing: external data to grounded intermediate.
/// The foundation validates the returned value against the declared
/// `GroundingShape` and mints it into a `Datum` if conformant.
/// # Examples
/// ```rust,ignore
/// use uor_foundation::enforcement::{Grounding, GroundedCoord};
///
/// /// Doubling grounding: maps each input byte b to 2b mod 256.
/// struct DoublingGrounding;
///
/// impl Grounding for DoublingGrounding {
///     type Output = GroundedCoord;
///
///     fn ground(&self, external: &[u8]) -> Option<GroundedCoord> {
///         // Reject empty input at the boundary
///         let &byte = external.first()?;
///         // Apply the doubling map: b -> 2b mod 256
///         Some(GroundedCoord::w8(byte.wrapping_mul(2)))
///     }
/// }
/// ```
pub trait Grounding {
    /// The grounded intermediate type. Bounded by `GroundedValue`,
    /// which is sealed \[only `GroundedCoord` and `GroundedTuple<N>`
    /// are permitted\].
    type Output: GroundedValue;

    /// Map external bytes into a grounded intermediate.
    /// The foundation handles validation and minting.
    /// Returns `None` if the input is malformed or undersized.
    fn ground(&self, external: &[u8]) -> Option<Self::Output>;
}

/// Proof that a value was produced by the conformance checker,
/// not fabricated by Prism code.
/// The inner value and `_sealed` field are private, so `Validated<T>`
/// can only be constructed within this crate.
/// # Examples
/// ```rust,ignore
/// use uor_foundation::enforcement::{CompileUnitBuilder, Term};
/// use uor_foundation::{WittLevel, VerificationDomain};
///
/// // Validated<T> proves that a value passed conformance checking.
/// // You cannot construct one directly — only builder validate() methods
/// // and the minting boundary produce them.
/// let terms = [Term::Literal { value: 1, level: WittLevel::W8 }];
/// let domains = [VerificationDomain::Enumerative];
///
/// let validated = CompileUnitBuilder::new()
///     .root_term(&terms)
///     .witt_level_ceiling(WittLevel::W8)
///     .thermodynamic_budget(1024)
///     .target_domains(&domains)
///     .validate()
///     .expect("all fields set");
///
/// // Access the inner value through the proof wrapper:
/// let compile_unit = validated.inner();
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Validated<T> {
    /// The validated inner value.
    inner: T,
    /// Prevents external construction.
    _sealed: (),
}

impl<T> Validated<T> {
    /// Returns a reference to the validated inner value.
    #[inline]
    #[must_use]
    pub fn inner(&self) -> &T {
        &self.inner
    }

    /// Creates a new `Validated<T>` wrapper. Only callable within the crate.
    #[inline]
    #[allow(dead_code)]
    pub(crate) const fn new(inner: T) -> Self {
        Self { inner, _sealed: () }
    }
}

/// An opaque derivation trace that can only be extended by the rewrite engine.
/// Records the number of rewrite steps and the content address of the
/// root term. Private fields prevent external construction.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Derivation {
    /// Number of rewrite steps in this derivation.
    step_count: u32,
    /// Content address of the root term.
    root_address: u64,
}

impl Derivation {
    /// Returns the number of rewrite steps.
    #[inline]
    #[must_use]
    pub const fn step_count(&self) -> u32 {
        self.step_count
    }

    /// Returns the content address of the root term.
    #[inline]
    #[must_use]
    pub const fn root_address(&self) -> u64 {
        self.root_address
    }

    /// Creates a new derivation. Only callable within the crate.
    #[inline]
    #[allow(dead_code)]
    pub(crate) const fn new(step_count: u32, root_address: u64) -> Self {
        Self {
            step_count,
            root_address,
        }
    }
}

/// An opaque free rank that can only be decremented by `PinningEffect`
/// and incremented by `UnbindingEffect` \[never by direct mutation\].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FreeRank {
    /// Total site capacity at the Witt level.
    total: u32,
    /// Currently pinned sites.
    pinned: u32,
}

impl FreeRank {
    /// Returns the total site capacity.
    #[inline]
    #[must_use]
    pub const fn total(&self) -> u32 {
        self.total
    }

    /// Returns the number of currently pinned sites.
    #[inline]
    #[must_use]
    pub const fn pinned(&self) -> u32 {
        self.pinned
    }

    /// Returns the number of remaining (unpinned) sites.
    #[inline]
    #[must_use]
    pub const fn remaining(&self) -> u32 {
        self.total - self.pinned
    }

    /// Creates a new free rank. Only callable within the crate.
    #[inline]
    #[allow(dead_code)]
    pub(crate) const fn new(total: u32, pinned: u32) -> Self {
        Self { total, pinned }
    }
}

/// Fixed-capacity term list for `#![no_std]`. Indices into a `TermArena`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct TermList {
    /// Start index in the arena.
    pub start: u32,
    /// Number of terms in this list.
    pub len: u32,
}

/// Stack-resident arena for `Term` trees.
/// Fixed capacity determined by the const generic `CAP`.
/// All `Term` child references are `u32` indices into this arena.
/// `#![no_std]`-safe: no heap allocation.
/// # Examples
/// ```rust
/// use uor_foundation::enforcement::{TermArena, Term, TermList};
/// use uor_foundation::{WittLevel, PrimitiveOp};
///
/// // Build the expression `add(3, 5)` bottom-up in an arena.
/// let mut arena = TermArena::<4>::new();
///
/// // Push leaves first:
/// let idx_3 = arena.push(Term::Literal { value: 3, level: WittLevel::W8 });
/// let idx_5 = arena.push(Term::Literal { value: 5, level: WittLevel::W8 });
///
/// // Push the application node, referencing the leaves by index:
/// let idx_add = arena.push(Term::Application {
///     operator: PrimitiveOp::Add,
///     args: TermList { start: idx_3.unwrap_or(0), len: 2 },
/// });
///
/// assert_eq!(arena.len(), 3);
/// // Retrieve a node by index:
/// let node = arena.get(idx_add.unwrap_or(0));
/// assert!(node.is_some());
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TermArena<const CAP: usize> {
    /// Node storage. `None` slots are unused.
    nodes: [Option<Term>; CAP],
    /// Number of allocated nodes.
    len: u32,
}

impl<const CAP: usize> TermArena<CAP> {
    /// Creates an empty arena.
    #[inline]
    #[must_use]
    pub fn new() -> Self {
        Self {
            nodes: core::array::from_fn(|_| None),
            len: 0,
        }
    }

    /// Push a term into the arena and return its index.
    /// # Errors
    /// Returns `None` if the arena is full.
    #[must_use]
    pub fn push(&mut self, term: Term) -> Option<u32> {
        let idx = self.len;
        if (idx as usize) >= CAP {
            return None;
        }
        self.nodes[idx as usize] = Some(term);
        self.len = idx + 1;
        Some(idx)
    }

    /// Returns a reference to the term at `index`, or `None` if out of bounds.
    #[inline]
    #[must_use]
    pub fn get(&self, index: u32) -> Option<&Term> {
        self.nodes
            .get(index as usize)
            .and_then(|slot| slot.as_ref())
    }

    /// Returns the number of allocated nodes.
    #[inline]
    #[must_use]
    pub const fn len(&self) -> u32 {
        self.len
    }

    /// Returns `true` if the arena has no allocated nodes.
    #[inline]
    #[must_use]
    pub const fn is_empty(&self) -> bool {
        self.len == 0
    }
}

impl<const CAP: usize> Default for TermArena<CAP> {
    fn default() -> Self {
        Self::new()
    }
}

/// Concrete AST node for the UOR term language.
/// Mirrors the EBNF grammar productions. All child references are
/// indices into a `TermArena`, keeping the AST stack-resident and
/// `#![no_std]`-safe.
/// # Examples
/// ```rust
/// use uor_foundation::enforcement::{Term, TermList};
/// use uor_foundation::{WittLevel, PrimitiveOp};
///
/// // Literal: an integer value tagged with a Witt level.
/// let lit = Term::Literal { value: 42, level: WittLevel::W8 };
///
/// // Application: an operation applied to arguments.
/// // `args` is a TermList { start, len } pointing into a TermArena.
/// let app = Term::Application {
///     operator: PrimitiveOp::Mul,
///     args: TermList { start: 0, len: 2 },
/// };
///
/// // Lift: canonical injection from a lower to a higher Witt level.
/// let lift = Term::Lift { operand_index: 0, target: WittLevel::new(32) };
///
/// // Project: canonical surjection from a higher to a lower level.
/// let proj = Term::Project { operand_index: 0, target: WittLevel::W8 };
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Term {
    /// Integer literal with Witt level annotation.
    Literal {
        /// The literal integer value.
        value: u64,
        /// The Witt level of this literal.
        level: WittLevel,
    },
    /// Variable reference by name index.
    Variable {
        /// Index into the name table.
        name_index: u32,
    },
    /// Operation application: operator applied to arguments.
    Application {
        /// The primitive operation to apply.
        operator: PrimitiveOp,
        /// Argument list (indices into arena).
        args: TermList,
    },
    /// Lift: canonical injection W_n to W_m (n < m, lossless).
    Lift {
        /// Index of the operand term in the arena.
        operand_index: u32,
        /// Target Witt level.
        target: WittLevel,
    },
    /// Project: canonical surjection W_m to W_n (m > n, lossy).
    Project {
        /// Index of the operand term in the arena.
        operand_index: u32,
        /// Target Witt level.
        target: WittLevel,
    },
    /// Match expression with pattern-result pairs.
    Match {
        /// Index of the scrutinee term in the arena.
        scrutinee_index: u32,
        /// Match arms (indices into arena).
        arms: TermList,
    },
    /// Bounded recursion with descent measure.
    Recurse {
        /// Index of the descent measure term.
        measure_index: u32,
        /// Index of the base case term.
        base_index: u32,
        /// Index of the recursive step term.
        step_index: u32,
    },
    /// Stream construction via unfold.
    Unfold {
        /// Index of the seed term.
        seed_index: u32,
        /// Index of the step function term.
        step_index: u32,
    },
    /// Try expression with failure recovery.
    Try {
        /// Index of the body term.
        body_index: u32,
        /// Index of the handler term.
        handler_index: u32,
    },
}

/// A type declaration with constraint kinds.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TypeDeclaration {
    /// Name index for this type.
    pub name_index: u32,
    /// Constraint terms (indices into arena).
    pub constraints: TermList,
}

/// A named binding: `let name : Type = term`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Binding {
    /// Name index for this binding.
    pub name_index: u32,
    /// Index of the type declaration.
    pub type_index: u32,
    /// Index of the value term in the arena.
    pub value_index: u32,
    /// EBNF surface syntax (compile-time constant).
    pub surface: &'static str,
    /// FNV-1a content address (compile-time constant).
    pub content_address: u64,
}

/// An assertion: `assert lhs = rhs`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Assertion {
    /// Index of the left-hand side term.
    pub lhs_index: u32,
    /// Index of the right-hand side term.
    pub rhs_index: u32,
    /// EBNF surface syntax (compile-time constant).
    pub surface: &'static str,
}

/// Boundary source declaration: `source name : Type via grounding`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SourceDeclaration {
    /// Name index for the source.
    pub name_index: u32,
    /// Index of the type declaration.
    pub type_index: u32,
    /// Name index of the grounding map.
    pub grounding_name_index: u32,
}

/// Boundary sink declaration: `sink name : Type via projection`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SinkDeclaration {
    /// Name index for the sink.
    pub name_index: u32,
    /// Index of the type declaration.
    pub type_index: u32,
    /// Name index of the projection map.
    pub projection_name_index: u32,
}

/// Structured violation diagnostic carrying metadata from the
/// conformance namespace. Every field is machine-readable.
/// # Examples
/// ```rust
/// use uor_foundation::enforcement::ShapeViolation;
/// use uor_foundation::ViolationKind;
///
/// // ShapeViolation carries structured metadata from the ontology.
/// // Every field is machine-readable — IRIs, counts, and a typed kind.
/// let violation = 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,
/// };
///
/// // Machine-readable for tooling (IDE plugins, CI pipelines):
/// assert_eq!(violation.kind, ViolationKind::Missing);
/// assert!(violation.shape_iri.ends_with("CompileUnitShape"));
/// assert_eq!(violation.min_count, 1);
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ShapeViolation {
    /// IRI of the `conformance:Shape` that was validated against.
    pub shape_iri: &'static str,
    /// IRI of the specific `conformance:PropertyConstraint` that failed.
    pub constraint_iri: &'static str,
    /// IRI of the property that was missing or invalid.
    pub property_iri: &'static str,
    /// The expected range class IRI.
    pub expected_range: &'static str,
    /// Minimum cardinality from the constraint.
    pub min_count: u32,
    /// Maximum cardinality (0 = unbounded).
    pub max_count: u32,
    /// What went wrong.
    pub kind: ViolationKind,
}

/// Builder for `CompileUnit` admission into the reduction pipeline.
/// Collects `rootTerm`, `wittLevelCeiling`, `thermodynamicBudget`,
/// and `targetDomains`. The `validate()` method checks structural
/// constraints (Tier 1) and value-dependent constraints (Tier 2).
/// # Examples
/// ```rust
/// use uor_foundation::enforcement::{CompileUnitBuilder, Term};
/// use uor_foundation::{WittLevel, VerificationDomain, ViolationKind};
///
/// // A CompileUnit packages a term graph for reduction admission.
/// // The builder enforces that all required fields are present.
/// let terms = [Term::Literal { value: 1, level: WittLevel::W8 }];
/// let domains = [VerificationDomain::Enumerative];
///
/// let unit = CompileUnitBuilder::new()
///     .root_term(&terms)
///     .witt_level_ceiling(WittLevel::W8)
///     .thermodynamic_budget(1024)
///     .target_domains(&domains)
///     .validate();
/// assert!(unit.is_ok());
///
/// // Omitting a required field produces a ShapeViolation
/// // with the exact conformance IRI that failed:
/// let err = CompileUnitBuilder::new()
///     .witt_level_ceiling(WittLevel::W8)
///     .thermodynamic_budget(1024)
///     .target_domains(&domains)
///     .validate();
/// assert!(err.is_err());
/// if let Err(violation) = err {
///     assert_eq!(violation.kind, ViolationKind::Missing);
///     assert!(violation.property_iri.contains("rootTerm"));
/// }
/// ```
#[derive(Debug, Clone)]
pub struct CompileUnitBuilder<'a> {
    /// The root term expression.
    root_term: Option<&'a [Term]>,
    /// The widest Witt level the computation may reference.
    witt_level_ceiling: Option<WittLevel>,
    /// Landauer-bounded energy budget.
    thermodynamic_budget: Option<u64>,
    /// Verification domains targeted.
    target_domains: Option<&'a [VerificationDomain]>,
}

/// A validated compile unit ready for reduction admission.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CompileUnit {
    /// The Witt level ceiling.
    level: WittLevel,
    /// The thermodynamic budget.
    budget: u64,
}

impl<'a> CompileUnitBuilder<'a> {
    /// Creates a new empty builder.
    #[must_use]
    pub const fn new() -> Self {
        Self {
            root_term: None,
            witt_level_ceiling: None,
            thermodynamic_budget: None,
            target_domains: None,
        }
    }

    /// Set the root term expression.
    #[must_use]
    pub const fn root_term(mut self, terms: &'a [Term]) -> Self {
        self.root_term = Some(terms);
        self
    }

    /// Set the Witt level ceiling.
    #[must_use]
    pub const fn witt_level_ceiling(mut self, level: WittLevel) -> Self {
        self.witt_level_ceiling = Some(level);
        self
    }

    /// Set the thermodynamic budget.
    #[must_use]
    pub const fn thermodynamic_budget(mut self, budget: u64) -> Self {
        self.thermodynamic_budget = Some(budget);
        self
    }

    /// Set the target verification domains.
    #[must_use]
    pub const fn target_domains(mut self, domains: &'a [VerificationDomain]) -> Self {
        self.target_domains = Some(domains);
        self
    }

    /// Validate against `CompileUnitShape`.
    /// Tier 1: checks presence and cardinality of all required fields.
    /// Tier 2: checks budget solvency and level coherence.
    /// # Errors
    /// Returns `ShapeViolation` if any constraint is not satisfied.
    pub fn validate(self) -> Result<Validated<CompileUnit>, ShapeViolation> {
        if self.root_term.is_none() {
            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 self.witt_level_ceiling {
                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 self.thermodynamic_budget {
            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,
            }),
        };
        match self.target_domains {
            Some(d) if !d.is_empty() => {}
            _ => {
                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,
                })
            }
        }
        Ok(Validated::new(CompileUnit { level, budget }))
    }
}

impl<'a> Default for CompileUnitBuilder<'a> {
    fn default() -> Self {
        Self::new()
    }
}

/// Builder for `EffectDeclaration`. Validates against `EffectShape`.
#[derive(Debug, Clone)]
pub struct EffectDeclarationBuilder<'a> {
    /// The `name` field.
    name: Option<&'a str>,
    /// The `target_sites` field.
    target_sites: Option<&'a [u32]>,
    /// The `budget_delta` field.
    budget_delta: Option<i64>,
    /// The `commutes` field.
    commutes: Option<bool>,
}

/// Declared effect validated against `EffectShape`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EffectDeclaration {
    /// Shape IRI this declaration was validated against.
    pub shape_iri: &'static str,
}

impl<'a> EffectDeclarationBuilder<'a> {
    /// Creates a new empty builder.
    #[must_use]
    pub const fn new() -> Self {
        Self {
            name: None,
            target_sites: None,
            budget_delta: None,
            commutes: None,
        }
    }

    /// Set the `name` field.
    #[must_use]
    pub const fn name(mut self, value: &'a str) -> Self {
        self.name = Some(value);
        self
    }

    /// Set the `target_sites` field.
    #[must_use]
    pub const fn target_sites(mut self, value: &'a [u32]) -> Self {
        self.target_sites = Some(value);
        self
    }

    /// Set the `budget_delta` field.
    #[must_use]
    pub const fn budget_delta(mut self, value: i64) -> Self {
        self.budget_delta = Some(value);
        self
    }

    /// Set the `commutes` field.
    #[must_use]
    pub const fn commutes(mut self, value: bool) -> Self {
        self.commutes = Some(value);
        self
    }

    /// Validate against `EffectShape`.
    /// # Errors
    /// Returns `ShapeViolation` if any required field is missing.
    pub fn validate(self) -> Result<Validated<EffectDeclaration>, ShapeViolation> {
        if self.name.is_none() {
            return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/conformance/EffectShape",
                constraint_iri: "https://uor.foundation/conformance/EffectShape",
                property_iri: "https://uor.foundation/conformance/name",
                expected_range: "http://www.w3.org/2002/07/owl#Thing",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::Missing,
            });
        }
        if self.target_sites.is_none() {
            return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/conformance/EffectShape",
                constraint_iri: "https://uor.foundation/conformance/EffectShape",
                property_iri: "https://uor.foundation/conformance/target_sites",
                expected_range: "http://www.w3.org/2002/07/owl#Thing",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::Missing,
            });
        }
        if self.budget_delta.is_none() {
            return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/conformance/EffectShape",
                constraint_iri: "https://uor.foundation/conformance/EffectShape",
                property_iri: "https://uor.foundation/conformance/budget_delta",
                expected_range: "http://www.w3.org/2002/07/owl#Thing",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::Missing,
            });
        }
        if self.commutes.is_none() {
            return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/conformance/EffectShape",
                constraint_iri: "https://uor.foundation/conformance/EffectShape",
                property_iri: "https://uor.foundation/conformance/commutes",
                expected_range: "http://www.w3.org/2002/07/owl#Thing",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::Missing,
            });
        }
        Ok(Validated::new(EffectDeclaration {
            shape_iri: "https://uor.foundation/conformance/EffectShape",
        }))
    }
}

impl<'a> Default for EffectDeclarationBuilder<'a> {
    fn default() -> Self {
        Self::new()
    }
}

/// Builder for `GroundingDeclaration`. Validates against `GroundingShape`.
#[derive(Debug, Clone)]
pub struct GroundingDeclarationBuilder<'a> {
    /// The `source_type` field.
    source_type: Option<&'a str>,
    /// The `ring_mapping` field.
    ring_mapping: Option<&'a str>,
    /// The `invertibility` field.
    invertibility: Option<bool>,
}

/// Declared grounding validated against `GroundingShape`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct GroundingDeclaration {
    /// Shape IRI this declaration was validated against.
    pub shape_iri: &'static str,
}

impl<'a> GroundingDeclarationBuilder<'a> {
    /// Creates a new empty builder.
    #[must_use]
    pub const fn new() -> Self {
        Self {
            source_type: None,
            ring_mapping: None,
            invertibility: None,
        }
    }

    /// Set the `source_type` field.
    #[must_use]
    pub const fn source_type(mut self, value: &'a str) -> Self {
        self.source_type = Some(value);
        self
    }

    /// Set the `ring_mapping` field.
    #[must_use]
    pub const fn ring_mapping(mut self, value: &'a str) -> Self {
        self.ring_mapping = Some(value);
        self
    }

    /// Set the `invertibility` field.
    #[must_use]
    pub const fn invertibility(mut self, value: bool) -> Self {
        self.invertibility = Some(value);
        self
    }

    /// Validate against `GroundingShape`.
    /// # Errors
    /// Returns `ShapeViolation` if any required field is missing.
    pub fn validate(self) -> Result<Validated<GroundingDeclaration>, ShapeViolation> {
        if self.source_type.is_none() {
            return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/conformance/GroundingShape",
                constraint_iri: "https://uor.foundation/conformance/GroundingShape",
                property_iri: "https://uor.foundation/conformance/source_type",
                expected_range: "http://www.w3.org/2002/07/owl#Thing",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::Missing,
            });
        }
        if self.ring_mapping.is_none() {
            return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/conformance/GroundingShape",
                constraint_iri: "https://uor.foundation/conformance/GroundingShape",
                property_iri: "https://uor.foundation/conformance/ring_mapping",
                expected_range: "http://www.w3.org/2002/07/owl#Thing",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::Missing,
            });
        }
        if self.invertibility.is_none() {
            return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/conformance/GroundingShape",
                constraint_iri: "https://uor.foundation/conformance/GroundingShape",
                property_iri: "https://uor.foundation/conformance/invertibility",
                expected_range: "http://www.w3.org/2002/07/owl#Thing",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::Missing,
            });
        }
        Ok(Validated::new(GroundingDeclaration {
            shape_iri: "https://uor.foundation/conformance/GroundingShape",
        }))
    }
}

impl<'a> Default for GroundingDeclarationBuilder<'a> {
    fn default() -> Self {
        Self::new()
    }
}

/// Builder for `DispatchDeclaration`. Validates against `DispatchShape`.
#[derive(Debug, Clone)]
pub struct DispatchDeclarationBuilder<'a> {
    /// The `predicate` field.
    predicate: Option<&'a [Term]>,
    /// The `target_resolver` field.
    target_resolver: Option<&'a str>,
    /// The `priority` field.
    priority: Option<u32>,
}

/// Declared dispatch rule validated against `DispatchShape`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DispatchDeclaration {
    /// Shape IRI this declaration was validated against.
    pub shape_iri: &'static str,
}

impl<'a> DispatchDeclarationBuilder<'a> {
    /// Creates a new empty builder.
    #[must_use]
    pub const fn new() -> Self {
        Self {
            predicate: None,
            target_resolver: None,
            priority: None,
        }
    }

    /// Set the `predicate` field.
    #[must_use]
    pub const fn predicate(mut self, value: &'a [Term]) -> Self {
        self.predicate = Some(value);
        self
    }

    /// Set the `target_resolver` field.
    #[must_use]
    pub const fn target_resolver(mut self, value: &'a str) -> Self {
        self.target_resolver = Some(value);
        self
    }

    /// Set the `priority` field.
    #[must_use]
    pub const fn priority(mut self, value: u32) -> Self {
        self.priority = Some(value);
        self
    }

    /// Validate against `DispatchShape`.
    /// # Errors
    /// Returns `ShapeViolation` if any required field is missing.
    pub fn validate(self) -> Result<Validated<DispatchDeclaration>, ShapeViolation> {
        if self.predicate.is_none() {
            return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/conformance/DispatchShape",
                constraint_iri: "https://uor.foundation/conformance/DispatchShape",
                property_iri: "https://uor.foundation/conformance/predicate",
                expected_range: "http://www.w3.org/2002/07/owl#Thing",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::Missing,
            });
        }
        if self.target_resolver.is_none() {
            return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/conformance/DispatchShape",
                constraint_iri: "https://uor.foundation/conformance/DispatchShape",
                property_iri: "https://uor.foundation/conformance/target_resolver",
                expected_range: "http://www.w3.org/2002/07/owl#Thing",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::Missing,
            });
        }
        if self.priority.is_none() {
            return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/conformance/DispatchShape",
                constraint_iri: "https://uor.foundation/conformance/DispatchShape",
                property_iri: "https://uor.foundation/conformance/priority",
                expected_range: "http://www.w3.org/2002/07/owl#Thing",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::Missing,
            });
        }
        Ok(Validated::new(DispatchDeclaration {
            shape_iri: "https://uor.foundation/conformance/DispatchShape",
        }))
    }
}

impl<'a> Default for DispatchDeclarationBuilder<'a> {
    fn default() -> Self {
        Self::new()
    }
}

/// Builder for `LeaseDeclaration`. Validates against `LeaseShape`.
#[derive(Debug, Clone)]
pub struct LeaseDeclarationBuilder<'a> {
    /// The `linear_site` field.
    linear_site: Option<u32>,
    /// The `scope` field.
    scope: Option<&'a str>,
}

/// Declared lease validated against `LeaseShape`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LeaseDeclaration {
    /// Shape IRI this declaration was validated against.
    pub shape_iri: &'static str,
}

impl<'a> LeaseDeclarationBuilder<'a> {
    /// Creates a new empty builder.
    #[must_use]
    pub const fn new() -> Self {
        Self {
            linear_site: None,
            scope: None,
        }
    }

    /// Set the `linear_site` field.
    #[must_use]
    pub const fn linear_site(mut self, value: u32) -> Self {
        self.linear_site = Some(value);
        self
    }

    /// Set the `scope` field.
    #[must_use]
    pub const fn scope(mut self, value: &'a str) -> Self {
        self.scope = Some(value);
        self
    }

    /// Validate against `LeaseShape`.
    /// # Errors
    /// Returns `ShapeViolation` if any required field is missing.
    pub fn validate(self) -> Result<Validated<LeaseDeclaration>, ShapeViolation> {
        if self.linear_site.is_none() {
            return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/conformance/LeaseShape",
                constraint_iri: "https://uor.foundation/conformance/LeaseShape",
                property_iri: "https://uor.foundation/conformance/linear_site",
                expected_range: "http://www.w3.org/2002/07/owl#Thing",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::Missing,
            });
        }
        if self.scope.is_none() {
            return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/conformance/LeaseShape",
                constraint_iri: "https://uor.foundation/conformance/LeaseShape",
                property_iri: "https://uor.foundation/conformance/scope",
                expected_range: "http://www.w3.org/2002/07/owl#Thing",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::Missing,
            });
        }
        Ok(Validated::new(LeaseDeclaration {
            shape_iri: "https://uor.foundation/conformance/LeaseShape",
        }))
    }
}

impl<'a> Default for LeaseDeclarationBuilder<'a> {
    fn default() -> Self {
        Self::new()
    }
}

/// Builder for `StreamDeclaration`. Validates against `StreamShape`.
#[derive(Debug, Clone)]
pub struct StreamDeclarationBuilder<'a> {
    /// The `seed` field.
    seed: Option<&'a [Term]>,
    /// The `step` field.
    step: Option<&'a [Term]>,
    /// The `productivity_witness` field.
    productivity_witness: Option<&'a str>,
}

/// Declared stream validated against `StreamShape`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct StreamDeclaration {
    /// Shape IRI this declaration was validated against.
    pub shape_iri: &'static str,
}

impl<'a> StreamDeclarationBuilder<'a> {
    /// Creates a new empty builder.
    #[must_use]
    pub const fn new() -> Self {
        Self {
            seed: None,
            step: None,
            productivity_witness: None,
        }
    }

    /// Set the `seed` field.
    #[must_use]
    pub const fn seed(mut self, value: &'a [Term]) -> Self {
        self.seed = Some(value);
        self
    }

    /// Set the `step` field.
    #[must_use]
    pub const fn step(mut self, value: &'a [Term]) -> Self {
        self.step = Some(value);
        self
    }

    /// Set the `productivity_witness` field.
    #[must_use]
    pub const fn productivity_witness(mut self, value: &'a str) -> Self {
        self.productivity_witness = Some(value);
        self
    }

    /// Validate against `StreamShape`.
    /// # Errors
    /// Returns `ShapeViolation` if any required field is missing.
    pub fn validate(self) -> Result<Validated<StreamDeclaration>, ShapeViolation> {
        if self.seed.is_none() {
            return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/conformance/StreamShape",
                constraint_iri: "https://uor.foundation/conformance/StreamShape",
                property_iri: "https://uor.foundation/conformance/seed",
                expected_range: "http://www.w3.org/2002/07/owl#Thing",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::Missing,
            });
        }
        if self.step.is_none() {
            return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/conformance/StreamShape",
                constraint_iri: "https://uor.foundation/conformance/StreamShape",
                property_iri: "https://uor.foundation/conformance/step",
                expected_range: "http://www.w3.org/2002/07/owl#Thing",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::Missing,
            });
        }
        if self.productivity_witness.is_none() {
            return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/conformance/StreamShape",
                constraint_iri: "https://uor.foundation/conformance/StreamShape",
                property_iri: "https://uor.foundation/conformance/productivity_witness",
                expected_range: "http://www.w3.org/2002/07/owl#Thing",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::Missing,
            });
        }
        Ok(Validated::new(StreamDeclaration {
            shape_iri: "https://uor.foundation/conformance/StreamShape",
        }))
    }
}

impl<'a> Default for StreamDeclarationBuilder<'a> {
    fn default() -> Self {
        Self::new()
    }
}

/// Builder for `PredicateDeclaration`. Validates against `PredicateShape`.
#[derive(Debug, Clone)]
pub struct PredicateDeclarationBuilder<'a> {
    /// The `input_type` field.
    input_type: Option<&'a str>,
    /// The `evaluator` field.
    evaluator: Option<&'a [Term]>,
    /// The `termination_witness` field.
    termination_witness: Option<&'a str>,
}

/// Declared predicate validated against `PredicateShape`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PredicateDeclaration {
    /// Shape IRI this declaration was validated against.
    pub shape_iri: &'static str,
}

impl<'a> PredicateDeclarationBuilder<'a> {
    /// Creates a new empty builder.
    #[must_use]
    pub const fn new() -> Self {
        Self {
            input_type: None,
            evaluator: None,
            termination_witness: None,
        }
    }

    /// Set the `input_type` field.
    #[must_use]
    pub const fn input_type(mut self, value: &'a str) -> Self {
        self.input_type = Some(value);
        self
    }

    /// Set the `evaluator` field.
    #[must_use]
    pub const fn evaluator(mut self, value: &'a [Term]) -> Self {
        self.evaluator = Some(value);
        self
    }

    /// Set the `termination_witness` field.
    #[must_use]
    pub const fn termination_witness(mut self, value: &'a str) -> Self {
        self.termination_witness = Some(value);
        self
    }

    /// Validate against `PredicateShape`.
    /// # Errors
    /// Returns `ShapeViolation` if any required field is missing.
    pub fn validate(self) -> Result<Validated<PredicateDeclaration>, ShapeViolation> {
        if self.input_type.is_none() {
            return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/conformance/PredicateShape",
                constraint_iri: "https://uor.foundation/conformance/PredicateShape",
                property_iri: "https://uor.foundation/conformance/input_type",
                expected_range: "http://www.w3.org/2002/07/owl#Thing",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::Missing,
            });
        }
        if self.evaluator.is_none() {
            return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/conformance/PredicateShape",
                constraint_iri: "https://uor.foundation/conformance/PredicateShape",
                property_iri: "https://uor.foundation/conformance/evaluator",
                expected_range: "http://www.w3.org/2002/07/owl#Thing",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::Missing,
            });
        }
        if self.termination_witness.is_none() {
            return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/conformance/PredicateShape",
                constraint_iri: "https://uor.foundation/conformance/PredicateShape",
                property_iri: "https://uor.foundation/conformance/termination_witness",
                expected_range: "http://www.w3.org/2002/07/owl#Thing",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::Missing,
            });
        }
        Ok(Validated::new(PredicateDeclaration {
            shape_iri: "https://uor.foundation/conformance/PredicateShape",
        }))
    }
}

impl<'a> Default for PredicateDeclarationBuilder<'a> {
    fn default() -> Self {
        Self::new()
    }
}

/// Builder for `ParallelDeclaration`. Validates against `ParallelShape`.
#[derive(Debug, Clone)]
pub struct ParallelDeclarationBuilder<'a> {
    /// The `site_partition` field.
    site_partition: Option<&'a [u32]>,
    /// The `disjointness_witness` field.
    disjointness_witness: Option<&'a str>,
}

/// Declared parallel composition validated against `ParallelShape`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ParallelDeclaration {
    /// Shape IRI this declaration was validated against.
    pub shape_iri: &'static str,
}

impl<'a> ParallelDeclarationBuilder<'a> {
    /// Creates a new empty builder.
    #[must_use]
    pub const fn new() -> Self {
        Self {
            site_partition: None,
            disjointness_witness: None,
        }
    }

    /// Set the `site_partition` field.
    #[must_use]
    pub const fn site_partition(mut self, value: &'a [u32]) -> Self {
        self.site_partition = Some(value);
        self
    }

    /// Set the `disjointness_witness` field.
    #[must_use]
    pub const fn disjointness_witness(mut self, value: &'a str) -> Self {
        self.disjointness_witness = Some(value);
        self
    }

    /// Validate against `ParallelShape`.
    /// # Errors
    /// Returns `ShapeViolation` if any required field is missing.
    pub fn validate(self) -> Result<Validated<ParallelDeclaration>, ShapeViolation> {
        if self.site_partition.is_none() {
            return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/conformance/ParallelShape",
                constraint_iri: "https://uor.foundation/conformance/ParallelShape",
                property_iri: "https://uor.foundation/conformance/site_partition",
                expected_range: "http://www.w3.org/2002/07/owl#Thing",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::Missing,
            });
        }
        if self.disjointness_witness.is_none() {
            return Err(ShapeViolation {
                shape_iri: "https://uor.foundation/conformance/ParallelShape",
                constraint_iri: "https://uor.foundation/conformance/ParallelShape",
                property_iri: "https://uor.foundation/conformance/disjointness_witness",
                expected_range: "http://www.w3.org/2002/07/owl#Thing",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::Missing,
            });
        }
        Ok(Validated::new(ParallelDeclaration {
            shape_iri: "https://uor.foundation/conformance/ParallelShape",
        }))
    }
}

impl<'a> Default for ParallelDeclarationBuilder<'a> {
    fn default() -> Self {
        Self::new()
    }
}

/// Builder for declaring a new Witt level beyond W32.
/// Validates against `WittLevelShape`.
#[derive(Debug, Clone)]
pub struct WittLevelDeclarationBuilder {
    /// The declared bit width.
    bit_width: Option<u32>,
    /// The declared cycle size.
    cycle_size: Option<u128>,
    /// The predecessor level.
    predecessor: Option<WittLevel>,
}

/// Validated Witt level declaration.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct WittLevelDeclaration {
    /// The declared bit width.
    pub bit_width: u32,
    /// The predecessor level.
    pub predecessor: WittLevel,
}

impl WittLevelDeclarationBuilder {
    /// Creates a new empty builder.
    #[must_use]
    pub const fn new() -> Self {
        Self {
            bit_width: None,
            cycle_size: None,
            predecessor: None,
        }
    }

    /// Set the declared bit width.
    #[must_use]
    pub const fn bit_width(mut self, w: u32) -> Self {
        self.bit_width = Some(w);
        self
    }

    /// Set the declared cycle size.
    #[must_use]
    pub const fn cycle_size(mut self, s: u128) -> Self {
        self.cycle_size = Some(s);
        self
    }

    /// Set the predecessor Witt level.
    #[must_use]
    pub const fn predecessor(mut self, level: WittLevel) -> Self {
        self.predecessor = Some(level);
        self
    }

    /// Validate against `WittLevelShape`.
    /// # Errors
    /// Returns `ShapeViolation` if any required field is missing.
    pub fn validate(self) -> Result<Validated<WittLevelDeclaration>, ShapeViolation> {
        let bw = match self.bit_width {
            Some(w) => w,
            None => {
                return Err(ShapeViolation {
                    shape_iri: "https://uor.foundation/conformance/WittLevelShape",
                    constraint_iri: "https://uor.foundation/conformance/WittLevelShape",
                    property_iri: "https://uor.foundation/conformance/declaredBitWidth",
                    expected_range: "http://www.w3.org/2001/XMLSchema#positiveInteger",
                    min_count: 1,
                    max_count: 1,
                    kind: ViolationKind::Missing,
                })
            }
        };
        let pred = match self.predecessor {
            Some(p) => p,
            None => {
                return Err(ShapeViolation {
                    shape_iri: "https://uor.foundation/conformance/WittLevelShape",
                    constraint_iri: "https://uor.foundation/conformance/WittLevelShape",
                    property_iri: "https://uor.foundation/conformance/predecessorLevel",
                    expected_range: "https://uor.foundation/schema/WittLevel",
                    min_count: 1,
                    max_count: 1,
                    kind: ViolationKind::Missing,
                })
            }
        };
        Ok(Validated::new(WittLevelDeclaration {
            bit_width: bw,
            predecessor: pred,
        }))
    }
}

impl Default for WittLevelDeclarationBuilder {
    fn default() -> Self {
        Self::new()
    }
}

/// Boundary session state tracker for the two-phase minting boundary.
/// Records crossing count and idempotency flag. Private fields
/// prevent external construction.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BoundarySession {
    /// Total boundary crossings in this session.
    crossing_count: u32,
    /// Whether the boundary effect is idempotent.
    is_idempotent: bool,
}

impl BoundarySession {
    /// Creates a new boundary session. Only callable within the crate.
    #[inline]
    #[allow(dead_code)]
    pub(crate) const fn new(is_idempotent: bool) -> Self {
        Self {
            crossing_count: 0,
            is_idempotent,
        }
    }

    /// Returns the total boundary crossings.
    #[inline]
    #[must_use]
    pub const fn crossing_count(&self) -> u32 {
        self.crossing_count
    }

    /// Returns whether the boundary effect is idempotent.
    #[inline]
    #[must_use]
    pub const fn is_idempotent(&self) -> bool {
        self.is_idempotent
    }
}

/// Validate a scalar grounding intermediate against a `GroundingShape`
/// and mint it into a `Datum`. Only callable within `uor-foundation`.
/// # Errors
/// Returns `ShapeViolation` if the coordinate fails validation.
#[allow(dead_code)]
pub(crate) fn validate_and_mint_coord(
    grounded: GroundedCoord,
    shape: &Validated<GroundingDeclaration>,
    session: &mut BoundarySession,
) -> Result<Datum, ShapeViolation> {
    // The Validated<GroundingDeclaration> proves the shape was already
    // validated at builder time. The coordinate's level is guaranteed
    // correct by the closed GroundedCoordInner enum — the type system
    // enforces that only supported levels can be constructed.
    let _ = shape; // shape validation passed at builder time
    session.crossing_count += 1;
    let inner = match grounded.inner {
        GroundedCoordInner::W8(b) => DatumInner::W8(b),
        GroundedCoordInner::W16(b) => DatumInner::W16(b),
        GroundedCoordInner::W24(b) => DatumInner::W24(b),
        GroundedCoordInner::W32(b) => DatumInner::W32(b),
    };
    Ok(Datum { inner })
}

/// Validate a tuple grounding intermediate and mint into a `Datum`.
/// Only callable within `uor-foundation`.
/// Mints the first coordinate of the tuple as the representative `Datum`.
/// Composite multi-coordinate `Datum` construction depends on the target
/// type's site decomposition, which is resolved during reduction evaluation.
/// # Errors
/// Returns `ShapeViolation` if the tuple is empty or fails validation.
#[allow(dead_code)]
pub(crate) fn validate_and_mint_tuple<const N: usize>(
    grounded: GroundedTuple<N>,
    shape: &Validated<GroundingDeclaration>,
    session: &mut BoundarySession,
) -> Result<Datum, ShapeViolation> {
    if N == 0 {
        return Err(ShapeViolation {
            shape_iri: shape.inner().shape_iri,
            constraint_iri: shape.inner().shape_iri,
            property_iri: "https://uor.foundation/conformance/groundingSourceType",
            expected_range: "https://uor.foundation/type/TypeDefinition",
            min_count: 1,
            max_count: 0,
            kind: ViolationKind::CardinalityViolation,
        });
    }
    // Mint the first coordinate as the representative Datum.
    // The full tuple is decomposed during reduction evaluation,
    // where each coordinate maps to a site in the constrained type.
    validate_and_mint_coord(grounded.coords[0].clone(), shape, session)
}

/// Evaluate a binary ring operation at compile time.
/// One helper is emitted per `schema:WittLevel` individual. The `uor!`
/// proc macro delegates to these helpers; it never performs ring
/// arithmetic itself.
/// # Examples
/// ```rust
/// use uor_foundation::enforcement::{const_ring_eval_w8, const_ring_eval_unary_w8};
/// use uor_foundation::PrimitiveOp;
///
/// // Ring arithmetic in Z/256Z: all operations wrap modulo 256.
///
/// // Addition wraps: 200 + 100 = 300 -> 300 - 256 = 44
/// assert_eq!(const_ring_eval_w8(PrimitiveOp::Add, 200, 100), 44);
///
/// // Multiplication: 3 * 5 = 15 (no wrap needed)
/// assert_eq!(const_ring_eval_w8(PrimitiveOp::Mul, 3, 5), 15);
///
/// // XOR: bitwise exclusive-or
/// assert_eq!(const_ring_eval_w8(PrimitiveOp::Xor, 0b1010, 0b1100), 0b0110);
///
/// // Negation: neg(x) = 256 - x (additive inverse in Z/256Z)
/// assert_eq!(const_ring_eval_unary_w8(PrimitiveOp::Neg, 1), 255);
///
/// // The critical identity: neg(bnot(x)) = succ(x) for all x
/// let x = 42u8;
/// let lhs = const_ring_eval_unary_w8(PrimitiveOp::Neg,
///     const_ring_eval_unary_w8(PrimitiveOp::Bnot, x));
/// let rhs = const_ring_eval_unary_w8(PrimitiveOp::Succ, x);
/// assert_eq!(lhs, rhs);
/// ```
#[inline]
#[must_use]
pub const fn const_ring_eval_w8(op: PrimitiveOp, a: u8, b: u8) -> u8 {
    match op {
        PrimitiveOp::Add => a.wrapping_add(b),
        PrimitiveOp::Sub => a.wrapping_sub(b),
        PrimitiveOp::Mul => a.wrapping_mul(b),
        PrimitiveOp::Xor => a ^ b,
        PrimitiveOp::And => a & b,
        PrimitiveOp::Or => a | b,
        _ => 0,
    }
}

#[inline]
#[must_use]
pub const fn const_ring_eval_unary_w8(op: PrimitiveOp, a: u8) -> u8 {
    match op {
        PrimitiveOp::Neg => 0u8.wrapping_sub(a),
        PrimitiveOp::Bnot => !a,
        PrimitiveOp::Succ => a.wrapping_add(1),
        PrimitiveOp::Pred => a.wrapping_sub(1),
        _ => 0,
    }
}

#[inline]
#[must_use]
pub const fn const_ring_eval_w16(op: PrimitiveOp, a: u16, b: u16) -> u16 {
    match op {
        PrimitiveOp::Add => a.wrapping_add(b),
        PrimitiveOp::Sub => a.wrapping_sub(b),
        PrimitiveOp::Mul => a.wrapping_mul(b),
        PrimitiveOp::Xor => a ^ b,
        PrimitiveOp::And => a & b,
        PrimitiveOp::Or => a | b,
        _ => 0,
    }
}

#[inline]
#[must_use]
pub const fn const_ring_eval_unary_w16(op: PrimitiveOp, a: u16) -> u16 {
    match op {
        PrimitiveOp::Neg => 0u16.wrapping_sub(a),
        PrimitiveOp::Bnot => !a,
        PrimitiveOp::Succ => a.wrapping_add(1),
        PrimitiveOp::Pred => a.wrapping_sub(1),
        _ => 0,
    }
}

#[inline]
#[must_use]
pub const fn const_ring_eval_w24(op: PrimitiveOp, a: u32, b: u32) -> u32 {
    const MASK: u32 = (18446744073709551615u64 >> (64 - 24)) as u32;
    match op {
        PrimitiveOp::Add => (a.wrapping_add(b)) & MASK,
        PrimitiveOp::Sub => (a.wrapping_sub(b)) & MASK,
        PrimitiveOp::Mul => (a.wrapping_mul(b)) & MASK,
        PrimitiveOp::Xor => (a ^ b) & MASK,
        PrimitiveOp::And => (a & b) & MASK,
        PrimitiveOp::Or => (a | b) & MASK,
        _ => 0,
    }
}

#[inline]
#[must_use]
pub const fn const_ring_eval_unary_w24(op: PrimitiveOp, a: u32) -> u32 {
    const MASK: u32 = (18446744073709551615u64 >> (64 - 24)) as u32;
    match op {
        PrimitiveOp::Neg => (0u32.wrapping_sub(a)) & MASK,
        PrimitiveOp::Bnot => (!a) & MASK,
        PrimitiveOp::Succ => (a.wrapping_add(1)) & MASK,
        PrimitiveOp::Pred => (a.wrapping_sub(1)) & MASK,
        _ => 0,
    }
}

#[inline]
#[must_use]
pub const fn const_ring_eval_w32(op: PrimitiveOp, a: u32, b: u32) -> u32 {
    match op {
        PrimitiveOp::Add => a.wrapping_add(b),
        PrimitiveOp::Sub => a.wrapping_sub(b),
        PrimitiveOp::Mul => a.wrapping_mul(b),
        PrimitiveOp::Xor => a ^ b,
        PrimitiveOp::And => a & b,
        PrimitiveOp::Or => a | b,
        _ => 0,
    }
}

#[inline]
#[must_use]
pub const fn const_ring_eval_unary_w32(op: PrimitiveOp, a: u32) -> u32 {
    match op {
        PrimitiveOp::Neg => 0u32.wrapping_sub(a),
        PrimitiveOp::Bnot => !a,
        PrimitiveOp::Succ => a.wrapping_add(1),
        PrimitiveOp::Pred => a.wrapping_sub(1),
        _ => 0,
    }
}

/// Sealed marker trait identifying types produced by the foundation crate's
/// conformance/reduction pipeline. v0.2.1 bounds `Validated<T>` on this trait
/// so downstream crates cannot fabricate `Validated<UserType>` — user types
/// cannot impl `OntologyTarget` because the supertrait is private.
pub trait OntologyTarget: ontology_target_sealed::Sealed {}

/// Sealed shim for `cert:GroundingCertificate`. Produced by GroundingAwareResolver.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct GroundingCertificate {
    witt_bits: u16,
}

impl Default for GroundingCertificate {
    #[inline]
    fn default() -> Self {
        Self { witt_bits: 32 }
    }
}

impl GroundingCertificate {
    /// Crate-internal constructor used by the pipeline to mint a
    /// certificate carrying the Witt level the pipeline advanced to.
    #[inline]
    #[must_use]
    #[allow(dead_code)]
    pub(crate) const fn with_witt_bits(witt_bits: u16) -> Self {
        Self { witt_bits }
    }

    /// Returns the Witt level the certificate was issued for. Sourced
    /// from the pipeline's `StageOutcome.witt_bits` at minting time.
    #[inline]
    #[must_use]
    pub const fn witt_bits(&self) -> u16 {
        self.witt_bits
    }
}

/// Sealed shim for `cert:LiftChainCertificate`. Carries the v0.2.1 `target_level()` accessor populated from the pipeline's StageOutcome.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct LiftChainCertificate {
    witt_bits: u16,
}

impl Default for LiftChainCertificate {
    #[inline]
    fn default() -> Self {
        Self { witt_bits: 32 }
    }
}

impl LiftChainCertificate {
    /// Crate-internal constructor used by the pipeline to mint a
    /// certificate carrying the Witt level the pipeline advanced to.
    #[inline]
    #[must_use]
    #[allow(dead_code)]
    pub(crate) const fn with_witt_bits(witt_bits: u16) -> Self {
        Self { witt_bits }
    }

    /// Returns the Witt level the certificate was issued for. Sourced
    /// from the pipeline's `StageOutcome.witt_bits` at minting time.
    #[inline]
    #[must_use]
    pub const fn witt_bits(&self) -> u16 {
        self.witt_bits
    }
}

/// Sealed shim for `cert:InhabitanceCertificate` (v0.2.1).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct InhabitanceCertificate {
    witt_bits: u16,
}

impl Default for InhabitanceCertificate {
    #[inline]
    fn default() -> Self {
        Self { witt_bits: 32 }
    }
}

impl InhabitanceCertificate {
    /// Crate-internal constructor used by the pipeline to mint a
    /// certificate carrying the Witt level the pipeline advanced to.
    #[inline]
    #[must_use]
    #[allow(dead_code)]
    pub(crate) const fn with_witt_bits(witt_bits: u16) -> Self {
        Self { witt_bits }
    }

    /// Returns the Witt level the certificate was issued for. Sourced
    /// from the pipeline's `StageOutcome.witt_bits` at minting time.
    #[inline]
    #[must_use]
    pub const fn witt_bits(&self) -> u16 {
        self.witt_bits
    }
}

/// Sealed shim for `cert:CompletenessCertificate`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct CompletenessCertificate {
    witt_bits: u16,
}

impl Default for CompletenessCertificate {
    #[inline]
    fn default() -> Self {
        Self { witt_bits: 32 }
    }
}

impl CompletenessCertificate {
    /// Crate-internal constructor used by the pipeline to mint a
    /// certificate carrying the Witt level the pipeline advanced to.
    #[inline]
    #[must_use]
    #[allow(dead_code)]
    pub(crate) const fn with_witt_bits(witt_bits: u16) -> Self {
        Self { witt_bits }
    }

    /// Returns the Witt level the certificate was issued for. Sourced
    /// from the pipeline's `StageOutcome.witt_bits` at minting time.
    #[inline]
    #[must_use]
    pub const fn witt_bits(&self) -> u16 {
        self.witt_bits
    }
}

/// Sealed shim for `proof:ImpossibilityWitness`. Returned by completeness and grounding resolvers on failure.
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash)]
pub struct GenericImpossibilityWitness {
    _private: (),
}

/// Sealed shim for `proof:InhabitanceImpossibilityWitness` (v0.2.1).
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash)]
pub struct InhabitanceImpossibilityWitness {
    _private: (),
}

/// Input shim for `type:ConstrainedType`. Used as `Certify::Input` for InhabitanceResolver, TowerCompletenessResolver, and IncrementalCompletenessResolver.
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash)]
pub struct ConstrainedTypeInput {
    _private: (),
}

impl LiftChainCertificate {
    /// Returns the Witt level the certificate was issued for.
    #[inline]
    #[must_use]
    pub const fn target_level(&self) -> WittLevel {
        WittLevel::new(self.witt_bits as u32)
    }
}

impl InhabitanceCertificate {
    /// Returns the witness value tuple bytes when `verified` is true.
    /// v0.2.1 returns `None` on the shim; real witnesses come from the
    /// macro back-door path.
    #[inline]
    #[must_use]
    pub const fn witness(&self) -> Option<&'static [u8]> {
        None
    }
}

mod ontology_target_sealed {
    /// Private supertrait. Not implementable outside this crate.
    pub trait Sealed {}
    impl Sealed for super::GroundingCertificate {}
    impl Sealed for super::LiftChainCertificate {}
    impl Sealed for super::InhabitanceCertificate {}
    impl Sealed for super::CompletenessCertificate {}
    impl Sealed for super::GenericImpossibilityWitness {}
    impl Sealed for super::InhabitanceImpossibilityWitness {}
    impl Sealed for super::ConstrainedTypeInput {}
    impl Sealed for super::CompileUnit {}
}

impl OntologyTarget for GroundingCertificate {}
impl OntologyTarget for LiftChainCertificate {}
impl OntologyTarget for InhabitanceCertificate {}
impl OntologyTarget for CompletenessCertificate {}
impl OntologyTarget for GenericImpossibilityWitness {}
impl OntologyTarget for InhabitanceImpossibilityWitness {}
impl OntologyTarget for ConstrainedTypeInput {}
impl OntologyTarget for CompileUnit {}

/// Sealed marker trait identifying type:ConstrainedType subclasses that may
/// appear as the parameter of `Grounded<T>`. Downstream crates implement
/// this via `#[derive(ConstrainedType)]` from `uor-foundation-macros`,
/// which gates impl emission through a back-door macro path.
/// Back-door supertrait for `GroundedShape`. Reachable via
/// `uor_foundation::enforcement::__macro_internals::GroundedShapeSealed`.
/// Only `#[derive(ConstrainedType)]` is supposed to impl it.
#[doc(hidden)]
pub mod __macro_internals {
    /// Sealed supertrait of `GroundedShape`. Not part of the stable API.
    pub trait GroundedShapeSealed {}
    /// Built-in impl for the foundation's own ConstrainedTypeInput shim.
    impl GroundedShapeSealed for super::ConstrainedTypeInput {}
}
pub trait GroundedShape: __macro_internals::GroundedShapeSealed {}
impl<T: __macro_internals::GroundedShapeSealed> GroundedShape for T {}

/// A binding entry in a `BindingsTable`. Pairs an address (u128 content
/// hash of the query coordinate) with the bound bytes.
#[derive(Debug, Clone, Copy)]
pub struct BindingEntry {
    /// Content-hashed query address.
    pub address: u128,
    /// Bound payload bytes (length determined by the WittLevel of the table).
    pub bytes: &'static [u8],
}

/// A static, sorted-by-address binding table laid out for `op:GS_5` zero-step
/// access. Looked up via binary search; the foundation guarantees the table
/// is materialized at compile time from the attested `state:GroundedContext`.
#[derive(Debug, Clone, Copy)]
pub struct BindingsTable {
    /// Entries, sorted ascending by `address`.
    pub entries: &'static [BindingEntry],
}

impl BindingsTable {
    /// Construct a `BindingsTable` from a sorted slice. Caller must ensure
    /// ascending order; this is `pub(crate)` so only the macro back-door
    /// path can construct one.
    #[inline]
    #[must_use]
    #[allow(dead_code)]
    pub(crate) const fn new(entries: &'static [BindingEntry]) -> Self {
        Self { entries }
    }
}

/// The compile-time witness that `op:GS_4` holds for the value it carries:
/// σ = 1, freeRank = 0, S = 0, T_ctx = 0. `Grounded<T>` is constructed only
/// by the reduction pipeline (or by `uor_ground!` macro expansion) and
/// provides `op:GS_5` zero-step binding access.
/// The `T` parameter is informational — it enables distinct static types for
/// distinct grounded shapes (so `Grounded<PixelQ8>` and `Grounded<MatrixRowQ32>`
/// are not interchangeable) — and does not affect memory layout.
#[derive(Debug, Clone)]
pub struct Grounded<T: GroundedShape> {
    /// The validated grounding certificate this wrapper carries.
    validated: Validated<GroundingCertificate>,
    /// The compile-time-materialized bindings table.
    bindings: BindingsTable,
    /// The Witt level the grounded value was minted at.
    witt_level_bits: u16,
    /// Content-address of the originating CompileUnit.
    unit_address: u128,
    /// Phantom type tying this `Grounded` to a specific `ConstrainedType`.
    _phantom: PhantomData<T>,
}

impl<T: GroundedShape> Grounded<T> {
    /// Returns the binding for the given query address, or `None` if not in
    /// the table. Resolves in O(log n) via binary search; for true `op:GS_5`
    /// zero-step access, downstream code uses statically-known indices.
    #[inline]
    #[must_use]
    pub fn get_binding(&self, address: u128) -> Option<&'static [u8]> {
        self.bindings
            .entries
            .binary_search_by_key(&address, |e| e.address)
            .ok()
            .map(|i| self.bindings.entries[i].bytes)
    }

    /// Iterate over all bindings in this grounded context.
    #[inline]
    pub fn iter_bindings(&self) -> impl Iterator<Item = &BindingEntry> + '_ {
        self.bindings.entries.iter()
    }

    /// Returns the Witt level the grounded value was minted at.
    #[inline]
    #[must_use]
    pub const fn witt_level_bits(&self) -> u16 {
        self.witt_level_bits
    }

    /// Returns the content-address of the originating CompileUnit.
    #[inline]
    #[must_use]
    pub const fn unit_address(&self) -> u128 {
        self.unit_address
    }

    /// Returns the validated grounding certificate this wrapper carries.
    #[inline]
    #[must_use]
    pub const fn certificate(&self) -> &Validated<GroundingCertificate> {
        &self.validated
    }

    /// Crate-internal constructor used by the macro back-door minting path.
    /// Not callable from outside `uor-foundation` or its trusted macro crate.
    #[inline]
    #[allow(dead_code)]
    pub(crate) const fn new_internal(
        validated: Validated<GroundingCertificate>,
        bindings: BindingsTable,
        witt_level_bits: u16,
        unit_address: u128,
    ) -> Self {
        Self {
            validated,
            bindings,
            witt_level_bits,
            unit_address,
            _phantom: PhantomData,
        }
    }
}

/// The Rust-surface rendering of `reduction:PipelineFailureReason` and the
/// v0.2.1 cross-namespace failure variants. Variant set and field shapes are
/// generated parametrically by walking `reduction:FailureField` individuals;
/// adding a new field requires only an ontology edit.
#[derive(Debug, Clone, PartialEq)]
#[non_exhaustive]
pub enum PipelineFailure {
    /// `DispatchMiss` failure variant.
    DispatchMiss {
        /// query_iri field.
        query_iri: &'static str,
        /// table_iri field.
        table_iri: &'static str,
    },
    /// `GroundingFailure` failure variant.
    GroundingFailure {
        /// reason_iri field.
        reason_iri: &'static str,
    },
    /// `ConvergenceStall` failure variant.
    ConvergenceStall {
        /// stage_iri field.
        stage_iri: &'static str,
        /// angle_milliradians field.
        angle_milliradians: i64,
    },
    /// `ContradictionDetected` failure variant.
    ContradictionDetected {
        /// at_step field.
        at_step: usize,
        /// trace_iri field.
        trace_iri: &'static str,
    },
    /// `CoherenceViolation` failure variant.
    CoherenceViolation {
        /// site_position field.
        site_position: usize,
        /// constraint_iri field.
        constraint_iri: &'static str,
    },
    /// `LiftObstructionFailure` failure variant.
    LiftObstructionFailure {
        /// site_position field.
        site_position: usize,
        /// obstruction_class_iri field.
        obstruction_class_iri: &'static str,
    },
    /// `ShapeViolation` failure variant.
    ShapeViolation {
        /// report field.
        report: ShapeViolation,
    },
}

impl core::fmt::Display for PipelineFailure {
    fn fmt(&self, ff: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            Self::DispatchMiss {
                query_iri,
                table_iri,
            } => write!(
                ff,
                "DispatchMiss(query_iri={:?}, table_iri={:?})",
                query_iri, table_iri
            ),
            Self::GroundingFailure { reason_iri } => {
                write!(ff, "GroundingFailure(reason_iri={:?})", reason_iri)
            }
            Self::ConvergenceStall {
                stage_iri,
                angle_milliradians,
            } => write!(
                ff,
                "ConvergenceStall(stage_iri={:?}, angle_milliradians={:?})",
                stage_iri, angle_milliradians
            ),
            Self::ContradictionDetected { at_step, trace_iri } => write!(
                ff,
                "ContradictionDetected(at_step={:?}, trace_iri={:?})",
                at_step, trace_iri
            ),
            Self::CoherenceViolation {
                site_position,
                constraint_iri,
            } => write!(
                ff,
                "CoherenceViolation(site_position={:?}, constraint_iri={:?})",
                site_position, constraint_iri
            ),
            Self::LiftObstructionFailure {
                site_position,
                obstruction_class_iri,
            } => write!(
                ff,
                "LiftObstructionFailure(site_position={:?}, obstruction_class_iri={:?})",
                site_position, obstruction_class_iri
            ),
            Self::ShapeViolation { report } => write!(ff, "ShapeViolation({:?})", report),
        }
    }
}

/// Sealed marker for impossibility witnesses (failure return type of `Certify`).
pub trait ImpossibilityWitnessKind: impossibility_witness_kind_sealed::Sealed {}

mod impossibility_witness_kind_sealed {
    /// Private supertrait.
    pub trait Sealed {}
    impl Sealed for super::GenericImpossibilityWitness {}
    impl Sealed for super::InhabitanceImpossibilityWitness {}
}

impl ImpossibilityWitnessKind for GenericImpossibilityWitness {}
impl ImpossibilityWitnessKind for InhabitanceImpossibilityWitness {}

/// The v0.2.1 verdict-producing trait. Each resolver façade impls `Certify`
/// to expose the consumer-facing one-liner:
/// ```rust,ignore
/// use uor_foundation::enforcement::*;
/// use uor_foundation::pipeline::ConstrainedTypeShape;
/// #[derive(ConstrainedType, Default)]
/// struct Shape;
/// let cert: Validated<LiftChainCertificate> =
///     TowerCompletenessResolver::new().certify(&Shape)?;
/// let level: WittLevel = cert.target_level();
/// ```
/// `Certify` is generic over the input type `I` so any user type
/// implementing `ConstrainedTypeShape` (via `#[derive(ConstrainedType)]`)
/// flows through the pipeline directly. The associated `Certificate` and
/// `Witness` types are sealed via `OntologyTarget` / `ImpossibilityWitnessKind`.
pub trait Certify<I: ?Sized> {
    /// The certificate type returned on success.
    type Certificate: OntologyTarget;
    /// The impossibility witness type returned on failure.
    type Witness: ImpossibilityWitnessKind;

    /// The default Witt level this resolver certifies at when the
    /// caller omits an explicit level via `certify`. v0.2.1 uses
    /// `WittLevel::W32` as the canonical default per ergonomics-spec §3.2.
    const DEFAULT_LEVEL: WittLevel = WittLevel::W32;

    /// Run the resolver on `input` at the default Witt level and return
    /// either a validated certificate or an impossibility witness.
    /// # Errors
    /// Returns `Self::Witness` when the resolver determines that no
    /// certificate can be issued for `input`.
    fn certify(&self, input: &I) -> Result<Validated<Self::Certificate>, Self::Witness> {
        self.certify_at(input, Self::DEFAULT_LEVEL)
    }

    /// Run the resolver on `input` at an explicit Witt level.
    /// # Errors
    /// Returns `Self::Witness` when the resolver determines that no
    /// certificate can be issued for `input` at `level`.
    fn certify_at(
        &self,
        input: &I,
        level: WittLevel,
    ) -> Result<Validated<Self::Certificate>, Self::Witness>;
}

/// v0.2.1 unit-struct façade for the `TowerCompletenessResolver` resolver class.
/// Constructed via `TowerCompletenessResolver::new()`. Implements `Certify` so the
/// foundation's verdict surface is reachable as a single one-liner.
#[derive(Debug, Default, Clone, Copy)]
pub struct TowerCompletenessResolver;

impl TowerCompletenessResolver {
    /// Construct a new resolver façade.
    #[inline]
    #[must_use]
    pub const fn new() -> Self {
        Self
    }
}

impl<__T: crate::pipeline::ConstrainedTypeShape + ?Sized> Certify<__T>
    for TowerCompletenessResolver
{
    type Certificate = LiftChainCertificate;
    type Witness = GenericImpossibilityWitness;
    fn certify_at(
        &self,
        input: &__T,
        level: WittLevel,
    ) -> Result<Validated<Self::Certificate>, Self::Witness> {
        crate::pipeline::run_tower_completeness(input, level)
            .map_err(|_| GenericImpossibilityWitness::default())
    }
}

/// v0.2.1 unit-struct façade for the `IncrementalCompletenessResolver` resolver class.
/// Constructed via `IncrementalCompletenessResolver::new()`. Implements `Certify` so the
/// foundation's verdict surface is reachable as a single one-liner.
#[derive(Debug, Default, Clone, Copy)]
pub struct IncrementalCompletenessResolver;

impl IncrementalCompletenessResolver {
    /// Construct a new resolver façade.
    #[inline]
    #[must_use]
    pub const fn new() -> Self {
        Self
    }
}

impl<__T: crate::pipeline::ConstrainedTypeShape + ?Sized> Certify<__T>
    for IncrementalCompletenessResolver
{
    type Certificate = LiftChainCertificate;
    type Witness = GenericImpossibilityWitness;
    fn certify_at(
        &self,
        input: &__T,
        level: WittLevel,
    ) -> Result<Validated<Self::Certificate>, Self::Witness> {
        crate::pipeline::run_incremental_completeness(input, level)
            .map_err(|_| GenericImpossibilityWitness::default())
    }
}

/// v0.2.1 unit-struct façade for the `GroundingAwareResolver` resolver class.
/// Constructed via `GroundingAwareResolver::new()`. Implements `Certify` so the
/// foundation's verdict surface is reachable as a single one-liner.
#[derive(Debug, Default, Clone, Copy)]
pub struct GroundingAwareResolver;

impl GroundingAwareResolver {
    /// Construct a new resolver façade.
    #[inline]
    #[must_use]
    pub const fn new() -> Self {
        Self
    }
}

impl Certify<CompileUnit> for GroundingAwareResolver {
    type Certificate = GroundingCertificate;
    type Witness = GenericImpossibilityWitness;
    fn certify_at(
        &self,
        input: &CompileUnit,
        level: WittLevel,
    ) -> Result<Validated<Self::Certificate>, Self::Witness> {
        crate::pipeline::run_grounding_aware(input, level)
            .map_err(|_| GenericImpossibilityWitness::default())
    }
}

/// v0.2.1 unit-struct façade for the `InhabitanceResolver` resolver class.
/// Constructed via `InhabitanceResolver::new()`. Implements `Certify` so the
/// foundation's verdict surface is reachable as a single one-liner.
#[derive(Debug, Default, Clone, Copy)]
pub struct InhabitanceResolver;

impl InhabitanceResolver {
    /// Construct a new resolver façade.
    #[inline]
    #[must_use]
    pub const fn new() -> Self {
        Self
    }
}

impl<__T: crate::pipeline::ConstrainedTypeShape + ?Sized> Certify<__T> for InhabitanceResolver {
    type Certificate = InhabitanceCertificate;
    type Witness = InhabitanceImpossibilityWitness;
    fn certify_at(
        &self,
        input: &__T,
        level: WittLevel,
    ) -> Result<Validated<Self::Certificate>, Self::Witness> {
        crate::pipeline::run_inhabitance(input, level)
    }
}

/// v0.2.1 phantom-typed ring operation surface. Each phantom struct binds a
/// `WittLevel` at the type level so consumers can write
/// `Mul::<W8>::apply(a, b)` for compile-time level-checked arithmetic.
pub trait RingOp<L> {
    /// Operand type at this level.
    type Operand;
    /// Apply this binary ring op.
    fn apply(a: Self::Operand, b: Self::Operand) -> Self::Operand;
}

/// Multiplicative ring op. phantom-typed at level `L`.
#[derive(Debug, Default, Clone, Copy)]
pub struct Mul<L>(PhantomData<L>);

/// Additive ring op. phantom-typed at level `L`.
#[derive(Debug, Default, Clone, Copy)]
pub struct Add<L>(PhantomData<L>);

/// Subtractive ring op. phantom-typed at level `L`.
#[derive(Debug, Default, Clone, Copy)]
pub struct Sub<L>(PhantomData<L>);

/// Bitwise XOR ring op. phantom-typed at level `L`.
#[derive(Debug, Default, Clone, Copy)]
pub struct Xor<L>(PhantomData<L>);

/// Bitwise AND ring op. phantom-typed at level `L`.
#[derive(Debug, Default, Clone, Copy)]
pub struct And<L>(PhantomData<L>);

/// Bitwise OR ring op. phantom-typed at level `L`.
#[derive(Debug, Default, Clone, Copy)]
pub struct Or<L>(PhantomData<L>);

/// W8 marker — 8-bit Witt level reified at the type level.
#[derive(Debug, Default, Clone, Copy)]
pub struct W8;

/// W16 marker — 16-bit Witt level reified at the type level.
#[derive(Debug, Default, Clone, Copy)]
pub struct W16;

/// W24 marker — 24-bit Witt level reified at the type level.
#[derive(Debug, Default, Clone, Copy)]
pub struct W24;

/// W32 marker — 32-bit Witt level reified at the type level.
#[derive(Debug, Default, Clone, Copy)]
pub struct W32;

impl RingOp<W8> for Mul<W8> {
    type Operand = u8;
    #[inline]
    fn apply(a: u8, b: u8) -> u8 {
        const_ring_eval_w8(PrimitiveOp::Mul, a, b)
    }
}

impl RingOp<W8> for Add<W8> {
    type Operand = u8;
    #[inline]
    fn apply(a: u8, b: u8) -> u8 {
        const_ring_eval_w8(PrimitiveOp::Add, a, b)
    }
}

impl RingOp<W8> for Sub<W8> {
    type Operand = u8;
    #[inline]
    fn apply(a: u8, b: u8) -> u8 {
        const_ring_eval_w8(PrimitiveOp::Sub, a, b)
    }
}

impl RingOp<W8> for Xor<W8> {
    type Operand = u8;
    #[inline]
    fn apply(a: u8, b: u8) -> u8 {
        const_ring_eval_w8(PrimitiveOp::Xor, a, b)
    }
}

impl RingOp<W8> for And<W8> {
    type Operand = u8;
    #[inline]
    fn apply(a: u8, b: u8) -> u8 {
        const_ring_eval_w8(PrimitiveOp::And, a, b)
    }
}

impl RingOp<W8> for Or<W8> {
    type Operand = u8;
    #[inline]
    fn apply(a: u8, b: u8) -> u8 {
        const_ring_eval_w8(PrimitiveOp::Or, a, b)
    }
}

impl RingOp<W16> for Mul<W16> {
    type Operand = u16;
    #[inline]
    fn apply(a: u16, b: u16) -> u16 {
        const_ring_eval_w16(PrimitiveOp::Mul, a, b)
    }
}

impl RingOp<W16> for Add<W16> {
    type Operand = u16;
    #[inline]
    fn apply(a: u16, b: u16) -> u16 {
        const_ring_eval_w16(PrimitiveOp::Add, a, b)
    }
}

impl RingOp<W16> for Sub<W16> {
    type Operand = u16;
    #[inline]
    fn apply(a: u16, b: u16) -> u16 {
        const_ring_eval_w16(PrimitiveOp::Sub, a, b)
    }
}

impl RingOp<W16> for Xor<W16> {
    type Operand = u16;
    #[inline]
    fn apply(a: u16, b: u16) -> u16 {
        const_ring_eval_w16(PrimitiveOp::Xor, a, b)
    }
}

impl RingOp<W16> for And<W16> {
    type Operand = u16;
    #[inline]
    fn apply(a: u16, b: u16) -> u16 {
        const_ring_eval_w16(PrimitiveOp::And, a, b)
    }
}

impl RingOp<W16> for Or<W16> {
    type Operand = u16;
    #[inline]
    fn apply(a: u16, b: u16) -> u16 {
        const_ring_eval_w16(PrimitiveOp::Or, a, b)
    }
}

impl RingOp<W24> for Mul<W24> {
    type Operand = u32;
    #[inline]
    fn apply(a: u32, b: u32) -> u32 {
        const_ring_eval_w24(PrimitiveOp::Mul, a, b)
    }
}

impl RingOp<W24> for Add<W24> {
    type Operand = u32;
    #[inline]
    fn apply(a: u32, b: u32) -> u32 {
        const_ring_eval_w24(PrimitiveOp::Add, a, b)
    }
}

impl RingOp<W24> for Sub<W24> {
    type Operand = u32;
    #[inline]
    fn apply(a: u32, b: u32) -> u32 {
        const_ring_eval_w24(PrimitiveOp::Sub, a, b)
    }
}

impl RingOp<W24> for Xor<W24> {
    type Operand = u32;
    #[inline]
    fn apply(a: u32, b: u32) -> u32 {
        const_ring_eval_w24(PrimitiveOp::Xor, a, b)
    }
}

impl RingOp<W24> for And<W24> {
    type Operand = u32;
    #[inline]
    fn apply(a: u32, b: u32) -> u32 {
        const_ring_eval_w24(PrimitiveOp::And, a, b)
    }
}

impl RingOp<W24> for Or<W24> {
    type Operand = u32;
    #[inline]
    fn apply(a: u32, b: u32) -> u32 {
        const_ring_eval_w24(PrimitiveOp::Or, a, b)
    }
}

impl RingOp<W32> for Mul<W32> {
    type Operand = u32;
    #[inline]
    fn apply(a: u32, b: u32) -> u32 {
        const_ring_eval_w32(PrimitiveOp::Mul, a, b)
    }
}

impl RingOp<W32> for Add<W32> {
    type Operand = u32;
    #[inline]
    fn apply(a: u32, b: u32) -> u32 {
        const_ring_eval_w32(PrimitiveOp::Add, a, b)
    }
}

impl RingOp<W32> for Sub<W32> {
    type Operand = u32;
    #[inline]
    fn apply(a: u32, b: u32) -> u32 {
        const_ring_eval_w32(PrimitiveOp::Sub, a, b)
    }
}

impl RingOp<W32> for Xor<W32> {
    type Operand = u32;
    #[inline]
    fn apply(a: u32, b: u32) -> u32 {
        const_ring_eval_w32(PrimitiveOp::Xor, a, b)
    }
}

impl RingOp<W32> for And<W32> {
    type Operand = u32;
    #[inline]
    fn apply(a: u32, b: u32) -> u32 {
        const_ring_eval_w32(PrimitiveOp::And, a, b)
    }
}

impl RingOp<W32> for Or<W32> {
    type Operand = u32;
    #[inline]
    fn apply(a: u32, b: u32) -> u32 {
        const_ring_eval_w32(PrimitiveOp::Or, a, b)
    }
}

/// Sealed marker trait for fragment classifiers (Is2SatShape, IsHornShape,
/// IsResidualFragment) emitted parametrically from the predicate individuals
/// referenced by `predicate:InhabitanceDispatchTable`.
pub trait FragmentMarker: fragment_sealed::Sealed {}

mod fragment_sealed {
    /// Private supertrait.
    pub trait Sealed {}
    impl Sealed for super::Is2SatShape {}
    impl Sealed for super::IsHornShape {}
    impl Sealed for super::IsResidualFragment {}
}

/// Fragment marker for `predicate:Is2SatShape`. Zero-sized.
#[derive(Debug, Default, Clone, Copy)]
pub struct Is2SatShape;
impl FragmentMarker for Is2SatShape {}

/// Fragment marker for `predicate:IsHornShape`. Zero-sized.
#[derive(Debug, Default, Clone, Copy)]
pub struct IsHornShape;
impl FragmentMarker for IsHornShape {}

/// Fragment marker for `predicate:IsResidualFragment`. Zero-sized.
#[derive(Debug, Default, Clone, Copy)]
pub struct IsResidualFragment;
impl FragmentMarker for IsResidualFragment {}

/// A single dispatch rule entry pairing a predicate IRI, a target resolver
/// name, and an evaluation priority.
#[derive(Debug, Clone, Copy)]
pub struct DispatchRule {
    /// IRI of the predicate that selects this rule.
    pub predicate_iri: &'static str,
    /// IRI of the target resolver class invoked when the predicate holds.
    pub target_resolver_iri: &'static str,
    /// Evaluation order; lower values evaluate first.
    pub priority: u32,
}

/// A static dispatch table — an ordered slice of `DispatchRule` entries.
pub type DispatchTable = &'static [DispatchRule];

/// v0.2.1 dispatch table generated from `predicate:InhabitanceDispatchTable`.
pub const INHABITANCE_DISPATCH_TABLE: DispatchTable = &[
    DispatchRule {
        predicate_iri: "https://uor.foundation/predicate/Is2SatShape",
        target_resolver_iri: "https://uor.foundation/resolver/TwoSatDecider",
        priority: 0,
    },
    DispatchRule {
        predicate_iri: "https://uor.foundation/predicate/IsHornShape",
        target_resolver_iri: "https://uor.foundation/resolver/HornSatDecider",
        priority: 1,
    },
    DispatchRule {
        predicate_iri: "https://uor.foundation/predicate/IsResidualFragment",
        target_resolver_iri: "https://uor.foundation/resolver/ResidualVerdictResolver",
        priority: 2,
    },
];

/// v0.2.1 `Deref` impl for `Validated<T: OntologyTarget>` so consumers can call
/// certificate methods directly: `cert.target_level()` rather than
/// `cert.inner().target_level()`. The bound `T: OntologyTarget` keeps the
/// auto-deref scoped to foundation-produced types.
impl<T: OntologyTarget> core::ops::Deref for Validated<T> {
    type Target = T;
    #[inline]
    fn deref(&self) -> &T {
        &self.inner
    }
}

/// Provenance witness sealing the macro back-door minting path. The only
/// constructor is `__for_macro_crate`, named with the reserved
/// `__uor_macro_*` prefix so the `uor::unsealed_grounded` lint can flag any
/// call site outside the foundation's macro crate at review time. The
/// proc-macro crate emits these calls inside generated token streams that
/// are visible in `cargo expand` output.
#[doc(hidden)]
#[derive(Debug, Clone, Copy)]
pub struct MacroProvenance {
    _marker: (),
}

impl MacroProvenance {
    /// The only constructor. Reachable only from `uor-foundation-macros`
    /// via the `__for_macro_crate` symbol naming convention; the
    /// `uor::unsealed_grounded` lint flags any call site outside the
    /// approved modules.
    #[doc(hidden)]
    #[inline]
    #[must_use]
    pub const fn __for_macro_crate() -> Self {
        Self { _marker: () }
    }
}

/// Back-door constructor for `Validated<T>`. Reachable only from macro-
/// generated token streams.
#[doc(hidden)]
#[inline]
pub fn __uor_macro_mint_validated<T: OntologyTarget>(
    _prov: MacroProvenance,
    inner: T,
) -> Validated<T> {
    Validated { inner, _sealed: () }
}

/// Back-door constructor for `Grounded<T>`. Reachable only from macro-
/// generated token streams.
#[doc(hidden)]
#[inline]
pub fn __uor_macro_mint_grounded<T: GroundedShape>(
    _prov: MacroProvenance,
    validated: Validated<GroundingCertificate>,
    bindings: BindingsTable,
    witt_level_bits: u16,
    unit_address: u128,
) -> Grounded<T> {
    Grounded::new_internal(validated, bindings, witt_level_bits, unit_address)
}

/// v0.2.1 ergonomics prelude. Re-exports the core symbols downstream crates
/// need for the consumer-facing one-liners.
/// Ontology-driven: the set of certificate / type / builder symbols is
/// sourced from `conformance:PreludeExport` individuals. Adding a new
/// symbol to the prelude is an ontology edit, verified against the
/// codegen's known-name mapping at build time.
pub mod prelude {
    pub use super::Add;
    pub use super::And;
    pub use super::BindingEntry;
    pub use super::BindingsTable;
    pub use super::Certify;
    pub use super::CompileUnit;
    pub use super::CompileUnitBuilder;
    pub use super::CompletenessCertificate;
    pub use super::ConstrainedTypeInput;
    pub use super::Datum;
    pub use super::FragmentMarker;
    pub use super::GenericImpossibilityWitness;
    pub use super::Grounded;
    pub use super::GroundedShape;
    pub use super::GroundingAwareResolver;
    pub use super::GroundingCertificate;
    pub use super::ImpossibilityWitnessKind;
    pub use super::IncrementalCompletenessResolver;
    pub use super::InhabitanceCertificate;
    pub use super::InhabitanceImpossibilityWitness;
    pub use super::InhabitanceResolver;
    pub use super::LiftChainCertificate;
    pub use super::Mul;
    pub use super::OntologyTarget;
    pub use super::Or;
    pub use super::PipelineFailure;
    pub use super::RingOp;
    pub use super::ShapeViolation;
    pub use super::Sub;
    pub use super::Term;
    pub use super::TermArena;
    pub use super::TowerCompletenessResolver;
    pub use super::Validated;
    pub use super::Xor;
    pub use super::W16;
    pub use super::W8;
    pub use crate::{Primitives, WittLevel};
    pub use uor_foundation_macros::uor;
}