@polyengine/runtime 0.1.0-pre.g633468a

package/types/task/streams.d.ts

@@ -0,0 +1,370 @@
+import { Trap } from "../cabi/trap.js";
+import { LiftLowerContext } from "../cabi/context.js";
+import type { ComponentValue, ValType } from "../cabi/types.js";
+import { Waitable } from "./waitable.js";
+/** Structural element-type equality (`null` = the zero-width payload).
+ * Delegates to `valTypeEqual`: naive `JSON.stringify` comparison throws on
+ * resource-bearing element types (cabi/types.ts `valTypeEqual` contract
+ * note; found by the #18 polymorph-tls smoke). */
+export declare function sameElemType(a: ValType | null, b: ValType | null): boolean;
+/** definitions.py `Buffer.MAX_LENGTH`. */
+export declare const BUFFER_MAX_LENGTH: number;
+/**
+ * One rendezvous chunk. u8 payloads travel as `Uint8Array` — the lift out of
+ * guest memory and the conventions layer's lowering both produce typed
+ * chunks, and every buffer in the copy path keeps them whole (issue #54: the
+ * typed shape is what makes both the guest-memory store and a host→host
+ * hand-off bulk). Every other element type travels as a plain array.
+ */
+export type PayloadChunk = ComponentValue[] | Uint8Array;
+/** definitions.py `CopyResult` (line 977). */
+export declare enum CopyResult {
+    COMPLETED = 0,
+    DROPPED = 1,
+    CANCELLED = 2
+}
+/** definitions.py `CopyState` (line 1075). */
+export declare enum CopyState {
+    IDLE = 1,
+    COPYING = 2,
+    CANCELLING_COPY = 3,
+    DONE = 4
+}
+export type ReclaimBuffer = () => void;
+export type OnCopy = (reclaim: ReclaimBuffer) => void;
+export type OnCopyDone = (result: CopyResult) => void;
+/**
+ * A cursor over `length` elements of type `t` at `ptr` in one guest's memory.
+ * `t === null` is the zero-width element type (`stream` with no payload),
+ * where only the *count* is meaningful.
+ */
+export declare class GuestBuffer {
+    readonly t: ValType | null;
+    readonly cx: LiftLowerContext;
+    ptr: number;
+    readonly length: number;
+    progress: number;
+    constructor(t: ValType | null, cx: LiftLowerContext, ptr: number, length: number);
+    remain(): number;
+    isZeroLength(): boolean;
+    /** definitions.py `ReadableBufferGuestImpl.read`. */
+    read(n: number): PayloadChunk;
+    /** definitions.py `WritableBufferGuestImpl.write`. */
+    write(vs: PayloadChunk): void;
+}
+/** Common shape of the object a `stream`/`future` *value* refers to. */
+export interface SharedBase {
+    readonly t: ValType | null;
+    dropped: boolean;
+    cancel(): void;
+    drop(): void;
+}
+export declare class SharedStreamImpl implements SharedBase {
+    #private;
+    readonly t: ValType | null;
+    /**
+     * Optional hook fired when this shared object is lowered into a component
+     * instance (`lower_stream`/`lower_future`). Host-owned ends use it to learn
+     * which `Store` is driving the guest they were just handed to; guest-owned
+     * streams leave it unset. Keeps `cabi` free of any host-stream knowledge.
+     */
+    onLowered: ((inst: {
+        store: unknown;
+    }) => void) | null;
+    /**
+     * Optional hook fired by `liftAsyncValue` whenever this object is lifted
+     * OUT of a guest table. The receiver — the host, or the destination of a
+     * guest-to-guest hop, in which case the immediately following lower fires
+     * `onLowered` — may now act on the transferred end. Host wrappers use it to
+     * re-arm their activity (#162, embedder-api amendment A15). Guest-owned
+     * objects leave it unset.
+     */
+    onLifted: ((inst: {
+        store: unknown;
+    }) => void) | null;
+    /**
+     * The `Store` driving the component this object has been handed to, set the
+     * first time it is lifted or lowered. Host ends need it to pump the guest
+     * between export calls (see exec/host_streams.ts `HostActivity.pump`); a
+     * purely guest-to-guest stream never reads it.
+     */
+    boundStore: unknown;
+    dropped: boolean;
+    pendingInst: unknown;
+    pendingBuffer: GuestBuffer | null;
+    pendingOnCopy: OnCopy | null;
+    pendingOnCopyDone: OnCopyDone | null;
+    /** Register `fn` for the drop notification (fires now if already dropped). */
+    whenDropped(fn: () => void): void;
+    /** @internal — fire the drop observers (idempotent; never throws). */
+    notifyDropped(): void;
+    constructor(t: ValType | null);
+    resetPending(): void;
+    setPending(inst: unknown, buffer: GuestBuffer | null, onCopy: OnCopy | null, onCopyDone: OnCopyDone | null): void;
+    resetAndNotifyPending(result: CopyResult): void;
+    cancel(): void;
+    drop(): void;
+    /** definitions.py `SharedStreamImpl.read` (line 1032). */
+    read(inst: unknown, dstBuffer: GuestBuffer, onCopy: OnCopy, onCopyDone: OnCopyDone): void;
+    /** definitions.py `SharedStreamImpl.write` (line 1050). */
+    write(inst: unknown, srcBuffer: GuestBuffer, onCopy: OnCopy, onCopyDone: OnCopyDone): void;
+}
+/** definitions.py `class SharedFutureImpl` (line 1119). Exactly one element. */
+export declare class SharedFutureImpl implements SharedBase {
+    #private;
+    readonly t: ValType | null;
+    /**
+     * Optional hook fired when this shared object is lowered into a component
+     * instance (`lower_stream`/`lower_future`). Host-owned ends use it to learn
+     * which `Store` is driving the guest they were just handed to; guest-owned
+     * streams leave it unset. Keeps `cabi` free of any host-stream knowledge.
+     */
+    onLowered: ((inst: {
+        store: unknown;
+    }) => void) | null;
+    /**
+     * Optional hook fired by `liftAsyncValue` whenever this object is lifted
+     * OUT of a guest table. The receiver — the host, or the destination of a
+     * guest-to-guest hop, in which case the immediately following lower fires
+     * `onLowered` — may now act on the transferred end. Host wrappers use it to
+     * re-arm their activity (#162, embedder-api amendment A15). Guest-owned
+     * objects leave it unset.
+     */
+    onLifted: ((inst: {
+        store: unknown;
+    }) => void) | null;
+    /**
+     * The `Store` driving the component this object has been handed to, set the
+     * first time it is lifted or lowered. Host ends need it to pump the guest
+     * between export calls (see exec/host_streams.ts `HostActivity.pump`); a
+     * purely guest-to-guest stream never reads it.
+     */
+    boundStore: unknown;
+    dropped: boolean;
+    /**
+     * Set when the future's **writable** side went away without ever delivering
+     * its one value (#84 teardown of a trap-poisoned instance, #90 host
+     * `drop()` on a lowered-but-unwritten future).
+     *
+     * definitions.py keeps this state unreachable: `WritableFutureEnd.drop`
+     * traps unless the end is DONE (definitions.py:1183-1184), so a readable
+     * future end can never observe DROPPED (`future_copy`'s `on_copy_done`
+     * assertion, definitions.py:2607). Our two teardown paths deliberately
+     * bypass that trap — a poisoned instance cannot be asked to trap again, and
+     * the host `drop()` is a public API door — so the state exists here and has
+     * to be *total*: an unwritten future whose writer died can never satisfy
+     * its reader, so the reader is told at its rendezvous point, with a
+     * **trap**, never a DROPPED/COMPLETED answer and never a silent hang.
+     *
+     * Consumers of the flag:
+     *   * `read` below, for a reader that has not parked yet (trap on the spot);
+     *   * intrinsics/stream_builtins.ts `futureCopy`, for a parked guest reader
+     *     (the pending event's thunk throws instead of producing a tuple);
+     *   * exec/host_streams.ts leaves host readers on their existing DROPPED
+     *     path — the conventions layer already brands that outcome.
+     */
+    abandonReason: Error | null;
+    pendingInst: unknown;
+    pendingBuffer: GuestBuffer | null;
+    pendingOnCopyDone: OnCopyDone | null;
+    /** Register `fn` for the drop notification (fires now if already dropped). */
+    whenDropped(fn: () => void): void;
+    /** @internal — fire the drop observers (idempotent; never throws). */
+    notifyDropped(): void;
+    constructor(t: ValType | null);
+    resetPending(): void;
+    setPending(inst: unknown, buffer: GuestBuffer | null, onCopyDone: OnCopyDone | null): void;
+    resetAndNotifyPending(result: CopyResult): void;
+    cancel(): void;
+    drop(): void;
+    read(inst: unknown, dstBuffer: GuestBuffer, onCopyDone: OnCopyDone): void;
+    write(inst: unknown, srcBuffer: GuestBuffer, onCopyDone: OnCopyDone): void;
+}
+/**
+ * One guest-visible end of a stream or future. It **is** a `Waitable`, so it
+ * joins waitable sets and delivers events through the machinery the subtask
+ * path already uses.
+ */
+export declare abstract class CopyEnd extends Waitable {
+    readonly shared: SharedBase;
+    state: CopyState;
+    constructor(shared: SharedBase);
+    /** "stream" | "future" — trap-wording parity with wasmtime. */
+    abstract readonly kind: "stream" | "future";
+    /**
+     * Which end this is. Wasmtime words a busy READABLE-end drop as a table
+     * removal ("cannot remove busy stream") and a busy WRITABLE-end drop as a
+     * drop ("cannot drop busy stream") — the suite pins both spellings side by
+     * side (drop-stream.wast:158 read end vs :160 / builtin-trap-poisons-
+     * instance.wast:38 write end).
+     */
+    abstract readonly side: "readable" | "writable";
+    copying(): boolean;
+    drop(): void;
+}
+export declare class ReadableStreamEnd extends CopyEnd {
+    readonly kind = "stream";
+    readonly side = "readable";
+    readonly shared: SharedStreamImpl;
+    copy(inst: unknown, dst: GuestBuffer, onCopy: OnCopy, onCopyDone: OnCopyDone): void;
+}
+export declare class WritableStreamEnd extends CopyEnd {
+    readonly kind = "stream";
+    readonly side = "writable";
+    readonly shared: SharedStreamImpl;
+    copy(inst: unknown, src: GuestBuffer, onCopy: OnCopy, onCopyDone: OnCopyDone): void;
+}
+export declare class ReadableFutureEnd extends CopyEnd {
+    readonly kind = "future";
+    readonly side = "readable";
+    readonly shared: SharedFutureImpl;
+    copy(inst: unknown, dst: GuestBuffer, onCopyDone: OnCopyDone): void;
+}
+export declare class WritableFutureEnd extends CopyEnd {
+    readonly kind = "future";
+    readonly side = "writable";
+    readonly shared: SharedFutureImpl;
+    copy(inst: unknown, src: GuestBuffer, onCopyDone: OnCopyDone): void;
+    /**
+     * definitions.py `WritableFutureEnd.drop` (line 1183): a future's writable
+     * end may only be dropped once it has actually delivered its one value —
+     * `test/async/futures-must-write.wast` is the case this exists for.
+     */
+    drop(): void;
+}
+/** The recorded poisoning failure for a shared stream/future value, if any. */
+export declare function poisonFailureOf(shared: unknown): Error | undefined;
+/**
+ * The trap a reader of an abandoned future observes at its rendezvous point.
+ *
+ * `Trap` is the guest-visible fault vocabulary (cabi/trap.ts); the recorded
+ * reason rides as `cause` so the embedder/host layers can still attribute the
+ * original fault. (`Trap`'s constructor takes only a message, so `cause` is
+ * attached after construction rather than through `ErrorOptions`.)
+ */
+export declare function futureAbandonTrap(reason: Error): Trap;
+/** The abandonment reason of a shared future, if it has one (#84/#90). */
+export declare function abandonReasonOf(shared: unknown): Error | null;
+/**
+ * Mark a future's writable side as gone-without-a-value and settle the
+ * rendezvous (#90's host `drop()` door; the poisoning walk below routes
+ * through `dropSharedForTeardown` instead, which adds the dead-guest
+ * discipline).
+ *
+ * Never throws, and idempotent: a second call on an already-dropped future is
+ * a no-op, so `drop()`/`Symbol.dispose` at the layers above are total.
+ */
+export declare function abandonSharedFuture(shared: SharedFutureImpl, reason: Error): void;
+/** The structural slice of `ComponentInstanceState` the walk needs. */
+interface PoisonedInstanceLike {
+    readonly index?: number;
+    handles: Iterable<unknown>;
+}
+/**
+ * Drop a shared stream/future as *teardown*, without waking a doomed guest.
+ *
+ * Same outcome as `drop()` for host ends and healthy guest peers (a DROPPED
+ * notification), with one difference: a parked side belonging to a
+ * **poisoned** guest instance is retired silently via `resetPending`.
+ * Notifying it would queue a phantom event into the corpse's waitables, and
+ * a later driving loop servicing it would resume machinery whose instance
+ * can no longer be entered (`tick` asserts enterability). Host sentinels are
+ * not instances at all, so they are always notified.
+ *
+ * #100: THE HEALTH TEST IS "POISONED", NOT "`mayEnter === false`". The
+ * original test used non-enterability as a proxy for deadness. The proxy is
+ * unsound in one direction, and the unsoundness stranded healthy tasks:
+ *
+ *  * (sound half, #84 audit) a healthy guest peer always parks with
+ *    `mayEnter === true`. Every park — the callback ABI's waitable-set wait,
+ *    and equally a sync-lowered/JSPI peer blocked inside `finishCopy`'s
+ *    SITE 4 via `blockCurrentActivation` — yields the thread out of the
+ *    scheduler's enter/leave bracket, and the bracket's `leaveTo` runs on the
+ *    way out (task/scheduler.ts `Store.tick` :905-917, task/thread.ts
+ *    `Thread.resumeWith` :157-179, whose resume-side
+ *    `assert_(mayEnterFrom(null))` would fire otherwise). Blocking inside a
+ *    wasm frame does NOT hold the enter bracket.
+ *  * (unsound converse) `mayEnter === false` does not imply "poisoned". An
+ *    instance that is merely mid-call is also non-enterable, and a CALLER
+ *    instance stays non-enterable for the whole duration of a
+ *    cross-component (FACT) call into an instance that traps
+ *    (`ComponentInstanceState.enterFrom` clears `mayEnter` on the callee's
+ *    entering set only, task/mod.ts). A *different*, healthy task of that
+ *    caller, parked on an end of a stream/future the trapping callee also
+ *    held, was classified dead here and retired silently — stranded, the
+ *    exact outcome #66 exists to prevent.
+ *
+ * So the test consults the poison marker itself. It is per-instance and
+ * recorded at the single seam every bracket-break site routes through
+ * (`notifyInstancePoisoned`, task/scheduler.ts: exec/boundary.ts `poison`,
+ * `Store.tick`, `Thread.resumeWith`, the FACT cross-component catches in
+ * intrinsics/fact_calls.ts, and cabi/handles.ts's gated destructor call),
+ * and it is recorded *before* the retirement walk runs, so an instance's own
+ * parked ends still see it during its own walk. `retiredInstances` is
+ * consulted alongside it because the walk is also reachable directly (it is
+ * set at walk entry, so the two agree); neither ever contains the synthetic
+ * per-instantiation root, which every poison site skips or releases (plan v3
+ * amendment 4, `releaseSyntheticRootOnPoison`).
+ *
+ * Why this does not re-open review B2 (phantom events into a corpse): the
+ * concern is that a DROPPED event queued onto a waitable of an instance that
+ * can never be entered again would be serviced by a later driving loop and
+ * resume machinery whose `tick` asserts enterability. "Can never be entered
+ * again" is precisely poisoning — a mid-call instance's `mayEnter` is
+ * restored by its own `leaveTo` when the call returns, and its parked task
+ * then resumes normally and consumes the event. The narrowed predicate
+ * therefore excludes exactly the population B2 is about, and admits only
+ * peers that will run again.
+ *
+ * Used by the poisoning walk below and by the trapping-import abandonment
+ * path (embedder/instantiate.ts `releaseAsyncArgs`). Idempotent.
+ */
+export declare function dropSharedForTeardown(shared: SharedStreamImpl | SharedFutureImpl): void;
+/**
+ * Retire every live stream/future end in a trap-poisoned instance's handle
+ * table (#66).
+ *
+ * Rationale: after a trap breaks the enter/leave bracket, `mayEnter` stays
+ * false forever, so no task of this instance can ever rendezvous again. Its
+ * table's `CopyEnd`s are therefore unreachable-forever — leaving their shared
+ * objects live strands the peers: a parked HOST operation never settles (its
+ * promise hangs), and a LATER host operation would "succeed" against the
+ * corpse (a copy into memory nothing will ever read — silent data loss).
+ * Dropping the shared object now converts both into the spec-shaped DROPPED
+ * outcome, and the recorded failure lets the embedder layer brand it.
+ *
+ * Called from every bracket-break site — exec/boundary.ts `poison()` (the
+ * sync-lift path), scheduler.ts `Store.tick` and thread.ts
+ * `Thread.resumeWith` (traps during a resumed thread), and the FACT
+ * cross-component catches (intrinsics/fact_calls.ts, callee side) — with the
+ * trap as `cause`. Idempotent per instance. The parked-side notification
+ * discipline lives in `dropSharedForTeardown` above.
+ *
+ * Two refinements over the original #66 walk, both from #84:
+ *
+ *  1. FUTURES ARE NOT STREAMS. A `stream`'s reader may legitimately observe
+ *     DROPPED (that is end-of-stream), but a `future`'s reader may not
+ *     (definitions.py:2607) — the reference keeps the state unreachable by
+ *     trapping an early writable-end drop (definitions.py:1183-1184), which
+ *     a poisoned instance can no longer be made to do. So an unwritten
+ *     writable future end in this table marks its shared object *abandoned*
+ *     (first pass below) and its reader traps instead. A writable end that
+ *     already reached `CopyState.DONE` delivered its value; nothing is owed.
+ *
+ *  2. ONE END'S FAILURE MUST NOT STRAND THE REST. The notification of a
+ *     retired end runs arbitrary peer callbacks (host settlers, event
+ *     thunks); a throw used to abort the loop mid-table, leaving the
+ *     remaining ends live and their peers hanging — exactly the outcome this
+ *     walk exists to prevent. The walk now always completes and rethrows the
+ *     first failure afterwards.
+ */
+export declare function retireInstanceAsyncEnds(inst: PoisonedInstanceLike, cause: unknown): void;
+/**
+ * definitions.py models the debug message as a `String` triple; we keep the
+ * decoded JS string plus its encoding, which is all `store_string` needs.
+ */
+export declare class ErrorContext {
+    readonly debugMessage: string;
+    constructor(debugMessage: string);
+}
+export {};

