@scriptc/compiler 0.1.7 → 0.2.1

package/dist/backend/native-toolchain.js

@@ -1,3 +1,8 @@
+import { driverTraceCandidates, linkTraceCandidate } from "./link-trace.js";
+import { toolchainEnvironmentCachePolicy, toolchainEnvironmentFingerprint } from "./toolchain-environment.js";
+export { toolchainEnvironmentCachePolicy, toolchainEnvironmentFingerprint } from "./toolchain-environment.js";
+import { IPHONEOS_MIN_VERSION, ANDROID_MIN_API, isIosTarget, isAndroidTarget, isMobileTarget, mobileLibraryTarget, mobileTargetRefusal, configuredTargetPlatform } from "./target-platform.js";
+export { IPHONEOS_MIN_VERSION, ANDROID_MIN_API, isIosTarget, isAndroidTarget, isMobileTarget, mobileLibraryTarget, mobileTargetRefusal, configuredTargetPlatform } from "./target-platform.js";
 import { InternalCompilerError } from "../errors.js";
 import { execFile, spawnSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
@@ -46,7 +51,7 @@ function stableTestMemo(cache, key, probe) {
     });
     return pending;
 }
-export const EXECUTABLE_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_crypto_async.c", "scr_child.c", "scr_cycle.c"];
+export const EXECUTABLE_RUNTIME_SOURCES = ["scr_number.c", "scr_bigint.c", "scr_string.c", "scr_grapheme.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_url_params.c", "scr_json.c", "scr_node_builtin.c", "scr_async.c", "scr_crypto_async.c", "scr_child.c", "scr_cycle.c"];
 /**
  * Per-target section-elimination recipe. This belongs beside the native
  * driver rather than a particular build path: one-shot compilation, cached
@@ -83,102 +88,6 @@ export function executableSectionEliminationFlags(platform) {
             return { compile: [], link: [] };
     }
 }
-/** Environment variables consumed by clang, its linker/subtools, or the
- * platform SDK selection. They are implicit command-line inputs: changing one
- * must never reuse an artifact produced under the old toolchain posture. */
-const TOOLCHAIN_ENV_KEYS = [
-    "COMPILER_PATH",
-    "GCC_EXEC_PREFIX",
-    "CPATH",
-    "C_INCLUDE_PATH",
-    "CPLUS_INCLUDE_PATH",
-    "OBJC_INCLUDE_PATH",
-    "OBJCPLUS_INCLUDE_PATH",
-    "LIBRARY_PATH",
-    "LD_LIBRARY_PATH",
-    "LD_RUN_PATH",
-    "DYLD_LIBRARY_PATH",
-    "DYLD_FRAMEWORK_PATH",
-    "DYLD_FALLBACK_LIBRARY_PATH",
-    "DYLD_FALLBACK_FRAMEWORK_PATH",
-    "SDKROOT",
-    "DEVELOPER_DIR",
-    "MACOSX_DEPLOYMENT_TARGET",
-    "IPHONEOS_DEPLOYMENT_TARGET",
-    "TVOS_DEPLOYMENT_TARGET",
-    "WATCHOS_DEPLOYMENT_TARGET",
-    "DRIVERKIT_DEPLOYMENT_TARGET",
-    "XROS_DEPLOYMENT_TARGET",
-    "CCC_OVERRIDE_OPTIONS",
-    "CCC_ADD_ARGS",
-    "CLANG_CONFIG_FILE_SYSTEM_DIR",
-    "CLANG_CONFIG_FILE_USER_DIR",
-    "CC",
-    "CFLAGS",
-    "CPPFLAGS",
-    "LDFLAGS",
-    "AR",
-    "RANLIB",
-    "CMAKE_GENERATOR",
-    "CMAKE_TOOLCHAIN_FILE",
-    "ZIG_LIB_DIR",
-    "ZIG_LIBC",
-    "SOURCE_DATE_EPOCH",
-    "ZERO_AR_DATE",
-    "LANG",
-    "LC_ALL",
-    "LC_CTYPE",
-];
-/** Toolchain variables whose values name mutable files/directories consumed
- * while compiling a TU (or can inject arbitrary compiler options). Hashing the
- * value is insufficient: a header, SDK, config, compiler helper, or loaded
- * dylib can change in place while the spelling remains stable. In that posture
- * neither complete artifacts nor per-TU runtime objects are safe to reuse. */
-const MUTABLE_COMPILE_ENV_KEYS = [
-    "COMPILER_PATH",
-    "GCC_EXEC_PREFIX",
-    "CPATH",
-    "C_INCLUDE_PATH",
-    "CPLUS_INCLUDE_PATH",
-    "OBJC_INCLUDE_PATH",
-    "OBJCPLUS_INCLUDE_PATH",
-    "LD_LIBRARY_PATH",
-    "DYLD_LIBRARY_PATH",
-    "DYLD_FRAMEWORK_PATH",
-    "DYLD_FALLBACK_LIBRARY_PATH",
-    "DYLD_FALLBACK_FRAMEWORK_PATH",
-    "SDKROOT",
-    "DEVELOPER_DIR",
-    "CCC_OVERRIDE_OPTIONS",
-    "CCC_ADD_ARGS",
-    "CLANG_CONFIG_FILE_SYSTEM_DIR",
-    "CLANG_CONFIG_FILE_USER_DIR",
-    // `zig cc` resolves its bundled headers/runtime through ZIG_LIB_DIR and a
-    // caller-selected native libc description through ZIG_LIBC. Both values name
-    // mutable compiler inputs whose contents can change behind a stable path.
-    "ZIG_LIB_DIR",
-    "ZIG_LIBC",
-];
-/** These variables only redirect link-time inputs. Runtime objects remain
- * reusable, but a complete executable could otherwise retain a library that
- * was rebuilt in place behind the same search-path spelling. */
-const MUTABLE_LINK_ENV_KEYS = ["LIBRARY_PATH", "LD_RUN_PATH"];
-export function toolchainEnvironmentCachePolicy(env = process.env) {
-    const mutableCompileInput = MUTABLE_COMPILE_ENV_KEYS.some((name) => env[name] !== undefined);
-    const mutableLinkInput = MUTABLE_LINK_ENV_KEYS.some((name) => env[name] !== undefined);
-    return {
-        completeArtifacts: !mutableCompileInput && !mutableLinkInput,
-        runtimeObjects: !mutableCompileInput,
-    };
-}
-export function toolchainEnvironmentFingerprint(env = process.env) {
-    const hash = createHash("sha256").update("toolchain-env-v1\0");
-    for (const name of TOOLCHAIN_ENV_KEYS) {
-        const value = env[name];
-        hash.update(name).update(value === undefined ? "\0unset\0" : "\0set\0").update(value ?? "").update("\0");
-    }
-    return hash.digest("hex");
-}
 /** Inputs that can change which native tool/runtime implementation an
  * executable build selects before compileC has a chance to rediscover it.
  * The early whole-program cache keys this exact posture before restoring a
@@ -299,50 +208,6 @@ export function isZigDriver(driver) {
  * embedder's side of the contract: Xcode links iOS archives against the
  * selected SDK, and Gradle/NDK builds link Android archives against the
  * API-26+ bionic stubs. */
