@polyengine/runtime 0.1.0-pre.g633468a

package/esm/exec/mod.js

@@ -0,0 +1,4 @@
+// Plan executor + host boundary (docs/architecture.md §4.3).
+export * from "./boundary.js";
+export * from "./executor.js";
+export * from "./host_streams.js";

package/esm/intrinsics/async_builtins.js

@@ -0,0 +1,510 @@
+// The 0.3 async canonical built-ins, as host trampolines
+// (contracts/intrinsics.md §B "M2"): task.{return,cancel},
+// backpressure.{set,inc,dec}, waitable-set.{new,wait,poll,drop},
+// waitable.join, subtask.{drop,cancel} and thread.yield.
+//
+// Every one is a direct port of the correspondingly named `canon_*` function
+// in definitions.py (cited per function), with one systematic substitution.
+//
+// ## `current_instance()` vs the trampoline's declared instance
+//
+// definitions.py reads `current_instance()` (line 312), defined as
+// `current_task().inst` — it can, because in the reference a canonical
+// built-in is only ever reached from inside a task. That is not true of a
+// real component: wasmtime lets a core module's **start function** call
+// instance-scoped built-ins (`waitable-set.new`, `backpressure.inc`, ...)
+// during instantiation, before any task exists. The official suite exercises
+// exactly this (e.g. `test/async/dont-block-start.wast`).
+//
+// wasmtime resolves it by naming the owning component instance *statically*
+// in every trampoline declaration (`Trampoline::WaitableSetNew { instance }`
+// and friends — the `instance` field the plan carries). So the built-ins
+// below take their instance from the declaration, which is well-defined at
+// instantiation time and identical to `current_instance()` whenever a task is
+// running. Built-ins that genuinely need the *task* or *thread*
+// (`task.return`, `task.cancel`, `subtask.cancel`, `thread.yield`) still read
+// the current-thread stack: they are meaningless outside a task, and the
+// reference's `trap_if`s are what report that.
+//
+// ## Blocking built-ins in a stackless world
+//
+// `waitable-set.wait`, `thread.yield` and the synchronous `subtask.cancel`
+// all *block the calling wasm frame* in the reference. A callback-ABI guest
+// is stackless: there is no suspendable wasm stack to park, so blocking here
+// genuinely requires JSPI (docs/architecture.md §6, JSPI role 2) and these built-ins say
+// so at the precise point, loudly, instead of faking a wait.
+//
+// They are not, however, unconditionally unavailable. Where the reference can
+// complete *without* suspending — `waitable-set.wait` on a set that already
+// has a pending event, `waitable-set.poll` always, `subtask.cancel` on a
+// subtask that resolved eagerly — this module returns the answer directly.
+// That is not a shortcut: definitions.py's `Thread.wait_until` (line 396) may
+// legitimately return without blocking when `ready_func()` already holds, so
+// taking that branch is a conforming schedule.
+import { blockCurrentActivation } from "../jspi/mod.js";
+import { assert_, trap, trapIf } from "../cabi/trap.js";
+import { CoreValueIter, LiftLowerContext, liftFlatValues, MAX_FLAT_PARAMS, store as storeValue, } from "../cabi/mod.js";
+import { valTypesEqual } from "../cabi/types.js";
+import { currentTask, currentThread, EventCode, liftOptionsEqual, needsJspi, Subtask, Waitable, WaitableSet, } from "../task/mod.js";
+import { cabiOptions, normalizeCoreValues } from "../exec/boundary.js";
+import { traceCopy } from "./stream_builtins.js";
+/**
+ * `BLOCKED` sentinel of `canon_subtask_cancel` (definitions.py line 2467).
+ */
+export const BLOCKED = 0xffff_ffff;
+// ---------------------------------------------------------------------------
+// task.return / task.cancel
+// ---------------------------------------------------------------------------
+/** definitions.py `canon_task_return` (line 2384). */
+export function createTaskReturn(decl, ctx) {
+    const opts = ctx.options(decl.options);
+    // plan v3: `resultType` is the interned `plan.types` entry; `results` is the
+    // raw wasmtime `TypeTupleIndex` (the FACT `task_return_type` key, consumed
+    // by the loader's dictionary). `null` is wire-legal for a task with no
+    // declared result type; today's producer always emits the empty tuple
+    // instead, so this degenerates to `[]` either way.
+    const resultTypes = decl.resultType === null
+        ? []
+        : ctx.resultTypes(decl.resultType);
+    return (...flatArgs) => {
+        const task = currentTask();
+        trapIf(!task.inst.mayLeave, "task.return: cannot leave component instance (may_leave violation)");
+        trapIf(!task.opts.async_, "task.return from a non-async task");
+        // `trap_if(result_type != task.ft.result)` (definitions.py:2388): the
+        // trampoline's interned result tuple must be the lifted function's result
+        // type. Compared structurally — the plan's type table interns by
+        // structure, so identity comparison would reject valid components.
+        //
+        // Plan v3 enables this for FACT cross-component tasks too: the callee
+        // task's declared result type is now resolvable from the raw
+        // `TypeTupleIndex` `prepare-call` carried (contracts/plan-format.md v3
+        // amendment 3, wired in fact_calls.ts). It remains skipped for the one
+        // case v3 does not answer — a callee the plan maps no `task.return`
+        // tuple for, where `ft.results` is a placeholder rather than a
+        // declaration (`factResultTypesKnown === false`); comparing against a
+        // placeholder would be a false rejection, not a check.
+        trapIf((!task.factPassthrough || task.factResultTypesKnown) &&
+            !valTypesEqual(resultTypes, task.ft.results), "task.return with a result type that is not the task's result type");
+        // `trap_if(not LiftOptions.equal(opts, task.opts))` (definitions.py:2389).
+        // The MEMORY half stays skipped for FACT tasks, and plan v3 does NOT
+        // change that: the relaxation was never about the type mapping. The
+        // task's memory is reconstructed from `prepare-call`'s `memory` field,
+        // which is the *adapter's* view of the lift options
+        // (`adapter.lift.options...memory`) and is `None` for callees whose own
+        // `task.return` options do name a memory — the 17-param async-lifted
+        // callees of `test/async/cross-abi-calls.wast` are exactly that shape.
+        // The information simply is not in the plan, at v3 as at v2; restoring
+        // the check needs `prepare-call`'s indices related to the callee's
+        // canonical options, which remains open contract friction.
+        //
+        // definitions.py `LiftOptions.equal` (line 643) compares string encoding
+        // *and* memory identity. Both halves are checked for a host-boundary task.
+        //
+        // For a FACT task the memory half is skipped, and the reason is specific
+        // rather than "we can't be bothered": the task's memory is reconstructed
+        // from `prepare-call`'s `memory` field, which carries the *adapter's* view
+        // of the lift options (`adapter.lift.options...memory`) and is `None`
+        // for callees whose own `task.return` options do name a memory —
+        // `test/async/cross-abi-calls.wast`'s 17-param async-lifted callees are
+        // exactly that shape. wasmtime tolerates the mismatch because its check is
+        // *one-sided*: `concurrent.rs:3344-3358` treats "the `task.return` site
+        // specifies no memory" as valid and only compares when it does, against a
+        // lift memory it holds first-hand. We hold ours second-hand, so applying
+        // either form of the memory comparison produces a false rejection.
+        //
+        // The string-encoding half IS checked on both paths: `prepare-call` passes
+        // the encoding directly, so that reconstruction is exact.
+        trapIf(!liftOptionsEqual({ stringEncoding: opts.stringEncoding, memory: opts.memory }, task.factPassthrough
+            ? { stringEncoding: task.opts.stringEncoding, memory: opts.memory }
+            : task.opts), "task.return with canonical options differing from the task's");
+        // Type-aware per-lane normalization: `normalizeFlat`'s blanket `>>> 0`
+        // silently truncated float lanes (a `task.return` of f64 -1.1 arrived at
+        // `[async-return]` as 4294967295). `normalizeCoreValues` consults the
+        // declared lane types, so only i32 lanes are coerced.
+        const flat = normalizeCoreValues(flatArgs, opts.coreType.params, "task.return arguments");
+        if (task.factPassthrough) {
+            // FACT cross-component call: the caller's `[async-return]` adapter
+            // function does the lift-and-lower itself, in wasm, so the host hands it
+            // the callee's flat results untouched. See `Task.factPassthrough`.
+            task.return_(flat);
+            return;
+        }
+        const cx = new LiftLowerContext(cabiOptions(opts), task.inst, task);
+        const vi = new CoreValueIter(flat);
+        const result = liftFlatValues(cx, MAX_FLAT_PARAMS, vi, task.ft.results);
+        task.return_(result);
+    };
+}
+/** definitions.py `canon_task_cancel` (line 2397). */
+export function createTaskCancel() {
+    return () => {
+        const task = currentTask();
+        trapIf(!task.inst.mayLeave, "task.cancel: cannot leave component instance (may_leave violation)");
+        trapIf(!task.opts.async_, "task.cancel from a non-async task");
+        task.cancel();
+    };
+}
+// ---------------------------------------------------------------------------
+// backpressure
+// ---------------------------------------------------------------------------
+// `canon_backpressure_set` is not ported: wasmtime 47 emits no
+// `BackpressureSet` trampoline (`component/info.rs` has only
+// `BackpressureInc`/`BackpressureDec`), and the reference's own copy was
+// unreachable dead code until upstream removed it (CM PR #690; see
+// upstream-component-model-repo-findings.md CM-2, RESOLVED). The counter
+// below is the live interface.
+/** definitions.py `canon_backpressure_inc` (line 2368). */
+export function createBackpressureInc(inst) {
+    return () => {
+        assert_(inst.backpressure >= 0 && inst.backpressure < 2 ** 16, "backpressure counter out of range");
+        inst.backpressure += 1;
+        trapIf(inst.backpressure === 2 ** 16, "backpressure counter overflow");
+    };
+}
+/** definitions.py `canon_backpressure_dec` (line 2375). */
+export function createBackpressureDec(inst) {
+    return () => {
+        assert_(inst.backpressure >= 0 && inst.backpressure < 2 ** 16, "backpressure counter out of range");
+        inst.backpressure -= 1;
+        trapIf(inst.backpressure < 0, "backpressure counter underflow");
+    };
+}
+// ---------------------------------------------------------------------------
+// waitable sets
+// ---------------------------------------------------------------------------
+/** definitions.py `canon_waitable_set_new` (line 2406). */
+export function createWaitableSetNew(inst) {
+    return () => {
+        trapIf(!inst.mayLeave, "waitable-set.new: cannot leave component instance");
+        return inst.handles.add(new WaitableSet());
+    };
+}
+/**
+ * definitions.py `canon_waitable_set_wait` (line 2414).
+ *
+ * The reference blocks the calling thread until the set has an event. From a
+ * stackless (callback-ABI) guest there is no wasm stack to suspend, so this
+ * only succeeds when an event is *already* pending — which is the reference's
+ * own non-blocking branch of `Thread.wait_until`. Otherwise: `needsJspi`.
+ *
+ * A guest using the callback ABI is expected to return the `WAIT` callback
+ * code rather than call this built-in; hitting the JSPI path here means the
+ * component uses the stackful async ABI.
+ */
+export function createWaitableSetWait(decl, ctx, inst, mode = "plain") {
+    const opts = ctx.options(decl.options);
+    // `cancellable` is a *canonical option*, not a trampoline field: wasmtime's
+    // `Trampoline::WaitableSetWait` carries only `{instance, options}`
+    // (wasmtime-environ 47.0.3 `component/info.rs:815`), while
+    // `CanonicalOptions.cancellable` (info.rs:540) is what the guest declared.
+    // It reaches definitions.py as `canon_waitable_set_wait`'s first parameter
+    // (line 2414).
+    const cancellable = opts.cancellable;
+    return (si, ptr) => {
+        trapIf(!inst.mayLeave, "waitable-set.wait: cannot leave component instance");
+        const wset = requireWaitableSet(inst, si ?? 0, "waitable-set.wait");
+        const task = currentTask();
+        let event;
+        if (task.deliverPendingCancel(cancellable)) {
+            event = [EventCode.TASK_CANCELLED, 0, 0];
+        }
+        else if (wset.hasPendingEvent()) {
+            // Non-blocking branch: definitions.py `Thread.wait_until` may return
+            // immediately when the condition already holds.
+            //
+            // This deliberately skips `wait_for_event_and`, and with it the
+            // `num_waiting += 1 / -= 1` bracket around the block
+            // (`WaitableSet.wait_for_event_and`, line 829). That is unobservable:
+            // `num_waiting` is read only by `WaitableSet.drop`
+            // (`trap_if(self.num_waiting > 0)`, line 852), and since we never yield
+            // between the increment and the decrement here, no other code could run
+            // to observe a non-zero value. Incrementing and immediately decrementing
+            // would be pure ceremony.
+            traceCopy(`waitable-set.wait si=${si} FAST (pending event)`);
+            event = wset.getPendingEvent();
+        }
+        else if (mode === "jspi") {
+            traceCopy(`waitable-set.wait si=${si} BLOCKS`);
+            // SITE 2 (lit). definitions.py `WaitableSet.wait_for_event_and`
+            // (line 829): block until the set has an event, then take it.
+            //
+            // The `num_waiting` bracket is real now. Skipping it was justified only
+            // while this path could not actually yield; a genuine block CAN be
+            // observed, because `WaitableSet.drop` traps on `num_waiting > 0`
+            // (line 852). Incremented before blocking and decremented in
+            // `onSettled`, which runs exactly once on EVERY terminal transition —
+            // normal resume, cancelled resume, produce-throw, and `abandon`
+            // (#106: decrementing in `produce` missed the abandon leg, leaving
+            // `numWaiting` elevated forever and a later `waitable-set.drop`
+            // trapping spuriously). The decrement is not idempotent, so it lives
+            // ONLY here, not in `produce` as well; nothing can observe the still-
+            // elevated count between `produce` and the hook — both run
+            // synchronously inside the settle, before any other code.
+            wset.numWaiting += 1;
+            return blockCurrentActivation({
+                store: inst.store,
+                task,
+                readyFunc: () => wset.hasPendingEvent(),
+                cancellable,
+                produce: (cancelled) => {
+                    const ev = cancelled
+                        ? [EventCode.TASK_CANCELLED, 0, 0]
+                        : wset.getPendingEvent();
+                    return unpackEvent(opts, inst, ptr ?? 0, ev);
+                },
+                onSettled: () => {
+                    wset.numWaiting -= 1;
+                },
+            });
+        }
+        else {
+            needsJspi("waitable-set.wait with no pending event (the calling wasm frame " +
+                "must block; a callback-ABI guest should return the WAIT code " +
+                "instead)");
+        }
+        return unpackEvent(opts, inst, ptr ?? 0, event);
+    };
+}
+/** definitions.py `canon_waitable_set_poll` (line 2431). */
+export function createWaitableSetPoll(decl, ctx, inst) {
+    const opts = ctx.options(decl.options);
+    /** See `createWaitableSetWait`: `cancellable` is an option, not a decl field. */
+    const cancellable = opts.cancellable;
+    return (si, ptr) => {
+        trapIf(!inst.mayLeave, "waitable-set.poll: cannot leave component instance");
+        const wset = requireWaitableSet(inst, si ?? 0, "waitable-set.poll");
+        const event = wset.poll(currentTask(), cancellable);
+        return unpackEvent(opts, inst, ptr ?? 0, event);
+    };
+}
+/** definitions.py `canon_waitable_set_drop` (line 2441). */
+export function createWaitableSetDrop(inst) {
+    return (i) => {
+        trapIf(!inst.mayLeave, "waitable-set.drop: cannot leave component instance");
+        const wset = inst.handles.remove(i ?? 0);
+        trapIf(!(wset instanceof WaitableSet), "waitable-set.drop: handle is not a waitable set");
+        wset.drop();
+    };
+}
+/** definitions.py `canon_waitable_join` (line 2451). */
+export function createWaitableJoin(inst) {
+    return (wi, si) => {
+        trapIf(!inst.mayLeave, "waitable.join: cannot leave component instance");
+        const w = inst.handles.get(wi ?? 0);
+        trapIf(!(w instanceof Waitable), "waitable.join: handle is not a waitable");
+        trapIf(w.hasSyncWaiter, "waitable.join on a waitable with a synchronous waiter");
+        if ((si ?? 0) === 0) {
+            w.join(null);
+            return;
+        }
+        const wset = requireWaitableSet(inst, si, "waitable.join");
+        w.join(wset);
+    };
+}
+// ---------------------------------------------------------------------------
+// subtasks
+// ---------------------------------------------------------------------------
+/** definitions.py `canon_subtask_drop` (line 2494). */
+export function createSubtaskDrop(inst) {
+    return (i) => {
+        trapIf(!inst.mayLeave, "subtask.drop: cannot leave component instance");
+        const s = inst.handles.remove(i ?? 0);
+        trapIf(!(s instanceof Subtask), "subtask.drop: handle is not a subtask");
+        s.drop();
+    };
+}
+/**
+ * definitions.py `canon_subtask_cancel` (line 2469).
+ *
+ * The synchronous form blocks (`subtask.wait_for_pending_event()`) when the
+ * callee does not resolve promptly; from a stackless guest that is JSPI
+ * territory. The async form returns `BLOCKED` instead of blocking, and is
+ * fully supported.
+ */
+/**
+ * The tail shared by `subtask.cancel`'s blocking and non-blocking exits:
+ * take the delivered SUBTASK event, check it is the one we expect, and report
+ * the resolved state. Factored out so the blocking form can run it at RESUME
+ * time inside `produce`.
+ */
+function finishSubtaskCancel(i, st) {
+    return () => {
+        const [code, index, payload] = st.getPendingEvent();
+        assert_(code === EventCode.SUBTASK && index === (i ?? 0) && payload === st.state, "unexpected event delivered by subtask.cancel");
+        assert_(st.resolveDelivered(), "subtask.cancel did not deliver the resolution");
+        return st.state;
+    };
+}
+export function createSubtaskCancel(decl, inst, mode = "plain") {
+    const async_ = decl.async === true;
+    return (i) => {
+        // The handle table is the **declared** instance's, not
+        // `current_thread().task.inst`. definitions.py `canon_subtask_cancel`
+        // (line 2469) uses the latter because the reference has no fused
+        // adapters, so the running task and the subtask's owner always coincide.
+        // With FACT they do not: `async-start-call` adds the subtask to
+        // `prepare-call`'s `caller_instance`, which for a nested component is a
+        // *different* instance from the one whose task is running — observed as
+        // caller=2 vs task.inst=3 in `big-interleaving-test.wast:1584`, where the
+        // lookup then failed with "table index out of range". wasmtime names the
+        // owner on the trampoline for exactly this reason
+        // (`Trampoline::SubtaskCancel { instance, .. }`), which is the same
+        // correction already applied to every other instance-scoped built-in —
+        // see this module's header.
+        trapIf(!inst.mayLeave, "subtask.cancel: cannot leave component instance");
+        const subtask = inst.handles.get(i ?? 0);
+        trapIf(!(subtask instanceof Subtask), "subtask.cancel: handle is not a subtask");
+        const st = subtask;
+        const finish = finishSubtaskCancel(i, st);
+        trapIf(st.resolveDelivered(), "subtask.cancel on a subtask whose resolution was already delivered");
+        trapIf(st.cancellationRequested, "subtask.cancel on a subtask that was already cancelled");
+        trapIf(st.inWaitableSet() && !async_, "synchronous subtask.cancel on a subtask that is in a waitable set");
+        if (st.resolved()) {
+            assert_(st.hasPendingEvent(), "resolved subtask without a pending event at cancellation");
+        }
+        else {
+            st.cancellationRequested = true;
+            assert_(st.onCancel !== null, "subtask.cancel on a subtask with no cancellation handler");
+            st.onCancel(inst);
+            if (!st.resolved()) {
+                if (!async_) {
+                    if (mode === "jspi") {
+                        // SITE 5 (lit): a sync `subtask.cancel` blocks until the callee
+                        // actually resolves (definitions.py `canon_subtask_cancel`), then
+                        // reports the resolved state through the same tail as the
+                        // non-blocking path. Mirrors SITE 4 (stream_builtins.ts:305-323)
+                        // and `Waitable.waitForPendingEvent` (definitions.py:786-790,
+                        // reached from canon_subtask_cancel's `subtask.wait_for_pending_event()`
+                        // call, :2484): `hasSyncWaiter` must
+                        // be set for the duration so a concurrent `waitable.join` on
+                        // this subtask traps (async_builtins.ts:362-365) instead of
+                        // racing the SUBTASK event away from this resume (#87).
+                        st.hasSyncWaiter = true;
+                        return blockCurrentActivation({
+                            store: inst.store,
+                            task: currentTask(),
+                            readyFunc: () => st.hasPendingEvent(),
+                            cancellable: false,
+                            produce: () => {
+                                st.hasSyncWaiter = false;
+                                return finish();
+                            },
+                            // #106: `abandon` never runs `produce`; without the backstop
+                            // the flag stayed set forever and a later `waitable.join` on
+                            // this subtask trapped spuriously. Idempotent, so the success
+                            // path's clear-inside-`produce` ordering is untouched.
+                            onSettled: () => {
+                                st.hasSyncWaiter = false;
+                            },
+                        });
+                    }
+                    needsJspi("synchronous subtask.cancel whose callee did not resolve " +
+                        "immediately (the calling wasm frame must block)");
+                }
+                // The ASYNC form answers "did the cancellation resolve the callee
+                // promptly?" — BLOCKED only when it genuinely did not
+                // (definitions.py line 2486). Under jspi "promptly" is invisible at
+                // this instant: `request_cancellation` delivered TASK_CANCELLED by
+                // settling the callee's suspension, and the engine runs the resumed
+                // activation (whose `task.cancel` resolves this subtask) on a LATER
+                // microtask (pin (j)). Deciding now reports BLOCKED for a callee the
+                // reference resolves synchronously (cancellable.wast tests 1-2). So:
+                // wait until the callee is DETERMINATE — resolved, finished, or
+                // re-parked on a scheduler condition — exactly `async-start-call`'s
+                // rule (fact_calls.ts). A callee with a pending (undeliverable)
+                // cancel sits parked non-cancellably, which is determinate, so the
+                // genuine BLOCKED answer is still immediate. Host-import subtasks
+                // carry no callee task: their onCancel is a no-op and their state
+                // cannot be mid-hop, so the pre-jspi immediate answer stands.
+                //
+                // NAMED DIVERGENCE (docs/architecture.md §6, #92): this park makes
+                // the async built-in non-atomic — other ready threads may run while
+                // it waits, a reordering within the reference's Store.tick freedom
+                // taken one built-in early.
+                if (mode === "jspi" && st.calleeTask !== null) {
+                    const t = st.calleeTask;
+                    const store = inst.store;
+                    const determinate = () => st.resolved() ||
+                        t.threads.every((th) => th.done()) ||
+                        store.waiting.some((w) => w.task === st.calleeTask);
+                    if (!determinate()) {
+                        return blockCurrentActivation({
+                            store: inst.store,
+                            task: currentTask(),
+                            readyFunc: determinate,
+                            cancellable: false,
+                            produce: () => (st.resolved() ? finish() : BLOCKED),
+                        });
+                    }
+                    if (!st.resolved())
+                        return BLOCKED;
+                    return finish();
+                }
+                return BLOCKED;
+            }
+        }
+        return finish();
+    };
+}
+// ---------------------------------------------------------------------------
+// thread.yield
+// ---------------------------------------------------------------------------
+/**
+ * definitions.py `canon_thread_yield` (line 2728).
+ *
+ * Yielding blocks the calling wasm frame until the scheduler comes back to
+ * it. A callback-ABI guest expresses the same intent by returning the `YIELD`
+ * callback code, which this runtime implements fully (exec/boundary.ts); the
+ * *built-in* form needs a suspendable stack.
+ */
+export function createThreadYield(decl, mode = "plain") {
+    const cancellable = decl.cancellable === true;
+    return () => {
+        const thread = currentThread();
+        trapIf(!thread.task.inst.mayLeave, "thread.yield: cannot leave component instance");
+        // A pending cancellation is deliverable without suspending at all
+        // (definitions.py `Thread.yield_` -> `wait_until` -> `deliver_pending_cancel`).
+        if (thread.task.deliverPendingCancel(cancellable))
+            return 1;
+        if (mode === "jspi") {
+            // SITE 3 (lit). definitions.py `Thread.yield_` is
+            // `wait_until(lambda: True, cancellable)`: immediately ready, but it
+            // goes through the scheduler, so other threads get a turn first. A
+            // suspension point with an always-true `readyFunc` is exactly that --
+            // `Store.tick` will resume it, after whatever else is already ready.
+            return blockCurrentActivation({
+                store: thread.task.inst.store,
+                task: thread.task,
+                readyFunc: () => true,
+                cancellable,
+                produce: (cancelled) => (cancelled ? 1 : 0),
+            });
+        }
+        needsJspi("thread.yield (the calling wasm frame must block; a callback-ABI " +
+            "guest should return the YIELD code instead)");
+    };
+}
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+function requireWaitableSet(inst, si, what) {
+    const wset = inst.handles.get(si);
+    trapIf(!(wset instanceof WaitableSet), `${what}: handle ${si} is not a waitable set`);
+    return wset;
+}
+/**
+ * definitions.py `unpack_event` (line 2422): store the two payload words at
+ * `ptr` and return the event code.
+ */
+function unpackEvent(opts, inst, ptr, e) {
+    const [event, p1, p2] = e;
+    const cx = new LiftLowerContext(cabiOptions(opts), inst, null);
+    storeValue(cx, p1, { kind: "u32" }, ptr);
+    storeValue(cx, p2, { kind: "u32" }, ptr + 4);
+    return event;
+}
+// Structural `ValType` equality (the C2-D bugfix) moved to cabi/types.ts
+// (`valTypesEqual`) when the #18 tls smoke found its stream-element sibling;
+// the contract note lives there now.
+/** Unused-import guard: `trap` is re-exported for symmetry with cabi. */
+void trap;

