build.zig

const std = @import("std");

// Vendored C engine translation units (relative to reference/upstream-c/), grouped
// per docs/PORTING-PLAN.md Phase 3 (build-pain fix: cross-compile to a static lib for
// the Linux shim target). Grammar files are discovered via glob at build time since
// there are ~160 of them; everything else is listed explicitly to keep this file
// reviewable and to make exclusions traceable.
const engine_c_sources = [_][]const u8{
    // foundation
    "src/foundation/arena.c",
    "src/foundation/hash_table.c",
    "src/foundation/str_intern.c",
    "src/foundation/log.c",
    "src/foundation/str_util.c",
    "src/foundation/platform.c",
    "src/foundation/system_info.c",
    "src/foundation/slab_alloc.c",
    "src/foundation/yaml.c",
    "src/foundation/compat.c",
    "src/foundation/compat_thread.c",
    "src/foundation/compat_regex.c",
    // compat_fs.c is compiled separately (see buildEngineLib) since hybrid builds
    // need a rename flag applied to it for the walk_guard chokepoint (Stage 4b).
    "src/foundation/mem.c",
    "src/foundation/diagnostics.c",
    "src/foundation/profile.c",
    "src/foundation/dump_verify.c",
    "src/foundation/limits.c",
    "src/foundation/subprocess.c",
    "src/foundation/sha256.c",

    // store / cypher / graph_buffer / simhash / traces / git
    "src/store/store.c",
    "src/cypher/cypher.c",
    "src/graph_buffer/graph_buffer.c",
    "src/simhash/minhash.c",
    "src/traces/traces.c",
    "src/git/git_context.c",

    // discover
    "src/discover/language.c",
    "src/discover/userconfig.c",
    "src/discover/gitignore.c",
    "src/discover/discover.c",

    // pipeline (all)
    "src/pipeline/fqn.c",
    "src/pipeline/path_alias.c",
    "src/pipeline/registry.c",
    "src/pipeline/pipeline.c",
    "src/pipeline/pipeline_incremental.c",
    "src/pipeline/worker_pool.c",
    "src/pipeline/pass_parallel.c",
    "src/pipeline/pass_definitions.c",
    "src/pipeline/pass_calls.c",
    "src/pipeline/pass_lsp_cross.c",
    "src/pipeline/pass_usages.c",
    "src/pipeline/pass_semantic.c",
    "src/pipeline/pass_tests.c",
    "src/pipeline/pass_githistory.c",
    "src/pipeline/pass_gitdiff.c",
    "src/pipeline/pass_configures.c",
    "src/pipeline/pass_configlink.c",
    "src/pipeline/pass_route_nodes.c",
    "src/pipeline/pass_enrichment.c",
    "src/pipeline/pass_envscan.c",
    "src/pipeline/pass_compile_commands.c",
    "src/pipeline/pass_infrascan.c",
    "src/pipeline/pass_k8s.c",
    "src/pipeline/pass_similarity.c",
    "src/pipeline/pass_semantic_edges.c",
    "src/pipeline/pass_complexity.c",
    "src/pipeline/pass_cross_repo.c",
    "src/pipeline/artifact.c",
    "src/pipeline/pass_pkgmap.c",

    // semantic
    "src/semantic/semantic.c",
    "src/semantic/ast_profile.c",
    "src/semantic/rotsq.c",

    // extraction (internal/cbm)
    "internal/cbm/cbm.c",
    "internal/cbm/extract_defs.c",
    "internal/cbm/extract_calls.c",
    "internal/cbm/extract_imports.c",
    "internal/cbm/extract_usages.c",
    "internal/cbm/extract_unified.c",
    "internal/cbm/extract_semantic.c",
    "internal/cbm/extract_type_refs.c",
    "internal/cbm/extract_type_assigns.c",
    "internal/cbm/extract_env_accesses.c",
    "internal/cbm/extract_channels.c",
    "internal/cbm/extract_k8s.c",
    "internal/cbm/helpers.c",
    "internal/cbm/lang_specs.c",
    "internal/cbm/macro_table.c",
    "internal/cbm/iris_export_xml.c",
    "internal/cbm/service_patterns.c",

    // lsp (unity build — includes lsp/*.c)
    "internal/cbm/lsp_all.c",

    // tree-sitter runtime (unity build — includes vendored/ts_runtime/src/lib.c)
    "internal/cbm/ts_runtime.c",

    // ac / lz4 / zstd / sqlite_writer
    "internal/cbm/ac.c",
    "internal/cbm/lz4_store.c",
    "internal/cbm/zstd_store.c",
    "internal/cbm/vendored/zstd/zstd.c", // libzstd amalgamation (ZSTD_* impl)
    "internal/cbm/sqlite_writer.c",

    // vendored (excluding sqlite3.c, mimalloc/static.c — special flags, added separately)
    "vendored/yyjson/yyjson.c",
    "vendored/tre/tre_all.c",
};

