@scriptc/runtime 0.0.31 → 0.0.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scriptc/runtime",
-  "version": "0.0.31",
+  "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_musl.c

@@ -2,7 +2,7 @@
  * this TU together with -DSCR_MUSL). musl deliberately provides no libc
  * identification macro, so the target-selected project macro is the guard.
  *
- * The x86_64 ucontext implementation below is derived from libucontext
+ * The x86_64 and AArch64 ucontext implementations below are derived from libucontext
  * commit 49e671dd52ff6791295d8161ad3b6da7dc5f6f9d:
  * https://github.com/kaniini/libucontext
  *
@@ -27,8 +27,8 @@
 #include <ucontext.h>
 #endif
 
-#if !defined(__x86_64__)
-#error "scriptc's musl runtime currently supports x86_64 only"
+#if !defined(__x86_64__) && !defined(__aarch64__)
+#error "scriptc's musl runtime currently supports x86_64 and AArch64 only"
 #endif
 
 /* The scriptc runtime uses arc4random_buf as its infallible CSPRNG contract.
@@ -57,9 +57,10 @@ void arc4random_buf(void *buf, size_t n) {
 
 /* musl exposes the POSIX ucontext types but intentionally omits these legacy
  * functions. scriptc's async/generator fibers need only user-space register
- * swaps; they never use a context to mutate the process signal mask. This is
- * libucontext's fast (non-POSIX-signal-mask) x86_64 implementation, emitted
- * under the standard symbol names that musl leaves unresolved. */
+ * swaps; they never use a context to mutate the process signal mask. These are
+ * libucontext's fast (non-POSIX-signal-mask) implementations, emitted under
+ * the standard symbol names that musl leaves unresolved. */
+#if defined(__x86_64__)
 _Static_assert(offsetof(ucontext_t, uc_mcontext.gregs) == 40,
                "unexpected musl x86_64 ucontext layout");
 _Static_assert(offsetof(ucontext_t, uc_mcontext.fpregs) == 224,
@@ -265,6 +266,169 @@ void makecontext(ucontext_t *ucp, void (*func)(void), int argc, ...) {
 #undef SCR_STR
 #undef SCR_STR_INNER
 
+#elif defined(__aarch64__)
+
+/* musl's AArch64 ucontext embeds the kernel sigcontext after a 128-byte
+ * signal mask. Keep the offsets pinned to the Zig 0.16 musl headers: the
+ * assembly below saves the ABI's callee-preserved GPR and SIMD state there. */
+_Static_assert(offsetof(ucontext_t, uc_mcontext.regs[0]) == 184,
+               "unexpected musl AArch64 register layout");
+_Static_assert(offsetof(ucontext_t, uc_mcontext.sp) == 432,
+               "unexpected musl AArch64 stack-pointer layout");
+_Static_assert(offsetof(ucontext_t, uc_mcontext.pc) == 440,
+               "unexpected musl AArch64 program-counter layout");
+_Static_assert(offsetof(ucontext_t, uc_mcontext.pstate) == 448,
+               "unexpected musl AArch64 processor-state layout");
+_Static_assert(offsetof(ucontext_t, uc_mcontext.__reserved) == 464,
+               "unexpected musl AArch64 SIMD-state layout");
+
+#define SCR_STR_INNER(x) #x
+#define SCR_STR(x) SCR_STR_INNER(x)
+#define SCR_A64_UC_REG(reg) (184 + ((reg) * 8))
+#define SCR_A64_UC_SP 432
+#define SCR_A64_UC_PC 440
+#define SCR_A64_UC_PSTATE 448
+#define SCR_A64_UC_FPSIMD 464
+
+__asm__(
+    ".text\n"
+    ".p2align 2\n"
+    ".global getcontext\n"
+    "getcontext:\n"
+    "  str xzr, [x0, #" SCR_STR(SCR_A64_UC_REG(0)) "]\n"
+    "  stp x2, x3, [x0, #" SCR_STR(SCR_A64_UC_REG(2)) "]\n"
+    "  str x30, [x0, #" SCR_STR(SCR_A64_UC_PC) "]\n"
+    "  mov x2, sp\n"
+    "  str x2, [x0, #" SCR_STR(SCR_A64_UC_SP) "]\n"
+    "  str xzr, [x0, #" SCR_STR(SCR_A64_UC_PSTATE) "]\n"
+    "  add x2, x0, #" SCR_STR(SCR_A64_UC_FPSIMD) "\n"
+    "  stp q8, q9, [x2, #144]\n"
+    "  stp q10, q11, [x2, #176]\n"
+    "  stp q12, q13, [x2, #208]\n"
+    "  stp q14, q15, [x2, #240]\n"
+    "  mov x2, x0\n"
+    "  mov x0, #0\n"
+    "  stp x0, x1, [x2, #" SCR_STR(SCR_A64_UC_REG(0)) "]\n"
+    "  stp x4, x5, [x2, #" SCR_STR(SCR_A64_UC_REG(4)) "]\n"
+    "  stp x6, x7, [x2, #" SCR_STR(SCR_A64_UC_REG(6)) "]\n"
+    "  stp x8, x9, [x2, #" SCR_STR(SCR_A64_UC_REG(8)) "]\n"
+    "  stp x10, x11, [x2, #" SCR_STR(SCR_A64_UC_REG(10)) "]\n"
+    "  stp x12, x13, [x2, #" SCR_STR(SCR_A64_UC_REG(12)) "]\n"
+    "  stp x14, x15, [x2, #" SCR_STR(SCR_A64_UC_REG(14)) "]\n"
+    "  stp x16, x17, [x2, #" SCR_STR(SCR_A64_UC_REG(16)) "]\n"
+    "  stp x18, x19, [x2, #" SCR_STR(SCR_A64_UC_REG(18)) "]\n"
+    "  stp x20, x21, [x2, #" SCR_STR(SCR_A64_UC_REG(20)) "]\n"
+    "  stp x22, x23, [x2, #" SCR_STR(SCR_A64_UC_REG(22)) "]\n"
+    "  stp x24, x25, [x2, #" SCR_STR(SCR_A64_UC_REG(24)) "]\n"
+    "  stp x26, x27, [x2, #" SCR_STR(SCR_A64_UC_REG(26)) "]\n"
+    "  stp x28, x29, [x2, #" SCR_STR(SCR_A64_UC_REG(28)) "]\n"
+    "  str x30, [x2, #" SCR_STR(SCR_A64_UC_REG(30)) "]\n"
+    "  ret\n"
+
+    ".p2align 2\n"
+    ".global setcontext\n"
+    "setcontext:\n"
+    "  ldp x18, x19, [x0, #" SCR_STR(SCR_A64_UC_REG(18)) "]\n"
+    "  ldp x20, x21, [x0, #" SCR_STR(SCR_A64_UC_REG(20)) "]\n"
+    "  ldp x22, x23, [x0, #" SCR_STR(SCR_A64_UC_REG(22)) "]\n"
+    "  ldp x24, x25, [x0, #" SCR_STR(SCR_A64_UC_REG(24)) "]\n"
+    "  ldp x26, x27, [x0, #" SCR_STR(SCR_A64_UC_REG(26)) "]\n"
+    "  ldp x28, x29, [x0, #" SCR_STR(SCR_A64_UC_REG(28)) "]\n"
+    "  ldr x30, [x0, #" SCR_STR(SCR_A64_UC_REG(30)) "]\n"
+    "  ldr x2, [x0, #" SCR_STR(SCR_A64_UC_SP) "]\n"
+    "  mov sp, x2\n"
+    "  add x2, x0, #" SCR_STR(SCR_A64_UC_FPSIMD) "\n"
+    "  ldp q8, q9, [x2, #144]\n"
+    "  ldp q10, q11, [x2, #176]\n"
+    "  ldp q12, q13, [x2, #208]\n"
+    "  ldp q14, q15, [x2, #240]\n"
+    "  ldr x16, [x0, #" SCR_STR(SCR_A64_UC_PC) "]\n"
+    "  ldp x2, x3, [x0, #" SCR_STR(SCR_A64_UC_REG(2)) "]\n"
+    "  ldp x4, x5, [x0, #" SCR_STR(SCR_A64_UC_REG(4)) "]\n"
+    "  ldp x6, x7, [x0, #" SCR_STR(SCR_A64_UC_REG(6)) "]\n"
+    "  ldp x0, x1, [x0, #" SCR_STR(SCR_A64_UC_REG(0)) "]\n"
+    "  br x16\n"
+
+    ".p2align 2\n"
+    ".global swapcontext\n"
+    "swapcontext:\n"
+    "  str xzr, [x0, #" SCR_STR(SCR_A64_UC_REG(0)) "]\n"
+    "  stp x2, x3, [x0, #" SCR_STR(SCR_A64_UC_REG(2)) "]\n"
+    "  stp x4, x5, [x0, #" SCR_STR(SCR_A64_UC_REG(4)) "]\n"
+    "  stp x6, x7, [x0, #" SCR_STR(SCR_A64_UC_REG(6)) "]\n"
+    "  stp x8, x9, [x0, #" SCR_STR(SCR_A64_UC_REG(8)) "]\n"
+    "  stp x10, x11, [x0, #" SCR_STR(SCR_A64_UC_REG(10)) "]\n"
+    "  stp x12, x13, [x0, #" SCR_STR(SCR_A64_UC_REG(12)) "]\n"
+    "  stp x14, x15, [x0, #" SCR_STR(SCR_A64_UC_REG(14)) "]\n"
+    "  stp x16, x17, [x0, #" SCR_STR(SCR_A64_UC_REG(16)) "]\n"
+    "  stp x18, x19, [x0, #" SCR_STR(SCR_A64_UC_REG(18)) "]\n"
+    "  stp x20, x21, [x0, #" SCR_STR(SCR_A64_UC_REG(20)) "]\n"
+    "  stp x22, x23, [x0, #" SCR_STR(SCR_A64_UC_REG(22)) "]\n"
+    "  stp x24, x25, [x0, #" SCR_STR(SCR_A64_UC_REG(24)) "]\n"
+    "  stp x26, x27, [x0, #" SCR_STR(SCR_A64_UC_REG(26)) "]\n"
+    "  stp x28, x29, [x0, #" SCR_STR(SCR_A64_UC_REG(28)) "]\n"
+    "  str x30, [x0, #" SCR_STR(SCR_A64_UC_REG(30)) "]\n"
+    "  str x30, [x0, #" SCR_STR(SCR_A64_UC_PC) "]\n"
+    "  mov x2, sp\n"
+    "  str x2, [x0, #" SCR_STR(SCR_A64_UC_SP) "]\n"
+    "  str xzr, [x0, #" SCR_STR(SCR_A64_UC_PSTATE) "]\n"
+    "  add x2, x0, #" SCR_STR(SCR_A64_UC_FPSIMD) "\n"
+    "  stp q8, q9, [x2, #144]\n"
+    "  stp q10, q11, [x2, #176]\n"
+    "  stp q12, q13, [x2, #208]\n"
+    "  stp q14, q15, [x2, #240]\n"
+    "  mov x0, x1\n"
+    "  b setcontext\n"
+
+    ".p2align 2\n"
+    ".hidden scr_musl_context_trampoline\n"
+    "scr_musl_context_trampoline:\n"
+    "  mov x0, x19\n"
+    "  cbz x0, 1f\n"
+    "  bl setcontext\n"
+    "  brk #0\n"
+    "1:\n"
+    "  mov w0, #0\n"
+    "  bl exit\n"
+    "  brk #0\n");
+
+extern void scr_musl_context_trampoline(void);
+
+void makecontext(ucontext_t *ucp, void (*func)(void), int argc, ...) {
+  greg_t *sp;
+  va_list va;
+  int i;
+
+  sp = (greg_t *)((uintptr_t)ucp->uc_stack.ss_sp + ucp->uc_stack.ss_size);
+  sp -= argc < 8 ? 0 : argc - 8;
+  sp = (greg_t *)((uintptr_t)sp & ~(uintptr_t)15);
+
+  ucp->uc_mcontext.sp = (greg_t)(uintptr_t)sp;
+  ucp->uc_mcontext.pc = (greg_t)(uintptr_t)func;
+  ucp->uc_mcontext.regs[19] = (greg_t)(uintptr_t)ucp->uc_link;
+  ucp->uc_mcontext.regs[30] =
+      (greg_t)(uintptr_t)&scr_musl_context_trampoline;
+
+  va_start(va, argc);
+  for (i = 0; i < argc && i < 8; i++) {
+    ucp->uc_mcontext.regs[i] = va_arg(va, greg_t);
+  }
+  for (; i < argc; i++) {
+    *sp++ = va_arg(va, greg_t);
+  }
+  va_end(va);
+}
+
+#undef SCR_A64_UC_FPSIMD
+#undef SCR_A64_UC_PSTATE
+#undef SCR_A64_UC_PC
+#undef SCR_A64_UC_SP
+#undef SCR_A64_UC_REG
+#undef SCR_STR
+#undef SCR_STR_INNER
+
+#endif /* architecture */
+
 #endif /* !SCR_LIB */
 
 #else /* !SCR_MUSL */

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. */
@@ -5493,18 +5593,25 @@ long scr_secure_ctx_live_count(void);
 #endif
 
 /* ── node:tls, the CA-store introspection slice (scr_tls_ca.c — its own
- * unit and link gate; plain PEM-block bookkeeping, NO mbedTLS, so a
- * getCACertificates-only binary never builds the archive; cc.ts also
- * compiles it whenever scr_tls.c does). The HOST bundle (the
- * /etc/ssl/cert.pem probe order scr_tls.c documents) stands in for both
- * Node's compiled-in Mozilla roots ('bundled', rootCertificates) and the
- * platform store ('system') — the established SEMANTICS divergence,
- * extended to introspection; 'extra' uses the NODE_EXTRA_CA_CERTS file
- * captured before user code runs. Arrays are cached per type (+1 retained
- * answers each call — Node's own caching, and the identity the suite pins
- * with strictEqual). */
+ * unit and link gate; NO mbedTLS, so a getCACertificates-only binary never
+ * builds the archive; cc.ts also compiles it whenever scr_tls.c does). The
+ * HOST roots (Windows' system certificate stores, the established bundle probe on
+ * POSIX) stand in for both Node's compiled-in Mozilla roots ('bundled',
+ * rootCertificates) and the platform store ('system') — the established
+ * SEMANTICS divergence, extended to introspection; 'extra' uses the
+ * NODE_EXTRA_CA_CERTS file captured before user code runs. Arrays are cached
+ * per type (+1 retained answers each call — Node's own caching, and the
+ * identity the suite pins with strictEqual). */
 void scr_tls_ca_install(void); /* snapshots NODE_EXTRA_CA_CERTS + file bytes */
 bool scr_tls_ca_extra_pem(const char **pem, size_t *len); /* borrowed launch snapshot */
