@robota-sdk/agent-transport 3.0.0-beta.78 → 3.0.0-beta.81

package/src/outbound-delivery.ts

@@ -0,0 +1,231 @@
+/**
+ * The connection-scoped outbound delivery boundary (ARCH-030).
+ *
+ * Every outbound `TServerMessage` on one connection — session-event fan-out AND every reply to an
+ * inbound frame — goes through ONE boundary that owns carrier-failure containment. Before this
+ * existed, `subscribeSessionEvents` guarded its sends while the reply paths received the raw carrier
+ * `send`, so a reply resolving after a disconnect threw from a Promise continuation, escaped as an
+ * unhandled rejection, and left the carrier's cleanup — written, idempotent, and waiting — unnotified.
+ *
+ * WHO BUILDS IT. The **carrier**, from its own private sink and its own failure policy, and passes the
+ * result down into the protocol handler. Not the other way round: the raw sink and the "what does a
+ * failed send mean for this connection" decision both belong to the carrier, and handing the protocol
+ * layer a raw sink so it can hand a wrapper back leaves the raw sink reachable — which is the hole a
+ * twelfth reply family walks through next year.
+ *
+ * WHY IT IS BRANDED. {@link createOutboundDelivery} is the only producer of {@link TOutboundDeliver}, so
+ * a plain `(message: TServerMessage) => void` is **refused by the compiler** wherever a boundary is
+ * required. That turns "a new raw-send continuation cannot be added silently" from a scan that a rename
+ * defeats into a type error at the call site. `src/__tests__` is inside this package's `tsconfig.json`
+ * `include`, so the `@ts-expect-error` case pinning it is checked by `tsgo --noEmit`.
+ *
+ * IT LATCHES. A boundary reports AT MOST ONE delivery failure; after the first, it is closed and every
+ * subsequent frame is dropped without a further report. All three carriers already treat a delivery
+ * failure as terminal (`WsSessionDelivery.close` → `socket.close(1011)`, `WebRtcDeliveryLifecycle` →
+ * `channel.close()`, `PairingGate` → `pairingChannel.close`) and each had grown its own latch to
+ * suppress the repeats; the latch belongs upstream of all three. `SessionResumeBridge` already behaved
+ * this way, so the handler path converges onto the bridge's semantics rather than the reverse.
+ *
+ * A boundary is not reusable across carriers: a latched one stays latched. `SessionResumeBridge` builds
+ * a fresh boundary per `attach`, which is what un-latches the session after a reconnect.
+ */
+
+import type { TServerMessage } from './wire-messages.js';
+
+declare const outboundDeliveryBrand: unique symbol;
+
+/**
+ * Deliver one outbound frame on a connection. A carrier failure is REPORTED through the boundary's
+ * error handler, never thrown at the caller — so a reply resolving after a disconnect cannot escape as
+ * an unhandled rejection or out of the carrier's inbound listener.
+ *
+ * Only {@link createOutboundDelivery} produces one. The brand is the mechanism, not decoration: it is
+ * what makes a raw carrier `send` unusable where a boundary is required.
+ */
+export type TOutboundDeliver = ((message: TServerMessage) => void) & {
+  readonly [outboundDeliveryBrand]: true;
+
+  /**
+   * Bytes this carrier has ACCEPTED and not yet written to the peer — or `undefined` when it cannot
+   * say.
+   *
+   * `deliver` returning is not delivery. Both carriers hand this boundary a fire-and-forget sink, so
+   * a frame that has "been sent" may be sitting in a socket buffer the boundary cannot see. Anything
+   * this boundary counted itself would be a count of what it HANDED OVER, which is a different
+   * quantity from what the peer has not read — and a budget over the wrong quantity reports a
+   * healthy connection for a peer that stopped reading (ARCH-030 / issue #1734).
+   *
+   * `undefined` is deliberately not `0`. A carrier that cannot report backpressure and a carrier with
+   * nothing pending are different states, and collapsing them would let "unknown" satisfy any
+   * threshold placed on this number.
+   */
+  readonly pendingBytes: () => number | undefined;
+};
+
+/**
+ * Observe THIS connection's first outbound delivery failure. `event` is the `type` of the frame that
+ * could not be delivered — a session event's own name for the fan-out (they are identical), and the
+ * reply's type for a reply (`command_result`, `protocol_error`, …).
+ *
+ * Required, never optional: a carrier that could opt out of observing its own delivery failures is the
+ * silent-failure shape this boundary exists to remove.
+ */
+export type TDeliveryErrorHandler = (error: Error, event: TServerMessage['type']) => void;
+
+/**
+ * Build the outbound delivery boundary for ONE connection from that connection's raw sink and its
+ * failure policy.
+ *
+ * @param send - the carrier's raw sink. May throw; that is what makes it raw.
+ * @param onDeliveryError - the carrier's failure policy, invoked at most once. A handler that itself
+ *   throws is isolated: a diagnostic cannot reverse an already-committed session operation.
+ * @param pendingBytes - the carrier's own backpressure reading. Optional because not every carrier
+ *   has one; omitted, the boundary answers `undefined` rather than inventing a number.
+ */
+/**
+ * Default outbound backpressure budget, in bytes the carrier has accepted and not yet written.
+ *
+ * 8 MiB. The number is a policy, not a measurement, and it is stated here rather than inlined so a
+ * reader can find the one place that decides it. It is well above any single frame this protocol
+ * produces and well below a figure at which a non-reading peer could exhaust the host — the property
+ * that matters is that SOME finite budget exists, because the previous behaviour was unbounded.
+ *
+ * A carrier that cannot report `pendingBytes` is not subject to it: `undefined` is unknown, not zero,
+ * so no threshold applies to it. That is deliberate and it is a gap — a carrier with no backpressure
+ * reading has no budget — recorded rather than hidden behind a default of `0`, which would refuse
+ * every frame on such a carrier.
+ */
+const BYTES_PER_MIB = Number('1024') * Number('1024');
+export const DEFAULT_MAX_PENDING_BYTES = Number('8') * BYTES_PER_MIB;
+
+/**
+ * Is this carrier holding more than the budget allows?
+ *
+ * Exported because a WebSocket carries TWO kinds of outbound frame over one socket — the text
+ * protocol and TRANS-001's payload channels — and only one of them goes through
+ * {@link createOutboundDelivery}. A budget the binary path re-implemented would be a second opinion
+ * about one socket's backpressure; a budget it skipped would leave the same non-reading peer
+ * unbounded on the other half of the connection.
+ *
+ * `undefined` is unknown, not zero: a carrier that cannot report backpressure is never over budget.
+ */
+export function isOverPendingBudget(
+  pending: number | undefined,
+  limit: number = DEFAULT_MAX_PENDING_BYTES,
+): boolean {
+  return pending !== undefined && pending > limit;
+}
+
+/**
+ * Default outbound DRAIN budget (issue #2306): how long a carrier may stay non-empty before the peer
+ * is treated as not reading.
+ *
+ * 120 seconds. The byte budget bounds HOW MUCH a peer holds; it cannot bound HOW LONG, because
+ * `bufferedAmount` is a quantity with no history — a peer draining just enough to stay under 8 MiB
+ * forever is never over it. The figure is generous on purpose: a legitimately slow link drains to
+ * zero between bursts, so the clock resets, whereas a peer that keeps SOMETHING pending for two
+ * minutes straight is holding a session, its resume buffer, and a socket it does not intend to read.
+ * A badly chosen figure here disconnects real users, which is why it is one named constant and an
+ * argument, never an inline number. `Infinity` disables the budget.
+ */
+export const DEFAULT_MAX_PENDING_MS = Number('120') * Number('1000');
+
+/**
+ * The drain clock the boundary keeps for a carrier (issue #2306). One timestamp, not per-frame
+ * bookkeeping: it starts on the first reading that finds the carrier non-empty, RESETS only when a
+ * reading finds it empty (a peer that drains to one byte and stalls again has not drained), and is
+ * consulted synchronously at each send — the boundary has no timer and gains none here.
+ */
+export interface IPendingStallClock {
+  readonly maxPendingMs: number;
+  /**
+   * Record one reading of the carrier's pending bytes. Returns how long the carrier has been
+   * continuously non-empty when that exceeds the budget; `undefined` otherwise. An `undefined`
+   * reading is unknown, not zero: it neither starts nor resets the clock.
+   */
+  observe: (pending: number | undefined) => number | undefined;
+}
+
+export function createPendingStallClock(
+  maxPendingMs: number = DEFAULT_MAX_PENDING_MS,
+  now: () => number = Date.now,
+): IPendingStallClock {
+  let nonEmptySince: number | undefined;
+  return {
+    maxPendingMs,
+    observe(pending) {
+      if (pending === undefined) return undefined;
+      if (pending === 0) {
+        nonEmptySince = undefined;
+        return undefined;
+      }
+      const at = now();
+      nonEmptySince ??= at;
+      const stalledMs = at - nonEmptySince;
+      return stalledMs > maxPendingMs ? stalledMs : undefined;
+    },
+  };
+}
+
+export function createOutboundDelivery(
+  send: (message: TServerMessage) => void,
+  onDeliveryError: TDeliveryErrorHandler,
+  pendingBytes?: () => number | undefined,
+  maxPendingBytes: number = DEFAULT_MAX_PENDING_BYTES,
+  stallClock: IPendingStallClock = createPendingStallClock(),
+): TOutboundDeliver {
+  let closed = false;
+  const deliver = (message: TServerMessage): void => {
+    if (closed) return;
+    // The budget is checked BEFORE the send, not after: a peer that has stopped reading is detected
+    // by what the carrier is still holding, and adding one more frame first would make the boundary
+    // the last contributor to the overflow it is reporting.
+    const pending = pendingBytes?.();
+    if (isOverPendingBudget(pending, maxPendingBytes)) {
+      closed = true;
+      reportFailure(
+        new Error(
+          `outbound backpressure budget exceeded: ${pending} byte(s) pending, limit ${maxPendingBytes}. ` +
+            'The peer has accepted frames it is not reading.',
+        ),
+        message.type,
+      );
+      return;
+    }
+    // Issue #2306: the same reading, judged by duration. A peer under the byte budget that has kept
+    // the carrier non-empty for longer than the drain budget is not reading either.
+    const stalledMs = stallClock.observe(pending);
+    if (stalledMs !== undefined) {
+      closed = true;
+      reportFailure(
+        new Error(
+          `outbound drain budget exceeded: ${pending} byte(s) pending for ${stalledMs} ms, limit ${stallClock.maxPendingMs} ms. ` +
+            'The peer is reading too slowly to ever drain what it accepted.',
+        ),
+        message.type,
+      );
+      return;
+    }
+    try {
+      send(message);
+    } catch (error) {
+      // allow-fallback: this IS the boundary — a carrier send failure is a CARRIER lifecycle failure,
+      // reported to the carrier's own policy (which closes the connection). It is never swallowed, and
+      // re-throwing it would fail a session operation that has already committed.
+      closed = true;
+      reportFailure(error instanceof Error ? error : new Error(String(error)), message.type);
+    }
+  };
+  function reportFailure(error: Error, event: TServerMessage['type']): void {
+    try {
+      onDeliveryError(error, event);
+    } catch {
+      // allow-fallback: the carrier-owned diagnostic is the LAST step of a failure already being
+      // reported. A throw from it has nowhere left to go, and letting it out would make a committed
+      // session operation fail for the sake of a diagnostic.
+    }
+  }
+  return Object.assign(deliver, {
+    pendingBytes: (): number | undefined => pendingBytes?.(),
+  }) as TOutboundDeliver;
+}

