@scriptc/runtime 0.0.11 → 0.0.13

package/package.json

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

package/src/scr_assert.c

@@ -396,15 +396,15 @@ void scr_assert_ref_eq_fn(const ScrClosure *a, const ScrClosure *b, bool negated
 }
 
 /* ── strictEqual / deepStrictEqual over CHECKED-DYNAMIC (dyn) operands ──
- * The DOM carries the value's kind at runtime, so one entry point serves
+ * The checked-dynamic tree carries the value's kind at runtime, so one entry point serves
  * the whole quartet: SameValue for the strict pair (numbers by Object.is,
  * strings by bytes, units by kind, arrays/objects/bytes by node identity,
  * functions by the BOXED CLOSURE — two dyn crossings of one function are
- * the same JS function), a structural DOM walk for the deep pair.
+ * the same JS function), a structural dyn walk for the deep pair.
  *
  * Failure messages reproduce Node's assertion_error.js against the v24
  * sources: inspectValue is a compact:false / sorted:true / depth-1000
- * rendering of the DOM (each entry on its own line, entries sorted by
+ * rendering of the checked-dynamic tree (each entry on its own line, entries sorted by
  * their RENDERED text — Node's `sorted: true` sorts formatted entries),
  * the simple/stacked scalar forms match the static paths byte-for-byte,
  * and composite diffs run the real myers line diff with Node's printer
@@ -415,7 +415,7 @@ void scr_assert_ref_eq_fn(const ScrClosure *a, const ScrClosure *b, bool negated
  * the [Function: name] form, and values rendering past ~4096 lines fall
  * back to the whole-value +/- form without context collapsing. */
 
-/* JS SameValue over two DOM values (Object.is — the strictEqual and
+/* JS SameValue over two dyn values (Object.is — the strictEqual and
  * notStrictEqual comparison). Functions compare by boxed closure: the
  * ScrDyn box is a boundary artifact, the closure IS the JS identity. */
 static bool scr_assert_dyn_same_value(const ScrDyn *a, const ScrDyn *b) {
@@ -449,19 +449,19 @@ static bool scr_assert_dyn_same_value(const ScrDyn *a, const ScrDyn *b) {
   }
 }
 