+#ifdef _WIN32
+/* Enumerates Windows' trusted ROOT, intermediate CA, and TrustedPeople store
+ * locations, yielding only certificates whose effective Windows EKU policy
+ * permits TLS server authentication. DER is borrowed for the call. */
+typedef void (*ScrTlsCaWindowsCertFn)(void *ctx, const unsigned char *der, size_t len);
+bool scr_tls_ca_windows_cert_server_auth(const void *cert_context);
+void scr_tls_ca_windows_certs(ScrTlsCaWindowsCertFn fn, void *ctx);
+#endif
 ScrArr *scr_tls_ca_get(ScrStr *type); /* +1; throws ERR_INVALID_ARG_VALUE on unknown types */
 ScrArr *scr_tls_ca_root(void);        /* +1; === getCACertificates("bundled") */
 /* Replaces the 'default' set: entries filter to their PEM certificate

package/src/scr_tls.c

@@ -56,7 +56,7 @@
  * head buffers in the socket's write buffer until the handshake
  * establishes (the mid-connect buffering path, reused verbatim).
  * rejectUnauthorized:false maps to VERIFY_NONE; `ca` replaces the trust
- * anchors; with neither, /etc/ssl/cert.pem stands in for Node's bundled
+ * anchors; with neither, the host trust store stands in for Node's bundled
  * Mozilla roots (SEMANTICS.md documents the divergence). Verify
  * failures surface as Node-shaped 'error' messages on the request
  * ("self-signed certificate", "self-signed certificate in certificate
@@ -336,15 +336,15 @@ typedef struct ScrTlsCli {
   bool verify_recorded;
 } ScrTlsCli;
 
-/* The default trust anchors when no `ca` option is given: the system
- * bundle, standing in for Node's compiled-in Mozilla roots, plus
- * NODE_EXTRA_CA_CERTS. The system bundle is probed once across the distro
- * spellings — /etc/ssl/cert.pem first (macOS ships it; Alpine links it),
- * then Debian/Ubuntu's ca-certificates.crt, Fedora/RHEL's ca-bundle.crt,
- * and openSUSE's ca-bundle.pem. On macOS only the first path exists, so
- * the probe order changes nothing there. A host with none leaves only the
- * optional extra chain. Windows is that host by construction (no PEM
- * bundle ships; the OS store is cert-database-shaped). */
+/* The default trust anchors when no `ca` option is given: the host trust
+ * store, standing in for Node's compiled-in Mozilla roots, plus
+ * NODE_EXTRA_CA_CERTS. Windows certificates live as DER entries across the
+ * machine, enterprise, current-user, and policy ROOT/CA/TrustedPeople store
+ * locations; mbedTLS copies each successfully parsed entry into its own chain.
+ * POSIX hosts probe the established bundle spellings — /etc/ssl/cert.pem
+ * first (macOS ships it; Alpine links it), then Debian/Ubuntu's
+ * ca-certificates.crt, Fedora/RHEL's ca-bundle.crt, and openSUSE's
+ * ca-bundle.pem. */
 static mbedtls_x509_crt scr_tls_system_roots;
 static bool scr_tls_system_roots_loaded = false;
 
