@scriptc/runtime 0.0.21 → 0.0.23

package/src/scr_runtime.h

@@ -197,9 +197,15 @@ void scr_library_bytes_out(ScrBytes *b, const uint8_t **out, size_t *out_len);
  * collection walks the buffer (markGray: trial-decrement internal edges;
  * scan: restore externally-referenced subgraphs; collectWhite: free the
  * dead cycle members, releasing only edges that LEAVE the white set).
- * Collection points: program exit (before the RC audit), event-loop
- * quiescence, and a root-buffer threshold (SCR_CYCLE_THRESHOLD env var,
- * default 256). There is no concurrent or incremental collection.
+ * It is GENERATIONAL: each header carries a generation, a pass names the
+ * oldest one it will walk, and objects that survive a pass are promoted out
+ * of the nursery so later nursery passes never re-walk them. That is what
+ * keeps a pass proportional to recent allocation rather than to the whole
+ * live heap — see the generation note in scr_cycle.c for the soundness
+ * argument and the schedule. Collection points: program exit (before the RC
+ * audit), event-loop quiescence, and the per-generation triggers.
+ * SCR_CYCLE_THRESHOLD pins the nursery trigger to a fixed candidate count.
+ * There is no concurrent or incremental collection.
  *
  * Contract for trace/teardown pairs (the compiler emits them for shapes,
  * the runtime owns its own): trace(obj) visits exactly the strong
@@ -214,16 +220,44 @@ typedef void (*ScrTraceVisit)(void *child, void *ctx);
 typedef void (*ScrTraceFn)(void *obj, ScrTraceVisit visit, void *ctx);
 typedef void (*ScrCycFreeFn)(void *obj);
 
-enum { SCR_CYC_BLACK = 0, SCR_CYC_PURPLE = 1, SCR_CYC_GRAY = 2, SCR_CYC_WHITE = 3 };
+/* DOOMED is WHITE that collectWhite has already gathered: it stops the
+ * gather recursing twice, and distinguishes "about to be freed" from a
+ * survivor for the re-buffering step (see scr_cycle.c). */
+enum {
+  SCR_CYC_BLACK = 0, SCR_CYC_PURPLE = 1, SCR_CYC_GRAY = 2, SCR_CYC_WHITE = 3,
+  SCR_CYC_DOOMED = 4
+};
+
+/* Generations. A candidate sits in the buffer named by its own `gen`, and a
+ * pass walks only objects at or below the generation it collects. */
+enum { SCR_CYC_NURSERY = 0, SCR_CYC_MATURE = 1, SCR_CYC_NGENS = 2 };
 
 typedef struct ScrCycHdr {
   ScrTraceFn trace;
   ScrCycFreeFn free_fn;
   uint32_t color;    /* SCR_CYC_* */
-  uint32_t buffered; /* 1 = sitting in the candidate-root buffer */
+  uint16_t buffered; /* 1 = sitting in its generation's candidate buffer */
+  uint16_t gen;      /* SCR_CYC_NURSERY..SCR_CYC_MATURE (the walk filter) */
   size_t buf_index;  /* position there (O(1) removal when rc hits 0) */
 } ScrCycHdr;
 
+/* This layout is an ABI, not an implementation detail: the LLVM backend
+ * inlines scr_cyc_mark_live as a raw `store i32 0` at obj-16 (it is a
+ * static inline here, so there is no symbol to call) and reaches the header
+ * at obj-32. Three sites emit it — llvm/shapes.ts, llvm/classes.ts,
+ * llvm/emitter.ts. Nothing but `color` may share those four bytes: a field
+ * placed in them is silently zeroed by every retain, which is invisible to
+ * the type system and to the C compiler. Hence the assertions. */
+_Static_assert(sizeof(ScrCycHdr) == 32, "LLVM backend reads the header at obj-32");
+_Static_assert(offsetof(ScrCycHdr, color) == 16,
+               "LLVM backend's inlined mark-live stores i32 0 at obj-16");
+_Static_assert(sizeof(((ScrCycHdr *)0)->color) == 4,
+               "mark-live is an i32 store: color must own all four bytes");
+_Static_assert(SCR_CYC_BLACK == 0,
+               "the emitted mark-live stores the LITERAL 0, not the enumerator "
+               "— reordering the colors would make every compiled retain write "
+               "the wrong one");
+
 static inline ScrCycHdr *scr_cyc_hdr(void *obj) { return (ScrCycHdr *)obj - 1; }
 
 /* Zeroed allocation with a cycle header in front; returns the OBJECT
@@ -243,9 +277,18 @@ static inline void scr_cyc_mark_live(void *obj) {
   scr_cyc_hdr(obj)->color = SCR_CYC_BLACK;
 }
 
-/* Run one full trial-deletion pass over the buffered candidates now. */
+/* Full sweep: trial-deletion passes over EVERY generation, to a fixpoint.
+ * This is the exit / session-reset entry point (the RC audit runs straight
+ * after and wants nothing reclaimable left), and it costs a walk of the
+ * live heap — do not put it on a per-turn path. */
 void scr_collect_cycles(void);
 
