@polyengine/runtime 0.1.0-pre.g633468a

package/types/plan/loader.d.ts

@@ -0,0 +1,113 @@
+import { type FuncType, ResourceTypeInfo, type ValType } from "../cabi/types.js";
+import type { WireErrorDetail, WirePlan, WireValType } from "./format.js";
+/** Fault in the plan document itself (version/shape/reference errors). */
+export declare class PlanError extends Error {
+    constructor(message: string);
+}
+/**
+ * A structured translation verdict from the shim (envelope `errorDetail`).
+ *
+ * Distinguished from `PlanError` on purpose: a `TranslateError` with
+ * `phase === "validation"` is *the translator's judgment about the input
+ * component* and is the only failure that satisfies `assert_invalid` /
+ * `assert_malformed`. `PlanError` and the other phases are failures of our
+ * own pipeline and must never be scored as conformance passes.
+ */
+export declare class TranslateError extends Error {
+    readonly phase: WireErrorDetail["phase"];
+    readonly detail: string;
+    constructor(d: WireErrorDetail);
+    /** True iff the shim judged the *input component* invalid or malformed. */
+    get isValidationVerdict(): boolean;
+}
+/**
+ * The single formatVersion this executor understands.
+ *
+ * v4 (2026-08-17, polyengine#13): `exports[]` gained the `"module"` kind — a
+ * component exporting one of its own embedded core modules, surfaced as the
+ * already-compiled `WebAssembly.Module`.
+ * v3 (2026-08-10, polyengine#89): `errorContextTables` — the index space the
+ * `error-context-transfer` trampoline actually uses (it was resolved through
+ * 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
+ * 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
+ * equality check ("Validate `formatVersion` and fail fast on mismatch",
+ * producer and consumer bumped in the same commit), so v0 plans are refused
+ * rather than best-effort accepted — a stale cached artifact must be a loud
+ * failure, not a subtly different execution.
+ */
+export declare const SUPPORTED_FORMAT_VERSION = 4;
+/** A types-table entry after conversion. */
+export type LoadedType = {
+    kind: "func";
+    funcType: FuncType;
+    paramNames: string[];
+} | {
+    kind: "value";
+    type: ValType;
+};
+export interface LoadedPlan {
+    wire: WirePlan;
+    /** Converted types table, index-aligned with `wire.types`. */
+    types: LoadedType[];
+    /**
+     * Identity tokens for resource tables, index-aligned with
+     * `wire.resourceTables`. The executor fills `impl`/`dtor` while running
+     * `resource` initializers.
+     */
+    resourceTokens: ResourceTypeInfo[];
+    /**
+     * Number of imported resource types. `ResourceIndex =
+     * numImportedResources + DefinedResourceIndex`
+     * (plan-format.md v0.1 amendment #2 / v0.2 `importedResources`).
+     */
+    numImportedResources: number;
+    /** Element type per stream table (plan v2); `null` = zero-width payload. */
+    streamElems: (ValType | null)[];
+    /** Element type per future table (plan v2). */
+    futureElems: (ValType | null)[];
+    /** Owning component instance per stream/future table (plan v2). */
+    streamTableInstances: number[];
+    futureTableInstances: number[];
+    /**
+     * Owning component instance per error-context table (plan v3), index space
+     * == `TypeComponentLocalErrorContextTableIndex`.
+     */
+    errorContextTableInstances: number[];
+    /**
+     * Raw wasmtime `TypeTupleIndex` -> `plan.types` index, collected from the
+     * `task-return` trampolines (plan v3). The key is what FACT's
+     * `prepare-call` passes as `task_return_type` at runtime; the value is the
+     * interned tuple type. A callee with no `task.return` trampoline of its own
+     * (a sync-lifted callee) contributes no entry, and the lookup then reports
+     * "unknown" rather than guessing.
+     */
+    resultTupleTypes: Map<number, number>;
+}
+/**
+ * Validate a plan document and convert its type tables. Fails fast on
+ * formatVersion mismatch per contracts/plan-format.md "Executor obligations".
+ */
+export declare function loadPlan(wire: WirePlan): LoadedPlan;
+/**
+ * Component-wide `ResourceIndex` for a `DefinedResourceIndex` (the `index`
+ * field of a `resource` initializer). Mirrors wasmtime
+ * `Component::resource_index` (wasmtime-environ 47.0.3
+ * `component/info.rs:222`).
+ */
+export declare function resourceIndexOfDefined(plan: LoadedPlan, definedIndex: number): number;
+/**
+ * Parse the shim's C-ABI JSON envelope into a validated wire plan + adapter
+ * bytes. The plan is validated (formatVersion, type tables) but returned in
+ * wire form: the executor re-runs `loadPlan` per instantiation so resource
+ * identity tokens are fresh per component instance.
+ */
+export declare function loadEnvelope(json: string): {
+    wire: WirePlan;
+    adapters: Map<string, Uint8Array>;
+};
+export declare function loadValType(t: WireValType, resourceTokens: ResourceTypeInfo[], where: string): ValType;

