uor-prism 0.1.3

//! The principal data path: admission, validation, and grounding.
//!
//! `pipeline` realizes the wiki's
//! [Building Block View § Whitebox `prism` pipeline][05-pipeline]
//! and the runtime narrative in
//! [Runtime View § Scenario 1: Principal Data Path Execution][06-scenario-1].
//! Its single sanctioned entry point is [`run`]: it consumes a
//! `Validated<CompileUnit, Phase>` produced by the foundation's builders
//! and emits a `(Grounded<T>, Trace)` pair simultaneously, both
//! constructed from the same intermediate values so that replay
//! equivalence (TC-05) holds by construction.
//!
//! Application authors implement [`ConstrainedTypeShape`] to declare a
//! constrained type; the closed set of [`ConstraintRef`] variants is the
//! vocabulary they assemble. `pipeline::run`'s type parameters are
//! exactly the three substitution axes identified in ADR-007: the
//! constrained type `T` (carrying the application's `HostBounds` const
//! generics), the validation phase `P`, and the substrate hasher `H`.
//!
//! ## The categorical reading (ADR-019) and the developer's contract (ADR-020)
//!
//! Per ADR-019, `uor-foundation`'s vocabulary is the **signature
//! category** of Prism's typed routes; `Term` is its **initial algebra**;
//! `pipeline::run` is the **catamorphism** into the runtime carrier.
//! The application author's surface for declaring an application against
//! that structure is [`PrismModel`] (ADR-020) — a sealed trait carrying
//! `(Input, Output, Route)` plus a `forward(input)` catamorphism. The
//! higher-level entry point [`run_route`] (ADR-022 D5) is the canonical
//! model-execution surface: `forward`'s body is `run_route::<H, B, A,
//! Self>(input)`, so the catamorphism is discharged at the application's
//! compile time and `forward` monomorphizes to native code per TC-01.
//! The `prism_model!` macro that emits the [`FoundationClosed`] +
//! `PrismModel` impls lives in the companion crate `uor-foundation-sdk`;
//! prism re-exports the trait so authors who bound on `PrismModel` reach
//! it through `prism::pipeline::PrismModel`, even when their model body
//! is generated by the SDK macro.
//!
//! ## OPM conceptual model
//!
//! The wiki's [Conceptual Model § SD2 Principal Data Path][cm-sd2] is
//! the OPM (ISO 19450) statement of what this module realizes: the
//! application author's Source becomes a Pipeline Runtime invocation
//! that yields `(Grounded Output, Trace, Certified Output)`.
//!
//! # See also
//!
//! - [Wiki: 05 Building Block View § Whitebox `prism` pipeline — staged transitions][05-pipeline]
//! - [Wiki: 06 Runtime View § Scenario 1: Principal Data Path Execution][06-scenario-1]
//! - [Wiki: 07 Deployment View § Quality Properties of the Deployment](https://github.com/UOR-Foundation/UOR-Framework/wiki/07-Deployment-View#quality-properties-of-the-deployment)
//! - [Wiki: 08 Concepts § Hashing Substrate Contract](https://github.com/UOR-Foundation/UOR-Framework/wiki/08-Concepts#hashing-substrate-contract)
//! - [Wiki: 09 Architecture Decisions § ADR-012](https://github.com/UOR-Foundation/UOR-Framework/wiki/09-Architecture-Decisions)
//! - [Wiki: Conceptual Model § SD2 Principal Data Path][cm-sd2]
//! - [Wiki: Conceptual Model § SD5 Distribute And Run][cm-sd5] — same
//!   `Execution` process viewed from the user's distribute-and-run
//!   perspective; `pipeline::run` is what runs inside the user's
//!   compiled executable per the SD5 OPL `Execution yields Trace`
//!
//! # Constraints
//!
//! - **TC-01** — pipeline execution is a sequence of monomorphized,
//!   non-dispatched calls; no Prism interpreter layer is interposed
//! - **TC-03** — `run` is the singular constructor of `Grounded<T>`;
//!   no alternative path exists
//! - **QS-01** — release builds with `opt-level=3`, `lto=true`,
//!   `codegen-units=1` reduce execution cost to the substrate hasher
//!   invocation plus the primitive operations
//! - **ADR-012** — the pipeline lives in `prism`, not `uor-foundation`,
//!   so alternative runtimes can consume the same foundation vocabulary
//! - **ADR-019** — foundation is a closed signature endofunctor; `Term`
//!   is its initial algebra; `pipeline::run` is the catamorphism
//! - **ADR-020** — `PrismModel` is the application author's typed-iso
//!   contract; the `prism_model!` macro derives `forward` from `Route`
//!   via initiality
//! - **ADR-022** — `run_route` is the higher-level catamorphism entry
//!   point that the macro-emitted `forward` body delegates to
//! - **ADR-023** — `M::Input` value flow into the `CompileUnit` binding
//!   table; `IntoBindingValue` is the serialization contract
//!
//! # C4 placement
//!
//! Component `pipeline` (Level 3) inside container `prism` (Level 2).
//! Its boundary properties are: validated input on the left, sealed
//! `Grounded<T>` plus `Trace` on the right; everything between is
//! foundation-internal staged transitions.
//!
//! # Behavior
//!
//! ```rust
//! // Given: the pipeline module surface
//! // When:  consumers reference the entry-point and admission types
//! // Then:  every name resolves at compile time
//! use prism::pipeline::{run as _, ConstrainedTypeShape as _, ConstraintRef};
//! // ConstraintRef is a closed enum; matching is exhaustive at compile time.
//! fn _is_total_admission_check(c: &ConstraintRef) -> bool {
//!     matches!(
//!         c,
//!         ConstraintRef::Residue { .. }
//!             | ConstraintRef::Hamming { .. }
//!             | ConstraintRef::Depth { .. }
//!             | ConstraintRef::Carry { .. }
//!             | ConstraintRef::Site { .. }
//!             | ConstraintRef::Affine { .. }
//!             | ConstraintRef::SatClauses { .. }
//!             | ConstraintRef::Bound { .. }
//!             | ConstraintRef::Conjunction { .. }
//!             | ConstraintRef::Recurse { .. }
//!     )
//! }
//! ```
//!
//! [05-pipeline]: https://github.com/UOR-Foundation/UOR-Framework/wiki/05-Building-Block-View#whitebox-prism-pipeline--staged-transitions
//! [06-scenario-1]: https://github.com/UOR-Foundation/UOR-Framework/wiki/06-Runtime-View#scenario-1-principal-data-path-execution
//! [cm-sd2]: https://github.com/UOR-Foundation/UOR-Framework/wiki/Conceptual-Model#sd2-principal-data-path
//! [cm-sd5]: https://github.com/UOR-Foundation/UOR-Framework/wiki/Conceptual-Model#sd5-distribute-and-run

