tracefork 0.1.0__tar.gz → 0.2.0__tar.gz

{tracefork-0.1.0 → tracefork-0.2.0}/.github/workflows/ci.yml

@@ -13,9 +13,9 @@ jobs:
       matrix:
         python-version: ["3.12", "3.13"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@v7
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies

{tracefork-0.1.0 → tracefork-0.2.0}/.gitignore

@@ -9,11 +9,16 @@ __pycache__/
 *.tape.sqlite
 /tmp_tapes/
 
+# Exception: the committed replay-fixture corpus (replay --check regression
+# gate) — these tapes are checked in, not regenerated per-run.
+!/experiments/replay_fixtures/*.tape.sqlite
+
 # Runtime artifacts (CLI output, regenerated on demand)
 /store.db
 /report.html
 /blame_*.json
 /validation_report.json
+/bench_report.json
 /examples/demo_report.html
 
 # Build, coverage, and tool caches (regenerated on demand)

tracefork-0.2.0/CHANGELOG.md

@@ -0,0 +1,124 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-07-02
+
+Generic, multi-provider, production-hardening release. The bit-exact, $0,
+hash-verified replay substrate from 0.1.0 is the contract and is unchanged —
+everything below is additive around it: all engine internals stay byte-stable,
+`digest()` is format-stable, and every existing tape still loads and replays.
+
+### Added
+
+- **Provider abstraction seam** (`providers/`): a `ProviderAdapter` protocol + registry
+  and a `gen_ai.*`-style `NormalizedResponse` view. Anthropic is now a *registered*
+  adapter, not a hardcoded assumption; raw request/response **bytes** stay the immutable
+  replay + hash contract. (#7)
+- **More provider backends** — **OpenAI** and **Google Gemini** (httpx-based, captured
+  through the existing transport seam, with provider-generic fault injection), and **AWS
+  Bedrock** (a separate botocore `before-send` seam, a stdlib `vnd.amazon.eventstream`
+  frame codec, and SigV4-canonical request matching so a fresh signature/timestamp is not
+  a false divergence). (#12, #21)
+- **Pluggable canonicalization / divergence matcher** (`matcher.py`): identity +
+  canonicalizing matchers so volatile material (Gemini `?key=`, Bedrock `x-amz-date`,
+  rotating auth) hashes equal while a real request-body change still diverges. (#9)
+- **Plugin & extension architecture** (`plugins.py`): entry-point registries for
+  providers, matchers, storage backends, transports, oracles, and adapters — each gated by
+  the same explicit allowlist. (#11)
+- **MCP + native tool-call record/replay** (`tools.py`, `mcp_client.py`): a JSON-RPC tee so
+  tool exchanges share the tape with LLM exchanges and replay bit-exact. (#14)
+- **Framework adapters** (`adapters/`, opt-in extras): a minimal
+  `bind()`/`on_step()`/`teardown()` protocol + a `StepDAG` normalizer, with
+  **LangChain/LangGraph** (including a tape-backed LangGraph checkpointer) plus **OpenAI
+  Agents SDK**, **CrewAI**, and **AutoGen** adapters — each binding at the framework's real
+  model-call chokepoint (never a second capture path) and each guarded so `import
+  tracefork` and the full offline suite run with none installed. (#16, #23)
+- **OTel GenAI / OpenInference interop** (`interop.py`, `tracefork export`/`ingest`): export
+  a tape (+ blame report) as OTel GenAI spans or an OpenInference dataset, and ingest either
+  back into a tape's step structure for **blame-by-re-execution** (explicitly *not* $0
+  bit-exact replay — an ingested tape diverges on `replay`/`fork` by design). Plain JSON, no
+  `opentelemetry-sdk` required. Plus an **opt-in `observability` extra** (structlog + OTel
+  self-instrumentation of record/replay/fork/blame), off by default. (#15)
+- **Deterministic asyncio concurrency replay** (`transport.py`): records the completion
+  order of concurrent fan-out (`gather`/`TaskGroup`) and re-imposes it on replay, so
+  concurrent agents replay bit-exact — not just single-call-at-a-time ones. (#17)
+- **Causal blame depth**: coalition / temporal-Shapley attribution with necessity +
+  sufficiency, and a long-tape competing-fault benchmark (`tracefork bench`) with Wilson
+  CIs. The one temporal-order Shapley limitation is documented, not hidden. (#18, #24)
+- **Oracle rigor** (`judge.py`, opt-in): an LLM-judge oracle with position-swap averaging +
+  a self-judge guard, gold-set calibration (FPR/FNR/Cohen's kappa), and Rogan-Gladen
+  flip-rate debiasing — all offline-testable via an injected judge function. (#19)
+- **Divergence diagnostics & debug UX** (`divergence.py`, web report): a structured
+  divergence diff, a report rewind panel, blame trust flags, and real-vs-tolerated
+  divergence messaging. (#20)
+- **Localhost record/replay proxy** (`tracefork proxy`): a base-URL MITM-style proxy (binds
+  127.0.0.1) for non-Python / non-httpx clients (curl, Node, Go), reusing the tape +
+  matcher. Record/replay only — outside the in-process `NondetSource` determinism
+  boundary. (#22)
+- **Hardening seams**: an opt-in record-time `BoundaryGuard` (thread/subprocess spawn,
+  direct `random`/`time` bypasses), `random_float()` virtualization through `NondetSource`,
+  a `replay --check` fixture-corpus regression gate, and opt-in secret/PII redaction on
+  record. (#10, #13)
+- **CLI**: new `bench`, `export`, `ingest`, and `proxy` commands (joining
+  `replay`/`verify`/`fork`/`report`/`serve`/`blame`/`validate`), plus a full end-to-end
+  integration suite and a single `scripts/e2e.sh` receipt. (#25)
+
+### Changed
+
+- **Versioned tape envelope** (`tape.py`): a `TAPE_MAGIC` + uint16 version header over a
+  zstd + content-addressed binary container (no base64, no pickle), with a read-time
+  upcaster chain (v1→v4). The version header is **not** part of `digest()`, so the hash
+  chain is byte-stable across format versions and legacy tapes still load and replay. (#6)
+- **Blame statistics**: three-valued trials (flip / no-flip / undefined) and pluggable CI
+  methods. (#8)
+- **SQLite persistence hardened**: WAL, `synchronous=NORMAL`, `busy_timeout`,
+  `foreign_keys=ON`, and writers take `BEGIN IMMEDIATE`. (#6)
+
+### Fixed
+
+- Wilson CI boundaries snap to analytically-exact 0/1 to avoid ~1e-17 platform float-dust
+  that differed across CI runners. (#8)
+
+## [0.1.0] - 2026-07-02
+
+### Added
+
+- **Record/replay** at the Anthropic SDK's httpx transport boundary
+  (`TraceforkTransport` / `AsyncTraceforkTransport`), streaming-SSE capable, with
+  bit-exact replay proven by sha256-checking every replayed request body against the
+  recorded tape — and drift detection that fails loudly on divergence rather than
+  silently falling back to the network.
+- **Content-addressed tape format** (`Tape`) — sha256 blobs plus an ordered event log,
+  JSON + base64 (never pickle), persistable to SQLite, with a hash-chain `digest()`
+  fingerprint.
+- **Nondeterminism virtualization** (`NondetSource`) — the only path through which an
+  agent reads time and ids, with `RecordingNondet`, `ReplayNondet`, and a `DriftingNondet`
+  negative control that proves the divergence detector actually detects divergence.
+- **Three-phase fork engine** (`ForkEngine`, `ForkTransport`) — prefix-replay ($0),
+  mutation-injection (swap a response), and tail-record (the recorded counterfactual
+  continuation), re-running the same agent that produced the original tape.
+- **Causal blame engine** (`BlameEngine`) — forks each step `k` times, re-runs the agent,
+  grades outcomes via an `Oracle`, and ranks steps by flip-rate with Wilson score
+  confidence intervals; a `BudgetGovernor` estimates dollar cost from the pricing table
+  and refuses to exceed a caller-supplied budget before making any real API calls.
+- **Fault-injection self-validation suite** (`faults.py`, `validate.py`) — five fault
+  classes with markers embedded in valid Anthropic JSON, scored end-to-end offline
+  against a synthetic fault-aware agent: **1.00 top-1 precision** across all five classes,
+  with an enforced negative-control threshold so the proof isn't vacuous.
+- **Single-file web report/UI** (`report.py`, `server.py`, `web/report.html`) — a
+  dependency-free, three-panel HTML report (timeline, exchange detail, blame ranking)
+  either rendered statically or served live via FastAPI (`serve`, 127.0.0.1, no CORS).
+- **CLI** (`cli.py`, Typer) — `replay`, `verify`, `fork`, `blame`, `report`, `serve`,
+  `validate`.
+- `src/tracefork_spike/` — the original Spike 0 that de-risked bit-exact, no-key replay
+  within the declared determinism boundary.
+
+[Unreleased]: https://github.com/pratik916/tracefork/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/pratik916/tracefork/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/pratik916/tracefork/releases/tag/v0.1.0

tracefork-0.2.0/CLAUDE.md

@@ -0,0 +1,236 @@
+# CLAUDE.md
+
+This file guides Claude Code when working in the `tracefork` repository.
+
+## What this is
+
+`tracefork` is a time-travel debugger for AI agents: record an agent run to a
+content-addressed **tape**, replay it **bit-exact for $0** (hash-verified), fork any
+step, and measure causal blame with confidence intervals — the instrument itself
+validated against runs with injected, known root-cause faults.
+
+**Current state: v1 built.** All five product pillars work offline and are tested
+(653 tests, $0): streaming-capable record/replay with drift detection, the three-phase
+fork engine, the causal blame engine with Wilson CIs and a budget governor, the
+single-file web report/UI, and the fault-injection self-validation suite (5 fault
+classes at 1.00 top-1 precision, plus a longer competing-fault fixture that measures
+whether the coalition/temporal-Shapley engine discriminates *several* simultaneously
+planted causes — `tracefork bench`; see README → Validation scope for exactly what each
+number does and doesn't claim). `src/tracefork_spike/` keeps the original Spike 0 that
+de-risked the load-bearing assumption (bit-exact, no-key replay within a declared
+determinism boundary). Design/feature list: `../ideas/2026-06-11-tracefork-features.md`;
+spike finding: `SPIKE0.md`.
+
+## Commands
+
+Python is **3.12 via uv**. The tests, the spike, `validate`, the demo, and
+record/replay/fork are offline and $0 — **no `ANTHROPIC_API_KEY`, no network**. Only
+`blame` against a *real* run hits the live API (budget-capped). Always prefix `uv run`.
+
+```bash
+uv sync --extra dev                  # install (anthropic, zstandard, typer, fastapi, uvicorn + pytest)
+uv run pytest -q                     # full offline suite (653 tests)
+uv run pytest tests/test_faults.py::test_validation_runner_fingers_fault_step -q   # one test
+uv run tracefork validate            # self-validation: blame vs injected, known faults
+uv run tracefork validate --check    # regression-gate vs experiments/validation_report_committed.json
+uv run tracefork bench                # long-tape competing-fault discrimination benchmark
+uv run python examples/demo_report.py   # write examples/demo_report.html (the README screenshot)
+uv run python -m tracefork_spike     # the original Spike 0 bit-exact replay receipt
+uv run tracefork --help              # replay, verify, fork, report, serve, blame, validate, bench, proxy
+uv run tracefork replay --check experiments/replay_fixtures   # replay-as-regression gate
+bash scripts/e2e.sh                  # single-receipt gate: sync, lint, type-check, tests+coverage,
+                                      # validate --check, replay --check, bench, build+twine, one PASS banner
+```
+
+## Architecture (the parts that span files)
+
+The spine is a **record/replay seam at the Anthropic SDK's httpx boundary**, plus a
+**nondeterminism-virtualization seam** the agent reads time/ids through. Bit-exactness
+is the contract between them.
+
+The product lives in `src/tracefork/`:
+
+- `nondet.py` — `NondetSource` is the *only* way the agent gets time/ids/random draws
+  (`now_iso`/`new_uuid_hex`/`random_float`). `RecordingNondet` draws real values and logs
+  them; `ReplayNondet` serves them back in order; `DriftingNondet` is the negative control
+  (fresh values → forced divergence). `random_float()` logs the exact `float.hex()` string
+  (lossless round-trip, no float-formatting dust) and, like `now_iso()`, is additive/opt-in
+  — an agent must be handed the active `NondetSource` explicitly; nothing patches `random`
+  globally the way `Recorder` patches `uuid.uuid4`. `find_divergence()` unwraps a
+  `DivergenceError` from the `APIConnectionError` the SDK wraps transport exceptions in —
+  **keep this; without it a real divergence looks like a network blip.**
+- `boundary_guard.py` — `BoundaryGuard`, an **opt-in** (default off) record-mode guard:
+  hard-errors on `threading.Thread.start`/`subprocess.Popen` (crossing the single-process
+  boundary) and direct `random.random`/`time.monotonic`/`time.sleep` (bypassing
+  `NondetSource`) instead of letting the tape fail replay later, mysteriously. Deliberately
+  does **not** guard `datetime.datetime.now()` (same immutable-C-type reason `recorder.py`
+  doesn't patch it) or `time.time()` (httpx's cookie-jar machinery calls it on every
+  response — guarding it would false-positive on every exchange). Pre-warms the Anthropic
+  SDK's `platform_headers()` `lru_cache` on `__enter__` so its one internal
+  `subprocess.Popen` call (uncached platform detection) doesn't trip the guard on the first
+  real API call. Wired into `Recorder`/`AsyncRecorder` via `boundary_guard=` (tri-state:
+  explicit wins over `TraceforkConfig.boundary_guard`, both default `False`).
+- `transport.py` — `TraceforkTransport` (sync) + `AsyncTraceforkTransport` (async) are the
+  capture seam, streaming-SSE capable (buffer via `.read()`/`.aread()`). Record mode tees
+  request+response bytes into the tape; replay mode serves recorded bytes and
+  sha256-asserts each request body matches (the divergence detector). A replay transport
+  has **no inner transport**, so any unrecorded request is a hard error. **Async
+  concurrency:** the async transport records the completion order of concurrent fan-out
+  (`asyncio.gather`/`TaskGroup`) — appending exchanges at completion and logging each
+  fully-overlapping batch to `tape.async_batches` — and on replay **correlates each request
+  to its recorded exchange by fingerprint (not positional arrival) and releases responses in
+  the recorded completion order** via an ordered gate, so a fan-out agent replays bit-exact.
+  A strictly-sequential async run never waits at the gate → byte-identical to before; the
+  sync transport is untouched (stays positional). `chaos_release_order(tape, seed)` derives a
+  seeded, physically-possible reordering of a recorded schedule (chaos-mode replay) for
+  race/ordering-bug analysis; **do NOT** add awaits/ordering to the sequential or sync path.
+- `tape.py` — `Tape` is content-addressed (sha256 blobs) + an ordered event log,
+  persistable to SQLite, with a hash-chain `digest()` fingerprint. `to_bytes`/`from_bytes`
+  emit a **versioned envelope** (`TAPE_MAGIC` + uint16 version, then a zstd + content-
+  addressed binary container — no base64); `from_bytes` dispatches on the version through a
+  read-time upcaster chain and still loads legacy header-less JSON blobs as v1. The version
+  header is envelope metadata, **not** part of `digest()`, so the hash chain is byte-stable
+  across format versions. **v4** adds the `async_batches` concurrency-batch log (recorded
+  completion order of fully-overlapping fan-out); like `boundary`/`agent_name` it is
+  persisted but **never** fed into `digest()` (the completion order is already fingerprinted
+  by the `exchanges` list ordering), so every existing and every sequential/sync tape's
+  digest is byte-identical and v1/v2/v3 tapes upcast to an empty batch log. It's a JSON
+  header + zstd blobs, **not pickle** — no
+  arbitrary-code-execution risk. `open_sqlite()` is the one hardened connection factory
+  (WAL, `synchronous=NORMAL`, `busy_timeout`, `foreign_keys=ON`); writers take `BEGIN
+  IMMEDIATE`. `store.py` reuses it and serializes its write fan-out with a lock.
+- `recorder.py` — `Recorder` context manager wraps a real `anthropic.Anthropic` at its
+  `_client._transport` seam (via `client.copy(http_client=...)`, so base_url / auth_token /
+  default headers are preserved). Patches `uuid.uuid4` globally; **does not** patch
+  `datetime.datetime` (immutable C type in 3.12+, and a subclass breaks the SDK's pydantic
+  schema builder) — agents needing deterministic clocks/random read `NondetSource` directly.
+  Optionally wraps the recording window in a `BoundaryGuard` (see `boundary_guard.py`).
+- `fork.py` — `ForkTransport` runs three phases: prefix-replay ($0, request asserted to
+  match the parent), mutation-injection (same request, swapped response), tail-record (the
+  counterfactual continuation). `Branch` carries `prefix_replayed`/`tail_recorded` counts.
+  `ForkEngine.fork()` re-runs the **same** agent that produced the tape.
+- `store.py` — `TapeStore`, SQLite persistence for tapes + the branch DAG.
+- `blame.py` — `BlameEngine.rank()` forks each step `k` times, re-runs the agent, grades
+  via an `Oracle`, counts flips vs. the parent outcome; `wilson_ci()` for intervals;
+  `BudgetGovernor` estimates tail-call cost from `constants.PRICING_TABLE` before spend and
+  `rank()` raises `BudgetExceededError` if the estimate exceeds `budget_usd`.
+- `judge.py` — OPT-IN, additive on top of `blame.py`'s `Oracle` protocol (never imported by the
+  default $0 path): `LLMJudgeOracle` is a binary-rubric judge with few-shot examples, a
+  configurable ("cross-family") judge model with a self-judge guard, position-swap averaging
+  (grades twice with the candidate output moved in the prompt; disagreement or low average
+  confidence abstains via `None`) — testable OFFLINE via an injected `judge_fn` (prompt -> raw
+  text), never a real API call in tests. `calibrate_oracle()` measures any `Oracle`'s FPR/FNR/
+  Cohen's kappa against a labeled gold set (`kappa_alert` below 0.6). `rogan_gladen_correct()` /
+  `debias_flip_rate()` debias an observed flip-rate for judge FPR/FNR (Rogan-Gladen 1978) and
+  widen a step's CI via delta-method propagation of BOTH k-sampling noise and finite-gold-set
+  judge noise. Pure math, reuses `blame.z_from_confidence`; registers `"llm_judge"` into
+  `blame.ORACLE_REGISTRY` at import time (importing the module is itself the opt-in).
+- `faults.py` / `validate.py` — 5 fault classes (valid JSON, marker **inside** a content
+  field) + the self-validation runner; a synthetic agent echoes each response forward so an
+  injected fault propagates to a fault-aware tail. `run_all_fault_classes()` scores top-1.
+  **Scope (don't overstate):** the fixture is a positive-vs-inert control on a short tape —
+  it proves the engine is genuinely causal (not a fixed-slot artifact), not that it
+  discriminates among competing causes on long tapes. See README → Validation scope.
+- `competing_faults.py` / `bench.py` — the longer-tape ANSWER to that scope note: a
+  7-exchange tape with several causally-DISTINCT faults planted at once (a root,
+  a downstream echo, and a two-part necessary-not-sufficient AND-conjunction), scored
+  against `blame.py`'s coalition/temporal-Shapley engine (`shapley_rank`) via `tracefork
+  bench`. 8/9 planted cases resolve correctly; the 9th is a documented, NOT hidden,
+  limitation of single-ordering temporal Shapley (it under-credits the earlier half of a
+  symmetric conjunction) — see `competing_faults.py`'s module docstring and README →
+  Validation scope. Cites, but does not reproduce, the published Who&When (ICML 2025)
+  ~14.2% log-based step-attribution anchor as context only — no external dataset is ever
+  downloaded (offline/$0 invariant applies here too). Zero-diff over the engines: both
+  modules only call `blame.py`'s existing public API.
+- `report.py` / `server.py` / `web/report.html` — the single-file, dependency-free
+  three-panel UI; `report.py` injects tape JSON (HTML-escaped against `</script>`
+  breakout), `server.py` is FastAPI same-origin (no CORS, binds 127.0.0.1).
+- `wire.py` / `synthetic.py` — Anthropic wire-format builders and the offline
+  Scripted/FaultAware fake transports, in the **package** so production never imports from
+  `tests/`; `tests/fakes.py` re-exports them.
+- `replay.py` — `ReplayVerifier` (per-tape) and `run_fixture_corpus_check()`, which extends
+  the `validate --check` idea to plain replay: gates a committed tape corpus
+  (`experiments/replay_fixtures/` + its `manifest.json`) by asserting both bit-exact replay
+  and a `digest()` match per fixture — `tracefork replay --check <dir>`. `fixtures.py` holds
+  the tiny deterministic agents the corpus is built from (kept out of `validate.py` so the
+  corpus doesn't couple to fault-testing concerns); `scripts/gen_replay_fixtures.py`
+  (re)generates the corpus offline.
+- `proxy.py` — `RecordProxy`/`ReplayProxy` (wired into FastAPI apps via
+  `build_record_app`/`build_replay_app`) are a **localhost base-URL record/replay proxy**
+  for clients the in-process httpx seam can't reach (curl, Node, Go, non-wrapped Python):
+  point the client's `base_url` at `http://127.0.0.1:<port>` instead of the provider.
+  Record forwards to a real (or, in tests, injected-fake) upstream and tees request+response
+  bytes into a `Tape`, streaming SSE chunk-by-chunk while forwarding; replay serves recorded
+  bytes with **no upstream**, matching each request to its recorded exchange by
+  `matcher.py`'s existing `RequestMatcher` fingerprint (an unrecorded request, or a real
+  body change, is a hard HTTP 502). Reuses `tape.py`/`matcher.py` unchanged — no in-process
+  `NondetSource` exists on this path, so a proxy-recorded tape (`Tape.boundary =
+  constants.PROXY_BOUNDARY`) sits outside the full single-process determinism boundary; see
+  the module docstring and README → Localhost record/replay proxy.
+- `adapters/` — opt-in framework adapters (`bind()` routes a framework's LLM client
+  through the *existing* `TraceforkTransport`/`NondetSource`; `on_step()` maps a
+  framework callback/event to a neutral `Step`/`StepDAG` overlay — observer-only,
+  never a second capture path). `base.py` owns the protocol/registry;
+  `langchain.py` (`ChatOpenAI`/`ChatAnthropic` + a tape-backed LangGraph
+  checkpointer), `openai_agents.py` (defensive client-attribute injection +
+  `agents.set_default_openai_client()` + a `TracingProcessor`),
+  `crewai.py` (LiteLLM's `client_session`/`aclient_session` — CrewAI's actual httpx
+  chokepoint — + a `crewai_event_bus` listener), and `autogen.py` (defensive
+  client-attribute injection + an `InterventionHandler` message-level seam) are the
+  concrete adapters, each its own optional extra with every framework import
+  guarded, so `import tracefork` and the whole offline suite work with none of
+  them installed. Where a framework's exact internal attribute names/event
+  shapes aren't a documented stable API, injection is defensive (a short
+  candidate list, never one hard-coded name) — see each module's docstring.
+- `cli.py` — Typer entry point for all eleven commands.
+
+`src/tracefork_spike/` holds the original Spike 0 (`fake_llm.py`, `agent.py`, `spike.py`):
+record → save → load → replay → verify + negative control, with its own tests.
+
+Most test files prove ONE module (or one seam) in isolation. Two are deliberately
+cross-module, added once every feature bead had merged: `tests/test_e2e.py` chains
+record → `TapeStore` save/load → replay → fork → blame → validate through the SAME
+tape at every stage (not fresh fixtures per stage), plus the negative control,
+asyncio-concurrency determinism, and every cross-feature path (MCP/tool exchanges
+sharing a tape with LLM exchanges, redaction, OTel/OpenInference export→ingest,
+plugin-registry resolution, `BoundaryGuard`, `divergence.py` diagnostics, the
+base-URL proxy, `bench`, and the Bedrock/OpenAI/Gemini provider seams with their
+documented scope boundaries called out explicitly, not papered over) — all
+offline/$0. `tests/test_cli_smoke.py` invokes every one of the eleven CLI
+subcommands and asserts its real exit code; `serve`/`proxy record`/`proxy replay`
+call `uvicorn.run()` directly, so those are driven by monkeypatching `uvicorn.run`
+to a no-op (proving the CLI's own wiring without binding a socket) plus a
+`TestClient`/ASGI-transport hit against the underlying FastAPI app for actual
+serving behavior. `scripts/e2e.sh` runs the whole gate — sync, lint, format,
+mypy, tests+coverage, `validate --check`, `replay --check`, `bench`, build+twine
+— as one script with a single PASS/FAIL verdict. Both test files are additive
+only: zero-diff over `transport.py`/`tape.py`/`fork.py`/`blame.py`/`matcher.py`.
+
+## Invariants / conventions
+
+- **Offline and $0 is non-negotiable** for the whole test suite, the spike, `validate`,
+  and the demo — no key, no network. The synthetic transports (`synthetic.py`) are the
+  seam; add to them rather than reaching for the real API. (`blame` on a real run is the
+  one budget-capped exception.)
+- **The agent must read time/ids/random only through `NondetSource`** — any direct
+  `datetime.now()` / `uuid` / `random` breaks the determinism boundary and the
+  bit-exactness claim. `BoundaryGuard` (opt-in, default off) turns a subset of these
+  violations (thread/subprocess spawn, direct `random`/`time.monotonic`/`time.sleep`) into
+  a loud record-time error instead of a mysterious later replay failure — see
+  `boundary_guard.py` for exactly which calls it can and can't intercept.
+- **The verifier proves, not asserts** — every request body is hash-checked against the
+  tape; the negative control must keep failing (drift detected) or the proof is vacuous.
+- **Declared determinism boundary (v1):** single-process (sync **or** asyncio), clock +
+  id nondeterminism captured through `NondetSource`, **plus concurrency-graph determinism**
+  — the completion order of concurrent asyncio fan-out is recorded and re-imposed on replay
+  (see `transport.py`), so `gather`/`TaskGroup` agents replay bit-exact, not just
+  single-call-at-a-time ones. Threads/subprocess are out of scope; fork and blame
+  additionally assume the agent rebuilds its prefix deterministically (the property replay
+  proves) — see `SPIKE0.md`.
+- **No `Co-Authored-By: Claude` trailer** on commits in this repo (public portfolio repo,
+  sole-author attribution).
+- **Model IDs / pricing / SDK usage:** consult the `claude-api` skill before writing or
+  editing any Anthropic integration code rather than relying on memory.
+- `docs/superpowers/`, `.beads/`, `planning/` are gitignored local scaffolding (but
+  `docs/demo.png` is committed). Runtime artifacts (`store.db`, `report.html`,
+  `blame_*.json`, `validation_report.json`, `examples/demo_report.html`) are gitignored.