blackbox/lib.rs
1//! # blackbox
2//!
3//! Local flight recorder and debugger for supervised processes — especially
4//! AI coding agents. The **crates.io package** is [`blackbox-recorder`](https://crates.io/crates/blackbox-recorder);
5//! the **library crate and CLI binary** are both named `blackbox`.
6//!
7//! ## What the library does
8//!
9//! 1. Supervise a child under a PTY (`run`)
10//! 2. Merge capture layers (terminal, git, filesystem, process)
11//! 3. Redact secrets before write (default)
12//! 4. Persist ordered `TraceEvent`s in SQLite + content-addressed blobs
13//! 5. Expose analysis, export, verification receipts, experiments, and MCP
14//!
15//! Most users run the **`blackbox` CLI**. This crate is the implementation
16//! library for that binary and for embedding capture/store logic.
17//!
18//! ## Operator docs (CLI)
19//!
20//! Guides and reference live in the repository (not all pages are rendered as
21//! rustdoc). Start here:
22//!
23//! - [README](https://github.com/wanazhar/blackbox/blob/master/README.md) — install and first commands
24//! - [docs index](https://github.com/wanazhar/blackbox/blob/master/docs/README.md) — full map
25//! - [CLI reference](https://github.com/wanazhar/blackbox/blob/master/docs/reference/cli.md)
26//!
27//! ## Library map
28//!
29//! | Module | Role |
30//! |--------|------|
31//! | [`run`] | PTY supervision (`RunSupervisor`) |
32//! | [`storage`] | `TraceStore` + SQLite backend |
33//! | [`core`] | `Run`, `TraceEvent`, checkpoints, blobs |
34//! | [`capture`] | Capture layers and merge |
35//! | [`pipeline`] | `EventWriter`, batch ingest |
36//! | [`adapters`] | Harness detection and parse |
37//! | [`redaction`] | Secret scanning before write |
38//! | [`verification`] | Immutable receipts and outcomes |
39//! | [`boundary`] | Boundary contracts, containment, detectors, provenance, trust (1.7) |
40//! | [`evidence`] | External evidence NDJSON import + sensor adapters (1.7) |
41//! | [`incident`] | Multi-run incident reconstruction + pagination (1.7) |
42//! | [`forensic`] | Local forensic analysis packs (1.7) |
43//! | [`protocol`] | Evidence protocol canonical form & schemas (1.9) |
44//! | [`native`] | Native run/event ingestion without PTY (1.9) |
45//! | [`security`] | Security decisions and action reconciliation (1.9) |
46//! | [`commitment`] | Run evidence hash chains and signatures (1.9) |
47//! | [`otlp`] | OpenTelemetry export/import foundation (1.9) |
48//! | [`conformance`] | Protocol conformance profiles and runner (1.9) |
49//! | [`integrations`] | Native harness reference integrations (1.9) |
50//! | [`experiment`] | Experiments, reports, gates |
51//! | [`export`] | Portable / JSONL / HTML |
52//! | [`integrity`] | `fsck` and repair |
53//! | [`budget`] | Wall/process/memory/tool budgets |
54//! | [`mcp`] | MCP stdio server |
55//! | [`cli`] | clap CLI definition |
56//!
57//! ## Quick embed sketch
58//!
59//! ```no_run
60//! use std::sync::Arc;
61//! use blackbox::cli::RunArgs;
62//! use blackbox::run::RunSupervisor;
63//! use blackbox::storage::sqlite::SqliteStore;
64//! use blackbox::storage::TraceStore;
65//!
66//! # async fn demo() -> anyhow::Result<()> {
67//! let store = Arc::new(SqliteStore::open_memory()?) as Arc<dyn TraceStore>;
68//! let run = RunSupervisor::new(store)
69//! .execute(&RunArgs {
70//! command: vec!["echo".into(), "hi".into()],
71//! ..Default::default()
72//! })
73//! .await?;
74//! println!("run id {}", run.id);
75//! # Ok(())
76//! # }
77//! ```
78//!
79//! ## License
80//!
81//! MIT OR Apache-2.0.
82
83#![warn(missing_docs)]
84
85/// External process adapter protocol (`blackbox.adapter/v1`).
86pub mod adapter_protocol;
87/// Built-in harness adapters (Claude, Codex, generic, …).
88pub mod adapters;
89/// Incremental per-run aggregate counters.
90pub mod aggregates;
91/// Post-hoc analysis passes (errors, anomalies, causal links).
92pub mod analysis;
93/// Sealed offline store backup / restore.
94pub mod backup;
95/// Agent boundary contracts, containment receipts, evidence gates (1.7).
96pub mod boundary;
97/// Execution budget policy and Linux enforcement.
98pub mod budget;
99/// Reproducibility capsules.
100pub mod capsule;
101/// Capture layers: PTY, git, filesystem, process.
102pub mod capture;
103/// Experimental MCP cassette record / replay.
104pub mod cassette;
105/// Clap CLI definition and command dispatch.
106pub mod cli;
107/// 1.6 CLI handlers (fsck, verify, experiment, …).
108pub mod cli_ext;
109/// Run evidence commitments: hash chains and optional signatures (1.9).
110pub mod commitment;
111/// Store paths, capture policy, continuity mode.
112pub mod config;
113/// Protocol conformance profiles and runner (1.9).
114pub mod conformance;
115/// Resume / context packing helpers.
116pub mod context;
117/// Core data model: runs, events, blobs, checkpoints.
118pub mod core;
119/// Content hashing and sealed-export crypto.
120pub mod crypto;
121/// External evidence ingestion (1.7).
122pub mod evidence;
123/// Experiments, multi-run reports, and CI gates.
124pub mod experiment;
125/// Export formats: portable JSON, JSONL, HTML.
126pub mod export;
127/// Local forensic analysis packs (1.7).
128pub mod forensic;
129/// Multi-run incident reconstruction (1.7).
130pub mod incident;
131/// Durable ingest spool and crash recovery.
132pub mod ingest;
133/// Native harness integrations (1.9).
134pub mod integrations;
135/// Store integrity checks (`fsck`) and repair.
136pub mod integrity;
137/// Ambient wrap decision table (`maybe-run`).
138pub mod maybe_run;
139/// MCP stdio server.
140pub mod mcp;
141/// Project memory pack build and shrink.
142pub mod memory;
143/// Native run/event ingestion without PTY wrapping (1.9).
144pub mod native;
145/// Nest guard without child-visible control env.
146pub mod nest;
147/// OpenTelemetry interoperability foundation (1.9).
148pub mod otlp;
149/// Human and JSON CLI output helpers.
150pub mod output;
151/// Event writer and batch ingest pipeline.
152pub mod pipeline;
153/// Token / cost estimation helpers.
154pub mod pricing;
155/// File permission hardening helpers.
156pub mod privacy;
157/// Multi-project metadata index.
158pub mod projects;
159/// Evidence protocol: canonical form, schemas, stability (1.9).
160pub mod protocol;
161/// Secret scanning and redaction.
162pub mod redaction;
163/// Replay engines: timeline, mock, sandbox, fork.
164pub mod replay;
165/// Resume pack construction.
166pub mod resume;
167/// Continuity launch injection.
168pub mod resume_inject;
169/// Retention policies.
170pub mod retention;
171/// PTY supervision orchestrator ([`run::RunSupervisor`]).
172pub mod run;
173/// Eval score.json builder.
174pub mod score;
175/// Historical re-redaction and blob GC.
176pub mod scrub;
177/// FTS search runner.
178pub mod search;
179/// Security decision receipts and action↔effect reconciliation (1.9).
180pub mod security;
181/// Local web dashboard (Axum).
182pub mod serve;
183/// Shell ambient-wrapper install.
184pub mod shell_install;
185/// Sticky project state.
186pub mod state;
187/// Status and handoff builders.
188pub mod status;
189/// Trace store trait and SQLite backend.
190pub mod storage;
191/// Run summary / postmortem text and JSON.
192pub mod summary;
193/// Supervisor lifecycle, rollup, shutdown.
194pub mod supervisor;
195/// Dir / HTTP / S3 sync.
196pub mod sync;
197/// PTY terminal recording, ANSI, coalescing.
198pub mod terminal;
199/// Run trajectory comparison (LCP / divergence).
200pub mod trajectory;
201/// Transcript rebuild from store blobs.
202pub mod transcript;
203/// Ratatui TUI views.
204pub mod ui;
205/// Shared string / path helpers.
206pub mod util;
207/// Verification receipts and outcomes.
208pub mod verification;
209/// JSON view types for `--json` envelopes.
210pub mod views;
211/// Workspace checkpoint manifests and restore.
212pub mod workspace_manifest;