+/* One pass on the normal generational schedule, for callers that reach a
+ * natural collection point rather than a threshold (the event loop between
+ * turns). Cheap: usually a nursery pass; a waiting mature backlog ages into
+ * a bounded full pass so sparse roots cannot float forever. */
+void scr_cyc_collect_scheduled(void);
+
 /* ── class hierarchies (single inheritance) ───────────────────────────
  * Classes in an `extends` hierarchy share a two-word object prefix: the
  * usual `size_t rc`, then a pointer to the class's static vtable (emitted
@@ -2416,7 +2459,10 @@ ScrStr *scr_path_win32_to_namespaced_path(ScrStr *path);
  * (failure throws the path-less "EBADF: bad file descriptor, close").
  * The pair behind spawn's fd-stdio form. */
 double scr_fs_open(ScrStr *path, ScrStr *flags);
-double scr_fs_read_sync(double fd, ScrBytes *buf, double offset, double length);
+/* position == -1 reads from and advances the descriptor's current offset;
+ * nonnegative positions leave that offset unchanged (pread/ReadFile seam). */
+double scr_fs_read_sync(double fd, ScrBytes *buf, double offset, double length,
+                        double position);
 void scr_fs_close(double fd);
 
 /* ── WHATWG URL (scr_url.c) ──────────────────────────────────────────
@@ -2683,9 +2729,15 @@ typedef enum {
    * a silent wrong answer. The dyn→cell edge is NOT visible to the cycle
    * collector (the dyn→closure stance): a cycle dyn → cell → engine
    * object → host closure → dyn is merely never collected (the
-   * documented cross-boundary-cycle divergence). Enum position: LAST —
-   * the LLVM backend hardcodes the preceding kind numbers. */
+   * documented cross-boundary-cycle divergence). */
   SCR_DYN_JSVAL,
+  /* A compiler-owned typed reference in transit through a native Web
+   * stream. Unlike an ordinary typed→unknown conversion, this capsule
+   * retains the original value so a statically typed reader can recover
+   * its identity. `materialize` supplies the ordinary deep-copy view for
+   * consumers such as fetch request bodies that need a dyn chunk. Enum
+   * position: LAST — LLVM hardcodes every preceding kind number. */
+  SCR_DYN_TYPED_REF,
 } ScrDynKind;
 
 /* The handle-type tags the checked-dynamic tree can carry. The set is deliberately the
@@ -2701,12 +2753,28 @@ typedef enum {
   SCR_DYNH_H2_STREAM,  /* ScrH2Stream — Http2Stream (client & server) */
   SCR_DYNH_HTTP_CLIENT, /* ScrHttpClientReq — http.ClientRequest */
   SCR_DYNH_HTTP_AGENT,  /* ScrHttpAgent — http.Agent / https.Agent */
+  SCR_DYNH_ABORT_SIGNAL, /* native static-fetch AbortSignal */
+  SCR_DYNH_WEB_STREAM,   /* native WHATWG ReadableStream */
+  SCR_DYNH_WEB_READER,   /* native ReadableStreamDefaultReader */
+  SCR_DYNH_WEB_CONTROLLER, /* native ReadableStreamDefaultController */
+  SCR_DYNH_FETCH_RESPONSE, /* native static-fetch Response */
+  SCR_DYNH_FETCH_HEADERS, /* native static-fetch response Headers */
+  SCR_DYNH_EVENT,          /* native static-fetch abort Event */
+  SCR_DYNH_ABORT_CONTROLLER, /* native static-fetch AbortController */
   SCR_DYNH_COUNT,
 } ScrDynHandleTag;
 
 typedef struct ScrDyn ScrDyn;
 typedef struct ScrBytes ScrBytes; /* full definition below (C11 repeat) */
 typedef struct ScrClosure ScrClosure; /* full definition below (C11 repeat) */