-export const IPHONEOS_MIN_VERSION = "15.0";
-export const ANDROID_MIN_API = 26;
-const MOBILE_LIBRARY_TARGETS = [
-    "aarch64-apple-ios",
-    "aarch64-apple-ios-simulator",
-    "aarch64-linux-android",
-];
-export function isIosTarget(target) {
-    return target === "aarch64-apple-ios" || target === "aarch64-apple-ios-simulator";
-}
-export function isAndroidTarget(target) {
-    return target === "aarch64-linux-android";
-}
-export function isMobileTarget(target) {
-    return isIosTarget(target) || isAndroidTarget(target);
-}
-/** The canonical mobile triple SCRIPTC_TARGET selects, or null when the
- * environment names none. Pure string inspection — safe to consult before
- * any toolchain discovery runs. */
-export function mobileLibraryTarget(env = process.env) {
-    const target = env["SCRIPTC_TARGET"] ?? "";
-    return isMobileTarget(target) ? target : null;
-}
-/** The admission verdict for a mobile-family triple: null when the spelling
- * and host pairing are supported, otherwise the refusal text (the same text
- * resolveCc throws and compileLibrary reports as SC3002). Pure string/host
- * inspection — no discovery, no subprocess. */
-export function mobileTargetRefusal(target, hostPlatform = process.platform) {
-    if (isIosTarget(target)) {
-        return hostPlatform === "darwin"
-            ? null
-            : `${target} library archives build on macOS hosts only (the Apple iOS SDK sysroot and Mach-O symbol localization live there); this host is ${hostPlatform}`;
-    }
-    if (isAndroidTarget(target))
-        return null;
-    // A near-miss mobile spelling must refuse with the supported set named,
-    // never reach zig with no sysroot wired (the compile would fail on the
-    // first libc header) or produce an artifact for an unverified device
-    // class.
-    if (/(?:^|-)(?:ios|tvos|watchos|visionos|android)/.test(target)) {
-        return `unsupported mobile target '${target}' (supported: ${MOBILE_LIBRARY_TARGETS.join(", ")})`;
-    }
-    return null;
-}
 /** The Apple SDK root for one mobile platform, discovered through xcrun the
  * way Xcode's own build system selects it. Memoized per SDK name and
  * selection environment: production rediscovers per process, and the two
@@ -544,33 +409,6 @@ function isMuslTarget(driver) {
  * analyze(): the FRONTEND consults it too (path.sep / os.EOL literals and
  * the path-module binding follow the target — a win32 triple compiles
  * Node-on-Windows semantics, path.win32 backing the bare module). */
