uor-foundation 0.1.5

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

//! Declarative enforcement types.
//!
//! This module contains the opaque witness types, declarative builders,
//! and Term AST that form the declarative enforcement surface of the
//! UOR Foundation crate. Prism code consumes these types but cannot
//! construct the sealed ones directly.
//!
//! # Layers
//!
//! - **Layer 1** \[Opaque Witnesses\]: `Datum`, `Validated<T>`, `Derivation`,
//!   `FiberBudget` \[private fields, no public constructors\]
//! - **Layer 2** \[Declarative Builders\]: `CompileUnitBuilder`,
//!   `EffectDeclarationBuilder`, etc. \[produce `Validated<T>` on success\]
//! - **Term AST**: `Term`, `TermArena`, `Binding`, `Assertion`, etc.

use crate::{PrimitiveOp, QuantumLevel, VerificationDomain, ViolationKind};

/// 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 quantum level.
/// Not publicly constructible \[sealed within the crate\].
#[derive(Debug, Clone, PartialEq, Eq)]
#[allow(clippy::large_enum_variant, dead_code)]
pub(crate) enum DatumInner {
    /// Q0: 8-bit ring Z/256Z.
    Q0([u8; 1]),
    /// Q1: 16-bit ring Z/65536Z.
    Q1([u8; 2]),
    /// Q3: 32-bit ring Z/2^32Z.
    Q3([u8; 4]),
    /// Q7: 64-bit ring Z/2^64Z.
    Q7([u8; 8]),
    /// Q511: 4096-bit ring Z/2^4096Z.
    Q511([u8; 512]),
}

/// A ring element at its minting quantum level.
/// Cannot be constructed outside the `uor_foundation` crate.
/// The only way to obtain a `Datum` is through cascade evaluation
/// or the two-phase minting boundary (`validate_and_mint_coord` /
/// `validate_and_mint_tuple`).
/// # Examples
/// ```rust,ignore
/// // A Datum is produced by cascade evaluation or the minting boundary —
/// // you never construct one directly.
/// fn inspect_datum(d: &uor_foundation::enforcement::Datum) {
///     // Query its quantum level (Q0 = 8-bit, Q7 = 64-bit, etc.)
///     let level = d.level();
///
///     // Datum width is determined by its level:
///     //   Q0 → 1 byte,  Q1 → 2 bytes,  Q3 → 4 bytes,
///     //   Q7 → 8 bytes, Q511 → 512 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 quantum level at which this datum was minted.
    #[inline]
    #[must_use]
    pub const fn level(&self) -> QuantumLevel {
        match self.inner {
            DatumInner::Q0(_) => QuantumLevel::Q0,
            DatumInner::Q1(_) => QuantumLevel::Q1,
            DatumInner::Q3(_) => QuantumLevel::new(3),
            DatumInner::Q7(_) => QuantumLevel::new(7),
            DatumInner::Q511(_) => QuantumLevel::new(511),
        }
    }

    /// Returns the raw byte representation of this datum.
    #[inline]
    #[must_use]
    pub fn as_bytes(&self) -> &[u8] {
        match &self.inner {
            DatumInner::Q0(b) => b,
            DatumInner::Q1(b) => b,
            DatumInner::Q3(b) => b,
            DatumInner::Q7(b) => b,
            DatumInner::Q511(b) => b,
        }
    }
}

/// Internal level-tagged coordinate value for grounding intermediates.
#[derive(Debug, Clone, PartialEq, Eq)]
#[allow(clippy::large_enum_variant, dead_code)]
pub(crate) enum GroundedCoordInner {
    /// Q0: 8-bit coordinate.
    Q0([u8; 1]),
    /// Q1: 16-bit coordinate.
    Q1([u8; 2]),
    /// Q3: 32-bit coordinate.
    Q3([u8; 4]),
    /// Q7: 64-bit coordinate.
    Q7([u8; 8]),
    /// Q511: 4096-bit coordinate.
    Q511([u8; 512]),
}

