@scriptc/compiler 0.0.34 → 0.0.35

package/dist/backend/cc.js

@@ -1,13 +1,16 @@
 import { execFile, spawnSync } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { constants as fsConstants, existsSync, readdirSync } from "node:fs";
 import { createRequire } from "node:module";
 import { access, chmod, copyFile, link, lstat, mkdir, mkdtemp, readdir, readFile, realpath, rename, rm, stat, unlink, utimes, writeFile } from "node:fs/promises";
 import { availableParallelism, homedir, tmpdir } from "node:os";
 import { basename, delimiter, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { performance } from "node:perf_hooks";
+import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { localizeElfObject, mergeAndLocalizeCoffObjects } from "./object-localize.js";
 const execFileAsync = promisify(execFile);
+const CC_IMPLEMENTATION_PATH = fileURLToPath(import.meta.url);
 /** Test lanes run against one immutable checkout and one immutable toolchain
  * for the lifetime of each Vitest worker. Production deliberately rediscovers
  * compiler/linker inputs on every invocation, but doing that thousands of
@@ -118,17 +121,6 @@ const MUTABLE_COMPILE_ENV_KEYS = [
     "CCC_ADD_ARGS",
     "CLANG_CONFIG_FILE_SYSTEM_DIR",
     "CLANG_CONFIG_FILE_USER_DIR",
-    // The direct runtime build does not consume the conventional Make/CMake
-    // variables, but the lazily-built QuickJS prerequisite does. Their values
-    // can name mutable tools, headers, libraries, and toolchain files, so a
-    // stable spelling is not a safe persistent-cache identity.
-    "CC",
-    "CFLAGS",
-    "CPPFLAGS",
-    "LDFLAGS",
-    "AR",
-    "RANLIB",
-    "CMAKE_TOOLCHAIN_FILE",
     // `zig cc` resolves its bundled headers/runtime through ZIG_LIB_DIR and a
     // caller-selected native libc description through ZIG_LIBC. Both values name
     // mutable compiler inputs whose contents can change behind a stable path.
@@ -155,6 +147,41 @@ export function toolchainEnvironmentFingerprint(env = process.env) {
     }
     return hash.digest("hex");
 }
+/** Inputs that can change which native tool/runtime implementation an
+ * executable build selects before compileC has a chance to rediscover it.
+ * The early whole-program cache keys this exact posture before restoring a
+ * final binary; compileC retains its deeper inode/content validation. */
+export async function executableNativeEnvironmentFingerprint(env = process.env) {
+    const configuredCompiler = env["SCRIPTC_CC"] ?? "";
+    let compilerIdentity;
+    try {
+        compilerIdentity = await effectiveCompilerEnvironmentIdentity(resolveCc(env), env);
+    }
+    catch {
+        // A failed trace cannot safely describe a reusable native posture. Keep
+        // the build working, but make this invocation miss every persistent early
+        // entry so compileC performs its full discovery and validation.
+        compilerIdentity = `<unavailable:${configuredCompiler}:${randomUUID()}>`;
+    }
+    const hash = createHash("sha256")
+        .update("executable-native-environment-v2\0")
+        .update(toolchainEnvironmentFingerprint(env)).update("\0")
+        // PATH text alone is not a resolution proof, and on Darwin /usr/bin/clang
+        // is a stable shim whose selected Xcode compiler can change underneath it.
+        // Re-resolve and trace the effective driver on every early lookup.
+        .update(compilerIdentity).update("\0");
+    for (const name of [
+        "PATH",
+        "SCRIPTC_FETCH_CURL",
+        "SCRIPTC_TEST_RUNTIME_SRC_DIR",
+        "SCRIPTC_TEST_VENDOR_CACHE_DIR",
+        "SCRIPTC_TEST_TRUST_COMPILER_WRAPPER",
+    ]) {
+        const value = env[name];
+        hash.update(name).update(value === undefined ? "\0unset\0" : "\0set\0").update(value ?? "").update("\0");
+    }
+    return hash.digest("hex");
+}
 /** Structured compiler-driver failure. Most callers still let this surface
  * as an internal build error; the TypeScript compiler pipeline recognizes it
  * when an outbound FFI profile is active and turns user-controlled native
@@ -505,14 +532,19 @@ export function cacheTargetIdentity(driver, hostPlatform = process.platform, hos
 function vendorEngineDir() {
     return join(runtimeSrcDir(), "..", "vendor", "quickjs-ng");
 }
-/** Vendor prerequisites have historically lived beside their source trees.
- * The test-only override gives cache-ordering tests a disposable root without
- * renaming package-local artifacts that parallel workers may be using. */
-function vendorBuildCacheRoot() {
+/** Vendor prerequisites follow the per-user build root when persistent cache
+ * validation succeeds. Keeping generated objects out of node_modules makes
+ * npm installations, read-only package stores, and explicit cache warming all
+ * share one writable cache. The test-only override remains the first choice;
+ * callers without a validated root retain the historical package-local
+ * default (ordinary builds give those callers a private transient root). */
+function vendorBuildCacheRoot(buildRoot) {
     const testRoot = process.env["SCRIPTC_TEST_VENDOR_CACHE_DIR"];
-    return testRoot === undefined
+    if (testRoot !== undefined)
+        return resolve(testRoot);
+    return buildRoot === undefined
         ? join(runtimeSrcDir(), "..", "vendor", ".cache")
-        : resolve(testRoot);
+        : join(buildRoot, "vendor");
 }
 /** Cross targets already carry their architecture in the explicit triple.
  * Host-native prerequisites need the same separation: a checkout/package can
@@ -521,27 +553,30 @@ export function vendorCacheTargetFlavor(driver, hostPlatform = process.platform,
     return driver.target === null ? `native-${hostPlatform}-${hostArch}` : driver.target;
 }
 /** Vendor prerequisites live outside the content-addressed build root, so
- * their directory name must carry the same environment and resolved compiler
- * identity as the artifacts that consume them. The short digest keeps the
- * package-local path readable while preventing build-order contamination. */
-export function vendorCacheBuildIdentity(environmentFingerprint, compilerIdentity) {
+ * their directory name must carry the environment, resolved compiler, owned
+ * source bytes, and build-recipe identity of the artifacts that consume them.
+ * The short digest keeps the cache path readable while preventing build-order
+ * and cross-installation contamination. */
+export function vendorCacheBuildIdentity(environmentFingerprint, compilerIdentity, nativeSourceIdentity) {
     return createHash("sha256")
-        .update("vendor-toolchain-v1\0")
+        .update("vendor-toolchain-v2\0")
         .update(environmentFingerprint)
         .update("\0")
         .update(compilerIdentity)
+        .update("\0")
+        .update(nativeSourceIdentity)
         .digest("hex")
         .slice(0, 20);
 }
 const vendorCompilerIdentityFallbacks = new Map();
 async function currentVendorCacheBuildIdentity(driver, environmentFingerprint) {
-    // Native vendor recipes additionally use bare clang/ar and CMake; cross
+    // Native vendor recipes additionally use bare clang/ar; cross
     // recipes use the zig driver for compilation and `zig ar`. Include every
-    // executable that can affect the package-local prerequisite, not just the
+    // executable that can affect the cached prerequisite, not just the
     // final program's driver.
     const commands = [
         driver.argv[0] ?? "clang",
-        ...(driver.target === null ? ["clang", "cc", "ar", "ranlib", "cmake"] : []),
+        ...(driver.target === null ? ["clang", "ar"] : []),
     ].filter((command, index, all) => all.indexOf(command) === index);
     const identities = await Promise.all(commands.map(async (command) => {
         const spellingKey = `${environmentFingerprint}\0${command}`;
@@ -555,7 +590,7 @@ async function currentVendorCacheBuildIdentity(driver, environmentFingerprint) {
                 `<unresolved>\0${command}`,
         ].join("\0");
     }));
-    return vendorCacheBuildIdentity(environmentFingerprint, identities.join("\x1f"));
+    return vendorCacheBuildIdentity(environmentFingerprint, identities.join("\x1f"), await runtimeFingerprint(runtimeSrcDir()));
 }
 function engineArchivePath(sanitize, driver, buildIdentity, cacheRoot = vendorBuildCacheRoot()) {
     const flavor = `${sanitize ? "asan" : "plain"}-${vendorCacheTargetFlavor(driver)}-${buildIdentity}`;
@@ -564,6 +599,18 @@ function engineArchivePath(sanitize, driver, buildIdentity, cacheRoot = vendorBu
 async function fileExists(path) {
     return stat(path).then((s) => s.isFile(), () => false);
 }
+/** Vendor prerequisites are shared persistent cache entries, so they carry
+ * the same adjacent content digest as runtime objects and complete artifacts.
+ * Missing/invalid pairs are rebuilt. Do not remove them during validation: a
+ * concurrent publisher installs data before its digest, and that temporary
+ * invalid window must not let a reader unlink the publisher's data. */
+async function validVendorArtifact(path) {
+    return validCachedFile(path);
+}
+function protectCachedArtifact(paths, path) {
+    paths?.add(path);
+    paths?.add(cacheDigestPath(path));
+}
 function privateSiblingPath(destination, label) {
     // Keep the temporary component independent of the caller's basename. A
     // destination can validly consume the filesystem's entire NAME_MAX budget;
@@ -586,8 +633,73 @@ async function installArtifact(source, destination, mode) {
         await rm(tmp, { force: true }).catch(() => undefined);
     }
 }
+/** Publish one finished vendor prerequisite from disposable build scratch.
+ * The shared data and digest use the ordinary atomic cache publisher.
+ * Concurrent builders produce equivalent bytes; on platforms where rename
+ * cannot replace the winner, accept only a checksum-verified winner. */
+async function publishVendorArtifact(source, destination) {
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            await publishCachedFile(source, destination);
+        }
+        catch (error) {
+            // A concurrent equivalent publisher may have won on a platform where
+            // rename cannot replace an existing file. Accept only its verified pair.
+            if (await validCachedFile(destination))
+                return;
+            if (attempt > 0)
+                throw error;
+            // Otherwise the existing pair is genuinely stale/corrupt and blocked
+            // replacement (notably on Windows). Remove it only after a complete
+            // replacement is ready in private scratch, then retry once.
+            await Promise.all([
+                rm(destination, { force: true }).catch(() => undefined),
+                rm(cacheDigestPath(destination), { force: true }).catch(() => undefined),
+            ]);
+            continue;
+        }
+        // Close publication races where another writer replaced only one member
+        // of the pair between this publisher's two atomic renames.
+        if (await validCachedFile(destination))
+            return;
+    }
+    throw new Error(`vendor cache publication failed integrity validation: ${destination}`);
+}
+/** Pin cache-backed vendor inputs under an invocation-private directory before
+ * linking/archiving. The shared LRU may unlink their cache names at any time;
+ * hard links (or copies where links are unavailable) keep active inputs alive.
+ * A sweep can race the initial pin, so rematerialize and retry once. */
+async function stageVendorInputs(materialize, stageDir) {
+    let lastError = new Error("vendor cache input disappeared while staging");
+    for (let attempt = 0; attempt < 2; attempt++) {
+        await rm(stageDir, { recursive: true, force: true }).catch(() => undefined);
+        await mkdir(stageDir, { recursive: true });
+        const sources = await materialize();
+        try {
+            const now = new Date();
+            return await Promise.all(sources.map(async (source) => {
+                const destination = join(stageDir, basename(source));
+                try {
+                    await link(source, destination);
+                }
+                catch {
+                    await copyFile(source, destination);
+                }
+                // Vendor prerequisites share the cache root's mtime-based LRU. A
+                // successful stage is a cache read, so promote the shared source name
+                // best-effort (it may have raced an eviction after the hard link).
+                await utimes(source, now, now).catch(() => undefined);
+                return destination;
+            }));
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    throw lastError;
+}
 /** The engine archive for one flavor, built lazily on the first --dynamic
- * compile (~10s) and cached under vendor/.cache/<commit>-<flavor>-<target>-<toolchain>/ — unlike
+ * compile and cached under <build-cache>/vendor/<commit>-<flavor>-<target>-<toolchain>/ — unlike
  * the runtime's own sources (recompiled every build, ~100ms), the engine is
  * far too big to rebuild per compile. The plain flavor is ALWAYS MinSizeRel
  * regardless of the program's optimization level: measured binary delta is
@@ -599,67 +711,24 @@ async function installArtifact(source, destination, mode) {
  * private temp dir and publish with an atomic rename — first one wins,
  * losers discard their work and use the winner's archive.
  *
- * SCRIPTC_TARGET adds a per-target cache flavor built WITHOUT CMake (the
- * mbedTLS recipe): the qjs library target is just four TUs
- * (QJS_ENGINE_SOURCES) compiled with `zig cc -target <triple>` under the
- * same flags CMake's MinSizeRel/Debug+ASan configurations apply, packed
- * with `zig ar`. Host builds keep the exact historical CMake recipe. */
+ * The qjs library target is just four TUs (QJS_ENGINE_SOURCES), so both host
+ * and cross builds use the same direct per-TU recipe. This removes CMake from
+ * the runtime dependency set and lets cache warming compile exactly the
+ * archive a later program consumes. Host builds use clang + ar; cross builds
+ * use the selected zig driver + zig ar. */
 async function ensureEngineArchive(sanitize, driver, buildIdentity, cacheRoot = vendorBuildCacheRoot()) {
-    const flavor = `${sanitize ? "asan" : "plain"}-${vendorCacheTargetFlavor(driver)}-${buildIdentity}`;
-    const vendor = vendorEngineDir();
     const archive = engineArchivePath(sanitize, driver, buildIdentity, cacheRoot);
     const cacheDir = dirname(archive);
-    if (await fileExists(archive))
+    if (await validVendorArtifact(archive))
         return archive;
-    if (driver.target !== null)
-        return buildEngineArchiveCross(sanitize, driver, cacheRoot, cacheDir);
-    await mkdir(cacheRoot, { recursive: true });
-    const buildDir = await mkdtemp(join(cacheRoot, `build-${flavor}-`));
-    const stageDir = `${buildDir}.stage`;
-    try {
-        const configureArgs = [
-            "-S", vendor,
-            "-B", buildDir,
-            ...(sanitize
-                ? ["-DCMAKE_BUILD_TYPE=Debug", "-DQJS_ENABLE_ASAN=ON"]
-                : ["-DCMAKE_BUILD_TYPE=MinSizeRel"]),
-            "-DQJS_BUILD_EXAMPLES=OFF",
-            "-DQJS_ENABLE_INSTALL=OFF",
-        ];
-        try {
-            await execFileAsync("cmake", configureArgs);
-        }
-        catch (err) {
-            if (err.code === "ENOENT") {
-                throw new Error("--dynamic builds the embedded engine once with CMake, which was not found on PATH.\n" +
-                    "Install cmake (e.g. `brew install cmake`) and retry. Static builds do not need it.");
-            }
-            throw new Error(`cmake failed configuring the embedded engine (${vendor}).\n\n` +
-                subprocessFailureDetail(err));
-        }
-        await execFileAsync("cmake", [
-            "--build", buildDir,
-            "--target", "qjs",
-            `-j${availableParallelism()}`,
-        ]);
-        // Publish only the archive, atomically: rename fails if a concurrent
-        // build won the race, and the winner's archive is just as good.
-        await mkdir(stageDir);
-        await copyFile(join(buildDir, "libqjs.a"), join(stageDir, "libqjs.a"));
-        await rename(stageDir, cacheDir).catch(() => undefined);
-    }
-    finally {
-        await rm(buildDir, { recursive: true, force: true });
-        await rm(stageDir, { recursive: true, force: true });
-    }
-    return archive;
+    return buildEngineArchiveDirect(sanitize, driver, cacheRoot, cacheDir);
 }
 /** The qjs library target's source list (CMakeLists.txt `qjs_sources` with
  * QJS_BUILD_LIBC off — cutils is header-only): the cross-build recipe
  * compiles exactly these. */
 const QJS_ENGINE_SOURCES = ["dtoa.c", "libregexp.c", "libunicode.c", "quickjs.c"];
-/** The engine archive for a CROSS target, per-TU `zig cc` compiles + `zig
- * ar` (no CMake — the mbedTLS recipe). The flags mirror what the CMake
+/** The engine archive for one target, per-TU compiler invocations plus ar.
+ * The flags mirror what the former CMake
  * configurations apply to the qjs library target: gnu11 (CMAKE_C_EXTENSIONS
  * ON), hidden visibility, -funsigned-char, -DQUICKJS_NG_BUILD and
  * -D_GNU_SOURCE (qjs_defines; linux targetArgs already carry the latter),
@@ -667,10 +736,11 @@ const QJS_ENGINE_SOURCES = ["dtoa.c", "libregexp.c", "libunicode.c", "quickjs.c"
  * (-O0 -ggdb -fno-omit-frame-pointer -fsanitize=address
  * -fno-sanitize-recover=all) for asan. Same atomic-rename publish as every
  * vendor cache. */
-async function buildEngineArchiveCross(sanitize, driver, cacheRoot, cacheDir) {
+async function buildEngineArchiveDirect(sanitize, driver, cacheRoot, cacheDir) {
     const vendor = vendorEngineDir();
     const archive = join(cacheDir, "libqjs.a");
-    const arArgv = [...driver.argv.slice(0, 1), "ar"];
+    const compileArgv = driver.target === null ? ["clang"] : driver.argv;
+    const arArgv = driver.target === null ? ["ar"] : [...driver.argv.slice(0, 1), "ar"];
     const cflags = [
         "-std=gnu11",
         ...driver.targetArgs,
@@ -687,21 +757,14 @@ async function buildEngineArchiveCross(sanitize, driver, cacheRoot, cacheDir) {
         "-I", vendor,
     ];
     await mkdir(cacheRoot, { recursive: true });
-    const buildDir = await mkdtemp(join(cacheRoot, `build-qjs-${driver.target ?? "host"}-`));
+    const buildDir = await mkdtemp(join(tmpdir(), `scriptc-vendor-qjs-${driver.target ?? "host"}-`));
     try {
         const width = Math.min(QJS_ENGINE_SOURCES.length, availableParallelism());
         for (let i = 0; i < QJS_ENGINE_SOURCES.length; i += width) {
-            await Promise.all(QJS_ENGINE_SOURCES.slice(i, i + width).map((src) => execFileAsync(driver.argv[0] ?? "clang", [...driver.argv.slice(1), ...cflags, "-c", join(vendor, src), "-o", join(buildDir, `${basename(src, ".c")}.o`)], { cwd: buildDir })));
+            await Promise.all(QJS_ENGINE_SOURCES.slice(i, i + width).map((src) => execFileAsync(compileArgv[0] ?? "clang", [...compileArgv.slice(1), ...cflags, "-c", join(vendor, src), "-o", join(buildDir, `${basename(src, ".c")}.o`)], { cwd: buildDir })));
         }
         await execFileAsync(arArgv[0] ?? "ar", [...arArgv.slice(1), "rcs", join(buildDir, "libqjs.a"), ...QJS_ENGINE_SOURCES.map((s) => join(buildDir, `${basename(s, ".c")}.o`))]);
-        // Atomic publish: rename fails if a concurrent build won the race, and
-        // the winner's archive is just as good.
-        const stageDir = `${buildDir}.stage`;
-        await mkdir(stageDir);
-        await copyFile(join(buildDir, "libqjs.a"), join(stageDir, "libqjs.a"));
-        await rename(stageDir, cacheDir).catch(async () => {
-            await rm(stageDir, { recursive: true, force: true });
-        });
+        await publishVendorArtifact(join(buildDir, "libqjs.a"), archive);
     }
     finally {
         await rm(buildDir, { recursive: true, force: true });
@@ -722,7 +785,7 @@ function lreObjectPaths(sanitize, driver, buildIdentity, cacheRoot = vendorBuild
 }
 /** The libregexp objects for one flavor, compiled lazily on the first
  * regex-using static build (~1s) and cached like the engine archive —
- * vendor/.cache/<commit>-lre-<flavor>-<target>-<toolchain>/*.o — with the same atomic-rename
+ * <build-cache>/vendor/<commit>-lre-<flavor>-<target>-<toolchain>/*.o — with the same atomic-rename
  * publish (parallel first builds race safely; losers discard their work).
  * Plain is -Os (size class matters: the regex fence pins regex-using
  * binaries well under the engine class); asan matches the final link so
@@ -741,11 +804,10 @@ async function ensureLreObjects(sanitize, driver, buildIdentity, cacheRoot = ven
         `-${vendorCacheTargetFlavor(driver)}-${buildIdentity}`;
     const vendor = vendorEngineDir();
     const objects = lreObjectPaths(sanitize, driver, buildIdentity, cacheRoot);
-    const cacheDir = dirname(objects[0]);
-    if ((await Promise.all(objects.map(fileExists))).every(Boolean))
+    if ((await Promise.all(objects.map(validVendorArtifact))).every(Boolean))
         return objects;
     await mkdir(cacheRoot, { recursive: true });
-    const buildDir = await mkdtemp(join(cacheRoot, `build-lre-${flavor}-`));
+    const buildDir = await mkdtemp(join(tmpdir(), `scriptc-vendor-lre-${flavor}-`));
     try {
         // One -c per invocation: zig's COFF driver rejects multiple -c inputs
         // in a single command ("coff does not support linking multiple
@@ -762,9 +824,7 @@ async function ensureLreObjects(sanitize, driver, buildIdentity, cacheRoot = ven
                 "-o", join(buildDir, f.replace(/\.c$/, ".o")),
             ], { cwd: buildDir });
         }
-        // Atomic publish: rename fails if a concurrent build won the race, and
-        // the winner's objects are just as good.
-        await rename(buildDir, cacheDir).catch(() => undefined);
+        await Promise.all(objects.map((destination) => publishVendorArtifact(join(buildDir, basename(destination)), destination)));
     }
     finally {
         await rm(buildDir, { recursive: true, force: true });
@@ -788,7 +848,7 @@ function zlibObjectPaths(sanitize, driver, buildIdentity, cacheRoot = vendorBuil
 }
 /** The zlib objects for one flavor, compiled lazily on the first zlib-using
  * CROSS build (~1s) and cached like the lre objects —
- * vendor/.cache/zlib-<version>-<flavor>-<target>-<toolchain>/*.o — with the same atomic-rename
+ * <build-cache>/vendor/zlib-<version>-<flavor>-<target>-<toolchain>/*.o — with the same atomic-rename
  * publish (parallel first builds race safely; losers discard their work).
  * Plain is -Os, asan matches the final link so the sanitized lane
  * instruments the codec too. The flavor keys the driver and target exactly
@@ -801,11 +861,10 @@ async function ensureZlibObjects(sanitize, driver, buildIdentity, cacheRoot = ve
         `-${vendorCacheTargetFlavor(driver)}-${buildIdentity}`;
     const vendor = vendorZlibDir();
     const objects = zlibObjectPaths(sanitize, driver, buildIdentity, cacheRoot);
-    const cacheDir = dirname(objects[0]);
-    if ((await Promise.all(objects.map(fileExists))).every(Boolean))
+    if ((await Promise.all(objects.map(validVendorArtifact))).every(Boolean))
         return objects;
     await mkdir(cacheRoot, { recursive: true });
-    const buildDir = await mkdtemp(join(cacheRoot, `build-zlib-${flavor}-`));
+    const buildDir = await mkdtemp(join(tmpdir(), `scriptc-vendor-zlib-${flavor}-`));
     try {
         // One -c per invocation, the lre recipe (zig's COFF driver rejects
         // multiple -c inputs in a single command).
@@ -820,9 +879,7 @@ async function ensureZlibObjects(sanitize, driver, buildIdentity, cacheRoot = ve
                 "-o", join(buildDir, f.replace(/\.c$/, ".o")),
             ], { cwd: buildDir });
         }
-        // Atomic publish: rename fails if a concurrent build won the race, and
-        // the winner's objects are just as good.
-        await rename(buildDir, cacheDir).catch(() => undefined);
+        await Promise.all(objects.map((destination) => publishVendorArtifact(join(buildDir, basename(destination)), destination)));
     }
     finally {
         await rm(buildDir, { recursive: true, force: true });
@@ -849,7 +906,7 @@ function curlStubDirPath(driver, buildIdentity, cacheRoot = vendorBuildCacheRoot
 }
 /** The libcurl import stub for one CROSS target, generated lazily on the
  * first fetch-using cross build and cached like the zlib objects —
- * vendor/.cache/curl-stub-<target>-<toolchain>/libcurl.so, atomic-rename publish. The
+ * <build-cache>/vendor/curl-stub-<target>-<toolchain>/libcurl.so, atomic-rename publish. The
  * stub is empty definitions of CURL_STUB_SYMBOLS compiled `-shared` with
  * `-soname libcurl.so.4`: linking against it satisfies scr_fetch_curl.c's
  * references and records a plain `DT_NEEDED libcurl.so.4`, which the
@@ -861,10 +918,10 @@ function curlStubDirPath(driver, buildIdentity, cacheRoot = vendorBuildCacheRoot
 async function ensureCurlStub(driver, buildIdentity, cacheRoot = vendorBuildCacheRoot()) {
     const cacheDir = curlStubDirPath(driver, buildIdentity, cacheRoot);
     const lib = join(cacheDir, "libcurl.so");
-    if (await fileExists(lib))
+    if (await validVendorArtifact(lib))
         return cacheDir;
     await mkdir(cacheRoot, { recursive: true });
-    const buildDir = await mkdtemp(join(cacheRoot, `build-curl-stub-`));
+    const buildDir = await mkdtemp(join(tmpdir(), "scriptc-vendor-curl-stub-"));
     try {
         const src = join(buildDir, "stub.c");
         await writeFile(src, CURL_STUB_SYMBOLS.map((s) => `void ${s}(void) {}\n`).join(""));
@@ -876,14 +933,7 @@ async function ensureCurlStub(driver, buildIdentity, cacheRoot = vendorBuildCach
             src,
             "-o", join(buildDir, "libcurl.so"),
         ]);
-        // Atomic publish: rename fails if a concurrent build won the race, and
-        // the winner's stub is just as good.
-        const stageDir = `${buildDir}.stage`;
-        await mkdir(stageDir);
-        await copyFile(join(buildDir, "libcurl.so"), join(stageDir, "libcurl.so"));
-        await rename(stageDir, cacheDir).catch(async () => {
-            await rm(stageDir, { recursive: true, force: true });
-        });
+        await publishVendorArtifact(join(buildDir, "libcurl.so"), lib);
     }
     finally {
         await rm(buildDir, { recursive: true, force: true });
@@ -899,7 +949,7 @@ function tlsArchivePath(sanitize, driver, buildIdentity, cacheRoot = vendorBuild
 }
 /** The mbedTLS archive for one flavor, compiled lazily on the first
  * TLS-using build (~15s over ~110 TUs, parallelized) and cached like the
- * engine archive — vendor/.cache/mbedtls-<version>-<flavor>-<target>-<toolchain>/libmbedtls.a —
+ * engine archive — <build-cache>/vendor/mbedtls-<version>-<flavor>-<target>-<toolchain>/libmbedtls.a —
  * with the same atomic-rename publish (parallel first builds race safely;
  * losers discard their work). Plain is -Os (the TLS stack is link-gated
  * but still wants its size class small); asan matches the final link so
@@ -918,13 +968,14 @@ async function ensureTlsArchive(sanitize, driver, buildIdentity, cacheRoot = ven
     const arArgv = driver.target !== null ? [...driver.argv.slice(0, 1), "ar"] : ["ar"];
     const vendor = vendorTlsDir();
     const archive = tlsArchivePath(sanitize, driver, buildIdentity, cacheRoot);
-    const cacheDir = dirname(archive);
-    if (await fileExists(archive))
+    if (await validVendorArtifact(archive))
         return archive;
     await mkdir(cacheRoot, { recursive: true });
-    const buildDir = await mkdtemp(join(cacheRoot, `build-mbedtls-${flavor}-`));
+    const buildDir = await mkdtemp(join(tmpdir(), `scriptc-vendor-mbedtls-${flavor}-`));
     try {
-        const sources = (await readdir(join(vendor, "library"))).filter((n) => n.endsWith(".c")).sort();
+        const sources = (await readdir(join(vendor, "library")))
+            .filter((name) => !name.startsWith(".") && name.endsWith(".c"))
+            .sort();
         const cflags = [
             "-std=c11",
             ...driver.targetArgs,
@@ -937,14 +988,7 @@ async function ensureTlsArchive(sanitize, driver, buildIdentity, cacheRoot = ven
             await Promise.all(sources.slice(i, i + width).map((src) => execFileAsync(compileArgv[0] ?? "clang", [...compileArgv.slice(1), ...cflags, "-c", join(vendor, "library", src), "-o", join(buildDir, `${basename(src, ".c")}.o`)])));
         }
         await execFileAsync(arArgv[0] ?? "ar", [...arArgv.slice(1), "rcs", join(buildDir, "libmbedtls.a"), ...sources.map((s) => join(buildDir, `${basename(s, ".c")}.o`))]);
-        // Atomic publish: rename fails if a concurrent build won the race, and
-        // the winner's archive is just as good.
-        const stageDir = `${buildDir}.stage`;
-        await mkdir(stageDir);
-        await copyFile(join(buildDir, "libmbedtls.a"), join(stageDir, "libmbedtls.a"));
-        await rename(stageDir, cacheDir).catch(async () => {
-            await rm(stageDir, { recursive: true, force: true });
-        });
+        await publishVendorArtifact(join(buildDir, "libmbedtls.a"), archive);
     }
     finally {
         await rm(buildDir, { recursive: true, force: true });
@@ -958,6 +1002,11 @@ async function ensureTlsArchive(sanitize, driver, buildIdentity, cacheRoot = ven
  * objects apart from executable-lane objects). Persistent builds cache the
  * completed archive by program-TU content and cache runtime objects separately,
  * so an edit recompiles only the changed program object before re-archiving.
+ * Large LLVM dev TUs split further into stable symbol-hash shards: compile
+ * those in parallel, cache each object independently, then relocatably merge
+ * them back into the archive's one canonical program member. A localized edit
+ * recompiles only the changed buckets; exact repeats use the merged-object or
+ * completed-archive tiers and never repeat the merge.
  * The base set narrows from the executable lane's unconditional sources:
  * scr_async.c (fibers, timers, the loop) and scr_child.c drop — the
  * async_free refusal already guarantees nothing references them — and
@@ -977,9 +1026,94 @@ const LIB_RUNTIME_SOURCES = [
     ...RUNTIME_SOURCES.filter((f) => f !== "scr_async.c" && f !== "scr_child.c" && f !== "scr_ffi.c"),
     "scr_library.c",
 ];
+function updateProgramShardCacheIdentity(hash, shards, publicSymbols, mergeIdentity) {
+    hash.update("\0program-shards\0");
+    if (shards === undefined) {
+        hash.update("<none>\0");
+    }
+    else {
+        hash.update("<present>\0");
+        for (const shard of shards) {
+            hash.update(shard.name).update("\0").update(shard.source).update("\0");
+        }
+    }
+    hash.update("\0program-public-symbols\0");
+    if (publicSymbols === undefined) {
+        hash.update("<none>\0");
+    }
+    else {
+        hash.update("<present>\0");
+        for (const symbol of publicSymbols)
+            hash.update(symbol).update("\0");
+    }
+    hash.update("\0program-shard-merge\0");
+    hash.update(mergeIdentity === undefined ? "<none>\0" : `<present>\0${mergeIdentity}\0`);
+}
+/** Identity of the machinery that turns LLVM shard objects back into the
+ * canonical program member, or null when the target cannot do so. Sharding is
+ * only a build optimization: a missing host tool or unsupported object class
+ * retains the ordinary single-TU compile. The identity joins every cache tier
+ * that contains merged bytes; raw shard-object keys deliberately omit it. */
+async function resolveProgramShardMergeIdentity(driver) {
+    const platform = targetPlatform(driver);
+    // Mach-O merging uses the host's ld64. A Darwin target produced from a
+    // non-Darwin host can still compile as one canonical Zig TU, but the host's
+    // ELF/COFF linker cannot combine those objects.
+    if (platform === "darwin") {
+        if (process.platform !== "darwin")
+            return null;
+        const ld = await resolvedTool("ld");
+        return ld === null
+            ? null
+            : rememberFingerprintDependencies(`program-shard-merge-darwin-v1\0${ld.cacheIdentity}`, [ld.canonicalPath]);
+    }
+    if (platform === "linux") {
+        if (driver.target === null) {
+            const [ld, objcopy] = await Promise.all([
+                resolvedTool("ld"),
+                resolvedTool("objcopy"),
+            ]);
+            return ld === null || objcopy === null
+                ? null
+                : rememberFingerprintDependencies(`program-shard-merge-linux-v1\0${ld.cacheIdentity}\0${objcopy.cacheIdentity}`, [ld.canonicalPath, objcopy.canonicalPath]);
+        }
+        const arch = driver.target.split("-", 1)[0];
+        if (arch !== "x86_64" && arch !== "aarch64")
+            return null;
+        const compiler = await resolvedTool(driver.argv[0] ?? "zig");
+        return compiler === null
+            ? null
+            : rememberFingerprintDependencies(`program-shard-merge-cross-elf-v1\0${arch}\0${compiler.cacheIdentity}`, [compiler.canonicalPath]);
+    }
+    if (platform === "win32") {
+        const arch = driver.target?.split("-", 1)[0] ?? process.arch;
+        return arch === "x86_64" || arch === "x64"
+            ? `program-shard-merge-coff-v1\0${arch}`
+            : null;
+    }
+    return null;
+}
 export async function compileLibArchive(opts) {
     const rtDir = runtimeSrcDir();
     const driver = resolveCc();
+    const shardNames = new Set();
+    const programShardsValid = opts.programShards?.every((shard) => {
+        if (basename(shard.name) !== shard.name || !shard.name.endsWith(".ll") ||
+            shardNames.has(shard.name))
+            return false;
+        shardNames.add(shard.name);
+        return true;
+    }) === true;
+    const programShardsRequested = opts.cPath.endsWith(".ll") &&
+        programShardsValid && opts.programShards !== undefined && opts.programShards.length > 1 &&
+        opts.programPublicSymbols !== undefined
+        ? opts.programShards
+        : null;
+    const programShardMergeIdentity = programShardsRequested === null
+        ? null
+        : await resolveProgramShardMergeIdentity(driver);
+    const programShards = programShardMergeIdentity === null ? null : programShardsRequested;
+    const programPublicSymbols = programShards === null ? undefined : opts.programPublicSymbols;
     const sanitize = opts.sanitize ?? false;
     const optimization = opts.optimization ?? "release";
     const regex = opts.regex ?? false;
@@ -1049,11 +1183,14 @@ export async function compileLibArchive(opts) {
         }
     }
     let implicitToolchain = null;
+    let implicitCompileToolchain = null;
     let runtimeCompilerInvocation = null;
     let programCompilerInvocation = null;
     if (persistentDriverCache) {
         try {
-            implicitToolchain = await implicitToolchainFingerprint(driver, toolchainEnv);
+            const fingerprints = await implicitToolchainFingerprints(driver, toolchainEnv);
+            implicitToolchain = fingerprints.complete;
+            implicitCompileToolchain = fingerprints.compile;
         }
         catch {
             // An identity probe is cache machinery, never a reason a valid native
@@ -1108,9 +1245,11 @@ export async function compileLibArchive(opts) {
                 const av = await toolVersionOnce(arArgv, toolchainEnv, true);
                 archiverVersion = av;
                 const key = createHash("sha256")
-                    // v7 adds effective compiler-wrapper invocations for the real runtime
-                    // and program compile flavors.
-                    .update("lib-v7\0")
+                    // v10 adds the shard-merge implementation/tool identity. The
+                    // canonical TU still keys source semantics; shard, keep, and merge
+                    // bytes key the exact merged program object so ABI projections,
+                    // tool replacements, and single-/multi-TU producers never collide.
+                    .update("lib-v10\0")
                     .update(cacheTargetIdentity(driver)).update("\0")
                     .update(toolchainEnv).update("\0")
                     .update(implicitToolchain).update("\0")
@@ -1130,12 +1269,14 @@ export async function compileLibArchive(opts) {
                     // latter. Archive members also inherit the TU's basename.
                     .update(opts.cPath).update("\0")
                     .update(resolve(opts.cPath)).update("\0")
-                    .update(programBytes)
+                    .update(programBytes);
+                updateProgramShardCacheIdentity(key, programShards ?? undefined, programPublicSymbols, programShardMergeIdentity ?? undefined);
+                const keyHex = key
                     .update("\0identity\0")
                     .update(identityBytes === null ? "<none>" : "<generated>").update("\0")
                     .update(identityBytes ?? Buffer.alloc(0))
                     .digest("hex");
-                cachedArchive = join(root, "lib", key);
+                cachedArchive = join(root, "lib", keyHex);
                 const tmpOut = privateSiblingPath(opts.outPath, "lib-hit");
                 try {
                     await mkdir(dirname(opts.outPath), { recursive: true });
@@ -1160,19 +1301,19 @@ export async function compileLibArchive(opts) {
             cachedArchive = null;
         }
     }
-    const transientVendorRoot = persistentDriverCache && implicitToolchain !== null
+    const transientVendorRoot = root !== null && implicitToolchain !== null
         ? null
         : join(tmpdir(), `scriptc-lib-vendor-${process.pid}-${Math.random().toString(36).slice(2)}`);
-    const vendorCacheRoot = transientVendorRoot ?? vendorBuildCacheRoot();
+    const vendorCacheRoot = transientVendorRoot ?? vendorBuildCacheRoot(root ?? undefined);
     try {
-        const lreObjects = regex
-            ? await ensureLreObjects(sanitize, driver, vendorBuildIdentity, vendorCacheRoot)
-            : [];
-        const zlibObjects = opts.zlib
-            ? await ensureZlibObjects(sanitize, driver, vendorBuildIdentity, vendorCacheRoot)
-            : [];
         const buildDir = await mkdtemp(join(tmpdir(), "scriptc-lib-"));
         try {
+            const lreObjects = regex
+                ? await stageVendorInputs(() => ensureLreObjects(sanitize, driver, vendorBuildIdentity, vendorCacheRoot), join(buildDir, "vendor-lre"))
+                : [];
+            const zlibObjects = opts.zlib
+                ? await stageVendorInputs(() => ensureZlibObjects(sanitize, driver, vendorBuildIdentity, vendorCacheRoot), join(buildDir, "vendor-zlib"))
+                : [];
             const compileOne = async (src, objName, compilerVisibleSource) => {
                 const obj = join(buildDir, objName);
                 const args = [
@@ -1203,13 +1344,14 @@ export async function compileLibArchive(opts) {
             const programSource = cachedProgramBytes === null
                 ? opts.cPath
                 : join(buildDir, `program${opts.cPath.endsWith(".ll") ? ".ll" : ".c"}`);
-            if (cachedProgramBytes !== null)
+            if (cachedProgramBytes !== null && programShards === null) {
                 await writeFile(programSource, cachedProgramBytes);
+            }
             let cachedProgramObject = null;
             if (root !== null && cachedProgramBytes !== null && compilerVersion !== "" &&
                 implicitToolchain !== null && programCompilerInvocation !== null) {
                 const programKey = createHash("sha256")
-                    .update("lib-program-obj-v1\0")
+                    .update("lib-program-obj-v3\0")
                     .update(cacheTargetIdentity(driver)).update("\0")
                     .update(toolchainEnv).update("\0")
                     .update(implicitToolchain).update("\0")
@@ -1222,16 +1364,120 @@ export async function compileLibArchive(opts) {
                     .update(programCompilerArgs.join("\x1f")).update("\0")
                     .update(opts.cPath).update("\0")
                     .update(resolve(opts.cPath)).update("\0")
-                    .update(cachedProgramBytes)
-                    .digest("hex");
-                cachedProgramObject = join(root, "program-obj", programKey);
+                    .update(cachedProgramBytes);
+                updateProgramShardCacheIdentity(programKey, programShards ?? undefined, programPublicSymbols, programShardMergeIdentity ?? undefined);
+                const programKeyHex = programKey.digest("hex");
+                cachedProgramObject = join(root, "program-obj", programKeyHex);
             }
             const stagedProgramObject = join(buildDir, `${stem}.program.o`);
             let programObject;
+            let programShardFallback = false;
             if (cachedProgramObject !== null &&
                 await copyValidCachedFile(cachedProgramObject, stagedProgramObject)) {
                 programObject = stagedProgramObject;
             }
+            else if (programShards !== null) {
+                try {
+                    const shardEntries = programShards.map((shard, index) => {
+                        const sourcePath = join(buildDir, shard.name);
+                        const staged = join(buildDir, `${stem}.program-${index.toString().padStart(3, "0")}.o`);
+                        let cachePath = null;
+                        if (root !== null && compilerVersion !== "" && implicitCompileToolchain !== null &&
+                            programCompilerInvocation !== null) {
+                            const key = createHash("sha256")
+                                // v2 removes the broad implicit-toolchain fingerprint: it
+                                // includes the linker selected by the driver, but raw shard
+                                // objects are compile-only outputs. The compile-only toolchain
+                                // identity retains compiler/config/header/assembler inputs;
+                                // the effective program invocation pins this exact flag lane.
+                                // Merge-tool identity belongs only to the merged-object and
+                                // completed-archive tiers.
+                                .update("lib-program-shard-v2\0")
+                                .update(cacheTargetIdentity(driver)).update("\0")
+                                .update(toolchainEnv).update("\0")
+                                .update(implicitCompileToolchain).update("\0")
+                                .update(programCompilerInvocation).update("\0")
+                                .update(opts.cacheIdentity).update("\0")
+                                .update(driver.argv.join("\x1f")).update("\0")
+                                .update(compilerVersion).update("\0")
+                                .update(runtimeHash).update("\0")
+                                .update(programDependencyHash).update("\0")
+                                .update(programCompilerArgs.join("\x1f")).update("\0")
+                                .update(opts.cPath).update("\0")
+                                .update(resolve(opts.cPath)).update("\0")
+                                .update(shard.name).update("\0")
+                                .update(shard.source)
+                                .digest("hex");
+                            cachePath = join(root, "program-shard", key);
+                        }
+                        return { ...shard, sourcePath, staged, cachePath, missed: false };
+                    });
+                    const shardWidth = Math.min(8, availableParallelism());
+                    for (let i = 0; i < shardEntries.length; i += shardWidth) {
+                        await Promise.all(shardEntries.slice(i, i + shardWidth).map(async (entry) => {
+                            await writeFile(entry.sourcePath, entry.source);
+                            if (entry.cachePath !== null &&
+                                await copyValidCachedFile(entry.cachePath, entry.staged))
+                                return;
+                            entry.missed = true;
+                            await compileOne(entry.sourcePath, basename(entry.staged), opts.cPath);
+                        }));
+                    }
+                    const publishable = shardEntries.filter((entry) => entry.missed && entry.cachePath !== null);
+                    const mergedProgramObject = await localizeLibraryObjects(driver, arArgv, buildDir, shardEntries.map((entry) => entry.staged), [], programPublicSymbols, `${stem}.program`);
+                    // Keep the canonical archive member spelling. The fact that native
+                    // compilation used shards is an implementation detail; consumers and
+                    // deterministic cache tests continue to see `<stem>.program.o`.
+                    await rename(mergedProgramObject, stagedProgramObject);
+                    programObject = stagedProgramObject;
+                    if (cachedProgramObject !== null || publishable.length > 0) {
+                        try {
+                            const [currentRuntime, currentInvocation, currentDependencies, currentCompiler] = await Promise.all([
+                                runtimeFingerprint(rtDir),
+                                effectiveCompilerInvocationFingerprint(driver, toolchainEnv, programCompilerArgs, programSourceExtension),
+                                translationUnitDependencyFingerprint(driver, cflags, opts.cPath, cachedProgramBytes, toolchainEnv),
+                                ccVersionOnce(driver.argv, toolchainEnv, true),
+                            ]);
+                            const shardInputsStillMatch = currentRuntime === runtimeHash &&
+                                currentInvocation === programCompilerInvocation &&
+                                currentDependencies === programDependencyHash && currentCompiler === compilerVersion;
+                            const currentFingerprints = shardInputsStillMatch
+                                ? await implicitToolchainFingerprints(driver, toolchainEnv)
+                                : null;
+                            const compileInputsStillMatch = shardInputsStillMatch &&
+                                currentFingerprints?.compile === implicitCompileToolchain;
+                            let mergedInputsStillMatch = false;
+                            if (compileInputsStillMatch && cachedProgramObject !== null) {
+                                const currentMerge = await resolveProgramShardMergeIdentity(driver).catch(() => null);
+                                mergedInputsStillMatch =
+                                    currentFingerprints?.complete === implicitToolchain &&
+                                        currentMerge === programShardMergeIdentity;
+                            }
+                            if (compileInputsStillMatch) {
+                                await Promise.all([
+                                    ...(mergedInputsStillMatch
+                                        ? [publishCachedFile(programObject, cachedProgramObject)]
+                                        : []),
+                                    ...publishable.map((entry) => publishCachedFile(entry.staged, entry.cachePath)),
+                                ]);
+                            }
+                        }
+                        catch {
+                            // Best-effort: the merged program object is already valid.
+                        }
+                    }
+                }
+                catch {
+                    // Sharding is only an optimization. A present but incompatible or
+                    // failing merge tool (or a shard-only compiler failure) must not
+                    // turn a valid canonical LLVM TU into a failed library build. Do not
+                    // publish this retry under shard-derived object/archive cache keys.
+                    programShardFallback = true;
+                    if (cachedProgramBytes !== null)
+                        await writeFile(programSource, cachedProgramBytes);
+                    programObject = await compileOne(programSource, `${stem}.program.o`, cachedProgramBytes === null ? undefined : opts.cPath);
+                }
+            }
             else {
                 programObject = await compileOne(programSource, `${stem}.program.o`, cachedProgramBytes === null ? undefined : opts.cPath);
                 if (cachedProgramObject !== null) {
@@ -1329,7 +1575,7 @@ export async function compileLibArchive(opts) {
                 programDependencyHash !== "" &&
                 compilerVersion !== "" &&
                 archiverVersion !== "") {
-                const [currentRuntime, currentImplicit, currentRuntimeInvocation, currentProgramInvocation, currentProgramDependencies, currentCompiler, currentArchiver] = await Promise.all([
+                const [currentRuntime, currentImplicit, currentRuntimeInvocation, currentProgramInvocation, currentProgramDependencies, currentCompiler, currentArchiver, currentProgramShardMerge] = await Promise.all([
                     runtimeFingerprint(rtDir).catch(() => null),
                     implicitToolchainFingerprint(driver, toolchainEnv).catch(() => null),
                     effectiveCompilerInvocationFingerprint(driver, toolchainEnv, cflags).catch(() => null),
@@ -1337,16 +1583,21 @@ export async function compileLibArchive(opts) {
                     translationUnitDependencyFingerprint(driver, cflags, opts.cPath, cachedProgramBytes, toolchainEnv).catch(() => null),
                     ccVersionOnce(driver.argv, toolchainEnv, true).catch(() => null),
                     toolVersionOnce(arArgv, toolchainEnv, true).catch(() => null),
+                    programShards === null
+                        ? Promise.resolve(null)
+                        : resolveProgramShardMergeIdentity(driver).catch(() => null),
                 ]);
                 runtimeStillMatchesKey =
                     cacheInputsStable &&
+                        !programShardFallback &&
                         currentRuntime === runtimeHash &&
                         currentImplicit === implicitToolchain &&
                         currentRuntimeInvocation === runtimeCompilerInvocation &&
                         currentProgramInvocation === programCompilerInvocation &&
                         currentProgramDependencies === programDependencyHash &&
                         currentCompiler === compilerVersion &&
-                        currentArchiver === archiverVersion;
+                        currentArchiver === archiverVersion &&
+                        currentProgramShardMerge === programShardMergeIdentity;
             }
             if (cachedArchive !== null && root !== null && runtimeStillMatchesKey) {
                 try {
@@ -1456,14 +1707,17 @@ async function localizeLibraryObjects(driver, arArgv, buildDir, rootObjects, sup
         }
         return combined;
     }
-    await run([arArgv[0] ?? "ar", ...arArgv.slice(1), "rcs", staging, ...supportObjects]);
+    const supportArgs = supportObjects.length === 0 ? [] : [staging];
+    if (supportObjects.length > 0) {
+        await run([arArgv[0] ?? "ar", ...arArgv.slice(1), "rcs", staging, ...supportObjects]);
+    }
     if (platform === "darwin") {
         await writeFile(keepFile, keepSymbols.map((s) => `_${s}\n`).join(""));
-        await run(["ld", "-r", ...rootObjects, staging, "-o", combined, "-exported_symbols_list", keepFile]);
+        await run(["ld", "-r", ...rootObjects, ...supportArgs, "-o", combined, "-exported_symbols_list", keepFile]);
     }
     else if (platform === "linux" && driver.target === null) {
         await writeFile(keepFile, keepSymbols.map((s) => `${s}\n`).join(""));
-        await run(["ld", "-r", "--force-group-allocation", ...rootObjects, staging, "-o", combined]);
+        await run(["ld", "-r", "--force-group-allocation", ...rootObjects, ...supportArgs, "-o", combined]);
         await run(["objcopy", `--keep-global-symbols=${keepFile}`, combined]);
     }
     else if (platform === "linux") {
@@ -1478,7 +1732,7 @@ async function localizeLibraryObjects(driver, arArgv, buildDir, rootObjects, sup
             ...driver.argv.slice(1),
             "-target", driver.zigTarget ?? driver.target,
             "-nostdlib",
-            "-r", ...rootObjects, staging,
+            "-r", ...rootObjects, ...supportArgs,
             "-o", combined,
         ]);
         try {
@@ -1497,7 +1751,7 @@ async function localizeLibraryObjects(driver, arArgv, buildDir, rootObjects, sup
  * Content-addressed caches that let repeat builds of unchanged programs skip
  * payload code generation/linking — the test lanes' dominant cost. Executable
  * lookups still run lightweight dependency and link-input metadata probes.
- * Three keyspaces under the cache root:
+ * Principal keyspaces under the cache root:
  *
  *   bin/<key>       — whole program binaries. key = sha256(resolved clang
  *                     identity/version, target + compiler/linker environment,
@@ -1527,6 +1781,14 @@ async function localizeLibraryObjects(driver, arArgv, buildDir, rootObjects, sup
  *                     identity, TU path, and program-TU bytes.
  *                     Checksum-verified hits skip native code generation and ar.
  *
+ *   program-obj/<key> — the canonical library program object, after any LLVM
+ *                     shard merge. Exact TU repeats reuse it directly.
+ *
+ *   program-shard/<key> — stable LLVM dev-library buckets keyed by their IR
+ *                     text and complete toolchain/TU identity. Local edits
+ *                     retain every bucket whose definitions/declarations did
+ *                     not change.
+ *
  *   obj/<set>/<f>.o — per-flavor runtime objects for cache-miss builds. The
  *                     historical single invocation recompiles every runtime
  *                     TU per program (~1.3s at -O2); with cached objects a
@@ -1642,6 +1904,52 @@ async function ensurePrivateCacheRoot(root, hardenExisting) {
     }
 }
 const ccVersionMemos = new Map();
+/** Identity of the compiler implementation and configuration selected by a
+ * fresh driver invocation. In particular, Darwin's stable /usr/bin/clang shim
+ * exposes the currently selected Xcode clang only in its `-###` trace. The
+ * normalized trace also covers output-affecting default driver configuration
+ * that can change while argv[0] and PATH retain the same spelling. */
+async function effectiveCompilerEnvironmentIdentity(driver, env) {
+    const compiler = driver.argv[0] ?? "clang";
+    const resolvedDriver = await resolvedTool(compiler, env);
+    if (resolvedDriver === null)
+        return `<unresolved:${compiler}>`;
+    const probeDir = await mkdtemp(join(tmpdir(), "scriptc-early-cc-probe-"));
+    try {
+        const source = join(probeDir, "empty.c");
+        const object = join(probeDir, "empty.o");
+        await writeFile(source, "int scriptc_early_driver_probe;\n");
+        const trace = await execFileAsync(compiler, [
+            ...driver.argv.slice(1),
+            ...driver.targetArgs,
+            "-###",
+            "-std=c11",
+            "-c",
+            source,
+            "-o",
+            object,
+        ], { cwd: probeDir, env, maxBuffer: 16 * 1024 * 1024 });
+        const effectiveSpellings = [];
+        for (const line of `${trace.stdout}\n${trace.stderr}`.split(/\r?\n/)) {
+            const tokens = driverTraceCandidates(line);
+            const cc1 = tokens.indexOf("-cc1");
+            if (cc1 > 0)
+                effectiveSpellings.push(tokens[cc1 - 1]);
+        }
+        const effective = effectiveSpellings.length === 1
+            ? await resolvedTool(effectiveSpellings[0], env)
+            : null;
+        return createHash("sha256")
+            .update("effective-compiler-environment-v1\0")
+            .update(resolvedDriver.cacheIdentity).update("\0")
+            .update(normalizedProbeInvocation(trace, probeDir)).update("\0")
+            .update(effective?.cacheIdentity ?? `<unresolved-effective:${effectiveSpellings.join("\x1f")}>`)
+            .digest("hex");
+    }
+    finally {
+        await rm(probeDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
 /** Resolve the executable the OS will select for an argv[0] spelling. The
  * path and inode metadata join the version output below: two PATH postures
  * must not share cache entries merely because both drivers call themselves
@@ -2174,7 +2482,7 @@ function translationUnitDependencyFingerprint(driver, cflags, sourcePath, source
  * change that redirects includes cannot hide behind an unchanged old path
  * list. Dependency discovery must succeed on every cache-enabled invocation;
  * a prior path list cannot reveal a new higher-priority header. */
-async function implicitToolchainFingerprintFresh(driver, environmentFingerprint) {
+async function implicitToolchainFingerprintsFresh(driver, environmentFingerprint) {
     let probe;
     const compiler = driver.argv[0] ?? "clang";
     const compilerIdentity = await resolvedToolIdentity(compiler);
@@ -2227,7 +2535,8 @@ async function implicitToolchainFingerprintFresh(driver, environmentFingerprint)
                 // executable/version and dependency set.
                 execFileAsync(compiler, [...prefix, "-std=c11", "-###", "-c", driverSource, "-o", driverOutput], { cwd: probeDir, maxBuffer: 16 * 1024 * 1024 }),
             ]);
-            const toolSpellings = [linker.stdout.trim(), assembler.stdout.trim()].filter((value, index, all) => value !== "" && all.indexOf(value) === index);
+            const assemblerSpelling = assembler.stdout.trim();
+            const toolSpellings = [linker.stdout.trim(), assemblerSpelling].filter((value, index, all) => value !== "" && all.indexOf(value) === index);
             const sourceSet = new Set(sources);
             const dependencyPaths = [
                 ...new Set(dependencyResults
@@ -2248,44 +2557,56 @@ async function implicitToolchainFingerprintFresh(driver, environmentFingerprint)
                         path: resolved?.canonicalPath ?? null,
                     };
                 })),
+                compileToolSpellings: assemblerSpelling === "" ? [] : [assemblerSpelling],
             };
         }
         finally {
             await rm(probeDir, { recursive: true, force: true }).catch(() => undefined);
         }
     }
-    const hash = createHash("sha256")
-        .update("implicit-toolchain-v2\0")
-        .update(environmentFingerprint)
-        .update("\0")
-        .update(probe.compilerIdentity)
-        .update("\0")
-        .update(probe.compilerInvocation)
-        .update("\0")
-        .update(driver.argv.join("\x1f"))
-        .update("\0")
-        .update(driver.targetArgs.join("\x1f"))
-        .update("\0")
-        .update(probe.dependencies.join("\x1f"))
-        .update("\0")
-        .update(probe.dependencyFingerprint)
-        .update("\0");
-    for (const tool of probe.tools) {
-        const currentIdentity = await resolvedToolIdentity(tool.spelling);
-        hash
-            .update(tool.spelling)
+    const tools = await Promise.all(probe.tools.map(async (tool) => ({
+        ...tool,
+        currentIdentity: await resolvedToolIdentity(tool.spelling),
+    })));
+    const fingerprint = (domain, selectedTools) => {
+        const hash = createHash("sha256")
+            .update(domain)
+            .update(environmentFingerprint)
+            .update("\0")
+            .update(probe.compilerIdentity)
+            .update("\0")
+            .update(probe.compilerInvocation)
+            .update("\0")
+            .update(driver.argv.join("\x1f"))
             .update("\0")
-            .update(currentIdentity ?? tool.identity ?? "<unresolved>")
+            .update(driver.targetArgs.join("\x1f"))
+            .update("\0")
+            .update(probe.dependencies.join("\x1f"))
+            .update("\0")
+            .update(probe.dependencyFingerprint)
             .update("\0");
-    }
-    return rememberFingerprintDependencies(hash.digest("hex"), [
-        ...probe.dependencies,
-        ...probe.invocationPaths,
-        ...probe.tools.flatMap((tool) => tool.path === null ? [] : [tool.path]),
-    ], probe.dependencies, probe.dependencyFingerprint);
+        for (const tool of selectedTools) {
+            hash
+                .update(tool.spelling)
+                .update("\0")
+                .update(tool.currentIdentity ?? tool.identity ?? "<unresolved>")
+                .update("\0");
+        }
+        return rememberFingerprintDependencies(hash.digest("hex"), [
+            ...probe.dependencies,
+            ...probe.invocationPaths,
+            ...selectedTools.flatMap((tool) => tool.path === null ? [] : [tool.path]),
+        ], probe.dependencies, probe.dependencyFingerprint);
+    };
+    const compileSpellingSet = new Set(probe.compileToolSpellings);
+    return {
+        // Preserve the established complete fingerprint domain and byte stream.
+        complete: fingerprint("implicit-toolchain-v2\0", tools),
+        compile: fingerprint("implicit-compile-toolchain-v1\0", tools.filter((tool) => compileSpellingSet.has(tool.spelling))),
+    };
 }
 const stableImplicitToolchainMemos = new Map();
-function implicitToolchainFingerprint(driver, environmentFingerprint) {
+function implicitToolchainFingerprints(driver, environmentFingerprint) {
     const key = [
         environmentFingerprint,
         driver.argv.join("\x1f"),
@@ -2293,7 +2614,10 @@ function implicitToolchainFingerprint(driver, environmentFingerprint) {
         driver.targetArgs.join("\x1f"),
         runtimeSrcDir(),
     ].join("\0");
-    return stableTestMemo(stableImplicitToolchainMemos, key, () => implicitToolchainFingerprintFresh(driver, environmentFingerprint));
+    return stableTestMemo(stableImplicitToolchainMemos, key, () => implicitToolchainFingerprintsFresh(driver, environmentFingerprint));
+}
+function implicitToolchainFingerprint(driver, environmentFingerprint) {
+    return implicitToolchainFingerprints(driver, environmentFingerprint).then((fingerprints) => fingerprints.complete);
 }
 function linkTraceCandidate(line) {
     const trimmed = line.trim().replace(/^(?:LOAD|load)\s+/, "");
@@ -2519,19 +2843,20 @@ function ccacheAvailable() {
     ccacheMemo ??= execFileAsync("ccache", ["--version"]).then(() => true, () => false);
     return ccacheMemo;
 }
-/** Content hash of every .c/.h in the runtime src tree, the Ryū sources
- * textually included by scr_number.c, and the separately-built vendor pins —
- * everything a binary links that the emitted C bytes don't already cover
- * (npm-embedded C rides inside the emitted C; the engine and standalone
- * vendor archives are pinned by their version constants). The small source
- * tree is hashed on every identity calculation: recursive enumeration is
- * required because a newly added nested header can begin shadowing a system
- * include without changing any previously selected dependency, while content
- * hashing catches same-size edits whose timestamp was preserved by a copy/sync
- * tool. */
+/** Content hash of every owned native source/header plus this backend's build
+ * recipe implementation. It keys complete artifacts, runtime objects, and the
+ * separately built vendor prerequisites, so two installed scriptc versions or
+ * worktrees can share a user cache without exchanging outputs produced from
+ * different vendored bytes or compile/archive recipes. Recursive enumeration
+ * also catches a newly added nested header that begins shadowing a system
+ * include, while content hashing catches same-size timestamp-preserving edits. */
 async function runtimeFingerprintFresh(rtDir) {
     const groups = await runtimeFingerprintInputGroups(rtDir);
-    const h = createHash("sha256").update(QJS_COMMIT).update(MBEDTLS_VERSION).update(ZLIB_VERSION);
+    const h = createHash("sha256")
+        .update("native-owned-inputs-v2\0")
+        .update(QJS_COMMIT).update(MBEDTLS_VERSION).update(ZLIB_VERSION)
+        .update("\0backend-recipe\0")
+        .update(await readFile(CC_IMPLEMENTATION_PATH));
     for (const group of groups) {
         for (const n of group.names) {
             h.update(group.label).update("/").update(n).update("\0").update(await readFile(join(group.dir, n))).update("\0");
@@ -2543,6 +2868,10 @@ async function runtimeFingerprintInputGroups(rtDir) {
     return Promise.all([
         { label: "runtime", dir: rtDir },
         { label: "ryu", dir: join(rtDir, "..", "vendor", "ryu") },
+        { label: "quickjs-ng", dir: join(rtDir, "..", "vendor", "quickjs-ng") },
+        { label: "mbedtls", dir: join(rtDir, "..", "vendor", "mbedtls") },
+        { label: "zlib", dir: join(rtDir, "..", "vendor", "zlib") },
+        { label: "curl", dir: join(rtDir, "..", "vendor", "curl") },
     ].map(async (group) => {
         const names = (await nativeSourceFiles(group.dir, true))
             .map((path) => relative(group.dir, path))
@@ -2551,7 +2880,10 @@ async function runtimeFingerprintInputGroups(rtDir) {
     }));
 }
 async function runtimeFingerprintInputPaths(rtDir) {
-    return (await runtimeFingerprintInputGroups(rtDir)).flatMap((group) => group.names.map((name) => join(group.dir, name)));
+    return [
+        ...(await runtimeFingerprintInputGroups(rtDir)).flatMap((group) => group.names.map((name) => join(group.dir, name))),
+        CC_IMPLEMENTATION_PATH,
+    ];
 }
 const stableRuntimeFingerprintMemos = new Map();
 export function runtimeFingerprint(rtDir) {
@@ -2737,7 +3069,22 @@ async function snapshotLocalArtifactDependencies(dependencyPaths, recursiveDirec
     const recursive = new Set(recursiveDirectories.map((path) => resolve(path)));
     return Promise.all([...new Set(dependencyPaths)].sort().map((path) => snapshotLocalArtifactDependency(path, recursive.has(resolve(path)) ? recursiveExclusions : null)));
 }
-async function localArtifactDependenciesStillMatch(dependencies) {
+export async function nativeArtifactDependenciesStillMatch(dependencies) {
+    if (!dependencies.every((dependency) => dependency !== null && typeof dependency === "object" &&
+        typeof dependency.path === "string" &&
+        (dependency.kind === "file" || dependency.kind === "directory" || dependency.kind === "symlink") &&
+        typeof dependency.dev === "number" && typeof dependency.ino === "number" &&
+        typeof dependency.size === "number" && typeof dependency.mtimeMs === "number" &&
+        typeof dependency.ctimeMs === "number" &&
+        (dependency.treeDigest === undefined || typeof dependency.treeDigest === "string") &&
+        (dependency.treeExclusions === undefined || (Array.isArray(dependency.treeExclusions) &&
+            dependency.treeExclusions.every((path) => typeof path === "string"))) &&
+        (dependency.kind !== "symlink" || (typeof dependency.targetPath === "string" &&
+            (dependency.targetKind === "file" || dependency.targetKind === "directory") &&
+            typeof dependency.targetDev === "number" && typeof dependency.targetIno === "number" &&
+            typeof dependency.targetSize === "number" && typeof dependency.targetMtimeMs === "number" &&
+            typeof dependency.targetCtimeMs === "number"))))
+        return false;
     return (await Promise.all(dependencies.map(async (dependency) => {
         const current = await snapshotLocalArtifactDependency(dependency.path, dependency.treeDigest === undefined ? null : dependency.treeExclusions ?? []).catch(() => null);
         return current !== null && JSON.stringify(current) === JSON.stringify(dependency);
@@ -2767,7 +3114,7 @@ async function readNativeMetadataStamp(root, key) {
                 values: stamp.values,
                 dependencies: stamp.dependencies,
             }) !== stamp.integrity ||
-            !(await localArtifactDependenciesStillMatch(stamp.dependencies))) {
+            !(await nativeArtifactDependenciesStillMatch(stamp.dependencies))) {
             return null;
         }
         return stamp;
@@ -2813,11 +3160,14 @@ function nativeMetadataKey(kind, parts) {
  * The generated TU bytes, every scriptc runtime source, the selected direct
  * compiler inode, target/options/environment, and the output path all join the
  * key. A digest rejects a modified/truncated output before the no-op hit. */
-function localArtifactIdentity(opts, driver, environmentFingerprint, compilerIdentity, runtimeHash, programBytes) {
+function localArtifactIdentity(opts, driver, environmentFingerprint, compilerIdentity, runtimeHash, programBytes, programShardMerge) {
     const normalizedOptions = Object.fromEntries(Object.entries(opts)
-        .filter(([, value]) => value !== undefined)
+        // Shard source can be tens of megabytes. Hash it incrementally below
+        // instead of materializing a second giant JSON string solely for this
+        // output-local fast-path identity.
+        .filter(([key, value]) => value !== undefined && key !== "programShards" && key !== "programPublicSymbols")
         .sort(([a], [b]) => a.localeCompare(b)));
-    return createHash("sha256")
+    const hash = createHash("sha256")
         .update("local-artifact-v1\0")
         .update(cacheTargetIdentity(driver)).update("\0")
         .update(environmentFingerprint).update("\0")
@@ -2825,7 +3175,11 @@ function localArtifactIdentity(opts, driver, environmentFingerprint, compilerIde
         .update(runtimeHash).update("\0")
         .update(driver.argv.join("\x1f")).update("\0")
         .update(driver.targetArgs.join("\x1f")).update("\0")
-        .update(driver.linkArgs.join("\x1f")).update("\0")
+        .update(driver.linkArgs.join("\x1f")).update("\0");
+    if (programShardMerge !== null) {
+        updateProgramShardCacheIdentity(hash, opts.programShards, opts.programPublicSymbols, programShardMerge);
+    }
+    return hash
         .update(process.env["SCRIPTC_FETCH_CURL"] === "1" ? "fetch-curl" : "fetch-native").update("\0")
         .update(JSON.stringify(normalizedOptions)).update("\0")
         .update(resolve(opts.cPath)).update("\0")
@@ -2880,16 +3234,16 @@ async function localArtifactHit(stampPath, outPath, key) {
                     typeof dependency.targetSize !== "number" ||
                     typeof dependency.targetMtimeMs !== "number" ||
                     typeof dependency.targetCtimeMs !== "number")) ||
-            !(await localArtifactDependenciesStillMatch(stamp.dependencies)) ||
+            !(await nativeArtifactDependenciesStillMatch(stamp.dependencies)) ||
             await fileDigest(outPath) !== stamp.digest) {
-            return false;
+            return null;
         }
         const now = new Date();
         await utimes(stampPath, now, now).catch(() => undefined);
-        return true;
+        return stamp;
     }
     catch {
-        return false;
+        return null;
     }
 }
 async function publishLocalArtifactStamp(stampPath, outPath, key, dependencyPaths, recursiveDirectories = [], recursiveExclusions = []) {
@@ -2909,6 +3263,7 @@ async function publishLocalArtifactStamp(stampPath, outPath, key, dependencyPath
         };
         await writeFile(tmp, `${JSON.stringify(stamp)}\n`, { mode: 0o600 });
         await rename(tmp, stampPath);
+        return stamp;
     }
     finally {
         await rm(tmp, { force: true }).catch(() => undefined);
@@ -2919,7 +3274,7 @@ async function publishLocalArtifactStamp(stampPath, outPath, key, dependencyPath
  * per-file atomic renames make every winner equivalent. Publication is held
  * until verifyInputs confirms that the source/header fingerprint used by the
  * key still describes the bytes clang just read. */
-async function ensureRuntimeObjects(root, ccArgv, cflags, sources, keyPrefix, verifyInputs) {
+async function ensureRuntimeObjects(root, ccArgv, cflags, sources, keyPrefix, verifyInputs, protectedPaths) {
     const setKey = createHash("sha256")
         .update(keyPrefix)
         .update(cflags.join("\x1f"))
@@ -2927,6 +3282,13 @@ async function ensureRuntimeObjects(root, ccArgv, cflags, sources, keyPrefix, ve
         .slice(0, 24);
     const objDir = join(root, "obj", setKey);
     const objOf = (src) => join(objDir, `${basename(src, ".c")}.o`);
+    if (protectedPaths !== undefined) {
+        for (const source of sources) {
+            const object = objOf(source);
+            protectedPaths.add(object);
+            protectedPaths.add(cacheDigestPath(object));
+        }
+    }
     const present = await Promise.all(sources.map((s) => validCachedFile(objOf(s))));
     const missing = sources.filter((_, i) => !present[i]);
     if (missing.length > 0) {
@@ -2937,7 +3299,7 @@ async function ensureRuntimeObjects(root, ccArgv, cflags, sources, keyPrefix, ve
             ccArgv[0] === "clang" &&
             (await ccacheAvailable());
         await mkdir(objDir, { recursive: true });
-        const tmpDir = await mkdtemp(join(root, "obj", "build-"));
+        const tmpDir = await mkdtemp(join(tmpdir(), "scriptc-cache-obj-"));
         try {
             const compiled = new Map();
             // Modest parallelism: a flavor's objects build once, but several cold
@@ -2963,7 +3325,7 @@ async function ensureRuntimeObjects(root, ccArgv, cflags, sources, keyPrefix, ve
                             },
                         }
                         : undefined);
-                    compiled.set(src, { object: tmpObj, digest: await fileDigest(tmpObj) });
+                    compiled.set(src, tmpObj);
                 }));
             }
             // The fingerprint was computed before these subprocesses started. Do
@@ -2973,12 +3335,7 @@ async function ensureRuntimeObjects(root, ccArgv, cflags, sources, keyPrefix, ve
                 throw new CacheInputsChangedError();
             for (const [src, built] of compiled) {
                 const destination = objOf(src);
-                const tmpDigest = `${built.object}.sha256`;
-                await writeFile(tmpDigest, `${built.digest}\n`);
-                // Publish data first and its verifier second. A concurrent reader in
-                // the tiny gap sees a missing/mismatched digest and falls back safely.
-                await rename(built.object, destination);
-                await rename(tmpDigest, cacheDigestPath(destination));
+                await publishCachedFile(built, destination);
             }
         }
         finally {
@@ -3025,7 +3382,7 @@ export async function stageRuntimeObjects(objects, stageDir) {
  * mtimes. Active links use private staged names/hard links, so cache names can
  * be unlinked safely. */
 const rootWriteCounts = new Map();
-async function pruneCache(root) {
+async function pruneCache(root, protectedPaths) {
     const configuredCap = process.env["SCRIPTC_CACHE_MAX_MB"];
     const writes = (rootWriteCounts.get(root) ?? 0) + 1;
     rootWriteCounts.set(root, writes);
@@ -3042,6 +3399,14 @@ async function pruneCache(root) {
             if (ent.isDirectory())
                 await walk(p);
             else if (ent.isFile()) {
+                // Atomic publishers use private names until their data/digest or
+                // metadata stamp is complete. They are active writes, not LRU entries.
+                if (ent.name.startsWith(".scriptc-") ||
+                    ent.name.startsWith(".tmp-") ||
+                    ent.name.includes(".tmp-"))
+                    continue;
+                if (protectedPaths?.has(p))
+                    continue;
                 const s = await stat(p).catch(() => null);
                 if (s !== null)
                     files.push({ path: p, size: s.size, mtimeMs: s.mtimeMs });
@@ -3079,9 +3444,10 @@ async function pruneCache(root) {
  * unchanged programs skip payload code generation/linking via the binary
  * cache after lightweight metadata probes, and misses link the program's own
  * TU against cached per-flavor runtime objects. */
-export async function compileC(opts) {
+async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
     const rtDir = runtimeSrcDir();
     const sanitize = opts.sanitize ?? false;
+    const optimization = opts.optimization ?? "release";
     const dynamic = opts.dynamic ?? false;
     const regex = opts.regex ?? false;
     // fetch's implementation switch: the default is the NATIVE bridge
@@ -3105,6 +3471,24 @@ export async function compileC(opts) {
     const tls = (opts.tls ?? false) || nativeFetch || netIsland;
     const tlsCa = (opts.tlsCa ?? false) || tls;
     const driver = resolveCc();
+    const shardNames = new Set();
+    const programShardsValid = opts.programShards?.every((shard) => {
+        if (basename(shard.name) !== shard.name || !shard.name.endsWith(".ll") ||
+            shardNames.has(shard.name))
+            return false;
+        shardNames.add(shard.name);
+        return true;
+    }) === true;
+    const programShardsRequested = optimization === "dev" && !sanitize && opts.cPath.endsWith(".ll") &&
+        programShardsValid && opts.programShards !== undefined && opts.programShards.length > 1 &&
+        opts.programPublicSymbols !== undefined
+        ? opts.programShards
+        : null;
+    const programShardMergeIdentity = programShardsRequested === null
+        ? null
+        : await resolveProgramShardMergeIdentity(driver);
+    const programShards = programShardMergeIdentity === null ? null : programShardsRequested;
+    const programPublicSymbols = programShards === null ? undefined : opts.programPublicSymbols;
     // Mobile triples produce library archives, never standalone executables:
     // the executable-lane runtime (event loop, sockets, child processes) is
     // not verified on those device classes. compile() reports the SC3002
@@ -3125,7 +3509,7 @@ export async function compileC(opts) {
         // See the resolveCc block: these inputs are built on and for the HOST
         // (vendored archives, system libs). Regex, zlib, and the engine archive
         // are NOT here: their vendored sources are plain C that ensureLreObjects
-        // / ensureZlibObjects / buildEngineArchiveCross compile per target with
+        // / ensureZlibObjects / buildEngineArchiveDirect compile per target with
         // the driver itself — win32 included (the Windows lane runs the
         // @dynamic corpus and the zlib program against the box's Node). The
         // NATIVE fetch rides the socket units and cross-compiles with them —
@@ -3166,11 +3550,19 @@ export async function compileC(opts) {
     let root = opts.cacheIdentity === undefined || !persistentDriverCache
         ? null
         : configuredCacheRoot;
+    if (cacheWarmOnly && root === null) {
+        throw new Error("native cache warming requires a persistently cacheable compiler environment");
+    }
     if (root !== null) {
         try {
             await ensurePrivateCacheRoot(root, process.env["SCRIPTC_CACHE_DIR"] === undefined);
         }
-        catch {
+        catch (error) {
+            if (cacheWarmOnly) {
+                throw new Error("native cache warming could not prepare the persistent cache root", {
+                    cause: error,
+                });
+            }
             root = null;
         }
     }
@@ -3180,7 +3572,8 @@ export async function compileC(opts) {
     // broader cross-output CAS performs its compiler/SDK/linker rediscovery.
     // FFI/native-input builds and the public arbitrary-C cache API stay on the
     // strict path because their dependency graphs are caller-owned.
-    if (root !== null &&
+    if (!cacheWarmOnly &&
+        root !== null &&
         cachePolicy.completeArtifacts &&
         opts.cacheIdentity === "scriptc-generated-v1" &&
         (opts.linkInputs?.length ?? 0) === 0 &&
@@ -3194,7 +3587,7 @@ export async function compileC(opts) {
             ]);
             if (compiler !== null) {
                 const effectiveCompiler = directCompilerSelections.get(compilerDriverProbeKey(driver, toolchainEnv)) ?? compiler;
-                const key = localArtifactIdentity(opts, driver, toolchainEnv, `${compiler.cacheIdentity}\0${effectiveCompiler.cacheIdentity}`, runtimeHash, programBytes);
+                const key = localArtifactIdentity(opts, driver, toolchainEnv, `${compiler.cacheIdentity}\0${effectiveCompiler.cacheIdentity}`, runtimeHash, programBytes, programShardMergeIdentity);
                 const stampPath = localArtifactStampPath(root, opts.outPath);
                 localArtifact = {
                     stampPath,
@@ -3203,8 +3596,11 @@ export async function compileC(opts) {
                     programBytes,
                     compilerPath: effectiveCompiler.canonicalPath,
                 };
-                if (await localArtifactHit(stampPath, opts.outPath, key))
+                const hit = await localArtifactHit(stampPath, opts.outPath, key);
+                if (hit !== null) {
+                    await opts.onArtifactReady?.({ dependencies: hit.dependencies }).catch(() => undefined);
                     return;
+                }
             }
         }
         catch {
@@ -3214,6 +3610,7 @@ export async function compileC(opts) {
         }
     }
     let implicitToolchain = null;
+    let implicitCompileToolchain = null;
     let toolchainMetadataStamp = null;
     const metadataCompiler = root === null
         ? null
@@ -3239,8 +3636,16 @@ export async function compileC(opts) {
                 root === null || toolchainMetadataKey === null
                     ? null
                     : await readNativeMetadataStamp(root, toolchainMetadataKey);
-            implicitToolchain = toolchainMetadataStamp?.values["implicitToolchain"] ??
-                await implicitToolchainFingerprint(driver, toolchainEnv);
+            implicitToolchain = toolchainMetadataStamp?.values["implicitToolchain"] ?? null;
+            implicitCompileToolchain =
+                toolchainMetadataStamp?.values["implicitCompileToolchain"] ?? null;
+            if (implicitToolchain === null ||
+                (programShards !== null && implicitCompileToolchain === null)) {
+                const fingerprints = await implicitToolchainFingerprints(driver, toolchainEnv);
+                implicitToolchain = fingerprints.complete;
+                implicitCompileToolchain = fingerprints.compile;
+                toolchainMetadataStamp = null;
+            }
             let compilerVersion = toolchainMetadataStamp?.values["compilerVersion"];
             if (compilerVersion === undefined) {
                 compilerVersion = await ccVersionOnce(driver.argv, toolchainEnv, true);
@@ -3249,73 +3654,122 @@ export async function compileC(opts) {
                 root !== null &&
                 toolchainMetadataKey !== null) {
                 if (metadataCompiler !== null && metadataEffectiveCompiler !== null) {
-                    toolchainMetadataStamp = await publishNativeMetadataStamp(root, toolchainMetadataKey, { implicitToolchain, compilerVersion }, [
+                    toolchainMetadataStamp = await publishNativeMetadataStamp(root, toolchainMetadataKey, {
+                        implicitToolchain,
+                        ...(implicitCompileToolchain === null ? {} : { implicitCompileToolchain }),
+                        compilerVersion,
+                    }, [
                         metadataCompiler.canonicalPath,
                         metadataEffectiveCompiler.canonicalPath,
                         ...fingerprintDependencyPaths(implicitToolchain),
-                    ], [implicitToolchain]);
+                        ...(implicitCompileToolchain === null
+                            ? []
+                            : fingerprintDependencyPaths(implicitCompileToolchain)),
+                    ], [
+                        implicitToolchain,
+                        ...(implicitCompileToolchain === null ? [] : [implicitCompileToolchain]),
+                    ]);
                 }
             }
         }
-        catch {
+        catch (error) {
             // Cache discovery is best-effort. In particular, a compiler wrapper can
             // compile successfully without implementing the metadata probes.
+            if (cacheWarmOnly) {
+                throw new Error("native cache warming could not validate the compiler toolchain", {
+                    cause: error,
+                });
+            }
             root = null;
         }
     }
     const vendorBuildIdentity = await currentVendorCacheBuildIdentity(driver, `${toolchainEnv}\0${implicitToolchain ?? "<uncached>"}`);
     // Mutable include/SDK/config inputs can change behind a stable environment
     // spelling. The complete/runtime cache is disabled below; vendor objects
-    // must follow the same rule instead of silently surviving in package-local
-    // .cache. A private root gives this invocation the usual vendor build recipe
+    // must follow the same rule instead of silently surviving in the user cache.
+    // A private root gives this invocation the usual vendor build recipe
     // without publishing or reusing those prerequisites.
-    const transientVendorRoot = persistentDriverCache && implicitToolchain !== null
+    const transientVendorRoot = root !== null && implicitToolchain !== null
         ? null
         : join(tmpdir(), `scriptc-vendor-${process.pid}-${Math.random().toString(36).slice(2)}`);
-    const vendorCacheRoot = transientVendorRoot ?? vendorBuildCacheRoot();
+    const vendorCacheRoot = transientVendorRoot ?? vendorBuildCacheRoot(root ?? undefined);
     // Every vendor output path is deterministic from pins, flags, driver, and
     // target. Build the command/key from those paths now, but do not materialize
     // them until a complete-binary lookup has missed.
-    const engineArchive = dynamic
+    let engineArchive = dynamic
         ? engineArchivePath(sanitize, driver, vendorBuildIdentity, vendorCacheRoot)
         : null;
-    const tlsArchive = tls
+    let tlsArchive = tls
         ? tlsArchivePath(sanitize, driver, vendorBuildIdentity, vendorCacheRoot)
         : null;
     // --dynamic + regex shares the archive's libregexp (its host hooks and
     // ours would collide; see scr_regex.c) — the standalone objects are for
     // static builds only.
-    const lreObjects = regex && !dynamic
+    let lreObjects = regex && !dynamic
         ? lreObjectPaths(sanitize, driver, vendorBuildIdentity, vendorCacheRoot)
         : [];
     // Vendored zlib is the CROSS story only — host builds keep the exact
     // historical `-lz` system link (see CcOptions.zlib). The native fetch's
     // gzip decoder rides the same objects/link.
-    const zlibObjects = ((opts.zlib ?? false) || nativeFetch) && driver.target !== null
+    let zlibObjects = ((opts.zlib ?? false) || nativeFetch) && driver.target !== null
         ? zlibObjectPaths(sanitize, driver, vendorBuildIdentity, vendorCacheRoot)
         : [];
     // The libcurl import stub is likewise CROSS-only — host builds keep the
     // exact historical system `-lcurl` link (see CcOptions.fetch). Curl
     // reference builds only.
-    const curlStubDir = curlFetch && driver.target !== null
+    let curlStubDir = curlFetch && driver.target !== null
         ? curlStubDirPath(driver, vendorBuildIdentity, vendorCacheRoot)
         : null;
-    const materializeVendorPrerequisites = async () => {
+    const materializeVendorPrerequisites = async (stageRoot, materializeCacheRoot = vendorCacheRoot) => {
         // Preserve the historical order to avoid multiplying first-build resource
         // pressure when several large vendor sets are cold simultaneously.
         if (dynamic) {
-            await ensureEngineArchive(sanitize, driver, vendorBuildIdentity, vendorCacheRoot);
+            const cachedArchive = engineArchivePath(sanitize, driver, vendorBuildIdentity, materializeCacheRoot);
+            protectCachedArtifact(cacheWarmPaths, cachedArchive);
+            const materialize = async () => [
+                await ensureEngineArchive(sanitize, driver, vendorBuildIdentity, materializeCacheRoot),
+            ];
+            const paths = stageRoot === undefined
+                ? await materialize()
+                : await stageVendorInputs(materialize, join(stageRoot, "engine"));
+            engineArchive = paths[0];
+        }
+        if (tls) {
+            const cachedArchive = tlsArchivePath(sanitize, driver, vendorBuildIdentity, materializeCacheRoot);
+            protectCachedArtifact(cacheWarmPaths, cachedArchive);
+            const materialize = async () => [
+                await ensureTlsArchive(sanitize, driver, vendorBuildIdentity, materializeCacheRoot),
+            ];
+            const paths = stageRoot === undefined
+                ? await materialize()
+                : await stageVendorInputs(materialize, join(stageRoot, "tls"));
+            tlsArchive = paths[0];
         }
-        if (tls)
-            await ensureTlsArchive(sanitize, driver, vendorBuildIdentity, vendorCacheRoot);
         if (regex && !dynamic) {
-            await ensureLreObjects(sanitize, driver, vendorBuildIdentity, vendorCacheRoot);
+            for (const object of lreObjectPaths(sanitize, driver, vendorBuildIdentity, materializeCacheRoot))
+                protectCachedArtifact(cacheWarmPaths, object);
+            const materialize = async () => await ensureLreObjects(sanitize, driver, vendorBuildIdentity, materializeCacheRoot);
+            lreObjects = stageRoot === undefined
+                ? await materialize()
+                : await stageVendorInputs(materialize, join(stageRoot, "lre"));
         }
         if (zlibObjects.length > 0) {
-            await ensureZlibObjects(sanitize, driver, vendorBuildIdentity, vendorCacheRoot);
+            for (const object of zlibObjectPaths(sanitize, driver, vendorBuildIdentity, materializeCacheRoot))
+                protectCachedArtifact(cacheWarmPaths, object);
+            const materialize = async () => await ensureZlibObjects(sanitize, driver, vendorBuildIdentity, materializeCacheRoot);
+            zlibObjects = stageRoot === undefined
+                ? await materialize()
+                : await stageVendorInputs(materialize, join(stageRoot, "zlib"));
         }
         if (curlStubDir !== null) {
-            await ensureCurlStub(driver, vendorBuildIdentity, vendorCacheRoot);
+            protectCachedArtifact(cacheWarmPaths, join(curlStubDirPath(driver, vendorBuildIdentity, materializeCacheRoot), "libcurl.so"));
+            const materialize = async () => [
+                join(await ensureCurlStub(driver, vendorBuildIdentity, materializeCacheRoot), "libcurl.so"),
+            ];
+            const paths = stageRoot === undefined
+                ? await materialize()
+                : await stageVendorInputs(materialize, join(stageRoot, "curl"));
+            curlStubDir = dirname(paths[0]);
         }
     };
     // rt() maps each runtime source's path on the command line: identity for
@@ -3326,7 +3780,7 @@ export async function compileC(opts) {
         ...threadArgs,
         ...(sanitize
             ? ["-O1", "-fsanitize=address", "-DSCR_RC_AUDIT"]
-            : ["-O2"]),
+            : [optimization === "dev" ? "-O0" : "-O2"]),
         ...(opts.textDecoderLegacy ? ["-DSCR_TEXT_DECODER_LEGACY"] : []),
         "-fno-math-errno",
         // The emitted object model is deliberately type-punned C: a hierarchy
@@ -3520,7 +3974,7 @@ export async function compileC(opts) {
         ...threadArgs,
         ...(sanitize
             ? ["-O1", "-fsanitize=address", "-DSCR_RC_AUDIT"]
-            : ["-O2"]),
+            : [optimization === "dev" ? "-O0" : "-O2"]),
         ...(opts.textDecoderLegacy ? ["-DSCR_TEXT_DECODER_LEGACY"] : []),
         "-fno-math-errno",
         "-fno-strict-aliasing", // the emitted object model type-puns — see buildArgs
@@ -3553,6 +4007,16 @@ export async function compileC(opts) {
                 `${guidance}\n\n${stderr}`);
         }
     };
+    const runUncachedBuild = async () => {
+        const privateVendorRoot = transientVendorRoot ?? join(tmpdir(), `scriptc-vendor-fallback-${process.pid}-${Math.random().toString(36).slice(2)}`);
+        try {
+            await materializeVendorPrerequisites(undefined, privateVendorRoot);
+            await runClang(buildArgs((p) => p));
+        }
+        finally {
+            await rm(privateVendorRoot, { recursive: true, force: true }).catch(() => undefined);
+        }
+    };
     let runtimeCompilerInvocation = null;
     let programCompilerInvocation = null;
     let payloadMetadata = null;
@@ -3613,23 +4077,20 @@ export async function compileC(opts) {
                 }
             }
         }
-        catch {
+        catch (error) {
             // Preserve the uncached build for wrappers that compile successfully but
             // cannot provide a dry-run trace for the real build flavor.
+            if (cacheWarmOnly) {
+                throw new Error("native cache warming could not validate the compiler invocation", {
+                    cause: error,
+                });
+            }
             root = null;
         }
     }
     if (root === null) {
         // The exact historical command line, byte for byte.
-        try {
-            await materializeVendorPrerequisites();
-            await runClang(buildArgs((p) => p));
-        }
-        finally {
-            if (transientVendorRoot !== null) {
-                await rm(transientVendorRoot, { recursive: true, force: true }).catch(() => undefined);
-            }
-        }
+        await runUncachedBuild();
         return;
     }
     let cv;
@@ -3642,12 +4103,16 @@ export async function compileC(opts) {
             readFile(opts.cPath),
         ]));
     }
-    catch {
+    catch (error) {
         // A version/fingerprint probe is an optimization boundary. If the compiler
         // itself can still compile, preserve the pre-cache behavior instead of
         // surfacing a metadata command's failure as the build result.
-        await materializeVendorPrerequisites();
-        await runClang(buildArgs((p) => p));
+        if (cacheWarmOnly) {
+            throw new Error("native cache warming could not validate cache inputs", {
+                cause: error,
+            });
+        }
+        await runUncachedBuild();
         return;
     }
     // Caller-supplied native inputs can all hide mutable dependencies: `-l`
@@ -3655,7 +4120,8 @@ export async function compileC(opts) {
     // script can retain identical top-level bytes as its referenced files are
     // rebuilt. Keep the safe runtime-object cache, but force a fresh final link
     // whenever the caller supplies either form.
-    let cacheCompleteArtifact = cachePolicy.completeArtifacts &&
+    let cacheCompleteArtifact = !cacheWarmOnly &&
+        cachePolicy.completeArtifacts &&
         (opts.linkInputs?.length ?? 0) === 0 &&
         (opts.systemLibraries?.length ?? 0) === 0;
     let programDependencies = null;
@@ -3714,6 +4180,7 @@ export async function compileC(opts) {
             linkProbeArgs,
             effectiveLinkInvocationArgs,
             linkTraceInvocationArgs,
+            ...(programShardMergeIdentity === null ? [] : [programShardMergeIdentity]),
         ]);
     if (cacheCompleteArtifact) {
         try {
@@ -3745,6 +4212,9 @@ export async function compileC(opts) {
                 ...(linkMetadataStamp?.dependencies.map((dependency) => dependency.path) ??
                     fingerprintDependencyPaths(implicitLinker)),
                 ...fingerprintDependencyPaths(programDependencies),
+                ...(programShardMergeIdentity === null
+                    ? []
+                    : fingerprintDependencyPaths(programShardMergeIdentity)),
             ]);
             // Every content-bearing fingerprint was computed before this metadata
             // snapshot. Re-read those exact files now so the snapshot cannot certify
@@ -3755,11 +4225,12 @@ export async function compileC(opts) {
                 programCompilerInvocation,
                 implicitLinker,
                 programDependencies,
+                ...(programShardMergeIdentity === null ? [] : [programShardMergeIdentity]),
             ])) ||
                 await runtimeFingerprint(rtDir).catch(() => null) !== fingerprint ||
                 !(await Promise.all([toolchainMetadataStamp, compileMetadataStamp, linkMetadataStamp]
                     .filter((stamp) => stamp !== null)
-                    .map((stamp) => localArtifactDependenciesStillMatch(stamp.dependencies)))).every(Boolean)) {
+                    .map((stamp) => nativeArtifactDependenciesStillMatch(stamp.dependencies)))).every(Boolean)) {
                 throw new CacheInputsChangedError();
             }
             if (localArtifact !== null) {
@@ -3784,6 +4255,25 @@ export async function compileC(opts) {
             localArtifactDependencyPaths = null;
         }
     }
+    // Warm-only builds deliberately do not need linker/header identity for a
+    // complete executable, but they still need a stable runtime-object key.
+    // The ordinary complete-artifact path computes these values above.
+    if (cacheWarmOnly && preBuildDependencies === null) {
+        try {
+            const [dependencies, invocation] = await Promise.all([
+                translationUnitDependencyFingerprint(driver, cflags, opts.cPath, cBytes, toolchainEnv),
+                effectiveCompilerInvocationFingerprint(driver, toolchainEnv, cflags),
+            ]);
+            programDependencies = dependencies;
+            if (runtimeCompilerInvocation === null)
+                runtimeCompilerInvocation = invocation;
+        }
+        catch (error) {
+            throw new Error("native cache warming could not validate runtime-object inputs", {
+                cause: error,
+            });
+        }
+    }
     const binDir = join(root, "bin");
     let keyHex = null;
     let cachedBin = null;
@@ -3795,9 +4285,10 @@ export async function compileC(opts) {
         // the fingerprint and the pin.
         const identityArgs = buildArgs((p) => p).map((a) => a === opts.cPath ? "<program.c>" : a === opts.outPath ? "<out>" : a);
         const key = createHash("sha256")
-            // v9 adds effective compiler-wrapper invocations for the real runtime,
-            // program, and link flavors.
-            .update("bin-v9\0")
+            // Sharded dev builds need the v10 identity below. Canonical single-TU
+            // builds retain v9 so adding the opt-in mode does not evict release
+            // binaries compiled by an earlier scriptc.
+            .update(programShards === null ? "bin-v9\0" : "bin-v10\0")
             .update(cacheTargetIdentity(driver)).update("\0")
             .update(toolchainEnv).update("\0")
             .update(implicitToolchain).update("\0")
@@ -3819,6 +4310,9 @@ export async function compileC(opts) {
             .update(fingerprint).update("\0")
             .update(identityArgs.join("\x1f")).update("\0")
             .update(cBytes);
+        if (programShards !== null) {
+            updateProgramShardCacheIdentity(key, programShards, programPublicSymbols, programShardMergeIdentity ?? undefined);
+        }
         keyHex = key.digest("hex");
         cachedBin = join(binDir, keyHex);
         const tmpOut = privateSiblingPath(opts.outPath, "bin-hit");
@@ -3835,7 +4329,10 @@ export async function compileC(opts) {
             await chmod(tmpOut, 0o777 & ~process.umask());
             await rename(tmpOut, opts.outPath);
             if (localArtifact !== null && localArtifactDependencyPaths !== null) {
-                await publishLocalArtifactStamp(localArtifact.stampPath, opts.outPath, localArtifact.key, localArtifactDependencyPaths, [dirname(resolve(opts.cPath))], [root]).catch(() => undefined);
+                const stamp = await publishLocalArtifactStamp(localArtifact.stampPath, opts.outPath, localArtifact.key, localArtifactDependencyPaths, [dirname(resolve(opts.cPath))], [root]).catch(() => null);
+                if (stamp !== null) {
+                    await opts.onArtifactReady?.({ dependencies: stamp.dependencies }).catch(() => undefined);
+                }
             }
             return; // hit: the program/runtime payload compile and link were skipped
         }
@@ -3844,7 +4341,6 @@ export async function compileC(opts) {
             /* miss — build below, then publish */
         }
     }
-    await materializeVendorPrerequisites();
     // Miss: link the program's own TU against cached per-flavor runtime objects.
     // Collect the runtime sources this build actually compiles (the same
     // conditionals as the command line, by construction).
@@ -3855,6 +4351,7 @@ export async function compileC(opts) {
     });
     const buildDir = await mkdtemp(join(tmpdir(), "scriptc-cache-build-"));
     try {
+        await materializeVendorPrerequisites(join(buildDir, "vendor-inputs"));
         // Freeze the exact bytes used for the key. Generated TUs live at stable
         // paths under .scriptc/, so two builds can otherwise overwrite that path
         // between hashing and clang and publish one invocation's code under the
@@ -3875,7 +4372,7 @@ export async function compileC(opts) {
         let strictObjectVerification = null;
         const objectImplicitToolchainStillMatches = () => {
             if (preBuildDependencies !== null) {
-                return localArtifactDependenciesStillMatch(preBuildDependencies);
+                return nativeArtifactDependenciesStillMatch(preBuildDependencies);
             }
             // Complete-artifact caching can be disabled by caller-owned native
             // inputs while the safe runtime-object tier remains active. Preserve its
@@ -3890,15 +4387,116 @@ export async function compileC(opts) {
             return strictObjectVerification;
         };
         try {
-            const cached = await ensureRuntimeObjects(root, driver.argv, cflags, rtInputs, `obj-v5\0${cacheTargetIdentity(driver)}\0${toolchainEnv}\0${implicitToolchain}\0${runtimeCompilerInvocation}\0${ccName}\0${cv}\0${fingerprint}\0`, async () => await objectImplicitToolchainStillMatches());
+            const cached = await ensureRuntimeObjects(root, driver.argv, cflags, rtInputs, `obj-v5\0${cacheTargetIdentity(driver)}\0${toolchainEnv}\0${implicitToolchain}\0${runtimeCompilerInvocation}\0${ccName}\0${cv}\0${fingerprint}\0`, async () => await objectImplicitToolchainStillMatches(), cacheWarmPaths);
             objects = await stageRuntimeObjects(cached, join(buildDir, "runtime-objects"));
         }
         catch (err) {
             if (err instanceof CacheInputsChangedError)
                 cacheInputsStable = false;
+            if (cacheWarmOnly) {
+                throw new Error("native cache warming could not persist runtime objects", {
+                    cause: err,
+                });
+            }
             objects = null; // cache trouble is never a build failure
         }
-        await runClang(buildArgs((p) => objects?.get(p) ?? p, { programPath, outPath: privateOut, compilerVisibleSource: opts.cPath }));
+        const compileShardedProgram = async () => {
+            if (programShards === null || programPublicSymbols === undefined ||
+                programCompilerInvocation === null || implicitCompileToolchain === null)
+                return null;
+            try {
+                const programDependencyHash = programDependencies ??
+                    await translationUnitDependencyFingerprint(driver, cflags, opts.cPath, cBytes, toolchainEnv);
+                const stem = basename(opts.cPath, ".ll");
+                const entries = programShards.map((shard, index) => {
+                    const sourcePath = join(buildDir, shard.name);
+                    const staged = join(buildDir, `${stem}.program-${index.toString().padStart(3, "0")}.o`);
+                    const key = createHash("sha256")
+                        .update("exe-program-shard-v1\0")
+                        .update(cacheTargetIdentity(driver)).update("\0")
+                        .update(toolchainEnv).update("\0")
+                        .update(implicitCompileToolchain).update("\0")
+                        .update(programCompilerInvocation).update("\0")
+                        .update(opts.cacheIdentity).update("\0")
+                        .update(driver.argv.join("\x1f")).update("\0")
+                        .update(cv).update("\0")
+                        .update(fingerprint).update("\0")
+                        .update(programDependencyHash).update("\0")
+                        .update(programCompilerArgs.join("\x1f")).update("\0")
+                        .update(opts.cPath).update("\0")
+                        .update(resolve(opts.cPath)).update("\0")
+                        .update(shard.name).update("\0")
+                        .update(shard.source)
+                        .digest("hex");
+                    return {
+                        ...shard,
+                        sourcePath,
+                        staged,
+                        cachePath: join(root, "program-shard", key),
+                        missed: false,
+                    };
+                });
+                const shardWidth = Math.min(8, availableParallelism());
+                for (let i = 0; i < entries.length; i += shardWidth) {
+                    await Promise.all(entries.slice(i, i + shardWidth).map(async (entry) => {
+                        await writeFile(entry.sourcePath, entry.source);
+                        if (await copyValidCachedFile(entry.cachePath, entry.staged))
+                            return;
+                        entry.missed = true;
+                        await runClang([
+                            ...programCompilerArgs,
+                            `-ffile-prefix-map=${entry.sourcePath}=${opts.cPath}`,
+                            "-c",
+                            entry.sourcePath,
+                            "-o",
+                            entry.staged,
+                        ]);
+                    }));
+                }
+                const arArgv = driver.argv[0] === "zig" ? [driver.argv[0], "ar"] : ["ar"];
+                const merged = await localizeLibraryObjects(driver, arArgv, buildDir, entries.map((entry) => entry.staged), [], programPublicSymbols, `${stem}.program`);
+                const publishable = entries.filter((entry) => entry.missed);
+                if (publishable.length > 0) {
+                    try {
+                        const [currentRuntime, currentFingerprints, currentInvocation, currentDependencies, currentCompiler, currentMerge] = await Promise.all([
+                            runtimeFingerprint(rtDir),
+                            implicitToolchainFingerprints(driver, toolchainEnv),
+                            effectiveCompilerInvocationFingerprint(driver, toolchainEnv, programCompilerArgs, ".ll"),
+                            translationUnitDependencyFingerprint(driver, cflags, opts.cPath, cBytes, toolchainEnv),
+                            ccVersionOnce(driver.argv, toolchainEnv, true),
+                            resolveProgramShardMergeIdentity(driver),
+                        ]);
+                        if (currentRuntime === fingerprint &&
+                            currentFingerprints.compile === implicitCompileToolchain &&
+                            currentInvocation === programCompilerInvocation &&
+                            currentDependencies === programDependencyHash &&
+                            currentCompiler === cv &&
+                            currentMerge === programShardMergeIdentity) {
+                            await Promise.all(publishable.map((entry) => publishCachedFile(entry.staged, entry.cachePath)));
+                        }
+                    }
+                    catch {
+                        // The merged object is valid for this invocation; publication is
+                        // only an optimization for later edits.
+                    }
+                }
+                return merged;
+            }
+            catch {
+                // Sharding is an optimization. Compile/link the canonical TU below if
+                // a target tool, one shard, or relocatable merge is unavailable.
+                return null;
+            }
+        };
+        const shardedProgramObject = await compileShardedProgram();
+        if (programShards !== null && shardedProgramObject === null) {
+            // The canonical TU fallback is valid output, but it must not populate a
+            // cache key describing a successful shard projection/merge.
+            cacheInputsStable = false;
+        }
+        await runClang(buildArgs((p) => objects?.get(p) ?? p, shardedProgramObject === null
+            ? { programPath, outPath: privateOut, compilerVisibleSource: opts.cPath }
+            : { programPath: shardedProgramObject, outPath: privateOut }));
         await installArtifact(privateOut, opts.outPath);
         if (cachedBin !== null && keyHex !== null) {
             // Metadata comparison catches ordinary changes cheaply, but cannot by
@@ -3906,7 +4504,7 @@ export async function compileC(opts) {
             // the key. Recompute every content-bearing identity after the final link
             // so a header/SDK/compiler change in either pre-build gap cannot publish
             // new output under an old key.
-            const [currentRuntime, currentImplicit, currentRuntimeInvocation, currentProgramInvocation, currentProgramDependencies, currentLinker, currentCompiler] = await Promise.all([
+            const [currentRuntime, currentImplicit, currentRuntimeInvocation, currentProgramInvocation, currentProgramDependencies, currentLinker, currentCompiler, currentProgramShardMerge] = await Promise.all([
                 runtimeFingerprint(rtDir).catch(() => null),
                 implicitToolchainFingerprint(driver, toolchainEnv).catch(() => null),
                 effectiveCompilerInvocationFingerprint(driver, toolchainEnv, cflags).catch(() => null),
@@ -3914,18 +4512,22 @@ export async function compileC(opts) {
                 translationUnitDependencyFingerprint(driver, cflags, opts.cPath, cBytes, toolchainEnv).catch(() => null),
                 implicitLinkerFingerprint(driver, toolchainEnv, linkProbeArgs, effectiveLinkInvocationArgs, linkTraceInvocationArgs).catch(() => null),
                 ccVersionOnce(driver.argv, toolchainEnv, true).catch(() => null),
+                programShards === null
+                    ? Promise.resolve(null)
+                    : resolveProgramShardMergeIdentity(driver).catch(() => null),
             ]);
             cacheInputsStable =
                 cacheInputsStable &&
                     preBuildDependencies !== null &&
-                    await localArtifactDependenciesStillMatch(preBuildDependencies) &&
+                    await nativeArtifactDependenciesStillMatch(preBuildDependencies) &&
                     currentRuntime === fingerprint &&
                     currentImplicit === implicitToolchain &&
                     currentRuntimeInvocation === runtimeCompilerInvocation &&
                     currentProgramInvocation === programCompilerInvocation &&
                     currentProgramDependencies === programDependencies &&
                     currentLinker === implicitLinker &&
-                    currentCompiler === cv;
+                    currentCompiler === cv &&
+                    currentProgramShardMerge === programShardMergeIdentity;
         }
         if (cachedBin !== null && keyHex !== null && cacheInputsStable) {
             try {
@@ -3942,7 +4544,10 @@ export async function compileC(opts) {
             localArtifactDependencyPaths !== null &&
             cacheCompleteArtifact &&
             cacheInputsStable) {
-            await publishLocalArtifactStamp(localArtifact.stampPath, opts.outPath, localArtifact.key, localArtifactDependencyPaths, [dirname(resolve(opts.cPath))], [root]).catch(() => undefined);
+            const stamp = await publishLocalArtifactStamp(localArtifact.stampPath, opts.outPath, localArtifact.key, localArtifactDependencyPaths, [dirname(resolve(opts.cPath))], [root]).catch(() => null);
+            if (stamp !== null) {
+                await opts.onArtifactReady?.({ dependencies: stamp.dependencies }).catch(() => undefined);
+            }
         }
     }
     finally {
@@ -3950,6 +4555,78 @@ export async function compileC(opts) {
     }
     // Runtime-object population is itself a cache write, including on builds
     // whose native link inputs disable complete-artifact publication.
-    await pruneCache(root).catch(() => undefined);
+    await pruneCache(root, cacheWarmPaths).catch(() => undefined);
+}
+export async function compileC(opts) {
+    await compileCInternal(opts, false);
+}
+export function supportedNativeCacheWarmProfiles(driver) {
+    if (isMobileTarget(driver.target) || targetPlatform(driver) === "wasi")
+        return [];
+    return ["runtime", "tls", "dynamic"];
+}
+/** Populate expensive native prerequisites against the current compiler,
+ * target, SDK, and environment. The resulting entries use the exact same
+ * identities and validators as ordinary builds; this merely pays their cost
+ * before a developer's first program asks for them. Synthetic link products
+ * are discarded and never enter the complete-executable cache. */
+export async function warmNativeCaches(options = {}) {
+    const cacheRoot = cacheRootDir();
+    if (cacheRoot === null) {
+        throw new Error("the native build cache is disabled (unset SCRIPTC_NO_CACHE and use a non-empty SCRIPTC_CACHE_DIR)");
+    }
+    await ensurePrivateCacheRoot(cacheRoot, process.env["SCRIPTC_CACHE_DIR"] === undefined);
+    const known = new Set(["runtime", "tls", "dynamic"]);
+    for (const profile of options.profiles ?? []) {
+        if (!known.has(profile))
+            throw new Error(`unknown native cache warm profile '${profile}'`);
+    }
+    if (options.profiles?.length === 0)
+        return { cacheRoot, profiles: [] };
+    const mobileTarget = mobileLibraryTarget();
+    if (mobileTarget !== null) {
+        throw new Error(`native cache warming targets executable builds and is unsupported for SCRIPTC_TARGET=${mobileTarget}`);
+    }
+    const driver = resolveCc();
+    const supported = supportedNativeCacheWarmProfiles(driver);
+    if (supported.length === 0) {
+        throw new Error(`native cache warming targets persistently cached native executables and is unsupported for SCRIPTC_TARGET=${driver.target}`);
+    }
+    const profiles = [...new Set(options.profiles ?? supported)];
+    for (const profile of profiles) {
+        if (!supported.includes(profile)) {
+            throw new Error(`native cache warm profile '${profile}' is unsupported for SCRIPTC_TARGET=${driver.target}`);
+        }
+    }
+    const workDir = await mkdtemp(join(tmpdir(), "scriptc-cache-warm-"));
+    const cPath = join(workDir, "warm.c");
+    await writeFile(cPath, "int main(void) { return 0; }\n");
+    const protectedPaths = new Set();
+    try {
+        const results = await Promise.all(profiles.map(async (profile) => {
+            const started = performance.now();
+            await compileCInternal({
+                cPath,
+                outPath: join(workDir, process.platform === "win32" ? `${profile}.exe` : profile),
+                cacheIdentity: "scriptc-native-cache-warm-v1",
+                optimization: options.optimization ?? "release",
+                sanitize: options.sanitize ?? false,
+                ...(profile === "tls" ? { fetch: true } : {}),
+                ...(profile === "dynamic" ? { dynamic: true } : {}),
+            }, true, protectedPaths);
+            return {
+                profile,
+                elapsedMs: Math.round((performance.now() - started) * 10) / 10,
+            };
+        }));
+        await pruneCache(cacheRoot).catch(() => undefined);
+        if (!(await Promise.all([...protectedPaths].map(fileExists))).every(Boolean)) {
+            throw new Error(`SCRIPTC_CACHE_MAX_MB is too small to retain the requested native cache warm profiles (${profiles.join(", ")})`);
+        }
+        return { cacheRoot, profiles: results };
+    }
+    finally {
+        await rm(workDir, { recursive: true, force: true }).catch(() => undefined);
+    }
 }
 //# sourceMappingURL=cc.js.map