@polyengine/runtime 0.1.0-pre.g633468a

package/esm/cabi/lift.js

@@ -0,0 +1,196 @@
+// Flat lifting (definitions.py `## Flat Lifting`): core values -> component
+// values.
+import { assert_, trapIf } from "./trap.js";
+import { canonicalizeNan32, canonicalizeNan64, decodeI32AsFloat, decodeI64AsFloat, } from "./float.js";
+import { convertI32ToChar, loadStringFromRange } from "./strings.js";
+import { convertIntToBool, loadListFromRange, unpackFlagsFromInt, } from "./load.js";
+import { requireMemory } from "./context.js";
+import { flattenVariant } from "./flatten.js";
+import { liftBorrow, liftOwn } from "./handles.js";
+import { despecialize, } from "./types.js";
+import { liftErrorContext, liftFuture, liftStream, } from "./async_values.js";
+export class CoreValueIter {
+    values;
+    i = 0;
+    constructor(values) {
+        this.values = values;
+    }
+    next(t) {
+        const v = this.values[this.i];
+        this.i += 1;
+        switch (t) {
+            case "i32":
+                assert_(typeof v === "number" && Number.isInteger(v) && 0 <= v &&
+                    v < 2 ** 32, "expected canonical i32 lane value");
+                break;
+            case "i64":
+                assert_(typeof v === "bigint" && 0n <= v && v < 1n << 64n, "expected canonical i64 lane value");
+                break;
+            case "f32":
+            case "f64":
+                assert_(typeof v === "number", "expected float lane value");
+                break;
+        }
+        return v;
+    }
+    done() {
+        return this.i === this.values.length;
+    }
+}
+export function liftFlat(cx, vi, t) {
+    const d = despecialize(t);
+    switch (d.kind) {
+        case "bool":
+            return convertIntToBool(vi.next("i32"));
+        case "u8":
+            return liftFlatUnsigned32(vi, 8);
+        case "u16":
+            return liftFlatUnsigned32(vi, 16);
+        case "u32":
+            return liftFlatUnsigned32(vi, 32);
+        case "u64":
+            return liftFlatUnsigned64(vi);
+        case "s8":
+            return liftFlatSigned32(vi, 8);
+        case "s16":
+            return liftFlatSigned32(vi, 16);
+        case "s32":
+            return liftFlatSigned32(vi, 32);
+        case "s64":
+            return liftFlatSigned64(vi);
+        case "f32":
+            return canonicalizeNan32(vi.next("f32"));
+        case "f64":
+            return canonicalizeNan64(vi.next("f64"));
+        case "char":
+            return convertI32ToChar(vi.next("i32"));
+        case "string":
+            return liftFlatString(cx, vi);
+        case "error-context":
+            return liftErrorContext(cx, vi.next("i32"));
+        case "list":
+            return liftFlatList(cx, vi, d.element, d.length ?? null);
+        case "record":
+            return liftFlatRecord(cx, vi, d.fields);
+        case "variant":
+            return liftFlatVariant(cx, vi, d.cases);
+        case "flags":
+            return liftFlatFlags(vi, d.labels);
+        case "own":
+            return liftOwn(cx, vi.next("i32"), d);
+        case "borrow":
+            return liftBorrow(cx, vi.next("i32"), d);
+        case "stream":
+            return liftStream(cx, vi.next("i32"), d);
+        case "future":
+            return liftFuture(cx, vi.next("i32"), d);
+    }
+}
+// definitions.py lift_flat_unsigned/lift_flat_signed, split by core width
+// because 32-bit lanes are numbers and 64-bit lanes are bigints.
+export function liftFlatUnsigned32(vi, tWidth) {
+    const i = vi.next("i32");
+    assert_(0 <= i && i < 2 ** 32);
+    return i % 2 ** tWidth;
+}
+export function liftFlatUnsigned64(vi) {
+    const i = vi.next("i64");
+    assert_(0n <= i && i < 1n << 64n);
+    return i; // i % 2**64 == i
+}
+export function liftFlatSigned32(vi, tWidth) {
+    const i0 = vi.next("i32");
+    assert_(0 <= i0 && i0 < 2 ** 32);
+    const i = i0 % 2 ** tWidth;
+    if (i >= 2 ** (tWidth - 1)) {
+        return i - 2 ** tWidth;
+    }
+    return i;
+}
+export function liftFlatSigned64(vi) {
+    const i = vi.next("i64");
+    assert_(0n <= i && i < 1n << 64n);
+    if (i >= 1n << 63n) {
+        return i - (1n << 64n);
+    }
+    return i;
+}
+export function liftFlatString(cx, vi) {
+    const ptrType = requireMemory(cx.opts).ptrType();
+    const ptr = vi.next(ptrType);
+    const packedLength = vi.next(ptrType);
+    return loadStringFromRange(cx, ptr, packedLength);
+}
+export function liftFlatList(cx, vi, elemType, maybeLength) {
+    if (maybeLength !== null) {
+        const a = [];
+        for (let i = 0; i < maybeLength; i++) {
+            a.push(liftFlat(cx, vi, elemType));
+        }
+        // docs/architecture.md §7: list<u8> is a Uint8Array.
+        if (despecialize(elemType).kind === "u8") {
+            return Uint8Array.from(a);
+        }
+        return a;
+    }
+    const ptrType = requireMemory(cx.opts).ptrType();
+    const ptr = vi.next(ptrType);
+    const length = vi.next(ptrType);
+    return loadListFromRange(cx, ptr, length, elemType);
+}
+export function liftFlatRecord(cx, vi, fields) {
+    const record = {};
+    for (const f of fields) {
+        record[f.label] = liftFlat(cx, vi, f.type);
+    }
+    return record;
+}
+export function liftFlatVariant(cx, vi, cases) {
+    const flatTypes = flattenVariant(cases, cx.opts);
+    assert_(flatTypes.shift() === "i32");
+    const caseIndex = vi.next("i32");
+    trapIf(caseIndex >= cases.length, "invalid variant discriminant");
+    const coerceIter = {
+        next(want) {
+            const have = flatTypes.shift();
+            const x = vi.next(have);
+            if (have === "i32" && want === "f32") {
+                return decodeI32AsFloat(x);
+            }
+            else if (have === "i64" && want === "i32") {
+                return wrapI64ToI32(x);
+            }
+            else if (have === "i64" && want === "f32") {
+                return decodeI32AsFloat(wrapI64ToI32(x));
+            }
+            else if (have === "i64" && want === "f64") {
+                return decodeI64AsFloat(x);
+            }
+            else {
+                assert_(have === want, `lane mismatch ${have} -> ${want}`);
+                return x;
+            }
+        },
+    };
+    const c = cases[caseIndex];
+    let v;
+    if (c.type === null) {
+        v = null;
+    }
+    else {
+        v = liftFlat(cx, coerceIter, c.type);
+    }
+    for (const have of flatTypes) {
+        vi.next(have);
+    }
+    return { [c.label]: v };
+}
+export function wrapI64ToI32(i) {
+    assert_(0n <= i && i < 1n << 64n);
+    return Number(i & 0xffffffffn);
+}
+export function liftFlatFlags(vi, labels) {
+    assert_(0 < labels.length && labels.length <= 32);
+    const i = vi.next("i32");
+    return unpackFlagsFromInt(i, labels);
+}

