Crate uor_foundation 

UOR Foundation — typed Rust traits for the complete ontology.

Version: 0.4.7

This crate exports every ontology class as a trait, every property as a method, and every named individual as a constant. Implementations import these traits and provide concrete types.

Principal data path

v0.2.2 establishes a single sanctioned API path. Everything else has been deleted (no proc-macro back-doors, no second constructor for sealed types):

 host bytes  ──▶  impl Grounding<Map = …>  ──▶  Datum<L>   [W4: kind-typed]
                                                 │
                                                 ▼
 builder.validate_const() │ .validate()  ──▶  Validated<T, Phase>
                                                 │            [W2 + W13]
                                                 ▼
 pipeline::run::<T, P>(unit)  ──▶  Grounded<T>
                                      │            [W14]
                                      ▼
                           .triad() → Triad<L>     [W8]
                           .certificate()          [W11: Certified<C>]

Every contract is enforced at the type and visibility level. Sealed traits, pub(crate) constructors, and the v0.2.2 conformance suite (W5 ψ-leakage gate, W6 public-API snapshot) catch any deviation.

Substitution axes (per the UOR-Framework wiki)

The wiki names three substitution axes the application author selects against — HostTypes, HostBounds, Hasher. The foundation defines the trait surface; downstream substrates declare the bound the trait must satisfy; the application’s crate selects the implementation.

HostTypes (target §4.1 W10)

Downstream chooses representations only for the three slots that genuinely vary across host environments. Witt-level integers, booleans, IRIs, canonical bytes, and UorTime are foundation-owned and derived from WittLevel.

use uor_foundation::{HostTypes, DefaultHostTypes};

// Use the canonical defaults: f64 / str / [u8].
type H = DefaultHostTypes;

// Or override one slot:
struct EmbeddedHost;
impl HostTypes for EmbeddedHost {
    type Decimal = f32;          // override: tighter precision budget
    type HostString = str;       // default
    type WitnessBytes = [u8];    // default
    const EMPTY_DECIMAL: f32 = 0.0;
    const EMPTY_HOST_STRING: &'static str = "";
    const EMPTY_WITNESS_BYTES: &'static [u8] = &[];
}

HostBounds (wiki ADR-018)

Carries every capacity bound that varies along the principal data path: the fingerprint output width range, the trace event-count ceiling, the algebraic-level bit-width ceiling. Per ADR-018 the architecture admits no capacity bound outside HostBounds.

use uor_foundation::{HostBounds, DefaultHostBounds};

type B = DefaultHostBounds;
assert_eq!(<B as HostBounds>::FINGERPRINT_MAX_BYTES, 32);

Module structure

• kernel — Immutable foundation: addressing, schema, operations
• bridge — Kernel-computed, user-consumed: queries, resolution, partitions, proofs
• user — Runtime declarations: types, morphisms, state
• enforcement — Sealed types and the principal-path entry surface
• pipeline — pipeline::run::<T, P> and the resolver dispatch

Enforcement layer

enforcement provides the sealed types that v0.2.2 forbids downstream from constructing directly:

Layer 1 — Opaque witnesses. enforcement::Datum, enforcement::Validated, enforcement::Derivation, enforcement::FreeRank, enforcement::Grounded, enforcement::Certified, enforcement::Triad: sealed types with private fields. Only the foundation’s pipeline / resolver paths produce them.

Layer 2 — Declarative builders. enforcement::CompileUnitBuilder and 8 others collect declarations and emit Validated<T, Phase> on success or enforcement::ShapeViolation with a machine-readable IRI.

Layer 3 — Term AST. enforcement::Term and enforcement::TermArena: stack-resident, #![no_std]-safe expression trees. The Term enum’s struct-variant constructors are the canonical builder API — there is no DSL macro in v0.2.2.

Foundation as a signature category (wiki ADR-019)

uor-foundation’s vocabulary is the signature category of Prism’s typed routes. Objects are pipeline::ConstrainedTypeShape impls under the substitution-axis selections; morphisms are typed compositions of PrimitiveOp discriminants and enforcement::Term::Application constructions.