package/types/task/subtask.d.ts

@@ -0,0 +1,96 @@
+import type { ResourceHandle } from "../cabi/handles.js";
+import type { CoreValue } from "../cabi/types.js";
+import { Waitable } from "./waitable.js";
+/** definitions.py `Subtask.State` (line 859). */
+export declare enum SubtaskState {
+    STARTING = 0,
+    STARTED = 1,
+    RETURNED = 2,
+    CANCELLED_BEFORE_STARTED = 3,
+    CANCELLED_BEFORE_RETURNED = 4
+}
+/**
+ * Anything that can be lent to a callee. `ResourceHandle` is the only
+ * implementor today; typed structurally so cabi's borrow-scope interfaces
+ * keep working unchanged.
+ */
+export interface Lendable {
+    numLends: number;
+}
+/** Cancellation callback handed back by a lifted callee (`OnCancel`). */
+export type OnCancel = (caller: any) => void;
+export declare class Subtask extends Waitable {
+    state: SubtaskState;
+    onCancel: OnCancel | null;
+    cancellationRequested: boolean;
+    flatResults: CoreValue[];
+    /**
+     * The callee TASK behind this subtask, when there is one (FACT
+     * cross-component calls; host-import subtasks have none). `subtask.cancel`
+     * needs it under jspi: a cancellation delivered to a suspended activation
+     * resumes it on a MICROTASK (the engine's, not ours), so the async form
+     * must wait until the callee's state is determinate before choosing
+     * between BLOCKED and the resolved state — the same determinacy question
+     * `async-start-call` answers, and it needs the same object to ask it of.
+     */
+    calleeTask: any;
+    /**
+     * Handles lent to the callee for the duration of the call. `null` once
+     * `deliverResolve` has run — the reference uses exactly this
+     * `lenders is None` sentinel to mean "resolve delivered" (line 908), so the
+     * nullability is semantic, not an optimization.
+     */
+    lenders: Lendable[] | null;
+    /** definitions.py `Subtask.resolved` (line 880). */
+    resolved(): boolean;
+    /** definitions.py `Subtask.add_lender` (line 890). */
+    addLender(h: Lendable): void;
+    /** definitions.py `Subtask.resolve` (line 895). */
+    resolve(state: SubtaskState, flatResults: CoreValue[]): void;
+    /** definitions.py `Subtask.deliver_resolve` (line 902). */
+    deliverResolve(): void;
+    /** definitions.py `Subtask.resolve_delivered` (line 908). */
+    resolveDelivered(): boolean;
+    /**
+     * Release a never-delivered subtask's lenders after its call broke off a
+     * non-poisoning exit — trap-rethrow past the CALLEE, capability bail, or
+     * an abandoned park (contracts/intrinsics.md v0.2 amendment 2, #91 scope
+     * clarification; the park legs are #102/#106).
+     *
+     * The reference has no analogue because it never resumes after a trap:
+     * the store dies with the lent handles inside it. The resolution state
+     * mirrors `canon_lower`'s `on_resolve(None)` branch (definitions.py
+     * line 2267): CANCELLED_BEFORE_STARTED if the callee never started,
+     * CANCELLED_BEFORE_RETURNED otherwise.
+     *
+     * Idempotent, and a no-op when the resolution was already delivered — a
+     * settled hook can call it unconditionally without disturbing the success
+     * path's own `deliverResolve`.
+     */
+    unwindLenders(): void;
+    /** definitions.py `Subtask.drop` (line 912). */
+    drop(): void;
+    /**
+     * definitions.py `canon_lower`'s `on_progress`/`subtask_event` closure
+     * (lines 2297-2298). The event payload is computed **at delivery time** and
+     * delivering it is what runs `deliver_resolve` — so the lent handles are
+     * released exactly when the guest observes the resolution, not when it
+     * happens.
+     *
+     * The `!this.resolveDelivered()` guard has no reference analogue: it exists
+     * so this can coexist with `unwindLenders()` (which may itself have already
+     * delivered the resolve on an abandoned path). The reference's
+     * `subtask_event` calls `deliver_resolve()` unconditionally and would
+     * assert on a double delivery.
+     */
+    setSubtaskPendingEvent(subtaski: number): void;
+}
+/**
+ * Pack a `canon_lower` async return value: `state | (subtaski << 4)`
+ * (definitions.py line 2306, with the accompanying asserts on the ranges).
+ */
+export declare function packSubtaskResult(state: SubtaskState, subtaski: number): number;
+/** Inverse of {@link packSubtaskResult}; used by tests mirroring the reference. */
+export declare function unpackSubtaskResult(packed: number): [state: SubtaskState, subtaski: number];
+/** Re-exported for callers that only import from this module. */
+export type { ResourceHandle };

