@polyengine/runtime 0.1.0-pre.g633468a

package/esm/cabi/flatten.js

@@ -0,0 +1,145 @@
+// Flattening (definitions.py `## Flattening`): component function types to
+// core function signatures, and component value types to flat core types.
+import { despecialize, discriminantType, } from "./types.js";
+import { requireMemory } from "./context.js";
+export const MAX_FLAT_PARAMS = 16;
+export const MAX_FLAT_ASYNC_PARAMS = 4;
+// Mutable to mirror run_tests.py toggling definitions.MAX_FLAT_RESULTS.
+export let MAX_FLAT_RESULTS = 1;
+// Test-only mirror of run_tests.py's constant toggling; not for production
+// use (naming convention: see `schedulerSeedForTesting`).
+export function setMaxFlatResultsForTesting(n) {
+    const prev = MAX_FLAT_RESULTS;
+    MAX_FLAT_RESULTS = n;
+    return prev;
+}
+export function flattenFunctype(opts, ft, context) {
+    let flatParams = flattenTypes(ft.params, opts);
+    let flatResults = flattenTypes(ft.results, opts);
+    if (!opts.async_) {
+        if (flatParams.length > MAX_FLAT_PARAMS) {
+            flatParams = [requireMemory(opts).ptrType()];
+        }
+        if (flatResults.length > MAX_FLAT_RESULTS) {
+            switch (context) {
+                case "lift":
+                    flatResults = [requireMemory(opts).ptrType()];
+                    break;
+                case "lower":
+                    flatParams = [...flatParams, requireMemory(opts).ptrType()];
+                    flatResults = [];
+                    break;
+            }
+        }
+        return { params: flatParams, results: flatResults };
+    }
+    else {
+        switch (context) {
+            case "lift":
+                if (flatParams.length > MAX_FLAT_PARAMS) {
+                    flatParams = [requireMemory(opts).ptrType()];
+                }
+                if (opts.callback) {
+                    flatResults = ["i32"];
+                }
+                else {
+                    flatResults = [];
+                }
+                break;
+            case "lower":
+                if (flatParams.length > MAX_FLAT_ASYNC_PARAMS) {
+                    flatParams = [requireMemory(opts).ptrType()];
+                }
+                if (flatResults.length > 0) {
+                    flatParams = [...flatParams, requireMemory(opts).ptrType()];
+                }
+                flatResults = ["i32"];
+                break;
+        }
+        return { params: flatParams, results: flatResults };
+    }
+}
+export function flattenTypes(ts, opts) {
+    return ts.flatMap((t) => flattenType(t, opts));
+}
+export function flattenType(t, opts) {
+    const d = despecialize(t);
+    switch (d.kind) {
+        case "bool":
+        case "u8":
+        case "u16":
+        case "u32":
+        case "s8":
+        case "s16":
+        case "s32":
+        case "char":
+            return ["i32"];
+        case "s64":
+        case "u64":
+            return ["i64"];
+        case "f32":
+            return ["f32"];
+        case "f64":
+            return ["f64"];
+        case "string": {
+            const pt = requireMemory(opts).ptrType();
+            return [pt, pt];
+        }
+        case "error-context":
+            return ["i32"];
+        case "list":
+            return flattenList(d.element, d.length ?? null, opts);
+        case "record":
+            return flattenRecord(d.fields, opts);
+        case "variant":
+            return flattenVariant(d.cases, opts);
+        case "flags":
+            return ["i32"];
+        case "own":
+        case "borrow":
+        case "stream":
+        case "future":
+            return ["i32"];
+    }
+}
+export function flattenList(elemType, maybeLength, opts) {
+    if (maybeLength !== null) {
+        const flat = [];
+        const one = flattenType(elemType, opts);
+        for (let i = 0; i < maybeLength; i++)
+            flat.push(...one);
+        return flat;
+    }
+    const pt = requireMemory(opts).ptrType();
+    return [pt, pt];
+}
+export function flattenRecord(fields, opts) {
+    const flat = [];
+    for (const f of fields)
+        flat.push(...flattenType(f.type, opts));
+    return flat;
+}
+export function flattenVariant(cases, opts) {
+    const flat = [];
+    for (const c of cases) {
+        if (c.type !== null) {
+            flattenType(c.type, opts).forEach((ft, i) => {
+                if (i < flat.length) {
+                    flat[i] = join(flat[i], ft);
+                }
+                else {
+                    flat.push(ft);
+                }
+            });
+        }
+    }
+    return [...flattenType(discriminantType(cases), opts), ...flat];
+}
+export function join(a, b) {
+    if (a === b)
+        return a;
+    if ((a === "i32" && b === "f32") || (a === "f32" && b === "i32")) {
+        return "i32";
+    }
+    return "i64";
+}