// Phase 4: MCP delegation seam sources. Not part of the Phase-3 `engine` lib
// (which only needed to prove the C engine cross-compiles); added only to the
// hybrid engine-lib builds. mcp.c pulls in the whole tool-dispatch surface, which
// transitively needs watcher.c and cli.c for symbols referenced by cli/cli.h and
// watcher/watcher.h consumers (see hybrid_extra_c_sources below for the resolved
// undefined-symbol set from actually linking main_hybrid.zig).
const mcp_c_sources = [_][]const u8{
    "src/mcp/mcp.c",
    "src/mcp/index_supervisor.c",
    "src/mcp/compact_out.c",
};

// Additional vendored C sources required to resolve undefined symbols once the
// MCP seam is linked into an executable (main_hybrid.zig calling
// cbm_mcp_server_*). Discovered iteratively from linker errors; see the comment
// block below for the exact resolution reasoning per file.
const hybrid_extra_c_sources = [_][]const u8{
    "src/watcher/watcher.c",
};

// walk_guard.c (Stage 4b) is OUR new code, not vendored — compiled with
// -Dcbm_opendir=cbm_opendir_real applied only to compat_fs.c for the hybrid
// builds so the real definition is renamed and walk_guard.c's cbm_opendir()
// becomes the sole chokepoint symbol.
const walkguard_rename_flag = "-Dcbm_opendir=cbm_opendir_real";

// popen_guard.c (bounds cbm_popen the same way walk_guard.c bounds
// cbm_opendir — see popen_guard.c's header comment for the audit finding and
// design). compat_fs.c gets both its cbm_popen and cbm_pclose definitions
// renamed so popen_guard.c's wrappers become the sole chokepoint symbols.
const popenguard_rename_flags = [_][]const u8{ "-Dcbm_popen=cbm_popen_real", "-Dcbm_pclose=cbm_pclose_real" };

// grammar_perl.c is compiled SEPARATELY (see buildEngineLib) with an extra
// -Dbsearch=cbm_perl_bsearch flag. Its vendored bsearch.h ships its OWN
// self-contained bsearch() definition (and the grammar calls that local copy),
// but declaring `void *bsearch(...)` as a plain identifier collides with zig's
// glibc stdlib.h `bsearch` (a `_Generic` macro on this target), so the plain
// declaration fails to parse. Renaming the identifier only within this TU is
// self-consistent (definition + call sites move together) and yields the
// tree_sitter_perl symbol lang_specs.c needs — no edit to reference/ required.
// NOTE: this TU must NOT be compiled with -D_GNU_SOURCE: under _GNU_SOURCE glibc
// exposes bsearch as a _Generic() macro that the -Dbsearch rename collides with,
// which is why perl gets its own flag set (grammars need no GNU extensions).
const perl_grammar_flags = [_][]const u8{
    "-std=c11",
    "-D_DEFAULT_SOURCE",
    "-DCBM_BIND_TS_ALLOCATOR=1",
    "-w",
    "-fno-sanitize=undefined",
    "-Dbsearch=cbm_perl_bsearch",
    // Some tree-sitter external scanners (e.g. `just`) hard-`#error` if NDEBUG is
    // defined ("expected assertions to be enabled"). Debug builds don't define
    // NDEBUG so this only bit under -Doptimize=ReleaseFast/-Safe. Keep assertions
    // on for GRAMMAR units only (their assert() overhead is negligible); the core
    // engine/SQLite stay at -DNDEBUG to match upstream's release perf. Must trail
    // any Zig-injected -DNDEBUG (per-file flags win over module flags).
    "-UNDEBUG",
};

