sim_lib_bridge/
lib.rs

1//! Checked BRIDGE packet runtime for SIM model exchanges.
2//!
3//! `sim-lib-bridge` is the send/receive guard around the reversible BRIDGE packet
4//! codec (`sim-codec-bridge`). It runs packets: validation, capability ceilings,
5//! content-addressed request identity, model-request construction, response
6//! decoding, the shared frontier engine, and the four profile helpers. It targets
7//! [`EvalFabric`](sim_kernel::EvalFabric) and the provider-neutral runner
8//! contracts; it does not own transports or model providers.
9//!
10//! # One checker, both directions
11//!
12//! There is exactly one receive checker (`rx_check`), and transmit runs it on its
13//! own output before anything leaves SIM -- so a peer never bounces a packet its
14//! author believed well-formed.
15//!
16//! ```text
17//! TX  `bridge_tx` / `run_bridge`:
18//!       canonicalize -> stamp cid -> assert_roundtrip -> render_model_face
19//!       -> assert_total_ownership -> rx_check (the self-check gate)
20//!       -> ModelRequest in EvalRequest.expr -> realize_final
21//! RX  `bridge_rx` / `bridge_rx_response`:
22//!       terminal_response_packet (LAST content item) -> decode -> rx_check:
23//!       move legality + from/to inversion + parent-`Return` reply legality
24//!       + per-part shape checks -> BridgeReport (accepted, obligations, repair menus)
25//! ```
26//!
27//! `effective_caps` resolves the header ceiling and every acting step runs under
28//! `diminish(current, ceiling)`. `verify_warrant` turns a stale-book packet into a
29//! `Fetch` obligation instead of a hard failure or a silent accept.
30//!
31//! # Profiles (helpers over the one packet)
32//!
33//! - **ASK** -- `ask_packet` / `run_ask` / `run_ask_with_policy`: a typed model
34//!   call whose arguments are fenced data and whose reply is validated against the
35//!   declared `Return` shape, with bounded `RepairPolicy` on an `AskFailure`.
36//! - **BRIEF** -- `bridge_brief` / `render_brief_sentences`: controlled
37//!   instruction frames rendered as fluent cited sentences.
38//! - **LOOM** -- `validate_weave` / `weave_row_by_row` over `frontier` /
39//!   `FrontierMenu`: model-authored program bodies, checked row by row against a
40//!   flat menu, with `LoomObligation`s carrying the valid replacement.
41//! - **COLLAB** -- `merge_bridge_replies` / `MergePolicy`: typed reviews, votes,
42//!   and patches merged by exact parent cid and target path;
43//!   `receipt_packet_for_report` serializes the report lens back onto the wire.
44//!
45//! `materialize_given` / `fetch_obligation` implement budgeted context with the
46//! `Fetch` affordance; `install_bridge_lib` / `BridgeLib` register the runtime
47//! verbs (`bridge/tx`, `bridge/rx`, `bridge/ask`, `bridge/brief`, ...).
48
49#![forbid(unsafe_code)]
50#![deny(missing_docs)]
51
52mod ask;
53mod brief;
54mod collab;
55mod frontier;
56mod loom_validate;
57mod loom_woven;
58mod materialize;
59mod model;
60mod parent;
61mod receipt;
62mod repair;
63mod report;
64mod runtime;
65mod rx;
66mod tx;
67mod warrant;
68
69#[cfg(test)]
70mod tests;
71
72pub use ask::{
73    ask_default_codec, ask_packet, ask_packet_with_model_params, run_ask, run_ask_with_policy,
74};
75pub use brief::{bridge_brief, render_brief_sentences};
76pub use collab::{MergePolicy, merge_bridge_replies};
77pub use frontier::{FrontierMenu, frontier};
78pub use loom_validate::{LoomObligation, next_frontier_menu, validate_weave};
79pub use loom_woven::{validate_woven_row, weave_row_by_row};
80pub use materialize::{
81    GivenMaterialization, bridge_fetch_capability, bridge_given_materialize_capability,
82    fetch_obligation, materialize_given,
83};
84pub use model::{
85    bridge_request_content_key, output_contract_for_packet, terminal_bridge_text,
86    terminal_response_packet,
87};
88pub use receipt::{receipt_packet_for_report, receipt_symbol};
89pub use repair::{AskFailure, RepairPolicy};
90pub use report::{BridgeObligation, BridgeReport};
91pub use runtime::{
92    BridgeFunction, BridgeFunctionKind, BridgeLib, bridge_ask_symbol, bridge_brief_symbol,
93    bridge_report_symbol, bridge_rx_symbol, bridge_tx_symbol, install_bridge_lib, manifest_name,
94};
95pub use rx::{bridge_rx, bridge_rx_response, effective_caps, rx_check};
96pub use tx::{bridge_tx, prepare_packet, render_model_face, run_bridge};
97pub use warrant::verify_warrant;
98
99/// Cookbook recipes embedded from this crate's `recipes/` directory.
100pub static RECIPES: sim_cookbook::EmbeddedDir =
101    include!(concat!(env!("OUT_DIR"), "/cookbook_recipes.rs"));
sim_lib_bridge/lib.rs

sim_lib_bridge/
lib.rs
