@loopdive/js2 0.58.0 → 0.59.0

package/README.md

@@ -57,7 +57,7 @@ STATUS.md rather than duplicating numbers that go stale. Standalone
 README until the current standalone regression is fixed.
 
 <!-- AUTO:conformance-start -->
-**test262 conformance**: 32,667 / 43,135 (75.7 %)
+**test262 conformance**: 32,704 / 43,135 (75.8 %)
 <!-- AUTO:conformance-end -->
 
 ## Current Status

package/dist/cli.js

@@ -66,13 +66,17 @@ Options:
                     is ON by default; this restores the pre-#1950 behaviour.
                     (No-op when binaryen/wasm-opt is unavailable — that path
                     already degrades to a one-line note, never a failure.)
-  --link-node-shims (WASI, #2625/#2633) Emit the per-module linkable node:<mod>
-                    shims instead of inlining the host APIs. Std-IO goes through
-                    node:fs: the module imports readSync/writeSync + its memory
-                    from node:fs (no wasi_snapshot_preview1 for stream IO) and
-                    links node-fs.wasm. console.log / process.std*.write lower to
-                    writeSync(1|2, …); stdin is readSync(0, …). Off by default —
-                    the inline fd_read/fd_write path is self-contained.
+  --link <ns>       (WASI, #2783) Leave the external namespace <ns> as link-time
+                    imports (repeatable) instead of inline-lowering it. Satisfied
+                    at instantiation by a preloaded provider module (e.g.
+                    'wasmtime --preload <ns>=provider.wasm'). Any namespace works
+                    (leave-as-import is universal); '--link node:fs' additionally
+                    selects the import-and-link std-IO path: the module imports
+                    readSync/writeSync + its memory from node:fs (no
+                    wasi_snapshot_preview1 for stream IO) and links node-fs.wasm.
+                    console.log / process.std*.write lower to writeSync(1|2, ...),
+                    stdin is readSync(0, ...). Off by default — every namespace is
+                    inline-lowered into a self-contained module.
   --emulate <env>   Emulate a host runtime's globals so they type-check without
                     @types/node. 'node' = ambient process/etc.; 'none' = off.
                     Auto-enabled (type-level only) when the source imports a
@@ -127,7 +131,7 @@ let allowFs = false;
 let quiet = false;
 let utf8Storage = false;
 let strictNoHostImports;
-let linkNodeShims = false;
+const linkedNamespaces = /* @__PURE__ */ new Set();
 let emulateNode = false;
 let emulateExplicit = false;
 let platform;
@@ -186,8 +190,13 @@ for (let i = 0; i < args.length; i++) {
     quiet = true;
   } else if (arg === "--utf8-storage") {
     utf8Storage = true;
-  } else if (arg === "--link-node-shims") {
-    linkNodeShims = true;
+  } else if (arg === "--link" || arg.startsWith("--link=")) {
+    const ns = arg.startsWith("--link=") ? arg.slice("--link=".length) : args[++i];
+    if (!ns) {
+      console.error("--link requires a namespace argument (e.g. --link node:fs)");
+      process.exit(1);
+    }
+    linkedNamespaces.add(ns);
   } else if (arg === "--emulate" || arg.startsWith("--emulate=")) {
     const env = arg.startsWith("--emulate=") ? arg.slice("--emulate=".length) : args[++i];
     if (env === "node") {
@@ -283,7 +292,7 @@ const compileOptions = {
   ...emitWit ? { wit: witPackageName ? { packageName: witPackageName } : true } : {},
   ...allowFs ? { allowFs: true } : {},
   ...utf8Storage ? { utf8Storage: true } : {},
-  ...linkNodeShims ? { linkNodeShims: true } : {},
+  ...linkedNamespaces.size ? { link: [...linkedNamespaces] } : {},
   ...emulateNode ? { emulateNode: true } : {},
   ...platform ? { platform } : {},
   fileName: absInput,

package/dist/codegen/array-element-typing.d.ts

@@ -1,21 +1,35 @@
 import { ts } from '../ts-api.js';
 /**
- * Return true if `expr` provably produces a 32-bit signed integer at runtime,
- * given that `i32Locals` is the set of locals already known to hold i32.
+ * Return true if `expr` provably produces a **canonical** signed-32-bit integer
+ * at runtime — a value `v ∈ ℤ ∩ [-2^31, 2^31)` whose f64 image is bit-identical
+ * to `v` (so `v` is not `-0`, not fractional, not NaN/±Inf, not `|v| ≥ 2^31`).
+ * `i32Locals` is the set of locals already known to hold i32.
  *
- * Recognised i32-safe forms (mirrors `isI32SafeExpr` in function-body.ts but
- * is intentionally narrower — we err on the side of disqualification):
- *   - integer numeric literal in [-2^31, 2^31)
- *   - identifier referencing a known-i32 local
- *   - bitwise `|`, `&`, `^`, `<<`, `>>` (always produce int32 per ECMAScript)
- *   - comparison ops (return boolean = i32)
- *   - unary `+` / `-` / `~` of an i32-safe operand
- *   - `+` / `-` / `*` of two i32-safe operands (overflow wraps; receiver is i32)
- *   - parenthesised / `as`-cast / non-null-asserted i32-safe expr
+ * The "canonical" property is the soundness contract for #2789: when EVERY write
+ * to a packed array yields a canonical i32, the i32-stored value read back as f64
+ * equals what the f64 backing would have stored, so NO read can observe a
+ * distinction i32 erases. That discharges the read-side proof obligation in the
+ * hybrid fast-path audit (Row 3) for free — there is no distinction to observe.
  *
- * Note: `>>>` is intentionally excluded — it produces uint32 which can sit
- * above 2^31 and would be reinterpreted as a negative i32 on store. The
- * conservative choice is to disqualify (the array would then stay f64).
+ * Recognised canonical-i32 forms (mirrors `isI32SafeExpr` in function-body.ts;
+ * intentionally narrow — we err on the side of disqualification):
+ *   - integer numeric literal in [-2^31, 2^31)  (always +0, never -0)
+ *   - identifier referencing a known-i32 local  (physically i32 ⇒ canonical)
+ *   - bitwise `|`, `&`, `^`, `<<`, `>>`  (ECMAScript defines these to yield a
+ *     value that equals ToInt32 of itself ⇒ canonical regardless of operands)
+ *   - comparison ops (return boolean = i32 0/1)
+ *   - `~x` (canonical int32) and unary `+x` of an i32-safe operand
+ *   - unary `-<non-zero integer literal>` only (a `-1`-style sentinel) — NOT
+ *     `-x` / `-(expr)`, which can be `-0` (#2789)
+ *   - parenthesised / `as`-cast / non-null-asserted canonical-i32 expr
+ *
+ * Deliberately EXCLUDED (would break canonicality → MISCOMPILE if packed):
+ *   - `+` / `-` / `*` arithmetic — f64 result stored via `i32.trunc_sat_f64_s`,
+ *     which SATURATES on overflow rather than yielding the spec-correct f64
+ *     (#2789, mirrors the #1236 scalar-local fix). Wrap-canonicalising patterns
+ *     like `(a*b) | 0` still qualify via the top-level bitwise op.
+ *   - `>>>` — produces uint32 which can sit above 2^31, reinterpreted as a
+ *     negative i32 on store.
  */
 export declare function isI32SafeExprForArray(expr: ts.Expression | undefined, i32Locals: ReadonlySet<string>, depth?: number): boolean;
 /**

package/dist/codegen/context/types.d.ts

@@ -55,22 +55,29 @@ export interface CodegenOptions {
     /** WASI target: emit WASI imports (fd_write, proc_exit) instead of JS host imports */
     wasi?: boolean;
     /**
-     * #2524 / #2633 — route std-IO through a separately compiled, linkable
-     * `node:fs` shim instead of inlining the `wasi_snapshot_preview1.fd_read`/
-     * `fd_write` glue. When set (WASI only), the user module imports
-     * `readSync`/`writeSync` plus its linear memory from `node:fs` and carries NO
+     * #2783 — the dynamic-linking axis: namespaces to leave as link-time imports
+     * (satisfied by a preloaded provider) instead of inline-lowering. `["node:fs"]`
+     * routes std-IO through the `node:fs` shim (the user module imports
+     * `readSync`/`writeSync` + its linear memory from `node:fs` and carries NO
      * `wasi_snapshot_preview1` import for the stream IO path; console.log /
-     * process.std*.write lower to `writeSync(1|2, …)`. `node-fs.wasm` implements
-     * the interface over WASI. The bespoke `js2wasm:node-process` shim was retired
-     * (#2633). Default off — the inline fd_read/fd_write path stays as fallback.
+     * process.std*.write lower to `writeSync(1|2, …)`; `node-fs.wasm` implements
+     * the interface over WASI). WASI-gated in `create-context.ts` (ignored for
+     * non-WASI targets). Default empty — the inline fd_read/fd_write path stays.
      */
-    linkNodeShims?: boolean;
+    link?: string[];
     /** Standalone target (#1470): pure WasmGC, no JS host imports and no WASI
      *  runtime. Implies `nativeStrings: true` and refuses to emit any
      *  `wasm:js-string` namespace or `env::__concat_*` / `__extern_toString` /
      *  `__unbox_string` JS-host string imports. Used so the compiled module is
      *  runnable under pure-Wasm engines (wasmtime, wasmer) without a JS host. */
     standalone?: boolean;
+    /** (#2796) Diff-test-harness fidelity: in JS-host mode, export the top-level
+     *  `__module_init` and do NOT run it via the wasm `start` section, so the host
+     *  invokes it AFTER `setExports` (symmetric with the standalone `_start`
+     *  model). Default false → top-level runs in the start section. See
+     *  `CompileOptions.deferTopLevelInit`. WASI is unaffected (it already exports
+     *  `_start`). */
+    deferTopLevelInit?: boolean;
     /**
      * Experimental: route a narrow set of functions through the middle-end IR
      * (see `src/ir/`). Defaults to **on** since #1131 (the front-end driver
@@ -842,6 +849,24 @@ export interface CodegenContext {
      */
     holeTypeIdx: number;
     holeGlobalIdx: number | undefined;
+    /**
+     * (#2800) The mutable i32 `__in_module_init` flag — 1 for the duration of
+     * `__module_init` (the Wasm `start` section in gc/host mode, which runs INSIDE
+     * `WebAssembly.instantiate`, BEFORE the host wires struct getters via
+     * `__setExports`), 0 otherwise. The delete-aware `any`-receiver READ
+     * (`tryEmitDeleteAwareDynamicGet`) branches on it: while init runs (host
+     * `__extern_get` can't reach `__sget_<field>` → returns undefined for every
+     * struct field), read the slot HOST-FREE via the `__get_member_<name>`
+     * dispatcher; at runtime use the tombstone-aware host `__extern_get`.
+     *
+     * `inModuleInitFlagReads` collects the `global.get` flag-read Instr objects
+     * emitted at read sites (with a placeholder index); `finalizeInModuleInitFlag`
+     * allocates the i32 global AFTER every import settles and patches their
+     * `.index` + records the final slot in `inModuleInitGlobalIdx`. Undefined/empty
+     * for delete-free / standalone / WASI modules (byte-identical).
+     */
+    inModuleInitFlagReads: Instr[] | undefined;
+    inModuleInitGlobalIdx: number | undefined;
     /**
      * (#2580 M0) Value-rep dynamic-read substrate. Set true by a call site that
      * needs the runtime property-presence read primitives (`__dyn_has` /
@@ -1675,6 +1700,11 @@ export interface CodegenContext {
      *  `__unbox_string`, `__str_from_mem`, `__str_to_mem`,
      *  `__str_extern_len`). Implies `nativeStrings === true`. */
     standalone: boolean;
+    /** (#2796) Diff-test-harness fidelity: in JS-host mode, export the top-level
+     *  `__module_init` and do NOT wire the wasm `start` section to it, so the host
+     *  runs it after `setExports` (symmetric with the standalone `_start` model).
+     *  Default false. WASI is unaffected. */
+    deferTopLevelInit: boolean;
     /** (#2179) True when the module body contains any `delete` of a property or
      *  element access (e.g. `delete o.a` / `delete o[k]`). Pre-scanned once at
      *  module setup. When true, `any`/`unknown`-typed property READS in JS-host
@@ -1745,10 +1775,27 @@ export interface CodegenContext {
      * `node:fs` `readSync`/`writeSync` calls (over a shim-owned, imported linear
      * memory) instead of inline `fd_read`/`fd_write`. console.log/warn/error and
      * process.std*.write lower to `writeSync(1|2, …)`; the bespoke
-     * `js2wasm:node-process` shim was retired (#2633). See `linkNodeShims` in
-     * `CodegenOptions`.
+     * `js2wasm:node-process` shim was retired (#2633). Driven by the `link` set
+     * (`["node:fs"]`).
+     *
+     * #2783 — an INTERNAL convenience boolean, **derived** from
+     * `linkedNamespaces.has("node:fs")` (there is no user-facing `linkNodeShims`
+     * option anymore — `link: string[]` is the only input). The two
+     * are computed together in `create-context.ts` from the same (WASI-gated)
+     * `link` set so they can never drift. Keeping this boolean lets the ~30
+     * existing `ctx.linkNodeShims` read sites stay zero-churn while the underlying
+     * state generalizes to an arbitrary set of linked namespaces.
      */
     linkNodeShims: boolean;
+    /**
+     * #2783 — the set of external namespaces left as **link-time imports** for
+     * this compile (WASI-gated; empty for non-WASI targets). `node:fs` membership
+     * additionally drives the import-and-link std-IO codegen path (see
+     * `linkNodeShims`, derived from this set). For an arbitrary namespace,
+     * membership only permits its imports past the strict `--no-host-imports` /
+     * WASI leaked-host-import gate (`assertNoLeakedHostImports`).
+     */
+    linkedNamespaces: ReadonlySet<string>;
     /** #2631/#2633: func index of the imported `node:fs::readSync` (fd,ptr,len)->i32 (-1 = not registered). */
     nodeFsReadSyncIdx: number;
     /** #2631/#2633: func index of the imported `node:fs::writeSync` (fd,ptr,len)->i32 (-1 = not registered). */

package/dist/codegen/fnctor-escape-gate.d.ts

@@ -85,6 +85,43 @@ export interface FnctorEscapeGateResult {
  * `undefined`.
  */
 export declare function resolveFnctorSymbol(checker: ts.TypeChecker, calleeExpr: ts.Expression): ts.Symbol | undefined;
+/**
+ * #2681/#2686 — resolve the fnctor `F` that OWNS the enclosing method a node sits
+ * in, for a `new this(…)` site or a lifted method body. `this` inside a method
+ * `F.method = function(){…}` / `F.prototype.m = function(){…}` / aliased `var pp =
+ * F.prototype; pp.m = function(){…}` binds to `F` (static) or an `F` instance
+ * (prototype). Walks up to the nearest non-arrow function (arrows do not rebind
+ * `this`) and resolves its defining assignment's holder to a fnctor symbol.
+ *
+ * Returns `{ name, sym, viaPrototype }` where `viaPrototype` is true for a
+ * prototype/aliased method (`this` is an INSTANCE — the read-dispatch case) and
+ * false for a direct static method (`this` is the CONSTRUCTOR — the `new this()`
+ * reconstruct case). `undefined` when the enclosing function is not a fnctor
+ * method, or the holder does not resolve to a user fnctor.
+ */
+export declare function resolveEnclosingFnctorOwner(checker: ts.TypeChecker, node: ts.Node): {
+    name: string;
+    sym: ts.Symbol;
+    viaPrototype: boolean;
+} | undefined;
+/**
+ * #2681/#2686 A3 — the `__fnctor_<F>` struct name a lifted PROTOTYPE method's
+ * `this` receiver resolves to, when `F` is approved for reconstruction. Sets
+ * `FunctionContext.thisStructName` (closures.ts) so the dynamic `this.<field>`
+ * read dispatch (property-access.ts) routes through the finalize-filled
+ * `__get_member_<name>` dispatcher.
+ *
+ * Deliberately NOT gated on `ctx.structMap.has(__fnctor_<F>)`: the reader method
+ * frequently compiles BEFORE the `new this()` site that registers the struct
+ * (acorn defines `pp.parseExprAtom` long before the static `Parser.parse`). The
+ * dispatcher is reserved at the read site and FILLED at finalize over the
+ * COMPLETE type table, so a struct registered later is still enumerated — pinning
+ * on `approvedNames` (frozen pre-codegen at index.ts) is order-independent and
+ * correct, while a `structMap.has` gate would race the compile order and miss.
+ * Excludes static methods (`viaPrototype === false`) — their `this` is the
+ * constructor function-value, not an instance.
+ */
+export declare function resolveLiftedMethodThisStruct(ctx: CodegenContext, fn: ts.FunctionExpression | ts.ArrowFunction): string | undefined;
 /**
  * #2660 PART-1 — resolve the WasmGC struct a member-access RECEIVER expression
  * concretely is, for the dynamic read/write/compound dispatch to PIN to.

package/dist/codegen/host-import-allowlist.d.ts

@@ -80,7 +80,7 @@ export declare function lookupAllowlistEntry(name: string): HostImportAllowlistE
  * `nativeStrings` mode which strict mode auto-enables; they should not
  * appear when strict mode is on.)
  */
-export declare function isHostImportAllowed(module: string, name: string): {
+export declare function isHostImportAllowed(module: string, name: string, linkedNamespaces?: ReadonlySet<string>): {
     allowed: true;
 } | {
     allowed: false;
@@ -129,7 +129,7 @@ export interface LeakedHostImport {
 export declare function scanForLeakedHostImports(imports: ReadonlyArray<{
     module: string;
     name: string;
-}>): LeakedHostImport[];
+}>, linkedNamespaces?: ReadonlySet<string>): LeakedHostImport[];
 /**
  * (#2094) Build the structured compile error for a host import that leaked
  * into a finished standalone/strict binary. Distinct from

package/dist/codegen/index.d.ts

@@ -89,6 +89,23 @@ export declare function generateModule(ast: TypedAST, options?: CodegenOptions):
         message: string;
     }[];
 };
+/**
+ * Emit __vec_get(externref, i32) -> externref and __vec_len(externref) -> i32
+ * exports so the runtime can iterate WasmGC vec structs that were coerced to
+ * externref (e.g. arrays stored in `any`-typed variables).
+ *
+ * For each registered vec type, emits ref.test/ref.cast dispatch to extract
+ * the length or the indexed element, boxing the result to externref.
+ */
+/**
+ * (#2784 S3) Reserve a `__vec_push` / `__vec_pop` helper funcIdx UP FRONT so the
+ * native-vec method dispatch (calls.ts) can bake the call at compile time — the
+ * helper bodies are only built in the finalize `emitVecAccessExports` pass, which
+ * runs AFTER the method-call site compiles. Pushes a valid placeholder body +
+ * export + funcMap entry (shift-tracked); the finalize pass FILLS the body in
+ * place (fill-or-build in `_emitVecAccessExportsInner`). Idempotent.
+ */
+export declare function reserveVecMethodHelper(ctx: CodegenContext, kind: "push" | "pop" | "get"): number;
 /**
  * Compile multiple typed source files into a single WasmModule IR.
  * All source files share the same codegen context (funcMap, structMap, etc.).
@@ -245,7 +262,7 @@ export declare function ensureWasiWriteAnyStringHelper(ctx: CodegenContext, useS
  * it to the *runtime* fd. This backs the STRING overload of `node:fs`
  * `writeSync(fd, str, position?, encoding?)`, where the fd is an arbitrary
  * integer (not just stdout/stderr). Two modes (#2655):
- *   - shim (`--link-node-shims`): `writeSync(fd, ptr, len)` returns the byte count.
+ *   - shim (`--link node:fs`): `writeSync(fd, ptr, len)` returns the byte count.
  *   - direct (standalone `--target wasi`): build a `{ base=ptr, len }` iovec at
  *     memory[0..7], call `fd_write(fd, iovs=0, 1, nwritten=8)`, load nwritten.
  */

package/dist/codegen/literals.d.ts

@@ -42,6 +42,33 @@ export declare function compileObjectLiteralAsExternref(ctx: CodegenContext, fct
  * value semantics suffice; plain data structs keep `extern.convert_any`.
  */
 export declare function materializeStructAsDynamicObject(ctx: CodegenContext, fctx: FunctionContext, structTypeIdx: number): boolean;
+/**
+ * (#2714 / #2804) True when a spread-containing object literal must be built via
+ * the host plain-object (`$Object`/externref) path rather than a closed struct,
+ * because its evaluation context does not pin a CONCRETE object SHAPE the struct
+ * path could faithfully build/enumerate: `any` / `unknown` / `object`, NO
+ * contextual type at all, or a shapeless object type with zero own properties
+ * (e.g. the `object` param of `Object.keys`).
+ *
+ * This is the single source of truth for the routing decision below AND for the
+ * variable-declaration local typing (statements/variables.ts, index.ts var
+ * hoist). Keeping them in lockstep is what fixes #2804: `const b = { ...a, z: 3 }`
+ * (no annotation) has NO contextual type, so the literal takes the host path —
+ * but the receiving variable's INFERRED type is a concrete struct `{x;y;z}`, so
+ * without this shared predicate the local was typed as that struct while the
+ * initializer produced a host `$Object`, and the externref→struct coercion
+ * (ref.test/ref.cast) failed at runtime → `b.x` read NaN / null. The variable
+ * sites consult this predicate and force an externref local so the local
+ * representation matches the host-object value (and `b.x` routes through
+ * `__extern_get`, preserving the spread's insertion-order keys + values, which
+ * the struct path cannot — its field order follows TS's own-prop-first inferred
+ * type, not the runtime CopyDataProperties insertion order).
+ *
+ * A CONCRETE annotated target (`const x: { a: number } = { ...o }`, ≥1 property)
+ * has a specific contextual type → returns false → keeps the struct path so
+ * typed consumers still receive a struct (#2714 control).
+ */
+export declare function objectLiteralSpreadTakesHostPath(ctx: CodegenContext, expr: ts.ObjectLiteralExpression): boolean;
 export declare function compileObjectLiteral(ctx: CodegenContext, fctx: FunctionContext, expr: ts.ObjectLiteralExpression): ValType | null;
 /**
  * Try to evaluate an expression to a constant numeric or string value at compile time.

package/dist/codegen/member-set-dispatch.d.ts

@@ -1,4 +1,4 @@
-import { CodegenContext } from './context/types.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
 /**
  * Reserve (or fetch) the member-set dispatcher `__set_member_<name>(recv, val)`
  * funcIdx with a placeholder body. The real body is built by
@@ -14,7 +14,7 @@ import { CodegenContext } from './context/types.js';
  *   - `__box_number`/`__unbox_number` (union imports — the per-struct arms may
  *     unbox the externref value into an f64/i32 field via `coercionInstrs`).
  */
-export declare function reserveMemberSetDispatch(ctx: CodegenContext, propName: string, strict: boolean): number | undefined;
+export declare function reserveMemberSetDispatch(ctx: CodegenContext, propName: string, strict: boolean, fctx?: FunctionContext): number | undefined;
 /**
  * Fill every reserved `__set_member_<name>` dispatcher body at FINALIZE, after
  * every struct type (incl. late-registered fnctor structs) is known. READ-ONLY

package/dist/codegen/registry/imports.d.ts

@@ -1,4 +1,4 @@
-import { Import } from '../../ir/types.js';
+import { Import, Instr } from '../../ir/types.js';
 import { CodegenContext } from '../context/types.js';
 /**
  * Register an import (`module.name`) on the current module.
@@ -37,6 +37,24 @@ export declare function addImport(ctx: CodegenContext, module: string, name: str
 export declare function addStringConstantGlobal(ctx: CodegenContext, value: string): void;
 /** Return the absolute Wasm global index for a new module-defined global. */
 export declare function nextModuleGlobalIdx(ctx: CodegenContext): number;
+/**
+ * (#2800) Record a `global.get __in_module_init` instruction for FINALIZE-time
+ * index resolution. Returns a fresh `global.get` Instr with a PLACEHOLDER index
+ * and registers it on `ctx.inModuleInitFlagReads`; the caller bakes this exact
+ * object into its body. `finalizeInModuleInitFlag` (codegen/index.ts) allocates
+ * the i32 flag global AFTER every import global has settled and patches each
+ * recorded instr's `.index` to the final slot — so no read can desync when a
+ * later string-constant import shifts the module-global range (the live-baked
+ * index hazard #2043 across closure bodies the per-add fixup can miss).
+ *
+ * The flag is 1 only while `__module_init` runs; the delete-aware `any`-receiver
+ * read branches on it (init → host-free `__get_member_<name>` slot dispatcher;
+ * runtime → tombstone-aware host `__extern_get`). gc/host runs `__module_init`
+ * via the Wasm `start` section INSIDE `WebAssembly.instantiate`, before the host
+ * wires struct getters (`__setExports`), so the host read returns undefined for
+ * every struct field at init — this flag is what makes init reads correct.
+ */
+export declare function recordInModuleInitFlagRead(ctx: CodegenContext): Instr;
 /** Convert an absolute Wasm global index to a local module-globals array index. */
 export declare function localGlobalIdx(ctx: CodegenContext, absIdx: number): number;
 /**

package/dist/codegen/shared.d.ts

@@ -64,6 +64,30 @@ export declare function flushLateImportShifts(ctx: CodegenContext, fctx: Functio
  * Check if a ValType is the any-value boxed type used for TS `any`.
  */
 export declare function isAnyValue(type: ValType, ctx: CodegenContext): boolean;
+/**
+ * (#2770, S5b of #2773) Brand an extern-method result ValType as a *boolean*
+ * when the method's declared TS return type is exactly `boolean`, so the
+ * `any`/return coercion boxes it via `__box_boolean` (→ `true`/`false`) instead
+ * of `__box_number` (→ `1`/`0`).
+ *
+ * Why a per-call-site wrap (not just registration): a boolean extern method's
+ * func type carries an `i32` result, and `funcTypeKey` (registry/types.ts) keys
+ * results on `.kind` only — so a branded `{i32,boolean:true}` result func type
+ * dedups to a pre-existing *unbranded* `…->i32` type. `getWasmFuncReturnType`
+ * then reads back the deduped unbranded i32 and the brand is lost at every
+ * `getWasmFuncReturnType(ctx, idx) ?? resolveWasmType(ctx, retType)` dispatch
+ * site. Re-branding from the call's TS return type here recovers it regardless
+ * of dedup. (Registration is also branded so the direct `methodInfo.results[0]`
+ * path in extern.ts is honest at source.)
+ *
+ * Over-boxing guards — idempotent, never widens:
+ *  - only a *bare* `i32` is touched (f64/externref/ref/ref_null pass through);
+ *  - an already `{i32,boolean:true}` value short-circuits (idempotent);
+ *  - only an *exactly*-`boolean` declared return is branded (numbers, unions,
+ *    `void`, etc. pass through unchanged — `map.get`/`indexOf`/`.size` stay
+ *    numbers).
+ */
+export declare function brandExternMethodResult(_ctx: CodegenContext, tsReturnType: ts.Type | undefined, valType: ValType): ValType;
 type EnsureAnyHelpersFn = (ctx: CodegenContext) => void;
 export declare function registerEnsureAnyHelpers(fn: EnsureAnyHelpersFn): void;
 type AddUnionImportsFn = (ctx: CodegenContext) => void;

package/dist/index.d.ts

@@ -315,19 +315,48 @@ export interface CompileOptions {
      *  Default: false (calls to fs.readFileSync / fs.writeFileSync raise a compile error). */
     allowFs?: boolean;
     /**
-     * #2625 / #2633 — emit the per-module linkable `node:<mod>` shims instead of
-     * inlining the host APIs. WASI-only (ignored for other targets). When set,
-     * std-IO is routed through `node:fs`: the user module imports `readSync`/
-     * `writeSync` plus its linear memory from `node:fs` and carries no
-     * `wasi_snapshot_preview1` import for stream IO; console.log / process.std*.write
-     * lower to `writeSync(1|2, …)` and synchronous stdin is `readSync(0, …)`. Link
-     * against `node-fs.wasm` (or `--preload node:fs=node-fs.wasm` under wasmtime).
-     * Default off — the self-contained inline `fd_read`/`fd_write` path stays. The
-     * bespoke `js2wasm:node-process` shim (`process.stdin.read`/`stdout_write`/…)
-     * was retired in #2633; `process.stdin.read(buf, offset)` is no longer a
-     * recognised API (it matched no real Node surface — use `node:fs` `readSync`).
+     * (#2796) Differential-test-harness fidelity flag. In the default JS-host
+     * (WasmGC) target, top-level module code runs via the wasm `start` section —
+     * i.e. DURING `WebAssembly.instantiate`, BEFORE the host can call
+     * `setExports(instance.exports)`. Top-level code that introspects WasmGC
+     * structs (`for…in` / `Object.keys` over a runtime-shaped object) needs the
+     * `__struct_field_names` / `__sget_*` exports, which only exist once the
+     * instance is constructed — so during the start section they resolve to
+     * nothing and a `for…in` enumerates zero keys. The standalone/WASI path does
+     * NOT hit this: it runs top-level code via an explicitly-called `_start`
+     * export AFTER instantiation, when every export is reachable.
+     *
+     * When `true`, emit the top-level `__module_init` as an EXPORT and do NOT run
+     * it via the wasm `start` section, so the host can invoke
+     * `instance.exports.__module_init()` AFTER wiring `setExports` — symmetric
+     * with the standalone `_start` model. The differential-test harness
+     * (`scripts/diff-test.ts`) sets this so the HOST lane runs top-level code with
+     * the same fully-wired runtime the standalone lane uses, rather than tripping
+     * over an exports-timing artifact of the harness. Default `false` →
+     * byte-identical output (top-level runs in the wasm `start` section) for every
+     * other consumer (website, playground, test262, library users).
+     */
+    deferTopLevelInit?: boolean;
+    /**
+     * #2783 — general `--link <namespace>` dynamic-linking axis (the ONLY
+     * link-vs-inline control; the old `linkNodeShims` boolean was removed). Each
+     * listed namespace is left as a **link-time import** (satisfied at
+     * instantiation by a preloaded provider module, e.g.
+     * `wasmtime --preload node:fs=node-fs.wasm`) instead of being inline-lowered to
+     * a self-contained module. "Leave-as-import" is the universal capability (any
+     * external namespace can be a wasm import); "inline-lower" is the special
+     * capability the compiler only has for a known few (`node:fs` fd IO). So for an
+     * arbitrary namespace `link: ["acme:telemetry"]` simply permits its imports
+     * past the strict `--no-host-imports` / WASI gate; for `node:fs` it
+     * additionally selects the import-and-link std-IO path (the user module imports
+     * `readSync`/`writeSync` + its linear memory from `node:fs` and carries no
+     * `wasi_snapshot_preview1` import for stream IO; console.log /
+     * process.std*.write lower to `writeSync(1|2, …)`, stdin is `readSync(0, …)`).
+     *
+     * WASI-gated: ignored for non-WASI targets. Default empty — every namespace
+     * stays standalone / inline-lowered. CLI: `--link <ns>` (repeatable).
      */
-    linkNodeShims?: boolean;
+    link?: string[];
     /**
      * Node API emulation (#2603). Opt-in via `--emulate node`. When set, the
      * checker is given an ambient `process` declaration so Node globals js2wasm

package/dist/index.js

@@ -1,6 +1,6 @@
 import * as path from "path";
-import { i as isKnownLibName, g as getLibSourceFile, a as getDefaultEnvironment, r as rewriteCjsRequire, f as forEachChild, e as entryHasRelativeImports, c as compileSource, b as compileMultiSource, d as buildImports, h as compileFilesSource, j as compileToObjectSource } from "./runtime-d_SmcBlN.js";
-import { k, l, m, n, o, p, q, s, t } from "./runtime-d_SmcBlN.js";
+import { i as isKnownLibName, g as getLibSourceFile, a as getDefaultEnvironment, r as rewriteCjsRequire, f as forEachChild, e as entryHasRelativeImports, c as compileSource, b as compileMultiSource, d as buildImports, h as compileFilesSource, j as compileToObjectSource } from "./runtime-UuI75J3h.js";
+import { k, l, m, n, o, p, q, s, t } from "./runtime-UuI75J3h.js";
 import ts from "typescript";
 class IncrementalLanguageService {
   currentSource = "";