@polyengine/runtime 0.4.0 → 0.5.1

package/types/embedder/streams.d.ts

@@ -2,8 +2,8 @@ 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[];
+import { type Chunk, type DirectDestination, type DirectSource, type DirectVerdict, type ErrorContext as ProtocolErrorContext, type Future as ProtocolFuture, type Stream as ProtocolStream, type StreamWriter as ProtocolStreamWriter } from "@polyengine/protocol";
+export type { Chunk } from "@polyengine/protocol";
 /**
  * Per-element adaptation, supplied by the value adapter.
  * @internal — supplied by the value adapter, never by a host.
@@ -26,13 +26,14 @@ export interface ElemCodec<T> {
 export { StreamProducerError } from "@polyengine/protocol";
 /** True for `stream<u8>` / `future<u8>`, whose chunks are `Uint8Array`. */
 export declare function isU8Element(element: ValType | null): boolean;
+export type { DirectDestination, DirectSource, DirectVerdict } from "@polyengine/protocol";
 /**
  * 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> {
+export declare class Stream<T> implements ProtocolStream<T> {
     #private;
     private constructor();
     /** Wrap a stream value that was lifted out of a guest. */
@@ -66,6 +67,29 @@ export declare class Stream<T> {
     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>>;
+    /**
+     * Consume the writer's bytes in place, without an intermediate chunk
+     * (`stream<u8>` only — contracts/embedder-api.md amendment A21,
+     * polyengine#128).
+     *
+     * At every rendezvous with a writer of nonzero capacity, `consume` runs
+     * exactly once, synchronously, with a `DirectSource` over the writer's
+     * unread bytes — guest linear memory when the peer is a guest, so the
+     * consumer's own `set()`/`subarray` copy IS the canonical-ABI copy.
+     * `"more"` keeps the session parked for the next rendezvous; `"done"` ends
+     * it. Resolves with the session's total byte count. Marking a prefix is
+     * normal: the writer re-offers the rest on its own schedule.
+     *
+     * `"done"` with zero bytes marked *retracts*: the session ends and the
+     * writer's operation stays parked, with no event delivered. `"more"` with
+     * zero marked, and a throwing callback, reject — and in both cases the
+     * writer's parked operation survives and the stream stays alive.
+     *
+     * Refusals mirror `read`: an unbound `Stream.create()` handle and a handle
+     * already passed to a guest (the A15 transfer guard) both throw, as does a
+     * non-`u8` element type.
+     */
+    readDirect(consume: (src: DirectSource) => DirectVerdict): Promise<number>;
     /**
      * Cancel an in-flight `read` (R-fix review advisory 1).
      *
@@ -103,7 +127,7 @@ export declare class Stream<T> {
     [Symbol.asyncIterator](): AsyncIterator<Chunk<T>>;
 }
 /** Writer half of `Stream.create()`. */
-export declare class StreamWriter<T> {
+export declare class StreamWriter<T> implements ProtocolStreamWriter<T> {
     #private;
     constructor(stream: Stream<T>);
     /**
@@ -117,6 +141,29 @@ export declare class StreamWriter<T> {
      * window is misuse. Plain-array chunks are lowered (copied) up front.
      */
     write(values: Chunk<T>): Promise<number>;
+    /**
+     * Fill the reader's landing zone in place, without an intermediate chunk
+     * (`stream<u8>` only — contracts/embedder-api.md amendment A21,
+     * polyengine#128).
+     *
+     * At every rendezvous with a reader of nonzero capacity, `produce` runs
+     * exactly once, synchronously, with a `DirectDestination` over the reader's
+     * unfilled landing zone — guest linear memory when the peer is a guest, so
+     * the producer's own `set()` IS the canonical-ABI copy and an external byte
+     * mover (a websocket frame, a SAB ring segment, a transferred
+     * `ArrayBuffer`) never pays a second copy inside the runtime. `"more"`
+     * keeps the session parked for the next rendezvous; `"done"` ends it.
+     * Resolves with the session's total byte count.
+     *
+     * `"done"` with zero bytes marked *retracts* (the session ends, the
+     * reader's operation stays parked, no event — the speculative-park
+     * correction); `"more"` with zero marked, and a throwing callback, reject.
+     *
+     * Parks until the element type is known, exactly as `write` does — a
+     * `Stream.create()` writer has no element type until the lowering site
+     * binds one — and then requires `u8`.
+     */
+    writeDirect(produce: (dest: DirectDestination) => DirectVerdict): Promise<number>;
     /** Offer values until all are taken or the reader goes away. */
     writeAll(values: Chunk<T>): Promise<number>;
     cancelWrite(): void;
@@ -131,7 +178,7 @@ export declare function publishHostStream<T>(s: Stream<T>, h: HostStream<T>): vo
  * 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> {
+export declare class Future<T> implements ProtocolFuture<T> {
     #private;
     private constructor();
     static fromLifted<T>(value: ComponentValue, codec: ElemCodec<T>): Future<T>;
@@ -182,7 +229,7 @@ export declare class Future<T> implements PromiseLike<T> {
  * The internal value is `task/streams.ts`'s `ErrorContext` (debug message
  * only, per definitions.py).
  */
-export declare class ErrorContext {
+export declare class ErrorContext implements ProtocolErrorContext {
     readonly message: string;
     /** @internal — the internal value, preserved so it can be lowered back. */
     readonly internal: InternalErrorContext;

package/types/exec/boundary.d.ts

@@ -336,6 +336,19 @@ export declare function createLoweredImport(input: {
     mode: SuspensionMode;
     /** Host fn carries the `suspending()` brand (embedder-api.md A1). */
     suspendable: boolean;
+    /**
+     * Host fn carries the `deferCancel()` brand (embedder-api.md A23): the
+     * import must run to completion, so a cancellation is accepted and ignored
+     * instead of taking the default discard.
+     */
+    deferCancel: boolean;
+    /**
+     * Host fn carries the `abortable()` brand (embedder-api.md A24): every call
+     * receives a fresh `AbortSignal` appended after the WIT-declared params, and
+     * the runtime aborts it when — and only when — the call is discarded by a
+     * guest cancellation.
+     */
+    abortable: boolean;
 }): CoreFn;
 /**
  * The callback-ABI dispatch loop of `canon_lift` (definitions.py lines

package/types/exec/host_streams.d.ts

@@ -37,6 +37,49 @@ export declare class HostBuffer {
      * writer used.
      */
     taken(): PayloadChunk;
+    byteView(n: number): Uint8Array;
+    advanceBytes(k: number): void;
+    endWindow(): void;
+}
+/** The scoped landing zone handed to a `writeDirect` producer (A21, #128). */
+export interface DirectDestination {
+    /**
+     * The reader's still-unfilled bytes. Re-derived on every call (a
+     * `memory.grow` between two rendezvous of one session never yields a stale
+     * view) and shrinking by whatever has been marked so far in THIS
+     * invocation. DEAD once the callback returns.
+     */
+    remaining(): Uint8Array;
+    /**
+     * Acknowledge bytes written into the view. Cumulative within the
+     * invocation; acknowledged only if the callback then returns cleanly.
+     */
+    markWritten(n: number): void;
+}
+/** The scoped view handed to a `readDirect` consumer (A21, #128). */
+export interface DirectSource {
+    /**
+     * The writer's unread bytes; read-only by contract. Same scoping and
+     * re-derivation rules as `DirectDestination.remaining`.
+     */
+    remaining(): Uint8Array;
+    /** Acknowledge bytes consumed from the view. See `markWritten`. */
+    markRead(n: number): void;
+}
+/** The callback's poll cadence, spelled event-style (A21). */
+export type DirectVerdict = "more" | "done";
+/**
+ * Out-parameter of the low-level direct forms: `true` iff the session ended
+ * because the callback itself returned `"done"`, rather than because the peer
+ * dropped / the operation was cancelled / the peer's instance trapped.
+ *
+ * The conventions layer needs the distinction for A7 precision — a session
+ * the producer already completed keeps its resolution even if the peer then
+ * trapped — and `Promise<number>` is the contract's return shape, so it rides
+ * here rather than in the resolved value.
+ */
+export interface DirectSessionInfo {
+    endedByVerdict: boolean;
 }
 /** Host end the embedder WRITES; the guest reads. */
 export interface HostWritableEnd<T> {
@@ -65,6 +108,24 @@ export interface HostWritableEnd<T> {
      * if the reader dropped.
      */
     writeAll(values: T[]): Promise<number>;
+    /**
+     * Park a **direct session** on this end (`stream<u8>` only — embedder-api
+     * amendment A21, polyengine#128).
+     *
+     * At every rendezvous with a reader of nonzero capacity, `produce` runs
+     * exactly once, synchronously, inside the rendezvous, with a
+     * `DirectDestination` over the reader's unfilled landing zone — guest linear
+     * memory when the peer is a guest, so the producer's own `set()` is the
+     * canonical-ABI copy. `"more"` keeps the session parked for the next
+     * rendezvous; `"done"` ends it. Resolves with the session's total.
+     *
+     * Marks acknowledge on clean return only. `"done"` with zero marked is
+     * *retraction* (the session ends, the reader's operation stays parked, no
+     * event); `"more"` with zero marked, and a throwing callback, reject.
+     *
+     * Participates in the one-in-flight-per-end rule exactly as `write` does.
+     */
+    writeDirect(produce: (dest: DirectDestination) => DirectVerdict, info?: DirectSessionInfo): Promise<number>;
     /**
      * Cancel an in-flight `write`/`writeAll` (definitions.py
      * `SharedStreamImpl.cancel` -> `CopyResult.CANCELLED`). No-op when nothing
@@ -92,6 +153,15 @@ export interface HostReadableEnd<T> {
      * array.
      */
     read(max: number): Promise<T[]>;
+    /**
+     * Park a **direct session** on this end (`stream<u8>` only — embedder-api
+     * amendment A21, polyengine#128). The mirror of
+     * `HostWritableEnd.writeDirect`: `consume` receives a `DirectSource` over
+     * the writer's unread bytes (a view of guest memory, or of the offered
+     * host chunk itself) and may take a prefix — a partial take is normal, and
+     * the writer re-offers on its own schedule.
+     */
+    readDirect(consume: (src: DirectSource) => DirectVerdict, info?: DirectSessionInfo): Promise<number>;
     /** Cancel an in-flight `read`; see `HostWritableEnd.cancelWrite`. */
     cancelRead(): void;
     drop(): void;

package/types/jspi/suspending.d.ts

@@ -1 +1 @@
-export { anySuspendingImport, isSuspending, suspending } from "@polyengine/protocol";
+export { abortable, anySuspendingImport, deferCancel, isAbortable, isDeferCancel, isSuspending, suspending, } from "@polyengine/protocol";

package/types/task/streams.d.ts

@@ -51,7 +51,90 @@ export declare class GuestBuffer {
     read(n: number): PayloadChunk;
     /** definitions.py `WritableBufferGuestImpl.write`. */
     write(vs: PayloadChunk): void;
+    /**
+     * A fresh view over the next `n` bytes of this buffer's remaining range.
+     *
+     * Fresh on every call, via `bytesOf` (cabi/memory.ts:195) over the
+     * `LiveMemory` getters — so a `memory.grow` between two rendezvous of one
+     * parked direct session never yields a view onto the detached buffer.
+     */
+    byteView(n: number): Uint8Array;
+    /**
+     * Advance by `k` WITHOUT copying: the bytes already moved through the view
+     * `byteView` handed out. Called by the seam only after the direct callback
+     * returned cleanly, which is what makes marks acknowledge-on-clean-return.
+     */
+    advanceBytes(k: number): void;
+}
+/**
+ * The buffer surface the rendezvous actually uses (definitions.py `Buffer`,
+ * line 918). `GuestBuffer` and the host layer's `HostBuffer` both satisfy it.
+ */
+export interface RendezvousBuffer {
+    remain(): number;
+    isZeroLength(): boolean;
+    read(n: number): PayloadChunk;
+    write(vs: PayloadChunk): void;
+}
+/**
+ * A21: the peer half of a direct rendezvous — a buffer that can expose its
+ * remaining range as bytes and be advanced without a copy.
+ *
+ * Implemented by `GuestBuffer` (a view into guest linear memory: the
+ * embedder's own `set()` becomes the one ABI copy) and by `HostBuffer` (a
+ * view of the offered chunk when it is the source; a synthesized scratch that
+ * becomes the delivered chunk when it is the destination).
+ */
+export interface ByteWindow {
+    /**
+     * A view over the next `n` bytes. May be called several times within one
+     * direct invocation (`remaining()` re-derives on every call); an
+     * implementation that *synthesizes* the window must return the same
+     * storage for the whole invocation and release it in `endWindow`.
+     */
+    byteView(n: number): Uint8Array;
+    /** Record `k` bytes as moved. Called only after a clean callback return. */
+    advanceBytes(k: number): void;
+    /** End of one direct invocation; drop any synthesized window. */
+    endWindow?(): void;
+}
+/**
+ * A21: the parked direct session, as the rendezvous sees it. It presents the
+ * ordinary buffer surface (so `remain()`/`isZeroLength()` keep the reference
+ * control flow working) but its `read`/`write` are never called — the seam
+ * routes it through `runDirect` instead.
+ */
+export interface DirectBuffer extends RendezvousBuffer {
+    readonly direct: true;
+    /**
+     * Run this session's callback exactly once against the peer's window,
+     * with `n` bytes of capacity. Applies the acknowledged marks to `peer`
+     * itself, and settles the session on failure — the seam only routes the
+     * rendezvous state that follows.
+     */
+    runDirect(peer: ByteWindow, n: number): DirectOutcome;
+    /**
+     * Reject this session out-of-band (the two-direct-sessions rendezvous,
+     * where neither side owns memory).
+     */
+    failDirect(error: Error): void;
 }
+/**
+ * What the seam did, and hence how the rendezvous must continue.
+ *
+ *  * `"chunk"` — no direct session was involved: the reference copy ran.
+ *  * `"copied"` — the callback acknowledged ≥ 1 byte; continue exactly as
+ *    after a reference copy (fire the pending side's `on_copy`).
+ *  * `"retracted"` — `"done"` with zero marked. Continue as if the direct
+ *    side's buffer had had `remain() == 0` all along, which is a state
+ *    definitions.py already routes.
+ *  * `"failed"` — misuse or a throwing callback; the session has already
+ *    rejected. No copy, no event, the peer's parked operation survives.
+ *  * `"both-direct"` — neither side owns memory; the ARRIVING side is
+ *    rejected by the caller and the parked side is left undisturbed.
+ */
+export type DirectOutcome = "copied" | "retracted" | "failed";
+export type RendezvousOutcome = DirectOutcome | "chunk" | "both-direct";
 /** Common shape of the object a `stream`/`future` *value* refers to. */
 export interface SharedBase {
     readonly t: ValType | null;