package/types/task/thread.d.ts

@@ -0,0 +1,73 @@
+import { type BlockRequest, type Cancelled, type SchedulableThread, type ThreadBody } from "./scheduler.js";
+export declare class Thread implements SchedulableThread {
+    #private;
+    task: any;
+    /**
+     * Per-thread context slots (definitions.py `Thread.storage`, line 323 —
+     * initialised `[0,0]`). `canon_context_{get,set}` (lines 2348/2358) read and
+     * write *this*, not per-task state: two threads of the same task have
+     * independent context. wit-bindgen 0.60 keeps its async task pointer in
+     * slot 0.
+     *
+     * Slots are plain JS numbers: a `context.set` of an i64 value above
+     * 2^53-1 would lose precision. Moot while memory64/threads support is
+     * deferred (issue #12) — revisit this when that issue's closure lands.
+     */
+    readonly storage: number[];
+    /**
+     * The FACT sync-call bracket stack for THIS activation.
+     *
+     * `enter-sync-call` pushes and `exit-sync-call` pops; FACT emits both from
+     * the same activation, so the activation is the continuity that makes this a
+     * stack. See the note on `Task.syncCallStack` for why per-task was not
+     * enough.
+     */
+    readonly syncCallStack: any[];
+    /** Slot in `inst.threads`, assigned by `Task.registerThread`. */
+    index: number | null;
+    /** definitions.py `Thread.cancellable` — set at each block point. */
+    cancellable: boolean;
+    constructor(task: any, body: ThreadBody);
+    running(): boolean;
+    suspended(): boolean;
+    waiting(): boolean;
+    done(): boolean;
+    /** definitions.py `Thread.ready` (line 334). */
+    ready(): boolean;
+    /** definitions.py `Thread.resume_later` (line 361). */
+    resumeLater(): void;
+    /**
+     * definitions.py `Thread.resume` (line 366): run the body until it blocks
+     * again or finishes.
+     *
+     * The reference's loop over `switch_to` targets is omitted (see the module
+     * header). What remains is: leave the waiting list if we were on it, become
+     * the current thread, and step the generator with the cancelled flag.
+     */
+    /** Pending `awaitValue` promise, if this thread is parked on one. */
+    awaiting: Promise<unknown> | null;
+    /** Resume a promise-parked thread with the settled result. */
+    resumeWith(value: unknown, failure?: {
+        error: unknown;
+    }): void;
+    resume(cancelled?: Cancelled): void;
+    /**
+     * definitions.py `Thread.wait_until` (line 396), as a generator-side helper.
+     *
+     * Call it from a thread body with `yield*`:
+     *   `const cancelled = yield* thread.waitUntil(() => cond, true);`
+     *
+     * Deviation from the reference, deliberate: the reference may return
+     * immediately when `ready_func()` already holds
+     * (`if ready_func() and not DETERMINISTIC_PROFILE and random.randint(0,1)`).
+     * We always take the blocking path, i.e. we behave as the reference's
+     * `DETERMINISTIC_PROFILE`. Blocking-then-immediately-ready is observably
+     * equivalent (the scheduler will find this thread ready on the next
+     * candidate scan) and it removes a coin flip from every wait.
+     */
+    waitUntil(readyFunc: () => boolean, cancellable?: boolean): Generator<BlockRequest, Cancelled, Cancelled>;
+    /** definitions.py `Thread.suspend` (line 390). */
+    suspend(cancellable: boolean): Generator<BlockRequest, Cancelled, Cancelled>;
+    /** definitions.py `Thread.yield_` (line 405): `wait_until(lambda: True)`. */
+    yield_(cancellable: boolean): Generator<BlockRequest, Cancelled, Cancelled>;
+}

