@scriptc/runtime 0.0.32 → 0.0.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scriptc/runtime",
-  "version": "0.0.32",
+  "version": "0.0.33",
   "description": "scriptc native runtime — C sources, compiled into every scriptc binary",
   "license": "Apache-2.0",
   "homepage": "https://scriptc.dev",

package/src/scr_async.c

@@ -2198,6 +2198,22 @@ void scr_loop_set_watch(bool (*pending)(void), void (*dispatch)(void), int (*pol
   scr_watch_pollfd_fn = pollfd;
 }
 
+/* The foreign-FFI queue hook (scr_ffi.c when a format-5 descriptor exists).
+ * Its pending count includes live registrations (reffed by default) and
+ * queued deliveries; dispatch runs exactly one callback per loop turn. */
+static bool (*scr_ffi_pending_fn)(void) = NULL;
+static bool (*scr_ffi_dispatch_fn)(void) = NULL;
+static int (*scr_ffi_pollfd_fn)(void) = NULL;
+static void (*scr_ffi_stop_fn)(void) = NULL;
+
+void scr_loop_set_ffi(bool (*pending)(void), bool (*dispatch)(void),
+                      int (*pollfd)(void), void (*stop)(void)) {
+  scr_ffi_pending_fn = pending;
+  scr_ffi_dispatch_fn = dispatch;
+  scr_ffi_pollfd_fn = pollfd;
+  scr_ffi_stop_fn = stop;
+}
+
 /* The stream hook (scr_stream.c, when linked): `pending` keeps the loop
  * alive while deferred stream ticks exist, `dispatch` drains them at the
  * TOP of every turn — before the events/net stations, the closest
@@ -2295,6 +2311,12 @@ bool scr_loop_run(ScrPromise *top_level) {
       if (scr_exc_pending()) return false;
       if (dispatched) continue;
     }
+    /* Foreign native callbacks are macrotasks. Deliver one, then restart at
+     * the microtask checkpoint before considering the next queued post. */
+    if (scr_ffi_dispatch_fn != NULL && scr_ffi_dispatch_fn()) {
+      if (scr_exc_pending()) return false;
+      if (scr_ready_len > 0 || scr_nt_head != NULL || scr_nunhandled > 0) continue;
+    }
     /* Stream tick dispatch (scr_stream.c, when linked): the deferred
      * next-tick emissions ('data' flow kicks, 'readable'/'end'/'finish'/
      * 'drain'/'error'/'close') fire now, FIRST — the nextTick station.
@@ -2363,6 +2385,7 @@ bool scr_loop_run(ScrPromise *top_level) {
           (scr_net_pending_fn != NULL && scr_net_pending_fn()) ||
           (scr_dgram_pending_fn != NULL && scr_dgram_pending_fn()) ||
           (scr_watch_pending_fn != NULL && scr_watch_pending_fn()) ||
+          (scr_ffi_pending_fn != NULL && scr_ffi_pending_fn()) ||
           scr_fs_renames_pending();
       if (held) {
         scr_children_poll();
@@ -2382,6 +2405,7 @@ bool scr_loop_run(ScrPromise *top_level) {
     bool net = scr_net_pending_fn != NULL && scr_net_pending_fn();
     bool dgram = scr_dgram_pending_fn != NULL && scr_dgram_pending_fn();
     bool watch = scr_watch_pending_fn != NULL && scr_watch_pending_fn();
+    bool ffi = scr_ffi_pending_fn != NULL && scr_ffi_pending_fn();
     bool renames = scr_fs_renames_pending();
     /* Timer liveness counts only REF'd timers: an unref'd timer stays in
      * the heap (and fires if the loop runs on for other reasons) but does
@@ -2389,7 +2413,7 @@ bool scr_loop_run(ScrPromise *top_level) {
      * Children follow the same rule: an unref'd child is still REAPED
      * while the loop runs (kids drives the sweeps and sleeps above) but
      * only reffed ones keep the process alive. */
-    if (scr_reffed_timers == 0 && scr_reffed_immediates == 0 && !scr_children_reffed_pending() && !io && !events && !net && !dgram && !watch && !renames) break;
+    if (scr_reffed_timers == 0 && scr_reffed_immediates == 0 && !scr_children_reffed_pending() && !io && !events && !net && !dgram && !watch && !ffi && !renames) break;
     /* Sleep to the earliest deadline, then run every due timer (each may
      * enqueue microtasks, which the next iteration drains first). Who
      * sleeps depends on what is pending:
@@ -2430,11 +2454,11 @@ bool scr_loop_run(ScrPromise *top_level) {
        * on EINTR), so they re-impose a coarser cap — bounded Ctrl-C and
        * socket latency during a fetch, without the reap-granularity
        * cost. */
-      else if ((evw || net || dgram || watch) && due > now + SCR_SIGNAL_POLL_MS) due = now + SCR_SIGNAL_POLL_MS;
+      else if ((evw || net || dgram || watch || ffi) && due > now + SCR_SIGNAL_POLL_MS) due = now + SCR_SIGNAL_POLL_MS;
       scr_io_poll_fn(due > now ? due - now : 0);
       now = scr_now_ms();
       if (scr_ready_len > 0) continue; /* io callbacks woke fibers */
-    } else if (evw || net || dgram || watch) {
+    } else if (evw || net || dgram || watch || ffi) {
 #if defined(_WIN32) || defined(__wasi__)
       /* The win32 arm, and WASI hosts whose poll_oneoff adapters do not
        * reliably wake for a closed inherited stdin pipe: the sleep is a capped nanosleep and
@@ -2449,6 +2473,7 @@ bool scr_loop_run(ScrPromise *top_level) {
        * WaitForMultipleObjects over WSAEVENTs, or IOCP. */
       if (evw && due > now + SCR_SIGNAL_POLL_MS) due = now + SCR_SIGNAL_POLL_MS;
       if ((net || dgram || watch) && due > now + SCR_CHILD_POLL_MS) due = now + SCR_CHILD_POLL_MS;
+      if (ffi && due > now + SCR_CHILD_POLL_MS) due = now + SCR_CHILD_POLL_MS;
       if (kids && due > now + SCR_CHILD_POLL_MS) due = now + SCR_CHILD_POLL_MS;
       if (due > now) {
         double wait = due - now;
@@ -2465,7 +2490,7 @@ bool scr_loop_run(ScrPromise *top_level) {
        * events are pending); unrepresentable children keep the ~1ms reap cap
        * instead. Dispatch happens at the next turn's top — the poll only
        * decides how long to sleep. */
-      struct pollfd fds[6];
+      struct pollfd fds[7];
       int nfds = 0;
       int evfds[2];
       int nev = evw && scr_events_pollfds_fn != NULL ? scr_events_pollfds_fn(evfds) : 0;
@@ -2510,6 +2535,16 @@ bool scr_loop_run(ScrPromise *top_level) {
           due = now + SCR_SIGNAL_POLL_MS;
         }
       }
+      if (ffi) {
+        int ffd = scr_ffi_pollfd_fn != NULL ? scr_ffi_pollfd_fn() : -1;
+        if (ffd >= 0) {
+          fds[nfds].fd = ffd;
+          fds[nfds].events = POLLIN;
+          fds[nfds++].revents = 0;
+        } else if (due > now + SCR_CHILD_POLL_MS) {
+          due = now + SCR_CHILD_POLL_MS;
+        }
+      }
       if (kids) {
         int cfd = scr_children_wake_fd();
         if (cfd >= 0) {
@@ -2618,7 +2653,21 @@ bool scr_loop_run(ScrPromise *top_level) {
    * them as leaks. Uncaught callback throws still return above for main
    * to report through the existing exceptional teardown path. */
   scr_timers_teardown();
-  /* Same story for unref'd children the loop never reaped: release the
+  /* No reffed foreign registration or queued invocation remains at ordinary
+   * exhaustion. Disarm posting before exit listeners/global teardown so a
+   * straggling native thread becomes a safe silent drop. */
+  if (scr_ffi_stop_fn != NULL) scr_ffi_stop_fn();
+  /* Retained native FFI registrations are deliberately NOT torn down
+   * here: process 'exit' listeners run after the loop returns (inline in
+   * main, before any atexit handler) and may legitimately release a
+   * registration or pump a native library one last time — exactly like
+   * the process.exit() path, where the ledger is also still intact. On
+   * returns that reach atexit, the sweep scr_ffi_retain registered (LIFO
+   * before the RC audit) then drops the ledger's references. It does NOT
+   * run on process.exit(): scr_process_exit ends in _Exit, skipping every
+   * atexit handler — the sweep and the RC audit alike — and leaves the
+   * ledger to the OS. */
+  /* Unref'd children the loop never reaped: release the
    * registry's references (their listeners never fire — the process is
    * exiting, Node's behavior; the OS reparents the children). */
   scr_children_teardown();

package/src/scr_bytes.c

@@ -63,6 +63,15 @@ ScrBytes *scr_bytes_new(ScrBytesElem elem, double n) {
   return scr_bytes_alloc(elem, (size_t)t);
 }
 
+ScrBytes *scr_bytes_from_data(const uint8_t *data, size_t len) {
+  if (data == NULL && len != 0) {
+    scr_trap("scriptc: native callback passed a NULL span with nonzero length\n");
+  }
+  ScrBytes *b = scr_bytes_alloc(SCR_BYTES_U8, len);
+  if (len != 0) memcpy(b->data, data, len);
+  return b;
+}
+
 ScrBytes *scr_bytes_copy(const ScrBytes *src) {
   ScrBytes *b = scr_bytes_alloc(src->elem, src->len);
   memcpy(b->data, src->data, src->len * scr_bytes_elem_size(src->elem));
@@ -410,6 +419,10 @@ static const char scr_hex_digits[] = "0123456789abcdef";
  * — what Buffer.prototype.toString("utf8") does. Output re-encodes as
  * (now valid) UTF-8: worst case 3 bytes per input byte. */
 static ScrStr *scr_bytes_decode_utf8(const uint8_t *in, size_t n) {
+  if (in == NULL && n != 0) {
+    scr_trap("scriptc: native callback passed a NULL span with nonzero length\n");
+  }
+  if (n > (SIZE_MAX - 1) / 3) scr_bytes_oom();
   char *out = malloc(n * 3 + 1);
   if (!out) scr_bytes_oom();
   size_t o = 0;
@@ -478,6 +491,10 @@ static ScrStr *scr_bytes_decode_utf8(const uint8_t *in, size_t n) {
   return s;
 }
 
+ScrStr *scr_str_from_utf8_lossy(const uint8_t *bytes, size_t len) {
+  return scr_bytes_decode_utf8(bytes, len);
+}
+
 /* WHATWG TextDecoder.decode (utf-8, default options): the SAME maximal-
  * subpart replacement decode as toString("utf8") above, with one
  * difference — a leading UTF-8 BOM is stripped (ignoreBOM defaults to

package/src/scr_ffi.c

@@ -0,0 +1,139 @@
+#include "scr_runtime.h"
+
+#include <stdlib.h>
+
+/* The process-global retained-registration ledger. Format-4 script-thread
+ * tables use the lock-free path in this always-linked unit. Format-5 foreign
+ * tables install an optional teardown hook owned by scr_ffi_queue.c, keeping
+ * all queue/thread machinery out of unrelated binaries. */
+static ScrFfiTable *scr_ffi_tables;
+static bool scr_ffi_exit_registered;
+
+static void scr_ffi_oom(void) { scr_trap("scriptc: out of memory\n"); }
+
+void scr_ffi_link(ScrFfiTable *table) {
+  if (!table->linked) {
+    table->linked = true;
+    table->next = scr_ffi_tables;
+    scr_ffi_tables = table;
+  }
+  if (!scr_ffi_exit_registered) {
+    scr_ffi_exit_registered = true;
+    scr_atexit(scr_ffi_teardown_all);
+  }
+}
+
+void scr_ffi_teardown(ScrFfiTable *table) {
+  if (table->teardown != NULL) {
+    table->teardown(table);
+    return;
+  }
+  /* Disarm the raw trampoline slot FIRST: a closure release below cannot
+   * run script code today, but the slot must never dangle over freed
+   * entries — a native exit-path invocation takes the NULL trap instead. */
+  if (table->slot != NULL) *table->slot = NULL;
+  for (size_t i = 0; i < table->len; i++) {
+    scr_closure_release(table->entries[i]);
+  }
+  free(table->entries);
+  table->entries = NULL;
+  table->len = 0;
+  table->cap = 0;
+}
+
+void scr_ffi_teardown_all(void) {
+  for (ScrFfiTable *table = scr_ffi_tables; table != NULL; table = table->next) {
+    scr_ffi_teardown(table);
+  }
+}
+
+void scr_ffi_retain(ScrFfiTable *table, ScrClosure *callback) {
+  scr_ffi_link(table);
+  if (table->len == table->cap) {
+    size_t cap = table->cap == 0 ? 4 : table->cap * 2;
+    if (cap < table->cap || cap > SIZE_MAX / sizeof *table->entries) scr_ffi_oom();
+    ScrClosure **entries = realloc(table->entries, cap * sizeof *entries);
+    if (entries == NULL) scr_ffi_oom();
+    table->entries = entries;
+    table->cap = cap;
+  }
+  table->entries[table->len++] = scr_closure_retain(callback);
+}
+
+/* Raw singleton registration runs in two halves around the native set
+ * call. The first half pins the incoming closure and records the slot,
+ * but leaves the CURRENT registration untouched: a native setter may
+ * flush the outgoing callback one last time mid-replace, and it must
+ * dispatch a live closure. An empty slot arms immediately so a native
+ * fire-on-subscribe during the set call reaches the new closure. */
+void scr_ffi_retain_slot(ScrFfiTable *table, ScrClosure **slot, ScrClosure *callback) {
+  table->slot = slot;
+  scr_ffi_retain(table, callback);
+  if (*slot == NULL) *slot = callback;
+}
+
+/* The second half, after the native call returns: point the slot at the
+ * new registration and retire every pin it superseded. A callback pumped
+ * during the native call may have released or replaced this registration
+ * already (nested rawSet/rawRemove) — commit only a still-live entry. */
+void scr_ffi_commit_slot(ScrFfiTable *table, ScrClosure *callback) {
+  bool live = false;
+  for (size_t i = 0; i < table->len; i++) {
+    if (table->entries[i] == callback) {
+      live = true;
+      break;
+    }
+  }
+  if (!live) return;
+  *table->slot = callback;
+  bool kept = false;
+  size_t i = 0;
+  while (i < table->len) {
+    ScrClosure *entry = table->entries[i];
+    if (entry == callback && !kept) {
+      kept = true;
+      i++;
+      continue;
+    }
+    /* Swap-remove BEFORE releasing so the table stays consistent while
+     * the release runs; the swapped-in tail entry is re-examined at i. */
+    table->len--;
+    table->entries[i] = table->entries[table->len];
+    scr_closure_release(entry);
+  }
+}
+
+/* Pre-call validation for an explicit release: emitted before the native
+ * removal call, so releasing an unregistered value traps before native
+ * code can act on the bogus pointer pair. */
+void scr_ffi_require(ScrFfiTable *table, ScrClosure *callback) {
+  for (size_t i = 0; i < table->len; i++) {
+    if (table->entries[i] == callback) return;
+  }
+  scr_trap("scriptc: releasing a native callback registration that does not exist\n");
+}
+
+void scr_ffi_release(ScrFfiTable *table, ScrClosure *callback) {
+  for (size_t i = 0; i < table->len; i++) {
+    if (table->entries[i] != callback) continue;
+    ScrClosure *owned = table->entries[i];
+    table->len--;
+    if (i != table->len) table->entries[i] = table->entries[table->len];
+    /* If the raw slot dispatched to this registration and no duplicate
+     * pin remains, disarm it — the trampoline must not reach a released
+     * closure. */
+    if (table->slot != NULL && *table->slot == callback) {
+      bool remaining = false;
+      for (size_t j = 0; j < table->len; j++) {
+        if (table->entries[j] == callback) {
+          remaining = true;
+          break;
+        }
+      }
+      if (!remaining) *table->slot = NULL;
+    }
+    scr_closure_release(owned);
+    return;
+  }
+  scr_trap("scriptc: releasing a native callback registration that does not exist\n");
+}

package/src/scr_ffi_queue.c

@@ -0,0 +1,379 @@
+#include "scr_runtime.h"
+
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#ifdef _WIN32
+#include <windows.h>
+#elif defined(__wasi__)
+/* Native FFI is rejected for WASI. This keeps direct runtime builds honest. */
+#else
+#include <fcntl.h>
+#include <pthread.h>
+#include <unistd.h>
+#endif
+
+typedef enum {
+  SCR_FFI_ARG_NONE = 0,
+  SCR_FFI_ARG_F64,
+  SCR_FFI_ARG_BOOL,
+  SCR_FFI_ARG_U8,
+  SCR_FFI_ARG_U32,
+  SCR_FFI_ARG_I32,
+  SCR_FFI_ARG_DATA,
+} ScrFfiArgKind;
+
+typedef struct {
+  ScrFfiArgKind kind;
+  union {
+    double f64;
+    uint32_t u32;
+    int32_t i32;
+    struct {
+      uint8_t *data;
+      size_t len;
+    } span;
+  } value;
+} ScrFfiArg;
+
+struct ScrFfiCall {
+  ScrFfiTable *table;       /* opaque on the posting thread */
+  void *loop;               /* reserved instance/loop identity */
+  ScrClosure *callback;     /* opaque; the table owns its script RC pin */
+  ScrFfiDispatchFn dispatch;
+  size_t nargs;
+  ScrFfiArg *args;
+  struct ScrFfiCall *next;
+};
+
+static ScrFfiCall *scr_ffi_head;
+static ScrFfiCall *scr_ffi_tail;
+static size_t scr_ffi_foreign_registrations;
+static bool scr_ffi_installed;
+static bool scr_ffi_stopping;
+static int scr_ffi_wake_pipe[2] = {-1, -1};
+
+#ifdef _WIN32
+static SRWLOCK scr_ffi_lock = SRWLOCK_INIT;
+static void scr_ffi_lock_enter(void) { AcquireSRWLockExclusive(&scr_ffi_lock); }
+static void scr_ffi_lock_leave(void) { ReleaseSRWLockExclusive(&scr_ffi_lock); }
+#elif defined(__wasi__)
+static void scr_ffi_lock_enter(void) {}
+static void scr_ffi_lock_leave(void) {}
+#else
+static pthread_mutex_t scr_ffi_lock = PTHREAD_MUTEX_INITIALIZER;
+static void scr_ffi_lock_enter(void) { (void)pthread_mutex_lock(&scr_ffi_lock); }
+static void scr_ffi_lock_leave(void) { (void)pthread_mutex_unlock(&scr_ffi_lock); }
+#endif
+
+static void scr_ffi_oom(void) { scr_trap("scriptc: out of memory\n"); }
+
+/* Foreign trampolines cannot enter the script exception machinery. Allocation
+ * failure and malformed native pointers are fatal process-boundary failures,
+ * reported without touching any runtime object. */
+static void scr_ffi_foreign_fatal(const char *message) {
+  fputs(message, stderr);
+  abort();
+}
+
+static void *scr_ffi_foreign_alloc(size_t size) {
+  void *ptr = malloc(size == 0 ? 1 : size);
+  if (ptr == NULL) scr_ffi_foreign_fatal("scriptc: out of memory\n");
+  return ptr;
+}
+
+static void scr_ffi_call_free(ScrFfiCall *call) {
+  if (call == NULL) return;
+  for (size_t i = 0; i < call->nargs; i++) {
+    if (call->args[i].kind == SCR_FFI_ARG_DATA) free(call->args[i].value.span.data);
+  }
+  free(call->args);
+  free(call);
+}
+
+static bool scr_ffi_table_contains(const ScrFfiTable *table, const ScrClosure *callback) {
+  for (size_t i = 0; i < table->len; i++) {
+    if (table->entries[i] == callback) return true;
+  }
+  return false;
+}
+
+static void scr_ffi_table_retire(ScrFfiTable *table, ScrClosure *callback) {
+  if (table->retired_len == table->retired_cap) {
+    size_t cap = table->retired_cap == 0 ? 4 : table->retired_cap * 2;
+    if (cap < table->retired_cap || cap > SIZE_MAX / sizeof *table->retired) scr_ffi_oom();
+    ScrClosure **retired = realloc(table->retired, cap * sizeof *retired);
+    if (retired == NULL) scr_ffi_oom();
+    table->retired = retired;
+    table->retired_cap = cap;
+  }
+  table->retired[table->retired_len++] = callback;
+}
+
+static void scr_ffi_release_retired(ScrFfiTable *table) {
+  ScrClosure **retired = NULL;
+  size_t len = 0;
+  scr_ffi_lock_enter();
+  if (table->queued == 0 && table->retired_len > 0) {
+    retired = table->retired;
+    len = table->retired_len;
+    table->retired = NULL;
+    table->retired_len = 0;
+    table->retired_cap = 0;
+  }
+  scr_ffi_lock_leave();
+  for (size_t i = 0; i < len; i++) scr_closure_release(retired[i]);
+  free(retired);
+}
+
+void scr_ffi_retain_foreign(ScrFfiTable *table, ScrClosure *callback) {
+  table->teardown = &scr_ffi_teardown_foreign;
+  scr_ffi_link(table);
+  scr_ffi_lock_enter();
+  if (table->len == table->cap) {
+    size_t cap = table->cap == 0 ? 4 : table->cap * 2;
+    if (cap < table->cap || cap > SIZE_MAX / sizeof *table->entries) scr_ffi_oom();
+    ScrClosure **entries = realloc(table->entries, cap * sizeof *entries);
+    if (entries == NULL) scr_ffi_oom();
+    table->entries = entries;
+    table->cap = cap;
+  }
+  table->entries[table->len++] = scr_closure_retain(callback);
+  scr_ffi_foreign_registrations++;
+  scr_ffi_lock_leave();
+}
+
+void scr_ffi_require_foreign(ScrFfiTable *table, ScrClosure *callback) {
+  scr_ffi_lock_enter();
+  bool found = scr_ffi_table_contains(table, callback);
+  scr_ffi_lock_leave();
+  if (!found) scr_trap("scriptc: releasing a native callback registration that does not exist\n");
+}
+
+void scr_ffi_release_foreign(ScrFfiTable *table, ScrClosure *callback) {
+  scr_ffi_lock_enter();
+  for (size_t i = 0; i < table->len; i++) {
+    if (table->entries[i] != callback) continue;
+    ScrClosure *owned = table->entries[i];
+    table->len--;
+    if (i != table->len) table->entries[i] = table->entries[table->len];
+    if (scr_ffi_foreign_registrations > 0) scr_ffi_foreign_registrations--;
+    bool deferred = table->queued > 0;
+    if (deferred) scr_ffi_table_retire(table, owned);
+    scr_ffi_lock_leave();
+    if (!deferred) scr_closure_release(owned);
+    return;
+  }
+  scr_ffi_lock_leave();
+  scr_trap("scriptc: releasing a native callback registration that does not exist\n");
+}
+
+ScrFfiCall *scr_ffi_call_new(ScrFfiTable *table, ScrClosure *callback,
+                             ScrFfiDispatchFn dispatch, size_t nargs) {
+  ScrFfiCall *call = scr_ffi_foreign_alloc(sizeof *call);
+  call->table = table;
+  call->loop = table->loop;
+  call->callback = callback;
+  call->dispatch = dispatch;
+  call->nargs = nargs;
+  call->args = nargs == 0 ? NULL : scr_ffi_foreign_alloc(nargs * sizeof *call->args);
+  if (nargs > 0) memset(call->args, 0, nargs * sizeof *call->args);
+  call->next = NULL;
+  return call;
+}
+
+static ScrFfiArg *scr_ffi_call_arg(ScrFfiCall *call, size_t index) {
+  if (index >= call->nargs) scr_ffi_foreign_fatal("scriptc: invalid staged FFI callback argument\n");
+  return &call->args[index];
+}
+
+void scr_ffi_call_set_f64(ScrFfiCall *call, size_t i, double v) {
+  ScrFfiArg *arg = scr_ffi_call_arg(call, i); arg->kind = SCR_FFI_ARG_F64; arg->value.f64 = v;
+}
+void scr_ffi_call_set_bool(ScrFfiCall *call, size_t i, uint8_t v) {
+  ScrFfiArg *arg = scr_ffi_call_arg(call, i); arg->kind = SCR_FFI_ARG_BOOL; arg->value.u32 = v != 0;
+}
+void scr_ffi_call_set_u8(ScrFfiCall *call, size_t i, uint8_t v) {
+  ScrFfiArg *arg = scr_ffi_call_arg(call, i); arg->kind = SCR_FFI_ARG_U8; arg->value.u32 = v;
+}
+void scr_ffi_call_set_u32(ScrFfiCall *call, size_t i, uint32_t v) {
+  ScrFfiArg *arg = scr_ffi_call_arg(call, i); arg->kind = SCR_FFI_ARG_U32; arg->value.u32 = v;
+}
+void scr_ffi_call_set_i32(ScrFfiCall *call, size_t i, int32_t v) {
+  ScrFfiArg *arg = scr_ffi_call_arg(call, i); arg->kind = SCR_FFI_ARG_I32; arg->value.i32 = v;
+}
+
+static void scr_ffi_call_copy_data(ScrFfiCall *call, size_t i,
+                                   const uint8_t *v, size_t len,
+                                   const char *null_message) {
+  if (v == NULL && len != 0) scr_ffi_foreign_fatal(null_message);
+  ScrFfiArg *arg = scr_ffi_call_arg(call, i);
+  arg->kind = SCR_FFI_ARG_DATA;
+  arg->value.span.len = len;
+  arg->value.span.data = len == 0 ? NULL : scr_ffi_foreign_alloc(len);
+  if (len > 0) memcpy(arg->value.span.data, v, len);
+}
+
+void scr_ffi_call_copy_string(ScrFfiCall *call, size_t i,
+                              const uint8_t *v, size_t len) {
+  scr_ffi_call_copy_data(call, i, v, len,
+      "scriptc: native callback passed a NULL string span with nonzero length\n");
+}
+
+void scr_ffi_call_copy_bytes(ScrFfiCall *call, size_t i,
+                             const uint8_t *v, size_t len) {
+  scr_ffi_call_copy_data(call, i, v, len,
+      "scriptc: native callback passed a NULL bytes span with nonzero length\n");
+}
+
+void scr_ffi_call_copy_cstring(ScrFfiCall *call, size_t i, const char *v) {
+  if (v == NULL) scr_ffi_foreign_fatal("scriptc: native callback passed a NULL cstring\n");
+  scr_ffi_call_copy_data(call, i, (const uint8_t *)v, strlen(v),
+                         "scriptc: native callback passed a NULL cstring\n");
+}
+
+void scr_ffi_post(ScrFfiCall *call) {
+  scr_ffi_lock_enter();
+  if (scr_ffi_stopping || !scr_ffi_table_contains(call->table, call->callback)) {
+    scr_ffi_lock_leave();
+    scr_ffi_call_free(call);
+    return;
+  }
+  call->table->queued++;
+  if (scr_ffi_tail != NULL) scr_ffi_tail->next = call;
+  else scr_ffi_head = call;
+  scr_ffi_tail = call;
+#if !defined(_WIN32) && !defined(__wasi__)
+  if (scr_ffi_wake_pipe[1] >= 0) {
+    ssize_t ignored = write(scr_ffi_wake_pipe[1], "f", 1);
+    (void)ignored; /* a full pipe is already readable */
+  }
+#endif
+  scr_ffi_lock_leave();
+}
+
+static const ScrFfiArg *scr_ffi_get_arg(const ScrFfiCall *call, size_t index) {
+  if (index >= call->nargs) scr_trap("scriptc: invalid staged FFI callback argument\n");
+  return &call->args[index];
+}
+
+double scr_ffi_call_get_f64(const ScrFfiCall *call, size_t i) { return scr_ffi_get_arg(call, i)->value.f64; }
+bool scr_ffi_call_get_bool(const ScrFfiCall *call, size_t i) { return scr_ffi_get_arg(call, i)->value.u32 != 0; }
+double scr_ffi_call_get_u8(const ScrFfiCall *call, size_t i) { return (double)scr_ffi_get_arg(call, i)->value.u32; }
+double scr_ffi_call_get_u32(const ScrFfiCall *call, size_t i) { return (double)scr_ffi_get_arg(call, i)->value.u32; }
+double scr_ffi_call_get_i32(const ScrFfiCall *call, size_t i) { return (double)scr_ffi_get_arg(call, i)->value.i32; }
+const uint8_t *scr_ffi_call_get_data(const ScrFfiCall *call, size_t i) { return scr_ffi_get_arg(call, i)->value.span.data; }
+size_t scr_ffi_call_get_len(const ScrFfiCall *call, size_t i) { return scr_ffi_get_arg(call, i)->value.span.len; }
+
+static bool scr_ffi_pending(void) {
+  bool pending;
+  scr_ffi_lock_enter();
+  pending = scr_ffi_foreign_registrations > 0 || scr_ffi_head != NULL;
+  scr_ffi_lock_leave();
+  return pending;
+}
+
+static void scr_ffi_wake_drain(void) {
+#if !defined(_WIN32) && !defined(__wasi__)
+  if (scr_ffi_wake_pipe[0] < 0) return;
+  char buf[64];
+  while (read(scr_ffi_wake_pipe[0], buf, sizeof buf) > 0) {}
+#endif
+}
+
+static bool scr_ffi_dispatch(void) {
+  scr_ffi_lock_enter();
+  ScrFfiCall *call = scr_ffi_head;
+  if (call != NULL) {
+    scr_ffi_head = call->next;
+    if (scr_ffi_head == NULL) scr_ffi_tail = NULL;
+  }
+  scr_ffi_lock_leave();
+  if (call == NULL) return false;
+
+  call->dispatch(call->callback, call);
+
+  ScrFfiTable *table = call->table;
+  scr_ffi_lock_enter();
+  if (table->queued > 0) table->queued--;
+  /* Keep the wake fd readable while queued calls remain. Drain only while
+   * holding the same lock writers use, closing the post-vs-drain lost-wakeup
+   * race for the transition to an empty queue. */
+  bool more = scr_ffi_head != NULL;
+  if (!more) scr_ffi_wake_drain();
+  scr_ffi_lock_leave();
+  scr_ffi_call_free(call);
+  scr_ffi_release_retired(table);
+  return true;
+}
+
+static int scr_ffi_pollfd(void) { return scr_ffi_wake_pipe[0]; }
+
+void scr_ffi_install(void) {
+  if (scr_ffi_installed) return;
+  scr_ffi_installed = true;
+#if !defined(_WIN32) && !defined(__wasi__)
+  if (pipe(scr_ffi_wake_pipe) == 0) {
+    for (int i = 0; i < 2; i++) {
+      (void)fcntl(scr_ffi_wake_pipe[i], F_SETFL, O_NONBLOCK);
+      (void)fcntl(scr_ffi_wake_pipe[i], F_SETFD, FD_CLOEXEC);
+    }
+  } else {
+    scr_ffi_wake_pipe[0] = scr_ffi_wake_pipe[1] = -1;
+  }
+#endif
+  scr_loop_set_ffi(&scr_ffi_pending, &scr_ffi_dispatch, &scr_ffi_pollfd,
+                   &scr_ffi_stop);
+}
+
+void scr_ffi_stop(void) {
+  scr_ffi_lock_enter();
+  if (scr_ffi_stopping) {
+    scr_ffi_lock_leave();
+    return;
+  }
+  scr_ffi_stopping = true;
+  ScrFfiCall *calls = scr_ffi_head;
+  scr_ffi_head = scr_ffi_tail = NULL;
+  for (ScrFfiCall *call = calls; call != NULL; call = call->next) {
+    if (call->table->queued > 0) call->table->queued--;
+  }
+  scr_ffi_wake_drain();
+#if !defined(_WIN32) && !defined(__wasi__)
+  if (scr_ffi_wake_pipe[0] >= 0) close(scr_ffi_wake_pipe[0]);
+  if (scr_ffi_wake_pipe[1] >= 0) close(scr_ffi_wake_pipe[1]);
+#endif
+  scr_ffi_wake_pipe[0] = scr_ffi_wake_pipe[1] = -1;
+  scr_ffi_lock_leave();
+  while (calls != NULL) {
+    ScrFfiCall *next = calls->next;
+    ScrFfiTable *table = calls->table;
+    scr_ffi_call_free(calls);
+    scr_ffi_release_retired(table);
+    calls = next;
+  }
+}
+
+void scr_ffi_teardown_foreign(ScrFfiTable *table) {
+  scr_ffi_stop();
+  scr_ffi_lock_enter();
+  ScrClosure **entries = table->entries;
+  size_t len = table->len;
+  ScrClosure **retired = table->retired;
+  size_t retired_len = table->retired_len;
+  if (scr_ffi_foreign_registrations >= len) scr_ffi_foreign_registrations -= len;
+  table->entries = NULL;
+  table->len = 0;
+  table->cap = 0;
+  table->retired = NULL;
+  table->retired_len = 0;
+  table->retired_cap = 0;
+  table->queued = 0;
+  scr_ffi_lock_leave();
+  for (size_t i = 0; i < len; i++) scr_closure_release(entries[i]);
+  free(entries);
+  for (size_t i = 0; i < retired_len; i++) scr_closure_release(retired[i]);
+  free(retired);
+}

package/src/scr_runtime.h

@@ -389,6 +389,9 @@ typedef struct ScrStr {
 } ScrStr;
 
 ScrStr *scr_str_new(const char *bytes, size_t len); /* returns +1 */
+/* Native callback boundary: copy and WHATWG-decode a UTF-8 span, replacing
+ * malformed subsequences with U+FFFD. NULL with len == 0 is an empty span. */
+ScrStr *scr_str_from_utf8_lossy(const uint8_t *bytes, size_t len); /* +1 */
 
 /* Internal allocators for buffer builders (scr_json.c): a +1 string with
  * UNINITIALIZED data (the builder fills bytes, then len and the NUL), and
@@ -1316,6 +1319,100 @@ static inline ScrClosure *scr_closure_retain(ScrClosure *c) {
 
 void scr_closure_release(ScrClosure *c); /* releases the boxes; NULL-tolerant */
 
+/* ── outbound FFI retained callbacks (scr_ffi.c) ─────────────────────
+ * One compiler-emitted table per retained callback descriptor. For
+ * context-bearing descriptors, entries are counted rather than
+ * deduplicated: registering the same closure twice requires two matching
+ * releases. Raw singleton slots replace instead: commit_slot retires
+ * every pin the new registration superseded — a duplicate of the same
+ * closure included — so after any number of set calls exactly one
+ * release is pending. The table owns one closure reference per entry and
+ * joins a process-global teardown list on first use. Script-thread retained
+ * callbacks do not contribute event-loop liveness; foreign registrations do,
+ * and their queued invocations keep released closure pins alive until the
+ * script-thread dispatch has finished. */
+typedef struct ScrFfiTable {
+  ScrClosure **entries;
+  size_t len;
+  size_t cap;
+  struct ScrFfiTable *next;
+  bool linked;
+  /* Raw retained singletons only: the compiler-emitted global the
+   * trampoline dispatches through. Teardown and release disarm it so a
+   * late native invocation hits the trampoline's NULL trap instead of a
+   * freed closure. NULL for context-bearing descriptors. */
+  ScrClosure **slot;
+  /* Foreign descriptors only. The global FFI queue lock protects these
+   * fields together with entries/len/cap. Retired pins were explicitly
+   * released while a queued invocation could still name them; dispatch
+   * drops them on the script thread after this table's queue reaches zero. */
+  ScrClosure **retired;
+  size_t retired_len;
+  size_t retired_cap;
+  size_t queued;
+  /* Reserved process-loop identity captured by queued calls. Executables use
+   * one global loop today; library mode can make this per instance later
+   * without changing the post/call ABI. */
+  void *loop;
+  /* Optional format-5 teardown. NULL keeps format-4 tables on the compact
+   * always-linked path; foreign tables point into scr_ffi_queue.c. */
+  void (*teardown)(struct ScrFfiTable *table);
+} ScrFfiTable;
+
+void scr_ffi_link(ScrFfiTable *table);
+void scr_ffi_retain(ScrFfiTable *table, ScrClosure *callback);
+void scr_ffi_retain_foreign(ScrFfiTable *table, ScrClosure *callback);
+/* Raw singleton registration, split around the native set call:
+ * retain_slot pins the incoming closure BEFORE the call without touching
+ * the current registration; commit_slot repoints the slot and retires the
+ * superseded pins after the call returns. */
+void scr_ffi_retain_slot(ScrFfiTable *table, ScrClosure **slot, ScrClosure *callback);
+void scr_ffi_commit_slot(ScrFfiTable *table, ScrClosure *callback);
+/* Traps unless the registration exists — emitted BEFORE a native release
+ * call so a bogus release cannot reach native code. */
+void scr_ffi_require(ScrFfiTable *table, ScrClosure *callback);
+void scr_ffi_release(ScrFfiTable *table, ScrClosure *callback);
+void scr_ffi_require_foreign(ScrFfiTable *table, ScrClosure *callback);
+void scr_ffi_release_foreign(ScrFfiTable *table, ScrClosure *callback);
+void scr_ffi_teardown(ScrFfiTable *table);
+void scr_ffi_teardown_all(void);
+
+/* Format-5 foreign-thread delivery. A generated native trampoline creates a
+ * plain malloc-backed call, stages scalar values or copied byte spans, and
+ * posts it. It never touches closure RC, exception cells, fibers, or other
+ * script-thread-only runtime state. The generated dispatch thunk runs later
+ * on the event loop and materializes script strings/bytes there. */
+typedef struct ScrFfiCall ScrFfiCall;
+typedef void (*ScrFfiDispatchFn)(ScrClosure *callback, ScrFfiCall *call);
+
+ScrFfiCall *scr_ffi_call_new(ScrFfiTable *table, ScrClosure *callback,
+                             ScrFfiDispatchFn dispatch, size_t nargs);
+void scr_ffi_call_set_f64(ScrFfiCall *call, size_t index, double value);
+void scr_ffi_call_set_bool(ScrFfiCall *call, size_t index, uint8_t value);
+void scr_ffi_call_set_u8(ScrFfiCall *call, size_t index, uint8_t value);
+void scr_ffi_call_set_u32(ScrFfiCall *call, size_t index, uint32_t value);
+void scr_ffi_call_set_i32(ScrFfiCall *call, size_t index, int32_t value);
+void scr_ffi_call_copy_cstring(ScrFfiCall *call, size_t index, const char *value);
+void scr_ffi_call_copy_string(ScrFfiCall *call, size_t index,
+                              const uint8_t *value, size_t len);
+void scr_ffi_call_copy_bytes(ScrFfiCall *call, size_t index,
+                             const uint8_t *value, size_t len);
+void scr_ffi_post(ScrFfiCall *call);
+
+double scr_ffi_call_get_f64(const ScrFfiCall *call, size_t index);
+bool scr_ffi_call_get_bool(const ScrFfiCall *call, size_t index);
+double scr_ffi_call_get_u8(const ScrFfiCall *call, size_t index);
+double scr_ffi_call_get_u32(const ScrFfiCall *call, size_t index);
+double scr_ffi_call_get_i32(const ScrFfiCall *call, size_t index);
+const uint8_t *scr_ffi_call_get_data(const ScrFfiCall *call, size_t index);
+size_t scr_ffi_call_get_len(const ScrFfiCall *call, size_t index);
+
+void scr_ffi_install(void);
+void scr_ffi_stop(void);
+void scr_ffi_teardown_foreign(ScrFfiTable *table);
+void scr_loop_set_ffi(bool (*pending)(void), bool (*dispatch)(void),
+                      int (*pollfd)(void), void (*stop)(void));
+
 /* ── unions ─────────────────────────────────────────────────────────
  * A union value (`A | B`) is an IMMUTABLE tagged box: a refcounted header,
  * the arm's tag (its index in the compiler's canonical arm order), and one
@@ -4735,6 +4832,9 @@ ScrJsval *scr_jsval_from_bytes(const ScrBytes *b);
  * THROWS Node's "Invalid typed array length" RangeError catchably and
  * returns NULL with the exception pending). */
 ScrBytes *scr_bytes_new(ScrBytesElem elem, double n); /* +1 */
+/* Native callback boundary: exact owned u8 copy. NULL with len == 0 is an
+ * empty span. */
+ScrBytes *scr_bytes_from_data(const uint8_t *data, size_t len); /* +1 */
 
 /* `new Uint8Array(src)` / Buffer.from(u8): a same-elem-kind copy (the
  * compiler fences cross-kind construction). Borrows src. Never throws. */