@scriptc/compiler 0.0.33 → 0.0.35

package/dist/index.js

@@ -1,14 +1,16 @@
-import { mkdir, rm, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
-import { CcCompileError, compileC, compileLibArchive, mobileLibraryTarget, mobileTargetRefusal, resolveCc, targetPlatform } from "./backend/cc.js";
+import { buildCacheRoot, CcCompileError, compileC, compileLibArchive, executableNativeEnvironmentFingerprint, mobileLibraryTarget, mobileTargetRefusal, prepareBuildCacheRoot, pruneBuildCache, resolveCc, targetPlatform } from "./backend/cc.js";
 import { emitModule } from "./backend/emission/emitter.js";
 import { emitLlvmModule, LlvmUnsupportedError } from "./backend/llvm/emitter.js";
+import { splitLlvmLibraryProgram, splitLlvmProgram } from "./backend/llvm/split.js";
+import { rebaseLibrarySourceComments, replaceLibraryIdentity, stripLibraryIdentity, stripLibrarySourceComments } from "./backend/library-identity.js";
 import { checkerPanicDiag, ffiNativeBuildDiag, libAsyncExportDiag, libAsyncSurfaceDiag, libExportUnresolvedDiag, libGenericExportDiag, libIntBoundaryDiag, libNpmIneligibleDiag, libSidecarDiag, libUnmappableSignatureDiag, iceDiag, isCheckerPanic, LIB_INBOUND_BYTES_TRAP_CODE, LIB_RUNTIME_TRAP_CODES } from "./diagnostics/diagnostic.js";
 import { checkLibraryIntegerSlots, classSeed, hasIntSlots, numberCarrierKind } from "./library/int-infer.js";
 import { loadLibraryProfile, profileRemediation, profileTeaching } from "./library/profile.js";
 import { decorateLibraryRefusals, evaluateLibraryFences } from "./library/fence-eval.js";
 import { assembleTrapTeaching } from "./library/trap-teaching.js";
-import { buildSidecar, canonicalModuleGraph, canonicalPath, compilerReleaseVersion, libraryIdentityHashes, } from "./library/sidecar.js";
+import { buildSidecar, canonicalModuleGraph, canonicalPath, compilerReleaseVersion, libraryIdentityHashes, updateSidecarIdentity, } from "./library/sidecar.js";
 import { validateSidecar } from "./library/sidecar-validate.js";
 import { entryFunctionExports } from "./frontend/lib-exports.js";
 import { entryContractFacts } from "./frontend/lib-contract.js";
@@ -18,13 +20,18 @@ import { validateModule } from "./ir/validate.js";
 import { canonicalBuiltinModule, checkPreflight, isNodeTypesPath, loadProgram, locOf, requiresOf, resolveNpmImport } from "./frontend/program.js";
 import { npmStaticIneligibleReason, npmStaticOffenders, npmStaticPackageOfPath } from "./frontend/npm-static.js";
 import { provenanceSources } from "./frontend/provenance-registry.js";
-import { resolveBareModule } from "./frontend/resolve.js";
+import { clearResolveCaches, resolveBareModule } from "./frontend/resolve.js";
 import { isJsSourceFileName, isRelativeSpecifier } from "./frontend/shared.js";
 import { lowerToIr } from "./frontend/lowering/lowerer.js";
 import { loadFfiProfile } from "./ffi/profile.js";
 import { hasForeignFfiCallback } from "./backend/ffi-callbacks.js";
+import { FrontendInputTracker, trackedReadFile } from "./frontend/input-tracker.js";
+import { libraryFrontendImplementationFingerprint, publishEarlyLibraryCache, readEarlyLibraryCache, readSemanticLibraryCache } from "./library/early-cache.js";
+import { createSourceLineRebaser } from "./library/semantic-source.js";
+import { publishEarlyExecutableCache, publishEarlyExecutableRoute, readEarlyExecutableCache } from "./executable/early-cache.js";
+import { compilerImplementationIdentity } from "./library/implementation-identity.js";
 export const VERSION = "0.0.1";
-export { compileC, runtimeSrcDir } from "./backend/cc.js";
+export { compileC, runtimeSrcDir, warmNativeCaches, } from "./backend/cc.js";
 export { ANDROID_MIN_API, IPHONEOS_MIN_VERSION, isAndroidTarget, isIosTarget, isMobileTarget, mobileLibraryTarget, mobileTargetRefusal } from "./backend/cc.js";
 export { emitModule } from "./backend/emission/emitter.js";
 export { renderAll, renderDiagnostic } from "./diagnostics/render.js";
@@ -317,6 +324,11 @@ function packageNameOfBareSpecifier(specifier) {
  * static-or-refuse teaching, and the detection closes over the opted-in
  * packages' own bare edges (no island exists to serve a dep from). */
 function runFrontend(entryPath, npmStatic, externalTypes) {
+    // Resolver package/workspace metadata is intentionally shared across the
+    // several load attempts of ONE auto-detection fixpoint, but never across
+    // separate compiles in a long-lived process.  A cache miss must observe
+    // package.json edits before it can publish a new early-library entry.
+    clearResolveCaches();
     const statuses = [];
     const npmSites = new Map();
     const judged = new Set();
@@ -620,13 +632,112 @@ export function analyze(entryPath, opts = {}) {
 }
 /** The whole pipeline: load → preflight → lower → validate → emit C → clang. */
 export async function compile(entryPath, opts) {
+    const frontendInputs = new FrontendInputTracker();
+    return frontendInputs.run(() => compileTracked(entryPath, opts, frontendInputs));
+}
+function executableNativeFeatures(mod, backend, dynamic, optimization, llvmRefusal) {
+    return {
+        backend,
+        ...(optimization === "dev" ? { optimization: "dev" } : {}),
+        ...(llvmRefusal === undefined ? {} : { llvmRefusal }),
+        dynamic,
+        regex: moduleUsesRegex(mod),
+        copying: moduleUsesCopying(mod),
+        textDecoderLegacy: moduleUsesLegacyTextDecoder(mod),
+        fileHandle: moduleUsesFileHandle(mod),
+        fetch: moduleUsesFetch(mod),
+        netIsland: moduleEmbedsBuiltin(mod, "node:http") ||
+            moduleEmbedsBuiltin(mod, "node:https") ||
+            moduleEmbedsBuiltin(mod, "node:net") ||
+            moduleEmbedsBuiltin(mod, "node:tls"),
+        zlib: moduleUsesZlib(mod) || moduleEmbedsCompressedNpm(mod),
+        assert: moduleUsesAssert(mod),
+        inspect: moduleUsesInspect(mod),
+        dynInvoke: moduleUsesDynInvoke(mod),
+        dc: moduleUsesDc(mod),
+        dynAsync: moduleUsesDynAsync(mod),
+        events: moduleUsesProcessEvents(mod),
+        emitter: moduleUsesEmitter(mod),
+        symbol: moduleUsesSymbol(mod),
+        searchParams: moduleUsesSearchParams(mod),
+        qs: moduleUsesQs(mod),
+        parseArgs: moduleUsesParseArgs(mod),
+        stream: moduleUsesStream(mod),
+        net: moduleUsesNet(mod),
+        http: moduleUsesHttpServer(mod),
+        http2: moduleUsesHttp2(mod),
+        dgram: moduleUsesDgram(mod),
+        watch: moduleUsesFsWatch(mod),
+        foreignFfi: hasForeignFfiCallback(mod.ffiImports ?? []),
+        nodeTest: moduleUsesNodeTest(mod),
+        tls: moduleUsesTls(mod),
+        tlsCa: moduleUsesTlsCa(mod),
+    };
+}
+async function compileExecutableNative(features, cPath, outPath, sanitize, ffi, programSplit = null, onArtifactReady) {
+    const effectiveProgramSplit = programSplit ??
+        (features.optimization === "dev" && features.backend === "llvm" && !sanitize
+            ? splitLlvmProgram(await readFile(cPath, "utf8"))
+            : null);
+    await compileC({
+        cPath,
+        outPath,
+        cacheIdentity: "scriptc-generated-v1",
+        ...(features.optimization === "dev" ? { optimization: "dev" } : {}),
+        ...(effectiveProgramSplit === null
+            ? {}
+            : {
+                programShards: effectiveProgramSplit.shards,
+                programPublicSymbols: effectiveProgramSplit.publicSymbols,
+            }),
+        sanitize,
+        dynamic: features.dynamic,
+        regex: features.regex,
+        copying: features.copying,
+        textDecoderLegacy: features.textDecoderLegacy,
+        fileHandle: features.fileHandle,
+        fetch: features.fetch,
+        netIsland: features.netIsland,
+        zlib: features.zlib,
+        assert: features.assert,
+        inspect: features.inspect,
+        dynInvoke: features.dynInvoke,
+        dc: features.dc,
+        dynAsync: features.dynAsync,
+        events: features.events,
+        emitter: features.emitter,
+        symbol: features.symbol,
+        searchParams: features.searchParams,
+        qs: features.qs,
+        parseArgs: features.parseArgs,
+        stream: features.stream,
+        net: features.net,
+        http: features.http,
+        http2: features.http2,
+        dgram: features.dgram,
+        watch: features.watch,
+        foreignFfi: features.foreignFfi,
+        nodeTest: features.nodeTest,
+        tls: features.tls,
+        tlsCa: features.tlsCa,
+        ...(onArtifactReady === undefined ? {} : { onArtifactReady }),
+        ...(ffi === null
+            ? {}
+            : { linkInputs: ffi.libraries, systemLibraries: ffi.systemLibraries }),
+    });
+}
+async function compileTracked(entryPath, opts, frontendInputs) {
+    entryPath = resolve(entryPath);
     let ffi = null;
+    let ffiProfileBytes = null;
     if (opts.ffiProfilePath !== undefined) {
-        const loaded = loadFfiProfile(opts.ffiProfilePath);
+        const ffiProfilePath = resolve(opts.ffiProfilePath);
+        const loaded = loadFfiProfile(ffiProfilePath);
         if (!loaded.ok) {
             return { ok: false, diagnostics: loaded.diagnostics, sourceTexts: new Map() };
         }
         ffi = loaded.profile;
+        ffiProfileBytes = loaded.profileBytes;
     }
     const buildPlatform = buildTargetPlatform();
     // Mobile triples are library-mode targets: the archive an embedding app
@@ -655,6 +766,81 @@ export async function compile(entryPath, opts) {
             };
         }
     }
+    const cacheRoot = provenanceSources() === null
+        ? await prepareBuildCacheRoot(buildCacheRoot())
+        : null;
+    const implementation = await compilerImplementationIdentity();
+    const earlyCacheOptions = {
+        entryPath,
+        outDir: opts.outDir,
+        outPath: opts.outPath,
+        emitIr: opts.emitIr ?? false,
+        sanitize: opts.sanitize ?? false,
+        dynamic: opts.dynamic ?? false,
+        backend: opts.backend ?? "auto",
+        ...(opts.optimization === "dev" ? { optimization: "dev" } : {}),
+        npmStatic: opts.npmStatic ?? null,
+        ffiProfile: opts.ffiProfilePath === undefined || ffiProfileBytes === null
+            ? null
+            : { path: opts.ffiProfilePath, bytes: ffiProfileBytes },
+        target: `${process.env["SCRIPTC_TARGET"] ?? "native"}:${buildPlatform}:${process.arch}`,
+        compiler: [process.env["SCRIPTC_CC"] ?? "clang"],
+        nativeEnvironment: await executableNativeEnvironmentFingerprint(),
+        nodeVersion: process.version,
+        implementation: implementation.digest,
+        implementationDependencies: implementation.dependencies,
+    };
+    const earlyHit = await readEarlyExecutableCache(cacheRoot, earlyCacheOptions);
+    if (earlyHit !== null) {
+        // Route/proof metadata is independently evictable. A full-compiler
+        // fallback that still finds the validated payload repairs that lightweight
+        // index so the next identical CLI invocation can avoid this module graph.
+        await publishEarlyExecutableRoute(cacheRoot, earlyCacheOptions).catch(() => undefined);
+        if (earlyHit.executableRestored) {
+            await pruneBuildCache(cacheRoot);
+            return {
+                ok: true,
+                binaryPath: opts.outPath,
+                cPath: earlyHit.cPath,
+                backend: earlyHit.native.backend,
+                ...(earlyHit.irPath === undefined ? {} : { irPath: earlyHit.irPath }),
+                ...(earlyHit.native.llvmRefusal === undefined
+                    ? {}
+                    : { llvmRefusal: earlyHit.native.llvmRefusal }),
+            };
+        }
+        try {
+            await compileExecutableNative(earlyHit.native, earlyHit.cPath, opts.outPath, opts.sanitize ?? false, ffi, null, async ({ dependencies }) => {
+                await publishEarlyExecutableCache(cacheRoot, earlyCacheOptions, {
+                    ...earlyHit,
+                    executableRestored: true,
+                    nativeDependencies: dependencies,
+                    frontend: earlyHit.frontend,
+                });
+            });
+        }
+        catch (err) {
+            if (ffi !== null && err instanceof CcCompileError) {
+                return {
+                    ok: false,
+                    diagnostics: [ffiNativeBuildDiag(ffiNativeBuildDetail(err), opts.ffiProfilePath ?? entryPath)],
+                    sourceTexts: new Map(),
+                };
+            }
+            throw err;
+        }
+        await pruneBuildCache(cacheRoot);
+        return {
+            ok: true,
+            binaryPath: opts.outPath,
+            cPath: earlyHit.cPath,
+            backend: earlyHit.native.backend,
+            ...(earlyHit.irPath === undefined ? {} : { irPath: earlyHit.irPath }),
+            ...(earlyHit.native.llvmRefusal === undefined
+                ? {}
+                : { llvmRefusal: earlyHit.native.llvmRefusal }),
+        };
+    }
     const fe = runFrontend(entryPath, opts.npmStatic);
     let lowered;
     let entryText;
@@ -728,6 +914,7 @@ export async function compile(entryPath, opts) {
     // (the frontend ran once, the IR is backend-agnostic — nothing recompiles).
     let cPath = join(opts.outDir, `${stem}.c`);
     let backend = "c";
+    let llvmSource = null;
     let llvmRefusal;
     if (opts.backend !== "c") {
         try {
@@ -737,6 +924,7 @@ export async function compile(entryPath, opts) {
             });
             cPath = join(opts.outDir, `${stem}.ll`);
             await writeFile(cPath, ll);
+            llvmSource = ll;
             backend = "llvm";
         }
         catch (err) {
@@ -763,105 +951,24 @@ export async function compile(entryPath, opts) {
         irPath = join(opts.outDir, `${stem}.ir.json`);
         await writeFile(irPath, serializeModule(lowered.module));
     }
+    const nativeFeatures = executableNativeFeatures(lowered.module, backend, opts.dynamic ?? false, opts.optimization ?? "release", llvmRefusal);
+    const programSplit = backend === "llvm" && (opts.optimization ?? "release") === "dev" &&
+        !(opts.sanitize ?? false) && llvmSource !== null
+        ? splitLlvmProgram(llvmSource)
+        : null;
     await mkdir(dirname(opts.outPath), { recursive: true });
+    let publishedExecutable = false;
     try {
-        await compileC({
-            cPath,
-            outPath: opts.outPath,
-            // The emitted TU's non-system dependencies are the runtime/vendor tree,
-            // which cc.ts fingerprints separately. Low-level arbitrary C omits this
-            // opt-in so same-path header edits can never hit a stale artifact.
-            cacheIdentity: "scriptc-generated-v1",
-            sanitize: opts.sanitize ?? false,
-            dynamic: opts.dynamic ?? false,
-            // The link switch for scr_regex.c + libregexp: detected on the IR, so
-            // regex-free programs keep the historical (pinned) command line.
-            regex: moduleUsesRegex(lowered.module),
-            // Array copying methods and the typed-array bridges live in one
-            // optional TU, linked only when one of their IR intrinsics survives.
-            copying: moduleUsesCopying(lowered.module),
-            textDecoderLegacy: moduleUsesLegacyTextDecoder(lowered.module),
-            // FileHandle owns a native descriptor and its settled-promise adapters;
-            // keep that optional TU out of programs that never call fsp.open.
-            fileHandle: moduleUsesFileHandle(lowered.module),
-            // The link switch for scr_fetch.c (the native bridge over scr_net +
-            // scr_tls + scr_http's client parser + zlib — cc.ts implies those
-            // units into the link): embedded npm code that references fetch gets
-            // the bridge; everything else keeps its exact link line.
-            fetch: moduleUsesFetch(lowered.module),
-            // The island's node:http/https client bridge: embedded graphs that
-            // import those builtins pull scr_net_island.c + the socket units.
-            netIsland: moduleEmbedsBuiltin(lowered.module, "node:http") ||
-                moduleEmbedsBuiltin(lowered.module, "node:https") ||
-                moduleEmbedsBuiltin(lowered.module, "node:net") ||
-                moduleEmbedsBuiltin(lowered.module, "node:tls"),
-            // The link switch for scr_zlib.c + libz: zlib.* libCalls on the IR,
-            // node:zlib in the embedded graph, or COMPRESSED embedded module text
-            // (emit-island.ts stores big npm sources as raw DEFLATE; the emitted
-            // main installs scr_zlib_inflate_exact on the same predicate).
-            zlib: moduleUsesZlib(lowered.module) || moduleEmbedsCompressedNpm(lowered.module),
-            // The link switch for scr_assert.c: assert.* libCalls on the IR (the
-            // regex switch also pulls it — scr_regex.c calls the assert helpers).
-            assert: moduleUsesAssert(lowered.module),
-            // The link switch for scr_inspect.c: insp.* libCalls on the IR.
-            inspect: moduleUsesInspect(lowered.module),
-            // The link switch for scr_dyn_invoke.c: dynInvoke nodes or
-            // dyn.defineProps libCalls on the IR.
-            dynInvoke: moduleUsesDynInvoke(lowered.module),
-            // The link switch for scr_dc.c: dc.* libCalls on the IR (the
-            // diagnostics_channel registry and pub/sub).
-            dc: moduleUsesDc(lowered.module),
-            // The link switch for scr_async_dyn.c: the checked-dynamic async
-            // surfaces (cc.ts also pulls it under the dynInvoke/dc gates).
-            dynAsync: moduleUsesDynAsync(lowered.module),
-            // The link switch for scr_events.c: process signal/exit listeners and
-            // the stdin event surface on the IR.
-            events: moduleUsesProcessEvents(lowered.module),
-            // The link switch for scr_events_emitter.c: the node:events
-            // EventEmitter surface on the IR (emitter.* libCalls or the
-            // %EventEmitter class def).
-            emitter: moduleUsesEmitter(lowered.module),
-            // The link switch for scr_symbol.c: sym.* libCalls or a symbol-kind
-            // type anywhere on the IR.
-            symbol: moduleUsesSymbol(lowered.module),
-            // The link switch for scr_url_params.c: sp.* libCalls, the
-            // url.searchParams getter, or a searchParams-kind type on the IR.
-            searchParams: moduleUsesSearchParams(lowered.module),
-            // The link switch for scr_qs.c: the qs.* libCalls that live there
-            // (parse/stringify/unescape; escape rides the always-linked encoder).
-            qs: moduleUsesQs(lowered.module),
-            // The static node:util parseArgs implementation (scr_util.c).
-            parseArgs: moduleUsesParseArgs(lowered.module),
-            // The link switch for scr_stream.c: the node:stream class surface on
-            // the IR (stream libCalls or the %Readable-family class defs).
-            stream: moduleUsesStream(lowered.module),
-            // The link switch for scr_net.c: net.* (or http.* — http rides on
-            // net) libCalls on the IR.
-            net: moduleUsesNet(lowered.module),
-            // The link switch for scr_http.c: http.* libCalls on the IR.
-            http: moduleUsesHttpServer(lowered.module),
-            http2: moduleUsesHttp2(lowered.module),
-            // The link switch for scr_dgram.c: dgram.* or dns.* libCalls on the IR.
-            dgram: moduleUsesDgram(lowered.module),
-            // The link switch for scr_watch.c: fs.watch/watcher.* libCalls on the IR.
-            watch: moduleUsesFsWatch(lowered.module),
-            foreignFfi: hasForeignFfiCallback(lowered.module.ffiImports ?? []),
-            // The link switch for scr_test.c: test.* libCalls on the IR.
-            nodeTest: moduleUsesNodeTest(lowered.module),
-            // The link switch for scr_tls.c + the vendored mbedTLS archive:
-            // tls.* or https.* libCalls on the IR.
-            tls: moduleUsesTls(lowered.module),
-            // The link switch for scr_tls_ca.c (the CA-store introspection unit
-            // — plain PEM bookkeeping, no mbedTLS): tlsca.* libCalls on the IR.
-            // cc.ts also compiles it under the tls gate (scr_tls.c consults the
-            // unit's default-set override for its trust anchors).
-            tlsCa: moduleUsesTlsCa(lowered.module),
-            ...(ffi !== null
-                ? {
-                    linkInputs: ffi.libraries,
-                    systemLibraries: ffi.systemLibraries,
-                }
-                : {}),
+        await compileExecutableNative(nativeFeatures, cPath, opts.outPath, opts.sanitize ?? false, ffi, programSplit, async ({ dependencies }) => {
+            await publishEarlyExecutableCache(cacheRoot, earlyCacheOptions, {
+                cPath,
+                native: nativeFeatures,
+                executableRestored: true,
+                nativeDependencies: dependencies,
+                frontend: frontendInputs.snapshot(),
+                ...(irPath === undefined ? {} : { irPath }),
+            });
+            publishedExecutable = true;
         });
     }
     catch (err) {
@@ -876,6 +983,16 @@ export async function compile(entryPath, opts) {
         }
         throw err;
     }
+    if (!publishedExecutable) {
+        await publishEarlyExecutableCache(cacheRoot, earlyCacheOptions, {
+            cPath,
+            native: nativeFeatures,
+            executableRestored: false,
+            frontend: frontendInputs.snapshot(),
+            ...(irPath === undefined ? {} : { irPath }),
+        }).catch(() => undefined);
+    }
+    await pruneBuildCache(cacheRoot);
     return {
         ok: true,
         binaryPath: opts.outPath,
@@ -1202,7 +1319,176 @@ function mergeSidecarIntSlots(cfg, facts, mod) {
     }
     return { ok: true, config: cfg };
 }
+function libraryNativeFeatures(mod, backend) {
+    return {
+        backend,
+        regex: moduleUsesRegex(mod),
+        assert: moduleUsesAssert(mod),
+        inspect: moduleUsesInspect(mod),
+        symbol: moduleUsesSymbol(mod),
+        searchParams: moduleUsesSearchParams(mod),
+        emitter: moduleUsesEmitter(mod),
+        zlib: moduleUsesZlib(mod),
+        copying: moduleUsesCopying(mod),
+        textDecoderLegacy: moduleUsesLegacyTextDecoder(mod),
+        ...(mod.lib?.identity !== undefined ? { buildId: mod.lib.identity.buildId } : {}),
+    };
+}
+function libraryLocalizeSymbols(profile) {
+    return profile.localizeRuntime
+        ? [
+            profile.initSymbol,
+            profile.sinkRegisterSymbol,
+            ...(profile.collectSymbol !== null ? [profile.collectSymbol] : []),
+            ...(profile.resultResetSymbol !== null ? [profile.resultResetSymbol] : []),
+            ...(profile.callbackRegisterSymbol !== null ? [profile.callbackRegisterSymbol] : []),
+            ...(profile.sidecar !== null
+                ? [profile.sidecar.buildIdSymbol, profile.sidecar.abiVersionSymbol]
+                : []),
+            ...profile.exports.map((entry) => entry.symbol),
+        ]
+        : undefined;
+}
+async function compileLibraryNative(profile, cPath, archivePath, sanitize, features) {
+    const localizeSymbols = libraryLocalizeSymbols(profile);
+    let identityCSource;
+    let programSource;
+    if (profile.sidecar !== null || profile.emission === "c" ||
+        (profile.emission === "llvm" && profile.optimization === "dev" && !sanitize)) {
+        const publicSource = await readFile(cPath, "utf8");
+        programSource = publicSource;
+    }
+    if (profile.sidecar !== null) {
+        if (features.buildId === undefined)
+            throw new Error("library identity TU has no build id");
+        const withoutIdentity = stripLibraryIdentity(programSource, profile.emission);
+        if (withoutIdentity === programSource) {
+            throw new Error("generated public library TU has no identity region");
+        }
+        programSource = withoutIdentity;
+        identityCSource = [
+            "#include <stdint.h>",
+            "#include <inttypes.h>",
+            `uint64_t ${profile.sidecar.buildIdSymbol}(void) { return UINT64_C(0x${features.buildId}); }`,
+            `uint32_t ${profile.sidecar.abiVersionSymbol}(void) { return ${profile.sidecar.abiVersion}u; }`,
+            "",
+        ].join("\n");
+    }
+    if (profile.emission === "c") {
+        programSource = stripLibrarySourceComments(programSource, profile.entry);
+    }
+    const llvmSplit = profile.emission === "llvm" && profile.optimization === "dev" && !sanitize && programSource !== undefined
+        ? splitLlvmLibraryProgram(programSource)
+        : null;
+    await compileLibArchive({
+        cPath,
+        ...(programSource !== undefined ? { programSource } : {}),
+        ...(identityCSource !== undefined ? { identityCSource } : {}),
+        ...(llvmSplit !== null
+            ? {
+                programShards: llvmSplit.shards,
+                programPublicSymbols: llvmSplit.publicSymbols,
+            }
+            : {}),
+        outPath: archivePath,
+        cacheIdentity: "scriptc-generated-library-v1",
+        sanitize,
+        optimization: profile.optimization,
+        ...(localizeSymbols !== undefined ? { localizeSymbols } : {}),
+        ...(profile.instancePerThread ? { threadInstances: true } : {}),
+        regex: features.regex,
+        assert: features.assert,
+        inspect: features.inspect,
+        symbol: features.symbol,
+        searchParams: features.searchParams,
+        emitter: features.emitter,
+        zlib: features.zlib,
+        copying: features.copying,
+        textDecoderLegacy: features.textDecoderLegacy,
+    });
+}
+async function emitSemanticLibraryHit(hit, profile, opts, archivePath, cacheRoot, cacheOptions, timing) {
+    const mod = hit.mod;
+    const rootDir = dirname(resolve(opts.profilePath));
+    let sidecarJson = hit.sidecarJson;
+    if (profile.sidecar !== null) {
+        if (mod.lib?.identity === undefined || sidecarJson === null) {
+            throw new Error("semantic library cache lost sidecar identity metadata");
+        }
+        const modules = canonicalModuleGraph(rootDir, hit.sourceTexts);
+        const { buildId, sourceHash } = libraryIdentityHashes(compilerReleaseVersion(), profile.profileBytes, modules);
+        mod.lib.identity.buildId = buildId;
+        hit.native.buildId = buildId;
+        sidecarJson = updateSidecarIdentity(sidecarJson, buildId, sourceHash);
+    }
+    const validation = validateModule(mod);
+    if (validation.length > 0) {
+        return {
+            ok: false,
+            diagnostics: validation.map((violation) => iceDiag(violation.message, violation.loc)),
+            sourceTexts: hit.sourceTexts,
+        };
+    }
+    await mkdir(opts.outDir, { recursive: true });
+    const stem = basename(profile.entry).replace(/\.(ts|js|mjs|cjs)$/, "");
+    const cPath = join(opts.outDir, `${stem}.lib.${profile.emission === "llvm" ? "ll" : "c"}`);
+    let translationUnit = hit.translationUnit;
+    if (profile.sidecar !== null) {
+        translationUnit = replaceLibraryIdentity(translationUnit, profile.emission, mod.lib.identity);
+    }
+    if (profile.emission === "llvm") {
+        await writeFile(cPath, translationUnit);
+    }
+    else {
+        const previous = hit.previousSources.get(mod.sourceFile);
+        const current = hit.sourceTexts.get(mod.sourceFile);
+        if (previous === undefined || current === undefined) {
+            throw new Error("semantic library cache lost the entry source text");
+        }
+        translationUnit = rebaseLibrarySourceComments(translationUnit, mod.sourceFile, createSourceLineRebaser(mod.sourceFile, previous, current));
+        await writeFile(cPath, translationUnit);
+    }
+    timing("semantic-tu-restore", { output_bytes: Buffer.byteLength(translationUnit) });
+    await rm(join(opts.outDir, `${stem}.lib.${profile.emission === "llvm" ? "c" : "ll"}`), { force: true });
+    let irPath;
+    if (opts.emitIr) {
+        irPath = join(opts.outDir, `${stem}.lib.ir.json`);
+        await writeFile(irPath, serializeModule(mod));
+    }
+    await compileLibraryNative(profile, cPath, archivePath, opts.sanitize ?? false, hit.native);
+    timing("native-archive");
+    let sidecarPath;
+    if (sidecarJson !== null) {
+        sidecarPath = profile.sidecar.path !== null
+            ? resolve(dirname(archivePath), profile.sidecar.path)
+            : `${archivePath}.contract.json`;
+        await writeFile(sidecarPath, sidecarJson);
+    }
+    await publishEarlyLibraryCache(cacheRoot, cacheOptions, {
+        cPath,
+        native: hit.native,
+        frontend: hit.frontend,
+        semantic: { mod, sources: hit.sourceTexts },
+        ...(irPath !== undefined ? { irPath } : {}),
+        ...(sidecarPath !== undefined ? { sidecarPath } : {}),
+    }).catch(() => undefined);
+    await pruneBuildCache(cacheRoot);
+    timing("semantic-cache-publish");
+    timing("complete");
+    return {
+        ok: true,
+        archivePath,
+        cPath,
+        backend: profile.emission,
+        ...(irPath !== undefined ? { irPath } : {}),
+        ...(sidecarPath !== undefined ? { sidecarPath } : {}),
+    };
+}
 export async function compileLibrary(opts) {
+    const frontendInputs = new FrontendInputTracker();
+    return frontendInputs.run(() => compileLibraryTracked(opts, frontendInputs));
+}
+async function compileLibraryTracked(opts, frontendInputs) {
     const timingOn = process.env["SCRIPTC_TIMING"] === "1";
     const timingStart = performance.now();
     let timingLast = timingStart;
@@ -1227,6 +1513,21 @@ export async function compileLibrary(opts) {
     const profile = loadedProfile.profile;
     const entryPath = profile.entry;
     const buildPlatform = buildTargetPlatform();
+    const profileDir = dirname(resolve(opts.profilePath));
+    for (let directory = dirname(entryPath);; directory = dirname(directory)) {
+        for (const name of ["tsconfig.json", "package.json"]) {
+            // Project configuration and package-realm metadata can affect the
+            // frontend even when TypeScript did not request their bytes through
+            // its delegated filesystem callbacks (tsgo may read them server-side).
+            frontendInputs.run(() => {
+                const path = join(directory, name);
+                trackedReadFile(path);
+            });
+        }
+        if (directory === profileDir || dirname(directory) === directory)
+            break;
+    }
+    const archivePath = opts.outPath ?? join(opts.outDir, `${basename(entryPath).replace(/\.(ts|js|mjs|cjs)$/, "")}.lib.a`);
     // Mobile-target admission first — a pure env/host check, so a refused
     // pairing never reaches toolchain discovery. iOS targets (device and
     // simulator) build on darwin hosts only: the Apple SDK sysroot and the
@@ -1283,6 +1584,44 @@ export async function compileLibrary(opts) {
             };
         }
     }
+    const cacheRoot = provenanceSources() === null
+        ? await prepareBuildCacheRoot(buildCacheRoot())
+        : null;
+    const earlyCacheOptions = {
+        profilePath: opts.profilePath,
+        profileBytes: profile.profileBytes,
+        entryPath,
+        outDir: opts.outDir,
+        ...(opts.outPath !== undefined ? { outPath: opts.outPath } : {}),
+        emitIr: opts.emitIr ?? false,
+        sanitize: opts.sanitize ?? false,
+        target: `${process.env["SCRIPTC_TARGET"] ?? "native"}:${buildPlatform}:${process.arch}`,
+        compiler: [process.env["SCRIPTC_CC"] ?? "clang"],
+        nodeVersion: process.version,
+        implementation: await libraryFrontendImplementationFingerprint(),
+    };
+    const earlyHit = await readEarlyLibraryCache(cacheRoot, earlyCacheOptions, profile.sidecar === null ? undefined : profile.sidecar.path);
+    if (earlyHit !== null) {
+        timing("early-cache-hit");
+        await compileLibraryNative(profile, earlyHit.cPath, archivePath, opts.sanitize ?? false, earlyHit.native);
+        timing("native-archive");
+        timing("complete");
+        return {
+            ok: true,
+            archivePath,
+            cPath: earlyHit.cPath,
+            backend: earlyHit.native.backend,
+            ...(earlyHit.irPath !== undefined ? { irPath: earlyHit.irPath } : {}),
+            ...(earlyHit.sidecarPath !== undefined ? { sidecarPath: earlyHit.sidecarPath } : {}),
+        };
+    }
+    timing("early-cache-miss");
+    const semanticHit = await readSemanticLibraryCache(cacheRoot, earlyCacheOptions, profile.sidecar === null ? undefined : profile.sidecar.path);
+    if (semanticHit !== null) {
+        timing("semantic-cache-hit", { changed_sources: semanticHit.changedSources.length });
+        return emitSemanticLibraryHit(semanticHit, profile, opts, archivePath, cacheRoot, earlyCacheOptions, timing);
+    }
+    timing("semantic-cache-miss");
     // Bare npm specifiers in a library graph take the STATIC-OR-REFUSE
     // posture: "lib" runs the same auto-detection and eligibility bar as
     // the executable lane's --npm-static (own .d.ts, unminified shipped JS,
@@ -1445,9 +1784,9 @@ export async function compileLibrary(opts) {
     // The ask-2 contract sidecar rides the same invocation. Identity first
     // (schema §2's worked build_id definition over compiler version, profile
     // bytes, and the sorted canonical module graph; source_hash per the
-    // profile's "module-graph" contract) — the u64 lands on the IR so both
-    // backends emit the identity getters from the ONE value the sidecar
-    // records (V12's coherence by construction), then the projection into
+    // profile's "module-graph" contract) — the u64 lands on the IR so native
+    // archive assembly emits the identity getters from the ONE value the
+    // sidecar records (V12's coherence by construction), then the projection into
     // the schema (declaration orders from the AST) and the V1–V14
     // self-check before anything is written.
     let sidecarJson = null;
@@ -1532,41 +1871,8 @@ export async function compileLibrary(opts) {
         irPath = join(opts.outDir, `${stem}.lib.ir.json`);
         await writeFile(irPath, serializeModule(mod));
     }
-    const archivePath = opts.outPath ?? join(opts.outDir, `${stem}.lib.a`);
-    // Multi-instance library mode: the profile-declared external surface —
-    // the mode-provided entries, the identity getters, and the export map —
-    // is exactly the set the localization step keeps global.
-    const localizeSymbols = profile.localizeRuntime
-        ? [
-            profile.initSymbol,
-            profile.sinkRegisterSymbol,
-            ...(profile.collectSymbol !== null ? [profile.collectSymbol] : []),
-            ...(profile.resultResetSymbol !== null ? [profile.resultResetSymbol] : []),
-            ...(profile.callbackRegisterSymbol !== null ? [profile.callbackRegisterSymbol] : []),
-            ...(profile.sidecar !== null
-                ? [profile.sidecar.buildIdSymbol, profile.sidecar.abiVersionSymbol]
-                : []),
-            ...profile.exports.map((e) => e.symbol),
-        ]
-        : undefined;
-    await compileLibArchive({
-        cPath,
-        outPath: archivePath,
-        cacheIdentity: "scriptc-generated-library-v1",
-        sanitize: opts.sanitize ?? false,
-        optimization: profile.optimization,
-        ...(localizeSymbols !== undefined ? { localizeSymbols } : {}),
-        ...(profile.instancePerThread ? { threadInstances: true } : {}),
-        regex: moduleUsesRegex(mod),
-        assert: moduleUsesAssert(mod),
-        inspect: moduleUsesInspect(mod),
-        symbol: moduleUsesSymbol(mod),
-        searchParams: moduleUsesSearchParams(mod),
-        emitter: moduleUsesEmitter(mod),
-        zlib: moduleUsesZlib(mod),
-        copying: moduleUsesCopying(mod),
-        textDecoderLegacy: moduleUsesLegacyTextDecoder(mod),
-    });
+    const nativeFeatures = libraryNativeFeatures(mod, profile.emission);
+    await compileLibraryNative(profile, cPath, archivePath, opts.sanitize ?? false, nativeFeatures);
     timing("native-archive");
     // The sidecar lands beside the compiled object, written by the same
     // invocation (profile-declared name; the neutral default when the
@@ -1579,6 +1885,17 @@ export async function compileLibrary(opts) {
                 : `${archivePath}.contract.json`;
         await writeFile(sidecarPath, sidecarJson);
     }
+    const earlyPublish = {
+        cPath,
+        native: nativeFeatures,
+        frontend: frontendInputs.snapshot(),
+        semantic: { mod, sources: sourceTexts },
+        ...(irPath !== undefined ? { irPath } : {}),
+        ...(sidecarPath !== undefined ? { sidecarPath } : {}),
+    };
+    await publishEarlyLibraryCache(cacheRoot, earlyCacheOptions, earlyPublish).catch(() => undefined);
+    await pruneBuildCache(cacheRoot);
+    timing("early-cache-publish");
     timing("complete");
     return {
         ok: true,