uor-foundation

The complete UOR Foundation ontology encoded as typed Rust traits. Import and implement.

Contents

• 34 namespaces
• 471 OWL classes (one trait each)
• 948 OWL properties (one method each)
• 3559 named individuals (constants and enums)
• enforcement module with declarative builders and opaque witnesses
• uor! proc macro for compile-time term-language DSL

Quick start

[dependencies]
uor-foundation = "0.4.2"

HostTypes (target §4.1 W10)

Every foundation trait is parametric over HostTypes — a sealed bundle declaring the host-environment types the ontology references. DefaultHostTypes ships for the common case; downstream implementers supply their own HostTypes impl when they need non-default carriers.

use uor_foundation::{DefaultHostTypes, HostTypes};

// Default bundle — satisfies every ring-adjacent surface. Ring
// arithmetic is mono-sorted by construction of the term grammar: host
// slots never participate.
type H = DefaultHostTypes;

Grounding maps (target §4.3)

Downstream sources of external data bind to GroundingMapKind by implementing Grounding with a combinator program(). The foundation supplies ground() via the sealed GroundingExt extension trait — the program's marker tuple mechanically verifies that the declared Map matches the combinator decomposition.

use uor_foundation::enforcement::{
    combinators, BinaryGroundingMap, GroundedCoord, Grounding, GroundingExt,
    GroundingProgram,
};

struct ReadFirstByte;

impl Grounding for ReadFirstByte {
    type Output = GroundedCoord;
    type Map = BinaryGroundingMap;

    // Downstream provides ONLY program(). `ground()` is foundation-owned
    // via the sealed `GroundingExt` blanket impl.
    fn program(&self) -> GroundingProgram<GroundedCoord, BinaryGroundingMap> {
        GroundingProgram::from_primitive(combinators::read_bytes::<GroundedCoord>())
    }
}

// Callers reach ground() through the sealed extension trait.
let g = ReadFirstByte;
let coord: Option<GroundedCoord> = <ReadFirstByte as GroundingExt>::ground(&g, &[0x42]);

Resolvers (target §4.2)

Every resolver is a module with a certify free function that consumes a &Validated<Input, P> carrier and returns Result<Certified<SuccessCert>, Certified<ImpossibilityWitness>>.

use uor_foundation::enforcement::{resolver, ConstrainedTypeInput};
use uor_foundation_test_helpers::{validated_runtime, Fnv1aHasher16};

let input = validated_runtime(ConstrainedTypeInput::default());
let cert = resolver::tower_completeness::certify::<_, _, Fnv1aHasher16>(&input)?;
// cert: Certified<LiftChainCertificate>

The 22 resolver modules share this shape; the only exception is multiplication::certify(&MulContext) whose input is a self-validated shape (target §4.2 MulContext exemption).

Wall-clock (target §1.7)

UorTime records three foundation-internal clocks; the wall-clock lower bound emerges from min_wall_clock(&Calibration):

use uor_foundation::enforcement::calibrations::X86_SERVER;
let min_nanos = grounded.uor_time().min_wall_clock(&X86_SERVER).as_u64();

Module structure

Features

This crate is #![no_std] with a single mandatory dependency on libm (always-on transcendental math per target §1.6). The uor! proc macro is re-exported from uor-foundation and parses term-language expressions at compile time.

Substrate-pluggable hashing

uor-foundation never picks a hash function. Every public path that produces a Grounded, Trace, or GroundingCertificate takes a generic H: Hasher parameter and threads the caller's substrate through fold_unit_digest (or one of the sibling fold_*_digest helpers). The foundation defines only the byte-layout contract and the ContentFingerprint parametric carrier; downstream code supplies the cryptographic primitive.

use uor_foundation::enforcement::{Hasher, ContentFingerprint};
use uor_foundation::pipeline::run;

struct Blake3Hasher { /* ... */ }
impl Hasher for Blake3Hasher {
    const OUTPUT_BYTES: usize = 32;
    fn initial() -> Self { /* ... */ }
    fn fold_byte(self, b: u8) -> Self { /* ... */ }
    fn fold_bytes(self, bytes: &[u8]) -> Self { /* ... */ }
    fn finalize(self) -> [u8; 32] { /* `<DefaultHostBounds>::FINGERPRINT_MAX_BYTES` */ }
}

let grounded = run::<MyShape, _, Blake3Hasher>(validated_unit)?;

The recommended production substrate is BLAKE3: fast, cryptographically sound, and 32-byte output. See PRISM's Hasher impl for a worked reference. FNV-1a test substrates live in uor-foundation-test-helpers and are used only by the round-trip conformance tests; they are not fit for production.

The typed pipeline entry points (pipeline::run, run_const, run_parallel, run_stream, run_interactive) and every resolver facade (TowerCompletenessResolver, IncrementalCompletenessResolver, GroundingAwareResolver, InhabitanceResolver, MultiplicationResolver) are generic over H: Hasher. There are no fallback paths, no zero-fingerprint sentinels, and no Default impls on cert shims — a substrate is mandatory at every grounding site.

Product / coproduct witnesses (Product/Coproduct Completion Amendment)

Three sealed witness types attest that a shape decomposes as one of the partition-algebra operations:

• PartitionProductWitness — gated on PT_1 / PT_3 / PT_4 and the foundation/ProductLayoutWidth invariant (UOR A × B, χ additive).
• PartitionCoproductWitness — gated on ST_1 / ST_2 / ST_6 / ST_7 / ST_8 / ST_9 / ST_10, the foundation/CoproductLayoutWidth invariant, and foundation/CoproductTagEncoding (UOR A + B, ln 2 tag entropy). validate_coproduct_structure walks the supplied ConstraintRef array at mint time to verify the canonical tag-pinner encoding structurally.
• CartesianProductWitness — gated on CPT_1 / CPT_3 / CPT_4 / CPT_5 and the foundation/CartesianLayoutWidth invariant (UOR A ⊠ B, χ multiplicative, Betti via Künneth).

Every witness implements Certificate with a partition-namespace IRI and a paired *Evidence associated type. The sealed VerifiedMint trait routes each *MintInputs struct through the corresponding mint primitive; failures return GenericImpossibilityWitness::for_identity citing the specific op:* theorem or foundation:* layout invariant that was violated.

use uor_foundation::{
    PartitionProductMintInputs, PartitionProductWitness, VerifiedMint,
};

let witness = PartitionProductWitness::mint_verified(inputs)?;
assert_eq!(witness.combined_site_budget(), /* A.sb + B.sb */);

PartitionHandle<H> is the content-addressed identity token for a partition; pair it with a PartitionResolver<H> via resolve_with to recover full PartitionRecord<H> data (site budget, Euler, Betti, entropy). Ergonomic ergonomic macros (product_shape!, coproduct_shape!, cartesian_product_shape!) live in the opt-in companion uor-foundation-sdk crate.

License

Apache-2.0 — see LICENSE.