+typedef struct ScrDynTypedCast {
+  const char *type_key;
+  size_t type_key_len;
+  void *ptr;
+  void *(*retain)(void *);
+  void (*release)(void *);
+  struct ScrDynTypedCast *next;
+} ScrDynTypedCast;
 typedef struct ScrJsval ScrJsval; /* opaque island cell (C11 repeat; the
                                    * always-linked dyn core never touches
                                    * its engine value — only the gated ops
@@ -2752,7 +2820,19 @@ struct ScrDyn {
     ScrStr *str; /* owned */
     ScrBytes *bytes; /* owned (SCR_DYN_BYTES) */
     struct { size_t len; size_t cap; ScrDyn **items; } arr;      /* owned */
-    struct { size_t len; size_t cap; ScrDynEntry *entries; } obj; /* owned */
+    struct {
+      size_t len;
+      size_t cap;
+      ScrDynEntry *entries;
+      /* Optional identity of the typed record that produced this ordinary
+       * deep-copy snapshot. EventTarget uses it to recognize the same
+       * EventListenerObject across repeated static→dyn crossings without
+       * changing generic dyn-object `===` semantics. */
+      /* Owned through source_access(source_identity, false). Callback
+       * interfaces may request a fresh snapshot with the true arm. */
+      void *source_identity;
+      ScrDyn *(*source_access)(void *, bool materialize);
+    } obj; /* owned */
     /* SCR_DYN_FUNC: the boxed closure (owned) + its call descriptor. `sig`
      * and `name` are static compiler-emitted literals (never freed); name
      * may be NULL (anonymous — inspect prints [Function (anonymous)]).
@@ -2767,6 +2847,23 @@ struct ScrDyn {
      * so a listener capturing its own boxed handle never cycles past the
      * settle — the settle-releases-listeners story. */
     struct { void *ptr; ScrDynHandleTag tag; } handle;
+    /* SCR_DYN_TYPED_REF: original static value + its compiler-emitted
+     * identity tag, RC adapters, and ordinary dyn snapshot adapter. */
+    struct {
+      void *ptr;
+      void *(*retain)(void *);
+      void (*release)(void *);
+      const char *type_key;
+      size_t type_key_len;
+      ScrDyn *(*materialize)(void *);
+      void (*commit)(void *, const ScrDyn *);
+      /* Both caches belong to this capsule. ReadableStream canonicalizes
+       * capsules for repeated source references, so the refreshed dyn view
+       * and every structurally converted static view keep JS reference
+       * identity while the source reference remains observable. */
+      ScrDyn *materialized;
+      ScrDynTypedCast *casts;
+    } typed_ref;
     /* SCR_DYN_PROMISE: the retained promise. The boundary contract: it
      * settles with a dyn payload (SCR_EXC_REF ScrDyn fulfillment or a
      * void fulfillment awaiters read as the undefined value) — the
@@ -2841,6 +2938,14 @@ 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);
+/* The ordinary deep-copy object plus a retained typed source. source_access
+ * releases that source when materialize=false and returns a fresh dyn snapshot
+ * when true. Generic dyn member reads and strict equality remain snapshot/node
+ * based; callback-interface consumers opt into the live arm explicitly. */
+ScrDyn *scr_dyn_new_obj_with_identity(
+    void *source, void *(*source_retain)(void *),
+    ScrDyn *(*source_access)(void *, bool materialize));
+bool scr_dyn_obj_same_source(const ScrDyn *a, const ScrDyn *b);
 /* Object.create(null): the fresh null-prototype dictionary (see the
  * null_proto flavor flag above). */
 ScrDyn *scr_dyn_new_obj_null_proto(void);
@@ -2850,6 +2955,26 @@ ScrDyn *scr_dyn_new_bytes_copy(const ScrBytes *b);
 /* The Buffer-flavored twin (stream chunks): string coercion/toString
  * decode utf8 instead of joining elements. */
 ScrDyn *scr_dyn_new_buffer_copy(const ScrBytes *b);
