uor-foundation 0.3.5

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

//! `stream/` namespace — Coinductive sequences of reduction epochs. Each epoch terminates independently; the stream is the unbounded composition of terminating epochs..
//!
//! Space: Kernel

use crate::HostTypes;

/// An unbounded sequence of reduction epochs where each epoch terminates and produces a well-typed output. The coinductive dual of a finite computation.
pub trait ProductiveStream<H: HostTypes> {
    /// Always true by construction: every epoch terminates. Invariant, not computed.
    fn is_productive(&self) -> bool;
    /// Associated type for `Term`.
    type Term: crate::kernel::schema::Term<H>;
    /// A term denoting a function from the current seed value to a pair (head, next_seed).
    fn step_term(&self) -> &Self::Term;
    /// IRI of a proof of stream productivity (coinductive well-foundedness).
    fn productivity_witness(&self) -> &H::HostString;
}

/// A single bounded iteration within a productive stream. Each epoch is a complete reduction execution from Initialization through Convergence.
pub trait Epoch<H: HostTypes> {
    /// Associated type for `EulerReduction`.
    type EulerReduction: crate::kernel::reduction::EulerReduction<H>;
    /// The reduction execution for this epoch.
    fn epoch_reduction(&self) -> &Self::EulerReduction;
    /// Associated type for `Datum`.
    type Datum: crate::kernel::schema::Datum<H>;
    /// The output datum produced by this epoch.
    fn epoch_output(&self) -> &Self::Datum;
    /// Associated type for `Context`.
    type Context: crate::user::state::Context<H>;
    /// The context at the start of this epoch.
    fn epoch_context(&self) -> &Self::Context;
    /// Zero-based index of this epoch in the stream.
    fn epoch_index(&self) -> u64;
}

/// The transition point between consecutive epochs. Carries the continuation context and the epoch output.
pub trait EpochBoundary<H: HostTypes> {
    /// Associated type for `Epoch`.
    type Epoch: Epoch<H>;
    /// The epoch that just completed.
    fn boundary_from(&self) -> &Self::Epoch;
    /// The epoch about to begin.
    fn boundary_to(&self) -> &Self::Epoch;
    /// Associated type for `Context`.
    type Context: crate::user::state::Context<H>;
    /// The context carried across the boundary.
    fn continuation_context(&self) -> &Self::Context;
}

/// A finite prefix of a productive stream: the first k epochs and their outputs. Every finite prefix is computable in finite time.
pub trait StreamPrefix<H: HostTypes> {
    /// Associated type for `Epoch`.
    type Epoch: Epoch<H>;
    /// The epochs in this prefix (ordered by stream:epochIndex).
    fn prefix_epochs(&self) -> &[Self::Epoch];
    /// Number of epochs in this prefix.
    fn prefix_length(&self) -> u64;
}

/// A transform between productive streams: maps each epoch of the source to an epoch of the target while preserving the productive property.
pub trait StreamMorphism<H: HostTypes>: crate::user::morphism::Transform<H> {}

/// The coinductive constructor: given an initial context and a step function (a morphism:ComputationDatum), produces a ProductiveStream. The step function must be certified to always reach reduction convergence.
pub trait Unfold<H: HostTypes> {
    /// Associated type for `Context`.
    type Context: crate::user::state::Context<H>;
    /// The initial context for the stream.
    fn unfold_seed(&self) -> &Self::Context;
    /// Associated type for `ComputationDatum`.
    type ComputationDatum: crate::user::morphism::ComputationDatum<H>;
    /// The certified step function producing each epoch.
    fn unfold_step(&self) -> &Self::ComputationDatum;
    /// Associated type for `ProductiveStream`.
    type ProductiveStream: ProductiveStream<H>;
    /// The stream produced by this unfold.
    fn unfold_result(&self) -> &Self::ProductiveStream;
}

