@scriptc/cli-darwin-arm64 0.2.5 → 0.2.6

package/dist/lib/runtime-sources/src/scr_runtime.h

@@ -35,7 +35,7 @@ char *strcasestr(const char *hay, const char *needle);
 void arc4random_buf(void *buf, size_t n);
 #endif
 
-/* ── thread-instanced library state ─────────────────────────────────────
+/* ── runtime instance state ─────────────────────────────────────────────
  * Archives built under the profile's abi.instance_per_thread compile every
  * TU with -DSCR_THREAD_INSTANCES, and SCR_TL moves each unit's mutable
  * state — and the emitted program's globals — into thread-local storage.
@@ -44,10 +44,10 @@ void arc4random_buf(void *buf, size_t n);
  * registration, poison flag, and program state. The instance's lifetime is
  * the thread's; the one-thread-per-instance contract (an instance is never
  * entered from two threads) is unchanged — this mode adds instances, not
- * thread awareness. Expands to nothing everywhere else, so executable
- * builds and classic library builds carry the exact bytes they always
- * carried. Truly immutable tables (static const data) stay shared. */
-#if defined(SCR_LIB) && defined(SCR_THREAD_INSTANCES)
+ * thread awareness. Worker executables use the same isolation for their
+ * collectors, caches and scheduler state. Expands to nothing for ordinary
+ * executables and classic libraries. Immutable tables stay shared. */
+#if (defined(SCR_LIB) && defined(SCR_THREAD_INSTANCES)) || defined(SCR_WORKERS)
 #define SCR_TL _Thread_local
 #else
 #define SCR_TL
@@ -62,7 +62,8 @@ void scr_init(void);
 /* Program objects emitted by the bundled LLVM helper reference this symbol.
  * Its versioned spelling makes a mismatched manual runtime link fail before
  * the program can start. */
-void scr_runtime_abi_v6(void);
+void scr_runtime_abi_v7(void);
+void scr_runtime_workers_v7(void);
 
 /* ── the trap funnel (scr_console.c; scr_library.c under -DSCR_LIB) ──────
  * Every unrecoverable runtime trap — OOM, semantic range traps, internal-
@@ -276,10 +277,45 @@ void scr_library_str_out(ScrStr *s, const uint8_t **out, size_t *out_len);
 void scr_library_bytes_out(ScrBytes *b, const uint8_t **out, size_t *out_len);
 
 #define scr_atexit(fn) scr_library_register_reset(fn)
+#elif defined(SCR_WORKERS)
+/* Executable workers drain their own cleanup stack before their TLS dies.
+ * Registering their callbacks with libc would execute them on the process
+ * exit thread against a different runtime instance. */
+int scr_context_atexit(void (*fn)(void));
+void scr_context_cleanup(void);
+void scr_context_enter(uint64_t thread_id);
+uint64_t scr_context_thread_id(void);
+void scr_context_stop_flag(const void *flag);
+void scr_context_stop(int code);
+bool scr_context_stopping(void);
+bool scr_context_checkpoint(void);
+void scr_loop_context_shutdown(void);
+extern SCR_TL void (*scr_context_report_error)(void);
+typedef struct ScrContextEnv ScrContextEnv;
+ScrContextEnv *scr_context_env_capture(void);
+void scr_context_env_free(ScrContextEnv *environment);
+void scr_context_env_enter(ScrContextEnv *environment);
+bool scr_context_env_set(const char *name, const char *value);
+const char *scr_context_getenv(const char *name);
+struct ScrArr *scr_context_env_pairs(void);
+#define scr_atexit(fn) scr_context_atexit(fn)
 #else
 #define scr_atexit(fn) atexit(fn)
 #endif /* SCR_LIB */
 