+/* Identity-preserving transit capsule used by ReadableStream.from over
+ * typed arrays. The constructor retains `ptr`; matching unbox returns +1.
+ * materialize lazily creates and then retains one detached dyn snapshot.
+ * The cast cache lets a non-exact dynCheck reuse one safe, compiler-built
+ * target view instead of raw-casting structurally different layouts. */
+ScrDyn *scr_dyn_new_typed_ref(
+    void *ptr, void *(*retain)(void *), void (*release)(void *),
+    const char *type_key, size_t type_key_len,
+    ScrDyn *(*materialize)(void *),
+    void (*commit)(void *, const ScrDyn *));
+bool scr_dyn_typed_ref_is(
+    const ScrDyn *d, const char *type_key, size_t type_key_len);
+void *scr_dyn_typed_ref_unbox(const ScrDyn *d); /* +1 */
+ScrDyn *scr_dyn_typed_ref_materialize(const ScrDyn *d); /* +1 */
+void scr_dyn_typed_ref_commit(ScrDyn *d);
+void *scr_dyn_typed_ref_cached_cast(
+    const ScrDyn *d, const char *type_key, size_t type_key_len); /* +1/NULL */
+void scr_dyn_typed_ref_cache_cast(
+    ScrDyn *d, const char *type_key, size_t type_key_len, void *ptr,
+    void *(*retain)(void *), void (*release)(void *));
 /* A fresh u8 COPY of a SCR_DYN_BYTES payload (+1) — the dynCheck
  * extraction (`u as Uint8Array`). */
 ScrBytes *scr_dyn_bytes_copy_out(const ScrDyn *d);
@@ -2902,6 +3027,7 @@ ScrStr *scr_dyn_string_coerce(const ScrDyn *d);
  * 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);
+bool scr_dyn_number_coerce_js(const ScrDyn *d, double *out);
 
 /* `d instanceof TypeError` (and the other builtin error classes) on a
  * checked-dynamic value: the from_error cache resolves the dyn encoding
@@ -3137,9 +3263,10 @@ 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. */
+/* dynTest arms that need the ENGINE's answer on a JSVAL node, or the
+ * materialized answer for a live typed-reference capsule. 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);
@@ -3819,6 +3946,35 @@ ScrGen *scr_gen_of_fiber(ScrFiber *f);
 long scr_promise_live_count(void);
 #endif
 
+/* ── fetch (scr_fetch.c) ──────────────────────────────────────────────
+ * The native bridge over scr_net + scr_tls + scr_http's client parser.
+ * Static fetch(url) resolves at the response head with native Response
+ * and ReadableStream handles; Response.json consumes that same stream.
+ * AbortSignal and streaming request bodies stay native too. Under
+ * --dynamic the same TU boots the broader engine web surface. The
+ * emitted main calls scr_fetch_install in either form. */
+void scr_fetch_install(void);
+ScrPromise *scr_fetch_static(ScrStr *url, ScrDyn *init); /* +1 promise<Response handle> */
+ScrDyn *scr_fetch_response_new(ScrDyn *body, ScrDyn *init); /* borrowed args; +1 Response handle or NULL pending */
+ScrPromise *scr_fetch_response_json(ScrDyn *response); /* +1 promise<dyn> */
+ScrPromise *scr_fetch_response_text(ScrDyn *response); /* +1 promise<dyn> */
+ScrPromise *scr_fetch_response_bytes(ScrDyn *response); /* +1 promise<dyn> */
+ScrDyn *scr_fetch_abort_controller_new(void); /* +1 AbortController handle */
+/* Borrowed number; +1 AbortSignal handle or NULL pending. */
+ScrDyn *scr_fetch_abort_timeout(ScrDyn *delay);
+ScrDyn *scr_fetch_abort_now(ScrDyn *reason); /* borrowed reason; +1 handle */
+ScrDyn *scr_fetch_abort_any(ScrDyn *signals); /* borrowed array; +1 handle or NULL pending */
+ScrDyn *scr_fetch_stream_new(ScrDyn *source); /* borrowed source; +1 handle or NULL pending */
+ScrDyn *scr_fetch_stream_from(ScrDyn *iterable); /* borrowed iterable; +1 handle or NULL pending */
+ScrDyn *scr_fetch_stream_from_array(
+    ScrArr *iterable,
+    ScrDyn *(*item)(ScrArr *, double)); /* borrowed array/callback; +1 handle */
+ScrDyn *scr_fetch_stream_from_bytes(
+    ScrBytes *iterable); /* borrowed bytes; +1 handle */
+ScrDyn *scr_fetch_stream_from_string(
+    ScrStr *iterable); /* borrowed string; +1 handle */
+ScrPromise *scr_fetch_reader_read(ScrDyn *reader); /* borrowed handle; +1 */
+
 /* ── dynamic island (scr_island.c; --dynamic builds ONLY) ────────────
  * The embedded QuickJS-ng engine. Compiled and linked only under
  * -DSCR_DYNAMIC; static builds never reference these symbols (nor the
@@ -3948,18 +4104,12 @@ bool scr_island_timers_due(void);
 bool scr_island_timers_fire_due(void); /* true = fired at least one */
 void scr_island_timers_teardown(void);
 