package/src/peer-message-ledger.ts

@@ -0,0 +1,193 @@
+/**
+ * PEER-001 (#1809): the receiver's record of what it has already taken responsibility for.
+ *
+ * ## What this decides, and why it is not the carrier's job
+ *
+ * The issue requires delivery, acknowledgement, duplicate, retry and shutdown to produce
+ * "deterministic, documented outcomes". Every one of those is a question about what the receiver has
+ * SEEN BEFORE, which no carrier can answer: a WebRTC data channel redelivers on reconnect, a retry
+ * repeats a message the sender already sent, and neither the socket nor the frame codec has any
+ * memory to consult. So the decision lives here, once, and the carriers stay dumb.
+ *
+ * ## The rules, stated rather than emergent
+ *
+ * - **A repeated `id` is a duplicate**, and the ledger returns the SAME ack it returned the first
+ *   time. That is what makes a retry safe: the sender learns the message landed, and the receiver
+ *   does not deliver it twice. An ack that merely said "duplicate" without the original state would
+ *   force the sender to guess whether the first attempt was accepted or refused.
+ * - **Sequence is per origin.** Two peers are independent senders; a shared counter would make one
+ *   peer's traffic look like the other's gap.
+ * - **A gap is REPORTED, never silently reordered.** If sequence 5 arrives while 4 has not, the
+ *   ledger says so. Buffering-and-reordering is a policy the session layer may choose; inventing it
+ *   here would hide a lost message behind an apparent success, which is the failure mode this whole
+ *   contract exists to avoid.
+ * - **Nothing is remembered across shutdown.** The ledger is per-connection state by construction —
+ *   a peer that reconnects gets a fresh sequence space, and the session layer decides what to do
+ *   with a peer that restarts mid-conversation.
+ */
+
+import type {
+  IPeerMessage,
+  IPeerMessageAck,
+  TPeerDeliveryState,
+} from '@robota-sdk/agent-interface-session-mobility';
+
+/**
+ * What the receiver has seen from one origin.
+ *
+ * `delivered` is a SET, not just a high-water mark, and that distinction is the whole of review
+ * finding #1. A high-water mark cannot tell "sequence 2 was already used" from "sequence 2 is the
+ * gap we reported and it has just arrived" — and answering the second as if it were the first
+ * refuses a message that was never delivered, permanently. `highestSequence` is kept alongside it
+ * because reporting a gap needs the frontier, not the membership.
+ *
+ * Exported because it is reachable from `IPeerMessageLedger`. A public interface whose field type is
+ * unexported is a name a consumer cannot write down (review finding #2). Measured: `tsdown` inlines
+ * it into the bundled declaration so no TS4033 is raised today — the finding's build-breakage claim
+ * does not reproduce — but a type nobody can name is still a bad public surface.
+ */
+export interface IOriginRecord {
+  /** The highest sequence delivered from this origin — the frontier a gap is measured against. */
+  highestSequence: number;
+  /** Every sequence actually delivered. Membership, not a range: gaps get filled out of order. */
+  delivered: Set<number>;
+  /** Acks already issued, by message id, so a retry gets the original answer back. */
+  issued: Map<string, IPeerMessageAck>;
+}
+
+/** Per-connection receive state. Created empty; discarded when the connection ends. */
+export interface IPeerMessageLedger {
+  readonly origins: Map<string, IOriginRecord>;
+}
+
+export function createPeerMessageLedger(): IPeerMessageLedger {
+  return { origins: new Map() };
+}
+
+/** Why a message was not accepted, when it was not. */
+export interface IPeerMessageRejection {
+  readonly state: Extract<TPeerDeliveryState, 'refused' | 'failed'>;
+  readonly reason: string;
+}
+
+export interface IPeerMessageVerdict {
+  readonly ack: IPeerMessageAck;
+  /**
+   * Should the session deliver this to the agent?
+   *
+   * False for a duplicate and for a refusal. Separate from `ack.state` because a caller that
+   * re-derived it from the state string would have to re-list which states mean "deliver", and that
+   * list is exactly what drifts.
+   */
+  readonly deliver: boolean;
+  /**
+   * Set when this message's sequence is ahead of the last one delivered from its origin.
+   *
+   * Reported, not resolved. The session layer decides whether a gap is worth waiting for; the
+   * ledger's job is to make sure it is never invisible.
+   */
+  readonly gapBefore?: number;
+}
+
+/**
+ * Record a message and say what should happen to it.
+ *
+ * Pure with respect to its inputs except for the ledger it is handed, which it updates in place —
+ * the caller owns the ledger's lifetime, so a connection ending is a reference going away rather
+ * than a cleanup step someone can forget.
+ */
+export function admitPeerMessage(
+  ledger: IPeerMessageLedger,
+  message: IPeerMessage,
+  rejection?: IPeerMessageRejection,
+): IPeerMessageVerdict {
+  const originId = message.origin.sessionId;
+  let record = ledger.origins.get(originId);
+  if (record === undefined) {
+    record = { highestSequence: 0, delivered: new Set(), issued: new Map() };
+    ledger.origins.set(originId, record);
+  }
+
+  // A repeated id is answered with the ORIGINAL verdict, before anything else is considered: a
+  // retry must not be re-judged, or a message accepted once could be refused on its second arrival
+  // and the sender would have two contradictory answers for one message.
+  const previous = record.issued.get(message.id);
+  if (previous !== undefined) {
+    return { ack: { ...previous, state: 'duplicate' }, deliver: false };
+  }
+
+  if (rejection !== undefined) {
+    const ack: IPeerMessageAck = {
+      id: message.id,
+      sequence: message.sequence,
+      state: rejection.state,
+      reason: rejection.reason,
+    };
+    record.issued.set(message.id, ack);
+    return { ack, deliver: false };
+  }
+
+  // A sequence this origin ACTUALLY delivered before, under a different id: a sender reusing a
+  // sequence, which is a protocol error rather than a duplicate.
+  //
+  // Membership, not `<= highestSequence`. The high-water form refused the late arrival of a gap it
+  // had itself reported — deliver 1, receive 3 (gap at 2 reported), then 2 arrives and is rejected
+  // as "already used" although it was never delivered. That contradicted this module's own stated
+  // rule that a gap is reported so the SESSION layer can decide, since the session never got the
+  // chance. Found in review.
+  if (record.delivered.has(message.sequence)) {
+    const ack: IPeerMessageAck = {
+      id: message.id,
+      sequence: message.sequence,
+      state: 'refused',
+      reason:
+        `sequence ${message.sequence} was already delivered by this origin under a different ` +
+        'message id. A retry must repeat its id; a new id on a delivered sequence cannot be ' +
+        'ordered against what the receiver already has.',
+    };
+    record.issued.set(message.id, ack);
+    return { ack, deliver: false };
+  }
+
+  const expected = record.highestSequence + 1;
+  const gapBefore = message.sequence > expected ? expected : undefined;
+
+  const ack: IPeerMessageAck = {
+    id: message.id,
+    sequence: message.sequence,
+    state: 'delivered',
+  };
+  record.issued.set(message.id, ack);
+  record.delivered.add(message.sequence);
+  // The frontier only moves FORWARD. A gap arriving late fills membership without rewinding what a
+  // later gap is measured against.
+  record.highestSequence = Math.max(record.highestSequence, message.sequence);
+
+  return gapBefore === undefined ? { ack, deliver: true } : { ack, deliver: true, gapBefore };
+}
+
+/**
+ * Mark a delivered message as acknowledged by the agent side.
+ *
+ * Separate from `admitPeerMessage` because delivery and acknowledgement answer different questions —
+ * "did the receiver take it" versus "did the agent act on it" — and a sender waiting for the second
+ * must not be told the first.
+ */
+export function acknowledgePeerMessage(
+  ledger: IPeerMessageLedger,
+  originSessionId: string,
+  id: string,
+): IPeerMessageAck | undefined {
+  const record = ledger.origins.get(originSessionId);
+  const issued = record?.issued.get(id);
+  if (record === undefined || issued === undefined || issued.state !== 'delivered')
+    return undefined;
+  const acknowledged: IPeerMessageAck = { ...issued, state: 'acknowledged' };
+  record.issued.set(id, acknowledged);
+  return acknowledged;
+}
+
+/** Forget one origin — used when a peer disconnects and its sequence space is no longer meaningful. */
+export function forgetPeerOrigin(ledger: IPeerMessageLedger, originSessionId: string): void {
+  ledger.origins.delete(originSessionId);
+}

