@polyengine/runtime 0.1.0-pre.g633468a

package/types/embedder/streams.d.ts

@@ -0,0 +1,202 @@
+import type { ValType } from "../cabi/types.js";
+import type { ComponentValue } from "../cabi/types.js";
+import { type HostFuture, type HostStream } from "../exec/host_streams.js";
+import { ErrorContext as InternalErrorContext } from "../task/mod.js";
+/** `Chunk<u8>` is a `Uint8Array`; every other element type chunks as `T[]`. */
+export type Chunk<T> = T extends number ? Uint8Array | T[] : T[];
+/** Per-element adaptation, supplied by the value adapter. */
+export interface ElemCodec<T> {
+    readonly element: ValType | null;
+    /** internal component value -> conventions value */
+    toHost(v: ComponentValue): T;
+    /** conventions value -> internal component value */
+    fromHost(v: T): ComponentValue;
+    /**
+     * Destroy a LOWERED element the reader will never take (amendment A13);
+     * present only for element types that hold resources (`own<R>`), where
+     * abandonment without destruction is a leak.
+     */
+    readonly release?: (lowered: ComponentValue) => void;
+    /** Optional site name (`import 'x'.f`, `export 'i#f'`) for diagnostics. */
+    readonly where?: string;
+}
+export { StreamProducerError } from "@polyengine/protocol";
+/** True for `stream<u8>` / `future<u8>`, whose chunks are `Uint8Array`. */
+export declare function isU8Element(element: ValType | null): boolean;
+/**
+ * A stream handle.
+ *
+ * `read` returning an empty chunk is end-of-stream, exactly as the contract
+ * spells it; `readable()` and the async iterator are built on it.
+ */
+export declare class Stream<T> {
+    #private;
+    private constructor();
+    /** Wrap a stream value that was lifted out of a guest. */
+    static fromLifted<T>(value: ComponentValue, codec: ElemCodec<T>): Stream<T>;
+    /** Wrap a freshly created host-owned stream of a known element type. */
+    static fromHostStream<T>(host: HostStream<T>, codec: ElemCodec<T>): Stream<T>;
+    /**
+     * `Stream.create<T>(): { stream, writer }` — the writer-side host end the
+     * contract names.
+     *
+     * The element type is deliberately NOT a parameter: the embedder does not
+     * have one (a `ValType` is a runtime-internal shape) and the *lowering site*
+     * always does. So the shared object is created lazily, at the moment the
+     * stream is passed to a guest, and writer operations issued before that park
+     * until then. A stream created and written but never passed anywhere simply
+     * never completes — the same honest hang the low-level layer documents.
+     */
+    static create<T>(): {
+        stream: Stream<T>;
+        writer: StreamWriter<T>;
+    };
+    /** @internal — bind a lazily created stream to the lowering site's type. */
+    bindElement(codec: ElemCodec<T>): void;
+    /** @internal — resolve once this handle has a shared object. */
+    whenBound(): Promise<void>;
+    /** @internal */
+    get bound(): boolean;
+    /** @internal — the shared value to hand to a lowering site. */
+    takeValue(codec: ElemCodec<T>): ComponentValue;
+    /** @internal */
+    get codec(): ElemCodec<T> | null;
+    /** Low-level read: up to `max` elements; an empty chunk means end-of-stream. */
+    read(max: number): Promise<Chunk<T>>;
+    /**
+     * Cancel an in-flight `read` (R-fix review advisory 1).
+     *
+     * #97, DELIBERATE AND PINNED: the cancelled `read` resolves with whatever
+     * had already arrived — typically the empty chunk, which this layer also
+     * uses as end-of-stream (`read`'s contract, and hence `readable()` and the
+     * async iterator, which close on it). **A cancelled read is therefore
+     * indistinguishable from EOS at this layer.** Kept as-is rather than given
+     * a distinct signal: the caller of `cancelRead()` is the same code that
+     * observes the read's result, so it already knows which happened, and only
+     * that caller can reach the state. See exec/host_streams.ts
+     * `HostReadableEnd.cancelRead` for the mechanism.
+     */
+    cancelRead(): void;
+    drop(): void;
+    /**
+     * @internal — teardown after a trapping import abandoned this handle
+     * (#66, instantiate.ts `releaseAsyncArgs`). Unlike `drop()`, this goes
+     * through `dropSharedForTeardown`, whose parked-side discipline never
+     * wakes the about-to-be-poisoned caller (review B2: a plain drop queued a
+     * DROPPED event into the trapping instance's waitables, and a later
+     * driving loop asserted on the corpse).
+     *
+     * The arm is released on this path too (#162, amendment A15): the wrapper's
+     * `HostActivity` now closes through the shared object's drop observers,
+     * which `dropSharedForTeardown` fires unconditionally — so a teardown with
+     * nothing parked no longer leaves the arm outliving the stream. (This
+     * paragraph previously recorded that asymmetry as a known, non-blocking
+     * review advisory.)
+     */
+    dropForTeardown(): void;
+    [Symbol.dispose](): void;
+    /** Web-native view: `ReadableStream<Chunk<T>>`. */
+    readable(): ReadableStream<Chunk<T>>;
+    [Symbol.asyncIterator](): AsyncIterator<Chunk<T>>;
+}
+/** Writer half of `Stream.create()`. */
+export declare class StreamWriter<T> {
+    #private;
+    constructor(stream: Stream<T>);
+    /**
+     * Offer values; resolves with how many the reader took.
+     *
+     * `Chunk<T>` mirrors the read side: a u8 stream accepts a `Uint8Array`
+     * (taken as already-lowered bytes), and a plain array of any element type
+     * is lowered per element. u8 chunks travel as `Uint8Array` all the way to
+     * the CABI store's bulk path (issue #54) — which makes a `Uint8Array`
+     * chunk a BORROW until the returned promise settles; mutating it in that
+     * window is misuse. Plain-array chunks are lowered (copied) up front.
+     */
+    write(values: Chunk<T>): Promise<number>;
+    /** Offer values until all are taken or the reader goes away. */
+    writeAll(values: Chunk<T>): Promise<number>;
+    cancelWrite(): void;
+    /** End-of-stream. */
+    close(): Promise<void>;
+}
+/** @internal — publish the host end for `StreamWriter` (see `hostOf`). */
+export declare function publishHostStream<T>(s: Stream<T>, h: HostStream<T>): void;
+/**
+ * A future handle. `await`able directly (`PromiseLike`), and droppable.
+ *
+ * A future whose write end dropped without ever writing rejects with
+ * `DroppedError` — not `undefined`, which `future<void>` legitimately yields.
+ */
+export declare class Future<T> implements PromiseLike<T> {
+    #private;
+    private constructor();
+    static fromLifted<T>(value: ComponentValue, codec: ElemCodec<T>): Future<T>;
+    static fromHostFuture<T>(host: HostFuture<T>, codec: ElemCodec<T>): Future<T>;
+    /**
+     * A future that is still in flight: the guest call that produces it has not
+     * resolved yet.
+     *
+     * CONTRACT (contracts/embedder-api.md): §"Functions and async" makes every
+     * export Promise-shaped, and §"Streams and futures" makes `Future<T>` a
+     * `PromiseLike<T>`. For an export whose *result* is a `future<T>` those two
+     * collide irreducibly: JS promise resolution unconditionally adopts a
+     * thenable, so `await someExport()` can never hand back a thenable handle —
+     * it hands back the value the handle would have yielded. Conservative
+     * reading, implemented here: the export returns the handle **eagerly** (it
+     * is itself PromiseLike, so `await` still works and still yields `T`), which
+     * keeps `drop()`/`cancel()` reachable for a caller that does not await. The
+     * alternative — resolving a Promise *to* the handle — is not expressible.
+     * Flagged in the C2 report.
+     */
+    static deferred<T>(pending: Promise<ComponentValue>, codec: ElemCodec<T>): Future<T>;
+    /** @internal */
+    adopt(h: HostFuture<T>): void;
+    /** @internal */
+    takeValue(): ComponentValue;
+    then<R1 = T, R2 = never>(onfulfilled?: ((v: T) => R1 | PromiseLike<R1>) | null, onrejected?: ((e: unknown) => R2 | PromiseLike<R2>) | null): PromiseLike<R1 | R2>;
+    cancel(): void;
+    /**
+     * Release this future handle. Total and idempotent (#90): it never throws,
+     * and calling it twice — or after `Symbol.dispose` — is a no-op.
+     *
+     * Dropping a future the host never wrote to, once the guest already holds
+     * its readable end, is **abandonment**: the guest's reader can never be
+     * satisfied, so it is armed with a trap at its rendezvous point rather than
+     * being handed a value-less completion (exec/host_streams.ts
+     * `HostFuture.drop`, task/streams.ts `abandonSharedFuture`; the spec keeps
+     * that state unreachable by trapping the early writable drop,
+     * definitions.py:1183-1184). Write-then-drop is the normal path and is
+     * unaffected; a future no guest ever saw is plain cleanup.
+     */
+    drop(): void;
+    /** @internal — see `Stream.dropForTeardown` (#66). */
+    dropForTeardown(): void;
+    [Symbol.dispose](): void;
+}
+/**
+ * `error-context` as the contract spells it: `{ readonly message: string }`.
+ * The internal value is `task/streams.ts`'s `ErrorContext` (debug message
+ * only, per definitions.py).
+ */
+export declare class ErrorContext {
+    readonly message: string;
+    /** @internal — the internal value, preserved so it can be lowered back. */
+    readonly internal: InternalErrorContext;
+    constructor(internal: InternalErrorContext);
+}
+/** Anything the layer accepts where a guest expects `stream<T>`. */
+export type StreamSource<T> = Stream<T> | ReadableStream<T[] | Uint8Array | T> | AsyncIterable<T[] | Uint8Array | T> | Iterable<T>;
+/** Anything the layer accepts where a guest expects `future<T>`. */
+export type FutureSource<T> = Future<T> | PromiseLike<T> | T;
+/**
+ * Adapt a producer to a lowered `stream<T>` value, and own the pumping.
+ *
+ * The driving arm auto-closes on end (the pump drops the write end when the
+ * producer is exhausted) and on `DROPPED` (host_streams settles the activity
+ * arm) — R-fix review advisory 2, the deadlock-masking activity-lifetime
+ * footgun.
+ */
+export declare function lowerStreamSource<T>(src: StreamSource<T>, codec: ElemCodec<T>): ComponentValue;
+/** Adapt a `Promise`/`Future`/plain value to a lowered `future<T>` value. */
+export declare function lowerFutureSource<T>(src: FutureSource<T>, codec: ElemCodec<T>): ComponentValue;