package/types/plan/mod.d.ts

@@ -0,0 +1,2 @@
+export * from "./format.js";
+export * from "./loader.js";

package/types/shim/mod.d.ts

@@ -0,0 +1 @@
+export * from "./translator.js";

package/types/shim/translator.d.ts

@@ -0,0 +1,55 @@
+import type { WirePlan } from "../plan/format.js";
+export interface TranslationResult {
+    plan: WirePlan;
+    /** Adapter artifacts keyed by `plan.modules[].file`. */
+    adapters: Map<string, Uint8Array>;
+    /** The raw envelope JSON (byte-exact; useful for determinism checks). */
+    envelopeJson: string;
+}
+/** An instantiated translator shim. One instance is reusable across calls. */
+export declare class Translator {
+    #private;
+    /**
+     * sha256 of the shim wasm bytes this instance was built from, hex-encoded;
+     * `null` when constructed from a pre-compiled `WebAssembly.Module` with no
+     * bytes available (module identity can't be recovered post-compile).
+     *
+     * This is the honest translator "build hash" for the artifact cache
+     * (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
+     * component for translator identity.
+     */
+    readonly buildHash: string | null;
+    private constructor();
+    /** Instantiate from compiled module or raw wasm bytes. */
+    static create(source: WebAssembly.Module | Uint8Array): Promise<Translator>;
+    /**
+     * Wrap an ALREADY-INSTANTIATED shim — the ESM wasm-module import path
+     * (issue #16 delivery design): `import * as shim from ".../translator_shim.wasm"`
+     * hands back an instantiated namespace (the shim imports nothing, so the
+     * ESM integration instantiates it trivially), and this wraps it with no
+     * further compile or copy.
+     *
+     * Sharing note: ESM gives ONE instance per realm, so every `fromExports`
+     * wrapper over the same namespace shares linear memory. That is safe by
+     * construction — `translate` is synchronous end-to-end (alloc → call →
+     * copy out → dealloc within one JS frame), so calls can never interleave —
+     * but treat the wrappers as equivalent, not independent.
+     *
+     * `buildHash` (hex sha-256 of the shim wasm bytes) cannot be recovered
+     * from an instance; pass it when known — a published package can ship the
+     * hash of the exact asset it carries — or leave it absent and the
+     * artifact cache politely refuses to key on translator identity
+     * (cache/core.ts).
+     */
+    static fromExports(exports: object, opts?: {
+        buildHash?: string;
+    }): Translator;
+    /** Translate a component binary into plan v0 + adapter artifacts. */
+    translate(componentBytes: Uint8Array): TranslationResult;
+    /** Translate, returning the raw envelope JSON without validation. */
+    translateRaw(componentBytes: Uint8Array): string;
+}

package/types/task/mod.d.ts

