uor-foundation 0.3.0

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

//! UOR Foundation — typed Rust traits for the complete ontology.
//!
//! Version: 0.3.0
//!
//! 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):
//!
//! ```text
//!  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.
//!
//! # 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`.
//!
//! ```no_run
//! 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
//! }
//! ```
//!
//!
//! # 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.
//!
//! # 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.

#![no_std]

pub mod bridge;
pub mod enforcement;
pub mod enums;
pub mod kernel;
pub mod pipeline;
pub mod user;

pub use enums::*;

pub use enforcement::{
    BindingEntry, BindingsTable, BindingsTableError, BoundConstraint, Calibration,
    CalibrationError, Certificate, CertificateKind, Certified, CompileUnit, CompileUnitBuilder,
    ContentAddress, ContentFingerprint, Derivation, Grounded, GroundingCertificate, Hasher,
    LandauerBudget, MultiplicationCertificate, Nanos, PipelineFailure, ReplayError, ShapeViolation,
    Term, TermArena, TermList, Trace, TraceEvent, UorTime, Validated, FINGERPRINT_MAX_BYTES,
    FINGERPRINT_MIN_BYTES, TRACE_MAX_EVENTS, TRACE_REPLAY_FORMAT_VERSION,
};

/// 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.
/// # Example
/// ```
/// use uor_foundation::{HostTypes, DefaultHostTypes};
/// // Canonical defaults: f64 / str / [u8].
/// type DefaultH = DefaultHostTypes;
/// // Override the Decimal slot for embedded targets with tighter precision:
/// struct EmbeddedHost;
/// impl HostTypes for EmbeddedHost {
///     type Decimal = f32;          // override
///     type HostString = str;       // default
///     type WitnessBytes = [u8];    // default
/// }
/// # let _ = (core::marker::PhantomData::<DefaultH>, core::marker::PhantomData::<EmbeddedHost>);
/// ```
pub trait HostTypes {
    /// Real-number representation for kernel observables (entropies, amplitudes, rates).
    /// `DefaultHostTypes` selects `f64`. Override with higher-precision or interval
    /// arithmetic as needed.
    type Decimal;

    /// Host-supplied opaque string (NOT a foundation IRI).
    /// `DefaultHostTypes` selects `str`. Override with owned `String`, `Cow<'_, str>`,
    /// etc. for embedded / host-heap environments.
    type HostString: ?Sized;

    /// Host-supplied opaque byte sequence (NOT a foundation `canonicalBytes` constant).
    /// `DefaultHostTypes` selects `[u8]`. Override with owned `Vec<u8>`, `Bytes`,
    /// etc. for host-heap environments.
    type WitnessBytes: ?Sized;
}

/// 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.
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash)]
pub struct DefaultHostTypes;

impl HostTypes for DefaultHostTypes {
    type Decimal = f64;
    type HostString = str;
    type WitnessBytes = [u8];
}