package/esm/cabi/load.js

@@ -0,0 +1,146 @@
+// Loading component values from linear memory (definitions.py `## Loading`).
+import { assert_, trapIf } from "./trap.js";
+import { bytesOf, loadIntS, loadIntU, loadPtr } from "./memory.js";
+import { decodeI32AsFloat, decodeI64AsFloat } from "./float.js";
+import { alignment, alignTo, elemSize, elemSizeFlags, maxCaseAlignment, } from "./layout.js";
+import { convertI32ToChar, loadString } from "./strings.js";
+import { requireMemory } from "./context.js";
+import { tryLoadNumericList } from "./bulk_lists.js";
+import { liftBorrow, liftOwn } from "./handles.js";
+import { despecialize, discriminantType, } from "./types.js";
+import { liftErrorContext, liftFuture, liftStream, } from "./async_values.js";
+export const MAX_LIST_BYTE_LENGTH = (1 << 28) - 1;
+export function load(cx, ptr, t) {
+    const mem = requireMemory(cx.opts);
+    assert_(ptr === alignTo(ptr, alignment(t, mem.ptrType())), "load misaligned");
+    assert_(ptr + elemSize(t, mem.ptrType()) <= mem.length, "load OOB");
+    const d = despecialize(t);
+    switch (d.kind) {
+        case "bool":
+            return convertIntToBool(loadIntU(mem, ptr, 1));
+        case "u8":
+            return loadIntU(mem, ptr, 1);
+        case "u16":
+            return loadIntU(mem, ptr, 2);
+        case "u32":
+            return loadIntU(mem, ptr, 4);
+        case "u64":
+            return loadIntU(mem, ptr, 8);
+        case "s8":
+            return loadIntS(mem, ptr, 1);
+        case "s16":
+            return loadIntS(mem, ptr, 2);
+        case "s32":
+            return loadIntS(mem, ptr, 4);
+        case "s64":
+            return loadIntS(mem, ptr, 8);
+        case "f32":
+            return decodeI32AsFloat(loadIntU(mem, ptr, 4));
+        case "f64":
+            return decodeI64AsFloat(loadIntU(mem, ptr, 8));
+        case "char":
+            return convertI32ToChar(loadIntU(mem, ptr, 4));
+        case "string":
+            return loadString(cx, ptr);
+        case "error-context":
+            return liftErrorContext(cx, loadIntU(cx.opts.memory, ptr, 4));
+        case "list":
+            return loadList(cx, ptr, d.element, d.length ?? null);
+        case "record":
+            return loadRecord(cx, ptr, d.fields);
+        case "variant":
+            return loadVariant(cx, ptr, d.cases);
+        case "flags":
+            return loadFlags(cx, ptr, d.labels);
+        case "own":
+            return liftOwn(cx, loadIntU(mem, ptr, 4), d);
+        case "borrow":
+            return liftBorrow(cx, loadIntU(mem, ptr, 4), d);
+        case "stream":
+            return liftStream(cx, loadIntU(cx.opts.memory, ptr, 4), d);
+        case "future":
+            return liftFuture(cx, loadIntU(cx.opts.memory, ptr, 4), d);
+    }
+}
+export function convertIntToBool(i) {
+    assert_(i >= 0);
+    return Boolean(i);
+}
+export function loadList(cx, ptr, elemType, maybeLength) {
+    if (maybeLength !== null) {
+        return loadListFromValidRange(cx, ptr, maybeLength, elemType);
+    }
+    const mem = requireMemory(cx.opts);
+    const begin = loadPtr(mem, ptr);
+    const length = loadPtr(mem, ptr + mem.ptrSize());
+    return loadListFromRange(cx, begin, length, elemType);
+}
+export function loadListFromRange(cx, ptr, length, elemType) {
+    const mem = requireMemory(cx.opts);
+    const size = elemSize(elemType, mem.ptrType());
+    const align = alignment(elemType, mem.ptrType());
+    const byteLengthBig = BigInt(length) * BigInt(size);
+    trapIf(byteLengthBig > BigInt(MAX_LIST_BYTE_LENGTH), "list too long");
+    const ptrBig = BigInt(ptr);
+    trapIf(ptrBig % BigInt(align) !== 0n, "misaligned list pointer");
+    trapIf(ptrBig + byteLengthBig > BigInt(mem.length), "list out of bounds");
+    return loadListFromValidRange(cx, Number(ptrBig), Number(length), elemType);
+}
+export function loadListFromValidRange(cx, ptr, length, elemType) {
+    const mem = requireMemory(cx.opts);
+    const kind = despecialize(elemType).kind;
+    // docs/architecture.md §7: list<u8> lifts to a Uint8Array copy.
+    if (kind === "u8") {
+        return bytesOf(mem, ptr, length).slice();
+    }
+    // Other flat element types lift bulk too (issue #67) — same host shapes
+    // (number[]/bigint[]/boolean[]), same NaN canonicalization; falls through
+    // to the per-element loop for compound types, char (per-element USV
+    // validation is the point), and non-little-endian platforms.
+    const bulk = tryLoadNumericList(mem, ptr, length, kind);
+    if (bulk !== null)
+        return bulk;
+    const size = elemSize(elemType, mem.ptrType());
+    const a = [];
+    for (let i = 0; i < length; i++) {
+        a.push(load(cx, ptr + i * size, elemType));
+    }
+    return a;
+}
+export function loadRecord(cx, ptr, fields) {
+    const mem = requireMemory(cx.opts);
+    const record = {};
+    let p = ptr;
+    for (const field of fields) {
+        p = alignTo(p, alignment(field.type, mem.ptrType()));
+        record[field.label] = load(cx, p, field.type);
+        p += elemSize(field.type, mem.ptrType());
+    }
+    return record;
+}
+export function loadVariant(cx, ptr, cases) {
+    const mem = requireMemory(cx.opts);
+    const discSize = elemSize(discriminantType(cases), mem.ptrType());
+    const caseIndex = loadIntU(mem, ptr, discSize);
+    let p = ptr + discSize;
+    trapIf(caseIndex >= cases.length, "invalid variant discriminant");
+    const c = cases[caseIndex];
+    p = alignTo(p, maxCaseAlignment(cases, mem.ptrType()));
+    if (c.type === null)
+        return { [c.label]: null };
+    return { [c.label]: load(cx, p, c.type) };
+}
+export function loadFlags(cx, ptr, labels) {
+    const mem = requireMemory(cx.opts);
+    const i = loadIntU(mem, ptr, elemSizeFlags(labels));
+    return unpackFlagsFromInt(i, labels);
+}
+export function unpackFlagsFromInt(i, labels) {
+    const record = {};
+    let v = i >>> 0;
+    for (const l of labels) {
+        record[l] = Boolean(v & 1);
+        v = v >>> 1;
+    }
+    return record;
+}

