milestone 15: make a green run mean a real pass

build.zig

@@ -21,14 +21,34 @@ pub fn build(b: *std.Build) void {
     const fuzz = b.option(bool, "fuzz", "Build the fuzz targets with the LLVM backend (required for --fuzz)") orelse false;
     const version_string = b.option([]const u8, "version-string", "Version reported by `nxdns version`") orelse "0.1.0-dev";
     const git_commit = b.option([]const u8, "git-commit", "Git commit reported by `nxdns version`") orelse "unknown";
-    const web_dist = b.option([]const u8, "web-dist", "Built web UI directory to embed (default: the placeholder page)") orelse "web/dist-placeholder";
+    const web_dist = b.option(
+        []const u8,
+        "web-dist",
+        "Built web UI directory to embed (default: the placeholder page). " ++
+            "Only the exact value `web/dist` gets the freshness check; " ++
+            "the placeholder and any other path skip it.",
+    ) orelse "web/dist-placeholder";
 
     // `b.path` panics on absolute paths, and a CI artifact directory is one.
     const web_dist_path: std.Build.LazyPath = if (std.fs.path.isAbsolute(web_dist))
         .{ .cwd_relative = web_dist }
     else
         b.path(web_dist);
-    const web_assets = webAssetsIndex(b, web_dist_path);
+
+    // A stale `web/dist` shipped a crashing settings page once (milestone-15
+    // ruling 5). The stamp is checked only for the real dist tree: the
+    // placeholder has no sources to be stale against, and an explicit path is a
+    // CI artifact that was built elsewhere.
+    const web_dist_check: ?*std.Build.Step = if (std.mem.eql(u8, web_dist, "web/dist")) check: {
+        const run_check = b.addSystemCommand(&.{"node"});
+        // The script path goes through `b.path` so it resolves against the
+        // build root: `zig build` run from any other directory would not find
+        // a cwd-relative one.
+        run_check.addFileArg(b.path("web/scripts/stamp-dist.mjs"));
+        run_check.addArg("--check");
+        break :check &run_check.step;
+    } else null;
+    const web_assets = webAssetsIndex(b, web_dist_path, web_dist_check);
 
     const options = b.addOptions();
     options.addOption(bool, "integration", integration);
@@ -45,6 +65,40 @@ pub fn build(b: *std.Build) void {
     if (b.args) |args| run.addArgs(args);
     b.step("run", "Run nxdns").dependOn(&run.step);
 
+    // Zig collects tests only from the root module, so a file missing from
+    // src/tests.zig silently contributes no tests. The list stays hand-written
+    // (generating it from a staged copy would point diagnostics at cache
+    // paths); this makes it complete by construction instead.
+    checkTestImports(b);
+
+    // A successful `zig build test` still prints `failed command: .../test
+    // ... --listen=-` as its last line. This is an upstream zig 0.16.0
+    // build-runner labelling defect, not a failure here, and not something
+    // this build script can suppress without hiding real failures.
+    //
+    // Mechanism, verified against the 0.16.0 sources on 2026-08-07:
+    //   - std/Build/Step/Run.zig:1540 sets `result_failed_command` for every
+    //     spawn, unconditionally ("if an error occurs, it's caused by this
+    //     command"). Nothing clears it when the child succeeds.
+    //   - compiler/build_runner.zig:1381 prints a step's diagnostics whenever
+    //     `result_stderr` is non-empty, explicitly "no matter the result".
+    //   - compiler/build_runner.zig:1515, reached from there, emits the
+    //     `failed command: ` line because `result_failed_command` is non-null.
+    // So any Run step that both succeeds and writes one byte to stderr gets
+    // the label. Our suite writes plenty: the tests that exercise the warning
+    // paths log through the real sink.
+    //
+    // Minimal reproducer, no mbedTLS and no C: one passing test whose body is
+    // `std.debug.print` plus `try expect(true)`, in a build.zig with nothing
+    // but `addTest` + `addRunArtifact`. It prints the label and reports
+    // "3/3 steps succeeded; 1/1 tests passed". Deleting the print removes the
+    // label. The test child does not crash and does not abort in teardown.
+    // (Running the cached test binary by hand with `--listen=-` does abort,
+    // but only because stdin is then closed and the IPC runner panics on
+    // `EndOfStream`; that is an artifact of the manual invocation.)
+    //
+    // No upstream issue matched a search of ziglang/zig for this behaviour;
+    // the reference is the 0.16.0 source lines above. See AGENTS.md.
     const tests = b.addTest(.{
         .root_module = b.createModule(.{
             .root_source_file = b.path("src/tests.zig"),
@@ -109,6 +163,26 @@ pub fn build(b: *std.Build) void {
     });
     test_step.dependOn(&b.addRunArtifact(blocklist_fuzz_tests).step);
 
+    // `src/web/http_util.zig` imports only std, so its fuzz module roots
+    // directly at the file — no aggregator needed (milestone-15 ruling 6c).
+    const http_util_mod = b.createModule(.{
+        .root_source_file = b.path("src/web/http_util.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+    const http_util_fuzz_mod = b.createModule(.{
+        .root_source_file = b.path("tests/fuzz/http_util_fuzz.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+    http_util_fuzz_mod.addImport("http_util", http_util_mod);
+    const http_util_fuzz_tests = b.addTest(.{
+        .name = "http-util-fuzz",
+        .use_llvm = if (fuzz) true else null,
+        .root_module = http_util_fuzz_mod,
+    });
+    test_step.dependOn(&b.addRunArtifact(http_util_fuzz_tests).step);
+
     // The bench harness (milestone-12 ruling 1). The measured roots
     // (matcher.zig, dns_cache.zig, compiler.zig) share files in their relative
     // import closures (model.zig, types.zig, ...), and a file may belong to
@@ -116,6 +190,10 @@ pub fn build(b: *std.Build) void {
     // into one executable. So one staged module: a copy of src/ plus a
     // generated aggregator root, imported by the bench as `core`. No sqlite,
     // no mbedTLS: the closure is pure Zig.
+    //
+    // The compiler fuzz target reuses the same staged tree (milestone-15
+    // ruling 6b): `compiler.zig` imports `../dns/`, so a module rooted under
+    // `src/filter/` fails with ImportOutsideModulePath.
     const bench_stage = b.addWriteFiles();
     _ = bench_stage.addCopyDirectory(b.path("src"), "src", .{});
     const bench_core = bench_stage.add("bench_core.zig",
@@ -133,6 +211,19 @@ pub fn build(b: *std.Build) void {
         .target = target,
         .optimize = optimize,
     });
+    const compiler_fuzz_mod = b.createModule(.{
+        .root_source_file = b.path("tests/fuzz/compiler_fuzz.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+    compiler_fuzz_mod.addImport("core", bench_core_mod);
+    const compiler_fuzz_tests = b.addTest(.{
+        .name = "compiler-fuzz",
+        .use_llvm = if (fuzz) true else null,
+        .root_module = compiler_fuzz_mod,
+    });
+    test_step.dependOn(&b.addRunArtifact(compiler_fuzz_tests).step);
+
     const bench_mod = b.createModule(.{
         .root_source_file = b.path("tools/bench.zig"),
         .target = target,
@@ -192,6 +283,53 @@ pub fn build(b: *std.Build) void {
     }
 }
 
+/// Milestone-15 ruling 4: every `*.zig` under `src/` must appear in
+/// `src/tests.zig` as a line that trims to exactly `_ = @import("<path>");`,
+/// where `<path>` is relative to `src/`. Whole-line equality, not a substring
+/// search: a commented-out import trims to a line starting with `//` and does
+/// not match, and `db.zig` cannot satisfy the requirement for `db2.zig`.
+/// Duplicate lines are an error too — they hide a botched merge. No allowlist:
+/// a file with no tests still gets imported, because the import is free and an
+/// exception is the thing that lets a real gap through.
+fn checkTestImports(b: *std.Build) void {
+    const gpa = b.allocator;
+    const io = b.graph.io;
+    const root = b.build_root.handle;
+
+    const tests_src = root.readFileAlloc(io, "src/tests.zig", gpa, .limited(4 << 20)) catch |err| {
+        std.process.fatal("cannot read src/tests.zig: {t}", .{err});
+    };
+
+    var src_dir = root.openDir(io, "src", .{ .iterate = true }) catch |err| {
+        std.process.fatal("cannot open src/: {t}", .{err});
+    };
+    defer src_dir.close(io);
+
+    var walker = src_dir.walk(gpa) catch @panic("OOM");
+    defer walker.deinit();
+
+    while (walker.next(io) catch |err| {
+        std.process.fatal("cannot walk src/: {t}", .{err});
+    }) |entry| {
+        if (entry.kind != .file) continue;
+        if (!std.mem.endsWith(u8, entry.path, ".zig")) continue;
+        if (std.mem.eql(u8, entry.path, "tests.zig")) continue;
+
+        const needle = b.fmt("_ = @import(\"{s}\");", .{entry.path});
+        var matches: usize = 0;
+        var lines = std.mem.splitScalar(u8, tests_src, '\n');
+        while (lines.next()) |line| {
+            if (std.mem.eql(u8, std.mem.trim(u8, line, " \t\r"), needle)) matches += 1;
+        }
+        if (matches == 0) {
+            std.process.fatal("src/tests.zig is missing `{s}`", .{needle});
+        }
+        if (matches > 1) {
+            std.process.fatal("src/tests.zig repeats `{s}` {d} times", .{ needle, matches });
+        }
+    }
+}
+
 fn addExecutable(
     b: *std.Build,
     target: std.Build.ResolvedTarget,
@@ -226,8 +364,14 @@ fn addExecutable(
 /// tool because a Run step hashes only the resolved path string of a directory
 /// argument, not its contents; the staged copy lives at a content-hashed path,
 /// so editing an asset re-runs the tool instead of replaying a stale cache.
-fn webAssetsIndex(b: *std.Build, dist: std.Build.LazyPath) std.Build.LazyPath {
-    const staged = b.addWriteFiles().addCopyDirectory(dist, ".", .{});
+fn webAssetsIndex(
+    b: *std.Build,
+    dist: std.Build.LazyPath,
+    freshness_check: ?*std.Build.Step,
+) std.Build.LazyPath {
+    const stage = b.addWriteFiles();
+    if (freshness_check) |check| stage.step.dependOn(check);
+    const staged = stage.addCopyDirectory(dist, ".", .{});
 
     const tool = b.addExecutable(.{
         .name = "gen_web_assets",