-/* ── fetch (scr_fetch.c) ──────────────────────────────────────────────
- * The native bridge behind the island's fetch (scr_net + scr_tls +
- * scr_http's client parser + zlib), compiled and linked ONLY into
- * --dynamic builds whose graph references fetch. The emitted main calls
- * scr_fetch_install BEFORE any island entry; install registers the
- * bridge's hooks with the island, which boots the fetch glue with the
- * engine. The native bridge registers NO pending/poll hooks (its
+/* ── dynamic fetch hooks ──────────────────────────────────────────────
+ * The native bridge registers NO pending/poll hooks (its
  * transfers live on real sockets the loop's poller sleeps on); the curl
  * reference implementation (scr_fetch_curl.c, SCRIPTC_FETCH_CURL=1 —
  * one release as the flip's reference) still registers all four so the
  * loop can sleep on curl's fds. */
-void scr_fetch_install(void);
 void scr_island_set_fetch(void (*boot)(void *jsctx), bool (*pending)(void),
                            void (*poll)(double max_wait_ms), void (*teardown)(void));
 
@@ -4078,6 +4228,7 @@ ScrJsval *scr_jsval_destr_check(ScrJsval *v, const char *spell, const char *firs
 ScrJsval *scr_jsval_iter_n(ScrJsval *v, double n);
 int scr_jsval_set_idx(ScrJsval *o, ScrJsval *key, ScrJsval *v);
 ScrJsval *scr_jsval_call_method(ScrJsval *o, const ScrStr *name, int argc, ScrJsval **argv);
+ScrJsval *scr_jsval_call_this(ScrJsval *f, ScrJsval *receiver, int argc, ScrJsval **argv);
 /* `o.name?.(...)`: a nullish member answers the engine's undefined;
  * 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);
@@ -4297,10 +4448,13 @@ bool scr_num_same_value(double a, double b);
  * 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. */
+/* ── Date, the read-only value slice (scr_lib.c) ──────────────────────
+ * A Date value is its TimeClip'd epoch-millisecond scalar. Identity and
+ * mutation are frontend-fenced; construction, storage, getters, and ISO
+ * formatting are exact over this representation. */
 double scr_date_now(void); /* integer ms since epoch, like Node */
+double scr_date_new_ms(double ms); /* TimeClip (NaN when invalid) */
+double scr_date_get_time(double ms);
 /* Node's exact ISO 8601 UTC format (expanded ±YYYYYY years outside
  * 0–9999). THROWS Node's "Invalid time value" RangeError on NaN or
  * |ms| > 8.64e15 and returns NULL; +1 otherwise. */
@@ -4314,6 +4468,30 @@ double scr_date_parse_get_time(ScrStr *s);
  * and years past V8's ±1e6 MakeDay bound. Never throws. */
 double scr_date_utc(double y, double mo, double d,
                     double h, double mi, double s, double ms);
+double scr_date_get_full_year(double ms, bool utc);
+double scr_date_get_month(double ms, bool utc);
+double scr_date_get_date(double ms, bool utc);
+double scr_date_get_day(double ms, bool utc);
+double scr_date_get_hours(double ms, bool utc);
+double scr_date_get_minutes(double ms, bool utc);
+double scr_date_get_seconds(double ms, bool utc);
+double scr_date_get_milliseconds(double ms);
+double scr_date_get_timezone_offset(double ms);
+/* One-argument ABI wrappers used by the LLVM lib-call table. */
+double scr_date_get_full_year_local(double ms);
+double scr_date_get_full_year_utc(double ms);
+double scr_date_get_month_local(double ms);
+double scr_date_get_month_utc(double ms);
+double scr_date_get_date_local(double ms);
+double scr_date_get_date_utc(double ms);
+double scr_date_get_day_local(double ms);
+double scr_date_get_day_utc(double ms);
+double scr_date_get_hours_local(double ms);
+double scr_date_get_hours_utc(double ms);
+double scr_date_get_minutes_local(double ms);
+double scr_date_get_minutes_utc(double ms);
+double scr_date_get_seconds_local(double ms);
+double scr_date_get_seconds_utc(double ms);
 
 /* ── bitwise operators (scr_lib.c) ────────────────────────────────────
  * JS-exact ToInt32/ToUint32 semantics: NaN/±Infinity → 0, truncation
@@ -4468,6 +4646,9 @@ void scr_dataview_set(ScrBytes *b, double byte_off, double value, ScrDataViewGet
  * toward zero, wrap mod 2^8/2^32), f32 by double→float rounding. */
 double scr_bytes_get(const ScrBytes *b, double i);
 void scr_bytes_set(ScrBytes *b, double i, double v);
+/* Replace a live typed-array capsule's fixed-size payload from its dyn
+ * snapshot. Source and target have the same compiler-checked bytes type. */
+void scr_bytes_copy_contents(ScrBytes *dst, const ScrBytes *src);
 
 /* TypedArray.prototype.slice(start, end): relative indices clamp like
  * string/array slice (ToIntegerOrInfinity, negatives from the end); the
@@ -5125,9 +5306,12 @@ long scr_secure_ctx_live_count(void);
  * /etc/ssl/cert.pem probe order scr_tls.c documents) stands in for both
  * Node's compiled-in Mozilla roots ('bundled', rootCertificates) and the
  * platform store ('system') — the established SEMANTICS divergence,
- * extended to introspection; 'extra' reads NODE_EXTRA_CA_CERTS. Arrays
- * are cached per type (+1 retained answers each call — Node's own
- * caching, and the identity the suite pins with strictEqual). */
+ * extended to introspection; 'extra' uses the NODE_EXTRA_CA_CERTS file
+ * captured before user code runs. Arrays are cached per type (+1 retained
+ * answers each call — Node's own caching, and the identity the suite pins
+ * with strictEqual). */
+void scr_tls_ca_install(void); /* snapshots NODE_EXTRA_CA_CERTS + file bytes */
+bool scr_tls_ca_extra_pem(const char **pem, size_t *len); /* borrowed launch snapshot */
 ScrArr *scr_tls_ca_get(ScrStr *type); /* +1; throws ERR_INVALID_ARG_VALUE on unknown types */
 ScrArr *scr_tls_ca_root(void);        /* +1; === getCACertificates("bundled") */
 /* Replaces the 'default' set: entries filter to their PEM certificate

package/src/scr_tls.c

@@ -336,17 +336,14 @@ typedef struct ScrTlsCli {
 } ScrTlsCli;
 
 /* The default trust anchors when no `ca` option is given: the system
- * bundle, standing in for Node's compiled-in Mozilla roots. Probed once
- * across the distro spellings — /etc/ssl/cert.pem first (macOS ships it;
- * Alpine links it), then Debian/Ubuntu's ca-certificates.crt,
- * Fedora/RHEL's ca-bundle.crt, and openSUSE's ca-bundle.pem. On macOS
- * only the first path exists, so the probe order changes nothing there.
- * A host with none leaves the chain empty: verification fails, exactly
- * the no-roots behavior /etc/ssl/cert.pem-only had. Windows is that host
- * by construction (no PEM bundle ships; the OS store is cert-database-
- * shaped) — a no-`ca` client there fails verification like a bundle-less
- * Unix host, which agrees with the oracle wherever the fixtures tread
- * (their CAs are local, never in Node's Mozilla roots either). */
+ * bundle, standing in for Node's compiled-in Mozilla roots, plus
+ * NODE_EXTRA_CA_CERTS. The system bundle is probed once across the distro
+ * spellings — /etc/ssl/cert.pem first (macOS ships it; Alpine links it),
+ * then Debian/Ubuntu's ca-certificates.crt, Fedora/RHEL's ca-bundle.crt,
+ * and openSUSE's ca-bundle.pem. On macOS only the first path exists, so
+ * the probe order changes nothing there. A host with none leaves only the
+ * optional extra chain. Windows is that host by construction (no PEM
+ * bundle ships; the OS store is cert-database-shaped). */
 static mbedtls_x509_crt scr_tls_system_roots;
 static bool scr_tls_system_roots_loaded = false;
 
@@ -386,6 +383,13 @@ static mbedtls_x509_crt *scr_tls_system_ca(void) {
     for (size_t i = 0; i < sizeof bundles / sizeof bundles[0]; i++) {
       if (mbedtls_x509_crt_parse_file(&scr_tls_system_roots, bundles[i]) == 0) break;
     }
+    const char *extra = NULL;
+    size_t extra_len = 0;
+    if (scr_tls_ca_extra_pem(&extra, &extra_len) && extra_len > 0) {
+      (void)mbedtls_x509_crt_parse(
+          &scr_tls_system_roots, (const unsigned char *)extra,
+          extra_len + 1);
+    }
   }
   return &scr_tls_system_roots;
 }

