@polyengine/runtime 0.5.1 → 0.6.1

package/esm/intrinsics/fact_calls.js

@@ -60,14 +60,15 @@
 //   * Reentrance between *related* instances is resolved statically:
 //     `trampoline.rs:116-127` emits an unconditional
 //     `trap(Trap::CannotEnterComponent)` when the lower and lift instances are
-//     the same or are ancestors of one another. So the flat-instance-tree gap
-//     recorded in task/mod.ts is NOT load-bearing here — wasmtime has already
-//     decided those cases at translation time, and the remaining runtime check
-//     is the ordinary "is the callee instance currently executing" one, which
-//     a flat tree answers correctly.
+//     the same or are ancestors of one another. The runtime-side counterpart
+//     — "is the callee instance currently executing" — does not exist at the
+//     pinned reference (definitions.py @ 2f13265 has no `may_enter`, CM#705),
+//     so the only refusal at these sites is polyengine's poisoned-corpse check
+//     (`entryRefusal`). The flat-instance-tree gap recorded in task/mod.ts is
+//     doubly not load-bearing here.
 import { assert_, trap } from "../cabi/trap.js";
 import { MAX_FLAT_RESULTS } from "../cabi/mod.js";
-import { NeedsJspi, currentTask, maybeCurrentTask, needsJspi, notifyInstancePoisoned, packSubtaskResult, PendingCapability, Subtask, SubtaskState, Task, Thread, withPoisonCause, } from "../task/mod.js";
+import { NeedsJspi, currentTask, maybeCurrentTask, needsJspi, notifyInstancePoisoned, packSubtaskResult, PendingCapability, Subtask, SubtaskState, Task, Thread, entryRefusal, } from "../task/mod.js";
 import { blockCurrentActivation, enterWasm } from "../jspi/mod.js";
 import { awaitCore, callCore, normalizeCoreValues, runCallbackLoop, } from "../exec/boundary.js";
 import { traceCopy } from "./stream_builtins.js";
