uor-foundation 0.2.0

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

//! `conformance/` namespace — SHACL-equivalent constraint shapes defining what a Prism implementation must provide at each extension point. Machine-verifiable contracts..
//!
//! Space: Bridge

use crate::enums::VerificationDomain;
use crate::enums::ViolationKind;
use crate::enums::WittLevel;
use crate::Primitives;

/// A constraint shape that a Prism-declared extension must satisfy. Analogous to sh:NodeShape in SHACL.
pub trait Shape<P: Primitives> {
    /// The OWL class that instances of this shape must belong to.
    fn target_class(&self) -> &P::String;
    /// Associated type for `PropertyConstraint`.
    type PropertyConstraint: PropertyConstraint<P>;
    /// A required property in this shape.
    fn required_property(&self) -> &[Self::PropertyConstraint];
}

/// A single required property within a shape: the property URI, its expected range, minimum and maximum cardinality.
pub trait PropertyConstraint<P: Primitives> {
    /// The property URI that must be present.
    fn constraint_property(&self) -> &P::String;
    /// The expected range of the required property.
    fn constraint_range(&self) -> &P::String;
    /// Minimum cardinality of the required property.
    fn min_count(&self) -> P::NonNegativeInteger;
    /// Maximum cardinality (0 = unbounded).
    fn max_count(&self) -> P::NonNegativeInteger;
}

/// Shape for declaring a new WittLevel beyond Q3.
pub trait WittLevelShape<P: Primitives>: Shape<P> {}

/// Shape for declaring an ExternalEffect.
pub trait EffectShape<P: Primitives>: Shape<P> {}

/// Shape for declaring a ParallelProduct.
pub trait ParallelShape<P: Primitives>: Shape<P> {}

/// Shape for declaring a ProductiveStream (targets stream:Unfold, the coinductive constructor).
pub trait StreamShape<P: Primitives>: Shape<P> {}

/// Shape for declaring a new DispatchRule in a DispatchTable.
pub trait DispatchShape<P: Primitives>: Shape<P> {}

/// Shape for declaring a Lease with LinearSite allocation.
pub trait LeaseShape<P: Primitives>: Shape<P> {}

/// Shape for declaring a GroundingMap from surface data to the ring.
pub trait GroundingShape<P: Primitives>: Shape<P> {}

/// The result of validating an extension against a shape: conforms (boolean), and violation details if non-conformant.
pub trait ValidationResult<P: Primitives> {
    /// Associated type for `Shape`.
    type Shape: Shape<P>;
    /// The shape that was validated against.
    fn validation_shape(&self) -> &Self::Shape;
    /// The instance that was validated.
    fn validation_target(&self) -> &P::String;
    /// True iff the target satisfies all constraints of the shape.
    fn conforms(&self) -> P::Boolean;
}

/// Shape for user-declared predicates. Requires a bounded evaluator (termination witness) and input type declaration.
pub trait PredicateShape<P: Primitives>: Shape<P> {}

/// Opaque ring element witness. Cannot be constructed outside the foundation crate — only produced by reduction evaluation or the two-phase minting boundary.
pub trait WitnessDatum<P: Primitives> {
    /// The quantum level at which this witness datum was minted.
    fn witness_level(&self) -> P::NonNegativeInteger;
    /// The raw byte representation of this witness datum.
    fn witness_bytes(&self) -> &P::String;
}

/// Boundary crossing intermediate for a single grounded coordinate value. Not a WitnessDatum — must be validated and minted by the foundation.
pub trait GroundedCoordinate<P: Primitives> {
    /// The quantum level tag of this grounded coordinate.
    fn coordinate_level(&self) -> WittLevel;
}

/// Boundary crossing intermediate for a fixed-size array of GroundedCoordinate values. Stack-resident, no heap allocation.
pub trait GroundedTuple<P: Primitives> {}

/// Sealed marker trait class. Implemented only for GroundedCoordinate and GroundedTuple. Prevents downstream crates from substituting arbitrary types.
pub trait GroundedValueMarker<P: Primitives> {}

/// Generic validation-proof wrapper. Proves that the inner value was produced by the conformance checker, not fabricated by Prism code.
pub trait ValidatedWrapper<P: Primitives> {
    /// The validated inner value wrapped by this proof.
    fn validated_inner(&self) -> &P::String;
}

/// Opaque derivation trace that can only be extended by the rewrite engine. Records rewrite step count and root term content address.
pub trait WitnessDerivation<P: Primitives> {}

/// Opaque site budget that can only be decremented by PinningEffect and incremented by UnbindingEffect — never by direct mutation.
pub trait WitnessSiteBudget<P: Primitives> {}

