@polyengine/runtime 0.5.1 → 0.6.0

package/esm/task/scheduler.js

@@ -43,7 +43,7 @@
 // stackless (callback-ABI) path never blocks *inside* a wasm frame — every
 // wasm call returns a callback code before the host decides to wait. Blocking
 // inside a wasm frame (stackful async lifts; a sync lower on an unresolved
-// subtask) genuinely requires JSPI and is M2 phase 3; those sites fail loudly
+// subtask) genuinely requires JSPI; those sites fail loudly
 // rather than pretending (see `needsJspi`).
 import { assert_, trapIf } from "../cabi/trap.js";
 /** definitions.py `Cancelled` (line 248). */
@@ -60,7 +60,7 @@ export const CANCELLED_TRUE = true;
  */
 export class NeedsJspi extends Error {
     constructor(what) {
-        super(`needs JSPI (M2 phase 3): ${what}`);
+        super(`needs JSPI: ${what}`);
         this.name = "NeedsJspi";
     }
 }
@@ -68,8 +68,32 @@ export function needsJspi(what) {
     throw new NeedsJspi(what);
 }
 /**
- * Failure raised where a capability scheduled for a later M2 phase is
- * required. Same rationale as `NeedsJspi`: never a `Trap`.
+ * Failure raised when a synchronous entry into an instance would race a
+ * pending lift (contracts/embedder-api.md §"Functions and async",
+ * failure-ladder arm 2).
+ *
+ * In jspi mode a promising-wrapped entry settles through a microtask hop even
+ * when nothing suspended, and the hop-quiescence gate (exec/boundary.ts)
+ * defers Promise-surface calls that would enter during that window. A
+ * synchronous caller — a resource constructor, or the embedder's `sync()`
+ * adapter — cannot be deferred, so it refuses instead.
+ *
+ * Deliberately *not* a `Trap`, and deliberately raised BEFORE the instance is
+ * entered: nothing was entered, so there is nothing to poison. The refusal is
+ * transient — the instance stays enterable, and the call succeeds on retry
+ * once the in-flight activity settles, or immediately through the
+ * Promise-shaped surface, which defers rather than refusing.
+ */
+export class SyncEntryBusy extends Error {
+    constructor(what) {
+        super(`sync entry refused: ${what} (the component instance has activity in ` +
+            `flight; retry once it settles, or use the Promise-shaped call)`);
+        this.name = "SyncEntryBusy";
+    }
+}
+/**
+ * Failure raised where a not-yet-implemented capability is required. Same
+ * rationale as `NeedsJspi`: never a `Trap`.
  */
 export class PendingCapability extends Error {
     constructor(what) {
@@ -114,23 +138,6 @@ const poisonedInstances = new WeakMap();
 export function isInstancePoisoned(inst) {
     return poisonedInstances.has(inst);
 }
-/**
- * May a settled activation tail for parked thread `t` be DISPATCHED now
- * (issue #156)? True iff its instance is host-enterable — `Thread.resumeWith`
- * brackets the resumption with `enterFrom(null)` — or POISONED, in which case
- * `resumeWith`'s early return retires it and deferring would leak forever.
- *
- * CONTRACT: a parked entry without a reachable `task.inst` (the partial
- * thread doubles the host-pump tests park in `Store.awaiting`) holds no
- * reentrance state, so there is nothing to defer on: dispatchable.
- */
-// deno-lint-ignore no-explicit-any
-export function dispatchableTail(t) {
-    const inst = t?.task?.inst;
-    if (inst === undefined || inst === null)
-        return true;
-    return isInstancePoisoned(inst) || inst.mayEnterFrom(null);
-}
 /**
  * The recorded cause of an instance's poisoning: the original trap that
  * broke the enter/leave bracket (polyengine#145). `undefined` when the instance
@@ -142,12 +149,12 @@ export function instancePoisonCause(inst) {
 }
 /**
  * Append the recorded poison cause to an entry-refusal trap message
- * (polyengine#145 ask 1). "cannot enter component instance" covers two states
- * that send an embedder down entirely different debugging paths — a
- * transient reentrance overlap (retry later, look for caller-side call
- * overlap) and a permanently poisoned instance (the corpse of an earlier
- * trap, which this suffix names). Only the poisoned case gets the suffix:
- * the transient message stays byte-identical, and the suffix is
+ * (polyengine#145 ask 1). "cannot enter component instance" has exactly one
+ * cause — a permanently poisoned instance, the corpse of an earlier trap —
+ * and this
+ * suffix names the trap that made it one. The call is kept unconditional at
+ * the refusal sites (returning `base` unchanged for an unmarked instance) so
+ * the message construction stays in one place; the suffix is
  * conformance-safe because the official suite matches trap messages by
  * substring (harness/src/runner.ts).
  */
@@ -157,6 +164,34 @@ export function withPoisonCause(inst, base) {
     const cause = describeCause(poisonedInstances.get(inst));
     return `${base} — instance poisoned by: ${cause}`;
 }
+/**
+ * The entry-refusal decision, in one place: may `caller` enter `callee` right
+ * now, and if not, what does the refusal trap say? Returns `null` when entry
+ * is allowed, otherwise the exact trap message for `base`.
+ *
+ * POISONING IS THE WHOLE MECHANISM (CM#705). There is no transient
+ * reentrance gate: at the pinned reference (definitions.py @ 2f13265)
+ * `may_enter`, `entering_set`, `enter_from`, `leave_to` and
+ * `ComponentInstance.parent` do not exist — `Store.lift` runs `canon_lift`
+ * with no gate at all, so host-mediated reentrance into a live instance is
+ * simply VALID.
+ *
+ * Against that, per-instance poisoning is polyengine's NAMED DIVERGENCE. A
+ * trapped instance is a corpse — entry is refused permanently, with the
+ * recorded cause appended (polyengine#145 ask 1) — where wasmtime instead
+ * kills the whole store. The reference never faces the question because a
+ * trap there is the end of the world.
+ *
+ * The `caller !== callee` guard keeps a self-call out of the refusal: a dtor
+ * invoked from inside its own instance (cabi/handles.ts) is the live case —
+ * it must not be refused by its own instance's marker.
+ */
+export function entryRefusal(callee, caller, base) {
+    if (caller !== callee && isInstancePoisoned(callee)) {
+        return withPoisonCause(callee, base);
+    }
+    return null;
+}
 function describeCause(cause) {
     try {
         // String(err) renders "Name: message" — for a `Trap`, exactly the
@@ -357,9 +392,9 @@ function activationOf() {
  * The opposite shape — A settles B's suspension so B runs AFTER A — is
  * deliberately NOT represented here: `SuspensionPoint.resume` pushes only when
  * nothing is currently running, so B never shadows A. B is picked up by its
- * own first `Suspending` call. (Until 2026-08-22 a third ambient tier — the
- * driver's `resumingThread` slot — also named B here; it was retired with the
- * slot, see `resolveAmbient` and `Store.pendingResumptions`.)
+ * own first `Suspending` call. A driver's settle-time claim would name B
+ * here, which is exactly why it is not an ambient tier — see `resolveAmbient`
+ * and `Store.pendingResumptions`.
  *
  * An activation leaves this stack when it parks again
  * (`blockCurrentActivation`) or finishes (its `awaitValue` promise settles —
@@ -453,14 +488,11 @@ export function releaseActivationAmbient(t) {
 // The resumed-but-not-yet-run gate (a SEPARATE concern from the ambient above)
 // ---------------------------------------------------------------------------
 //
-// This used to be a module-global single slot, `resumingThread`, doing two
-// jobs: (1) the DRIVER's scheduling gate ("a suspension was settled and its
-// activation has not run yet — do not schedule anything else"), and (2) tier 3
-// of ambient resolution. Job (2) was retired on 2026-08-22 (issue #158) after
-// measurement showed it never decided a read; job (1) is real, but it is
-// per-Store SET semantics, not a global identity slot — see
-// `Store.pendingResumptions` below, and `resolveAmbient` for the retirement
-// evidence.
+// The gate answers one question for the DRIVER: "was a suspension settled
+// whose activation has not run yet — must I refrain from scheduling anything
+// else?" That is per-Store SET semantics, not a global identity slot, and it
+// is not an input to ambient resolution: see `Store.pendingResumptions`
+// below.
 const AMBIENT_TRACE = (() => {
     try {
         return Deno.env.get("CE_AMBIENT_TRACE") === "1";
@@ -498,48 +530,38 @@ export function ambientResidue() {
  *      is running outside our frames (a `Suspending` hop or a resumption).
  *      LIFO, because activations nest: an outer activation's built-in can
  *      synchronously enter an inner one's wasm.
- *   (There is no tier 3. A third tier — `resumingThread`, the driver's
- *      settle-time claim — existed from M3A-1 until 2026-08-22 and was
- *      RETIRED, see below.)
  *
- * Tier 2 replaced an async-context store (M3A-1). The store held
- * precisely "the innermost wasm activation currently executing, across the
- * engine's hops and resumptions", because it was written by `withActivation`
- * around the wasm entry and the engine restored it on every continuation it
- * had captured inside that extent. Tiers 1+2 now state that directly. The
- * equivalence is not asserted from the armchair: it was established
- * differentially, by running the whole conformance corpus with both the store
- * and this queue live and comparing them at every read (zero disagreements
- * over 1395 commands), and the corpus pins the result.
+ * What tiers 1+2 state directly is "the innermost wasm activation currently
+ * executing, across the engine's hops and resumptions" -- the same quantity
+ * an async-context store written around the wasm entry would carry, without
+ * depending on the engine to restore it on every continuation captured inside
+ * that extent (M3A-1). The equivalence is not asserted from the armchair: it
+ * was established differentially, against such a store, over the whole
+ * conformance corpus, comparing at every read (zero disagreements over 1395
+ * commands), and the corpus pins the result.
  *
- * Having TWO readers with different orders is not a hypothetical hazard: for
- * two rounds `currentThread` used store-first while `maybeCurrentThread` still
- * used slot-first, and since the FACT bracket sites read the latter, the
- * bracket was attributed to the driver's claim instead of its own activation
- * (`exit-sync-call with an empty sync-call stack`). Fixing the precedence in
- * one reader measured as "no change" because the failing sites used the other.
- * Do not add a third reader; extend this one. (`activationOf` above is not a
+ * Having TWO readers with different precedence orders is not a hypothetical
+ * hazard: they disagree silently at exactly the sites that matter -- the FACT
+ * bracket sites read `maybeCurrentThread`, so a divergent order there
+ * attributes the bracket to the driver's claim instead of its own activation
+ * (`exit-sync-call with an empty sync-call stack`), and a precedence fix
+ * applied to the other reader measures as "no change" because the failing
+ * sites never call it. Do not add a third reader; extend this one. (`activationOf` above is not a
  * second reader -- it answers a different question, "whose wasm frame are we
  * running on behalf of", and is used only by
  * `Store.consumePendingIfRunning`.)
  *
- * TIER 3 RETIRED, 2026-08-22 (issue #158). The bottom tier used to be
- * `resumingThread`, the driver's settle-time claim -- a last resort that named
- * whichever activation was settled or claimed across an await, right for that
- * one and wrong for every other in-flight activation. It was removed on the
- * strength of a re-run of the M3A-1 differential methodology: an instrumented
- * build counted every read where tiers 1-2 were empty and the slot was live,
- * and measured ZERO deciding reads across the conformance corpus (FIFO,
- * 1257/0), both seeded shuffles (`POLYENGINE_SCHED_SEED` 1 and 4242),
- * test-runtime (all jspi pins), and the smoke-tls three-async-component #24
- * corpus. A removal build then ran green on every engine lane we have:
- * test-runtime, test-protocol, conformance (1257/0, no expectation changes),
- * sched-seeds, the shells (sm + node + jsc + bun, all "OK, matches
- * expectation"), the browsers (chromium + firefox), smoke-tls and smoke-c0.
- * The reading: post-#24 the sentinel discipline (tier 2's claim/release edges)
- * always answers first, so the slot's attribution role was vestigial. Its
- * other, live role -- the scheduling gate -- survives as the per-Store
- * `Store.pendingResumptions` set.
+ * TWO TIERS ARE ENOUGH, and specifically a driver's settle-time claim is NOT
+ * a third: such a claim names whichever activation was settled or claimed
+ * across an await -- right for that one and wrong for every other in-flight
+ * activation. It is not needed, because the sentinel discipline (tier 2's
+ * claim/release edges, #24) always answers first: instrumented reads where
+ * tiers 1-2 were empty and a settle-time claim was live decided NOTHING
+ * across the conformance corpus, both seeded shuffles
+ * (`POLYENGINE_SCHED_SEED` 1 and 4242), test-runtime and the smoke-tls
+ * three-async-component #24 corpus. A driver's settle-time claim is a
+ * SCHEDULING gate only, and lives as the per-Store `Store.pendingResumptions`
+ * set (issue #158).
  */
 function resolveAmbient() {
     return threadStack[threadStack.length - 1] ??
@@ -703,22 +725,18 @@ export class Store {
      * wedges the loops, because an activation that merely hopped legitimately
      * holds an ambient while the scheduler is free to proceed.
      *
-     * PER-STORE and MULTI-ENTRY since 2026-08-22 (issues #158 mechanism B,
-     * #210). It was one module-global slot with a one-claimant assert, which
-     * (a) could not represent two legitimately-pending engine resumptions — a
-     * running activation X delivering a resume to Z while Y's resumption was
-     * still pending crashed on the assert — and (b) made every driver on every
-     * store yield while ANY store held a claim, so an idle store's
-     * `driveStoreAsync` died at the 10,000-hop assert (~311ms) while another
-     * store merely dwelt on a slow host import. The assert's invariant was
-     * tier-3 attribution unambiguity, which no longer exists (see
-     * `resolveAmbient`), so it is gone with the slot; the entries and their
-     * release edges are otherwise unchanged, per entry.
+     * PER-STORE and MULTI-ENTRY (issues #158 mechanism B, #210), both load
+     * bearing. MULTI-ENTRY because two engine resumptions can legitimately be
+     * pending at once: a running activation X may deliver a resume to Z while
+     * Y's resumption is still outstanding, and a one-claimant gate cannot
+     * represent that. PER-STORE because a claim held store-wide makes every
+     * driver on EVERY store yield: an idle store's `driveStoreAsync` dies at
+     * the 10,000-hop assert (~311ms) while another store merely dwells on a
+     * slow host import.
      *
      * Cross-store de-serialization is safe by disjointness: an activation
-     * belongs to exactly one store. Same-store it is strictly more conservative
-     * than the old slot — the gate keeps refusing until EVERY pending entry has
-     * died, rather than crashing on the second.
+     * belongs to exactly one store. Same-store the set is conservative — the
+     * gate keeps refusing until EVERY pending entry has died.
      *
      * Release edges, per entry: the activation PARKS again
      * (`blockCurrentActivation` -> `consumePendingIfRunning`), it FINISHES (its
@@ -860,30 +878,18 @@ export class Store {
      * throw (trap unwinding); callers propagate or park it exactly as they do
      * for `tick`.
      *
-     * A tail whose instance is NOT host-enterable is DEFERRED IN PLACE — left
-     * in the queue, skipped here — until the lock releases (issue #156).
-     * `resumeWith` brackets the resumption with `enterFrom(null)`, and under
-     * the shared synthetic per-instantiation root a host entry into ANY
-     * instance of the graph locks the root, so while one instance is entered a
-     * sibling's tail cannot be dispatched: dispatching it tripped
-     * `resumeWith`'s enterability assert (which, mutating before asserting,
-     * also stranded the thread and lost the settle).
+     * Every non-stale tail is dispatched immediately, in queue order: there is
+     * no enterability condition to defer on (CM#705).
      *
-     * Deferral is safe because `!inst.mayEnterFrom(null)` is EXACTLY `tick`'s
-     * candidate-filter predicate on the same instance: while a tail of `inst`
-     * is deferred, `tick` cannot resume any thread of `inst` either, so the
-     * phantom-state gate the queue exists to enforce is preserved per-instance
-     * by construction.
+     * The ordering discipline is therefore settle order, full stop — and it is
+     * the reason this queue exists rather than a direct resumption from the
+     * settle continuation: in definitions.py the tail runs atomically inside
+     * the entered bracket, so the phantom-state gate (`tick` refuses while an
+     * unserviced tail is queued, see `hasServiceableSettled`) is what keeps a
+     * parked activation's tail from being observed out of order.
      *
-     * The ordering discipline is therefore per-instance settle order. Cross-
-     * instance order relaxes only when enterability defers a tail, which is
-     * conforming schedule nondeterminism: in definitions.py the tail runs
-     * atomically inside the entered bracket, so a host entry admitted during a
-     * park necessarily orders before the parked activation's tail there.
-     *
-     * A POISONED instance's tail is still dispatched: `resumeWith`'s poison
-     * early-return retires it, and deferring it would leak forever — a
-     * poisoned leaf keeps its lock permanently.
+     * A POISONED instance's tail is dispatched like any other: `resumeWith`'s
+     * poison early-return retires it, so it drains rather than leaking.
      */
     serviceSettled() {
         let did = false;
@@ -899,8 +905,6 @@ export class Store {
                     this.settled.splice(i, 1);
                     continue scan;
                 }
-                if (!dispatchableTail(s.t))
-                    continue;
                 this.settled.splice(i, 1);
                 s.t.resumeWith(s.value, s.failure);
                 did = true;
@@ -911,19 +915,16 @@ export class Store {
         }
     }
     /**
-     * "Would a `serviceSettled` call make progress right now?" — i.e. some
-     * entry is stale (would be removed) or serviceable (would be dispatched).
-     * A queue holding ONLY deferred tails (issue #156) answers false: `tick`
-     * must not be gated by them, and the driving loops must not spin on them.
+     * "Would a `serviceSettled` call make progress right now?" — i.e. is any
+     * entry queued at all. Every entry either dispatches or is dropped as
+     * stale, so a non-empty queue always makes progress.
+     *
+     * It exists to gate `tick` (and to keep the driving loops from parking)
+     * behind unserviced tails: resuming some other thread while a settled tail
+     * waits would expose the out-of-order state the queue is there to prevent.
      */
     hasServiceableSettled() {
-        for (const s of this.settled) {
-            if (!this.awaiting.has(s.t))
-                return true;
-            if (dispatchableTail(s.t))
-                return true;
-        }
-        return false;
+        return this.settled.length > 0;
     }
     /**
      * "Does component instance `inst` still have runnable work?" — the
@@ -997,9 +998,9 @@ export class Store {
         return false;
     }
     /**
-     * definitions.py `Store.tick` (line 597): resume one ready thread, bracketed
-     * by the reentrance gate for a host-initiated entry (`enter_from(None)` /
-     * `leave_to(None)`).
+     * definitions.py `Store.tick` (@ 2f13265): resume one ready thread. There
+     * is no bracket and no gate — the reference body is exactly "pick a ready
+     * thread, resume it" (CM#705).
      *
      * Returns false when no thread was ready, so callers can distinguish
      * "made progress" from "stuck" without inspecting the queue themselves.
@@ -1024,83 +1025,51 @@ export class Store {
         // Same discipline, other edge: a settled-but-unserviced activation tail
         // (see `settled`) is mid-"atomic resume" from the reference's point of
         // view; scheduling anything before servicing it acts on phantom state.
-        //
-        // Only a SERVICEABLE tail gates: a tail DEFERRED on a non-enterable
-        // instance (issue #156) cannot be dispatched now, and gating on it would
-        // wedge the store (and hot-spin the drivers). It does not need to gate,
-        // because its instance is self-excluded from the candidate set by the
-        // enterability filter below — the same predicate on the same instance —
-        // so no thread of that instance can be resumed while its tail waits.
+        // That is settle-order discipline and has nothing to do with reentrance.
+        // `hasServiceableSettled` (rather than
+        // "queue non-empty") only because a tail whose thread was already resumed
+        // elsewhere must not wedge the store.
         if (this.hasServiceableSettled())
             return false;
-        // Ready is not sufficient: the thread's instance must also be enterable
-        // from the host. The reference *asserts* this in `Store.tick` — a waiting
-        // thread's instance is always re-enterable there, because its host entry
-        // has either left or is itself a waiting thread. That does not hold here.
+        // Ready is sufficient — almost. Nothing filters this set for reentrance:
+        // at the pinned reference (definitions.py @ 2f13265) `Store.tick` resumes
+        // any ready thread with no gate and no bracket (CM#705), so a sibling
+        // instance's thread going ready while another instance is entered from
+        // the host is simply resumable.
         //
-        // Instances of one linked graph share a Store and, with it, the synthetic
-        // per-instantiation root (plan v3 amendment 4): `enterFrom(null)` locks
-        // the callee AND the root, so while ANY instance is entered from the host
-        // — e.g. a sync export parked on an async host import, which in this
-        // runtime is a real suspension rather than a blocked OS thread — no
-        // instance in the graph is host-enterable. A sibling instance whose
-        // thread goes ready in that window (event-driven wakeups do this on every
-        // clock turn) would then trip the assertion, and the failure escapes
-        // through whatever host-import promise is in flight.
-        //
-        // So "ready but not enterable" is treated as no progress, exactly as the
-        // sync driving loop already does by restricting its candidate set to the
-        // callee instance (`driveSyncLift` below; definitions.py `canon_lift`).
-        // This cannot livelock: the entered call's host import settles from host
-        // JS independently of `tick`, and when that call returns, `leaveTo(null)`
-        // unlocks the root and the skipped threads run on the next turn.
-        const candidates = this.readyCandidates().filter((t) => t.task.inst.mayEnterFrom(null));
+        // What is added is polyengine's per-instance poisoning divergence: a
+        // poisoned instance is a corpse, its threads must never resume, and the
+        // MARKER is the whole test. `Thread.resumeWith` makes the same call on
+        // the tail path.
+        const candidates = this.readyCandidates().filter((t) => !isInstancePoisoned(t.task.inst));
         if (candidates.length === 0)
             return false;
         const thread = chooseCandidate(candidates);
         const inst = thread.task.inst;
-        inst.enterFrom(null);
-        // Deliberately NOT a `finally`: if the resumed thread traps, the reference
-        // never reaches `leave_to` either (definitions.py `Store.tick`, line 597,
-        // where a Trap propagates out of `thread.resume()`), so the instance stays
-        // locked — the Component Model's instance poisoning. See the `poison`
-        // helper in exec/boundary.ts for the full rationale.
-        //
-        // Capability signals are the exception, for the same reason as there: a
-        // `NeedsJspi`/`PendingCapability` marks an operation this runtime cannot
-        // perform, not a component fault. In the reference that operation blocks
-        // and then completes, so `leave_to` *is* reached and the instance stays
-        // enterable — poisoning here would turn one unsupported operation into a
-        // permanently dead instance.
+        // A trap out of the resumption poisons the instance (polyengine's named
+        // divergence: a per-instance corpse where wasmtime kills the whole store).
+        // Capability signals are the exception: a `NeedsJspi`/`PendingCapability`
+        // marks an operation this runtime cannot perform, not a component fault —
+        // in the reference that operation blocks and then completes, so poisoning
+        // here would turn one unsupported operation into a permanently dead
+        // instance.
         try {
             thread.resume();
         }
         catch (e) {
-            if (e instanceof NeedsJspi || e instanceof PendingCapability) {
-                inst.leaveTo(null);
-            }
-            else {
-                // The bracket stays broken (instance poisoned, comment above), so
-                // its live stream/future ends can never rendezvous again — retire
-                // them so parked host peers settle instead of hanging (#66).
-                //
-                // The synthetic root (plan v3 amendment 4) is released, though: it is
-                // in this entry's entering set but must not turn per-instance
-                // poisoning into store-wide poisoning. See
-                // `ComponentInstanceState.releaseSyntheticRootOnPoison`.
+            if (!(e instanceof NeedsJspi) && !(e instanceof PendingCapability)) {
+                // Poisoned: its live stream/future ends can never rendezvous again —
+                // retire them so parked host peers settle instead of hanging (#66).
                 //
                 // Routed through `notifyInstancePoisoned` (not the raw hook) so the
                 // poison MARKER is recorded too (polyengine#145): `Thread.resumeWith`'s
-                // quiet-retire of late settled tails and `dispatchableTail`'s
-                // dispatch-or-defer decision (#156) both read it, and without the
-                // marker a settled tail of this instance would hit the backstop
-                // assert or defer forever.
-                inst.releaseSyntheticRootOnPoison?.();
+                // quiet-retire of late settled tails (#156) and `entryRefusal` both
+                // read it; without the marker a settled tail of this dead instance
+                // would be resumed as if healthy.
                 notifyInstancePoisoned(inst, e);
             }
             throw e;
         }
-        inst.leaveTo(null);
         return true;
     }
 }