@scriptc/compiler 0.0.32 → 0.0.33

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",
@@ -1602,6 +1605,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 +1635,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 +1676,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 +1687,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 +1769,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 +1873,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 +1898,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 +1912,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 +1987,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 +2007,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 +2044,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 +2054,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 +2148,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 +2187,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 +2227,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 +2357,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 +2376,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 +2402,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 +2428,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 +2448,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 +2550,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 +2856,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 +3083,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 +3321,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 +3464,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 +3545,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 +3568,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 +3608,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 +3743,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 +3781,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 +3810,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 +3826,8 @@ export async function compileC(opts) {
             ]);
             cacheInputsStable =
                 cacheInputsStable &&
+                    preBuildDependencies !== null &&
+                    await localArtifactDependenciesStillMatch(preBuildDependencies) &&
                     currentRuntime === fingerprint &&
                     currentImplicit === implicitToolchain &&
                     currentRuntimeInvocation === runtimeCompilerInvocation &&
@@ -3214,6 +3847,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);