@statewalker/webrun-streams 0.1.0 → 0.2.0

package/dist/uint32.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uint32.d.ts","sourceRoot":"","sources":["../src/uint32.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,0EAA0E;AAC1E,eAAO,MAAM,UAAU,aAAa,CAAC;AAErC;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU,CAKlD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAGlE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-streams",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "description": "Async-iterator / ReadableStream primitives: collect, text/jsonl codecs, lines, backpressure generators, serialisable errors.",
@@ -16,31 +16,36 @@
     "directory": "packages/webrun-streams"
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "files": [
     "dist",
     "src"
   ],
   "devDependencies": {
-    "@types/node": "^25.6.0",
+    "@types/node": "^26.2.0",
     "rimraf": "^6.1.3",
-    "tsdown": "^0.21.9",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.4"
+    "rolldown": "^1.2.4",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
   },
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
+  "types": "./dist/index.d.ts",
   "scripts": {
-    "build": "tsdown",
+    "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
     "dev": "tsdown --watch",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
+    "typecheck:tests": "tsc -p tsconfig.tests.json",
     "clean": "rimraf dist",
-    "lint": "biome check --write .",
+    "lint": "biome check src tests",
     "format": "biome format --write ."
   }
 }

package/src/duplex.ts

@@ -0,0 +1,59 @@
+/**
+ * The transport seam every `webrun-streams-*` adapter and the conformance suite
+ * are written against.
+ *
+ * These types live here rather than beside an implementation on purpose: the
+ * emulated multiplexer that once declared them is scheduled for deletion, and a
+ * seam that disappears with its first implementation is not a seam.
+ */
+
+/**
+ * Canonical seam for the webrun-streams transport family. A `Duplex` carries
+ * one logical call: caller emits an iterable of bytes as input, peer yields an
+ * async generator of bytes as output. Same shape on both sides — an in-process
+ * test can wire `const caller = handler` and run without any transport.
+ *
+ * Iterator semantics carry every signal:
+ *  - Consumer `.return()` on the output → producer's `finally` runs.
+ *  - Producer `throw` → consumer's `for await` throws.
+ *  - Normal exhaustion on either side → matching end on the other side.
+ */
+export type Duplex = (
+  input: AsyncIterable<Uint8Array> | Iterable<Uint8Array>,
+) => AsyncGenerator<Uint8Array>;
+
+/**
+ * Adapter-side factory that stands up a transport connection and yields a
+ * caller `Duplex`. One `Connect` invocation owns one transport; each call
+ * to the resolved `call` opens a new sub-stream on it.
+ *
+ * A caller must either drain the returned generator or `.return()` it.
+ * Dropping the reference without doing either emits no observable signal:
+ * the abandoned consumer never acknowledges inbound data, so the peer's
+ * outbound pump blocks awaiting that acknowledgement, no end-of-stream is
+ * ever exchanged, and both peers hold the stream's slot open. There is no
+ * way for the transport to detect this — an unreferenced generator is not
+ * observable — so it is the consumer's obligation.
+ */
+export type Connect<P> = (params: P) => Promise<{
+  call: Duplex;
+  close: () => Promise<void>;
+}>;
+
+/**
+ * Adapter-side factory that registers a handler `Duplex` against a transport.
+ * Returns an idempotent teardown.
+ */
+export type Serve<P> = (params: P, handler: Duplex) => Promise<() => Promise<void>>;
+
+/**
+ * Thrown by `emulateMux` and adapters when the underlying transport closes
+ * while one or more `Duplex` calls are in flight. Consumers can catch by
+ * `instanceof TransportClosedError` or by checking `error.name`.
+ */
+export class TransportClosedError extends Error {
+  override readonly name = "TransportClosedError";
+  constructor(message = "transport closed") {
+    super(message);
+  }
+}

package/src/emulate-mux.ts

@@ -1,35 +1,12 @@
+import { type Duplex, TransportClosedError } from "./duplex.js";
 import { deserializeError, serializeError } from "./errors.js";
