@scriptc/compiler 0.0.32 → 0.0.34

package/dist/backend/cc.js

@@ -2,9 +2,9 @@ import { execFile, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { constants as fsConstants, existsSync, readdirSync } from "node:fs";
 import { createRequire } from "node:module";
-import { access, chmod, copyFile, link, mkdir, mkdtemp, readdir, readFile, realpath, rename, rm, stat, unlink, utimes, writeFile } from "node:fs/promises";
+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, resolve } from "node:path";
+import { basename, delimiter, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { promisify } from "node:util";
 import { localizeElfObject, mergeAndLocalizeCoffObjects } from "./object-localize.js";
 const execFileAsync = promisify(execFile);
@@ -32,7 +32,7 @@ function stableTestMemo(cache, key, probe) {
     });
     return pending;
 }
-const RUNTIME_SOURCES = ["scr_number.c", "scr_string.c", "scr_array.c", "scr_bytes.c", "scr_bytes_io.c", "scr_map.c", "scr_closure.c", "scr_object.c", "scr_union.c", "scr_exception.c", "scr_error.c", "scr_console.c", "scr_lib.c", "scr_path.c", "scr_url.c", "scr_json.c", "scr_async.c", "scr_child.c", "scr_cycle.c"];
+const RUNTIME_SOURCES = ["scr_number.c", "scr_string.c", "scr_array.c", "scr_bytes.c", "scr_bytes_io.c", "scr_map.c", "scr_closure.c", "scr_ffi.c", "scr_object.c", "scr_union.c", "scr_exception.c", "scr_error.c", "scr_console.c", "scr_lib.c", "scr_path.c", "scr_url.c", "scr_json.c", "scr_async.c", "scr_child.c", "scr_cycle.c"];
 /** The pinned quickjs-ng snapshot under packages/runtime/vendor/quickjs-ng
  * (see vendor/README.md — update both together). Keys the archive cache so
  * a vendor bump can never reuse a stale engine build. */
