uor-foundation 0.2.0

UOR Foundation — typed Rust traits for the complete ontology. Import and implement.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

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

//! `boundary/` namespace — Typed interface between kernel computation and the external world. Formalizes how data enters and exits the ring substrate..
//!
//! Space: Bridge

use crate::Primitives;

/// A typed interface point between the kernel and the external world. Every data flow into or out of the ring crosses exactly one IOBoundary.
pub trait IOBoundary<P: Primitives> {}

/// A typed source of external data entering the ring. Carries an expected TypeDefinition describing the shape of incoming data.
pub trait Source<P: Primitives>: IOBoundary<P> {
    /// Associated type for `TypeDefinition`.
    type TypeDefinition: crate::user::type_::TypeDefinition<P>;
    /// The expected type of data arriving from this source.
    fn source_type(&self) -> &Self::TypeDefinition;
    /// Associated type for `GroundingMap`.
    type GroundingMap: crate::user::morphism::GroundingMap<P>;
    /// The grounding map that transforms incoming surface data to ring datums.
    fn source_grounding(&self) -> &Self::GroundingMap;
}

/// A typed destination for data leaving the ring. Carries an expected TypeDefinition describing the shape of outgoing data.
pub trait Sink<P: Primitives>: IOBoundary<P> {
    /// Associated type for `TypeDefinition`.
    type TypeDefinition: crate::user::type_::TypeDefinition<P>;
    /// The expected type of data departing through this sink.
    fn sink_type(&self) -> &Self::TypeDefinition;
    /// Associated type for `ProjectionMap`.
    type ProjectionMap: crate::user::morphism::ProjectionMap<P>;
    /// The projection map that transforms ring datums to outgoing surface data.
    fn sink_projection(&self) -> &Self::ProjectionMap;
}

/// An effect that crosses the kernel/external boundary. Specializes effect:ExternalEffect with explicit source or sink binding.
pub trait BoundaryEffect<P: Primitives>: crate::kernel::effect::ExternalEffect<P> {
    /// Associated type for `IOBoundary`.
    type IOBoundary: IOBoundary<P>;
    /// The boundary this effect crosses.
    fn effect_boundary(&self) -> &Self::IOBoundary;
    /// True iff applying the boundary effect twice produces the same result as applying it once.
    fn is_idempotent(&self) -> P::Boolean;
}

/// A BoundaryEffect that reads from a Source and produces a datum in the ring.
pub trait IngestEffect<P: Primitives>: BoundaryEffect<P> {
    /// Associated type for `Source`.
    type Source: Source<P>;
    /// The source being read.
    fn ingest_source(&self) -> &Self::Source;
}

/// A BoundaryEffect that writes a ring datum to a Sink.
pub trait EmitEffect<P: Primitives>: BoundaryEffect<P> {
    /// Associated type for `Sink`.
    type Sink: Sink<P>;
    /// The sink being written to.
    fn emit_sink(&self) -> &Self::Sink;
}

/// A specification of the data shape, ordering, and framing constraints for data crossing a boundary.
pub trait BoundaryProtocol<P: Primitives> {
    /// Associated type for `TypeDefinition`.
    type TypeDefinition: crate::user::type_::TypeDefinition<P>;
    /// The type specification for boundary data.
    fn protocol_type(&self) -> &Self::TypeDefinition;
    /// Associated type for `CompositeConstraint`.
    type CompositeConstraint: crate::user::type_::CompositeConstraint<P>;
    /// Sequencing constraints on boundary data.
    fn protocol_ordering(&self) -> &Self::CompositeConstraint;
}

/// A Session that includes BoundaryEffects. Extends the session model to track which boundaries were crossed.
pub trait BoundarySession<P: Primitives>: crate::user::state::Session<P> {
    /// Associated type for `IOBoundary`.
    type IOBoundary: IOBoundary<P>;
    /// The boundaries crossed during this session.
    fn session_boundaries(&self) -> &[Self::IOBoundary];
    /// Total number of boundary crossings in this session.
    fn crossing_count(&self) -> P::NonNegativeInteger;
}