uor-foundation 0.3.4

# uor-foundation

The complete [UOR Foundation](https://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)
- 3554 named individuals (constants and enums)
- `enforcement` module with declarative builders and opaque witnesses
- `uor!` proc macro for compile-time term-language DSL

## Quick start

```toml
[dependencies]
uor-foundation = "0.3.4"
```

### 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.

```rust
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.

```rust
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>>`.

```rust,ignore
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)`:

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

## Module structure

| Module | Space | Description |
|--------|-------|-------------|
| `kernel::address` | Kernel | Content-addressable identifiers for ring elements |
| `kernel::schema` | Kernel | Core value types and term language for the UOR ring substrate |
| `kernel::op` | Kernel | Ring operations, involutions, algebraic identities, and the dihedral symmetry group D_{2^n} generated by neg and bnot |
| `bridge::query` | Bridge | Information extraction queries |
| `bridge::resolver` | Bridge | Type resolution strategies implementing the partition map Π : T_n → Part(R_n) |
| `user::type_` | User | Runtime type declarations that parameterize the resolution pipeline |
| `bridge::partition` | Bridge | Irreducibility partitions produced by type resolution |
| `bridge::foundation` | Bridge | Foundation-level layout invariants complementing op-namespace theorems |
| `bridge::observable` | Bridge | Observable quantities and metrics computed by the UOR kernel |
| `kernel::carry` | Kernel | Carry chain algebra: generate/propagate/kill event classification, carry profiles, encoding configurations, and encoding quality metrics for d_Δ optimization |
| `bridge::homology` | Bridge | Simplicial complexes, chain complexes, boundary operators, and homology groups for structural reasoning |
| `bridge::cohomology` | Bridge | Cochain complexes, sheaf cohomology, and local-to-global obstruction detection |
| `bridge::proof` | Bridge | Kernel-produced verification proofs attesting to algebraic properties of UOR objects and operations |
| `bridge::derivation` | Bridge | Computation witnesses recording term rewriting sequences from original terms to their canonical forms |
| `bridge::trace` | Bridge | Execution traces recording the sequence of kernel operations, intermediate results, and accumulated metrics for a computation |
| `bridge::cert` | Bridge | Kernel-produced attestation certificates for transforms, isometries, and involutions |
| `user::morphism` | User | Runtime abstractions for maps between UOR objects: transforms, isometries, embeddings, and group actions |
| `user::state` | User | Parameterized address spaces, context management, binding lifecycle, and state transitions |
| `kernel::reduction` | Kernel | Sequential composition of the foundation's nine inter-algebra maps into a parameterized reduction pipeline |
| `kernel::convergence` | Kernel | Hopf convergence tower: four levels R, C, H, O corresponding to the four normed division algebras of dimensions 1, 2, 4, 8 |
| `kernel::division` | Kernel | The four normed division algebras R, C, H, O and the Cayley-Dickson construction |
| `bridge::interaction` | Bridge | Multi-entity interaction: commutator states, associator triples, negotiation convergence |
| `kernel::monoidal` | Kernel | Sequential composition of computations via monoidal product A ⊗ B |
| `kernel::operad` | Kernel | Structural type nesting via operad composition |
| `kernel::effect` | Kernel | Typed endomorphisms on state:Context classified by site target |
| `kernel::predicate` | Kernel | Boolean-valued functions on kernel objects |
| `kernel::parallel` | Kernel | Independent computations over provably disjoint site budgets |
| `kernel::stream` | Kernel | Coinductive sequences of reduction epochs |
| `kernel::failure` | Kernel | Partial computations, typed failure propagation, and recovery |
| `kernel::linear` | Kernel | Linear discipline on site consumption |
| `kernel::recursion` | Kernel | Self-referential computations with well-founded descent measures guaranteeing termination |
| `kernel::region` | Kernel | Spatial locality of content-addressed ring elements |
| `bridge::boundary` | Bridge | Typed interface between kernel computation and the external world |
| `bridge::conformance_` | Bridge | SHACL-equivalent constraint shapes defining what a Prism implementation must provide at each extension point |
| `enums` | — | Controlled vocabulary enums (WittLevel, PrimitiveOp, etc.) |
| `enforcement` | — | Opaque witnesses, declarative builders, Term AST |

## 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.

```rust,ignore
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.

```rust,ignore
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](https://github.com/UOR-Foundation/UOR-Framework/blob/main/LICENSE).