sim_lib_stream_fabric/
lib.rs

1#![forbid(unsafe_code)]
2#![deny(missing_docs)]
3//! Content-addressed distributed evaluation for remote stream realization.
4//!
5//! This crate is the EvalFabric / realize transport layer for SIM streams: the
6//! location-transparent eval surface that server and agent code target to place
7//! work and exchange streams, rather than reaching for transport-specific APIs.
8//! It turns `StreamValue` packet spines into kernel chunk events or existing
9//! server stream frames, and turns event or frame buffers back into lazy stream
10//! spines. It stays in library space: it does not add server frame kinds or
11//! kernel object hooks.
12//!
13//! Content-addressed evaluation treats a fleet as a store of immutable eval
14//! replies. [`ContentServeFabric`] answers a request only if this node already
15//! holds its [`ContentKey`]. [`ContentAddressedFabric`] presents local and peer
16//! cassettes as one [`EvalFabric`]: it checks the local [`EvalCassette`], asks
17//! peers that hold the content id, computes on a home site when no holder has
18//! the reply, and records every successful reply so this node becomes a holder
19//! too. There is no routing table; the lookup question is simply "who holds
20//! content id X." [`HoldingIndex`] is a grow-only gossip index of holders.
21//! Because content never mutates, a holder fact is never invalidated and the
22//! index needs no consensus. Recovery is [`EvalCassette::from_ledger`] replay.
23//! The `FleetRelayFabric` design names the explicit-routing alternative for
24//! small, statically known fleets.
25//!
26//! The surface has four families:
27//!
28//! - Control plane: [`StreamControl`] and its frame round-trip carry open, next,
29//!   push, close, cancel, stats, metadata, and fault actions between peers.
30//! - Frame codec: [`stream_to_frames`] and the `stream_frames_to_*` family
31//!   encode a stream into bounded server frames and decode them back, applying
32//!   [`StreamFrameLimits`].
33//! - Placement: [`ServerPlacementRequest`] and [`server_placement_stream_frames`]
34//!   place a fragment on a site under [`PlacementResourceLimits`], with sensitive
35//!   inputs redacted by [`redact_placement_expr`].
36//! - Realize requests: [`stream_realize_request`] and [`realize_stream_events`]
37//!   bridge a stream to the realize event surface.
38//! - Relay surfaces: [`RelayFabric`] carries a surface session as a remote
39//!   [`EvalFabric`] node. [`ContentKey`] gives each stable [`EvalRequest`] a
40//!   deterministic identity, [`EvalCassette`] stores successful replies in an
41//!   effect-ledger-backed cache, [`LedgeredRelayFabric`] adds cache-first
42//!   cassette replay and write-through around any inner fabric, and
43//!   [`ContentAddressedFabric`] resolves work from any holder by content id.
44//!   Capability policy stays with the inner fabric and is not weakened by
45//!   caching.
46//!
47//! [`EvalFabric`]: sim_kernel::EvalFabric
48//! [`EvalRequest`]: sim_kernel::EvalRequest
49
50mod cassette;
51mod content_key;
52mod control;
53mod events;
54mod frames;
55mod holders;
56mod ledgered_relay;
57mod placement;
58mod placement_report;
59mod placement_security;
60mod relay;
61mod request;
62mod store;
63
64pub use cassette::{EffectLedgerCassette, EvalCassette, EvalCassetteLedger};
65pub use content_key::ContentKey;
66pub use control::{
67    StreamControl, stream_control_cancel_symbol, stream_control_close_symbol,
68    stream_control_fault_symbol, stream_control_frame_from_control, stream_control_from_frame,
69    stream_control_metadata_symbol, stream_control_next_symbol, stream_control_open_symbol,
70    stream_control_operation_symbols, stream_control_push_symbol,
71    stream_control_required_capability, stream_control_stats_symbol,
72};
73pub use events::{
74    event_buffer_to_stream, expr_chunk_event, refused_profile_diagnostic_kind,
75    remote_error_diagnostic_kind, stream_limit_diagnostic_kind,
76};
77pub use frames::{
78    StreamFrameLimits, cassette_to_stream_frames, expr_to_stream_chunk_frame,
79    remote_frame_to_event, stream_chunk_frame_to_expr, stream_frames_to_cassette,
80    stream_frames_to_events, stream_frames_to_stream, stream_to_frames,
81    stream_to_frames_with_envelope, stream_to_frames_with_limits, stream_to_frames_with_profile,
82};
83pub use holders::HoldingIndex;
84pub use ledgered_relay::{LedgeredRelayFabric, ledgered_relay_fabric_value};
85pub use placement::{
86    ServerPlacementRequest, server_buffered_preview_profile,
87    server_placement_frame_operation_symbols, server_placement_refusal_diagnostic_kind,
88    server_placement_refusal_symbol, server_placement_request_symbol,
89    server_placement_result_symbol, server_placement_stream_frames, server_render_return_profile,
90    server_site_symbol,
91};
92pub use placement_security::{
93    PlacementCapability, PlacementResourceLimits, placement_capability_names,
94    placement_host_device_capability, placement_remote_render_capability,
95    placement_run_node_on_lan_peer_capability, placement_run_node_on_server_capability,
96    redact_placement_expr,
97};
98pub use relay::{RelayFabric, RelayStatus};
99pub use request::{realize_placed_stream_events, realize_stream_events, stream_realize_request};
100pub use store::{ContentAddressedFabric, ContentPeer, ContentServeFabric, HeldContent};
101
102#[cfg(test)]
103mod control_tests;
104#[cfg(test)]
105mod placement_tests;
106#[cfg(test)]
107mod store_tests;
108#[cfg(test)]
109mod tests;
sim_lib_stream_fabric/lib.rs

sim_lib_stream_fabric/
lib.rs