pub use uor_foundation::pipeline::{
    run, validate_compile_unit_const, validate_constrained_type, validate_constrained_type_const,
    ConstrainedTypeShape, ConstraintRef, FragmentKind, StageOutcome,
};
pub use uor_foundation::ViolationKind;
pub use uor_foundation::{PipelineFailure, ShapeViolation};

// `PrismModel` is the developer-facing contract introduced in
// foundation 0.3.2 per wiki ADR-020 and extended in 0.4 per ADR-035/036
// with the `R: ResolverTuple` substrate parameter: the sealed trait an
// application author implements (via the `prism_model!` macro from
// `uor-foundation-sdk`) to declare a typed route from `Input` to
// `Output`. `run_route` is the higher-level catamorphism entry point
// (ADR-022 D5) — the canonical model-execution surface; the
// macro-emitted `forward` body delegates to it. `FoundationClosed`
// (the type-level closure witness on `Route`) and `IntoBindingValue`
// (the serialization contract on `Input` and `Output`, per ADR-023)
// are the sealed supertraits the macro emits alongside.
pub use uor_foundation::pipeline::{run_route, FoundationClosed, IntoBindingValue, PrismModel};

// ADR-035/036 substrate axes: `AxisTuple` (axis-substrate parameter for
// `PrismModel::A`, blanket-impl'd for any `H: Hasher` so existing
// `H: Hasher` bounds keep resolving) and `ResolverTuple` (the
// eight-categorical-machinery resolvers carried in the model's `R`
// parameter, default `NullResolverTuple`). The `Has*Resolver` family
// names which resolver categories a tuple satisfies; each null
// implementation raises the `RESOLVER_ABSENT` shape violation per
// TR-15 so applications that don't declare real resolvers fail loudly
// at evaluation time (the verb body's outer `Term::Try` handler may
// recover the case per ADR-022 D3 G9; absent that handler the
// shape-violation propagates as `PipelineFailure::ShapeViolation`).
// The ψ-residuals discipline of TR-14 is enforced earlier — at
// proc-macro expansion of `verb!`/`prism_model!` — so resolver-bound
// ψ-Term variants reach the runtime path only when the macro accepted
// the verb body as well-formed.
pub use uor_foundation::pipeline::{
    AxisExtension, AxisTuple, HasChainComplexResolver, HasCochainComplexResolver,
    HasCohomologyGroupResolver, HasHomologyGroupResolver, HasHomotopyGroupResolver,
    HasKInvariantResolver, HasNerveResolver, HasPostnikovResolver, NullResolverTuple,
    ResolverCategory, ResolverTuple,
};
pub use uor_foundation::pipeline::{
    ChainComplexResolver, CochainComplexResolver, CohomologyGroupResolver, HomologyGroupResolver,
    HomotopyGroupResolver, KInvariantResolver, NerveResolver, PostnikovResolver,
};
pub use uor_foundation::pipeline::{
    NullChainComplexResolver, NullCochainComplexResolver, NullCohomologyGroupResolver,
    NullHomologyGroupResolver, NullHomotopyGroupResolver, NullKInvariantResolver,
    NullNerveResolver, NullPostnikovResolver,
};

