Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python

ADR 0212: build time is analysis-bound

justrachf6c4054be307
diff --git a/docs/adr/0212-build-time-is-analysis-bound.md b/docs/adr/0212-build-time-is-analysis-bound.md
new file mode 100644
index 00000000..9167892f
--- /dev/null
+++ b/docs/adr/0212-build-time-is-analysis-bound.md
@@ -0,0 +1,68 @@
+# 0212. Build time is analysis-bound: keep the default backend, filter test builds
+
+Status: accepted 2026-09-28
+
+## Context
+
+A cold `zig build` of graff takes about 16 s and a cold `zig build test-bin`
+about 44 s (Zig 0.17.0-dev.813, Debug, Apple silicon). The question was
+whether redundant files were inflating that, and what could make it faster.
+
+An audit of the import graph from every root in `build.zig`:
+
+- 825 `.zig` files. 649 (8.6 MB) are reachable from the shipped binaries;
+ 175 (2.0 MB) only from `test` blocks; none from nothing.
+ `src/shell_identity_probe.zig` looks unreferenced from Zig but is built on
+ its own by `scripts/eval-tier1.sh`.
+- No two files have identical content. No single file is outsized.
+- The spec JSON under `spec/kernels/` (1.1 MB) is embedded only into the unit
+ test binary. `libgraff` and the wasm core are opt-in steps, not part of the
+ default install.
+- Six `*_test.zig` / `*_tests.zig` files are imported at the top level of
+ normal code. Zig analyzes only what is referenced and `test` blocks only in
+ test builds, so the binary pays for parsing them and nothing else.
+
+Measurements, each cold (fresh local cache) and run one at a time:
+
+| Build | Time |
+|---|---|
+| `graff`, default backend | 16 s |
+| `graff`, analysis only (`-fno-emit-bin`) | 17 s |
+| `graff`, `-fllvm` | 36 s |
+| No-op rebuild | 0.2 s |
+| `test-bin`, all tests | 44 s |
+| `test-bin`, one `-Dtest-filter` | 13 s |
+
+Analysis-only takes as long as the full build: semantic analysis of the code
+actually used is the whole cost, and it runs on one core. Code generation and
+linking with the default backend are nearly free.
+
+Tried and rejected:
+
+- `-fllvm`: twice as slow in Debug.
+- `-fincremental`: its state does not persist across separate `zig build`
+ invocations, so each edit still re-analyzes everything. Under
+ `zig build --watch -fincremental`, a comment edit took 15 s to rebuild and a
+ one-function change 70 s: slower than a cold build.
+- `-fno-llvm -fno-lld` (self-hosted backend without lld): memory grew without
+ bound, past 150 GB, and took the host down. Do not use it on this codebase.
+
+## Decision
+
+- Keep the default backend for Debug builds. Do not add `-fllvm`,
+ `-fincremental`, or `-fno-llvm -fno-lld` to `build.zig` or scripts.
+- No file removal: there is no dead weight to cut. Size is not the lever;
+ analyzed code is.
+- While iterating, build unit tests with `-Dtest-filter=<name>` (about 3x
+ faster). `test-bin` only compiles; run the resulting test binary to execute
+ the filtered tests. Leave the full suite to the pre-push hook and CI.
+- Run build-time experiments one at a time, never in parallel, and watch
+ memory.
+
+## Consequences
+
+A cold build stays around 16 s and each edit re-analyzes the whole binary.
+Faster iteration comes from filtered test builds, not from build flags.
+Revisit when a Zig upgrade makes `-fincremental` persist across invocations,
+or makes `--watch` rebuilds faster than cold ones, and re-check the
+self-hosted backend's memory before trying it again.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 7a7491e9..82dd3796 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -238,6 +238,7 @@ record only when you need the evidence or the edge cases.
| [0209](0209-desktop-app-has-no-computer-use.md) | The desktop app has no computer use: the `computer` tool, endpoint and menu toggle are removed; the native input bridge remains a test-only driver. Supersedes the `computer` half of 0071. |
| [0210](0210-macos-cli-is-signed-in-ci-before-upload.md) | Tag releases sign and notarize the macOS CLI tarballs on a macOS runner before anything is uploaded, gated on all five signing secrets; without them the job no-ops and docs/notarization.md is the fallback. `SHA256SUMS` is computed once from the uploaded bytes. The desktop DMG stays a local `distribute.sh` step. |
| [0211](0211-mcp-servers-by-name-user-level-sync-via-harness.md) | `graff mcp add <name>` resolves from the codegraff.com/mcp.json catalog, then the MCP registry only for a namespace owner matching the name. `--everywhere` writes the user-level file. Harness syncs that file through its registry as non-secret rows. Env values, headers and OAuth tokens stay on each device. Harness drives graff only over ACP (slash command, form elicitation, `_meta["graff/mcp"]` status). Supersedes the vault-item sync in #1371. |
+| [0212](0212-build-time-is-analysis-bound.md) | A cold build is ~16 s of single-core semantic analysis; codegen and link are nearly free. No redundant files to cut. Keep the default backend: `-fllvm` is 2x slower, `-fincremental`/`--watch` do not help on Zig 0.17-dev, and `-fno-llvm -fno-lld` exhausts memory. Iterate with `-Dtest-filter` (44 s → 13 s). |
## When to write one