+/* Also used by ordinary event-loop builds, where this always returns true. */
+bool scr_context_is_main(void);
+double scr_context_thread_number(void);
+double scr_worker_root(void);
+int scr_worker_argc(void);
+char **scr_worker_argv(void);
+
+#ifdef SCR_WORKERS
+#define scr_getenv(name) scr_context_getenv(name)
+#else
+#define scr_getenv(name) getenv(name)
+#endif
+
 /* ── cycle collection (scr_cycle.c) ───────────────────────────────────
  * Reference counting alone cannot free cycles, so every object that can
  * participate in one — capture boxes, heap closures, unions, promises, and
@@ -380,6 +416,12 @@ static inline ScrCycHdr *scr_cyc_hdr(void *obj) { return (ScrCycHdr *)obj - 1; }
 void *scr_cyc_alloc(size_t size, ScrTraceFn trace, ScrCycFreeFn free_fn);
 void scr_cyc_free(void *obj); /* frees the block, header included */
 
+/* Dispose an object whose reference count already reached zero. The caller
+ * removes its cycle candidate first. Nested disposals keep bounded stack
+ * depth; deeper objects wait until the outer disposal drains the worklist.
+ * The callback owns the object and must release its children and free it. */
+void scr_rc_destroy(void *obj, void (*destroy)(void *));
+
 /* RC hooks for cycle-headered types. on_release: rc was decremented and
  * stayed above zero — buffer the object as a possible cycle root (may run
  * a collection when the buffer crosses the threshold; the caller must not
@@ -397,6 +439,7 @@ static inline void scr_cyc_mark_live(void *obj) {
  * 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);
+void scr_cyc_context_cleanup(void);
 
 /* One pass on the normal generational schedule, for callers that reach a
  * natural collection point rather than a threshold (the event loop between
@@ -765,6 +808,16 @@ ScrStr *scr_str_slice(ScrStr *s, double start, double end);
 /* substring: clamp-and-swap (negatives clamp to 0, start > end swaps). */
 ScrStr *scr_str_substring(ScrStr *s, double start, double end);
 
+/* Scalar-only local slices retain their original owner without copying.
+ * Bounds and split-surrogate replacements are snapshotted at construction. */
+typedef struct ScrStringSlice {
+  size_t start, length;
+  uint32_t split;
+} ScrStringSlice;
+void scr_str_slice_range(ScrStr *s, double start, double end, bool substring,
+                         ScrStringSlice *out);
+double scr_str_slice_char_code_at(ScrStr *s, const ScrStringSlice *range, double index);
+
 /* repeat(count): count < 0 or Infinity is a JS RangeError; scriptc has no
  * exceptions, so it prints "scriptc: RangeError: Invalid count value" to
  * stderr and abort()s. Returns +1. */
@@ -805,6 +858,25 @@ ScrStr *scr_str_trim_end(ScrStr *s);
 struct ScrArr;
 struct ScrArr *scr_str_split(ScrStr *s, ScrStr *sep);
 struct ScrArr *scr_str_split_limit(ScrStr *s, ScrStr *sep, double limit);
+/* Internal dense split traversal. The cursor borrows input strings, returns
+ * one owned piece per step, and uses NULL only for exhaustion. Its layout
+ * is shared with generated stack storage, including wasm32. */
+typedef struct ScrSplitCursor {
+  size_t offset;
+  uint32_t remaining;
+  uint32_t pending_unit;
+} ScrSplitCursor;
+void scr_str_split_cursor_init(ScrSplitCursor *cursor, uint32_t limit);
+/* Optional scratch is a separately owned, NULL-initialized string slot.
+ * A piece that has not escaped can reuse it after the preceding yield is
+ * released. The caller releases the slot on every exit; NULL disables reuse. */
+ScrStr *scr_str_split_cursor_next(ScrStr *s, ScrStr *sep, ScrSplitCursor *cursor,
+                                  ScrStr **scratch);
+/* Borrowed split bytes remain valid while the source snapshot is owned.
+ * Materialization returns +1 and uses the same optional scratch contract. */
+const char *scr_str_split_cursor_span(ScrStr *s, ScrStr *sep, ScrSplitCursor *cursor,
+                                     size_t *length);
+ScrStr *scr_str_split_materialize(const char *bytes, size_t length, ScrStr **scratch);
 
 /* padStart(maxLength, fill)/padEnd — ECMA StringPad, UTF-16 unit counts.
  * Target at or below the length (or empty fill) returns the receiver
@@ -1144,6 +1216,7 @@ double scr_arr_get_number(const ScrArr *a, double i);
 bool scr_arr_index_eq(const ScrArr *a, double i, const ScrArr *b, double j);
 bool scr_arr_get_bool(ScrArr *a, double i);  /* trap missing/hole */
 void *scr_arr_get_ref(ScrArr *a, double i);  /* trap missing/hole; +1 */
