@polyengine/runtime 0.1.0-pre.g633468a

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,23 @@
+# @polyengine/runtime
+
+A WebAssembly Component Model host for JavaScript engines: plan executor, canonical ABI, 0.3 task scheduler, JSPI bridge, and embedder API.
+
+Part of [polyengine](https://github.com/polymorph-components/polyengine), a
+WebAssembly Component Model host for JavaScript engines. This is the npm
+distribution; the same package is published to JSR as `jsr:@polyengine/runtime`, and the
+two are built from the same sources at the same version.
+
+```sh
+npm install @polyengine/runtime
+```
+
+```js
+import * as api from "@polyengine/runtime/cabi";
+```
+
+Entry points: `./cabi`, `./cache`, `./digest`, `./embedder`, `./exec`, `./intrinsics`, `./jspi`, `./plan`, `./shim`, `./task`.
+
+ESM only, Node >= 22.14. Documentation, examples and the embedder API contract
+live in the [repository](https://github.com/polymorph-components/polyengine).
+
+Apache-2.0.

package/esm/cabi/async_values.js

@@ -0,0 +1,162 @@
+// Lift and lower for the async value types: `stream`, `future` and
+// `error-context` (definitions.py `lift_async_value` line 1530,
+// `lower_stream`/`lower_future` line 1828, `lift_error_context` line 1451,
+// `lower_error_context` line 1757).
+//
+// ===========================================================================
+// HOST SHAPE (interpreter decision — flagged, per contracts/descriptor-ir.md)
+// ===========================================================================
+//
+// Every other `ComponentValue` in this interpreter is plain data: numbers,
+// strings, arrays, records. The async value types cannot be, and the reference
+// is explicit about why: `lift_async_value` returns `e.shared` — the *shared*
+// stream/future object, not a copy and not an index — and `lower_stream` wraps
+// that same object in a fresh `ReadableStreamEnd` in the destination
+// instance's handle table. The identity of the shared object is the value; two
+// components holding ends of one stream must observe each other's copies.
+//
+// So a lifted `stream`/`future` is a `SharedStreamImpl`/`SharedFutureImpl`
+// instance, and a lifted `error-context` is an `ErrorContext` instance. Host
+// code that receives one should treat it as an opaque token. This is the same
+// concession the reference makes; it is recorded here because it widens what
+// `ComponentValue` can hold beyond plain data, which the descriptor-IR
+// contract's "host-shaped component values" wording did not anticipate.
+import { copyCensus, ERROR_CONTEXT, hasBrand } from "@polyengine/protocol";
+import { assert_, trapIf } from "./trap.js";
+import { contains, fmtValType } from "./types.js";
+import { CopyState, ErrorContext, ReadableFutureEnd, ReadableStreamEnd, SharedFutureImpl, sameElemType, SharedStreamImpl, } from "../task/streams.js";
+/**
+ * Diagnostic for a handle-table entry that carries the A9 error-context brand
+ * without being one of THIS copy's `ErrorContext`s (amendment A9, issue #83).
+ *
+ * A backstop, deliberately: the embedder's lowering site (embedder/values.ts)
+ * refuses a foreign error-context before it can ever reach a handle table, so
+ * this branch should be unreachable. It exists because "handle is not an
+ * error-context" is precisely the misleading generic that made #83 expensive
+ * to diagnose — if a path ever does get here, it says what happened.
+ *
+ * This layer is below `embedder/`, so it composes the census from
+ * `@polyengine/protocol` directly rather than importing `embedder/copy.ts`.
+ */
+export function errorContextTrapMessage(where, e) {
+    if (!hasBrand(e, ERROR_CONTEXT)) {
+        return `${where}: handle is not an error-context`;
+    }
+    const census = copyCensus();
+    return `${where}: this error-context was minted by a DIFFERENT polyengine ` +
+        `runtime copy and cannot be used through this one` +
+        `${census === "" ? "" : ` (${census})`} ` +
+        `(contracts/embedder-api.md amendment A9, issue #83)`;
+}
+/** definitions.py `contains_borrow` — async values may never carry borrows. */
+function containsBorrow(t) {
+    return contains(t, (x) => x.kind === "borrow");
+}
+/**
+ * definitions.py `lift_async_value` (line 1530).
+ *
+ * Lifting **removes** the handle: the readable end is transferred out of this
+ * instance's table, which is why a stream can only be passed on once.
+ */
+function liftAsyncValue(cx, i, t, 
+// deno-lint-ignore no-explicit-any
+EndT, elem, what) {
+    assert_(!containsBorrow(t), `${what} may not contain a borrow`);
+    const inst = cx.inst;
+    assert_(inst !== null, `${what} lift requires a component instance`);
+    const e = inst.handles.remove(i);
+    trapIf(!(e instanceof EndT), `${what} lift: handle is not a ${what} end`);
+    const end = e;
+    trapIf(!sameElemType(end.shared.t, elem), `${what} lift: element type mismatch`);
+    trapIf(end.state === CopyState.DONE, what === "future"
+        ? "cannot lift future after previous read succeeded"
+        : "cannot lift stream after being notified that the writable end dropped");
+    trapIf(end.state !== CopyState.IDLE, `cannot remove busy ${what}`);
+    trapIf(end.inWaitableSet(), `cannot lift ${what} while it's in a waitable set`);
+    // Remember the driving store so a host wrapper can pump the guest later.
+    // Single-store only: a shared object crossing into a SECOND store is
+    // unsupported misuse — fail loudly rather than silently pumping the first
+    // (review advisory, host-streams round). Class field initializes to null;
+    // != null covers both sentinels.
+    const holder = end.shared;
+    const store = inst.store;
+    if (holder.boundStore != null && store != null) {
+        // A9: when several runtime copies are loaded, "a second store" is very
+        // often "a second COPY" — the shared object was minted by one runtime and
+        // is being driven by another. The two stores are indistinguishable from
+        // here (stores carry no copy identity), so the census is appended as the
+        // hypothesis it is, rather than asserted (issue #83).
+        const census = copyCensus();
+        assert_(holder.boundStore === store, `${what} crossed into a second store; multi-store is unsupported` +
+            (census === ""
+                ? ""
+                : ` (${census} — a value from one copy cannot be lowered through ` +
+                    `another)`));
+    }
+    holder.boundStore ??= store;
+    // Host-wrapper re-arm hook (#162, embedder-api amendment A15): the readable
+    // end just left a guest table, so whoever receives it can act on it again.
+    // See `bindOnLower` in exec/host_streams.ts for the retention rule.
+    end.shared.onLifted?.(inst);
+    return end.shared;
+}
+export function liftStream(cx, i, t) {
+    return liftAsyncValue(cx, i, t, ReadableStreamEnd, t.element, "stream");
+}
+export function liftFuture(cx, i, t) {
+    return liftAsyncValue(cx, i, t, ReadableFutureEnd, t.element, "future");
+}
+/** definitions.py `lower_stream` (line 1828). */
+export function lowerStream(cx, v, t) {
+    assert_(v instanceof SharedStreamImpl, "lower_stream expects a shared stream value");
+    assert_(!containsBorrow(t), "stream may not contain a borrow");
+    // Loud element-type check. A host-created stream carries a hand-passed
+    // `ValType` (typed derivation is bindgen's job), so this is the first point
+    // at which a mismatch against the guest's declared `stream<T>` can be
+    // caught — and a silent mismatch would corrupt every copy, since the
+    // element type is what sizes and lifts the buffer. `fmtValType`, not
+    // `JSON.stringify`: the latter throws on resource-bearing element types
+    // (cabi/types.ts `valTypeEqual` contract note) — and as a template-literal
+    // argument it was evaluated even when the assertion PASSED.
+    const declared = t.element ?? null;
+    if (!sameElemType(v.t, declared)) {
+        assert_(false, `stream element type mismatch: host end carries ` +
+            `${fmtValType(v.t)}, callee expects ${fmtValType(declared)}`);
+    }
+    const inst = cx.inst;
+    assert_(inst !== null, "stream lower requires a component instance");
+    v.boundStore ??=
+        inst.store;
+    v.onLowered?.(inst);
+    return inst.handles.add(new ReadableStreamEnd(v));
+}
+/** definitions.py `lower_future` (line 1833). */
+export function lowerFuture(cx, v, t) {
+    assert_(v instanceof SharedFutureImpl, "lower_future expects a shared future value");
+    assert_(!containsBorrow(t), "future may not contain a borrow");
+    const declared = t.element ?? null;
+    if (!sameElemType(v.t, declared)) {
+        assert_(false, `future element type mismatch: host end carries ` +
+            `${fmtValType(v.t)}, callee expects ${fmtValType(declared)}`);
+    }
+    const inst = cx.inst;
+    assert_(inst !== null, "future lower requires a component instance");
+    v.boundStore ??=
+        inst.store;
+    v.onLowered?.(inst);
+    return inst.handles.add(new ReadableFutureEnd(v));
+}
+/** definitions.py `lift_error_context` (line 1451). Does NOT remove the handle. */
+export function liftErrorContext(cx, i) {
+    const inst = cx.inst;
+    assert_(inst !== null, "error-context lift requires a component instance");
+    const e = inst.handles.get(i);
+    trapIf(!(e instanceof ErrorContext), errorContextTrapMessage("error-context lift", e));
+    return e;
+}
+/** definitions.py `lower_error_context` (line 1757). */
+export function lowerErrorContext(cx, v) {
+    const inst = cx.inst;
+    assert_(inst !== null, "error-context lower requires a component instance");
+    return inst.handles.add(v);
+}

package/esm/cabi/bulk_lists.js

@@ -0,0 +1,198 @@
+// Bulk (TypedArray-backed) list copies for flat element types (issue #67).
+//
+// The per-element interpreted `load()`/`store()` costs ~13-45 ns/element
+// (despecialize + asserts + DataView per element); these helpers replace the
+// loop body with one typed-array view per list and a tight per-element pass
+// that preserves the interpreted path's EXACT observable semantics:
+//
+//   * integers: the same `assert_` type-shape texts as `storeInt` (`"int
+//     store"`, `"64-bit store requires bigint"`) but, unlike the scalar path
+//     in memory.ts (`storeInt`'s range `assert_`s, issue #96), NOT the same
+//     range check: this bulk path wraps out-of-range values instead of
+//     raising the host-precondition error (`OverflowError` per
+//     definitions.py:1568-1569 `int.to_bytes`) that `storeInt` raises. That
+//     is a deliberate scalar/bulk posture split, not an oversight:
+//       - the whole point of this file (see the perf numbers above) is an
+//         allocation-free, branch-minimal per-element loop; an added range
+//         check is itself a per-element cost, defeating the purpose;
+//       - values reaching this path from a descriptor-driven lower already
+//         went through the descriptor layer's own type conversions for the
+//         cases that matter in practice (see contracts/descriptor-ir.md);
+//         the wrap here is a defense-in-depth gap only for a raw/buggy
+//         embedder value, which the scalar path (used for non-bulk-eligible
+//         kinds, and reachable directly from embedder code) still catches.
+//     A TypedArray element write coerces exactly like the matching DataView
+//     setter (wraps mod 2^width), so this is pinned as intentional behavior
+//     (see bulk_list_test.ts), not merely undocumented;
+//   * floats: the deterministic profile's NaN canonicalization on BOTH
+//     directions (float.ts `decodeI32AsFloat` / `encodeFloatAsI32`): every
+//     lifted NaN becomes the JS canonical NaN, every stored `number` NaN
+//     writes the canonical bit pattern. Non-NaN values round-trip bit-exactly
+//     (Float32Array narrowing is the same IEEE round-to-nearest-even as
+//     `DataView.setFloat32`);
+//   * bool: store normalizes any value by truthiness to 0/1 (`store()`'s
+//     `Number(Boolean(v))`), lift maps any nonzero byte to `true`
+//     (`convertIntToBool` semantics — it never traps for unsigned bytes).
+//
+// u8 is NOT here: it has its own, shape-changing fast path (`list<u8>` is
+// `Uint8Array` on the host — load.ts/store.ts). char is NOT here: its lift
+// validates USVs per element (`convertI32ToChar` traps), which is the cost.
+//
+// NAMED ASSUMPTION (issue #67): wasm linear memory is little-endian by spec;
+// JS TypedArrays follow the PLATFORM's endianness. Every engine polyengine
+// targets runs little-endian, but rather than bake that in silently, the
+// check below gates the fast paths — on a big-endian platform they decline
+// and the callers keep the (endianness-correct) DataView per-element loops.
+//
+// Alignment: the canonical ABI guarantees list pointers are element-aligned,
+// and real guest memories sit at byteOffset 0, so the view construction
+// below virtually never declines; a misaligned combination (possible for a
+// test MemInst wrapping a subarray) falls back the same way.
+import { assert_ } from "./trap.js";
+import { bytesOf } from "./memory.js";
+import { CANONICAL_FLOAT32_NAN, CANONICAL_FLOAT64_NAN } from "./float.js";
+export const PLATFORM_LITTLE_ENDIAN = new Uint8Array(new Uint32Array([0x11223344]).buffer)[0] === 0x44;
+const INT_CTORS = {
+    s8: Int8Array,
+    u16: Uint16Array,
+    s16: Int16Array,
+    u32: Uint32Array,
+    s32: Int32Array,
+};
+const BIG_CTORS = {
+    u64: BigUint64Array,
+    s64: BigInt64Array,
+};
+const FLOAT_CTORS = {
+    f32: Float32Array,
+    f64: Float64Array,
+};
+/** Kinds these helpers handle (besides them, u8 has its own path). */
+export function isBulkListKind(kind) {
+    return kind === "bool" || kind in INT_CTORS || kind in BIG_CTORS ||
+        kind in FLOAT_CTORS;
+}
+function viewOf(ctor, mem, ptr, length) {
+    if (!PLATFORM_LITTLE_ENDIAN)
+        return null;
+    const byteOffset = mem.bytes.byteOffset + ptr;
+    if (byteOffset % ctor.BYTES_PER_ELEMENT !== 0)
+        return null;
+    return new ctor(mem.bytes.buffer, byteOffset, length);
+}
+/**
+ * Bulk lift of `length` elements of `kind` at `ptr`. Returns `null` when the
+ * kind is not handled here (caller falls back to the per-element loop) —
+ * never for a handled kind on a little-endian platform with an aligned view.
+ * The caller has already trap-checked alignment and bounds.
+ */
+export function tryLoadNumericList(mem, ptr, length, kind) {
+    if (kind === "bool") {
+        const out = new Array(length);
+        const bytes = bytesOf(mem, ptr, length); // range assert: defense-in-depth
+        for (let i = 0; i < length; i++)
+            out[i] = bytes[i] !== 0;
+        return out;
+    }
+    const intCtor = INT_CTORS[kind];
+    if (intCtor !== undefined) {
+        const view = viewOf(intCtor, mem, ptr, length);
+        if (view === null)
+            return null;
+        // Manual preallocated loop: measurably faster than Array.from(view).
+        const out = new Array(length);
+        for (let i = 0; i < length; i++)
+            out[i] = view[i];
+        return out;
+    }
+    const bigCtor = BIG_CTORS[kind];
+    if (bigCtor !== undefined) {
+        const view = viewOf(bigCtor, mem, ptr, length);
+        if (view === null)
+            return null;
+        const out = new Array(length);
+        for (let i = 0; i < length; i++)
+            out[i] = view[i];
+        return out;
+    }
+    const floatCtor = FLOAT_CTORS[kind];
+    if (floatCtor !== undefined) {
+        const view = viewOf(floatCtor, mem, ptr, length);
+        if (view === null)
+            return null;
+        const out = new Array(length);
+        for (let i = 0; i < length; i++) {
+            const v = view[i];
+            // decodeI32AsFloat/decodeI64AsFloat: every NaN lifts as the canonical
+            // one (the JS NaN literal IS the canonical f64 NaN, and the canonical
+            // f32 NaN widens to it exactly).
+            out[i] = v === v ? v : NaN;
+        }
+        return out;
+    }
+    return null;
+}
+/**
+ * Bulk store of `v` as elements of `kind` at `ptr`. Returns false when not
+ * handled (caller falls back). The caller has already trap-checked alignment
+ * and bounds.
+ */
+export function tryStoreNumericList(mem, v, ptr, kind) {
+    const n = v.length;
+    if (kind === "bool") {
+        const bytes = bytesOf(mem, ptr, n); // range assert: defense-in-depth
+        for (let i = 0; i < n; i++)
+            bytes[i] = v[i] ? 1 : 0;
+        return true;
+    }
+    const intCtor = INT_CTORS[kind];
+    if (intCtor !== undefined) {
+        const view = viewOf(intCtor, mem, ptr, n);
+        if (view === null)
+            return false;
+        for (let i = 0; i < n; i++) {
+            const x = v[i];
+            assert_(typeof x === "number" && Number.isInteger(x), "int store");
+            view[i] = x; // wraps exactly like the DataView setter
+        }
+        return true;
+    }
+    const bigCtor = BIG_CTORS[kind];
+    if (bigCtor !== undefined) {
+        const view = viewOf(bigCtor, mem, ptr, n);
+        if (view === null)
+            return false;
+        for (let i = 0; i < n; i++) {
+            const x = v[i];
+            assert_(typeof x === "bigint", "64-bit store requires bigint");
+            view[i] = x; // wraps mod 2^64 like setBigUint64/setBigInt64
+        }
+        return true;
+    }
+    const floatCtor = FLOAT_CTORS[kind];
+    if (floatCtor !== undefined) {
+        const view = viewOf(floatCtor, mem, ptr, n);
+        if (view === null)
+            return false;
+        const size = floatCtor.BYTES_PER_ELEMENT;
+        for (let i = 0; i < n; i++) {
+            const x = v[i];
+            if (typeof x === "number" && Number.isNaN(x)) {
+                // encodeFloatAsI32/encodeFloatAsI64: a number NaN stores the
+                // canonical bit pattern, never the engine's.
+                if (size === 4) {
+                    mem.view.setUint32(ptr + i * 4, CANONICAL_FLOAT32_NAN, true);
+                }
+                else {
+                    mem.view.setBigUint64(ptr + i * 8, CANONICAL_FLOAT64_NAN, true);
+                }
+            }
+            else {
+                // Same ToNumber coercion + IEEE narrowing as DataView.setFloat*.
+                view[i] = x;
+            }
+        }
+        return true;
+    }
+    return false;
+}

package/esm/cabi/context.js

@@ -0,0 +1,42 @@
+// Canonical options and lift/lower context (definitions.py `## Canonical ABI
+// Options`, `## Lifting and Lowering Context`).
+import { assert_, trapIf } from "./trap.js";
+export function mkCanonicalOptions(partial = {}) {
+    return {
+        stringEncoding: partial.stringEncoding ?? "utf8",
+        memory: partial.memory ?? null,
+        realloc: partial.realloc ?? null,
+        postReturn: partial.postReturn ?? null,
+        async_: partial.async_ ?? false,
+        callback: partial.callback ?? null,
+    };
+}
+/** Memory accessor that traps-or-asserts like `cx.opts.memory` derefs. */
+export function requireMemory(opts) {
+    assert_(opts.memory !== null, "canonical option `memory` required");
+    return opts.memory;
+}
+export class LiftLowerContext {
+    opts;
+    inst;
+    borrowScope;
+    constructor(opts, inst = null, borrowScope = null) {
+        this.opts = opts;
+        this.inst = inst;
+        this.borrowScope = borrowScope;
+    }
+    /**
+     * definitions.py `LiftLowerContext.reallocate` routes the call through
+     * canon_lift (reentrance bookkeeping and may_leave toggling around a
+     * guest-side realloc export). v1 simplification: call the provided realloc
+     * directly. The full path returns with the task machinery.
+     */
+    reallocate(old, oldByteLength, alignment, newByteLength) {
+        const realloc = this.opts.realloc;
+        trapIf(realloc === null, "realloc required but not provided");
+        return realloc(old, oldByteLength, alignment, newByteLength);
+    }
+    allocate(alignment, byteLength) {
+        return this.reallocate(0, 0, alignment, byteLength);
+    }
+}