@scriptc/compiler 0.1.6 → 0.2.0

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";
@@ -11,6 +16,7 @@ import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { localizeElfObject, mergeAndLocalizeCoffObjects } from "./object-localize.js";
 import { executableOptimizationLinkerArgs, executableStripLinkerArgs, windowsSubsystemLinkerArgs } from "./targets.js";
+import { createDarwinDebugSymbols, installDarwinDebugSymbols, needsDarwinDebugSymbols, readDarwinDebugSymbols } from "./debug-symbols.js";
 import { createVendorArchives, MBEDTLS_VERSION, QJS_COMMIT, ZLIB_VERSION, } from "./vendor-archives.js";
 import { cacheDigestPath, cacheRootDir, copyValidCachedFile, ensurePrivateCacheRoot, fileDigest, fileExists, installArtifact, privateSiblingPath, protectCachedArtifact, pruneCache, publishCachedFile, validCachedFile, } from "./build-cache.js";
 export { buildCacheRoot, prepareBuildCacheRoot, pruneBuildCache, resolveBuildCacheRoot, } from "./build-cache.js";
@@ -45,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_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
@@ -82,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
@@ -298,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
@@ -543,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;
@@ -721,12 +560,12 @@ 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"] : []),
     ];
@@ -819,9 +658,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([
@@ -1097,7 +936,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`);
                 })();
@@ -1267,8 +1106,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");
@@ -1354,9 +1192,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
@@ -1385,7 +1223,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
@@ -2138,29 +1976,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/)) {
@@ -2680,7 +2495,7 @@ function localArtifactStampIntegrity(stamp) {
         .update(JSON.stringify(stamp))
         .digest("hex");
 }
-async function localArtifactHit(stampPath, outPath, key) {
+async function localArtifactHit(stampPath, outPath, key, darwinDebugSymbols = false) {
     try {
         const stamp = JSON.parse(await readFile(stampPath, "utf8"));
         const output = await lstat(outPath);
@@ -2688,6 +2503,8 @@ async function localArtifactHit(stampPath, outPath, key) {
         if (stamp.version !== 2 ||
             stamp.key !== key ||
             !/^[0-9a-f]{64}$/.test(stamp.digest ?? "") ||
+            (darwinDebugSymbols !== (stamp.debugSymbolsDigest !== undefined)) ||
+            (stamp.debugSymbolsDigest !== undefined && !/^[0-9a-f]{64}$/.test(stamp.debugSymbolsDigest)) ||
             !Array.isArray(stamp.dependencies) ||
             !/^[0-9a-f]{64}$/.test(stamp.integrity ?? "") ||
             localArtifactStampIntegrity({
@@ -2695,6 +2512,7 @@ async function localArtifactHit(stampPath, outPath, key) {
                 key: stamp.key,
                 digest: stamp.digest,
                 dependencies: stamp.dependencies,
+                ...(stamp.debugSymbolsDigest === undefined ? {} : { debugSymbolsDigest: stamp.debugSymbolsDigest }),
             }) !== stamp.integrity ||
             !output.isFile() ||
             (output.mode & 0o777) !== expectedMode ||
@@ -2718,7 +2536,8 @@ async function localArtifactHit(stampPath, outPath, key) {
                     typeof dependency.targetMtimeMs !== "number" ||
                     typeof dependency.targetCtimeMs !== "number")) ||
             !(await nativeArtifactDependenciesStillMatch(stamp.dependencies)) ||
-            await fileDigest(outPath) !== stamp.digest) {
+            await fileDigest(outPath) !== stamp.digest ||
+            darwinDebugSymbols && createHash("sha256").update(await readDarwinDebugSymbols(outPath)).digest("hex") !== stamp.debugSymbolsDigest) {
             return null;
         }
         const now = new Date();
@@ -2729,7 +2548,7 @@ async function localArtifactHit(stampPath, outPath, key) {
         return null;
     }
 }
-async function publishLocalArtifactStamp(stampPath, outPath, key, dependencyPaths, recursiveDirectories = [], recursiveExclusions = []) {
+async function publishLocalArtifactStamp(stampPath, outPath, key, dependencyPaths, recursiveDirectories = [], recursiveExclusions = [], darwinDebugSymbols = false) {
     await mkdir(dirname(stampPath), { recursive: true });
     const tmp = `${stampPath}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
     try {
@@ -2739,6 +2558,9 @@ async function publishLocalArtifactStamp(stampPath, outPath, key, dependencyPath
             key,
             digest: await fileDigest(outPath),
             dependencies,
+            ...(darwinDebugSymbols
+                ? { debugSymbolsDigest: createHash("sha256").update(await readDarwinDebugSymbols(outPath)).digest("hex") }
+                : {}),
         };
         const stamp = {
             ...unsigned,
@@ -2898,6 +2720,14 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
     const tls = (opts.tls ?? false) || nativeFetch || netIsland;
     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"])]
+        : [];
     const shardNames = new Set();
     const programShardsValid = opts.programShards?.every((shard) => {
         if (basename(shard.name) !== shard.name || !shard.name.endsWith(".ll") ||
@@ -2978,7 +2808,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.
@@ -3013,6 +2843,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 {
@@ -3032,7 +2863,7 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
                     programBytes,
                     compilerPath: effectiveCompiler.canonicalPath,
                 };
-                const hit = await localArtifactHit(stampPath, opts.outPath, key);
+                const hit = await localArtifactHit(stampPath, opts.outPath, key, darwinDebugSymbols);
                 if (hit !== null) {
                     await opts.onArtifactReady?.({ dependencies: hit.dependencies }).catch(() => undefined);
                     return;
@@ -3212,23 +3043,24 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
     // the historical single invocation, cached-.o substitution on cache misses.
     const buildArgs = (rt, build = {}) => [
         "-std=c11",
+        ...debugFlags,
         ...driver.targetArgs,
         ...threadArgs,
         ...(sanitize
-            ? ["-O1", "-fsanitize=address", "-DSCR_RC_AUDIT"]
+            ? [optimization === "dev" ? "-O0" : "-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",
@@ -3254,10 +3086,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.
@@ -3282,7 +3114,6 @@ 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"))] : []),
@@ -3386,6 +3217,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
@@ -3405,10 +3237,11 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
     // historical single clang invocation.
     const cflags = [
         "-std=c11",
+        ...debugFlags,
         ...driver.targetArgs,
         ...threadArgs,
         ...(sanitize
-            ? ["-O1", "-fsanitize=address", "-DSCR_RC_AUDIT"]
+            ? [optimization === "dev" ? "-O0" : "-O1", "-fsanitize=address", "-DSCR_RC_AUDIT"]
             : [optimization === "dev" ? "-O0" : "-O2"]),
         ...executableSectionFlags.compile,
         ...(opts.textDecoderLegacy ? ["-DSCR_TEXT_DECODER_LEGACY"] : []),
@@ -3434,11 +3267,11 @@ 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}`);
         }
@@ -3559,6 +3392,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 = [
@@ -3761,12 +3595,29 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
             if (!(await copyValidCachedFile(cachedBin, tmpOut))) {
                 throw new Error("invalid cached executable");
             }
+            if (darwinDebugSymbols) {
+                const cachedSymbols = `${cachedBin}.dsym`;
+                const symbolsCopy = privateSiblingPath(opts.outPath, "dsym-hit");
+                try {
+                    if (!(await copyValidCachedFile(cachedSymbols, symbolsCopy)))
+                        throw new Error("invalid cached dSYM");
+                    const bytes = await readFile(symbolsCopy);
+                    // A concurrent publisher may replace either payload. The sidecar
+                    // also names its binary digest so a mixed pair always misses.
+                    if (bytes.subarray(0, 32).toString("hex") !== await fileDigest(tmpOut))
+                        throw new Error("mismatched cached dSYM");
+                    await installDarwinDebugSymbols(bytes.subarray(32), opts.outPath);
+                }
+                finally {
+                    await rm(symbolsCopy, { force: true });
+                }
+            }
             // Match a fresh linker output under the caller's current umask. Reusing a
             // 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) {
-                const stamp = await publishLocalArtifactStamp(localArtifact.stampPath, opts.outPath, localArtifact.key, localArtifactDependencyPaths, [dirname(resolve(opts.cPath))], [persistentCache.root]).catch(() => null);
+                const stamp = await publishLocalArtifactStamp(localArtifact.stampPath, opts.outPath, localArtifact.key, localArtifactDependencyPaths, [dirname(resolve(opts.cPath))], [persistentCache.root], darwinDebugSymbols).catch(() => null);
                 if (stamp !== null) {
                     await opts.onArtifactReady?.({ dependencies: stamp.dependencies }).catch(() => undefined);
                 }
@@ -3934,6 +3785,14 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
         await runClang(buildArgs((p) => objects?.get(p) ?? p, shardedProgramObject === null
             ? { programPath, outPath: privateOut, compilerVisibleSource: opts.cPath }
             : { 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
+            // the merged object and staged runtime inputs still exist.
+            if (shardedProgramObject !== null)
+                await createDarwinDebugSymbols(privateOut);
+            await installDarwinDebugSymbols(await readDarwinDebugSymbols(privateOut), opts.outPath);
+        }
         await installArtifact(privateOut, opts.outPath);
         if (cachedBin !== null && keyHex !== null) {
             // Metadata comparison catches ordinary changes cheaply, but cannot by
@@ -3972,6 +3831,14 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
                 // generated code and embedded literals private; the hit path reapplies
                 // the caller's current executable mode to its destination copy.
                 await publishCachedFile(privateOut, cachedBin);
+                if (darwinDebugSymbols) {
+                    const symbols = privateSiblingPath(privateOut, "debug-symbols");
+                    await writeFile(symbols, Buffer.concat([
+                        Buffer.from(await fileDigest(privateOut), "hex"),
+                        await readDarwinDebugSymbols(privateOut),
+                    ]));
+                    await publishCachedFile(symbols, `${cachedBin}.dsym`);
+                }
             }
             catch {
                 /* publishing is best-effort */
@@ -3981,7 +3848,7 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
             localArtifactDependencyPaths !== null &&
             cacheCompleteArtifact &&
             cacheInputsStable) {
-            const stamp = await publishLocalArtifactStamp(localArtifact.stampPath, opts.outPath, localArtifact.key, localArtifactDependencyPaths, [dirname(resolve(opts.cPath))], [persistentCache.root]).catch(() => null);
+            const stamp = await publishLocalArtifactStamp(localArtifact.stampPath, opts.outPath, localArtifact.key, localArtifactDependencyPaths, [dirname(resolve(opts.cPath))], [persistentCache.root], darwinDebugSymbols).catch(() => null);
             if (stamp !== null) {
                 await opts.onArtifactReady?.({ dependencies: stamp.dependencies }).catch(() => undefined);
             }
@@ -3997,6 +3864,9 @@ async function compileCInternal(opts, cacheWarmOnly, cacheWarmPaths) {
 export async function compileC(opts) {
     clearCcCaches();
     await compileCInternal(opts, false);
+    if (targetPlatform(resolveCc()) === "darwin" && !needsDarwinDebugSymbols("darwin", opts.optimization, opts.strip)) {
+        await rm(`${opts.outPath}.dSYM`, { recursive: true, force: true });
+    }
 }
 export function supportedNativeCacheWarmProfiles(driver) {
     if (isMobileTarget(driver.target) || targetPlatform(driver) === "wasi")