@scriptc/runtime 0.0.8 → 0.0.10

package/src/scr_runtime.h

@@ -48,8 +48,10 @@ void scr_init(void);
  * the host-registered panic sink and abort only as the last resort: before
  * registration, or if the sink returns (the ruled host-contract violation —
  * a conforming sink longjmps to a host frame BELOW the entry, never back
- * into library frames). Messages keep their trailing newline in both lanes so
- * the funnel is a pure indirection over identical bytes. */
+ * into library frames). Messages keep their trailing newline in both lanes;
+ * the library funnel additionally assembles every DETECTED trap into the
+ * structured trap-teaching form before delivery (a message that already
+ * begins with the 0x01 marker passes verbatim) — see ScrLibSinkFn below. */
 _Noreturn void scr_trap(const char *msg);
 _Noreturn void scr_trap_fmt(const char *fmt, ...);
 
@@ -82,7 +84,17 @@ typedef struct ScrBytes ScrBytes;
  * diagnostic code, 2 the trapping symbol as the host linked it, 3 the
  * remediation; a missing or empty field means none; ignore any field past
  * the fourth. Fields are (pointer, length) — never assume NUL termination.
- * A plain-text host may print the whole buffer: the teaching leads it. */
+ * A plain-text host may print the whole buffer: the teaching leads it.
+ *
+ * Every trap the runtime DETECTS arrives structured: the funnel assembles
+ * the baseline human line into field 0 unchanged, a stable code for the
+ * trap kind (the compiler registry's SC4013–SC4019 runtime family,
+ * classified in scr_library.c), the entry symbol recorded by the trapping
+ * entry's prologue, and the profile's remediation for that code when the
+ * program TU's overlay table declares one (the whole fourth field is
+ * absent otherwise). A message that already begins with the marker — a
+ * facade-authored structured throw, or the wrapper's compile-time-
+ * assembled SC4012 contract trap — passes through byte-for-byte. */
 typedef void (*ScrLibSinkFn)(void *ctx, const uint8_t *msg, size_t msg_len,
                               uint64_t address);
 void scr_library_set_sink(ScrLibSinkFn fn, void *ctx); /* latest wins */
@@ -90,8 +102,15 @@ void scr_library_set_sink(ScrLibSinkFn fn, void *ctx); /* latest wins */
 /* Entry prologue: aborts deterministically when the library is poisoned (a
  * trap already fired — no profile entry may run again; recovery is process
  * restart). reset_arena additionally drops the result arena (the
- * auto-reset posture, and the reset/collect entries' shared body). */
-void scr_library_entry(bool reset_arena);
+ * auto-reset posture, and the reset/collect entries' shared body).
+ * entry_symbol is the generated entry's external symbol exactly as the
+ * host linked it (a static string in the program TU): the prologue records
+ * it in the funnel's current-entry slot so a detected trap's structured
+ * message can name the trapping entry — sound as a single static slot
+ * because exactly one core is ever live and entries never nest. Init and
+ * the mode entries (reset, collect) record theirs too; the identity
+ * getters and sink registration touch no runtime and never trap. */
+void scr_library_entry(bool reset_arena, const char *entry_symbol);
 void scr_library_arena_reset(void);
 /* The mode-provided collect entry's body: arena reset + a full cycle
  * collection (snapshot-invariant by construction — collection frees only
@@ -124,6 +143,16 @@ void scr_library_check_exc(void);
  * structured message is length-delimited, never NUL-scanned. */
 _Noreturn void scr_trap_len(const char *msg, size_t len);
 
+/* The runtime-trap overlay table, DEFINED by the generated program TU
+ * (both emissions emit identical data) and consumed by the funnel when it
+ * assembles a detected trap's structured message: flat triples of
+ * (code, teaching-or-NULL, remediation-or-NULL), one per runtime trap code
+ * (SC4013–SC4019 family) the profile declares text for; _len counts
+ * triples. A declared teaching replaces the baseline human line as field 0;
+ * a declared remediation becomes the optional fourth field. */
+extern const char *const scr_library_trap_overlays[];
+extern const size_t scr_library_trap_overlays_len;
+
 /* Marshalling helpers the generated wrappers call (both emissions share
  * these bodies, which is how the two lanes stay identical by
  * construction). Inbound is borrowed-and-copied; outbound values MOVE into
@@ -449,6 +478,9 @@ void scr_undef_global_read(ScrStr *name);
 void scr_error_set_code(ScrError *e, const char *code);
 ScrStr *scr_error_code(ScrError *e);
 void scr_throw_error_msg_code(int kind, const char *message, size_t len, const char *code);
+/* The compiler-resolved Node-parity throw (error.nodeThrow): builtin
+ * error of `kind`, `code` stamped when non-empty. Borrows both. */
+void scr_throw_node_coded(double kind, const ScrStr *code, const ScrStr *msg);
 
 /* ── string methods ─────────────────────────────────────────────────
  * ECMA-262 observable semantics (UTF-16 code units) computed over the
@@ -1552,6 +1584,13 @@ bool scr_stream_push_dyn(ScrStream *s, const ScrDyn *d);       /* borrows d; tag
 bool scr_stream_write_dyn(ScrStream *s, const ScrDyn *d, ScrClosure *cb); /* cb moves */
 ScrPromise *scr_stream_next_chunk(ScrStream *s);
 ScrPromise *scr_stream_next_chunk_dyn(ScrStream *s);