The category supports a signature endofunctor F whose enriched signature has one branch per enforcement::Term variant — the four first-order constructors (Literal, Application, Lift, Project), plus binding (Variable), case analysis (Match), explicit fixed-point (Recurse), explicit unfold (Unfold), and failure-promote (Try).

enforcement::Term is F’s initial algebra: any well-typed term tree is an element of the free term language F generates from its enriched signature, and any carrier supporting the same enriched structure admits a unique structure-preserving map from Term.

pipeline::run is the catamorphism into the runtime carrier parameterized by the substitution axes (HostTypes, HostBounds, Hasher). Its dual, the anamorphism, is the trace-replay surface (enforcement::Derivation::replay + enforcement::replay::certify_from_trace); the trace is the anamorphism’s witness object. The four UOR-domain sealed types (enforcement::Datum, enforcement::Triad, enforcement::Derivation, enforcement::FreeRank) and the three Prism-mechanism sealed types (enforcement::Validated, enforcement::Grounded, enforcement::Certified) are fixed points of the typed pipeline endofunctor (distinct from F; see wiki section 8, Fixed Points).

Initiality and uniqueness of the catamorphism hold within each fixed choice of the three substitution axes: for a given (HostTypes, HostBounds, Hasher) selection, there is exactly one F-algebra homomorphism from Term to the corresponding carrier. The categorical statement of ADR-018’s capacity completeness is that the indexing of carriers is total over HostBounds — every capacity-bounded width that varies along the principal data path is part of the index. The substrate-vs-implementor split (ADR-007’s three-position pattern) extends naturally: foundation defines F and the initial algebra; the runtime declares the bound any application’s Route MUST satisfy and the catamorphism that compiles it; the application author selects the F-algebra by writing the model.

PrismModel — the application author’s typed iso (wiki ADR-020)

pipeline::PrismModel codifies the iso the application author declares: an Input feature type, an Output label type, and a type-level Route witness of the term tree mapping one to the other. The Route associated type is bound by pipeline::FoundationClosed — closure under foundation vocabulary, enforced at the application’s compile time per UORassembly (TC-04, ADR-006). forward() is the catamorphism into pipeline::run’s runtime carrier; together with the Trace-witnessed anamorphism through enforcement::replay::certify_from_trace it forms the verifiable round-trip described in the wiki.

Witness minting (Phases 10 + 12 + 14 + 15)

Path-2 ontology classes (theorem-attesting witnesses such as witness_scaffolds::MintBornRuleVerification, witness_scaffolds::MintCompletenessWitness, etc.) implement the sealed OntologyVerifiedMint trait. Mint a witness by populating its Mint{Foo}Inputs<H> bundle with non-zero handles + true attestation flags + non-empty strings, then calling Mint{Foo}::ontology_mint::<H>(inputs). On structural-invariant failure each verify_* primitive in crate::primitives::{family} returns a typed enforcement::GenericImpossibilityWitness whose IRI cites the specific failing op-namespace identity (BR_, CC_, IH_, FX_4, WLS_, surfaceSymmetry).

Per-class observable views (Phase 16)

enforcement::Validated<T, Phase> does not directly implement the kind-specific Observable<H> trait — Rust forbids multiple Observable<H> impls per type, and the bare blanket would return a sentinel for every kind. Consumers select an explicit kind via the inherent accessors Validated::as_landauer, Validated::as_jacobian, Validated::as_carry_depth, Validated::as_derivation_depth, and Validated::as_free_rank. Each returns a zero-cost newtype view in blanket_impls whose Observable<H>::value() body delegates to the relevant primitive (primitive_descent_metrics, primitive_curvature_jacobian, primitive_dihedral_signature, etc.).

