@polyengine/runtime 0.1.0-pre.g633468a

package/types/exec/boundary.d.ts

@@ -0,0 +1,360 @@
+import { type CanonicalOptions, type ComponentValue, type CoreFuncType, type CoreType, type CoreValue, type FuncType, type PtrType, ResourceTypeInfo } from "../cabi/mod.js";
+import { type BlockRequest, type Cancelled, ComponentInstanceState, Store, Task, Thread } from "../task/mod.js";
+import { type SuspensionMode } from "../jspi/mod.js";
+/**
+ * Structural view of an intrinsics `SyncCallScope`: everything this module
+ * needs in order to unwind a FACT sync-call bracket a trap escaped.
+ */
+export interface LenderScope {
+    releaseLenders(): void;
+}
+/** A raw core function as exposed through the JS WebAssembly API. */
+export type CoreFn = (...args: any[]) => unknown;
+/** Counters exposed for tests/diagnostics on the component handle. */
+export interface ExecutionStats {
+    liftedCalls: number;
+    tasksResolved: number;
+    postReturnsRun: number;
+    loweredCalls: number;
+    enterSyncCalls: number;
+    exitSyncCalls: number;
+    /** Callback-export invocations of the async lift loop (`canon_lift`). */
+    callbackInvocations: number;
+}
+export declare function newStats(): ExecutionStats;
+/**
+ * A `MemInst`-shaped view over a `WebAssembly.Memory` that never goes stale:
+ * `bytes`/`view` re-derive from `memory.buffer` whenever the buffer identity
+ * changes (memory.grow detaches the previous ArrayBuffer — a cached
+ * Uint8Array would silently drop writes). The provider indirection also
+ * covers plan-order effects: canonical options can reference a memory whose
+ * `extract-memory` initializer runs later; accesses before extraction fail
+ * with a PlanError.
+ *
+ * Structurally compatible with cabi's `MemInst` (same public surface).
+ */
+export declare class LiveMemory {
+    #private;
+    readonly addrType: PtrType;
+    constructor(provider: () => WebAssembly.Memory | undefined, label: string);
+    get bytes(): Uint8Array;
+    get view(): DataView;
+    get length(): number;
+    ptrType(): PtrType;
+    ptrSize(): 4 | 8;
+}
+/**
+ * Canonical options resolved against executor state. `memory` is a
+ * LiveMemory (or null); `realloc`/`postReturn`/`callback` resolve lazily so
+ * options can be constructed before the corresponding extract initializers
+ * run (wasmtime semantics: options hold indices, resolved at use).
+ */
+export interface ResolvedOptions {
+    stringEncoding: "utf8" | "utf16" | "latin1+utf16";
+    memory: LiveMemory | null;
+    realloc: (() => CoreFn | undefined) | null;
+    postReturn: (() => CoreFn | undefined) | null;
+    callback: (() => CoreFn | undefined) | null;
+    async: boolean;
+    /**
+     * `CanonicalOptions.cancellable` (wasmtime-environ 47.0.3
+     * `component/info.rs:540`), i.e. whether a built-in reached through these
+     * options is a *cancellable* block point.
+     *
+     * It lives in the options, not in the trampoline: `Trampoline::
+     * WaitableSetWait`/`WaitableSetPoll` carry only `{instance, options}`
+     * (info.rs:815-831). definitions.py takes it as the first parameter of
+     * `canon_waitable_set_wait` / `canon_waitable_set_poll` (lines 2414/2431),
+     * which is the same information arriving by a different route.
+     *
+     * (`thread.yield` and `subtask.cancel` are the exceptions: wasmtime puts
+     * their `cancellable` / `async` flags on the *trampoline*, and those
+     * built-ins read them from the decl.)
+     */
+    cancellable: boolean;
+    coreType: CoreFuncType;
+    instance: ComponentInstanceState;
+}
+/** cabi-facing options object (LiftLowerOptions + flatten inputs). */
+export declare function cabiOptions(opts: ResolvedOptions): CanonicalOptions;
+/**
+ * Call a core function, mapping core-wasm exceptions to canonical-ABI traps
+ * (reference `call_and_trap_on_throw`). Component traps and internal errors
+ * of ours propagate unchanged.
+ */
+/**
+ * Layering rule: a core-wasm trap's message is engine-specific text (V8,
+ * SpiderMonkey, JSC each word `unreachable` differently, for instance) and is
+ * passed through here UNTOUCHED — it is diagnostics only, "engine-flavored"
+ * and not normalized to any particular host's wording. The runtime never
+ * emulates another host's (e.g. wasmtime's) message text.
+ *
+ * Suite-wording normalization (matching the official test suite's
+ * `assert_trap` expectations, which are typically worded per wasmtime) lives
+ * in the harness instead: see `TRAP_MESSAGE_EQUIVALENTS` in
+ * harness/src/runner.ts, which maps engine-specific spellings to the
+ * suite-expected forms at comparison time. (The FACT *adapter* traps take a
+ * different route entirely — they arrive as numeric codes through the `trap`
+ * trampoline and are runtime-authored text, see `FACT_TRAP_MESSAGES` in
+ * intrinsics/mod.ts; that table is untouched by this layering rule.)
+ */
+export declare function callCore(fn: CoreFn, args: CoreValue[]): CoreValue[];
+/**
+ * Normalize raw JS-API core values to cabi's canonical lane representation:
+ * i32 lanes as unsigned numbers (the JS API yields signed), i64 lanes as
+ * unsigned bigints, floats as numbers.
+ */
+export declare function normalizeCoreValues(values: CoreValue[], lanes: CoreType[], what: string): CoreValue[];
+/**
+ * THE asynchronous driving loop, exported for the one other driver in the
+ * runtime: `HostActivity` in exec/host_streams.ts, which must pump the store
+ * BETWEEN export calls (when no lifted call is in flight) with exactly these
+ * semantics — service settled tails, tick to quiescence, then await the race
+ * of every outstanding promise (parked activations AND `pendingHostCalls`),
+ * repeat. Reimplementing it there diverged: that copy only drained
+ * `store.awaiting` and never awaited `pendingHostCalls`, so a guest parked on
+ * a Promise-returning host import was never resumed and the host's read of
+ * the stream it was feeding hung (C0 finding R-1).
+ *
+ * Callers that must not hit the deadlock traps below (the host pump: an
+ * embedder that never does its half is documented to hang, not trap) can
+ * exclude them entirely — BOTH trap sites require
+ * `store.pendingHostCalls.size === 0`, and both are reached only through the
+ * synchronous fall-through from `done()`, so a `done` that returns true
+ * whenever `pendingHostCalls` is empty provably never traps.
+ */
+export declare function driveStoreAsync(store: Store, done: () => boolean, what: string): Promise<void>;
+export declare function storeDriverDepth(store: Store): number;
+/** Resolves once no `driveAsync` loop is live on `store`. */
+export declare function whenStoreDriverIdle(store: Store): Promise<void>;
+/**
+ * Ensure a settlement pump is watching `store`'s real outstanding host calls.
+ * Idempotent and cheap; called at every driver exit. Never throws.
+ */
+export declare function ensureSettlementPump(store: Store): void;
+/**
+ * Build the host-callable function for one lifted export (reference
+ * `Store.lift` + `canon_lift`, definitions.py lines 578 and 2154).
+ *
+ * All three lift shapes go through one `Task` + implicit `Thread`:
+ *
+ *   * **sync** (`not ft.async`) — call, lift results, `task.return_`,
+ *     post-return, then the sync driving loop until the task resolves;
+ *   * **async + callback** (stackless) — the packed-code loop
+ *     (EXIT / YIELD / WAIT), fully implemented here;
+ *   * **async, no callback** (stackful) — the guest blocks mid-stack, which
+ *     needs genuine wasm-frame suspension: `needsJspi`, at the precise point.
+ */
+/**
+ * The plain-entered variant of a `[constructor]` export in jspi mode,
+ * attached to the promising-wrapped lifted function under this symbol.
+ *
+ * A WIT constructor is surfaced as a JS class constructor
+ * (contracts/embedder-api.md §"Resources"), and a JS constructor cannot
+ * await — but in jspi mode every promising-wrapped entry returns a Promise
+ * even when the activation completes without suspending (jspi pin (e)). So
+ * constructor exports carry a second lifted function whose ENTRY is plain
+ * (unwrapped): a constructor that completes synchronously — the
+ * overwhelmingly common case; WIT constructors are always sync-typed —
+ * returns its rep synchronously through it.
+ *
+ * The cost is confined to genuinely-suspending constructors, which no JS
+ * host can surface as `new` anyway: a blocking built-in reached through the
+ * plain entry signals `NeedsJspi` (a capability error, instance left
+ * enterable), and a Suspending-wrapped host import reached from the
+ * unwrapped frame fails as a trap. Both name the constructor rather than
+ * silently deadlocking.
+ */
+export declare const CONSTRUCTOR_SYNC_ENTRY: unique symbol;
+export declare function createLiftedFunction(input: {
+    name: string;
+    ft: FuncType;
+    opts: ResolvedOptions;
+    core: CoreFn;
+    stats: ExecutionStats;
+    /**
+     * Suspension discipline for this instantiation (jspi/bridge.ts). In `jspi`
+     * mode the export's core function is `promising`-wrapped, so the whole
+     * activation can suspend and the lifted function necessarily returns a
+     * Promise.
+     */
+    suspensionMode?: SuspensionMode;
+    /** Optional; see intrinsics `HostTrapState`. */
+    trapState?: {
+        pending: unknown;
+    };
+    /**
+     * Optional; the executor's sync-call scope stack (intrinsics
+     * `SyncCallScope`). Structural, to keep this module free of an import
+     * cycle with `../intrinsics/`.
+     */
+    syncCallStack?: LenderScope[];
+    /**
+     * Optional; every component instance of this component, for restoring
+     * `may_leave` when a trap unwinds out of a FACT adapter.
+     */
+    allInstances?: () => Iterable<{
+        mayLeave: boolean;
+    }>;
+    /**
+     * Opt out of the reference's *synchronous* driving loop (`driveSyncLift`,
+     * definitions.py `canon_lift` line 2213) for a sync-typed lift whose caller
+     * does not need a synchronous answer — today only the host-initiated
+     * resource destructor (#160; `createDtorEntry` below, `drop(): void` is
+     * documented non-blocking).
+     *
+     * This is not a weakening of the deadlock trap: `drive` below enforces the
+     * same "no ready thread, no pending host call, nothing awaiting" trap, just
+     * asynchronously — which is exactly the substitution jspi mode already
+     * makes unconditionally (see the comment at the `driveSyncLift` call).
+     * It matters only when a *plain*-mode core returns a thenable, i.e. a
+     * host-supplied JS destructor: the sync loop sees a thread parked on a
+     * Promise, which it can never advance, and declares a bogus deadlock.
+     */
+    allowAsyncCompletion?: boolean;
+}): (...args: ComponentValue[]) => unknown;
+/**
+ * Build the host-callable entry for a resource destructor — a full canonical
+ * **lift**, exactly as definitions.py `canon_resource_drop` (line 2319) does:
+ *
+ * ```python
+ *   opts = CanonicalOptions(async_ = False)
+ *   ft = FuncType([U32Type()], [], async_ = False)
+ *   dtor = rt.dtor or (lambda rep: [])
+ *   callee = inst.store.lift(dtor, ft, opts, rt.impl)
+ * ```
+ *
+ * Before #160 the host-initiated path (embedder `drop()`, the GC backstop,
+ * `dropOwn`) hand-rolled the bracket in cabi/handles.ts `callDtorGated`: a
+ * bare call to the dtor with `enterFrom(null)` HELD across the returned
+ * promise. Three defects followed from having no Task/Thread behind the
+ * activation:
+ *
+ *  - **#160 itself**: the held bracket left the impl instance non-enterable,
+ *    so `Store.tick`'s enterability filter (#155) could never resume a
+ *    suspension point belonging to the dtor's own activation. The completion
+ *    promise sat in `pendingHostCalls` looking like external work, and every
+ *    driver parked on it forever.
+ *  - it was the runtime's only `enterFrom(null)` bracket spanning an await —
+ *    the macro-scale reachability window of the #156 class, through which a
+ *    sibling instance looked non-enterable from the synthetic root.
+ *  - built-ins reached inside the dtor had no ambient task (`currentTask()`
+ *    → `PendingCapability`, or a foreign-task misattribution, the #24 class).
+ *
+ * Under the lift harness all three go away structurally: the activation has a
+ * real `Task` + implicit `Thread`, the entry bracket is released when the
+ * first segment parks (`leave()` before `drive`), and settled tails flow
+ * through `serviceSettled` like any other lifted sync call.
+ *
+ * The returned function takes the rep and returns either `undefined` (the
+ * activation completed synchronously — the overwhelmingly common case) or a
+ * Promise, exactly like any lifted sync export in jspi mode.
+ */
+export declare function createDtorEntry(input: {
+    /** Diagnostic name; appears in deadlock/trap messages. */
+    name?: string;
+    /**
+     * The destructor's core function, unwrapped: `createLiftedFunction` applies
+     * `enterWasm` itself per `suspensionMode`. `null` is the reference's
+     * `rt.dtor or (lambda rep: [])` — the bracket still runs.
+     */
+    dtor: CoreFn | null;
+    /** `rt.impl`, the implementing instance the lift enters. */
+    instance: ComponentInstanceState;
+    suspensionMode?: SuspensionMode;
+    stats?: ExecutionStats;
+    trapState?: {
+        pending: unknown;
+    };
+    syncCallStack?: LenderScope[];
+    allInstances?: () => Iterable<{
+        mayLeave: boolean;
+    }>;
+}): (rep: number) => unknown;
+/**
+ * Run a host-initiated drop of a guest (or host-implemented) resource rep —
+ * the observable remainder of `canon_resource_drop` for an owning handle when
+ * the holder is the host (`caller = None`, `Store.invoke`).
+ *
+ * A failure that arrives asynchronously has no frame to propagate into, so it
+ * is parked on the store's host-failure channel (first failure wins), where
+ * the next driven call surfaces it. The completion promise is deliberately
+ * NOT registered in `store.pendingHostCalls`: that registration was #160's
+ * lie — it claims *external* work for a promise whose settlement may need
+ * this very scheduler. The dtor's genuine external dependencies (its host
+ * imports) register themselves when they park. Poisoning on a trap now
+ * happens inside the lift harness (`poison()` in `createLiftedFunction`).
+ */
+export declare function hostDtorCall(rt: ResourceTypeInfo, rep: number): void;
+/**
+ * Call into wasm and hand back the result, awaiting it only if it is a
+ * Promise.
+ *
+ * This is the whole of the jspi entry seam. In **plain** mode the entry is not
+ * `promising`-wrapped, `callCore` returns core values, and this returns them
+ * without yielding — no await, no Promise allocation, the identical
+ * synchronous path M1 shipped. In **jspi** mode the entry *is* wrapped, so the
+ * call returns a Promise (jspi pin (e)) and we park the thread on it via the
+ * `awaitValue` block request; the driving loop resumes us with the values, or
+ * throws the rejection in (a post-resume trap).
+ */
+export declare function awaitCore(fn: CoreFn, args: CoreValue[], thread: any): Generator<BlockRequest, CoreValue[], unknown>;
+/** definitions.py `CallbackCode` (line 2220). */
+declare enum CallbackCode {
+    EXIT = 0,
+    YIELD = 1,
+    WAIT = 2
+}
+/** definitions.py `unpack_callback_result` (line 2226). */
+export declare function unpackCallbackResult(packed: number): [code: CallbackCode, waitableSetIndex: number];
+/**
+ * Build the core-callable body for one lowered host import (reference
+ * `canon_lower`, definitions.py line 2242).
+ *
+ * Sync and async lowers share one `Subtask` and one pair of
+ * `on_start`/`on_resolve` closures, exactly as the reference does; the sync
+ * case is the degenerate one where the callee resolves before returning.
+ *
+ * The host callee is a plain JS function. If it returns a **Promise**, the
+ * subtask resolves when that promise settles:
+ *
+ *   * async lower — fully supported and JSPI-free. The guest gets a STARTED
+ *     subtask back, joins it to a waitable set, returns WAIT from its
+ *     callback, and the scheduler delivers the SUBTASK event once the promise
+ *     settles. This is the flagship capability of this phase: an ordinary
+ *     `async` JS function is a valid Component Model async import.
+ *   * sync lower — the guest's wasm frame would have to block
+ *     (`thread.wait_until(subtask.resolved)`, line 2286), so: `needsJspi`.
+ */
+export declare function createLoweredImport(input: {
+    name: string;
+    ft: FuncType;
+    opts: ResolvedOptions;
+    hostFn: (...args: unknown[]) => unknown;
+    stats: ExecutionStats;
+    /** Executor's suspension mode; decides whether a sync lower may park. */
+    mode: SuspensionMode;
+    /** Host fn carries the `suspending()` brand (embedder-api.md A1). */
+    suspendable: boolean;
+}): CoreFn;
+/**
+ * The callback-ABI dispatch loop of `canon_lift` (definitions.py lines
+ * 2183-2214), factored out so both entry points share one implementation:
+ *
+ *   * a host-boundary lift (`liftBody` above), and
+ *   * a FACT cross-component call, where the host invokes an async-lifted
+ *     callee on the caller's behalf (`intrinsics/fact_calls.ts`).
+ *
+ * `packed` is the code the *initial* activation returned; the loop runs until
+ * it sees EXIT, invoking the callback export with each delivered event.
+ */
+export declare function runCallbackLoop(input: {
+    name: string;
+    task: Task;
+    thread: Thread;
+    inst: ComponentInstanceState;
+    callback: CoreFn;
+    packed: number;
+    stats: ExecutionStats;
+}): Generator<BlockRequest, void, Cancelled>;
+export {};

