graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Harness lifecycle models
These TLA+ models describe concurrency rules in the harness. TLC explores the finite configurations committed beside each model, including interleavings that are difficult to reproduce with ordinary tests.
- Effort selection: admission, stale completions, manual changes, cancellation, and owner-boundary application.
- Async tools: early admission, call identity, ordering barriers, result ownership, joining, and cancellation.
- ACP permissions: transport-owned GUI tokens, replaced workers, offered choices, and responses racing with cancellation.
- HTTP/2 leases: exclusive ownership, idle pooling, cancellation, shutdown, and reuse only after stream completion.
Each model has a normal configuration and a deliberately broken configuration. The negative control must fail the intended invariant. A syntax error, timeout, or unrelated failure is not a successful negative control.
See change evidence for connecting source diffs, model counterexamples, and runtime regressions.
See the ranked extension plan for the next ownership, retry, budget, and session properties to model.
The DGM integration guide separates formal admission from task correctness and measured fitness, covers the optional Python and native learning gates, and identifies the remaining ungated promotion path.
Scope
Passing TLC establishes the checked properties of these finite abstractions. It is not a proof that the Zig implementation refines the models, an unbounded mathematical proof, or evidence of faster execution or lower token usage. The companion documents map actions to code and state what is omitted. Runtime regression tests remain necessary, particularly for parsing, allocation, transport behavior, and cancellation implementation.
Changes to the corresponding runtime lifecycle should update its model and mapping in the same change. A counterexample is a design or model finding until it is reproduced against the implementation; do not report it as a runtime bug without that check.
Toolchain
Use Java 11 or newer and the official
TLA+ command-line tools.
The checked tool release is
v1.7.4, whose
tla2tools.jar has SHA-256:
936a262061c914694dfd669a543be24573c45d5aa0ff20a8b96b23d01e050e88
Set JAVA to the Java executable and TLA2TOOLS to that jar. The check runner
uses a bounded heap, one worker, and temporary state directories. It does not
download tools or call a model provider.
python3 scripts/check-formal.py
Keep model-checker state and counterexample output outside the source tree.
See the individual model documents for configuration bounds, invariants, and
any fairness assumptions. These checks are separate from the Zig unit suite;
running zig build test alone does not run TLC.