-
-/**
- * Canonical seam for the webrun-streams transport family. A `Duplex` carries
- * one logical call: caller emits an iterable of bytes as input, peer yields an
- * async generator of bytes as output. Same shape on both sides — an in-process
- * test can wire `const caller = handler` and run without any transport.
- *
- * Iterator semantics carry every signal:
- *  - Consumer `.return()` on the output → producer's `finally` runs.
- *  - Producer `throw` → consumer's `for await` throws.
- *  - Normal exhaustion on either side → matching end on the other side.
- */
-export type Duplex = (
-  input: AsyncIterable<Uint8Array> | Iterable<Uint8Array>,
-) => AsyncGenerator<Uint8Array>;
-
-/**
- * Adapter-side factory that stands up a transport connection and yields a
- * caller `Duplex`. One `Connect` invocation owns one transport; each call
- * to the resolved `call` opens a new sub-stream on it.
- */
-export type Connect<P> = (params: P) => Promise<{
-  call: Duplex;
-  close: () => Promise<void>;
-}>;
-
-/**
- * Adapter-side factory that registers a handler `Duplex` against a transport.
- * Returns an idempotent teardown.
- */
-export type Serve<P> = (params: P, handler: Duplex) => Promise<() => Promise<void>>;
+import {
+  type CreditGrantor,
+  type CreditLedger,
+  newCreditGrantor,
+  newCreditLedger,
+} from "./flow-control.js";
+import { decodeUint32, encodeUint32 } from "./uint32.js";
 
 /**
  * The minimum a transport must expose to be wrapped by `emulateMux`. Inbound
@@ -45,18 +22,6 @@ export type ByteChannel = {
   close(): void;
 };
 
-/**
- * Thrown by `emulateMux` and adapters when the underlying transport closes
- * while one or more `Duplex` calls are in flight. Consumers can catch by
- * `instanceof TransportClosedError` or by checking `error.name`.
- */
-export class TransportClosedError extends Error {
-  override readonly name = "TransportClosedError";
-  constructor(message = "transport closed") {
-    super(message);
-  }
-}
-
 const TYPE_OPEN = 0x01;
 const TYPE_DATA = 0x02;
 const TYPE_ACK = 0x03;
@@ -66,6 +31,7 @@ const TYPE_CLOSE = 0x06;
 
 const DEFAULT_MAX_STREAMS = 256;
 const DEFAULT_MTU = 64 * 1024;
+const DEFAULT_MAX_STREAM_BUFFER = 8 * 1024 * 1024;
 
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder();
@@ -75,14 +41,42 @@ interface Stream {
   inbound: AsyncGenerator<Uint8Array>;
   pushIn: (chunk: Uint8Array) => Promise<boolean>;
   doneIn: (err?: Error) => Promise<boolean>;
-  resolveAck: (() => void) | null;
-  rejectAck: ((err: Error) => void) | null;
+  /** Credit the peer has granted us for sending on this stream. */
+  outboundCredit: CreditLedger;
+  /** Tracks consumer drainage to decide when to grant the peer more credit. */
+  grantor: CreditGrantor;
   closed: boolean;
+  /** Peer sent END (or the stream was torn down): nothing more arrives. */
+  inDone: boolean;
+  /** Our outbound pump sent END: nothing more will be sent. */
+  outDone: boolean;
+  /** Inbound bytes pushed but not yet taken by the consumer. */
+  queuedBytes: number;
+  /**
+   * Cancels the caller's outbound input, set by `pumpOutbound`.
+   *
+   * WHY THIS EXISTS. `pumpOutbound` is fire-and-forget and checks `s.closed`
+   * only AFTER a chunk arrives, so an input that yields nothing more leaves
+   * the pump parked on `input.next()` for ever — holding the producer and its
+   * `finally` — even though the consumer has cancelled and the slot is gone.
+   * Teardown has to reach back and return the input rather than wait for it.
+   */
+  cancelInput?: () => void;
 }
 
 export interface EmulateMuxOptions {
   maxStreams?: number;
   mtu?: number;
+  /**
+   * Cap on inbound bytes one stream may hold for a consumer that has not
+   * drained them. Exceeding it tears down that stream alone.
+   *
+   * It is also the credit this side advertises to the peer, so it must be at
+   * least 1 — a window of 0 authorises nothing and hangs the peer forever —
+   * and it travels in a uint32, so a value above `MAX_UINT32` (4 GiB - 1) is
+   * advertised as `MAX_UINT32`.
+   */
+  maxStreamBuffer?: number;
   /**
    * Stream-id allocation side. Initiator uses even ids (2, 4, …); responder
    * uses odd ids (1, 3, …). Pick one per peer so allocations don't collide.
@@ -100,6 +94,13 @@ export function emulateMux(
 } {
   const maxStreams = opts.maxStreams ?? DEFAULT_MAX_STREAMS;
   const mtu = opts.mtu ?? DEFAULT_MTU;
+  const maxStreamBuffer = opts.maxStreamBuffer ?? DEFAULT_MAX_STREAM_BUFFER;
+  // A window of 0 is not a small window, it is a permanent stall: the peer is
+  // authorised to send nothing and no event would ever grant it more. Refuse
+  // it at construction rather than deadlocking on the first call.
+  if (!(maxStreamBuffer >= 1)) {
+    throw new RangeError(`emulateMux: maxStreamBuffer must be at least 1, got ${maxStreamBuffer}`);
+  }
   const side = opts.side ?? "initiator";
 
   const streams = new Map<number, Stream>();
@@ -125,13 +126,31 @@ export function emulateMux(
   const teardownStream = (s: Stream, err?: Error): void => {
     if (s.closed) return;
     s.closed = true;
-    const resolve = s.resolveAck;
-    const reject = s.rejectAck;
-    s.resolveAck = null;
-    s.rejectAck = null;
-    if (reject && err) reject(err);
-    else resolve?.();
+    // A sender parked in `reserve()` unwinds here: the credit it is waiting
+    // for will never arrive, so fail the ledger rather than leave it queued.
+    s.outboundCredit.fail(err ?? new TransportClosedError("emulateMux: stream closed"));
     void s.doneIn(err);
+    // Return the caller's input so its `finally` runs. Not awaited, and that
+    // is deliberate: `.return()` on a generator parked awaiting its own source
+    // is QUEUED behind that pending `next()`, so awaiting it here would make
+    // teardown hang on exactly the input we are trying to abandon.
+    s.cancelInput?.();
+    streams.delete(s.id);
+  };
+
+  /**
+   * Graceful counterpart to `teardownStream`. A stream occupies a slot in
+   * `streams` until BOTH directions finish; releasing on inbound END alone
+   * would set `closed` while our own `pumpOutbound` is still sending, and it
+   * checks that flag to decide whether to keep going.
+   *
+   * Without this, only abnormal endings (cancel, ERROR, CLOSE, transport
+   * failure) ever freed a slot, so every normally-completed call leaked one
+   * until `maxStreams` began rejecting new calls.
+   */
+  const releaseIfComplete = (s: Stream): void => {
+    if (s.closed || !s.inDone || !s.outDone) return;
+    s.closed = true;
     streams.delete(s.id);
   };
 
@@ -152,9 +171,12 @@ export function emulateMux(
       }),
       pushIn: queue.push,
       doneIn: queue.done,