// engine_c_extra_flags + -UNDEBUG, for grammar translation units (see the
// -UNDEBUG note in perl_grammar_flags).
const grammar_extra_flags = engine_c_extra_flags ++ [_][]const u8{"-UNDEBUG"};

// Windows (MinGW) engine flags: same as engine_c_extra_flags but WITHOUT
// -D_GNU_SOURCE. On x86_64-windows-gnu, _GNU_SOURCE is honored by some vendored
// C (e.g. zstd's COVER trainer) to select glibc-only reentrant APIs like
// qsort_r() that MinGW does not provide (and it isn't _MSC_VER, so the qsort_s
// branch is skipped either) — dropping it makes that code take its portable
// C90 fallback. Selected per-target in buildEngineLib.
const win_engine_flags = [_][]const u8{
    "-std=c11",
    "-D_DEFAULT_SOURCE",
    "-DCBM_BIND_TS_ALLOCATOR=1",
    "-w",
    "-fno-sanitize=undefined",
    // MinGW <ctype.h>/<string.h> declare locale/ctype internals (_wctype,
    // __ptmbcinfo, __newclmap, __globallocalestatus, …) as tentative DATA defs and
    // the sec_api _s helpers (strnlen_s/wcsnlen_s) as inline funcs. The tree-sitter
    // grammar scanners include these headers (iswalpha, etc.), so at Zig's -ODebug
    // (-O0, nothing folded) every grammar object emits its own copy -> lld-link
    // "duplicate symbol". Two orthogonal fixes:
    //  - -fcommon: emit tentative data as COMMON symbols the linker merges (Clang
    //    defaults to -fno-common since Clang 11, which turns them into hard dups).
    //  - -D__CRT__NO_INLINE: make the headers emit plain declarations for their
    //    __CRT_INLINE functions, resolved once from the CRT import lib.
    // Both are harmless off-Windows; set only here where MinGW headers are in play.
    "-fcommon",
    "-D__CRT__NO_INLINE",
};

/// Return base ++ extra as a fresh runtime slice (build-graph lifetime). Used to
/// layer per-file defines onto the per-target base flags without needing the
/// bases to be comptime-known.
fn catFlags(b: *std.Build, base: []const []const u8, extra: []const []const u8) []const []const u8 {
    const out = b.allocator.alloc([]const u8, base.len + extra.len) catch @panic("oom");
    @memcpy(out[0..base.len], base);
    @memcpy(out[base.len..], extra);
    return out;
}

const engine_c_extra_flags = [_][]const u8{
    "-std=c11",
    "-D_DEFAULT_SOURCE",
    "-D_GNU_SOURCE",
    "-DCBM_BIND_TS_ALLOCATOR=1",
    "-w",
    // Upstream builds the engine at -O2 with no sanitizers. Zig's default Debug
    // build injects -fsanitize=undefined into C code, which traps on the benign
    // UB the vendored C relies on (e.g. memcpy(dst, NULL, 0) / null passed to a
    // __nonnull param in pass_similarity.c) and aborts. We don't own this C, so
    // don't instrument it — match upstream's non-sanitized behavior.
    "-fno-sanitize=undefined",
};