/// 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 quantum level.
/// # Examples
/// ```rust
/// use uor_foundation::enforcement::GroundedCoord;
///
/// // Q0: 8-bit ring Z/256Z — lightweight, exhaustive-verification baseline
/// let byte_coord = GroundedCoord::q0(42);
///
/// // Q1: 16-bit ring Z/65536Z — audio samples, small indices
/// let short_coord = GroundedCoord::q1(1000);
///
/// // Q3: 32-bit ring Z/2^32Z — pixel data, general-purpose integers
/// let word_coord = GroundedCoord::q3(70_000);
///
/// // Q7: 64-bit ring Z/2^64Z — cryptographic hashes, content addresses
/// let wide_coord = GroundedCoord::q7(0xDEAD_BEEF_CAFE_BABE);
///
/// // Q511: 4096-bit ring Z/2^4096Z — cryptographic/verification workloads
/// let huge_coord = GroundedCoord::q511([0u8; 512]);
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct GroundedCoord {
    /// Level-tagged coordinate bytes.
    pub(crate) inner: GroundedCoordInner,
}

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

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

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

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

    /// Construct a Q511 coordinate from a 512-byte array (little-endian).
    #[inline]
    #[must_use]
    pub const fn q511(bytes: [u8; 512]) -> Self {
        Self {
            inner: GroundedCoordInner::Q511(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 Q0 (8-bit per channel)
/// let pixel = GroundedTuple::new([
///     GroundedCoord::q0(255), // red channel
///     GroundedCoord::q0(128), // green channel
/// ]);
///
/// // An E8 lattice point: 8 coordinates at Q0
/// let lattice_point = GroundedTuple::new([
///     GroundedCoord::q0(2), GroundedCoord::q0(0),
///     GroundedCoord::q0(0), GroundedCoord::q0(0),
///     GroundedCoord::q0(0), GroundedCoord::q0(0),
///     GroundedCoord::q0(0), GroundedCoord::q0(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::q0(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::{QuantumLevel, 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: QuantumLevel::Q0 }];
/// let domains = [VerificationDomain::Enumerative];
///
/// let validated = CompileUnitBuilder::new()
///     .root_term(&terms)
///     .quantum_level_ceiling(QuantumLevel::Q0)
///     .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 fiber budget that can only be decremented by `PinningEffect`
/// and incremented by `UnbindingEffect` \[never by direct mutation\].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FiberBudget {
    /// Total fiber capacity at the quantum level.
    total: u32,
    /// Currently pinned fibers.
    pinned: u32,
}

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

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

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

    /// Creates a new fiber budget. 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::{QuantumLevel, 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: QuantumLevel::Q0 });
/// let idx_5 = arena.push(Term::Literal { value: 5, level: QuantumLevel::Q0 });
///
/// // 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::{QuantumLevel, PrimitiveOp};
///
/// // Literal: an integer value tagged with a quantum level.
/// let lit = Term::Literal { value: 42, level: QuantumLevel::Q0 };
///
/// // 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 quantum level.
/// let lift = Term::Lift { operand_index: 0, target: QuantumLevel::new(3) };
///
/// // Project: canonical surjection from a higher to a lower level.
/// let proj = Term::Project { operand_index: 0, target: QuantumLevel::Q0 };
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Term {
    /// Integer literal with quantum level annotation.
    Literal {
        /// The literal integer value.
        value: u64,
        /// The quantum level of this literal.
        level: QuantumLevel,
    },
    /// 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 Q_n to Q_m (n < m, lossless).
    Lift {
        /// Index of the operand term in the arena.
        operand_index: u32,
        /// Target quantum level.
        target: QuantumLevel,
    },
    /// Project: canonical surjection Q_m to Q_n (m > n, lossy).
    Project {
        /// Index of the operand term in the arena.
        operand_index: u32,
        /// Target quantum level.
        target: QuantumLevel,
    },
    /// 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/cascade/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 cascade pipeline.
/// Collects `rootTerm`, `quantumLevelCeiling`, `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::{QuantumLevel, VerificationDomain, ViolationKind};
///
/// // A CompileUnit packages a term graph for cascade admission.
/// // The builder enforces that all required fields are present.
/// let terms = [Term::Literal { value: 1, level: QuantumLevel::Q0 }];
/// let domains = [VerificationDomain::Enumerative];
///
/// let unit = CompileUnitBuilder::new()
///     .root_term(&terms)
///     .quantum_level_ceiling(QuantumLevel::Q0)
///     .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()
///     .quantum_level_ceiling(QuantumLevel::Q0)
///     .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 quantum level the computation may reference.
    quantum_level_ceiling: Option<QuantumLevel>,
    /// Landauer-bounded energy budget.
    thermodynamic_budget: Option<u64>,
    /// Verification domains targeted.
    target_domains: Option<&'a [VerificationDomain]>,
}

/// A validated compile unit ready for cascade admission.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CompileUnit {
    /// The quantum level ceiling.
    level: QuantumLevel,
    /// 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,
            quantum_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 quantum level ceiling.
    #[must_use]
    pub const fn quantum_level_ceiling(mut self, level: QuantumLevel) -> Self {
        self.quantum_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/cascade/rootTerm",
                expected_range: "https://uor.foundation/schema/Term",
                min_count: 1,
                max_count: 1,
                kind: ViolationKind::Missing,
            });
        }
        let level = match self.quantum_level_ceiling {
            Some(l) => l,
            None => {
                return Err(ShapeViolation {
                    shape_iri: "https://uor.foundation/conformance/CompileUnitShape",
                    constraint_iri:
                        "https://uor.foundation/conformance/compileUnit_unitQuantumLevel_constraint",
                    property_iri: "https://uor.foundation/cascade/unitQuantumLevel",
                    expected_range: "https://uor.foundation/schema/QuantumLevel",
                    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/cascade/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/cascade/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_fibers` field.
    target_fibers: 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_fibers: 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_fibers` field.
    #[must_use]
    pub const fn target_fibers(mut self, value: &'a [u32]) -> Self {
        self.target_fibers = 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_fibers.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_fibers",
                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_fiber` field.
    linear_fiber: 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_fiber: None,
            scope: None,
        }
    }

    /// Set the `linear_fiber` field.
    #[must_use]
    pub const fn linear_fiber(mut self, value: u32) -> Self {
        self.linear_fiber = 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_fiber.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_fiber",
                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 `fiber_partition` field.
    fiber_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 {
            fiber_partition: None,
            disjointness_witness: None,
        }
    }

    /// Set the `fiber_partition` field.
    #[must_use]
    pub const fn fiber_partition(mut self, value: &'a [u32]) -> Self {
        self.fiber_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.fiber_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/fiber_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 quantum level beyond Q3.
/// Validates against `QuantumLevelShape`.
#[derive(Debug, Clone)]
pub struct QuantumLevelDeclarationBuilder {
    /// The declared bit width.
    bit_width: Option<u32>,
    /// The declared cycle size.
    cycle_size: Option<u128>,
    /// The predecessor level.
    predecessor: Option<QuantumLevel>,
}

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

impl QuantumLevelDeclarationBuilder {
    /// 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 quantum level.
    #[must_use]
    pub const fn predecessor(mut self, level: QuantumLevel) -> Self {
        self.predecessor = Some(level);
        self
    }

    /// Validate against `QuantumLevelShape`.
    /// # Errors
    /// Returns `ShapeViolation` if any required field is missing.
    pub fn validate(self) -> Result<Validated<QuantumLevelDeclaration>, ShapeViolation> {
        let bw = match self.bit_width {
            Some(w) => w,
            None => {
                return Err(ShapeViolation {
                    shape_iri: "https://uor.foundation/conformance/QuantumLevelShape",
                    constraint_iri: "https://uor.foundation/conformance/QuantumLevelShape",
                    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/QuantumLevelShape",
                    constraint_iri: "https://uor.foundation/conformance/QuantumLevelShape",
                    property_iri: "https://uor.foundation/conformance/predecessorLevel",
                    expected_range: "https://uor.foundation/schema/QuantumLevel",
                    min_count: 1,
                    max_count: 1,
                    kind: ViolationKind::Missing,
                })
            }
        };
        Ok(Validated::new(QuantumLevelDeclaration {
            bit_width: bw,
            predecessor: pred,
        }))
    }
}

impl Default for QuantumLevelDeclarationBuilder {
    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::Q0(b) => DatumInner::Q0(b),
        GroundedCoordInner::Q1(b) => DatumInner::Q1(b),
        GroundedCoordInner::Q3(b) => DatumInner::Q3(b),
        GroundedCoordInner::Q7(b) => DatumInner::Q7(b),
        GroundedCoordInner::Q511(b) => DatumInner::Q511(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 fiber decomposition, which is resolved during cascade 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 cascade evaluation,
    // where each coordinate maps to a fiber in the constrained type.
    validate_and_mint_coord(grounded.coords[0].clone(), shape, session)
}

/// Evaluate a binary ring operation on Q0 (8-bit, Z/256Z) at compile time.
/// This is the sole evaluator for ground assertions. The `uor!` proc macro
/// delegates to this function; it never performs ring arithmetic itself.
/// # Examples
/// ```rust
/// use uor_foundation::enforcement::{const_ring_eval_q0, const_ring_eval_unary_q0};
/// 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_q0(PrimitiveOp::Add, 200, 100), 44);
///
/// // Multiplication: 3 * 5 = 15 (no wrap needed)
/// assert_eq!(const_ring_eval_q0(PrimitiveOp::Mul, 3, 5), 15);
///
/// // XOR: bitwise exclusive-or
/// assert_eq!(const_ring_eval_q0(PrimitiveOp::Xor, 0b1010, 0b1100), 0b0110);
///
/// // Negation: neg(x) = 256 - x (additive inverse in Z/256Z)
/// assert_eq!(const_ring_eval_unary_q0(PrimitiveOp::Neg, 1), 255);
///
/// // The critical identity: neg(bnot(x)) = succ(x) for all x
/// let x = 42u8;
/// let lhs = const_ring_eval_unary_q0(PrimitiveOp::Neg,
///     const_ring_eval_unary_q0(PrimitiveOp::Bnot, x));
/// let rhs = const_ring_eval_unary_q0(PrimitiveOp::Succ, x);
/// assert_eq!(lhs, rhs);
/// ```
#[inline]
#[must_use]
pub const fn const_ring_eval_q0(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,
    }
}

/// Evaluate a unary ring operation on Q0 (8-bit, Z/256Z) at compile time.
#[inline]
#[must_use]
pub const fn const_ring_eval_unary_q0(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,
    }
}

/// Evaluate a binary ring operation on Q1 (16-bit, Z/65536Z) at compile time.
#[inline]
#[must_use]
pub const fn const_ring_eval_q1(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,
    }
}

/// Evaluate a unary ring operation on Q1 (16-bit, Z/65536Z) at compile time.
#[inline]
#[must_use]
pub const fn const_ring_eval_unary_q1(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,
    }
}

/// Evaluate a binary ring operation on Q3 (32-bit, Z/2^32Z) at compile time.
#[inline]
#[must_use]
pub const fn const_ring_eval_q3(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,
    }
}

/// Evaluate a unary ring operation on Q3 (32-bit, Z/2^32Z) at compile time.
#[inline]
#[must_use]
pub const fn const_ring_eval_unary_q3(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,
    }
}

/// Evaluate a binary ring operation on Q7 (64-bit, Z/2^64Z) at compile time.
#[inline]
#[must_use]
pub const fn const_ring_eval_q7(op: PrimitiveOp, a: u64, b: u64) -> u64 {
    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,
    }
}

/// Evaluate a unary ring operation on Q7 (64-bit, Z/2^64Z) at compile time.
#[inline]
#[must_use]
pub const fn const_ring_eval_unary_q7(op: PrimitiveOp, a: u64) -> u64 {
    match op {
        PrimitiveOp::Neg => 0u64.wrapping_sub(a),
        PrimitiveOp::Bnot => !a,
        PrimitiveOp::Succ => a.wrapping_add(1),
        PrimitiveOp::Pred => a.wrapping_sub(1),
        _ => 0,
    }
}