package/esm/cabi/lower.js

@@ -0,0 +1,141 @@
+// Flat lowering (definitions.py `## Flat Lowering`): component values ->
+// core values.
+import { assert_ } from "./trap.js";
+import { encodeFloatAsI32, encodeFloatAsI64, maybeScrambleNan32, maybeScrambleNan64, } from "./float.js";
+import { charToI32, storeStringIntoRange } from "./strings.js";
+import { matchCase, packFlagsIntoInt, storeListIntoRange } from "./store.js";
+import { requireMemory } from "./context.js";
+import { flattenType, flattenVariant } from "./flatten.js";
+import { lowerBorrow, lowerOwn } from "./handles.js";
+import { despecialize, } from "./types.js";
+import { lowerErrorContext, lowerFuture, lowerStream, } from "./async_values.js";
+export function lowerFlat(cx, v, t) {
+    const d = despecialize(t);
+    switch (d.kind) {
+        case "bool":
+            return [Number(v)];
+        case "u8":
+        case "u16":
+        case "u32":
+            return [v];
+        case "u64":
+            return [v];
+        case "s8":
+        case "s16":
+        case "s32":
+            return lowerFlatSigned32(v);
+        case "s64":
+            return lowerFlatSigned64(v);
+        case "f32":
+            return [maybeScrambleNan32(v)];
+        case "f64":
+            return [maybeScrambleNan64(v)];
+        case "char":
+            return [charToI32(v)];
+        case "string":
+            return lowerFlatString(cx, v);
+        case "error-context":
+            return [lowerErrorContext(cx, v)];
+        case "list":
+            return lowerFlatList(cx, v, d.element, d.length ?? null);
+        case "record":
+            return lowerFlatRecord(cx, v, d.fields);
+        case "variant":
+            return lowerFlatVariant(cx, v, d.cases);
+        case "flags":
+            return lowerFlatFlags(v, d.labels);
+        case "own":
+            return [lowerOwn(cx, v, d)];
+        case "borrow":
+            return [lowerBorrow(cx, v, d)];
+        case "stream":
+            return [lowerStream(cx, v, d)];
+        case "future":
+            return [lowerFuture(cx, v, d)];
+    }
+}
+// definitions.py lower_flat_signed, split by core width (number vs bigint).
+export function lowerFlatSigned32(i) {
+    if (i < 0) {
+        return [i + 2 ** 32];
+    }
+    return [i];
+}
+export function lowerFlatSigned64(i) {
+    if (i < 0n) {
+        return [i + (1n << 64n)];
+    }
+    return [i];
+}
+export function lowerFlatString(cx, v) {
+    const [ptr, packedLength] = storeStringIntoRange(cx, v);
+    if (requireMemory(cx.opts).ptrType() === "i32") {
+        return [ptr, Number(packedLength)];
+    }
+    return [BigInt(ptr), packedLength];
+}
+export function lowerFlatList(cx, v, elemType, maybeLength) {
+    if (maybeLength !== null) {
+        assert_(maybeLength === v.length, "fixed-length list length mismatch");
+        const flat = [];
+        for (let i = 0; i < v.length; i++) {
+            flat.push(...lowerFlat(cx, v[i], elemType));
+        }
+        return flat;
+    }
+    const [ptr, length] = storeListIntoRange(cx, v, elemType);
+    if (requireMemory(cx.opts).ptrType() === "i32") {
+        return [ptr, length];
+    }
+    return [BigInt(ptr), BigInt(length)];
+}
+export function lowerFlatRecord(cx, v, fields) {
+    const flat = [];
+    for (const f of fields) {
+        flat.push(...lowerFlat(cx, v[f.label], f.type));
+    }
+    return flat;
+}
+export function lowerFlatVariant(cx, v, cases) {
+    const [caseIndex, caseValue] = matchCase(v, cases);
+    const flatTypes = flattenVariant(cases, cx.opts);
+    assert_(flatTypes.shift() === "i32");
+    const c = cases[caseIndex];
+    let payload;
+    if (c.type === null) {
+        payload = [];
+    }
+    else {
+        payload = lowerFlat(cx, caseValue, c.type);
+        const haveTypes = flattenType(c.type, cx.opts);
+        for (let i = 0; i < payload.length; i++) {
+            const fv = payload[i];
+            const have = haveTypes[i];
+            const want = flatTypes.shift();
+            if (have === "f32" && want === "i32") {
+                payload[i] = encodeFloatAsI32(fv);
+            }
+            else if (have === "i32" && want === "i64") {
+                payload[i] = BigInt(fv);
+            }
+            else if (have === "f32" && want === "i64") {
+                payload[i] = BigInt(encodeFloatAsI32(fv));
+            }
+            else if (have === "f64" && want === "i64") {
+                payload[i] = encodeFloatAsI64(fv);
+            }
+            else {
+                assert_(have === want, `lane mismatch ${have} -> ${want}`);
+            }
+        }
+    }
+    // Pad the remaining lanes of wider cases with zeros of the lane type.
+    for (const want of flatTypes) {
+        payload.push(want === "i64" ? 0n : 0);
+    }
+    return [caseIndex, ...payload];
+}
+export function lowerFlatFlags(v, labels) {
+    assert_(0 < labels.length && labels.length <= 32);
+    return [packFlagsIntoInt(v, labels)];
+}