// Grammar translation units, each compiled as its own object (they define
// conflicting static symbols so cannot share a TU). Discovered by listing
// internal/cbm/grammar_*.c at the time this file was written (159 files);
// zig 0.16's std.Io.Dir API needs an Io context not readily available in
// build.zig, so this list is captured statically rather than glob'd at
// build time. grammar_perl.c is NOT in this list — it is added separately in
// buildEngineLib with the bsearch rename flag (see perl_grammar_flag).
const engine_grammar_sources = [_][]const u8{
    "internal/cbm/grammar_ada.c",
    "internal/cbm/grammar_agda.c",
    "internal/cbm/grammar_apex.c",
    "internal/cbm/grammar_assembly.c",
    "internal/cbm/grammar_astro.c",
    "internal/cbm/grammar_awk.c",
    "internal/cbm/grammar_bash.c",
    "internal/cbm/grammar_beancount.c",
    "internal/cbm/grammar_bibtex.c",
    "internal/cbm/grammar_bicep.c",
    "internal/cbm/grammar_bitbake.c",
    "internal/cbm/grammar_blade.c",
    "internal/cbm/grammar_c.c",
    "internal/cbm/grammar_c_sharp.c",
    "internal/cbm/grammar_cairo.c",
    "internal/cbm/grammar_capnp.c",
    "internal/cbm/grammar_cfml.c",
    "internal/cbm/grammar_cfscript.c",
    "internal/cbm/grammar_clojure.c",
    "internal/cbm/grammar_cmake.c",
    "internal/cbm/grammar_cobol.c",
    "internal/cbm/grammar_commonlisp.c",
    "internal/cbm/grammar_cpp.c",
    "internal/cbm/grammar_crystal.c",
    "internal/cbm/grammar_css.c",
    "internal/cbm/grammar_csv.c",
    "internal/cbm/grammar_cuda.c",
    "internal/cbm/grammar_d.c",
    "internal/cbm/grammar_dart.c",
    "internal/cbm/grammar_devicetree.c",
    "internal/cbm/grammar_diff.c",
    "internal/cbm/grammar_dockerfile.c",
    "internal/cbm/grammar_dotenv.c",
    "internal/cbm/grammar_elisp.c",
    "internal/cbm/grammar_elixir.c",
    "internal/cbm/grammar_elm.c",
    "internal/cbm/grammar_erlang.c",
    "internal/cbm/grammar_fennel.c",
    "internal/cbm/grammar_fish.c",
    "internal/cbm/grammar_form.c",
    "internal/cbm/grammar_fortran.c",
    "internal/cbm/grammar_fsharp.c",
    "internal/cbm/grammar_func.c",
    "internal/cbm/grammar_gdscript.c",
    "internal/cbm/grammar_gitattributes.c",
    "internal/cbm/grammar_gitignore.c",
    "internal/cbm/grammar_gleam.c",
    "internal/cbm/grammar_glsl.c",
    "internal/cbm/grammar_gn.c",
    "internal/cbm/grammar_go.c",
    "internal/cbm/grammar_gomod.c",
    "internal/cbm/grammar_gotemplate.c",
    "internal/cbm/grammar_graphql.c",
    "internal/cbm/grammar_groovy.c",
    "internal/cbm/grammar_hare.c",
    "internal/cbm/grammar_haskell.c",
    "internal/cbm/grammar_hcl.c",
    "internal/cbm/grammar_hlsl.c",
    "internal/cbm/grammar_html.c",
    "internal/cbm/grammar_hyprlang.c",
    "internal/cbm/grammar_ini.c",
    "internal/cbm/grammar_ispc.c",
    "internal/cbm/grammar_janet.c",
    "internal/cbm/grammar_java.c",
    "internal/cbm/grammar_javascript.c",
    "internal/cbm/grammar_jinja2.c",
    "internal/cbm/grammar_jsdoc.c",
    "internal/cbm/grammar_json.c",
    "internal/cbm/grammar_json5.c",
    "internal/cbm/grammar_jsonnet.c",
    "internal/cbm/grammar_julia.c",
    "internal/cbm/grammar_just.c",
    "internal/cbm/grammar_kconfig.c",
    "internal/cbm/grammar_kdl.c",
    "internal/cbm/grammar_kotlin.c",
    "internal/cbm/grammar_lean.c",
    "internal/cbm/grammar_linkerscript.c",
    "internal/cbm/grammar_liquid.c",
    "internal/cbm/grammar_llvm.c",
    "internal/cbm/grammar_lua.c",
    "internal/cbm/grammar_luau.c",
    "internal/cbm/grammar_magma.c",
    "internal/cbm/grammar_makefile.c",
    "internal/cbm/grammar_markdown.c",
    "internal/cbm/grammar_matlab.c",
    "internal/cbm/grammar_mermaid.c",
    "internal/cbm/grammar_meson.c",
    "internal/cbm/grammar_mojo.c",
    "internal/cbm/grammar_move.c",
    "internal/cbm/grammar_nasm.c",
    "internal/cbm/grammar_nickel.c",
    "internal/cbm/grammar_nix.c",
    "internal/cbm/grammar_objc.c",
    "internal/cbm/grammar_objectscript_routine.c",
    "internal/cbm/grammar_objectscript_udl.c",
    "internal/cbm/grammar_ocaml.c",
    "internal/cbm/grammar_odin.c",
    "internal/cbm/grammar_pascal.c",
    "internal/cbm/grammar_php.c",
    "internal/cbm/grammar_pine.c",
    "internal/cbm/grammar_pkl.c",
    "internal/cbm/grammar_po.c",
    "internal/cbm/grammar_pony.c",
    "internal/cbm/grammar_powershell.c",
    "internal/cbm/grammar_prisma.c",
    "internal/cbm/grammar_properties.c",
    "internal/cbm/grammar_protobuf.c",
    "internal/cbm/grammar_puppet.c",
    "internal/cbm/grammar_purescript.c",
    "internal/cbm/grammar_python.c",
    "internal/cbm/grammar_qml.c",
    "internal/cbm/grammar_r.c",
    "internal/cbm/grammar_racket.c",
    "internal/cbm/grammar_regex.c",
    "internal/cbm/grammar_requirements.c",
    "internal/cbm/grammar_rescript.c",
    "internal/cbm/grammar_ron.c",
    "internal/cbm/grammar_rst.c",
    "internal/cbm/grammar_ruby.c",
    "internal/cbm/grammar_rust.c",
    "internal/cbm/grammar_scala.c",
    "internal/cbm/grammar_scheme.c",
    "internal/cbm/grammar_scss.c",
    "internal/cbm/grammar_slang.c",
    "internal/cbm/grammar_smali.c",
    "internal/cbm/grammar_smithy.c",
    "internal/cbm/grammar_solidity.c",
    "internal/cbm/grammar_soql.c",
    "internal/cbm/grammar_sosl.c",
    "internal/cbm/grammar_sql.c",
    "internal/cbm/grammar_squirrel.c",
    "internal/cbm/grammar_sshconfig.c",
    "internal/cbm/grammar_starlark.c",
    "internal/cbm/grammar_svelte.c",
    "internal/cbm/grammar_sway.c",
    "internal/cbm/grammar_swift.c",
    "internal/cbm/grammar_systemverilog.c",
    "internal/cbm/grammar_tablegen.c",
    "internal/cbm/grammar_tcl.c",
    "internal/cbm/grammar_teal.c",
    "internal/cbm/grammar_templ.c",
    "internal/cbm/grammar_thrift.c",
    "internal/cbm/grammar_tlaplus.c",
    "internal/cbm/grammar_toml.c",
    "internal/cbm/grammar_tsx.c",
    "internal/cbm/grammar_typescript.c",
    "internal/cbm/grammar_typst.c",
    "internal/cbm/grammar_verilog.c",
    "internal/cbm/grammar_vhdl.c",
    "internal/cbm/grammar_vim.c",
    "internal/cbm/grammar_vue.c",
    "internal/cbm/grammar_wgsl.c",
    "internal/cbm/grammar_wit.c",
    "internal/cbm/grammar_wolfram.c",
    "internal/cbm/grammar_xml.c",
    "internal/cbm/grammar_yaml.c",
    "internal/cbm/grammar_zig.c",
    "internal/cbm/grammar_zsh.c",
};