@@ -0,0 +1,257 @@
+import { Table } from "../cabi/handles.js";
+import type { ComponentInstanceLike } from "../cabi/context.js";
+import type { ComponentValue, FuncType } from "../cabi/types.js";
+import { type Cancelled, Store } from "./scheduler.js";
+import { Thread } from "./thread.js";
+import { Waitable, WaitableSet } from "./waitable.js";
+import { Subtask } from "./subtask.js";
+export * from "./scheduler.js";
+export * from "./thread.js";
+export * from "./waitable.js";
+export * from "./subtask.js";
+export * from "./streams.js";
+/** Constructor marker: "this one IS the root, do not give it a parent". */
+declare const ROOT_TOKEN: unique symbol;
+/** Anything a component instance's handle table can hold. */
+export type HandleTableEntry = unknown;
+/**
+ * Per-component-instance runtime state (definitions.py `ComponentInstance`,
+ * line 191).
+ *
+ * `mayLeave` is backed by a real `WebAssembly.Global(i32, mutable)` because
+ * FACT adapters import that global (`flags` namespace) and read/write it as
+ * the may_leave boolean (wasmtime 47 FACT treats the whole flags global as
+ * may_leave; there is no bitmask). Initial value 1 (true). `mayEnter` is
+ * host-side state: nothing wasm-visible reads it.
+ */
+export declare class ComponentInstanceState implements ComponentInstanceLike {
+    readonly index: number;
+    readonly flags: WebAssembly.Global;
+    handles: Table<HandleTableEntry>;
+    /** definitions.py `ComponentInstance.threads` — a Table, so `thread.index`. */
+    readonly threads: Table<Thread>;
+    mayEnter: boolean;
+    /** definitions.py `backpressure: int` — a *counter* (backpressure.{inc,dec}). */
+    backpressure: number;
+    /** definitions.py `num_waiting_to_enter`. */
+    numWaitingToEnter: number;
+    /** definitions.py `exclusive_thread`. */
+    exclusiveThread: Thread | null;
+    /**
+     * definitions.py `ComponentInstance.parent`.
+     *
+     * The plan still gives us a flat instance space, but the tree is no longer
+     * needed: every instance of one instantiation gets the same **synthetic
+     * root** as its parent (contracts/plan-format.md v3 amendment 4 /
+     * polyengine#101). See `enteringSet` for why that is observably equivalent to
+     * the real chain. The root itself has no parent.
+     */
+    parent: ComponentInstanceState | null;
+    readonly store: Store;
+    /**
+     * The synthetic per-instantiation root (v3 amendment 4). One per `Store`:
+     * a `Store` is exactly one component instantiation's scheduling scope, so
+     * "all `ComponentInstanceState`s sharing a `Store`" is the set that shares
+     * a top-level component — which is the granularity wasmtime's own
+     * top-level-instance-id comparison uses (concurrent.rs:1876-1886).
+     *
+     * It is a real `ComponentInstanceState` (index -1) rather than a bare flag
+     * so it flows through `selfAndAncestors`/`enteringSet` unchanged; its
+     * handle table stays empty and no task ever runs on it.
+     */
+    static rootOf(store: Store): ComponentInstanceState;
+    /** Is this the synthetic root (never a real component instance)? */
+    get isSyntheticRoot(): boolean;
+    constructor(index: number, store?: Store, root?: typeof ROOT_TOKEN);
+    /**
+     * Release the synthetic root after a trap broke the enter/leave bracket
+     * (v3 amendment 4, and a **named divergence** from the reference).
+     *
+     * definitions.py poisons the whole entering set: `Store.lift` never reaches
+     * `leave_to`, so the root — which is in every host entry's entering set —
+     * stays `may_enter == False` forever and NO instance of the component can
+     * be entered again. wasmtime is the same by other means (it poisons the
+     * store). polyengine deliberately supports post-trap re-entry of instances the
+     * trap did not touch (exec/boundary.ts `poison`: "sibling instances stay
+     * usable, which is why the lock is released per-instance rather than by
+     * poisoning a whole store the way wasmtime does"), and the synthetic root
+     * must not silently convert that documented divergence into store-wide
+     * poisoning. So a trap poisons the LEAF set only, and the root is released
+     * here — the reentrance gate the root exists for (a *second, concurrent*
+     * host entry) is about a live entry, and after a trap unwinds to the host
+     * there is none.
+     */
+    releaseSyntheticRootOnPoison(): void;
+    get mayLeave(): boolean;
+    set mayLeave(v: boolean);
+    /** definitions.py `ComponentInstance.self_and_ancestors` (line 236). */
+    selfAndAncestors(): Set<ComponentInstanceState>;
+    /**
+     * definitions.py `ComponentInstance.entering_set` (line 230):
+     * `self_and_ancestors() - caller.self_and_ancestors()`.
+     *
+     * CONTRACT (contracts/plan-format.md v3 amendment 4, polyengine#101): the plan
+     * still carries no wire form for the component-instance tree, and it no
+     * longer needs one. Every instance's parent is the synthetic
+     * per-instantiation root, so:
+     *
+     *   * host entry (`caller === null`): `{this, root}` — the reference's
+     *     entering set for a host entry is `self_and_ancestors()`, which always
+     *     contains the top-level root, so a second host entry anywhere in the
+     *     tree trips on the root either way. This is the divergence #101
+     *     reported (host -> A.f -> host import -> host enters a *different*
+     *     instance): now caught.
+     *   * guest-to-guest (`caller !== null`): `{this}` — the root is in the
+     *     caller's ancestor set and cancels out. Intermediate ancestors would
+     *     be the only difference from the real chain, and they are never
+     *     reachably consulted: FACT compiles same-instance and ancestor calls
+     *     to unconditional compile-time traps, and sibling cycles are
+     *     unreachable because instance imports form a DAG (polyengine#99
+     *     adjudication).
+     *
+     * So the synthetic root is observably equivalent to the full chain, and it
+     * matches wasmtime's own shortcut — a top-level instance-id comparison
+     * (concurrent.rs:1876-1886) — by construction. This reopens only if some
+     * future upstream shape makes nesting depth observable.
+     *
+     * One deliberate departure remains, at the trap path rather than here: see
+     * `releaseSyntheticRootOnPoison`.
+     */
+    enteringSet(caller: ComponentInstanceState | null): Set<ComponentInstanceState>;
+    /** definitions.py `ComponentInstance.may_enter_from` (line 214). */
+    mayEnterFrom(caller: ComponentInstanceState | null): boolean;
+    /** definitions.py `ComponentInstance.enter_from` (line 220). */
+    enterFrom(caller: ComponentInstanceState | null): void;
+    /** definitions.py `ComponentInstance.leave_to` (line 225). */
+    leaveTo(caller: ComponentInstanceState | null): void;
+    /** Backwards-compatible host-entry helpers (the M0 spelling). */
+    enter(): void;
+    leave(): void;
+}
+/** definitions.py `Task.State` (line 445). */
+export type TaskState = "initial" | "started" | "pending-cancel" | "cancel-delivered" | "resolved";
+export type OnStart = () => ComponentValue[];
+export type OnResolve = (result: ComponentValue[] | null) => void;
+/**
+ * Canonical options as the task model needs to see them (definitions.py
+ * `Task.opts`): only the two flags that change task *semantics*.
+ */
+export interface TaskOptions {
+    async_: boolean;
+    callback: boolean;
+    /**
+     * The two fields definitions.py's `LiftOptions.equal` (line 643) compares.
+     * `canon_task_return` requires the options at the `task.return` site to
+     * equal the ones the task was lifted with, so the task has to remember
+     * them.
+     */
+    stringEncoding: string;
+    memory: unknown | null;
+}
+/** definitions.py `LiftOptions.equal` (line 643): encoding + memory identity. */
+export declare function liftOptionsEqual(a: {
+    stringEncoding: string;
+    memory: unknown | null;
+}, b: {
+    stringEncoding: string;
+    memory: unknown | null;
+}): boolean;
+export declare class Task {
+    ft: FuncType;
+    opts: TaskOptions;
+    inst: ComponentInstanceState;
+    onStart: OnStart;
+    onResolve: OnResolve;
+    state: TaskState;
+    /** TaskBorrowScope (cabi/context.ts): live borrows lowered into this task. */
+    numBorrows: number;
+    implicitThread: Thread | null;
+    readonly threads: Thread[];
+    /**
+     * True for a task created by a FACT cross-component call
+     * (`prepare-call`, see intrinsics/fact_calls.ts).
+     *
+     * Such a task's `onStart` / `onResolve` carry **flat core values**, not
+     * lifted component values: FACT fuses the caller-side lift and callee-side
+     * lower into a pair of adapter functions (`[async-start]` / `[async-return]`)
+     * that run *in wasm*, so the host only shuttles the core values between
+     * them. definitions.py has no analogue because it has no fused adapters —
+     * there, `canon_lift` lowers the params and `canon_lower`'s `on_resolve`
+     * lifts the results, both in the host. The observable semantics are
+     * identical; only which side of the boundary performs the copy differs.
+     *
+     * `canon_task_return` consults this to decide whether to lift its flat
+     * arguments (host-boundary task) or pass them straight through (FACT task).
+     */
+    factPassthrough: boolean;
+    /**
+     * Plan v3: does `ft.results` hold this FACT task's *declared* result type?
+     *
+     * A FACT callee task's result type arrives as the raw wasmtime
+     * `TypeTupleIndex` `prepare-call` passes as `task_return_type`; v3's
+     * `task-return.results` / `resultType` pair is the dictionary for it
+     * (contracts/plan-format.md v3 amendment 3). It resolves for every callee
+     * that has a `task.return` trampoline of its own — which is every callee
+     * that can call `task.return` — but a callee with none (sync-lifted,
+     * reached through an async-to-sync adapter) contributes no entry, and then
+     * `ft.results` is the empty placeholder it was before v3. Only when this is
+     * true may `canon_task_return` compare against it.
+     */
+    factResultTypesKnown: boolean;
+    /**
+     * In-flight FACT sync-call brackets for THIS task
+     * (`enter-sync-call`/`exit-sync-call`).
+     *
+     * MOVED to `Thread` (see `Thread.syncCallStack`). Per-task was already an
+     * improvement on per-executor, but it is still not the right unit: a task
+     * can own several threads, so one activation's `exit-sync-call` could pop a
+     * sibling activation's scope. Tracing big-interleaving showed exactly that
+     * -- tasks whose `enter` count exceeded their `exit` count by one, and other
+     * tasks taking an `exit` at depth 0, with the `ctx` fallback never firing.
+     *
+     * The bracket belongs to the ACTIVATION that opened it: FACT emits the
+     * matching `enter-sync-call` and `exit-sync-call` from the same wasm
+     * activation by construction, so riding the activation identity makes the
+     * exit find the same stack the enter used no matter which task the scheduler
+     * considers current in between (the 3i bracket-spans-suspension ruling).
+     */
+    constructor(ft: FuncType, opts: TaskOptions, inst: ComponentInstanceState, onStart: OnStart, onResolve: OnResolve);
+    /**
+     * definitions.py `Task.needs_exclusive` (line 473): an async-typed task
+     * needs the instance's exclusive thread unless it is a *stackful* async
+     * lift. Sync-lowered (`not opts.async_`) and callback-ABI tasks both do.
+     */
+    needsExclusive(): boolean;
+    /**
+     * definitions.py `Task.enter_implicit_thread` (line 477) — the backpressure
+     * and exclusivity gate, in full.
+     *
+     * Returns false when the task was cancelled while waiting to enter, in
+     * which case the caller must return immediately (the task is already
+     * resolved by `cancel()`).
+     */
+    enterImplicitThread(thread: Thread): Generator<import("./scheduler.js").BlockRequest, boolean, Cancelled>;
+    /** definitions.py `Task.register_thread` (line 497). */
+    registerThread(thread: Thread): void;
+    /** definitions.py `Task.exit_implicit_thread` (line 503). */
+    exitImplicitThread(thread: Thread): void;
+    /** definitions.py `Task.unregister_thread` (line 510). */
+    unregisterThread(thread: Thread): void;
+    /**
+     * definitions.py `Task.request_cancellation` (line 519). Delivered to a
+     * cancellable thread if one exists and the instance is enterable; otherwise
+     * recorded as pending, to be picked up at the next cancellable block point
+     * (`deliverPendingCancel`).
+     */
+    requestCancellation(caller: ComponentInstanceState | null): void;
+    /** definitions.py `Task.deliver_pending_cancel` (line 536). */
+    deliverPendingCancel(cancellable: boolean): boolean;
+    /** definitions.py `Task.start` (line 542). */
+    start(): ComponentValue[];
+    /** definitions.py `Task.return_` (line 547). */
+    return_(result: ComponentValue[]): void;
+    /** definitions.py `Task.cancel` (line 554). */
+    cancel(): void;
+}
+/** Convenience re-exports so `../task/mod.ts` remains the single entry point. */
+export { Store, Subtask, Thread, Waitable, WaitableSet };