uor-foundation 0.1.3

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

//! `schema/` namespace — Core value types and term language for the UOR ring substrate. Defines Datum (ring element), Term (syntactic expression), and the Ring container..
//!
//! Space: Kernel

use crate::enums::QuantumLevel;
use crate::Primitives;

/// An element of the ring Z/(2^n)Z at a specific quantum level n. The primary semantic value type. Disjoint from Term: datums are values, terms are syntactic expressions that evaluate to datums.
/// Disjoint with: Term.
pub trait Datum<P: Primitives> {
    /// The integer value of a datum element. For a Datum in Z/(2^n)Z, this is an integer in \[0, 2^n).
    fn value(&self) -> P::NonNegativeInteger;
    /// The quantum level n of a datum, where the datum's ring is Z/(2^n)Z. Determines the bit width and modulus of the datum.
    fn quantum(&self) -> P::PositiveInteger;
    /// The ring-layer index of a datum, indicating its position in the stratification of Z/(2^n)Z.
    fn stratum(&self) -> P::NonNegativeInteger;
    /// The bit-pattern representation of a datum, encoding its position in the hypercube geometry of Z/(2^n)Z.
    fn spectrum(&self) -> &P::String;
    /// Associated type for `Address`.
    type Address: crate::kernel::address::Address<P>;
    /// The Braille address associated with this datum, linking the algebraic value to its content-addressable identifier.
    fn glyph(&self) -> &Self::Address;
}

/// A syntactic expression in the UOR term language. Terms are evaluated to produce Datums. Disjoint from Datum.
/// Disjoint with: Datum.
pub trait Term<P: Primitives> {}

/// A three-component structure encoding an element's position in the UOR address space: stratum (ring layer), spectrum (bit pattern), and glyph (Braille address).
pub trait Triad<P: Primitives> {}

/// A term that directly denotes a datum value. A Literal is a leaf node in the term language — it refers to a concrete Datum via schema:denotes without being a Datum itself.
pub trait Literal<P: Primitives>: Term<P> {
    /// Associated type for `Datum`.
    type Datum: Datum<P>;
    /// The datum value that a Literal term denotes. Bridges the Term/Datum disjointness: a Literal refers to a Datum without being one. Evaluation of a Literal produces its denoted Datum.
    fn denotes(&self) -> &Self::Datum;
}

/// A term formed by applying an operation to one or more argument terms. The application's value is the result of evaluating the operator on the evaluated arguments.
pub trait Application<P: Primitives>: Term<P> {
    /// Associated type for `Operation`.
    type Operation: crate::kernel::op::Operation<P>;
    /// The operation applied in an Application term.
    fn operator(&self) -> &Self::Operation;
    /// Associated type for `Term`.
    type Term: Term<P>;
    /// An argument term in an Application. The ordering of arguments follows rdf:List semantics.
    fn argument(&self) -> &[Self::Term];
}

/// The ambient ring Z/(2^n)Z at a specific quantum level n. The Ring is the primary data structure of the UOR kernel. Its two generators (negation and complement) produce the dihedral group D_{2^n} that governs the invariance frame.
pub trait Ring<P: Primitives> {
    /// The bit width n of the ring Z/(2^n)Z. Distinct from schema:quantum on Datum — ringQuantum is the container's bit width; datum quantum is a membership property.
    fn ring_quantum(&self) -> P::PositiveInteger;
    /// The modulus 2^n of the ring. Equals 2 raised to the power of ringQuantum.
    fn modulus(&self) -> P::PositiveInteger;
    /// Associated type for `Datum`.
    type Datum: Datum<P>;
    /// The generator element π₁ (value = 1) of the ring. Under iterated successor application, π₁ generates all ring elements.
    fn generator(&self) -> &Self::Datum;
    /// Associated type for `Involution`.
    type Involution: crate::kernel::op::Involution<P>;
    /// The ring reflection involution: neg(x) = (-x) mod 2^n. One of the two generators of the dihedral group D_{2^n}.
    fn negation(&self) -> &Self::Involution;
    /// The hypercube reflection involution: bnot(x) = (2^n - 1) ⊕ x. The second generator of the dihedral group D_{2^n}.
    fn complement(&self) -> &Self::Involution;
    /// The quantum level at which this Ring instance operates. Links a concrete Ring individual to its QuantumLevel.
    fn at_quantum_level(&self) -> QuantumLevel;
}

