proof_stream/
lib.rs

1//! `proof-stream` — real-time 3D streaming visualization of stwo-ml ZK proof sessions.
2//!
3//! # Overview
4//!
5//! This crate intercepts events emitted during stwo-ml proving (GKR walk,
6//! sumcheck rounds, GPU utilization, layer activations) and streams them to a
7//! [Rerun](https://rerun.io) viewer in real time via a background thread.
8//!
9//! # Quick start
10//!
11//! ```bash
12//! # With the `rerun` feature enabled:
13//! cargo run --bin prove-model --features proof-stream-rerun -- \
14//!   --model-dir ./tiny-model --rerun spawn
15//! ```
16//!
17//! # Feature flags
18//!
19//! - `rerun` — enables the `RerunSink` and its background thread. Without this
20//!   flag the crate compiles with zero Rerun dependency.
21//!
22//! # Architecture
23//!
24//! 1. stwo-ml installs a `ProofSink` via `set_proof_sink()` (thread-local, RAII).
25//! 2. The prover calls `emit_proof_event!(|| ...)` at hot points; the closure is
26//!    never evaluated when no sink is active.
27//! 3. Active sinks (e.g. `RerunSink`) forward events through a bounded
28//!    crossbeam channel (8 192 slots, `try_send` — never blocks).
29//! 4. A background thread drains the channel and calls the Rerun SDK.
30
31pub mod blueprint;
32pub mod events;
33pub mod rerun_sink;
34pub mod sink;
35pub mod viz;
36#[cfg(feature = "ws-server")]
37pub mod ws_sink;
38
39// ── Public re-exports ─────────────────────────────────────────────────────────
40
41pub use events::{
42    ActivationStats, CircuitNodeMeta, GpuSnapshot, LayerKind, LayerProofKind,
43    LogLevel, ProofEvent, RoundPolyDeg3Viz, RoundPolyViz, SecureFieldMirror,
44};
45pub use sink::{ChannelSink, CollectingSink, NullSink, ProofEventSink, ProofSink};
46
47#[cfg(feature = "rerun")]
48pub use rerun_sink::{RerunConnection, RerunSink};
49
50#[cfg(feature = "ws-server")]
51pub use ws_sink::WsBroadcastSink;
52
53// ── Convenience constructor ───────────────────────────────────────────────────
54
55/// Parse a connection string and return a `ProofSink` wrapping a `RerunSink`.
56///
57/// Connection string formats:
58/// - `"spawn"` — spawn a Rerun viewer subprocess
59/// - `"file:<path>"` — write a `.rrd` replay file
60/// - `"tcp://host:port"` or `"host:port"` — connect to a running viewer
61///
62/// Returns an error if the connection fails (e.g. viewer not running).
63/// Error type returned by `sink_from_str`.
64#[cfg(feature = "rerun")]
65pub type SinkError = Box<dyn std::error::Error + Send + Sync>;
66
67#[cfg(feature = "rerun")]
68pub fn sink_from_str(addr: &str, app_id: &str) -> Result<ProofSink, SinkError> {
69    let conn = RerunConnection::from_str(addr);
70    let sink = RerunSink::connect(conn, app_id)?;
71    Ok(ProofSink::new(sink))
72}
proof_stream/lib.rs

proof_stream/
lib.rs
