@polyengine/runtime 0.1.0-pre.g633468a

package/types/task/scheduler.d.ts

@@ -0,0 +1,421 @@
+/** definitions.py `Cancelled` (line 248). */
+export declare const CANCELLED_FALSE = false;
+export declare const CANCELLED_TRUE = true;
+export type Cancelled = boolean;
+/**
+ * What a thread body yields when it wants to stop running. Mirrors the
+ * reference's `Thread.wait_until` (`ready_func` + `cancellable`); `suspend`
+ * is `wait_until` with no ready condition (`ready_func === null`), and
+ * `yield_` is `wait_until(() => true)`.
+ */
+export interface BlockRequest {
+    /** Resumable once this returns true; `null` = only an explicit resume. */
+    readyFunc: (() => boolean) | null;
+    cancellable: boolean;
+    /**
+     * JSPI seam. When present the thread is not waiting on a scheduler
+     * condition at all — it is waiting for a **Promise**, namely the one a
+     * `promising`-wrapped wasm entry returned. The driving loop awaits it and
+     * resumes the body with the resolved value (or throws the rejection into
+     * the body, so a post-resume trap unwinds exactly like a synchronous one —
+     * jspi pin (e)).
+     *
+     * This is what lets one generator body serve both modes: in plain mode the
+     * core call returns a value and the body never yields such a request, so
+     * the synchronous path is bit-for-bit what it was before JSPI existed.
+     */
+    awaitValue?: Promise<unknown>;
+}
+/**
+ * A thread body: yields block requests, and receives back either the
+ * cancelled flag (for a scheduler block point) or the resolved value of an
+ * `awaitValue` request.
+ */
+export type ThreadBody = Generator<BlockRequest, void, any>;
+/**
+ * Failure raised where the reference genuinely needs to suspend a wasm frame.
+ *
+ * This is deliberately *not* a `Trap`: the component is not at fault and the
+ * program is not ill-formed — our runtime is incomplete. Reporting it as a
+ * trap would let a conformance run score a missing capability as a correct
+ * rejection, which is the exact failure mode contracts/plan-format.md's
+ * error-phase split exists to prevent.
+ */
+export declare class NeedsJspi extends Error {
+    constructor(what: string);
+}
+export declare function needsJspi(what: string): never;
+/**
+ * Failure raised where a capability scheduled for a later M2 phase is
+ * required. Same rationale as `NeedsJspi`: never a `Trap`.
+ */
+export declare class PendingCapability extends Error {
+    constructor(what: string);
+}
+/** @internal — see `onInstancePoisoned`; registered once by task/streams.ts. */
+export declare function setOnInstancePoisoned(f: (inst: {
+    handles: Iterable<unknown>;
+}, cause: unknown) => void): void;
+/**
+ * @internal — invoke the poisoning hook. For the bracket-break sites that
+ * live outside this module (`Thread.resumeWith`, exec/boundary.ts `poison`):
+ * one seam, all sites.
+ */
+export declare function notifyInstancePoisoned(inst: {
+    handles: Iterable<unknown>;
+}, cause: unknown): void;
+export declare function isInstancePoisoned(inst: object): boolean;
+/**
+ * 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.
+ */
+export declare function dispatchableTail(t: any): boolean;
+/**
+ * The recorded cause of an instance's poisoning: the original trap that
+ * broke the enter/leave bracket (polyengine#145). `undefined` when the instance
+ * is not poisoned — and, degenerately, when the poisoning cause itself was
+ * a thrown `undefined`; use `isInstancePoisoned` for the predicate.
+ */
+export declare function instancePoisonCause(inst: object): unknown;
+/**
+ * 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
+ * conformance-safe because the official suite matches trap messages by
+ * substring (harness/src/runner.ts).
+ */
+export declare function withPoisonCause(inst: object, base: string): string;
+/** Test hook: switch policy at runtime. `null` restores FIFO. */
+export declare function schedulerSeedForTesting(value: number | null): void;
+export declare function schedulerPolicy(): "fifo" | "seeded-shuffle";
+/**
+ * Pick one candidate. FIFO (index 0 — candidates are supplied in
+ * ready-order) unless a seed is configured, in which case a seeded uniform
+ * choice, mirroring the reference's `random.choice`.
+ */
+export declare function chooseCandidate<T>(candidates: readonly T[]): T;
+export interface CurrentThreadLike {
+    storage: number[];
+    task: any;
+}
+export declare function pushCurrentThread(t: CurrentThreadLike): void;
+export declare function popCurrentThread(t: CurrentThreadLike): void;
+/**
+ * Run `fn` with `t` as the ambient, for `fn`'s SYNCHRONOUS extent.
+ *
+ * This is the wasm-entry bracket (`awaitCore`). It is the same `threadStack`
+ * the scheduler's own `resume()` bracket uses, deliberately: a wasm entry made
+ * from *inside* an engine-driven resumption (a FACT callee reached from a
+ * resumed activation — fact_calls.ts) has an empty scheduler bracket, and the
+ * entry itself is then the most specific statement of who is running.
+ */
+export declare function withActivation<T>(t: any, fn: () => T): T;
+/**
+ * Record that the engine will run `t`'s wasm outside our frames.
+ *
+ * Idempotent in MEMBERSHIP but not in POSITION: re-claiming MOVES an
+ * existing claim to the top. The stack's contract is "top = the innermost
+ * activation the engine is running outside our frames", and a re-claim is
+ * direct evidence that `t` is running RIGHT NOW (its Suspending import just
+ * returned into its wasm). The previous early-return kept stale order: a
+ * nested callee's claim whose release edge is a promise reaction
+ * (`Store.noteAwaiting` -> `releaseClaimOf`) outlives the callee by a
+ * microtask, and an outer activation's continuation chunk that resumed in
+ * that window re-claimed itself as a NOOP — leaving the finished callee on
+ * top, so every ambient read in the rest of the chunk (the next hop's
+ * `owner` capture, and any unsafe intrinsic like `context.set`, which has
+ * no hop to re-anchor on) answered the wrong thread. Found as issue #24:
+ * wit-bindgen's callback epilogue restored its task pointer into another
+ * thread's context slots, and the next disciplined callback invocation
+ * panicked on a null slot (async_support.rs:578).
+ *
+ * A null/undefined activation is "no claim" — the instantiation-time shape
+ * that has no thread at all.
+ */
+export declare function claimActivationAmbient(t: any): void;
+export declare function dbgId(t: unknown): string;
+/**
+ * Drop `t`'s activation-ambient claim, if it holds one.
+ *
+ * The two closing edges: the activation PARKS on a fresh suspension
+ * (`blockCurrentActivation`), or it FINISHES — its `awaitValue` promise
+ * settles, normally or by rejection, and `Store.noteAwaiting`'s eager settle
+ * continuation calls this. The `task.implicitThread` indirection covers the
+ * second edge for claims taken against a task's implicit thread.
+ */
+export declare function releaseActivationAmbient(t: any): void;
+/** Claim the ambient for `t` across an engine-driven resumption. */
+export declare function setResumingThread(t: any): void;
+/** Is a settled-but-not-yet-run activation holding the ambient? */
+export declare function hasResumingThread(): boolean;
+/** Release the claim; called once we are back in our own continuation. */
+export declare function clearResumingThread(): void;
+/**
+ * Release the driver's claim iff its activation is demonstrably RUNNING —
+ * i.e. the claim names the same thread the ACTIVATION AMBIENT names for the
+ * code calling us. The claim exists to cover the window between settling a
+ * suspension and the resumed activation running; once that activation's own
+ * code is on the stack the window is closed, and holding the claim would
+ * falsely trip the one-claimant assert when the running activation's built-in
+ * settles ANOTHER activation's suspension — `subtask.cancel` delivering a
+ * cancellation to a parked callee (cancellable.wast) is exactly that shape.
+ * When the two disagree (or no ambient is present) the claim stays, and the
+ * assert keeps guarding the genuine two-unrun-claimants bug it was built for.
+ *
+ * The comparison used to be against the async-context store; it is now
+ * against `activationOf()`, which is the same statement made explicitly.
+ */
+export declare function consumeClaimIfRunning(): void;
+/**
+ * Release the claim iff it names `t` — the settle-side half of the claim
+ * discipline: a claim taken when `t`'s suspension was settled dies when `t`'s
+ * activation finishes (its `awaitValue` promise settles; `Store.noteAwaiting`
+ * calls this from the eager settle continuation) or parks again
+ * (`blockCurrentActivation` consumes via `consumeClaimIfRunning`).
+ *
+ * `t` FINISHING also ends its activation ambient, so both are dropped here.
+ */
+export declare function releaseClaimOf(t: any): void;
+/** Diagnostic (#24 probe): the full ambient state, for tracing. */
+export declare function ambientDebug(): {
+    stack: unknown[];
+    claims: unknown[];
+    resuming: unknown;
+};
+/** Diagnostic: module-scope state that must NOT survive a completed call. */
+export declare function ambientResidue(): {
+    stack: number;
+    claim: boolean;
+};
+export declare function currentThread<T = CurrentThreadLike>(): T;
+export declare function maybeCurrentThread(): CurrentThreadLike | undefined;
+/** definitions.py `current_task()` (line 309). */
+export declare function currentTask(): any;
+/**
+ * The running task, or `null` outside any task — e.g. a core module's start
+ * function during instantiation, which the reference has no model for.
+ */
+export declare function maybeCurrentTask(): any | null;
+/** definitions.py `current_instance()` (line 312). */
+export declare function currentInstance(): any;
+/** Structural view of a Thread, as the store's ready queue needs it. */
+export interface SchedulableThread {
+    ready(): boolean;
+    waiting(): boolean;
+    resume(cancelled?: Cancelled): void;
+    task: any;
+}
+/**
+ * The embedder-visible scheduler state (definitions.py `Store`). One per
+ * instantiated component in this runtime — the reference shares one `Store`
+ * across component instances of a linked graph, and so do we: `Executor`
+ * creates a single `Store` and hands it to every `ComponentInstanceState`.
+ *
+ * `waiting` is kept as an **array, in insertion order**, which is what makes
+ * the default policy FIFO: `readyCandidates()` preserves the order in which
+ * threads started waiting.
+ */
+export declare class Store {
+    readonly waiting: SchedulableThread[];
+    /**
+     * Host-import promises this store is waiting on. Non-empty means progress
+     * is possible but only after a microtask turn — see `drive` in
+     * exec/boundary.ts. (definitions.py has no analogue: its host functions run
+     * on real threads.)
+     */
+    readonly pendingHostCalls: Set<Promise<unknown>>;
+    /**
+     * An exception raised by a host import's promise (a rejection, or a trap
+     * thrown while lowering its results). It cannot propagate out of the
+     * microtask that produced it, so it is parked here and rethrown by whoever
+     * is driving the store — which is the call the guest is blocked in.
+     */
+    hostFailure: unknown;
+    startWaiting(t: SchedulableThread): void;
+    stopWaiting(t: SchedulableThread): void;
+    /** Ready waiting threads, in wait order (the FIFO of the default policy). */
+    readyCandidates(): SchedulableThread[];
+    /**
+     * Threads parked on a Promise (the jspi `awaitValue` seam). They are not in
+     * `waiting` — nothing the scheduler can do makes them ready — so the driving
+     * loop tracks them separately and resumes them when their promise settles.
+     */
+    readonly awaiting: Set<any>;
+    /**
+     * Settled-but-unserviced activation tails, in settle order.
+     *
+     * A settled `awaitValue` is the rest of an activation that already finished
+     * its wasm: result shaping, the callback loop, `exit_implicit_thread` (and
+     * with it the exclusive-thread release). The reference runs all of that
+     * atomically inside `Thread.resume`; under jspi it lands a few engine
+     * microtasks after the observable effects of the activation (`task.return`
+     * flips `resolved` DURING the wasm, the settle only afterwards — jspi
+     * pin (j)). Any scheduling decision taken in that window sees phantom
+     * state — a finished callee still "holding" its exclusive slot made
+     * cancellable.wast report STARTING for an entry the reference admits. So
+     * settlement is recorded EAGERLY (at park time, below), `tick` refuses to
+     * run anything while a tail is unserviced, and the driving loop services
+     * this queue first.
+     */
+    readonly settled: {
+        t: any;
+        value: unknown;
+        failure: {
+            error: unknown;
+        } | undefined;
+    }[];
+    /**
+     * Park `t` on `promise` (jspi `awaitValue`), with EAGER settle tracking.
+     *
+     * The `.then` here is also what closes the claim discipline for
+     * resumptions the driver did not settle itself (a guest built-in resolving
+     * another activation's suspension — `subtask.cancel` delivering a
+     * cancellation): the claim taken at settle time must survive until the
+     * resumed activation parks again or finishes, and "finished" is exactly
+     * this continuation firing. See `releaseClaimOf`.
+     */
+    noteAwaiting(t: any, promise: Promise<unknown>): void;
+    /**
+     * Service settled activation tails. Returns whether anything ran. EVERY
+     * driving loop must call this before (and interleaved with) `tick` — the
+     * queue gates `tick`, so a driver that never services it wedges the store
+     * (observed: host-stream pumping between export calls). A `resumeWith` may
+     * 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).
+     *
+     * 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 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.
+     */
+    serviceSettled(): boolean;
+    /**
+     * "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.
+     */
+    hasServiceableSettled(): boolean;
+    /**
+     * "Does component instance `inst` still have runnable work?" — the
+     * drain-to-quiescence predicate behind the **deferred entry decision**
+     * (issue #43).
+     *
+     * wasmtime decides an async-lowered call's initial status only after the
+     * executor has drained the work queued ahead of it: a queued
+     * `GuestCall(StartImplicit)` is popped, and if `is_ready` is false
+     * (`do_not_enter || backpressure`) the caller is told STARTING
+     * (concurrent.rs :1497-1522, :3040-3160). That formulation is FIFO-order
+     * dependent; polyengine uses the order-robust restatement (issue #43): *the
+     * call reports STARTING only if the callee is still unstarted after the
+     * instance's runnable work has been exhausted* — drain to quiescence, not
+     * pop-one. That is what keeps `sync-streams.wast` green under
+     * `POLYENGINE_SCHED_SEED` shuffles, which wasmtime's own rule would not be.
+     * Adjudicated 2026-08-10 (issue #43): entry-status timing is NOT
+     * normative — this predicate implements a scheduler *policy*, picked so
+     * the suite's schedule-overfitted STARTED assertion holds under any
+     * seed; the hold-rule gate itself is the spec semantics.
+     *
+     * "Runnable work of `inst`" is, exhaustively:
+     *
+     *   (a) a settled-but-unserviced activation tail (`settled`) — bookkeeping
+     *       the reference runs atomically inside `Thread.resume`, so the
+     *       instance is mid-step, not quiescent;
+     *   (b) a waiting entry (thread or `SuspensionPoint`) of `inst` that is
+     *       `ready()` — the scheduler will resume it on the next tick. A gate
+     *       holder parked mid-frame on an un-rendezvous'd operation is NOT
+     *       ready and therefore contributes nothing: that is the "holder
+     *       cannot be drained" case, whose answer is STARTING;
+     *   (c) a thread of `inst` in `awaiting` whose promise is not a scheduler
+     *       park — i.e. genuinely in flight across an engine microtask hop.
+     *       A JSPI-parked activation appears in `awaiting` *and* owns a
+     *       `SuspensionPoint` in `waiting` (`SuspensionPoint.owner`), and is
+     *       accounted for by (b) instead; counting it here would make the
+     *       instance permanently non-quiescent.
+     *
+     * `excludeTask` is the CALLER's task, and is excluded everywhere: the
+     * caller cannot be drained — it is the activation asking the question.
+     * This is what makes the "only obstacle is the current running activation"
+     * shape (a nested lower from inside the gate holder's own invocation)
+     * answer STARTING immediately, with no park at all.
+     */
+    hasRunnableWork(inst: unknown, excludeTask: unknown): boolean;
+    /**
+     * 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)`).
+     *
+     * Returns false when no thread was ready, so callers can distinguish
+     * "made progress" from "stuck" without inspecting the queue themselves.
+     */
+    tick(): boolean;
+}
+/** Mark `p` as an activity arm (exec/host_streams.ts `HostActivity`). */
+export declare function markHostActivityArm(p: Promise<unknown>): void;
+/** Is there host-call work outstanding that is not just an activity arm? */
+export declare function hasRealHostCall(store: Store): boolean;
+/** Every outstanding host call that is real work (not an activity arm). */
+export declare function realHostCalls(store: Store): Promise<unknown>[];
+/**
+ * Is there anything left that only a turn of the event loop could advance?
+ * Activity arms do not count: they say "the embedder may still act", which is
+ * precisely the state in which a between-calls driver should stop and let the
+ * operation's promise stay pending (the documented hang, exec/host_streams.ts
+ * module header).
+ *
+ * `store.settled` (settled-but-unserviced activation tails) DOES count: it
+ * gates `tick`, so exiting with a tail queued is a lost wakeup — the store is
+ * wedged until some other driver appears.
+ */
+export declare function storeQuiescent(store: Store): boolean;
+/**
+ * The reference's `canon_lift` sync driving loop (line 2213):
+ *
+ * ```python
+ * while task.state != Task.State.RESOLVED:
+ *   candidates = { t for t in inst.threads if t.ready() and t is not inst.exclusive_thread }
+ *   trap_if(not candidates)
+ *   random.choice(list(candidates)).resume()
+ * ```
+ *
+ * Note the candidate set is `inst.threads` — threads *of the callee instance*
+ * — and excludes the exclusive thread, and that an empty set is a **trap**
+ * (the spec's deadlock trap), not a hang.
+ */
+export declare function driveSyncLift(task: {
+    state: string;
+    inst: {
+        threads: Iterable<SchedulableThread>;
+        exclusiveThread: unknown;
+    };
+}): void;