# Milestone 15: make a green run mean a real pass

Goal: repair the verification pipeline — CI that watches the branch we push to, a test run whose output contains no false failure text, guards that make the test list and the embedded frontend complete by construction, and coverage for the seams the audit found unguarded. This is phase 1 of `TECH_DEBT.md`; nothing in phases 2-5 can be validated until this lands.

Origin: `TECH_DEBT.md` Theme 1 (lines 17-52), audited at `1ff727f`, every finding adversarially verified.

## Sequencing (binding)

This milestone lands **before** milestone 14 is implemented. Ruling 1 pulls the `ci.yml` branch switch forward from milestone-14 §7; when milestone 14's S4 later restructures the workflows into `gates.yml`/`release.yml`, it rebases on what this milestone leaves behind. One more overlap is binding: milestone 14's S1 rewrites `build.zig` (deletes `cross`, adds `dist`/`verify-dist`) — it must rebase on and **preserve** the configure-time machinery this milestone adds there (ruling 4's import guard, ruling 5's stamp check, ruling 6b's staged `core` module). Milestone 14's spec stands as written otherwise.

## Rulings (binding)

### 1. CI watches `master`

`.gitea/workflows/ci.yml:1-11` triggers on `push`/`pull_request` for `main`. Day-to-day pushes go to `origin/master` (`branch.master.merge` confirms), so milestone 13+ never ran through any gate. Change both `branches:` lists to `[master]`. Nothing else in the file changes — the `gates.yml` restructure is milestone-14 work.

Orchestrator, after merge: delete `origin/main`, set the Gitea default branch to `master`, push, and confirm a run starts. (Milestone-14 §7 already rules `master` canonical; this executes the branch part now.)

### 2. The live-network suite runs on a schedule

`.gitea/workflows/live-tls.yml` runs on `workflow_dispatch` only. Both failure modes it exists to catch have each happened once (35f2324; the milestone-4 cert drift). Add:

```yaml
on:
  workflow_dispatch:
  schedule:
    - cron: "0 5 * * 1"
```

Weekly, Monday 05:00 UTC. It stays non-blocking — this does not conflict with the milestone-1 ruling that live tests never gate a push. Everything else in the file is untouched.

### 3. The teardown abort is root-caused, or documented where it lives

Reproduction, verified at HEAD: `zig build test` exits 0 but prints as its last line `failed command: .../test ... --listen=-`. The same binary exits 0 in stdio mode (`1242 passed; 115 skipped; 0 failed`) and exits 134 (SIGABRT) under `--listen=-`. The abort happens after all tests pass, in teardown, only under zig's IPC runner. No comment anywhere in the repository records this; the knowledge lives in one contributor's memory and `TECH_DEBT.md:24-25`.

The cost is not the abort — it is that the one string that should mean failure prints on every success, and everyone learns to ignore failure text.

The session must attempt a root cause, in this order:

1. Reproduce: run the cached test binary directly with and without `--listen=-`. Capture the abort backtrace (`ulimit -c` / gdb / the zig `--debug-...` runner flags — whatever this host offers).
2. Bisect the mbedTLS linkage: `addMbedtlsThreadingMacros` (build.zig), the shim (`src/platform/mbedtls_shim.c`), and the two `extern fn` link checks in `src/tests.zig:121-123` are the suspects. A minimal reproducer (empty test file + mbedTLS link + `--listen`) decides whether the abort is ours or an upstream zig 0.16 runner defect.
3. Outcome A — the cause is ours: fix it. Acceptance is a `zig build test` run whose output contains no `failed command` line.
4. Outcome B — the cause is upstream: do not patch around it. Document it in two places: a comment on the test wiring in `build.zig` (at the `b.addTest` block, lines 48-69) stating the exact mechanism and the upstream reference, and a paragraph in `AGENTS.md` stating that `failed command` + exit 0 after a full pass is this known artifact and that any *other* failure text is real.

Either way: no check is loosened, no output is filtered, and the spec is updated afterward to record which outcome held (per the spec-update rule).

**Outcome recorded (implementation): B — upstream, and this ruling's own diagnosis was wrong.** The label is not an abort and has nothing to do with mbedTLS. In Zig 0.16.0, `std/Build/Step/Run.zig:1540` sets `result_failed_command` unconditionally on every spawn and nothing clears it on success; `compiler/build_runner.zig:1381` prints a step's diagnostics whenever the child wrote to stderr, "no matter the result", and `:1515` then emits the `failed command:` label because the field is non-null. Any Run step that succeeds while writing one byte to stderr gets the label; our warning-path tests log through the real sink. Minimal reproducer: one passing test containing a `std.debug.print` shows the label; the same test without the print shows nothing. The old "exits 134 under `--listen=-`" observation was a manual-invocation artifact: the IPC runner panics with `EndOfStream` (test_runner.zig:88) reading a closed stdin when no build runner sits on the other end. Documented in the `b.addTest` comment in build.zig and in AGENTS.md ("Reading `zig build test` output"). No matching upstream issue found; the 0.16.0 source lines are the reference.

### 4. The test import list gets a completeness guard

`src/tests.zig:3-119` is a hand-maintained `comptime` block of 115 `_ = @import("...");` lines. Zig collects tests only from the root module; a forgotten import silently drops a file's tests (verified empirically). The list stays hand-written — generation via a staged copy of `src/` would point diagnostics at cache paths — but it becomes complete by construction:

In `build.zig`, at configure time, walk `src/` recursively. For every `*.zig` file except `src/tests.zig` itself, require that `src/tests.zig` contains a **line** which, after whitespace trim, is exactly `_ = @import("<path>");` where `<path>` is the file's path relative to `src/`. A line match, not a substring search: a commented-out import (`// _ = @import(...)`) trims to a line that starts with `//` and does not match, and a path that is a prefix of another (`db.zig` vs `db2.zig`) cannot false-match because the full line is compared. Duplicate matching lines are an error too (they hide a botched merge). On the first missing file, fail the configure with an error that names it:

```
src/tests.zig is missing `_ = @import("filter/new_module.zig");`
```

No allowlist. A file with no tests still gets imported — the import is free, and the rule stays exceptionless. The walk runs on the host in every invocation, including the aarch64 configure.

### 5. `web/dist` gets a freshness stamp

A stale `web/dist` has already shipped a crashing settings page once (`docs/explanation/performance-and-testing.md:154-163` admits the hole). Mechanism — one implementation, in JavaScript, because the frontend CI job has Node and no Zig:

- New file `web/scripts/stamp-dist.mjs`. Two modes:
  - default (write): hash the input set, write the hex digest to `web/dist/.src-hash`.
  - `--check`: recompute, compare with `web/dist/.src-hash`, exit 1 with `web/dist is stale: rebuild the frontend (npm run build)` on mismatch or missing stamp.
- The script resolves every path (input files and `web/dist/.src-hash`) from its own location via `import.meta.url`, never from `process.cwd()`: write mode runs from `web/` (npm script) and check mode runs from the repo root (build.zig system command), and both must hash the same set. The acceptance run exercises both working directories.
- Input set, sorted by path, SHA-256 over `path ++ "\x00" ++ contents ++ "\x00"` per file: every file under `web/src/` and `web/public/`, plus `web/index.html`, `web/package.json`, `web/package-lock.json`, `web/vite.config.ts`, `web/tsconfig.json`, `web/tsconfig.app.json`, `web/tsconfig.node.json`. Node's `crypto` module; no new dependency.
- `web/package.json`: `"build"` becomes `"vite build && node scripts/stamp-dist.mjs"`.
- `build.zig`: when the resolved `-Dweb-dist` value is exactly `web/dist`, the asset pipeline (`webAssetsIndex`) gains a dependency on `b.addSystemCommand(&.{ "node", "web/scripts/stamp-dist.mjs", "--check" })`. The default `web/dist-placeholder` path and any other explicit path skip the check; the `web-dist` option description says so.

### 6. Three new fuzz surfaces, corpus replay only

All targets follow the existing registration shape (one `test "fuzz ..."` + one `fn target(ctx, smith: *Smith)`), attach to `test_step`, and run as corpus replay under plain `zig build test` — once per corpus entry plus once on empty input. CI never passes `--fuzz` (blocked by upstream zig 0.16 defects; the audit confirmed corpus replay is the sanctioned CI smoke).

**6a. `stripEcs`** — the only attacker-facing packet-rewriting entry point, absent from the fuzz targets. Add a target to `tests/fuzz/dns_fuzz.zig`. Derive input exactly as `parseTarget` (lines 57-89) already does: it ends with a validated `Packet` and its `OptRecord`, which are `stripEcs`'s second and third parameters. Respect the three entry assertions (`src/dns/edns.zig:196-204`): pass the same `bytes` the packet was parsed from, and a separate stack `out` buffer — an assertion trip from a violated precondition is not a finding. Assert on `.rewritten` output: it re-parses, `findOptRecord` + `parseOpt` succeed, no ECS option (code 8) remains, and header counts survive. No build.zig change — the module exists.

**6b. `compiler.compile`** — the streaming `takeDelimiter`/`StreamTooLong`/discard loop (`src/filter/compiler.zig:64-78`) is never fuzzed, and its `error.EndOfStream`-during-discard arm (line 73) has no test at all. `compiler.zig` imports `../dns/`, so a module rooted under `src/filter/` fails with `ImportOutsideModulePath`. Use the staged-copy aggregator pattern from `bench_core` (`build.zig:112-135`) — `bench_core` already exposes `compiler` at line 124; reusing the same staged tree is allowed. New file `tests/fuzz/compiler_fuzz.zig`, module import name `core`. The target feeds `compile()` via `std.Io.Reader.fixed` over smith bytes with a deliberately small reader buffer, into discarding writers, and asserts it returns without panic and that `counts` are internally consistent. Corpus (inline, `sliceInput` idiom): a line longer than `max_line_len` (4096) with and without a trailing `\n`, so both the discard path and the EndOfStream-during-discard arm replay. Add a plain unit test for the line-73 arm alongside the existing compiler tests.

**6c. `http_util`** — the third untrusted-byte family, unfuzzed. `src/web/http_util.zig` imports only `std`, so the fuzz module roots at a new file `tests/fuzz/http_util_fuzz.zig` with `addImport("http_util", <module rooted at src/web/http_util.zig>)` — no aggregator. Targets: `parsePath`, `decodeInPlace` (both `PlusRule` values), `queryValue`. Invariants to assert: split-before-decode and decode-only-shrinks (result length ≤ input length; result is a prefix-aliased slice of the buffer). **Corrected during implementation:** the original phrasing "a decoded segment never gains a `/`" is false — `%2F` legitimately decodes to a literal `/` inside its segment (http_util.zig's own tests assert it), and the fuzz target caught that on its first run. The property that holds is a count: segmentation is decided by the raw bytes, so each decoded segment pairs with its raw `/`-delimited chunk in order, the segment counts match, and each segment is no longer than its chunk. A decode-then-split implementation still fails this. `dnsParam`/`decodeDnsValue` stay private in `doh_server.zig` and stay unfuzzed — recorded, out of scope.

### 7. The multi-read fetch path gets a real fixture route

The exact seam of 35k-killer 35f2324 is still never driven end to end: every fixture reply is one `request.respond` of a ~130-byte body (`src/filter/filter_integration_test.zig:414`), and the post-fix unit tests pre-buffer readers. Two thresholds matter and they are different: a body over 16 KiB (`fetcher.min_transfer_buf`, fetcher.zig:24) forces the fetcher's `pumpBody` loop to iterate; a body over the fixture's 8192-byte write buffer forces the fixture to flush in parts.

- Add a route `chunked` to the `Route` enum (line 354). Its `respond` arm uses `respondStreaming`, writes a well-formed blocklist body of at least 24 KiB in at least three writes with an explicit `flush()` between each, then ends the stream. `keep_alive = false`, like every other arm (the comment at lines 409-411 is load-bearing).
- Add one `-Dintegration` test that drives the full `refreshOnce` path through this route and asserts the parsed domain counts.
- Prove it can fail: during development, reintroduce the `readSliceShort(self.transfer_buf)` aliasing pattern locally and confirm the new test dies where the old suite stayed green. Record the proof in the session notes; do not commit the revert. **Proof recorded (implementation):** with the aliasing reintroduced, the new test failed (`expected 1500, found 1238`) while all 1378 other tests stayed green. On this body the bug silently dropped 262 domains rather than crashing — the count assertion does the real work, not the crash.

### 8. The rotation failure paths get tests

`src/platform/logging.zig` codifies an exactly-one-sink-error contract across four functions (stated at lines 455-460) and its own test section admits the rotation failure paths are uncovered (lines 604-612). Injection seam:

```zig
var rotate_fault: enum { none, fail_delete, fail_rename } = .none;
```

file-private, read by `deleteLocked` (line 590) and `renameLocked` (line 597) as their first statement (`if (rotate_fault == .fail_delete) return error.RotateFailed;`), compiled only under `@import("builtin").is_test`. Two new tests, each following the established shape of the failed-open test at lines 883-909 (save and restore `state.*`, hold `std.debug.lockStderr`):

- `fail_delete`: `prepareFileLocked` returns false, `sink_errors` rose by exactly one, `rotate_pending` stays set, the file stays closed.
- `fail_rename`: same assertions through the rename step.

### 9. The CLI drift guard derives its needles

`src/docs_drift_test.zig:51` hardcodes the subcommand list; its two sibling guards derive theirs (`routes.table`, `model.toSettings`). The source of truth today is three parallel copies: the `if (eql(...))` parse chain (`cli.zig:91-102`), the `main.zig:69-78` dispatch switch, and `usage_text` (cli.zig:334). Note the spelling trap: tags are `export_`/`import_`, argv strings are `export`/`import`.

- Add to `cli.zig`:

  ```zig
  pub const CommandName = struct { name: []const u8, tag: std.meta.Tag(Command) };
  pub const command_names = [_]CommandName{
      .{ .name = "run", .tag = .run },
      .{ .name = "check", .tag = .check },
      .{ .name = "export", .tag = .export_ },
      .{ .name = "import", .tag = .import_ },
      .{ .name = "version", .tag = .version },
      .{ .name = "help", .tag = .help },
  };
  ```

  plus a comptime assert that `command_names.len == @typeInfo(Command).@"union".fields.len`, so a new tag without a table entry fails the compile.
- `parseArgs` matches the command word by iterating `command_names` (the per-command argument parsing that follows stays as-is).
- `docs_drift_test.zig` iterates `cli.command_names` for its `## `{s}`` needles; the hardcoded list is deleted.
- New test in `cli.zig`: every `command_names[i].name` appears in `usage_text`.
- `main.zig`'s dispatch switch stays — it is exhaustive over the union and the compiler already guards it.

## Sessions

S1-S4 run in parallel; no two sessions write the same file. The S1/S3 interface is fixed here so neither blocks: S3 writes the fuzz source files named in ruling 6; S1 wires them in `build.zig` with the module shapes named there (6b gets `core` via the staged-copy pattern; 6c gets `http_util` rooted at `src/web/http_util.zig`); both artifacts attach to `test_step` exactly like `fuzz_tests` at build.zig:92.

### Session S1: build system and stamp

Owns `build.zig`, `AGENTS.md`, `web/scripts/stamp-dist.mjs`, `web/package.json`. Rulings 3, 4, 5, and the wiring half of 6.

### Session S2: workflows

Owns `.gitea/workflows/ci.yml`, `.gitea/workflows/live-tls.yml`. Rulings 1 (file edit only), 2.

### Session S3: fuzz targets and fixture

Owns `tests/fuzz/dns_fuzz.zig`, `tests/fuzz/compiler_fuzz.zig` (new), `tests/fuzz/http_util_fuzz.zig` (new), `src/filter/filter_integration_test.zig`, and the compiler unit-test addition in `src/filter/compiler.zig`. Rulings 6 (target half), 7.

### Session S4: guards and seams

Owns `src/cli.zig`, `src/docs_drift_test.zig`, `src/platform/logging.zig`. Rulings 8, 9.

### Orchestrator

Ruling 1's remote operations (delete `origin/main`, flip the Gitea default, confirm a run starts), the ruling-3 outcome recorded back into this spec, and striking the closed Theme-1 findings in `TECH_DEBT.md`.

## Module layout

New files:

- `web/scripts/stamp-dist.mjs` — dist freshness stamp, write and `--check` modes.
- `tests/fuzz/compiler_fuzz.zig` — compiler streaming-loop target.
- `tests/fuzz/http_util_fuzz.zig` — HTTP parser targets.

## Acceptance (milestone complete)

- [ ] `ci.yml` triggers on `master` for push and pull_request; a push to
      `origin/master` starts a CI run; `origin/main` is deleted; the Gitea
      default branch is `master`.
- [ ] `live-tls.yml` keeps `workflow_dispatch` and gains the weekly cron.
- [ ] Ruling 3 resolved: either `zig build test` prints no `failed command`
      line, or the build.zig comment and the AGENTS.md paragraph exist and
      name the upstream cause. The outcome is recorded in this spec.
- [ ] The import guard was proven able to fail: a temporary
      `src/guard_probe.zig` containing one test, not imported, makes
      `zig build test` fail at configure naming the file; after adding the
      import it runs; the probe is then deleted.
- [ ] `npm run build` writes `web/dist/.src-hash`. Appending a byte to a
      file under `web/src/` (restored after the probe — the digest hashes
      paths and contents, so a bare `touch` cannot make it stale) then
      running `zig build -Dweb-dist=web/dist` from the repo
      root fails with the stale message; rebuilding the frontend clears it.
      (The probe is the default install step, not `cross` — milestone 14
      deletes `cross`, and this check must stay valid across that rebase.)
      Plain `zig build test` (placeholder path) is unaffected.
- [ ] The three fuzz surfaces run under `zig build test` as corpus replay:
      the stripEcs target with its re-parse/no-ECS assertions, the compiler
      target with the long-line corpus entries, the http_util targets with
      both invariants. The line-73 EndOfStream arm has a unit test.
- [ ] The `chunked` fixture route writes ≥ 24 KiB in ≥ 3 flushed parts; the
      new integration test passes; the session notes record the
      proven-able-to-fail run against the 35f2324 aliasing pattern.
- [ ] The two rotation-failure tests pass, each asserting exactly one
      `sink_error` per the lines-455-460 contract.
- [ ] `docs_drift_test.zig` contains no hardcoded subcommand list;
      `cli.command_names` exists with the comptime length assert; the
      usage-text test passes.
- [ ] Full suite green (`-Dintegration`), test count strictly above 1242, and
      the aarch64 suite still builds and runs under qemu.

## Anti-requirements

- No `gates.yml`, no `release.yml`, no `dist`/`verify-dist` steps — that is milestone 14, which rebases on this milestone.
- No `--fuzz` anywhere in CI.
- No fuzzing or relocation of `dnsParam`/`decodeDnsValue`.
- No generated `tests.zig`; the hand list stays, the guard makes it complete.
- No frontend changes beyond `web/scripts/stamp-dist.mjs` and the one-line `build` script edit.
- No filtering, wrapping, or suppression of test-runner output to hide the `failed command` line.
- No new dependencies, Zig or npm.