package/esm/intrinsics/context.js

@@ -0,0 +1,90 @@
+// `CoreDef::UnsafeIntrinsic` (plan v1 / contracts/plan-format.md v0.3):
+// wasmtime compile-time builtins that a component's core modules import
+// directly, bypassing the trampoline table.
+//
+// Of wasmtime-environ 47.0.3's 21 unsafe intrinsics
+// (`component/intrinsic.rs`, `for_each_unsafe_intrinsic!`) only four have
+// Component Model meaning: `context-{get,set}-i32-{0,1}`, the canonical
+// `context.get` / `context.set` built-ins. The other seventeen
+// (`*-native-load` / `*-native-store` / `store-data-address`) are raw host
+// memory access for wasmtime's own internals; they have no portable meaning
+// in a JS host and are refused at instantiate time.
+import { assert_, trapIf } from "../cabi/trap.js";
+import { currentThread } from "../task/mod.js";
+import { ambientDebug, dbgId } from "../task/scheduler.js";
+import { UnsupportedFeatureError } from "./errors.js";
+/**
+ * Number of `i32` context slots per thread. definitions.py `Thread.storage`
+ * is initialised `[0,0]` (line 347) and `canon_context_{get,set}` assert
+ * `i < len(thread.storage)` — so exactly two, matching the intrinsic names
+ * `context-*-i32-0` and `context-*-i32-1`.
+ */
+export const NUM_CONTEXT_SLOTS = 2;
+/**
+ * definitions.py `canon_context_get` (line 2348).
+ *
+ * The storage is **per thread**, not per task: two threads of one task have
+ * independent context. wit-bindgen 0.60 keeps its async-executor task pointer
+ * in slot 0, which is why this intrinsic is the entry blocker for async
+ * guests.
+ */
+export function canonContextGet(i) {
+    const thread = currentThread();
+    assert_(i < NUM_CONTEXT_SLOTS, `context.get slot ${i} out of range`);
+    const result = thread.storage[i];
+    assert_(result < 2 ** 32, "context.get value out of i32 range");
+    if (CTX_TRACE)
+        trace(`get[${i}] -> ${result}`, thread);
+    return result >>> 0;
+}
+// Standing probe (CE_CTX_TRACE=1): per-call context-slot traffic with the
+// full ambient state — the instrument that isolated issue #24. Cheap and
+// env-gated; keep.
+const CTX_TRACE = (() => {
+    try {
+        return Deno.env.get("CE_CTX_TRACE") === "1";
+    }
+    catch {
+        return false;
+    }
+})();
+export function ctxThreadId(t) {
+    return dbgId(t);
+}
+function trace(msg, thread) {
+    const a = ambientDebug();
+    console.error(`[ctx] ${ctxThreadId(thread)} ${msg} storage=${JSON.stringify(thread.storage)} | stack=[${a.stack.map(ctxThreadId).join(",")}] claims=[${a.claims.map(ctxThreadId).join(",")}] resuming=${a.resuming === null ? "-" : ctxThreadId(a.resuming)}`);
+}
+/** definitions.py `canon_context_set` (line 2358). */
+export function canonContextSet(i, v) {
+    const thread = currentThread();
+    assert_(i < NUM_CONTEXT_SLOTS, `context.set slot ${i} out of range`);
+    if (CTX_TRACE)
+        trace(`set[${i}] = ${v >>> 0}`, thread);
+    thread.storage[i] = v >>> 0;
+}
+/**
+ * Materialize one `unsafe-intrinsic` CoreDef as a core function.
+ *
+ * Called during initializer resolution — i.e. at instantiate time — so an
+ * unimplementable symbol fails instantiation rather than the first call
+ * (contracts/plan-format.md "Executor obligations").
+ */
+export function createUnsafeIntrinsic(symbol) {
+    const match = /^context-(get|set)-i32-(\d+)$/.exec(symbol);
+    if (match === null) {
+        throw new UnsupportedFeatureError("M2", `component imports the unsafe intrinsic '${symbol}', which has no ` +
+            `portable meaning in a JS host (only context.{get,set} do)`);
+    }
+    const slot = Number(match[2]);
+    // A slot outside the canonical range would be a wasmtime/plan inconsistency
+    // rather than a missing capability, but refusing it here is still the right
+    // shape: instantiate-time, never call-time.
+    trapIf(slot >= NUM_CONTEXT_SLOTS, `unsafe intrinsic '${symbol}' addresses context slot ${slot}, but a ` +
+        `thread has ${NUM_CONTEXT_SLOTS}`);
+    if (match[1] === "get")
+        return () => canonContextGet(slot);
+    return (v) => {
+        canonContextSet(slot, (v ?? 0) >>> 0);
+    };
+}

package/esm/intrinsics/errors.js

@@ -0,0 +1,13 @@
+// Shared failure type for trampolines/intrinsics scheduled after the current
+// milestone. Split out of ./mod.ts so sibling intrinsic modules can raise it
+// without importing the (much larger) trampoline dispatcher.
+/** Instantiate-time failure for functionality scheduled after M0. */
+export class UnsupportedFeatureError extends Error {
+    milestone;
+    constructor(milestone, what) {
+        super(`${what} — scheduled for ${milestone}, not implemented in the current ` +
+            `executor (contracts/intrinsics.md §B)`);
+        this.milestone = milestone;
+        this.name = "UnsupportedFeatureError";
+    }
+}