@scriptc/compiler 0.0.32 → 0.0.33

package/dist/backend/llvm/emitter.js

@@ -61,9 +61,9 @@
  * lazy-inflate representation as the C debugging backend.
  */
 import { deflateRawSync } from "node:zlib";
-import { canMarshalFuncIntoIsland, CAUGHT, DYN, F64, ffiCallbackType, islandCallbackRet, islandPromisePayloadTag, isFfiCallbackParam, isFfiContextParam, isRefCounted, isUnitType, MAY_THROW_LIB_FNS, moduleEmbedsBuiltin, moduleEmbedsCompressedNpm, moduleUsesDynInvoke, moduleUsesFetch, moduleUsesFsWatch, moduleUsesHttpServer, moduleUsesNet, moduleUsesNodeTest, moduleUsesProcessEvents, moduleUsesStream, moduleUsesTls, moduleUsesTlsCa, NPM_COMPRESS_MIN, RUNTIME_EMITTER_CLASS, RUNTIME_ERROR_CLASSES, RUNTIME_STREAM_CLASSES, STRING, typeEquals, typeKey, VOID } from "../../ir/nodes.js";
+import { canMarshalFuncIntoIsland, CAUGHT, DYN, F64, ffiCallbackType, islandCallbackRet, islandPromisePayloadTag, isFfiCallbackParam, isFfiContextParam, isFfiReleaseParam, isRefCounted, isUnitType, MAY_THROW_LIB_FNS, moduleEmbedsBuiltin, moduleEmbedsCompressedNpm, moduleUsesDynInvoke, moduleUsesFetch, moduleUsesFsWatch, moduleUsesHttpServer, moduleUsesNet, moduleUsesNodeTest, moduleUsesProcessEvents, moduleUsesStream, moduleUsesTls, moduleUsesTlsCa, NPM_COMPRESS_MIN, RUNTIME_EMITTER_CLASS, RUNTIME_ERROR_CLASSES, RUNTIME_STREAM_CLASSES, STRING, typeEquals, typeKey, VOID } from "../../ir/nodes.js";
 import { matchIntegerBytesForLoop } from "../../ir/integer-loops.js";
-import { allocateFfiCallbackAdapters } from "../ffi-callbacks.js";
+import { allocateFfiCallbackAdapters, collectFfiRetainedOps, hasForeignFfiCallback, hasRetainedFfiCallback, parseFfiCallbackKey } from "../ffi-callbacks.js";
 import { computeMayThrow } from "../emission/may-throw.js";
 import { mangleArgPack, mangleAsyncSpawn, mangleClassNew, mangleClassObj, mangleClassRetain, mangleFnClosure, mangleFunction, mangleGenDrop, mangleGenResThunk, mangleGenSpawn, mangleGlobal, mangleLocal, mangleRecordNew, mangleRecordStruct, mangleResolveThunk, mangleTrampoline, mangleVtStruct, mangleWrapper } from "../mangle.js";
 import { BlockBuilder } from "./blocks.js";