-/* Node's strict deep equality over two DOM values: kind-wise — Object.is
+/* Node's strict deep equality over two dyn values: kind-wise — Object.is
  * numbers, byte-equal strings, units by kind, per-element arrays,
- * key-set-plus-values objects (DOM keys are unique, so equal lengths and
+ * key-set-plus-values objects (dyn keys are unique, so equal lengths and
  * an a⊆b value walk prove the bijection), brand-aware bytes (the buffer
  * flavor bit IS the Buffer-vs-Uint8Array prototype Node compares first),
  * reference identity for functions (boxed closure). Plain recursion:
- * JSON-origin DOMs are trees; a keyed-write cycle (h.self = h) has no
+ * JSON-origin dyn values are trees; a keyed-write cycle (h.self = h) has no
  * memo here where Node carries one (documented divergence). */
 static bool scr_assert_dyn_deep_eq(const ScrDyn *a, const ScrDyn *b) {
   if (a == b) return true;
   if (a->kind != b->kind) {
     /* A MIXED comparison with an island side (wrapped engine object vs
-     * DOM data): Node walks both structurally — a plain `false` would
+     * dyn data): Node walks both structurally — a plain `false` would
      * mint a fabricated AssertionError for values Node may call equal.
      * Loud fence (the long-tail lane's structural walk). */
     if (a->kind == SCR_DYN_JSVAL || b->kind == SCR_DYN_JSVAL) {
@@ -528,7 +528,7 @@ static bool scr_assert_dyn_deep_eq(const ScrDyn *a, const ScrDyn *b) {
   return false; /* unreachable */
 }
 
-/* ── inspectValue over the DOM (assertion_error.js's inspect options:
+/* ── inspectValue over the checked-dynamic tree (assertion_error.js's inspect options:
  * compact:false, sorted:true, depth 1000, maxArrayLength Infinity) ───── */
 
 #define SCR_ASSERT_CF_DEPTH 1000
@@ -924,7 +924,7 @@ static bool scr_assert_print_myers(ScrAssertBuf *b, const ScrDiffOp *diff, size_
 
 /* ── the dyn entry point ─────────────────────────────────────────────── */
 
-/* Is this DOM kind `typeof == "object" && != null` to assertion_error.js? */
+/* Is this dyn kind `typeof == "object" && != null` to assertion_error.js? */
 static bool scr_assert_dyn_is_object(const ScrDyn *d) {
   return d->kind == SCR_DYN_ARR || d->kind == SCR_DYN_OBJ || d->kind == SCR_DYN_BYTES ||
          d->kind == SCR_DYN_HANDLE || d->kind == SCR_DYN_PROMISE ||
@@ -1095,7 +1095,7 @@ static void scr_assert_dyn_neq_fail(ScrDyn *a, bool deep, ScrStr *msg, bool has_
 }
 
 /* strictEqual / notStrictEqual / deepStrictEqual / notDeepStrictEqual
- * where either operand is a checked-dynamic value (both arrive as DOM
+ * where either operand is a checked-dynamic value (both arrive as dyn
  * values — the frontend boxes a static side). Borrows everything. */
 void scr_assert_eq_dyn(ScrDyn *a, ScrDyn *b, bool negated, bool deep,
                        ScrStr *msg, bool has_msg) {
@@ -1113,7 +1113,7 @@ void scr_assert_eq_dyn(ScrDyn *a, ScrDyn *b, bool negated, bool deep,
 }
 
 /* Node's expectsError over an error-INSTANCE expected (assert.throws/
- * rejects second argument): every key of the expected DOM error (the
+ * rejects second argument): every key of the expected dyn error (the
  * %error marker skipped; name/message/code is the encoding's surface)
  * must deep-strict-equal the caught value's — extra ACTUAL keys are fine
  * (Node walks the expected's keys only). A mismatch fails through the
@@ -1441,7 +1441,7 @@ void scr_assert_iferror_bool(bool v) {
 }
 
 /* The checked-dynamic argument (test/common's mustSucceed wrapper): the
- * DOM kind dispatches — units pass quietly, %error-marked objects (the
+ * dyn kind dispatches — units pass quietly, %error-marked objects (the
  * caughtToDyn encoding) throw with the error's message (its name when
  * the message is empty, Node's rule), everything else throws with the
  * value's inspection. */

package/src/scr_async.c

@@ -106,6 +106,10 @@ struct ScrPromise {
   size_t ncbs, cbs_cap;
   /* Unhandled-rejection tracking: set when rejected, cleared on await. */
   bool rejection_observed;
+  /* Set when the loop-end report delivered THIS promise to
+   * 'unhandledRejection' listeners — a handler attached after that is
+   * Node's 'rejectionHandled' moment (scr_prom_observe below). */
+  bool reported_unhandled;
 };
 
 #ifdef SCR_RC_AUDIT
@@ -187,6 +191,35 @@ ScrPromise *scr_promise_new(void) {
   return p;
 }
 
+/* The 'rejectionHandled' hook (scr_async_dyn.c installs it at listener
+ * registration — the scr_urj_deliver_fn pattern, so listener-free
+ * binaries keep their size class): called when a promise the loop-end
+ * report already delivered as unhandled gains a handler. */
+void (*scr_rjh_notify_fn)(ScrPromise *p) = NULL;
+
+/* Every handler attach funnels here: mark the rejection observed, and
+ * fire Node's 'rejectionHandled' when the attach arrived AFTER the
+ * report delivered this promise to 'unhandledRejection' listeners (the
+ * model's one late-handling window — earlier handling keeps the promise
+ * out of the report entirely). The flag clears on the first attach, so
+ * one report fires at most one 'rejectionHandled' — Node's pairing. */
+static void scr_prom_observe(ScrPromise *p) {
+  p->rejection_observed = true;
+  if (p->reported_unhandled) {
+    p->reported_unhandled = false;
+    if (scr_rjh_notify_fn != NULL) scr_rjh_notify_fn(p);
+  }
+}
+
+/* The attach-time handled mark (scr_async_dyn.c's dyn then/catch with a
+ * rejection handler): Node marks a rejection handled at ATTACH, not when
+ * the reaction runs — and the loop-exhaustion window (a .catch inside an
+ * 'unhandledRejection' listener) has no later fiber turn whose await
+ * could observe it. */
+void scr_promise_mark_handled(ScrPromise *p) {
+  if (p->state == SCR_PROM_REJECTED) scr_prom_observe(p);
+}
+
 ScrPromise *scr_promise_retain(ScrPromise *p) {
   if (p && p->rc != SIZE_MAX) {
     p->rc++;
@@ -272,7 +305,7 @@ struct ScrFiber {
 
 /* ── AsyncLocalStorage (node:async_hooks) ─────────────────────────────
  * Stores are process-lived ids; the CONTEXT is an immutable refcounted
- * snapshot of (store id → DOM value) entries. One ACTIVE SLOT pointer
+ * snapshot of (store id → dyn value) entries. One ACTIVE SLOT pointer
  * (the exc-cell pattern): main owns a static slot, every fiber owns its
  * own field, scr_switch repoints the active slot — so run()'s window
  * rides the fiber across awaits, and a spawned fiber INHERITS the
@@ -855,7 +888,7 @@ static void scr_promise_settle_from(ScrPromise *dst, ScrPromise *src) {
     }
     scr_promise_settle_wake(dst);
   }
-  if (src->state == SCR_PROM_REJECTED) src->rejection_observed = true;
+  if (src->state == SCR_PROM_REJECTED) scr_prom_observe(src);
 }
 
 /* The emitted same-type Promise.race adapter (see raceAdapterFor). */
@@ -1024,7 +1057,7 @@ ScrStr *scr_promise_payload_str(ScrPromise *p) {
   return scr_str_retain((ScrStr *)p->payload);
 }
 /* Thin views for the gated dyn-async TU (scr_async_dyn.c): the payload
- * KIND, whether a REF payload is a DOM value (the dyn adapters), and the
+ * KIND, whether a REF payload is a dyn value (the dyn adapters), and the
  * settled-await primitive (park/hop + rejection re-throw; true =
  * fulfilled). */
 static bool scr_await_settled(ScrPromise *p); /* defined with the await family */
@@ -1201,7 +1234,7 @@ void scr_await_hop(void) { scr_await_yield(); }
 static bool scr_await_settled(ScrPromise *p) {
   if (p->state != SCR_PROM_PENDING) scr_await_yield();
   while (p->state == SCR_PROM_PENDING) scr_await_park(p);
-  p->rejection_observed = true;
+  scr_prom_observe(p);
   if (p->state == SCR_PROM_REJECTED) {
     switch (p->payload_kind) {
     case SCR_EXC_F64: scr_throw_f64(p->f64); break;
@@ -1439,12 +1472,12 @@ ScrPromise *scr_tp_set_immediate(void) {
   return p;
 }
 
-/* ── setImmediate as a first-class DOM value ─────────────────────────
+/* ── setImmediate as a first-class dyn value ─────────────────────────
  * The global passed AS A FUNCTION VALUE into untyped code (the Node-suite
  * traceCallback shape: `channel.traceCallback(setImmediate, 0, ctx, null,
  * cb)`). The minted dyn callable schedules its own immediate that calls
  * args[0] with the remaining arguments (Node's setImmediate(cb, ...args)
- * contract) and answers undefined (the Immediate handle object has no DOM
+ * contract) and answers undefined (the Immediate handle object has no dyn
  * story — clearImmediate over this value is not modeled). A non-function
  * first argument throws Node's ERR_INVALID_ARG_TYPE synchronously. */
 
@@ -2050,7 +2083,7 @@ void scr_loop_set_island_rejections(bool (*fn)(bool print)) {
 }
 
 /* ── process.on('unhandledRejection') ─────────────────────────────────
- * DOM listeners called per never-observed rejection instead of the
+ * dyn listeners called per never-observed rejection instead of the
  * default report below. Node fires the event at end-of-turn; the
  * compiled runtime fires at loop exhaustion, where the ledger is
  * decided — the same values, later (SEMANTICS.md; mustCall-style
@@ -2076,8 +2109,12 @@ bool scr_report_unhandled_rejections(void) {
       if (scr_urj_deliver_fn != NULL) {
         /* Listener dispatch (scr_async_dyn.c installed the hook at
          * registration): the event handles it, like Node — per entry,
-         * no report, exit 0. A listener throw is the uncaught crash. */
+         * no report, exit 0. A listener throw is the uncaught crash.
+         * reported_unhandled arms the 'rejectionHandled' window: a
+         * handler the listener itself attaches fires the sibling event
+         * (scr_prom_observe). */
         p->rejection_observed = true;
+        p->reported_unhandled = true;
         if (!scr_urj_deliver_fn(p)) crashed = true;
       } else if (!any) {
         any = true;
@@ -2118,6 +2155,14 @@ bool scr_report_unhandled_rejections(void) {
     bool island = scr_island_rejections_fn(!any);
     any = any || island;
   }
+  /* An 'unhandledRejection' listener can spawn fibers the exhausted loop
+   * will never run (a .catch attach mints a reaction fiber): they are
+   * abandoned by construction — re-note them so the RC audit's skip
+   * covers their parked state, exactly the loop-teardown accounting. */
+  if (scr_fibers_live > scr_fibers_abandoned) {
+    scr_fibers_abandoned = scr_fibers_live;
+    scr_note_abandoned_fibers(scr_fibers_abandoned);
+  }
   /* main returns 1 on a reported rejection — the 'exit' listeners (atexit)
    * must see that code, like Node's. */
   if (any) scr_exit_code_note(1);

package/src/scr_async_dyn.c

@@ -1,7 +1,7 @@
 /* Checked-dynamic ASYNC surfaces (gated — cc.ts links this TU only when
  * the IR carries the crossing libCalls or dyn dispatch: the scr_dc.c
  * size-class precedent). Everything here rides scr_async.c's public
- * machinery: the DOM-promise reaction helpers (.then/.catch/.finally
+ * machinery: the checked-dynamic tree-promise reaction helpers (.then/.catch/.finally
  * over SCR_DYN_PROMISE, await of a checked-dynamic value, the
  * `new Promise(setImmediate)` constructor), the AsyncLocalStorage API
  * over the fiber-carried snapshots (the always-linked core keeps only
@@ -128,7 +128,7 @@ void scr_als_disable(double id) {
 }
 
 /* run(store, fn, ...args) / exit(fn, ...args): enter (or clear), call the
- * DOM function with the forwarded arguments, restore — the finally, so a
+ * dyn function with the forwarded arguments, restore — the finally, so a
  * throw still restores before propagating. Result +1 or NULL pending. */
 static ScrDyn *scr_als_call_in(ScrAlsCtx *prev, ScrDyn *fn, ScrDyn *args) {
   size_t argc = args->kind == SCR_DYN_ARR ? args->v.arr.len : 0;
@@ -146,59 +146,170 @@ ScrDyn *scr_als_exit_run(double id, ScrDyn *fn, ScrDyn *args) {
   return scr_als_call_in(scr_als_enter_absent(id), fn, args);
 }
 
-static ScrDyn **scr_urj_listeners = NULL;
+/* The two rejection-event registries share one shape: listeners with a
+ * `once` flag (auto-removed after one delivery, Node's once) and
+ * identity-based removal (the offWarning stance). */
+typedef struct {
+  ScrDyn *fn;
+  bool once;
+} ScrRejListener;
+
+static ScrRejListener *scr_urj_listeners = NULL;
 static size_t scr_nurj = 0, scr_urj_cap = 0;
+static ScrRejListener *scr_rjh_listeners = NULL;
+static size_t scr_nrjh = 0, scr_rjh_cap = 0;
 
 static void scr_urj_teardown(void) {
-  for (size_t i = 0; i < scr_nurj; i++) scr_dyn_release(scr_urj_listeners[i]);
+  for (size_t i = 0; i < scr_nurj; i++) scr_dyn_release(scr_urj_listeners[i].fn);
   free(scr_urj_listeners);
   scr_urj_listeners = NULL;
   scr_nurj = scr_urj_cap = 0;
 }
 
-static bool scr_urj_dispatch(ScrPromise *p);
+static void scr_rjh_teardown(void) {
+  for (size_t i = 0; i < scr_nrjh; i++) scr_dyn_release(scr_rjh_listeners[i].fn);
+  free(scr_rjh_listeners);
+  scr_rjh_listeners = NULL;
+  scr_nrjh = scr_rjh_cap = 0;
+}
 
-void scr_process_on_unhandled_rejection(ScrDyn *fn) {
-  if (fn->kind != SCR_DYN_FUNC) {
-    const char *msg = "The \"listener\" argument must be of type function";
-    scr_throw_error_msg_code(SCR_ERR_TYPE, msg, strlen(msg), "ERR_INVALID_ARG_TYPE");
-    return;
+static bool scr_urj_dispatch(ScrPromise *p);
+static void scr_rjh_dispatch(ScrPromise *p);
+
+/* Node's ERR_INVALID_ARG_TYPE for a non-function listener; true when the
+ * value is fine. */
+static bool scr_rej_check_listener(ScrDyn *fn) {
+  if (fn->kind == SCR_DYN_FUNC) return true;
+  const char *msg = "The \"listener\" argument must be of type function";
+  scr_throw_error_msg_code(SCR_ERR_TYPE, msg, strlen(msg), "ERR_INVALID_ARG_TYPE");
+  return false;
+}
+
+static void scr_rej_push(ScrRejListener **list, size_t *n, size_t *cap, ScrDyn *fn, bool once) {
+  if (*n == *cap) {
+    *cap = *cap ? *cap * 2 : 4;
+    *list = realloc(*list, *cap * sizeof **list);
+    if (!*list) scr_ad_oom();
   }
-  if (scr_nurj == scr_urj_cap) {
-    scr_urj_cap = scr_urj_cap ? scr_urj_cap * 2 : 4;
-    scr_urj_listeners = realloc(scr_urj_listeners, scr_urj_cap * sizeof *scr_urj_listeners);
-    if (!scr_urj_listeners) scr_ad_oom();
+  (*list)[(*n)++] = (ScrRejListener){scr_dyn_retain(fn), once};
+}
+
+static void scr_rej_remove(ScrRejListener *list, size_t *n, ScrDyn *fn) {
+  for (size_t i = 0; i < *n; i++) {
+    ScrDyn *l = list[i].fn;
+    bool same = l == fn || (l->kind == SCR_DYN_FUNC && fn->kind == SCR_DYN_FUNC &&
+                            l->v.fn.clo == fn->v.fn.clo);
+    if (same) {
+      scr_dyn_release(l);
+      memmove(list + i, list + i + 1, (*n - i - 1) * sizeof *list);
+      (*n)--;
+      return;
+    }
   }
-  if (scr_nurj == 0) {
+}
+
+/* The hooks arm exactly while their registry is non-empty: Node with
+ * every listener removed (off, or once-consumed) reverts to the default
+ * report/silence, and the report loop consults the hook per promise. */
+static void scr_urj_sync_hook(void) {
+  scr_urj_deliver_fn = scr_nurj > 0 ? scr_urj_dispatch : NULL;
+}
+
+static void scr_rjh_sync_hook(void) {
+  scr_rjh_notify_fn = scr_nrjh > 0 ? scr_rjh_dispatch : NULL;
+}
+
+void scr_process_on_unhandled_rejection(ScrDyn *fn, bool once) {
+  if (!scr_rej_check_listener(fn)) return;
+  static bool teardown_armed = false;
+  if (!teardown_armed) {
+    teardown_armed = true;
     atexit(scr_urj_teardown);
-    scr_urj_deliver_fn = scr_urj_dispatch; /* arm the loop-end report */
   }
-  scr_urj_listeners[scr_nurj++] = scr_dyn_retain(fn);
+  scr_rej_push(&scr_urj_listeners, &scr_nurj, &scr_urj_cap, fn, once);
+  scr_urj_sync_hook();
+}
+
+void scr_process_off_unhandled_rejection(ScrDyn *fn) {
+  scr_rej_remove(scr_urj_listeners, &scr_nurj, fn);
+  scr_urj_sync_hook();
+}
+
+void scr_process_on_rejection_handled(ScrDyn *fn, bool once) {
+  if (!scr_rej_check_listener(fn)) return;
+  static bool teardown_armed = false;
+  if (!teardown_armed) {
+    teardown_armed = true;
+    atexit(scr_rjh_teardown);
+  }
+  scr_rej_push(&scr_rjh_listeners, &scr_nrjh, &scr_rjh_cap, fn, once);
+  scr_rjh_sync_hook();
+}
+
+void scr_process_off_rejection_handled(ScrDyn *fn) {
+  scr_rej_remove(scr_rjh_listeners, &scr_nrjh, fn);
+  scr_rjh_sync_hook();
+}
+
+/* One registry pass: call every listener with `args`, removing once-
+ * listeners BEFORE their call (Node's once removes at dispatch, so a
+ * re-registration inside the listener sticks). The registry is accessed
+ * THROUGH its pointers per step — a listener that registers can realloc
+ * the array mid-pass. Returns false when a listener threw (the caller's
+ * crash path). */
+static bool scr_rej_fire(ScrRejListener **list, size_t *n, ScrDyn **args, size_t argc) {
+  size_t i = 0;
+  bool ok = true;
+  while (i < *n && ok) {
+    /* Own +1 across the call: a once-removal (here) or the listener
+     * removing itself (off inside the body) must not free a running
+     * function. */
+    ScrDyn *fn = scr_dyn_retain((*list)[i].fn);
+    if ((*list)[i].once) {
+      scr_dyn_release((*list)[i].fn);
+      memmove(*list + i, *list + i + 1, (*n - i - 1) * sizeof **list);
+      (*n)--;
+    } else {
+      i++;
+    }
+    ScrDyn *r = scr_dyn_call(fn, args, argc, "listener");
+    if (r == NULL) ok = false;
+    else scr_dyn_release(r);
+    scr_dyn_release(fn);
+  }
+  return ok;
 }
 
 /* Dispatch one unhandled rejection to the registered listeners —
  * (reason, promise), Node's signature. A listener throw is an uncaught
- * exception (Node crashes there too): print it and exit 1. Returns
- * false on that crash path. */
+ * exception (Node crashes there too): the caller prints it and exits 1.
+ * A once-consumed-to-empty registry disarms the hook on the way out, so
+ * the report's NEXT promise takes the default print — Node's
+ * listener-less behavior. */
 static bool scr_urj_dispatch(ScrPromise *p) {
   ScrDyn *reason = scr_promise_reason_dyn(p);
   ScrDyn *boxed = scr_dyn_new_promise(p);
   ScrDyn *args[2] = {reason, boxed};
-  bool ok = true;
-  for (size_t i = 0; i < scr_nurj && ok; i++) {
-    ScrDyn *r = scr_dyn_call(scr_urj_listeners[i], args, 2, "listener");
-    if (r == NULL) ok = false;
-    else scr_dyn_release(r);
-  }
+  bool ok = scr_rej_fire(&scr_urj_listeners, &scr_nurj, args, 2);
   scr_dyn_release(reason);
   scr_dyn_release(boxed);
+  scr_urj_sync_hook();
   return ok;
 }
 
+/* 'rejectionHandled' delivery — (promise), Node's payload. A listener
+ * throw propagates as a pending exception through the attach site. */
+static void scr_rjh_dispatch(ScrPromise *p) {
+  ScrDyn *boxed = scr_dyn_new_promise(p);
+  (void)scr_rej_fire(&scr_rjh_listeners, &scr_nrjh, &boxed, 1);
+  scr_dyn_release(boxed);
+  scr_rjh_sync_hook(); /* a once-consumed-to-empty registry disarms */
+}
+
 /* `new Promise(setImmediate)` (the Node-suite early-exit shape): the
  * executor IS setImmediate, so resolve rides the immediate queue — a
- * fresh promise an armed immediate fulfills with the undefined DOM value
- * (the executor's resolve receives no argument; the DOM payload keeps
+ * fresh promise an armed immediate fulfills with the undefined dyn value
+ * (the executor's resolve receives no argument; the dyn payload keeps
  * promise<dyn> awaiters honest and void awaiters ignore it). +1. */
 static void scr_imm_promise_thunk(ScrClosure *self) {
   ScrPromise *p = (ScrPromise *)scr_box_get_ref(self->caps[0]);
@@ -216,12 +327,12 @@ ScrPromise *scr_immediate_promise(void) {
   return p;
 }
 
-/* ── .then/.catch/.finally over DOM promises (scr_dyn_invoke's promise
+/* ── .then/.catch/.finally over dyn promises (scr_dyn_invoke's promise
  * arm and the dc tracePromise reactions) ──────────────────────────────
  * One reaction fiber per registration: it awaits src (the settled-await
  * microtask hop keeps JS's ordering — reactions never run synchronously
- * inside settle), runs the DOM handler, and settles dst. A handler
- * returning a DOM promise is ADOPTED (awaited in a loop, like JS's
+ * inside settle), runs the checked-dynamic tree handler, and settles dst. A handler
+ * returning a dyn promise is ADOPTED (awaited in a loop, like JS's
  * resolve). Non-callable handlers pass the settlement through (JS's
  * PromisePrototypeThen over non-function reactions). The fiber's own
  * promise is dropped unobserved — the entry consumes every exception
@@ -258,7 +369,7 @@ static void scr_dyn_then_entry(ScrFiber *self, void *ap) {
         scr_promise_fulfill_ref(a->dst, scr_dyn_retain(v), scr_dyn_retain_v, scr_dyn_release_v, NULL);
       }
     } else {
-      /* Adopt DOM-promise results (JS's resolve walk). */
+      /* Adopt dyn-promise results (JS's resolve walk). */
       while (r != NULL && r->kind == SCR_DYN_PROMISE) {
         ScrDyn *inner = scr_await_dyn(r->v.promise);
         scr_dyn_release(r);
@@ -289,6 +400,11 @@ static void scr_dyn_then_entry(ScrFiber *self, void *ap) {
 }
 
 ScrDyn *scr_dyn_promise_then(ScrPromise *src, ScrDyn *onf, ScrDyn *onr, ScrDyn *onfin) {
+  /* A rejection HANDLER marks the source handled at attach (Node's
+   * moment; the reaction fiber's await re-marks harmlessly) — this is
+   * also what lets a .catch inside an 'unhandledRejection' listener fire
+   * 'rejectionHandled' when no fiber turn remains. */
+  if (onr != NULL) scr_promise_mark_handled(src);
   ScrDynThenPack *a = malloc(sizeof *a);
   if (!a) scr_ad_oom();
   a->src = scr_promise_retain(src);
@@ -301,7 +417,7 @@ ScrDyn *scr_dyn_promise_then(ScrPromise *src, ScrDyn *onf, ScrDyn *onr, ScrDyn *
   scr_promise_release(waiter); /* the entry never rejects; nobody awaits it */
   return boxed;
 }
-/* `await v` where v is a CHECKED-DYNAMIC value: a DOM promise adopts
+/* `await v` where v is a CHECKED-DYNAMIC value: a dyn promise adopts
  * (the boxed promise awaits — rejections re-throw); every other kind is
  * JS's await-of-a-non-thenable — one microtask hop, the value itself
  * (+1). Thenable ADOPTION (a plain object carrying a then method) is not
@@ -314,14 +430,14 @@ ScrDyn *scr_await_dyn_value(ScrDyn *v) {
 
 /* ── process warnings (emitWarning + the 'warning' event) ─────────────
  * Gated with the rest of this TU (a deprecation-emitting unit's gate
- * must imply the dynAsync link). Listeners are DOM functions; emission
+ * must imply the dynAsync link). Listeners are dyn functions; emission
  * is SYNCHRONOUS at the
  * call (Node defers a tick through nextTick — the MaxListenersExceeded
  * precedent, SEMANTICS.md 138) and the default stderr report always
  * prints (Node's own bootstrap listener; a compiled binary has no
- * --no-warnings). The warning VALUE is the DOM error encoding built over
+ * --no-warnings). The warning VALUE is the dyn error encoding built over
  * an ScrError (identity-cached, so a listener comparing two deliveries
- * of one warning sees one object); a string `detail` joins the DOM node
+ * of one warning sees one object); a string `detail` joins the dyn node
  * and the report's second line, exactly Node. */
 static ScrDyn **scr_warn_listeners = NULL;
 static size_t scr_nwarn = 0, scr_warn_cap = 0;
@@ -366,7 +482,7 @@ void scr_process_off_warning(ScrDyn *fn) {
   }
 }
 
-/* Dispatch + the default stderr report over a built warning DOM node.
+/* Dispatch + the default stderr report over a built warning dyn node.
  * Borrowed. A listener throw propagates (the dc publish stance). */
 static void scr_warning_dispatch(ScrDyn *w) {
   for (size_t i = 0; i < scr_nwarn; i++) {
@@ -415,7 +531,7 @@ static void scr_warn_bad_arg(const char *arg, const char *want) {
   scr_throw_error_msg_code(SCR_ERR_TYPE, buf, (size_t)n, "ERR_INVALID_ARG_TYPE");
 }
 
-/* process.emitWarning(...) — Node's full argument grammar over DOM
+/* process.emitWarning(...) — Node's full argument grammar over dyn
  * values: (warning: string | Error), then for string warnings a type
  * string / ctor function / options object ({type, code, detail}) second
  * and a code string / ctor function third. Wrong kinds throw Node's
@@ -487,11 +603,11 @@ void scr_process_emit_warning(ScrDyn *args) {
 
 
 
-/* A caught-exception snapshot as a DOM value — identity-preserving for
- * DOM payloads (a dyn-thrown value is retained, not copied), the
+/* A caught-exception snapshot as a dyn value — identity-preserving for
+ * dyn payloads (a dyn-thrown value is retained, not copied), the
  * identity-cached %error encoding above for Error-family objects,
  * scalars by value, the type-erased empty object for the rest
- * (SEMANTICS.md 67). Shared by the dc trace choreography, the DOM
+ * (SEMANTICS.md 67). Shared by the dc trace choreography, the checked-dynamic tree
  * promise reactions, and the unhandled-rejection dispatch. Borrows the
  * box; result +1. */
 ScrDyn *scr_caught_to_dyn(const ScrCaught *c) {
@@ -510,8 +626,8 @@ ScrDyn *scr_caught_to_dyn(const ScrCaught *c) {
   }
 }
 
-/* Await a DOM-CROSSING promise (SCR_DYN_PROMISE's boundary contract —
- * dyn or void fulfillment): the payload as a DOM value (+1; a void
+/* Await a dyn-CROSSING promise (SCR_DYN_PROMISE's boundary contract —
+ * dyn or void fulfillment): the payload as a dyn value (+1; a void
  * fulfillment answers the undefined value, and the defensive scalar arms
  * cover payload kinds a direct box could theoretically carry), or NULL
  * with the rejection re-thrown into the awaiter. */
@@ -528,7 +644,7 @@ ScrDyn *scr_await_dyn(ScrPromise *p) {
   }
   case SCR_EXC_REF: {
     void *v = scr_promise_payload_ref(p);
-    if (v) return (ScrDyn *)v; /* the DOM contract: a retained dyn */
+    if (v) return (ScrDyn *)v; /* the dyn contract: a retained dyn */
     return scr_dyn_retain(scr_dyn_undefined());
   }
   default:
@@ -536,7 +652,7 @@ ScrDyn *scr_await_dyn(ScrPromise *p) {
   }
 }
 
-/* The rejection reason as a DOM value — the scr_caught_to_dyn stances
+/* The rejection reason as a dyn value — the scr_caught_to_dyn stances
  * over a promise's payload slot (identity-preserving for dyn-thrown
  * values and %Error instances). */
 ScrDyn *scr_promise_reason_dyn(const ScrPromise *p) {
@@ -573,10 +689,10 @@ ScrDyn *scr_promise_reason_dyn(const ScrPromise *p) {
   }
 }
 
-/* ── promises in the DOM (SCR_DYN_PROMISE) ────────────────────────────
+/* ── promises in the checked-dynamic tree (SCR_DYN_PROMISE) ────────────────────────────
  * Reference boxes over the fiber machinery's ScrPromise (scr_runtime.h's
  * design note). The boundary contract — a boxed promise settles with a
- * DOM payload — is the CALLERS' to keep: the compiler's converters box
+ * dyn payload — is the CALLERS' to keep: the compiler's converters box
  * promise<dyn> directly and every other inner type through the adapting
  * constructor below. */
 
@@ -588,7 +704,7 @@ ScrDyn *scr_dyn_new_promise(ScrPromise *p) {
 
 /* The typed-inner box: a fresh destination promise parked on `src`
  * through the Promise.race cb-waiter machinery — `adapt` (emitted,
- * per-inner-type) converts the fulfillment payload into a DOM value and
+ * per-inner-type) converts the fulfillment payload into a dyn value and
  * fulfills the destination; rejections copy raw inside the machinery and
  * count as HANDLED on src (the box is the tracked promise, like a JS
  * .then chain). Already-settled sources adapt inline. Borrows src; +1. */

package/src/scr_bytes_io.c

@@ -61,7 +61,7 @@ ScrBytes *scr_fs_read_file_bytes(ScrStr *path) {
  * utf8 answers a string, Node's other real encodings meet the loud
  * not-supported ladder, unknown names throw ERR_UNKNOWN_ENCODING, and an
  * options object dispatches on its `encoding` member (Node's form). +1
- * DOM value, or NULL with the exception pending. */
+ * dyn value, or NULL with the exception pending. */
 ScrDyn *scr_fs_read_file_sync_dyn(ScrStr *path, const ScrDyn *enc) {
   if (enc->kind == SCR_DYN_OBJ) {
     ScrDyn *ev = scr_dyn_obj_get((ScrDyn *)enc, "encoding", 8); /* borrowed */
@@ -166,7 +166,7 @@ bool scr_process_stderr_write_bytes(const ScrBytes *b) {
 
 /* ── the checked-dynamic Buffer compare/equals validators ──────────────
  * Node's argument ladders for buf.equals / buf.compare / Buffer.compare
- * over DOM-boxed arguments (the invalid-input probes: string needles,
+ * over dyn-boxed arguments (the invalid-input probes: string needles,
  * '0' offsets, null/object range args). A well-typed dyn still computes
  * the real answer — validation, not a constant fence. */
 
@@ -260,7 +260,7 @@ double scr_fs_to_unix_timestamp(const ScrDyn *t) {
 
 /* ── the fs argument-validation ladders (checked-dynamic lane) ─────────
  * Each fs.*Chk libCall replicates its API's Node-order validation over
- * DOM values and throws Node's exact typed errors; when every validation
+ * dyn values and throws Node's exact typed errors; when every validation
  * passes, the honest tail runs — the real operation where one exists
  * (mkdtempSync, lchmodSync on macOS), the compiler-rendered SC2020 fence
  * otherwise (scr_throw_lowering_fence). All arguments borrowed. */
@@ -282,7 +282,7 @@ static bool scr_fs_cb_chk(const ScrDyn *cb, const char *name) {
 }
 
 /* getValidatedPath: strings and Buffers pass (URL instances never reach
- * these ladders — the DOM has no URL kind here, and Node would accept
+ * these ladders — the checked-dynamic tree has no URL kind here, and Node would accept
  * only file: URLs anyway). */
 static bool scr_fs_path_chk(const ScrDyn *p, const char *name) {
   if (p->kind == SCR_DYN_STR || p->kind == SCR_DYN_BYTES) return true;
@@ -522,7 +522,7 @@ static void scr_fs_lchmod_apply(const ScrDyn *path, const ScrDyn *mode) {
 }
 #endif
 
-/* Answers the DOM undefined (+1) on success — lchmodSync's JS value, so
+/* Answers the dyn undefined (+1) on success — lchmodSync's JS value, so
  * return-position uses lower; NULL with the exception pending. */
 ScrDyn *scr_fs_lchmod_sync_chk(const ScrDyn *path, const ScrDyn *mode) {
   if (!scr_fs_lchmod_defined("fs.lchmodSync")) return NULL;