@@ -203,8 +204,9 @@ function mkCalleeTask(input) {
     // `task_return_type` at all: fact.rs's comment on `PrepareCall.memory` says
     // the same for the memory check).
     // `task_return_type` arrives as wasmtime's *own* `TypeTupleIndex` — a
-    // runtime argument, not a plan field. Plan v3 (contracts/plan-format.md v3
-    // amendment 3) supplies the dictionary for it: every `task-return`
+    // runtime argument, not a plan field. The task-return trampoline's raw
+    // `results` key + interned `resultType` (contracts/plan-format.md schema)
+    // supplies the dictionary for it: every `task-return`
     // trampoline decl carries that raw index alongside its interned
     // `plan.types` entry, so the callee task CAN now carry its declared result
     // types and `canon_task_return`'s `trap_if(result_type != task.ft.result)`
@@ -287,8 +289,8 @@ function mkCalleeTask(input) {
         // entry that owns a FACT sync-call bracket: `enter-sync-call` runs here
         // under this task, and if the callee suspends, the engine resumes it later
         // with no driver. Without the ambient travelling with the activation the
-        // matching `exit-sync-call` had no task in scope at all (traced in M2
-        // phase 3h as `ENTER-SYNC owner=K26` / `EXIT-SYNC owner=EXECUTOR`).
+        // matching `exit-sync-call` had no task in scope at all (traced as
+        // `ENTER-SYNC owner=K26` / `EXIT-SYNC owner=EXECUTOR`).
         //
         // Entries deliberately NOT wrapped: `realloc`, `post-return`, resource
         // destructors and the `[async-start]`/`[async-return]` copy adapters.
@@ -303,7 +305,7 @@ function mkCalleeTask(input) {
         // line 12). This is only coherent together with site 1 below blocking
         // rather than raising `NeedsJspi`, since a promising callee resolves on a
         // later turn by construction.
-        // NOTE (M2 stackful round): this wrap is RIGHT for a callee that blocks and
+        // NOTE: this wrap is RIGHT for a callee that blocks and
         // Wrap ONLY a callee that can actually reach a suspension point.
         //
         // The wrap is required when the callee blocks: without its own `promising`
@@ -452,35 +454,30 @@ export function createSyncStartCall(decl, ctx) {
             },
             lenderScope,
         });
-        // Reference `Store.lift`: the reentrance gate, with the *caller* as the
-        // entering context (definitions.py `entering_set(caller)`).
-        // A poisoned callee's refusal names the original trap (polyengine#145).
-        if (!prepared.calleeInst.mayEnterFrom(prepared.callerInst)) {
-            trap(withPoisonCause(prepared.calleeInst, "cannot enter component instance"));
+        // Reference `Store.lift` (@ 2f13265) has no reentrance gate; the only
+        // refusal left is polyengine's poisoned-corpse check, whose message names
+        // the original trap (polyengine#145).
+        {
+            const refusal = entryRefusal(prepared.calleeInst, prepared.callerInst, "cannot enter component instance");
+            if (refusal !== null)
+                trap(refusal);
         }
-        prepared.calleeInst.enterFrom(prepared.callerInst);
-        let ok = false;
         try {
             const thread = spawn(task, body);
             thread.resume();
-            ok = true;
         }
         catch (e) {
-            // A trap leaves the instance poisoned: `leave_to` is not reached
-            // (definitions.py `Store.lift`, line 578). A *capability signal* does
-            // not — see the `isCapabilitySignal` note in exec/boundary.ts.
-            if (e instanceof NeedsJspi || e instanceof PendingCapability) {
-                prepared.calleeInst.leaveTo(prepared.callerInst);
-            }
-            else {
-                // Retire the poisoned CALLEE's stream/future ends (#66): this is a
-                // bracket-break site like `Store.tick`'s, and the trap unwinds to a
-                // hooked site that walks only the CALLER's chain — a composed
-                // component's callee would otherwise strand its host peers.
+            // A trap poisons the callee instance. A *capability signal* does not —
+            // see the `isCapabilitySignal` note in exec/boundary.ts.
+            if (!(e instanceof NeedsJspi) && !(e instanceof PendingCapability)) {
+                // Retire the poisoned CALLEE's stream/future ends (#66): the trap
+                // unwinds to a hooked site that walks only the CALLER's chain — a
+                // composed component's callee would otherwise strand its host peers.
                 notifyInstancePoisoned(prepared.calleeInst, e);
             }
             // The lent handles are the CALLER's, and the caller is not poisoned by
-            // either exit (contracts/intrinsics.md v0.2 amendment 2: this runtime
+            // either exit (contracts/intrinsics.md §A's trap-unwind/lender-release
+            // obligation: this runtime
             // deliberately supports post-trap re-entry on the caller side, where
             // the reference kills the whole store, so the sync-call scopes it
             // skipped have to be unwound explicitly). Leaving `numLends` elevated
@@ -490,8 +487,6 @@ export function createSyncStartCall(decl, ctx) {
             lenderScope.releaseLenders();
             throw e;
         }
-        if (ok)
-            prepared.calleeInst.leaveTo(prepared.callerInst);
         if (callerResults === null) {
             // The callee did not resolve within its first activation. definitions.py
             // `canon_lower`'s sync path blocks here — `thread.wait_until(
@@ -550,7 +545,7 @@ export function createSyncStartCall(decl, ctx) {
                 //     sits in `store.waiting`, e.g. the caller's whole host call was
                 //     abandoned). No JS runs, so nothing can release; the lent
                 //     handles die with the store, which is the reference's own
-                //     outcome. Out of scope for amendment 2 (no non-poisoning exit).
+                //     outcome. Out of scope for the trap-unwind/lender-release obligation (no non-poisoning exit).
                 //  6. Trap-poisoning of the parked instance: does not settle this
                 //     point by itself — it reaches the guest either as (2) (a
                 //     produce-time trap) or as (4) (teardown abandons the park), so
@@ -679,25 +674,20 @@ export function createAsyncStartCall(decl, ctx) {
         subtask.onCancel = (callerInst) => task.requestCancellation(callerInst);
         subtask.calleeTask = task;
         // A poisoned callee's refusal names the original trap (polyengine#145).
-        if (!prepared.calleeInst.mayEnterFrom(prepared.callerInst)) {
-            trap(withPoisonCause(prepared.calleeInst, "cannot enter component instance"));
+        {
+            const refusal = entryRefusal(prepared.calleeInst, prepared.callerInst, "cannot enter component instance");
+            if (refusal !== null)
+                trap(refusal);
         }
-        prepared.calleeInst.enterFrom(prepared.callerInst);
-        let ok = false;
         let thread;
         try {
             thread = spawn(task, body);
             thread.resume();
-            ok = true;
         }
         catch (e) {
             // See the sync form above and `isCapabilitySignal` in exec/boundary.ts.
-            if (e instanceof NeedsJspi || e instanceof PendingCapability) {
-                prepared.calleeInst.leaveTo(prepared.callerInst);
-            }
-            else {
-                // Bracket-break site — retire the poisoned callee's ends (#66),
-                // as in the sync form above.
+            if (!(e instanceof NeedsJspi) && !(e instanceof PendingCapability)) {
+                // Retire the poisoned callee's ends (#66), as in the sync form above.
                 notifyInstancePoisoned(prepared.calleeInst, e);
             }
             // The subtask never reached `report()`, so it has no handle in the
@@ -710,8 +700,6 @@ export function createAsyncStartCall(decl, ctx) {
             unwindSubtaskLenders(subtask);
             throw e;
         }
-        if (ok)
-            prepared.calleeInst.leaveTo(prepared.callerInst);
         const report = () => {
             if (subtask.resolved()) {
                 // Eager completion: no handle, no event (definitions.py line 2293).
@@ -729,7 +717,7 @@ export function createAsyncStartCall(decl, ctx) {
         // NO WAIT FOR RESOLUTION HERE, deliberately. An async-lowered caller must
         // not block on its callee's *completion* -- that is the entire point of
         // async lowering: it takes a subtask handle and learns of completion
-        // through events. An earlier attempt (M2 "Fix 1") parked the caller here
+        // through events. An earlier attempt parked the caller here
         // until the callee resolved. It made cross-abi-calls agree in both modes,
         // and it broke the thing it had no business touching: the caller's
         // activation was now suspended, so the sync-lowered parked caller of
@@ -833,7 +821,7 @@ export function createAsyncStartCall(decl, ctx) {
                 // subtask index (it either threw before `handles.add`, or after it
                 // with the index lost), so nothing will ever deliver this subtask's
                 // resolution — exactly the state `unwindSubtaskLenders` exists for
-                // (contracts/intrinsics.md v0.2 amendment 2).
+                // (contracts/intrinsics.md §A's trap-unwind/lender-release obligation).
                 let produced = false;
                 return blockCurrentActivation({
                     store: prepared.callerInst.store,

package/esm/intrinsics/mod.js

@@ -1,23 +1,23 @@
 // Host trampolines (contracts/intrinsics.md §B) and FACT-adapter intrinsic
-// obligations (§A) — the M0 subset, with instantiate-time (never call-time)
-// milestone-aware failures for everything else.
+// obligations (§A) — the core subset, with instantiate-time (never
+// call-time) capability-gated failures for everything else.
 //
-// Implemented in M0:
+// Implemented from the core subset:
 //   lower-import        host function call through descriptor-IR lift/lower
 //   trap                FACT `Trap` import -> ComponentTrap
 //   enter/exit-sync-call  degenerate sync-call bookkeeping (assert-and-count)
 //   resource-new/rep/drop  sync resource paths over cabi handle tables
-//                          (M1 schedule, implemented early: the resources
-//                          fixture references them at instantiation)
+//                          (resources capability, implemented early: the
+//                          resources fixture references them at instantiation)
 //
-// Everything else fails at instantiate time with the milestone at which
-// intrinsics.md §B schedules it — "this component needs the M2 task core"
+// Everything else fails at instantiate time naming the capability that
+// intrinsics.md §B schedules it under — "this component needs the task core"
 // is a feature, not a crash.
 import { canonResourceDrop, canonResourceNew, canonResourceRep, trap, } from "../cabi/mod.js";
 import { ResourceHandle } from "../cabi/handles.js";
 import { trapIf } from "../cabi/trap.js";
 import { assert_ } from "../cabi/trap.js";
-import { maybeCurrentThread, PendingCapability, withPoisonCause } from "../task/mod.js";
+import { dbgId, entryRefusal, maybeCurrentThread } from "../task/mod.js";
 import { UnsupportedFeatureError } from "./errors.js";
 import { createBackpressureDec, createBackpressureInc, createSubtaskCancel, createSubtaskDrop, createTaskCancel, createTaskReturn, createThreadYield, createWaitableJoin, createWaitableSetDrop, createWaitableSetNew, createWaitableSetPoll, createWaitableSetWait, } from "./async_builtins.js";
 import { createAsyncStartCall, createPrepareCall, createSyncStartCall, } from "./fact_calls.js";
@@ -55,21 +55,21 @@ const FACT_TRAP_MESSAGES = {
 /** Ordinal of `Trap::UncaughtException` in wasmtime's trap encoding. */
 const TRAP_UNCAUGHT_EXCEPTION = 49;
 export { UnsupportedFeatureError } from "./errors.js";
-/** Milestone at which each trampoline kind stops instantiate-failing. */
-const TRAMPOLINE_MILESTONE = {
-    "lower-import": "M0",
-    "trap": "M0",
-    "enter-sync-call": "M0",
-    "exit-sync-call": "M0",
-    "resource-new": "M1",
-    "resource-rep": "M1",
-    "resource-drop": "M1",
-    "transcoder": "M1",
-    "resource-transfer-own": "M1",
-    "resource-transfer-borrow": "M1",
+/** Capability at which each trampoline kind stops instantiate-failing. */
+const TRAMPOLINE_CAPABILITY = {
+    "lower-import": "core",
+    "trap": "core",
+    "enter-sync-call": "core",
+    "exit-sync-call": "core",
+    "resource-new": "resources",
+    "resource-rep": "resources",
+    "resource-drop": "resources",
+    "transcoder": "resources",
+    "resource-transfer-own": "resources",
+    "resource-transfer-borrow": "resources",
 };
-function milestoneOf(kind) {
-    return TRAMPOLINE_MILESTONE[kind] ?? "M2";
+function capabilityOf(kind) {
+    return TRAMPOLINE_CAPABILITY[kind] ?? "task-core";
 }
 /**
  * The borrow bookkeeping of one in-flight synchronous cross-component call,
@@ -119,7 +119,7 @@ export class SyncCallScope {
  * unsupported kind fails instantiation, not the first call
  * (plan-format.md "Executor obligations"). Unreferenced trampolines are
  * never created and therefore never fail (intrinsics.md §B tolerates e.g.
- * an unreferenced task-return until M2).
+ * an unreferenced task-return until the task core exists).
  */
 export function createTrampoline(decl, ctx) {
     const fn = createTrampolineBody(decl, ctx);
@@ -139,16 +139,6 @@ export function createTrampoline(decl, ctx) {
         }
     };
 }
-/**
- * A trampoline that instantiates fine but fails at its first call, naming the
- * phase that will implement it. See the CONTRACT note at the stream/future
- * cases for why these are not instantiate-time failures.
- */
-function deferredCapability(kind, capability) {
-    return () => {
-        throw new PendingCapability(`built-in '${kind}' is not implemented yet: ${capability}`);
-    };
-}
 /**
  * The component instance a trampoline is declared in (wasmtime names it in
  * every instance-scoped `Trampoline` variant). This is the static answer to
@@ -180,23 +170,12 @@ const SCOPE_TRACE = (() => {
         return false;
     }
 })();
-const taskIds = new WeakMap();
-let nextTaskId = 1;
-function taskId(t) {
-    if (t === undefined || t === null)
-        return "NONE(->ctx fallback)";
-    let id = taskIds.get(t);
-    if (id === undefined) {
-        id = nextTaskId++;
-        taskIds.set(t, id);
-    }
-    return `T${id}`;
-}
 function syncScopes(ctx, site = "?") {
     const thread = maybeCurrentThread();
     const scopes = thread?.syncCallStack ?? ctx.syncCallStack;
     if (SCOPE_TRACE) {
-        console.error(`[scope] ${site} act=${taskId(thread)} depth=${scopes.length}`);
+        console.error(`[scope] ${site} act=${thread ? dbgId(thread) : "NONE(->ctx fallback)"} ` +
+            `depth=${scopes.length}`);
     }
     return scopes;
 }
@@ -227,8 +206,8 @@ function createTrampolineBody(decl, ctx) {
                     ? `FACT adapter trap (code ${code ?? "?"})`
                     : `wasm trap: ${message}`);
             };
-        // Sync-call task bookkeeping (intrinsics.md §A: "degenerate-case
-        // implementation in M0: assert-and-count"). wasmtime 47 signatures:
+        // Sync-call task bookkeeping (intrinsics.md §A) — assert-and-count.
+        // wasmtime 47 signatures:
         // enter-sync-call carries the caller/callee instance pair, which is what
         // the reentrance gate below needs; balance of the bracket is asserted at
         // component teardown by tests.
@@ -238,72 +217,31 @@ function createTrampolineBody(decl, ctx) {
         //   async.exit-sync-call() -> ()
         case "enter-sync-call":
             return (callerInstance, async_, calleeInstance) => {
-                // Reference reentrance gate. Every guest->guest call in
-                // definitions.py routes through the callee's lift wrapper:
-                //   canon_lower (line 2312) calls
-                //     `callee(on_start, on_resolve, caller = thread.task.inst)`,
-                //   and `callee` is `Store.lift`'s `func_inst` (lines 578-585), whose
-                //   first act is
-                //     `trap_if(not inst.may_enter_from(caller))`   (line 581)
-                //   with `entering_set(caller) = callee.self_and_ancestors()
-                //                                - caller.self_and_ancestors()`
-                //   (lines 230-234).
-                // A sync fused adapter is an *optimization* of that path, so the gate
-                // belongs here (issue #99).
-                //
-                // Note on the shape of the entering set, which is what makes this
-                // check safe for the legal shapes:
-                //   * caller == callee, or either an ancestor of the other -> the
-                //     entering set is empty and this never traps. Those pairs never
-                //     reach this trampoline anyway: FACT emits an unconditional
-                //     `CannotEnterComponent` trap for them at compile time
-                //     (wasmtime-environ 47.0.3 `fact/trampoline.rs:120-127`), which
-                //     is what `test/async/trap-on-reenter.wast` cases 2 and 3 pin.
-                //   * an *idle* sibling -> `mayEnter` is true, no trap. This is what
-                //     `test/async/sync-barges-in.wast` needs: an async callee that is
-                //     merely blocked has already run `leave_to` (its `canon_lift`
-                //     returned), so a sync sibling may barge in.
-                //   * an *entered* sibling -> trap, which is the A -> C -> A cycle.
+                // ENTRY REFUSAL at the fused sync-call boundary.
                 //
-                // CONTRACT / reachability: a pure guest-to-guest sibling cycle is
-                // unreachable by construction, because component instance imports
-                // form a DAG (a callee must be instantiated before its caller, so it
-                // cannot hold an import of its caller; `wasm-tools` rejects the
-                // mutual-import composition outright). wasmtime relies on exactly
-                // that to elide the runtime check in fused adapters -- see the
-                // comment in `may_enter`, wasmtime 47.0.3
-                // `runtime/component/concurrent.rs:1876-1886`, and
-                // `enter_guest_sync_call` (concurrent.rs:1723) which performs no
-                // reentrance check at all. The gate is kept anyway because the
-                // reference mandates it and no corpus test pins the permissive
-                // behaviour; it is cheap, and it is the honest place for the
-                // invariant to be asserted rather than assumed.
+                // The reference has no reentrance gate (CM#705; definitions.py @
+                // 2f13265 has no `may_enter`/`entering_set`/`enter_from`): a
+                // guest->guest call through `Store.lift` runs `canon_lift`
+                // unconditionally, and host-mediated reentrance — host -> A.f -> C.g
+                // -> host import -> host invokes C.g — is simply valid. wasmtime's
+                // fused adapters agreed all along: `enter_guest_sync_call`
+                // (47.0.3 `runtime/component/concurrent.rs:1723`) performs no
+                // reentrance check, and `fact/trampoline.rs:120-127` decides the
+                // caller==callee / ancestor pairs statically at compile time (what
+                // `test/async/trap-on-reenter.wast` cases 2 and 3 pin — a translation
+                // -time trap, not this site).
                 //
-                // Deliberately *not* done here: `enter_from` / `leave_to` around the
-                // bracket. The reference locks the callee for the duration, which
-                // would additionally trap host-mediated reentrance (host -> A.f ->
-                // C.g -> host import -> host invokes C.g).
-                //
-                // ADJUDICATED 2026-08-20 (polyengine#165; named divergence in
-                // docs/architecture.md section 6): accepted — the bracket stays
-                // omitted. Three grounds: wasmtime parity (`enter_guest_sync_call`
-                // checks nothing); taking the bracket would create a guest-to-guest
-                // lock spanning suspension points, reintroducing the await-spanning
-                // -lock class removed by #156/#160; and upstream is deleting the
-                // trap outright — CM PR #705 ("CABI: remove the may_enter
-                // flag/trap") makes previously-trapping reentrance valid, so this
-                // divergence is a trailing indicator of the removal and
-                // self-resolves at the submodule pin advance (migration map:
-                // polyengine#173). Until that pin advance the reference's checks polyengine
-                // DOES enforce stay in force.
+                // What this site does check is polyengine's per-instance poisoning: a
+                // callee that trapped is a corpse and may never be entered again,
+                // and the refusal names the original trap (polyengine#145). That is
+                // the whole content of this check.
                 if (typeof callerInstance === "number" &&
                     typeof calleeInstance === "number") {
                     const callerInst = ctx.componentInstance(callerInstance >>> 0);
                     const calleeInst = ctx.componentInstance(calleeInstance >>> 0);
-                    // A poisoned callee's refusal names the original trap (polyengine#145).
-                    if (!calleeInst.mayEnterFrom(callerInst)) {
-                        trap(withPoisonCause(calleeInst, "cannot enter component instance"));
-                    }
+                    const refusal = entryRefusal(calleeInst, callerInst, "cannot enter component instance");
+                    if (refusal !== null)
+                        trap(refusal);
                 }
                 // `async_` records whether the callee is *async-lifted*. wasmtime
                 // stores it on the guest task it creates here
@@ -374,7 +312,7 @@ function createTrampolineBody(decl, ctx) {
         // `lift_own`/`lower_own` and `lift_borrow`/`lower_borrow`
         // (definitions.py) with the src/dst tables named by index rather than
         // implied by the running instance.
-        // FACT string transcoders (contracts/intrinsics.md §B "M1"). The plan
+        // FACT string transcoders (contracts/intrinsics.md §B). The plan
         // carries the op name plus the source/destination `RuntimeMemoryIndex`es;
         // `./transcode.ts` holds the twelve operations.
         case "transcoder": {
@@ -382,14 +320,14 @@ function createTrampolineBody(decl, ctx) {
             if (d.from64 || d.to64) {
                 // 64-bit linear memories are out of scope (https://github.com/polymorph-components/polyengine/issues/12); refusing at
                 // instantiate time keeps "instantiate-time, never call-time".
-                throw new UnsupportedFeatureError("M2", `transcoder '${d.op}' over a 64-bit linear memory`);
+                throw new UnsupportedFeatureError("task-core", `transcoder '${d.op}' over a 64-bit linear memory`);
             }
             if (!TRANSCODE_OPS.includes(d.op)) {
-                throw new UnsupportedFeatureError("M2", `unknown string transcode operation '${d.op}'`);
+                throw new UnsupportedFeatureError("task-core", `unknown string transcode operation '${d.op}'`);
             }
             return createTranscoder(d.op, ctx.runtimeMemory(d.from), ctx.runtimeMemory(d.to));
         }
-        // --- 0.3 async built-ins (contracts/intrinsics.md §B "M2") -------------
+        // --- 0.3 async built-ins (contracts/intrinsics.md §B) -------------
         // All ported in ./async_builtins.ts; the ones that would have to block a
         // wasm frame fail there, at the call site, with a JSPI-shaped message.
         case "task-return":
@@ -484,7 +422,7 @@ function createTrampolineBody(decl, ctx) {
         case "resource-transfer-borrow":
             return (handle, srcTable, dstTable) => transferBorrow(ctx, handle >>> 0, srcTable, dstTable);
         default:
-            throw new UnsupportedFeatureError(milestoneOf(decl.kind) === "M1" ? "M1" : "M2", `component requires host trampoline '${decl.kind}'`);
+            throw new UnsupportedFeatureError(capabilityOf(decl.kind) === "resources" ? "resources" : "task-core", `component requires host trampoline '${decl.kind}'`);
     }
 }
 // ---------------------------------------------------------------------------
@@ -526,10 +464,9 @@ function transferOwn(ctx, handle, srcTable, dstTable) {
  *    which is this path's stand-in for the callee `Subtask`/`Task` of
  *    definitions.py.
  */
-// CONTRACT: contracts/intrinsics.md §A schedules ResourceTransfer* at "M1,
-// resources milestone" and describes them only as "handle-table moves between
-// component instances" — the borrow-scope interaction is unspecified there.
-// The reading implemented here is taken from definitions.py
+// CONTRACT: contracts/intrinsics.md §A describes ResourceTransfer* only as
+// "handle-table moves between component instances" — the borrow-scope
+// interaction beyond the lender registration is taken from definitions.py
 // (`lift_borrow`/`lower_borrow` + `Subtask.lenders`/`Task.num_borrows`) and
 // is what makes `test/resources/borrows.wast:162` (`lend-trap`) trap.
 function transferBorrow(ctx, handle, srcTable, dstTable) {

package/esm/intrinsics/stream_builtins.js

@@ -553,8 +553,8 @@ export function createFutureTransfer(ctx) {
  * rather than removing it, so the source keeps its own.
  */
 /**
- * Plan v3 (contracts/plan-format.md v3 amendment 2): `instanceOf` resolves
- * through the plan's `errorContextTables` section — the
+ * `instanceOf` resolves through the plan's `errorContextTables` section
+ * (contracts/plan-format.md schema) — the
  * `TypeComponentLocalErrorContextTableIndex` space these arguments actually
  * live in. It replaced a resource-table lookup, which shared neither the
  * index space nor (in a multi-instance composition) the answer.

package/esm/intrinsics/transcode.js

@@ -1,5 +1,5 @@
 // FACT string-transcoder intrinsics (`wasmtime_environ::component::Trampoline
-// ::Transcoder`, contracts/intrinsics.md §B "M1").
+// ::Transcoder`, contracts/intrinsics.md §B).
 //
 // FACT emits these when a cross-component call has to move a string between
 // two components whose canonical `string-encoding` options disagree (or, for

package/esm/jspi/bridge.js

@@ -49,7 +49,8 @@ import { withActivation, claimActivationAmbient, dbgId, maybeCurrentThread, rele
  * `requested` is the embedder's opt-in. We additionally require the engine to
  * actually implement JSPI: on an engine without it every blocking site falls
  * back to the precise `NeedsJspi` it raised before this module existed, which
- * is the M3 browser-matrix degradation path (docs/milestones.md M3).
+ * is the browser-matrix degradation path for engines without JSPI (see
+ * `just browsers`).
  */
 export function chooseMode(requested, needed) {
     if (requested === false)
@@ -395,8 +396,8 @@ export class SuspensionPoint {
      * transition this point takes — produce-success, produce-throw, or
      * `abandon` (issue #102). It is the seam a blocking built-in uses to
      * discharge state it owns for the duration of the park (the FACT
-     * start-calls' borrow-lender scopes, contracts/intrinsics.md v0.2
-     * amendment 2) without having to trust that `produce` runs.
+     * start-calls' borrow-lender scopes, contracts/intrinsics.md §A's
+     * trap-unwind/lender-release obligation) without having to trust that `produce` runs.
      *
      * INVARIANTS this hook must respect, so bridge.ts's own contracts are
      * not disturbed:

package/esm/jspi/suspending.js

@@ -1,7 +1,7 @@
 // The per-declaration suspendability marker (contracts/embedder-api.md
-// §"Functions and async", amendments A1/A2; docs/architecture.md §5).
+// §"Functions and async"; docs/architecture.md §5).
 //
-// The canonical definitions live in `@polyengine/protocol` since amendment A9:
+// The canonical definitions live in `@polyengine/protocol` since §"Module identity and @polyengine/protocol":
 // the mark is a process-global `Symbol.for("polyengine.suspending/1")` brand, so
 // a function marked by ANY runtime copy is honored by every other copy
 // (issue #83 — a module-local symbol made a copy-B mark invisible to copy A's
@@ -9,12 +9,12 @@
 // surfacing far away as `NeedsJspi`).
 //
 // Layering: this module was import-free on purpose (jspi/ stays standalone);
-// A9 relaxes that to "imports `@polyengine/protocol` only" — the protocol package
+// module identity relaxes that to "imports `@polyengine/protocol` only" — the protocol package
 // is itself dependency-free, so jspi/ still pulls in no runtime machinery.
-// A23 (`deferCancel`/`isDeferCancel`) and A24 (`abortable`/`isAbortable`)
+// cancellation discard (`deferCancel`/`isDeferCancel`) and abortable() (`abortable`/`isAbortable`)
 // ride the same re-export: they are the other per-declaration host-import
 // marks, they live in the same dependency-free package, and
 // `exec/executor.ts` reads all three through `jspi/mod.ts`.
 // (Host modules import the marks from `@polyengine/protocol` directly —
-// the embedder surface stopped re-exporting the vocabulary at A22.)
+// the embedder surface stopped re-exporting the vocabulary at host-ABI version.)
 export { abortable, anySuspendingImport, deferCancel, isAbortable, isDeferCancel, isSuspending, suspending, } from "@polyengine/protocol";

package/esm/plan/loader.js

@@ -2,8 +2,7 @@
 // of the wire descriptor IR (contracts/descriptor-ir.md JSON) into the cabi
 // in-memory type model (runtime/src/cabi/types.ts, the normative model).
 //
-// Wire -> in-memory deltas handled here (recorded in the M0 contract
-// friction report):
+// Wire -> in-memory deltas handled here:
 //   - `result.err` (wire, per descriptor-ir.md) -> `result.error` (types.ts)
 //   - func params `{label, type}[]` (wire) -> unlabeled `ValType[]`
 //     (types.ts drops ABI-irrelevant names; labels are preserved separately
@@ -56,7 +55,7 @@ export class TranslateError extends Error {
  * the *resource*-table mapping before, a different space) — and
  * `task-return`'s `resultType` / raw `results` split, which lets a FACT
  * callee task carry its declared result type.
- * v2 (M2 phase 2c): `streamTables` / `futureTables` — the element types the
+ * v2: `streamTables` / `futureTables` — the element types the
  * stream and future built-ins need to size their copy buffers.
  * v1 (contracts/plan-format.md v0.3): `CoreDef` gained `"unsafe-intrinsic"`.
  * The change is purely additive, but the contract's compat rule is a strict
@@ -142,7 +141,7 @@ export function loadPlan(wire) {
         }
     }
     // Identity tokens: one per RESOURCE, aliased through every table that
-    // names it — NOT one per table. plan-format.md C2 amendment #1: "one
+    // names it — NOT one per table. plan-format.md "Type exports index into `resourceTables`": "one
     // resource type can be reachable through several distinct table indices …
     // Consumers keying per-resource state must key by `resourceTables[n]
     // .resource`, treating table indices as aliases." Minting per-table broke
@@ -526,7 +525,8 @@ function validateExport(exp, where) {
             validateTypeExport(e.type, `${where}.type`);
             return;
         case "module":
-            // plan-format.md v4 amendment 2: exported embedded core module.
+            // The `module` export kind (contracts/plan-format.md schema notes):
+            // exported embedded core module.
             expectString(e, "name", where);
             expectNumber(e, "module", where);
             return;

package/esm/shim/translator.js

@@ -19,8 +19,8 @@ export class Translator {
      * (docs/architecture.md §10): the wire envelope's `producer` block records
      * `{shimVersion, wasmtimeEnviron, features}`, which does NOT change when
      * the shim wasm is rebuilt from the same source versions (e.g. a local
-     * patch or a different toolchain producing different codegen) — see the
-     * M3-B dispatch. Digesting the actual bytes is the only sound cache key
+     * patch or a different toolchain producing different codegen). Digesting
+     * the actual bytes is the only sound cache key
      * component for translator identity.
      */
     buildHash;