package/esm/cabi/float.js

@@ -0,0 +1,67 @@
+// Float bit handling (definitions.py NaN canonicalization and
+// reinterpretation helpers).
+//
+// The reference has a DETERMINISTIC_PROFILE toggle; this port implements only
+// the deterministic profile (NaNs canonicalized on lift and on
+// store/lower). JS forces this: NaN payloads are not reliably observable or
+// preservable through JS numbers, so the "scramble" branch of the reference
+// is not implementable — and run_tests.py itself runs the deterministic
+// profile. Recorded as a decision in runtime/README.md.
+export const CANONICAL_FLOAT32_NAN = 0x7fc00000;
+export const CANONICAL_FLOAT64_NAN = 0x7ff8000000000000n;
+const scratch = new DataView(new ArrayBuffer(8));
+export function coreF32ReinterpretI32(i) {
+    scratch.setUint32(0, i, true);
+    return scratch.getFloat32(0, true);
+}
+export function coreF64ReinterpretI64(i) {
+    scratch.setBigUint64(0, i, true);
+    return scratch.getFloat64(0, true);
+}
+export function coreI32ReinterpretF32(f) {
+    scratch.setFloat32(0, f, true);
+    return scratch.getUint32(0, true);
+}
+export function coreI64ReinterpretF64(f) {
+    scratch.setFloat64(0, f, true);
+    return scratch.getBigUint64(0, true);
+}
+export function canonicalizeNan32(f) {
+    if (Number.isNaN(f))
+        return coreF32ReinterpretI32(CANONICAL_FLOAT32_NAN);
+    return f;
+}
+export function canonicalizeNan64(f) {
+    if (Number.isNaN(f))
+        return coreF64ReinterpretI64(CANONICAL_FLOAT64_NAN);
+    return f;
+}
+export function decodeI32AsFloat(i) {
+    return canonicalizeNan32(coreF32ReinterpretI32(i));
+}
+export function decodeI64AsFloat(i) {
+    return canonicalizeNan64(coreF64ReinterpretI64(i));
+}
+// definitions.py maybe_scramble_nan{32,64}: deterministic profile only —
+// write the canonical NaN bit pattern explicitly, never relying on engine
+// NaN propagation through DataView.
+export function maybeScrambleNan32(f) {
+    if (Number.isNaN(f))
+        return coreF32ReinterpretI32(CANONICAL_FLOAT32_NAN);
+    return f;
+}
+export function maybeScrambleNan64(f) {
+    if (Number.isNaN(f))
+        return coreF64ReinterpretI64(CANONICAL_FLOAT64_NAN);
+    return f;
+}
+export function encodeFloatAsI32(f) {
+    if (Number.isNaN(f))
+        return CANONICAL_FLOAT32_NAN;
+    return coreI32ReinterpretF32(f);
+}
+export function encodeFloatAsI64(f) {
+    if (Number.isNaN(f))
+        return CANONICAL_FLOAT64_NAN;
+    return coreI64ReinterpretF64(f);
+}

package/esm/cabi/handles.js

