@scriptc/compiler 0.0.34 → 0.0.36

package/dist/backend/{cc-cache.test.js → native-toolchain.test.js}

@@ -5,7 +5,8 @@ import { chmod, cp, mkdir, mkdtemp, readdir, readFile, rm, stat, symlink, utimes
 import { tmpdir } from "node:os";
 import { delimiter, join } from "node:path";
 import { afterAll, afterEach, expect, test as vitestTest } from "vitest";
-import { cacheTargetIdentity, ccVersionOnce, compileC, compileLibArchive, implicitDependencyProbeIncludes, parseLinkTraceFiles, resolveBuildCacheRoot, runtimeFingerprint, runtimeSrcDir, stageRuntimeObjects, toolchainEnvironmentCachePolicy, toolchainEnvironmentFingerprint, vendorCacheBuildIdentity, vendorCacheTargetFlavor, } from "./cc.js";
+import { cacheTargetIdentity, ccVersion, compileC, compileLibArchive, executableSectionEliminationFlags, executableNativeEnvironmentFingerprint, implicitDependencyProbeIncludes, parseLinkTraceFiles, resolveBuildCacheRoot, runtimeFingerprint, runtimeSrcDir, stageRuntimeObjects, supportedNativeCacheWarmProfiles, toolchainEnvironmentCachePolicy, toolchainEnvironmentFingerprint, vendorCacheBuildIdentity, vendorCacheTargetFlavor, warmNativeCaches, } from "./native-toolchain.js";
+import { splitLlvmProgram } from "./llvm/split.js";
 const scratch = [];
 const TEST_CACHE_IDENTITY = "cc-cache-tests-v1";
 const originalStableToolchain = process.env["SCRIPTC_TEST_STABLE_TOOLCHAIN"];
@@ -41,10 +42,20 @@ const test = Object.assign((name, ...args) => Reflect.apply(cacheTestSelected(na
 const trustInstrumentedCompilerWrapper = () => {
     process.env["SCRIPTC_TEST_TRUST_COMPILER_WRAPPER"] = "1";
 };
-const zigExecutable = (process.env["PATH"] ?? "")
+const executableOnPath = (name) => (process.env["PATH"] ?? "")
     .split(delimiter)
-    .map((entry) => join(entry === "" ? process.cwd() : entry, "zig"))
+    .map((entry) => join(entry === "" ? process.cwd() : entry, name))
     .find((candidate) => existsSync(candidate));
+const zigExecutable = executableOnPath("zig");
+const clangExecutable = executableOnPath("clang");
+const arExecutable = executableOnPath("ar");
+const ldExecutable = executableOnPath("ld");
+const objcopyExecutable = executableOnPath("objcopy");
+const nativeShardMergeAvailable = process.platform === "darwin"
+    ? ldExecutable !== undefined
+    : process.platform === "linux"
+        ? ldExecutable !== undefined && objcopyExecutable !== undefined
+        : process.platform === "win32" && process.arch === "x64";
 const completeArtifacts = async (root, kind) => (await readdir(join(root, kind))).filter((name) => !name.endsWith(".sha256"));
 const cacheTreeBytes = async (root) => {
     let total = 0;
@@ -85,6 +96,51 @@ test("the production cache root follows overrides, platform defaults, and the ha
     expect(resolveBuildCacheRoot({}, "darwin", "/Users/tester")).toBe("/Users/tester/Library/Caches/scriptc/build");
     expect(resolveBuildCacheRoot({ LOCALAPPDATA: "/Users/tester/AppData/Local" }, "win32", "/Users/tester")).toBe("/Users/tester/AppData/Local/scriptc/cache/build");
 });
+test("executable section elimination flags are target-aware and never enter library recipes", () => {
+    expect(executableSectionEliminationFlags("darwin")).toEqual({
+        compile: [],
+        link: ["-Wl,-dead_strip"],
+    });
+    expect(executableSectionEliminationFlags("linux")).toEqual({
+        compile: ["-ffunction-sections", "-fdata-sections"],
+        link: ["-Wl,--gc-sections"],
+    });
+    expect(executableSectionEliminationFlags("win32")).toEqual({
+        compile: ["-ffunction-sections", "-fdata-sections"],
+        link: ["-Wl,--gc-sections"],
+    });
+    expect(executableSectionEliminationFlags("wasi")).toEqual({ compile: [], link: [] });
+});
+test.skipIf(process.platform === "win32")("the early executable identity follows a compiler selected behind a stable driver", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-effective-compiler-"));
+    scratch.push(dir);
+    const binDir = join(dir, "bin");
+    const selector = join(dir, "selected");
+    const firstCompiler = join(dir, "clang-first");
+    const secondCompiler = join(dir, "clang-second");
+    await mkdir(binDir);
+    await Promise.all([
+        writeFile(firstCompiler, "#!/bin/sh\nexit 0\n"),
+        writeFile(secondCompiler, "#!/bin/sh\nexit 0\n"),
+        writeFile(join(binDir, "clang"), "#!/bin/sh\nselected=$(cat \"$SCRIPTC_TEST_EFFECTIVE_COMPILER\")\nprintf '\"%s\" \"-cc1\"\\n' \"$selected\" >&2\n"),
+        writeFile(selector, `${firstCompiler}\n`),
+    ]);
+    await Promise.all([
+        chmod(firstCompiler, 0o755),
+        chmod(secondCompiler, 0o755),
+        chmod(join(binDir, "clang"), 0o755),
+    ]);
+    const env = {
+        ...process.env,
+        PATH: `${binDir}${delimiter}${process.env["PATH"] ?? ""}`,
+        SCRIPTC_TEST_EFFECTIVE_COMPILER: selector,
+    };
+    const first = await executableNativeEnvironmentFingerprint(env);
+    expect(await executableNativeEnvironmentFingerprint(env)).toBe(first);
+    await writeFile(selector, `${secondCompiler}\n`);
+    const second = await executableNativeEnvironmentFingerprint(env);
+    expect(second).not.toBe(first);
+});
 test("native cache identities separate host architectures while cross targets remain explicit", () => {
     expect(cacheTargetIdentity({ target: null }, "darwin", "arm64")).toBe("native:darwin:arm64");
     expect(cacheTargetIdentity({ target: null }, "darwin", "x64")).toBe("native:darwin:x64");
@@ -93,6 +149,95 @@ test("native cache identities separate host architectures while cross targets re
     expect(vendorCacheTargetFlavor({ target: null }, "darwin", "x64")).toBe("native-darwin-x64");
     expect(vendorCacheTargetFlavor({ target: "x86_64-linux-gnu.2.36" }, "darwin", "arm64")).toBe("x86_64-linux-gnu.2.36");
 });
+test.skipIf(process.platform === "win32" || zigExecutable === undefined ||
+    clangExecutable === undefined || arExecutable === undefined)("targetless Zig vendor caches are separate from host-clang and reusable", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-zig-vendor-cache-"));
+    scratch.push(dir);
+    const cacheRoot = join(dir, "cache");
+    const vendorRoot = join(dir, "vendor-cache");
+    const cPath = join(dir, "program.c");
+    const oldCacheDir = process.env["SCRIPTC_CACHE_DIR"];
+    const oldNoCache = process.env["SCRIPTC_NO_CACHE"];
+    const oldVendorCacheDir = process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"];
+    const oldCc = process.env["SCRIPTC_CC"];
+    const oldTarget = process.env["SCRIPTC_TARGET"];
+    try {
+        await writeFile(cPath, "int main(void) { return 0; }\n");
+        process.env["SCRIPTC_CACHE_DIR"] = cacheRoot;
+        process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"] = vendorRoot;
+        delete process.env["SCRIPTC_NO_CACHE"];
+        delete process.env["SCRIPTC_TARGET"];
+        process.env["SCRIPTC_CC"] = "clang";
+        await compileC({
+            cPath,
+            outPath: join(dir, "host"),
+            cacheIdentity: TEST_CACHE_IDENTITY,
+            dynamic: true,
+            net: true,
+            http: true,
+            tls: true,
+            zlib: true,
+            // Keep the complete executable tier out of this test: the second Zig
+            // invocation must walk the vendor cache and prove its artifacts are
+            // reusable independently of the output path.
+            systemLibraries: ["m"],
+        });
+        const hostEngine = (await readdir(vendorRoot)).find((name) => /^3c8f3d689539-plain-/.test(name));
+        const hostTls = (await readdir(vendorRoot)).find((name) => name.startsWith("mbedtls-"));
+        expect(hostEngine).toBeDefined();
+        expect(hostTls).toBeDefined();
+        process.env["SCRIPTC_CC"] = "zigcc";
+        const zigOptions = {
+            cPath,
+            cacheIdentity: TEST_CACHE_IDENTITY,
+            dynamic: true,
+            net: true,
+            http: true,
+            tls: true,
+            zlib: true,
+            systemLibraries: ["m"],
+        };
+        await compileC({ ...zigOptions, outPath: join(dir, "zig-first") });
+        let vendorEntries = await readdir(vendorRoot);
+        expect(vendorEntries.filter((name) => /^3c8f3d689539-plain-/.test(name))).toHaveLength(2);
+        expect(vendorEntries.filter((name) => name.startsWith("mbedtls-")).length).toBe(2);
+        // Host clang uses system zlib, so only the Zig build materializes a zlib
+        // object family in the shared vendor root.
+        expect(vendorEntries.filter((name) => name.startsWith("zlib-")).length).toBe(1);
+        // Invalidate the host archive. A targetless Zig rebuild must continue to
+        // use the separately keyed Zig archive instead of repairing or consuming
+        // the host-clang entry.
+        await writeFile(join(vendorRoot, hostEngine, "libqjs.a"), "host archive intentionally invalid\n");
+        await writeFile(join(vendorRoot, hostTls, "libmbedtls.a"), "host archive intentionally invalid\n");
+        await compileC({ ...zigOptions, outPath: join(dir, "zig-second") });
+        vendorEntries = await readdir(vendorRoot);
+        expect(vendorEntries.filter((name) => /^3c8f3d689539-plain-/.test(name))).toHaveLength(2);
+        expect(await readFile(join(vendorRoot, hostEngine, "libqjs.a"), "utf8")).toBe("host archive intentionally invalid\n");
+        expect(await readFile(join(vendorRoot, hostTls, "libmbedtls.a"), "utf8")).toBe("host archive intentionally invalid\n");
+    }
+    finally {
+        if (oldCacheDir === undefined)
+            delete process.env["SCRIPTC_CACHE_DIR"];
+        else
+            process.env["SCRIPTC_CACHE_DIR"] = oldCacheDir;
+        if (oldNoCache === undefined)
+            delete process.env["SCRIPTC_NO_CACHE"];
+        else
+            process.env["SCRIPTC_NO_CACHE"] = oldNoCache;
+        if (oldVendorCacheDir === undefined)
+            delete process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"];
+        else
+            process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"] = oldVendorCacheDir;
+        if (oldCc === undefined)
+            delete process.env["SCRIPTC_CC"];
+        else
+            process.env["SCRIPTC_CC"] = oldCc;
+        if (oldTarget === undefined)
+            delete process.env["SCRIPTC_TARGET"];
+        else
+            process.env["SCRIPTC_TARGET"] = oldTarget;
+    }
+}, 600_000);
 test("Zig COFF dry-run parsing retains every linker input on its single command line", async () => {
     const dir = await mkdtemp(join(tmpdir(), "scriptc-link-trace-"));
     scratch.push(dir);
@@ -142,9 +287,11 @@ test("the toolchain environment joins cache identities", () => {
         completeArtifacts: false,
         runtimeObjects: false,
     });
+    // scriptc invokes its compiler and archiver directly; conventional build-
+    // system variables do not alter those commands.
     expect(toolchainEnvironmentCachePolicy({ CFLAGS: "-I/headers" })).toEqual({
-        completeArtifacts: false,
-        runtimeObjects: false,
+        completeArtifacts: true,
+        runtimeObjects: true,
     });
     expect(toolchainEnvironmentCachePolicy({ ZIG_LIB_DIR: "/zig/lib" })).toEqual({
         completeArtifacts: false,
@@ -154,8 +301,9 @@ test("the toolchain environment joins cache identities", () => {
         completeArtifacts: false,
         runtimeObjects: false,
     });
-    expect(vendorCacheBuildIdentity(base, "compiler-one")).not.toBe(vendorCacheBuildIdentity(base, "compiler-two"));
-    expect(vendorCacheBuildIdentity(base, "compiler-one")).not.toBe(vendorCacheBuildIdentity(toolchainEnvironmentFingerprint({ MACOSX_DEPLOYMENT_TARGET: "11.0" }), "compiler-one"));
+    expect(vendorCacheBuildIdentity(base, "compiler-one", "sources-one")).not.toBe(vendorCacheBuildIdentity(base, "compiler-two", "sources-one"));
+    expect(vendorCacheBuildIdentity(base, "compiler-one", "sources-one")).not.toBe(vendorCacheBuildIdentity(toolchainEnvironmentFingerprint({ MACOSX_DEPLOYMENT_TARGET: "11.0" }), "compiler-one", "sources-one"));
+    expect(vendorCacheBuildIdentity(base, "compiler-one", "sources-one")).not.toBe(vendorCacheBuildIdentity(base, "compiler-one", "sources-two"));
 });
 test.skipIf(process.platform === "win32")("compiler version probes use and remove a private working directory", async () => {
     const dir = await mkdtemp(join(tmpdir(), "scriptc-version-probe-"));
@@ -174,7 +322,7 @@ printf 'fake zig cc version probe\n'
         // Zig 0.16 creates cwd/a.o for `zig cc --version`. Model that side
         // effect directly so this regression does not depend on Zig being
         // installed in every generic test shard.
-        await ccVersionOnce([fakeCompiler, "cc"], `version-probe-${dir}`);
+        await ccVersion([fakeCompiler, "cc"], `version-probe-${dir}`);
         expect(await readdir(probeTmp)).toEqual([]);
     }
     finally {
@@ -305,6 +453,69 @@ test("implicit dependency seeds include separately compiled vendor system header
     // to the native object/cache identity.
     expect(includes).toContain("<stdatomic.h>");
 });
+test.skipIf(process.platform === "win32" || clangExecutable === undefined || arExecutable === undefined ||
+    ldExecutable === undefined)("public native builds re-probe ccache availability after PATH changes", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-ccache-reset-"));
+    scratch.push(dir);
+    const binDir = join(dir, "bin");
+    const cacheRoot = join(dir, "cache");
+    const cPath = join(dir, "program.c");
+    const ccacheLog = join(dir, "ccache.log");
+    const oldCacheDir = process.env["SCRIPTC_CACHE_DIR"];
+    const oldNoCache = process.env["SCRIPTC_NO_CACHE"];
+    const oldPath = process.env["PATH"];
+    const oldCcacheLog = process.env["SCRIPTC_TEST_CCACHE_LOG"];
+    try {
+        await Promise.all([mkdir(binDir), mkdir(cacheRoot, { mode: 0o700 })]);
+        await Promise.all([
+            symlink(clangExecutable, join(binDir, "clang")),
+            symlink(arExecutable, join(binDir, "ar")),
+            symlink(ldExecutable, join(binDir, "ld")),
+            writeFile(cPath, "int main(void) { return 0; }\n"),
+        ]);
+        process.env["SCRIPTC_CACHE_DIR"] = cacheRoot;
+        process.env["PATH"] = binDir;
+        delete process.env["SCRIPTC_NO_CACHE"];
+        await compileC({
+            cPath,
+            outPath: join(dir, "first"),
+            cacheIdentity: TEST_CACHE_IDENTITY,
+            regex: true,
+        });
+        await writeFile(join(binDir, "ccache"), `#!/bin/sh
+if [ "$1" = "--version" ]; then exit 0; fi
+printf '%s\n' "$*" >> "$SCRIPTC_TEST_CCACHE_LOG"
+exec "$@"
+`);
+        await chmod(join(binDir, "ccache"), 0o755);
+        process.env["SCRIPTC_TEST_CCACHE_LOG"] = ccacheLog;
+        await compileC({
+            cPath,
+            outPath: join(dir, "second"),
+            cacheIdentity: TEST_CACHE_IDENTITY,
+            dynamic: true,
+        });
+        expect((await readFile(ccacheLog, "utf8")).trim()).not.toBe("");
+    }
+    finally {
+        if (oldCacheDir === undefined)
+            delete process.env["SCRIPTC_CACHE_DIR"];
+        else
+            process.env["SCRIPTC_CACHE_DIR"] = oldCacheDir;
+        if (oldNoCache === undefined)
+            delete process.env["SCRIPTC_NO_CACHE"];
+        else
+            process.env["SCRIPTC_NO_CACHE"] = oldNoCache;
+        if (oldPath === undefined)
+            delete process.env["PATH"];
+        else
+            process.env["PATH"] = oldPath;
+        if (oldCcacheLog === undefined)
+            delete process.env["SCRIPTC_TEST_CCACHE_LOG"];
+        else
+            process.env["SCRIPTC_TEST_CCACHE_LOG"] = oldCcacheLog;
+    }
+});
 test.skipIf(process.platform === "win32")("opaque compiler wrappers bypass persistent caches", async () => {
     const dir = await mkdtemp(join(tmpdir(), "scriptc-cache-compiler-wrapper-"));
     scratch.push(dir);
@@ -1682,41 +1893,46 @@ test("the hard disable bypasses vendor prerequisite caches", async () => {
             process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"] = oldVendorCacheDir;
     }
 });
-test.skipIf(process.platform !== "darwin")("vendor object caches separate deployment-target environments", async () => {
-    const dir = await mkdtemp(join(tmpdir(), "scriptc-vendor-environment-"));
+test.skipIf(process.platform === "win32")("shared vendor prerequisites re-key when vendored source bytes change", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-vendor-source-identity-"));
     scratch.push(dir);
     const cacheRoot = join(dir, "cache");
-    const vendorCacheRoot = join(dir, "vendor-cache");
+    const fakeRuntimeRoot = join(dir, "runtime");
+    const fakeRuntime = join(fakeRuntimeRoot, "src");
+    const originalRuntime = runtimeSrcDir();
     const cPath = join(dir, "program.c");
     const oldCacheDir = process.env["SCRIPTC_CACHE_DIR"];
     const oldNoCache = process.env["SCRIPTC_NO_CACHE"];
+    const oldRuntimeDir = process.env["SCRIPTC_TEST_RUNTIME_SRC_DIR"];
     const oldVendorCacheDir = process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"];
-    const oldDeploymentTarget = process.env["MACOSX_DEPLOYMENT_TARGET"];
     try {
+        await Promise.all([
+            cp(originalRuntime, fakeRuntime, { recursive: true }),
+            mkdir(join(fakeRuntimeRoot, "vendor"), { recursive: true }).then(() => Promise.all(["quickjs-ng", "ryu"].map((name) => cp(join(originalRuntime, "..", "vendor", name), join(fakeRuntimeRoot, "vendor", name), { recursive: true })))),
+        ]);
         process.env["SCRIPTC_CACHE_DIR"] = cacheRoot;
-        process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"] = vendorCacheRoot;
+        process.env["SCRIPTC_TEST_RUNTIME_SRC_DIR"] = fakeRuntime;
         delete process.env["SCRIPTC_NO_CACHE"];
+        delete process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"];
         await writeFile(cPath, "int main(void) { return 0; }\n");
-        process.env["MACOSX_DEPLOYMENT_TARGET"] = "14.0";
         await compileC({
             cPath,
-            outPath: join(dir, "newer"),
+            outPath: join(dir, "first"),
             cacheIdentity: TEST_CACHE_IDENTITY,
             regex: true,
         });
-        process.env["MACOSX_DEPLOYMENT_TARGET"] = "11.0";
+        const vendorRoot = join(cacheRoot, "vendor");
+        expect((await readdir(vendorRoot)).filter((name) => name.includes("-lre-"))).toHaveLength(1);
+        const libregexp = join(fakeRuntimeRoot, "vendor", "quickjs-ng", "libregexp.c");
+        await writeFile(libregexp, `${await readFile(libregexp, "utf8")}\n/* cache identity probe */\n`);
+        await writeFile(cPath, "int main(void) { return 0; } /* second */\n");
         await compileC({
             cPath,
-            outPath: join(dir, "older"),
+            outPath: join(dir, "second"),
             cacheIdentity: TEST_CACHE_IDENTITY,
             regex: true,
         });
-        const lreCaches = (await readdir(vendorCacheRoot)).filter((name) => name.includes("-lre-"));
-        expect(lreCaches).toHaveLength(2);
-        const minVersions = lreCaches.map((cache) => execFileSync("vtool", ["-show-build", join(vendorCacheRoot, cache, "libregexp.o")], {
-            encoding: "utf8",
-        }).match(/minos\s+(\S+)/)?.[1]);
-        expect(new Set(minVersions)).toEqual(new Set(["11.0", "14.0"]));
+        expect((await readdir(vendorRoot)).filter((name) => name.includes("-lre-"))).toHaveLength(2);
     }
     finally {
         if (oldCacheDir === undefined)
@@ -1727,56 +1943,48 @@ test.skipIf(process.platform !== "darwin")("vendor object caches separate deploy
             delete process.env["SCRIPTC_NO_CACHE"];
         else
             process.env["SCRIPTC_NO_CACHE"] = oldNoCache;
+        if (oldRuntimeDir === undefined)
+            delete process.env["SCRIPTC_TEST_RUNTIME_SRC_DIR"];
+        else
+            process.env["SCRIPTC_TEST_RUNTIME_SRC_DIR"] = oldRuntimeDir;
         if (oldVendorCacheDir === undefined)
             delete process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"];
         else
             process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"] = oldVendorCacheDir;
-        if (oldDeploymentTarget === undefined)
-            delete process.env["MACOSX_DEPLOYMENT_TARGET"];
-        else
-            process.env["MACOSX_DEPLOYMENT_TARGET"] = oldDeploymentTarget;
     }
-});
-test("complete binary hits precede missing vendor prerequisite materialization", async () => {
-    const dir = await mkdtemp(join(tmpdir(), "scriptc-cache-vendor-hit-"));
+}, 120_000);
+test.skipIf(process.platform === "win32")("uncached arbitrary C keeps vendor prerequisites outside a read-only runtime package", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-readonly-runtime-"));
     scratch.push(dir);
-    const cacheRoot = join(dir, "cache");
-    const vendorCacheRoot = join(dir, "vendor-cache");
+    const fakeRuntimeRoot = join(dir, "runtime");
+    const fakeRuntime = join(fakeRuntimeRoot, "src");
+    const fakeVendor = join(fakeRuntimeRoot, "vendor");
+    const originalRuntime = runtimeSrcDir();
     const cPath = join(dir, "program.c");
     const oldCacheDir = process.env["SCRIPTC_CACHE_DIR"];
     const oldNoCache = process.env["SCRIPTC_NO_CACHE"];
+    const oldRuntimeDir = process.env["SCRIPTC_TEST_RUNTIME_SRC_DIR"];
     const oldVendorCacheDir = process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"];
     try {
-        process.env["SCRIPTC_CACHE_DIR"] = cacheRoot;
-        process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"] = vendorCacheRoot;
+        await Promise.all([
+            cp(originalRuntime, fakeRuntime, { recursive: true }),
+            mkdir(fakeVendor, { recursive: true }).then(() => Promise.all(["quickjs-ng", "ryu"].map((name) => cp(join(originalRuntime, "..", "vendor", name), join(fakeVendor, name), {
+                recursive: true,
+            })))),
+        ]);
+        process.env["SCRIPTC_CACHE_DIR"] = join(dir, "cache");
+        process.env["SCRIPTC_TEST_RUNTIME_SRC_DIR"] = fakeRuntime;
         delete process.env["SCRIPTC_NO_CACHE"];
-        await writeFile(cPath, '#include <stdio.h>\nint main(void) { puts("cached"); return 0; }\n');
-        const firstOut = join(dir, "first");
-        await compileC({
-            cPath,
-            outPath: firstOut,
-            cacheIdentity: TEST_CACHE_IDENTITY,
-            regex: true,
-        });
-        expect(execFileSync(firstOut, { encoding: "utf8" }).trim()).toBe("cached");
-        expect(await completeArtifacts(cacheRoot, "bin")).toHaveLength(1);
-        expect((await stat(vendorCacheRoot)).isDirectory()).toBe(true);
-        // Simulate a package reinstall: the per-package vendor build disappears,
-        // while the per-user complete executable remains. The hit must not
-        // recreate that directory even though the compiler remains available for
-        // fresh dependency discovery.
-        await rm(vendorCacheRoot, { recursive: true, force: true });
-        const hitOut = firstOut;
-        await compileC({
-            cPath,
-            outPath: hitOut,
-            cacheIdentity: TEST_CACHE_IDENTITY,
-            regex: true,
-        });
-        expect(execFileSync(hitOut, { encoding: "utf8" }).trim()).toBe("cached");
-        await expect(stat(vendorCacheRoot)).rejects.toMatchObject({ code: "ENOENT" });
+        delete process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"];
+        await writeFile(cPath, "int main(void) { return 0; }\n");
+        await chmod(fakeVendor, 0o555);
+        const outPath = join(dir, "program");
+        await compileC({ cPath, outPath, regex: true });
+        expect((await stat(outPath)).isFile()).toBe(true);
+        await expect(stat(join(fakeVendor, ".cache"))).rejects.toMatchObject({ code: "ENOENT" });
     }
     finally {
+        await chmod(fakeVendor, 0o755).catch(() => undefined);
         if (oldCacheDir === undefined)
             delete process.env["SCRIPTC_CACHE_DIR"];
         else
@@ -1785,37 +1993,41 @@ test("complete binary hits precede missing vendor prerequisite materialization",
             delete process.env["SCRIPTC_NO_CACHE"];
         else
             process.env["SCRIPTC_NO_CACHE"] = oldNoCache;
+        if (oldRuntimeDir === undefined)
+            delete process.env["SCRIPTC_TEST_RUNTIME_SRC_DIR"];
+        else
+            process.env["SCRIPTC_TEST_RUNTIME_SRC_DIR"] = oldRuntimeDir;
         if (oldVendorCacheDir === undefined)
             delete process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"];
         else
             process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"] = oldVendorCacheDir;
     }
-});
-test("arbitrary C bypasses persistent artifacts so same-path header edits cannot go stale", async () => {
-    const dir = await mkdtemp(join(tmpdir(), "scriptc-arbitrary-c-cache-"));
+}, 120_000);
+test("native cache warming seeds exact runtime and vendor families without complete binaries", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-cache-warm-"));
     scratch.push(dir);
     const cacheRoot = join(dir, "cache");
-    const cPath = join(dir, "program.c");
-    const headerPath = join(dir, "value.h");
+    const vendorCacheRoot = join(cacheRoot, "vendor");
     const oldCacheDir = process.env["SCRIPTC_CACHE_DIR"];
     const oldNoCache = process.env["SCRIPTC_NO_CACHE"];
+    const oldVendorCacheDir = process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"];
     try {
         process.env["SCRIPTC_CACHE_DIR"] = cacheRoot;
+        delete process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"];
         delete process.env["SCRIPTC_NO_CACHE"];
-        await writeFile(cPath, '#include <stdio.h>\n#include "value.h"\nint main(void) { puts(VALUE); return 0; }\n');
-        await writeFile(headerPath, '#define VALUE "one"\n');
-        const firstOut = join(dir, "first");
-        await compileC({ cPath, outPath: firstOut });
-        expect(execFileSync(firstOut, { encoding: "utf8" }).trim()).toBe("one");
-        await writeFile(headerPath, '#define VALUE "two"\n');
-        const secondOut = join(dir, "second");
-        await compileC({ cPath, outPath: secondOut });
-        expect(execFileSync(secondOut, { encoding: "utf8" }).trim()).toBe("two");
-        await expect(stat(join(cacheRoot, "bin"))).rejects.toMatchObject({ code: "ENOENT" });
-        const archiveOut = join(dir, "program.lib.a");
-        await compileLibArchive({ cPath, outPath: archiveOut });
-        expect((await stat(archiveOut)).isFile()).toBe(true);
-        await expect(stat(join(cacheRoot, "lib"))).rejects.toMatchObject({ code: "ENOENT" });
+        const warmed = await warmNativeCaches({ profiles: ["runtime", "tls", "dynamic"] });
+        expect(warmed.cacheRoot).toBe(cacheRoot);
+        expect(warmed.profiles.map(({ profile }) => profile)).toEqual(["runtime", "tls", "dynamic"]);
+        expect(warmed.profiles.every(({ elapsedMs }) => elapsedMs >= 0)).toBe(true);
+        expect((await readdir(join(cacheRoot, "obj"), { withFileTypes: true })).filter((e) => e.isDirectory())).toHaveLength(3);
+        expect(await readdir(join(cacheRoot, "bin")).catch(() => [])).toEqual([]);
+        const vendorEntries = await readdir(vendorCacheRoot);
+        const tlsEntry = vendorEntries.find((name) => name.startsWith("mbedtls-"));
+        const engineEntry = vendorEntries.find((name) => /^3c8f3d689539-plain-/.test(name));
+        expect(tlsEntry).toBeDefined();
+        expect(engineEntry).toBeDefined();
+        expect((await stat(join(vendorCacheRoot, tlsEntry, "libmbedtls.a.sha256"))).isFile()).toBe(true);
+        expect((await stat(join(vendorCacheRoot, engineEntry, "libqjs.a.sha256"))).isFile()).toBe(true);
     }
     finally {
         if (oldCacheDir === undefined)
@@ -1826,34 +2038,44 @@ test("arbitrary C bypasses persistent artifacts so same-path header edits cannot
             delete process.env["SCRIPTC_NO_CACHE"];
         else
             process.env["SCRIPTC_NO_CACHE"] = oldNoCache;
+        if (oldVendorCacheDir === undefined)
+            delete process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"];
+        else
+            process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"] = oldVendorCacheDir;
     }
-});
-test("cached translation units keep the compiler-visible source path in their identity", async () => {
-    const dir = await mkdtemp(join(tmpdir(), "scriptc-cache-source-path-"));
+}, 120_000);
+test("damaged shared vendor archives are rejected and rebuilt before linking", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-vendor-integrity-"));
     scratch.push(dir);
     const cacheRoot = join(dir, "cache");
-    const aPath = join(dir, "a.c");
-    const bPath = join(dir, "b.c");
-    const headerPath = join(dir, "cache_path_header.h");
-    const source = '#include <stdio.h>\n#include "cache_path_header.h"\nint main(void) { puts(__FILE__); puts(CACHE_PATH_HEADER); return 0; }\n';
+    const cPath = join(dir, "program.c");
+    const outPath = join(dir, "program");
     const oldCacheDir = process.env["SCRIPTC_CACHE_DIR"];
     const oldNoCache = process.env["SCRIPTC_NO_CACHE"];
+    const oldVendorCacheDir = process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"];
+    const corruption = Buffer.from("scriptc-corrupt-vendor-archive\n");
     try {
         process.env["SCRIPTC_CACHE_DIR"] = cacheRoot;
         delete process.env["SCRIPTC_NO_CACHE"];
-        await Promise.all([
-            writeFile(aPath, source),
-            writeFile(bPath, source),
-            writeFile(headerPath, '#define CACHE_PATH_HEADER "header"\n'),
-        ]);
-        const aOut = join(dir, "a-out", "program");
-        const bOut = join(dir, "b-out", "program");
-        await Promise.all([mkdir(join(dir, "a-out")), mkdir(join(dir, "b-out"))]);
-        await compileC({ cPath: aPath, outPath: aOut, cacheIdentity: TEST_CACHE_IDENTITY });
-        await compileC({ cPath: bPath, outPath: bOut, cacheIdentity: TEST_CACHE_IDENTITY });
-        expect(execFileSync(aOut, { encoding: "utf8" }).trim()).toBe(`${aPath}\nheader`);
-        expect(execFileSync(bOut, { encoding: "utf8" }).trim()).toBe(`${bPath}\nheader`);
-        expect(await completeArtifacts(cacheRoot, "bin")).toHaveLength(2);
+        delete process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"];
+        await writeFile(cPath, "int main(void) { return 0; }\n");
+        await warmNativeCaches({ profiles: ["dynamic"] });
+        const vendorRoot = join(cacheRoot, "vendor");
+        const engineDir = (await readdir(vendorRoot)).find((name) => /^3c8f3d689539-plain-/.test(name));
+        expect(engineDir).toBeDefined();
+        const engineArchive = join(vendorRoot, engineDir, "libqjs.a");
+        expect((await stat(`${engineArchive}.sha256`)).isFile()).toBe(true);
+        await writeFile(engineArchive, corruption);
+        await compileC({
+            cPath,
+            outPath,
+            cacheIdentity: TEST_CACHE_IDENTITY,
+            dynamic: true,
+        });
+        expect((await stat(outPath)).isFile()).toBe(true);
+        const repaired = await readFile(engineArchive);
+        expect(repaired).not.toEqual(corruption);
+        expect((await readFile(`${engineArchive}.sha256`, "utf8")).trim()).toBe(createHash("sha256").update(repaired).digest("hex"));
     }
     finally {
         if (oldCacheDir === undefined)
@@ -1864,36 +2086,358 @@ test("cached translation units keep the compiler-visible source path in their id
             delete process.env["SCRIPTC_NO_CACHE"];
         else
             process.env["SCRIPTC_NO_CACHE"] = oldNoCache;
+        if (oldVendorCacheDir === undefined)
+            delete process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"];
+        else
+            process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"] = oldVendorCacheDir;
     }
-});
-test.skipIf(process.platform === "win32")("cache publication compiles the exact translation-unit bytes used by its key", async () => {
-    const dir = await mkdtemp(join(tmpdir(), "scriptc-cache-tu-race-"));
+}, 120_000);
+test("dynamic builds promote staged vendor archives before bounded LRU eviction", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-vendor-lru-"));
     scratch.push(dir);
     const cacheRoot = join(dir, "cache");
-    const binDir = join(dir, "bin");
     const cPath = join(dir, "program.c");
-    const signal = join(dir, "compile-started");
-    const release = join(dir, "compile-release");
+    const outPath = join(dir, "program");
     const oldCacheDir = process.env["SCRIPTC_CACHE_DIR"];
     const oldNoCache = process.env["SCRIPTC_NO_CACHE"];
-    const oldPath = process.env["PATH"];
-    const oldRealClang = process.env["SCRIPTC_TEST_REAL_CLANG"];
-    const oldRaceSource = process.env["SCRIPTC_TEST_RACE_SOURCE"];
-    const oldRaceSignal = process.env["SCRIPTC_TEST_RACE_SIGNAL"];
-    const oldRaceRelease = process.env["SCRIPTC_TEST_RACE_RELEASE"];
-    const originalClang = (oldPath ?? "")
-        .split(delimiter)
-        .map((entry) => join(entry === "" ? process.cwd() : entry, "clang"))
-        .find((candidate) => existsSync(candidate));
-    expect(originalClang).toBeDefined();
-    const source = (value) => `#include <stdio.h>\nint main(void) { puts("${value}"); return 0; }\n`;
-    const waitForSignal = async () => {
-        const deadline = Date.now() + 10_000;
-        while (!existsSync(signal)) {
-            if (Date.now() > deadline)
-                throw new Error("timed out waiting for the compiler wrapper");
-            await new Promise((resolveWait) => setTimeout(resolveWait, 10));
-        }
+    const oldMax = process.env["SCRIPTC_CACHE_MAX_MB"];
+    const oldVendorCacheDir = process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"];
+    try {
+        process.env["SCRIPTC_CACHE_DIR"] = cacheRoot;
+        delete process.env["SCRIPTC_NO_CACHE"];
+        delete process.env["SCRIPTC_CACHE_MAX_MB"];
+        delete process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"];
+        await writeFile(cPath, "int main(void) { return 0; }\n");
+        await warmNativeCaches({ profiles: ["dynamic"] });
+        const vendorRoot = join(cacheRoot, "vendor");
+        const engineDir = (await readdir(vendorRoot)).find((name) => /^3c8f3d689539-plain-/.test(name));
+        expect(engineDir).toBeDefined();
+        const engineArchive = join(vendorRoot, engineDir, "libqjs.a");
+        const initialBytes = await cacheTreeBytes(cacheRoot);
+        const capMb = Math.max(4, Math.ceil(initialBytes * 2 / (1024 * 1024)));
+        const filler = join(cacheRoot, "filler.bin");
+        const staleArchiveTime = new Date("2000-01-01T00:00:00.000Z");
+        const fillerTime = new Date("2001-01-01T00:00:00.000Z");
+        await writeFile(filler, Buffer.alloc(capMb * 1024 * 1024));
+        await utimes(engineArchive, staleArchiveTime, staleArchiveTime);
+        await utimes(filler, fillerTime, fillerTime);
+        process.env["SCRIPTC_CACHE_MAX_MB"] = String(capMb);
+        await compileC({
+            cPath,
+            outPath,
+            cacheIdentity: TEST_CACHE_IDENTITY,
+            dynamic: true,
+        });
+        expect((await stat(outPath)).isFile()).toBe(true);
+        expect((await stat(engineArchive)).mtimeMs).toBeGreaterThan(fillerTime.getTime());
+        expect(await cacheTreeBytes(cacheRoot)).toBeLessThanOrEqual(capMb * 1024 * 1024);
+    }
+    finally {
+        if (oldCacheDir === undefined)
+            delete process.env["SCRIPTC_CACHE_DIR"];
+        else
+            process.env["SCRIPTC_CACHE_DIR"] = oldCacheDir;
+        if (oldNoCache === undefined)
+            delete process.env["SCRIPTC_NO_CACHE"];
+        else
+            process.env["SCRIPTC_NO_CACHE"] = oldNoCache;
+        if (oldMax === undefined)
+            delete process.env["SCRIPTC_CACHE_MAX_MB"];
+        else
+            process.env["SCRIPTC_CACHE_MAX_MB"] = oldMax;
+        if (oldVendorCacheDir === undefined)
+            delete process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"];
+        else
+            process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"] = oldVendorCacheDir;
+    }
+}, 120_000);
+test("native cache warming follows the hard cache disable", async () => {
+    const oldNoCache = process.env["SCRIPTC_NO_CACHE"];
+    try {
+        process.env["SCRIPTC_NO_CACHE"] = "1";
+        await expect(warmNativeCaches({ profiles: ["runtime"] })).rejects.toThrow("native build cache is disabled");
+    }
+    finally {
+        if (oldNoCache === undefined)
+            delete process.env["SCRIPTC_NO_CACHE"];
+        else
+            process.env["SCRIPTC_NO_CACHE"] = oldNoCache;
+    }
+});
+test("native cache warming refuses environments that disable persistent objects", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-cache-warm-disabled-"));
+    scratch.push(dir);
+    const cacheRoot = join(dir, "cache");
+    const oldCacheDir = process.env["SCRIPTC_CACHE_DIR"];
+    const oldCpath = process.env["CPATH"];
+    try {
+        process.env["SCRIPTC_CACHE_DIR"] = cacheRoot;
+        process.env["CPATH"] = dir;
+        await expect(warmNativeCaches({ profiles: ["runtime"] })).rejects.toThrow("requires a persistently cacheable compiler environment");
+        expect(await readdir(cacheRoot)).toEqual([]);
+    }
+    finally {
+        if (oldCacheDir === undefined)
+            delete process.env["SCRIPTC_CACHE_DIR"];
+        else
+            process.env["SCRIPTC_CACHE_DIR"] = oldCacheDir;
+        if (oldCpath === undefined)
+            delete process.env["CPATH"];
+        else
+            process.env["CPATH"] = oldCpath;
+    }
+});
+test("native cache warm profiles follow target capabilities", () => {
+    expect(supportedNativeCacheWarmProfiles({
+        argv: ["zig", "cc"],
+        target: "wasm32-wasi",
+        zigTarget: "wasm32-wasi",
+        targetArgs: [],
+        linkArgs: [],
+    })).toEqual([]);
+    expect(supportedNativeCacheWarmProfiles({
+        argv: ["zig", "cc"],
+        target: "aarch64-apple-ios",
+        zigTarget: "aarch64-ios.15.0",
+        targetArgs: [],
+        linkArgs: [],
+    })).toEqual([]);
+});
+test("parallel native cache warming fails cleanly when the bounded cache cannot retain its profiles", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-cache-warm-cap-"));
+    scratch.push(dir);
+    const cacheRoot = join(dir, "cache");
+    const oldCacheDir = process.env["SCRIPTC_CACHE_DIR"];
+    const oldMax = process.env["SCRIPTC_CACHE_MAX_MB"];
+    try {
+        process.env["SCRIPTC_CACHE_DIR"] = cacheRoot;
+        process.env["SCRIPTC_CACHE_MAX_MB"] = "2.5";
+        await expect(warmNativeCaches()).rejects.toThrow("SCRIPTC_CACHE_MAX_MB is too small to retain the requested native cache warm profiles");
+        expect(await readdir(cacheRoot)).not.toEqual([]);
+    }
+    finally {
+        if (oldCacheDir === undefined)
+            delete process.env["SCRIPTC_CACHE_DIR"];
+        else
+            process.env["SCRIPTC_CACHE_DIR"] = oldCacheDir;
+        if (oldMax === undefined)
+            delete process.env["SCRIPTC_CACHE_MAX_MB"];
+        else
+            process.env["SCRIPTC_CACHE_MAX_MB"] = oldMax;
+    }
+}, 120_000);
+test.skipIf(process.platform !== "darwin")("vendor object caches separate deployment-target environments", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-vendor-environment-"));
+    scratch.push(dir);
+    const cacheRoot = join(dir, "cache");
+    const vendorCacheRoot = join(dir, "vendor-cache");
+    const cPath = join(dir, "program.c");
+    const oldCacheDir = process.env["SCRIPTC_CACHE_DIR"];
+    const oldNoCache = process.env["SCRIPTC_NO_CACHE"];
+    const oldVendorCacheDir = process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"];
+    const oldDeploymentTarget = process.env["MACOSX_DEPLOYMENT_TARGET"];
+    try {
+        process.env["SCRIPTC_CACHE_DIR"] = cacheRoot;
+        process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"] = vendorCacheRoot;
+        delete process.env["SCRIPTC_NO_CACHE"];
+        await writeFile(cPath, "int main(void) { return 0; }\n");
+        process.env["MACOSX_DEPLOYMENT_TARGET"] = "14.0";
+        await compileC({
+            cPath,
+            outPath: join(dir, "newer"),
+            cacheIdentity: TEST_CACHE_IDENTITY,
+            regex: true,
+        });
+        process.env["MACOSX_DEPLOYMENT_TARGET"] = "11.0";
+        await compileC({
+            cPath,
+            outPath: join(dir, "older"),
+            cacheIdentity: TEST_CACHE_IDENTITY,
+            regex: true,
+        });
+        const lreCaches = (await readdir(vendorCacheRoot)).filter((name) => name.includes("-lre-"));
+        expect(lreCaches).toHaveLength(2);
+        const minVersions = lreCaches.map((cache) => execFileSync("vtool", ["-show-build", join(vendorCacheRoot, cache, "libregexp.o")], {
+            encoding: "utf8",
+        }).match(/minos\s+(\S+)/)?.[1]);
+        expect(new Set(minVersions)).toEqual(new Set(["11.0", "14.0"]));
+    }
+    finally {
+        if (oldCacheDir === undefined)
+            delete process.env["SCRIPTC_CACHE_DIR"];
+        else
+            process.env["SCRIPTC_CACHE_DIR"] = oldCacheDir;
+        if (oldNoCache === undefined)
+            delete process.env["SCRIPTC_NO_CACHE"];
+        else
+            process.env["SCRIPTC_NO_CACHE"] = oldNoCache;
+        if (oldVendorCacheDir === undefined)
+            delete process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"];
+        else
+            process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"] = oldVendorCacheDir;
+        if (oldDeploymentTarget === undefined)
+            delete process.env["MACOSX_DEPLOYMENT_TARGET"];
+        else
+            process.env["MACOSX_DEPLOYMENT_TARGET"] = oldDeploymentTarget;
+    }
+});
+test("complete binary hits precede missing vendor prerequisite materialization", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-cache-vendor-hit-"));
+    scratch.push(dir);
+    const cacheRoot = join(dir, "cache");
+    const vendorCacheRoot = join(dir, "vendor-cache");
+    const cPath = join(dir, "program.c");
+    const oldCacheDir = process.env["SCRIPTC_CACHE_DIR"];
+    const oldNoCache = process.env["SCRIPTC_NO_CACHE"];
+    const oldVendorCacheDir = process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"];
+    try {
+        process.env["SCRIPTC_CACHE_DIR"] = cacheRoot;
+        process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"] = vendorCacheRoot;
+        delete process.env["SCRIPTC_NO_CACHE"];
+        await writeFile(cPath, '#include <stdio.h>\nint main(void) { puts("cached"); return 0; }\n');
+        const firstOut = join(dir, "first");
+        await compileC({
+            cPath,
+            outPath: firstOut,
+            cacheIdentity: TEST_CACHE_IDENTITY,
+            regex: true,
+        });
+        expect(execFileSync(firstOut, { encoding: "utf8" }).trim()).toBe("cached");
+        expect(await completeArtifacts(cacheRoot, "bin")).toHaveLength(1);
+        expect((await stat(vendorCacheRoot)).isDirectory()).toBe(true);
+        // Simulate a package reinstall: the per-package vendor build disappears,
+        // while the per-user complete executable remains. The hit must not
+        // recreate that directory even though the compiler remains available for
+        // fresh dependency discovery.
+        await rm(vendorCacheRoot, { recursive: true, force: true });
+        const hitOut = firstOut;
+        await compileC({
+            cPath,
+            outPath: hitOut,
+            cacheIdentity: TEST_CACHE_IDENTITY,
+            regex: true,
+        });
+        expect(execFileSync(hitOut, { encoding: "utf8" }).trim()).toBe("cached");
+        await expect(stat(vendorCacheRoot)).rejects.toMatchObject({ code: "ENOENT" });
+    }
+    finally {
+        if (oldCacheDir === undefined)
+            delete process.env["SCRIPTC_CACHE_DIR"];
+        else
+            process.env["SCRIPTC_CACHE_DIR"] = oldCacheDir;
+        if (oldNoCache === undefined)
+            delete process.env["SCRIPTC_NO_CACHE"];
+        else
+            process.env["SCRIPTC_NO_CACHE"] = oldNoCache;
+        if (oldVendorCacheDir === undefined)
+            delete process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"];
+        else
+            process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"] = oldVendorCacheDir;
+    }
+});
+test("arbitrary C bypasses persistent artifacts so same-path header edits cannot go stale", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-arbitrary-c-cache-"));
+    scratch.push(dir);
+    const cacheRoot = join(dir, "cache");
+    const cPath = join(dir, "program.c");
+    const headerPath = join(dir, "value.h");
+    const oldCacheDir = process.env["SCRIPTC_CACHE_DIR"];
+    const oldNoCache = process.env["SCRIPTC_NO_CACHE"];
+    try {
+        process.env["SCRIPTC_CACHE_DIR"] = cacheRoot;
+        delete process.env["SCRIPTC_NO_CACHE"];
+        await writeFile(cPath, '#include <stdio.h>\n#include "value.h"\nint main(void) { puts(VALUE); return 0; }\n');
+        await writeFile(headerPath, '#define VALUE "one"\n');
+        const firstOut = join(dir, "first");
+        await compileC({ cPath, outPath: firstOut });
+        expect(execFileSync(firstOut, { encoding: "utf8" }).trim()).toBe("one");
+        await writeFile(headerPath, '#define VALUE "two"\n');
+        const secondOut = join(dir, "second");
+        await compileC({ cPath, outPath: secondOut });
+        expect(execFileSync(secondOut, { encoding: "utf8" }).trim()).toBe("two");
+        await expect(stat(join(cacheRoot, "bin"))).rejects.toMatchObject({ code: "ENOENT" });
+        const archiveOut = join(dir, "program.lib.a");
+        await compileLibArchive({ cPath, outPath: archiveOut });
+        expect((await stat(archiveOut)).isFile()).toBe(true);
+        await expect(stat(join(cacheRoot, "lib"))).rejects.toMatchObject({ code: "ENOENT" });
+    }
+    finally {
+        if (oldCacheDir === undefined)
+            delete process.env["SCRIPTC_CACHE_DIR"];
+        else
+            process.env["SCRIPTC_CACHE_DIR"] = oldCacheDir;
+        if (oldNoCache === undefined)
+            delete process.env["SCRIPTC_NO_CACHE"];
+        else
+            process.env["SCRIPTC_NO_CACHE"] = oldNoCache;
+    }
+});
+test("cached translation units keep the compiler-visible source path in their identity", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-cache-source-path-"));
+    scratch.push(dir);
+    const cacheRoot = join(dir, "cache");
+    const aPath = join(dir, "a.c");
+    const bPath = join(dir, "b.c");
+    const headerPath = join(dir, "cache_path_header.h");
+    const source = '#include <stdio.h>\n#include "cache_path_header.h"\nint main(void) { puts(__FILE__); puts(CACHE_PATH_HEADER); return 0; }\n';
+    const oldCacheDir = process.env["SCRIPTC_CACHE_DIR"];
+    const oldNoCache = process.env["SCRIPTC_NO_CACHE"];
+    try {
+        process.env["SCRIPTC_CACHE_DIR"] = cacheRoot;
+        delete process.env["SCRIPTC_NO_CACHE"];
+        await Promise.all([
+            writeFile(aPath, source),
+            writeFile(bPath, source),
+            writeFile(headerPath, '#define CACHE_PATH_HEADER "header"\n'),
+        ]);
+        const aOut = join(dir, "a-out", "program");
+        const bOut = join(dir, "b-out", "program");
+        await Promise.all([mkdir(join(dir, "a-out")), mkdir(join(dir, "b-out"))]);
+        await compileC({ cPath: aPath, outPath: aOut, cacheIdentity: TEST_CACHE_IDENTITY });
+        await compileC({ cPath: bPath, outPath: bOut, cacheIdentity: TEST_CACHE_IDENTITY });
+        expect(execFileSync(aOut, { encoding: "utf8" }).trim()).toBe(`${aPath}\nheader`);
+        expect(execFileSync(bOut, { encoding: "utf8" }).trim()).toBe(`${bPath}\nheader`);
+        expect(await completeArtifacts(cacheRoot, "bin")).toHaveLength(2);
+    }
+    finally {
+        if (oldCacheDir === undefined)
+            delete process.env["SCRIPTC_CACHE_DIR"];
+        else
+            process.env["SCRIPTC_CACHE_DIR"] = oldCacheDir;
+        if (oldNoCache === undefined)
+            delete process.env["SCRIPTC_NO_CACHE"];
+        else
+            process.env["SCRIPTC_NO_CACHE"] = oldNoCache;
+    }
+});
+test.skipIf(process.platform === "win32")("cache publication compiles the exact translation-unit bytes used by its key", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-cache-tu-race-"));
+    scratch.push(dir);
+    const cacheRoot = join(dir, "cache");
+    const binDir = join(dir, "bin");
+    const cPath = join(dir, "program.c");
+    const signal = join(dir, "compile-started");
+    const release = join(dir, "compile-release");
+    const oldCacheDir = process.env["SCRIPTC_CACHE_DIR"];
+    const oldNoCache = process.env["SCRIPTC_NO_CACHE"];
+    const oldPath = process.env["PATH"];
+    const oldRealClang = process.env["SCRIPTC_TEST_REAL_CLANG"];
+    const oldRaceSource = process.env["SCRIPTC_TEST_RACE_SOURCE"];
+    const oldRaceSignal = process.env["SCRIPTC_TEST_RACE_SIGNAL"];
+    const oldRaceRelease = process.env["SCRIPTC_TEST_RACE_RELEASE"];
+    const originalClang = (oldPath ?? "")
+        .split(delimiter)
+        .map((entry) => join(entry === "" ? process.cwd() : entry, "clang"))
+        .find((candidate) => existsSync(candidate));
+    expect(originalClang).toBeDefined();
+    const source = (value) => `#include <stdio.h>\nint main(void) { puts("${value}"); return 0; }\n`;
+    const waitForSignal = async () => {
+        const deadline = Date.now() + 10_000;
+        while (!existsSync(signal)) {
+            if (Date.now() > deadline)
+                throw new Error("timed out waiting for the compiler wrapper");
+            await new Promise((resolveWait) => setTimeout(resolveWait, 10));
+        }
     };
     try {
         await mkdir(binDir);
@@ -2183,7 +2727,11 @@ done
 exec "$SCRIPTC_TEST_REAL_CLANG" "$@"
 `);
         await chmod(wrapper, 0o755);
-        await writeFile(cPath, "int main(void) { return 0; }\n");
+        // Keep the injected datum reachable. With executable section GC an
+        // unreferenced test-only global is rightly removed before the binary
+        // assertion below can observe it.
+        await writeFile(cPath, "extern int scriptc_runtime_race_marker(void);\n" +
+            "int main(void) { return scriptc_runtime_race_marker(); }\n");
         process.env["SCRIPTC_CACHE_DIR"] = cacheRoot;
         process.env["SCRIPTC_TEST_RUNTIME_SRC_DIR"] = fakeRuntime;
         process.env["SCRIPTC_TEST_REAL_CLANG"] = realClang;
@@ -2208,7 +2756,11 @@ exec "$SCRIPTC_TEST_REAL_CLANG" "$@"
                 throw new Error("timed out waiting for runtime compile");
             await new Promise((resolveWait) => setTimeout(resolveWait, 10));
         }
-        await writeFile(raceSource, `${originalRuntimeSource}\nconst char scriptc_runtime_race_marker[] = "${marker}";\n`);
+        await writeFile(raceSource, `${originalRuntimeSource}\n` +
+            `volatile const char scriptc_runtime_race_marker_data[] = "${marker}";\n` +
+            "int scriptc_runtime_race_marker(void) {\n" +
+            "  return scriptc_runtime_race_marker_data[0] == '\\0';\n" +
+            "}\n");
         await writeFile(release, "go");
         await firstBuild;
         expect((await readFile(firstOut)).includes(Buffer.from(marker))).toBe(true);
@@ -2434,7 +2986,78 @@ test("frontend-generated same-output builds no-op only while output and dependen
             delete process.env["SCRIPTC_NO_CACHE"];
         else
             process.env["SCRIPTC_NO_CACHE"] = oldNoCache;
-        process.umask(oldUmask);
+        process.umask(oldUmask);
+    }
+});
+test("pre-section-GC output-local stamps cannot restore an old executable", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-section-gc-local-stamp-"));
+    scratch.push(dir);
+    const cacheRoot = join(dir, "cache");
+    const cPath = join(dir, "program.c");
+    const outPath = join(dir, "program");
+    const oldCacheDir = process.env["SCRIPTC_CACHE_DIR"];
+    const oldNoCache = process.env["SCRIPTC_NO_CACHE"];
+    try {
+        process.env["SCRIPTC_CACHE_DIR"] = cacheRoot;
+        delete process.env["SCRIPTC_NO_CACHE"];
+        await writeFile(cPath, "int main(void) { return 0; }\n");
+        await compileC({ cPath, outPath, cacheIdentity: "scriptc-generated-v1" });
+        const stampPath = join(cacheRoot, "local", createHash("sha256").update(outPath).digest("hex"));
+        const current = JSON.parse(await readFile(stampPath, "utf8"));
+        const legacy = { ...current, key: "old-non-gc-output", version: 1 };
+        await writeFile(stampPath, `${JSON.stringify(legacy)}\n`);
+        const pinnedTime = new Date("2001-01-01T00:00:00.000Z");
+        await utimes(outPath, pinnedTime, pinnedTime);
+        await compileC({ cPath, outPath, cacheIdentity: "scriptc-generated-v1" });
+        expect((await stat(outPath)).mtimeMs).toBeGreaterThan(pinnedTime.getTime());
+    }
+    finally {
+        if (oldCacheDir === undefined)
+            delete process.env["SCRIPTC_CACHE_DIR"];
+        else
+            process.env["SCRIPTC_CACHE_DIR"] = oldCacheDir;
+        if (oldNoCache === undefined)
+            delete process.env["SCRIPTC_NO_CACHE"];
+        else
+            process.env["SCRIPTC_NO_CACHE"] = oldNoCache;
+    }
+});
+test("artifact-ready callbacks expose native dependencies on builds and validated hits", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-artifact-ready-"));
+    scratch.push(dir);
+    const cacheRoot = join(dir, "cache");
+    const cPath = join(dir, "program.c");
+    const outPath = join(dir, "program");
+    const oldCacheDir = process.env["SCRIPTC_CACHE_DIR"];
+    const oldNoCache = process.env["SCRIPTC_NO_CACHE"];
+    try {
+        process.env["SCRIPTC_CACHE_DIR"] = cacheRoot;
+        delete process.env["SCRIPTC_NO_CACHE"];
+        await writeFile(cPath, "int main(void) { return 0; }\n");
+        const observations = [];
+        const build = () => compileC({
+            cPath,
+            outPath,
+            cacheIdentity: "scriptc-generated-v1",
+            onArtifactReady: async ({ dependencies }) => {
+                observations.push(dependencies.map((dependency) => dependency.path));
+            },
+        });
+        await build();
+        await build();
+        expect(observations).toHaveLength(2);
+        expect(observations[0].length).toBeGreaterThan(0);
+        expect(observations[1]).toEqual(observations[0]);
+    }
+    finally {
+        if (oldCacheDir === undefined)
+            delete process.env["SCRIPTC_CACHE_DIR"];
+        else
+            process.env["SCRIPTC_CACHE_DIR"] = oldCacheDir;
+        if (oldNoCache === undefined)
+            delete process.env["SCRIPTC_NO_CACHE"];
+        else
+            process.env["SCRIPTC_NO_CACHE"] = oldNoCache;
     }
 });
 test.skipIf(process.platform === "win32")("output-local hits follow symlinked header targets", async () => {
@@ -2515,7 +3138,7 @@ test("fresh processes preserve output-local dependency coverage after source edi
     delete childEnv["SCRIPTC_NO_CACHE"];
     delete childEnv["SCRIPTC_TEST_STABLE_TOOLCHAIN"];
     delete childEnv["SCRIPTC_TEST_TRUST_COMPILER_WRAPPER"];
-    await writeFile(helperPath, `import { compileC } from ${JSON.stringify(new URL("./cc.ts", import.meta.url).href)};\n` +
+    await writeFile(helperPath, `import { compileC } from ${JSON.stringify(new URL("./native-toolchain.ts", import.meta.url).href)};\n` +
         `await compileC({ cPath: process.argv[2], outPath: process.argv[3], cacheIdentity: "scriptc-generated-v1" });\n`);
     const compileInFreshProcess = () => {
         execFileSync(process.execPath, ["--import", "tsx", helperPath, cPath, outPath], {
@@ -2867,6 +3490,553 @@ test("library identity edits reuse the cached large program object", async () =>
             process.env["SCRIPTC_NO_CACHE"] = oldNoCache;
     }
 });
+test.skipIf(!nativeShardMergeAvailable)("LLVM library shards reuse unaffected program objects after a localized edit", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-lib-program-shards-"));
+    scratch.push(dir);
+    const cacheRoot = join(dir, "cache");
+    const cPath = join(dir, "program.ll");
+    const outPath = join(dir, "program.lib.a");
+    const oldCacheDir = process.env["SCRIPTC_CACHE_DIR"];
+    const oldNoCache = process.env["SCRIPTC_NO_CACHE"];
+    const source = (value) => `%Pair = type { i64, i64 }
+@private_value = internal global i64 ${value}
+
+define internal i64 @left() {
+entry:
+  %v = load i64, ptr @private_value
+  ret i64 %v
+}
+
+define internal i64 @right() {
+entry:
+  %v = call i64 @left()
+  ret i64 %v
+}
+
+define i64 @scriptc_public_value() {
+entry:
+  %v = call i64 @right()
+  ret i64 %v
+}
+`;
+    try {
+        process.env["SCRIPTC_CACHE_DIR"] = cacheRoot;
+        delete process.env["SCRIPTC_NO_CACHE"];
+        await mkdir(cacheRoot, { mode: 0o700 });
+        const build = async (value) => {
+            const programSource = source(value);
+            const split = splitLlvmProgram(programSource, { minimumBytes: 0, targetBytes: 64 * 1024 });
+            expect(split?.shards).toHaveLength(3);
+            await writeFile(cPath, programSource);
+            await compileLibArchive({
+                cPath,
+                programSource,
+                programShards: split.shards,
+                programPublicSymbols: split.publicSymbols,
+                outPath,
+                cacheIdentity: TEST_CACHE_IDENTITY,
+                optimization: "dev",
+            });
+        };
+        await build(7);
+        const initial = (await readdir(join(cacheRoot, "program-shard")))
+            .filter((name) => !name.endsWith(".sha256"));
+        expect(initial).toHaveLength(3);
+        await build(9);
+        const after = (await readdir(join(cacheRoot, "program-shard")))
+            .filter((name) => !name.endsWith(".sha256"));
+        expect(after).toHaveLength(4);
+        expect(initial.filter((name) => after.includes(name))).toHaveLength(3);
+        const old = new Date("2000-01-01T00:00:00.000Z");
+        await Promise.all(after.map((name) => utimes(join(cacheRoot, "program-shard", name), old, old)));
+        await build(9);
+        for (const name of after) {
+            // The completed archive hit returns before shard lookup/merge; exact
+            // repeats do not even touch the per-bucket object cache.
+            expect((await stat(join(cacheRoot, "program-shard", name))).mtimeMs).toBe(old.getTime());
+        }
+        const probeSource = join(dir, "probe.c");
+        const probe = join(dir, "probe");
+        await writeFile(probeSource, "#include <stdio.h>\nlong long scriptc_public_value(void);\nint main(void) { printf(\"%lld\\n\", scriptc_public_value()); }\n");
+        execFileSync("clang", [probeSource, outPath, "-lm", "-o", probe]);
+        expect(execFileSync(probe, { encoding: "utf8" })).toBe("9\n");
+    }
+    finally {
+        if (oldCacheDir === undefined)
+            delete process.env["SCRIPTC_CACHE_DIR"];
+        else
+            process.env["SCRIPTC_CACHE_DIR"] = oldCacheDir;
+        if (oldNoCache === undefined)
+            delete process.env["SCRIPTC_NO_CACHE"];
+        else
+            process.env["SCRIPTC_NO_CACHE"] = oldNoCache;
+    }
+});
+test.skipIf(!nativeShardMergeAvailable)("LLVM executable dev shards reuse unaffected program objects after a localized edit", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-exe-program-shards-"));
+    scratch.push(dir);
+    const cacheRoot = join(dir, "cache");
+    const cPath = join(dir, "program.ll");
+    const outPath = join(dir, "program");
+    const oldCacheDir = process.env["SCRIPTC_CACHE_DIR"];
+    const oldNoCache = process.env["SCRIPTC_NO_CACHE"];
+    const source = (value) => `@private_value = internal global i64 ${value}
+
+define internal i64 @left() {
+entry:
+  %v = load i64, ptr @private_value
+  ret i64 %v
+}
+
+define internal i64 @right() {
+entry:
+  %v = call i64 @left()
+  ret i64 %v
+}
+
+define i32 @main() {
+entry:
+  %v = call i64 @right()
+  %exit = trunc i64 %v to i32
+  ret i32 %exit
+}
+`;
+    try {
+        process.env["SCRIPTC_CACHE_DIR"] = cacheRoot;
+        delete process.env["SCRIPTC_NO_CACHE"];
+        await mkdir(cacheRoot, { mode: 0o700 });
+        const build = async (value) => {
+            const programSource = source(value);
+            const split = splitLlvmProgram(programSource, { minimumBytes: 0, targetBytes: 64 * 1024 });
+            expect(split?.shards).toHaveLength(3);
+            await writeFile(cPath, programSource);
+            await compileC({
+                cPath,
+                programShards: split.shards,
+                programPublicSymbols: split.publicSymbols,
+                outPath,
+                cacheIdentity: TEST_CACHE_IDENTITY,
+                optimization: "dev",
+            });
+        };
+        await build(7);
+        const initial = (await readdir(join(cacheRoot, "program-shard")))
+            .filter((name) => !name.endsWith(".sha256"));
+        expect(initial).toHaveLength(3);
+        expect(spawnSync(outPath).status).toBe(7);
+        await build(9);
+        const after = (await readdir(join(cacheRoot, "program-shard")))
+            .filter((name) => !name.endsWith(".sha256"));
+        expect(after).toHaveLength(4);
+        expect(initial.filter((name) => after.includes(name))).toHaveLength(3);
+        expect(spawnSync(outPath).status).toBe(9);
+        const old = new Date("2000-01-01T00:00:00.000Z");
+        await Promise.all(after.map((name) => utimes(join(cacheRoot, "program-shard", name), old, old)));
+        await build(9);
+        for (const name of after) {
+            // The completed executable hit returns before shard lookup/merge.
+            expect((await stat(join(cacheRoot, "program-shard", name))).mtimeMs).toBe(old.getTime());
+        }
+    }
+    finally {
+        if (oldCacheDir === undefined)
+            delete process.env["SCRIPTC_CACHE_DIR"];
+        else
+            process.env["SCRIPTC_CACHE_DIR"] = oldCacheDir;
+        if (oldNoCache === undefined)
+            delete process.env["SCRIPTC_NO_CACHE"];
+        else
+            process.env["SCRIPTC_NO_CACHE"] = oldNoCache;
+    }
+});
+test.skipIf(process.platform === "win32" || clangExecutable === undefined ||
+    ldExecutable === undefined || (process.platform === "linux" && objcopyExecutable === undefined))("LLVM executable shards fall back without publishing a shard-derived binary", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-exe-program-shard-fallback-"));
+    scratch.push(dir);
+    const binDir = join(dir, "bin");
+    const cacheRoot = join(dir, "cache");
+    const cPath = join(dir, "program.ll");
+    const outPath = join(dir, "program");
+    const oldCacheDir = process.env["SCRIPTC_CACHE_DIR"];
+    const oldNoCache = process.env["SCRIPTC_NO_CACHE"];
+    const oldPath = process.env["PATH"];
+    const oldRealLd = process.env["SCRIPTC_TEST_REAL_LD"];
+    const programSource = [
+        "define i32 @main() {",
+        "entry:",
+        "  ret i32 7",
+        "}",
+        "",
+        "define internal i64 @other_value() {",
+        "entry:",
+        "  ret i64 9",
+        "}",
+        "",
+    ].join("\n");
+    try {
+        await Promise.all([mkdir(binDir), mkdir(cacheRoot, { mode: 0o700 })]);
+        await Promise.all([
+            symlink(clangExecutable, join(binDir, "clang")),
+            ...(process.platform === "linux"
+                ? [symlink(objcopyExecutable, join(binDir, "objcopy"))]
+                : []),
+            writeFile(join(binDir, "ld"), "#!/bin/sh\nfor arg in \"$@\"; do if [ \"$arg\" = -r ]; then exit 1; fi; done\nexec \"$SCRIPTC_TEST_REAL_LD\" \"$@\"\n"),
+            writeFile(cPath, programSource),
+        ]);
+        await chmod(join(binDir, "ld"), 0o755);
+        process.env["PATH"] = binDir;
+        process.env["SCRIPTC_CACHE_DIR"] = cacheRoot;
+        process.env["SCRIPTC_TEST_REAL_LD"] = ldExecutable;
+        delete process.env["SCRIPTC_NO_CACHE"];
+        await compileC({
+            cPath,
+            programShards: [
+                {
+                    name: "program-f000.ll",
+                    source: "define i32 @main() {\nentry:\n  ret i32 7\n}\ndeclare hidden i64 @other_value()\n",
+                },
+                {
+                    name: "program-f001.ll",
+                    source: "declare i32 @main()\ndefine hidden i64 @other_value() {\nentry:\n  ret i64 9\n}\n",
+                },
+            ],
+            programPublicSymbols: ["main"],
+            outPath,
+            cacheIdentity: TEST_CACHE_IDENTITY,
+            optimization: "dev",
+        });
+        expect(spawnSync(outPath).status).toBe(7);
+        // The canonical retry is valid output, but cannot occupy a key describing
+        // a successful shard merge. Repairing the merge tool must retry the mode.
+        expect(await readdir(join(cacheRoot, "bin")).catch(() => [])).toEqual([]);
+        expect(await readdir(join(cacheRoot, "program-shard")).catch(() => [])).toEqual([]);
+    }
+    finally {
+        if (oldCacheDir === undefined)
+            delete process.env["SCRIPTC_CACHE_DIR"];
+        else
+            process.env["SCRIPTC_CACHE_DIR"] = oldCacheDir;
+        if (oldNoCache === undefined)
+            delete process.env["SCRIPTC_NO_CACHE"];
+        else
+            process.env["SCRIPTC_NO_CACHE"] = oldNoCache;
+        if (oldPath === undefined)
+            delete process.env["PATH"];
+        else
+            process.env["PATH"] = oldPath;
+        if (oldRealLd === undefined)
+            delete process.env["SCRIPTC_TEST_REAL_LD"];
+        else
+            process.env["SCRIPTC_TEST_REAL_LD"] = oldRealLd;
+    }
+});
+test.skipIf(!nativeShardMergeAvailable)("LLVM merged-object and archive caches separate shard projections and public-symbol keep sets", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-lib-program-shard-abi-"));
+    scratch.push(dir);
+    const cacheRoot = join(dir, "cache");
+    const cPath = join(dir, "program.ll");
+    const oldCacheDir = process.env["SCRIPTC_CACHE_DIR"];
+    const oldNoCache = process.env["SCRIPTC_NO_CACHE"];
+    const programSource = [
+        "define i64 @foo() {",
+        "entry:",
+        "  ret i64 1",
+        "}",
+        "",
+        "define i64 @bar() {",
+        "entry:",
+        "  ret i64 2",
+        "}",
+        "",
+    ].join("\n");
+    const programShards = [
+        {
+            name: "program-f000.ll",
+            source: "define i64 @foo() {\nentry:\n  ret i64 1\n}\ndeclare i64 @bar()\n",
+        },
+        {
+            name: "program-f001.ll",
+            source: "declare i64 @foo()\ndefine i64 @bar() {\nentry:\n  ret i64 2\n}\n",
+        },
+    ];
+    try {
+        process.env["SCRIPTC_CACHE_DIR"] = cacheRoot;
+        delete process.env["SCRIPTC_NO_CACHE"];
+        await mkdir(cacheRoot, { mode: 0o700 });
+        await writeFile(cPath, programSource);
+        const build = async (symbol, outPath, shards = programShards) => {
+            await compileLibArchive({
+                cPath,
+                programSource,
+                programShards: shards,
+                programPublicSymbols: [symbol],
+                outPath,
+                cacheIdentity: TEST_CACHE_IDENTITY,
+                optimization: "dev",
+            });
+        };
+        await build("foo", join(dir, "foo.lib.a"));
+        const barArchive = join(dir, "bar.lib.a");
+        await build("bar", barArchive);
+        expect(await completeArtifacts(cacheRoot, "lib")).toHaveLength(2);
+        expect((await readdir(join(cacheRoot, "program-obj"))).filter((name) => !name.endsWith(".sha256"))).toHaveLength(2);
+        const probeSource = join(dir, "probe.c");
+        const probe = join(dir, "probe");
+        await writeFile(probeSource, "long long bar(void);\nint main(void) { return bar() != 2; }\n");
+        execFileSync("clang", [probeSource, barArchive, "-lm", "-o", probe]);
+        expect(execFileSync(probe, { encoding: "utf8" })).toBe("");
+        // The canonical TU and ABI stay fixed, but the exact shard projection
+        // changes. The merged-object tier must not reuse the previous layout.
+        await build("bar", join(dir, "bar-commented.lib.a"), [
+            { ...programShards[0], source: `; projection edit\n${programShards[0].source}` },
+            programShards[1],
+        ]);
+        expect(await completeArtifacts(cacheRoot, "lib")).toHaveLength(3);
+        expect((await readdir(join(cacheRoot, "program-obj"))).filter((name) => !name.endsWith(".sha256"))).toHaveLength(3);
+    }
+    finally {
+        if (oldCacheDir === undefined)
+            delete process.env["SCRIPTC_CACHE_DIR"];
+        else
+            process.env["SCRIPTC_CACHE_DIR"] = oldCacheDir;
+        if (oldNoCache === undefined)
+            delete process.env["SCRIPTC_NO_CACHE"];
+        else
+            process.env["SCRIPTC_NO_CACHE"] = oldNoCache;
+    }
+});
+test.skipIf(process.platform === "win32" || clangExecutable === undefined || arExecutable === undefined ||
+    ldExecutable === undefined || (process.platform === "linux" && objcopyExecutable === undefined))("LLVM merged-object caches follow in-place shard merge-tool replacements", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-lib-program-shard-merge-tool-"));
+    scratch.push(dir);
+    const binDir = join(dir, "bin");
+    const cacheRoot = join(dir, "cache");
+    const mergeLog = join(dir, "merge.log");
+    const cPath = join(dir, "program.ll");
+    const oldCacheDir = process.env["SCRIPTC_CACHE_DIR"];
+    const oldNoCache = process.env["SCRIPTC_NO_CACHE"];
+    const oldPath = process.env["PATH"];
+    const oldRealLd = process.env["SCRIPTC_TEST_REAL_LD"];
+    const oldMergeLog = process.env["SCRIPTC_TEST_MERGE_LOG"];
+    const programSource = [
+        "define i64 @foo() {",
+        "entry:",
+        "  ret i64 1",
+        "}",
+        "",
+        "define i64 @bar() {",
+        "entry:",
+        "  ret i64 2",
+        "}",
+        "",
+    ].join("\n");
+    const programShards = [
+        {
+            name: "program-f000.ll",
+            source: "define i64 @foo() {\nentry:\n  ret i64 1\n}\ndeclare i64 @bar()\n",
+        },
+        {
+            name: "program-f001.ll",
+            source: "declare i64 @foo()\ndefine i64 @bar() {\nentry:\n  ret i64 2\n}\n",
+        },
+    ];
+    const ldWrapper = (generation) => `#!/bin/sh
+printf '${generation}\\n' >> "$SCRIPTC_TEST_MERGE_LOG"
+exec "$SCRIPTC_TEST_REAL_LD" "$@"
+`;
+    try {
+        await Promise.all([mkdir(binDir), mkdir(cacheRoot, { mode: 0o700 })]);
+        await Promise.all([
+            symlink(clangExecutable, join(binDir, "clang")),
+            symlink(arExecutable, join(binDir, "ar")),
+            ...(process.platform === "linux"
+                ? [symlink(objcopyExecutable, join(binDir, "objcopy"))]
+                : []),
+            writeFile(join(binDir, "ld"), ldWrapper("first")),
+            writeFile(cPath, programSource),
+        ]);
+        await chmod(join(binDir, "ld"), 0o755);
+        process.env["PATH"] = binDir;
+        process.env["SCRIPTC_CACHE_DIR"] = cacheRoot;
+        process.env["SCRIPTC_TEST_REAL_LD"] = ldExecutable;
+        process.env["SCRIPTC_TEST_MERGE_LOG"] = mergeLog;
+        delete process.env["SCRIPTC_NO_CACHE"];
+        const build = (outPath) => compileLibArchive({
+            cPath,
+            programSource,
+            programShards,
+            programPublicSymbols: ["foo", "bar"],
+            outPath,
+            cacheIdentity: TEST_CACHE_IDENTITY,
+            optimization: "dev",
+        });
+        await build(join(dir, "first.lib.a"));
+        await writeFile(join(binDir, "ld"), ldWrapper("second"));
+        await chmod(join(binDir, "ld"), 0o755);
+        await build(join(dir, "second.lib.a"));
+        expect((await readFile(mergeLog, "utf8")).trim().split("\n")).toEqual(["first", "second"]);
+        expect(await completeArtifacts(cacheRoot, "lib")).toHaveLength(2);
+        expect((await readdir(join(cacheRoot, "program-obj"))).filter((name) => !name.endsWith(".sha256"))).toHaveLength(2);
+        // The compiler and shard IR did not change; only merged outputs split by
+        // localization-tool identity.
+        expect((await readdir(join(cacheRoot, "program-shard"))).filter((name) => !name.endsWith(".sha256"))).toHaveLength(2);
+    }
+    finally {
+        if (oldCacheDir === undefined)
+            delete process.env["SCRIPTC_CACHE_DIR"];
+        else
+            process.env["SCRIPTC_CACHE_DIR"] = oldCacheDir;
+        if (oldNoCache === undefined)
+            delete process.env["SCRIPTC_NO_CACHE"];
+        else
+            process.env["SCRIPTC_NO_CACHE"] = oldNoCache;
+        if (oldPath === undefined)
+            delete process.env["PATH"];
+        else
+            process.env["PATH"] = oldPath;
+        if (oldRealLd === undefined)
+            delete process.env["SCRIPTC_TEST_REAL_LD"];
+        else
+            process.env["SCRIPTC_TEST_REAL_LD"] = oldRealLd;
+        if (oldMergeLog === undefined)
+            delete process.env["SCRIPTC_TEST_MERGE_LOG"];
+        else
+            process.env["SCRIPTC_TEST_MERGE_LOG"] = oldMergeLog;
+    }
+});
+test.skipIf(process.platform === "win32" || clangExecutable === undefined || arExecutable === undefined)("LLVM library shards fall back to the canonical TU without host merge tools", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-lib-program-shard-fallback-"));
+    scratch.push(dir);
+    const binDir = join(dir, "bin");
+    const cPath = join(dir, "program.ll");
+    const outPath = join(dir, "program.lib.a");
+    const oldCacheDir = process.env["SCRIPTC_CACHE_DIR"];
+    const oldNoCache = process.env["SCRIPTC_NO_CACHE"];
+    const oldPath = process.env["PATH"];
+    const programSource = "define i64 @public_value() {\nentry:\n  ret i64 7\n}\n";
+    try {
+        await mkdir(binDir);
+        await Promise.all([
+            symlink(clangExecutable, join(binDir, "clang")),
+            symlink(arExecutable, join(binDir, "ar")),
+        ]);
+        process.env["PATH"] = binDir;
+        process.env["SCRIPTC_NO_CACHE"] = "1";
+        delete process.env["SCRIPTC_CACHE_DIR"];
+        await writeFile(cPath, programSource);
+        await compileLibArchive({
+            cPath,
+            programSource,
+            // If compilation reaches either shard, this build fails. Missing ld
+            // (and objcopy on Linux) must select the valid canonical TU instead.
+            programShards: [
+                { name: "program-f000.ll", source: "not valid LLVM IR\n" },
+                { name: "program-f001.ll", source: "also not valid LLVM IR\n" },
+            ],
+            programPublicSymbols: ["public_value"],
+            outPath,
+            optimization: "dev",
+        });
+        expect(await readFile(outPath)).not.toHaveLength(0);
+    }
+    finally {
+        if (oldCacheDir === undefined)
+            delete process.env["SCRIPTC_CACHE_DIR"];
+        else
+            process.env["SCRIPTC_CACHE_DIR"] = oldCacheDir;
+        if (oldNoCache === undefined)
+            delete process.env["SCRIPTC_NO_CACHE"];
+        else
+            process.env["SCRIPTC_NO_CACHE"] = oldNoCache;
+        if (oldPath === undefined)
+            delete process.env["PATH"];
+        else
+            process.env["PATH"] = oldPath;
+    }
+});
+test.skipIf(process.platform === "win32" || clangExecutable === undefined || arExecutable === undefined ||
+    (process.platform === "linux" && objcopyExecutable === undefined))("LLVM library shards fall back when an available host merge tool fails", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-lib-program-shard-merge-failure-"));
+    scratch.push(dir);
+    const binDir = join(dir, "bin");
+    const cacheRoot = join(dir, "cache");
+    const cPath = join(dir, "program.ll");
+    const outPath = join(dir, "program.lib.a");
+    const oldCacheDir = process.env["SCRIPTC_CACHE_DIR"];
+    const oldNoCache = process.env["SCRIPTC_NO_CACHE"];
+    const oldPath = process.env["PATH"];
+    const programSource = [
+        "define i64 @public_value() {",
+        "entry:",
+        "  ret i64 7",
+        "}",
+        "",
+        "define i64 @other_value() {",
+        "entry:",
+        "  ret i64 9",
+        "}",
+        "",
+    ].join("\n");
+    try {
+        await Promise.all([mkdir(binDir), mkdir(cacheRoot, { mode: 0o700 })]);
+        await Promise.all([
+            symlink(clangExecutable, join(binDir, "clang")),
+            symlink(arExecutable, join(binDir, "ar")),
+            ...(process.platform === "linux"
+                ? [symlink(objcopyExecutable, join(binDir, "objcopy"))]
+                : []),
+            writeFile(join(binDir, "ld"), "#!/bin/sh\nexit 1\n"),
+            writeFile(cPath, programSource),
+        ]);
+        await chmod(join(binDir, "ld"), 0o755);
+        process.env["PATH"] = binDir;
+        process.env["SCRIPTC_CACHE_DIR"] = cacheRoot;
+        delete process.env["SCRIPTC_NO_CACHE"];
+        await compileLibArchive({
+            cPath,
+            programSource,
+            programShards: [
+                {
+                    name: "program-f000.ll",
+                    source: "define i64 @public_value() {\nentry:\n  ret i64 7\n}\ndeclare i64 @other_value()\n",
+                },
+                {
+                    name: "program-f001.ll",
+                    source: "declare i64 @public_value()\ndefine i64 @other_value() {\nentry:\n  ret i64 9\n}\n",
+                },
+            ],
+            programPublicSymbols: ["public_value", "other_value"],
+            outPath,
+            cacheIdentity: TEST_CACHE_IDENTITY,
+            optimization: "dev",
+        });
+        const probeSource = join(dir, "probe.c");
+        const probe = join(dir, "probe");
+        await writeFile(probeSource, "long long public_value(void);\nint main(void) { return public_value() != 7; }\n");
+        execFileSync(clangExecutable, [probeSource, outPath, "-lm", "-o", probe]);
+        expect(execFileSync(probe, { encoding: "utf8" })).toBe("");
+        // The canonical retry is valid for this invocation, but must not occupy a
+        // key describing merged shard bytes. A repaired merge tool retries the
+        // optimization instead of receiving a poisoned completed/object hit.
+        expect(await readdir(join(cacheRoot, "lib")).catch(() => [])).toEqual([]);
+        expect(await readdir(join(cacheRoot, "program-obj")).catch(() => [])).toEqual([]);
+        expect(await readdir(join(cacheRoot, "program-shard")).catch(() => [])).toEqual([]);
+    }
+    finally {
+        if (oldCacheDir === undefined)
+            delete process.env["SCRIPTC_CACHE_DIR"];
+        else
+            process.env["SCRIPTC_CACHE_DIR"] = oldCacheDir;
+        if (oldNoCache === undefined)
+            delete process.env["SCRIPTC_NO_CACHE"];
+        else
+            process.env["SCRIPTC_NO_CACHE"] = oldNoCache;
+        if (oldPath === undefined)
+            delete process.env["PATH"];
+        else
+            process.env["PATH"] = oldPath;
+    }
+});
 test.skipIf(process.platform === "win32" || zigExecutable === undefined)("cross-ELF localized archives retain unreferenced identity roots", async () => {
     const dir = await mkdtemp(join(tmpdir(), "scriptc-lib-localized-identity-"));
     scratch.push(dir);
@@ -2933,4 +4103,4 @@ test.skipIf(process.platform === "win32" || zigExecutable === undefined)("cross-
             process.env["SCRIPTC_TARGET"] = oldTarget;
     }
 });
-//# sourceMappingURL=cc-cache.test.js.map
+//# sourceMappingURL=native-toolchain.test.js.map