package/types/embedder/values.d.ts

@@ -0,0 +1,70 @@
+import type { ComponentValue, ValType } from "../cabi/types.js";
+/**
+ * The parts of adaptation that need instance state: resources (identity
+ * mapping, ownership) and the borrow scope of the call in flight.
+ */
+export interface ValueBridge {
+    /** A guest handed the host an `own<R>`; the host now owns it. */
+    liftOwn(rep: number, t: ValType & {
+        kind: "own";
+    }): unknown;
+    /** A guest handed the host a `borrow<R>`, valid only for this call. */
+    liftBorrow(rep: number, t: ValType & {
+        kind: "borrow";
+    }, scope: BorrowScope): unknown;
+    /** The host is passing an `own<R>` (transfer). */
+    lowerOwn(v: unknown, t: ValType & {
+        kind: "own";
+    }): number;
+    /** The host is passing a `borrow<R>` (no transfer). */
+    lowerBorrow(v: unknown, t: ValType & {
+        kind: "borrow";
+    }): number;
+    /**
+     * Destroy a LOWERED `own<R>` the guest will never receive (amendment
+     * A13: a stream element the producer lowered but the reader never took).
+     * Runs the resource's destructor — for a host-implemented R the
+     * instance's `[Symbol.dispose]`, for a guest-implemented R the guest
+     * dtor — exactly as if the guest had taken the handle and dropped it.
+     */
+    dropOwn(rep: number, t: ValType & {
+        kind: "own";
+    }): void;
+}
+/**
+ * Wrappers materialized for `borrow<R>` arguments of one call. The contract:
+ * "instance valid **only during the call** (retention throws)", so the scope
+ * invalidates them when the call returns.
+ */
+export declare class BorrowScope {
+    #private;
+    add(f: () => void): void;
+    end(): void;
+}
+/** A no-op scope for positions where no borrow can appear. */
+export declare const NO_BORROWS: BorrowScope;
+/**
+ * Refuse two labels in one scope that camelCase to the same JS name.
+ *
+ * `read-only` and `readOnly` are distinct WIT labels but one JS property, so
+ * one would silently shadow the other at the boundary — values corrupted with
+ * no diagnostic anywhere. Contract principle 2: footguns are design defects.
+ */
+export declare function checkNoCollisions(key: object, labels: string[], what: string): void;
+export interface AdapterOptions {
+    bridge: ValueBridge;
+    /** Names the site in error messages (`import 'wasi:x/y'.f`, param 2). */
+    where: string;
+}
+/**
+ * Adapt one lifted value to its conventions shape.
+ *
+ * `inOption` implements the contract's option rule: the *outermost* option in
+ * a chain maps to `T | undefined`; an option nested **directly inside another
+ * option** boxes as `{ kind: "some", value } | { kind: "none" }`. Only option maps
+ * to `undefined`, so this is the only ambiguity, and the flag is set only when
+ * descending through an option's payload — every other constructor resets it.
+ */
+export declare function toHost(v: ComponentValue, t: ValType, o: AdapterOptions, scope?: BorrowScope, inOption?: boolean): unknown;
+export declare function fromHost(v: unknown, t: ValType, o: AdapterOptions, inOption?: boolean): ComponentValue;
+export declare function describe(v: unknown): string;