@@ -0,0 +1,253 @@
+// Handle tables and resource handles (definitions.py `### Table State`,
+// `### Resource State`, `canon resource.{new,drop,rep}`, and the
+// own/borrow lift/lower functions).
+//
+// The Table and ResourceHandle mechanics are pure and ported fully. What is
+// simplified here (pending the task machinery):
+//   - canon_resource_* take the instance explicitly instead of reading
+//     current_instance() from the running thread;
+//   - canon_resource_drop routes the dtor through `callDtorGated` below,
+//     which reconstructs the reference's store.lift/store.lower bracket
+//     (may_enter gating + trap poisoning) around the destructor call (#85).
+//     Host-initiated drops do NOT come here: they run the dtor through the
+//     real lift harness (`hostDtorCall`, exec/boundary.ts) — see #160.
+import { assert_, Trap, trap, trapIf } from "./trap.js";
+import { NeedsJspi, notifyInstancePoisoned, PendingCapability, withPoisonCause, } from "../task/scheduler.js";
+export class Table {
+    static MAX_LENGTH = 2 ** 28 - 1;
+    array = [null];
+    free = [];
+    get(i) {
+        trapIf(i >= this.array.length, "table index out of range");
+        trapIf(this.array[i] === null, "table entry empty");
+        return this.array[i];
+    }
+    add(e) {
+        let i;
+        if (this.free.length > 0) {
+            i = this.free.pop();
+            assert_(this.array[i] === null);
+            this.array[i] = e;
+        }
+        else {
+            i = this.array.length;
+            trapIf(i > Table.MAX_LENGTH, "table full");
+            this.array.push(e);
+        }
+        return i;
+    }
+    remove(i) {
+        const e = this.get(i);
+        this.array[i] = null;
+        this.free.push(i);
+        return e;
+    }
+    *[Symbol.iterator]() {
+        for (const e of this.array) {
+            if (e !== null)
+                yield e;
+        }
+    }
+}
+export class ResourceHandle {
+    rt;
+    rep;
+    own;
+    borrowScope;
+    numLends = 0;
+    constructor(rt, rep, own, borrowScope = null) {
+        this.rt = rt;
+        this.rep = rep;
+        this.own = own;
+        this.borrowScope = borrowScope;
+    }
+}
+// ---------------------------------------------------------------------------
+// own/borrow lift & lower (called from load/store/lift/lower dispatchers)
+// ---------------------------------------------------------------------------
+function requireInst(cx) {
+    assert_(cx.inst !== null, "context requires a component instance");
+    return cx.inst;
+}
+export function liftOwn(cx, i, t) {
+    const h = requireInst(cx).handles.remove(i);
+    trapIf(!(h instanceof ResourceHandle), "not a resource handle");
+    const rh = h;
+    trapIf(rh.rt !== t.rt, "resource type mismatch");
+    trapIf(rh.numLends !== 0, "handle still lent out");
+    trapIf(!rh.own, "expected own handle");
+    return rh.rep;
+}
+export function liftBorrow(cx, i, t) {
+    const scope = cx.borrowScope;
+    assert_(scope !== null && typeof scope.addLender === "function", "lifting a borrow requires a subtask borrow scope");
+    const h = requireInst(cx).handles.get(i);
+    trapIf(!(h instanceof ResourceHandle), "not a resource handle");
+    const rh = h;
+    trapIf(rh.rt !== t.rt, "resource type mismatch");
+    scope.addLender(rh);
+    return rh.rep;
+}
+export function lowerOwn(cx, rep, t) {
+    const h = new ResourceHandle(t.rt, rep, true);
+    return requireInst(cx).handles.add(h);
+}
+export function lowerBorrow(cx, rep, t) {
+    const scope = cx.borrowScope;
+    assert_(scope !== null && typeof scope.numBorrows === "number", "lowering a borrow requires a task borrow scope");
+    if (cx.inst !== null && cx.inst === t.rt.impl) {
+        return rep;
+    }
+    const h = new ResourceHandle(t.rt, rep, false, scope);
+    scope.numBorrows += 1;
+    return requireInst(cx).handles.add(h);
+}
+// ---------------------------------------------------------------------------
+// canon resource.new / resource.drop / resource.rep
+// (instance passed explicitly; see module comment)
+// ---------------------------------------------------------------------------
+export function canonResourceNew(inst, rt, rep) {
+    trapIf(!inst.mayLeave, "may_leave violation");
+    const h = new ResourceHandle(rt, rep, true);
+    return inst.handles.add(h);
+}
+function asGate(x) {
+    if (x === null || typeof x !== "object")
+        return null;
+    const g = x;
+    return typeof g.mayEnterFrom === "function" &&
+        typeof g.enterFrom === "function" && typeof g.leaveTo === "function"
+        ? x
+        : null;
+}
+function isThenable(v) {
+    return typeof v === "object" && v !== null &&
+        typeof v.then === "function";
+}
+/**
+ * Invoke a resource destructor through the reference's entry bracket.
+ *
+ * definitions.py `canon_resource_drop` (line 2319) does not call `rt.dtor`
+ * directly. It builds the dtor into a function instance and calls it through
+ * `Store.lift` / `Store.lower` (lines 2330-2333):
+ *
+ * ```python
+ *   dtor = rt.dtor or (lambda rep: [])
+ *   callee = inst.store.lift(dtor, ft, opts, rt.impl)
+ *   caller = inst.store.lower(callee, ft, opts, inst)
+ *   caller([h.rep])
+ * ```
+ *
+ * so the dtor inherits `Store.lift`'s gate verbatim (lines 579-584):
+ * `trap_if(not inst.may_enter_from(caller))`, `enter_from(caller)`, the call,
+ * then `leave_to(caller)` — which a trap skips, leaving the *implementing*
+ * instance permanently unenterable (poisoned).
+ *
+ * Two consequences that are easy to get wrong, both taken from the reference
+ * rather than from intuition:
+ *
+ *  - the bracket runs even when `rt.dtor is None` (the `or (lambda rep: [])`
+ *    above), so a dtor-less resource whose impl instance is mid-execution is
+ *    still a trap. `may_enter_from`/`enter_from` walk `entering_set(caller)`
+ *    (line 230), which is empty when the caller *is* the implementing
+ *    instance — that, not a special case, is the same-instance exemption:
+ *    a component dropping a handle to its own resource never traps.
+ *  - poisoning applies to `rt.impl`, not to the dropping instance. The
+ *    dropper's own bracket (its `Store.lift` frame) is broken by the same
+ *    propagating trap at its own level; here only the callee is retired.
+ *
+ * Capability signals (`NeedsJspi`, `PendingCapability`) are not traps — see
+ * `isCapabilitySignal` in exec/boundary.ts — so they release the gate.
+ *
+ * SCOPE (#160): this is the **guest-initiated** path only. A guest-initiated
+ * drop must complete synchronously (the reference lifts the dtor with
+ * `async_ = False`), so a thenable here is a trap. The host-initiated path
+ * used to share this function with an `allowAsync` flag that held the entry
+ * bracket across the dtor's promise; it now goes through the full lift
+ * harness instead (`hostDtorCall` in exec/boundary.ts), which is what
+ * definitions.py actually does and what unwedges #160.
+ */
+export function callDtorGated(rt, rep, caller) {
+    const impl = asGate(rt.impl);
+    // Always the raw synchronous dtor: `dtorHost` is the host path's lifted
+    // entry, which is not callable from inside a guest activation.
+    const dtorFn = rt.dtor;
+    // No gate available: an imported (host-implemented) resource has
+    // `impl === null` by construction (executor.ts `bindImportedResources`),
+    // and there is no component instance to gate entry into. Test doubles that
+    // supply a bare `{handles, mayLeave}` instance land here too.
+    if (impl === null) {
+        const r = dtorFn?.(rep);
+        trapIf(isThenable(r), "resource destructor did not complete synchronously");
+        return;
+    }
+    // definitions.py `entering_set` (line 230): `self_and_ancestors() -
+    // caller.self_and_ancestors()`. The caller is only meaningful when it is a
+    // real component instance; a host-initiated drop passes null, which is the
+    // reference's `caller = None` (Store.invoke).
+    const callerInst = asGate(caller) === null ? null : caller;
+    // A poisoned target's refusal names the original trap (polyengine#145).
+    if (!impl.mayEnterFrom(callerInst)) {
+        trap(withPoisonCause(impl, "cannot enter component instance"));
+    }
+    impl.enterFrom(callerInst);
+    const poison = (e) => {
+        if (e instanceof NeedsJspi || e instanceof PendingCapability) {
+            // Not a trap: the reference reaches `leave_to` on every execution these
+            // stand in for, so the instance stays enterable.
+            impl.leaveTo(callerInst);
+            return;
+        }
+        // `leave_to` is NOT reached (the gate stays taken, permanently), and the
+        // poisoned instance's live stream/future ends are retired (#66) through
+        // the same seam fact_calls.ts uses for its bracket-break sites.
+        notifyInstancePoisoned(impl, e);
+    };
+    let out;
+    try {
+        out = dtorFn?.(rep);
+    }
+    catch (e) {
+        poison(e);
+        throw e;
+    }
+    if (isThenable(out)) {
+        // A guest-initiated drop is lifted with `async_ = False`: the dtor must
+        // resolve before `canon_resource_drop` returns. Reaching here means the
+        // dtor's activation escaped, which is a trap that poisons the impl.
+        const e = new Trap("resource destructor did not complete synchronously");
+        poison(e);
+        throw e;
+    }
+    impl.leaveTo(callerInst);
+}
+export function canonResourceDrop(inst, rt, i) {
+    trapIf(!inst.mayLeave, "may_leave violation");
+    const h = inst.handles.remove(i);
+    trapIf(!(h instanceof ResourceHandle), "not a resource handle");
+    const rh = h;
+    trapIf(rh.rt !== rt, "resource type mismatch");
+    trapIf(rh.numLends !== 0, "handle still lent out");
+    if (rh.own) {
+        assert_(rh.borrowScope === null);
+        // definitions.py line 2326-2333: the dtor runs through the store's
+        // lift/lower bracket. SCOPE NOTE (#85): the call below is a JS frame
+        // inside the drop trampoline, so a *guest*-initiated drop whose dtor
+        // suspends traps under the JSPI frame rule. That is deterministic and
+        // loud, and routing guest-initiated dtor calls through generated wasm is
+        // explicitly out of scope for #85 (docs/architecture.md §5/§7 carry the
+        // known-limitation note).
+        callDtorGated(rt, rh.rep, inst);
+    }
+    else {
+        assert_(rh.borrowScope !== null);
+        rh.borrowScope.numBorrows -= 1;
+    }
+}
+export function canonResourceRep(inst, rt, i) {
+    const h = inst.handles.get(i);
+    trapIf(!(h instanceof ResourceHandle), "not a resource handle");
+    const rh = h;
+    trapIf(rh.rt !== rt, "resource type mismatch");
+    return rh.rep;
+}

