uor-foundation 0.3.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

// @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::HostTypes;

/// 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<H: HostTypes> {}

/// A typed source of external data entering the ring. Carries an expected TypeDefinition describing the shape of incoming data.
pub trait Source<H: HostTypes>: IOBoundary<H> {
    /// Associated type for `TypeDefinition`.
    type TypeDefinition: crate::user::type_::TypeDefinition<H>;
    /// The expected type of data arriving from this source.
    fn source_type(&self) -> &Self::TypeDefinition;
}

/// A typed destination for data leaving the ring. Carries an expected TypeDefinition describing the shape of outgoing data.
pub trait Sink<H: HostTypes>: IOBoundary<H> {
    /// Associated type for `TypeDefinition`.
    type TypeDefinition: crate::user::type_::TypeDefinition<H>;
    /// The expected type of data departing through this sink.
    fn sink_type(&self) -> &Self::TypeDefinition;
}

/// An effect that crosses the kernel/external boundary. Specializes effect:ExternalEffect with explicit source or sink binding.
pub trait BoundaryEffect<H: HostTypes>: crate::kernel::effect::ExternalEffect<H> {
    /// Associated type for `IOBoundary`.
    type IOBoundary: IOBoundary<H>;
    /// 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) -> bool;
}

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

/// A BoundaryEffect that writes a ring datum to a Sink.
pub trait EmitEffect<H: HostTypes>: BoundaryEffect<H> {
    /// Associated type for `Sink`.
    type Sink: Sink<H>;
    /// 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<H: HostTypes> {
    /// Associated type for `TypeDefinition`.
    type TypeDefinition: crate::user::type_::TypeDefinition<H>;
    /// The type specification for boundary data.
    fn protocol_type(&self) -> &Self::TypeDefinition;
    /// Associated type for `Conjunction`.
    type Conjunction: crate::user::type_::Conjunction<H>;
    /// Sequencing constraints on boundary data.
    fn protocol_ordering(&self) -> &Self::Conjunction;
}

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