+/* node:stream/promises — the promise forms over the finished/pipeline
+ * machinery above: a pending void promise the terminal watcher settles
+ * (fulfilled on a clean finish, rejected with the finish status
+ * otherwise — the stream's error or ERR_STREAM_PREMATURE_CLOSE).
+ * Streams borrowed; +1 promises. */
+ScrPromise *scr_sp_finished(ScrStream *s);
+ScrPromise *scr_sp_pipeline(double n, ScrStream **streams);
 /* Readable.from(array): +1 fully-seeded object-entry stream (one WHOLE
  * chunk per element — strings or Buffers per the flag; hwm 1, already
  * EOF'd). Borrows arr. */
@@ -2578,6 +2617,28 @@ typedef enum {
    * (the dyn→closure stance): a cycle THROUGH a dyn-boxed promise is
    * merely never collected. */
   SCR_DYN_PROMISE,
+  /* An ISLAND (engine-held) value — the jsval→DOM crossing. Never
+   * produced by the parser — it enters the DOM through the gated
+   * constructor scr_dyn_from_jsval (scr_island.c): an 'any'-typed value
+   * flowing into an 'unknown'/'object'/JS-residue slot. Boxes by
+   * REFERENCE (a retained ScrJsval cell). The constructor SCALAR-
+   * NORMALIZES: engine numbers/strings/booleans/null/undefined convert
+   * to the native DOM kinds at wrap time, so JSVAL nodes only ever hold
+   * engine objects, arrays, and functions (plus the symbol/bigint edge —
+   * kinds the DOM cannot represent at all). Identity is the CELL's
+   * engine value: strict equality routes to the engine's === (two wraps
+   * of one engine value compare equal), and scr_jsval_from_dyn unwraps
+   * the SAME cell back (+1) — the boundary is identity-preserving for
+   * engine-born values. typeof/truthiness/String() route to the engine
+   * per use (scr_dyn_jsval_ops); every DOM walk without an armed route
+   * (JSON, structuredClone, deepStrictEqual, inspect, keyed access,
+   * calls, iteration) throws the LOUD "not supported yet" ladder — never
+   * a silent wrong answer. The dyn→cell edge is NOT visible to the cycle
+   * collector (the dyn→closure stance): a cycle DOM → cell → engine
+   * object → host closure → DOM is merely never collected (the
+   * documented cross-boundary-cycle divergence). Enum position: LAST —
+   * the LLVM backend hardcodes the preceding kind numbers. */
+  SCR_DYN_JSVAL,
 } ScrDynKind;
 
 /* The handle-type tags the DOM can carry. The set is deliberately the
@@ -2597,6 +2658,10 @@ typedef enum {
 typedef struct ScrDyn ScrDyn;
 typedef struct ScrBytes ScrBytes; /* full definition below (C11 repeat) */
 typedef struct ScrClosure ScrClosure; /* full definition below (C11 repeat) */
+typedef struct ScrJsval ScrJsval; /* opaque island cell (C11 repeat; the
+                                   * always-linked DOM core never touches
+                                   * its engine value — only the gated ops
+                                   * installed by scr_dyn_from_jsval do) */
 
 /* The compiler-emitted call glue carried by a SCR_DYN_FUNC box: checks the
  * dyn arguments against the boxed closure's declared parameter types (a
@@ -2622,6 +2687,16 @@ struct ScrDyn {
    * coercion and toString() decode utf8, where a plain Uint8Array joins
    * its elements ("1,2,3"). Everything else ignores it. */
   bool buffer;
+  /* SCR_DYN_OBJ flavor: true for Object.create(null)'s dictionary — an
+   * object with NO prototype. Method dispatch needs nothing (the DOM's
+   * OBJ dispatch is already own-member-only, which IS Node's null-proto
+   * answer); util.inspect prefixes "[Object: null prototype]", and
+   * deepStrictEqual separates it from plain objects (Node compares
+   * prototypes — the bytes `buffer` gate's stance). Keyed reads/writes,
+   * Object.keys/entries/assign, JSON, and typeof are flag-blind, and
+   * fresh copies (structuredClone) DROP the flag — Node's serialization
+   * answers a plain object too. */
+  bool null_proto;
   union {
     bool b;
     double num;
@@ -2649,6 +2724,11 @@ struct ScrDyn {
      * emitted converters guarantee it (direct box for promise<dyn>,
      * adapter promise otherwise). */
     ScrPromise *promise;
+    /* SCR_DYN_JSVAL: the retained island cell (engine objects/arrays/
+     * functions only — the constructor scalar-normalizes; see the kind's
+     * comment). Released through the installed ops so this always-linked
+     * core never references the gated island unit. */
+    struct { ScrJsval *cell; } jsval;
   } v;
 };
 
@@ -2677,8 +2757,24 @@ ScrDyn *scr_dyn_obj_keys(const ScrDyn *v);
  * TypeError; every other kind answers false. */
 bool scr_dyn_has_own(const ScrDyn *v, const ScrStr *key);
 /* Object.assign over DOM values (+1 target back; ToObject TypeError on a
- * nullish target). */
+ * nullish target). Sources copy their own enumerable keys exactly as
+ * Object.keys lists them: OBJ members, ARR/STR/BYTES index keys; nullish
+ * and scalar/function/handle sources copy nothing. */
 ScrDyn *scr_dyn_assign(ScrDyn *target, const ScrDyn *src);
