@scriptc/compiler 0.0.33 → 0.0.35

package/dist/backend/cc-cache.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, ccVersionOnce, compileC, compileLibArchive, executableNativeEnvironmentFingerprint, implicitDependencyProbeIncludes, parseLinkTraceFiles, resolveBuildCacheRoot, runtimeFingerprint, runtimeSrcDir, stageRuntimeObjects, supportedNativeCacheWarmProfiles, toolchainEnvironmentCachePolicy, toolchainEnvironmentFingerprint, vendorCacheBuildIdentity, vendorCacheTargetFlavor, warmNativeCaches, } from "./cc.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,36 @@ 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.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");
@@ -142,9 +183,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 +197,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-"));
@@ -1682,6 +1726,339 @@ test("the hard disable bypasses vendor prerequisite caches", async () => {
             process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"] = oldVendorCacheDir;
     }
 });
+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 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"];
+    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_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");
+        await compileC({
+            cPath,
+            outPath: join(dir, "first"),
+            cacheIdentity: TEST_CACHE_IDENTITY,
+            regex: true,
+        });
+        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, "second"),
+            cacheIdentity: TEST_CACHE_IDENTITY,
+            regex: true,
+        });
+        expect((await readdir(vendorRoot)).filter((name) => name.includes("-lre-"))).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 (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;
+    }
+}, 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 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 {
+        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"];
+        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
+            process.env["SCRIPTC_CACHE_DIR"] = oldCacheDir;
+        if (oldNoCache === undefined)
+            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;
+    }
+}, 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 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"];
+        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)
+            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;
+    }
+}, 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 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"];
+        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)
+            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;
+    }
+}, 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 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 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);
@@ -2437,6 +2814,44 @@ test("frontend-generated same-output builds no-op only while output and dependen
         process.umask(oldUmask);
     }
 });
+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 () => {
     const dir = await mkdtemp(join(tmpdir(), "scriptc-local-artifact-symlink-"));
     scratch.push(dir);
@@ -2811,4 +3226,673 @@ test("library archives hit by content, invalidate on edits, and reuse runtime ob
             process.env["PATH"] = oldPath;
     }
 });
+test("library identity edits reuse the cached large program object", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scriptc-lib-program-object-"));
+    scratch.push(dir);
+    const cacheRoot = join(dir, "cache");
+    const cPath = join(dir, "program.c");
+    const outPath = join(dir, "program.lib.a");
+    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 mkdir(cacheRoot, { mode: 0o700 });
+        const programSource = "int scriptc_large_program_value(void) { return 7; }\n";
+        await writeFile(cPath, `${programSource}unsigned long long scriptc_build_id(void) { return 1; }\n`);
+        await compileLibArchive({
+            cPath,
+            programSource,
+            identityCSource: "unsigned long long scriptc_build_id(void) { return 1; }\n",
+            outPath,
+            cacheIdentity: TEST_CACHE_IDENTITY,
+        });
+        const [objectName] = (await readdir(join(cacheRoot, "program-obj")))
+            .filter((name) => !name.endsWith(".sha256"));
+        expect(objectName).toBeDefined();
+        const objectPath = join(cacheRoot, "program-obj", objectName);
+        const objectDigest = await readFile(`${objectPath}.sha256`, "utf8");
+        const old = new Date("2000-01-01T00:00:00.000Z");
+        await utimes(objectPath, old, old);
+        await writeFile(cPath, `${programSource}unsigned long long scriptc_build_id(void) { return 2; }\n`);
+        await compileLibArchive({
+            cPath,
+            programSource,
+            identityCSource: "unsigned long long scriptc_build_id(void) { return 2; }\n",
+            outPath,
+            cacheIdentity: TEST_CACHE_IDENTITY,
+        });
+        expect(await readFile(`${objectPath}.sha256`, "utf8")).toBe(objectDigest);
+        expect((await stat(objectPath)).mtimeMs).toBeGreaterThan(old.getTime());
+        expect((await readdir(join(cacheRoot, "program-obj"))).filter((name) => !name.endsWith(".sha256"))).toEqual([objectName]);
+        const probeSource = join(dir, "probe.c");
+        const probe = join(dir, "probe");
+        await writeFile(probeSource, "#include <stdio.h>\nint scriptc_large_program_value(void);\nunsigned long long scriptc_build_id(void);\nint main(void) { printf(\"%d %llu\\n\", scriptc_large_program_value(), scriptc_build_id()); }\n");
+        execFileSync("clang", [probeSource, outPath, "-lm", "-o", probe]);
+        expect(execFileSync(probe, { encoding: "utf8" })).toBe("7 2\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 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);
+    const cPath = join(dir, "program.c");
+    const probePath = join(dir, "probe.c");
+    const archivePath = join(dir, "program.lib.a");
+    const probeOutput = join(dir, "probe");
+    const cacheRoot = join(dir, "cache");
+    const target = "x86_64-linux-gnu.2.36";
+    const oldCacheDir = process.env["SCRIPTC_CACHE_DIR"];
+    const oldNoCache = process.env["SCRIPTC_NO_CACHE"];
+    const oldCc = process.env["SCRIPTC_CC"];
+    const oldTarget = process.env["SCRIPTC_TARGET"];
+    try {
+        process.env["SCRIPTC_CACHE_DIR"] = cacheRoot;
+        delete process.env["SCRIPTC_NO_CACHE"];
+        process.env["SCRIPTC_CC"] = "zigcc";
+        process.env["SCRIPTC_TARGET"] = target;
+        await writeFile(cPath, "int scriptc_large_program_value(void) { return 7; }\n");
+        await compileLibArchive({
+            cPath,
+            identityCSource: [
+                "unsigned long long scriptc_build_id(void) { return 2; }",
+                "unsigned scriptc_abi_version(void) { return 1; }",
+                "",
+            ].join("\n"),
+            outPath: archivePath,
+            cacheIdentity: TEST_CACHE_IDENTITY,
+            localizeSymbols: [
+                "scriptc_large_program_value",
+                "scriptc_build_id",
+                "scriptc_abi_version",
+            ],
+        });
+        await writeFile(probePath, [
+            "int scriptc_large_program_value(void);",
+            "unsigned long long scriptc_build_id(void);",
+            "unsigned scriptc_abi_version(void);",
+            "int main(void) {",
+            "  return scriptc_large_program_value() != 7 || scriptc_build_id() != 2 || scriptc_abi_version() != 1;",
+            "}",
+            "",
+        ].join("\n"));
+        execFileSync(zigExecutable, [
+            "cc", "-target", target, probePath, archivePath, "-lm", "-o", probeOutput,
+        ]);
+    }
+    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 (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;
+    }
+});
 //# sourceMappingURL=cc-cache.test.js.map