/// Structured violation diagnostic carrying the shape IRI, constraint IRI, property IRI, expected range, cardinality bounds, and violation kind.
pub trait ShapeViolationReport<P: Primitives> {
    /// IRI of the conformance:Shape that was validated against.
    fn shape_iri(&self) -> &P::String;
    /// IRI of the specific PropertyConstraint that failed.
    fn constraint_iri(&self) -> &P::String;
    /// IRI of the property that was missing or invalid.
    fn property_iri(&self) -> &P::String;
    /// The expected range class IRI for the violated property.
    fn expected_range(&self) -> &P::String;
    /// The minimum cardinality from the violated constraint.
    fn violation_min_count(&self) -> P::NonNegativeInteger;
    /// The maximum cardinality from the violated constraint (0 = unbounded).
    fn violation_max_count(&self) -> P::NonNegativeInteger;
    /// The kind of violation that occurred.
    fn violation_kind(&self) -> ViolationKind;
}

/// Builder for CompileUnit admission. Collects rootTerm, quantumLevelCeiling, thermodynamicBudget, and targetDomains. Validates against CompileUnitShape.
pub trait CompileUnitBuilder<P: Primitives> {
    /// Associated type for `Term`.
    type Term: crate::kernel::schema::Term<P>;
    /// The root term expression for the CompileUnit.
    fn builder_root_term(&self) -> &Self::Term;
    /// The widest quantum level the computation may reference.
    fn builder_witt_level_ceiling(&self) -> WittLevel;
    /// Landauer-bounded energy budget in kBT ln 2 units.
    fn builder_thermodynamic_budget(&self) -> P::Decimal;
    /// Verification domains targeted by the CompileUnit.
    fn builder_target_domains(&self) -> &[VerificationDomain];
}

/// Builder for EffectShape. Collects effect name, target sites, budget delta, and commutation flag.
pub trait EffectDeclaration<P: Primitives> {
    /// The name of the declared effect.
    fn effect_name(&self) -> &P::String;
    /// Site coordinates this effect reads or writes.
    fn target_sites(&self) -> &[P::NonNegativeInteger];
    /// The site budget delta (positive = increment, negative = decrement).
    fn budget_delta(&self) -> P::Integer;
    /// Whether this effect commutes with effects on disjoint sites.
    fn commutation_flag(&self) -> P::Boolean;
}

/// Builder for GroundingShape. Collects source type, ring mapping, and invertibility contract.
pub trait GroundingDeclaration<P: Primitives> {
    /// Associated type for `TypeDefinition`.
    type TypeDefinition: crate::user::type_::TypeDefinition<P>;
    /// The source type of incoming external data.
    fn grounding_source_type(&self) -> &Self::TypeDefinition;
    /// Description of the mapping from surface data to ring.
    fn ring_mapping(&self) -> &P::String;
    /// Whether the grounding map is invertible.
    fn invertibility_contract(&self) -> P::Boolean;
}

/// Builder for DispatchShape. Collects predicate, target resolver, and dispatch priority.
pub trait DispatchDeclaration<P: Primitives> {
    /// Associated type for `PredicateExpression`.
    type PredicateExpression: crate::kernel::reduction::PredicateExpression<P>;
    /// The predicate expression guarding this dispatch rule.
    fn dispatch_predicate(&self) -> &Self::PredicateExpression;
    /// Associated type for `Resolver`.
    type Resolver: crate::bridge::resolver::Resolver<P>;
    /// The resolver to dispatch to when the predicate holds.
    fn target_resolver(&self) -> &Self::Resolver;
    /// Priority ordering for this dispatch rule (lower = first).
    fn dispatch_priority(&self) -> P::NonNegativeInteger;
}

/// Builder for LeaseShape. Collects linear site and lease scope.
pub trait LeaseDeclaration<P: Primitives> {
    /// The site coordinate allocated linearly by this lease.
    fn linear_site(&self) -> P::NonNegativeInteger;
    /// The scope within which this lease is valid.
    fn lease_scope(&self) -> &P::String;
}

/// Builder for StreamShape. Collects unfold seed, step term, and productivity witness.
pub trait StreamDeclaration<P: Primitives> {
    /// Associated type for `Term`.
    type Term: crate::kernel::schema::Term<P>;
    /// The seed term for the stream unfold constructor.
    fn unfold_seed(&self) -> &Self::Term;
    /// The step function term for the stream unfold.
    fn step_term(&self) -> &Self::Term;
    /// Evidence that the stream is productive (always produces a next element).
    fn productivity_witness(&self) -> &P::String;
}

/// Builder for PredicateShape. Collects input type, evaluator term, and termination witness.
pub trait PredicateDeclaration<P: Primitives> {
    /// Associated type for `TypeDefinition`.
    type TypeDefinition: crate::user::type_::TypeDefinition<P>;
    /// The input type for the declared predicate.
    fn predicate_input_type(&self) -> &Self::TypeDefinition;
    /// Associated type for `Term`.
    type Term: crate::kernel::schema::Term<P>;
    /// The evaluator term for the declared predicate.
    fn evaluator_term(&self) -> &Self::Term;
    /// Evidence that the predicate evaluator terminates on all inputs.
    fn termination_witness(&self) -> &P::String;
}