+void *scr_arr_borrow_ref(ScrArr *a, double i); /* same checks; borrowed */
 /* Borrow a non-null reference element, or NULL for a hole/undefined/missing
  * property. Keep the array alive and retain before removing its element.
  * This read does not invoke retain callbacks or mutate runtime state. */
@@ -1196,6 +1269,8 @@ double scr_arr_unshift_bool(ScrArr *a, bool v);
 double scr_arr_unshift_ref(ScrArr *a, void *v);
 double scr_arr_unshift_spread(ScrArr *a, const ScrArr *src);
 ScrArr *scr_arr_reverse(ScrArr *a);
+/* Default primitive String ordering; stable, borrowed receiver, owned result. */
+ScrArr *scr_arr_sort_primitive(ScrArr *a, bool copy);
 
 /* pop traps on an empty array; _ref transfers ownership out (+1 to the
  * caller, no release). */
@@ -1406,7 +1481,7 @@ typedef struct ScrMap {
   size_t ecap;     /* entries capacity */
   ScrMapEntry *entries;
   size_t nbuckets;  /* zero for small linear maps; otherwise power of two >= 2 * nentries */
-  size_t *buckets;  /* entry indices; SIZE_MAX = empty */
+  void *buckets;  /* compact tagged indices, or size_t indices for large tables */
   size_t iter_depth; /* > 0: an iteration is active — no compaction */
   const ScrMapDynOps *dyn_ops;
   const uint8_t *union_keys; /* immutable key-kind table indexed by union tag */
@@ -1414,6 +1489,12 @@ typedef struct ScrMap {
 
 /* Called once on a fresh UNION_VALUE collection, before its first insert. */
 void scr_map_union_keys(ScrMap *map, const uint8_t *kinds);
+/* String-key lookups borrow an exact byte span. Reference results return
+ * +1; scalar outputs are written only on a hit, like the string getters. */
+bool scr_map_get_span_f64(const ScrMap *m, const char *bytes, size_t length, double *out);
+bool scr_map_get_span_bool(const ScrMap *m, const char *bytes, size_t length, bool *out);
+void *scr_map_get_span_ref(const ScrMap *m, const char *bytes, size_t length);
+
 /* Fresh shallow copies with compact storage and independent mutation.
  * keys_only selects a Set; checked views materialize their boxed values. */
 ScrMap *scr_map_clone(const ScrMap *source, bool keys_only);
@@ -1840,6 +1921,9 @@ extern SCR_TL ScrVt scr_emitter_vt; /* main() stamps pre/post */
 extern SCR_TL double scr_emitter_default_max;
 
 ScrEmitter *scr_emitter_new(void); /* +1, collector-headered */
+/* Internal owner hook; observes listener presence without running script. */
+void scr_emitter_observe(ScrEmitter *em,
+                        void (*observe)(void *, const ScrStr *, bool), void *context);
 void scr_emitter_init(void *obj);  /* super() into the prefix (no-op today) */
 ScrEmitter *scr_emitter_retain(ScrEmitter *em);
 void scr_emitter_release(ScrEmitter *em); /* dispatches through em->vt */
@@ -1917,6 +2001,7 @@ ScrEmitter *scr_emitter_remove_all(ScrEmitter *em, ScrStr *name, bool all);
  * emit('error', err): no listener ⇒ THROWS err (borrowed; +1 taken). */
 bool scr_emitter_emit(ScrEmitter *em, ScrStr *name, ...);
 bool scr_emitter_emit_flex(ScrEmitter *em, ScrStr *name, ScrDyn *const *args, size_t argc);
+bool scr_emitter_emit_error_flex(ScrEmitter *em, ScrDyn *error);
 bool scr_emitter_emit_error(ScrEmitter *em, ScrStr *name, ScrError *err);
 double scr_emitter_listener_count(ScrEmitter *em, ScrStr *name);
 double scr_emitter_listener_count_fn(ScrEmitter *em, ScrStr *name, ScrClosure *fn);
@@ -1938,7 +2023,7 @@ bool scr_emitter_has(ScrEmitter *em, const char *name);
  * the END of scr_emitter_on with the emitter and the event name, so the
  * stream unit can start flowing on the first 'data' listener. NULL when
  * the stream unit is not linked; emitter behavior is byte-identical. */
-extern void (*scr_emitter_on_hook)(ScrEmitter *em, ScrStr *name);
+extern SCR_TL void (*scr_emitter_on_hook)(ScrEmitter *em, ScrStr *name);
 
 /* ── node:stream (scr_stream.c, link-gated by moduleUsesStream) ───────
  * The runtime-provided stream classes (Readable/Writable/Duplex/
@@ -1979,7 +2064,7 @@ typedef struct ScrStream {
   ScrStreamState *st;
 } ScrStream;
 
-extern ScrVt scr_readable_vt, scr_writable_vt, scr_duplex_vt,
+extern SCR_TL ScrVt scr_readable_vt, scr_writable_vt, scr_duplex_vt,
     scr_transform_vt, scr_passthrough_vt; /* main() stamps pre/post */
 
 /* Compiler-emitted option-callback invoke adapters (the leading-`this`
@@ -2290,6 +2375,9 @@ typedef enum {
    * functions, and checked-dynamic primitives). The payload uses the
    * same ownership as REF. */
   SCR_EXC_PRIMITIVE_REF,
+  /* Noncatchable context shutdown. Owns no payload; generated unwinding
+   * releases locals while bypassing user catch and finally handlers. */
+  SCR_EXC_TERMINATE,
 } ScrExcKind;
 
 /* One cell per fiber (JS has one exception in flight per execution
@@ -2407,7 +2495,7 @@ ScrDyn *scr_caught_to_dyn(const ScrCaught *c);
 void scr_exc_print_uncaught(void);
 /* Optional native process exception registry. Hook returns 1 when handled,
  * 0 when unhandled, and -1 when a handler itself threw (Node exit 7). */
-extern int (*scr_uncaught_exception_hook)(bool from_promise);
+extern SCR_TL int (*scr_uncaught_exception_hook)(bool from_promise);
 bool scr_exc_handle_uncaught(bool from_promise);
 void scr_process_on_uncaught_exception(ScrDyn *fn, bool once, bool monitor);
 void scr_process_off_uncaught_exception(ScrDyn *fn, bool monitor);
@@ -2469,7 +2557,7 @@ ScrStr *scr_process_cwd(void);      /* +1 fresh (getcwd) */
  * internal stdio formatting buffer never delays live output. */
 bool scr_stdio_write(int fd, const void *data, size_t len);
 int scr_stdio_write_raw(int fd, const void *data, size_t len);
-extern bool (*scr_stdio_write_hook)(int fd, const void *data, size_t len);
+extern SCR_TL bool (*scr_stdio_write_hook)(int fd, const void *data, size_t len);
 /* process.stdout/.stderr .write — raw bytes (no newline or formatting; data
  * borrowed), promptly visible and ordered with console output. Constantly
  * true (the synchronous runtime never queues backpressure). */
@@ -2632,15 +2720,11 @@ void scr_fs_write_file_mode(ScrStr *path, ScrStr *data, double mode);
 void scr_fs_mkdir_mode(ScrStr *path, double mode);
 void scr_fs_mkdir_recursive_mode(ScrStr *path, double mode);
 
-/* Atomics.wait(int32Array, idx, expected, timeoutMs): "not-equal" when
- * the element differs from expected, else a real nanosleep for the
- * timeout and "timed-out" (+1 string either way). scriptc has no
- * threads, so nothing can ever notify — for every compilable program
- * this IS the spec's behavior and "ok" is unreachable (the compiler
- * requires the timeout argument; an infinite wait would be a certain
- * deadlock). Out-of-range indices trap like every bytes access. */
-typedef struct ScrBytes ScrBytes; /* full definition below (C11 repeat) */
-ScrStr *scr_atomics_wait(ScrBytes *arr, double idx, double expected, double timeout_ms);
+/* Sequentially consistent integer operations and shared Int32 wait queues. */
+typedef struct ScrBytes ScrBytes;
+ScrStr *scr_atomics_wait(ScrBytes *, double, double, double);
+double scr_atomics_notify(ScrBytes *, double, double);
+double scr_atomics_op(ScrBytes *, double, double, double, double);
 
 /* isatty(3) over an fd (0/1/2): a real boolean — false where Node's
  * non-TTY streams expose undefined (SEMANTICS.md). stdin_destroy is a
@@ -3665,6 +3749,9 @@ typedef enum {
   SCR_DYNH_CONSOLE,        /* stored global console value */
   SCR_DYNH_SEARCH_PARAMS,  /* live WHATWG URLSearchParams */
   SCR_DYNH_FETCH_REQUEST,
+  SCR_DYNH_WORKER,
+  SCR_DYNH_MESSAGE_PORT,
+  SCR_DYNH_SHARED_ARRAY_BUFFER,
   SCR_DYNH_COUNT,
 } ScrDynHandleTag;
 