@@ -974,13 +974,14 @@ async function ensureTlsArchive(sanitize, driver, buildIdentity, cacheRoot = ven
 /** The library base: the executable lane's unconditional sources minus the
  * fiber/loop and child-process units, plus the library-mode TU. */
 const LIB_RUNTIME_SOURCES = [
-    ...RUNTIME_SOURCES.filter((f) => f !== "scr_async.c" && f !== "scr_child.c"),
+    ...RUNTIME_SOURCES.filter((f) => f !== "scr_async.c" && f !== "scr_child.c" && f !== "scr_ffi.c"),
     "scr_library.c",
 ];
 export async function compileLibArchive(opts) {
     const rtDir = runtimeSrcDir();
     const driver = resolveCc();
     const sanitize = opts.sanitize ?? false;
+    const optimization = opts.optimization ?? "release";
     const regex = opts.regex ?? false;
     const sources = [
         ...LIB_RUNTIME_SOURCES,
@@ -1008,7 +1009,9 @@ export async function compileLibArchive(opts) {
     const cflags = [
         "-std=c11",
         ...driver.targetArgs,
-        ...(sanitize ? ["-O1", "-fsanitize=address", "-DSCR_RC_AUDIT"] : ["-O2"]),
+        ...(sanitize
+            ? ["-O1", "-fsanitize=address", "-DSCR_RC_AUDIT"]
+            : [optimization === "dev" ? "-O0" : "-O2"]),
         "-fno-math-errno",
         "-fno-strict-aliasing", // the emitted object model type-puns — see compileC's buildArgs
         "-Wno-deprecated-declarations",
@@ -1084,24 +1087,26 @@ export async function compileLibArchive(opts) {
     let archiverVersion = "";
     let runtimeHash = "";
     let programDependencyHash = "";
-    let cachedProgramBytes = null;
+    let cachedProgramBytes = opts.programSource === undefined
+        ? null
+        : Buffer.from(opts.programSource, "utf8");
+    const identityBytes = opts.identityCSource === undefined
+        ? null
+        : Buffer.from(opts.identityCSource, "utf8");
     if (root !== null) {
         try {
             const [cv, fingerprint, programBytes] = await Promise.all([
                 ccVersionOnce(driver.argv, toolchainEnv, true),
                 runtimeFingerprint(rtDir),
-                readFile(opts.cPath),
+                cachedProgramBytes === null ? readFile(opts.cPath) : Promise.resolve(cachedProgramBytes),
             ]);
             compilerVersion = cv;
             runtimeHash = fingerprint;
             cachedProgramBytes = programBytes;
+            programDependencyHash = await translationUnitDependencyFingerprint(driver, cflags, opts.cPath, programBytes, toolchainEnv);
             if (cacheCompleteArchive) {
-                const [av, programDependencies] = await Promise.all([
-                    toolVersionOnce(arArgv, toolchainEnv, true),
-                    translationUnitDependencyFingerprint(driver, cflags, opts.cPath, programBytes, toolchainEnv),
-                ]);
+                const av = await toolVersionOnce(arArgv, toolchainEnv, true);
                 archiverVersion = av;
-                programDependencyHash = programDependencies;
                 const key = createHash("sha256")
                     // v7 adds effective compiler-wrapper invocations for the real runtime
                     // and program compile flavors.
@@ -1111,7 +1116,7 @@ export async function compileLibArchive(opts) {
                     .update(implicitToolchain).update("\0")
                     .update(runtimeCompilerInvocation).update("\0")
                     .update(programCompilerInvocation).update("\0")
-                    .update(programDependencies).update("\0")
+                    .update(programDependencyHash).update("\0")
                     .update(opts.cacheIdentity).update("\0")
                     .update(driver.argv.join("\x1f")).update("\0")
                     .update(cv).update("\0")
@@ -1126,6 +1131,9 @@ export async function compileLibArchive(opts) {
                     .update(opts.cPath).update("\0")
                     .update(resolve(opts.cPath)).update("\0")
                     .update(programBytes)
+                    .update("\0identity\0")
+                    .update(identityBytes === null ? "<none>" : "<generated>").update("\0")
+                    .update(identityBytes ?? Buffer.alloc(0))
                     .digest("hex");
                 cachedArchive = join(root, "lib", key);
                 const tmpOut = privateSiblingPath(opts.outPath, "lib-hit");
@@ -1197,7 +1205,64 @@ export async function compileLibArchive(opts) {
                 : join(buildDir, `program${opts.cPath.endsWith(".ll") ? ".ll" : ".c"}`);
             if (cachedProgramBytes !== null)
                 await writeFile(programSource, cachedProgramBytes);
-            const programObject = await compileOne(programSource, `${stem}.program.o`, cachedProgramBytes === null ? undefined : opts.cPath);
+            let cachedProgramObject = null;
+            if (root !== null && cachedProgramBytes !== null && compilerVersion !== "" &&
+                implicitToolchain !== null && programCompilerInvocation !== null) {
+                const programKey = createHash("sha256")
+                    .update("lib-program-obj-v1\0")
+                    .update(cacheTargetIdentity(driver)).update("\0")
+                    .update(toolchainEnv).update("\0")
+                    .update(implicitToolchain).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(cachedProgramBytes)
+                    .digest("hex");
+                cachedProgramObject = join(root, "program-obj", programKey);
+            }
+            const stagedProgramObject = join(buildDir, `${stem}.program.o`);
+            let programObject;
+            if (cachedProgramObject !== null &&
+                await copyValidCachedFile(cachedProgramObject, stagedProgramObject)) {
+                programObject = stagedProgramObject;
+            }
+            else {
+                programObject = await compileOne(programSource, `${stem}.program.o`, cachedProgramBytes === null ? undefined : opts.cPath);
+                if (cachedProgramObject !== null) {
+                    try {
+                        const [currentRuntime, currentImplicit, currentInvocation, currentDependencies, currentCompiler] = await Promise.all([
+                            runtimeFingerprint(rtDir),
+                            implicitToolchainFingerprint(driver, toolchainEnv),
+                            effectiveCompilerInvocationFingerprint(driver, toolchainEnv, programCompilerArgs, programSourceExtension),
+                            translationUnitDependencyFingerprint(driver, cflags, opts.cPath, cachedProgramBytes, toolchainEnv),
+                            ccVersionOnce(driver.argv, toolchainEnv, true),
+                        ]);
+                        if (currentRuntime === runtimeHash &&
+                            currentImplicit === implicitToolchain &&
+                            currentInvocation === programCompilerInvocation &&
+                            currentDependencies === programDependencyHash &&
+                            currentCompiler === compilerVersion) {
+                            await publishCachedFile(programObject, cachedProgramObject);
+                        }
+                    }
+                    catch {
+                        // Best-effort: the archive build already owns a valid object.
+                    }
+                }
+            }
+            const identityObject = identityBytes === null
+                ? null
+                : await (async () => {
+                    const source = join(buildDir, "identity.c");
+                    await writeFile(source, identityBytes);
+                    return compileOne(source, `${stem}.identity.o`);
+                })();
             let runtimeObjects = null;
             let cacheInputsStable = true;
             let objectImplicitVerification = null;
@@ -1230,14 +1295,14 @@ export async function compileLibArchive(opts) {
                     runtimeObjects.push(...(await Promise.all(sources.slice(i, i + width).map((f) => compileOne(join(rtDir, f), f.replace(/\.c$/, ".o"))))));
                 }
             }
-            const objects = [programObject, ...runtimeObjects, ...lreObjects, ...zlibObjects];
+            const objects = [programObject, ...(identityObject === null ? [] : [identityObject]), ...runtimeObjects, ...lreObjects, ...zlibObjects];
             // Multi-instance library mode: the archive's one member becomes the
             // combined, symbol-localized object (cached vendor/runtime objects
             // are read-only inputs here — the combine step never mutates them).
             const archiveMembers = opts.localizeSymbols === undefined
                 ? objects
                 : [
-                    await localizeLibraryObjects(driver, arArgv, buildDir, programObject, [...runtimeObjects, ...lreObjects, ...zlibObjects], opts.localizeSymbols, stem),
+                    await localizeLibraryObjects(driver, arArgv, buildDir, [programObject, ...(identityObject === null ? [] : [identityObject])], [...runtimeObjects, ...lreObjects, ...zlibObjects], opts.localizeSymbols, stem),
                 ];
             // A cacheable or runtime-localized build owns a private archive from
             // `ar` through publication. Localized archives deliberately bypass the
@@ -1317,7 +1382,8 @@ export async function compileLibArchive(opts) {
  * shared by design. Windows embedders additionally link advapi32, iphlpapi,
  * and ws2_32.
  *
- * Member selection matters: a classic archive's unused members (and their
+ * The generated program and optional identity objects are mandatory roots;
+ * support-member selection still matters. A classic archive's unused members (and their
  * undefined references to units library mode excludes, like the
  * fs-promises unit's fiber symbols) never reach an embedder's link. A
  * blind merge of every object would carry those references into the one
@@ -1326,7 +1392,7 @@ export async function compileLibArchive(opts) {
  * members the program object transitively needs (the COFF arm implements
  * the same member semantics in process).
  *
- *   Mach-O — one host-ld64 invocation: -r merges program + needed members,
+ *   Mach-O — one host-ld64 invocation: -r merges roots + needed members,
  *            -exported_symbols_list demotes every unlisted global to
  *            private extern, and -r without -keep_private_externs writes
  *            private externs out as non-external symbols. Apple ASan's
@@ -1357,7 +1423,7 @@ export async function compileLibArchive(opts) {
  *            mirrors MSVC link.exe; zig's COFF driver refuses multi-object
  *            merges) and llvm-objcopy rejects symbol-scope flags for
  *            COFF, so no tool pairing exists to shell out to. */
-async function localizeLibraryObjects(driver, arArgv, buildDir, programObject, supportObjects, keepSymbols, stem) {
+async function localizeLibraryObjects(driver, arArgv, buildDir, rootObjects, supportObjects, keepSymbols, stem) {
     const platform = targetPlatform(driver);
     const combined = join(buildDir, `${stem}.localized.o`);
     const staging = join(buildDir, `${stem}.localize-staging.a`);
@@ -1375,10 +1441,13 @@ async function localizeLibraryObjects(driver, arArgv, buildDir, programObject, s
     if (platform === "win32") {
         // COFF has no relocatable-link tool to stage through; the member
         // selection and combine+demote happen in process over the object bytes.
-        const [program, ...support] = await Promise.all([programObject, ...supportObjects].map((path) => readFile(path)));
+        const [roots, support] = await Promise.all([
+            Promise.all(rootObjects.map((path) => readFile(path))),
+            Promise.all(supportObjects.map((path) => readFile(path))),
+        ]);
         try {
-            await writeFile(combined, mergeAndLocalizeCoffObjects(program, support, new Set(keepSymbols), {
-                program: basename(programObject),
+            await writeFile(combined, mergeAndLocalizeCoffObjects(roots, support, new Set(keepSymbols), {
+                roots: rootObjects.map((path) => basename(path)),
                 support: supportObjects.map((path) => basename(path)),
             }));
         }
@@ -1390,11 +1459,11 @@ async function localizeLibraryObjects(driver, arArgv, buildDir, programObject, s
     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", programObject, staging, "-o", combined, "-exported_symbols_list", keepFile]);
+        await run(["ld", "-r", ...rootObjects, staging, "-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", programObject, staging, "-o", combined]);
+        await run(["ld", "-r", "--force-group-allocation", ...rootObjects, staging, "-o", combined]);
         await run(["objcopy", `--keep-global-symbols=${keepFile}`, combined]);
     }
     else if (platform === "linux") {
@@ -1409,7 +1478,7 @@ async function localizeLibraryObjects(driver, arArgv, buildDir, programObject, s
             ...driver.argv.slice(1),
             "-target", driver.zigTarget ?? driver.target,
             "-nostdlib",
-            "-r", programObject, staging,
+            "-r", ...rootObjects, staging,
             "-o", combined,
         ]);
         try {
@@ -1518,6 +1587,31 @@ export function resolveBuildCacheRoot(env = process.env, platform = process.plat
         ? resolve(userHome, "Library", "Caches", "scriptc", "build")
         : resolve(userHome, ".cache", "scriptc", "build");
 }
+/** Shared persistent-cache root for compiler-level tiers.  The early library
+ * cache deliberately follows the native cache's activation and hard-disable
+ * contract, while native compilation retains ownership of toolchain safety. */
+export function buildCacheRoot() {
+    return resolveBuildCacheRoot();
+}
+/** Harden/create a compiler-level cache root using the same privacy policy as
+ * the artifact caches.  Failure disables only the optional caller's tier. */
+export async function prepareBuildCacheRoot(root) {
+    if (root === null)
+        return null;
+    try {
+        await ensurePrivateCacheRoot(root, process.env["SCRIPTC_CACHE_DIR"] === undefined);
+        return root;
+    }
+    catch {
+        return null;
+    }
+}
+/** Register a successful compiler-level cache write with the shared bounded
+ * LRU policy. */
+export async function pruneBuildCache(root) {
+    if (root !== null)
+        await pruneCache(root).catch(() => undefined);
+}
 function cacheRootDir() {
     return resolveBuildCacheRoot();
 }
@@ -1602,6 +1696,15 @@ async function resolvedToolIdentity(command, env = process.env) {
     return (await resolvedTool(command, env))?.cacheIdentity ?? null;
 }
 const directCompilerDriverMemos = new Map();
+const directCompilerSelections = new Map();
+function compilerDriverProbeKey(driver, environmentFingerprint) {
+    return [
+        environmentFingerprint,
+        driver.argv.join("\x1f"),
+        driver.target ?? "<native>",
+        driver.targetArgs.join("\x1f"),
+    ].join("\0");
+}
 /** `/usr/bin/clang` on Darwin is Apple's immutable driver shim: its `-###`
  * trace names the selected Xcode/CommandLineTools clang rather than the shim
  * itself. The ordinary implicit-toolchain fingerprint below captures that
@@ -1623,12 +1726,7 @@ async function compilerDriverSupportsPersistentCache(driver, environmentFingerpr
     // wrapper. This is deliberately undocumented and test-scoped.
     if (process.env["SCRIPTC_TEST_TRUST_COMPILER_WRAPPER"] === "1")
         return true;
-    const driverKey = [
-        environmentFingerprint,
-        driver.argv.join("\x1f"),
-        driver.target ?? "<native>",
-        driver.targetArgs.join("\x1f"),
-    ].join("\0");
+    const driverKey = compilerDriverProbeKey(driver, environmentFingerprint);
     const compiler = driver.argv[0] ?? "clang";
     const resolvedDriver = await resolvedTool(compiler);
     // A prior dependency list cannot prove that name resolution is unchanged:
@@ -1669,6 +1767,8 @@ async function compilerDriverSupportsPersistentCache(driver, environmentFingerpr
             direct = effectiveCompiler !== null &&
                 (effectiveCompiler.fileIdentity === resolvedDriver.fileIdentity ||
                     isAppleSystemClangHandoff(resolvedDriver, effectiveCompiler));
+            if (direct)
+                directCompilerSelections.set(driverKey, effectiveCompiler);
         }
     }
     catch {
@@ -1678,6 +1778,8 @@ async function compilerDriverSupportsPersistentCache(driver, environmentFingerpr
         await rm(probeDir, { recursive: true, force: true }).catch(() => undefined);
     }
     directCompilerDriverMemos.set(probeKey, direct);
+    if (!direct)
+        directCompilerSelections.delete(driverKey);
     return direct;
 }
 /** Complete library archives may skip `ar`, so the selected archiver must be
@@ -1758,6 +1860,29 @@ async function toolVersionOnce(argv, environmentFingerprint = toolchainEnvironme
         toolVersionFallbacks.set(spellingKey, memo);
     return memo;
 }
+/** Dependency paths discovered while computing one strict fingerprint. The
+ * output-local cache stamp snapshots these exact files/directories after a
+ * validated build, then can prove a later same-output no-op without spawning
+ * clang again. The content identity closes the gap between hashing and that
+ * metadata snapshot: a file changed in the gap cannot make new bytes ride an
+ * old key. Keep the map bounded for long-lived corpus/test processes. */
+const fingerprintDependencies = new Map();
+function rememberFingerprintDependencies(fingerprint, paths, contentPaths = [], contentFingerprint = null) {
+    fingerprintDependencies.set(fingerprint, {
+        paths: [...new Set(paths)].sort(),
+        contentPaths: [...new Set(contentPaths)].sort(),
+        contentFingerprint,
+    });
+    if (fingerprintDependencies.size > 256) {
+        const oldest = fingerprintDependencies.keys().next().value;
+        if (oldest !== undefined)
+            fingerprintDependencies.delete(oldest);
+    }
+    return fingerprint;
+}
+function fingerprintDependencyPaths(fingerprint) {
+    return fingerprintDependencies.get(fingerprint)?.paths ?? [];
+}
 function parseMakeDependencies(output, cwd = process.cwd()) {
     const flattened = output.replace(/\\\r?\n/g, " ");
     const separator = flattened.indexOf(": ");
@@ -1839,13 +1964,14 @@ async function effectiveCompilerInvocationFingerprintFresh(driver, environmentFi
                 invocation: normalizedProbeInvocation(invocation, probeDir),
                 dependencies,
                 dependencyFingerprint: await fingerprintDependencyFiles(dependencies),
+                invocationPaths: await existingDriverTracePaths(`${invocation.stdout}\n${invocation.stderr}`, probeDir, probeDir),
             };
         }
         finally {
             await rm(probeDir, { recursive: true, force: true }).catch(() => undefined);
         }
     }
-    return createHash("sha256")
+    const fingerprint = createHash("sha256")
         .update("effective-compiler-invocation-v2\0")
         .update(environmentFingerprint)
         .update("\0")
@@ -1863,6 +1989,7 @@ async function effectiveCompilerInvocationFingerprintFresh(driver, environmentFi
         .update("\0")
         .update(probe.dependencyFingerprint)
         .digest("hex");
+    return rememberFingerprintDependencies(fingerprint, [...probe.dependencies, ...probe.invocationPaths], probe.dependencies, probe.dependencyFingerprint);
 }
 const stableEffectiveCompilerInvocationMemos = new Map();
 function effectiveCompilerInvocationFingerprint(driver, environmentFingerprint, compileArgs, sourceExtension = ".c") {
@@ -1876,17 +2003,30 @@ function effectiveCompilerInvocationFingerprint(driver, environmentFingerprint,
 }
 async function nativeSourceFiles(directory, recursive, include = (name) => name.endsWith(".c") || name.endsWith(".h")) {
     const files = [];
-    const walk = async (current) => {
+    const walk = async (current, ancestors) => {
+        const canonical = await realpath(current).catch(() => resolve(current));
+        if (ancestors.has(canonical))
+            return;
+        const nestedAncestors = new Set(ancestors).add(canonical);
         const entries = await readdir(current, { withFileTypes: true }).catch(() => []);
         for (const entry of entries) {
             const path = join(current, entry.name);
-            if (entry.isDirectory() && recursive)
-                await walk(path);
-            else if (entry.isFile() && include(entry.name))
+            if (entry.isDirectory() && recursive) {
+                await walk(path, nestedAncestors);
+            }
+            else if (entry.isSymbolicLink()) {
+                const target = await stat(path).catch(() => null);
+                if (target?.isDirectory() && recursive)
+                    await walk(path, nestedAncestors);
+                else if (target?.isFile() && include(entry.name))
+                    files.push(path);
+            }
+            else if (entry.isFile() && include(entry.name)) {
                 files.push(path);
+            }
         }
     };
-    await walk(directory);
+    await walk(directory, new Set());
     return files.sort();
 }
 /** Every system-header spelling consumed by a source tree scriptc owns. The
@@ -1938,6 +2078,18 @@ async function fingerprintDependencyFiles(paths) {
     }
     return hash.digest("hex");
 }
+async function fingerprintDependenciesStillMatch(fingerprints) {
+    const distinct = [...new Set(fingerprints)];
+    const identities = distinct
+        .map((fingerprint) => fingerprintDependencies.get(fingerprint))
+        // A restored native-metadata stamp carries and revalidates the dependency
+        // snapshot from the process that minted this fingerprint. Only identities
+        // computed in this process have an additional content hash to recheck here.
+        .filter((identity) => identity !== undefined);
+    return (await Promise.all(identities.map(async (identity) => identity.contentFingerprint === null ||
+        await fingerprintDependencyFiles(identity.contentPaths).catch(() => null) ===
+            identity.contentFingerprint))).every(Boolean);
+}
 /** Exact headers selected while preprocessing the caller's translation unit.
  * The shared toolchain probe covers the runtime/vendor trees, but compileC is
  * also a public API: an opted-in caller can include a system or header-only SDK
@@ -1946,7 +2098,7 @@ async function fingerprintDependencyFiles(paths) {
  * quote-include directory and compiler-visible source spelling. */
 async function translationUnitDependencyFingerprintFresh(driver, cflags, sourcePath, sourceBytes, environmentFingerprint) {
     if (sourcePath.endsWith(".ll")) {
-        return createHash("sha256").update("translation-unit-dependencies-v1\0llvm-ir").digest("hex");
+        return rememberFingerprintDependencies(createHash("sha256").update("translation-unit-dependencies-v1\0llvm-ir").digest("hex"), []);
     }
     const compiler = driver.argv[0] ?? "clang";
     const compilerIdentity = await resolvedToolIdentity(compiler);
@@ -1983,7 +2135,7 @@ async function translationUnitDependencyFingerprintFresh(driver, cflags, sourceP
             await rm(probeDir, { recursive: true, force: true }).catch(() => undefined);
         }
     }
-    return createHash("sha256")
+    const fingerprint = createHash("sha256")
         .update("translation-unit-dependencies-v1\0")
         .update(environmentFingerprint)
         .update("\0")
@@ -1993,6 +2145,7 @@ async function translationUnitDependencyFingerprintFresh(driver, cflags, sourceP
         .update("\0")
         .update(probe.dependencyFingerprint)
         .digest("hex");
+    return rememberFingerprintDependencies(fingerprint, probe.dependencies, probe.dependencies, probe.dependencyFingerprint);
 }
 const stableTranslationUnitDependencyMemos = new Map();
 function translationUnitDependencyFingerprint(driver, cflags, sourcePath, sourceBytes, environmentFingerprint) {
@@ -2086,10 +2239,15 @@ async function implicitToolchainFingerprintFresh(driver, environmentFingerprint)
                 compilerInvocation: normalizedProbeInvocation(compilerInvocation, probeDir),
                 dependencies: dependencyPaths,
                 dependencyFingerprint: await fingerprintDependencyFiles(dependencyPaths),
-                tools: await Promise.all(toolSpellings.map(async (spelling) => ({
-                    spelling,
-                    identity: await resolvedToolIdentity(spelling),
-                }))),
+                invocationPaths: await existingDriverTracePaths(`${compilerInvocation.stdout}\n${compilerInvocation.stderr}`, probeDir, probeDir),
+                tools: await Promise.all(toolSpellings.map(async (spelling) => {
+                    const resolved = await resolvedTool(spelling);
+                    return {
+                        spelling,
+                        identity: resolved?.cacheIdentity ?? null,
+                        path: resolved?.canonicalPath ?? null,
+                    };
+                })),
             };
         }
         finally {
@@ -2120,7 +2278,11 @@ async function implicitToolchainFingerprintFresh(driver, environmentFingerprint)
             .update(currentIdentity ?? tool.identity ?? "<unresolved>")
             .update("\0");
     }
-    return hash.digest("hex");
+    return rememberFingerprintDependencies(hash.digest("hex"), [
+        ...probe.dependencies,
+        ...probe.invocationPaths,
+        ...probe.tools.flatMap((tool) => tool.path === null ? [] : [tool.path]),
+    ], probe.dependencies, probe.dependencyFingerprint);
 }
 const stableImplicitToolchainMemos = new Map();
 function implicitToolchainFingerprint(driver, environmentFingerprint) {
@@ -2156,6 +2318,51 @@ function driverTraceCandidates(line) {
     }
     return candidates;
 }
+async function existingDriverTracePaths(output, cwd, excludedRoot) {
+    const candidates = new Set();
+    for (const line of output.split(/\r?\n/)) {
+        const tokens = driverTraceCandidates(line);
+        for (let index = 0; index < tokens.length; index++) {
+            const token = tokens[index];
+            const joinedPathOption = ["-I", "-L", "-F"].find((option) => token.startsWith(option) && token.length > option.length);
+            const equalsPathOption = ["--sysroot=", "-resource-dir="].find((option) => token.startsWith(option));
+            const separatePathOptions = [
+                "-I",
+                "-L",
+                "-F",
+                "--sysroot",
+                "-isysroot",
+                "-resource-dir",
+                "-isystem",
+                "-iquote",
+                "-internal-isystem",
+                "-internal-externc-isystem",
+                "-internal-iframework",
+            ];
+            const optionPath = joinedPathOption !== undefined
+                ? token.slice(joinedPathOption.length)
+                : equalsPathOption !== undefined
+                    ? token.slice(equalsPathOption.length)
+                    : separatePathOptions.includes(token)
+                        ? tokens[index + 1] ?? ""
+                        : token;
+            if (!isAbsolute(optionPath))
+                continue;
+            const path = resolve(cwd, optionPath);
+            if (path === excludedRoot ||
+                path.startsWith(`${excludedRoot}/`) ||
+                path.startsWith(`${excludedRoot}\\`)) {
+                continue;
+            }
+            candidates.add(path);
+        }
+    }
+    const existing = await Promise.all([...candidates].map(async (path) => [path, await lstat(path).catch(() => null)]));
+    return existing
+        .filter((entry) => entry[1] !== null)
+        .map(([path]) => path)
+        .sort();
+}
 export async function parseLinkTraceFiles(output, cwd, excludedRoot, driverDryRun = false) {
     const files = new Set();
     for (const line of output.split(/\r?\n/)) {
@@ -2241,9 +2448,15 @@ async function implicitLinkerFingerprintFresh(driver, environmentFingerprint, li
                 linkerInvocation: normalizedProbeInvocation(driverInvocation, probeDir),
                 dependencies,
                 dependencyFingerprint: await fingerprintDependencyFiles(dependencies),
+                invocationPaths: await existingDriverTracePaths(`${driverInvocation.stdout}\n${driverInvocation.stderr}`, probeDir, probeDir),
                 linker: {
                     spelling: linkerSpelling,
-                    identity: linkerSpelling === "" ? null : await resolvedToolIdentity(linkerSpelling),
+                    identity: linkerSpelling === ""
+                        ? null
+                        : (await resolvedTool(linkerSpelling))?.cacheIdentity ?? null,
+                    path: linkerSpelling === ""
+                        ? null
+                        : (await resolvedTool(linkerSpelling))?.canonicalPath ?? null,
                 },
             };
         }
@@ -2254,7 +2467,7 @@ async function implicitLinkerFingerprintFresh(driver, environmentFingerprint, li
     const linkerIdentity = probe.linker.spelling === ""
         ? null
         : await resolvedToolIdentity(probe.linker.spelling);
-    return createHash("sha256")
+    const fingerprint = createHash("sha256")
         .update("implicit-linker-v3\0")
         .update(environmentFingerprint)
         .update("\0")
@@ -2280,6 +2493,11 @@ async function implicitLinkerFingerprintFresh(driver, environmentFingerprint, li
         .update("\0")
         .update(linkerIdentity ?? probe.linker.identity ?? "<unresolved>")
         .digest("hex");
+    return rememberFingerprintDependencies(fingerprint, [
+        ...probe.dependencies,
+        ...probe.invocationPaths,
+        ...(probe.linker.path === null ? [] : [probe.linker.path]),
+    ], probe.dependencies, probe.dependencyFingerprint);
 }
 const stableImplicitLinkerMemos = new Map();
 function implicitLinkerFingerprint(driver, environmentFingerprint, linkArgs, effectiveInvocationArgs, traceInvocationArgs) {
@@ -2301,21 +2519,18 @@ function ccacheAvailable() {
     ccacheMemo ??= execFileAsync("ccache", ["--version"]).then(() => true, () => false);
     return ccacheMemo;
 }
-/** Content hash of every .c/.h in the runtime src dir, the Ryū sources
+/** 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: a stat-only memo can miss a
- * same-size edit whose timestamp was preserved by a copy/sync tool. */
+ * 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. */
 async function runtimeFingerprintFresh(rtDir) {
-    const groups = await Promise.all([
-        { label: "runtime", dir: rtDir },
-        { label: "ryu", dir: join(rtDir, "..", "vendor", "ryu") },
-    ].map(async (group) => {
-        const names = (await readdir(group.dir)).filter((n) => n.endsWith(".c") || n.endsWith(".h")).sort();
-        return { ...group, names };
-    }));
+    const groups = await runtimeFingerprintInputGroups(rtDir);
     const h = createHash("sha256").update(QJS_COMMIT).update(MBEDTLS_VERSION).update(ZLIB_VERSION);
     for (const group of groups) {
         for (const n of group.names) {
@@ -2324,6 +2539,20 @@ async function runtimeFingerprintFresh(rtDir) {
     }
     return h.digest("hex");
 }
+async function runtimeFingerprintInputGroups(rtDir) {
+    return Promise.all([
+        { label: "runtime", dir: rtDir },
+        { label: "ryu", dir: join(rtDir, "..", "vendor", "ryu") },
+    ].map(async (group) => {
+        const names = (await nativeSourceFiles(group.dir, true))
+            .map((path) => relative(group.dir, path))
+            .sort();
+        return { ...group, names };
+    }));
+}
+async function runtimeFingerprintInputPaths(rtDir) {
+    return (await runtimeFingerprintInputGroups(rtDir)).flatMap((group) => group.names.map((name) => join(group.dir, name)));
+}
 const stableRuntimeFingerprintMemos = new Map();
 export function runtimeFingerprint(rtDir) {
     const key = resolve(rtDir);
@@ -2412,6 +2641,279 @@ async function publishCachedFile(source, destination) {
         ]);
     }
 }
+async function directoryTreeDigest(root, excludedPaths = []) {
+    const hash = createHash("sha256").update("native-dependency-tree-v1\0");
+    const visited = new Set();
+    const excluded = excludedPaths.map((path) => resolve(path));
+    const walk = async (directory, relative) => {
+        const canonical = await realpath(directory);
+        if (visited.has(canonical)) {
+            hash.update(relative).update("\0cycle\0").update(canonical).update("\0");
+            return;
+        }
+        visited.add(canonical);
+        const entries = await readdir(directory, { withFileTypes: true });
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of entries) {
+            const path = join(directory, entry.name);
+            const absolute = resolve(path);
+            if (excluded.some((candidate) => absolute === candidate ||
+                absolute.startsWith(`${candidate}/`) ||
+                absolute.startsWith(`${candidate}\\`)))
+                continue;
+            const child = relative === "" ? entry.name : `${relative}/${entry.name}`;
+            const info = await lstat(path);
+            const kind = info.isDirectory()
+                ? "directory"
+                : info.isFile()
+                    ? "file"
+                    : info.isSymbolicLink()
+                        ? "symlink"
+                        : "other";
+            hash.update(child).update("\0").update(kind).update("\0");
+            if (kind === "symlink") {
+                const target = await realpath(path).catch(() => "<missing>");
+                hash.update(target).update("\0");
+                const targetInfo = await stat(path).catch(() => null);
+                if (targetInfo?.isDirectory())
+                    await walk(path, child);
+            }
+            if (kind === "directory")
+                await walk(path, child);
+        }
+        visited.delete(canonical);
+    };
+    await walk(root, "");
+    return hash.digest("hex");
+}
+function localDependencyKind(info) {
+    return info.isFile()
+        ? "file"
+        : info.isDirectory()
+            ? "directory"
+            : info.isSymbolicLink()
+                ? "symlink"
+                : null;
+}
+async function snapshotLocalArtifactDependency(path, treeExclusions = null) {
+    const info = await lstat(path);
+    const kind = localDependencyKind(info);
+    if (kind === null)
+        throw new Error(`unsupported local artifact dependency: ${path}`);
+    const dependency = {
+        path,
+        kind,
+        dev: info.dev,
+        ino: info.ino,
+        size: info.size,
+        mtimeMs: info.mtimeMs,
+        ctimeMs: info.ctimeMs,
+    };
+    if (kind === "directory" && treeExclusions !== null) {
+        dependency.treeExclusions = [...new Set(treeExclusions.map((entry) => resolve(entry)))].sort();
+        dependency.treeDigest = await directoryTreeDigest(path, dependency.treeExclusions);
+    }
+    if (kind === "symlink") {
+        const targetPath = await realpath(path);
+        const target = await stat(path);
+        const targetKind = target.isFile() ? "file" : target.isDirectory() ? "directory" : null;
+        if (targetKind === null)
+            throw new Error(`unsupported symlink target dependency: ${path}`);
+        dependency.targetPath = targetPath;
+        dependency.targetKind = targetKind;
+        dependency.targetDev = target.dev;
+        dependency.targetIno = target.ino;
+        dependency.targetSize = target.size;
+        dependency.targetMtimeMs = target.mtimeMs;
+        dependency.targetCtimeMs = target.ctimeMs;
+        if (targetKind === "directory" && treeExclusions !== null) {
+            dependency.treeExclusions = [...new Set(treeExclusions.map((entry) => resolve(entry)))].sort();
+            dependency.treeDigest = await directoryTreeDigest(path, dependency.treeExclusions);
+        }
+    }
+    return dependency;
+}
+async function snapshotLocalArtifactDependencies(dependencyPaths, recursiveDirectories = [], recursiveExclusions = []) {
+    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) {
+    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);
+    }))).every(Boolean);
+}
+function nativeMetadataStampPath(root, key) {
+    return join(root, "meta", createHash("sha256").update(key).digest("hex"));
+}
+function nativeMetadataStampIntegrity(stamp) {
+    return createHash("sha256")
+        .update("native-metadata-stamp-v2\0")
+        .update(JSON.stringify(stamp))
+        .digest("hex");
+}
+async function readNativeMetadataStamp(root, key) {
+    try {
+        const stamp = JSON.parse(await readFile(nativeMetadataStampPath(root, key), "utf8"));
+        if (stamp.version !== 2 ||
+            stamp.key !== key ||
+            stamp.values === null ||
+            typeof stamp.values !== "object" ||
+            !Array.isArray(stamp.dependencies) ||
+            !/^[0-9a-f]{64}$/.test(stamp.integrity) ||
+            nativeMetadataStampIntegrity({
+                version: stamp.version,
+                key: stamp.key,
+                values: stamp.values,
+                dependencies: stamp.dependencies,
+            }) !== stamp.integrity ||
+            !(await localArtifactDependenciesStillMatch(stamp.dependencies))) {
+            return null;
+        }
+        return stamp;
+    }
+    catch {
+        return null;
+    }
+}
+async function publishNativeMetadataStamp(root, key, values, dependencyPaths, fingerprints = []) {
+    const destination = nativeMetadataStampPath(root, key);
+    await mkdir(dirname(destination), { recursive: true });
+    const dependencies = await snapshotLocalArtifactDependencies(dependencyPaths);
+    if (!(await fingerprintDependenciesStillMatch(fingerprints))) {
+        throw new CacheInputsChangedError();
+    }
+    const unsigned = { version: 2, key, values, dependencies };
+    const stamp = {
+        ...unsigned,
+        integrity: nativeMetadataStampIntegrity(unsigned),
+    };
+    const tmp = `${destination}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+    try {
+        await writeFile(tmp, `${JSON.stringify(stamp)}\n`, { mode: 0o600 });
+        await rename(tmp, destination);
+    }
+    finally {
+        await rm(tmp, { force: true }).catch(() => undefined);
+    }
+    return stamp;
+}
+function nativeMetadataKey(kind, parts) {
+    const hash = createHash("sha256").update(`native-metadata-${kind}-v2\0`);
+    for (const part of parts) {
+        hash.update(typeof part === "string" ? part : part.join("\x1f")).update("\0");
+    }
+    return `${kind}-${hash.digest("hex")}`;
+}
+/** The caller-visible output is itself the cheapest safe cache tier. Once a
+ * generated TU has produced this exact binary, an unchanged rebuild need not
+ * rediscover every SDK header and linker input merely to copy equivalent bytes
+ * back onto the same path. This tier is deliberately narrower than the CAS:
+ * only frontend-generated programs with no caller-owned native inputs opt in.
+ * 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) {
+    const normalizedOptions = Object.fromEntries(Object.entries(opts)
+        .filter(([, value]) => value !== undefined)
+        .sort(([a], [b]) => a.localeCompare(b)));
+    return createHash("sha256")
+        .update("local-artifact-v1\0")
+        .update(cacheTargetIdentity(driver)).update("\0")
+        .update(environmentFingerprint).update("\0")
+        .update(compilerIdentity).update("\0")
+        .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(process.env["SCRIPTC_FETCH_CURL"] === "1" ? "fetch-curl" : "fetch-native").update("\0")
+        .update(JSON.stringify(normalizedOptions)).update("\0")
+        .update(resolve(opts.cPath)).update("\0")
+        .update(resolve(opts.outPath)).update("\0")
+        .update(programBytes)
+        .digest("hex");
+}
+function localArtifactStampPath(root, outPath) {
+    const outputKey = createHash("sha256").update(resolve(outPath)).digest("hex");
+    return join(root, "local", outputKey);
+}
+function localArtifactStampIntegrity(stamp) {
+    return createHash("sha256")
+        .update("local-artifact-stamp-v2\0")
+        .update(JSON.stringify(stamp))
+        .digest("hex");
+}
+async function localArtifactHit(stampPath, outPath, key) {
+    try {
+        const stamp = JSON.parse(await readFile(stampPath, "utf8"));
+        const output = await lstat(outPath);
+        const expectedMode = 0o777 & ~process.umask();
+        if (stamp.version !== 2 ||
+            stamp.key !== key ||
+            !/^[0-9a-f]{64}$/.test(stamp.digest ?? "") ||
+            !Array.isArray(stamp.dependencies) ||
+            !/^[0-9a-f]{64}$/.test(stamp.integrity ?? "") ||
+            localArtifactStampIntegrity({
+                version: stamp.version,
+                key: stamp.key,
+                digest: stamp.digest,
+                dependencies: stamp.dependencies,
+            }) !== stamp.integrity ||
+            !output.isFile() ||
+            (output.mode & 0o777) !== expectedMode ||
+            stamp.dependencies.some((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.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")) ||
+            !(await localArtifactDependenciesStillMatch(stamp.dependencies)) ||
+            await fileDigest(outPath) !== stamp.digest) {
+            return false;
+        }
+        const now = new Date();
+        await utimes(stampPath, now, now).catch(() => undefined);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function publishLocalArtifactStamp(stampPath, outPath, key, dependencyPaths, recursiveDirectories = [], recursiveExclusions = []) {
+    await mkdir(dirname(stampPath), { recursive: true });
+    const tmp = `${stampPath}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+    try {
+        const dependencies = await snapshotLocalArtifactDependencies(dependencyPaths, recursiveDirectories, recursiveExclusions);
+        const unsigned = {
+            version: 2,
+            key,
+            digest: await fileDigest(outPath),
+            dependencies,
+        };
+        const stamp = {
+            ...unsigned,
+            integrity: localArtifactStampIntegrity(unsigned),
+        };
+        await writeFile(tmp, `${JSON.stringify(stamp)}\n`, { mode: 0o600 });
+        await rename(tmp, stampPath);
+    }
+    finally {
+        await rm(tmp, { force: true }).catch(() => undefined);
+    }
+}
 /** The cached .o set for one flag flavor, compiled on first need. Concurrent
  * first builds (parallel test workers on a cold cache) may duplicate work;
  * per-file atomic renames make every winner equivalent. Publication is held
@@ -2445,7 +2947,22 @@ async function ensureRuntimeObjects(root, ccArgv, cflags, sources, keyPrefix, ve
                 await Promise.all(missing.slice(i, i + width).map(async (src) => {
                     const tmpObj = join(tmpDir, `${basename(src, ".c")}.o`);
                     const argv = [...(useCcache ? ["ccache"] : []), ...ccArgv, ...cflags, "-c", src, "-o", tmpObj];
-                    await execFileAsync(argv[0] ?? "clang", argv.slice(1));
+                    await execFileAsync(argv[0] ?? "clang", argv.slice(1), useCcache
+                        ? {
+                            // ccache direct mode remembers only the headers selected by
+                            // its previous manifest and can miss a newly created,
+                            // higher-priority header. The scriptc object-set key already
+                            // includes the recursive runtime namespace fingerprint, so
+                            // carry it into ccache's own keyspace as well.
+                            env: {
+                                ...process.env,
+                                CCACHE_NAMESPACE: [
+                                    process.env["CCACHE_NAMESPACE"],
+                                    `scriptc-${setKey}`,
+                                ].filter((value) => value !== undefined && value !== "").join(":"),
+                            },
+                        }
+                        : undefined);
                     compiled.set(src, { object: tmpObj, digest: await fileDigest(tmpObj) });
                 }));
             }
@@ -2657,10 +3174,88 @@ export async function compileC(opts) {
             root = null;
         }
     }
+    let localArtifact = null;
+    // Generated executable TUs are closed over scriptc's own runtime tree. A
+    // same-output rebuild can therefore check those bytes directly before the
+    // 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 &&
+        cachePolicy.completeArtifacts &&
+        opts.cacheIdentity === "scriptc-generated-v1" &&
+        (opts.linkInputs?.length ?? 0) === 0 &&
+        (opts.systemLibraries?.length ?? 0) === 0 &&
+        process.env["SCRIPTC_TEST_TRUST_COMPILER_WRAPPER"] !== "1") {
+        try {
+            const [compiler, runtimeHash, programBytes] = await Promise.all([
+                resolvedTool(driver.argv[0] ?? "clang"),
+                runtimeFingerprint(rtDir),
+                readFile(opts.cPath),
+            ]);
+            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 stampPath = localArtifactStampPath(root, opts.outPath);
+                localArtifact = {
+                    stampPath,
+                    key,
+                    runtimeHash,
+                    programBytes,
+                    compilerPath: effectiveCompiler.canonicalPath,
+                };
+                if (await localArtifactHit(stampPath, opts.outPath, key))
+                    return;
+            }
+        }
+        catch {
+            // The output-local tier is only an optimization; the fully validated
+            // CAS below remains the source of truth on any metadata trouble.
+            localArtifact = null;
+        }
+    }
     let implicitToolchain = null;
+    let toolchainMetadataStamp = null;
+    const metadataCompiler = root === null
+        ? null
+        : await resolvedTool(driver.argv[0] ?? "clang");
+    const metadataEffectiveCompiler = directCompilerSelections.get(compilerDriverProbeKey(driver, toolchainEnv)) ?? metadataCompiler;
+    const toolchainMetadataKey = root === null ||
+        metadataCompiler === null ||
+        metadataEffectiveCompiler === null ||
+        process.env["SCRIPTC_TEST_TRUST_COMPILER_WRAPPER"] === "1"
+        ? null
+        : nativeMetadataKey("toolchain", [
+            cacheTargetIdentity(driver),
+            toolchainEnv,
+            driver.argv,
+            driver.targetArgs,
+            metadataCompiler.cacheIdentity,
+            metadataEffectiveCompiler.cacheIdentity,
+            rtDir,
+        ]);
     if (persistentDriverCache) {
         try {
-            implicitToolchain = await implicitToolchainFingerprint(driver, toolchainEnv);
+            toolchainMetadataStamp =
+                root === null || toolchainMetadataKey === null
+                    ? null
+                    : await readNativeMetadataStamp(root, toolchainMetadataKey);
+            implicitToolchain = toolchainMetadataStamp?.values["implicitToolchain"] ??
+                await implicitToolchainFingerprint(driver, toolchainEnv);
+            let compilerVersion = toolchainMetadataStamp?.values["compilerVersion"];
+            if (compilerVersion === undefined) {
+                compilerVersion = await ccVersionOnce(driver.argv, toolchainEnv, true);
+            }
+            if (toolchainMetadataStamp === null &&
+                root !== null &&
+                toolchainMetadataKey !== null) {
+                if (metadataCompiler !== null && metadataEffectiveCompiler !== null) {
+                    toolchainMetadataStamp = await publishNativeMetadataStamp(root, toolchainMetadataKey, { implicitToolchain, compilerVersion }, [
+                        metadataCompiler.canonicalPath,
+                        metadataEffectiveCompiler.canonicalPath,
+                        ...fingerprintDependencyPaths(implicitToolchain),
+                    ], [implicitToolchain]);
+                }
+            }
         }
         catch {
             // Cache discovery is best-effort. In particular, a compiler wrapper can
@@ -2817,6 +3412,7 @@ export async function compileC(opts) {
         ...(opts.http2 ?? false ? [rt(join(rtDir, "scr_http2.c"))] : []),
         ...(opts.dgram ? [rt(join(rtDir, "scr_dgram.c"))] : []),
         ...(opts.watch ? [rt(join(rtDir, "scr_watch.c"))] : []),
+        ...(opts.foreignFfi ? [rt(join(rtDir, "scr_ffi_queue.c"))] : []),
         ...(opts.nodeTest ? [rt(join(rtDir, "scr_test.c"))] : []),
         // The CA-store unit rides its own gate OR the tls one: scr_tls.c
         // references its default-set override unconditionally.
@@ -2959,12 +3555,63 @@ export async function compileC(opts) {
     };
     let runtimeCompilerInvocation = null;
     let programCompilerInvocation = null;
+    let payloadMetadata = null;
+    let compileMetadataStamp = null;
+    const compileMetadataKey = root === null || process.env["SCRIPTC_TEST_TRUST_COMPILER_WRAPPER"] === "1"
+        ? null
+        : nativeMetadataKey("compile", [
+            cacheTargetIdentity(driver),
+            toolchainEnv,
+            implicitToolchain ?? "<uncached>",
+            driver.argv,
+            cflags,
+            programCompilerArgs,
+            programSourceExtension,
+        ]);
     if (root !== null) {
         try {
-            runtimeCompilerInvocation = await effectiveCompilerInvocationFingerprint(driver, toolchainEnv, cflags);
-            programCompilerInvocation = programSourceExtension === ".ll"
-                ? await effectiveCompilerInvocationFingerprint(driver, toolchainEnv, programCompilerArgs, programSourceExtension)
-                : runtimeCompilerInvocation;
+            // These probes inspect disjoint inputs. Start the payload reads here as
+            // well so runtime hashing and clang's dry-run traces overlap instead of
+            // forming a serial prelude before every cache lookup.
+            payloadMetadata = Promise.all([
+                Promise.resolve(toolchainMetadataStamp?.values["compilerVersion"] ??
+                    ccVersionOnce(driver.argv, toolchainEnv, true)),
+                localArtifact === null
+                    ? runtimeFingerprint(rtDir)
+                    : Promise.resolve(localArtifact.runtimeHash),
+                localArtifact === null
+                    ? readFile(opts.cPath)
+                    : Promise.resolve(localArtifact.programBytes),
+            ]);
+            compileMetadataStamp = compileMetadataKey === null
+                ? null
+                : await readNativeMetadataStamp(root, compileMetadataKey);
+            if (compileMetadataStamp !== null) {
+                runtimeCompilerInvocation = compileMetadataStamp.values["runtimeInvocation"] ?? null;
+                programCompilerInvocation = compileMetadataStamp.values["programInvocation"] ?? null;
+                if (runtimeCompilerInvocation === null || programCompilerInvocation === null) {
+                    compileMetadataStamp = null;
+                }
+            }
+            if (compileMetadataStamp === null) {
+                const [runtimeInvocation, programInvocation] = await Promise.all([
+                    effectiveCompilerInvocationFingerprint(driver, toolchainEnv, cflags),
+                    programSourceExtension === ".ll"
+                        ? effectiveCompilerInvocationFingerprint(driver, toolchainEnv, programCompilerArgs, programSourceExtension)
+                        : Promise.resolve(null),
+                ]);
+                runtimeCompilerInvocation = runtimeInvocation;
+                programCompilerInvocation = programInvocation ?? runtimeInvocation;
+                if (compileMetadataKey !== null) {
+                    compileMetadataStamp = await publishNativeMetadataStamp(root, compileMetadataKey, {
+                        runtimeInvocation: runtimeCompilerInvocation,
+                        programInvocation: programCompilerInvocation,
+                    }, [
+                        ...fingerprintDependencyPaths(runtimeCompilerInvocation),
+                        ...fingerprintDependencyPaths(programCompilerInvocation),
+                    ], [runtimeCompilerInvocation, programCompilerInvocation]);
+                }
+            }
         }
         catch {
             // Preserve the uncached build for wrappers that compile successfully but
@@ -2989,11 +3636,11 @@ export async function compileC(opts) {
     let fingerprint;
     let cBytes;
     try {
-        [cv, fingerprint, cBytes] = await Promise.all([
+        [cv, fingerprint, cBytes] = await (payloadMetadata ?? Promise.all([
             ccVersionOnce(driver.argv, toolchainEnv, true),
             runtimeFingerprint(rtDir),
             readFile(opts.cPath),
-        ]);
+        ]));
     }
     catch {
         // A version/fingerprint probe is an optimization boundary. If the compiler
@@ -3012,16 +3659,6 @@ export async function compileC(opts) {
         (opts.linkInputs?.length ?? 0) === 0 &&
         (opts.systemLibraries?.length ?? 0) === 0;
     let programDependencies = null;
-    if (cacheCompleteArtifact) {
-        try {
-            programDependencies = await translationUnitDependencyFingerprint(driver, cflags, opts.cPath, cBytes, toolchainEnv);
-        }
-        catch {
-            // Program-header discovery is needed only for a complete hit. Runtime
-            // objects remain safe because they never contain the caller's TU.
-            cacheCompleteArtifact = false;
-        }
-    }
     const linkProbeArgs = [
         ...(sanitize ? ["-fsanitize=address"] : []),
         ...threadArgs,
@@ -3062,15 +3699,89 @@ export async function compileC(opts) {
         ? effectiveLinkInvocationArgs
         : effectiveLinkInvocationArgs.filter((arg) => arg !== `-L${curlStubDir}`);
     let implicitLinker = null;
+    let preBuildDependencies = null;
+    let localArtifactDependencyPaths = null;
+    let linkMetadataStamp = null;
+    const linkMetadataKey = root === null || process.env["SCRIPTC_TEST_TRUST_COMPILER_WRAPPER"] === "1"
+        ? null
+        : nativeMetadataKey("link", [
+            cacheTargetIdentity(driver),
+            toolchainEnv,
+            implicitToolchain ?? "<uncached>",
+            runtimeCompilerInvocation ?? "<uncached>",
+            programCompilerInvocation ?? "<uncached>",
+            driver.argv,
+            linkProbeArgs,
+            effectiveLinkInvocationArgs,
+            linkTraceInvocationArgs,
+        ]);
     if (cacheCompleteArtifact) {
         try {
-            implicitLinker = await implicitLinkerFingerprint(driver, toolchainEnv, linkProbeArgs, effectiveLinkInvocationArgs, linkTraceInvocationArgs);
+            // Header discovery and linker tracing are independent subprocess trees.
+            // Running them together removes one complete probe round-trip from both
+            // cache hits and ordinary edit/build misses without changing either key.
+            linkMetadataStamp = linkMetadataKey === null
+                ? null
+                : await readNativeMetadataStamp(root, linkMetadataKey);
+            if (linkMetadataStamp !== null) {
+                implicitLinker = linkMetadataStamp.values["implicitLinker"] ?? null;
+                if (implicitLinker === null)
+                    linkMetadataStamp = null;
+            }
+            [programDependencies, implicitLinker] = await Promise.all([
+                translationUnitDependencyFingerprint(driver, cflags, opts.cPath, cBytes, toolchainEnv),
+                linkMetadataStamp === null
+                    ? implicitLinkerFingerprint(driver, toolchainEnv, linkProbeArgs, effectiveLinkInvocationArgs, linkTraceInvocationArgs)
+                    : Promise.resolve(implicitLinker),
+            ]);
+            if (linkMetadataStamp === null && linkMetadataKey !== null) {
+                linkMetadataStamp = await publishNativeMetadataStamp(root, linkMetadataKey, { implicitLinker }, fingerprintDependencyPaths(implicitLinker), [implicitLinker]);
+            }
+            preBuildDependencies = await snapshotLocalArtifactDependencies([
+                ...(await runtimeFingerprintInputPaths(rtDir)),
+                ...(toolchainMetadataStamp?.dependencies.map((dependency) => dependency.path) ??
+                    fingerprintDependencyPaths(implicitToolchain)),
+                ...(compileMetadataStamp?.dependencies.map((dependency) => dependency.path) ?? []),
+                ...(linkMetadataStamp?.dependencies.map((dependency) => dependency.path) ??
+                    fingerprintDependencyPaths(implicitLinker)),
+                ...fingerprintDependencyPaths(programDependencies),
+            ]);
+            // Every content-bearing fingerprint was computed before this metadata
+            // snapshot. Re-read those exact files now so the snapshot cannot certify
+            // bytes that changed after hashing but before the final compile starts.
+            if (!(await fingerprintDependenciesStillMatch([
+                implicitToolchain,
+                runtimeCompilerInvocation,
+                programCompilerInvocation,
+                implicitLinker,
+                programDependencies,
+            ])) ||
+                await runtimeFingerprint(rtDir).catch(() => null) !== fingerprint ||
+                !(await Promise.all([toolchainMetadataStamp, compileMetadataStamp, linkMetadataStamp]
+                    .filter((stamp) => stamp !== null)
+                    .map((stamp) => localArtifactDependenciesStillMatch(stamp.dependencies)))).every(Boolean)) {
+                throw new CacheInputsChangedError();
+            }
+            if (localArtifact !== null) {
+                // Native metadata stamps persist their dependency paths across CLI
+                // processes; fingerprintDependencyPaths deliberately does not. Build
+                // the output-local stamp from this complete validated snapshot so a
+                // source edit in a fresh process cannot replace it with only the two
+                // process-local fallback paths.
+                localArtifactDependencyPaths = [
+                    localArtifact.compilerPath,
+                    dirname(resolve(opts.cPath)),
+                    ...preBuildDependencies.map((dependency) => dependency.path),
+                ];
+            }
         }
         catch {
-            // Some compiler wrappers/linkers do not implement trace mode. Runtime
-            // objects remain safely cacheable, but a complete executable cannot be
-            // keyed without knowing every implicit link input.
+            // Program-header discovery and linker tracing are both required for a
+            // complete hit. Runtime objects remain safely cacheable if either probe
+            // is unavailable.
             cacheCompleteArtifact = false;
+            preBuildDependencies = null;
+            localArtifactDependencyPaths = null;
         }
     }
     const binDir = join(root, "bin");
@@ -3123,6 +3834,9 @@ export async function compileC(opts) {
             // cache entry populated by a less restrictive shell must not widen access.
             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);
+            }
             return; // hit: the program/runtime payload compile and link were skipped
         }
         catch {
@@ -3158,18 +3872,25 @@ export async function compileC(opts) {
         await writeFile(programPath, cBytes);
         let objects = null;
         let cacheInputsStable = true;
-        let objectImplicitVerification = null;
+        let strictObjectVerification = null;
         const objectImplicitToolchainStillMatches = () => {
-            objectImplicitVerification ??= Promise.all([
+            if (preBuildDependencies !== null) {
+                return localArtifactDependenciesStillMatch(preBuildDependencies);
+            }
+            // Complete-artifact caching can be disabled by caller-owned native
+            // inputs while the safe runtime-object tier remains active. Preserve its
+            // strict discovery fallback in that posture.
+            strictObjectVerification ??= Promise.all([
+                runtimeFingerprint(rtDir),
                 implicitToolchainFingerprint(driver, toolchainEnv),
                 effectiveCompilerInvocationFingerprint(driver, toolchainEnv, cflags),
-            ]).then(([currentImplicit, currentInvocation]) => currentImplicit === implicitToolchain &&
+            ]).then(([currentRuntime, currentImplicit, currentInvocation]) => currentRuntime === fingerprint &&
+                currentImplicit === implicitToolchain &&
                 currentInvocation === runtimeCompilerInvocation, () => false);
-            return objectImplicitVerification;
+            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 runtimeFingerprint(rtDir)) === fingerprint &&
-                (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());
             objects = await stageRuntimeObjects(cached, join(buildDir, "runtime-objects"));
         }
         catch (err) {
@@ -3180,10 +3901,11 @@ export async function compileC(opts) {
         await runClang(buildArgs((p) => objects?.get(p) ?? p, { programPath, outPath: privateOut, compilerVisibleSource: opts.cPath }));
         await installArtifact(privateOut, opts.outPath);
         if (cachedBin !== null && keyHex !== null) {
-            // This check is deliberately fresh rather than the object-publication
-            // verification above. The final program compile/link can itself race an
-            // SDK header, compiler, linker, CRT, or system-library replacement; its
-            // bytes must not be published under the pre-build identity in that case.
+            // Metadata comparison catches ordinary changes cheaply, but cannot by
+            // itself prove the snapshot was taken from the same bytes hashed into
+            // 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([
                 runtimeFingerprint(rtDir).catch(() => null),
                 implicitToolchainFingerprint(driver, toolchainEnv).catch(() => null),
@@ -3195,6 +3917,8 @@ export async function compileC(opts) {
             ]);
             cacheInputsStable =
                 cacheInputsStable &&
+                    preBuildDependencies !== null &&
+                    await localArtifactDependenciesStillMatch(preBuildDependencies) &&
                     currentRuntime === fingerprint &&
                     currentImplicit === implicitToolchain &&
                     currentRuntimeInvocation === runtimeCompilerInvocation &&
@@ -3214,6 +3938,12 @@ export async function compileC(opts) {
                 /* publishing is best-effort */
             }
         }
+        if (localArtifact !== null &&
+            localArtifactDependencyPaths !== null &&
+            cacheCompleteArtifact &&
+            cacheInputsStable) {
+            await publishLocalArtifactStamp(localArtifact.stampPath, opts.outPath, localArtifact.key, localArtifactDependencyPaths, [dirname(resolve(opts.cPath))], [root]).catch(() => undefined);
+        }
     }
     finally {
         await rm(buildDir, { recursive: true, force: true }).catch(() => undefined);