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/run-ask`,
48//! `bridge/brief`, ...). `bridge/run-ask` accepts any object exposing
49//! [`EvalFabric`](sim_kernel::EvalFabric), a packet expression, and an optional
50//! bounded retry count.
51
52#![forbid(unsafe_code)]
53#![deny(missing_docs)]
54
55mod ask;
56mod brief;
57mod collab;
58mod frontier;
59mod loom_validate;
60mod loom_woven;
61mod materialize;
62mod model;
63mod parent;
64mod receipt;
65mod repair;
66mod report;
67mod runtime;
68mod rx;
69mod tx;
70mod warrant;
71
72#[cfg(test)]
73mod tests;
74
75pub use ask::{
76    ask_default_codec, ask_packet, ask_packet_with_model_params, run_ask, run_ask_with_policy,
77};
78pub use brief::{bridge_brief, render_brief_sentences};
79pub use collab::{MergePolicy, merge_bridge_replies};
80pub use frontier::{FrontierMenu, frontier};
81pub use loom_validate::{LoomObligation, next_frontier_menu, validate_weave};
82pub use loom_woven::{validate_woven_row, weave_row_by_row};
83pub use materialize::{
84    GivenMaterialization, bridge_fetch_capability, bridge_given_materialize_capability,
85    fetch_obligation, materialize_given,
86};
87pub use model::{
88    bridge_request_content_key, output_contract_for_packet, terminal_bridge_text,
89    terminal_response_packet,
90};
91pub use receipt::{receipt_packet_for_report, receipt_symbol};
92pub use repair::{AskFailure, RepairPolicy};
93pub use report::{BridgeObligation, BridgeReport};
94pub use runtime::{
95    BridgeFunction, BridgeFunctionKind, BridgeLib, bridge_ask_symbol, bridge_brief_symbol,
96    bridge_report_symbol, bridge_run_ask_symbol, bridge_rx_symbol, bridge_tx_symbol,
97    install_bridge_lib, manifest_name,
98};
99pub use rx::{bridge_rx, bridge_rx_response, effective_caps, rx_check};
100pub use tx::{bridge_tx, prepare_packet, render_model_face, run_bridge};
101pub use warrant::verify_warrant;
102
103/// Cookbook recipes embedded from this crate's `recipes/` directory.
104pub static RECIPES: sim_cookbook::EmbeddedDir =
105    include!(concat!(env!("OUT_DIR"), "/cookbook_recipes.rs"));
sim_lib_bridge/lib.rs

sim_lib_bridge/
lib.rs