#[doc(hidden)]
#[doc = "THEORY-DEFERRED \u{2014} not a valid implementation; see [docs/theory_deferred.md]. Exists only to satisfy downstream trait-bound references."]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct NullProductiveStream<H: HostTypes> {
    _phantom: core::marker::PhantomData<H>,
}
impl<H: HostTypes> Default for NullProductiveStream<H> {
    fn default() -> Self {
        Self {
            _phantom: core::marker::PhantomData,
        }
    }
}
impl<H: HostTypes> NullProductiveStream<H> {
    /// Absent-value sentinel. `&Self::ABSENT` gives every trait-typed accessor a `'static`-lifetime reference target.
    pub const ABSENT: NullProductiveStream<H> = NullProductiveStream {
        _phantom: core::marker::PhantomData,
    };
}
impl<H: HostTypes> ProductiveStream<H> for NullProductiveStream<H> {
    fn is_productive(&self) -> bool {
        false
    }
    type Term = crate::kernel::schema::NullTerm<H>;
    fn step_term(&self) -> &Self::Term {
        &<crate::kernel::schema::NullTerm<H>>::ABSENT
    }
    fn productivity_witness(&self) -> &H::HostString {
        H::EMPTY_HOST_STRING
    }
}

#[doc(hidden)]
#[doc = "THEORY-DEFERRED \u{2014} not a valid implementation; see [docs/theory_deferred.md]. Exists only to satisfy downstream trait-bound references."]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct NullEpoch<H: HostTypes> {
    _phantom: core::marker::PhantomData<H>,
}
impl<H: HostTypes> Default for NullEpoch<H> {
    fn default() -> Self {
        Self {
            _phantom: core::marker::PhantomData,
        }
    }
}
impl<H: HostTypes> NullEpoch<H> {
    /// Absent-value sentinel. `&Self::ABSENT` gives every trait-typed accessor a `'static`-lifetime reference target.
    pub const ABSENT: NullEpoch<H> = NullEpoch {
        _phantom: core::marker::PhantomData,
    };
}
impl<H: HostTypes> Epoch<H> for NullEpoch<H> {
    type EulerReduction = crate::kernel::reduction::NullEulerReduction<H>;
    fn epoch_reduction(&self) -> &Self::EulerReduction {
        &<crate::kernel::reduction::NullEulerReduction<H>>::ABSENT
    }
    type Datum = crate::kernel::schema::NullDatum<H>;
    fn epoch_output(&self) -> &Self::Datum {
        &<crate::kernel::schema::NullDatum<H>>::ABSENT
    }
    type Context = crate::user::state::NullContext<H>;
    fn epoch_context(&self) -> &Self::Context {
        &<crate::user::state::NullContext<H>>::ABSENT
    }
    fn epoch_index(&self) -> u64 {
        0
    }
}

#[doc(hidden)]
#[doc = "THEORY-DEFERRED \u{2014} not a valid implementation; see [docs/theory_deferred.md]. Exists only to satisfy downstream trait-bound references."]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct NullEpochBoundary<H: HostTypes> {
    _phantom: core::marker::PhantomData<H>,
}
impl<H: HostTypes> Default for NullEpochBoundary<H> {
    fn default() -> Self {
        Self {
            _phantom: core::marker::PhantomData,
        }
    }
}
impl<H: HostTypes> NullEpochBoundary<H> {
    /// Absent-value sentinel. `&Self::ABSENT` gives every trait-typed accessor a `'static`-lifetime reference target.
    pub const ABSENT: NullEpochBoundary<H> = NullEpochBoundary {
        _phantom: core::marker::PhantomData,
    };
}
impl<H: HostTypes> EpochBoundary<H> for NullEpochBoundary<H> {
    type Epoch = NullEpoch<H>;
    fn boundary_from(&self) -> &Self::Epoch {
        &<NullEpoch<H>>::ABSENT
    }
    fn boundary_to(&self) -> &Self::Epoch {
        &<NullEpoch<H>>::ABSENT
    }
    type Context = crate::user::state::NullContext<H>;
    fn continuation_context(&self) -> &Self::Context {
        &<crate::user::state::NullContext<H>>::ABSENT
    }
}

#[doc(hidden)]
#[doc = "THEORY-DEFERRED \u{2014} not a valid implementation; see [docs/theory_deferred.md]. Exists only to satisfy downstream trait-bound references."]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct NullStreamPrefix<H: HostTypes> {
    _phantom: core::marker::PhantomData<H>,
}
impl<H: HostTypes> Default for NullStreamPrefix<H> {
    fn default() -> Self {
        Self {
            _phantom: core::marker::PhantomData,
        }
    }
}
impl<H: HostTypes> NullStreamPrefix<H> {
    /// Absent-value sentinel. `&Self::ABSENT` gives every trait-typed accessor a `'static`-lifetime reference target.
    pub const ABSENT: NullStreamPrefix<H> = NullStreamPrefix {
        _phantom: core::marker::PhantomData,
    };
}
impl<H: HostTypes> StreamPrefix<H> for NullStreamPrefix<H> {
    type Epoch = NullEpoch<H>;
    fn prefix_epochs(&self) -> &[Self::Epoch] {
        &[]
    }
    fn prefix_length(&self) -> u64 {
        0
    }
}