Calling .landauer_nats() on the view requires the bridge::observable::LandauerBudget trait to be in scope — distinct from the enforcement::LandauerBudget struct re-exported at the crate root. Likewise for as_jacobian → bridge::observable::JacobianObservable, as_carry_depth → kernel::carry::CarryDepthObservable, as_derivation_depth → bridge::derivation::DerivationDepthObservable, and as_free_rank → bridge::partition::FreeRankObservable. <_ as Observable<H>>::value(&view) works for every view once Observable itself is in scope.

Resolvers (v0.2.2 W12)

Verdict-producing resolvers are free functions in module-per-resolver organization. Each function returns a Result<Certified<Cert>, Witness>:

• enforcement::resolver::inhabitance::certify(input) — inhabitance verdict
• enforcement::resolver::tower_completeness::certify(input) — tower completeness
• enforcement::resolver::incremental_completeness::certify(input) — incremental
• enforcement::resolver::grounding_aware::certify(unit) — grounding-aware

Features

The crate ships this feature-flag layout. Every capability the default build omits is opt-in; the default is #![no_std]-pure and alloc-free.

Feature	Default	Adds	When to enable
alloc	off	extern crate alloc; alloc-backed diagnostic helpers	Heap available but no OS
std	off	alloc + std-specific paths	Hosted platforms
libm	on (unconditional dep)	libm-backed ln, exp, sqrt for transcendental observables	Always on — required by xsd:decimal observables (see target §1.6)
serde	off	serde::{Serialize, Deserialize} on Trace, TraceEvent, and other carriers	Exporting traces to external verifiers
observability	off	alloc + a subscribe(handler: FnMut(&TraceEvent)) surface	Runtime observation of the reduction pipeline

The default = [] posture means bare-metal targets (thumbv7em-none-eabihf) build without any feature flag. CI validates three configurations: the bare-metal no_std cross-build, the alloc-additive hosted build, and the --all-features composite. See target §1.6 and §7.5.

Scope note

This crate is conformance-first: every surface the ontology specifies is present, and every surface it rejects (e.g., the deleted v0.2.1 Primitives trait and unit-struct resolver façades) is absent. There is no migration layer, no deprecation aliases, and no compatibility shims — the crate is either in conformance with the ontology or it isn’t.

Re-exports

pub use witness_scaffolds::OntologyVerifiedMint;

pub use enforcement::BindingEntry;

pub use enforcement::BindingsTable;

pub use enforcement::BindingsTableError;

pub use enforcement::BoundConstraint;

pub use enforcement::Calibration;

pub use enforcement::CalibrationError;

pub use enforcement::Certificate;

pub use enforcement::CertificateKind;

pub use enforcement::Certified;

pub use enforcement::CompileUnit;

pub use enforcement::CompileUnitBuilder;

pub use enforcement::ContentAddress;

pub use enforcement::ContentFingerprint;

pub use enforcement::Derivation;

pub use enforcement::Grounded;

pub use enforcement::GroundingCertificate;

pub use enforcement::Hasher;

pub use enforcement::LandauerBudget;

pub use enforcement::MultiplicationCertificate;

pub use enforcement::Nanos;

pub use enforcement::PipelineFailure;

pub use enforcement::ReplayError;

pub use enforcement::ShapeViolation;

pub use enforcement::Term;

pub use enforcement::TermArena;

pub use enforcement::TermList;

pub use enforcement::Trace;

pub use enforcement::TraceEvent;

pub use enforcement::UorTime;

pub use enforcement::Validated;

pub use enforcement::TRACE_REPLAY_FORMAT_VERSION;

pub use enforcement::CartesianProductEvidence;

pub use enforcement::CartesianProductMintInputs;

pub use enforcement::CartesianProductWitness;

pub use enforcement::GenericImpossibilityWitness;

pub use enforcement::NullPartition;

pub use enforcement::PartitionCoproductEvidence;

pub use enforcement::PartitionCoproductMintInputs;

pub use enforcement::PartitionCoproductWitness;

pub use enforcement::PartitionHandle;

pub use enforcement::PartitionProductEvidence;

pub use enforcement::PartitionProductMintInputs;