package/types/task/waitable.d.ts

@@ -0,0 +1,67 @@
+import type { BlockRequest, Cancelled } from "./scheduler.js";
+import type { Thread } from "./thread.js";
+/** definitions.py `EventCode` (line 756). */
+export declare enum EventCode {
+    NONE = 0,
+    SUBTASK = 1,
+    STREAM_READ = 2,
+    STREAM_WRITE = 3,
+    FUTURE_READ = 4,
+    FUTURE_WRITE = 5,
+    TASK_CANCELLED = 6
+}
+/** definitions.py `EventTuple` = `(EventCode, int, int)`. */
+export type EventTuple = [code: EventCode, p1: number, p2: number];
+export declare const NO_EVENT: EventTuple;
+/**
+ * definitions.py `class Waitable` (line 767).
+ *
+ * The pending event is a **thunk**, not a value: the reference computes the
+ * payload at delivery time (`get_pending_event` calls it), which is what lets
+ * a subtask report its *final* state even if it advanced between the event
+ * being set and being read. Keeping the thunk is load-bearing — see
+ * `Subtask.setPendingEvent`.
+ */
+export declare class Waitable {
+    pendingEvent: (() => EventTuple) | null;
+    wset: WaitableSet | null;
+    hasSyncWaiter: boolean;
+    setPendingEvent(pendingEvent: () => EventTuple): void;
+    hasPendingEvent(): boolean;
+    inWaitableSet(): boolean;
+    /**
+     * definitions.py `Waitable.wait_for_pending_event` (line 786): a
+     * *non-cancellable* block until this waitable has an event, used by the
+     * synchronous `subtask.cancel` path.
+     */
+    waitForPendingEvent(thread: Thread): Generator<BlockRequest, void, Cancelled>;
+    getPendingEvent(): EventTuple;
+    /** definitions.py `Waitable.join` (line 797). */
+    join(wset: WaitableSet | null): void;
+    /** definitions.py `Waitable.drop` (line 805). */
+    drop(): void;
+}
+/** definitions.py `class WaitableSet` (line 810). */
+export declare class WaitableSet {
+    readonly elems: Waitable[];
+    numWaiting: number;
+    hasPendingEvent(): boolean;
+    /**
+     * definitions.py `WaitableSet.get_pending_event` (line 821). The reference
+     * shuffles `elems` before scanning; we scan in **join order** under the
+     * default FIFO policy (`chooseCandidate` over the ready elements), which is
+     * within the same allowed nondeterminism — see scheduler.ts's policy note.
+     */
+    getPendingEvent(): EventTuple;
+    /** definitions.py `WaitableSet.wait_for_event_and` (line 829). */
+    waitForEventAnd(thread: Thread, readyFunc: () => boolean, cancellable: boolean): Generator<BlockRequest, EventTuple, Cancelled>;
+    /** definitions.py `WaitableSet.wait_for_event` (line 841). */
+    waitForEvent(thread: Thread, cancellable: boolean): Generator<BlockRequest, EventTuple, Cancelled>;
+    /**
+     * definitions.py `WaitableSet.poll` (line 844). Never blocks, so it is a
+     * plain function rather than a generator.
+     */
+    poll(task: any, cancellable: boolean): EventTuple;
+    /** definitions.py `WaitableSet.drop` (line 852). */
+    drop(): void;
+}