@polyengine/runtime 0.5.1 → 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
@@ -680,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
@@ -742,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.
             //
@@ -805,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
@@ -855,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
@@ -874,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,
@@ -882,12 +883,12 @@ 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, plus the
-                    // driver-arrival one-shot: every park in this loop races it, so the
-                    // stand-down below is prompt wherever we happen to be waiting.
+                    // 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,
@@ -917,11 +918,11 @@ 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.
+                // 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
@@ -941,13 +942,14 @@ async function driveAsync(store, done, what) {
                 // 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 the entry used to close at depth >= 2.
+                // 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, promise identity and
-                // `dispatchableTail` synchronously — mechanisms (a) and (b), which is
-                // where that note already puts the weight.
+                // 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);
@@ -979,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;
@@ -1051,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").
  *
- * 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.
+ * 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.
  *
- * 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.
+ * Two consumers, one mechanism:
+ *
+ *  * **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;
@@ -1108,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;
@@ -1186,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
@@ -1231,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?
@@ -1254,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
@@ -1264,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
@@ -1309,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
@@ -1335,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
@@ -1374,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}`);
         }
@@ -1381,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`
@@ -1487,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
@@ -1593,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).
@@ -1789,23 +1750,23 @@ export function createLoweredImport(input) {
         // 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; amendment A23 makes the DEFAULT answer the
+        // 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 A1
+        // 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-A23
+        // `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 = () => { };
-        // A24 (contracts/embedder-api.md §"Functions and async"): a marked import
+        // 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
@@ -1829,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
@@ -1846,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
@@ -1890,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
@@ -1943,7 +1905,7 @@ export function createLoweredImport(input) {
             }
             const promise = Promise.resolve(raw).then((v) => {
                 store.pendingHostCalls.delete(promise);
-                // A23: the subtask may already be resolved when the host 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
@@ -1971,7 +1933,7 @@ export function createLoweredImport(input) {
             });
             store.pendingHostCalls.add(promise);
             if (!deferCancel) {
-                // A23 DISCARD (contracts/embedder-api.md §"Functions and async";
+                // 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).
@@ -1994,7 +1956,7 @@ export function createLoweredImport(input) {
                     store.pendingHostCalls.delete(promise);
                     onResolve(null);
                     if (controller !== null) {
-                        // A24: tell the host its result was discarded, so it can stop the
+                        // 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
@@ -2012,7 +1974,7 @@ export function createLoweredImport(input) {
                         // 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 A23
+                        // 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());