#[doc(hidden)]
#[doc = "THEORY-DEFERRED \u{2014} not a valid implementation; see [docs/theory_deferred.md]. Exists only to satisfy downstream trait-bound references."]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct NullStreamMorphism<H: HostTypes> {
    _phantom: core::marker::PhantomData<H>,
}
impl<H: HostTypes> Default for NullStreamMorphism<H> {
    fn default() -> Self {
        Self {
            _phantom: core::marker::PhantomData,
        }
    }
}
impl<H: HostTypes> NullStreamMorphism<H> {
    /// Absent-value sentinel. `&Self::ABSENT` gives every trait-typed accessor a `'static`-lifetime reference target.
    pub const ABSENT: NullStreamMorphism<H> = NullStreamMorphism {
        _phantom: core::marker::PhantomData,
    };
}
impl<H: HostTypes> crate::user::morphism::Transform<H> for NullStreamMorphism<H> {
    fn source(&self) -> &H::HostString {
        H::EMPTY_HOST_STRING
    }
    fn target(&self) -> &H::HostString {
        H::EMPTY_HOST_STRING
    }
    fn preserves_count(&self) -> usize {
        0
    }
    fn preserves_at(&self, _index: usize) -> &H::HostString {
        H::EMPTY_HOST_STRING
    }
    type ComputationTrace = crate::bridge::trace::NullComputationTrace<H>;
    fn trace(&self) -> &Self::ComputationTrace {
        &<crate::bridge::trace::NullComputationTrace<H>>::ABSENT
    }
    type TransformTarget = crate::user::morphism::NullTransform<H>;
    fn composes_with(&self) -> &[Self::TransformTarget] {
        &[]
    }
    type Identity = crate::kernel::op::NullIdentity<H>;
    fn preserved_invariant(&self) -> &Self::Identity {
        &<crate::kernel::op::NullIdentity<H>>::ABSENT
    }
    fn input_class(&self) -> &H::HostString {
        H::EMPTY_HOST_STRING
    }
    fn output_class(&self) -> &H::HostString {
        H::EMPTY_HOST_STRING
    }
    type Witness = crate::user::morphism::NullWitness<H>;
    fn has_witness(&self) -> &[Self::Witness] {
        &[]
    }
}
impl<H: HostTypes> StreamMorphism<H> for NullStreamMorphism<H> {}

#[doc(hidden)]
#[doc = "THEORY-DEFERRED \u{2014} not a valid implementation; see [docs/theory_deferred.md]. Exists only to satisfy downstream trait-bound references."]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct NullUnfold<H: HostTypes> {
    _phantom: core::marker::PhantomData<H>,
}
impl<H: HostTypes> Default for NullUnfold<H> {
    fn default() -> Self {
        Self {
            _phantom: core::marker::PhantomData,
        }
    }
}
impl<H: HostTypes> NullUnfold<H> {
    /// Absent-value sentinel. `&Self::ABSENT` gives every trait-typed accessor a `'static`-lifetime reference target.
    pub const ABSENT: NullUnfold<H> = NullUnfold {
        _phantom: core::marker::PhantomData,
    };
}
impl<H: HostTypes> Unfold<H> for NullUnfold<H> {
    type Context = crate::user::state::NullContext<H>;
    fn unfold_seed(&self) -> &Self::Context {
        &<crate::user::state::NullContext<H>>::ABSENT
    }
    type ComputationDatum = crate::user::morphism::NullComputationDatum<H>;
    fn unfold_step(&self) -> &Self::ComputationDatum {
        &<crate::user::morphism::NullComputationDatum<H>>::ABSENT
    }
    type ProductiveStream = NullProductiveStream<H>;
    fn unfold_result(&self) -> &Self::ProductiveStream {
        &<NullProductiveStream<H>>::ABSENT
    }
}