const engine_include_dirs = [_][]const u8{
    "src",
    "vendored",
    "vendored/sqlite3",
    "vendored/mimalloc/include",
    "internal/cbm",
    "internal/cbm/vendored/ts_runtime/include",
    "internal/cbm/vendored/ts_runtime/src",
    "internal/cbm/vendored/zstd",
};

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const exe = b.addExecutable(.{
        .name = "codebase-memory-zig",
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/main.zig"),
            .target = target,
            .optimize = optimize,
        }),
    });
    b.installArtifact(exe);

    const run_cmd = b.addRunArtifact(exe);
    run_cmd.step.dependOn(b.getInstallStep());
    if (b.args) |args| run_cmd.addArgs(args);
    const run_step = b.step("run", "Run the MCP server on stdio");
    run_step.dependOn(&run_cmd.step);

    const tests = b.addTest(.{
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/main.zig"),
            .target = target,
            .optimize = optimize,
        }),
    });
    // Calibration slice: minhash.zig parity tests link a whitebox C oracle
    // (src/simhash/oracle_shim.c, which #includes the vendored minhash.c
    // directly) compiled for the native (test) target. Test-only — not part
    // of any shipped artifact.
    tests.root_module.link_libc = true;
    tests.root_module.addIncludePath(b.path("reference/upstream-c/src"));
    tests.root_module.addIncludePath(b.path("reference/upstream-c/vendored"));
    tests.root_module.addIncludePath(b.path("reference/upstream-c/internal/cbm/vendored/ts_runtime/include"));
    tests.root_module.addCSourceFile(.{
        .file = b.path("src/simhash/oracle_shim.c"),
        .flags = &.{"-std=c11"},
    });

    // popen_guard tests: rename-flagged compat_fs.c (POSIX-only symbols needed:
    // cbm_popen/cbm_pclose/cbm_canonical_path) + walk_guard.c + popen_guard.c +
    // the C test entry points, all compiled for the native test target. Mirrors
    // the oracle_shim wiring above. Skipped on Windows targets (the guard's
    // process-group/fork machinery is POSIX-only; the file itself #ifdefs a
    // Windows path but this repo's tests always run on the native/WSL host).
    if (target.result.os.tag != .windows) {
        tests.root_module.addIncludePath(b.path("src/cshim"));
        tests.root_module.addCSourceFile(.{
            .file = b.path("reference/upstream-c/src/foundation/compat_fs.c"),
            .flags = catFlags(b, catFlags(b, &engine_c_extra_flags, &.{walkguard_rename_flag}), &popenguard_rename_flags),
        });
        tests.root_module.addCSourceFiles(.{
            .files = &.{ "src/cshim/walk_guard.c", "src/cshim/popen_guard.c", "src/cshim/popen_guard_test.c" },
            .flags = &engine_c_extra_flags,
        });
        tests.root_module.linkSystemLibrary("pthread", .{});
    }

    const run_tests = b.addRunArtifact(tests);
    const test_step = b.step("test", "Run unit tests");
    test_step.dependOn(&run_tests.step);

    // ---- Phase 3: vendored C engine cross-compiled to a static lib -------------
    // Always targets the Debian-12 / glibc-2.36 Linux shim, independent of the host
    // build's -Dtarget, since this is what the shim environment needs regardless of
    // what platform `zig build` is invoked on.
    const engine_lib = buildEngineLib(b, "x86_64-linux-gnu.2.36", "cbmengine", optimize, false);

    // NOTE: engine/hybrid artifacts are attached ONLY to their named steps (below),
    // never to the default install step — otherwise `zig build` would cross-compile
    // the entire ~400MB C engine (x3 for the two hybrids) on every invocation.
    const engine_step = b.step("engine", "Cross-compile the vendored C engine to a static lib for the Linux shim target");
    engine_step.dependOn(&b.addInstallArtifact(engine_lib, .{}).step);

    // ---- Phase 4a/4b: hybrid binary (Zig stdio harness + vendored C engine) ----
    // Two variants: deploy (glibc 2.36, matches the shim host) and test (glibc
    // 2.35, matches this dev box's WSL Ubuntu for smoke-testing under `wsl.exe`).
    addHybridExe(b, "x86_64-linux-gnu.2.36", "cbmengine-hybrid", "codebase-memory-zig-hybrid", optimize, "hybrid", "Build the hybrid (Zig+C) MCP server, glibc 2.36 deploy target");
    addHybridExe(b, "x86_64-linux-gnu.2.35", "cbmengine-hybrid-test", "codebase-memory-zig-hybrid-test", optimize, "hybrid-test", "Build the hybrid (Zig+C) MCP server, glibc 2.35 (WSL Ubuntu) test target");
    addHybridExe(b, "x86_64-windows-gnu", "cbmengine-hybrid-win", "codebase-memory-zig-hybrid", optimize, "hybrid-win", "Build the hybrid (Zig+C) MCP server for the Windows host lane (.exe)");
}

