@statewalker/webrun-streams 0.1.1 → 0.2.1

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,43 +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.
- *
- * 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>>;
+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
@@ -53,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;
@@ -84,8 +41,10 @@ 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;
@@ -93,6 +52,16 @@ interface Stream {
   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 {
@@ -101,6 +70,11 @@ export interface EmulateMuxOptions {
   /**
    * 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;
   /**
@@ -121,6 +95,12 @@ 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>();
@@ -146,13 +126,15 @@ 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);
   };
 
@@ -189,8 +171,8 @@ 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,
@@ -203,20 +185,40 @@ 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;
         }
       }
@@ -308,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;
     }
@@ -317,11 +326,11 @@ export function emulateMux(
 
     switch (type) {
       case TYPE_DATA: {
-        // Flow control is the peer holding one in-flight DATA per stream and
-        // waiting for its ACK — 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
+        // 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) {
@@ -333,21 +342,26 @@ export function emulateMux(
           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) => {
           s.queuedBytes -= copy.byteLength;
-          if (handled && !s.closed && !muxClosed) sendFrame(id, TYPE_ACK);
+          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: {
@@ -394,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;
   };
@@ -519,7 +533,8 @@ function decodeVarint(buf: Uint8Array, start: number): { value: number; offset:
   let shift = 0;
   let i = start;
   while (i < buf.length) {
-    const b = buf[i++]!; // i < buf.length, checked by the while condition, so this index exists
+    // biome-ignore lint/style/noNonNullAssertion: i < buf.length, checked by the while condition, so this index exists.
+    const b = buf[i++]!;
     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";

package/src/readable-streams.ts

@@ -1,21 +1,44 @@
+/**
+ * The iterator ↔ `ReadableStream` boundary.
+ *
+ * Both adapters must carry CANCELLATION, not just data: a response body leaves
+ * a handler as a `ReadableStream`, crosses a transport as an iterator, and
+ * becomes a `ReadableStream` again at the caller — so when the caller walks
+ * away, the only path back to the handler's producer runs through both of
+ * these functions. Teardown that stops at an adapter leaves a producer running
+ * for ever.
+ */
+
 export function toReadableStream(it: AsyncIterator<Uint8Array>): ReadableStream<Uint8Array> {
   return new ReadableStream<Uint8Array>({
+    /**
+     * One chunk per pull. An earlier version drained the whole iterator inside
+     * a single `pull`, which defeated the stream's own backpressure (every
+     * chunk was enqueued as fast as the producer could make them, however slow
+     * the reader was) and left no point between chunks at which a cancellation
+     * could take effect.
+     */
     async pull(controller) {
-      let handled = false;
       try {
-        while (true) {
-          const slot = await it.next();
-          if (!slot || slot.done) break;
-          const value = (await slot.value) as Uint8Array;
-          controller.enqueue(value);
+        const slot = await it.next();
+        if (!slot || slot.done) {
+          controller.close();
+          return;
         }
+        controller.enqueue((await slot.value) as Uint8Array);
       } catch (error) {
-        handled = true;
         controller.error(error);
-      } finally {
-        if (!handled) controller.close();
       }
     },
+    /**
+     * Release the source. NOT awaited: `.return()` on an async generator that
+     * is parked awaiting its own source is queued behind that pending
+     * `next()`, so awaiting it here would hang `reader.cancel()` on exactly
+     * the producers that most need cancelling.
+     */
+    cancel(reason) {
+      void Promise.resolve(it.return?.(reason)).catch(() => {});
+    },
   });
 }
 
@@ -23,9 +46,22 @@ export async function* fromReadableStream(
   stream: ReadableStream<Uint8Array>,
 ): AsyncGenerator<Uint8Array, void, unknown> {
   const reader = stream.getReader();
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    if (value !== undefined) yield value;
+  let drained = false;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        drained = true;
+        break;
+      }
+      if (value !== undefined) yield value;
+    }
+  } finally {
+    // A consumer that stops early (`break`, `.return()`, an error) must cancel
+    // the source, or whatever fills it keeps filling it. A stream that ended
+    // on its own is merely released — cancelling it would be a lie to any
+    // `cancel()` hook watching for an abandoned reader.
+    if (drained) reader.releaseLock();
+    else await reader.cancel().catch(() => {});
   }
 }

package/src/uint32.ts

@@ -0,0 +1,34 @@
+/**
+ * Credit payloads are a single big-endian uint32, matching the frame header's
+ * byte order.
+ *
+ * Deliberately **not** re-exported from `index.ts`: this is an internal codec
+ * for the `emulateMux` wire format, not a compatibility commitment. Tests
+ * import it by path.
+ */
+/** The largest credit a single frame can advertise or grant: 2^32 - 1. */
+export const MAX_UINT32 = 0xffffffff;
+
+/**
+ * Clamps rather than wraps. `n >>> 0` is the obvious spelling and it is wrong
+ * here: 2^32 becomes **0**, so a 4 GiB window advertises *zero credit* and the
+ * peer stalls forever with no error — the exact silent hang credit exists to
+ * remove. 2^32 + 5 becomes 5, which looks like a working window and is worse.
+ * Anything above the ceiling is advertised as the ceiling.
+ */
+export function encodeUint32(n: number): Uint8Array {
+  const bytes = new Uint8Array(4);
+  const clamped = Number.isFinite(n) ? Math.min(MAX_UINT32, Math.max(0, Math.floor(n))) : 0;
+  new DataView(bytes.buffer).setUint32(0, clamped, false);
+  return bytes;
+}
+
+/**
+ * Returns `undefined` rather than a garbage number when the payload is too
+ * short, so a truncated frame — or one from a peer predating credit — is
+ * detectable at the call site instead of silently granting nonsense.
+ */
+export function decodeUint32(bytes: Uint8Array): number | undefined {
+  if (bytes.byteLength < 4) return undefined;
+  return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(0, false);
+}