@polyengine/runtime 0.5.0 → 0.6.0

package/esm/exec/boundary.js

@@ -4,7 +4,7 @@
 // canonical options — docs/architecture.md §4.3 items 2 and 5, degenerate sync case.
 import { coreFuncTypeEquals, CoreValueIter, flattenFunctype, liftFlatValues, LiftLowerContext, lowerFlatValues, MAX_FLAT_ASYNC_PARAMS, MAX_FLAT_PARAMS, MAX_FLAT_RESULTS, trap, trapIf, } from "../cabi/mod.js";
 import { AssertionError, assert_ } from "../cabi/trap.js";
-import { driveSyncLift, EventCode, withActivation, hasRealHostCall, dispatchableTail, NeedsJspi, needsJspi, packSubtaskResult, PendingCapability, notifyInstancePoisoned, realHostCalls, storeQuiescent, Subtask, WaitableSet, SubtaskState, Task, Thread, withPoisonCause, } from "../task/mod.js";
+import { driveSyncLift, EventCode, withActivation, hasRealHostCall, NeedsJspi, needsJspi, packSubtaskResult, PendingCapability, notifyInstancePoisoned, realHostCalls, storeQuiescent, Subtask, SyncEntryBusy, WaitableSet, SubtaskState, Task, Thread, entryRefusal, } from "../task/mod.js";
 import { currentTask } from "../task/scheduler.js";
 import { PlanError } from "../plan/loader.js";
 import { blockCurrentActivation, enterWasm, } from "../jspi/mod.js";
