Module sdk_wire 

Utilities for the wire-conformance harness.

Intentionally separate from forge-sdk so the SDK crate surface stays focused on what library consumers use. Nothing here is public SDK API.

Two testing modes

Each scenario runs in one of two modes:

• Live mode (FORGE_WIRE_CAPTURE=1): spawn real claude, drive forge-sdk through the scenario, capture the full stdin/stdout trace to target/wire-traces/. Burns API tokens. Updates the committed baseline on request.
• Replay mode (default): load the committed baseline trace fixture for the scenario, feed every inbound line through forge_sdk::transport::codec::decode_dispatch, assert everything decodes cleanly (including no DecodedLine::Unknown variants unless explicitly expected). Runs on every cargo check / just check - no API cost.

Baselines

Committed baselines live under crates/forge-test-harness/baselines/sdk/ <cli-version>/<scenario>.jsonl. Each scenario knows its own name; the cli-version dir rotates when we bump the pinned CLI version through the upgrade ritual.

Re-exports

use std::sync::Arc; 🔒

use forge_sdk::Error; 🔒

use forge_sdk::OptionsBuilder; 🔒

use forge_sdk::transport::codec::DecodedLine; 🔒

use forge_sdk::transport::codec::decode_dispatch; 🔒

use parking_lot::Mutex; 🔒

Modules

session_redact

Session-persistence → stream-json transformer + PII redactor.

Structs

DecodeReport

Outcome of running every inbound line in a log through decode_dispatch. Split across known decode categories plus Unknowns and outright errors.

TraceLog

One captured line in a trace.

Enums

DumpKind 🔒

What a dump is for, deciding its filename prefix AND whether it is redacted together, so the two cannot disagree: README.md promotes with cp target/wire-traces/capture-*.jsonl, so anything that glob reaches must be redacted.

Constants

CATCH_ALL_MARKERS 🔒

Serialised forms of the catch-all variants that stand in for a wire value the decoder does not model (#[serde(other)]).

EXPECTED_GENERIC_SYSTEM_SUBTYPES

system subtypes the decoder deliberately leaves generic. Everything else reaching Message::System is a subtype nobody has modelled yet.

PINNED_CLI_VERSION

Pinned CLI version these baselines were captured against.

Functions

attach_recording

Install inbound + outbound wire-tee callbacks on a builder so the resulting forge_sdk::Options captures every stream-json line the SDK exchanges with the claude subprocess. Returns the configured builder + a shared handle to the trace log. Wire capture is a spawn-time configuration concern, not a transport-injection one.

baseline_dir

Directory holding the committed trace baselines for the pinned CLI version. Resolves to crates/forge-test-harness/baselines/sdk/<PINNED_CLI_VERSION>/.

collect_catch_all_drift 🔒

Walk raw and reencoded together, recording every shared key whose value the decoder replaced with a catch-all marker.

decode_all_inbound

Run every inbound line from log through decode_dispatch, returning a categorised report.

legacy_baseline_dir

Directory holding the legacy-surface corpus for the pinned CLI version: the same scenarios captured with the CLI’s ambient routing on a model id it does not recognize. The CLI tailors its tool surface per model, so this corpus records the surface a proxy-backed account actually gets. That surface is neither identical to the recognized one nor a superset of it: measure both rather than assuming the older “unrecognized ids keep the full legacy surface” story still holds. Resolves to baseline_dir()’s legacy-surface/ subdirectory, which keeps the two corpora out of each other’s diffs.

load_baseline

Load a trace fixture by scenario name.

load_baseline_from

load_baseline against an explicit baseline directory - the legacy-surface corpus lives in a sibling directory of the pinned one and is loaded the same way.

record_fallbacks 🔒

Record every fallback the decoder took on msg, which decoded from line.

run_live_scenario

Run a live-capture scenario end-to-end: build options, spawn a recorded claude, drive the scenario to a Result frame, dump the trace to target/wire-traces/, assert every inbound line decodes cleanly.