package/esm/cabi/layout.js

@@ -0,0 +1,149 @@
+// Alignment and element size (definitions.py `## Alignment`, `## Element
+// Size`): byte layout of component values in linear memory.
+import { assert_ } from "./trap.js";
+import { ptrSize } from "./memory.js";
+import { despecialize, discriminantType, } from "./types.js";
+export function alignTo(ptr, alignment) {
+    return Math.ceil(ptr / alignment) * alignment;
+}
+export function alignment(t, ptrType) {
+    const d = despecialize(t);
+    switch (d.kind) {
+        case "bool":
+        case "s8":
+        case "u8":
+            return 1;
+        case "s16":
+        case "u16":
+            return 2;
+        case "s32":
+        case "u32":
+        case "f32":
+        case "char":
+            return 4;
+        case "s64":
+        case "u64":
+        case "f64":
+            return 8;
+        case "string":
+            return ptrSize(ptrType);
+        case "error-context":
+            return 4;
+        case "list":
+            return alignmentList(d.element, d.length ?? null, ptrType);
+        case "record":
+            return alignmentRecord(d.fields, ptrType);
+        case "variant":
+            return alignmentVariant(d.cases, ptrType);
+        case "flags":
+            return alignmentFlags(d.labels);
+        case "own":
+        case "borrow":
+        case "stream":
+        case "future":
+            return 4;
+    }
+}
+export function alignmentList(elemType, maybeLength, ptrType) {
+    if (maybeLength !== null)
+        return alignment(elemType, ptrType);
+    return ptrSize(ptrType);
+}
+export function alignmentRecord(fields, ptrType) {
+    let a = 1;
+    for (const f of fields)
+        a = Math.max(a, alignment(f.type, ptrType));
+    return a;
+}
+export function alignmentVariant(cases, ptrType) {
+    return Math.max(alignment(discriminantType(cases), ptrType), maxCaseAlignment(cases, ptrType));
+}
+export function maxCaseAlignment(cases, ptrType) {
+    let a = 1;
+    for (const c of cases) {
+        if (c.type !== null)
+            a = Math.max(a, alignment(c.type, ptrType));
+    }
+    return a;
+}
+export function alignmentFlags(labels) {
+    const n = labels.length;
+    assert_(0 < n && n <= 32, "flags label count");
+    if (n <= 8)
+        return 1;
+    if (n <= 16)
+        return 2;
+    return 4;
+}
+export function elemSize(t, ptrType) {
+    const d = despecialize(t);
+    switch (d.kind) {
+        case "bool":
+        case "s8":
+        case "u8":
+            return 1;
+        case "s16":
+        case "u16":
+            return 2;
+        case "s32":
+        case "u32":
+        case "f32":
+        case "char":
+            return 4;
+        case "s64":
+        case "u64":
+        case "f64":
+            return 8;
+        case "string":
+            return 2 * ptrSize(ptrType);
+        case "error-context":
+            return 4;
+        case "list":
+            return elemSizeList(d.element, d.length ?? null, ptrType);
+        case "record":
+            return elemSizeRecord(d.fields, ptrType);
+        case "variant":
+            return elemSizeVariant(d.cases, ptrType);
+        case "flags":
+            return elemSizeFlags(d.labels);
+        case "own":
+        case "borrow":
+        case "stream":
+        case "future":
+            return 4;
+    }
+}
+export function elemSizeList(elemType, maybeLength, ptrType) {
+    if (maybeLength !== null)
+        return maybeLength * elemSize(elemType, ptrType);
+    return 2 * ptrSize(ptrType);
+}
+export function elemSizeRecord(fields, ptrType) {
+    let s = 0;
+    for (const f of fields) {
+        s = alignTo(s, alignment(f.type, ptrType));
+        s += elemSize(f.type, ptrType);
+    }
+    assert_(s > 0, "empty record");
+    return alignTo(s, alignmentRecord(fields, ptrType));
+}
+export function elemSizeVariant(cases, ptrType) {
+    let s = elemSize(discriminantType(cases), ptrType);
+    s = alignTo(s, maxCaseAlignment(cases, ptrType));
+    let cs = 0;
+    for (const c of cases) {
+        if (c.type !== null)
+            cs = Math.max(cs, elemSize(c.type, ptrType));
+    }
+    s += cs;
+    return alignTo(s, alignmentVariant(cases, ptrType));
+}
+export function elemSizeFlags(labels) {
+    const n = labels.length;
+    assert_(0 < n && n <= 32, "flags label count");
+    if (n <= 8)
+        return 1;
+    if (n <= 16)
+        return 2;
+    return 4;
+}