/// Build the vendored C engine (Phase 3 sources) as a static lib for `triple`.
/// `for_hybrid`: when true, additionally compiles the MCP delegation-seam
/// sources (mcp.c, index_supervisor.c, compact_out.c) plus the extra vendored
/// sources needed to resolve their symbols, and applies the walk_guard rename
/// flag to compat_fs.c so `src/cshim/walk_guard.c` becomes the sole
/// `cbm_opendir` chokepoint (Stage 4b).
fn buildEngineLib(b: *std.Build, triple: []const u8, name: []const u8, optimize: std.builtin.OptimizeMode, for_hybrid: bool) *std.Build.Step.Compile {
    const target_query = std.Target.Query.parse(.{ .arch_os_abi = triple }) catch @panic("bad engine target triple");
    const target = b.resolveTargetQuery(target_query);

    // Per-target base C flags: Windows (MinGW) drops -D_GNU_SOURCE (see
    // win_engine_flags). eflags is the common base; gflags adds -UNDEBUG for
    // grammar TUs (some tree-sitter scanners #error under NDEBUG).
    const is_win = target.result.os.tag == .windows;
    const eflags: []const []const u8 = if (is_win) &win_engine_flags else &engine_c_extra_flags;
    // Grammars: base + -UNDEBUG (assertions on). On Windows also pre-set MinGW's
    // <sec_api/string_s.h> include guard (_INC_STRING_S) so its __forceinline
    // secure-string helpers (strnlen_s/wcsnlen_s) aren't defined — Clang otherwise
    // emits an out-of-line gnu_inline copy in each grammar TU that pulls <string.h>,
    // colliding at link. Grammar scanners never call the Annex K _s functions, so
    // this is safe and scoped to grammars only (the core engine keeps them).
    const gflags: []const []const u8 = if (is_win)
        catFlags(b, eflags, &.{ "-UNDEBUG", "-D_INC_STRING_S" })
    else
        catFlags(b, eflags, &.{"-UNDEBUG"});

    const lib = b.addLibrary(.{
        .name = name,
        .linkage = .static,
        .root_module = b.createModule(.{
            .target = target,
            .optimize = optimize,
            .link_libc = true,
            .link_libcpp = true,
        }),
    });

    const upstream_c = "reference/upstream-c/";

    var include_paths: [engine_include_dirs.len]std.Build.LazyPath = undefined;
    for (engine_include_dirs, 0..) |dir, i| {
        include_paths[i] = b.path(b.fmt("{s}{s}", .{ upstream_c, dir }));
    }
    for (include_paths) |p| lib.root_module.addIncludePath(p);
    // mimalloc's static.c unity-includes sibling files with plain #include "x.c";
    // needs its own source dir on the include path too.
    lib.root_module.addIncludePath(b.path(upstream_c ++ "vendored/mimalloc/src"));
    if (for_hybrid) {
        // walk_guard.c lives outside reference/ and includes foundation/compat_fs.h.
        lib.root_module.addIncludePath(b.path("src/cshim"));
    }

    var c_paths: [engine_c_sources.len][]const u8 = undefined;
    for (engine_c_sources, 0..) |src, i| {
        c_paths[i] = b.fmt("{s}{s}", .{ upstream_c, src });
    }
    lib.root_module.addCSourceFiles(.{
        .files = &c_paths,
        .flags = eflags,
    });

    if (for_hybrid) {
        // compat_fs.c is compiled SEPARATELY from the rest of engine_c_sources for
        // hybrid builds: it needs the -Dcbm_opendir=cbm_opendir_real rename flag
        // so walk_guard.c's cbm_opendir() (in src/cshim/walk_guard.c) becomes the
        // sole entry point; every other TU still calls the (unrenamed) symbol
        // `cbm_opendir`, which now resolves to walk_guard.c's wrapper.
        lib.root_module.addCSourceFile(.{
            .file = b.path(upstream_c ++ "src/foundation/compat_fs.c"),
            .flags = catFlags(b, catFlags(b, eflags, &.{walkguard_rename_flag}), &popenguard_rename_flags),
        });
        lib.root_module.addCSourceFile(.{
            .file = b.path("src/cshim/walk_guard.c"),
            .flags = eflags,
        });
        lib.root_module.addCSourceFile(.{
            .file = b.path("src/cshim/popen_guard.c"),
            .flags = eflags,
        });

        var mcp_paths: [mcp_c_sources.len][]const u8 = undefined;
        for (mcp_c_sources, 0..) |src, i| mcp_paths[i] = b.fmt("{s}{s}", .{ upstream_c, src });
        lib.root_module.addCSourceFiles(.{ .files = &mcp_paths, .flags = eflags });

        var extra_paths: [hybrid_extra_c_sources.len][]const u8 = undefined;
        for (hybrid_extra_c_sources, 0..) |src, i| extra_paths[i] = b.fmt("{s}{s}", .{ upstream_c, src });
        lib.root_module.addCSourceFiles(.{ .files = &extra_paths, .flags = eflags });

        // Minimal replacements for CLI/UI symbols the vendored MCP layer references
        // but whose defining TUs (cli.c, ui/http_server.c) we don't compile. See
        // src/cshim/engine_stubs.c for why each stub's return value is correct.
        lib.root_module.addCSourceFile(.{
            .file = b.path("src/cshim/engine_stubs.c"),
            .flags = eflags,
        });
    } else {
        // Phase-3 `engine` step compiles the plain, unrenamed compat_fs.c (no
        // walk_guard involved — that step only proves the engine cross-compiles).
        lib.root_module.addCSourceFile(.{
            .file = b.path(upstream_c ++ "src/foundation/compat_fs.c"),
            .flags = eflags,
        });
    }

    // sqlite3.c needs its own extra defines on top of the common engine flags.
    lib.root_module.addCSourceFile(.{
        .file = b.path(upstream_c ++ "vendored/sqlite3/sqlite3.c"),
        .flags = catFlags(b, eflags, &.{ "-DSQLITE_DQS=0", "-DSQLITE_THREADSAFE=1", "-DSQLITE_ENABLE_FTS5" }),
    });

    // mimalloc static.c needs MI_OVERRIDE=1.
    lib.root_module.addCSourceFile(.{
        .file = b.path(upstream_c ++ "vendored/mimalloc/src/static.c"),
        .flags = catFlags(b, eflags, &.{"-DMI_OVERRIDE=1"}),
    });

    // Grammars: separate translation units (each grammar is compiled as its own
    // unit because they define conflicting static symbols). grammar_perl.c is
    // added separately below with the bsearch rename flag.
    var grammar_paths: [engine_grammar_sources.len][]const u8 = undefined;
    for (engine_grammar_sources, 0..) |src, i| {
        grammar_paths[i] = b.fmt("{s}{s}", .{ upstream_c, src });
    }
    lib.root_module.addCSourceFiles(.{
        .files = &grammar_paths,
        .flags = gflags,
    });

    // preprocessor.cpp — the one C++ unit (unity-includes vendored/simplecpp).
    lib.root_module.addCSourceFile(.{
        .file = b.path(upstream_c ++ "internal/cbm/preprocessor.cpp"),
        .flags = &[_][]const u8{ "-std=c++14", "-w", "-fno-sanitize=undefined" },
    });

    // grammar_perl.c — compiled with the bsearch rename (see perl_grammar_flag).
    lib.root_module.addCSourceFile(.{
        .file = b.path(upstream_c ++ "internal/cbm/grammar_perl.c"),
        .flags = &perl_grammar_flags,
    });

    // nomic-embed-code vector blob (PRETRAINED_VECTOR_BLOB, referenced by
    // semantic.c). Preprocessed assembly that `.incbin`s vendored/nomic/
    // code_vectors.bin, so the assembler needs reference/upstream-c on its
    // include search path for that relative path to resolve.
    lib.root_module.addCSourceFile(.{
        .file = b.path(upstream_c ++ "vendored/nomic/code_vectors_blob.S"),
        .flags = &[_][]const u8{"-I" ++ upstream_c},
    });

    return lib;
}