// ADR-033 G20: partition-product factor-field directory machinery —
// types that admit themselves as cartesian products carry these traits
// so the closure body can locate factor fields by index.
pub use uor_foundation::pipeline::{PartitionProductFactor, PartitionProductFields};

// ADR-035 leaf-constraint refinement of `ConstraintRef` for ψ-chain
// `Term::Closure` body grammar (G16); referenced from
// `partition_product` factor declarations.
pub use uor_foundation::pipeline::LeafConstraintRef;

// ADR-057 bounded recursive structural typing — the foundation
// shape-IRI registry that powers `ConstraintRef::Recurse { shape_iri,
// descent_bound }`. Recurse references another `ConstrainedTypeShape`
// by content-addressed IRI per ADR-017 with a per-reference monotonic
// descent budget; the IRI graph may carry cycles and mutual recursion
// provided every cycle is bounded by some `descent_bound` along it.
// Two-tier lookup mirrors the observable-IRI registry of ADR-038/049:
// `lookup_shape` consults the foundation-owned registry (reserved for
// future foundation-curated stdlib shapes); `lookup_shape_in::<R>`
// consults the application-provided `ShapeRegistryProvider` first
// then falls back to the foundation registry. Applications emit a
// concrete provider via the `register_shape!` SDK macro re-exported
// below. The `Recurse`-bearing shape declares
// `CYCLE_SIZE = u64::MAX` (saturation per ADR-032); ψ_1 NerveResolver
// evaluates the registry lookup at runtime admission.
pub use uor_foundation::pipeline::shape_iri_registry::{
    lookup_shape, lookup_shape_in, EmptyShapeRegistry, RegisteredShape, ShapeRegistryProvider,
};

// ADR-057 nerve / Betti substrate primitives.
//
// `primitive_simplicial_nerve_betti::<T>()` computes the Betti-number
// array of the simplicial nerve of `T`'s constraint set per ADR-031's
// ψ_1 NerveResolver lowering;
// `primitive_cartesian_nerve_betti::<S>()` is the
// cartesian-product-shape variant that Künneth-composes its two
// components' Betti arrays per ADR-031 PT_3.
//
// The `_in::<…, R: ShapeRegistryProvider>()` companions shipped in
// foundation 0.4.15 walk `ConstraintRef::Recurse` entries through `R`'s
// registry plus foundation's built-in registry, so applications using
// `register_shape!` for recursive grammars get the structurally-correct
// nerve / Betti reading of the recursively-expanded constraint set.
// `expand_constraints_in::<R>` is the workhorse helper both `_in`
// Betti primitives compose over (and an application-grade primitive
// in its own right for resolver impls that need the registry-aware
// constraint walk).
pub use uor_foundation::enforcement::{
    expand_constraints_in, primitive_simplicial_nerve_betti, primitive_simplicial_nerve_betti_in,
};
pub use uor_foundation::pipeline::{
    primitive_cartesian_nerve_betti, primitive_cartesian_nerve_betti_in,
};

// ADR-057 capacity constants honored by the nerve / Betti primitives:
// `NERVE_CONSTRAINTS_CAP` is the per-shape constraint cap after
// recursive expansion; `NERVE_SITES_CAP` is the site-support bitmask
// width cap. Exceeding either raises
// `NERVE_CAPACITY_EXCEEDED`; an unregistered `Recurse` IRI raises
// `RECURSE_SHAPE_UNREGISTERED`. `MAX_BETTI_DIMENSION` is the array
// length returned by the Betti primitives.
pub use uor_foundation::enforcement::{
    MAX_BETTI_DIMENSION, NERVE_CONSTRAINTS_CAP, NERVE_SITES_CAP,
};