package/types/exec/executor.d.ts

@@ -0,0 +1,125 @@
+import type { ComponentValue } from "../cabi/types.js";
+import { ComponentInstanceState } from "../task/mod.js";
+import type { WirePlan } from "../plan/format.js";
+import type { LoadedPlan } from "../plan/loader.js";
+import { type ExecutionStats } from "./boundary.js";
+/**
+ * Host-provided imports: a nested record keyed by the component's *exact*
+ * import strings. A plan import with a non-empty `path` (an item extracted
+ * from an imported instance — plan-format.md v0.1 amendment #4) is looked up
+ * by walking `imports[name]` then each path segment in order. So an import
+ * of `"ns:pkg/iface"` exposing `f` is supplied as
+ * `{ "ns:pkg/iface": { f: (…) => … } }`.
+ *
+ * Leaf values by import kind:
+ *   - `func`     — a JS function; arguments/results are host-shaped
+ *                  component values (contracts/descriptor-ir.md).
+ *   - `resource` — a `HostResourceType` (see `hostResourceType`).
+ *   - `instance` — a plain object; only its leaves are ever read.
+ *   - `module`   — not supported (see `InstantiateModule::Import` below).
+ */
+export type HostImports = Record<string, unknown>;
+/**
+ * Identity token for a resource type **defined by the host** and imported by
+ * a component (plan `importedResources`). One object per resource type;
+ * object identity is the type identity, exactly as for guest-defined
+ * resources whose identity is the per-instantiation `ResourceTypeInfo`.
+ */
+export declare class HostResourceType {
+    readonly options: {
+        /** Debug name, used in error messages only. */
+        readonly name?: string;
+        /**
+         * Destructor for handles owned by a component and dropped there.
+         * Per docs/architecture.md §7 / CanonicalABI.md `canon resource.drop`, it runs
+         * synchronously and may not block.
+         */
+        readonly dtor?: (rep: number) => void;
+    };
+    constructor(options?: {
+        /** Debug name, used in error messages only. */
+        readonly name?: string;
+        /**
+         * Destructor for handles owned by a component and dropped there.
+         * Per docs/architecture.md §7 / CanonicalABI.md `canon resource.drop`, it runs
+         * synchronously and may not block.
+         */
+        readonly dtor?: (rep: number) => void;
+    });
+}
+/** Convenience constructor for {@link HostResourceType}. */
+export declare function hostResourceType(options?: HostResourceType["options"]): HostResourceType;
+export interface InstantiateInput {
+    plan: WirePlan;
+    /** The original component binary (embedded modules are sliced from it). */
+    componentBytes: Uint8Array;
+    /** FACT adapter artifacts keyed by `plan.modules[].file`. */
+    adapters?: Map<string, Uint8Array>;
+    imports?: HostImports;
+    /** Verify plan.component.sha256 against componentBytes (default true). */
+    verifyHash?: boolean;
+    /**
+     * Opt in to JSPI-backed suspension (docs/architecture.md §6 role 1-3).
+     *
+     * Off by default, and deliberately so: in this mode every lifted export
+     * returns a Promise (empirical fact (e) — `WebAssembly.promising` always
+     * does), which is an API-shape change. Ignored on an engine without JSPI,
+     * where every blocking site keeps raising the precise `NeedsJspi` it raises
+     * today (the M3 degradation path).
+     */
+    jspi?: boolean;
+    /**
+     * A plan already converted by `loadPlan`, used instead of re-loading.
+     *
+     * Why this exists: the conventions layer (`src/embedder/`) must have the
+     * per-instantiation `ResourceTypeInfo` identity tokens and the converted
+     * types table *before* instantiation begins, because host imports genuinely
+     * fire DURING it — a core module's `start` function runs inside
+     * `runInitializers`, and real guests do call imports from it (Go's runtime
+     * calls `monotonic-clock.now()` from `schedinit`). Reading them off the
+     * returned `ComponentHandle.loadedPlan` is therefore too late. Handing the
+     * same `LoadedPlan` in keeps the tokens identical on both sides.
+     *
+     * Contract: one `LoadedPlan` per instantiation (tokens must be fresh per
+     * component instance), and `loadedPlan.wire` must be `plan`. Both are
+     * checked.
+     */
+    loadedPlan?: LoadedPlan;
+}
+/** An instantiated component: its export surface plus introspection state. */
+export interface ComponentHandle {
+    /** Lifted functions / nested instance objects, by export name. */
+    exports: Record<string, unknown>;
+    stats: ExecutionStats;
+    componentInstances: ComponentInstanceState[];
+    coreInstances: WebAssembly.Instance[];
+    /** See `Executor.suspendableFuncs`. */
+    suspendableFuncs: WeakSet<object>;
+    taskMayBlock: WebAssembly.Global;
+    /** `ResourceIndex` -> the `HostResourceType` bound to it, if any. */
+    hostResourceTypes: Map<number, HostResourceType>;
+    /**
+     * Plan exports deliberately absent from `exports`, by export path, with the
+     * reason. Only `type` exports appear here; a missing *function* export is
+     * always an error, never an omission (see `Executor.buildExport`).
+     */
+    omittedExports: Map<string, string>;
+    /**
+     * The plan as loaded for THIS instantiation.
+     *
+     * Exposed for the conventions layer (`src/embedder/`), which needs the two
+     * things only the executor's own `loadPlan` call can supply: the per-instance
+     * `ResourceTypeInfo` identity tokens (`resourceTokens`) — the same objects
+     * the `own`/`borrow` types in every signature point at, and the only route to
+     * a resource's destructor for a *host-initiated* drop of a guest handle
+     * (definitions.py `canon_resource_drop` runs `rt.dtor(rep)`; the host holds
+     * reps, never table indices, so there is no handle to drop through) — and the
+     * converted `types` table it reads function signatures from.
+     *
+     * Introspection only: mutating it is undefined behaviour.
+     */
+    loadedPlan: LoadedPlan;
+}
+export declare function instantiateComponent(input: InstantiateInput): Promise<ComponentHandle>;
+/** Convenience for callers: typed view of a lifted export. */
+export type LiftedFunction = (...args: ComponentValue[]) => unknown;

