@polyengine/runtime 0.4.0 → 0.5.0

package/esm/embedder/copy.js

@@ -29,7 +29,7 @@ export const COPY_URL = import.meta.url;
  * @internal — copy-identity constant for the A9 multi-copy diagnostics; not
  * host-facing.
  */
-export const RUNTIME_VERSION = "0.4.0";
+export const RUNTIME_VERSION = "0.5.0";
 /**
  * Compose a cross-copy diagnostic: what was foreign, which copy is speaking,
  * the census of every copy in the graph, and the by-value remediation.

package/esm/embedder/mod.js

@@ -22,19 +22,30 @@ registerRuntimeCopy({
     protocolGeneration: PROTOCOL_GENERATION,
 });
 export { COPY_URL, RUNTIME_VERSION } from "./copy.js";
-// The A9 vocabulary, re-exported unchanged: embedder code needs no import
-// change, and consumers that want the multi-copy-robust spellings get them
-// from the same module they already import.
-export { copyCensus, defineRealmLocal, DROPPED, ERROR_CONTEXT, fromCloneable, FUTURE, hasBrand, INVALID_HANDLE, isDroppedError, isInvalidHandleError, isPeerTrappedError, isRealmLocal, isStreamProducerError, isSuspending, isTrap, isComponentException, PEER_TRAPPED, PROTOCOL_GENERATION, REALM_LOCAL, registerRuntimeCopy, RESOURCE_STATE, runtimeCopies, STREAM, STREAM_PRODUCER, SUSPENDING, toCloneable, TRAP, COMPONENT_EXCEPTION, } from "@polyengine/protocol";
+// Amendment A22 (contracts/embedder-api.md §"The host-ABI surface and its
+// version"): the runtime's exported surface is application-only. The A9
+// courtesy re-exports (error classes, predicates, brands, `suspending`,
+// realm crossing, the copy registry) are removed — host modules import that
+// vocabulary from `@polyengine/protocol` directly. The runtime still
+// registers its own copy on the census above; it just no longer hands out
+// the registry API to callers of this module.
 export { artifactsFromEnvelope, instantiate, instantiateEmbedder, resolveArtifacts, } from "./instantiate.js";
 export { requiredImports } from "./imports.js";
-export { DroppedError, InvalidHandleError, NameCollisionError, PeerTrappedError, Trap, ComponentException, } from "./errors.js";
-export { ErrorContext, Future, Stream, StreamProducerError, StreamWriter, } from "./streams.js";
+// `NameCollisionError` is the one error class that stays here: it's raised
+// while building an instantiation facade, before any handle/value exists —
+// application machinery, not host-ABI vocabulary (contracts/embedder-api.md
+// §"The host-ABI surface and its version", amendment A22).
+export { NameCollisionError } from "./errors.js";
+// `createStream<T>()` — the A22 stream-pair factory (contracts/embedder-api.md
+// §"The host-ABI surface and its version" / §"Streams and futures"): the
+// `Stream.create()` static's application-surface spelling, since the
+// concrete `Stream`/`StreamWriter` classes are no longer exported. Handle
+// TYPES are spelled against `@polyengine/protocol`'s structural interfaces.
+import { Stream as InternalStream } from "./streams.js";
+export function createStream() {
+    return InternalStream.create();
+}
 export { GuestResource, HostResourceRegistry } from "./resources.js";
 export { camelCase, parseLeafName, pascalCase } from "./casing.js";
-// Per-declaration suspendability (contracts/embedder-api.md §"Functions and
-// async", amendment A1): declares that a sync-typed host import may return a
-// Promise, parking the calling wasm frame (JSPI engines only).
-export { suspending } from "../jspi/suspending.js";
 export { asTrackKeySpelling, compareSemver, ImportRegistrationError, ImportResolutionError, ImportResolver, parseInterfaceId, parseSemver, trackKey, } from "./version.js";
 export { BorrowScope, fromHost, toHost, } from "./values.js";

package/esm/embedder/streams.js

@@ -10,7 +10,7 @@
 import { despecialize } from "../cabi/types.js";
 import { hostFuture, hostFutureFor, hostStream, hostStreamFor, } from "../exec/host_streams.js";
 import { CopyResult, dropSharedForTeardown, poisonFailureOf, } from "../task/mod.js";
-import { defineBrand, defineRealmLocal, ERROR_CONTEXT, FUTURE, hasBrand, isStreamProducerError, STREAM, StreamProducerError, } from "@polyengine/protocol";
+import { defineBrand, defineRealmLocal, ERROR_CONTEXT, FUTURE, hasBrand, isStreamProducerError, STREAM, StreamProducerError, STREAM_WRITER, } from "@polyengine/protocol";
 import { describeCrossCopy } from "./copy.js";
 import { DroppedError, PeerTrappedError } from "./errors.js";
 // `StreamProducerError`'s canonical definition moved to `@polyengine/protocol`
@@ -85,6 +85,16 @@ function throwIfPeerTrapped(value, where, progress) {
 export function isU8Element(element) {
     return element !== null && despecialize(element).kind === "u8";
 }
+/**
+ * A21 (#128): the direct-access byte edges are `stream<u8>` only. A
+ * zero-width element type (`t === null`) is not u8 either.
+ */
+function requireU8Direct(codec, who) {
+    if (codec === null || !isU8Element(codec.element)) {
+        throw new TypeError(`${who} is available on stream<u8> only (embedder-api amendment A21, ` +
+            `polyengine#128); use write()/read() for other element types`);
+    }
+}
 /**
  * A stream handle.
  *
@@ -203,6 +213,45 @@ export class Stream {
             throwIfPeerTrapped(host.value, where);
         return this.#chunk(raw);
     }
+    /**
+     * 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.
+     */
+    async readDirect(consume) {
+        const host = this.#require();
+        const where = this.#codec?.where ?? "stream read";
+        throwIfFailed(host.value, where);
+        requireU8Direct(this.#codec, "readDirect");
+        const info = { endedByVerdict: false };
+        const n = await host.readable.readDirect(consume, info);
+        // A7 precision, `read`'s rule adapted: a session the CONSUMER itself
+        // ended with `"done"` genuinely completed and keeps its resolution. Any
+        // other way out (the writer dropped, the session was cancelled, the
+        // retirement walk settled us) is a settle-path this consumer did not
+        // cause — so if the peer's instance trapped, reject with the delivered
+        // count rather than fake a clean end.
+        if (!info.endedByVerdict)
+            throwIfPeerTrapped(host.value, where, n);
+        return n;
+    }
     #chunk(raw) {
         const codec = this.#codec;
         if (isU8Element(codec.element)) {
@@ -327,6 +376,44 @@ export class StreamWriter {
             throwIfPeerTrapped(host.value, where, n);
         return n;
     }
+    /**
+     * 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`.
+     */
+    async writeDirect(produce) {
+        await this.#stream.whenBound();
+        const host = hostOf(this.#stream);
+        const where = this.#stream.codec?.where ?? "stream write";
+        throwIfFailed(host.value, where);
+        requireU8Direct(this.#stream.codec, "writeDirect");
+        const info = { endedByVerdict: false };
+        const n = await host.writable.writeDirect(produce, info);
+        // A7 precision, `write`'s short-take rule adapted: a session the PRODUCER
+        // itself ended with `"done"` keeps its resolution; every other way out is
+        // a settle-path the producer did not cause, so a trapped peer rejects
+        // here carrying the delivered count.
+        if (!info.endedByVerdict)
+            throwIfPeerTrapped(host.value, where, n);
+        return n;
+    }
     /** Offer values until all are taken or the reader goes away. */
     async writeAll(values) {
         await this.#stream.whenBound();
@@ -544,11 +631,15 @@ export class ErrorContext {
         defineRealmLocal(this);
     }
 }
-// A9 brands (contracts/embedder-api.md §"Module identity"): the three
-// STATEFUL embedder-facing handle classes. Their machinery lives in the copy
-// that minted them, so the brand never makes a foreign handle usable — it
-// makes it DIAGNOSABLE, at the lowering sites below.
+// A9 brands (contracts/embedder-api.md §"Module identity"): the STATEFUL
+// embedder-facing handle classes. Their machinery lives in the copy that
+// minted them, so the brand never makes a foreign handle usable — it makes
+// it DIAGNOSABLE, at the lowering sites below. `StreamWriter` gains its
+// brand with amendment A22 (§"The host-ABI surface and its version"):
+// writers carried none before because nothing needed to recognize one, and
+// `isStreamWriter` now does.
 defineBrand(Stream.prototype, STREAM);
+defineBrand(StreamWriter.prototype, STREAM_WRITER);
 defineBrand(Future.prototype, FUTURE);
 defineBrand(ErrorContext.prototype, ERROR_CONTEXT);
 /**

package/esm/exec/host_streams.js

@@ -186,6 +186,55 @@ export class HostBuffer {
         }
         return out;
     }
+    // --- A21 `ByteWindow` (embedder-api amendment A21, polyengine#128) ---
+    //
+    // A host buffer can be the PEER of a direct session on the other end of a
+    // host↔host rendezvous. Which of the two shapes it takes follows from the
+    // direction it was built for, exactly as `read`/`write` above do:
+    //
+    //   * SOURCE (`values !== null`, a parked `write`): the window is a view of
+    //     the offered chunk itself — the A5 borrow, scoped to the callback. No
+    //     extra copy at all.
+    //   * DESTINATION (`values === null`, a parked/arriving `read(max)`): there
+    //     is no landing zone to view, so the window is a fresh scratch; the
+    //     marked prefix becomes the delivered chunk (ownership passes with it,
+    //     and `taken()` hands a sole chunk through unsliced).
+    /** The synthesized destination window, live for one direct invocation. */
+    #scratch = null;
+    byteView(n) {
+        assert_(n <= this.remain(), "host direct window beyond remaining");
+        if (this.values === null) {
+            // Stable for the whole invocation: `remaining()` re-derives on every
+            // call and the producer's earlier `set()`s must survive that.
+            if (this.#scratch === null || this.#scratch.length !== n) {
+                this.#scratch = new Uint8Array(n);
+            }
+            return this.#scratch;
+        }
+        assert_(this.values instanceof Uint8Array, "host direct window on a non-u8 chunk");
+        return this.values.subarray(this.progress, this.progress + n);
+    }
+    advanceBytes(k) {
+        assert_(k >= 0 && k <= this.remain(), "host direct advance beyond remaining");
+        if (this.values === null) {
+            // A callback may mark bytes it never actually looked at the window to
+            // write (nonsense, but the runtime must stay total rather than trip an
+            // internal assertion). The acknowledged prefix is then whatever the
+            // synthesized landing zone held — zeroes — which is the faithful
+            // analogue of the guest-peer case, where it would be whatever the
+            // reader's memory already contained.
+            const scratch = this.#scratch ?? new Uint8Array(k);
+            // Delivered as an owned chunk; `write` is the same call the reference
+            // copy would have made, so `remain()`/`taken()` stay consistent.
+            this.write(scratch.subarray(0, k));
+        }
+        else {
+            this.progress += k;
+        }
+    }
+    endWindow() {
+        this.#scratch = null;
+    }
 }
 /**
  * Every live `HostActivity` arm, by identity. These are the promises this
@@ -418,6 +467,209 @@ class HostActivity {
         this.#arm();
     }
 }
+/**
+ * The `DirectDestination`/`DirectSource` object itself. One per INVOCATION,
+ * not per session: "the object dies when the callback returns" is the
+ * contract's validity window, and every later method call throws a
+ * `TypeError` naming the rule.
+ */
+class DirectScope {
+    peer;
+    capacity;
+    marked = 0;
+    #live = true;
+    constructor(peer, 
+    /** The peer's actual remaining capacity — never the parked sentinel. */
+    capacity) {
+        this.peer = peer;
+        this.capacity = capacity;
+    }
+    remaining() {
+        this.#check();
+        // Re-derived per call: `byteView` is grow-safe for a guest peer, and the
+        // `subarray` accounts for the marks made so far in this invocation.
+        return this.peer.byteView(this.capacity).subarray(this.marked);
+    }
+    markWritten(n) {
+        this.#mark(n, "markWritten");
+    }
+    markRead(n) {
+        this.#mark(n, "markRead");
+    }
+    #mark(n, who) {
+        this.#check();
+        if (!Number.isInteger(n) || n < 0) {
+            throw new TypeError(`${who}(${n}): a direct-access mark must be a non-negative integer`);
+        }
+        if (this.marked + n > this.capacity) {
+            throw new TypeError(`${who}(${n}) would take the invocation's cumulative mark to ` +
+                `${this.marked + n}, past the ${this.capacity} byte(s) the view ` +
+                `held on entry (embedder-api amendment A21)`);
+        }
+        this.marked += n;
+    }
+    #check() {
+        if (!this.#live) {
+            throw new TypeError("this direct-access view is dead: a DirectDestination/DirectSource " +
+                "is scoped to the synchronous callback invocation it was passed " +
+                "to, and retaining one past its return is misuse (embedder-api " +
+                "amendment A21, polyengine#128)");
+        }
+    }
+    /**
+     * End of the invocation: the object is dead, and every later method call
+     * throws. Releasing the peer's synthesized window is the caller's job
+     * (`DirectSession.runDirect`), because it must happen strictly after the
+     * acknowledged marks are applied.
+     */
+    die() {
+        this.#live = false;
+    }
+}
+/**
+ * A parked direct session, as both halves see it: a `DirectBuffer` to the
+ * rendezvous (task/streams.ts) and a promise to the embedder.
+ *
+ * It presents the ordinary buffer surface so the reference control flow keeps
+ * working unchanged — `remain()` answers a positive SENTINEL while the session
+ * is live, which only ever feeds the rendezvous' `min()` and so resolves to
+ * the peer's real capacity — but `read`/`write` are unreachable: the seam
+ * routes a direct buffer through `runDirect` instead.
+ */
+class DirectSession {
+    t;
+    invoke;
+    direct = true;
+    /** Bytes acknowledged across the whole session. */
+    total = 0;
+    /** The callback said `"done"`, or the session failed / was settled. */
+    ended = false;
+    /** `ended` because the callback said so (A7 precision; see `DirectSessionInfo`). */
+    endedByVerdict = false;
+    /** Installed in the shared object's pending slot right now. */
+    pending = false;
+    /** `cancelWrite`/`cancelRead` arrived; stop at the next loop top. */
+    cancelled = false;
+    #settle = null;
+    #reject = null;
+    constructor(t, invoke) {
+        this.t = t;
+        this.invoke = invoke;
+    }
+    // --- buffer surface (definitions.py `Buffer`) ---
+    remain() {
+        // The sentinel is `Buffer.MAX_LENGTH`, the largest value the rendezvous
+        // can legally see; it never surfaces to the embedder because the scope is
+        // built from `min(peer.remain(), sentinel)`.
+        return this.ended ? 0 : BUFFER_MAX_LENGTH;
+    }
+    isZeroLength() {
+        return false;
+    }
+    read(_n) {
+        throw new Error("internal: a direct session must go through the A21 seam");
+    }
+    write(_vs) {
+        throw new Error("internal: a direct session must go through the A21 seam");
+    }
+    // --- the direct protocol ---
+    runDirect(peer, n) {
+        const scope = new DirectScope(peer, n);
+        try {
+            return this.#runDirect(scope, peer);
+        }
+        finally {
+            // Release any window the peer SYNTHESIZED (a `HostBuffer` destination's
+            // scratch). Strictly after `advanceBytes`, which is what turns the
+            // marked prefix of that scratch into the delivered chunk.
+            peer.endWindow?.();
+        }
+    }
+    #runDirect(scope, peer) {
+        let verdict;
+        try {
+            verdict = this.invoke(scope);
+        }
+        catch (e) {
+            // "A callback that throws rejects the session with that error, and the
+            // invocation's marks are discarded" — so nothing touches `peer`.
+            scope.die();
+            this.#fail(e);
+            return "failed";
+        }
+        scope.die();
+        if (verdict !== "more" && verdict !== "done") {
+            this.#fail(new TypeError(`a direct-access callback must return "more" or "done", got ` +
+                `${JSON.stringify(verdict)} (embedder-api amendment A21)`));
+            return "failed";
+        }
+        const k = scope.marked;
+        if (k === 0) {
+            if (verdict === "done") {
+                // Retraction: the speculative-park correction. The session ends with
+                // its running total and the peer's operation stays parked.
+                this.ended = true;
+                this.endedByVerdict = true;
+                return "retracted";
+            }
+            this.#fail(new TypeError('a direct-access callback returned "more" without marking any ' +
+                "bytes; a session that has nothing to offer retracts by " +
+                'returning "done" (embedder-api amendment A21, polyengine#128)'));
+            return "failed";
+        }
+        // Marks acknowledge ON CLEAN RETURN ONLY: this is the first and only
+        // place the peer's progress moves, and it completes the copy with `k`.
+        peer.advanceBytes(k);
+        this.total += k;
+        if (verdict === "done") {
+            this.ended = true;
+            this.endedByVerdict = true;
+        }
+        return "copied";
+    }
+    failDirect(error) {
+        this.#fail(error);
+    }
+    // --- promise plumbing ---
+    /** Arm the settle hooks for one issuance of this session. */
+    arm(settle, reject) {
+        this.#settle = settle;
+        this.#reject = reject;
+    }
+    #take() {
+        const s = this.#settle, r = this.#reject;
+        this.#settle = null;
+        this.#reject = null;
+        return [s, r];
+    }
+    #fail(e) {
+        this.ended = true;
+        this.pending = false;
+        const [, r] = this.#take();
+        r?.(e);
+    }
+    /** The session is over; the driving loop resolves with `total`. */
+    finish() {
+        this.ended = true;
+        this.pending = false;
+        const [s] = this.#take();
+        s?.("done");
+    }
+    /** This issuance rendezvoused but the session lives; re-issue it. */
+    reissue() {
+        this.pending = false;
+        const [s] = this.#take();
+        s?.("reissue");
+    }
+}
+/** A21 is `stream<u8>` only; `null` (zero-width) is not u8 either. */
+function requireU8Element(t, who) {
+    if (t === null || despecialize(t).kind !== "u8") {
+        throw new TypeError(`${who} is available on stream<u8> only; this stream's element type ` +
+            `is ${t === null ? "the zero-width payload" : despecialize(t).kind} ` +
+            `(embedder-api amendment A21, polyengine#128)`);
+    }
+}
 /**
  * Attach host-activity bookkeeping to a shared object at the CABI seam.
  *
@@ -516,6 +768,92 @@ function mkStreamEnds(shared, activity) {
         else
             activity.notify();
     };
+    /** The live direct session on each end, if any (A21, polyengine#128). */
+    const direct = {
+        read: null,
+        write: null,
+    };
+    /**
+     * Drive one direct session from park to end (A21).
+     *
+     * Two shapes reach us, and the difference is *which side arrived second*:
+     *
+     *  * the session is the PENDING side — every rendezvous fires `onCopy`, and
+     *    the `"more"` verdict simply declines to `reclaim()`, so the session
+     *    stays in the pending slot for the next peer operation. This is
+     *    `write()`'s "stay parked until the offer is exhausted" mechanism, with
+     *    the callback's verdict in place of `buf.remain() > 0`.
+     *  * the session ARRIVED second — the rendezvous completes it with
+     *    `onCopyDone(COMPLETED)`, so a `"more"` verdict has to re-issue. The
+     *    re-issue rides the loop below (one `await` apart), which is exactly
+     *    `writeAll`'s re-offer shape and therefore inherits its ordering: the
+     *    peer's pending event is delivered and its buffer reclaimed before we
+     *    can rendezvous against it a second time.
+     */
+    const runDirectSession = async (side, session) => {
+        parked[side] = true;
+        direct[side] = session;
+        try {
+            for (;;) {
+                if (session.cancelled)
+                    break;
+                const step = await new Promise((res, rej) => {
+                    session.arm(res, rej);
+                    session.pending = true;
+                    const onCopy = (reclaim) => {
+                        if (!session.ended)
+                            return; // "more": stay parked
+                        reclaim();
+                        activity.notify();
+                        session.finish();
+                    };
+                    const onCopyDone = (result) => {
+                        session.pending = false;
+                        settle(result);
+                        // COMPLETED with the session still live == the arriving-side
+                        // rendezvous above; anything else (DROPPED, CANCELLED, or the
+                        // retraction path through `reset_and_notify_pending`) ends it.
+                        if (result === CopyResult.COMPLETED && !session.ended) {
+                            session.reissue();
+                        }
+                        else {
+                            session.finish();
+                        }
+                    };
+                    if (side === "write") {
+                        shared.write(writeInst, session, onCopy, onCopyDone);
+                    }
+                    else {
+                        shared.read(readInst, session, onCopy, onCopyDone);
+                    }
+                    activity.notify();
+                    activity.pump();
+                });
+                if (step === "done")
+                    break;
+            }
+        }
+        finally {
+            parked[side] = false;
+            direct[side] = null;
+        }
+        return session.total;
+    };
+    /** Shared tail of `cancelWrite`/`cancelRead` for a parked direct session. */
+    const cancelDirect = (session) => {
+        // A21: cancelling RETRACTS the session — it resolves with its running
+        // total (A8's indistinguishability caveats unchanged). `shared.cancel()`
+        // only when the session actually holds the pending slot: a session caught
+        // between two issuances holds nothing, and `SharedBase.cancel` asserts
+        // that something is pending.
+        session.cancelled = true;
+        if (session.pending)
+            shared.cancel();
+        else
+            session.finish();
+        activity.notify();
+        activity.pump();
+    };
     return {
         writable: {
             write(values) {
@@ -579,9 +917,29 @@ function mkStreamEnds(shared, activity) {
                 }
                 return sent;
             },
+            writeDirect(produce, info) {
+                // Same one-in-flight-per-end rule, same wording shape as `write`:
+                // `writeDirect` participates in it exactly as `write` does (A21).
+                if (parked.write) {
+                    throw new TypeError("a write is already in flight on this stream's writable end; " +
+                        "await it or cancelWrite() first");
+                }
+                requireU8Element(shared.t, "writeDirect");
+                const session = new DirectSession(shared.t, (scope) => produce(scope));
+                const p = runDirectSession("write", session);
+                if (info === undefined)
+                    return p;
+                return p.then((n) => {
+                    info.endedByVerdict = session.endedByVerdict;
+                    return n;
+                });
+            },
             cancelWrite() {
                 if (!parked.write)
                     return;
+                const session = direct.write;
+                if (session !== null)
+                    return cancelDirect(session);
                 parked.write = false;
                 shared.cancel();
                 activity.notify();
@@ -622,6 +980,21 @@ function mkStreamEnds(shared, activity) {
                     activity.pump();
                 });
             },
+            readDirect(consume, info) {
+                if (parked.read) {
+                    throw new TypeError("a read is already in flight on this stream's readable end; " +
+                        "await it or cancelRead() first");
+                }
+                requireU8Element(shared.t, "readDirect");
+                const session = new DirectSession(shared.t, (scope) => consume(scope));
+                const p = runDirectSession("read", session);
+                if (info === undefined)
+                    return p;
+                return p.then((n) => {
+                    info.endedByVerdict = session.endedByVerdict;
+                    return n;
+                });
+            },
             cancelRead() {
                 // #97, DELIBERATE AND PINNED: cancelling resolves the in-flight
                 // `read` promise with whatever the buffer took so far — for a read
@@ -635,6 +1008,9 @@ function mkStreamEnds(shared, activity) {
                 // this state — a guest cannot cancel the host's read.
                 if (!parked.read)
                     return;
+                const session = direct.read;
+                if (session !== null)
+                    return cancelDirect(session);
                 parked.read = false;
                 shared.cancel();
                 activity.notify();

package/esm/task/streams.js

@@ -45,6 +45,7 @@
 // expressible.
 import { defineBrand, ERROR_CONTEXT } from "@polyengine/protocol";
 import { assert_, Trap, trapIf } from "../cabi/trap.js";
+import { bytesOf } from "../cabi/memory.js";
 import { loadListFromValidRange } from "../cabi/load.js";
 import { storeListIntoValidRange } from "../cabi/store.js";
 import { alignment, alignTo, elemSize } from "../cabi/layout.js";
@@ -141,6 +142,69 @@ export class GuestBuffer {
         }
         this.progress += vs.length;
     }
+    // --- A21 direct-access byte edges (embedder-api amendment A21, #128) ---
+    //
+    // `ByteWindow`, implemented for the `stream<u8>` case only. The two methods
+    // together are the copy `read`/`write` would have done, split so that the
+    // *peer's* callback performs it: `byteView` hands out the range, and
+    // `advanceBytes` records the bytes that actually moved. They are role-blind
+    // (destination or source) because `this.ptr` already advances on BOTH
+    // `read` and `write` above, and `elemSize(u8) === 1`.
+    /**
+     * 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) {
+        assert_(this.t !== null && despecialize(this.t).kind === "u8", "direct byte window on a non-u8 buffer");
+        assert_(n <= this.remain(), "direct byte window beyond remaining");
+        const mem = this.cx.opts.memory;
+        assert_(mem !== null, "direct byte window requires a memory");
+        return bytesOf(mem, this.ptr, n);
+    }
+    /**
+     * 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) {
+        assert_(k >= 0 && k <= this.remain(), "direct advance beyond remaining");
+        this.ptr += k; // elemSize(u8) === 1
+        this.progress += k;
+    }
+}
+function isDirectBuffer(b) {
+    return b.direct === true;
+}
+/**
+ * The one copy site, shared by `SharedStreamImpl.read` and `.write`.
+ *
+ * Collapses to definitions.py's `dst_buffer.write(src_buffer.read(n))`
+ * whenever neither side is a direct session — which is every guest↔guest,
+ * guest↔host-chunk and host-chunk↔host-chunk rendezvous, i.e. everything
+ * that existed before A21.
+ */
+function rendezvousCopy(src, dst, n) {
+    const srcDirect = isDirectBuffer(src);
+    const dstDirect = isDirectBuffer(dst);
+    if (!srcDirect && !dstDirect) {
+        dst.write(src.read(n));
+        return "chunk";
+    }
+    if (srcDirect && dstDirect)
+        return "both-direct";
+    return srcDirect
+        ? src.runDirect(dst, n)
+        : dst.runDirect(src, n);
+}
+/** The A21 rejection for a rendezvous of two direct sessions. */
+function bothDirectError() {
+    return new TypeError("at least one side of a host-to-host rendezvous must use the chunk " +
+        "forms: two direct-access sessions cannot rendezvous with each other " +
+        "because neither side owns the memory the other would write into " +
+        "(embedder-api amendment A21, polyengine#128)");
 }
 /**
  * definitions.py `none_or_number_type` (line 1070). Guards the "temporary"
@@ -272,7 +336,19 @@ export class SharedStreamImpl {
             if (this.pendingBuffer.remain() > 0) {
                 if (dstBuffer.remain() > 0) {
                     const n = Math.min(dstBuffer.remain(), this.pendingBuffer.remain());
-                    dstBuffer.write(this.pendingBuffer.read(n));
+                    // A21 seam (#128). `"chunk"` is the reference line verbatim.
+                    const pendingIsDirect = isDirectBuffer(this.pendingBuffer);
+                    const out = rendezvousCopy(this.pendingBuffer, dstBuffer, n);
+                    if (out === "both-direct") {
+                        // The ARRIVING side (here the reader) is the one refused; the
+                        // parked session keeps the pending slot, undisturbed.
+                        dstBuffer.failDirect(bothDirectError());
+                        return;
+                    }
+                    if (out === "retracted" || out === "failed") {
+                        this.#routeDirectNoCopy(out, pendingIsDirect, inst, dstBuffer, onCopy, onCopyDone);
+                        return;
+                    }
                     this.pendingOnCopy(() => this.resetPending());
                 }
                 onCopyDone(CopyResult.COMPLETED);
@@ -298,7 +374,19 @@ export class SharedStreamImpl {
             if (this.pendingBuffer.remain() > 0) {
                 if (srcBuffer.remain() > 0) {
                     const n = Math.min(srcBuffer.remain(), this.pendingBuffer.remain());
-                    this.pendingBuffer.write(srcBuffer.read(n));
+                    // A21 seam (#128). `"chunk"` is the reference line verbatim.
+                    const pendingIsDirect = isDirectBuffer(this.pendingBuffer);
+                    const out = rendezvousCopy(srcBuffer, this.pendingBuffer, n);
+                    if (out === "both-direct") {
+                        // The ARRIVING side (here the writer) is refused; the parked
+                        // session keeps the pending slot.
+                        srcBuffer.failDirect(bothDirectError());
+                        return;
+                    }
+                    if (out === "retracted" || out === "failed") {
+                        this.#routeDirectNoCopy(out, pendingIsDirect, inst, srcBuffer, onCopy, onCopyDone);
+                        return;
+                    }
                     this.pendingOnCopy(() => this.resetPending());
                 }
                 onCopyDone(CopyResult.COMPLETED);
@@ -315,6 +403,43 @@ export class SharedStreamImpl {
             }
         }
     }
+    /**
+     * A21 (#128): route a rendezvous whose direct session did NOT copy.
+     *
+     * Two outcomes land here, and both share one invariant: the peer's parked
+     * operation survives, no event is delivered, and the stream is not dropped
+     * — a runtime never emits a zero-progress COMPLETED copy, which is
+     * unreachable in definitions.py for a nonzero-capacity operation.
+     *
+     *  * `"retracted"` — `"done"` with zero marked. The session ends and
+     *    resolves with its running total, through the ordinary
+     *    `on_copy_done(COMPLETED)` channel.
+     *  * `"failed"` — misuse or a throwing callback. The session has ALREADY
+     *    rejected (`DirectSession.#fail`), so it must be retired silently:
+     *    its rejection is its notification.
+     *
+     * Which side was the session decides where each goes, and both shapes are
+     * states definitions.py already produces:
+     *
+     *  * PARKED session ⇒ the "the parked side had nothing left" branch
+     *    (definitions.py:1043/1063): retire it and park the arriving
+     *    operation, which gets no event either way.
+     *  * ARRIVING session ⇒ the "arriving buffer of zero capacity" state
+     *    (definitions.py:1041/1057): the pending side is left untouched with
+     *    its `on_copy` unfired, and the arriving side completes.
+     */
+    #routeDirectNoCopy(out, pendingIsDirect, inst, arriving, onCopy, onCopyDone) {
+        if (pendingIsDirect) {
+            if (out === "retracted")
+                this.resetAndNotifyPending(CopyResult.COMPLETED);
+            else
+                this.resetPending();
+            this.setPending(inst, arriving, onCopy, onCopyDone);
+            return;
+        }
+        if (out === "retracted")
+            onCopyDone(CopyResult.COMPLETED);
+    }
     #assertSameElemType(b) {
         // Structural, not identity: definitions.py compares dataclass types with
         // `==`, and our `ValType`s are fresh objects per table (the plan's type

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polyengine/runtime",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A WebAssembly Component Model host for JavaScript engines: plan executor, canonical ABI, 0.3 task scheduler, JSPI bridge, and embedder API.",
   "homepage": "https://github.com/polymorph-components/polyengine#readme",
   "repository": {
@@ -55,7 +55,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@polyengine/protocol": "^0.2.1"
+    "@polyengine/protocol": "^0.2.2"
   },
   "_generatedBy": "dnt@0.43.2"
 }

