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.mdnew file mode 100644index 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.mdindex 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