Module testbench 

Testbench: hermetic-execution composition primitive.

Wires the four pluggable axes Harn already had — virtual time, mocked LLM, filesystem overlay, recorded subprocess — behind a single Testbench handle. Production wires real impls; tests/demos pick a config and get an audit trail of everything that crossed the host boundary.

Axes

• Clock (crate::clock_mock). Pinned wall-clock + monotonic time honored by stdlib now_ms/sleep/monotonic_ms, the trigger dispatcher, and the cron scheduler. Tests advance with crate::clock_mock::advance or the script-side advance_time(...).

• LLM (crate::llm). The CLI replay/record path (install_cli_llm_mocks / enable_cli_llm_mock_recording) is the workhorse; [crate::llm::FakeLlmProvider] adds streaming/error fidelity for tests that care about per-token order.

• Filesystem (overlay_fs). Copy-on-write overlay rooted at a real worktree: reads pass through, writes land in an in-memory layer, and overlay_fs::OverlayFs::diff surfaces a unified-style diff that can be applied back or discarded.

• Subprocess (process_tape). Records (program, args, cwd) → (stdout, stderr, exit, virtual Δt) tuples in record mode and replays them deterministically in replay mode. Env-var matching is documented as future work — the JSON tape carries an env field reserved for it.

Network

Network egress is deny-by-default in testbench mode — outbound HTTP and connector requests fail fast unless an explicit allowlist names the destination. The deny pass routes through crate::egress, the same policy engine production uses.

Modules

annotations

Annotation sidecar for testbench tapes.

fidelity

Replay fidelity oracle.

overlay_fs

Copy-on-write filesystem overlay.

process_tape

Subprocess record/replay tape for the testbench.

tape

Unified event tape for the testbench.

Structs

EmittedTape

Summary metadata for a unified tape that was emitted at finalize-time.

Testbench

Declarative configuration for Testbench::activate. Every axis is optional so callers can compose only the surfaces they need.

TestbenchBuilder

Fluent constructor for Testbench.

TestbenchFinalize

Outcome of a finalized testbench session — the artifacts the operator inspects after a hermetic run.

TestbenchSession

RAII handle returned by Testbench::activate. Holds every guard for the active axes; dropping it tears them all down in order.

Enums

ClockConfig

Configures the unified mock clock. Defaults to the runtime’s real clock so the testbench stays opt-in.

FilesystemConfig

Filesystem overlay configuration.

LlmConfig

LLM provider configuration. Mirrors harn run --llm-mock / --llm-mock-record so the testbench is a strict superset of that flag pair. The testbench does not install LLM mocks itself — it stays declarative so crate::llm::install_cli_llm_mocks (or its harn-cli wrapper) remains the single mutator of LLM state.

NetworkConfig

Network policy. Defaults to the production egress policy (no override). Testbench callers usually pick DenyByDefault.

SubprocessConfig

Subprocess record/replay configuration.

TapeConfig

Unified-tape configuration. Recording is opt-in: Off (the default) installs nothing and pays nothing in production; Emit { path } installs a tape::TapeRecorder consulted by every host-capability axis, then persists the result to path (plus path.cas/ for large payloads) when TestbenchSession::finalize runs.

TestbenchError

Errors surfaced when activating or finalizing a testbench session.