43fb76c4

docs: hygiene-kit doctrine — the table is the law, verdicts print, scopes stated

a73x 2026-08-14 09:43

Commit message

docs: hygiene-kit doctrine — the table is the law, verdicts print, scopes stated

Names the silent-module-loss hazard class where the comptime-error
finding already describes it. Appends the hygiene-kit doctrine to
the 2026-08-14 section: the layer table as computed topological
strata (extract-and-diff proof, 76 edges unchanged), the two
adjudicated cross-layer edges, test-only imports as a declared
column, refAllDecls scope stated honestly (pub-only, plain vs.
recursive variant per module, and why), leak verdicts that print
instead of changing exit codes, the persistence soak phase's fd/RSS
bounds, and `zig build check` as the pre-commit gate.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/decisions.md

@@ @@ -2623,7 +2623,8 @@ Seven, each stated as the rule it became. @@
+   simply vanishes from the run (227 of 251 tests, and no property
+   named) rather than failing loudly. Length-asserts go first and the
+   slices get sized at runtime, so a bad mutation fails as a test rather
+   than as an absence. This hazard class is named "silent-module-loss"
+   elsewhere in this file and in the module roots' refAllDecls comments.
+. **Flipping a conjunction's operands is not negation.** Shared
+   structure absorbs it — two paths on one filesystem share a `dev`, so
+   swapping the operands of the identity check changed nothing
@@ @@ -3212,3 +3213,59 @@ two dialects. @@
+  `sudo: a password is required` (exit 1): this box grants no non-interactive
+  sudo, so the run half is pending install. valgrind not installable
+  non-interactively; run `sudo pacman -S valgrind` then the script.
+- **The layer table is the law.** build.zig's module graph is declared data:
+  a table row per module (name, root, frozen stratum, production imports,
+  test-only imports), the wiring loop derives every grant, and a production
+  import that does not point strictly downward is a comptime error — as is
+  a table-row rename (comptime idxOf) and a wasm row importing a non-wasm
+  row (the wasm set is closed under production imports). Layers are
+  COMPUTED topological strata, frozen 2026-08-14 — hand-assignment was
+  tried first and misplaced engine on the first draft. Changing the
+  architecture now means editing the table, which is the point. Proven by
+  extract-and-diff: 76 edges before and after, empty diff.
+- **Two adjudicated edges.** `server -> replica` is test-only (sole use is
+  the applyFrame test helper) and lives in the test_imports column.
+  `client -> proxy` is production (ignoreSigpipe in the live attach path)
+  and is grandfathered with the debt comment at client.zig — relocating
+  ignoreSigpipe to a leaf is the recorded fix, deliberately not taken here.
+- **Test-only imports are a declared column, not an accident.** The testtmp
+  pattern (production modules importing test scaffolding used only inside
+  `test` blocks, kept out of release binaries by lazy compilation) is now
+  stated per-row. The strata computation excludes the column.
+- **refAllDecls in every test-loop module root, scope stated honestly.**
+  Pub decls only — std.meta.declarations sees nothing private. Narrower
+  still than the original hazard framing: in 0.15.2 a pub decl with an
+  unresolvable type fails eagerly once the module is touched at all (the
+  planned probe proof did not reproduce; two isolated repros confirmed),
+  so the gap this closes is the module that is imported but never
+  referenced by name — plus forcing analysis where nothing referenced the
+  decl. quic/quic_server/quic_client use the plain variant (the recursive
+  walk would analyze the whole wolfSSL/ngtcp2 cImport namespace); engine
+  was downgraded to plain because recursion reaches pre-existing comptime
+  errors inside vendored ghostty-vt (re-promote when the dep is bumped);
+  wasm_core is excluded because it is not in the native test loop and a
+  block there would never run.
+- **Leak verdicts print, never panic.** All three binaries check
+  `gpa.deinit()` and print `<binary>: LEAK: allocations outlived deinit`
+  to stderr on `.leak` — never an exit-code change, because muxd's exit
+  code carries the session shell's. e2e captures every daemon's stderr and
+  sweeps all captures at the end, behind a canary that fails if the sweep
+  has nothing to read; agent.sh checks the detached-daemon log after each
+  clean stop, post process-exit, and fails loudly if the daemon outlives
+  the stop (a wedged daemon must not read as leak-free). Proven by
+  deliberate leak: marker appeared, e2e failed at the sweep, agent failed
+  all three leakcheck sites. kill -9 paths print nothing — no false
+  positive, no coverage, stated. Known uncovered captures: $OUT.q and the
+  other mid-suite rm'd files (recorded debt).
+- **The persistence soak phase owns the classes 6a cannot see.** One
+  daemon, N client lifecycles: every cycle must prove its client attached
+  (a vacuous cycle fails the phase); fd count must return to baseline
+  exactly, with one settle resample to absorb the unacked-detach race; RSS
+  gets a 4MB growth bound past a 3-cycle warmup (allocators retain pages;
+  equality would flake). The zombie /proc pitfall is guarded (`VmRSS`
+  absent on a dead child reads as empty, not 0). Failure evidence is swept
+  into the faildir, never rm'd. First real numbers: fds 5->5 exact, RSS
+  +108 kB over 8 cycles.
+- **`zig build check` is the pre-commit gate**: fmt (including
+  build.zig.zon) + unit tests, seconds. e2e/agent/soak stay separate
+  steps — minutes-long and process-spawning.