@@ -4117,6 +4204,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);
+ScrStr *scr_regex_replace_callback(ScrStr *subject, ScrRegex *regex, ScrDyn *callback, bool all);
 bool scr_dyn_number_coerce_js(const ScrDyn *d, double *out);
 /* Direct-return ABI wrapper for compiler libCalls: JS ToNumber, or NaN
  * with the exception pending when an object hook throws/refuses. */
@@ -4341,7 +4429,7 @@ ScrDyn *scr_dyn_new_promise(ScrPromise *p); /* scr_async_dyn.c (gated) */
 /* The allocator view the gated boxes use; installs the release arm's
  * promise-release edge (runtime-internal). */
 ScrDyn *scr_dyn_alloc_promise(void (*release_fn)(ScrPromise *p));
-extern void (*scr_dyn_promise_release_fn)(ScrPromise *p);
+extern SCR_TL void (*scr_dyn_promise_release_fn)(ScrPromise *p);
 ScrDyn *scr_dyn_new_promise_adapting(ScrPromise *src,
                                      void (*adapt)(ScrPromise *dst, ScrPromise *src));
 /* BORROWED peek at the boxed promise; NULL when d is not a promise box. */
@@ -4583,6 +4671,8 @@ void scr_jb_puts(ScrJsonBuf *b, const char *s);
 /* JS JSON.stringify number rules: NaN/±Infinity → null, -0 → 0, else
  * shortest-roundtrip via scr_f64_to_str. */
 void scr_jb_put_f64(ScrJsonBuf *b, double v);