-      resolveAck: null,
-      rejectAck: null,
+      outboundCredit: newCreditLedger(0),
+      grantor: newCreditGrantor(maxStreamBuffer),
       closed: false,
+      inDone: false,
+      outDone: false,
+      queuedBytes: 0,
     };
     return state;
   };
@@ -163,24 +185,48 @@ export function emulateMux(
     s: Stream,
     input: AsyncIterable<Uint8Array> | Iterable<Uint8Array>,
   ): Promise<void> => {
+    // Hand teardown a way to cancel this input. An async iterator's `return`
+    // is the only cancellation the protocol has, and the pump cannot poll for
+    // one: between two chunks it is parked inside `next()`, which for a
+    // long-lived session is where it spends its whole life.
+    //
+    // THE ITERATOR IS ACQUIRED ONCE AND DRIVEN BY HAND. `for await (… of
+    // input)` would call `[Symbol.asyncIterator]()` again; for a generator
+    // that returns the same object, but for any other iterable it returns a
+    // SECOND iterator — and then `cancelInput` would be cancelling something
+    // the loop is not reading.
+    const iterator: AsyncIterator<Uint8Array> | Iterator<Uint8Array> =
+      (input as AsyncIterable<Uint8Array>)[Symbol.asyncIterator]?.() ??
+      (input as Iterable<Uint8Array>)[Symbol.iterator]();
+    s.cancelInput = () => {
+      void (iterator as AsyncIterator<Uint8Array>).return?.(undefined);
+    };
     try {
-      for await (const chunk of input) {
+      for (;;) {
+        const next = await iterator.next();
+        if (next.done === true) break;
+        const chunk = next.value;
         if (s.closed || muxClosed) return;
         if (chunk.byteLength === 0) continue;
         let off = 0;
         while (off < chunk.byteLength) {
           if (s.closed || muxClosed) return;
-          const end = Math.min(off + mtu, chunk.byteLength);
-          const piece = chunk.subarray(off, end);
-          sendFrame(s.id, TYPE_DATA, piece);
-          await new Promise<void>((resolve, reject) => {
-            s.resolveAck = resolve;
-            s.rejectAck = reject;
-          });
+          // Reserve BEFORE framing. `reserve` returns what the peer's window
+          // can actually take, up to one mtu, so a piece is never larger than
+          // the credit that exists for it — which is what stops a sender whose
+          // mtu exceeds the peer's whole window from stalling forever.
+          const take = await s.outboundCredit.reserve(Math.min(mtu, chunk.byteLength - off));
+          if (s.closed || muxClosed) return;
+          const end = off + take;
+          sendFrame(s.id, TYPE_DATA, chunk.subarray(off, end));
           off = end;
         }
       }
-      if (!s.closed && !muxClosed) sendFrame(s.id, TYPE_END);
+      if (!s.closed && !muxClosed) {
+        sendFrame(s.id, TYPE_END);
+        s.outDone = true;
+        releaseIfComplete(s);
+      }
     } catch (err) {
       if (!s.closed && !muxClosed) {
         const e = err instanceof Error ? err : new Error(String(err));
@@ -201,16 +247,54 @@ export function emulateMux(
       return;
     }
     await pumpOutbound(s, outbound);
+    // The response is complete. If the handler never consumed the request
+    // body, nothing will ever drain the inbound queue, so no ACK is sent, the
+    // caller's pump parks forever awaiting one, and neither peer frees the
+    // slot — while the caller's `for await` completes normally, so nothing
+    // looks wrong from user code. Tell the peer we no longer want the body.
+    //
+    // This is why a handler must consume `input` within its generator's
+    // lifetime: draining it from a detached task is indistinguishable, from
+    // here, from not draining it at all.
+    if (!s.inDone && !s.closed && !muxClosed) {
+      sendFrame(s.id, TYPE_CLOSE);
+      teardownStream(s);
+    }
   };
 
   const handleFrame = (frame: Uint8Array): void => {
     if (muxClosed) return;
     if (frame.byteLength < 2) return;
-    const { value: id, offset } = decodeVarint(frame, 0);
+
+    // The id is the one field parsed from untrusted bytes before we know which
+    // stream a frame belongs to, and decodeVarint throws on a truncated or
+    // over-long encoding. Left unguarded that exception escapes handleFrame,
+    // reaches the inbound loop's catch, and calls failAll — so a single
+    // malformed frame tears down every stream on the connection.
+    //
+    // A ByteChannel is message-oriented, so frames are discrete and a corrupt
+    // one cannot desync the next. Dropping it is therefore safe, and is what
+    // keeps one bad frame from becoming a denial of service against every
+    // healthy stream sharing the mux.
+    let id: number;
+    let offset: number;
+    try {
+      ({ value: id, offset } = decodeVarint(frame, 0));
+    } catch {
+      return;
+    }
+    if (offset >= frame.byteLength) return; // id consumed the whole frame: no type byte
     const type = frame[offset];
     const payload = frame.subarray(offset + 1);
 
     if (type === TYPE_OPEN) {
+      // A duplicate OPEN for a LIVE stream is ignored. A replay of one that
+      // already finished is deliberately not guarded: every transport here is
+      // ordered and reliable, so a replay cannot occur by accident, and a
+      // hostile peer gains nothing by it — opening a fresh id invokes the same
+      // handler just as well. An earlier monotonic high-water mark did guard
+      // it, at the cost of letting one OPEN with a high id permanently refuse
+      // every later stream, including that peer's own legitimate traffic.
       if (streams.has(id)) return;
       if (streams.size >= maxStreams) {
         sendFrame(
@@ -226,6 +310,13 @@ export function emulateMux(
       }
       const s = createStream(id);
       streams.set(id, s);
+      // The opener's advertisement is our whole sending allowance; our own
+      // goes back so the opener can start. Both ledgers begin at zero, so the
+      // advertisement and every later grant are the same operation — an
+      // increment — and the ACK handler needs no special first case.
+      const advertised = decodeUint32(payload);
+      if (advertised !== undefined) s.outboundCredit.grant(advertised);
+      sendFrame(id, TYPE_ACK, encodeUint32(maxStreamBuffer));
       void runHandler(s, handler);
       return;
     }
@@ -235,25 +326,48 @@ export function emulateMux(
 
     switch (type) {
       case TYPE_DATA: {
+        // Flow control is the peer spending only the credit we granted it —
+        // voluntary, and a hostile peer simply does not. Pushes are
+        // fire-and-forget by necessity (see the comment below), so nothing
+        // else bounds this queue: a peer that floods DATA at a handler which
+        // has not started draining retains every payload. Refuse past a
+        // per-stream cap and tear down THAT stream, never the whole mux.
+        s.queuedBytes += payload.byteLength;
+        if (s.queuedBytes > maxStreamBuffer) {
+          const err = new RangeError(
+            `emulateMux: stream ${id} buffered ${s.queuedBytes} bytes past maxStreamBuffer=${maxStreamBuffer} without being drained`,
+          );
+          sendFrame(id, TYPE_ERROR, encodeError(err));
+          teardownStream(s, err);
+          return;
+        }
         const copy = payload.byteLength === 0 ? payload : new Uint8Array(payload);
-        // Push fire-and-forget; ACK after the consumer drains. The inbound
-        // loop must NOT block on consumer drainage — peer holds one in-flight
-        // DATA per stream and waits for ACK, so blocking here causes a
-        // cross-direction deadlock where ACK frames can't be processed.
+        // Push fire-and-forget; grant after the consumer drains. The inbound
+        // loop must NOT block on consumer drainage — our own sender is parked
+        // in `reserve()` waiting for the peer's grants, so blocking here
+        // causes a cross-direction deadlock where ACK frames can't be
+        // processed.
         void s.pushIn(copy).then((handled) => {
-          if (handled && !s.closed && !muxClosed) sendFrame(id, TYPE_ACK);
+          s.queuedBytes -= copy.byteLength;
+          if (!handled || s.closed || muxClosed) return;
+          // Grant only for bytes the consumer actually took, batched while the
+          // receiver is behind and flushed the moment its queue empties.
+          const grant = s.grantor.consumed(copy.byteLength, s.queuedBytes === 0);
+          if (grant > 0) sendFrame(id, TYPE_ACK, encodeUint32(grant));
         });
         return;
       }
       case TYPE_ACK: {
-        const r = s.resolveAck;
-        s.resolveAck = null;
-        s.rejectAck = null;
-        r?.();
+        const granted = decodeUint32(payload);
+        // A payload-less ACK is not from a credit-speaking peer; ignore it
+        // rather than granting an arbitrary amount.
+        if (granted !== undefined) s.outboundCredit.grant(granted);
         return;
       }
       case TYPE_END: {
+        s.inDone = true;
         void s.doneIn();
+        releaseIfComplete(s);
         return;
       }
       case TYPE_ERROR: {
@@ -294,7 +408,7 @@ export function emulateMux(
     nextLocalId += 2;
     const s = createStream(id);
     streams.set(id, s);
-    sendFrame(id, TYPE_OPEN);
+    sendFrame(id, TYPE_OPEN, encodeUint32(maxStreamBuffer));
     void pumpOutbound(s, input);
     return s.inbound;
   };
@@ -419,7 +533,7 @@ function decodeVarint(buf: Uint8Array, start: number): { value: number; offset:
   let shift = 0;
   let i = start;
   while (i < buf.length) {
-    const b = buf[i++];
+    const b = buf[i++]!; // i < buf.length, checked by the while condition, so this index exists
     value |= (b & 0x7f) << shift;
     if ((b & 0x80) === 0) return { value: value >>> 0, offset: i };
     shift += 7;

package/src/flow-control.ts

@@ -0,0 +1,146 @@
+/**
+ * Credit-based flow control, as a pair of pure state machines with no I/O.
+ *
+ * The sender holds a {@link CreditLedger}: it reserves credit before it puts
+ * anything on the wire, and stalls at zero. The receiver holds a
+ * {@link CreditGrantor}: it counts what its consumer has actually drained and
+ * says when to hand the sender more.
+ *
+ * A sender therefore cannot overrun a receiver's buffer, because it was never
+ * granted permission to. That is the property a sender-side window cannot
+ * offer: the receiver's capacity is not knowable to the sender unless the
+ * receiver states it.
+ *
+ * **The unit is opaque.** This module never interprets the numbers it counts.
+ * `emulateMux` passes byte counts and advertises `maxStreamBuffer`; the RPC
+ * tier passes 1 per value and advertises a maximum in-flight value count.
+ * Nothing here depends on which.
+ */
+
+export interface CreditLedger {
+  /** Units authorised by the peer and not yet reserved. */
+  readonly available: number;
+  /**
+   * Reserve up to `upTo` units, resolving with how many were actually
+   * granted — at least 1, never more than `upTo`. The caller sends exactly
+   * that much and calls `reserve` again for the rest.
+   *
+   * `upTo` must itself be at least 1; anything less rejects with a
+   * `RangeError` rather than resolving with 0, which would be a silent no-op
+   * that also consumed a waiter slot.
+   *
+   * Returning a partial amount rather than waiting for the full request is
+   * what makes the ledger deadlock-free: a peer that advertises less than
+   * one `upTo` still makes progress, one short piece at a time.
+   *
+   * Rejects if {@link fail} is called.
+   */
+  reserve(upTo: number): Promise<number>;
+  /** The peer authorised `units` more. */
+  grant(units: number): void;
+  /** Reject every pending and future reservation — transport or stream is gone. */
+  fail(err: Error): void;
+}
+
+interface Waiter {
+  upTo: number;
+  resolve: (granted: number) => void;
+  reject: (err: Error) => void;
+}
+
+export function newCreditLedger(initial = 0): CreditLedger {
+  let available = initial;
+  let failure: Error | undefined;
+  const waiters: Waiter[] = [];
+
+  // Waiters are released strictly in order, head first. Letting a later
+  // reservation overtake an earlier one would reorder the stream.
+  const pump = (): void => {
+    while (waiters.length > 0 && available > 0) {
+      const next = waiters[0];
+      if (!next) return;
+      waiters.shift();
+      const granted = Math.min(next.upTo, available);
+      available -= granted;
+      next.resolve(granted);
+    }
+  };
+
+  return {
+    get available() {
+      return available;
+    },
+    reserve(upTo: number): Promise<number> {
+      if (failure) return Promise.reject(failure);
+      // A reservation below one unit is a caller bug, not a legal request: the
+      // contract is "at least 1", and the queued path would otherwise consume
+      // a waiter in order to hand back nothing.
+      if (!(upTo >= 1)) {
+        return Promise.reject(
+          new RangeError(`newCreditLedger: reserve(${upTo}) — upTo must be at least 1`),
+        );
+      }
+      if (waiters.length === 0 && available > 0) {
+        const granted = Math.min(upTo, available);
+        available -= granted;
+        return Promise.resolve(granted);
+      }
+      return new Promise<number>((resolve, reject) => {
+        waiters.push({ upTo, resolve, reject });
+      });
+    },
+    grant(units: number): void {
+      if (failure) return;
+      available += units;
+      pump();
+    },
+    fail(err: Error): void {
+      failure ??= err;
+      while (waiters.length > 0) {
+        waiters.shift()?.reject(err);
+      }
+    },
+  };
+}
+
+export interface CreditGrantor {
+  /**
+   * Record that the consumer drained `units`, and whether the receive queue
+   * is now empty. Returns the credit to hand back to the peer, or `0` to stay
+   * silent and keep accumulating.
+   */
+  consumed(units: number, queueEmpty: boolean): number;
+}
+
+/**
+ * Grants are batched: replenishing on every chunk while the receiver is
+ * behind would reinvent the per-frame ACK this change exists to remove.
+ * `threshold` is the fraction of the window that must drain before a grant is
+ * emitted.
+ *
+ * The batch is flushed unconditionally once the receive queue is empty, even
+ * below the threshold, so the receiver never sits on credit it owes. Note what
+ * this is and is not: paired with a {@link CreditLedger}, a sender blocks only
+ * at *exactly* zero credit, and at that point the receiver holds the entire
+ * window as `pending` — above any threshold at or below the whole window — so
+ * the threshold alone cannot deadlock that pairing. The flush is what keeps
+ * that from being an argument about a global accounting identity: it is
+ * locally decidable from one boolean, and it returns owed credit now rather
+ * than at the next threshold crossing. It costs an extra frame only when the
+ * consumer is keeping pace, which is exactly when the sender is not blocked
+ * and the frame is cheap.
+ */
+export function newCreditGrantor(window: number, threshold = 0.5): CreditGrantor {
+  const trigger = Math.max(1, Math.floor(window * threshold));
+  let pending = 0;
+  return {
+    consumed(units: number, queueEmpty: boolean): number {
+      pending += units;
+      if (pending === 0) return 0;
+      if (pending < trigger && !queueEmpty) return 0;
+      const grant = pending;
+      pending = 0;
+      return grant;
+    },
+  };
+}

package/src/index.ts

@@ -1,6 +1,8 @@
 export * from "./collect.js";
+export * from "./duplex.js";
 export * from "./emulate-mux.js";
 export * from "./errors.js";
+export * from "./flow-control.js";
 export * from "./jsonl.js";
 export * from "./lines.js";
 export * from "./map.js";