+/* Variadic Object.assign (the spread-source form): the compiler packs
+ * every source into one fresh DOM array — pack_push retains a plain
+ * source in (BORROWED), pack_push_spread flattens a spread source through
+ * the spread-call walk (V8's exact TypeError texts, `what` spelling the
+ * spread expression; MAY THROW pending) — then assign_all copies each
+ * pack element's own members onto the target left to right and answers
+ * the target retained (+1; ToObject TypeError on a nullish target). */
+void scr_dyn_pack_push(ScrDyn *pack, ScrDyn *v);
+void scr_dyn_pack_push_spread(ScrDyn *pack, const ScrDyn *src, const ScrStr *what);
+/* The iterated-path twin — a spread that is NOT the single last argument
+ * takes V8's iterator-protocol failure texts, which describe the VALUE
+ * ("object null", "number 5", ...) instead of spelling the expression. */
+void scr_dyn_pack_push_spread_iter(ScrDyn *pack, const ScrDyn *src);
+ScrDyn *scr_dyn_assign_all(ScrDyn *target, const ScrDyn *sources);
 ScrDyn *scr_dyn_obj_values(const ScrDyn *v);
 ScrDyn *scr_dyn_obj_entries(const ScrDyn *v);
 
@@ -2696,6 +2792,9 @@ ScrDyn *scr_dyn_new_num(double n);
 ScrDyn *scr_dyn_new_str(ScrStr *s);
 ScrDyn *scr_dyn_new_arr(void);
 ScrDyn *scr_dyn_new_obj(void);
+/* Object.create(null): the fresh null-prototype dictionary (see the
+ * null_proto flavor flag above). */
+ScrDyn *scr_dyn_new_obj_null_proto(void);
 /* Wraps a fresh COPY of the u8 payload (the static→dyn boundary copies —
  * DataView-backed sources copy their aliased window). Borrows b. */
 ScrDyn *scr_dyn_new_bytes_copy(const ScrBytes *b);
@@ -2706,6 +2805,20 @@ ScrDyn *scr_dyn_new_buffer_copy(const ScrBytes *b);
  * extraction (`u as Uint8Array`). */
 ScrBytes *scr_dyn_bytes_copy_out(const ScrDyn *d);
 void scr_dyn_arr_push(ScrDyn *arr, ScrDyn *item);
+/* Spread completion for a runtime-arity argument list (`f(...xs)` in the
+ * checked-dynamic tier): flattens `src` into `arr` per JS's spread over the
+ * DOM's iterable kinds — arrays element-by-element (retained), strings by
+ * code POINT (the string iterator), bytes by byte — and throws V8's exact
+ * SPREAD-CALL TypeError for every other kind (pending; callers check):
+ * nullish sources spell the spread expression (`what`), everything else is
+ * the generic "Spread syntax requires ..." text. Borrows src. */
+void scr_dyn_arr_push_spread(ScrDyn *arr, const ScrDyn *src, const char *what);
+/* Destructuring pack over a DOM source: iterable kinds (arrays, strings by
+ * code point, bytes) collect into a fresh array (+1); every other kind
+ * throws V8's destructuring TypeError — `msg` verbatim when non-empty (the
+ * compile-time source spelling), else the runtime kind wording. Borrows
+ * both; NULL with the exception pending on the throw. */
+ScrDyn *scr_dyn_iter_pack(const ScrDyn *src, const ScrStr *msg);
 void scr_dyn_obj_set(ScrDyn *obj, const char *key, size_t key_len, ScrDyn *value);
 /* The checked-dynamic keyed WRITE (`h.k = v` on a dyn receiver): OBJ sets
  * the member (JS: later writes win, insertion order); undefined/null and
@@ -2719,9 +2832,17 @@ ScrStr *scr_dyn_typeof(const ScrDyn *d);
  * enc — utf8 default; strings/numbers/booleans/arrays/objects answer
  * JS-exactly; undefined/null throw the catchable TypeError). Borrows; +1. */
 ScrStr *scr_dyn_to_string(const ScrDyn *d, const ScrStr *enc);
+/* The method-call spelling `d.toString(enc?)`: identical, except a
+ * null-prototype dictionary throws "<what> is not a function" — its
+ * prototype chain has no toString (Node's answer). */
+ScrStr *scr_dyn_to_string_method(const ScrDyn *d, const ScrStr *enc, const ScrStr *what);
 /* JS String() over the DOM kind (units render "null"/"undefined" where
  * scr_dyn_to_string throws) — the web globals' WebIDL ToString. +1. */
 ScrStr *scr_dyn_string_coerce(const ScrDyn *d);
+/* JS ToString WITH the object protocol (user toString/valueOf members
+ * called, their throws propagating) — the WHATWG USVString conversions.
+ * Borrows; +1 or NULL with the exception pending. */
+ScrStr *scr_dyn_string_coerce_js(const ScrDyn *d);
 
 /* `d instanceof TypeError` (and the other builtin error classes) on a
  * checked-dynamic value: the from_error cache resolves the DOM encoding
@@ -2792,6 +2913,10 @@ ScrDyn *scr_dyn_new_func(ScrClosure *clo, ScrDynThunk thunk, uint32_t arity, con
  * boxed thunk (per-arg checks live there). `args` entries are BORROWED;
  * the result is owned (+1), or NULL with the exception pending. */
 ScrDyn *scr_dyn_call(const ScrDyn *d, ScrDyn *const *args, size_t argc, const char *what);
+/* scr_dyn_call over a DOM ARRAY's elements (the spread-application form —
+ * `f(...args)` after the emitted argument array is built): argv IS the
+ * array's items. Borrows both; result owned (+1), or NULL pending. */
+ScrDyn *scr_dyn_apply(const ScrDyn *d, const ScrDyn *args, const char *what);
 
 /* Path spine for dynCheck error messages — a compile-time-shaped linked
  * list the emitted builders stack-allocate per recursion level: `key`
@@ -2888,6 +3013,87 @@ ScrDyn *scr_dyn_new_promise_adapting(ScrPromise *src,
 /* BORROWED peek at the boxed promise; NULL when d is not a promise box. */
 ScrPromise *scr_dyn_promise_of(const ScrDyn *d);
 