// `GenericImpossibilityWitness` is the substrate-level error type
// returned by the nerve / Betti primitives and by `expand_constraints_in`.
// Surfacing it here lets applications match against the witness
// (e.g. `NERVE_CAPACITY_EXCEEDED`, `RECURSE_SHAPE_UNREGISTERED`) without
// a separate `uor-foundation` import path.
pub use uor_foundation::enforcement::GenericImpossibilityWitness;

// ADR-048 typed-commitment substrate: the 5th model-declaration
// parameter `C: TypedCommitment` (default `EmptyCommitment`) and the
// 6th runtime argument to `run_route`. The catamorphism evaluates
// `commitment.evaluate(kappa_label)` after the resolver-bound κ-label
// is emitted, giving zero-cost typed-bandwidth admission composition.
// Foundation publishes the closed three-impl set — `EmptyCommitment`
// (the no-commitment baseline), `SingletonCommitment<P>` (a single
// typed predicate over a UOR observable per ADR-049), and
// `AndCommitment<A, B>` (typed conjunction; bandwidth additive,
// accept_prob multiplicative) — plus the `TargetCommitment` canonical
// search-cost commitment alias per ADR-048's wire-format amendment.
pub use uor_foundation::pipeline::{
    AndCommitment, EmptyCommitment, SingletonCommitment, TargetCommitment, TypedCommitment,
};

// ADR-049 typed UOR observable surface — the foundation-published five
// `ObservablePredicate` impls that close the catalog correspondence
// with ADR-040's `BoundShape` roster: `Stratum<P>` (p-adic valuation
// per `observable:StratumObservable`), `WalshHadamardParity` (spectral
// parity under `observable:SpectralObservable`), `UltrametricCloseTo<P>`
// (p-adic ultrametric distance, `observable:MetricObservable`),
// `AffineParity` (single-bit value at a designated position,
// `observable:StratumObservable`), and `LexicographicLessEqThreshold`
// (big-endian integer threshold against a `&'static [u8]` target,
// `observable:ValueThresholdObservable` realizing
// `type:LexicographicLessEqBound` per ADR-040). Each predicate is
// `Copy + Sealed`, consumable as a `SingletonCommitment<P>` operand
// per ADR-048, and IRI-bound to ADR-038's closed observable taxonomy.
pub use uor_foundation::pipeline::{
    AffineParity, LexicographicLessEqThreshold, ObservablePredicate, Stratum, UltrametricCloseTo,
    WalshHadamardParity,
};

// ADR-043 witness-tuple source: the substrate for resolver-internal
// bounded-search convergence/exhaustion accounting.
pub use uor_foundation::pipeline::WitnessTupleSource;

// `TimingPolicy` is the foundation-sealed trait the application author
// references to declare timing budgets that participate in preflight
// and runtime timing checks of the principal data path. It is part of
// the admission contract surfaced by [`run`] indirectly, through
// `Validated<CompileUnit, _>`'s thermodynamic-budget plumbing.
pub use uor_foundation::enforcement::TimingPolicy;

// Free functions that drive the per-stage admission machinery. They are
// surfaced because `prism::pipeline` is the wiki-defined home of the
// principal data path (ADR-012); having them here means consumers can
// reach the const-evaluable validators without depending on
// `uor-foundation`'s `pipeline` module path directly.
pub use uor_foundation::pipeline::{
    fragment_classify, preflight_budget_solvency, preflight_dispatch_coverage,
    preflight_feasibility, preflight_package_coherence,
};

// `WITT_MAX_BITS` is the normative upper bound on Witt-level bit width
// honored by `preflight_budget_solvency`. Surfacing it here keeps the
// pipeline contract self-contained.
pub use uor_foundation::pipeline::WITT_MAX_BITS;

// ADR-030 capacity caps and substitution-axis machinery for application
// authors who declare their own axes via `axis!`.
pub use uor_foundation::pipeline::{AXIS_OUTPUT_BYTES_CEILING, MAX_AXIS_TUPLE_ARITY};

// Wiki ADR-031 façade commitment: the SDK macros declared by
// `uor-foundation-sdk` are re-exported through `prism::pipeline` so a
// single import path reaches the canonical application-author surface.
// The macros expand to items that depend on foundation-sealed traits;
// because `prism` re-exports those traits as well, applications never
// need to depend on `uor-foundation-sdk` or `uor-foundation` directly.
pub use uor_foundation_sdk::{
    axis, cartesian_product_shape, coproduct_shape, output_shape, partition_coproduct,
    partition_product, prism_model, product_shape, register_shape, resolver, use_verbs, verb,
};