@@ -31,7 +31,7 @@ export function newStats() {
  * Structurally compatible with cabi's `MemInst` (same public surface).
  */
 export class LiveMemory {
-    addrType = "i32"; // memory64 components: out of M0 scope
+    addrType = "i32"; // memory64 components: not yet implemented
     #provider;
     #label;
     #buffer = null;
@@ -240,7 +240,7 @@ function isPromiseLike(v) {
         typeof v.then === "function");
 }
 // ---------------------------------------------------------------------------
-// Handshake probe (M2 phase 3l)
+// Handshake probe
 // ---------------------------------------------------------------------------
 //
 // Env-gated tracing of the drive loops. This exists because site 1 is the
@@ -366,7 +366,7 @@ function tagAwait(t) {
  * repeat. Reimplementing it there diverged: that copy only drained
  * `store.awaiting` and never awaited `pendingHostCalls`, so a guest parked on
  * a Promise-returning host import was never resumed and the host's read of
- * the stream it was feeding hung (C0 finding R-1).
+ * the stream it was feeding hung (host-pump starvation of `pendingHostCalls`).
  *
  * Callers that must not hit the deadlock traps below (the host pump: an
  * embedder that never does its half is documented to hang, not trap) can
@@ -385,7 +385,9 @@ export async function driveStoreAsync(store, done, what) {
  * have always produced concurrent loops, and the host-stream pump's stand-down
  * below is cooperative, so a *bounded overlap window* remains by construction
  * (an export call can start while the pump is parked mid-`await`; the pump
- * only notices at its next `done()` evaluation). The invariant is:
+ * notices at its next `done()` evaluation, which the driver-arrival one-shot
+ * below now makes prompt — before issue #239 it was "whenever the host happens
+ * to answer", i.e. not bounded at all). The invariant is:
  *
  *   **no activation is resumed twice for one settlement, and no activation is
  *   resumed with a value from a settlement it has already consumed.**
@@ -455,6 +457,51 @@ export function whenStoreDriverIdle(store) {
     return w.p;
 }
 // ---------------------------------------------------------------------------
+// Driver arrival: closing the overlap window (issue #239)
+// ---------------------------------------------------------------------------
+//
+// The stand-down above ("the pumps are *fallback* drivers") is evaluated only
+// at a driver's next `done()`, so the doc's "bounded overlap window" is really
+// bounded by whatever the incumbent driver is parked on — and its longest park
+// is `Promise.race([...parked tags, ...pendingHostCalls])`, i.e. HOST-CONTROLLED
+// time. That is a stall in its own right, and it is fatal in combination with
+// the SPECULATIVE resume entry the race holds: `Store.pendingResumptions` is a
+// store-wide scheduling gate, so a second driver on the same store spins at
+// `driveAsync`'s top and dies at the 10,000-hop internal-bug assert in ~311ms
+// (issue #239 — the same-store half of the cross-store stall #210 fixed; see
+// `tests/cross_store_driver_test.ts`, whose header describes this gate being
+// "held for the entire duration of a guest's wait on a slow host import").
+//
+// So drivers announce themselves: every `driveAsync` that finds itself the
+// second (or later) loop on a store fires this one-shot, which every driver
+// races alongside its parked tags. The incumbent wakes within a microtask,
+// drops the speculative entry on its way out of the race, and re-evaluates
+// `done()` — which is exactly the stand-down the pumps were always supposed to
+// perform, now prompt instead of "whenever the host happens to answer".
+const driverArrivals = new WeakMap();
+/** A one-shot that resolves (to `null`, the race's "nothing settled" value)
+ * when another driver starts on `store`. */
+function armDriverArrival(store) {
+    let n = driverArrivals.get(store);
+    if (n === undefined) {
+        let r;
+        const p = new Promise((res) => (r = () => res(null)));
+        n = { p, r };
+        driverArrivals.set(store, n);
+    }
+    return n.p;
+}
+function fireDriverArrival(store) {
+    const n = driverArrivals.get(store);
+    if (n === undefined)
+        return;
+    // Deleted before resolving so the next `armDriverArrival` mints a fresh,
+    // unresolved one-shot: a driver that wakes on this and re-parks must not
+    // pick the settled promise back up and spin.
+    driverArrivals.delete(store);
+    n.r();
+}
+// ---------------------------------------------------------------------------
 // The settlement pump: liveness between export calls
 // ---------------------------------------------------------------------------
 //
@@ -599,7 +646,14 @@ async function settlementPumpLoop(store) {
     }
 }
 async function driveAsync(store, done, what) {
-    driverDepth.set(store, storeDriverDepth(store) + 1);
+    const depth = storeDriverDepth(store) + 1;
+    driverDepth.set(store, depth);
+    // An incumbent driver may be parked in the awaiting-race holding the
+    // speculative resume entry — a store-wide gate this loop would otherwise
+    // spin on until the 10,000-hop assert (issue #239). Announce ourselves so it
+    // stands down within a microtask.
+    if (depth > 1)
+        fireDriverArrival(store);
     try {
         let claimHops = 0;
         for (;;) {
@@ -626,11 +680,12 @@ async function driveAsync(store, done, what) {
             // and clearing it before that activation runs re-opens the
             // mis-attribution window the entry exists to close.
             //
-            // PER-STORE (issue #210): this gate used to read a module-global slot, so
-            // an idle store's driver spun here — and died at the hop bound below in
-            // ~311ms — merely because ANOTHER store's guest was dwelling on a slow
-            // host import. Activations never cross stores; another store's pending
-            // resumption is none of this loop's business.
+            // PER-STORE (issue #210): read only THIS store's entries. Activations
+            // never cross stores, so another store's pending resumption is none of
+            // this loop's business — and a gate shared across stores would spin an
+            // idle store's driver here, to its death at the hop bound below in
+            // ~311ms, merely because ANOTHER store's guest was dwelling on a slow
+            // host import.
             if (store.hasPendingResumptions()) {
                 traceDrive("driveAsync", store, done, "yield-pending");
                 // Bounded: a pending entry that never dies is an internal bug (every
@@ -688,7 +743,7 @@ async function driveAsync(store, done, what) {
             // therefore stops the scheduler while waiting for something that needs the
             // scheduler: a pure-microtask stall with no trap and no rejection.
             // Observed on `async/async-calls-sync.wast` the moment site 1 became the
-            // first lit suspension site (M2 phase 3l): turn N serviced a promise that
+            // first lit suspension site: turn N serviced a promise that
             // never settled while three other parked threads and three ready-able
             // suspension points went unexamined.
             //
@@ -751,12 +806,12 @@ async function driveAsync(store, done, what) {
                         // set changing: the same activation resumes off an engine
                         // continuation chunk during the probe's macrotask turn (jspi
                         // pin (j) — a sync-completing Suspending import still defers its
-                        // continuation), runs, and re-parks through the A1 arm, which
+                        // continuation), runs, and re-parks through the suspending mark arm, which
                         // registers a fresh `pendingHostCalls` entry. The activation
                         // promise never settled and `awaiting` membership is unchanged,
                         // but the park is externally wakeable now — the verdict's own
                         // precondition (`pendingHostCalls.size === 0`) no longer holds.
-                        // Observed on wasi-shims' A5 poll (sync fast path): probe sampled
+                        // Observed on wasi-shims' stream/future round-trip poll (sync fast path): probe sampled
                         // hostCalls=0 between a settled park and the next one, then
                         // trapped a live workload with hostCalls=1. Re-check ⇒ re-probe.
                         // Likewise a SERVICEABLE settled entry (issue #156): dispatching
@@ -801,7 +856,7 @@ async function driveAsync(store, done, what) {
                 // snapshot's `parked[0]` is then `undefined` — the exact check-then-act
                 // shape that made the host pump's copy of this loop throw
                 // `TypeError: ... (reading 'awaiting')` into `store.hostFailure`, where
-                // it poisoned a later unrelated call (C0 finding R-2). Nothing to
+                // it poisoned a later unrelated call via check-then-act on `store.hostFailure`. Nothing to
                 // service ⇒ go back to the top and re-evaluate `done`.
                 // Same re-check for the settled queue, and for the same reason: the
                 // probe's macrotask turn can land a fresh, SERVICEABLE activation tail
@@ -820,7 +875,7 @@ async function driveAsync(store, done, what) {
                 // never be held hostage by it. The claimed thread's promise may only be
                 // settleable by further scheduler progress (a promising-wrapped nested
                 // activation whose own suspension points this loop must still resume);
-                // blocking on it alone is the pure-microtask stall of M2 phase 3l.
+                // blocking on it alone is the pure-microtask stall described above.
                 // Same exclusion as the probe (issue #156): a thread whose tail is
                 // already queued in `store.settled` must not be raced — its tag is
                 // settled, so it re-wins instantly and livelocks the event loop,
@@ -828,12 +883,17 @@ async function driveAsync(store, done, what) {
                 const queued = new Set(store.settled.map((s) => s.t));
                 const parked = [...store.awaiting].filter((t) => !queued.has(t));
                 if (parked.length === 0) {
-                    // Every awaiting thread's settle is deferred on a non-enterable
-                    // instance. The way out is the lock holder finishing, and the only
-                    // await-spanning host-entry lock is the async-dtor bracket, which
-                    // registers in `pendingHostCalls` — so park on those.
+                    // UNREACHABLE BY CONSTRUCTION. `parked` is `store.awaiting` minus
+                    // the threads whose tails are already queued in `store.settled`, and
+                    // we only get here with `awaiting` non-empty and
+                    // `hasServiceableSettled()` false — which means the settled queue is
+                    // EMPTY, so nothing was excluded. Retained as a wedge detector, not
+                    // as expected behavior.
                     if (store.pendingHostCalls.size > 0) {
-                        await Promise.race([...store.pendingHostCalls]).catch(() => { });
+                        await Promise.race([
+                            ...store.pendingHostCalls,
+                            armDriverArrival(store),
+                        ]).catch(() => { });
                         continue;
                     }
                     // Per the issue #156 analysis this is unreachable (a spanning lock
@@ -858,18 +918,55 @@ async function driveAsync(store, done, what) {
                 // `SuspensionPoint.resume`) is what carries it, and dropping an entry
                 // that names a thread already gone from the set is a no-op.
                 //
-                // ONLY ITS OWN ENTRY (issue #158): the `finally` used to blanket-clear
-                // the single global slot, so a guest-synchronous delivery during the
-                // await — which takes a fresh entry of its own — had that entry
-                // clobbered early, re-opening the window it exists to close. With a set
-                // we can name exactly what we added.
-                store.addPendingResumption(chosen);
+                // ONLY ITS OWN ENTRY (issue #158): the `finally` must drop the entry
+                // THIS loop added and nothing else. A guest-synchronous delivery during
+                // the await takes a fresh entry of its own, and clearing that one here
+                // would re-open early the very window it exists to close — which is why
+                // the gate is a set of entries rather than a single slot.
+                //
+                // SOLE DRIVER ONLY, AND ONLY UNTIL ONE ARRIVES (issue #239). The entry
+                // is a claim over a window this loop cannot bound: the race settles when
+                // the HOST answers, which may be never. As a store-wide scheduling gate
+                // (`Store.tick` refuses; every driver yields at its top) that is a wedge
+                // the moment a second driver exists — it spins at the top of its own
+                // loop and dies at the 10,000-hop assert in ~311ms, an internal-bug
+                // detector firing on a perfectly ordinary suspended guest. Two concurrent
+                // export calls with one slow suspending import were enough; the reported
+                // shape was a detached guest task cancelling an in-flight import, which
+                // parks mid-frame with no export call outstanding and leaves the
+                // settlement pump holding this entry.
+                //
+                // What the entry protects — "the engine may run `chosen`'s wasm during
+                // this await" — it protects by refusing OTHER `Store.tick` callers, and
+                // this loop is not one of them while it awaits. The tick callers that
+                // can reach a store mid-race are another `driveAsync` loop and
+                // `HostActivity.pump`'s synchronous drain (exec/host_streams.ts) — the
+                // latter is not gated by driver depth, so scoping the entry to "sole
+                // driver" does hand it a window an unscoped entry would close at
+                // depth >= 2.
+                // What holds regardless is the invariant the `driverDepth` note names:
+                // a genuine resumption is preceded by `SuspensionPoint.resume`'s OWN
+                // entry (jspi/bridge.ts, minted before the settle), and every
+                // resumption site here re-checks membership and promise identity
+                // synchronously — mechanisms (a) and (b), which is where that note
+                // already puts the weight.
+                const sole = storeDriverDepth(store) === 1;
+                if (sole)
+                    store.addPendingResumption(chosen);
                 let winner;
                 try {
-                    winner = await Promise.race([chosenTag, ...others]);
+                    // `armDriverArrival` rides the race for every driver, not just the one
+                    // holding the entry: waking on a new arrival is also how a fallback
+                    // pump reaches its next `done()` — i.e. its stand-down — promptly.
+                    winner = await Promise.race([
+                        chosenTag,
+                        ...others,
+                        armDriverArrival(store),
+                    ]);
                 }
                 finally {
-                    store.removePendingResumption(chosen);
+                    if (sole)
+                        store.removePendingResumption(chosen);
                 }
                 // Resume whichever thread actually settled -- not necessarily the one we
                 // claimed. Resuming only the claimed thread would spin: its promise may
@@ -884,13 +981,7 @@ async function driveAsync(store, done, what) {
                 // true again but the tag's value belongs to a settlement this thread
                 // has already consumed. Compare promise identity too.
                 if (winner !== null && store.awaiting.has(winner.t) &&
-                    winner.t.awaiting === winner.p &&
-                    // Dispatch guard, the same predicate `Store.serviceSettled` uses
-                    // (issue #156): never resume into an instance that is not
-                    // host-enterable. The entry is (also) queued in `store.settled` by
-                    // `noteAwaiting`'s continuation, and `serviceSettled` owns it once
-                    // the lock releases.
-                    dispatchableTail(winner.t)) {
+                    winner.t.awaiting === winner.p) {
                     winner.t.resumeWith(winner.value, winner.failure);
                 }
                 continue;
@@ -906,7 +997,18 @@ async function driveAsync(store, done, what) {
             // not ours — this is genuine, unavoidable nondeterminism at the boundary
             // (the reference has the same freedom in `Store.tick`). Everything
             // *inside* the component stays deterministic per scheduler.ts.
-            await Promise.race([...store.pendingHostCalls]).catch(() => { });
+            //
+            // The driver-arrival one-shot rides here too. This is the routine park of
+            // a quiet guest with a real host call outstanding — no speculative entry
+            // is held, so there is no wedge to break, but a fallback pump parked here
+            // would otherwise not reach its `done()` (i.e. its stand-down) until the
+            // HOST answered, leaving two loops interleaving `serviceSettled`/`tick`
+            // for that whole window. That interleaving is what the `driverDepth` note
+            // above calls out as bad for throughput and blame.
+            await Promise.race([
+                ...store.pendingHostCalls,
+                armDriverArrival(store),
+            ]).catch(() => { });
         }
     }
     finally {
@@ -945,26 +1047,35 @@ function takeHostFailure(store) {
  *     needs genuine wasm-frame suspension: `needsJspi`, at the precise point.
  */
 /**
- * The plain-entered variant of a `[constructor]` export in jspi mode,
- * attached to the promising-wrapped lifted function under this symbol.
+ * The plain-entered variant of a **sync-typed** lifted export in jspi mode,
+ * attached to the promising-wrapped lifted function under this symbol
+ * (contracts/embedder-api.md §"Functions and async", §"Functions and async").
+ *
+ * In jspi mode every promising-wrapped entry returns a Promise even when the
+ * activation completes without suspending (jspi pin (e)). Some host contexts
+ * cannot use a Promise no matter how promptly it resolves, so each sync-typed
+ * export carries a second lifted function whose ENTRY is plain (unwrapped):
+ * a guest activation that completes synchronously — the overwhelmingly common
+ * case for sync-typed WIT — delivers its results synchronously through it.
  *
- * A WIT constructor is surfaced as a JS class constructor
- * (contracts/embedder-api.md §"Resources"), and a JS constructor cannot
- * await — but in jspi mode every promising-wrapped entry returns a Promise
- * even when the activation completes without suspending (jspi pin (e)). So
- * constructor exports carry a second lifted function whose ENTRY is plain
- * (unwrapped): a constructor that completes synchronously — the
- * overwhelmingly common case; WIT constructors are always sync-typed —
- * returns its rep synchronously through it.
+ * Two consumers, one mechanism:
  *
- * The cost is confined to genuinely-suspending constructors, which no JS
- * host can surface as `new` anyway: a blocking built-in reached through the
- * plain entry signals `NeedsJspi` (a capability error, instance left
- * enterable), and a Suspending-wrapped host import reached from the
- * unwrapped frame fails as a trap. Both name the constructor rather than
- * silently deadlocking.
+ *  * **resource constructors** — a WIT constructor is surfaced as a JS class
+ *    constructor (§"Resources") and a JS constructor cannot await, so the
+ *    embedder layer reads this symbol unconditionally for `[constructor]`
+ *    exports;
+ *  * **the embedder `sync()` adapter** — the explicit per-use
+ *    synchronous view of any sync-typed export.
+ *
+ * The cost is confined to genuinely-suspending activations: a blocking
+ * built-in reached through the plain entry signals `NeedsJspi` (a capability
+ * error, instance left enterable), and a `Suspending`-wrapped host import
+ * reached from the unwrapped frame fails as a trap. Both name the export
+ * rather than silently deadlocking. A call made while the instance has
+ * hop-parked activations refuses with `SyncEntryBusy` before entering
+ * (`refuseOnEntryHops` below).
  */
-export const CONSTRUCTOR_SYNC_ENTRY = Symbol("polyengine.constructorSyncEntry");
+export const SYNC_ENTRY = Symbol("polyengine.syncEntry");
 export function createLiftedFunction(input) {
     const { name, ft, opts, core, stats, trapState, syncCallStack, allInstances, } = input;
     const inst = opts.instance;
@@ -1002,19 +1113,16 @@ export function createLiftedFunction(input) {
             trapState.pending = undefined;
         // Depth of the sync-call scope stack on entry; see the `finally` below.
         const syncCallDepth = syncCallStack?.length ?? 0;
-        // Reference `Store.lift` (line 578): the host is the caller, so the
-        // entering set is the callee's `self_and_ancestors()`.
-        // On refusal, distinguish the corpse from the crowd: a poisoned
-        // instance's refusal names the original trap (polyengine#145 ask 1).
-        if (!inst.mayEnterFrom(null)) {
-            trap(withPoisonCause(inst, `cannot enter component instance ${inst.index} (reentrance forbidden)`));
+        // Reference `Store.lift` (@ 2f13265) runs `canon_lift` with NO gate
+        // (CM#705), so host entry into a live instance is valid. What this adds
+        // is polyengine's per-instance
+        // poisoning divergence — a poisoned instance is a corpse, and its refusal
+        // names the original trap (polyengine#145 ask 1).
+        {
+            const refusal = entryRefusal(inst, null, `cannot enter component instance ${inst.index}`);
+            if (refusal !== null)
+                trap(refusal);
         }
-        // The set this entry locked (definitions.py `ComponentInstance.enter_from`
-        // iterates `entering_set`). Remembered so a trap can leave exactly these
-        // locked and no others.
-        const enteredSet = inst.enteringSet(null);
-        inst.enterFrom(null);
-        let entered = true;
         let completed = false;
         let resolved = null;
         let resolvedSeen = false;
@@ -1080,44 +1188,30 @@ export function createLiftedFunction(input) {
             // definition; assert that resting state rather than leaving the
             // component bricked.
             //
-            // The *entered* instances are excluded: they are poisoned by this trap
-            // (see `poison` below) and must stay exactly as the trap left them.
-            // Restoring their `may_leave` would be tidying the state of an instance
-            // that is no longer allowed to run at all.
+            // The ENTERED instance is excluded: it is poisoned by this trap (see
+            // `poison` below) and must stay exactly as the trap left it. Restoring
+            // its `may_leave` would be tidying the state of an instance that is no
+            // longer allowed to run at all.
             for (const i of allInstances?.() ?? []) {
-                if (!enteredSet.has(i)) {
+                if (i !== inst) {
                     i.mayLeave = true;
                 }
             }
         };
-        const leave = () => {
-            if (!entered)
-                return;
-            entered = false;
-            inst.leaveTo(null);
-        };
         /**
-         * A trap escaped the task: **do not** release the reentrance lock.
-         *
-         * definitions.py `Store.lift` (line 578) is
-         *
-         * ```python
-         * trap_if(not inst.may_enter_from(caller))
-         * inst.enter_from(caller)
-         * on_cancel = canon_lift(...)     # <-- a Trap propagates out of here
-         * inst.leave_to(caller)           # <-- and so this never runs
-         * ```
+         * A trap escaped the task: mark the instance poisoned.
          *
-         * so a trapping task leaves every instance it entered with
-         * `may_enter == False` permanently. That is the Component Model's
-         * "poisoning": a component that trapped is not in a known state, so it may
-         * never be entered again, and the next call reports `cannot enter
-         * component instance`. `test/async/builtin-trap-poisons-instance.wast`
-         * asserts exactly this, twice.
+         * polyengine's NAMED DIVERGENCE. definitions.py has no notion of a
+         * post-trap instance at all — a Trap is the end of the world — and
+         * wasmtime's answer is to poison the whole store. This runtime keeps the
+         * component graph alive and buries only the instance that trapped: it is
+         * not in a known state, so it may never be entered again, and the next
+         * call reports `cannot enter component instance` with the recorded cause
+         * appended (polyengine#145 ask 1).
+         * `test/async/builtin-trap-poisons-instance.wast` asserts exactly this,
+         * twice; the marker (`notifyInstancePoisoned`) is the whole mechanism.
          *
-         * Only the entered set is affected; sibling instances stay usable, which
-         * is why the lock is released per-instance rather than by poisoning a
-         * whole store the way wasmtime does.
+         * Only `inst` is affected; sibling instances stay usable.
          *
          * Poisoned instances can never rendezvous again, so their handle tables'
          * live stream/future ends are retired here (#66): parked host operations
@@ -1125,21 +1219,10 @@ export function createLiftedFunction(input) {
          * lets the embedder layer reject them loudly.
          */
         const poison = (e) => {
-            entered = false; // consumed: the lock is now permanent
-            // ...for the leaf. The synthetic per-instantiation root (plan v3
-            // amendment 4) is in `enteredSet` too, and leaving IT locked would
-            // poison every instance of the component — exactly the store-wide
-            // behaviour the paragraph above says this runtime deliberately does not
-            // have. Released; see `releaseSyntheticRootOnPoison` in task/mod.ts.
-            inst.releaseSyntheticRootOnPoison();
             // Through the seam (not retireInstanceAsyncEnds directly) so the
             // poison marker is recorded too — `Thread.resumeWith` retires this
             // instance's late settles against it instead of assert-cascading.
-            for (const i of enteredSet) {
-                if (i.isSyntheticRoot)
-                    continue;
-                notifyInstancePoisoned(i, e);
-            }
+            notifyInstancePoisoned(inst, e);
         };
         /**
          * Is `e` a *capability* signal rather than a genuine trap?
@@ -1148,9 +1231,9 @@ export function createLiftedFunction(input) {
          * not "the component faulted". Poisoning on them is wrong on the
          * reference's own terms: the operation they stand in for — a synchronous
          * stream copy, `waitable-set.wait`, a blocking cross-component call —
-         * *blocks and then completes* in definitions.py. `Store.lift` reaches
-         * `leave_to` in every one of those executions, so the instance stays
-         * enterable. Poisoning would attribute a permanent fault to a component
+         * *blocks and then completes* in definitions.py. Every one of those
+         * executions returns normally there, so the instance stays healthy.
+         * Poisoning would attribute a permanent fault to a component
          * that, on a complete runtime, is perfectly healthy — and it cascades:
          * one unsupported operation made every later call on that instance report
          * `cannot enter component instance`, which is neither our real behaviour
@@ -1158,8 +1241,6 @@ export function createLiftedFunction(input) {
          *
          * What unwinding must still do on this path, and what it must not:
          *
-         *  - MUST release the reentrance lock (`leave`) — the call is over and no
-         *    activation of this instance survives it.
          *  - MUST unwind the FACT sync-call scopes and restore `may_leave`
          *    (`unwind`), for exactly the reasons it does after a trap: a bail-out
          *    mid-adapter skips `exit-sync-call` and the `may_leave` restore, and
@@ -1203,17 +1284,10 @@ export function createLiftedFunction(input) {
         }
         catch (e) {
             unwind();
-            if (isCapabilitySignal(e))
-                leave();
-            else
+            if (!isCapabilitySignal(e))
                 poison(e);
             throw e;
         }
-        // The reentrance gate is released here, before the store is pumped:
-        // `Store.tick` re-enters each waiting thread's instance itself
-        // (`enter_from(None)` / `leave_to(None)`), exactly as in the reference,
-        // where `lift_and_run` ticks after `store.invoke` has returned.
-        leave();
         let pending;
         try {
             // Completion is "the task resolved AND its threads have drained", not
@@ -1229,7 +1303,7 @@ export function createLiftedFunction(input) {
             // abandoned mid-loop — leaking the exclusive thread and its table slot.
             // The lifted call is over when the task has resolved AND this task's
             // activation is no longer mid-wasm-call. Those are two different events
-            // and both matter (M2 phase 3e):
+            // and both matter:
             //
             //   * "task resolved" alone abandons a still-running activation. Under
             //     JSPI the guest calls `task.return` while suspended, so returning
@@ -1268,6 +1342,14 @@ export function createLiftedFunction(input) {
         });
     };
     return (...hostArgs) => {
+        // sync() arm 2: the synchronous variant refuses rather than deferring, and
+        // does so FIRST — before the arity check's sibling logic reaches
+        // `invokeNow` — because the refusal must be pre-enter to stay
+        // non-poisoning. See `refuseOnEntryHops` above for why the mode-keyed
+        // gate below cannot cover this variant.
+        if (input.refuseOnEntryHops && entryHopThreads(store, inst).length > 0) {
+            throw new SyncEntryBusy(name);
+        }
         if (hostArgs.length !== ft.params.length) {
             throw new TypeError(`${name}: expected ${ft.params.length} argument(s), got ${hostArgs.length}`);
         }
@@ -1275,11 +1357,10 @@ export function createLiftedFunction(input) {
         //
         // A promising-wrapped entry settles a microtask AFTER the guest's core
         // call returns, even when nothing suspended (jspi pin (j)) — so there
-        // is a hop between core return and the host-side result LIFT, and the
-        // reentrance bracket has already been released by then (`leave()` runs
-        // when the first segment parks). In the reference no such window
-        // exists: `canon_lift` for sync options runs core + lift atomically
-        // inside one entered bracket. Admitting another host call into the
+        // is a hop between core return and the host-side result LIFT, with
+        // nothing holding the instance against another host entry. In the
+        // reference no such window exists: `canon_lift` for sync options runs
+        // core + lift atomically. Admitting another host call into the
         // window lets a full guest turn mutate the memory the pending lift
         // will read — observed as `Trap: list too long` lifting the wosh
         // engine's `tick` (`list<list<u8>>`) after a concurrent `feed-keys`
@@ -1381,27 +1462,13 @@ function dtorOptions(instance) {
  *   callee = inst.store.lift(dtor, ft, opts, rt.impl)
  * ```
  *
- * Before #160 the host-initiated path (embedder `drop()`, the GC backstop,
- * `dropOwn`) hand-rolled the bracket in cabi/handles.ts `callDtorGated`: a
- * bare call to the dtor with `enterFrom(null)` HELD across the returned
- * promise. Three defects followed from having no Task/Thread behind the
- * activation:
- *
- *  - **#160 itself**: the held bracket left the impl instance non-enterable,
- *    so `Store.tick`'s enterability filter (#155) could never resume a
- *    suspension point belonging to the dtor's own activation. The completion
- *    promise sat in `pendingHostCalls` looking like external work, and every
- *    driver parked on it forever.
- *  - it was the runtime's only `enterFrom(null)` bracket spanning an await —
- *    the macro-scale reachability window of the #156 class, through which a
- *    sibling instance looked non-enterable from the synthetic root.
- *  - built-ins reached inside the dtor had no ambient task (`currentTask()`
- *    → `PendingCapability`, or a foreign-task misattribution, the #24 class).
- *
- * Under the lift harness all three go away structurally: the activation has a
- * real `Task` + implicit `Thread`, the entry bracket is released when the
- * first segment parks (`leave()` before `drive`), and settled tails flow
- * through `serviceSettled` like any other lifted sync call.
+ * The host-initiated paths (embedder `drop()`, the GC backstop, `dropOwn`)
+ * route through this harness rather than calling the dtor bare, because the
+ * activation then has a real `Task` + implicit `Thread`: built-ins reached
+ * inside the dtor are well-attributed (a bare call leaves `currentTask()`
+ * with no ambient task — `PendingCapability`, or a foreign-task
+ * misattribution, the #24 class), and settled tails flow through
+ * `serviceSettled` like any other lifted sync call.
  *
  * The returned function takes the rep and returns either `undefined` (the
  * activation completed synchronously — the overwhelmingly common case) or a
@@ -1487,7 +1554,7 @@ export function hostDtorCall(rt, rep) {
  * This is the whole of the jspi entry seam. In **plain** mode the entry is not
  * `promising`-wrapped, `callCore` returns core values, and this returns them
  * without yielding — no await, no Promise allocation, the identical
- * synchronous path M1 shipped. In **jspi** mode the entry *is* wrapped, so the
+ * synchronous path plain mode always used. In **jspi** mode the entry *is* wrapped, so the
  * call returns a Promise (jspi pin (e)) and we park the thread on it via the
  * `awaitValue` block request; the driving loop resumes us with the values, or
  * throws the rejection in (a post-resume trap).
@@ -1626,7 +1693,7 @@ function* liftBody(input) {
  *     (`thread.wait_until(subtask.resolved)`, line 2286), so: `needsJspi`.
  */
 export function createLoweredImport(input) {
-    const { name, ft, opts, hostFn, stats, mode, suspendable } = input;
+    const { name, ft, opts, hostFn, stats, mode, suspendable, deferCancel, abortable, } = input;
     const inst = opts.instance;
     const store = inst.store;
     const computed = flattenFunctype(cabiOptions(opts), ft, "lower");
@@ -1677,22 +1744,42 @@ export function createLoweredImport(input) {
         // definitions.py assigns the callee's `OnCancel` here:
         //   `subtask.on_cancel = callee(on_start, on_resolve, caller = ...)`
         //
-        // A host import is a plain JS function and offers no cancellation
-        // channel — there is nothing to forward a request to. The faithful model
-        // is therefore a handler that *accepts and ignores* the request, which is
-        // exactly what the reference permits: `canon_subtask_cancel` (line 2469)
-        // calls `on_cancel` and then re-checks `subtask.resolved()`; a callee that
-        // declines to cancel promptly leaves the subtask unresolved, and the async
-        // form returns BLOCKED while the sync form waits. The subtask still
-        // resolves normally when the promise settles — cancellation is a request,
-        // not a guarantee.
+        // The `OnCancel` is the CALLEE's to supply: `Store.invoke` takes it back
+        // from the callee it invoked (`on_cancel = f(on_start, on_resolve, caller
+        // = None)`, definitions.py line 572), i.e. the reference expects the
+        // embedding to hand back the cancellation behaviour of whatever it is
+        // hosting. A wasmtime host gets a real one for free — dropping a Rust
+        // future IS cancellation. A JS Promise has no such channel, so polyengine
+        // answers on the host's behalf; §"Functions and async" makes the DEFAULT answer the
+        // reference's prompt-cancel host (`on_cancel = () => on_resolve(None)`),
+        // installed by the async arm below.
+        //
+        // The no-op assigned HERE is only the placeholder for paths where
+        // `subtask.cancel` is unreachable, so no answer can ever be demanded of
+        // it: an eagerly-resolving callee never mints a subtask handle (the
+        // fast-path return below is a bare state), and a sync-typed import's suspending mark
+        // park never mints one either. It is also the FINAL handler for a
+        // `deferCancel()`-branded import — accept and ignore, the pre-cancellation discard
+        // behaviour, now per-declaration.
         //
         // Leaving `on_cancel` null instead made a *legal* `subtask.cancel` crash
         // with an internal AssertionError, which is neither reference behaviour
         // nor a sanctioned incompleteness signal.
         subtask.onCancel = () => { };
+        // abortable() (contracts/embedder-api.md §"Functions and async"): a marked import
+        // is handed a fresh `AbortSignal` after its WIT-declared parameters. The
+        // mark controls the SIGNATURE UNCONDITIONALLY — a marked function receives
+        // a signal on every call, including the paths where it can never fire
+        // (sync-typed, eager resolve, `deferCancel`) — so the host's arity is a
+        // property of its declaration, not of how a particular call happened to
+        // go. `new AbortController()` is evaluated only for marked imports, which
+        // keeps bare engine shells with no `AbortController` off this path for the
+        // whole unmarked corpus.
+        const controller = abortable ? new AbortController() : null;
         const args = onStart();
-        const raw = hostFn(...args);
+        const raw = controller === null
+            ? hostFn(...args)
+            : hostFn(...args, controller.signal);
         const toResults = (v) => ft.results.length === 0 ? [] : [v];
         if (isPromiseLike(raw)) {
             if (!opts.async) {
@@ -1703,8 +1790,9 @@ export function createLoweredImport(input) {
                     // Suspending wrap is applied per-declaration (`importValue`), so an
                     // unmarked import physically cannot suspend, whatever the mode.
                     //
-                    // A capability signal is expressly NON-poisoning (amendment 2, #91
-                    // scope clarification): the caller keeps running, so the borrows
+                    // A capability signal is expressly NON-poisoning (the
+                    // trap-unwind/lender-release obligation, contracts/intrinsics.md §A):
+                    // the caller keeps running, so the borrows
                     // `onStart` lifted into this subtask must be discharged here or
                     // its lenders stay elevated forever and later `resource.drop`s
                     // trap "handle still lent out" on a healthy instance (found
@@ -1720,7 +1808,7 @@ export function createLoweredImport(input) {
                             `only park the frame when declared with suspending() ` +
                             `(contracts/embedder-api.md §"Functions and async")`);
                 }
-                // The park (A1): the reference's plain, NON-cancellable wait — a
+                // The park: the reference's plain, NON-cancellable wait — a
                 // cancel request against the caller stays pending-cancel and is
                 // delivered at its next cancellable wait, exactly as for any other
                 // mid-frame block. The instance-entry gate stays HELD across the park
@@ -1764,8 +1852,8 @@ export function createLoweredImport(input) {
                 //  * produce SUCCESS   -> `onResolve` + `deliverResolve` release the
                 //    lenders; the `onSettled` backstop below observes
                 //    `resolveDelivered()` and is a no-op.
-                //  * produce THROW     -> exempt-by-poisoning under amendment 2
-                //    (contracts/intrinsics.md v0.2 §2: release is owed only on exits
+                //  * produce THROW     -> exempt under the trap-unwind/lender-release
+                //    obligation (contracts/intrinsics.md §A: release is owed only on exits
                 //    that do NOT poison the caller). Every rejection that reaches
                 //    this park is a poisoning trap in the CALLER's own frame:
                 //    branded `ComponentException`s on fallible imports were already resolved
@@ -1817,6 +1905,16 @@ export function createLoweredImport(input) {
             }
             const promise = Promise.resolve(raw).then((v) => {
                 store.pendingHostCalls.delete(promise);
+                // cancellation discard: the subtask may already be resolved when the host promise
+                // settles — the discard `onCancel` below resolved it
+                // CANCELLED_BEFORE_RETURNED (the only pre-settle resolver on this
+                // arm). The value has no addressee, and `onResolve` would run
+                // straight into its `state === STARTED` assert ("on_resolve on a
+                // subtask that never started") and park that AssertionError on
+                // `store.hostFailure`, poisoning whatever unrelated embedder call
+                // came next.
+                if (subtask.resolved())
+                    return;
                 try {
                     onResolve(toResults(v));
                 }
@@ -1825,9 +1923,64 @@ export function createLoweredImport(input) {
                 }
             }, (e) => {
                 store.pendingHostCalls.delete(promise);
+                // Same guard, different reason: a rejection of a RENOUNCED call is
+                // not a host failure. The guest cancelled and was told so; surfacing
+                // the rejection would fail an unrelated later call with the error of
+                // an operation nobody is waiting for.
+                if (subtask.resolved())
+                    return;
                 store.hostFailure = e;
             });
             store.pendingHostCalls.add(promise);
+            if (!deferCancel) {
+                // cancellation discard DISCARD (contracts/embedder-api.md §"Functions and async";
+                // polyengine#241) — the reference's prompt-cancel host,
+                // `on_cancel = () => on_resolve(None)` (definitions.py canon_lower's
+                // null branch, line ~2267).
+                //
+                // This runs synchronously inside `canon_subtask_cancel`, which already
+                // set `cancellationRequested` before calling us (the assert in
+                // `onResolve`'s null branch relies on that ordering). `onResolve(null)`
+                // arms the SUBTASK event — a delivery-time thunk — and resolves
+                // CANCELLED_BEFORE_RETURNED, so the built-in's `finish()` tail consumes
+                // the event, `deliverResolve` releases the lenders (the #106 class,
+                // discharged exactly as a RETURNED delivery would), and BOTH cancel
+                // forms return the state without blocking. The null path lowers
+                // nothing, so there is no realloc re-entry from inside a built-in.
+                //
+                // The renounced call can no longer wake the guest, so it must stop
+                // counting as externally-wakeable for the driver's deadlock probe:
+                // deregister it NOW. (The settle continuation above also deletes;
+                // `Set.delete` is idempotent.)
+                subtask.onCancel = () => {
+                    store.pendingHostCalls.delete(promise);
+                    onResolve(null);
+                    if (controller !== null) {
+                        // abortable(): tell the host its result was discarded, so it can stop the
+                        // underlying operation — clear a timer, abort a fetch, close a
+                        // dial. Reachable only from this arm by construction: a
+                        // `deferCancel()` import never discards, so its signal never
+                        // fires.
+                        //
+                        // Deferred one microtask. This closure runs SYNCHRONOUSLY inside
+                        // `canon_subtask_cancel`, i.e. inside a live guest activation, and
+                        // host abort listeners must not execute there — that is the
+                        // issue-#24 attribution class, plus arbitrary re-entrancy into a
+                        // guest mid-built-in. `Promise.resolve().then`, not
+                        // `queueMicrotask`: the latter does not exist in bare engine
+                        // shells (see jspi/bridge.ts's SENTINEL_TICK note).
+                        //
+                        // The resulting order is: the guest observes
+                        // CANCELLED_BEFORE_RETURNED first, the host observes the abort a
+                        // tick later. Any settlement the abort provokes (typically an
+                        // `AbortError` rejection) arrives at the settle continuation above
+                        // with the subtask already resolved, so it lands on the cancellation discard
+                        // resolved-subtask guards and is discarded like any other late
+                        // settlement — never a `store.hostFailure`.
+                        Promise.resolve().then(() => controller.abort());
+                    }
+                };
+            }
         }
         else {
             onResolve(toResults(raw));