@@ -81,6 +81,8 @@ function ffiNativeTypeLl(cls) {
         case "u32":
         case "i32":
             return "i32";
+        case "cstring":
+            return "ptr";
         case "string":
         case "bytes":
             throw new Error(`llvm emitter bug: span class '${cls}' has no scalar LLVM type`);
@@ -917,6 +919,12 @@ class LlEmitter {
     /** C-ABI callback trampolines and (for raw/no-userdata callbacks) their
      * distinct call-scoped TLS closure slots. */
     ffiCallbackAdapters;
+    /** Module-level constant consulted per ffiCall: with a retained
+     * descriptor anywhere in the manifest, every native call is a
+     * pending-exception checkpoint (may-throw derives the same fact from
+     * the same helper). */
+    ffiHasRetainedCallback;
+    ffiHasForeignCallback;
     globalTypes = new Map();
     /** May-throw analysis (the C emitter's computeMayThrow, shared): pending
      * checks are emitted only after calls that can actually raise. */
@@ -1019,6 +1027,8 @@ class LlEmitter {
         // bytes behind a wasm32 object and 16 bytes behind a 64-bit object.
         this.cycleColorOffset = options.pointerBits === 32 ? 12 : 16;
         this.ffiCallbackAdapters = allocateFfiCallbackAdapters(mod.ffiImports ?? []);
+        this.ffiHasRetainedCallback = hasRetainedFfiCallback(mod.ffiImports ?? []);
+        this.ffiHasForeignCallback = hasForeignFfiCallback(mod.ffiImports ?? []);
         for (const fn of mod.functions)
             this.fnByName.set(fn.name, fn);
         for (const entry of mod.ffiImports ?? []) {
@@ -1172,13 +1182,129 @@ class LlEmitter {
         this.declare(`declare zeroext i1 @scr_exc_pending()`);
         this.declare(`declare void @scr_trap(ptr)`);
         const expired = this.cstr("scriptc: native callback invoked outside its call-scoped lifetime\n");
+        const released = this.cstr("scriptc: native callback invoked outside its retained lifetime\n");
         for (const adapter of this.ffiCallbackAdapters.values()) {
             const cb = adapter.callback;
             if (adapter.tls !== null)
                 globals.push(`@${adapter.tls} = internal thread_local global ptr null`);
-            const params = cb.params.map((param, i) => isFfiContextParam(param) ? `ptr %ctx` : `${ffiNativeTypeLl(param)} %a${i}`);
+            if (adapter.global !== null)
+                globals.push(`@${adapter.global} = internal global ptr null`);
+            if (adapter.table !== null) {
+                globals.push(`@${adapter.table} = internal global %ScrFfiTable zeroinitializer`);
+            }
+            const params = cb.params.flatMap((param, i) => {
+                if (isFfiContextParam(param))
+                    return [`ptr %ctx`];
+                if (param === "string" || param === "bytes") {
+                    return [`ptr %a${i}`, `${this.sizeType} %a${i}_len`];
+                }
+                return [`${ffiNativeTypeLl(param)} %a${i}`];
+            });
             const ret = ffiNativeTypeLl(cb.returns);
-            defs.push(`define internal ${ret} @${adapter.symbol}(${params.join(", ")}) ${FN_ATTRS} {`, `entry:`, adapter.tls === null ? `  %cb = getelementptr inbounds i8, ptr %ctx, i64 0` : `  %cb = load ptr, ptr @${adapter.tls}`, `  %missing = icmp eq ptr %cb, null`, `  br i1 %missing, label %expired, label %ready`, `expired:`, `  call void @scr_trap(ptr ${expired})`, `  unreachable`, `ready:`, `  %pending = call zeroext i1 @scr_exc_pending()`, `  br i1 %pending, label %skip, label %invoke`, `skip:`, `  ret ${ffiCallbackDummyLl(cb)}`, `invoke:`, `  %fnp = getelementptr inbounds %ScrClosure, ptr %cb, i64 0, i32 1`, `  %fn = load ptr, ptr %fnp`);
+            if (cb.invoke === "foreign") {
+                if (adapter.table === null || !cb.params.some(isFfiContextParam) || cb.returns !== "void") {
+                    throw new Error("llvm emitter bug: invalid foreign FFI callback descriptor");
+                }
+                const dispatch = `${adapter.symbol}_dispatch`;
+                const scriptArgs = [];
+                const dispatchBody = [
+                    `define internal void @${dispatch}(ptr %cb, ptr %call) ${FN_ATTRS} {`,
+                    `entry:`,
+                    `  %fnp = getelementptr inbounds %ScrClosure, ptr %cb, i64 0, i32 1`,
+                    `  %fn = load ptr, ptr %fnp`,
+                ];
+                for (let i = 0; i < cb.params.length; i++) {
+                    const param = cb.params[i];
+                    if (isFfiContextParam(param))
+                        continue;
+                    switch (param) {
+                        case "f64":
+                            this.declare(`declare double @scr_ffi_call_get_f64(ptr, ${this.sizeType})`);
+                            dispatchBody.push(`  %s${i} = call double @scr_ffi_call_get_f64(ptr %call, ${this.sizeType} ${i})`);
+                            scriptArgs.push(`double %s${i}`);
+                            break;
+                        case "bool":
+                            this.declare(`declare zeroext i1 @scr_ffi_call_get_bool(ptr, ${this.sizeType})`);
+                            dispatchBody.push(`  %s${i} = call zeroext i1 @scr_ffi_call_get_bool(ptr %call, ${this.sizeType} ${i})`);
+                            scriptArgs.push(`i1 %s${i}`);
+                            break;
+                        case "u8":
+                        case "u32":
+                        case "i32":
+                            this.declare(`declare double @scr_ffi_call_get_${param}(ptr, ${this.sizeType})`);
+                            dispatchBody.push(`  %s${i} = call double @scr_ffi_call_get_${param}(ptr %call, ${this.sizeType} ${i})`);
+                            scriptArgs.push(`double %s${i}`);
+                            break;
+                        case "cstring":
+                        case "string":
+                        case "bytes": {
+                            this.declare(`declare ptr @scr_ffi_call_get_data(ptr, ${this.sizeType})`);
+                            this.declare(`declare ${this.sizeType} @scr_ffi_call_get_len(ptr, ${this.sizeType})`);
+                            dispatchBody.push(`  %data${i} = call ptr @scr_ffi_call_get_data(ptr %call, ${this.sizeType} ${i})`, `  %len${i} = call ${this.sizeType} @scr_ffi_call_get_len(ptr %call, ${this.sizeType} ${i})`);
+                            if (param === "bytes") {
+                                this.declare(`declare ptr @scr_bytes_from_data(ptr, ${this.sizeType})`);
+                                dispatchBody.push(`  %s${i} = call ptr @scr_bytes_from_data(ptr %data${i}, ${this.sizeType} %len${i})`);
+                            }
+                            else {
+                                this.declare(`declare ptr @scr_str_from_utf8_lossy(ptr, ${this.sizeType})`);
+                                dispatchBody.push(`  %s${i} = call ptr @scr_str_from_utf8_lossy(ptr %data${i}, ${this.sizeType} %len${i})`);
+                            }
+                            scriptArgs.push(`ptr %s${i}`);
+                            break;
+                        }
+                    }
+                }
+                dispatchBody.push(`  call void %fn(${[`ptr %cb`, ...scriptArgs].join(", ")})`, `  ret void`, `}`, ``);
+                defs.push(...dispatchBody);
+                this.declare(`declare ptr @scr_ffi_call_new(ptr, ptr, ptr, ${this.sizeType})`);
+                this.declare(`declare void @scr_ffi_post(ptr)`);
+                defs.push(`define internal void @${adapter.symbol}(${params.join(", ")}) ${FN_ATTRS} {`, `entry:`, `  %cb = getelementptr inbounds i8, ptr %ctx, i64 0`, `  %call = call ptr @scr_ffi_call_new(ptr @${adapter.table}, ptr %cb, ptr @${dispatch}, ${this.sizeType} ${cb.params.length})`);
+                for (let i = 0; i < cb.params.length; i++) {
+                    const param = cb.params[i];
+                    if (isFfiContextParam(param))
+                        continue;
+                    if (param === "cstring") {
+                        this.declare(`declare void @scr_ffi_call_copy_cstring(ptr, ${this.sizeType}, ptr)`);
+                        defs.push(`  call void @scr_ffi_call_copy_cstring(ptr %call, ${this.sizeType} ${i}, ptr %a${i})`);
+                    }
+                    else if (param === "string" || param === "bytes") {
+                        this.declare(`declare void @scr_ffi_call_copy_${param}(ptr, ${this.sizeType}, ptr, ${this.sizeType})`);
+                        defs.push(`  call void @scr_ffi_call_copy_${param}(ptr %call, ${this.sizeType} ${i}, ptr %a${i}, ${this.sizeType} %a${i}_len)`);
+                    }
+                    else {
+                        const nativeTy = ffiNativeTypeLl(param);
+                        this.declare(`declare void @scr_ffi_call_set_${param}(ptr, ${this.sizeType}, ${nativeTy})`);
+                        defs.push(`  call void @scr_ffi_call_set_${param}(ptr %call, ${this.sizeType} ${i}, ${nativeTy} %a${i})`);
+                    }
+                }
+                defs.push(`  call void @scr_ffi_post(ptr %call)`, `  ret void`, `}`, ``);
+                continue;
+            }
+            defs.push(`define internal ${ret} @${adapter.symbol}(${params.join(", ")}) ${FN_ATTRS} {`, `entry:`, adapter.tls !== null
+                ? `  %cb = load ptr, ptr @${adapter.tls}`
+                : adapter.global !== null
+                    ? `  %cb = load ptr, ptr @${adapter.global}`
+                    : `  %cb = getelementptr inbounds i8, ptr %ctx, i64 0`, `  %missing = icmp eq ptr %cb, null`, `  br i1 %missing, label %expired, label %ready`, `expired:`, `  call void @scr_trap(ptr ${adapter.callback.lifetime === "call" ? expired : released})`, `  unreachable`, `ready:`, `  %pending = call zeroext i1 @scr_exc_pending()`, `  br i1 %pending, label %skip, label %invoke`, `skip:`, `  ret ${ffiCallbackDummyLl(cb)}`, `invoke:`);
+            // Validate every native pointer before allocating any copy-in value.
+            // A later bad slot therefore cannot leak an earlier materialization.
+            for (let i = 0; i < cb.params.length; i++) {
+                const param = cb.params[i];
+                if (param !== "cstring" && param !== "string" && param !== "bytes")
+                    continue;
+                const invalid = `%invalid${i}`;
+                defs.push(`  %null${i} = icmp eq ptr %a${i}, null`);
+                if (param === "cstring") {
+                    defs.push(`  ${invalid} = or i1 %null${i}, false`);
+                }
+                else {
+                    defs.push(`  %nonempty${i} = icmp ne ${this.sizeType} %a${i}_len, 0`, `  ${invalid} = and i1 %null${i}, %nonempty${i}`);
+                }
+                const message = param === "cstring"
+                    ? "scriptc: native callback passed a NULL cstring\n"
+                    : `scriptc: native callback passed a NULL ${param} span with nonzero length\n`;
+                defs.push(`  br i1 ${invalid}, label %invalid_param${i}, label %param_ok${i}`, `invalid_param${i}:`, `  call void @scr_trap(ptr ${this.cstr(message)})`, `  unreachable`, `param_ok${i}:`);
+            }
+            defs.push(`  %fnp = getelementptr inbounds %ScrClosure, ptr %cb, i64 0, i32 1`, `  %fn = load ptr, ptr %fnp`);
             const scriptArgs = [];
             for (let i = 0; i < cb.params.length; i++) {
                 const param = cb.params[i];
@@ -1204,16 +1330,40 @@ class LlEmitter {
                         defs.push(`  %s${i} = sitofp i32 %a${i} to double`);
                         scriptArgs.push(`double %s${i}`);
                         break;
+                    case "cstring":
+                        this.declare(`declare ${this.sizeType} @strlen(ptr)`);
+                        this.declare(`declare ptr @scr_str_from_utf8_lossy(ptr, ${this.sizeType})`);
+                        defs.push(`  %len${i} = call ${this.sizeType} @strlen(ptr %a${i})`, `  %s${i} = call ptr @scr_str_from_utf8_lossy(ptr %a${i}, ${this.sizeType} %len${i})`);
+                        scriptArgs.push(`ptr %s${i}`);
+                        break;
+                    case "string":
+                        this.declare(`declare ptr @scr_str_from_utf8_lossy(ptr, ${this.sizeType})`);
+                        defs.push(`  %s${i} = call ptr @scr_str_from_utf8_lossy(ptr %a${i}, ${this.sizeType} %a${i}_len)`);
+                        scriptArgs.push(`ptr %s${i}`);
+                        break;
+                    case "bytes":
+                        this.declare(`declare ptr @scr_bytes_from_data(ptr, ${this.sizeType})`);
+                        defs.push(`  %s${i} = call ptr @scr_bytes_from_data(ptr %a${i}, ${this.sizeType} %a${i}_len)`);
+                        scriptArgs.push(`ptr %s${i}`);
+                        break;
                 }
             }
             const ft = ffiCallbackType(cb);
             const internalRet = this.llType(ft.ret);
             const callArgs = [`ptr %cb`, ...scriptArgs].join(", ");
+            if (cb.lifetime === "retained") {
+                this.declare(`declare ptr @scr_closure_retain_v(ptr)`);
+                this.declare(`declare void @scr_closure_release_v(ptr)`);
+                defs.push(`  %invoke_pin = call ptr @scr_closure_retain_v(ptr %cb)`);
+            }
             if (cb.returns === "void") {
-                defs.push(`  call void %fn(${callArgs})`, `  ret void`, `}`, ``);
+                defs.push(`  call void %fn(${callArgs})`, ...(cb.lifetime === "retained" ? [`  call void @scr_closure_release_v(ptr %invoke_pin)`] : []), `  ret void`, `}`, ``);
                 continue;
             }
             defs.push(`  %result = call ${internalRet} %fn(${callArgs})`);
+            if (cb.lifetime === "retained") {
+                defs.push(`  call void @scr_closure_release_v(ptr %invoke_pin)`);
+            }
             switch (cb.returns) {
                 case "f64":
                     defs.push(`  ret double %result`);
@@ -1337,7 +1487,6 @@ class LlEmitter {
         const snapshotsTlsCa = moduleUsesTls(this.mod) || moduleUsesTlsCa(this.mod) ||
             moduleEmbedsBuiltin(this.mod, "node:https") ||
             moduleEmbedsBuiltin(this.mod, "node:tls");
-        const hasRefGlobals = globals.some((g) => isRefCounted(g.type)) || fnValueProps.length > 0;
         // The process verdict has the same precedence as the C reference
         // emitter: node:test owns the final status when present; otherwise an
         // embedded process.exitCode owns it; ordinary programs return zero.
@@ -1348,6 +1497,8 @@ class LlEmitter {
             this.declare(`declare void @scr_events_install()`);
         if (usesFsWatch)
             this.declare(`declare void @scr_watch_install()`);
+        if (this.ffiHasForeignCallback)
+            this.declare(`declare void @scr_ffi_install()`);
         if (usesStream)
             this.declare(`declare void @scr_stream_install()`);
         if (usesNet) {
@@ -1375,12 +1526,21 @@ class LlEmitter {
         if (snapshotsTlsCa) {
             this.declare(`declare void @scr_tls_ca_install()`);
         }
-        if (usesEvents && hasRefGlobals) {
+        // Inline exit listeners run when something they must beat exists:
+        // the refcounted-global releases, or the retained-FFI atexit ledger
+        // sweep (a listener may legitimately release or pump a registration,
+        // and only the inline call orders ahead of every atexit handler —
+        // the C emitter's runExitListeners stance). Plain event programs
+        // with neither keep the atexit path, so their listener timing is
+        // unchanged.
+        const hasRefGlobals = globals.some((g) => isRefCounted(g.type)) || fnValueProps.length > 0;
+        const inlineExitListeners = usesEvents && (hasRefGlobals || this.ffiHasRetainedCallback);
+        if (inlineExitListeners) {
             this.declare(`declare void @scr_run_exit_listeners(double)`);
             this.declare(`declare i32 @scr_exit_code_hint_get()`);
         }
         const exitListenerLines = (prefix) => {
-            if (!usesEvents || !hasRefGlobals)
+            if (!inlineExitListeners)
                 return [];
             return [
                 `  %${prefix}h = call i32 @scr_exit_code_hint_get()`,
@@ -1399,6 +1559,7 @@ class LlEmitter {
         // async loop-exhaustion story.
         const runsLoop = this.usesTimers ||
             usesIsland ||
+            this.ffiHasForeignCallback ||
             this.mod.functions.some((f) => f.async === true || f.generator !== undefined);
         const uncaughtReleases = entryMayThrow && !asyncEntry ? globalReleaseLines("gu") : [];
         const loopReleasesU = runsLoop ? globalReleaseLines("gl") : [];
@@ -1421,7 +1582,7 @@ class LlEmitter {
             this.declare(`declare void @scr_promise_rethrow_top_level(ptr)`);
             this.declare(`declare void @scr_promise_release(ptr)`);
             this.declare(`declare void @scr_exit_code_note(i32)`);
-            if (programExitUsesIsland && usesEvents && hasRefGlobals) {
+            if (programExitUsesIsland && inlineExitListeners) {
                 this.declare(`declare ${this.sizeType} @scr_island_exit_code_version()`);
             }
         }
@@ -1439,7 +1600,7 @@ class LlEmitter {
                 lines.push(`  %tla_program_exit_zero = icmp eq i32 %tla_program_exit, 0`, `  %tla_exit_status = select i1 %tla_program_exit_zero, i32 %tla_status, i32 %tla_program_exit`);
             }
             const exitStatus = usesNodeTest || usesIsland ? "%tla_exit_status" : "%tla_status";
-            const tracksIslandExit = programExitUsesIsland && usesEvents && hasRefGlobals;
+            const tracksIslandExit = programExitUsesIsland && inlineExitListeners;
             if (tracksIslandExit) {
                 lines.push(`  %tla_exit_version = call ${this.sizeType} @scr_island_exit_code_version()`);
             }
@@ -1508,6 +1669,7 @@ class LlEmitter {
             `%ScrVt = type { ${this.sizeType}, ${this.sizeType}, ptr }`,
             `%ScrUnion = type { ${this.sizeType}, i32, ptr, ptr, ptr, i64 }`,
             `%ScrClosure = type { ${this.sizeType}, ptr, ${this.sizeType}, ptr }`,
+            `%ScrFfiTable = type { ptr, ${this.sizeType}, ${this.sizeType}, ptr, i8, ptr, ptr, ${this.sizeType}, ${this.sizeType}, ${this.sizeType}, ptr, ptr }`,
             `%ScrRegex = type { ${this.sizeType}, ptr, ptr, ptr }`,
             // ScrArr mirror { rc, len, cap, elem(i32+pad), elem_retain,
             // elem_release, elem_trace, data } — the immortal tagged-template
@@ -1718,7 +1880,7 @@ class LlEmitter {
         ...(usesEvents ? [`  call void @scr_events_install()`] : []), 
         // fs.watch programs fill the loop's watch hooks the same way —
         // scr_watch.c links only when this line is emitted.
-        ...(usesFsWatch ? [`  call void @scr_watch_install()`] : []), ...(snapshotsTlsCa ? [`  call void @scr_tls_ca_install()`] : []), ...(usesFetch ? [`  call void @scr_fetch_install()`] : []), ...(embedsZlib ? [`  call void @scr_zlib_island_install()`] : []), ...(embedsNet ? [`  call void @scr_net_island_install()`] : []), ...(usesNet ? [`  call void @scr_net_install()`, `  call void @scr_net_dyn_install()`] : []), ...(usesHttp ? [`  call void @scr_http_dyn_install()`] : []), ...(usesStream ? [`  call void @scr_stream_install()`] : []), `  call void @scr_lib_init(i32 %argc, ptr %argv)`, ...(usesIsland
+        ...(usesFsWatch ? [`  call void @scr_watch_install()`] : []), ...(this.ffiHasForeignCallback ? [`  call void @scr_ffi_install()`] : []), ...(snapshotsTlsCa ? [`  call void @scr_tls_ca_install()`] : []), ...(usesFetch ? [`  call void @scr_fetch_install()`] : []), ...(embedsZlib ? [`  call void @scr_zlib_island_install()`] : []), ...(embedsNet ? [`  call void @scr_net_island_install()`] : []), ...(usesNet ? [`  call void @scr_net_install()`, `  call void @scr_net_dyn_install()`] : []), ...(usesHttp ? [`  call void @scr_http_dyn_install()`] : []), ...(usesStream ? [`  call void @scr_stream_install()`] : []), `  call void @scr_lib_init(i32 %argc, ptr %argv)`, ...(usesIsland
             ? [
                 ...(moduleEmbedsCompressedNpm(this.mod)
                     ? [`  call void @scr_island_set_inflate(ptr @scr_zlib_inflate_exact)`]
@@ -5605,7 +5767,48 @@ class LlEmitter {
                     sourceArgs.set(abiIndex, arg);
                     if (isFfiCallbackParam(param))
                         callbackArgs.set(param.callback.id, arg);
+                    if (isFfiReleaseParam(param))
+                        callbackArgs.set(param.callback.release, arg);
                 });
+                const { registrations: retainedRegistrations, releases: retainedReleases } = collectFfiRetainedOps(entry, callbackArgs, (binding, id) => this.ffiCallbackAdapter(binding, id));
+                if (retainedRegistrations.length > 0) {
+                    this.declare(`declare void @scr_ffi_retain(ptr, ptr)`);
+                    if (retainedRegistrations.some((registration) => registration.global !== null)) {
+                        this.declare(`declare void @scr_ffi_retain_slot(ptr, ptr, ptr)`);
+                        this.declare(`declare void @scr_ffi_commit_slot(ptr, ptr)`);
+                    }
+                }
+                if (retainedReleases.length > 0) {
+                    this.declare(`declare void @scr_ffi_require(ptr, ptr)`);
+                    if (retainedReleases.some((release) => release.foreign)) {
+                        this.declare(`declare void @scr_ffi_require_foreign(ptr, ptr)`);
+                    }
+                }
+                // Pin before registration. Raw retained descriptors are native
+                // singletons: the incoming closure is pinned (and an EMPTY slot
+                // armed) before the native set call, but a replaced registration
+                // stays live and dispatching until the call returns — a native
+                // setter may flush the outgoing callback one last time mid-replace.
+                // scr_ffi_commit_slot below repoints the slot and retires the
+                // superseded pins after the call.
+                for (const registration of retainedRegistrations) {
+                    if (registration.global !== null) {
+                        B.line(`call void @scr_ffi_retain_slot(ptr @${registration.table}, ptr @${registration.global}, ptr ${registration.callback.name})`);
+                    }
+                    else if (registration.foreign) {
+                        this.declare(`declare void @scr_ffi_retain_foreign(ptr, ptr)`);
+                        B.line(`call void @scr_ffi_retain_foreign(ptr @${registration.table}, ptr ${registration.callback.name})`);
+                    }
+                    else {
+                        B.line(`call void @scr_ffi_retain(ptr @${registration.table}, ptr ${registration.callback.name})`);
+                    }
+                }
+                // Validate releases BEFORE the native removal call runs: a bogus
+                // release traps without native code observing any side effect. The
+                // registration itself is unpinned only after the call returns.
+                for (const release of retainedReleases) {
+                    B.line(`call void @scr_ffi_require${release.foreign ? "_foreign" : ""}(ptr @${release.table}, ptr ${release.callback.name})`);
+                }
                 const rawContexts = [];
                 for (const param of entry.params) {
                     if (!isFfiCallbackParam(param))
@@ -5628,6 +5831,13 @@ class LlEmitter {
                         nativeArgs.push(`ptr @${adapter.symbol}`);
                         return;
                     }
+                    if (isFfiReleaseParam(param)) {
+                        const { binding, id } = parseFfiCallbackKey(param.callback.release);
+                        const adapter = this.ffiCallbackAdapter(binding, id);
+                        nativeParamTypes.push("ptr");
+                        nativeArgs.push(`ptr @${adapter.symbol}`);
+                        return;
+                    }
                     if (isFfiContextParam(param)) {
                         const callback = callbackArgs.get(param.context);
                         if (!callback)
@@ -5713,10 +5923,30 @@ class LlEmitter {
                         B.line(`store ptr ${saved.previous}, ptr @${saved.tls}`);
                     }
                 };
-                const callbacksMayThrow = callbackArgs.size > 0;
+                const finishRetainedReleases = () => {
+                    // Commit raw replacements first (repoint the slot, retire the
+                    // superseded pins), then unpin explicit releases — the runtime
+                    // disarms the slot itself when the released closure holds it.
+                    for (const registration of retainedRegistrations) {
+                        if (registration.global !== null) {
+                            B.line(`call void @scr_ffi_commit_slot(ptr @${registration.table}, ptr ${registration.callback.name})`);
+                        }
+                    }
+                    if (retainedReleases.some((release) => !release.foreign)) {
+                        this.declare(`declare void @scr_ffi_release(ptr, ptr)`);
+                    }
+                    if (retainedReleases.some((release) => release.foreign)) {
+                        this.declare(`declare void @scr_ffi_release_foreign(ptr, ptr)`);
+                    }
+                    for (const release of retainedReleases) {
+                        B.line(`call void @scr_ffi_release${release.foreign ? "_foreign" : ""}(ptr @${release.table}, ptr ${release.callback.name})`);
+                    }
+                };
+                const callbacksMayThrow = callbackArgs.size > 0 || this.ffiHasRetainedCallback;
                 if (entry.returns === "void") {
                     B.line(call);
                     restoreRawContexts();
+                    finishRetainedReleases();
                     if (callbacksMayThrow)
                         this.emitPendingCheck();
                     return { name: "", type: e.type };
@@ -5724,6 +5954,7 @@ class LlEmitter {
                 const raw = B.tmp();
                 B.line(`${raw} = ${call}`);
                 restoreRawContexts();
+                finishRetainedReleases();
                 if (entry.returns === "f64") {
                     const result = { name: raw, type: e.type };
                     if (callbacksMayThrow)