+/* Append String(number), including NaN/Infinity, without a temporary string. */
+void scr_jb_put_number(ScrJsonBuf *b, double v);
 /* Quoted + escaped JSON string: \" \\ \n \r \t \b \f, other control chars
  * as \u00XX, everything else (UTF-8 included) verbatim — exactly the JS
  * JSON.stringify escape set for well-formed strings. */
@@ -4598,6 +4688,10 @@ void scr_dyn_isl_tostr_buf(ScrJsonBuf *b, const ScrDyn *d);
  * DROP, array slots holding undefined print null (exactly Node). */
 void scr_jb_put_dyn(ScrJsonBuf *b, const ScrDyn *d);
 ScrStr *scr_jb_finish(ScrJsonBuf *b); /* returns +1; frees the buffer */
+/* Reformat compiler-produced compact JSON with an already resolved gap.
+ * Borrows both inputs; gap_len is a byte length, including embedded NUL.
+ * Returns a new owned string, or retains compact when the gap is empty. */
+ScrStr *scr_json_indent(const ScrStr *compact, const char *gap, size_t gap_len);
 
 void *scr_dyn_retain_v(void *d);
 void scr_dyn_release_v(void *d);
@@ -4710,7 +4804,13 @@ typedef struct ScrAlsCtx {
   ScrAlsEntry entries[]; /* flexible */
 } ScrAlsCtx;
 /* Runtime-internal (the fiber machinery's always-linked core). */
