@loopdive/js2 0.57.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,456 / 43,135 (75.2 %)
+**test262 conformance**: 32,704 / 43,135 (75.8 %)
 <!-- AUTO:conformance-end -->
 
 ## Current Status

package/dist/cli.js

@@ -13,7 +13,7 @@ const args = process.argv.slice(2);
 if (args.includes("--ts7")) {
   process.env.JS2WASM_TS7 = "1";
 }
-const { compile } = await import("./index.js");
+const { compile, compileProject, entryHasRelativeImports } = await import("./index.js");
 const { buildDefaultDefines } = await import("./define-substitution-BcUeKC2A.js").then((n) => n.d);
 if (args.includes("--version") || args.includes("-v")) {
   console.log(getCliVersion());
@@ -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") {
@@ -276,20 +285,21 @@ if (!emulateExplicit && !emulateNode && /['"]node:[A-Za-z0-9_./-]+['"]/.test(sou
 }
 const name = basename(absInput, ".ts");
 const dir = outDir ? resolve(outDir) : dirname(absInput);
-const result = await compile(source, {
+const compileOptions = {
   ...optimize ? { optimize } : {},
   ...target ? { target } : {},
   ...allocator ? { allocator } : {},
   ...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,
   ...strictNoHostImports !== void 0 ? { strictNoHostImports } : {},
   ...Object.keys(defines).length > 0 ? { define: defines } : {}
-});
+};
+const result = entryHasRelativeImports(source) ? await compileProject(absInput, compileOptions) : await compile(source, compileOptions);
 if (!result.success) {
   for (const e of result.errors) {
     const severity = e.severity === "warning" ? "warning" : "error";

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). */
@@ -1819,6 +1866,17 @@ export interface CodegenContext {
      * Wasm byte-identical.
      */
     fnctorEscapeGate?: import('../fnctor-escape-gate.js').FnctorEscapeGateResult;
+    /**
+     * #2773 S1 (keystone) — fnctor name → reserved `$__fnctor_<Name>` struct type
+     * index. Populated up-front by `reserveFnctorStructTypes` (index.ts) at the
+     * deterministic type-init phase so the index is IDENTICAL across the hoist pass
+     * and the emit pass (the on-demand registration at the `new F()` site landed at
+     * a pass-dependent index → `ref.test`/`struct.get` desync). When a name is
+     * present here, `compileNewFunctionDeclaration` FILLS the reserved slot in place
+     * instead of pushing a new type (which would re-shift every downstream typeIdx).
+     * Empty for fnctor-free modules ⇒ byte-identical no-op.
+     */
+    fnctorReservedTypeIdx: Map<string, number>;
     /**
      * #1886 Slice B — Func index of the lazily-emitted
      * `__lin_u8_alloc(len:i32)->i32` bump allocator for linear-backed Uint8Array

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

@@ -1,4 +1,5 @@
 import { ts } from '../ts-api.js';
+import { FieldDef } from '../ir/types.js';
 import { CodegenContext, FunctionContext } from './context/types.js';
 /** Classification of a `new F()` fnctor allocation site. */
 export type FnctorGateClass = 
@@ -52,6 +53,28 @@ export interface FnctorEscapeGateResult {
      * `resolveReceiverStruct`; no lowering reads it, so emitted Wasm is byte-identical.
      */
     readonly receiverStruct: ReadonlyMap<ts.Expression, string>;
+    /**
+     * #2773 S2b — fnctor NAMES that own a `new this()` reconstruct site (a
+     * `new this()` inside a static / prototype method classified as an `F`
+     * reconstruct). The #2773 S1 up-front struct-type reservation
+     * (`reserveFnctorStructTypes`) unions this with {@link approvedNames} so a
+     * `Parser` reconstructed via `new this()` also gets a reserved
+     * `$__fnctor_Parser` slot. **S1 ships this as an EMPTY set** — S1 only READS it
+     * (so the reservation union is a no-op today); S2b populates it. Landing the
+     * field shape here keeps S2b purely additive.
+     */
+    readonly newThisOwnerNames: ReadonlySet<string>;
+    /**
+     * #2773 S1 — fnctor NAME → its function-like declaration (the body-bearer whose
+     * `this.<field> = …` writes derive the `$__fnctor_<Name>` struct shape). Covers
+     * EVERY fnctor `new F()` site seen (not just approved ones) so
+     * `reserveFnctorStructTypes` can resolve a name to the SAME declaration the
+     * on-demand `compileNewFunctionDeclaration` path uses — guaranteeing identical
+     * field derivation. A name with ≥2 distinct declarations keeps the first
+     * (deterministic by source order); ambiguity here only affects WHICH body shapes
+     * the reserved slot (matching the on-demand resolution at the dominant site).
+     */
+    readonly ctorDeclByName: ReadonlyMap<string, ts.FunctionDeclaration | ts.FunctionExpression>;
 }
 /**
  * Whether `expr` resolves to a plain function constructor (fnctor) rather than a
@@ -62,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.
@@ -90,3 +150,25 @@ export declare function resolveReceiverStruct(ctx: CodegenContext, fctx: Functio
  *          sites exist (so the pass is a no-op for class-only / fnctor-free code).
  */
 export declare function analyzeFnctorEscapeGate(checker: ts.TypeChecker, sourceFile: ts.SourceFile): FnctorEscapeGateResult;
+/**
+ * #2773 S1 (keystone) — derive the WasmGC field shape of a fnctor's
+ * `$__fnctor_<Name>` struct from its constructor body's `this.<field> = …`
+ * assignments. This is the **single source of truth** for the field set,
+ * EXTRACTED verbatim from the on-demand inline logic that lived in
+ * `compileNewFunctionDeclaration` (new-super.ts) so both the up-front reservation
+ * pass and the legacy on-demand fallback produce the SAME shape — divergent field
+ * order would give `struct.new` a different arity than the reserved type and trap.
+ *
+ * Mirrors the original logic exactly:
+ *   - collects EVERY `this.<field>` LHS across (possibly CHAINED) assignments
+ *     (`this.a = this.b = expr`), recursing into if/else and loop blocks;
+ *   - prefers the RHS type when the LHS is `any` (externref) — the RHS carries the
+ *     concrete type (e.g. number → f64);
+ *   - widens non-null `ref` fields to `ref_null` so `struct.new`'s `ref.null`
+ *     default-init is well-typed (a struct.new can't default a non-null ref).
+ *
+ * @param ctx      codegen context (for the checker + `resolveWasmType`)
+ * @param funcDecl the fnctor's function-like declaration (its body is read)
+ * @returns the ordered field set, or `[]` for a body-less / empty-body fnctor.
+ */
+export declare function deriveFnctorFields(ctx: CodegenContext, funcDecl: ts.FunctionDeclaration | ts.FunctionExpression): FieldDef[];

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.).
@@ -183,6 +200,41 @@ export declare function reserveTypedArraySubviewTypes(ctx: CodegenContext): void
  * fallback can't fire without a class).
  */
 export declare function reserveObjVecArrType(ctx: CodegenContext): void;
+/**
+ * #2773 S1 (KEYSTONE) — reserve every reconstructed-fnctor `$__fnctor_<Name>`
+ * struct type at the deterministic up-front type-init phase (the same stable
+ * point as `reserveTypedArraySubviewTypes` / `reserveObjVecArrType`), so the type
+ * index is IDENTICAL across the hoist pass and the emit pass.
+ *
+ * ROOT CAUSE this fixes: the on-demand registration at the `new F()` call site
+ * (`compileNewFunctionDeclaration`, new-super.ts — `ctx.mod.types.length`) assigns
+ * the index at a NON-deterministic mid-compile point that depends on which
+ * function the compiler reached first. The two-pass type numbering then desyncs:
+ * a typed-receiver `ref.test $__fnctor_<Name>` baked in the hoist pass misses the
+ * emit-pass `struct.new` index, and a read site compiled before the `new` site is
+ * excluded from `findAlternateStructsForField`'s candidate set. Reserving up-front
+ * collapses BOTH facets — the index is pass-invariant AND the candidate set is
+ * complete at every read site. This is the one thing the #2674 finalize
+ * dispatcher cannot retroactively fix (it can't rewrite a baked typeIdx).
+ *
+ * Two sub-passes — the ORDER is load-bearing:
+ *   (1) reserve ALL indices + names FIRST (placeholder struct, `structMap`,
+ *       `typeIdxToStructName`, `fnctorReservedTypeIdx`), so a cross-fnctor ref
+ *       field in sub-pass 2 (a `Parser` field typed `Scope` →
+ *       `(ref null $__fnctor_Scope)`) resolves against an already-registered
+ *       `structMap` entry. Do NOT collapse the two sub-passes.
+ *   (2) FILL each placeholder's fields via the shared `deriveFnctorFields`
+ *       (single source of truth — identical to the on-demand derivation) and
+ *       record `structFields` for candidate-set completeness.
+ *
+ * Determinism: the name set is SORTED, and the call-site position is fixed, so the
+ * reserved index is identical across the hoist pass and the emit pass (the entire
+ * point of the slice). Gated on a non-empty approved set ⇒ fnctor-free modules are
+ * byte-identical (a true no-op). Runs in BOTH host and standalone — the on-demand
+ * struct path is target-independent. A reserved-but-never-constructed placeholder
+ * is unreferenced ⇒ `dead-elimination` prunes + renumbers it cleanly.
+ */
+export declare function reserveFnctorStructTypes(ctx: CodegenContext): void;
 export declare function ensureLinearU8AllocHelper(ctx: CodegenContext): number;
 /**
  * #1618: Ensure __wasi_write_any_string(s: ref NativeString) -> void exists and
@@ -210,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/property-access.d.ts

@@ -289,6 +289,6 @@ export declare function emitThisReceiverGuardConvert(ctx: CodegenContext, fctx:
  * `ref.is_null`, and emit the index + read only in the non-null arm.
  */
 export declare function compileOptionalElementAccess(ctx: CodegenContext, fctx: FunctionContext, expr: ts.ElementAccessExpression): ValType | null;
-export declare function compileElementAccess(ctx: CodegenContext, fctx: FunctionContext, expr: ts.ElementAccessExpression): ValType | null;
+export declare function compileElementAccess(ctx: CodegenContext, fctx: FunctionContext, expr: ts.ElementAccessExpression, expectedType?: ValType): ValType | null;
 /** Inner element access logic — assumes objType is on the stack and non-null */
-export declare function compileElementAccessBody(ctx: CodegenContext, fctx: FunctionContext, expr: ts.ElementAccessExpression, objType: ValType): ValType | null;
+export declare function compileElementAccessBody(ctx: CodegenContext, fctx: FunctionContext, expr: ts.ElementAccessExpression, objType: ValType, expectedType?: ValType): ValType | null;

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/codegen/statements/loops.d.ts

@@ -1,6 +1,36 @@
 import { ts } from '../../ts-api.js';
 import { CodegenContext, FunctionContext } from '../context/types.js';
 export declare function compileWhileStatement(ctx: CodegenContext, fctx: FunctionContext, stmt: ts.WhileStatement): void;
+/**
+ * #1196: Detect mutations of the loop index or array binding inside a for-loop
+ * body. Used by the bounds-check elimination pass — we can only elide bounds
+ * checks for `arr[i]` if both `i` and `arr` are stable across every iteration.
+ *
+ * Returns `true` if the body contains anything that could mutate either
+ * binding:
+ *   - Direct assignment / compound assignment to `i` or `arr`
+ *     (`i = …`, `i += …`, `arr = …`, etc.)
+ *   - `i++ / ++i / i-- / --i` or the same on `arr`
+ *   - Method calls on `arr` (`arr.push()`, `arr.length = …`, etc.)
+ *   - `arr.length = …` assignment
+ *   - Any nested function / arrow / class — closures could capture and mutate
+ *     either binding outside our static view (conservative).
+ *
+ * Notes:
+ *   - `arr[k] = v` writes through the array but does not change the binding
+ *     itself or `arr.length` (when `k < arr.length`), so element writes are
+ *     allowed — they're the whole point of the optimisation.
+ */
+export declare function loopBodyMutatesIndexOrArray(body: ts.Statement, indexName: string, arrayName: string): boolean;
+/**
+ * #2682: the increment must strictly INCREASE `i` so that, combined with a
+ * non-negative init and the strict `i < recv.length` condition, `0 <= i < len`
+ * holds at every body point. `i++`/`++i` and `i += <positive int literal>`
+ * qualify; `i--`/`i -= k`/`i += <non-positive>` do NOT (would break the proof).
+ * Narrower than `detectI32LoopVar`'s incrementor check, which also accepts the
+ * decreasing forms.
+ */
+export declare function isIncreasingStep(incr: ts.Expression | undefined, name: string): boolean;
 export declare function compileForStatement(ctx: CodegenContext, fctx: FunctionContext, stmt: ts.ForStatement): void;
 export declare function compileDoWhileStatement(ctx: CodegenContext, fctx: FunctionContext, stmt: ts.DoStatement): void;
 export declare function compileForOfStatement(ctx: CodegenContext, fctx: FunctionContext, stmt: ts.ForOfStatement): void;