package/types/embedder/copy.d.ts

@@ -17,7 +17,7 @@ export declare const COPY_URL: string;
  * @internal — copy-identity constant for the A9 multi-copy diagnostics; not
  * host-facing.
  */
-export declare const RUNTIME_VERSION = "0.4.0";
+export declare const RUNTIME_VERSION = "0.5.0";
 /**
  * Compose a cross-copy diagnostic: what was foreign, which copy is speaking,
  * the census of every copy in the graph, and the by-value remediation.

package/types/embedder/mod.d.ts

@@ -1,11 +1,14 @@
 export { COPY_URL, RUNTIME_VERSION } from "./copy.js";
-export { copyCensus, defineRealmLocal, DROPPED, ERROR_CONTEXT, fromCloneable, FUTURE, hasBrand, INVALID_HANDLE, isDroppedError, isInvalidHandleError, isPeerTrappedError, isRealmLocal, isStreamProducerError, isSuspending, isTrap, isComponentException, PEER_TRAPPED, PROTOCOL_GENERATION, REALM_LOCAL, registerRuntimeCopy, RESOURCE_STATE, type RuntimeCopy, runtimeCopies, STREAM, STREAM_PRODUCER, SUSPENDING, toCloneable, TRAP, COMPONENT_EXCEPTION, } from "@polyengine/protocol";
 export { artifactsFromEnvelope, type ComponentArtifacts, type EmbedderInstance, type EmbedderOptions, type InstantiateSource, type UntranslatedArtifacts, instantiate, instantiateEmbedder, resolveArtifacts, } from "./instantiate.js";
 export { type FuncSummary, type ImportLeaf, type PlanLike, requiredImports } from "./imports.js";
-export { DroppedError, InvalidHandleError, NameCollisionError, PeerTrappedError, Trap, ComponentException, } from "./errors.js";
-export { type Chunk, type ElemCodec, ErrorContext, Future, type FutureSource, Stream, StreamProducerError, type StreamSource, StreamWriter, } from "./streams.js";
+export { NameCollisionError } from "./errors.js";
+export { type ElemCodec } from "./streams.js";
+import type { Stream as ProtocolStream, StreamWriter as ProtocolStreamWriter } from "@polyengine/protocol";
+export declare function createStream<T>(): {
+    stream: ProtocolStream<T>;
+    writer: ProtocolStreamWriter<T>;
+};
 export { GuestResource, HostResourceRegistry } from "./resources.js";
 export { camelCase, type LeafName, parseLeafName, pascalCase } from "./casing.js";
-export { suspending } from "../jspi/suspending.js";
 export { asTrackKeySpelling, compareSemver, ImportRegistrationError, ImportResolutionError, ImportResolver, type ParsedId, parseInterfaceId, parseSemver, type Semver, trackKey, } from "./version.js";
 export { type AdapterOptions, BorrowScope, fromHost, toHost, type ValueBridge, } from "./values.js";

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/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/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;