pub use enforcement::PartitionProductWitness;

pub use enforcement::PartitionRecord;

pub use enforcement::PartitionResolver;

pub use enforcement::VerifiedMint;

pub use enums::*;

Modules

blanket_impls

bridge

bridge space modules.

enforcement

Declarative enforcement types.

enums

Shared enumerations derived from the UOR Foundation ontology.

kernel

kernel space modules.

pipeline

Reduction Pipeline — no_std in-process driver.

primitives

Per-family verify_* primitives for Path-2 witnesses.

user

user space modules.

witness_scaffolds

Phase 10 — Path-2 VerifiedMint witness scaffolds. Generated from every Path2TheoremWitness classification; one Mint{Foo} + Mint{Foo}Inputs<H> + Certificate + OntologyVerifiedMint per class. Routes to per-family primitive stubs in crate::primitives::*.

Structs

DefaultHostBounds

Canonical default impl of HostBounds. Carries the values the default const-generic on Hasher, ContentFingerprint, and Trace resolves to. Use as type B = uor_foundation::DefaultHostBounds; to inherit; replace with a downstream marker struct when an application needs different capacity bounds (per ADR-018, this is the only sanctioned way to vary).

DefaultHostTypes

Phase B: canonical default impl of HostTypes. Selects f64/str/[u8]. Use as type H = uor_foundation::DefaultHostTypes; to inherit the defaults; replace with a downstream marker struct if any slot needs an override.

Constants

CALIBRATION_CHAR_ENERGY_HI_BITS

Upper bound for Calibration::characteristic_energy (1e3 J), in IEEE-754 bits.

CALIBRATION_KBT_HI_BITS

Upper bound for Calibration::k_b_t (1e-15 J), in IEEE-754 bits.

CALIBRATION_KBT_LO_BITS

Lower bound for Calibration::k_b_t (1e-30 J), in IEEE-754 bits.

CALIBRATION_THERMAL_POWER_HI_BITS

Upper bound for Calibration::thermal_power (1e9 W), in IEEE-754 bits.

LN_2_BITS

Natural logarithm of 2, in IEEE-754 bits. Drives the Landauer bit-erasure unit.

NANOS_PER_SECOND_BITS

Nanoseconds per second (1.0e9) in IEEE-754 bits. Used by UorTime::min_wall_clock.

PI_TIMES_H_BAR_BITS

π · ℏ = core::f64::consts::PI * 1.054_571_817e-34 J·s, in IEEE-754 bits. Half of one orthogonal-state-transition Margolus-Levitin bound.

Traits

DecimalTranscendental

Closed arithmetic and transcendental math for the HostTypes::Decimal slot. f64 and f32 implement this via libm. Downstream HostTypes impls are free to bring their own implementation (interval arithmetic, arbitrary precision, fixed-point, etc.).

HostBounds

Substitution axis 2 of 3 (per the UOR-Framework wiki). Carries every capacity bound that varies along the principal data path: the fingerprint output width range, the trace event-count ceiling, and the algebraic-level bit-width ceiling. The application author selects an impl; the foundation (this trait) declares the contract. Per the wiki’s ADR-018, the architecture admits no capacity bound outside HostBounds. Foundation’s Hasher, ContentFingerprint, and Trace are const-generic over their capacity bounds; applications populate each type’s const-generic with <MyBounds as HostBounds>::CONST. There are no free-standing capacity constants on the public surface — collapsing the substitution axis is exactly what ADR-018 rejects.

HostTypes

Phase B (target §4.1 W10): narrow host-types trait — the only carrier for the slots that genuinely vary across host environments. Foundation-owned types (Witt-level integers, booleans, IRIs, canonicalBytes, UorTime) are derived from the WittLevel family and not exposed here. Three slots: Decimal (real-number representation), HostString (opaque host string, NOT a foundation IRI), and WitnessBytes (opaque host byte sequence, NOT a foundation canonicalBytes constant). The v0.2.1 DateTime slot is removed; downstream associates timestamps out-of-band.