@@ -356,6 +356,12 @@ static bool scr_tls_system_roots_loaded = false;
 static mbedtls_x509_crt scr_tls_override_roots;
 static uint64_t scr_tls_override_parsed_gen = 0;
 
+#ifdef _WIN32
+static void scr_tls_add_windows_ca(void *ctx, const unsigned char *der, size_t len) {
+  (void)mbedtls_x509_crt_parse_der((mbedtls_x509_crt *)ctx, der, len);
+}
+#endif
+
 static mbedtls_x509_crt *scr_tls_system_ca(void) {
   const char *pem = NULL;
   size_t pem_len = 0;
@@ -375,6 +381,12 @@ static mbedtls_x509_crt *scr_tls_system_ca(void) {
   if (!scr_tls_system_roots_loaded) {
     scr_tls_system_roots_loaded = true;
     mbedtls_x509_crt_init(&scr_tls_system_roots);
+#ifdef _WIN32
+    /* The shared enumerator applies Windows' effective server-auth EKU
+     * policy before yielding DER. mbedTLS copies every successfully parsed
+     * entry, so the store contexts may die immediately after each callback. */
+    scr_tls_ca_windows_certs(scr_tls_add_windows_ca, &scr_tls_system_roots);
+#else
     static const char *const bundles[] = {
         "/etc/ssl/cert.pem",                  /* macOS, Alpine */
         "/etc/ssl/certs/ca-certificates.crt", /* Debian/Ubuntu */
@@ -384,6 +396,7 @@ static mbedtls_x509_crt *scr_tls_system_ca(void) {
     for (size_t i = 0; i < sizeof bundles / sizeof bundles[0]; i++) {
       if (mbedtls_x509_crt_parse_file(&scr_tls_system_roots, bundles[i]) == 0) break;
     }
+#endif
     const char *extra = NULL;
     size_t extra_len = 0;
     if (scr_tls_ca_extra_pem(&extra, &extra_len) && extra_len > 0) {

package/src/scr_tls_ca.c

@@ -2,28 +2,33 @@
  * rootCertificates, and setDefaultCACertificates (scr_runtime.h has the
  * contracts). Its own link gate ("tlsca." libCalls), deliberately free
  * of mbedTLS: everything here is PEM-BLOCK bookkeeping over the host
- * bundle, so a program that only inspects the CA store keeps the lean
- * link line. scr_tls.c (when it links — cc.ts compiles this unit
- * alongside it) consults scr_tls_ca_default_override for its client
- * trust anchors, which is what makes setDefaultCACertificates LIVE
- * semantics: the next https/tls dial verifies against the replaced set.
+ * roots (plus crypt32 store access on Windows), so a program that only
+ * inspects the CA store never builds the TLS archive. scr_tls.c (when it
+ * links — cc.ts compiles this unit alongside it) consults
+ * scr_tls_ca_default_override for its client trust anchors, which is what
+ * makes setDefaultCACertificates LIVE semantics: the next https/tls dial
+ * verifies against the replaced set.
  *
  * Divergences, documented: the host bundle stands in for Node's
  * compiled-in Mozilla roots ('bundled' and rootCertificates) AND for the
- * platform store ('system') — the same /etc/ssl/cert.pem stance
- * scr_tls.c's anchors established; and set-time validation is PEM-BLOCK
- * shaped (a well-formed block with corrupt DER inside is kept here where
- * Node's X509 parse would drop it — such a cert then fails verification
- * instead, the same observable outcome one step later). Deduplication is
- * byte-exact over the extracted block where Node compares parsed X509
- * identities; re-encoded duplicates of one certificate stay distinct
- * entries, which no equality the tests observe can distinguish without a
- * parser. */
+ * platform store ('system') — Windows' system certificate stores and the POSIX
+ * bundle probe are the same sources scr_tls.c's anchors use; and set-time
+ * validation is PEM-BLOCK shaped (a well-formed block with corrupt DER
+ * inside is kept here where Node's X509 parse would drop it — such a cert
+ * then fails verification instead, the same observable outcome one step
+ * later). Deduplication is byte-exact over the extracted block where Node
+ * compares parsed X509 identities; re-encoded duplicates of one certificate
+ * stay distinct entries, which no equality the tests observe can distinguish
+ * without a parser. */
 #include "scr_runtime.h"
 
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
+#ifdef _WIN32
+#include <windows.h>
+#include <wincrypt.h>
+#endif
 
 /* The per-type caches: +1 held here for the process lifetime (an atexit
  * teardown releases them so the RC audit stays clean). 'default' also
@@ -154,9 +159,121 @@ bool scr_tls_ca_extra_pem(const char **pem, size_t *len) {
   return true;
 }
 
-/* The host bundle, probed in scr_tls.c's documented order. */
+#ifdef _WIN32
+/* Windows can restrict a certificate's purposes in a store property that is
+ * not part of its DER. CertGetEnhancedKeyUsage with flags 0 intersects that
+ * property with the encoded EKU extension. An empty result means either all
+ * purposes (CRYPT_E_NOT_FOUND) or no purposes (ERROR_SUCCESS); every other
+ * API failure is fail-closed too. */
+bool scr_tls_ca_windows_cert_server_auth(const void *cert_context) {
+  PCCERT_CONTEXT cert = (PCCERT_CONTEXT)cert_context;
+  DWORD usage_len = 0;
+  if (!CertGetEnhancedKeyUsage(cert, 0, NULL, &usage_len) || usage_len == 0) {
+    return false;
+  }
+  CERT_ENHKEY_USAGE *usage = malloc((size_t)usage_len);
+  if (usage == NULL) scr_ca_oom();
+  if (!CertGetEnhancedKeyUsage(cert, 0, usage, &usage_len)) {
+    free(usage);
+    return false;
+  }
+  DWORD usage_error = GetLastError();
+  bool allowed = usage->cUsageIdentifier == 0 &&
+      usage_error == CRYPT_E_NOT_FOUND;
+  for (DWORD i = 0; !allowed && usage->rgpszUsageIdentifier != NULL &&
+       i < usage->cUsageIdentifier; i++) {
+    const char *oid = usage->rgpszUsageIdentifier[i];
+    allowed = oid != NULL &&
+        (strcmp(oid, szOID_PKIX_KP_SERVER_AUTH) == 0 ||
+         strcmp(oid, szOID_ANY_ENHANCED_KEY_USAGE) == 0);
+  }
+  free(usage);
+  return allowed;
+}
+
+static void scr_tls_ca_windows_certs_at(
+    DWORD location, const char *store_name, HCERTSTORE seen,
+    ScrTlsCaWindowsCertFn fn, void *ctx) {
+  HCERTSTORE store = CertOpenStore(
+      CERT_STORE_PROV_SYSTEM_A, 0, 0,
+      location | CERT_STORE_OPEN_EXISTING_FLAG | CERT_STORE_READONLY_FLAG,
+      store_name);
+  if (store == NULL) return;
+  PCCERT_CONTEXT cert = NULL;
+  /* CertEnumCertificatesInStore frees the previous context on every call,
+   * including the final NULL result. Each callback must copy DER it keeps. */
+  while ((cert = CertEnumCertificatesInStore(store, cert)) != NULL) {
+    /* The logical stores overlap (notably CurrentUser inherits machine
+     * roots). CERT_STORE_ADD_NEW turns the memory store into a process-local
+     * identity set: only the first allowed context reaches the consumer. */
+    if (scr_tls_ca_windows_cert_server_auth(cert) &&
+        CertAddCertificateContextToStore(
+            seen, cert, CERT_STORE_ADD_NEW, NULL)) {
+      fn(ctx, cert->pbCertEncoded, (size_t)cert->cbCertEncoded);
+    }
+  }
+  (void)CertCloseStore(store, 0);
+}
+
+void scr_tls_ca_windows_certs(ScrTlsCaWindowsCertFn fn, void *ctx) {
+  /* Match Node's Windows system-certificate sources: roots and intermediate
+   * CAs from all five applicable locations, plus explicitly trusted server
+   * certificates from the three local-machine TrustedPeople locations.
+   * A memory store deduplicates their overlapping contents. */
+  typedef struct ScrTlsCaWindowsStore {
+    DWORD location;
+    const char *name;
+  } ScrTlsCaWindowsStore;
+  static const ScrTlsCaWindowsStore stores[] = {
+      {CERT_SYSTEM_STORE_LOCAL_MACHINE, "ROOT"},
+      {CERT_SYSTEM_STORE_LOCAL_MACHINE_GROUP_POLICY, "ROOT"},
+      {CERT_SYSTEM_STORE_LOCAL_MACHINE_ENTERPRISE, "ROOT"},
+      {CERT_SYSTEM_STORE_CURRENT_USER, "ROOT"},
+      {CERT_SYSTEM_STORE_CURRENT_USER_GROUP_POLICY, "ROOT"},
+      {CERT_SYSTEM_STORE_LOCAL_MACHINE, "CA"},
+      {CERT_SYSTEM_STORE_LOCAL_MACHINE_GROUP_POLICY, "CA"},
+      {CERT_SYSTEM_STORE_LOCAL_MACHINE_ENTERPRISE, "CA"},
+      {CERT_SYSTEM_STORE_CURRENT_USER, "CA"},
+      {CERT_SYSTEM_STORE_CURRENT_USER_GROUP_POLICY, "CA"},
+      {CERT_SYSTEM_STORE_LOCAL_MACHINE, "TrustedPeople"},
+      {CERT_SYSTEM_STORE_LOCAL_MACHINE_GROUP_POLICY, "TrustedPeople"},
+      {CERT_SYSTEM_STORE_LOCAL_MACHINE_ENTERPRISE, "TrustedPeople"},
+  };
+  HCERTSTORE seen = CertOpenStore(
+      CERT_STORE_PROV_MEMORY, 0, 0, CERT_STORE_CREATE_NEW_FLAG, NULL);
+  if (seen == NULL) return;
+  for (size_t i = 0; i < sizeof stores / sizeof stores[0]; i++) {
+    scr_tls_ca_windows_certs_at(
+        stores[i].location, stores[i].name, seen, fn, ctx);
+  }
+  (void)CertCloseStore(seen, 0);
+}
+
+static void scr_ca_push_windows_cert(void *ctx, const unsigned char *der, size_t len) {
+  if (len > UINT32_MAX) return;
+  DWORD pem_cap = 0;
+  DWORD flags = CRYPT_STRING_BASE64HEADER | CRYPT_STRING_NOCR;
+  if (!CryptBinaryToStringA(der, (DWORD)len, flags, NULL, &pem_cap) ||
+      pem_cap == 0) {
+    return;
+  }
+  char *pem = malloc((size_t)pem_cap);
+  if (pem == NULL) scr_ca_oom();
+  DWORD pem_len = pem_cap;
+  if (CryptBinaryToStringA(der, (DWORD)len, flags, pem, &pem_len)) {
+    scr_arr_push_ref((ScrArr *)ctx, scr_str_new(pem, (size_t)pem_len));
+  }
+  free(pem);
+}
+#endif
+
+/* The host roots, from the Windows logical store or the POSIX bundle probe
+ * shared with scr_tls.c. */
 static ScrArr *scr_ca_load_host_bundle(void) {
   ScrArr *arr = scr_arr_new(SCR_ELEM_STR, 128);
+#ifdef _WIN32
+  scr_tls_ca_windows_certs(scr_ca_push_windows_cert, arr);
+#else
   static const char *const bundles[] = {
       "/etc/ssl/cert.pem",                  /* macOS, Alpine */
       "/etc/ssl/certs/ca-certificates.crt", /* Debian/Ubuntu */
@@ -171,6 +288,7 @@ static ScrArr *scr_ca_load_host_bundle(void) {
     free(text);
     break; /* first bundle wins, like the anchor probe */
   }
+#endif
   return arr;
 }
 

package/vendor/README.md

@@ -6,7 +6,7 @@
 - Commit: 49e671dd52ff6791295d8161ad3b6da7dc5f6f9d
 - License: ISC (copyright and permission notice reproduced in `src/scr_musl.c`)
 
-The x86_64 register-save/restore and `makecontext` logic is adapted into `src/scr_musl.c`, rather than carried as a separate library, to supply the legacy `ucontext` functions that musl declares but does not implement. It is compiled only for the explicit `x86_64-linux-musl` target and uses musl's public `ucontext_t` layout. The signal-mask compatibility wrapper is deliberately not included: scriptc fibers perform user-space register swaps and do not change a per-fiber signal mask.
+The x86_64 and AArch64 register-save/restore and `makecontext` logic is adapted into `src/scr_musl.c`, rather than carried as a separate library, to supply the legacy `ucontext` functions that musl declares but does not implement. It is compiled for the explicit `x86_64-linux-musl` and `aarch64-linux-musl` targets and uses musl's public `ucontext_t` layouts. The signal-mask compatibility wrapper is deliberately not included: scriptc fibers perform user-space register swaps and do not change a per-fiber signal mask.
 
 ## ryu/