package/src/scr_tls_ca.c

@@ -32,6 +32,9 @@ static ScrArr *scr_ca_bundled = NULL;
 static ScrArr *scr_ca_system = NULL;
 static ScrArr *scr_ca_extra = NULL;
 static ScrArr *scr_ca_default = NULL;
+static char *scr_ca_extra_buf = NULL;
+static size_t scr_ca_extra_len = 0;
+static bool scr_ca_installed = false;
 static char *scr_ca_override_buf = NULL;
 static size_t scr_ca_override_len = 0;
 static uint64_t scr_ca_override_gen = 0; /* 0 = never set */
@@ -47,6 +50,9 @@ static void scr_ca_teardown(void) {
   if (scr_ca_extra != NULL) scr_arr_release(scr_ca_extra);
   if (scr_ca_default != NULL) scr_arr_release(scr_ca_default);
   scr_ca_bundled = scr_ca_system = scr_ca_extra = scr_ca_default = NULL;
+  free(scr_ca_extra_buf);
+  scr_ca_extra_buf = NULL;
+  scr_ca_extra_len = 0;
   free(scr_ca_override_buf);
   scr_ca_override_buf = NULL;
 }
@@ -123,6 +129,31 @@ static char *scr_ca_read_file(const char *path, size_t *out_len) {
   return buf;
 }
 