/// The concrete ring Z/(2^16)Z at quantum level 16. Subclass of schema:Ring. Carries 65,536 elements. Q1Ring is the first extension of the default Q0 ring and is the target of Amendment 26's universality proofs.
pub trait Q1Ring<P: Primitives>: Ring<P> {
    /// Bit width of the Q1 ring: 16.
    fn q1bit_width(&self) -> P::PositiveInteger;
    /// Carrier set size of the Q1 ring: 65,536 elements.
    fn q1capacity(&self) -> P::PositiveInteger;
}

/// The unique generator of R_n under successor. Value = 1 at every quantum level. Under iterated application of succ, π₁ generates every element of the ring.
pub mod pi1 {
    /// `value`
    pub const VALUE: i64 = 1;
}

/// The additive identity of the ring. Value = 0 at every quantum level. op:add(x, zero) = x for all x in R_n.
pub mod zero {
    /// `value`
    pub const VALUE: i64 = 0;
}

/// Quantum level 0: 8-bit ring Z/256Z, 256 states. The reference level for all ComputationCertificate proofs in the spec.
pub mod q0 {
    /// `bitsWidth`
    pub const BITS_WIDTH: i64 = 8;
    /// `cycleSize`
    pub const CYCLE_SIZE: i64 = 256;
    /// `nextLevel` -> `Q1`
    pub const NEXT_LEVEL: &str = "https://uor.foundation/schema/Q1";
    /// `quantumIndex`
    pub const QUANTUM_INDEX: i64 = 0;
}

/// Quantum level 1: 16-bit ring Z/65536Z, 65,536 states.
pub mod q1 {
    /// `bitsWidth`
    pub const BITS_WIDTH: i64 = 16;
    /// `cycleSize`
    pub const CYCLE_SIZE: i64 = 65536;
    /// `levelSuccessor` -> `Q0`
    pub const LEVEL_SUCCESSOR: &str = "https://uor.foundation/schema/Q0";
    /// `nextLevel` -> `Q2`
    pub const NEXT_LEVEL: &str = "https://uor.foundation/schema/Q2";
    /// `quantumIndex`
    pub const QUANTUM_INDEX: i64 = 1;
}

/// Quantum level 2: 24-bit ring Z/16777216Z, 16,777,216 states.
pub mod q2 {
    /// `bitsWidth`
    pub const BITS_WIDTH: i64 = 24;
    /// `cycleSize`
    pub const CYCLE_SIZE: i64 = 16777216;
    /// `levelSuccessor` -> `Q1`
    pub const LEVEL_SUCCESSOR: &str = "https://uor.foundation/schema/Q1";
    /// `nextLevel` -> `Q3`
    pub const NEXT_LEVEL: &str = "https://uor.foundation/schema/Q3";
    /// `quantumIndex`
    pub const QUANTUM_INDEX: i64 = 2;
}

/// Quantum level 3: 32-bit ring Z/4294967296Z, 4,294,967,296 states. The highest named level in the spec. nextLevel is absent — Prism implementations may extend the chain.
pub mod q3 {
    /// `bitsWidth`
    pub const BITS_WIDTH: i64 = 32;
    /// `cycleSize`
    pub const CYCLE_SIZE: i64 = 4294967296;
    /// `levelSuccessor` -> `Q2`
    pub const LEVEL_SUCCESSOR: &str = "https://uor.foundation/schema/Q2";
    /// `quantumIndex`
    pub const QUANTUM_INDEX: i64 = 3;
}