+/* ── island values in the DOM (SCR_DYN_JSVAL) ─────────────────────────
+ * Engine routing ops for JSVAL nodes, installed by the gated constructor
+ * (scr_dyn_from_jsval, scr_island.c — the scr_dyn_alloc_promise hook
+ * story: JSVAL nodes exist only after the constructor ran, so the ops
+ * are always installed when a dispatch arm meets the kind, and a
+ * dynamic-free link never references engine symbols). Contracts mirror
+ * the scr_jsval_* entries they route to. */
+typedef struct ScrDynJsvalOps {
+  void (*release)(ScrJsval *cell);
+  ScrStr *(*type_of)(ScrJsval *cell); /* engine typeof; +1, never throws */
+  bool (*truthy)(ScrJsval *cell);     /* engine ToBoolean; never throws */
+  /* String(v) in the engine (the full ToString protocol — user toString
+   * runs, its throw bridges): +1, or NULL with the exception pending. */
+  ScrStr *(*to_str)(ScrJsval *cell);
+  bool (*strict_eq)(ScrJsval *a, ScrJsval *b); /* engine ===; never throws */
+  bool (*is_array)(ScrJsval *cell);   /* Array.isArray, engine-side */
+  bool (*is_error)(ScrJsval *cell);   /* native Error instance, engine-side */
+  /* ── the routed operation set (lane dyn-routing-ops) ────────────────
+   * Each routes to the engine at the moment of use and converts at the
+   * boundary: dyn ARGUMENTS cross through scr_jsval_from_dyn (wrapped
+   * cells unwrap by reference, DOM data deep-copies, DOM FUNC boxes
+   * cross through the generic host-function shim), engine RESULTS come
+   * back through scr_dyn_from_jsval (scalar-normalizing). Fallible ops
+   * bridge the ENGINE's exception catchably and answer NULL/false/-1. */
+  ScrDyn *(*key_get)(ScrJsval *cell, const ScrStr *k); /* o[k]; +1 or NULL pending */
+  bool (*key_set)(ScrJsval *cell, const ScrStr *k, const ScrDyn *v); /* false = pending */
+  ScrDyn *(*call)(ScrJsval *cell, ScrDyn *const *args, size_t argc); /* f(...); +1 or NULL pending */
+  /* o.m(...) — the ENGINE's own prototypes run (JS-exact flatMap/map/
+   * forEach/...). A missing or non-callable member throws Node's
+   * "<what> is not a function" (the call site's spelling — V8's text,
+   * front-run before the engine's terser claim). */
+  ScrDyn *(*invoke)(ScrJsval *cell, const char *method, ScrDyn *const *args, size_t argc, const char *what);
+  bool (*is_nullish)(ScrJsval *cell); /* engine undefined/null; never throws
+                                       * (always false today — the wrap
+                                       * constructor scalar-normalizes) */
+  /* Object.keys/values/entries (mode 0/1/2) as a NATIVE DOM array (+1):
+   * keys are DOM strings, values wrap per element, entries are native
+   * DOM pairs. NULL with the engine's exception pending on refusal. */
+  ScrDyn *(*obj_walk)(ScrJsval *cell, int mode);
+  int (*has_own)(ScrJsval *cell, const ScrStr *k); /* 0/1; -1 = pending */
+  /* Object.assign(target, src) with the ENGINE target: src converts per
+   * member semantics (a wrapped src spreads by reference; DOM data
+   * enters as the usual deep copy). false = pending. */
+  bool (*assign)(ScrJsval *cell, const ScrDyn *src);
+  /* JSON.stringify text of the engine value (+1) — the engine's own
+   * stringify (toJSON protocols, cycle TypeErrors). NULL + pending when
+   * not JSON-representable. */
+  ScrStr *(*to_json)(ScrJsval *cell);
+} ScrDynJsvalOps;
+
+/* The allocator view the gated constructor uses (installs the ops);
+ * ownership of `cell` MOVES in (the caller retains first). */
+ScrDyn *scr_dyn_alloc_jsval(ScrJsval *cell, const ScrDynJsvalOps *ops);
+/* The installed ops (traps on a missing install — impossible unless a
+ * JSVAL node was forged without the constructor). */
+const ScrDynJsvalOps *scr_dyn_jsval_ops(void);
+/* dynTest arms that need the ENGINE's answer on a JSVAL node. Each
+ * answers false for every other kind (callers test unconditionally —
+ * the emitted narrowing tests stay branch-free). Never throw. */
+bool scr_dyn_isl_typeof_is(const ScrDyn *d, const char *name);
+bool scr_dyn_isl_is_array(const ScrDyn *d);
+bool scr_dyn_isl_is_error(const ScrDyn *d);
+/* The JSVAL honesty ladder: when d is a JSVAL node, THROWS the catchable
+ * "<what> on an island value held in 'unknown' is not supported yet"
+ * Error and returns false; every other kind returns false untouched.
+ * Callers gate un-armed operations with it — never a silent wrong
+ * answer (the retired fence-box bug). */
+bool scr_dyn_isl_fence(const ScrDyn *d, const char *what);
+/* The emitted keyed READ's JSVAL arm (sc_dyn_key_get): routes o[k] to the
+ * engine through the installed ops and wraps the result back (+1, scalars
+ * normalized) — the retired `.length -> fence` row. d MUST be a JSVAL
+ * node; NULL with the engine's exception bridged catchably. */
+ScrDyn *scr_dyn_isl_key_get(const ScrDyn *d, const ScrStr *k);
+/* The `??`/optional-chain nullish test over a DOM value: UNDEF/NULL
+ * native, JSVAL through the engine's own test (defensively — the wrap
+ * constructor scalar-normalizes engine null/undefined away), every other
+ * kind false. Never throws. */
+bool scr_dyn_is_nullish(const ScrDyn *d);
+/* scr_dyn_isl_tostr_buf (the display walkers' JSVAL arm) is declared
+ * with the ScrJsonBuf surface below. */
+
 /* ── the ambient receiver (JS `this` inside listener/callback bodies) ──
  * Node calls a handle's listeners with `this` bound to the emitting
  * handle (server.listen(0, function() { this.address().port })), and a
@@ -2932,7 +3138,28 @@ void scr_dyn_check_listener(const ScrDyn *cb, const char *argname);
  * generic ERR_INVALID_ARG_TYPE thrower over it (`expected` is the whole
  * "of type ..." clause). The handle dispatchers' per-arg gates. */
 const char *scr_dyn_specific_type(const ScrDyn *v, char *buf, size_t cap);