-extern ScrAlsCtx **scr_als_active;
+extern SCR_TL ScrAlsCtx **scr_als_active;
+#ifdef SCR_WORKERS
+ScrAlsCtx **scr_als_slot(void);
+#define SCR_ALS_SLOT() scr_als_slot()
+#else
+#define SCR_ALS_SLOT() scr_als_active
+#endif
 ScrAlsCtx *scr_als_ctx_retain(ScrAlsCtx *c);
 void scr_als_ctx_release(ScrAlsCtx *c);
 double scr_als_new(void);
@@ -4741,12 +4841,12 @@ void scr_process_off_rejection_handled(ScrDyn *fn);
 /* The checkpoint delivery hook the registration above installs
  * (scr_async_dyn.c → scr_report_unhandled_rejections; NULL = default
  * report). Runtime-internal. */
-extern bool (*scr_urj_deliver_fn)(ScrPromise *p);
+extern SCR_TL bool (*scr_urj_deliver_fn)(ScrPromise *p);
 /* The late-handled hook (scr_async_dyn.c installs it when a
  * 'rejectionHandled' listener registers): scr_async.c calls it when a
  * promise the report already delivered as unhandled gains a handler.
  * Runtime-internal. */
-extern void (*scr_rjh_notify_fn)(ScrPromise *p);
+extern SCR_TL void (*scr_rjh_notify_fn)(ScrPromise *p);
 /* The attach-time handled mark (a dyn then/catch carrying a rejection
  * handler, or the module loader taking ownership of an evaluation
  * promise): marks pending and rejected sources observed at Node's attach
@@ -4977,8 +5077,8 @@ void scr_stdin_data_thunk_bytes(ScrClosure *cb, ScrBytes *chunk);
  * not the unit is present. */
 void scr_loop_set_events(bool (*pending)(void), bool (*watching)(void),
                           void (*dispatch)(void), int (*pollfds)(int out[2]));
-extern void (*scr_process_exit_hook)(double code);
-extern void (*scr_stdin_destroy_hook)(void);
+extern SCR_TL void (*scr_process_exit_hook)(double code);
+extern SCR_TL void (*scr_stdin_destroy_hook)(void);
 void scr_exit_code_note(int code);
 int scr_exit_code_hint_get(void);
 /* The pollable child-exit wake fd (the child kqueue / pidfd epoll) for the loop's
@@ -5769,6 +5869,8 @@ typedef enum ScrBytesElem {
   SCR_BYTES_U8C, /* Uint8ClampedArray */
 } ScrBytesElem;
 