fn addHybridExe(b: *std.Build, triple: []const u8, lib_name: []const u8, exe_name: []const u8, optimize: std.builtin.OptimizeMode, step_name: []const u8, step_desc: []const u8) void {
    const engine_lib = buildEngineLib(b, triple, lib_name, optimize, true);

    const target_query = std.Target.Query.parse(.{ .arch_os_abi = triple }) catch @panic("bad hybrid target triple");
    const target = b.resolveTargetQuery(target_query);

    const exe = b.addExecutable(.{
        .name = exe_name,
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/main_hybrid.zig"),
            .target = target,
            .optimize = optimize,
            .link_libc = true,
            .link_libcpp = true,
        }),
    });
    exe.root_module.addIncludePath(b.path("reference/upstream-c/src"));
    exe.root_module.linkLibrary(engine_lib);
    // libm / libpthread are POSIX; on Windows math is in the CRT and threading is
    // Win32 (the engine's compat layer handles it). Only link them off-Windows.
    if (target.result.os.tag != .windows) {
        exe.root_module.linkSystemLibrary("m", .{});
        exe.root_module.linkSystemLibrary("pthread", .{});
    }

    // Attach only to the named step (not the default install) — see note in build().
    const step = b.step(step_name, step_desc);
    step.dependOn(&b.addInstallArtifact(exe, .{}).step);
}