/// Builder for ParallelShape. Collects site partition and disjointness witness.
pub trait ParallelDeclaration<P: Primitives> {
    /// Associated type for `Partition`.
    type Partition: crate::bridge::partition::Partition<P>;
    /// The site partition for the parallel composition.
    fn site_partition(&self) -> &Self::Partition;
    /// Evidence that the site partition components are pairwise disjoint.
    fn disjointness_witness(&self) -> &P::String;
}

/// Builder for WittLevelShape. Collects declared bit width, cycle size, and predecessor level.
pub trait WittLevelDeclaration<P: Primitives> {
    /// The declared bit width for this quantum level.
    fn declared_bit_width(&self) -> P::PositiveInteger;
    /// The declared number of ring states at this level.
    fn declared_cycle_size(&self) -> P::NonNegativeInteger;
    /// The predecessor quantum level in the chain.
    fn predecessor_level(&self) -> WittLevel;
}

/// Boundary session state tracker. Records crossing count and idempotency flag for the two-phase minting boundary.
pub trait MintingSession<P: Primitives> {
    /// Total boundary crossings in this minting session.
    fn session_crossing_count(&self) -> P::NonNegativeInteger;
    /// Whether applying this session's boundary effect twice equals applying it once.
    fn session_is_idempotent(&self) -> P::Boolean;
}

/// Shape validating that a CompileUnit carries all required properties before reduction admission. The unitAddress property is NOT required — it is computed by stage_initialization after shape validation passes.
pub mod compile_unit_shape {
    /// `requiredProperty`
    pub const REQUIRED_PROPERTY: &[&str] = &[
        "https://uor.foundation/conformance/compileUnit_rootTerm_constraint",
        "https://uor.foundation/conformance/compileUnit_unitWittLevel_constraint",
        "https://uor.foundation/conformance/compileUnit_thermodynamicBudget_constraint",
        "https://uor.foundation/conformance/compileUnit_targetDomains_constraint",
    ];
    /// `targetClass` -> `CompileUnit`
    pub const TARGET_CLASS: &str = "https://uor.foundation/reduction/CompileUnit";
}

/// Exactly one root term is required. Range is schema:Term.
pub mod compile_unit_root_term_constraint {
    /// `constraintProperty` -> `rootTerm`
    pub const CONSTRAINT_PROPERTY: &str = "https://uor.foundation/reduction/rootTerm";
    /// `constraintRange` -> `Term`
    pub const CONSTRAINT_RANGE: &str = "https://uor.foundation/schema/Term";
    /// `maxCount`
    pub const MAX_COUNT: i64 = 1;
    /// `minCount`
    pub const MIN_COUNT: i64 = 1;
}

/// Exactly one quantum level is required. Range is schema:WittLevel.
pub mod compile_unit_unit_witt_level_constraint {
    /// `constraintProperty` -> `unitWittLevel`
    pub const CONSTRAINT_PROPERTY: &str = "https://uor.foundation/reduction/unitWittLevel";
    /// `constraintRange` -> `WittLevel`
    pub const CONSTRAINT_RANGE: &str = "https://uor.foundation/schema/WittLevel";
    /// `maxCount`
    pub const MAX_COUNT: i64 = 1;
    /// `minCount`
    pub const MIN_COUNT: i64 = 1;
}

/// Exactly one thermodynamic budget is required. Shape validates presence and type; the BudgetSolvencyCheck preflight validates the value against the Landauer bound.
pub mod compile_unit_thermodynamic_budget_constraint {
    /// `constraintProperty` -> `thermodynamicBudget`
    pub const CONSTRAINT_PROPERTY: &str = "https://uor.foundation/reduction/thermodynamicBudget";
    /// `constraintRange` -> `decimal`
    pub const CONSTRAINT_RANGE: &str = "http://www.w3.org/2001/XMLSchema#decimal";
    /// `maxCount`
    pub const MAX_COUNT: i64 = 1;
    /// `minCount`
    pub const MIN_COUNT: i64 = 1;
}

/// At least one target verification domain is required. maxCount 0 means unbounded.
pub mod compile_unit_target_domains_constraint {
    /// `constraintProperty` -> `targetDomains`
    pub const CONSTRAINT_PROPERTY: &str = "https://uor.foundation/reduction/targetDomains";
    /// `constraintRange` -> `VerificationDomain`
    pub const CONSTRAINT_RANGE: &str = "https://uor.foundation/op/VerificationDomain";
    /// `maxCount`
    pub const MAX_COUNT: i64 = 0;
    /// `minCount`
    pub const MIN_COUNT: i64 = 1;
}

/// Required property was not set on the builder.
pub mod missing {}

/// Property was set but its value is not an instance of the constraintRange.
pub mod type_mismatch {}

/// Cardinality violated: too few or too many values provided.
pub mod cardinality_violation {}

/// Value-dependent check failed (Tier 2). For example, thermodynamic budget insufficient for Landauer bound.
pub mod value_check {}

/// A term's quantum level annotation exceeds the CompileUnit ceiling, or binary operation operands are at different levels without an intervening lift or project.
pub mod level_mismatch {}