package/esm/cabi/memory.js

@@ -0,0 +1,182 @@
+// Linear-memory access (definitions.py `MemInst`, `load_int`, `store_int`,
+// `ptr_size`).
+//
+// A `MemInst` wraps a byte buffer with an address type (wasm32/wasm64). All
+// multi-byte accesses are little-endian via DataView. Following docs/architecture.md §7,
+// integer lanes/values of width <= 32 are JS numbers and 64-bit values are
+// BigInt.
+//
+// Addresses and sizes are JS numbers throughout: real guest memories are far
+// below Number.MAX_SAFE_INTEGER. Values arriving from i64 lanes (memory64)
+// are bounds-checked as BigInt before conversion — see `asIndex`.
+import { assert_, trapIf } from "./trap.js";
+export function ptrSize(ptrType) {
+    return ptrType === "i32" ? 4 : 8;
+}
+/**
+ * `MemInst` caches its `Uint8Array`/`DataView` at construction time and never
+ * re-derives them. That is only sound for a memory that cannot grow within
+ * this instance's lifetime: `memory.grow` (guest-triggered or host-triggered)
+ * detaches the backing `ArrayBuffer`, and a cached view over a detached
+ * buffer reads/writes garbage rather than trapping.
+ *
+ * Production call/lift/lower paths do NOT construct `MemInst` directly against
+ * a live, growable `WebAssembly.Memory` for this reason: the executor
+ * re-derives a fresh view per access via `LiveMemory`
+ * (`exec/boundary.ts:97-160`), which is grow-safe. `MemInst` is for contexts
+ * where the buffer is known fixed for the duration (tests, or a snapshot
+ * already taken).
+ */
+export class MemInst {
+    bytes;
+    view;
+    addrType;
+    constructor(bytes, addrType) {
+        this.bytes = bytes;
+        this.view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        this.addrType = addrType;
+    }
+    get length() {
+        return this.bytes.length;
+    }
+    ptrType() {
+        return this.addrType;
+    }
+    ptrSize() {
+        return ptrSize(this.addrType);
+    }
+}
+/**
+ * Convert a (possibly BigInt) address/length to a JS number index, after the
+ * caller has already trapped on any out-of-bounds condition using exact
+ * (BigInt) arithmetic. Asserts rather than traps: by this point the value is
+ * known small.
+ */
+export function asIndex(v) {
+    if (typeof v === "bigint") {
+        assert_(v >= 0n && v <= BigInt(Number.MAX_SAFE_INTEGER), "index overflow");
+        return Number(v);
+    }
+    assert_(Number.isSafeInteger(v) && v >= 0, "index not a safe integer");
+    return v;
+}
+export function loadIntU(mem, ptr, nbytes) {
+    assert_(ptr + nbytes <= mem.length, "load out of bounds");
+    switch (nbytes) {
+        case 1:
+            return mem.view.getUint8(ptr);
+        case 2:
+            return mem.view.getUint16(ptr, true);
+        case 4:
+            return mem.view.getUint32(ptr, true);
+        case 8:
+            return mem.view.getBigUint64(ptr, true);
+    }
+}
+export function loadIntS(mem, ptr, nbytes) {
+    assert_(ptr + nbytes <= mem.length, "load out of bounds");
+    switch (nbytes) {
+        case 1:
+            return mem.view.getInt8(ptr);
+        case 2:
+            return mem.view.getInt16(ptr, true);
+        case 4:
+            return mem.view.getInt32(ptr, true);
+        case 8:
+            return mem.view.getBigInt64(ptr, true);
+    }
+}
+/** Load a pointer-sized unsigned integer (returns bigint for i64 memories). */
+export function loadPtr(mem, ptr) {
+    return mem.ptrSize() === 4 ? loadIntU(mem, ptr, 4) : loadIntU(mem, ptr, 8);
+}
+// definitions.py store_int(cx, v, ptr, nbytes, signed): `int.to_bytes` raises
+// `OverflowError` when `v` does not fit in `nbytes` (signed/unsigned per the
+// flag) — a host-precondition violation, not a guest-visible trap (the value
+// never came from validated guest bytes; it is a JS number/bigint an
+// embedder handed the lowering path). Ported as `assert_`/`AssertionError`
+// (see cabi/trap.ts's Trap-vs-AssertionError taxonomy), not `Trap`.
+// definitions.py:1568-1569 (`store_int`).
+//
+// This scalar path is where the check lives; the bulk (TypedArray) path in
+// bulk_lists.ts intentionally wraps instead — see that file's header for why.
+function bigintFitsIn64(v, signed) {
+    return signed
+        ? v >= -(2n ** 63n) && v < 2n ** 63n
+        : v >= 0n && v < 2n ** 64n;
+}
+function numberFitsInWidth(v, nbytes, signed) {
+    const bits = nbytes * 8;
+    if (signed) {
+        const min = -(2 ** (bits - 1));
+        const max = 2 ** (bits - 1) - 1;
+        return v >= min && v <= max;
+    }
+    return v >= 0 && v <= 2 ** bits - 1;
+}
+export function storeInt(mem, v, ptr, nbytes, signed = false) {
+    assert_(ptr + nbytes <= mem.length, "store out of bounds");
+    if (nbytes === 8) {
+        assert_(typeof v === "bigint", "64-bit store requires bigint");
+        assert_(bigintFitsIn64(v, signed), "int store: value out of range");
+        if (signed)
+            mem.view.setBigInt64(ptr, v, true);
+        else
+            mem.view.setBigUint64(ptr, v, true);
+        return;
+    }
+    assert_(typeof v === "number" && Number.isInteger(v), "int store");
+    assert_(numberFitsInWidth(v, nbytes, signed), "int store: value out of range");
+    switch (nbytes) {
+        case 1:
+            if (signed)
+                mem.view.setInt8(ptr, v);
+            else
+                mem.view.setUint8(ptr, v);
+            break;
+        case 2:
+            if (signed)
+                mem.view.setInt16(ptr, v, true);
+            else
+                mem.view.setUint16(ptr, v, true);
+            break;
+        case 4:
+            if (signed)
+                mem.view.setInt32(ptr, v, true);
+            else
+                mem.view.setUint32(ptr, v, true);
+            break;
+    }
+}
+/** Store a pointer-sized unsigned integer, taking a JS number. */
+export function storePtr(mem, v, ptr) {
+    if (mem.ptrSize() === 4)
+        storeInt(mem, v, ptr, 4);
+    else
+        storeInt(mem, BigInt(v), ptr, 8);
+}
+/** Bounds-checked byte-range read (callers trap on OOB before calling). */
+export function bytesOf(mem, ptr, len) {
+    assert_(ptr >= 0 && len >= 0 && ptr + len <= mem.length, "range OOB");
+    return mem.bytes.subarray(ptr, ptr + len);
+}
+/** Copy bytes into memory; used by string/list stores after trap checks. */
+export function writeBytes(mem, ptr, src) {
+    assert_(ptr >= 0 && ptr + src.length <= mem.length, "write OOB");
+    mem.bytes.set(src, ptr);
+}
+/**
+ * Exact bounds check usable with i64-lane values: traps when
+ * `ptr + byteLength > len(memory)`, computed without precision loss.
+ *
+ * `what` selects the trap wording only. Callers that are checking a pointer
+ * *returned by realloc* pass wasmtime's phrasing for that case
+ * ("realloc return: beyond end of memory",
+ * `wasmtime/src/runtime/component/func/options.rs:185`) and the string-lift
+ * path passes its own ("string pointer/length out of bounds of memory",
+ * `.../func/typed.rs:1528`), because the official suite matches those texts.
+ * The default is unchanged.
+ */
+export function trapIfRangeExceedsMemory(mem, ptr, byteLength, what = "out of bounds of linear memory") {
+    trapIf(BigInt(ptr) + BigInt(byteLength) > BigInt(mem.length), what);
+}

package/esm/cabi/mod.js

@@ -0,0 +1,22 @@
+// Canonical ABI v1 reference interpreter — public surface.
+//
+// A direct TypeScript port of the value lift/lower machinery of
+// third_party/component-model/design/mvp/canonical-abi/definitions.py
+// (readable over fast; docs/architecture.md §8 "v1: a generic interpreter").
+// Task/thread/waitable machinery is deliberately absent — see
+// runtime/README.md for the port/defer inventory.
+export * from "./trap.js";
+export * from "./types.js";
+export * from "./memory.js";
+export * from "./layout.js";
+export * from "./float.js";
+export * from "./context.js";
+export * from "./handles.js";
+export * from "./strings.js";
+export * from "./bulk_lists.js";
+export * from "./load.js";
+export * from "./store.js";
+export * from "./flatten.js";
+export * from "./lift.js";
+export * from "./lower.js";
+export * from "./values.js";