build.zig

const std = @import("std");
const builtin = @import("builtin");

const codegen_corpus = @import("tests/etch_interp/codegen_corpus_build.zig");

pub fn build(b: *std.Build) void {
    comptime {
        if (builtin.zig_version.major != 0 or builtin.zig_version.minor != 16) {
            @compileError(std.fmt.comptimePrint(
                "Weld requires Zig 0.16.x, got {d}.{d}.{d}",
                .{ builtin.zig_version.major, builtin.zig_version.minor, builtin.zig_version.patch },
            ));
        }
    }

    // There is NO root binary: the engine is consumed as a lib + tools. The
    // demonstration is the standalone `examples/triangle/` sub-project, which
    // owns the windowing CLI and documents its own flags.
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    // Shared `weld_core` module — Tier 0 internals consumed by the runtime,
    // the bench harness, and every test executable.
    //
    // `b.addModule` (instead of `b.createModule`) so the module is reachable
    // by the standalone `examples/triangle/` sub-project via
    // `b.dependency("weld", ...).module("weld_core")`. Tier 0
    // `platform.window` is the public window API the triangle binary
    // consumes to open its Vulkan-ready window — same rationale as
    // `weld_render` exposed below.
    const core_module = b.addModule("weld_core", .{
        .root_source_file = b.path("src/core/root.zig"),
        .target = target,
        .optimize = optimize,
        // Generated Vulkan + Wayland bindings use `extern "c"` for the
        // dlopen/dlsym wrapper on POSIX hosts. Linking libc satisfies the
        // resolver; on Windows the same code path takes the kernel32
        // branch and libc is not actually referenced.
        .link_libc = true,
    });

    // Shared `weld_etch` module — parser + type-checker + tree-walking
    // interpreter (foundation submodule per `engine-directory-structure.md`
    // §9.1). Etch is not a Tier 1 module; it is conceptually a foundation
    // submodule and ships as its own top-level public surface under
    // `src/etch/root.zig`. The interpreter pulls in `weld_core` to drive
    // the runtime registry / dynamic archetype / resource store.
    const etch_module = b.createModule(.{
        .root_source_file = b.path("src/etch/root.zig"),
        .target = target,
        .optimize = optimize,
    });
    etch_module.addImport("weld_core", core_module);

    // `weld_audio` module exposes the Tier 1 audio module entry
    // (the Dummy backend is what exists; no real backend does). Consumed by the
    // audio tests and, later, by the runtime once the audio strategy
    // selection wires in.
    const audio_module = b.createModule(.{
        .root_source_file = b.path("src/modules/audio/root.zig"),
        .target = target,
        .optimize = optimize,
    });

    // `weld_render` module exposes the Render Tier 1 module entry,
    // starting with the GAL (GPU Abstraction Layer) public surface and
    // the `Null` + `Vulkan` backends. Consumed by `tests/render/*.zig`
    // and, eventually, by the runtime + `examples/triangle/` standalone
    // sub-project.
    //
    // Imports `weld_core` because the Vulkan backend uses
    // `weld_core.platform.vk` (binding generated by `tools/bindgen`).
    // `b.addModule` (instead of `b.createModule`) registers the module
    // in `b.modules` and makes it consumable by dependents via
    // `b.dependency("weld", ...).module("weld_render")` — a prerequisite of
    // the `examples/triangle/` sub-project.
    const render_module = b.addModule("weld_render", .{
        .root_source_file = b.path("src/modules/render/root.zig"),
        .target = target,
        .optimize = optimize,
    });
    render_module.addImport("weld_core", core_module);

    // `foundation` module: transversal sibling submodules
    // (math, simd). Ships `simd` (batched-SIMD kernels; `adler32` inaugural).
    // Imports nothing but std (engine-simd.md §4). Consumed by
    // `asset_pipeline` (zlib ADLER32 trailer check), the simd tests, and the
    // adler32 bench.
    const foundation_module = b.addModule("foundation", .{
        .root_source_file = b.path("src/foundation/root.zig"),
        .target = target,
        .optimize = optimize,
    });

    // Tier 0 gains a `foundation` dep. `foundation` imports nothing
    // but std, so the graph stays acyclic (`ARCH-016`) and this is the shared
    // bottom layer depending downward, not sideways. What makes the dep
    // load-bearing rather than convenient: the float environment is ASSERTED by
    // `forge_3d`, `forge_3d` may not import `weld_core` (a C1.1 exit metric), so
    // the single owner of the register layout has to be reachable from
    // `foundation` — and `core/jobs/scheduler.zig`, which creates threads, reads
    // `foundation.math.float_env` from there.
    core_module.addImport("foundation", foundation_module);
    // `ARCH-031` rule 5: the shader hot-reload watcher creates a thread,
    // so it must INSTALL the float environment. It reaches the single definition
    // in `foundation/math/float_env.zig` directly, and NOT through a re-export
    // across a tier boundary: a re-export adds a name without adding a
    // definition, and the register layout has exactly one owner.
    render_module.addImport("foundation", foundation_module);

    // `weld_asset_pipeline` module: the Tier 1 Asset Pipeline. The on-disk
    // surfaces it ships are FROZEN — the intermediate `<type>.asset.etch` schema
    // and the runtime `.<type>.bin` 40-byte header — alongside the `AssetHandle`
    // and the slot registry (refcount + generation invalidation). `weld_core`
    // serves the async loader, which consumes the Tier 0 job system;
    // `foundation` serves the DEFLATE/zlib codec, which verifies the ADLER32
    // trailer via `foundation.simd.adler32`.
    const asset_pipeline_module = b.createModule(.{
        .root_source_file = b.path("src/modules/asset_pipeline/root.zig"),
        .target = target,
        .optimize = optimize,
    });
    asset_pipeline_module.addImport("weld_core", core_module);
    asset_pipeline_module.addImport("foundation", foundation_module);

    // `weld_forge` public API surface: Forge ECS component types
    // (`engine-physics-forge.md` §2) + physics descriptor/handle types
    // (`engine-tier-interfaces.md` §1). Imports `foundation` (math types) and
    // `weld_core` (re-exports `core.ecs.components.Velocity` +
    // `core.ecs.EntityId`). Rooted at `api/root.zig` and TYPES ONLY: the module
    // that instantiates the physics module is a separate one, `forge_module`
    // below, rooted at `forge/module.zig`. The `forge_3d` solver depends on this
    // module.
    const forge_api_module = b.createModule(.{
        .root_source_file = b.path("src/modules/forge/api/root.zig"),
        .target = target,
        .optimize = optimize,
    });
    forge_api_module.addImport("foundation", foundation_module);
    forge_api_module.addImport("weld_core", core_module);

    // `physics_f64` build option (default false → `Real = f32`).
    // `-Dphysics_f64=true` flips forge_3d to double precision (large worlds).
    // Exposed to forge_3d as the `build_options` module read by `config.zig`.
    const physics_f64 = b.option(bool, "physics_f64", "Build forge_3d in f64 (double) precision (default f32)") orelse false;
    const forge_build_options = b.addOptions();
    forge_build_options.addOption(bool, "physics_f64", physics_f64);

    // `forge_3d` native 3D solver skeleton. Depends only on
    // `foundation` (math) and `weld_forge` (the api surface; core entity types
    // reach it through api/), plus the `build_options` for the `Real` scalar.
    const forge_3d_module = b.createModule(.{
        .root_source_file = b.path("src/modules/forge/forge_3d/root.zig"),
        .target = target,
        .optimize = optimize,
    });
    forge_3d_module.addImport("foundation", foundation_module);
    forge_3d_module.addImport("weld_forge", forge_api_module);
    forge_3d_module.addOptions("build_options", forge_build_options);

    // `forge/sync.zig`, the ECS <-> solver seam. It is the ONE module
    // that sees both sides: `weld_core` for the World and the `Transform`, `weld_forge`
    // for the physics components, and `forge_3d` for `PhysicsWorld`. `forge_3d` itself
    // keeps its two-import discipline and never learns about the ECS.
    const forge_sync_module = b.createModule(.{
        .root_source_file = b.path("src/modules/forge/sync.zig"),
        .target = target,
        .optimize = optimize,
    });
    forge_sync_module.addImport("weld_core", core_module);
    forge_sync_module.addImport("weld_forge", forge_api_module);
    forge_sync_module.addImport("forge_3d", forge_3d_module);
    forge_sync_module.addImport("foundation", foundation_module);

    // `forge/module.zig`, the `Forge3DModule` adapter. Same import set
    // as `forge_sync`: `weld_core` for `ModuleContext`, `weld_forge` for the frozen
    // descriptor and query types, `forge_3d` for `PhysicsWorld` and the query family.
    // `forge_3d` keeps its two-import discipline and never learns about the ECS.
    const forge_module = b.createModule(.{
        .root_source_file = b.path("src/modules/forge/module.zig"),
        .target = target,
        .optimize = optimize,
    });
    forge_module.addImport("weld_core", core_module);
    forge_module.addImport("weld_forge", forge_api_module);
    forge_module.addImport("forge_3d", forge_3d_module);
    forge_module.addImport("foundation", foundation_module);

    // `src/interfaces/PhysicsModule.zig`, the Tier 1 physics interface and the first file
    // of `src/interfaces/`. FROZEN: it carries
    // `WELD_PHYSICS_PROTOCOL_VERSION` and the comptime surface guard over the thirty-two
    // entries, plus the three body pose/velocity contracts moved out of
    // `forge/api/types.zig`. It needs `weld_forge` for the descriptor and query types and
    // `weld_core` for `ModuleContext`, which the guard's first entry names.
    const interfaces_physics_module = b.createModule(.{
        .root_source_file = b.path("src/interfaces/PhysicsModule.zig"),
        .target = target,
        .optimize = optimize,
    });
    interfaces_physics_module.addImport("weld_forge", forge_api_module);
    interfaces_physics_module.addImport("weld_core", core_module);

    // plugin loader ABI module shared with the stub
    // plugin sub-projects under `tests/core/plugin_loader/stub_plugin/`.
    // Exposes the C ABI types from `desc.zig` (no `WeldAPI` itself,
    // just the declarations the stubs need: `WeldPluginDesc`,
    // `WeldStr`, etc.). Case 3 decision — cross-import via a shared
    // module rather than duplicating the types in each stub.
    const plugin_loader_abi_module = b.createModule(.{
        .root_source_file = b.path("src/core/plugin_loader/desc.zig"),
        .target = target,
        .optimize = optimize,
    });

    // stub plugin libraries, dynamic linkage. Each
    // produces `lib<name>.so` (Linux), `lib<name>.dylib` (macOS),
    // or `<name>.dll` (Windows). Installed under `zig-out/lib/`
    // (POSIX) or `zig-out/bin/` (Windows) so the load_unload_test
    // can find them at known paths.
    const StubSpec = struct {
        name: []const u8,
        root: []const u8,
    };
    const stub_specs = [_]StubSpec{
        .{ .name = "weld_stub_plugin_happy", .root = "tests/core/plugin_loader/stub_plugin/plugin.zig" },
        .{ .name = "weld_stub_plugin_future", .root = "tests/core/plugin_loader/stub_plugin/plugin_future_api.zig" },
        .{ .name = "weld_stub_plugin_legacy", .root = "tests/core/plugin_loader/stub_plugin/plugin_legacy_api.zig" },
        .{ .name = "weld_stub_plugin_no_entry", .root = "tests/core/plugin_loader/stub_plugin/plugin_no_entry.zig" },
    };
    var stub_install_steps: [stub_specs.len]*std.Build.Step = undefined;
    for (stub_specs, 0..) |spec, i| {
        const stub_module = b.createModule(.{
            .root_source_file = b.path(spec.root),
            .target = target,
            .optimize = optimize,
        });
        stub_module.addImport("weld_plugin_abi", plugin_loader_abi_module);
        const stub_lib = b.addLibrary(.{
            .name = spec.name,
            .linkage = .dynamic,
            .root_module = stub_module,
        });
        const stub_install = b.addInstallArtifact(stub_lib, .{});
        stub_install_steps[i] = &stub_install.step;
    }
    const stub_plugins_step = b.step(
        "stub-plugins",
        "Build the three stub plugin libraries used by the plugin_loader tests",
    );
    for (stub_install_steps) |s| stub_plugins_step.dependOn(s);

    // Shaders embedding — shared by the editor + runtime binaries for
    // the viewport blit, and by `examples/triangle/` for the
    // triangle.vert/frag SPIR-V. The `.spv` live under `assets/shaders/`.
    // `b.addModule` (instead of `b.createModule`) so the standalone
    // sub-project consumes it via `b.dependency("weld", ...).module("shaders")`.
    const shaders_module = b.addModule("shaders", .{
        .root_source_file = b.path("assets/shaders/embed.zig"),
        .target = target,
        .optimize = optimize,
    });

    // `zig build run-example-triangle` invokes the standalone
    // `examples/triangle/` sub-project via a `zig build run` subprocess.
    // It is the living architectural test of external consumability.
    const ex_run = b.addSystemCommand(&.{
        b.graph.zig_exe,
        "build",
        "run",
    });
    ex_run.setCwd(b.path("examples/triangle"));
    if (b.args) |args| {
        ex_run.addArg("--");
        ex_run.addArgs(args);
    }
    const ex_step = b.step("run-example-triangle", "Build & run the triangle example sub-project");
    ex_step.dependOn(&ex_run.step);

    // `zig build verify-synth-100` builds the standalone
    // `bench/fixtures/synth_100/` sub-project: a
    // real path-dep package that cooks the committed corpus through the
    // parent's `etch_cook` artifact and compiles it against
    // `weld.module("weld_core")`. A nested cold build — kept OUT of the
    // default `zig build test` (its own CI step, like the triangle).
    const synth_verify = b.addSystemCommand(&.{
        b.graph.zig_exe,
        "build",
    });
    synth_verify.setCwd(b.path("bench/fixtures/synth_100"));
    const synth_verify_step = b.step("verify-synth-100", "Build the synth_100 sub-project (nested zig build — the standalone proof)");
    synth_verify_step.dependOn(&synth_verify.step);

    // `zig build ecs-access-counterproof` drives the declared-access corpus in
    // `tests/core/ecs/access_counterproof/` — the first harness in this
    // repository that asserts a COMPILATION FAILURE.
    //
    // **It matches the diagnostic text and never the exit code**, because a
    // build that dies before the guard is reached exits exactly like one the
    // guard stops. Each case therefore carries two checks: the expected exit,
    // which says something failed, and a substring unique to that case, which
    // says WHAT failed. The substrings are distinct across cases on purpose —
    // matching only the shared refusal marker would let any one case stand in
    // for any other.
    //
    // The control runs in the SAME step and must SUCCEED. Without it the three
    // refusals prove nothing: a view that refused every access would satisfy
    // all three.
    const counterproof_dir = "tests/core/ecs/access_counterproof";
    const CounterproofCase = struct {
        step: ?[]const u8,
        marks: []const []const u8,
    };
    const counterproof_cases = [_]CounterproofCase{
        // The control: `zig build` with no step argument, which this
        // sub-project wires to the one fixture that must compile.
        .{ .step = null, .marks = &.{} },
        .{
            .step = "case-undeclared",
            .marks = &.{"weld-access-refused: this system attempts a read of component"},
        },
        .{
            .step = "case-mutable-on-read",
            .marks = &.{"weld-access-refused: this system attempts a write to component"},
        },
        .{
            // The compiler's own message, not the view's marker: the pairing is
            // refused at the SIGNATURE, so nothing here ever reaches an access
            // test. Its predecessor omitted the `accesses` field and matched
            // `missing struct field: accesses` — which measured that Zig
            // refuses a literal missing a field without a default, a fact that
            // owed nothing to this milestone and guarded nothing.
            .step = "case-mismatched-pair",
            .marks = &.{"expected type 'fn (ecs.scheduler.SystemContextOf"},
        },
        .{
            // Also the compiler's, and for a stronger reason: the promotion is
            // refused at the TYPE, before any access test can run. A refusal
            // carrying the view's marker would mean the second view had been
            // built and was objecting afterwards.
            .step = "case-view-promotion",
            .marks = &.{"expected type '*ecs.view.ErasedFor"},
        },
        .{
            // The job bound, and the mark is the MARKER'S OWN TEXT rather than
            // the refusal's frame — which is what says the reason travelled and
            // not merely that something was refused.
            .step = "case-erased-in-job",
            .marks = &.{"the erased world a view is rebuilt from"},
        },
        .{
            // The same bound reached through a FIELD. **The mark deliberately
            // avoids the message's tail**, which today reads `no reason
            // declared`: `reasonOf` walks only pointers and optionals where
            // `carriesMarkedIn` enters everything, so a marker reached through a
            // field refuses correctly and explains nothing. That asymmetry is a
            // debt this milestone named and left to the bound's owner, and a
            // fixture anchored on its message would go red the day it is
            // repaired — asserting on a defect's symptom is how a repair gets
            // read as a regression. The type name is what identifies this case.
            .step = "case-erased-wrapped-in-job",
            .marks = &.{"Carrier` reaches a dispatched body"},
        },
    };
    const counterproof_step = b.step(
        "ecs-access-counterproof",
        "Assert the six declared-access refusals fire, and that legitimate code still compiles",
    );
    for (counterproof_cases) |case| {
        const run = if (case.step) |name|
            b.addSystemCommand(&.{ b.graph.zig_exe, "build", name })
        else
            b.addSystemCommand(&.{ b.graph.zig_exe, "build" });
        run.setCwd(b.path(counterproof_dir));
        // ALWAYS RE-RUN, and this is not a precaution. A `Run` step with no file
        // argument is cached on its argv alone, and `setCwd` does not make the
        // directory's contents an input — so the first version of this harness
        // replayed a cached success and reported GREEN against a deliberately
        // disabled guard. The verdict of a harness that cannot observe the code
        // it judges is worth nothing, and it looks exactly like a verdict that is.
        run.has_side_effects = true;
        if (case.step == null) {
            run.expectExitCode(0);
        } else {
            run.expectExitCode(1);
            for (case.marks) |mark| run.addCheck(.{ .expect_stderr_match = mark });
        }
        counterproof_step.dependOn(&run.step);
    }

    const shader_compiler_module = b.createModule(.{
        .root_source_file = b.path("tools/shader_compiler/main.zig"),
        .target = target,
        .optimize = optimize,
        .link_libc = true,
    });
    const sp_compiler_module = b.createModule(.{
        .root_source_file = b.path("src/modules/render/shader_pipeline/compiler.zig"),
        .target = target,
        .optimize = optimize,
        .link_libc = true,
    });
    shader_compiler_module.addImport("shader_pipeline_compiler", sp_compiler_module);
    const shader_compiler_exe = b.addExecutable(.{
        .name = "shader_compiler",
        .root_module = shader_compiler_module,
    });
    const shaders_run = b.addRunArtifact(shader_compiler_exe);
    const shaders_step = b.step("shaders", "Regenerate .spv files from .glsl sources via glslc");
    shaders_step.dependOn(&shaders_run.step);

    const shaders_check_run = b.addRunArtifact(shader_compiler_exe);
    shaders_check_run.addArg("--check");
    const shaders_check_step = b.step("shaders-check", "Verify .spv on disk matches a fresh glslc regen");
    shaders_check_step.dependOn(&shaders_check_run.step);

    // `zig build vk-gen-check`: regenerates vk.zig and verifies that
    // the diff vs the commit is empty. Delegated to the existing `bindgen-verify`
    // which covers all generated bindings.
    const vk_gen_check_step = b.step("vk-gen-check", "Verify vk.zig matches a fresh bindgen regen (delegates to bindgen-verify)");
    if (b.top_level_steps.get("bindgen-verify")) |bv| {
        vk_gen_check_step.dependOn(&bv.step);
    }

    // -------------------------------------------------------------- Tests --

    const test_step = b.step("test", "Run all tests");

    // Inline tests living next to the core code.
    const core_tests = b.addTest(.{ .root_module = core_module });
    test_step.dependOn(&b.addRunArtifact(core_tests).step);

    // Same-file tests inside src/etch/*.zig.
    const etch_tests = b.addTest(.{ .root_module = etch_module });
    test_step.dependOn(&b.addRunArtifact(etch_tests).step);

    // inline tests inside src/modules/asset_pipeline/**. The module
    // root re-exports format/ and registry/, so every sub-file is reachable
    // and its inline tests run (engine-zig-conventions.md §13).
    const asset_pipeline_tests = b.addTest(.{ .root_module = asset_pipeline_module });
    test_step.dependOn(&b.addRunArtifact(asset_pipeline_tests).step);

    // inline tests inside src/foundation/** (traits + kernels).
    // simd/root.zig re-exports traits/portable/dispatch/kernels, so they are all
    // reachable and analysed (engine-zig-conventions.md §13).
    const foundation_tests = b.addTest(.{ .root_module = foundation_module });
    test_step.dependOn(&b.addRunArtifact(foundation_tests).step);

    // inline tests inside src/modules/forge/api/** (component
    // size/align asserts, descriptor + component defaults, Velocity re-export
    // identity, BodyId pack/unpack). The api root re-exports components/ +
    // types/, so their inline tests are reachable (engine-zig-conventions.md §13).
    const forge_api_tests = b.addTest(.{ .root_module = forge_api_module });
    test_step.dependOn(&b.addRunArtifact(forge_api_tests).step);

    // forge_3d solver unit tests (C1.1 verification path): the
    // inline tests in config/shape/body/body_manager + the acceptance suite
    // under forge_3d/tests/. root.zig pins them all. Added to
    // `zig build test`; `zig build test-forge-3d` runs just these.
    const forge_sync_tests = b.addTest(.{ .root_module = forge_sync_module });
    test_step.dependOn(&b.addRunArtifact(forge_sync_tests).step);
    const forge_module_tests = b.addTest(.{ .root_module = forge_module });
    test_step.dependOn(&b.addRunArtifact(forge_module_tests).step);

    // the interface file's own tests: the attestation that no protocol
    // version is declared yet, and that the three signatures follow the world scalar.
    const interfaces_physics_tests = b.addTest(.{ .root_module = interfaces_physics_module });
    test_step.dependOn(&b.addRunArtifact(interfaces_physics_tests).step);

    const forge_3d_tests = b.addTest(.{ .root_module = forge_3d_module });
    const forge_3d_tests_run = b.addRunArtifact(forge_3d_tests);
    test_step.dependOn(&forge_3d_tests_run.step);
    const forge_3d_test_step = b.step("test-forge-3d", "Run only the forge_3d solver tests");
    forge_3d_test_step.dependOn(&forge_3d_tests_run.step);

    // `zig build forge-determinism`: the determinism instrument, run
    // at ONE worker over the canonical scenario. The step is deliberately an
    // EXECUTABLE over a library (`tests/determinism/run.zig`) rather than a
    // test, because it gets REPLAYED — at N workers, and on a rebuilt scheduler
    // DAG — and a harness whose logic lived in its `main` would have to be
    // re-entered through a process to be replayed at all. Its self-reproducibility and its artifact
    // liveness are ALSO asserted inside `zig build test`, where the same library
    // is exercised by `forge_3d`'s own suite.
    //
    // Its module carries the same imports as `forge_3d` itself because its root
    // reaches the solver by relative path, exactly as the acceptance suite does.
    const forge_determinism_module = b.createModule(.{
        .root_source_file = b.path("src/modules/forge/forge_3d/determinism_main.zig"),
        .target = target,
        .optimize = optimize,
    });
    forge_determinism_module.addImport("foundation", foundation_module);
    forge_determinism_module.addImport("weld_forge", forge_api_module);
    forge_determinism_module.addOptions("build_options", forge_build_options);
    const forge_determinism_exe = b.addExecutable(.{
        .name = "forge-determinism",
        .root_module = forge_determinism_module,
    });
    const forge_determinism_run = b.addRunArtifact(forge_determinism_exe);
    if (b.args) |args| forge_determinism_run.addArgs(args);
    const forge_determinism_step = b.step(
        "forge-determinism",
        "Run the canonical determinism scenario at one worker",
    );
    forge_determinism_step.dependOn(&forge_determinism_run.step);

    // `zig build forge-asm-inventory`: the conformance test of
    // `ARCH-031` rule 4, read in the EMITTED ASSEMBLY rather than in the source.
    // `forge_3d` is compiled to assembly for the three targets the engine ships
    // and every call site is inspected for a libm transcendental.
    //
    // The scanner is `tools/asm_inventory/` — a Zig program, not `grep`. Named
    // substitution: the check has to anchor on the instruction mnemonic at line
    // start, and the natural `\b` for that is a GNU extension that silently
    // matches NOTHING on BSD grep. A scanner removes the class instead of
    // dodging one instance of it, and it carries its own counter-factuals.
    //
    // A DEDICATED step and NOT part of `zig build test`: three cross-compiles
    // of the whole physics module are minutes of work, `test` runs twice on
    // every `git push` through the pre-push hook, and the answer is a property
    // of the three TARGETS — it does not vary with the host that asks. So CI
    // invokes it on one cell, exactly as it already does for
    // `verify-synth-100`. The scanner's own tests are in `zig build test`.
    const asm_inventory_module = b.createModule(.{
        .root_source_file = b.path("tools/asm_inventory/main.zig"),
        .target = b.graph.host,
        .optimize = .ReleaseSafe,
    });
    const asm_inventory_exe = b.addExecutable(.{
        .name = "asm_inventory",
        .root_module = asm_inventory_module,
    });
    const asm_inventory_run = b.addRunArtifact(asm_inventory_exe);

    // The three targets of the determinism contract: the two OSes of level 1
    // and the ISA of level 2 (`engine-phase-1-criteria.md` C1.1). Each is
    // pinned to `baseline` for the same reason every CI cell is — a runner
    // image that changes processor generation must not change what is emitted
    // (`ARCH-031` rule 6).
    const inventory_targets = [_][]const u8{
        "x86_64-linux-gnu",
        "x86_64-windows-gnu",
        "aarch64-linux-gnu",
    };
    for (inventory_targets) |triple| {
        const query = std.Target.Query.parse(.{
            .arch_os_abi = triple,
            .cpu_features = "baseline",
        }) catch @panic("bad inventory target triple");
        const resolved = b.resolveTargetQuery(query);

        // The module chain has to be rebuilt per target: a `Module` is bound to
        // its target at creation, so the host-bound handles above cannot serve.
        // It mirrors the graph declared earlier in this file and nothing more —
        // if that graph gains an edge, this loop is where it has to be repeated,
        // and a missing edge is a compile error here rather than a silent gap.
        const t_foundation = b.createModule(.{
            .root_source_file = b.path("src/foundation/root.zig"),
            .target = resolved,
            .optimize = .ReleaseSafe,
        });
        const t_core = b.createModule(.{
            .root_source_file = b.path("src/core/root.zig"),
            .target = resolved,
            .optimize = .ReleaseSafe,
            .link_libc = true,
        });
        t_core.addImport("foundation", t_foundation);
        const t_forge_api = b.createModule(.{
            .root_source_file = b.path("src/modules/forge/api/root.zig"),
            .target = resolved,
            .optimize = .ReleaseSafe,
        });
        t_forge_api.addImport("foundation", t_foundation);
        t_forge_api.addImport("weld_core", t_core);
        const t_forge_3d = b.createModule(.{
            .root_source_file = b.path("src/modules/forge/forge_3d/root.zig"),
            .target = resolved,
            .optimize = .ReleaseSafe,
        });
        t_forge_3d.addImport("foundation", t_foundation);
        t_forge_3d.addImport("weld_forge", t_forge_api);
        t_forge_3d.addOptions("build_options", forge_build_options);

        // Compiling `forge_3d/root.zig` DIRECTLY emits nothing — it is a
        // re-export file and Zig is lazy. Measured before this indirection
        // existed: `0 call sites examined` on all three targets, which the
        // scanner refuses rather than reports as clean. The surface root forces
        // the module's public functions into codegen; see its header.
        const t_surface = b.createModule(.{
            .root_source_file = b.path("tools/asm_inventory/forge_3d_surface.zig"),
            .target = resolved,
            .optimize = .ReleaseSafe,
        });
        t_surface.addImport("forge_3d", t_forge_3d);

        const obj = b.addObject(.{
            .name = b.fmt("forge_3d_asm_{s}", .{triple}),
            .root_module = t_surface,
        });
        asm_inventory_run.addFileArg(obj.getEmittedAsm());
    }

    const asm_inventory_step = b.step(
        "forge-asm-inventory",
        "Assert zero libm transcendental call in forge_3d assembly (ARCH-031 rule 4)",
    );
    asm_inventory_step.dependOn(&asm_inventory_run.step);

    // The scanner's own counter-factuals ride in `zig build test`: a scanner
    // that cannot fire reports a clean tree for the wrong reason, and that is
    // the failure this suite exists to make impossible.
    const asm_inventory_tests = b.addTest(.{ .root_module = asm_inventory_module });
    test_step.dependOn(&b.addRunArtifact(asm_inventory_tests).step);

    // `zig build ecs-access-zero-cost` — the declared-access view claims to cost
    // nothing, and that claim is about EMITTED CODE. It is read in the listing,
    // on the `forge-asm-inventory` shape above: emit the assembly of a witness
    // pair, hand the path to a Zig scanner, compare.
    //
    // ReleaseSafe rather than Debug: the claim is about the code a game ships,
    // and Debug emits a prologue and stack probes that say nothing about the
    // view. Pinned here rather than taken from the cell's mode, for the same
    // reason `forge-asm-inventory` pins its own.
    const view_asm_module = b.createModule(.{
        .root_source_file = b.path("tools/view_asm_equiv/main.zig"),
        .target = b.graph.host,
        .optimize = .ReleaseSafe,
    });
    const view_asm_exe = b.addExecutable(.{
        .name = "view_asm_equiv",
        .root_module = view_asm_module,
    });
    const view_asm_run = b.addRunArtifact(view_asm_exe);
    {
        const zc_target = b.resolveTargetQuery(std.Target.Query.parse(.{
            .arch_os_abi = "native",
            .cpu_features = "baseline",
        }) catch unreachable);
        const zc_foundation = b.createModule(.{
            .root_source_file = b.path("src/foundation/root.zig"),
            .target = zc_target,
            .optimize = .ReleaseSafe,
        });
        const zc_core = b.createModule(.{
            .root_source_file = b.path("src/core/root.zig"),
            .target = zc_target,
            .optimize = .ReleaseSafe,
            .link_libc = true,
        });
        zc_core.addImport("foundation", zc_foundation);
        const zc_surface = b.createModule(.{
            .root_source_file = b.path("tests/core/ecs/access_zero_cost_surface.zig"),
            .target = zc_target,
            .optimize = .ReleaseSafe,
        });
        zc_surface.addImport("weld_core", zc_core);
        const zc_obj = b.addObject(.{
            .name = "ecs_access_zero_cost",
            .root_module = zc_surface,
        });
        view_asm_run.addFileArg(zc_obj.getEmittedAsm());
    }
    // `zig build c-api-read-column-constness` — the Tier 3 half of `ARCH-030`.
    //
    // C has no comptime view, and what it has instead is `const`. The witness
    // compiles as published and must NOT compile with one line added that takes
    // a mutable pointer to a column the query declared read-only. Both
    // directions in ONE step, because a refusal nobody pairs with an acceptance
    // is satisfied by a file that never compiles at all.
    //
    // Driven through `zig cc` rather than a `Compile` step: a C compilation
    // expected to FAIL cannot be a step of the graph it would fail. The
    // diagnostic is matched on its text, never on the exit code — a compiler
    // that died for an unrelated reason exits identically.
    const c_witness_dir = "tests/c_api/read_column_constness";
    const c_witness_flags = [_][]const u8{ "-std=c11", "-Wall", "-Werror", "-pedantic" };
    const constness_step = b.step(
        "c-api-read-column-constness",
        "Assert a Tier 3 read column is unreachable by a mutable pointer (engine-c-api.md 5.5)",
    );
    {
        var argv: std.ArrayList([]const u8) = .empty;
        defer argv.deinit(b.allocator);
        argv.appendSlice(b.allocator, &.{ b.graph.zig_exe, "cc" }) catch @panic("OOM");
        argv.appendSlice(b.allocator, &c_witness_flags) catch @panic("OOM");
        argv.appendSlice(b.allocator, &.{ "-c", b.pathJoin(&.{ c_witness_dir, "witness.c" }), "-o" }) catch @panic("OOM");
        const ok = b.addSystemCommand(argv.items);
        // The object goes to a build-owned path rather than to a device: the
        // point is that the compiler accepted it, and a run that writes nowhere
        // is one the build system may legitimately skip.
        _ = ok.addOutputFileArg("witness.o");
        ok.has_side_effects = true;
        ok.expectExitCode(0);
        constness_step.dependOn(&ok.step);
    }
    {
        var argv: std.ArrayList([]const u8) = .empty;
        defer argv.deinit(b.allocator);
        argv.appendSlice(b.allocator, &.{ b.graph.zig_exe, "cc" }) catch @panic("OOM");
        argv.appendSlice(b.allocator, &c_witness_flags) catch @panic("OOM");
        argv.appendSlice(b.allocator, &.{
            "-DWELD_ASSIGN_THROUGH_READ_COLUMN",
            "-c",
            b.pathJoin(&.{ c_witness_dir, "witness.c" }),
            "-o",
        }) catch @panic("OOM");
        const bad = b.addSystemCommand(argv.items);
        _ = bad.addOutputFileArg("witness_counterproof.o");
        // Always re-run: a `Run` cached on its argv alone replays a stale
        // verdict, which is how the sibling counter-proof harness first
        // reported green against a deliberately disabled guard.
        bad.has_side_effects = true;
        bad.expectExitCode(1);
        bad.addCheck(.{ .expect_stderr_match = "discards qualifiers" });
        constness_step.dependOn(&bad.step);
    }

    const view_asm_step = b.step(
        "ecs-access-zero-cost",
        "Assert the declared-access view emits the same instructions as a direct World access",
    );
    view_asm_step.dependOn(&view_asm_run.step);

    // The scanner's own tests ride in `zig build test`, for the reason written
    // beside `asm_inventory`'s: a scanner that cannot discriminate reports a
    // clean verdict for the wrong reason.
    const view_asm_tests = b.addTest(.{ .root_module = view_asm_module });
    test_step.dependOn(&b.addRunArtifact(view_asm_tests).step);

    // Out-of-tree tests: each file is its own root_module and imports
    // `weld_core` to reach the engine internals. The exception is a group whose
    // files `@import` each other — Zig 0.16 forbids a single file from belonging
    // to two module trees, so such a group CANNOT be exposed as sibling modules
    // and gets one thin facade module instead.
    const wl_protocols_test_module = b.createModule(.{
        .root_source_file = b.path("src/core/platform/window/wayland_protocols/tests_facade.zig"),
        .target = target,
        .optimize = optimize,
    });
    const etch_corpus_module = b.createModule(.{
        .root_source_file = b.path("tests/etch/corpus_facade.zig"),
        .target = target,
        .optimize = optimize,
    });

    // Generic test driver module (independent of the corpus + runner) so it
    // can be reused by the codegen-runner without modifying call sites.
    const etch_interp_driver_module = b.createModule(.{
        .root_source_file = b.path("tests/etch_interp/diff_runner.zig"),
        .target = target,
        .optimize = optimize,
    });
    etch_interp_driver_module.addImport("weld_core", core_module);
    // Differential corpus — `tests/etch_interp/` houses the `.etch` programs
    // and their sidecar `expected.zig` files. The facade enumerates
    // them and is consumed by `corpus_test.zig` (the test driver) and by
    // the bench harness. Sidecars in `programs/` reach the diff_runner
    // types through the `diff_runner` module dependency below.
    const etch_interp_corpus_module = b.createModule(.{
        .root_source_file = b.path("tests/etch_interp/corpus_facade.zig"),
        .target = target,
        .optimize = optimize,
    });
    etch_interp_corpus_module.addImport("weld_core", core_module);
    etch_interp_corpus_module.addImport("weld_etch", etch_module);
    etch_interp_corpus_module.addImport("diff_runner", etch_interp_driver_module);
    // Runner module — the interpreter backend.
    const etch_interp_runner_module = b.createModule(.{
        .root_source_file = b.path("tests/etch_interp/runner_interp.zig"),
        .target = target,
        .optimize = optimize,
    });
    etch_interp_runner_module.addImport("weld_core", core_module);
    etch_interp_runner_module.addImport("weld_etch", etch_module);

    // the toy service and the `.d.etch` emitter, defined HERE
    // rather than beside the bindgen steps below because the test-spec loop
    // needs them too, and one module definition serving both is what keeps the
    // tests exercising the very code the `bindgen-check` step runs.
    // The toy is a PERMANENT manifest entry: `etch-abi-zig.md` §8.7 has the
    // interop gates prove themselves on a toy and never on the physics.
    const toy_service_module = b.createModule(.{
        .root_source_file = b.path("tests/etch_services/toy_service.zig"),
        .target = b.graph.host,
        .optimize = .Debug,
    });
    toy_service_module.addImport("weld_etch", etch_module);
    const emit_detch_module = b.createModule(.{
        .root_source_file = b.path("tools/bindgen/emit_detch.zig"),
        .target = b.graph.host,
        .optimize = .Debug,
    });
    emit_detch_module.addImport("weld_etch", etch_module);

    // the physics service and the sensor-event types enter the
    // manifest. They import the forge module, so their modules are built here
    // alongside the toy's.
    const forge_services_module = b.createModule(.{
        .root_source_file = b.path("src/modules/forge/services/physics.zig"),
        .target = b.graph.host,
        .optimize = .Debug,
    });
    forge_services_module.addImport("weld_etch", etch_module);
    forge_services_module.addImport("weld_forge", forge_api_module);
    forge_services_module.addImport("forge_3d", forge_3d_module);
    forge_services_module.addImport("weld_core", core_module);
    forge_services_module.addImport("foundation", foundation_module);
    forge_services_module.addImport("forge_module", forge_module);
    // the MUTATION half of the service resolves an entity to the body the
    // seam drives and marks the seam's own journal, so it needs the seam. `forge_sync` is
    // the only module that sees both the ECS and `PhysicsWorld`, which is exactly what a
    // wrapper writing an ECS mirror needs.
    forge_services_module.addImport("forge_sync", forge_sync_module);
    // the bidirectional Etch slice. It is DRIVEN by a test rather
    // than left as a directory to read: a mechanism nothing executes is the defect
    // an earlier milestone named and this one has closed twice.
    const arena_slice_module = b.createModule(.{
        .root_source_file = b.path("examples/arena/slice.zig"),
        .target = target,
        .optimize = optimize,
    });

    const forge_sensor_events_module = b.createModule(.{
        .root_source_file = b.path("src/modules/forge/sensor_events.zig"),
        .target = b.graph.host,
        .optimize = .Debug,
    });
    forge_sensor_events_module.addImport("weld_etch", etch_module);
    forge_sensor_events_module.addImport("weld_forge", forge_api_module);
    forge_sensor_events_module.addImport("forge_3d", forge_3d_module);
    forge_sensor_events_module.addImport("weld_core", core_module);
    forge_sensor_events_module.addImport("foundation", foundation_module);
    arena_slice_module.addImport("weld_core", core_module);
    arena_slice_module.addImport("weld_forge", forge_api_module);
    arena_slice_module.addImport("forge_3d", forge_3d_module);
    arena_slice_module.addImport("weld_etch", etch_module);
    arena_slice_module.addImport("forge_module", forge_module);
    arena_slice_module.addImport("forge_services", forge_services_module);
    arena_slice_module.addImport("forge_sensor_events", forge_sensor_events_module);
    arena_slice_module.addImport("forge_sync", forge_sync_module);
    arena_slice_module.addImport("foundation", foundation_module);

    const TestSpec = struct {
        path: []const u8,
        wl_protocols: bool = false,
        etch: bool = false,
        etch_interp: bool = false,
        /// when set, the test step depends on
        /// `stub_install_steps[]` so the three stub libraries are
        /// built before the test runs.
        needs_stub_plugins: bool = false,
        /// when set, imports the `weld_audio` module.
        audio: bool = false,
        /// when set, imports the `weld_render` module (GAL public
        /// surface + Null backend, Vulkan backend wires in later).
        render: bool = false,
        /// when set, imports the `weld_asset_pipeline` module.
        asset_pipeline: bool = false,
        /// when set, imports the Forge synchronisation seam and the two
        /// modules it joins, so a test can drive a `PhysicsWorld` against a real ECS
        /// `World`.
        forge: bool = false,
        /// when set, imports the `foundation` module (simd).
        foundation: bool = false,
        /// when set, imports `weld_etch` (the scene cook driver). A
        /// dedicated flag rather than `.etch` so `tests/scene/` does not pull in
        /// the `corpus_facade` baggage `.etch` carries.
        scene: bool = false,
        /// when set, imports the bidirectional arena slice.
        arena_slice: bool = false,
        /// when set, imports the physics service, the sensor-event
        /// types and `weld_etch`, so a test can drive a rule through the service.
        physics_service: bool = false,
        /// when set, imports the toy service module (which also
        /// carries the toy EVENT and its emitted declaration).
        etch_events: bool = false,
        /// when set, imports the `.d.etch` emitter and the toy
        /// service, so a test exercises the SAME functions `bindgen-check` runs.
        bindgen_detch: bool = false,
        /// when set, create a dedicated `zig build
        /// <name>` step that runs ONLY this test. Used by the CI
        /// runtime-smoke-test job to gate strictly on the capture PSNR
        /// without re-running every other test in the repo (some of
        /// which have unrelated ReleaseSafe issues tracked as
        /// out-of-scope debt).
        dedicated_step: ?[]const u8 = null,
    };
    const test_specs = [_]TestSpec{
        .{ .path = "tests/smoke_test.zig" },
        .{ .path = "tests/physics/transform_sync_test.zig", .forge = true },
        // `Forge3DModule`: the allocator/fallibility shape of the
        // frozen surface, and the `step` failure contract.
        .{ .path = "tests/physics/forge_module_test.zig", .forge = true },
        // the Tier 1 physics service called from a rule, and the two
        // sensor deltas translated onto the Tier 0 bus.
        .{ .path = "tests/physics/physics_service_test.zig", .forge = true, .physics_service = true },
        // the slice, run in both directions.
        .{ .path = "tests/physics/arena_slice_test.zig", .arena_slice = true },
        .{ .path = "tests/ecs/world_test.zig" },
        .{ .path = "tests/ecs/chunk_test.zig" },
        .{ .path = "tests/ecs/query_test.zig" },
        .{ .path = "tests/ecs/no_alloc_in_simulation_test.zig" },
        .{ .path = "tests/ecs/generational_indices.zig" },
        .{ .path = "tests/ecs/archetype_transitions.zig" },
        .{ .path = "tests/ecs/queries.zig" },
        // The POSITIVE half of the declared-access enforcement. The refusals it
        // makes non-vacuous live in `tests/core/ecs/access_counterproof/`,
        // driven by `zig build ecs-access-counterproof` — a compile error
        // cannot be a test block.
        .{ .path = "tests/core/ecs/access_view_test.zig" },
        // What the command buffer no longer holds, and when it resolves what it
        // does — the two halves of the `world` field's removal.
        .{ .path = "tests/core/ecs/command_buffer_test.zig" },
        // The Zig half of the `WeldQueryChunk` drift pin; the C half is the
        // `_Static_assert`s in `tests/c_api/read_column_constness/`.
        .{ .path = "tests/c_api/chunk_layout_test.zig" },
        .{ .path = "tests/ecs/change_detection.zig" },
        .{ .path = "tests/ecs/scheduler.zig" },
        .{ .path = "tests/ecs/scheduler_dag.zig" },
        .{ .path = "tests/ecs/no_alloc_scheduler_dispatch.zig" },
        .{ .path = "tests/ecs/command_buffer.zig" },
        .{ .path = "tests/ecs/observers.zig" },
        .{ .path = "tests/ecs/no_alloc_steady_state.zig" },
        .{ .path = "tests/ecs/integration_scenario.zig" },
        .{ .path = "tests/ecs/sparse_routing_test.zig" },
        .{ .path = "tests/ecs/hybrid_query_test.zig" },
        .{ .path = "tests/ecs/requires_test.zig" },
        .{ .path = "tests/core/rtti/comptime_builder_test.zig" },
        .{ .path = "tests/core/rtti/hash_test.zig" },
        .{ .path = "tests/core/rtti/registry_test.zig" },
        .{ .path = "tests/core/rtti/ipc_compat_test.zig" },
        .{ .path = "tests/core/resources/api_test.zig" },
        .{ .path = "tests/core/resources/change_detection_test.zig" },
        .{ .path = "tests/core/resources/query_exclusion_test.zig" },
        .{ .path = "tests/core/resources/lifecycle_test.zig" },
        .{ .path = "tests/core/events/queue_test.zig" },
        .{ .path = "tests/core/events/saturation_test.zig" },
        .{ .path = "tests/core/events/lifetime_test.zig" },
        .{ .path = "tests/core/events/scheduler_integration_test.zig" },
        // `core.ModuleContext`: the four-field pin and its negative
        // twin (exactly one field reaches component registration and the event bus).
        .{ .path = "tests/core/module_context_test.zig" },
        .{ .path = "tests/bindgen/roundtrip_test.zig" },
        .{ .path = "tests/core/plugin_loader/api_stub_test.zig" },
        .{ .path = "tests/core/plugin_loader/load_unload_test.zig", .needs_stub_plugins = true },
        .{ .path = "tests/jobs/deque_test.zig" },
        .{ .path = "tests/jobs/scheduler_test.zig" },
        .{ .path = "tests/window/win32_open_close_test.zig" },
        .{ .path = "tests/window/wayland_open_close_test.zig" },
        .{ .path = "tests/bindings/vk_abi_test.zig" },
        .{ .path = "tests/bindings/wayland_abi_test.zig", .wl_protocols = true },
        .{ .path = "tests/etch/corpus_test.zig", .etch = true },
        // Etch idents that collide with Zig keywords must
        // codegen to parseable (escaped) Zig. RED before the lower.zig fix.
        .{ .path = "tests/etch/keyword_ident_test.zig", .etch = true },
        // top-level recovery sync-point (ParseResult.diagnostics
        // slice + resync at the next top-level keyword).
        .{ .path = "tests/etch/recovery_toplevel_test.zig", .etch = true },
        // EBNF harness: every ```etch example block parses clean.
        .{ .path = "tests/etch/ebnf_examples_test.zig", .etch = true },
        // AST stable interface freeze: thirty Level-1 entry points (§10.3.1).
        // Compilation is the cross-phase invariant.
        .{ .path = "tests/etch/ast_stable_interface.zig", .etch = true, .dedicated_step = "test-ast-stable" },
        // interpreter hot-reload: edit rule body → AST swap →
        // behaviour change on the same live world, measured < 500 ms.
        .{ .path = "tests/etch/hot_reload_test.zig", .etch = true, .dedicated_step = "test-hot-reload" },
        // full-grammar 500+ line integration reference: parse
        // < 50 ms + type-check clean + Level-A interpret.
        .{ .path = "tests/etch/reference_500_test.zig", .etch = true, .dedicated_step = "test-ref500" },
        // `@storage` consumed end to end: the mode reaches the registry, a
        // sparse component leaves the archetype signature, a rule selects on it
        // and writes its row, and the codegen refuses a sparse program.
        // `.etch = true` for `weld_etch`; `weld_core` is unconditional here.
        .{ .path = "tests/etch/storage_mode_test.zig", .etch = true },
        // one test per type-checker diagnostic code: each names its code and
        // asserts PRESENCE, so it reddens the day emission stops.
        .{ .path = "tests/etch/diagnostic_coverage_test.zig", .etch = true },
        // TIME_LITERAL §3.2 expression arm wired (builtin Time §2.2).
        .{ .path = "tests/etch/time_literal_test.zig", .etch = true, .dedicated_step = "test-time-lit" },
        // the consolidated cook library.
        .{ .path = "tests/etch/cook_consolidate_test.zig", .etch = true },
        // triple-quote `"""…"""` multiline string lexer token
        // + §1.4 common-indent strip at parse.
        .{ .path = "tests/etch/lexer_triple_quote_test.zig", .etch = true },
        // cross-file scene/prefab validation (E1782 cross-scene,
        // E1786 cross-file prefab ref, E1791 cross-file prefab base).
        .{ .path = "tests/etch/crossfile_scene_prefab_test.zig", .etch = true },
        // `import` directive parsing: the four grammar forms (whole, selective,
        // aliased, per-item alias), items accepting IDENT as well as TYPE_IDENT,
        // and malformed-import recovery — resync, and no
        // `UnsupportedConstructInS3`.
        .{ .path = "tests/etch/import_parse_test.zig", .etch = true },
        // module graph + cycle (E0108), exports binding
        // (E0103/E0104), cross-file type resolution (no E0102).
        .{ .path = "tests/etch/import_resolve_test.zig", .etch = true },
        // qualified `m.Type` resolution under validateProject:
        // type-alias-target parity with the selective form (`as m` + `m.Type`),
        // use-site E0104/E0107, unresolved-alias E0102, and W0902.
        .{ .path = "tests/etch/qualified_import_test.zig", .etch = true },
        // the E1793 unblock: a `.prefab.etch` importing its
        // component types validates clean; an undeclared component still errors.
        .{ .path = "tests/etch/crossfile_prefab_import_test.zig", .etch = true },
        // interpreter ↔ filtered ECS queries: has / not has / value
        // field-filters (== and ordered) / and-or-not composition + the
        // dynamic-archetype (never-matches-then-matches) case + the per-rule
        // matched-count observable.
        .{ .path = "tests/etch/v1/query_filters_test.zig", .etch = true },
        .{ .path = "tests/etch_interp/corpus_test.zig", .etch_interp = true },
        // scene cook → writer → accessor round-trip (entities,
        // archetypes, UUIDs, names, parent links, content_version, resources,
        // mixed-alignment columns, byte-identical determinism).
        // the Tier 1 service path end to end: `.d.etch` declares,
        // the checker resolves, the tree-walker dispatches into a Zig function.
        .{ .path = "tests/etch_services/service_call_test.zig", .scene = true },
        // the emitter and the `bindgen-check` comparison.
        .{ .path = "tests/etch_bindgen/detch_emitter_test.zig", .bindgen_detch = true },
        // the Tier 0 → Etch event bridge and its tick ordering.
        .{ .path = "tests/etch_events/event_bridge_test.zig", .etch_events = true },
        .{ .path = "tests/scene/cook_roundtrip_test.zig", .scene = true },
        // scene cook negative cases (typed errors, no panic).
        .{ .path = "tests/scene/cook_errors_test.zig", .scene = true },
        // prefab cook → `.prefab.bin`: standalone + `of` variant
        // (base inherited from its cooked `.prefab.bin`, field-merge/add overrides),
        // re-cook determinism, and the rejected forms (`extends`, hooks on `of`).
        .{ .path = "tests/scene/prefab_cook_test.zig", .scene = true, .dedicated_step = "test-prefab-cook" },
        // `instance of` flattening at scene cook: override-free
        // instance == hand-authored equivalent (same archetype + bytes), both
        // override forms, N instances cook→load→ECS, single-entity boundary.
        .{ .path = "tests/scene/prefab_flatten_test.zig", .scene = true, .dedicated_step = "test-prefab-flatten" },
        // entity→entity cross-references: cook writes dead + a
        // side-table entry (by-name, two-phase), loader patches the slot to the
        // target handle; unset = dead; absent target = UnresolvedCrossRef at cook.
        .{ .path = "tests/scene/crossref_test.zig", .scene = true, .dedicated_step = "test-crossref" },
        // The `extensions:` clause from the parse to the executed hook: AST and
        // descriptors, the cook and its binary tables, `applyExtensions` and the
        // `on_attach` dispatch at load.
        .{ .path = "tests/scene/extensions_test.zig", .scene = true, .dedicated_step = "test-extensions" },
        // capstone: prefab instances + per-field override +
        // cross-ref + active extension in one scene, cook → load → ECS.
        .{ .path = "tests/scene/prefab_integration_test.zig", .scene = true, .dedicated_step = "test-prefab-integration" },
        // runtime loader `.scene.bin` → ECS: instantiate every
        // entity (component bytes verbatim), two-phase `on_spawned` (fires once
        // per entity, after all entities exist). `weld_core` only (no `.scene`
        // flag → no `weld_etch`); builds the image in-memory via the writer.
        .{ .path = "tests/scene/load_roundtrip_test.zig" },
        // resource `string` fields round-trip through the Tier-0 persistent
        // heap — interned at load into a refcounted block owned by the
        // resource's `StringSlot`. `weld_core` only.
        .{ .path = "tests/scene/load_resources_test.zig" },
        // common platform layer tests.
        .{ .path = "tests/platform/fs_vfs_test.zig" },
        .{ .path = "tests/platform/time_test.zig" },
        .{ .path = "tests/platform/threading_test.zig" },
        .{ .path = "tests/platform/dynamic_lib_test.zig" },
        // Win32 thread safety stress (Windows runner only).
        .{ .path = "tests/platform/win32_thread_safety_test.zig" },
        // Wayland thread safety stress (Linux runner only).
        .{ .path = "tests/platform/wayland_thread_safety_test.zig" },
        // Multi-monitor enumeration + current monitor + per-monitor DPI.
        .{ .path = "tests/platform/multi_monitor_test.zig" },
        // WindowEvent union surface validation.
        .{ .path = "tests/platform/window_events_test.zig" },
        // Input Tier 0 (event-driven path, runs on all OSes).
        .{ .path = "tests/platform/input_raw_state_test.zig" },
        .{ .path = "tests/platform/input_gamepad_test.zig" },
        // Audio Dummy stub test.
        .{ .path = "tests/audio/dummy_stub_test.zig", .audio = true },
        // GAL Null backend smoke + interface check (CI headless).
        .{ .path = "tests/render/gal_null_smoke.zig", .render = true },
        // GAL Vulkan backend offline init test (skip if Vulkan absent).
        .{ .path = "tests/render/gal_vulkan_offline.zig", .render = true },
        // Render graph topological sort + cycle detection.
        .{ .path = "tests/render/render_graph_topo.zig", .render = true },
        // Render graph auto-tracking barriers (write-after-read,
        // explicit mode skip).
        .{ .path = "tests/render/render_graph_barriers.zig", .render = true },
        // Instancing batcher (bucketing mesh+material, drawcalls
        // ≤ 100 for 100k entities).
        .{ .path = "tests/render/instancing_batcher.zig", .render = true },
        // Shader disk cache round-trip (hit/miss source change /
        // miss glslc version change).
        .{ .path = "tests/render/shader_cache.zig", .render = true },
        // smoke-test capture PSNR vs golden.
        // Skip if the platform has no Vulkan window backend or if the golden
        // has not yet been committed.
        // `dedicated_step` exposes `zig build test-render-capture` so
        // the CI runtime-smoke-test job can run only this test (the
        // generic `zig build test` pulls in the whole repo, including
        // unrelated tests with current ReleaseSafe issues — tracked as
        // housekeeping debt).
        .{ .path = "tests/render/capture.zig", .render = true, .dedicated_step = "test-render-capture" },
        // GAL capture helper surface coverage (encodePpm +
        // Device.captureFrameToPPM); §13 consumer test, runs on every platform.
        .{ .path = "tests/render/capture_helper.zig", .render = true },
        // direct PSNR gate reading the pre-produced
        // out/smoke_test.ppm with no rebuild and no triangle re-spawn.
        // std-only (no .render), so `zig build test-ppm-psnr` compiles in
        // seconds and replaces the rebuild-heavy `test-render-capture` in CI.
        .{ .path = "tests/render/ppm_psnr_compare.zig", .dedicated_step = "test-ppm-psnr" },
        // hot-reload filewatch latency < 200 ms.
        // Skip if glslc absent from PATH.
        .{ .path = "tests/render/shader_hot_reload.zig", .render = true },
        // vk_gen whitelist closure (variant filtering + closure
        // convergence under 20 iterations).
        .{ .path = "tests/vk_gen/whitelist_closure.zig" },
        // vk_gen *Raw variants emission (3 targets emitted, others
        // not emitted).
        .{ .path = "tests/vk_gen/raw_variants.zig" },
        // asset registry stale-handle (generation) acceptance.
        .{ .path = "tests/assets/handle_generation.zig", .asset_pipeline = true },
        // async loader + lifecycle (internal 5 s watchdog).
        .{ .path = "tests/assets/loader_async.zig", .asset_pipeline = true },
        // DEFLATE/zlib inflate known-vector acceptance.
        .{ .path = "tests/assets/deflate_vectors.zig", .asset_pipeline = true },
        // adler32 kernel known vectors + cross-variant correctness.
        .{ .path = "src/foundation/simd/tests/adler32_test.zig", .foundation = true },
        .{ .path = "src/foundation/simd/tests/correctness.zig", .foundation = true },
        // paeth_filter_decode kernel portable == reference.
        .{ .path = "src/foundation/simd/tests/paeth_test.zig", .foundation = true },
        // import → cook → load round-trips + cache differential.
        .{ .path = "tests/assets/png_roundtrip.zig", .asset_pipeline = true },
        .{ .path = "tests/assets/gltf_static_roundtrip.zig", .asset_pipeline = true },
        .{ .path = "tests/assets/wav_roundtrip.zig", .asset_pipeline = true },
        .{ .path = "tests/assets/cache_diff.zig", .asset_pipeline = true },
    };
    // The shared fail-fast watchdog for in-process concurrency tests. It covers
    // the `Scheduler.deinit`-join site that masked a windows-2025/ReleaseSafe
    // hang. Imported by tests as `@import("test_watchdog")` and compiled only
    // into the specs that use it.
    const watchdog_module = b.createModule(.{
        .root_source_file = b.path("tests/support/watchdog.zig"),
        .target = target,
        .optimize = optimize,
    });
    watchdog_module.addImport("weld_core", core_module);
    for (test_specs) |spec| {
        const t_mod = b.createModule(.{
            .root_source_file = b.path(spec.path),
            .target = target,
            .optimize = optimize,
        });
        t_mod.addImport("weld_core", core_module);
        t_mod.addImport("test_watchdog", watchdog_module);
        if (spec.wl_protocols) {
            t_mod.addImport("wl_protocols", wl_protocols_test_module);
        }
        if (spec.etch) {
            t_mod.addImport("weld_etch", etch_module);
            t_mod.addImport("corpus_facade", etch_corpus_module);
        }
        if (spec.etch_interp) {
            t_mod.addImport("weld_etch", etch_module);
            t_mod.addImport("corpus_facade", etch_interp_corpus_module);
            t_mod.addImport("diff_runner", etch_interp_driver_module);
            t_mod.addImport("runner_interp", etch_interp_runner_module);
        }
        if (spec.audio) {
            t_mod.addImport("weld_audio", audio_module);
        }
        if (spec.render) {
            t_mod.addImport("weld_render", render_module);
        }
        if (spec.asset_pipeline) {
            t_mod.addImport("weld_asset_pipeline", asset_pipeline_module);
        }
        if (spec.forge) {
            t_mod.addImport("weld_forge", forge_api_module);
            t_mod.addImport("forge_3d", forge_3d_module);
            t_mod.addImport("forge_sync", forge_sync_module);
            t_mod.addImport("forge_module", forge_module);
            t_mod.addImport("foundation", foundation_module);
            t_mod.addImport("weld_interfaces_physics", interfaces_physics_module);
        }
        if (spec.foundation) {
            t_mod.addImport("foundation", foundation_module);
        }
        if (spec.scene) {
            t_mod.addImport("weld_etch", etch_module);
        }
        if (spec.etch_events) {
            t_mod.addImport("weld_etch", etch_module);
            t_mod.addImport("toy_service", toy_service_module);
        }
        if (spec.arena_slice) {
            t_mod.addImport("arena_slice", arena_slice_module);
        }
        if (spec.physics_service) {
            t_mod.addImport("weld_etch", etch_module);
            t_mod.addImport("forge_services", forge_services_module);
            t_mod.addImport("forge_sensor_events", forge_sensor_events_module);
            t_mod.addImport("forge_sync", forge_sync_module);
        }
        if (spec.bindgen_detch) {
            t_mod.addImport("weld_etch", etch_module);
            t_mod.addImport("emit_detch", emit_detch_module);
            t_mod.addImport("toy_service", toy_service_module);
            t_mod.addImport("forge_services", forge_services_module);
            t_mod.addImport("forge_sensor_events", forge_sensor_events_module);
        }
        const t = b.addTest(.{ .root_module = t_mod });
        const t_run = b.addRunArtifact(t);
        if (spec.needs_stub_plugins) {
            for (stub_install_steps) |s| t_run.step.dependOn(s);
        }
        test_step.dependOn(&t_run.step);
        if (spec.dedicated_step) |name| {
            const dedicated = b.step(name, "Run only this test (used by targeted CI gates)");
            dedicated.dependOn(&t_run.step);
        }
    }

    // `zig build test-stress` builds and runs ONLY the
    // scheduler-livelock stress test. It is deliberately OUT of `test_step` and
    // must STAY out: the 100× stress-signal loop is a local validation tool, not
    // a routine CI test. Adding it to `test_step` also reddens `dead-tests`,
    // whose exclusion for that file points at this declaration. Local
    // diagnostic only — exit code 2 from the test process signals
    // SchedulerLivelock watchdog fired (5 s timeout).
    {
        const stress_mod = b.createModule(.{
            .root_source_file = b.path("tests/ecs/no_alloc_steady_state_stress.zig"),
            .target = target,
            .optimize = optimize,
        });
        stress_mod.addImport("weld_core", core_module);
        // the stress spec is created outside the `test_specs` loop, so it
        // does not get `test_watchdog` automatically — wire it explicitly for
        // the global teardown watchdog it now arms.
        stress_mod.addImport("test_watchdog", watchdog_module);
        const stress_test = b.addTest(.{ .root_module = stress_mod });
        const stress_test_run = b.addRunArtifact(stress_test);
        const stress_step = b.step(
            "test-stress",
            "Run only the scheduler-livelock stress test",
        );
        stress_step.dependOn(&stress_test_run.step);
    }

    // ----------------------------- editor + runtime stub binaries -----
    //
    // Two binaries at the canonical locations per
    // `engine-directory-structure.md` §9.1, and NOT under `src/spike/`: these
    // stubs are where the real editor and runtime grow from.

    const runtime_module = b.createModule(.{
        .root_source_file = b.path("src/runtime/main.zig"),
        .target = target,
        .optimize = optimize,
        .link_libc = true,
    });
    runtime_module.addImport("weld_core", core_module);
    // the main thread installs the engine float environment
    // (`ARCH-031` rule 5) from its single definition under `foundation/math/`.
    runtime_module.addImport("foundation", foundation_module);
    const runtime_exe = b.addExecutable(.{
        .name = "weld-runtime",
        .root_module = runtime_module,
    });
    b.installArtifact(runtime_exe);
    const runtime_run = b.addRunArtifact(runtime_exe);
    runtime_run.step.dependOn(b.getInstallStep());
    if (b.args) |args| runtime_run.addArgs(args);
    const runtime_step = b.step(
        "run-runtime-stub",
        "Run the runtime stub directly (requires --socket=… --shm=… argv)",
    );
    runtime_step.dependOn(&runtime_run.step);

    const editor_module = b.createModule(.{
        .root_source_file = b.path("src/editor/main.zig"),
        .target = target,
        .optimize = optimize,
        .link_libc = true,
    });
    editor_module.addImport("weld_core", core_module);
    // same as the runtime: the main thread is not born of a spawn.
    editor_module.addImport("foundation", foundation_module);
    // The viewport blit pipeline embeds pre-compiled SPIR-V via the
    // shared `shaders` facade — the same module the windowing spike uses.
    editor_module.addImport("shaders", shaders_module);
    // the viewport blit (vk_blit.zig) renders through the public
    // GAL (gal.Device) instead of raw Vulkan.
    editor_module.addImport("weld_render", render_module);
    const editor_exe = b.addExecutable(.{
        .name = "weld-editor",
        .root_module = editor_module,
    });
    b.installArtifact(editor_exe);
    const editor_run = b.addRunArtifact(editor_exe);
    editor_run.step.dependOn(b.getInstallStep());
    if (b.args) |args| editor_run.addArgs(args);
    const editor_step = b.step(
        "run-editor-stub",
        "Run the editor stub alone (will spawn the runtime stub)",
    );
    editor_step.dependOn(&editor_run.step);

    // Full demo entry point — the editor spawns the runtime, handshake,
    // message exchange, viewport mire visible for a 60 s window, graceful
    // shutdown.
    //
    // Any editor flag passes through `--`, e.g.
    //   zig build run-ipc-demo -- --frames=3600
    // With no `--` args the step supplies `--frames=3600` itself, so the
    // canonical demo is the 60 s one whether or not the caller says so.
    const ipc_demo_run = b.addRunArtifact(editor_exe);
    ipc_demo_run.step.dependOn(b.getInstallStep());
    if (b.args) |args| {
        ipc_demo_run.addArgs(args);
    } else {
        ipc_demo_run.addArg("--frames=3600");
    }
    const ipc_demo_step = b.step(
        "run-ipc-demo",
        "Run the editor↔runtime demo (window + Vulkan blit, default 60 s; override with `-- --frames=N`)",
    );
    ipc_demo_step.dependOn(&ipc_demo_run.step);

    // ------------------------------------------------ IPC tests --------
    //
    // Each IPC test is its own exe, and putting several back into one would be
    // wrong: a deadlock in one case stalls its whole exe, and there is no
    // bounded receive in Tier 0 IPC to cut it short, so a shared exe takes the
    // rest of `zig build test` down with it. The `test-ipc` step runs only the
    // IPC tests for fast iteration; the main `test` step also dependsOn each of
    // them so CI keeps a single entry point.
    const test_ipc_step = b.step("test-ipc", "Run the IPC tests");
    const ipc_test_paths = [_][]const u8{
        "tests/ipc/framing.zig",
        "tests/ipc/schema_hash.zig",
        "tests/ipc/transport.zig",
        // `shm` and `shm_viewport` are split into one-test-per-binary
        // under `tests/ipc/{shm,viewport}_cases/` because the macOS BSD
        // shm namespace caps a process at ONE successful
        // `shm_open(O_CREAT) → shm_open(O_RDWR)` sequence; running two
        // such tests in the same exe makes the second EACCES. One exe
        // per test sidesteps the quirk and gives real macOS coverage.
        "tests/ipc/shm.zig",
        "tests/ipc/shm_cases/round_trip.zig",
        "tests/ipc/shm_cases/attacher_writes.zig",
        "tests/ipc/viewport_cases/two_slots.zig",
        "tests/ipc/viewport_cases/wrong_width.zig",
        "tests/ipc/viewport_cases/no_tearing_1000_frames.zig",
        "tests/ipc/fd_passing.zig",
        "tests/ipc/handoff_fd.zig",
        "tests/ipc/catalogue.zig",
        "tests/ipc/process.zig",
        "tests/ipc/handshake.zig",
        "tests/ipc/crash_recovery.zig",
        "tests/ipc/fuzz_short.zig",
    };
    for (ipc_test_paths) |p| {
        const t_mod = b.createModule(.{
            .root_source_file = b.path(p),
            .target = target,
            .optimize = optimize,
            // The IPC tests bind directly to libc primitives (socket,
            // shm_open, pipe, unlink, setsockopt) alongside the
            // `weld_core` re-exports. `weld_core` itself links libc
            // but the test module needs the link flag too — Zig 0.16
            // does not propagate `link_libc` across module imports
            // for the consumer's own `extern "c"` declarations.
            .link_libc = true,
        });
        t_mod.addImport("weld_core", core_module);
        const t = b.addTest(.{ .root_module = t_mod });
        const run_t = b.addRunArtifact(t);
        // `tests/ipc/crash_recovery.zig` and `tests/ipc/catalogue.zig`
        // spawn `zig-out/bin/weld-runtime` to exercise the editor↔runtime
        // contract end-to-end (the catalogue handlers). The
        // path is relative to the project root which is the cwd when
        // `zig build test` dispatches the test binary; the runtime exe must
        // already be installed for `posix_spawnp` to find it. Bare
        // `b.addRunArtifact(t).step.dependOn(b.getInstallStep())` would gate
        // the test on every install step (including `etch_cook`), so we
        // wire the dependency narrowly to the runtime install step alone.
        if (std.mem.eql(u8, p, "tests/ipc/crash_recovery.zig") or
            std.mem.eql(u8, p, "tests/ipc/catalogue.zig"))
        {
            run_t.step.dependOn(&b.addInstallArtifact(runtime_exe, .{}).step);
        }
        test_step.dependOn(&run_t.step);
        test_ipc_step.dependOn(&run_t.step);
    }

    // ----------------------------------------------- IPC RTT bench -----

    const ipc_rtt_module = b.createModule(.{
        .root_source_file = b.path("bench/ipc_rtt.zig"),
        .target = target,
        .optimize = optimize,
        .link_libc = true,
    });
    ipc_rtt_module.addImport("weld_core", core_module);
    const ipc_rtt_exe = b.addExecutable(.{
        .name = "ipc-rtt-bench",
        .root_module = ipc_rtt_module,
    });
    b.installArtifact(ipc_rtt_exe);
    const ipc_rtt_run = b.addRunArtifact(ipc_rtt_exe);
    ipc_rtt_run.step.dependOn(b.getInstallStep());
    if (b.args) |args| ipc_rtt_run.addArgs(args);
    const ipc_rtt_step = b.step(
        "bench-ipc-rtt",
        "Run the IPC RTT bench (N=10_000 Echo round-trips, writes bench/results/ipc_rtt.md)",
    );
    ipc_rtt_step.dependOn(&ipc_rtt_run.step);

    // ----------------------------------------- 1 h fuzz harness --------

    const fuzz_1h_module = b.createModule(.{
        .root_source_file = b.path("tests/ipc/fuzz_1h.zig"),
        .target = target,
        .optimize = optimize,
        .link_libc = true,
    });
    fuzz_1h_module.addImport("weld_core", core_module);
    const fuzz_1h_exe = b.addExecutable(.{
        .name = "ipc-fuzz-1h",
        .root_module = fuzz_1h_module,
    });
    b.installArtifact(fuzz_1h_exe);
    const fuzz_1h_run = b.addRunArtifact(fuzz_1h_exe);
    fuzz_1h_run.step.dependOn(b.getInstallStep());
    // Forward `-- <args>` so the duration can be overridden for a local
    // smoke run, e.g. `zig build test-ipc-fuzz-1h -- --duration-ms=3000`.
    // The nightly cron runs it with no args (1 h default).
    if (b.args) |forwarded| fuzz_1h_run.addArgs(forwarded);
    const fuzz_1h_step = b.step(
        "test-ipc-fuzz-1h",
        "Run the IPC fuzz harness over the full catalogue (1 h default; nightly CI). Override: -- --duration-ms=N",
    );
    fuzz_1h_step.dependOn(&fuzz_1h_run.step);

    // ----------------------------------------------------- ECS bench step --
    //
    // `bench/ecs_benchmark.zig` carries the non-regression case and the
    // C0.1 1 M × 4 archetypes × 10 systems case.
    const bench_module = b.createModule(.{
        .root_source_file = b.path("bench/ecs_benchmark.zig"),
        .target = target,
        .optimize = optimize,
    });
    bench_module.addImport("weld_core", core_module);
    const bench_exe = b.addExecutable(.{
        .name = "ecs-benchmark",
        .root_module = bench_module,
    });
    b.installArtifact(bench_exe);

    const bench_run = b.addRunArtifact(bench_exe);
    bench_run.step.dependOn(b.getInstallStep());
    if (b.args) |args| bench_run.addArgs(args);
    const bench_step = b.step(
        "bench-ecs",
        "Run the ECS benchmark (non-regression case; pass `-- --smoke` for a CI sanity run)",
    );
    bench_step.dependOn(&bench_run.step);

    // ------------------------------- ECS hybrid-storage crossover bench --
    //
    // Table vs SparseSet per-tick cost over (population fraction, churn rate),
    // swept one parameter at a time from a declared base over payload size,
    // query member count, archetype spread and worker count. TWO COLUMNS per
    // cell — first occurrence and steady state, never averaged — each with its
    // allocation count. REPORTED, NOT GATED, and permanently: the owning spec
    // (`engine-ecs-internals.md` §2) refuses to engrave a threshold and names
    // this bench as what produces one instead, so a pass threshold here would
    // grade an implementation against a number the bench exists to produce.
    // Writes `bench/results/ecs_hybrid_crossover.md`. Pass `-- --smoke` for a
    // one-cell-per-configuration CI run.
    const hybrid_bench_module = b.createModule(.{
        .root_source_file = b.path("bench/ecs_hybrid_crossover.zig"),
        .target = target,
        .optimize = optimize,
    });
    hybrid_bench_module.addImport("weld_core", core_module);
    const hybrid_bench_exe = b.addExecutable(.{
        .name = "ecs-hybrid-crossover-bench",
        .root_module = hybrid_bench_module,
    });
    b.installArtifact(hybrid_bench_exe);
    const hybrid_bench_run = b.addRunArtifact(hybrid_bench_exe);
    hybrid_bench_run.step.dependOn(b.getInstallStep());
    if (b.args) |args| hybrid_bench_run.addArgs(args);
    const hybrid_bench_step = b.step(
        "bench-ecs-hybrid",
        "Run the ECS hybrid-storage crossover bench (reported, not gated; writes bench/results/ecs_hybrid_crossover.md)",
    );
    hybrid_bench_step.dependOn(&hybrid_bench_run.step);

    // ----------------------------------- driver-election cost + flip rate --
    //
    // Two tracks: the cost of ONE `QueryPlan.elect` by with-set shape over a
    // swept archetype count, and the flip rate per tick under the crossover
    // bench's churn values — doubled with a population-MOVING churn, because the
    // crossover's own churn leaves both populations unchanged by construction
    // and therefore cannot flip a cardinality election at all. REPORTED, NOT
    // GATED, on the same grounds as its sibling: the owning spec refuses to
    // engrave a threshold and names a bench as what produces figures instead.
    // Writes `bench/results/ecs_election.md`. Pass `-- --smoke` for a
    // one-archetype-count CI run.
    const election_bench_module = b.createModule(.{
        .root_source_file = b.path("bench/ecs_election.zig"),
        .target = target,
        .optimize = optimize,
    });
    election_bench_module.addImport("weld_core", core_module);
    const election_bench_exe = b.addExecutable(.{
        .name = "ecs-election-bench",
        .root_module = election_bench_module,
    });
    b.installArtifact(election_bench_exe);
    const election_bench_run = b.addRunArtifact(election_bench_exe);
    election_bench_run.step.dependOn(b.getInstallStep());
    if (b.args) |args| election_bench_run.addArgs(args);
    const election_bench_step = b.step(
        "bench-ecs-election",
        "Run the driver-election bench (reported, not gated; writes bench/results/ecs_election.md)",
    );
    election_bench_step.dependOn(&election_bench_run.step);

    // ------------------------------ forge narrowphase fast-path bench --
    //
    // Per-pair dispatched `collideOrdered` vs the generic GJK/EPA oracle
    // `collideOrderedGeneric`, same pose set, contact + separated, checksum
    // anti-DCE. Writes `bench/results/forge_narrowphase.md`. ReleaseFast for the
    // absolute ns; the dispatched/generic ratio is meaningful in any mode.
    const forge_np_bench_module = b.createModule(.{
        .root_source_file = b.path("bench/forge_narrowphase.zig"),
        .target = target,
        .optimize = optimize,
        .link_libc = true,
    });
    forge_np_bench_module.addImport("forge_3d", forge_3d_module);
    const forge_np_bench_exe = b.addExecutable(.{
        .name = "forge-narrowphase-bench",
        .root_module = forge_np_bench_module,
    });
    b.installArtifact(forge_np_bench_exe);
    const forge_np_bench_run = b.addRunArtifact(forge_np_bench_exe);
    forge_np_bench_run.step.dependOn(b.getInstallStep());
    if (b.args) |args| forge_np_bench_run.addArgs(args);
    const forge_np_bench_step = b.step(
        "bench-forge-narrowphase",
        "Run the forge narrowphase fast-path bench (dispatched vs generic per pair, writes bench/results/forge_narrowphase.md)",
    );
    forge_np_bench_step.dependOn(&forge_np_bench_run.step);

    // ------------------------------------- forge raycast bench --------
    //
    // Closest / any / all raycast throughput over a 10 000-body STATIC scene,
    // plus a short-bound variant. Writes `bench/results/forge_3d_raycast.md`.
    // REPORTED, not gated — no envelope is pre-registered (bench header).
    const forge_ray_bench_module = b.createModule(.{
        .root_source_file = b.path("bench/forge_3d_raycast.zig"),
        .target = target,
        .optimize = optimize,
        .link_libc = true,
    });
    forge_ray_bench_module.addImport("forge_3d", forge_3d_module);
    forge_ray_bench_module.addImport("weld_forge", forge_api_module);
    const forge_ray_bench_exe = b.addExecutable(.{
        .name = "forge-raycast-bench",
        .root_module = forge_ray_bench_module,
    });
    b.installArtifact(forge_ray_bench_exe);
    const forge_ray_bench_run = b.addRunArtifact(forge_ray_bench_exe);
    forge_ray_bench_run.step.dependOn(b.getInstallStep());
    if (b.args) |args| forge_ray_bench_run.addArgs(args);
    const forge_ray_bench_step = b.step(
        "bench-forge-raycast",
        "Run the forge raycast throughput bench (closest/any/all over 10k static bodies, writes bench/results/forge_3d_raycast.md)",
    );
    forge_ray_bench_step.dependOn(&forge_ray_bench_run.step);

    // --------------------------------- C1.1 physics integration bench --------
    //
    // The instrument `engine-phase-1-criteria.md` C1.1 names and which did not exist before
    // the FULL `step()` at 1 000 dynamic + 10 000 static bodies, 60 Hz. TWO GATED
    // targets — frame time and zero allocation in steady state — so this step FAILS rather
    // than reports. The retention shape is reported beside them, at two sizes.
    const forge_integration_module = b.createModule(.{
        .root_source_file = b.path("bench/physics_forge_3d_integration.zig"),
        .target = target,
        .optimize = optimize,
        .link_libc = true,
    });
    forge_integration_module.addImport("forge_3d", forge_3d_module);
    forge_integration_module.addImport("weld_forge", forge_api_module);
    const forge_integration_exe = b.addExecutable(.{
        .name = "forge-integration-bench",
        .root_module = forge_integration_module,
    });
    b.installArtifact(forge_integration_exe);
    const forge_integration_run = b.addRunArtifact(forge_integration_exe);
    forge_integration_run.step.dependOn(b.getInstallStep());
    if (b.args) |args| forge_integration_run.addArgs(args);
    const forge_integration_step = b.step(
        "bench-physics-integration",
        "Run the C1.1 physics integration bench (full step() at 1k dynamic + 10k static, 60 Hz; frame time and steady-state zero-alloc are GATED)",
    );
    forge_integration_step.dependOn(&forge_integration_run.step);

    // ---------------------------------- forge shapecast bench --------
    //
    // Sphere / box / capsule casts and shape overlaps over the SAME 10 000-body
    // static scene as the raycast bench, plus a point-cast / raycast pair that
    // isolates the GJK march against the analytic ray kernels. Writes
    // `bench/results/forge_3d_shapecast.md`. REPORTED, not gated — no envelope is
    // pre-registered (bench header).
    const forge_cast_bench_module = b.createModule(.{
        .root_source_file = b.path("bench/forge_3d_shapecast.zig"),
        .target = target,
        .optimize = optimize,
        .link_libc = true,
    });
    forge_cast_bench_module.addImport("forge_3d", forge_3d_module);
    forge_cast_bench_module.addImport("weld_forge", forge_api_module);
    const forge_cast_bench_exe = b.addExecutable(.{
        .name = "forge-shapecast-bench",
        .root_module = forge_cast_bench_module,
    });
    b.installArtifact(forge_cast_bench_exe);
    const forge_cast_bench_run = b.addRunArtifact(forge_cast_bench_exe);
    forge_cast_bench_run.step.dependOn(b.getInstallStep());
    if (b.args) |args| forge_cast_bench_run.addArgs(args);
    const forge_cast_bench_step = b.step(
        "bench-forge-shapecast",
        "Run the forge shapecast/overlap throughput bench (10k static bodies, writes bench/results/forge_3d_shapecast.md)",
    );
    forge_cast_bench_step.dependOn(&forge_cast_bench_run.step);

    // ---------------------------------- forge mesh bench -----------
    //
    // Build time and traversal time against triangle count, at three sizes, PLUS the
    // `worldAabb` O(V) pass on the `aabbOverlapsBody` path measured against the per-body
    // cache that would replace it. Writes `bench/results/forge_3d_mesh.md`. The first
    // two rows are REPORTED, not gated — no envelope is pre-registered; the third is a
    // DECISION taken on its own figures, and the bench header carries which is which.
    const forge_mesh_bench_module = b.createModule(.{
        .root_source_file = b.path("bench/forge_3d_mesh.zig"),
        .target = target,
        .optimize = optimize,
        .link_libc = true,
    });
    forge_mesh_bench_module.addImport("forge_3d", forge_3d_module);
    forge_mesh_bench_module.addImport("weld_forge", forge_api_module);
    const forge_mesh_bench_exe = b.addExecutable(.{
        .name = "forge-mesh-bench",
        .root_module = forge_mesh_bench_module,
    });
    b.installArtifact(forge_mesh_bench_exe);
    const forge_mesh_bench_run = b.addRunArtifact(forge_mesh_bench_exe);
    forge_mesh_bench_run.step.dependOn(b.getInstallStep());
    if (b.args) |args| forge_mesh_bench_run.addArgs(args);
    const forge_mesh_bench_step = b.step(
        "bench-forge-mesh",
        "Run the forge mesh bench (build + traversal against triangle count, writes bench/results/forge_3d_mesh.md)",
    );
    forge_mesh_bench_step.dependOn(&forge_mesh_bench_run.step);

    // -------------------------------- forge character controller bench --
    //
    // `moveCharacter` on a plane / stairs / a wall / a triangle mesh, plus
    // `resizeCharacter`, INTERLEAVED across reps. Writes
    // `bench/results/forge_3d_character.md`. REPORTED, not gated — no envelope is
    // pre-registered (bench header).
    const forge_char_bench_module = b.createModule(.{
        .root_source_file = b.path("bench/forge_3d_character.zig"),
        .target = target,
        .optimize = optimize,
        .link_libc = true,
    });
    forge_char_bench_module.addImport("forge_3d", forge_3d_module);
    forge_char_bench_module.addImport("weld_forge", forge_api_module);
    const forge_char_bench_exe = b.addExecutable(.{
        .name = "forge-character-bench",
        .root_module = forge_char_bench_module,
    });
    b.installArtifact(forge_char_bench_exe);
    const forge_char_bench_run = b.addRunArtifact(forge_char_bench_exe);
    forge_char_bench_run.step.dependOn(b.getInstallStep());
    if (b.args) |args| forge_char_bench_run.addArgs(args);
    const forge_char_bench_step = b.step(
        "bench-forge-character",
        "Run the forge character controller bench (five paths interleaved, writes bench/results/forge_3d_character.md)",
    );
    forge_char_bench_step.dependOn(&forge_char_bench_run.step);

    // sensor pass bench: the cost sleep does NOT economise, plus a floor row
    // and a many-triggers row (reported, not gated).
    const forge_sensor_bench_module = b.createModule(.{
        .root_source_file = b.path("bench/forge_3d_sensor.zig"),
        .target = target,
        .optimize = optimize,
        .link_libc = true,
    });
    forge_sensor_bench_module.addImport("forge_3d", forge_3d_module);
    forge_sensor_bench_module.addImport("weld_forge", forge_api_module);
    const forge_sensor_bench_exe = b.addExecutable(.{
        .name = "forge-sensor-bench",
        .root_module = forge_sensor_bench_module,
    });
    b.installArtifact(forge_sensor_bench_exe);
    const forge_sensor_bench_run = b.addRunArtifact(forge_sensor_bench_exe);
    forge_sensor_bench_run.step.dependOn(b.getInstallStep());
    if (b.args) |args| forge_sensor_bench_run.addArgs(args);
    const forge_sensor_bench_step = b.step(
        "bench-forge-sensor",
        "Run the forge sensor pass bench (three rows interleaved, writes bench/results/forge_3d_sensor.md)",
    );
    forge_sensor_bench_step.dependOn(&forge_sensor_bench_run.step);

    // -------------------------------------- scene loader bench --------
    //
    // `loadFromBytes` on a ~10k-entity image synthesized in-bench via the
    // writer. Measurement only (median), not a gate — see the bench header.
    const scene_load_bench_module = b.createModule(.{
        .root_source_file = b.path("bench/scene_load_bench.zig"),
        .target = target,
        .optimize = optimize,
    });
    scene_load_bench_module.addImport("weld_core", core_module);
    const scene_load_bench_exe = b.addExecutable(.{
        .name = "scene-load-bench",
        .root_module = scene_load_bench_module,
    });
    b.installArtifact(scene_load_bench_exe);

    const scene_load_bench_run = b.addRunArtifact(scene_load_bench_exe);
    scene_load_bench_run.step.dependOn(b.getInstallStep());
    if (b.args) |args| scene_load_bench_run.addArgs(args);
    const scene_load_bench_step = b.step(
        "bench-scene-load",
        "Run the scene loader bench (~10k entities, reports median)",
    );
    scene_load_bench_step.dependOn(&scene_load_bench_run.step);

    // ------------------------------------- render instancing bench ------
    //
    // CPU-side batcher harness: 100k entities × 100 distinct (mesh, material)
    // pairs, drawcall gate <= 100. GPU-side metrics live in the
    // runtime-smoke-test CI step.
    const render_bench_module = b.createModule(.{
        .root_source_file = b.path("bench/render_instancing.zig"),
        .target = target,
        .optimize = optimize,
        .link_libc = true,
    });
    render_bench_module.addImport("weld_core", core_module);
    render_bench_module.addImport("weld_render", render_module);
    const render_bench_exe = b.addExecutable(.{
        .name = "render-instancing-bench",
        .root_module = render_bench_module,
    });
    b.installArtifact(render_bench_exe);

    const render_bench_run = b.addRunArtifact(render_bench_exe);
    render_bench_run.step.dependOn(b.getInstallStep());
    if (b.args) |args| render_bench_run.addArgs(args);
    const render_bench_step = b.step(
        "bench-render-instancing",
        "Run the render instancing bench (writes bench/out/render_instancing_<os>.md)",
    );
    render_bench_step.dependOn(&render_bench_run.step);

    // ------------------------------------------- adler32 baseline bench --
    //
    // Inaugural foundation/simd kernel throughput baseline. No parity target
    // (cold path — runs once at cook time). `zig build bench-adler32`.
    const adler32_bench_module = b.createModule(.{
        .root_source_file = b.path("src/foundation/simd/bench/adler32_bench.zig"),
        .target = target,
        .optimize = optimize,
    });
    adler32_bench_module.addImport("foundation", foundation_module);
    const adler32_bench_exe = b.addExecutable(.{
        .name = "adler32-bench",
        .root_module = adler32_bench_module,
    });
    b.installArtifact(adler32_bench_exe);
    const adler32_bench_run = b.addRunArtifact(adler32_bench_exe);
    adler32_bench_run.step.dependOn(b.getInstallStep());
    if (b.args) |args| adler32_bench_run.addArgs(args);
    const adler32_bench_step = b.step(
        "bench-adler32",
        "Run the adler32 throughput baseline (pass `-- --smoke` for a CI sanity run)",
    );
    adler32_bench_step.dependOn(&adler32_bench_run.step);

    // ------------------------------------------- paeth baseline bench ----
    //
    // Second foundation/simd kernel throughput baseline. No parity target.
    const paeth_bench_module = b.createModule(.{
        .root_source_file = b.path("src/foundation/simd/bench/paeth_bench.zig"),
        .target = target,
        .optimize = optimize,
    });
    paeth_bench_module.addImport("foundation", foundation_module);
    const paeth_bench_exe = b.addExecutable(.{
        .name = "paeth-bench",
        .root_module = paeth_bench_module,
    });
    b.installArtifact(paeth_bench_exe);
    const paeth_bench_run = b.addRunArtifact(paeth_bench_exe);
    paeth_bench_run.step.dependOn(b.getInstallStep());
    if (b.args) |args| paeth_bench_run.addArgs(args);
    const paeth_bench_step = b.step(
        "bench-paeth",
        "Run the paeth_filter_decode throughput baseline (pass `-- --smoke` for a CI sanity run)",
    );
    paeth_bench_step.dependOn(&paeth_bench_run.step);

    // ------------------------------------- asset cooking-cache bench -----
    //
    // Cold-cook-vs-warm-hit time differential. Host- and load-dependent, so
    // it lives here (archived, non-blocking, measured under the opposable
    // protocol) and NOT in `zig build test` — the correctness half (miss →
    // hit transition + byte-identity) is the deterministic gate
    // `tests/assets/cache_diff.zig`. `zig build bench-asset-cache`.
    const asset_cache_bench_module = b.createModule(.{
        .root_source_file = b.path("bench/asset_cache.zig"),
        .target = target,
        .optimize = optimize,
    });
    asset_cache_bench_module.addImport("weld_asset_pipeline", asset_pipeline_module);
    const asset_cache_bench_exe = b.addExecutable(.{
        .name = "asset-cache-bench",
        .root_module = asset_cache_bench_module,
    });
    b.installArtifact(asset_cache_bench_exe);
    const asset_cache_bench_run = b.addRunArtifact(asset_cache_bench_exe);
    asset_cache_bench_run.step.dependOn(b.getInstallStep());
    if (b.args) |args| asset_cache_bench_run.addArgs(args);
    const asset_cache_bench_step = b.step(
        "bench-asset-cache",
        "Run the cooking-cache cold-vs-hit differential (writes bench/out/asset_cache_<os>.md; pass `-- --smoke` for a CI sanity run)",
    );
    asset_cache_bench_step.dependOn(&asset_cache_bench_run.step);

    // ----------------------------------- thin offline asset cook demo ----
    //
    // `zig build cook-demo` cooks the three fixtures end-to-end through
    // the cache and logs hits.
    const asset_cook_module = b.createModule(.{
        .root_source_file = b.path("tools/asset_cook/main.zig"),
        .target = target,
        .optimize = optimize,
    });
    asset_cook_module.addImport("weld_asset_pipeline", asset_pipeline_module);
    const asset_cook_exe = b.addExecutable(.{
        .name = "asset_cook",
        .root_module = asset_cook_module,
    });
    b.installArtifact(asset_cook_exe);
    const asset_cook_run = b.addRunArtifact(asset_cook_exe);
    if (b.args) |args| asset_cook_run.addArgs(args);
    const asset_cook_step = b.step(
        "cook-demo",
        "Cook the three fixtures end-to-end (import → cook → cache; logs hits)",
    );
    asset_cook_step.dependOn(&asset_cook_run.step);

    // `zig build scene-cook -- --output <out.scene.bin> <in.scene.etch>`
    // cooks one `.scene.etch` into the runtime `.scene.bin`, in-process via
    // `weld_etch.scene_cook` + `weld_core.scene.writer`. Mirrors the asset_cook
    // user-facing CLI step (built on the user target, args forwarded via `--`).
    const scene_cook_module = b.createModule(.{
        .root_source_file = b.path("tools/scene_cook/main.zig"),
        .target = target,
        .optimize = optimize,
    });
    scene_cook_module.addImport("weld_etch", etch_module);
    scene_cook_module.addImport("weld_core", core_module);
    const scene_cook_exe = b.addExecutable(.{
        .name = "scene_cook",
        .root_module = scene_cook_module,
    });
    b.installArtifact(scene_cook_exe);
    const scene_cook_run = b.addRunArtifact(scene_cook_exe);
    if (b.args) |args| scene_cook_run.addArgs(args);
    const scene_cook_step = b.step(
        "scene-cook",
        "Cook a .scene.etch into a .scene.bin (scene_cook --output <out> <in>)",
    );
    scene_cook_step.dependOn(&scene_cook_run.step);

    // -------------------------------------------- Fixture facade (demo) --

    // `@embedFile` cannot escape the package root of the module that
    // invokes it, so both the bench and the demo binary import this
    // tiny facade module that holds the fixture at its canonical path.
    const fixture_facade_module = b.createModule(.{
        .root_source_file = b.path("bench/fixture_facade.zig"),
        .target = target,
        .optimize = optimize,
    });

    // ------------------------------------------------- demo binary ------

    const demo_module = b.createModule(.{
        .root_source_file = b.path("src/demo_etch_interp.zig"),
        .target = target,
        .optimize = optimize,
    });
    demo_module.addImport("weld_core", core_module);
    demo_module.addImport("foundation", foundation_module);
    demo_module.addImport("weld_etch", etch_module);
    demo_module.addImport("fixture_facade", fixture_facade_module);
    const demo_exe = b.addExecutable(.{
        .name = "demo-etch-interp",
        .root_module = demo_module,
    });
    b.installArtifact(demo_exe);
    const demo_run = b.addRunArtifact(demo_exe);
    demo_run.step.dependOn(b.getInstallStep());
    if (b.args) |args| demo_run.addArgs(args);
    const demo_step = b.step(
        "run-demo-etch-interp",
        "Run the interpreter demo (1000 entities × 5 rules × 60 ticks)",
    );
    demo_step.dependOn(&demo_run.step);

    // -------------------------------------------- Etch interpreter bench --

    const interp_bench_module = b.createModule(.{
        .root_source_file = b.path("bench/etch_interp.zig"),
        .target = target,
        .optimize = optimize,
    });
    interp_bench_module.addImport("weld_core", core_module);
    interp_bench_module.addImport("weld_etch", etch_module);
    interp_bench_module.addImport("fixture_facade", fixture_facade_module);
    const interp_bench_exe = b.addExecutable(.{
        .name = "etch-interp-bench",
        .root_module = interp_bench_module,
    });
    b.installArtifact(interp_bench_exe);
    const interp_bench_run = b.addRunArtifact(interp_bench_exe);
    interp_bench_run.step.dependOn(b.getInstallStep());
    if (b.args) |args| interp_bench_run.addArgs(args);
    const interp_bench_step = b.step(
        "bench-etch-interp",
        "Run the interpreter bench (pass `-- --smoke` for a CI sanity run)",
    );
    interp_bench_step.dependOn(&interp_bench_run.step);

    // ---------------------------------------------------- Etch parse bench --

    const etch_bench_module = b.createModule(.{
        .root_source_file = b.path("bench/etch_parse.zig"),
        .target = target,
        .optimize = optimize,
    });
    etch_bench_module.addImport("weld_etch", etch_module);
    etch_bench_module.addImport("corpus_facade", etch_corpus_module);
    const etch_bench_exe = b.addExecutable(.{
        .name = "etch-parse-bench",
        .root_module = etch_bench_module,
    });
    b.installArtifact(etch_bench_exe);

    const etch_bench_run = b.addRunArtifact(etch_bench_exe);
    etch_bench_run.step.dependOn(b.getInstallStep());
    if (b.args) |args| etch_bench_run.addArgs(args);
    const etch_bench_step = b.step(
        "bench-etch",
        "Run the Etch parse bench (pass `-- --smoke` for a CI sanity run)",
    );
    etch_bench_step.dependOn(&etch_bench_run.step);

    // --------------------------------------- Etch → Zig codegen tool ---
    //
    // `tools/etch_cook` is a standalone CLI that runs the codegen on a
    // list of `.etch` programs and emits a single consolidated `.zig`
    // file. The build invokes it once per corpus (the differential test
    // programs, the synthetic 100-file bench fixture) and exposes the
    // result as a Zig module for downstream test / bench binaries.

    const etch_cook_module = b.createModule(.{
        .root_source_file = b.path("tools/etch_cook/main.zig"),
        .target = b.graph.host,
        // Use the user-selected optimize so `zig build bench-etch-compile
        // -Doptimize=ReleaseSafe` builds the cook tool in the same mode
        // as the bench harness — otherwise metric (a) is dominated by
        // Debug-mode parser/type-checker cost and the gate is unreachable.
        .optimize = optimize,
    });
    etch_cook_module.addImport("weld_etch", etch_module);
    etch_cook_module.addImport("weld_core", core_module);
    const etch_cook_exe = b.addExecutable(.{
        .name = "etch_cook",
        .root_module = etch_cook_module,
    });
    b.installArtifact(etch_cook_exe);

    // `etch_test` shim (thin CLI over `weld_etch.test_runner`) + the
    // `test-etch` acceptance step. The shim owns arg parsing + I/O; all logic is
    // in the library (same split as `etch_cook`).
    const etch_test_module = b.createModule(.{
        .root_source_file = b.path("tools/etch_test/main.zig"),
        .target = b.graph.host,
        .optimize = optimize,
    });
    etch_test_module.addImport("weld_etch", etch_module);
    etch_test_module.addImport("weld_core", core_module);
    const etch_test_exe = b.addExecutable(.{
        .name = "etch_test",
        .root_module = etch_test_module,
    });
    b.installArtifact(etch_test_exe);

    // The Zig acceptance driver (assertions over the `.etch` fixtures + the
    // diagnostic cases). Wired manually — not through `test_specs` — so the
    // `test-etch` step can depend on it directly AND it stays in `zig build test`.
    const etch_driver_module = b.createModule(.{
        .root_source_file = b.path("tests/etch/test_runner/driver_test.zig"),
        .target = target,
        .optimize = optimize,
    });
    etch_driver_module.addImport("weld_core", core_module);
    etch_driver_module.addImport("weld_etch", etch_module);
    const etch_driver_test = b.addTest(.{ .root_module = etch_driver_module });
    const etch_driver_run = b.addRunArtifact(etch_driver_test);
    test_step.dependOn(&etch_driver_run.step);

    const test_etch_step = b.step("test-etch", "Run the Etch test-runner acceptance corpus (driver + shim over the green fixtures)");
    test_etch_step.dependOn(&etch_driver_run.step);
    // Run the shim over the all-green fixtures in a SINGLE invocation (the shim
    // takes many files): prints the ✓ / skipped lines + per-file and total
    // aggregates (observable behavior), exits 0. One process → clean, un-
    // interleaved output. `failing.etch` is exercised by the driver (which
    // asserts the failure) + by hand, not here.
    const etch_shim_run = b.addRunArtifact(etch_test_exe);
    for ([_][]const u8{
        "tests/etch/test_runner/green.etch",
        "tests/etch/test_runner/only.etch",
        "tests/etch/test_runner/isolation.etch",
        "tests/etch/test_runner/world.etch",
        "tests/etch/test_runner/timing.etch",
    }) |fixture| {
        etch_shim_run.addFileArg(b.path(fixture));
    }
    etch_shim_run.stdio = .inherit; // show the ✓ lines during the build
    test_etch_step.dependOn(&etch_shim_run.step);

    // Cook the differential corpus programs into a single consolidated
    // `corpus_codegen.zig`, which the driver test imports under the
    // `corpus_codegen` module name. `codegen_corpus_build.zig` is the list.
    const cook_diff_run = b.addRunArtifact(etch_cook_exe);
    cook_diff_run.addArg("--output");
    const diff_codegen_path = cook_diff_run.addOutputFileArg("corpus_codegen.zig");
    for (codegen_corpus.programs) |p| {
        // `addPrefixedFileArg` content-tracks each `.etch` input in the Run
        // step's cache manifest — a raw `name=path` string arg
        // is hashed by its bytes only, so a source edit would not
        // invalidate the cached cook output.
        cook_diff_run.addPrefixedFileArg(b.fmt("{s}=", .{p.name}), b.path(p.etch_path));
    }

    const diff_codegen_module = b.createModule(.{
        .root_source_file = diff_codegen_path,
        .target = target,
        .optimize = optimize,
    });
    diff_codegen_module.addImport("weld_core", core_module);

    // Codegen-backed runner module — used by both the codegen diff test
    // and the synthetic bench (the latter compiles the cooked corpus
    // through `zig build` to measure compile-time wall-clock).
    const codegen_runner_module = b.createModule(.{
        .root_source_file = b.path("tests/etch_interp/runner_codegen.zig"),
        .target = target,
        .optimize = optimize,
    });
    codegen_runner_module.addImport("weld_core", core_module);
    codegen_runner_module.addImport("corpus_codegen", diff_codegen_module);

    // Build step that just executes the codegen diff binary.
    const codegen_diff_module = b.createModule(.{
        .root_source_file = b.path("tests/etch_interp/codegen_diff_test.zig"),
        .target = target,
        .optimize = optimize,
    });
    codegen_diff_module.addImport("weld_core", core_module);
    codegen_diff_module.addImport("weld_etch", etch_module);
    codegen_diff_module.addImport("corpus_facade", etch_interp_corpus_module);
    codegen_diff_module.addImport("diff_runner", etch_interp_driver_module);
    codegen_diff_module.addImport("runner_codegen", codegen_runner_module);
    const codegen_diff_test = b.addTest(.{ .root_module = codegen_diff_module });
    const codegen_diff_run = b.addRunArtifact(codegen_diff_test);
    test_step.dependOn(&codegen_diff_run.step);
    const codegen_diff_step = b.step(
        "test-codegen-diff",
        "Run the differential corpus through the Zig codegen runner",
    );
    codegen_diff_step.dependOn(&codegen_diff_run.step);

    // Level-B serialized-IR differential: interpreter-built
    // descriptors vs cooked emit-structure, byte-identical canonical dumps.
    const levelb_ir_diff_module = b.createModule(.{
        .root_source_file = b.path("tests/etch_interp/levelb_ir_diff_test.zig"),
        .target = target,
        .optimize = optimize,
    });
    levelb_ir_diff_module.addImport("weld_core", core_module);
    levelb_ir_diff_module.addImport("weld_etch", etch_module);
    levelb_ir_diff_module.addImport("corpus_codegen", diff_codegen_module);
    const levelb_ir_diff_test = b.addTest(.{ .root_module = levelb_ir_diff_module });
    const levelb_ir_diff_run = b.addRunArtifact(levelb_ir_diff_test);
    test_step.dependOn(&levelb_ir_diff_run.step);

    // Parity test: same corpus, runs interpreter + codegen back-to-back.
    const codegen_parity_module = b.createModule(.{
        .root_source_file = b.path("tests/etch_interp/codegen_parity_test.zig"),
        .target = target,
        .optimize = optimize,
    });
    codegen_parity_module.addImport("weld_core", core_module);
    codegen_parity_module.addImport("weld_etch", etch_module);
    codegen_parity_module.addImport("corpus_facade", etch_interp_corpus_module);
    codegen_parity_module.addImport("diff_runner", etch_interp_driver_module);
    codegen_parity_module.addImport("runner_interp", etch_interp_runner_module);
    codegen_parity_module.addImport("runner_codegen", codegen_runner_module);
    const codegen_parity_test = b.addTest(.{ .root_module = codegen_parity_module });
    const codegen_parity_run = b.addRunArtifact(codegen_parity_test);
    test_step.dependOn(&codegen_parity_run.step);
    // `zig build test-ref500-codegen` runs the interp↔codegen parity
    // suite, which includes program 84 (the full-grammar TOTAL codegen
    // integration: cook whole-file + Sema-compile + Level-A byte-exact).
    const ref500_codegen_step = b.step(
        "test-ref500-codegen",
        "Run the interp↔codegen parity suite (incl. the full-grammar codegen integration, program 84)",
    );
    ref500_codegen_step.dependOn(&codegen_parity_run.step);

    // ----------------------------------------- etch_synth tool ------------

    const etch_synth_module = b.createModule(.{
        .root_source_file = b.path("tools/etch_synth/main.zig"),
        .target = b.graph.host,
        .optimize = .Debug,
    });
    const etch_synth_exe = b.addExecutable(.{
        .name = "etch_synth",
        .root_module = etch_synth_module,
    });
    const etch_synth_run = b.addRunArtifact(etch_synth_exe);
    etch_synth_run.has_side_effects = true;
    if (b.args) |args| etch_synth_run.addArgs(args);
    const etch_synth_step = b.step(
        "synth-100",
        "Regenerate bench/fixtures/synth_100/scripts from the deterministic seed",
    );
    etch_synth_step.dependOn(&etch_synth_run.step);

    // -------------------------------- demo binary (run-demo-etch-codegen) --

    const cook_demo_run = b.addRunArtifact(etch_cook_exe);
    cook_demo_run.addArg("--output");
    const demo_codegen_path = cook_demo_run.addOutputFileArg("cooked_demo.zig");
    cook_demo_run.addPrefixedFileArg("demo=", b.path("bench/fixtures/demo_5_rules_codegen.etch"));

    const cooked_demo_module = b.createModule(.{
        .root_source_file = demo_codegen_path,
        .target = target,
        .optimize = optimize,
    });
    cooked_demo_module.addImport("weld_core", core_module);

    const demo_codegen_module = b.createModule(.{
        .root_source_file = b.path("src/demo_etch_codegen.zig"),
        .target = target,
        .optimize = optimize,
    });
    demo_codegen_module.addImport("weld_core", core_module);
    demo_codegen_module.addImport("foundation", foundation_module);
    demo_codegen_module.addImport("cooked_demo", cooked_demo_module);
    const demo_codegen_exe = b.addExecutable(.{
        .name = "demo-etch-codegen",
        .root_module = demo_codegen_module,
    });
    b.installArtifact(demo_codegen_exe);
    const demo_codegen_run = b.addRunArtifact(demo_codegen_exe);
    demo_codegen_run.step.dependOn(b.getInstallStep());
    if (b.args) |args| demo_codegen_run.addArgs(args);
    const demo_codegen_step = b.step(
        "run-demo-etch-codegen",
        "Run the codegen demo (cooks demo_5_rules_codegen.etch, runs 10 ticks)",
    );
    demo_codegen_step.dependOn(&demo_codegen_run.step);

    // ----------------------- vertical slice (run-vertical-slice) --
    // Headless slice: cook examples/vertical_slice/gameplay.etch (POD
    // components + 5 rules) → cooked module; the HOST (main.zig) spawns the 100
    // entities — the cooked module does not — and ticks the rules at a fixed
    // 60 Hz timestep. The *.scene.etch / *.prefab.etch are NOT cooked
    // here — they are authored content cross-file validated by the integration
    // test, not loaded — scene serialization is another milestone's.
    const cook_slice_run = b.addRunArtifact(etch_cook_exe);
    cook_slice_run.addArg("--output");
    const slice_codegen_path = cook_slice_run.addOutputFileArg("cooked_vertical_slice.zig");
    cook_slice_run.addPrefixedFileArg("gameplay=", b.path("examples/vertical_slice/gameplay.etch"));

    const cooked_slice_module = b.createModule(.{
        .root_source_file = slice_codegen_path,
        .target = target,
        .optimize = optimize,
    });
    cooked_slice_module.addImport("weld_core", core_module);

    // the slice gains a Vulkan forward renderer + a cooked
    // texture asset + input. The host module (main.zig) file-imports
    // sim.zig / render.zig / math.zig, so its named deps (core/render/assets/
    // cooked) cover all three files.
    const slice_module = b.createModule(.{
        .root_source_file = b.path("examples/vertical_slice/main.zig"),
        .target = target,
        .optimize = optimize,
    });
    slice_module.addImport("weld_core", core_module);
    slice_module.addImport("weld_render", render_module);
    slice_module.addImport("weld_asset_pipeline", asset_pipeline_module);
    slice_module.addImport("cooked_slice", cooked_slice_module);
    const slice_exe = b.addExecutable(.{
        .name = "vertical-slice",
        .root_module = slice_module,
    });
    b.installArtifact(slice_exe);

    // cook the slice's single source asset (PNG → .texture.bin) through
    // the real pipeline, installed to a stable path the runtime Loader
    // reads (zig-out/vertical-slice-assets/slice_albedo.texture.bin).
    const cook_assets_module = b.createModule(.{
        .root_source_file = b.path("examples/vertical_slice/cook_assets.zig"),
        .target = target,
        .optimize = optimize,
    });
    cook_assets_module.addImport("weld_asset_pipeline", asset_pipeline_module);
    const cook_assets_exe = b.addExecutable(.{
        .name = "cook-vertical-slice-assets",
        .root_module = cook_assets_module,
    });
    const cook_assets_run = b.addRunArtifact(cook_assets_exe);
    cook_assets_run.addFileArg(b.path("examples/vertical_slice/assets/slice_albedo.png"));
    const slice_albedo_bin = cook_assets_run.addOutputFileArg("slice_albedo.texture.bin");
    const install_slice_assets = b.addInstallFileWithDir(
        slice_albedo_bin,
        .{ .custom = "vertical-slice-assets" },
        "slice_albedo.texture.bin",
    );
    const cook_assets_step = b.step(
        "cook-vertical-slice-assets",
        "Cook the vertical slice's source asset (PNG → .texture.bin) through the asset pipeline",
    );
    cook_assets_step.dependOn(&install_slice_assets.step);

    const slice_run = b.addRunArtifact(slice_exe);
    slice_run.step.dependOn(b.getInstallStep());
    slice_run.step.dependOn(&install_slice_assets.step);
    if (b.args) |args| slice_run.addArgs(args);
    const slice_run_step = b.step(
        "run-vertical-slice",
        "Run the vertical slice (windowed render; --smoke-test / --headless)",
    );
    slice_run_step.dependOn(&slice_run.step);

    // Integration test: imports the slice module (sim + render via re-export) +
    // weld_etch (`validateProject`) + weld_asset_pipeline (in-memory asset
    // cook+load verify). composeNull exercises the render path cross-platform.
    const slice_test_module = b.createModule(.{
        .root_source_file = b.path("tests/integration/vertical_slice_test.zig"),
        .target = target,
        .optimize = optimize,
    });
    slice_test_module.addImport("weld_core", core_module);
    slice_test_module.addImport("weld_etch", etch_module);
    slice_test_module.addImport("weld_asset_pipeline", asset_pipeline_module);
    slice_test_module.addImport("slice", slice_module);
    const slice_test = b.addTest(.{ .root_module = slice_test_module });
    const slice_test_run = b.addRunArtifact(slice_test);
    test_step.dependOn(&slice_test_run.step);
    const slice_test_step = b.step(
        "test-vertical-slice",
        "Run the vertical slice integration test",
    );
    slice_test_step.dependOn(&slice_test_run.step);

    // ----------------------------- compile-time bench (3 metrics) -------

    const compile_bench_module = b.createModule(.{
        .root_source_file = b.path("bench/etch_compile.zig"),
        .target = target,
        .optimize = optimize,
    });
    // The bench consumes the consolidated cook IN-PROCESS through the
    // codegen library — no etch_cook
    // child process on the timed path.
    compile_bench_module.addImport("weld_etch", etch_module);
    const compile_bench_exe = b.addExecutable(.{
        .name = "etch-compile-bench",
        .root_module = compile_bench_module,
    });
    b.installArtifact(compile_bench_exe);
    const compile_bench_run = b.addRunArtifact(compile_bench_exe);
    if (b.args) |args| compile_bench_run.addArgs(args);
    const compile_bench_step = b.step(
        "bench-etch-compile",
        "Run the compile-time bench (cook + cold + incremental, N=10; pass `-- --smoke` for CI)",
    );
    compile_bench_step.dependOn(&compile_bench_run.step);

    // -------------------------------------------- bindgen (unified) --
    //
    // Unified bindgen system per `engine-c-bindings.md` §1. The two
    // adapters (`vk_xml`, `wayland_xml`) port the legacy
    // generators 1:1. Run explicitly via:
    //   - `zig build bindgen`                — regenerate every adapter
    //   - `zig build bindgen -- --target vulkan`  — only Vulkan
    //   - `zig build bindgen -- --target wayland` — only Wayland
    //   - `zig build bindgen-vk`             — back-compat single adapter
    //   - `zig build bindgen-wayland`        — back-compat single adapter
    //   - `zig build bindgen-verify`         — regenerate + empty-diff gate

    const vk_gen_module = b.createModule(.{
        .root_source_file = b.path("tools/bindgen/adapters/vk_xml.zig"),
        .target = b.graph.host,
        .optimize = .Debug,
    });
    const vk_gen_exe = b.addExecutable(.{
        .name = "vk_gen",
        .root_module = vk_gen_module,
    });
    const vk_gen_run = b.addRunArtifact(vk_gen_exe);
    vk_gen_run.has_side_effects = true;
    // Generator output is unformatted, so `bindgen-vk` produces an empty diff
    // only after `zig fmt` normalises identifier escapes (e.g. `@"undefined"` →
    // `undefined`) and trims trailing blank lines. Pipe through fmt in the same
    // step so the command is self-sufficient regardless of pre-commit hooks.
    const vk_gen_fmt = b.addSystemCommand(&.{ b.graph.zig_exe, "fmt", "src/core/platform/vk.zig" });
    vk_gen_fmt.step.dependOn(&vk_gen_run.step);
    const vk_gen_step = b.step("bindgen-vk", "Regenerate src/core/platform/vk.zig from vk.xml");
    vk_gen_step.dependOn(&vk_gen_fmt.step);

    // ----------------------------------------- wayland_gen (unified) --

    const wayland_gen_module = b.createModule(.{
        .root_source_file = b.path("tools/bindgen/adapters/wayland_xml.zig"),
        .target = b.graph.host,
        .optimize = .Debug,
    });
    const wayland_gen_exe = b.addExecutable(.{
        .name = "wayland_gen",
        .root_module = wayland_gen_module,
    });
    const wayland_gen_run = b.addRunArtifact(wayland_gen_exe);
    wayland_gen_run.has_side_effects = true;
    // Same fmt pass as vk_gen — see comment there.
    const wayland_gen_fmt = b.addSystemCommand(&.{
        b.graph.zig_exe,
        "fmt",
        "src/core/platform/window/wayland_protocols/core.zig",
        "src/core/platform/window/wayland_protocols/xdg_shell.zig",
        "src/core/platform/window/wayland_protocols/xdg_decoration.zig",
    });
    wayland_gen_fmt.step.dependOn(&wayland_gen_run.step);
    const wayland_gen_step = b.step(
        "bindgen-wayland",
        "Regenerate src/core/platform/window/wayland_protocols/*.zig from wayland-protocols XMLs",
    );
    wayland_gen_step.dependOn(&wayland_gen_fmt.step);

    // -------------------------------------------- bindgen unified dispatcher --
    //
    // Aggregates the per-adapter targets. `zig build bindgen` runs
    // every adapter sequentially (vk_gen + wayland_gen + fmt).
    const bindgen_step = b.step("bindgen", "Regenerate every bindgen adapter (Vulkan + Wayland)");
    bindgen_step.dependOn(&vk_gen_fmt.step);
    bindgen_step.dependOn(&wayland_gen_fmt.step);

    // ------------------------------- .d.etch service-spec emitter --
    //
    // `engine-c-bindings.md` §8.4: the `bindgen.ServiceSpec` a Tier 1 module
    // declares is the SOURCE OF TRUTH, and the committed `.d.etch` is a derived
    // artifact. Two steps over ONE rendering, so the check cannot disagree with
    // the regeneration:
    //   - `zig build bindgen-detch` — regenerate in place (manual, §8.4.4)
    //   - `zig build bindgen-check` — compare and fail with a line-by-line diff
    //
    // Distinct from `bindgen-verify` / `vk-gen-check`, which gate the Vulkan and
    // Wayland `.api.zig` → Zig pipeline and have nothing to do with services.
    const detch_module = b.createModule(.{
        .root_source_file = b.path("tools/bindgen/detch_main.zig"),
        .target = b.graph.host,
        .optimize = .Debug,
    });
    detch_module.addImport("weld_etch", etch_module);
    detch_module.addImport("toy_service", toy_service_module);
    detch_module.addImport("forge_services", forge_services_module);
    detch_module.addImport("forge_sensor_events", forge_sensor_events_module);

    const detch_exe = b.addExecutable(.{
        .name = "bindgen_detch",
        .root_module = detch_module,
    });
    const detch_write_run = b.addRunArtifact(detch_exe);
    detch_write_run.has_side_effects = true;
    // `.inherit` and not the default capture, MEASURED: with the default the
    // step failed with exit 1 and printed only the error trace — the
    // line-by-line diff E1902 owes the reader went to a captured pipe and was
    // discarded. A guard that fails without saying why is half a guard.
    detch_write_run.stdio = .inherit;
    detch_write_run.addArg("--write");
    const detch_write_step = b.step(
        "bindgen-detch",
        "Regenerate the .d.etch service declarations from their Zig ServiceSpec",
    );
    detch_write_step.dependOn(&detch_write_run.step);

    const detch_check_run = b.addRunArtifact(detch_exe);
    detch_check_run.has_side_effects = true;
    detch_check_run.stdio = .inherit; // see the note on `detch_write_run`
    const detch_check_step = b.step(
        "bindgen-check",
        "Fail if a committed .d.etch diverges from its Zig ServiceSpec (E1902)",
    );
    detch_check_step.dependOn(&detch_check_run.step);

    // -------------------------------------------- bindgen-verify gate --
    //
    // The non-negotiable mechanical criterion: regenerate then
    // `git diff --quiet bindings/generated/ src/core/platform/`. Exit
    // 0 if the regen matches the committed output bit-for-bit; non-zero
    // (visible diff) signals a divergence and blocks the merge.
    //
    // KNOWN-GOOD CONTROL FIRST: `git diff --exit-code` answers 1 for a real diff
    // and a different non-zero when git cannot run at all, so the control must
    // establish that git answers before the diff's code is read as a verdict.
    const bindgen_verify_control = b.addSystemCommand(&.{ "git", "--version" });
    const bindgen_verify_diff = b.addSystemCommand(&.{
        "git",
        "diff",
        "--quiet",
        "--exit-code",
        "bindings/generated/",
        "src/core/platform/",
    });
    bindgen_verify_diff.step.dependOn(&bindgen_verify_control.step);
    bindgen_verify_diff.step.dependOn(&vk_gen_fmt.step);
    bindgen_verify_diff.step.dependOn(&wayland_gen_fmt.step);
    const bindgen_verify_step = b.step(
        "bindgen-verify",
        "Regenerate bindings + assert `git diff --quiet` on bindings/generated + src/core/platform",
    );
    bindgen_verify_step.dependOn(&bindgen_verify_diff.step);

    // -------------------------------------- weld_lint (custom linter) --
    //
    // In-tree Zig linter enforcing four patterns:
    //  - no `@cImport`
    //  - no `usingnamespace`
    //  - `///` doc comments on every root-level `pub` declaration
    //  - `*_c` module imports only from files with a generated-file header
    //
    // The same binary also validates Conventional Commits via the
    // `commit-msg` subcommand. Both subcommands run on the host target
    // because they are pure-Zig text/AST tools with no platform deps.

    const weld_lint_module = b.createModule(.{
        .root_source_file = b.path("tools/weld_lint/main.zig"),
        .target = b.graph.host,
        .optimize = .Debug,
    });
    const weld_lint_exe = b.addExecutable(.{
        .name = "weld_lint",
        .root_module = weld_lint_module,
    });
    b.installArtifact(weld_lint_exe);

    const lint_run = b.addRunArtifact(weld_lint_exe);
    lint_run.addArg("lint");
    if (b.args) |args| lint_run.addArgs(args);
    // INHERITED, like the bindgen check beside it. Both this step and the
    // dead-test guard below print a report a reader is meant to act on, and a
    // captured stdout reaches nobody on success — measured: the rule pass's
    // coverage report vanished entirely from `zig build lint` while the binary
    // printed all of it when run directly.
    const lint_step = b.step(
        "lint",
        "Run weld_lint on the production tree (no @cImport / no usingnamespace / doc comments / *_c isolation)",
    );
    lint_step.dependOn(&lint_run.step);

    // the dead-test guard, ACTIVE. Every file holding a `test` block
    // must belong to some test target's analysis closure or to a declared
    // exclusion. It builds nothing and runs nothing: it reads `build.zig` for its
    // roots and walks relative imports, so it costs a tree scan and rides on the
    // existing lint gate rather than earning a cell of its own.
    //
    // WHY IT IS ACTIVE AND NOT ADVISORY. An uncollected `test` block is never
    // ANALYSED, so the code it instantiates loses type-checking, not just
    // assertions — which is how `zig_codegen/cache.zig` stopped compiling at the
    // Zig 0.16 pin unnoticed and how a use-after-return in the render graph
    // survived ten milestones. Writing that as doctrine while nothing enforced it
    // is the prohibition this milestone named against itself.
    //
    // It takes no paths, so `b.args` is deliberately NOT forwarded: the args of
    // `zig build lint -- src` belong to the rule pass beside it.
    const dead_tests_run = b.addRunArtifact(weld_lint_exe);
    dead_tests_run.addArg("dead-tests");

    // `-Dexpect-collected=N` FORWARDED, and the reason it exists is
    // that the conservation it feeds was unreachable. The tool's suite-derived check
    // sat behind `--expect-collected=N` and NOTHING passed it: not this file, not the
    // CI. So the lint printed an expected-collected line and then printed `clean`,
    // having compared nothing — the fourth instance in this milestone of a control
    // that exists and a path bypasses, this time inside the tool built against that
    // family.
    //
    // Two layers, and only this one is optional. The tool now confronts the closure
    // against a DECLARED per-OS total on every invocation, with no flag to forget;
    // this option supplies the second number, the total the suite itself reported.
    // CI passes it from the same job that ran the tests. Locally it is optional
    // because `zig build lint` cannot run the suite to learn the figure, and an
    // option that silently defaults to the closure's own arithmetic would be the
    // defect again in a new costume.
    if (b.option(
        usize,
        "expect-collected",
        "Confront the dead-test closure with a collected-test total from `zig build test`",
    )) |n| {
        dead_tests_run.addArg(b.fmt("--expect-collected={d}", .{n}));
    }

    // ORDERED AGAINST THE RULE PASS, and the reason is a MEASURED truncation, not
    // tidiness. Both run steps write to the same stdout and the build runner may
    // run them concurrently. While the rule pass printed nothing on a clean tree
    // nothing collided; the moment it printed its coverage, the dead-test output
    // came back cut mid-sentence with the conservation verdict missing entirely —
    // a control whose verdict can be eaten is a control nobody can read.
    dead_tests_run.step.dependOn(&lint_run.step);
    lint_step.dependOn(&dead_tests_run.step);

    const dead_tests_step = b.step(
        "dead-tests",
        "Report every file with `test` blocks outside all test-target closures",
    );
    dead_tests_step.dependOn(&dead_tests_run.step);

    // The two REPORTERS and the token oracle of the comment pass. They get their
    // own steps and are deliberately NOT wired into `lint_step`: a comment ratio
    // that can fail a build turns the question from "does this comment deserve to
    // exist" into "how do I get under the threshold"
    // (`engine-zig-conventions.md` §12). `fingerprint --check` is the one that can
    // fail, and it compares token identity rather than any quantity.
    const coverage_run = b.addRunArtifact(weld_lint_exe);
    coverage_run.addArg("coverage");
    const coverage_step = b.step(
        "comment-coverage",
        "Print the subtrees the comment rules do not report on yet (empty = whole perimeter read)",
    );
    coverage_step.dependOn(&coverage_run.step);

    const census_run = b.addRunArtifact(weld_lint_exe);
    census_run.addArg("census");
    if (b.args) |args| census_run.addArgs(args);
    const census_step = b.step(
        "census",
        "Report per-file comment lines, blocks and density (zig build census -- [path]...)",
    );
    census_step.dependOn(&census_run.step);

    const fingerprint_run = b.addRunArtifact(weld_lint_exe);
    fingerprint_run.addArg("fingerprint");
    if (b.args) |args| fingerprint_run.addArgs(args);
    const fingerprint_step = b.step(
        "fingerprint",
        "Token fingerprint per file; --check <baseline> fails if any token moved",
    );
    fingerprint_step.dependOn(&fingerprint_run.step);

    const lint_commit_run = b.addRunArtifact(weld_lint_exe);
    lint_commit_run.addArg("commit-msg");
    if (b.args) |args| lint_commit_run.addArgs(args);
    const lint_commit_step = b.step(
        "lint-commit",
        "Validate a Conventional Commits message file (zig build lint-commit -- <file>)",
    );
    lint_commit_step.dependOn(&lint_commit_run.step);

    // runner_test for the linter fixture corpus. The test spawns
    // the installed `weld_lint` binary, so wire the install step in as
    // an explicit dependency just like `tests/ipc/crash_recovery.zig`
    // wires the runtime binary.
    const lint_runner_module = b.createModule(.{
        .root_source_file = b.path("tests/lint/runner_test.zig"),
        .target = target,
        .optimize = optimize,
    });
    const lint_runner_test = b.addTest(.{ .root_module = lint_runner_module });
    const lint_runner_run = b.addRunArtifact(lint_runner_test);
    lint_runner_run.step.dependOn(&b.addInstallArtifact(weld_lint_exe, .{}).step);
    test_step.dependOn(&lint_runner_run.step);

    // the linter's OWN inline tests. The fixture corpus above proves
    // each rule is WIRED into `runLint`, by running the real binary; it cannot
    // prove a rule's logic, since the runner only reads an exit code and a
    // fixture can say no more than "something fired". The two layers are
    // complementary and neither substitutes for the other: a rule tested only
    // inline can be left out of `main.zig` and still pass, and a rule covered
    // only by fixtures can miscount, mis-scope its escape hatch, or flag its own
    // prose without a single test noticing.
    //
    // Until this step existed, every `test` block under `tools/weld_lint/` was
    // dead text — compiled by nothing, run by nothing. The root is `tests.zig`
    // and NOT `main.zig`: a test build does not analyse a plain `const` import,
    // so rooting here at `main.zig` ran zero tests while reporting success —
    // measured, by appending a deliberately failing test and watching this step
    // stay green.
    const weld_lint_test_module = b.createModule(.{
        .root_source_file = b.path("tools/weld_lint/tests.zig"),
        .target = b.graph.host,
        .optimize = .Debug,
    });
    const weld_lint_unit_test = b.addTest(.{ .root_module = weld_lint_test_module });
    test_step.dependOn(&b.addRunArtifact(weld_lint_unit_test).step);

    // three modules held `test` blocks that NO test target collected,
    // so they had never run: `src/modules/render/` (49 blocks), `tools/bindgen/`
    // (8) and `src/modules/audio/` (1). Found by counting source `test` blocks
    // against the suite's own per-target totals, then confirming each by
    // appending a deliberately failing test and watching the suite stay green.
    // RENDER IS HELD, and the reason is what the sweep was for. Wiring its 49
    // never-run tests turns two of them red, and a probe settled why: the
    // render-graph passes return a `Pass` whose `reads`/`writes` slices point at
    // an anonymous literal in `buildPass`'s OWN STACK FRAME. Measured on
    // `depth_prepass`: `writes.ptr` is a stack address, `depth_attachment` reads
    // `false` immediately after the call, and a fresh call at the SAME address
    // reads `true` — a use-after-return, long-lived and invisible because
    // nothing ever compiled the tests that assert it. `forward.zig` fails
    // identically. The fix is an ownership decision in the render graph, not a
    // determinism change, so it is reported rather than taken here.
    const render_tests = b.addTest(.{ .root_module = render_module });
    test_step.dependOn(&b.addRunArtifact(render_tests).step);

    const audio_tests = b.addTest(.{ .root_module = audio_module });
    test_step.dependOn(&b.addRunArtifact(audio_tests).step);

    const bindgen_test_module = b.createModule(.{
        .root_source_file = b.path("tools/bindgen/tests.zig"),
        .target = b.graph.host,
        .optimize = .Debug,
    });
    const bindgen_tests = b.addTest(.{ .root_module = bindgen_test_module });
    test_step.dependOn(&b.addRunArtifact(bindgen_tests).step);
}