package/types/exec/host_streams.d.ts

@@ -0,0 +1,165 @@
+import type { ComponentValue, ValType } from "../cabi/types.js";
+import { CopyResult, type PayloadChunk, sameElemType } from "../task/mod.js";
+/**
+ * A buffer over JS values. Sibling of `GuestBuffer`, same four methods, no
+ * memory access. Used in one of two directions:
+ *
+ *   * as a *readable* buffer (host supplies `values`, the guest reads them);
+ *   * as a *writable* buffer (host supplies capacity, the guest fills it and
+ *     `taken()` is what arrived).
+ *
+ * u8 payloads stay `Uint8Array` through both directions (issue #54): `read`
+ * slices the typed array (bulk, and the ONE semantically required copy — the
+ * chunk is only borrowed by the stream until the write settles, so the reader
+ * must receive owned bytes), and `write` keeps arriving chunks whole instead
+ * of exploding them element-by-element into a plain array.
+ */
+export declare class HostBuffer {
+    #private;
+    readonly t: ValType | null;
+    private readonly values;
+    readonly length: number;
+    progress: number;
+    constructor(t: ValType | null, values: PayloadChunk | null, length: number);
+    remain(): number;
+    isZeroLength(): boolean;
+    /** Guest side is reading from us. */
+    read(n: number): PayloadChunk;
+    /** Guest side is writing into us. */
+    write(vs: PayloadChunk): void;
+    /**
+     * Everything written into this buffer, in arrival order.
+     *
+     * For a u8 element type the result is a `Uint8Array`; in the common case —
+     * one rendezvous before the read resolves — the writer's chunk is returned
+     * as-is, so the whole host-side read costs exactly the one rendezvous copy.
+     * Every other element type yields a plain array regardless of the shape the
+     * writer used.
+     */
+    taken(): PayloadChunk;
+}
+/** Host end the embedder WRITES; the guest reads. */
+export interface HostWritableEnd<T> {
+    /**
+     * Offer `values`. Resolves with how many the guest actually took — a
+     * partial copy is normal, not an error (definitions.py copies
+     * `min(remain, remain)`). Re-offer the remainder to finish.
+     *
+     * `values` is BORROWED until the returned promise settles (the buffer may
+     * stay parked across several partial reads); mutating it in that window is
+     * misuse. Readers always receive their own copy.
+     */
+    write(values: T[]): Promise<number>;
+    /**
+     * Offer `values` repeatedly until all of them have been taken or the reader
+     * goes away. Convenience over `write`, and the shape most embedders want.
+     *
+     * The loop is unavoidable in the single-shot form because of *which side
+     * arrives second*: when the host arrives second the reference completes the
+     * arriving call with just the count copied in that rendezvous
+     * (`SharedStreamImpl.write` -> `on_copy_done(COMPLETED)`), leaving the rest
+     * of the offer unsent. When the host arrives *first* it stays parked and is
+     * drained across several guest reads. `writeAll` papers over the difference.
+     *
+     * Resolves with the total accepted, which is less than `values.length` only
+     * if the reader dropped.
+     */
+    writeAll(values: T[]): Promise<number>;
+    /**
+     * Cancel an in-flight `write`/`writeAll` (definitions.py
+     * `SharedStreamImpl.cancel` -> `CopyResult.CANCELLED`). No-op when nothing
+     * of ours is parked. Surfaced per the R-fix review's stream advisory 1: the
+     * cancel channel existed on the shared object but had no embedder-facing
+     * spelling, so a host writer could only be abandoned, never retracted.
+     */
+    cancelWrite(): void;
+    /** definitions.py `SharedStreamImpl.drop`: notifies a parked reader. */
+    drop(): void;
+    /**
+     * Fire `fn` once the stream becomes dropped — by either end, including
+     * the A7 teardown walk (immediately, if it already is). The embedder's
+     * producer pump uses it to cancel a producer parked on an external
+     * event (amendment A13's cancellation companion).
+     */
+    onDropped(fn: () => void): void;
+}
+/** Host end the embedder READS; the guest writes. */
+export interface HostReadableEnd<T> {
+    /**
+     * Resolves with up to `max` values once the guest writes (or an empty
+     * chunk on drop). A u8 stream resolves with a `Uint8Array` (see
+     * `HostBuffer.taken`); every other element type resolves with a plain
+     * array.
+     */
+    read(max: number): Promise<T[]>;
+    /** Cancel an in-flight `read`; see `HostWritableEnd.cancelWrite`. */
+    cancelRead(): void;
+    drop(): void;
+}
+export interface HostStream<T> {
+    readable: HostReadableEnd<T>;
+    writable: HostWritableEnd<T>;
+    /**
+     * The value to pass across the boundary. Lowering it into a guest gives the
+     * guest the **readable** end (`lower_stream`), so an embedder feeding a
+     * guest uses `writable`; an embedder consuming a guest-produced stream gets
+     * its shared object from the lift and wraps it with `hostStreamFor`.
+     */
+    value: ComponentValue;
+}
+/** Create a host-owned stream of `element` (`null` = zero-width payload). */
+export declare function hostStream<T>(element: ValType | null): HostStream<T>;
+/**
+ * Wrap a stream that came *out* of a guest (from `liftStream`). Idempotent:
+ * a shared object that already has a host wrapper (it was created by
+ * `hostStream`, or lifted before) yields that same wrapper.
+ */
+export declare function hostStreamFor<T>(value: ComponentValue): HostStream<T>;
+export interface HostFuture<T> {
+    /** Deliver the future's single value. */
+    write(value: T): Promise<void>;
+    /** Await the future's single value. */
+    read(): Promise<T | undefined>;
+    /**
+     * `read`, but reporting *why* it settled. A future carries at most one
+     * value, so `read`'s `undefined` is ambiguous between "the value was
+     * `undefined`" (a `future<void>`) and "the write end dropped without ever
+     * writing" — the case the conventions layer must turn into a
+     * `DroppedError` (R-fix review advisory 4). `result` disambiguates:
+     * `COMPLETED` iff `value` is real.
+     */
+    readResult(): Promise<{
+        value: T | undefined;
+        result: CopyResult;
+    }>;
+    /** Cancel an in-flight `read`/`write`; see `HostWritableEnd.cancelWrite`. */
+    cancel(): void;
+    /**
+     * Release this future. Total and idempotent (#90): it never throws, and a
+     * second call is a no-op.
+     *
+     * Three cases, per the #90 ruling:
+     *
+     *  * the value was already delivered (the normal write-then-drop path) —
+     *    plain state cleanup, the spec's `WritableFutureEnd.drop` precondition
+     *    (definitions.py:1183-1184) is satisfied;
+     *  * never written, and the future was **lowered** into a guest (the guest
+     *    holds the readable end, so this wrapper plays the spec's writable
+     *    role) — *abandon*: the reader can never be satisfied, so it is armed
+     *    with the rendezvous-point trap (task/streams.ts `abandonSharedFuture`)
+     *    rather than being handed a DROPPED it may not observe;
+     *  * never written and never lowered — no guest ever saw it; plain
+     *    cleanup.
+     */
+    drop(): void;
+    value: ComponentValue;
+}
+/** Create a host-owned future of `element`. */
+export declare function hostFuture<T>(element: ValType | null): HostFuture<T>;
+/**
+ * Wrap a future that came *out* of a guest (from `liftFuture`). Idempotent —
+ * see `hostStreamFor`.
+ */
+export declare function hostFutureFor<T>(value: ComponentValue): HostFuture<T>;
+/** Re-exported so embedders can build element types without importing cabi. */
+export { sameElemType };

package/types/exec/mod.d.ts

@@ -0,0 +1,3 @@
+export * from "./boundary.js";
+export * from "./executor.js";
+export * from "./host_streams.js";