@scriptc/runtime 0.0.7 → 0.0.9

package/package.json

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

package/src/scr_bytes.c

@@ -312,6 +312,49 @@ double scr_dataview_get(const ScrBytes *b, double byte_off, ScrDataViewGet kind,
   return 0; /* unreachable */
 }
 
+void scr_dataview_set(ScrBytes *b, double byte_off, double value, ScrDataViewGet kind, bool le) {
+  size_t width = scr_dataview_get_size(kind);
+  /* ToIndex + the view-relative bounds check — the getters' ONE message. */
+  double off = (byte_off != byte_off) ? 0 : trunc(byte_off);
+  if (!(off >= 0) || off > 9007199254740991.0 || off + (double)width > (double)b->len) {
+    static const char msg[] = "Offset is outside the bounds of the DataView";
+    scr_throw_error_msg(SCR_ERR_RANGE, msg, sizeof msg - 1);
+    return;
+  }
+  /* Coerce to the stored bit pattern. The integer kinds share ToUint32's
+   * 2^32 residue (signed/unsigned store the same bits; narrower widths
+   * take the low bytes — 2^width divides 2^32, so the residues agree);
+   * F32 rounds double→float to nearest even, exactly the spec. */
+  uint64_t u = 0;
+  switch (kind) {
+    case SCR_DV_U8:
+    case SCR_DV_I8:
+    case SCR_DV_U16:
+    case SCR_DV_I16:
+    case SCR_DV_U32:
+    case SCR_DV_I32:
+      u = (uint64_t)scr_bytes_to_u32(value);
+      break;
+    case SCR_DV_F32: {
+      float f = (float)value;
+      uint32_t bits;
+      memcpy(&bits, &f, 4);
+      u = bits;
+      break;
+    }
+    case SCR_DV_F64:
+      memcpy(&u, &value, 8);
+      break;
+    default:
+      return; /* BIG kinds never lower (bigint arguments) */
+  }
+  /* Scatter host-independently; le false is the JS big-endian default. */
+  uint8_t *p = b->data + (size_t)off;
+  for (size_t i = 0; i < width; i++) {
+    p[le ? i : width - 1 - i] = (uint8_t)(u >> (8 * i));
+  }
+}
+
 /* ── encodings (u8 only — the compiler routes only u8 receivers here) ──── */
 
 static const char scr_hex_digits[] = "0123456789abcdef";