+/* ERR_INVALID_ARG_TYPE with the runtime-rendered Received tail (the
+ * error.argTypeThrow libCall). Borrows all three; always throws. */
+void scr_throw_arg_type(const ScrStr *argname, const ScrStr *expected, const ScrDyn *got);
 void scr_dyn_arg_type_fail(const char *argname, const char *expected, const ScrDyn *got);
+/* The property flavor ("The \"options.x\" property must be ...") — the
+ * option-bag validators' gate (error.propTypeThrow). Always throws. */
+void scr_throw_prop_type(const ScrStr *name, const ScrStr *expected, const ScrDyn *got);
+void scr_dyn_prop_type_fail(const char *name, const char *expected, const ScrDyn *got);
+/* Node's ERR_INVALID_ARG_VALUE ("The argument 'encoding' is invalid
+ * encoding. Received 'no'") — reason NULL renders "is invalid".
+ * TypeError; always throws catchably. */
+void scr_dyn_arg_value_fail(const char *name, const char *reason, const ScrDyn *got);
+/* The ERR_INVALID_ARG_VALUE/%j "Received" renderer (inspect-lite:
+ * strings quote, scalars print plain, deep shapes sketch). */
+const char *scr_dyn_inspect_lite(const ScrDyn *v, char *buf, size_t cap);
+/* A ladder's post-validation refuse: throws the compiler-rendered SC2020
+ * statement-fence text verbatim (Node's validation errors run first). */
+void scr_throw_lowering_fence(const ScrStr *msg);
+/* ERR_OUT_OF_RANGE's "Received" number rendering (Node's
+ * addNumericalSeparator underscores past 2^32) — scr_bytes.c's renderer,
+ * shared by the fs/net/tls option-ladder validators. */
+size_t scr_num_received(double v, char out[48]);
 /* Listener-closure builders for the handle dispatchers' .on(...) paths:
  * a runtime-built ScrClosure whose capture is the boxed dyn listener and
  * whose invoke boxes the event tuple back into the DOM and calls through
@@ -3007,6 +3234,12 @@ void scr_jb_put_f64(ScrJsonBuf *b, double v);
  * as \u00XX, everything else (UTF-8 included) verbatim — exactly the JS
  * JSON.stringify escape set for well-formed strings. */
 void scr_jb_put_json_str(ScrJsonBuf *b, const ScrStr *s);
+/* String(v) of a JSVAL node appended into b (the emitted sc_ds display
+ * walkers' arm; scr_dyn_display/to_string route here too): the engine's
+ * ToString. A bridged failure (throwing user toString, a symbol) leaves
+ * the exception PENDING and appends nothing — the loud path, never a
+ * fabricated rendering. */
+void scr_dyn_isl_tostr_buf(ScrJsonBuf *b, const ScrDyn *d);
 /* JSON-serialize a DOM value into the buffer — the sc_jw_* walker for the
  * dyn leaves the compiler cannot type: object members holding undefined
  * DROP, array slots holding undefined print null (exactly Node). */
@@ -3680,11 +3913,27 @@ ScrJsval *scr_jsval_from_f64(double v);
 ScrJsval *scr_jsval_from_bool(bool v);
 ScrJsval *scr_jsval_from_str(const ScrStr *s);
 ScrJsval *scr_jsval_from_json(const ScrStr *json);
-/* A CHECKED-DYNAMIC (DOM) value entering the island — deep copy, data
- * kinds only (a boxed function/handle/promise throws the catchable
- * TypeError). NULL with a pending exception on failure. Borrows d. */
+/* A CHECKED-DYNAMIC (DOM) value entering the island — deep copy for data
+ * kinds (a boxed handle/promise throws the catchable TypeError). A JSVAL
+ * node unwraps to its OWN cell (+1) — an engine value that crossed into
+ * the DOM and back is the SAME engine value, by reference (nested JSVAL
+ * members embed their engine values directly). A boxed FUNCTION crosses
+ * as one generic host-function shim over its uniform ScrDynThunk: the
+ * shim wraps engine arguments as DOM values (scalar-normalizing), calls
+ * the thunk, and converts the DOM result back — each crossing mints a
+ * fresh engine function (identity is not preserved for re-crossings;
+ * SEMANTICS.md). NULL with a pending exception on failure. Borrows d. */
 ScrJsval *scr_jsval_from_dyn(const ScrDyn *d);
 
+/* The jsval→DOM crossing (the IR's dynFromJsval): wraps an island value
+ * as a SCR_DYN_JSVAL node, SCALAR-NORMALIZING first — engine numbers/
+ * strings/booleans/null/undefined convert to the native DOM kinds (the
+ * strict exits cannot fail on engine-reported scalars), so JSVAL nodes
+ * only ever hold engine objects/arrays/functions (and the symbol/bigint
+ * edge). Installs the DOM's engine-routing ops on first use. Borrows
+ * the cell (retains it into the node); +1 out; never throws. */
+ScrDyn *scr_dyn_from_jsval(ScrJsval *cell);
+
 /* Engine operations. Arithmetic yields a fresh cell (NULL = bridged);
  * comparisons yield 0/1 (-1 = bridged); truthy/not never fail. */
 ScrJsval *scr_jsval_binop(int op, ScrJsval *a, ScrJsval *b);
