xag-flight-recorder 0.8.0

Record tool calls at an app's nondeterminism boundary; replay them deterministically with every internal variable observable

flight-recorder

Record what the outside world told your code — every database answer, HTTP response, clock read and random draw — as one small JSONL file per request: a tape. Replay that file against your real code later: same inputs, same execution, bit for bit, with every internal variable observable. When a replay diverges, the report names the first difference instead of leaving you to guess.

A program's execution is fully determined by its code plus its nondeterministic inputs. Record just those, per call — one cheap line — and that line is the execution, compressed. Feed the answers back and the real code re-runs the original execution exactly: no network, no database, no waiting for the bug to happen again.

The cardinal rule: instrument, never duplicate. Nothing here evaluates a query, reimplements a client, or knows what any value means. Recording is a transparent proxy; replay feeds the recorded answers back and verifies the questions still match.

→ Read the guide

The full walkthrough — declare the boundary, record, replay, edit the tape to visit worlds that never happened, invariants, semantic spans — in Python, Node and .NET, one tab away. Slides — Testing as Simulation.

The tape is a standard

The recording format is a frozen, documented wire contract: spec/tape-v1.md. Implementations are welcome — only record and replay must be native to a runtime; everything that analyzes a tape works on any tape. Conformance is not the prose: it is spec/fixtures/ plus the checker in spec/validate.py (mirrored in JS, .NET, Go, and Java). Every implementation must validate every fixture, and every fixture must have been produced by an implementation. This repo ships five implementations — Python, Node, .NET, Go, and Java — reading and writing the same tapes.

Why

flight-recorder pushes the heavy lifting from human to AI, and from AI to code. As AI takes on most of the development, scenario testing and debugging become the bottleneck, and the work left to the human is the tedious kind. Recording at the nondeterminism boundary gives the agent the missing instruments: it re-runs the exact request against the real code and watches any variable as the bug happens — root cause by lookup, not by guess; fixes proven by replay; regressions caught by a directory of files. What is left to the human is the decisions.

License

Apache-2.0 — see LICENSE and NOTICE. Relicensed from MIT deliberately, before any outside contribution existed: the tape spec is meant to be implemented by others, and Apache-2.0's explicit patent grant is what makes "implement this freely" a promise rather than a mood.

© 2026 Xavier Grehant