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 },
            ));
        }
    }

    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 — S3 parser + type-checker + S4 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 S4 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);

    // M0.3 — `weld_audio` module exposes the Tier 1 audio module entry
    // (Dummy backend Phase 0, real backends Phase 1). 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,
    });

    // M0.4 — `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 (brief §Scope).
    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);

    // M0.6 — `weld_asset_pipeline` module: the Tier 1 Asset Pipeline. E1
    // ships the day-1-frozen on-disk surfaces (intermediate
    // `<type>.asset.etch` schema + runtime `.<type>.bin` 40-byte header),
    // the `AssetHandle`, and the slot registry (refcount + generation
    // invalidation). Depends on `weld_core` (the E5 async loader consumes the
    // Tier 0 job system); the `foundation` (SIMD) import wires in at E2 when
    // the `adler32` / `paeth` kernels land. No `weld_etch` dependency
    // (brief §Out-of-scope).
    // M0.6 / E2 — `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,
    });

    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);
    // M0.6 / E2 — `foundation` dep wires in now that simd exists (deferred
    // from E1): the DEFLATE/zlib codec verifies the ADLER32 trailer via
    // `foundation.simd.adler32`.
    asset_pipeline_module.addImport("foundation", foundation_module);

    // M0.2 / E6 — 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,
    });

    // M0.2 / E6 — 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_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 M0.2 / E6 stub plugin libraries used by the plugin_loader tests",
    );
    for (stub_install_steps) |s| stub_plugins_step.dependOn(s);

    // M0.4 — `src/main.zig` removed (cf. brief §Removals). The Weld
    // engine is consumed as a lib + tools, not as a root binary. The
    // demonstration lives in `examples/triangle/`. All the CLI-parsing
    // logic of the S2 spike binary (--smoke-test, --gpu-prefer, --capture-frame)
    // is migrated into `examples/triangle/src/main.zig`.

    // Shaders embedding — shared by the editor + runtime binaries for
    // the S6 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,
    });

    // M0.4 — `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
    // (brief §Notes decision 12 + §Observable behavior).
    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);

    // M0.8 / E3-D — `zig build verify-synth-100` builds the standalone
    // `bench/fixtures/synth_100/` sub-project (D-S5-synth100-proper): 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 D-S5-synth100-proper proof)");
    synth_verify_step.dependOn(&synth_verify.step);

    // M0.4 — Shader compiler tool: `zig build shaders` regenerates the
    // `.spv` from the `.glsl`. `zig build shaders-check` diffs vs
    // the committed ones (brief §Files + §CI).
    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);

    // M0.4 — `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);

    // M0.6 — 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);

    // M0.6 / E2 — inline tests inside src/foundation/** (traits + kernels).
    // simd.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);

    // Out-of-tree tests. Each file is its own root_module and imports
    // `weld_core` to reach the engine internals.
    // Out-of-tree bindings tests need to reach files that live outside
    // `weld_core`'s module tree. Each group is exposed via a thin facade
    // module — Zig 0.16 forbids a single file from belonging to two module
    // trees, so we can't expose siblings as separate modules when they
    // `@import` each other.
    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,
    });

    // S4 differential corpus — `tests/etch_interp/` houses 20 .etch
    // programs and their sidecar `expected.zig` files. The facade is the
    // shared module the corpus_test driver and the bench harness both
    // import (same pattern as the S3 corpus facade above).
    // Generic test driver module (independent of the corpus + runner) so it
    // can be reused by S5's 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);
    // S4 differential corpus — `tests/etch_interp/` houses 20 .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);

    const TestSpec = struct {
        path: []const u8,
        // M0.4 — `spike` field removed, no entry needs it anymore.
        wl_protocols: bool = false,
        etch: bool = false,
        etch_interp: bool = false,
        /// M0.2 / E6 — 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,
        /// M0.3 — when set, imports the `weld_audio` module.
        audio: bool = false,
        /// M0.4 — when set, imports the `weld_render` module (GAL public
        /// surface + Null backend, Vulkan backend wires in later).
        render: bool = false,
        /// M0.6 — when set, imports the `weld_asset_pipeline` module.
        asset_pipeline: bool = false,
        /// M0.6 / E2 — when set, imports the `foundation` module (simd).
        foundation: bool = false,
        /// M1.0.4 — 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,
        /// M0.4 stabilization — 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 M0.4 debt).
        dedicated_step: ?[]const u8 = null,
    };
    const test_specs = [_]TestSpec{
        .{ .path = "tests/smoke_test.zig" },
        .{ .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" },
        .{ .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/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" },
        .{ .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" },
        // M0.4 — tests/spike/ removed with the rest of the folder
        // (cf. brief §Removals). The multi-GPU scoring is ported into
        // gal/vulkan/device.zig, the CLI parse lives in
        // examples/triangle/src/main.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 },
        // M0.5 item 8 — 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 },
        // M0.8 / E1 — top-level recovery sync-point (ParseResult.diagnostics
        // slice + resync at the next top-level keyword).
        .{ .path = "tests/etch/recovery_toplevel_test.zig", .etch = true },
        // M0.8 / E1 — EBNF harness: every ```etch example block parses clean.
        .{ .path = "tests/etch/ebnf_examples_test.zig", .etch = true },
        // M0.8 / E7 — AST stable interface freeze: ≥20 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" },
        // M0.8 / E7 — 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" },
        // M0.8 / E7 — 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" },
        // M0.8 / E7 — 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" },
        // M0.8 / E3-D — D-S5-etchcook-inproc: the consolidated cook library.
        .{ .path = "tests/etch/cook_consolidate_test.zig", .etch = true },
        // M0.9 / E2-A — triple-quote `"""…"""` multiline string lexer token
        // + §1.4 common-indent strip at parse.
        .{ .path = "tests/etch/lexer_triple_quote_test.zig", .etch = true },
        // M0.9 / E2-B — 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 },
        // M1.0.7 / E3 — `import` directive parsing: the four grammar forms
        // (whole / selective / aliased / per-item alias), IDENT+TYPE_IDENT items
        // (D-D), and malformed-import recovery (resync, no UnsupportedConstructInS3).
        .{ .path = "tests/etch/import_parse_test.zig", .etch = true },
        // M1.0.7 / E4-E6 — module graph + cycle (E0108), exports binding
        // (E0103/E0104), cross-file type resolution (no E0102).
        .{ .path = "tests/etch/import_resolve_test.zig", .etch = true },
        // M1.0.7 / E6 — 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 },
        // M1.0.0 — 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 },
        // M1.0.4 / E2 — scene cook → writer → accessor round-trip (entities,
        // archetypes, UUIDs, names, parent links, content_version, resources,
        // mixed-alignment columns, byte-identical determinism).
        .{ .path = "tests/scene/cook_roundtrip_test.zig", .scene = true },
        // M1.0.4 / E3 — scene cook negative cases (typed errors, no panic).
        .{ .path = "tests/scene/cook_errors_test.zig", .scene = true },
        // M1.0.6 / E2 — 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" },
        // M1.0.6 / E3 — `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" },
        // M1.0.6 / E4 — 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" },
        // M1.0.6 / E5 — `extensions:` clause parse + AST + descriptors. The
        // cook/binary + load portions land once the hooks-section shape unblocks.
        .{ .path = "tests/scene/extensions_test.zig", .scene = true, .dedicated_step = "test-extensions" },
        // M1.0.6 / E3+E4+E6 — 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" },
        // M1.0.5 / E2 — 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" },
        // M1.0.5 / E3 — resource `string` fields round-trip through the Tier-0
        // persistent heap (intern on load, owned by `LoadResult`). `weld_core` only.
        .{ .path = "tests/scene/load_resources_test.zig" },
        // M0.3 — 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" },
        // M0.3 — Win32 thread safety stress (Windows runner only).
        .{ .path = "tests/platform/win32_thread_safety_test.zig" },
        // M0.3 — Wayland thread safety stress (Linux runner only).
        .{ .path = "tests/platform/wayland_thread_safety_test.zig" },
        // M0.3 — Multi-monitor enumeration + current monitor + per-monitor DPI.
        .{ .path = "tests/platform/multi_monitor_test.zig" },
        // M0.3 — WindowEvent union surface validation.
        .{ .path = "tests/platform/window_events_test.zig" },
        // M0.3 — 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" },
        // M0.3 — Audio Dummy stub test.
        .{ .path = "tests/audio/dummy_stub_test.zig", .audio = true },
        // M0.4 — GAL Null backend smoke + interface check (CI headless).
        .{ .path = "tests/render/gal_null_smoke.zig", .render = true },
        // M0.4 — GAL Vulkan backend offline init test (skip if Vulkan absent).
        .{ .path = "tests/render/gal_vulkan_offline.zig", .render = true },
        // M0.4 — Render graph topological sort + cycle detection.
        .{ .path = "tests/render/render_graph_topo.zig", .render = true },
        // M0.4 — Render graph auto-tracking barriers (write-after-read,
        // explicit mode skip).
        .{ .path = "tests/render/render_graph_barriers.zig", .render = true },
        // M0.4 — Instancing batcher (bucketing mesh+material, drawcalls
        // ≤ 100 for 100k entities).
        .{ .path = "tests/render/instancing_batcher.zig", .render = true },
        // M0.4 — Shader disk cache round-trip (hit/miss source change /
        // miss glslc version change).
        .{ .path = "tests/render/shader_cache.zig", .render = true },
        // M0.4 § Scope Post-Review — 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
        // M0.7 housekeeping debt).
        .{ .path = "tests/render/capture.zig", .render = true, .dedicated_step = "test-render-capture" },
        // M0.5 item 2 — GAL capture helper surface coverage (encodePpm +
        // Device.captureFrameToPPM); §13 consumer test, runs on every platform.
        .{ .path = "tests/render/capture_helper.zig", .render = true },
        // M0.5 item 1 — 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" },
        // M0.4 § Scope Post-Review — hot-reload filewatch latency < 200 ms.
        // Skip if glslc absent from PATH.
        .{ .path = "tests/render/shader_hot_reload.zig", .render = true },
        // M0.4 — vk_gen whitelist closure (variant filtering + closure
        // convergence under 20 iterations).
        .{ .path = "tests/vk_gen/whitelist_closure.zig" },
        // M0.4 — vk_gen *Raw variants emission (3 targets emitted, others
        // not emitted).
        .{ .path = "tests/vk_gen/raw_variants.zig" },
        // M0.6 / E1 — asset registry stale-handle (generation) acceptance.
        .{ .path = "tests/assets/handle_generation.zig", .asset_pipeline = true },
        // M0.6 / E5 — async loader + lifecycle (internal 5 s watchdog).
        .{ .path = "tests/assets/loader_async.zig", .asset_pipeline = true },
        // M0.6 / E2 — DEFLATE/zlib inflate known-vector acceptance.
        .{ .path = "tests/assets/deflate_vectors.zig", .asset_pipeline = true },
        // M0.6 / E2 — 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 },
        // M0.6 / E3 — paeth_filter_decode kernel portable == reference.
        .{ .path = "src/foundation/simd/tests/paeth_test.zig", .foundation = true },
        // M0.6 / E4 — 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 },
    };
    // M1.0.1 — shared fail-fast watchdog for in-process concurrency tests
    // (point-4 permanent guard; covers the scheduler.deinit-join site that
    // masked the windows-2025/ReleaseSafe hang). Imported by tests via
    // `@import("test_watchdog")`; only compiled into 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.foundation) {
            t_mod.addImport("foundation", foundation_module);
        }
        if (spec.scene) {
            t_mod.addImport("weld_etch", etch_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);
        }
    }

    // M0.2.1 / E2 — `zig build test-stress` builds and runs ONLY the
    // scheduler-livelock stress test. Kept out of `test_step` per
    // brief § Notes ("No adding `test_stress` to `zig build
    // test` by default; the 100× stress-signal loop is a local
    // validation tool, not a routine CI test"). 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);
        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 M0.2.1/E2 scheduler-livelock stress test",
        );
        stress_step.dependOn(&stress_test_run.step);
    }

    // ----------------------------- S6 editor + runtime stub binaries -----
    //
    // Two binaries at the canonical Phase 0+ locations per
    // `engine-directory-structure.md` §9.1, not in `src/spike/`.
    // S6 produces code that survives — these stubs grow into the
    // real editor / runtime in Phase 0.

    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);
    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 S6 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);
    // S6 viewport blit pipeline embeds pre-compiled SPIR-V via the
    // shared `shaders` facade — the same module the S2 spike uses.
    editor_module.addImport("shaders", shaders_module);
    // M0.9 / E6 — 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 S6 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 the
    // brief's 60 s observable window, graceful shutdown. Honours
    // the G6 manual-demo checklist.
    //
    // Pass any editor flag through `--`, e.g.
    //   zig build run-ipc-demo -- --frames=3600
    // for a one-minute observable session at 60 Hz. Defaults to
    // `--frames=3600` (≈ 60 s) when the caller passes no `--` args
    // so the canonical S6 demo matches the G6 verdict description.
    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 S6 editor↔runtime demo (window + Vulkan blit, default 60 s; override with `-- --frames=N`)",
    );
    ipc_demo_step.dependOn(&ipc_demo_run.step);

    // ------------------------------------------------ S6 IPC tests --------
    //
    // Each IPC test is its own exe so a deadlock in one case (the
    // previous session's 46-minute test-runner hang taught us this
    // the expensive way) cannot stall the rest of `zig build test`.
    // The `test-ipc` step runs only the IPC tests for fast iteration
    // during S6; 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 S6 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 (G4 + G5; M0.7 / E2 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 the S5 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);
    }

    // ----------------------------------------------- S6 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 S6 IPC RTT bench (N=10_000 Echo round-trips, writes bench/results/ipc_rtt.md)",
    );
    ipc_rtt_step.dependOn(&ipc_rtt_run.step);

    // ----------------------------------------- S6 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 --
    //
    // M0.1 / E1 renamed `bench/ecs_iteration.zig` → `bench/ecs_benchmark.zig`
    // (file rename only — content stays the S1 non-regression case until
    // E7 extends it with 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 (S1 non-regression case; pass `-- --smoke` for a CI sanity run)",
    );
    bench_step.dependOn(&bench_run.step);

    // -------------------------------------- M1.0.5 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 M1.0.5 scene loader bench (~10k entities, reports median)",
    );
    scene_load_bench_step.dependOn(&scene_load_bench_run.step);

    // ------------------------------------- M0.4 render instancing bench ------
    //
    // CPU-side batcher harness for the brief Benchmarks targets
    // (100k entities × 100 (mesh, material) distinct -> 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 M0.4 render instancing bench (writes bench/out/render_instancing_<os>.md)",
    );
    render_bench_step.dependOn(&render_bench_run.step);

    // ------------------------------------------- M0.6 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 M0.6 adler32 throughput baseline (pass `-- --smoke` for a CI sanity run)",
    );
    adler32_bench_step.dependOn(&adler32_bench_run.step);

    // ------------------------------------------- M0.6 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 M0.6 paeth_filter_decode throughput baseline (pass `-- --smoke` for a CI sanity run)",
    );
    paeth_bench_step.dependOn(&paeth_bench_run.step);

    // ------------------------------------- M0.6 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 M0.6 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);

    // ----------------------------------- M0.6 thin offline asset cook demo ----
    //
    // `zig build cook-demo` cooks the three M0.6 fixtures end-to-end through
    // the cache and logs hits (brief §Observable behavior). The user-facing
    // `weld cook` CLI is Phase 1.
    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 M0.6 fixtures end-to-end (import → cook → cache; logs hits)",
    );
    asset_cook_step.dependOn(&asset_cook_run.step);

    // M1.0.4 / E3 — `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 (S4 demo) --

    // `@embedFile` cannot escape the package root of the module that
    // invokes it, so both the S4 bench and the S4 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,
    });

    // ------------------------------------------------- S4 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("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 S4 demo (1000 entities × 5 rules × 60 ticks)",
    );
    demo_step.dependOn(&demo_run.step);

    // -------------------------------------------- S4 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 S4 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 S3 Etch parse bench (pass `-- --smoke` for a CI sanity run)",
    );
    etch_bench_step.dependOn(&etch_bench_run.step);

    // --------------------------------------- S5 Etch → Zig codegen tool ---
    //
    // `tools/etch_cook` is a standalone CLI that runs the S5 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);

    // Cook the 20 differential corpus programs into a single consolidated
    // `corpus_codegen.zig`. The driver test imports it via the
    // `corpus_codegen` module name.
    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 (M0.8 E3-D) — 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 S5 differential corpus through the Zig codegen runner",
    );
    codegen_diff_step.dependOn(&codegen_diff_run.step);

    // Level-B serialized-IR differential (M0.8 E4): 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);
    // M0.8 E7 — `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);

    // ----------------------------------------- S5 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);

    // -------------------------------- S5 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("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 S5 codegen demo (cooks demo_5_rules_codegen.etch, runs 10 ticks)",
    );
    demo_codegen_step.dependOn(&demo_codegen_run.step);

    // ----------------------- M0.9 / E3 vertical slice (run-vertical-slice) --
    // Headless slice: cook examples/vertical_slice/gameplay.etch (POD
    // components + 5 rules) → cooked module; the host (main.zig) spawns 100
    // entities (Option A host-spawn, brief Blockers #1) 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 (E2-B), not loaded (Phase 1 Scene Serialization).
    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);

    // M0.9 / E4 — the slice gains a Vulkan forward renderer + an M0.6-cooked
    // texture asset + M0.3 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);

    // E4 — cook the slice's single source asset (PNG → .texture.bin) through
    // the real M0.6 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 M0.9 slice's source asset (PNG → .texture.bin) via M0.6",
    );
    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 M0.9 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 (E2-B 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 M0.9 vertical slice integration test",
    );
    slice_test_step.dependOn(&slice_test_run.step);

    // ----------------------------- S5 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 (M0.8 E3-D, D-S5-etchcook-inproc) — 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 S5 compile-time bench (cook + cold + incremental, N=10; pass `-- --smoke` for CI)",
    );
    compile_bench_step.dependOn(&compile_bench_run.step);

    // -------------------------------------------- bindgen (M0.2 unified) --
    //
    // Unified bindgen system per `engine-c-bindings.md` §1. The two
    // M0.2 adapters (`vk_xml`, `wayland_xml`) port the legacy S2
    // 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 + diff vide 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; the brief's "bindgen-vk produces
    // an empty diff" criterion only holds 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);

    // -------------------------------------------- bindgen-verify gate --
    //
    // M0.2 / E5 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.
    const bindgen_verify_diff = b.addSystemCommand(&.{
        "git",
        "diff",
        "--quiet",
        "--exit-code",
        "bindings/generated/",
        "src/core/platform/",
    });
    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 (M0.0 custom linter) --
    //
    // In-tree Zig linter enforcing the four patterns from M0.0:
    //  - 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);
    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);

    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);

    // M0.0 — 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);
}