@@ -3720,6 +3969,13 @@ ScrJsval *scr_jsval_call_method(ScrJsval *o, const ScrStr *name, int argc, ScrJs
  * anything else calls with this = o (non-callables throw in the engine). */
 ScrJsval *scr_jsval_opt_call_method(ScrJsval *o, const ScrStr *name, int argc, ScrJsval **argv);
 ScrJsval *scr_jsval_call(ScrJsval *f, int argc, ScrJsval **argv);
+/* Spread application on an island callee — `f(...pre, ...spread)` through
+ * the prelude helper's REAL spread syntax (iterator protocols are the
+ * engine's own; the guards front-run V8's exact spread-call TypeError
+ * texts). `pre` is the engine array of leading fixed arguments; `what` the
+ * spread expression's source spelling (the nullish text spells it).
+ * Borrows everything; +1 out, or NULL with the exception bridged. */
+ScrJsval *scr_jsval_call_spread(ScrJsval *f, ScrJsval *pre, ScrJsval *spread, const ScrStr *what);
 /* `new X(...)` on an island callee (jsOp construct) — JS_CallConstructor.
  * Borrows everything; +1 out, or NULL with the exception bridged. */
 ScrJsval *scr_jsval_construct(ScrJsval *f, int argc, ScrJsval **argv);
@@ -3867,6 +4123,12 @@ void scr_jsval_cast_fail(ScrJsval *v, const ScrStr *target);
  */
 size_t scr_f64_to_str(double x, char *buf);
 
+/* The Ryū digit core (scr_number.c), shared with the Intl en-US number
+ * formatter: the shortest round-tripping digits of a POSITIVE finite
+ * double — value = 0.digits × 10^n, no trailing zeros, NUL-terminated.
+ * Returns k, the digit count (≤ 17). */
+int scr_f64_digits(double x, char digits[18], int *n_out);
+
 /* ToString for template literals / string coercion. Returns +1. */
 ScrStr *scr_f64_to_scrstr(double x);
 ScrStr *scr_bool_to_scrstr(bool b); /* interned "true"/"false" */
@@ -3898,6 +4160,18 @@ bool scr_num_is_safe_integer(double x);
 ScrStr *scr_num_to_exponential(double x);
 ScrStr *scr_num_to_fixed0(double x);
 
+/* Object.is over two numbers — the spec's SameValue on doubles: NaN
+ * equals NaN, +0 differs from -0, everything else is ==. Never throws. */
+bool scr_num_same_value(double a, double b);
+
+/* Intl.NumberFormat("en-US").format(x) / x.toLocaleString("en-US") with
+ * default options: decimal notation, 0–3 fraction digits rounded half-up
+ * on the shortest round-tripping decimal (ICU's rounding input — NOT
+ * toFixed's exact-value rounding), "," grouping every three integer
+ * digits, "∞"/"NaN" texts, "-0" for negative inputs rounding to zero.
+ * en-US is the one embedded locale. Result +1; never throws. */
+ScrStr *scr_intl_num_format_en_us(double x);
+
 /* ── Date, the composed slice (scr_lib.c) ─────────────────────────────
  * Date values have no representation; the runtime surface is exactly
  * Date.now() and toISOString over a millisecond time value. */
@@ -4052,6 +4326,14 @@ typedef enum ScrDataViewGet {
 } ScrDataViewGet;
 double scr_dataview_get(const ScrBytes *b, double byte_off, ScrDataViewGet kind, bool le);
 
+/* DataView setters (the integer/float kinds only — the BIG kinds never
+ * lower: bigint arguments have no representation). Values coerce
+ * JS-exactly: the integer kinds by modular truncation (ToUint32's residue
+ * — the narrower widths store its low bytes, the same 2^width residue),
+ * F32 by double→float round-to-nearest-even. Offsets go through ToIndex
+ * with the getters' one RangeError. */
+void scr_dataview_set(ScrBytes *b, double byte_off, double value, ScrDataViewGet kind, bool le);
+
 /* Element read/write. Any invalid index — negative, fractional, NaN, or
  * out of bounds — TRAPS like the array runtime (SEMANTICS.md documents
  * the divergence from JS's undefined-read/ignored-write). Writes coerce
@@ -4122,6 +4404,49 @@ bool scr_bytes_is_encoding(const ScrStr *s);
 bool scr_bytes_equals(const ScrBytes *a, const ScrBytes *b);
 double scr_bytes_compare(const ScrBytes *src, const ScrBytes *target, double nargs,
                          double ts, double te, double ss, double se);
+/* Node's validateOffset ladder (buffer.js): non-integers (±Infinity and
+ * NaN included) throw the 'an integer' ERR_OUT_OF_RANGE RangeError, the
+ * rest the '>= 0 && <= max' render; max < 0 drops the upper bound.
+ * Returns false after arming the pending throw. */
+bool scr_bytes_validate_off(const char *name, double value, double max);
+/* The checked-dynamic compare/equals validators (scr_bytes_io.c): Node's
+ * argument ladder over DOM-boxed arguments — a non-bytes value throws
+ * ERR_INVALID_ARG_TYPE with the API's own argument name ("buf1"/"buf2",
+ * "otherBuffer", "target"), non-number offsets ERR_INVALID_ARG_TYPE
+ * "of type number", out-of-range numbers the validateOffset RangeError;
+ * an undefined offset takes its Node default. All arguments BORROWED. */
+double scr_buffer_compare_chk(const ScrDyn *a, const ScrDyn *b);
+bool scr_bytes_equals_chk(const ScrBytes *recv, const ScrDyn *other);
+double scr_bytes_compare_chk(const ScrBytes *src, const ScrDyn *target,
+                             const ScrDyn *ts, const ScrDyn *te,
+                             const ScrDyn *ss, const ScrDyn *se);
+/* new Buffer(number, encoding)'s string-arm type error (always throws;
+ * borrowed). */
+ScrBytes *scr_buffer_new_string_fail(const ScrDyn *got);
+/* fs._toUnixTimestamp over a DOM time value: numeric strings and finite
+ * numbers coerce (negatives answer now/1000), the rest throw Node's
+ * ERR_INVALID_ARG_TYPE. Borrowed. */
+double scr_fs_to_unix_timestamp(const ScrDyn *t);
+/* The fs argument-validation ladders (the fs.*Chk libCalls): Node-order
+ * validation over DOM values with Node's exact typed errors; a pass
+ * meets the real operation where one exists (mkdtempSync, macOS
+ * lchmodSync) or the compiler-rendered fence. All borrowed; the Chk
+ * forms without results always leave an exception pending. */
+ScrDyn *scr_fs_exists_async(const ScrDyn *path, const ScrDyn *cb);
+void scr_fs_mkdtemp_chk(const ScrDyn *prefix, const ScrDyn *cb, const ScrStr *fence);
+ScrStr *scr_fs_mkdtemp_sync_chk(const ScrDyn *prefix, const ScrDyn *opts, const ScrStr *fence);
+void scr_fs_read_file_chk(const ScrDyn *path, const ScrDyn *opts, const ScrDyn *cb, const ScrStr *fence);
+void scr_fs_opendir_chk(const ScrDyn *path, const ScrDyn *opts, const ScrStr *fence);
+void scr_fs_watch_file_chk(const ScrDyn *path, const ScrDyn *listener, const ScrStr *fence);
+void scr_fs_lchmod_chk(const ScrDyn *path, const ScrDyn *mode, const ScrDyn *cb, const ScrStr *fence);
+ScrDyn *scr_fs_lchmod_sync_chk(const ScrDyn *path, const ScrDyn *mode);
+ScrPromise *scr_fsp_lchmod_chk(const ScrDyn *path, const ScrDyn *mode);
+void scr_fs_read_chk(const ScrDyn *fd, const ScrDyn *buffer, const ScrDyn *offset,
+                     const ScrDyn *length, const ScrDyn *position, const ScrStr *fence);
+void scr_fs_stream_opts_chk(const ScrDyn *path, const ScrDyn *opts, const ScrStr *fence);
+/* The checked-dynamic max-listeners ladders (scr_events_emitter.c). */
+ScrEmitter *scr_emitter_set_max_chk(ScrEmitter *em, const ScrDyn *n);
+void scr_emitter_set_default_max_chk(const ScrDyn *n, const ScrStr *name);
 double scr_bytes_index_of(const ScrBytes *b, const ScrBytes *needle, double off, double align, bool fwd);
 double scr_bytes_index_of_num(const ScrBytes *b, double v, double off, bool fwd);
 ScrBytes *scr_bytes_fill(ScrBytes *b, const ScrBytes *pattern, double nargs, double offset, double end);
@@ -4386,6 +4711,16 @@ void scr_net_server_on_connection(ScrNetServer *s, ScrClosure *cb /*moves*/, Scr
  * server never fires it, like Node). */
 void scr_net_server_on_secure_connection(ScrNetServer *s, ScrClosure *cb /*moves*/, ScrNetConnFn fn, bool once);
 ScrNetSocket *scr_net_connect(double port, ScrStr *host /*borrowed, nullable*/, ScrClosure *cb /*moves, nullable*/); /* +1 */
+/* connect with a validated autoSelectFamilyAttemptTimeout option: the
+ * budget runs Node's validateInt32-from-1 ladder (ERR_OUT_OF_RANGE /
+ * ERR_INVALID_ARG_TYPE) and is then inert — the single dial has nothing
+ * to time. +1, or NULL with the throw pending. */
+ScrNetSocket *scr_net_connect_attempt(double port, ScrStr *host /*borrowed*/, const ScrDyn *t /*borrowed*/);
+/* net.connect/createConnection over a RUNTIME option bag (computed
+ * keys): Node-order validation (objectMode trio, port, host,
+ * autoSelectFamily, attempt budget), then the compiler-rendered fence —
+ * always leaves an exception pending. Borrowed. */
+void scr_net_connect_opts_chk(const ScrDyn *opts, const ScrStr *fence);
 /* connect with a caller lookup (net.connect({ ..., lookup })): invokes
  * lookup(hostname, options, answer-closure) synchronously; answer_fn is
  * the emitted per-shape thunk that decodes the answer down to
@@ -4600,6 +4935,13 @@ void scr_tls_h2_client_wrap(ScrNetSocket *sock, ScrStr *host /*borrowed*/, bool
  * the default pair, exactly Node. */
 typedef struct ScrSecureCtx ScrSecureCtx;
 ScrSecureCtx *scr_tls_create_secure_context(const char *cert, size_t cert_len, const char *key, size_t key_len); /* +1 */
+/* createSecureContext over a RUNTIME options record: Node's typed option
+ * validations first, then the pem walk (+1, or NULL with the exception
+ * pending). Borrowed. */
+ScrSecureCtx *scr_tls_create_secure_context_dyn(const ScrDyn *opts);
+/* tls.getCACertificates(type): validateString + the documented name set,
+ * then the compiler-rendered fence — always leaves an exception pending. */
+void scr_tls_ca_certs_chk(const ScrDyn *type, const ScrStr *fence);
 ScrSecureCtx *scr_secure_ctx_retain(ScrSecureCtx *c);
 void scr_secure_ctx_release(ScrSecureCtx *c);
 void *scr_secure_ctx_retain_v(void *p);
@@ -5023,6 +5365,13 @@ void scr_dgram_bind(ScrDgramSocket *s, double port, ScrStr *host /*borrowed*/, S
 void scr_dgram_connect(ScrDgramSocket *s, double port, ScrStr *host /*borrowed*/, ScrClosure *cb /*moves, nullable*/);
 void scr_dgram_send_str(ScrDgramSocket *s, ScrStr *data /*borrowed*/, double port, ScrStr *host /*borrowed*/);
 void scr_dgram_send_bytes(ScrDgramSocket *s, ScrBytes *data /*borrowed*/, double port, ScrStr *host /*borrowed*/);
+/* The send argument-validation ladder over DOM arguments (Node's
+ * signature shuffle, slice bounds, list/type contracts, port/address
+ * validation, and the connected-state errors); a fully-validated
+ * unconnected single-payload send RUNS, the rest meet the fence. */
+void scr_dgram_send_chk(ScrDgramSocket *s, const ScrDyn *buffer, const ScrDyn *a1,
+                        const ScrDyn *a2, const ScrDyn *a3, const ScrDyn *a4,
+                        const ScrStr *fence);
 /* address() parts: ip THROWS "Not running" before bind/connect (+1
  * otherwise); family/port are only called after ip succeeded. */
 ScrStr *scr_dgram_addr_ip(ScrDgramSocket *s);     /* +1, may throw */

package/src/scr_stream.c

@@ -683,7 +683,9 @@ static void *scr_stream_read_n(ScrStream *s, double size) {
       st->r.hwm = h;
     }
   }
-  if (!absent && n != 0) st->r.emitted_readable = false;
+  /* Node's read(): `if (n !== 0) state.emittedReadable = false` — the
+   * absent form is NaN there, which also clears; only read(0) keeps it. */
+  if (absent || n != 0) st->r.emitted_readable = false;
   if (!absent && n == 0 && st->r.need_readable &&
       (st->r.length >= st->r.hwm || st->r.ended)) {
     if (st->r.length == 0 && st->r.ended) scr_stream_end_readable(s);
@@ -2148,6 +2150,49 @@ ScrStream *scr_stream_pipeline(double n_d, ScrStream **streams /*borrowed*/,
   return scr_stream_retain(streams[n - 1]);
 }
 
+/* ── node:stream/promises ─────────────────────────────────────────────
+ * The promise forms ride the callback machinery above with a settling
+ * watcher: caps[0] boxes the pending promise; the terminal status
+ * fulfills (NULL) or rejects (the error moves through the exception
+ * cell, the reject-pending pattern). */
+
+static void scr_sp_settle_inv(ScrClosure *cb, ScrStream *s, ScrError *err) {
+  (void)s;
+  ScrPromise *p = scr_box_get_ref(cb->caps[0]); /* +1 */
+  if (err != NULL) {
+    scr_throw_obj(scr_error_retain(err), &scr_error_retain_v, &scr_error_release_v,
+                  scr_error_trace_arg());
+    scr_promise_reject_pending(p);
+  } else {
+    scr_promise_fulfill_void(p);
+  }
+  scr_promise_release(p);
+}
+
+static ScrClosure *scr_sp_watcher(ScrPromise *p /*borrowed*/) {
+  ScrClosure *w = scr_closure_new((void *)&scr_sp_settle_inv, 1);
+  w->caps[0] = scr_box_new_obj(scr_promise_retain_v, scr_promise_release_v, scr_promise_trace_v);
+  scr_box_set_ref(w->caps[0], scr_promise_retain(p));
+  return w;
+}
+
+ScrPromise *scr_sp_finished(ScrStream *s) {
+  ScrPromise *p = scr_promise_new();
+  /* The cleanup closure is the callback form's return value; the promise
+   * form exposes no unhook, so it drops here (the watcher stays parked —
+   * scr_stream_finished retained it into the stream's list). */
+  ScrClosure *cleanup = scr_stream_finished(s, scr_sp_watcher(p), &scr_sp_settle_inv);
+  scr_closure_release(cleanup);
+  return p;
+}
+
+ScrPromise *scr_sp_pipeline(double n, ScrStream **streams) {
+  ScrPromise *p = scr_promise_new();
+  ScrStream *dst = scr_stream_pipeline(n, streams, scr_sp_watcher(p), &scr_sp_settle_inv);
+  scr_stream_release(dst);
+  return p;
+}
+
 /* ── the readable surface ─────────────────────────────────────────────── */
 
 bool scr_stream_push(ScrStream *s, ScrBytes *chunk) {
@@ -2664,10 +2709,12 @@ double scr_stream_prop(ScrStream *s, const char *name) {
  * arrives outside a _read call). */
 static void scr_stream_emit_readable_now(ScrStream *s) {
   ScrStreamState *st = s->st;
-  st->r.emitted_readable = false;
+  /* Node's emitReadable_ clears emittedReadable AFTER the emit (a
+   * 'readable' listener observes true) and only when it really fired. */
   if (!st->destroyed && !st->errored && (st->r.length > 0 || st->r.ended)) {
     scr_stream_emit0(s, "readable");
     if (scr_exc_pending()) return;
+    st->r.emitted_readable = false;
   }
   st->r.need_readable = st->r.flowing != 1 && !st->r.ended &&
                         st->r.length <= st->r.hwm;