@@ -886,16 +929,19 @@ ScrBytes *scr_bytes_from_arr(ScrBytesElem elem, const ScrArr *arr) {
 
 static size_t scr_bytes_received(double v, char out[48]); /* the numeric section below */
 
-/* validateOffset(name, 0, max): non-integers are 'an integer', the rest
- * '>= 0 && <= max' (Node spells '&&' here, unlike the read/write
- * families' 'and'). max < 0 means copy's no-upper-bound '>= 0' render. */
-static bool scr_bytes_validate_off(const char *name, double value, double max) {
-  if (floor(value) == value && value >= 0 && (max < 0 || value <= max)) return true;
+/* validateOffset(name, 0, max): non-integers are 'an integer' (Number.
+ * isInteger — ±Infinity render 'an integer' too), the rest '>= 0 && <=
+ * max' (Node spells '&&' here, unlike the read/write families' 'and').
+ * max < 0 means copy's no-upper-bound '>= 0' render. Exported: the
+ * checked-dynamic compare/equals validators (scr_bytes_io.c) run the
+ * same ladder after their own type gate. */
+bool scr_bytes_validate_off(const char *name, double value, double max) {
+  if (isfinite(value) && floor(value) == value && value >= 0 && (max < 0 || value <= max)) return true;
   char recv[48];
   scr_bytes_received(value, recv);
   char msg[160];
   int mlen;
-  if (floor(value) != value) {
+  if (floor(value) != value || !isfinite(value)) {
     mlen = snprintf(msg, sizeof msg,
                     "The value of \"%s\" is out of range. It must be an integer. Received %s",
                     name, recv);
@@ -909,7 +955,7 @@ static bool scr_bytes_validate_off(const char *name, double value, double max) {
                     "The value of \"%s\" is out of range. It must be >= 0 && <= %s. Received %s",
                     name, maxb, recv);
   }
-  scr_throw_error_msg(SCR_ERR_RANGE, msg, (size_t)mlen);
+  scr_throw_error_msg_code(SCR_ERR_RANGE, msg, (size_t)mlen, "ERR_OUT_OF_RANGE");
   return false;
 }
 
@@ -994,7 +1040,7 @@ static ScrBytes *scr_bytes_fill_core(ScrBytes *b, const uint8_t *pat, size_t pat
                                      bool zero_ok, double nargs, double offset, double end) {
   if (patn == 0 && !zero_ok) {
     static const char msg[] = "The argument 'value' is invalid. Received <Buffer >";
-    scr_throw_error_msg(SCR_ERR_TYPE, msg, sizeof msg - 1);
+    scr_throw_error_msg_code(SCR_ERR_TYPE, msg, sizeof msg - 1, "ERR_INVALID_ARG_VALUE");
     return NULL;
   }
   size_t n = (size_t)nargs;
@@ -1065,7 +1111,7 @@ ScrBytes *scr_bytes_swap(ScrBytes *b, double width) {
   if (b->len % w != 0) {
     char msg[64];
     int mlen = snprintf(msg, sizeof msg, "Buffer size must be a multiple of %zu-bits", w * 8);
-    scr_throw_error_msg(SCR_ERR_RANGE, msg, (size_t)mlen);
+    scr_throw_error_msg_code(SCR_ERR_RANGE, msg, (size_t)mlen, "ERR_INVALID_BUFFER_SIZE");
     return NULL;
   }
   for (size_t g = 0; g < b->len; g += w) {
@@ -1244,7 +1290,7 @@ static void scr_bytes_bounds_error(double value, double length, const char *type
                     type ? type : "offset", recv);
   } else if (length < 0) {
     static const char oob[] = "Attempt to access memory outside buffer bounds";
-    scr_throw_error_msg(SCR_ERR_RANGE, oob, sizeof oob - 1);
+    scr_throw_error_msg_code(SCR_ERR_RANGE, oob, sizeof oob - 1, "ERR_BUFFER_OUT_OF_BOUNDS");
     return;
   } else {
     char lenbuf[32];
@@ -1253,7 +1299,7 @@ static void scr_bytes_bounds_error(double value, double length, const char *type
                     "The value of \"%s\" is out of range. It must be >= %d and <= %s. Received %s",
                     type ? type : "offset", type ? 1 : 0, lenbuf, recv);
   }
-  scr_throw_error_msg(SCR_ERR_RANGE, msg, (size_t)mlen);
+  scr_throw_error_msg_code(SCR_ERR_RANGE, msg, (size_t)mlen, "ERR_OUT_OF_RANGE");
 }
 
 /* The shared offset gate: width bytes at offset must lie inside b. */
@@ -1297,7 +1343,7 @@ static bool scr_bytes_check_int(const ScrBytes *b, double value, double offset,
                       "The value of \"value\" is out of range. It must be >= %s and <= %s. Received %s",
                       minb, maxb, recv);
     }
-    scr_throw_error_msg(SCR_ERR_RANGE, msg, (size_t)mlen);
+    scr_throw_error_msg_code(SCR_ERR_RANGE, msg, (size_t)mlen, "ERR_OUT_OF_RANGE");
     return false;
   }
   return scr_bytes_rw_check(b, offset, width);

package/src/scr_bytes_io.c

@@ -7,9 +7,11 @@
 #include "scr_runtime.h"
 
 #include <errno.h>
+#include <math.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
+#include <time.h>
 
 static void scr_bytes_io_oom(void) {
   scr_trap("scriptc: out of memory\n");
@@ -138,7 +140,7 @@ ScrBytes *scr_crypto_random_bytes(double n) {
         msg, sizeof msg,
         "The value of \"size\" is out of range. It must be >= 0 && <= 2147483647. Received %.*s",
         (int)numlen, num);
-    scr_throw_error_msg(SCR_ERR_RANGE, msg, (size_t)mlen);
+    scr_throw_error_msg_code(SCR_ERR_RANGE, msg, (size_t)mlen, "ERR_OUT_OF_RANGE");
     return NULL;
   }
   ScrBytes *b = scr_bytes_new(SCR_BYTES_U8, n);
@@ -158,3 +160,97 @@ bool scr_process_stderr_write_bytes(const ScrBytes *b) {
   fwrite(b->data, 1, b->len * scr_bytes_elem_size(b->elem), stderr);
   return true;
 }
+
+/* ── 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,
+ * '0' offsets, null/object range args). A well-typed dyn still computes
+ * the real answer — validation, not a constant fence. */
+
+/* A bytes payload or the API's own ERR_INVALID_ARG_TYPE (borrowed). */
+static ScrBytes *scr_bytes_chk_u8(const ScrDyn *d, const char *argname) {
+  if (d->kind != SCR_DYN_BYTES) {
+    scr_dyn_arg_type_fail(argname, "an instance of Buffer or Uint8Array", d);
+    return NULL;
+  }
+  return d->v.bytes;
+}
+
+double scr_buffer_compare_chk(const ScrDyn *a, const ScrDyn *b) {
+  ScrBytes *b1 = scr_bytes_chk_u8(a, "buf1");
+  if (!b1) return 0;
+  ScrBytes *b2 = scr_bytes_chk_u8(b, "buf2");
+  if (!b2) return 0;
+  return scr_bytes_compare(b1, b2, 0, 0, 0, 0, 0);
+}
+
+bool scr_bytes_equals_chk(const ScrBytes *recv, const ScrDyn *other) {
+  ScrBytes *o = scr_bytes_chk_u8(other, "otherBuffer");
+  if (!o) return false;
+  return scr_bytes_equals(recv, o);
+}
+
+/* One offset slot: undefined takes the Node default, non-numbers throw
+ * ERR_INVALID_ARG_TYPE "of type number", numbers run validateOffset. */
+static bool scr_bytes_chk_off(const ScrDyn *d, const char *name, double max,
+                              double dflt, double *out) {
+  if (d->kind == SCR_DYN_UNDEF) {
+    *out = dflt;
+    return true;
+  }
+  if (d->kind != SCR_DYN_NUM) {
+    scr_dyn_arg_type_fail(name, "of type number", d);
+    return false;
+  }
+  *out = d->v.num;
+  return scr_bytes_validate_off(name, *out, max);
+}
+
+double scr_bytes_compare_chk(const ScrBytes *src, const ScrDyn *target,
+                             const ScrDyn *ts, const ScrDyn *te,
+                             const ScrDyn *ss, const ScrDyn *se) {
+  ScrBytes *t = scr_bytes_chk_u8(target, "target");
+  if (!t) return 0;
+  double tsv, tev, ssv, sev;
+  if (!scr_bytes_chk_off(ts, "targetStart", 9007199254740991.0, 0, &tsv)) return 0;
+  if (!scr_bytes_chk_off(te, "targetEnd", (double)t->len, (double)t->len, &tev)) return 0;
+  if (!scr_bytes_chk_off(ss, "sourceStart", 9007199254740991.0, 0, &ssv)) return 0;
+  if (!scr_bytes_chk_off(se, "sourceEnd", (double)src->len, (double)src->len, &sev)) return 0;
+  /* Every slot validated or defaulted above; nargs 4 revalidates the
+   * now-known-good numbers (a no-op) and keeps one comparison core. */
+  return scr_bytes_compare(src, t, 4, tsv, tev, ssv, sev);
+}
+
+/* new Buffer(number, encoding) — the deprecated ctor's string arm with a
+ * non-string first argument: Node's exact ERR_INVALID_ARG_TYPE (the
+ * throwing path never fires DEP0005, so compiled silence matches). */
+ScrBytes *scr_buffer_new_string_fail(const ScrDyn *got) {
+  scr_dyn_arg_type_fail("string", "of type string", got);
+  return NULL;
+}
+
+/* fs._toUnixTimestamp — the seconds coercion the utimes family runs on
+ * its time arguments (fs.js's toUnixTimestamp, underscore-exported):
+ * numeric STRINGS pass ToNumber's loose-equality gate (+time == time —
+ * whitespace-only strings answer 0), finite numbers pass (negatives
+ * answer now/1000, Node's "past times" shape), everything else throws
+ * Node's exact ERR_INVALID_ARG_TYPE. Borrowed; the throw is pending on
+ * the dummy 0 return. */
+double scr_fs_to_unix_timestamp(const ScrDyn *t) {
+  if (t->kind == SCR_DYN_STR) {
+    double n = scr_string_to_number(t->v.str);
+    /* +time == time: NaN fails; every parsed number loosely equals its
+     * own source string by construction of ToNumber. */
+    if (n == n) return n;
+  }
+  if (t->kind == SCR_DYN_NUM && isfinite(t->v.num)) {
+    if (t->v.num < 0) {
+      struct timespec ts;
+      clock_gettime(CLOCK_REALTIME, &ts);
+      return ((double)ts.tv_sec * 1000.0 + (double)ts.tv_nsec / 1e6) / 1000.0;
+    }
+    return t->v.num;
+  }
+  scr_dyn_arg_type_fail("time", "an instance of Date or an Time in seconds", t);
+  return 0;
+}

package/src/scr_dyn_handle.c

@@ -1,77 +1,19 @@
 /* The checked-dynamic HANDLE support unit — everything the handle
  * dispatchers (scr_http.c / scr_net.c) and the emitter unit's dyn
- * registrations share BEYOND the DOM core: errors.js's
- * determineSpecificType renderer and the ERR_INVALID_ARG_TYPE throwers
- * (the listener gate), and the runtime-built listener adapter closures
- * whose fire thunks box event tuples back into the DOM. Split out of
- * scr_json.c so handle-free binaries keep their exact size class:
- * cc.ts compiles this unit exactly when a user of it links (the net or
- * emitter gate — http implies net).
+ * registrations share BEYOND the DOM core: the listener gate over the
+ * ERR_INVALID_ARG_TYPE throwers (the throwers themselves live in
+ * scr_json.c beside the DOM core — the always-linked bytes/fs argument
+ * validators call them too), and the runtime-built listener adapter
+ * closures whose fire thunks box event tuples back into the DOM. Split
+ * out of scr_json.c so handle-free binaries keep their exact size
+ * class: cc.ts compiles this unit exactly when a user of it links (the
+ * net or emitter gate — http implies net).
  */
 #include "scr_runtime.h"
 
 #include <stdio.h>
 #include <string.h>
 
-/* errors.js's determineSpecificType over a DOM value — the "Received
- * ..." tail of Node's ERR_INVALID_ARG_TYPE messages. Renders into buf
- * when the shape needs a payload; returns the text either way. */
-const char *scr_dyn_specific_type(const ScrDyn *cb, char *detail, size_t cap) {
-  const char *d = detail;
-  switch (cb->kind) {
-  case SCR_DYN_NULL: d = "null"; break;
-  case SCR_DYN_UNDEF: d = "undefined"; break;
-  case SCR_DYN_OBJ: d = "an instance of Object"; break;
-  case SCR_DYN_ARR: d = "an instance of Array"; break;
-  case SCR_DYN_BYTES: d = "an instance of Uint8Array"; break;
-  case SCR_DYN_FUNC: d = "function"; break; /* callers usually return before this */
-  case SCR_DYN_HANDLE:
-    snprintf(detail, cap, "an instance of %s", scr_dyn_handle_cls(cb));
-    break;
-  case SCR_DYN_PROMISE: d = "an instance of Promise"; break;
-  case SCR_DYN_BOOL:
-    snprintf(detail, cap, "type boolean (%s)", cb->v.b ? "true" : "false");
-    break;
-  case SCR_DYN_NUM: {
-    char num[32];
-    size_t n = scr_f64_to_str(cb->v.num, num);
-    snprintf(detail, cap, "type number (%.*s)", (int)n, num);
-    break;
-  }
-  case SCR_DYN_STR: {
-    const ScrStr *sv = cb->v.str;
-    char insp[32];
-    size_t n = 0;
-    insp[n++] = '\'';
-    for (size_t i = 0; i < sv->len && n < 28; i++) insp[n++] = sv->data[i];
-    if (sv->len + 2 > 28) {
-      n = 25;
-      memcpy(insp + n, "...", 3);
-      n += 3;
-    } else {
-      insp[n++] = '\'';
-    }
-    snprintf(detail, cap, "type string (%.*s)", (int)n, insp);
-    break;
-  }
-  default: d = "an instance of Object"; break;
-  }
-  return d;
-}
-
-/* Node's ERR_INVALID_ARG_TYPE thrower ("The \"chunk\" argument must be
- * of type string or an instance of Buffer or Uint8Array. Received type
- * number (5)") — the handle dispatchers' per-arg gates. `expected` is
- * the full "of type ..."/"an instance of ..." clause. */
-void scr_dyn_arg_type_fail(const char *argname, const char *expected, const ScrDyn *got) {
-  char detail[64];
-  const char *d = scr_dyn_specific_type(got, detail, sizeof detail);
-  char msg[224];
-  int len = snprintf(msg, sizeof msg,
-                     "The \"%s\" argument must be %s. Received %s", argname, expected, d);
-  scr_throw_error_msg_code(SCR_ERR_TYPE, msg, (size_t)len, "ERR_INVALID_ARG_TYPE");
-}
-
 /* Node's ERR_INVALID_ARG_TYPE listener gate (errors.js's
  * determineSpecificType shapes — the scr_emitter_check_listener wording,
  * shared here so the gated units need not link the emitter unit). */

package/src/scr_error.c

@@ -237,6 +237,21 @@ void scr_throw_error_msg_code(int kind, const char *message, size_t len,
                  scr_error_traced ? &scr_error_trace : NULL);
 }
 
+/* A compiler-resolved Node-parity throw (the always-throwing lowered
+ * arms: ERR_INVALID_THIS receivers, ERR_MISSING_ARGS ladders, the
+ * symbol-to-string TypeError): builds the builtin error of `kind` with
+ * `code` stamped when non-empty. Borrows both strings; always throws
+ * (catchably — call sites are compiler-emitted pending checks). */
+void scr_throw_node_coded(double kind, const ScrStr *code, const ScrStr *msg) {
+  ScrError *e = scr_error_new((int)kind, (ScrStr *)msg); /* borrowed in */
+  if (code->len > 0) {
+    scr_str_release(e->code); /* NULL-safe */
+    e->code = scr_str_retain((ScrStr *)code);
+  }
+  scr_throw_obj(e, &scr_error_retain_v, &scr_error_release_v,
+                 scr_error_traced ? &scr_error_trace : NULL);
+}
+
 /* A read of a `declare`d const nothing defines (the bundler-define
  * pattern — __VERSION__): Node running the source throws ReferenceError
  * "<name> is not defined" at the access. Borrows `name`; always throws

package/src/scr_events_emitter.c

@@ -662,6 +662,18 @@ ScrArr *scr_emitter_listeners(ScrEmitter *em, ScrStr *name) {
 
 /* ── max listeners ────────────────────────────────────────────────────── */
 
+/* The checked-dynamic setMaxListeners ladder: non-numbers throw Node's
+ * ERR_INVALID_ARG_TYPE ("The \"setMaxListeners\" argument must be of
+ * type number. Received ..."), numbers run the range gate below.
+ * Borrowed dyn; +1 receiver either way (the pending check unwinds). */
+ScrEmitter *scr_emitter_set_max_chk(ScrEmitter *em, const ScrDyn *n) {
+  if (n->kind != SCR_DYN_NUM) {
+    scr_dyn_arg_type_fail("setMaxListeners", "of type number", n);
+    return scr_emitter_retain(em);
+  }
+  return scr_emitter_set_max(em, n->v.num);
+}
+
 ScrEmitter *scr_emitter_set_max(ScrEmitter *em, double n) {
   if (!(n >= 0)) { /* negatives and NaN — Node's validateNumber */
     char num[32];
@@ -682,6 +694,28 @@ double scr_emitter_get_max(ScrEmitter *em) {
   return scr_emitter_default_max;
 }
 
+/* The checked-dynamic defaultMaxListeners ladder — `name` picks the
+ * message's slot ("setMaxListeners" for the static call,
+ * "defaultMaxListeners" for the module-property assignment, Node's own
+ * split). Borrowed. */
+void scr_emitter_set_default_max_chk(const ScrDyn *n, const ScrStr *name) {
+  if (n->kind != SCR_DYN_NUM) {
+    scr_dyn_arg_type_fail(name->data, "of type number", n);
+    return;
+  }
+  if (!(n->v.num >= 0)) {
+    char num[32];
+    size_t nlen = scr_f64_to_str(n->v.num, num);
+    char msg[128];
+    int len = snprintf(msg, sizeof msg,
+                       "The value of \"%s\" is out of range. It must be >= 0. Received %.*s",
+                       name->data, (int)nlen, num);
+    scr_throw_error_msg_code(SCR_ERR_RANGE, msg, (size_t)len, "ERR_OUT_OF_RANGE");
+    return;
+  }
+  scr_emitter_set_default_max(n->v.num);
+}
+
 void scr_emitter_set_default_max(double n) {
   if (!(n >= 0)) { /* negatives and NaN — Node's validateNumber(n, "setMaxListeners", 0) */
     char num[32];

package/src/scr_exception.c

@@ -181,10 +181,33 @@ ScrStr *scr_caught_to_string(const ScrCaught *c) {
  * contract-shaped failure exactly like a trap. Render the same "Uncaught
  * ..." first line the executable epilogue prints (scr_exc_print_uncaught's
  * arms, buffer-writing), release the payload, and route the text through
- * the trap funnel — one failure channel at the boundary. */
+ * the trap funnel — one failure channel at the boundary. The funnel
+ * (scr_library.c) assembles the rendered line into the structured
+ * trap-teaching form (code SC4013, the trapping entry's symbol) before
+ * delivery; only the 0x01-led verbatim path below bypasses assembly. */
 void scr_library_check_exc(void) {
   if (!scr_exc_pending()) return;
   static char buf[1024]; /* the message is copied out before the payload dies */
+  /* The ratified verbatim rule: a thrown message that ALREADY begins with
+   * the structured trap-teaching marker (0x01) is delivered exactly as
+   * authored — no "Uncaught " prefix, no added newline — which is how a
+   * facade-authored structured teaching rides the throw channel through to
+   * the sink. Both throw idioms qualify: a thrown string, and an Error
+   * whose .message starts with the marker. Everything else keeps the
+   * baseline "Uncaught ..." shape below, whose first byte is printable —
+   * the guarantee the marker's unambiguity rests on. */
+  const ScrStr *marked = NULL;
+  if (scr_exc_kind == SCR_EXC_STR) {
+    marked = (const ScrStr *)scr_exc_payload;
+  } else if (scr_exc_kind == SCR_EXC_OBJ && scr_error_is(scr_exc_payload)) {
+    marked = ((const ScrError *)scr_exc_payload)->message;
+  }
+  if (marked != NULL && marked->len > 0 && (uint8_t)marked->data[0] == 0x01) {
+    size_t take = marked->len > sizeof buf ? sizeof buf : marked->len;
+    memcpy(buf, marked->data, take);
+    scr_exc_reset(); /* the payload is released before the funnel poisons */
+    scr_trap_len(buf, take);
+  }
   size_t n = 0;
   const char prefix[] = "Uncaught ";
   memcpy(buf, prefix, sizeof prefix - 1);

package/src/scr_island.c

@@ -379,6 +379,7 @@ enum {
   ISL_H_DESTRCHECK,
   ISL_H_ITERN,
   ISL_H_ITER,
+  ISL_H_CALLSPREAD,
   ISL_H_COUNT,
 };
 
@@ -417,7 +418,17 @@ static const char isl_prelude[] =
     "else if(typeof v===\"number\")d=\"number \"+v;else if(typeof v===\"boolean\")d=\"boolean \"+v;"
     "else if(typeof v===\"function\")d=\"function\";else d=\"object\";"
     "throw new TypeError(d+\" is not iterable (cannot read property Symbol(Symbol.iterator))\")}"
-    "return v[Symbol.iterator]()}]";
+    "return v[Symbol.iterator]()},"
+    /* ISL_H_CALLSPREAD: spread application (`f(...pre, ...s)` — the
+     * rest-forwarding idiom's call): REAL spread syntax, so iterator
+     * protocols are the engine's own; the guards front-run V8's exact
+     * spread-call TypeError texts (nullish spells the spread expression
+     * `w`, everything else the generic Spread-syntax text). */
+    "(f,p,s,w)=>{if(s===undefined||s===null)"
+    "throw new TypeError(w+\" is not iterable (cannot read property \"+s+\")\");"
+    "if(typeof s[Symbol.iterator]!==\"function\")"
+    "throw new TypeError(\"Spread syntax requires ...iterable[Symbol.iterator] to be a function\");"
+    "return f(...p,...s)}]";
 
 static void isl_free_boot(void);
 static void isl_prom_wraps_teardown(void);
@@ -1274,6 +1285,23 @@ ScrJsval *scr_jsval_call(ScrJsval *f, int argc, ScrJsval **argv) {
   return isl_cell_new(r);
 }
 
+/* Spread application on an island callee (jsOp callSpread) — the prelude
+ * helper's real `f(...pre, ...spread)`, so iterator protocols are the
+ * engine's own and the guards front-run V8's exact spread-call TypeError
+ * texts (`what` is the spread expression's source spelling). Borrows
+ * everything; +1 out, or NULL with the engine exception bridged. */
+ScrJsval *scr_jsval_call_spread(ScrJsval *f, ScrJsval *pre, ScrJsval *spread, const ScrStr *what) {
+  isl_entry();
+  JSValue argv[4] = {f->v, pre->v, spread->v, JS_NewStringLen(isl_ctx, what->data, what->len)};
+  JSValue r = JS_Call(isl_ctx, isl_helpers[ISL_H_CALLSPREAD], JS_UNDEFINED, 4, argv);
+  JS_FreeValue(isl_ctx, argv[3]);
+  if (JS_IsException(r)) {
+    isl_bridge_exception();
+    return NULL;
+  }
+  return isl_cell_new(r);
+}
+
 /* `new X(...)` on an island callee (jsOp construct). Borrows everything;
  * +1 out, or NULL with the engine exception bridged. */
 ScrJsval *scr_jsval_construct(ScrJsval *f, int argc, ScrJsval **argv) {
@@ -1412,8 +1440,27 @@ static JSValue isl_hostfn_invoke(JSContext *ctx, JSValueConst this_val, int argc
   IslHostFn *b = JS_GetOpaque(func_data[0], isl_hostfn_class_id);
   if (!b) return JS_ThrowTypeError(ctx, "detached scriptc host function");
   ScrJsval *cells[ISL_HOSTFN_MAX_ARITY];
-  for (int i = 0; i < b->arity; i++) {
-    cells[i] = isl_cell_new(i < argc ? JS_DupValue(ctx, argv[i]) : JS_UNDEFINED);
+  int ncells;
+  if (b->arity < 0) {
+    /* The ISLAND-REST shape (negative arity = -(leading declared + 1)):
+     * leading params pad/drop like any host call; the trailing cell is a
+     * fresh ENGINE ARRAY of the surplus arguments — the closure's rest
+     * binding IS the engine's own arguments array. */
+    int leading = -b->arity - 1;
+    for (int i = 0; i < leading; i++) {
+      cells[i] = isl_cell_new(i < argc ? JS_DupValue(ctx, argv[i]) : JS_UNDEFINED);
+    }
+    JSValue rest = JS_NewArray(ctx);
+    for (int i = leading; i < argc; i++) {
+      JS_SetPropertyUint32(ctx, rest, (uint32_t)(i - leading), JS_DupValue(ctx, argv[i]));
+    }
+    cells[leading] = isl_cell_new(rest);
+    ncells = leading + 1;
+  } else {
+    for (int i = 0; i < b->arity; i++) {
+      cells[i] = isl_cell_new(i < argc ? JS_DupValue(ctx, argv[i]) : JS_UNDEFINED);
+    }
+    ncells = b->arity;
   }
   bool strayed_before = isl_anchor_strayed;
   isl_host_depth++;
@@ -1429,7 +1476,7 @@ static JSValue isl_hostfn_invoke(JSContext *ctx, JSValueConst this_val, int argc
     isl_anchor_here();
     isl_anchor_strayed = strayed_before;
   }
-  for (int i = 0; i < b->arity; i++) scr_jsval_release(cells[i]);
+  for (int i = 0; i < ncells; i++) scr_jsval_release(cells[i]);
   if (scr_exc_pending()) {
     if (r) scr_jsval_release(r);
     return isl_throw_pending(ctx);
@@ -1443,7 +1490,9 @@ static JSValue isl_hostfn_invoke(JSContext *ctx, JSValueConst this_val, int argc
 ScrJsval *scr_jsval_from_closure(ScrClosure *c, int arity,
                                   ScrJsval *(*adapt)(ScrClosure *, ScrJsval **)) {
   isl_entry();
-  if (arity > ISL_HOSTFN_MAX_ARITY) {
+  /* Negative arity = the island-rest shape; the CELL count is the leading
+   * declared params + the one rest-array slot. */
+  if ((arity < 0 ? -arity : arity) > ISL_HOSTFN_MAX_ARITY) {
     fprintf(stderr, "scriptc: island callback arity %d exceeds %d\n", arity,
             ISL_HOSTFN_MAX_ARITY);
     abort(); /* the frontend fences this; reaching here is a compiler bug */
@@ -1459,7 +1508,7 @@ ScrJsval *scr_jsval_from_closure(ScrClosure *c, int arity,
   JSValue box = JS_NewObjectClass(isl_ctx, isl_hostfn_class_id);
   JS_SetOpaque(box, b);
   JSValueConst data[1] = {box};
-  JSValue fn = JS_NewCFunctionData(isl_ctx, isl_hostfn_invoke, arity, 0, 1, data);
+  JSValue fn = JS_NewCFunctionData(isl_ctx, isl_hostfn_invoke, arity < 0 ? -arity - 1 : arity, 0, 1, data);
   JS_FreeValue(isl_ctx, box); /* fn's func_data holds its own reference */
   return isl_cell_new(fn);
 }
@@ -1717,6 +1766,60 @@ ScrJsval *scr_jsval_obj_lit(int npairs, ScrJsval **kv) {
   return isl_cell_new(o);
 }
 
+/* The engine-native TemplateStringsArray for an island tag call: `kv`
+ * carries n cooked strings then n raw strings — a fresh array whose
+ * `.raw` property holds the raw spellings, exactly the object a tagged
+ * template hands its tag (a JSON marshal would drop `.raw`, and tags
+ * dispatch on it). */
+ScrJsval *scr_jsval_tpl_strings(int n, ScrJsval **kv) {
+  isl_entry();
+  JSValue cooked = JS_NewArray(isl_ctx);
+  JSValue raw = JS_NewArray(isl_ctx);
+  for (int i = 0; i < n; i++) {
+    JS_SetPropertyUint32(isl_ctx, cooked, (uint32_t)i, JS_DupValue(isl_ctx, kv[i]->v));
+    JS_SetPropertyUint32(isl_ctx, raw, (uint32_t)i, JS_DupValue(isl_ctx, kv[n + i]->v));
+  }
+  JS_SetPropertyStr(isl_ctx, cooked, "raw", raw); /* consumes raw */
+  return isl_cell_new(cooked);
+}
+
+/* Spread completion for an island-native literal: copies `src`'s own
+ * enumerable properties onto `obj` — the engine's own Object.assign (the
+ * spec's CopyDataProperties; null/undefined sources spread nothing) — and
+ * answers the target retained (+1). NULL with the exception pending when
+ * a source getter throws. */
+ScrJsval *scr_jsval_obj_spread(ScrJsval *obj, ScrJsval *src) {
+  isl_entry();
+  if (JS_IsNull(src->v) || JS_IsUndefined(src->v)) return scr_jsval_retain(obj);
+  JSValue global = JS_GetGlobalObject(isl_ctx);
+  JSValue object_ctor = JS_GetPropertyStr(isl_ctx, global, "Object");
+  JS_FreeValue(isl_ctx, global);
+  JSValue assign = JS_GetPropertyStr(isl_ctx, object_ctor, "assign");
+  JS_FreeValue(isl_ctx, object_ctor);
+  JSValueConst args[2] = { obj->v, src->v };
+  JSValue r = JS_Call(isl_ctx, assign, JS_UNDEFINED, 2, args);
+  JS_FreeValue(isl_ctx, assign);
+  if (JS_IsException(r)) {
+    isl_bridge_exception();
+    return NULL;
+  }
+  JS_FreeValue(isl_ctx, r); /* assign answers the target itself */
+  return scr_jsval_retain(obj);
+}
+
+/* Getter completion for an island-native literal: defines `key` on `obj`
+ * as an engine GETTER invoking `fn` (a marshaled host function), and
+ * answers the object retained (+1) so builds chain. Enumerable +
+ * configurable, no setter — exactly a JS object-literal `get k() {}`. */
+ScrJsval *scr_jsval_define_getter(ScrJsval *obj, ScrJsval *key, ScrJsval *fn) {
+  isl_entry();
+  JSAtom k = JS_ValueToAtom(isl_ctx, key->v);
+  JS_DefinePropertyGetSet(isl_ctx, obj->v, k, JS_DupValue(isl_ctx, fn->v), JS_UNDEFINED,
+                          JS_PROP_ENUMERABLE | JS_PROP_CONFIGURABLE);
+  JS_FreeAtom(isl_ctx, k);
+  return scr_jsval_retain(obj);
+}
+
 ScrJsval *scr_jsval_arr_lit(int n, ScrJsval **elems) {
   isl_entry();
   JSValue a = JS_NewArray(isl_ctx);