-export function configuredTargetPlatform(env = process.env, hostPlatform = process.platform) {
-    const target = env["SCRIPTC_TARGET"] ?? "";
-    if (target === "")
-        return hostPlatform;
-    if (target === "wasm32-wasi")
-        return "wasi";
-    if (target.includes("wasi")) {
-        throw new Error(`unsupported WASI target '${target}' (supported: wasm32-wasi)`);
-    }
-    // iOS is a darwin-family target: Mach-O objects, ld64 localization,
-    // POSIX path/EOL semantics. Android falls to the linux arm below —
-    // bionic is a linux libc and its archives are ordinary ELF.
-    if (isIosTarget(target))
-        return "darwin";
-    if (isAndroidTarget(target))
-        return "linux";
-    if (/(?:^|-)(?:ios|tvos|watchos|visionos|android)/.test(target)) {
-        throw new Error(`unsupported mobile target '${target}' (supported: ${MOBILE_LIBRARY_TARGETS.join(", ")})`);
-    }
-    if (target.includes("linux"))
-        return "linux";
-    if (target.includes("windows"))
-        return "win32";
-    if (target.includes("macos") || target.includes("darwin"))
-        return "darwin";
-    throw new Error(`unsupported target '${target}' (supported OS families: linux, windows, macos/darwin, wasm32-wasi)`);
-}
 export function targetPlatform(driver) {
     if (driver.target === null)
         return process.platform;
@@ -722,12 +560,11 @@ export async function compileLibArchive(opts) {
         ...(isMuslTarget(driver) ? ["scr_musl.c"] : []),
         ...(regex ? ["scr_regex.c"] : []),
         ...(opts.assert || regex || opts.symbol ? ["scr_assert.c"] : []),
-        ...(opts.inspect ? ["scr_inspect.c"] : []),
+        ...(opts.inspect ? ["scr_inspect.c", "scr_console_native.c"] : []),
         ...(opts.symbol ? ["scr_symbol.c"] : []),
-        ...(opts.bigint ? ["scr_bigint.c"] : []),
         ...(opts.assert && opts.bigint ? ["scr_bigint_assert.c"] : []),
-        ...(opts.searchParams ? ["scr_url_params.c"] : []),
         ...(opts.emitter ? ["scr_events_emitter.c", "scr_dyn_handle.c"] : []),
+        ...(opts.dynInvoke ? ["scr_dyn_invoke.c"] : []),
         ...(opts.zlib ? ["scr_zlib.c"] : []),
         ...(opts.copying ? ["scr_copying.c"] : []),
     ];
@@ -820,9 +657,9 @@ export async function compileLibArchive(opts) {
     let cachedProgramBytes = opts.programSource === undefined
         ? null
         : Buffer.from(opts.programSource, "utf8");
-    const identityBytes = opts.identityCSource === undefined
+    const identityBytes = opts.identityLlvmSource === undefined
         ? null
-        : Buffer.from(opts.identityCSource, "utf8");
+        : Buffer.from(opts.identityLlvmSource, "utf8");
     if (persistentCache !== null) {
         try {
             const [cv, fingerprint, programBytes] = await Promise.all([
@@ -1098,7 +935,7 @@ export async function compileLibArchive(opts) {
             const identityObject = identityBytes === null
                 ? null
                 : await (async () => {
-                    const source = join(buildDir, "identity.c");
+                    const source = join(buildDir, "identity.ll");
                     await writeFile(source, identityBytes);
                     return compileOne(source, `${stem}.identity.o`);
                 })();
@@ -1268,8 +1105,7 @@ export async function compileLibArchive(opts) {
  *            mirrors MSVC link.exe; zig's COFF driver refuses multi-object
  *            merges) and llvm-objcopy rejects symbol-scope flags for
  *            COFF, so no tool pairing exists to shell out to. */
-async function localizeLibraryObjects(driver, arArgv, buildDir, rootObjects, supportObjects, keepSymbols, stem) {
-    const platform = targetPlatform(driver);
+export async function localizeLibraryObjects(driver, arArgv, buildDir, rootObjects, supportObjects, keepSymbols, stem, platform = targetPlatform(driver)) {
     const combined = join(buildDir, `${stem}.localized.o`);
     const staging = join(buildDir, `${stem}.localize-staging.a`);
     const keepFile = join(buildDir, "localize-keep.syms");
@@ -1355,9 +1191,9 @@ async function localizeLibraryObjects(driver, arArgv, buildDir, rootObjects, sup
  *                     (every .c/.h in the runtime src dir plus the vendor pin
  *                     QJS_COMMIT), the caller's dependency identity, the
  *                     compiler-visible TU path, Darwin output basename, the
- *                     FULL normalized command line, and the emitted C bytes).
- *                     Emitted C is
- *                     byte-stable by project invariant, so unchanged programs
+ *                     FULL normalized command line, and the emitted LLVM bytes).
+ *                     Emitted LLVM is
+ *                     deterministic, so unchanged programs
  *                     hit; any flag difference — e.g. the sanitized lane's
  *                     -O1/-fsanitize=address/-DSCR_RC_AUDIT — lands in a
  *                     naturally distinct key. On a hit the cached binary is
@@ -1386,7 +1222,7 @@ async function localizeLibraryObjects(driver, arArgv, buildDir, rootObjects, sup
  *   obj/<set>/<f>.o — per-flavor runtime objects for cache-miss builds. The
  *                     historical single invocation recompiles every runtime
  *                     TU per program (~1.3s at -O2); with cached objects a
- *                     miss compiles ONLY the program's C and links (~0.15s).
+ *                     miss compiles only the program's LLVM and links (~0.15s).
  *                     Library-mode -DSCR_LIB objects use a distinct flavor.
  *                     The clang driver hands every input the same option set,
  *                     so per-TU `-c` compiles with those options plus a final
@@ -2139,29 +1975,6 @@ function implicitToolchainFingerprints(driver, environmentFingerprint) {
 function implicitToolchainFingerprint(driver, environmentFingerprint) {
     return implicitToolchainFingerprints(driver, environmentFingerprint).then((fingerprints) => fingerprints.complete);
 }
-function linkTraceCandidate(line) {
-    const trimmed = line.trim().replace(/^(?:LOAD|load)\s+/, "");
-    if (trimmed === "")
-        return [];
-    const unquoted = (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
-        (trimmed.startsWith("'") && trimmed.endsWith("'"))
-        ? trimmed.slice(1, -1)
-        : trimmed;
-    const candidates = [unquoted];
-    const member = unquoted.lastIndexOf("(");
-    if (member > 0 && unquoted.endsWith(")"))
-        candidates.push(unquoted.slice(0, member));
-    return candidates;
-}
-function driverTraceCandidates(line) {
-    const candidates = [];
-    for (const match of line.matchAll(/"((?:\\.|[^"\\])*)"|'([^']*)'|(\S+)/g)) {
-        const token = (match[1] ?? match[2] ?? match[3] ?? "").replace(/\\(["\\])/g, "$1");
-        if (token !== "")
-            candidates.push(token);
-    }
-    return candidates;
-}
 async function existingDriverTracePaths(output, cwd, excludedRoot) {
     const candidates = new Set();
     for (const line of output.split(/\r?\n/)) {
@@ -2660,6 +2473,8 @@ function localArtifactIdentity(opts, driver, environmentFingerprint, compilerIde
         hash.update("optimization-linker-flags\0")
             .update(executableOptimizationFlags.join("\x1f")).update("\0");
     }
+    if (opts.sanitize && opts.optimization === "dev")
+        hash.update("sanitized-runtime-o1-v1\0");
     if (programShardMerge !== null) {
         updateProgramShardCacheIdentity(hash, opts.programShards, opts.programPublicSymbols, programShardMerge);
     }
@@ -2867,8 +2682,9 @@ export async function stageRuntimeObjects(objects, stageDir) {
 }
 /** Compiles one C program together with the runtime sources.
  * With caching disabled, the runtime (a dozen small files) is recompiled on
- * every build in one clang invocation — no cached-archive
- * staleness bugs. --dynamic additionally compiles
+ * every build — no cached-archive staleness bugs. Sanitized dev builds compile
+ * the program separately so its O0 setting does not slow the O1 runtime.
+ * Other builds use one clang invocation. --dynamic additionally compiles
  * scr_island.c under SCR_DYNAMIC and links the cached engine archive (built
  * lazily, see above); regex-using programs additionally compile scr_regex.c
  * and link libregexp (the cached objects, or the archive's own copy under
@@ -2907,6 +2723,10 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
     const tlsCa = (opts.tlsCa ?? false) || tls;
     const driver = resolveCc();
     const darwinDebugSymbols = needsDarwinDebugSymbols(targetPlatform(driver), optimization, opts.strip);
+    if (opts.frameworks?.length && targetPlatform(driver) !== "darwin")
+        throw new Error("FFI frameworks require a Darwin target");
+    if (opts.frameworks?.some(name => !/^[A-Za-z][A-Za-z0-9_]*$/.test(name)))
+        throw new Error("Invalid FFI framework name");
     const debugFlags = optimization === "dev" && !opts.strip
         ? ["-gline-tables-only", ...(opts.cPath.endsWith(".ll") ? [] : ["-gno-column-info"])]
         : [];
@@ -2990,7 +2810,7 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
     const persistentDriverCache = cachePolicy.runtimeObjects &&
         configuredCacheRoot !== null &&
         await compilerDriverSupportsPersistentCache(driver, toolchainEnv);
-    // Only compiler-generated TUs opt in. Arbitrary `compileC` / `--from-c`
+    // Only compiler-generated TUs opt in. Arbitrary `compileC` inputs
     // inputs may include caller-owned headers whose contents are not otherwise
     // represented in this key, so they retain the fully uncached historical
     // path unless the caller supplies its own complete dependency identity.
@@ -3025,6 +2845,7 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
         cachePolicy.completeArtifacts &&
         persistentCache.identity === "scriptc-generated-v1" &&
         (opts.linkInputs?.length ?? 0) === 0 &&
+        (opts.frameworks?.length ?? 0) === 0 &&
         (opts.systemLibraries?.length ?? 0) === 0 &&
         process.env["SCRIPTC_TEST_TRUST_COMPILER_WRAPPER"] !== "1") {
         try {
@@ -3228,20 +3049,20 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
         ...driver.targetArgs,
         ...threadArgs,
         ...(sanitize
-            ? [optimization === "dev" ? "-O0" : "-O1", "-fsanitize=address", "-DSCR_RC_AUDIT"]
+            ? ["-O1", "-fsanitize=address", "-DSCR_RC_AUDIT"]
             : [optimization === "dev" ? "-O0" : "-O2"]),
         ...executableSectionFlags.compile,
         ...(opts.textDecoderLegacy ? ["-DSCR_TEXT_DECODER_LEGACY"] : []),
         "-fno-math-errno",
-        // The emitted object model is deliberately type-punned C: a hierarchy
+        // The runtime object model uses type-punned C: a hierarchy
         // upcast is a raw pointer cast, so one object's header (rc, vt) and
         // fields are read and written through BOTH the base and derived struct
         // types (sc_retain_Derived vs sc_release_Base on the same object).
         // C's effective-type rule calls that UB, and clang's TBAA at -O2
         // reorders/elides the rc updates once everything inlines — an upcast
         // identity compare frees the object while a global still owns it.
-        // The LLVM backend emits no TBAA metadata, so this flag is also what
-        // keeps the two backends' memory semantics identical. Mirrored in the
+        // The LLVM backend emits no TBAA metadata; this flag preserves
+        // matching memory semantics in the runtime. Mirrored in the
         // cache-miss cflags below and compileLibArchive — the three option
         // sets must stay in lockstep.
         "-fno-strict-aliasing",
@@ -3267,10 +3088,10 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
             ? ["-I", vendorEngineDir(), rt(join(rtDir, "scr_regex.c")), ...lreObjects]
             : []),
         ...(opts.assert || regex || opts.symbol ? [rt(join(rtDir, "scr_assert.c"))] : []),
-        ...(opts.inspect ? [rt(join(rtDir, "scr_inspect.c"))] : []),
+        ...(opts.inspect ? [rt(join(rtDir, "scr_inspect.c")), rt(join(rtDir, "scr_console_native.c"))] : []),
         ...((opts.dynInvoke || nativeFetch) ? [rt(join(rtDir, "scr_dyn_invoke.c"))] : []),
         ...(opts.dc ? [rt(join(rtDir, "scr_dc.c"))] : []),
-        ...(opts.dynAsync || opts.dynInvoke || opts.dc || nativeFetch ? [rt(join(rtDir, "scr_async_dyn.c"))] : []),
+        ...(opts.dynAsync || opts.dynInvoke || opts.dc || opts.fileHandle || nativeFetch ? [rt(join(rtDir, "scr_async_dyn.c"))] : []),
         // The zlib UNIT (scr_zlib.c) gates on zlib.* IR use; the LINK (system
         // libz on the default host-clang build, vendored objects on Zig builds)
         // also serves the native fetch's gzip decoder — spread exactly once.
@@ -3295,9 +3116,7 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
         // their exact size class.
         ...(opts.emitter || net ? [rt(join(rtDir, "scr_dyn_handle.c"))] : []),
         ...(opts.symbol ? [rt(join(rtDir, "scr_symbol.c"))] : []),
-        ...(opts.bigint ? [rt(join(rtDir, "scr_bigint.c"))] : []),
         ...(opts.assert && opts.bigint ? [rt(join(rtDir, "scr_bigint_assert.c"))] : []),
-        ...(opts.searchParams ? [rt(join(rtDir, "scr_url_params.c"))] : []),
         ...(opts.qs ? [rt(join(rtDir, "scr_qs.c"))] : []),
         ...(opts.parseArgs ? [rt(join(rtDir, "scr_util.c"))] : []),
         ...(opts.stream ? [rt(join(rtDir, "scr_stream.c"))] : []),
@@ -3399,6 +3218,7 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
         build.programPath ?? opts.cPath,
         ...(opts.linkInputs ?? []),
         ...(opts.systemLibraries ?? []).map((name) => `-l${name}`),
+        ...(opts.frameworks ?? []).flatMap(name => ["-framework", name]),
         // GNU ld resolves libraries from left to right and commonly enables
         // --as-needed: host-clang libz must follow scr_zlib.c/scr_fetch.c and every
         // generated/native input that references inflate symbols. Cross
@@ -3413,16 +3233,15 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
         ...executableLinkFlags,
         "-o", build.outPath ?? opts.outPath,
     ];
-    // Compile-only flags shared by runtime-object population and the caller-TU
-    // dependency probe. They reproduce the option set every TU sees in the
-    // historical single clang invocation.
+    // Runtime-object flags. Program compilation and dependency discovery add
+    // the dev sanitizer override below so both cache identities match reality.
     const cflags = [
         "-std=c11",
         ...debugFlags,
         ...driver.targetArgs,
         ...threadArgs,
         ...(sanitize
-            ? [optimization === "dev" ? "-O0" : "-O1", "-fsanitize=address", "-DSCR_RC_AUDIT"]
+            ? ["-O1", "-fsanitize=address", "-DSCR_RC_AUDIT"]
             : [optimization === "dev" ? "-O0" : "-O2"]),
         ...executableSectionFlags.compile,
         ...(opts.textDecoderLegacy ? ["-DSCR_TEXT_DECODER_LEGACY"] : []),
@@ -3436,9 +3255,15 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
         ...(tlsArchive !== null ? ["-I", join(vendorTlsDir(), "include")] : []),
         ...(dynamic ? ["-DSCR_DYNAMIC"] : []),
     ];
-    const programCompilerArgs = opts.cPath.endsWith(".ll")
-        ? [...cflags, "-Wno-override-module"]
-        : cflags;
+    // Keep sanitizer runtime objects optimized in both postures. Large dev
+    // programs still compile at O0, avoiding an expensive LLVM optimization
+    // pass while retaining ASan and reference-count checks in every runtime unit.
+    const separateSanitizedProgram = sanitize && optimization === "dev";
+    const programCompilerArgs = [
+        ...cflags,
+        ...(separateSanitizedProgram ? ["-O0"] : []),
+        ...(opts.cPath.endsWith(".ll") ? ["-Wno-override-module"] : []),
+    ];
     const programSourceExtension = opts.cPath.endsWith(".ll") ? ".ll" : ".c";
     const ccName = driver.argv.join(" ");
     const runClang = async (args) => {
@@ -3448,20 +3273,44 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
         catch (err) {
             const stderr = subprocessFailureDetail(err);
             const guidance = (opts.linkInputs?.length ?? 0) > 0 ||
+                (opts.frameworks?.length ?? 0) > 0 ||
                 (opts.systemLibraries?.length ?? 0) > 0
                 ? "This build includes native FFI link inputs. Check that every symbol and system library exists, " +
                     "that archive/object ordering is correct, and that each input matches the selected target."
-                : `This is a scriptc bug (generated C should always compile) unless ` +
-                    `${ccName} itself is missing/broken.`;
+                : `Check the supplied native source and the selected ${ccName} toolchain.`;
             throw new CcCompileError(ccName, stderr, `${ccName} failed compiling ${opts.cPath}.\n` +
                 `${guidance}\n\n${stderr}`);
         }
     };
+    const buildExecutable = async (runtimeInput, build = {}) => {
+        if (!separateSanitizedProgram) {
+            await runClang(buildArgs(runtimeInput, build));
+            return;
+        }
+        const stage = await mkdtemp(join(tmpdir(), "scriptc-sanitized-program-"));
+        try {
+            const object = join(stage, "program.o");
+            await runClang([
+                ...programCompilerArgs,
+                ...(build.compilerVisibleSource === undefined ? [] : [
+                    `-ffile-prefix-map=${build.programPath}=${build.compilerVisibleSource}`,
+                    "-iquote", dirname(resolve(build.compilerVisibleSource)),
+                ]),
+                "-c", build.programPath ?? opts.cPath, "-o", object,
+            ]);
+            await runClang(buildArgs(runtimeInput, { programPath: object, outPath: build.outPath ?? opts.outPath }));
+            if (darwinDebugSymbols)
+                await createDarwinDebugSymbols(build.outPath ?? opts.outPath);
+        }
+        finally {
+            await rm(stage, { recursive: true, force: true });
+        }
+    };
     const runUncachedBuild = async () => {
         const privateVendorRoot = transientVendorRoot ?? join(tmpdir(), `scriptc-vendor-fallback-${process.pid}-${Math.random().toString(36).slice(2)}`);
         try {
             await materializeVendorPrerequisites(undefined, privateVendorRoot);
-            await runClang(buildArgs((p) => p));
+            await buildExecutable((p) => p);
         }
         finally {
             await rm(privateVendorRoot, { recursive: true, force: true }).catch(() => undefined);
@@ -3510,7 +3359,7 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
             if (compileMetadataStamp === null) {
                 const [runtimeInvocation, programInvocation] = await Promise.all([
                     effectiveCompilerInvocationFingerprint(driver, toolchainEnv, cflags),
-                    programSourceExtension === ".ll"
+                    programSourceExtension === ".ll" || separateSanitizedProgram
                         ? effectiveCompilerInvocationFingerprint(driver, toolchainEnv, programCompilerArgs, programSourceExtension)
                         : Promise.resolve(null),
                 ]);
@@ -3573,6 +3422,7 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
     let cacheCompleteArtifact = !cacheWarmOnly &&
         cachePolicy.completeArtifacts &&
         (opts.linkInputs?.length ?? 0) === 0 &&
+        (opts.frameworks?.length ?? 0) === 0 &&
         (opts.systemLibraries?.length ?? 0) === 0;
     let programDependencies = null;
     const linkProbeArgs = [
@@ -3593,7 +3443,7 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
     // compile/link flag shape: wrappers commonly inject flags or native inputs
     // conditionally on optimization, sanitizer, dynamic, or platform switches.
     const effectiveLinkInvocationArgs = [
-        ...programCompilerArgs,
+        ...(separateSanitizedProgram ? cflags : programCompilerArgs),
         ...(targetPlatform(driver) === "win32"
             ? ["-ladvapi32", "-liphlpapi", "-lws2_32"]
             : []),
@@ -3647,7 +3497,7 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
                     linkMetadataStamp = null;
             }
             [programDependencies, implicitLinker] = await Promise.all([
-                translationUnitDependencyFingerprint(driver, cflags, opts.cPath, cBytes, toolchainEnv),
+                translationUnitDependencyFingerprint(driver, programCompilerArgs, opts.cPath, cBytes, toolchainEnv),
                 linkMetadataStamp === null
                     ? implicitLinkerFingerprint(driver, toolchainEnv, linkProbeArgs, effectiveLinkInvocationArgs, linkTraceInvocationArgs)
                     : Promise.resolve(implicitLinker),
@@ -3712,7 +3562,7 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
     if (cacheWarmOnly && preBuildDependencies === null) {
         try {
             const [dependencies, invocation] = await Promise.all([
-                translationUnitDependencyFingerprint(driver, cflags, opts.cPath, cBytes, toolchainEnv),
+                translationUnitDependencyFingerprint(driver, programCompilerArgs, opts.cPath, cBytes, toolchainEnv),
                 effectiveCompilerInvocationFingerprint(driver, toolchainEnv, cflags),
             ]);
             programDependencies = dependencies;
@@ -3874,7 +3724,7 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
                 return null;
             try {
                 const programDependencyHash = programDependencies ??
-                    await translationUnitDependencyFingerprint(driver, cflags, opts.cPath, cBytes, toolchainEnv);
+                    await translationUnitDependencyFingerprint(driver, programCompilerArgs, opts.cPath, cBytes, toolchainEnv);
                 const stem = basename(opts.cPath, ".ll");
                 const entries = programShards.map((shard, index) => {
                     const sourcePath = join(buildDir, shard.name);
@@ -3930,7 +3780,7 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
                             runtimeFingerprint(rtDir),
                             implicitToolchainFingerprints(driver, toolchainEnv),
                             effectiveCompilerInvocationFingerprint(driver, toolchainEnv, programCompilerArgs, ".ll"),
-                            translationUnitDependencyFingerprint(driver, cflags, opts.cPath, cBytes, toolchainEnv),
+                            translationUnitDependencyFingerprint(driver, programCompilerArgs, opts.cPath, cBytes, toolchainEnv),
                             ccVersion(driver.argv, toolchainEnv, true),
                             resolveProgramShardMergeIdentity(driver),
                         ]);
@@ -3962,9 +3812,9 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
             // cache key describing a successful shard projection/merge.
             cacheInputsStable = false;
         }
-        await runClang(buildArgs((p) => objects?.get(p) ?? p, shardedProgramObject === null
+        await buildExecutable((p) => objects?.get(p) ?? p, shardedProgramObject === null
             ? { programPath, outPath: privateOut, compilerVisibleSource: opts.cPath }
-            : { programPath: shardedProgramObject, outPath: privateOut }));
+            : { programPath: shardedProgramObject, outPath: privateOut });
         if (darwinDebugSymbols) {
             // clang invokes dsymutil when compiling a source TU while linking.
             // A sharded program is already an object, so run it explicitly while
@@ -3985,7 +3835,7 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
                 implicitToolchainFingerprint(driver, toolchainEnv).catch(() => null),
                 effectiveCompilerInvocationFingerprint(driver, toolchainEnv, cflags).catch(() => null),
                 effectiveCompilerInvocationFingerprint(driver, toolchainEnv, programCompilerArgs, programSourceExtension).catch(() => null),
-                translationUnitDependencyFingerprint(driver, cflags, opts.cPath, cBytes, toolchainEnv).catch(() => null),
+                translationUnitDependencyFingerprint(driver, programCompilerArgs, opts.cPath, cBytes, toolchainEnv).catch(() => null),
                 implicitLinkerFingerprint(driver, toolchainEnv, linkProbeArgs, effectiveLinkInvocationArgs, linkTraceInvocationArgs).catch(() => null),
                 ccVersion(driver.argv, toolchainEnv, true).catch(() => null),
                 programShards === null