package/src/protocol-session.ts

@@ -0,0 +1,28 @@
+import type {
+  ISessionBackgroundGroups,
+  ISessionBackgroundTasks,
+  ISessionCommands,
+  ISessionConversationRead,
+  ISessionDriverAttribution,
+  ISessionEvents,
+  ISessionExecutionState,
+  ISessionExecutionWorkspace,
+  ISessionPromptResolution,
+  ISessionTurnControl,
+  ISessionTurnSubmission,
+} from '@robota-sdk/agent-interface-session';
+
+/** Session roles required by the shared WebSocket/WebRTC protocol. */
+export interface IProtocolSession
+  extends
+    ISessionTurnSubmission,
+    ISessionTurnControl,
+    ISessionCommands,
+    ISessionEvents,
+    ISessionPromptResolution,
+    ISessionConversationRead,
+    ISessionExecutionState,
+    ISessionDriverAttribution,
+    ISessionBackgroundTasks,
+    ISessionBackgroundGroups,
+    ISessionExecutionWorkspace {}

package/src/resume-buffer.ts

@@ -0,0 +1,123 @@
+/**
+ * Bounded un-acked output buffer for session-resume (REMOTE-013 Stage E4).
+ *
+ * Holds the tail of outbound `TServerMessage`s that a reconnecting client may not have received, keyed by a
+ * monotonic sequence number. On reconnect the client sends `resume{lastSeq}` and the host replays
+ * {@link ResumeBuffer.tailAfter}; a periodic `ack{seq}` frees everything up to `seq`. The buffer is bounded by
+ * a frame count AND a byte budget (drop-oldest) so a never-acking or gone peer cannot exhaust host memory —
+ * and when a client's `lastSeq` predates the oldest retained frame it returns an **overrun** marker so the
+ * client does a full refresh rather than accept a silent gap.
+ */
+
+import type { TServerMessage } from './wire-messages.js';
+
+/** One retained frame: its sequence number and the message. */
+export interface IBufferedFrame {
+  readonly seq: number;
+  readonly message: TServerMessage;
+}
+
+/** The result of a `tailAfter` — either the ordered replay slice, or an overrun (client must full-refresh). */
+export type TResumeTail =
+  | { readonly kind: 'tail'; readonly frames: readonly IBufferedFrame[] }
+  | { readonly kind: 'overrun' };
+
+export interface IResumeBufferOptions {
+  /** Max retained frames (drop-oldest beyond this). Default 512. */
+  readonly maxFrames?: number;
+  /** Max retained bytes across frames (drop-oldest beyond this). Default 4 MiB. */
+  readonly maxBytes?: number;
+  /** Serialized size of a message (for the byte budget). Default: JSON length. Injectable for tests. */
+  readonly sizeOf?: (message: TServerMessage) => number;
+}
+
+const DEFAULT_MAX_FRAMES = 512;
+const DEFAULT_MAX_BYTES = 4 * 1024 * 1024;
+
+/**
+ * A monotonic, bounded ring of un-acked frames. Sequence numbers are assigned by {@link append} and never
+ * reused; `tailAfter` / `ackThrough` operate over the retained window.
+ */
+export class ResumeBuffer {
+  private readonly frames: IBufferedFrame[] = [];
+  private readonly sizes: number[] = []; // parallel to `frames` — retained byte size per frame
+  private nextSeq = 1;
+  private bytes = 0;
+
+  private readonly maxFrames: number;
+  private readonly maxBytes: number;
+  private readonly sizeOf: (message: TServerMessage) => number;
+
+  public constructor(options: IResumeBufferOptions = {}) {
+    this.maxFrames = options.maxFrames ?? DEFAULT_MAX_FRAMES;
+    this.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    this.sizeOf = options.sizeOf ?? ((m) => JSON.stringify(m).length);
+  }
+
+  /** Append a message, assign + return its monotonic seq, and evict oldest frames beyond the bounds. */
+  public append(message: TServerMessage): number {
+    const seq = this.nextSeq;
+    this.nextSeq += 1;
+    const size = this.sizeOf(message);
+    this.frames.push({ seq, message });
+    this.sizes.push(size);
+    this.bytes += size;
+    this.evict();
+    return seq;
+  }
+
+  /** Drop all retained frames with `seq <= throughSeq` (the client confirmed receipt up to there). */
+  public ackThrough(throughSeq: number): void {
+    let drop = 0;
+    while (drop < this.frames.length && this.frames[drop].seq <= throughSeq) drop += 1;
+    this.removeOldest(drop);
+  }
+
+  /**
+   * The ordered frames with `seq > lastSeq`. Returns an `overrun` marker when `lastSeq` is older than the
+   * oldest retained frame (i.e. some frame after `lastSeq` was already evicted) — the client must full-refresh.
+   * `lastSeq` at or beyond the newest seq yields an empty tail (nothing to replay).
+   */
+  public tailAfter(lastSeq: number): TResumeTail {
+    if (this.frames.length === 0) {
+      // Nothing retained. Only an overrun if the client is behind the frames we HAVE emitted+evicted.
+      return lastSeq >= this.nextSeq - 1 ? { kind: 'tail', frames: [] } : { kind: 'overrun' };
+    }
+    const oldest = this.frames[0].seq;
+    if (lastSeq < oldest - 1) return { kind: 'overrun' };
+    return { kind: 'tail', frames: this.frames.filter((f) => f.seq > lastSeq) };
+  }
+
+  /** The last seq assigned (0 when nothing has been appended). */
+  public get lastSeq(): number {
+    return this.nextSeq - 1;
+  }
+
+  /** Retained frame count (diagnostics/tests). */
+  public get size(): number {
+    return this.frames.length;
+  }
+
+  private evict(): void {
+    let drop = 0;
+    let remainingBytes = this.bytes;
+    // Evict oldest while over the frame cap, or over the byte cap (but always keep at least the newest frame).
+    while (
+      this.frames.length - drop > this.maxFrames ||
+      (remainingBytes > this.maxBytes && this.frames.length - drop > 1)
+    ) {
+      remainingBytes -= this.sizes[drop];
+      drop += 1;
+    }
+    this.removeOldest(drop);
+  }
+
+  /** The single place that mutates `frames`/`sizes`/`bytes` for removal, so byte accounting can't drift. */
+  private removeOldest(count: number): void {
+    if (count <= 0) return;
+    for (let i = 0; i < count; i += 1) this.bytes -= this.sizes[i] ?? 0;
+    this.frames.splice(0, count);
+    this.sizes.splice(0, count);
+    if (this.frames.length === 0) this.bytes = 0;
+  }
+}