+typedef struct ScrSharedBytes ScrSharedBytes;
+
 typedef struct ScrBytes {
   size_t rc;
   size_t len; /* ELEMENT count, fixed at construction */
@@ -5782,8 +5884,46 @@ typedef struct ScrBytes {
   bool is_buffer; /* Buffer brand belongs to the view, not its backing. */
   bool is_data_view; /* DataView is distinct from a numeric typed array. */
   bool external; /* Root aliases foreign memory; releasing it never frees data. */
+  ScrSharedBytes *shared; /* Neutral backing, borrowed by views from their local owner. */
 } ScrBytes;
 
+/* Internal scoped locking is only for leaf memory operations. Never hold this
+ * guard across a script callback, blocking I/O, or a fiber suspension. */
+void scr_shared_enter(void);
+void scr_shared_leave(void);
+bool scr_shared_guard(const ScrBytes *, const ScrBytes *);
+void scr_shared_guard_release(bool *);
+#if defined(SCR_WORKERS) || (defined(SCR_LIB) && defined(SCR_THREAD_INSTANCES))
+#define SCR_SHARED_GUARD(a, b) bool scr_shared_held __attribute__((cleanup(scr_shared_guard_release))) = scr_shared_guard(a, b)
+#else
+#define SCR_SHARED_GUARD(a, b) ((void)0)
+#endif
+ScrSharedBytes *scr_shared_retain(ScrSharedBytes *);
+void scr_shared_release(ScrSharedBytes *);
+void scr_bytes_make_shared(ScrBytes *);
+ScrBytes *scr_shared_wrap(ScrSharedBytes *);
+void scr_bytes_read(const ScrBytes *, size_t, void *, size_t);
+void scr_bytes_write(ScrBytes *, size_t, const void *, size_t);
+ScrStr *scr_bytes_string(const ScrBytes *, size_t, size_t);
+ScrBytes *scr_bytes_snapshot(const ScrBytes *);
+void scr_bytes_snapshot_release(ScrBytes **);
+ScrBytes *scr_bytes_local_copy(ScrBytes *); /* +1; shared inputs are copied */
+void scr_bytes_require_unshared(const ScrBytes *);
+/* Snapshot before passing byte pointers to I/O or callback-capable consumers.
+ * The copy is local, so neither a lock nor shared raw memory escapes. */
+#if defined(SCR_WORKERS) || (defined(SCR_LIB) && defined(SCR_THREAD_INSTANCES))
+#define SCR_BYTES_SNAPSHOT(name) \
+  ScrBytes *scr_snapshot_##name __attribute__((cleanup(scr_bytes_snapshot_release))) = scr_bytes_snapshot(name); \
+  if (scr_snapshot_##name) name = scr_snapshot_##name
+#else
+#define SCR_BYTES_SNAPSHOT(name) ((void)0)
+#endif
+ScrDyn *scr_shared_array_buffer_new(ScrDyn *);
+ScrDyn *scr_worker_data(void);
+ScrDyn *scr_worker_parent_port(void);
+ScrDyn *scr_worker_new(double root, ScrStr *filename, ScrDyn *options);
+bool scr_shared_array_buffer_is(const ScrDyn *);
+bool scr_buffer_storage_is(const ScrDyn *);
 ScrBytes *scr_bytes_from_external(void *data, size_t length);
 ScrDyn *scr_ffi_memory_module(ScrDyn *catalog);
 ScrDyn *scr_ffi_argument(ScrDyn *value, ScrStr *type);
@@ -6198,9 +6338,11 @@ bool scr_dataview_write_u64_raw(ScrBytes *b, double offset, bool le, uint64_t va
  * Failures THROW catchably (scr_fs_throw, Node-shaped messages). */
 ScrBytes *scr_fs_read_file_bytes(ScrStr *path); /* +1 */
 /* readFileSync's runtime-encoding form (scr_bytes_io.c's note): +1 dyn
- * value — a Buffer box for undefined/null, a string for utf8 — or NULL
+ * value — a Buffer box for nullish/empty encodings, a decoded string otherwise — or NULL
  * with the exception pending. */
 ScrDyn *scr_fs_read_file_sync_dyn(ScrStr *path, const ScrDyn *enc);
+ScrStr *scr_fs_read_file_encoded(ScrStr *path, ScrStr *encoding);
+ScrStr *scr_fs_read_fd_encoded(double fd, ScrStr *encoding);
 ScrDyn *scr_fs_callback_value(ScrStr *member);
 ScrDyn *scr_fs_callback_call(ScrStr *member, const ScrDyn *args);
 ScrBytes *scr_fs_read_fd_bytes(double fd);      /* +1; the fd form (scr_lib.c) */
@@ -6696,7 +6838,7 @@ ScrArr *scr_tls_ca_root(void);        /* +1; === getCACertificates("bundled") */
  * ERR_CRYPTO_OPERATION_FAILED and leaves the set unchanged. Borrows. */
 void scr_tls_ca_set_default(ScrArr *certs);
 /* scr_tls.c's anchor consult: true iff setDefaultCACertificates ran;
- * *pem/*len then carry the concatenated NUL-terminated blocks (len 0 =
+ * *pem and *len then carry the concatenated NUL-terminated blocks (len 0 =
  * the empty set — verification fails, Node's own consequence), and *gen
  * a counter that bumps per set so the parsed chain re-parses on change. */
 bool scr_tls_ca_default_override(const char **pem, size_t *len, uint64_t *gen);