package/types/embedder/version.d.ts

@@ -0,0 +1,85 @@
+/** Fault in how the embedder registered its imports. */
+export declare class ImportRegistrationError extends Error {
+    constructor(message: string);
+}
+/** Fault resolving a component's import against the registered providers. */
+export declare class ImportResolutionError extends Error {
+    constructor(message: string);
+}
+/** A parsed `name@version` interface id. `version` is null when unversioned. */
+export interface ParsedId {
+    /** The id with the version suffix removed (`wasi:clocks/monotonic-clock`). */
+    base: string;
+    /** The raw version text, or null. */
+    version: string | null;
+    /** Parsed semver, or null when unversioned / unparseable. */
+    semver: Semver | null;
+}
+export interface Semver {
+    major: number;
+    minor: number;
+    patch: number;
+    /** Dot-separated prerelease identifiers; empty when there is none. */
+    prerelease: string[];
+    build: string | null;
+}
+/**
+ * Split an interface id at its LAST `@`.
+ *
+ * Last, not first: a package name may not contain `@`, but being explicit
+ * costs nothing and matches how wasmtime splits (`name.rfind('@')`).
+ */
+export declare function parseInterfaceId(id: string): ParsedId;
+export declare function parseSemver(v: string): Semver | null;
+/**
+ * The compatibility-track key of an interface id, or null when the id belongs
+ * to no track (unversioned, unparseable, prerelease, or `0.0.z`).
+ *
+ * Mirrors wasmtime `alternate_lookup_key`:
+ *   - `major > 0`            -> `base@{major}`      (`1.2.3` -> `@1`)
+ *   - `major == 0, minor > 0`-> `base@0.{minor}`    (`0.2.6` -> `@0.2`)
+ *   - `0.0.z`                -> none (patch-only versions are compatible with
+ *                               nothing)
+ *   - any prerelease         -> none (wasmtime treats prereleases as
+ *                               exact-only; the historic WASI `0.2.0-rc`
+ *                               snapshots are exactly the phenomenon this
+ *                               exclusion protects — same track on paper,
+ *                               divergent function sets in fact)
+ *
+ * Build metadata is ignored for track purposes (`2.1.2+abc` -> `@2`), as
+ * semver requires.
+ */
+export declare function trackKey(id: string): string | null;
+/**
+ * Is `id` itself spelled as a *track key* (`ns:pkg/iface@0.2`, `…@1`)?
+ *
+ * Note `semver::Version::parse("0.2")` fails — which is exactly why the two
+ * mechanisms compose: a track key can never be mistaken for a full version,
+ * and a full version never generates a track key equal to itself.
+ */
+export declare function asTrackKeySpelling(id: string): string | null;
+/**
+ * Registration table over the embedder's imports record.
+ *
+ * Only the *interface-id* keys participate: world-level bare imports live at
+ * the record's top level under camelCase names and are matched by exact
+ * string equality, never by version machinery.
+ */
+export declare class ImportResolver {
+    #private;
+    constructor(record: Record<string, unknown>);
+    /** Every registered key, in registration order. */
+    keys(): string[];
+    /**
+     * Resolve one component import name. Returns `undefined` when nothing is
+     * registered for it; throws when a registration *nearly* matches in a way
+     * the contract bans (unversioned folding), because silently reporting
+     * "not provided" would hide the real mistake.
+     */
+    resolve(id: string): {
+        key: string;
+        value: unknown;
+    } | undefined;
+}
+/** Semver precedence, prerelease-aware (semver.org §11). */
+export declare function compareSemver(a: Semver, b: Semver): number;