+/*
+ * Node consumes NODE_EXTRA_CA_CERTS while the process is initialized:
+ * changing process.env or replacing the referenced file later does not
+ * alter either TLS trust or getCACertificates("extra"). Generated main
+ * calls this install hook before user code; the lazy fallback only serves
+ * library/direct-runtime callers that have no executable startup hook.
+ */
+void scr_tls_ca_install(void) {
+  if (scr_ca_installed) return;
+  scr_ca_installed = true;
+  scr_ca_arm_teardown();
+  const char *path = getenv("NODE_EXTRA_CA_CERTS");
+  if (path != NULL && path[0] != '\0') {
+    scr_ca_extra_buf = scr_ca_read_file(path, &scr_ca_extra_len);
+  }
+}
+
+bool scr_tls_ca_extra_pem(const char **pem, size_t *len) {
+  scr_tls_ca_install();
+  if (scr_ca_extra_buf == NULL) return false;
+  *pem = scr_ca_extra_buf;
+  *len = scr_ca_extra_len;
+  return true;
+}
+
 /* The host bundle, probed in scr_tls.c's documented order. */
 static ScrArr *scr_ca_load_host_bundle(void) {
   ScrArr *arr = scr_arr_new(SCR_ELEM_STR, 128);
@@ -163,14 +194,10 @@ static ScrArr *scr_ca_extra_arr(void) {
   if (scr_ca_extra == NULL) {
     scr_ca_arm_teardown();
     scr_ca_extra = scr_arr_new(SCR_ELEM_STR, 4);
-    const char *path = getenv("NODE_EXTRA_CA_CERTS");
-    if (path != NULL && path[0] != '\0') {
-      size_t len = 0;
-      char *text = scr_ca_read_file(path, &len);
-      if (text != NULL) {
-        scr_ca_push_pem_blocks(scr_ca_extra, text, len);
-        free(text);
-      }
+    const char *pem = NULL;
+    size_t len = 0;
+    if (scr_tls_ca_extra_pem(&pem, &len)) {
+      scr_ca_push_pem_blocks(scr_ca_extra, pem, len);
     }
   }
   return scr_ca_extra;