@nanobpm/urban-agent-client 0.1.0

package/src/conformance.test.ts

@@ -0,0 +1,151 @@
+/**
+ * Conformance: the worker client is held to the SAME shared adversarial corpus
+ * (`@nanobpm/agentic/source/protocol/conformance`) as the S0 codec and the
+ * cross-repo c8ctl client. A shared prose spec does not stop divergence — shared
+ * vectors do. This test file is the package's `test:conformance` entry point and
+ * runs with no build step (source-only imports, hence the `/source/conformance`
+ * subpath), so the CI `conformance` job
+ * exercises the real vectors against this client.
+ */
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  GOLDEN_FRAMES,
+  MALFORMED_FRAMES,
+  VALID_TOKENS,
+  INVALID_TOKENS,
+} from "@nanobpm/agentic/source/protocol/conformance";
+import { AgenticClient } from "./client.ts";
+import {
+  FrameDecodeError,
+  bytesToHex,
+  decodeFrame,
+  encodeFrame,
+  hexToBytes,
+  isValidToken,
+  validatePayload,
+} from "./protocol.ts";
+import type { Frame, ServePayload } from "./protocol.ts";
+import { fakeTransportFactory } from "./testkit.ts";
+
+test("golden frames round-trip through the codec the client uses (both directions)", () => {
+  for (const golden of GOLDEN_FRAMES) {
+    const decoded = decodeFrame(hexToBytes(golden.hex));
+    assert.deepEqual(decoded, golden.frame, `decode ${golden.name}`);
+    assert.equal(bytesToHex(encodeFrame(golden.frame)), golden.hex, `encode ${golden.name}`);
+  }
+});
+
+test("malformed vectors reject with the codes the corpus specifies", () => {
+  for (const bad of MALFORMED_FRAMES) {
+    assert.throws(
+      () => decodeFrame(hexToBytes(bad.hex)),
+      (error: unknown) => {
+        assert.ok(error instanceof FrameDecodeError, `${bad.name} threw FrameDecodeError`);
+        assert.equal(error.code, bad.expected, `${bad.name} code`);
+        return true;
+      },
+    );
+  }
+});
+
+test("the client tolerates every malformed corpus vector without crashing", () => {
+  const t = fakeTransportFactory();
+  const client = new AgenticClient({
+    url: "ws://test",
+    instance: "w-conformance",
+    transport: t.factory,
+    reconnect: { enabled: false },
+    serveTimeoutMs: 0,
+  });
+  const errors: Error[] = [];
+  client.onError((e) => errors.push(e));
+  client.connect();
+  t.last().fireOpen();
+
+  for (const bad of MALFORMED_FRAMES) {
+    t.last().deliver(hexToBytes(bad.hex));
+  }
+  // Every malformed vector surfaced an error; the client is still usable.
+  assert.equal(errors.length, MALFORMED_FRAMES.length);
+  client.heartbeat();
+  assert.ok(t.last().sentFrames.some((f) => f.family === "heartbeat"));
+  client.close();
+});
+
+test("the client resolves register against a golden SERVE frame from the corpus", async () => {
+  const golden = GOLDEN_FRAMES.find((g) => g.frame.family === "serve");
+  assert.ok(golden, "corpus has a serve golden");
+  const servePayload = golden.frame.payload;
+  assert.ok(isServePayload(servePayload));
+
+  const t = fakeTransportFactory();
+  const client = new AgenticClient({
+    url: "ws://test",
+    instance: servePayload.instance,
+    transport: t.factory,
+    reconnect: { enabled: false },
+    serveTimeoutMs: 1000,
+  });
+  client.connect();
+  t.last().fireOpen();
+  const pending = client.register({ capability: { cognition: "opus" } });
+  t.last().deliver(hexToBytes(golden.hex));
+  const { serve } = await pending;
+  assert.deepEqual(serve, servePayload.tokens);
+  client.close();
+});
+
+test("frames the client produces satisfy the S0 payload contract and family codes", () => {
+  const t = fakeTransportFactory();
+  const client = new AgenticClient({
+    url: "ws://test",
+    instance: "w-1",
+    transport: t.factory,
+    reconnect: { enabled: false },
+    serveTimeoutMs: 0,
+    capability: { cognition: "opus", weight: 3, family: "anthropic", host: "mac-01" },
+  });
+  client.connect();
+  t.last().fireOpen(); // auto-registers
+  client.heartbeat();
+  client.relay("stdout", "multi-byte: café ☕");
+  client.deregister("done");
+
+  for (const frame of t.last().sentFrames) {
+    // Every emitted frame decodes to a known family and passes its contract.
+    const result = validatePayload(frame.family, frame.payload);
+    assert.ok(result.ok, `emitted ${frame.family} frame is contract-valid`);
+    // And its wire bytes round-trip byte-for-byte.
+    assert.equal(bytesToHex(encodeFrame(frame)), bytesToHex(encodeFrame(reencode(frame))));
+  }
+  const families = t.last().sentFrames.map((f) => f.family);
+  assert.deepEqual(new Set(families), new Set(["register", "heartbeat", "relay", "deregister"]));
+  client.close();
+});
+
+test("the client accepts exactly the corpus's valid routing tokens in a SERVE", () => {
+  // The client validates SERVE tokens via the S0 codec's isValidToken; assert it
+  // agrees with the corpus so token acceptance can never drift from the vectors.
+  for (const valid of VALID_TOKENS) {
+    assert.ok(isValidToken(valid.token), `accepts ${valid.name}`);
+  }
+  for (const invalid of INVALID_TOKENS) {
+    assert.ok(!isValidToken(invalid.token), `rejects ${invalid.name}`);
+  }
+});
+
+function reencode(frame: Frame): Frame {
+  return decodeFrame(encodeFrame(frame));
+}
+
+function isServePayload(payload: unknown): payload is ServePayload {
+  if (typeof payload !== "object" || payload === null) {
+    return false;
+  }
+  if (!("instance" in payload) || !("tokens" in payload)) {
+    return false;
+  }
+  const { instance, tokens } = payload;
+  return typeof instance === "string" && Array.isArray(tokens);
+}

package/src/index.ts

@@ -0,0 +1,77 @@
+/**
+ * `@nanobpm/urban-agent-client` — the worker-side client for the Nano agentic
+ * channel (ADR 0056, slice S9).
+ *
+ * A worker uses it on a connection SEPARATE from the C8 job protocol to:
+ *  - `REGISTER` a capability and receive its resolved `SERVE` tokens,
+ *  - `heartbeat` / `deregister` for presence & liveness,
+ *  - produce `relay` bytes (live terminal / command-stream output), and
+ *  - keep producing across a hub outage — everything is buffered in a bounded,
+ *    QoS-aware {@link OutboundRing} and drained, control-before-bulk, on
+ *    reconnect (hub-down tolerance, invariant #6).
+ *
+ * The wire contract itself is owned by `@nanobpm/agentic/protocol` (S0); this
+ * package imports and is held to it (including its shared conformance corpus),
+ * never redefining it.
+ *
+ * @example
+ * ```ts
+ * import { connectAgenticChannel } from "@nanobpm/urban-agent-client";
+ *
+ * const agent = connectAgenticChannel({ url: process.env.AGENTIC_CHANNEL_URL! });
+ * const { serve } = await agent.register({
+ *   capability: { cognition: "high", weight: 3, family: "opus", host: "cli" },
+ * });
+ * agent.heartbeat();
+ * agent.relay("stdout", "hello\n");
+ * // …later…
+ * agent.deregister("done");
+ * ```
+ */
+
+export {
+  AgenticClient,
+  connectAgenticChannel,
+  isMessageFamily,
+} from "./client.ts";
+export type {
+  AgenticClientOptions,
+  AgenticClientState,
+  ReconnectOptions,
+  RegisterResult,
+} from "./client.ts";
+
+export { OutboundRing, compareFrameOrder } from "./ring.ts";
+export type { EnqueueResult, OutboundRingOptions } from "./ring.ts";
+
+export { websocketTransport, normaliseIncoming } from "./transport.ts";
+export type {
+  Transport,
+  TransportCloseInfo,
+  TransportFactory,
+  TransportHooks,
+} from "./transport.ts";
+
+// Re-export the S0 contract surface a worker needs so consumers can build and
+// inspect frames without a second dependency line. Sourced from
+// @nanobpm/agentic/protocol (the single source of truth).
+export {
+  MESSAGE_FAMILIES,
+  QOS_LANES,
+  encodeFrame,
+  decodeFrame,
+  parseToken,
+  isValidToken,
+  validatePayload,
+} from "./protocol.ts";
+export type {
+  Capability,
+  Frame,
+  MessageFamily,
+  QosLane,
+  RegisterPayload,
+  HeartbeatPayload,
+  DeregisterPayload,
+  ServePayload,
+  RelayPayload,
+} from "./protocol.ts";

package/src/protocol.ts

@@ -0,0 +1,46 @@
+/**
+ * Single import point for the S0 wire contract.
+ *
+ * We import from the package's `./source` export (raw `.ts`) rather than the
+ * bare entry (`dist`) on purpose: the CI `conformance` job runs
+ * `npm run test:conformance` with **no build step**, so every module this client
+ * touches must be runnable straight from source under
+ * `node --experimental-strip-types`. The Urban stack ships source `.ts` and runs
+ * under strip-types (ADR 0052/0053), so a published consumer resolves the same
+ * source. Keeping the import in one module gives a single swap point.
+ *
+ * The contract itself is owned by `@nanobpm/agentic/protocol` (S0, #126) — this
+ * client imports it, it never redefines it.
+ */
+export {
+  MESSAGE_FAMILIES,
+  isMessageFamily,
+  QOS_LANES,
+  isQosLane,
+  compareFrameOrder,
+  encodeFrame,
+  decodeFrame,
+  FrameDecodeError,
+  FrameEncodeError,
+  MAX_SEQ,
+  parseToken,
+  isValidToken,
+  validatePayload,
+  bytesToHex,
+  hexToBytes,
+} from "@nanobpm/agentic/source/protocol";
+
+export type {
+  MessageFamily,
+  QosLane,
+  Frame,
+  FrameDecodeErrorCode,
+  Capability,
+  RegisterPayload,
+  HeartbeatPayload,
+  DeregisterPayload,
+  ServePayload,
+  RelayPayload,
+  BlackboardPayload,
+  DemandPayload,
+} from "@nanobpm/agentic/source/protocol";

package/src/ring.test.ts

@@ -0,0 +1,155 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { OutboundRing, compareFrameOrder } from "./ring.ts";
+import type { Frame, QosLane } from "./protocol.ts";
+
+function frame(lane: QosLane, seq: number, family: Frame["family"] = "relay"): Frame {
+  return { lane, family, seq, payload: { seq } };
+}
+
+test("drains in strict QoS lane priority, FIFO within a lane", () => {
+  const ring = new OutboundRing({ capacity: 16 });
+  ring.enqueue(frame("bulk", 0));
+  ring.enqueue(frame("interactive", 1));
+  ring.enqueue(frame("control", 2, "heartbeat"));
+  ring.enqueue(frame("bulk", 3));
+  ring.enqueue(frame("control", 4, "heartbeat"));
+
+  const order = [ring.dequeue(), ring.dequeue(), ring.dequeue(), ring.dequeue(), ring.dequeue()];
+  assert.deepEqual(
+    order.map((f) => f && [f.lane, f.seq]),
+    [
+      ["control", 2],
+      ["control", 4],
+      ["interactive", 1],
+      ["bulk", 0],
+      ["bulk", 3],
+    ],
+  );
+  assert.equal(ring.dequeue(), undefined);
+});
+
+test("a bulk storm never head-of-line-blocks a control frame", () => {
+  const ring = new OutboundRing({ capacity: 1000 });
+  for (let i = 0; i < 500; i++) {
+    ring.enqueue(frame("bulk", i));
+  }
+  ring.enqueue(frame("control", 500, "heartbeat"));
+  // Despite 500 queued bulk frames enqueued first, the heartbeat drains next.
+  const next = ring.dequeue();
+  assert.equal(next?.lane, "control");
+  assert.equal(next?.seq, 500);
+});
+
+test("toArray drain order equals sorting by S0 compareFrameOrder", () => {
+  const ring = new OutboundRing({ capacity: 32 });
+  const frames = [
+    frame("bulk", 10),
+    frame("control", 11, "heartbeat"),
+    frame("interactive", 12),
+    frame("bulk", 13),
+    frame("control", 14, "heartbeat"),
+    frame("interactive", 15),
+  ];
+  for (const f of frames) {
+    ring.enqueue(f);
+  }
+  const expected = [...frames].sort(compareFrameOrder);
+  assert.deepEqual(ring.toArray(), expected);
+});
+
+test("overflow evicts the oldest bulk frame first, never a control frame", () => {
+  const ring = new OutboundRing({ capacity: 3 });
+  const c = frame("control", 0, "heartbeat");
+  ring.enqueue(c);
+  ring.enqueue(frame("bulk", 1));
+  ring.enqueue(frame("bulk", 2));
+  // Full. Next enqueue evicts the oldest bulk (seq 1), keeps the control frame.
+  const { evicted } = ring.enqueue(frame("bulk", 3));
+  assert.equal(evicted?.lane, "bulk");
+  assert.equal(evicted?.seq, 1);
+  assert.equal(ring.size, 3);
+  const remaining = ring.toArray();
+  assert.deepEqual(remaining.map((f) => [f.lane, f.seq]), [
+    ["control", 0],
+    ["bulk", 2],
+    ["bulk", 3],
+  ]);
+});
+
+test("overflow falls back to interactive, then control, when nothing lower is buffered", () => {
+  const ring = new OutboundRing({ capacity: 2 });
+  ring.enqueue(frame("control", 0, "heartbeat"));
+  ring.enqueue(frame("interactive", 1));
+  // Full with only control+interactive: the interactive frame is shed before control.
+  let res = ring.enqueue(frame("control", 2, "heartbeat"));
+  assert.equal(res.evicted?.lane, "interactive");
+  // Now two control frames: an overflow must evict the oldest control frame.
+  res = ring.enqueue(frame("control", 3, "heartbeat"));
+  assert.equal(res.evicted?.lane, "control");
+  assert.equal(res.evicted?.seq, 0);
+});
+
+test("overflow drops a lower-priority incoming frame rather than evicting a higher-priority buffered one", () => {
+  // Ring full of only control frames: a bulk frame must NOT displace control.
+  const ring = new OutboundRing({ capacity: 2 });
+  ring.enqueue(frame("control", 0, "heartbeat"));
+  ring.enqueue(frame("control", 1, "heartbeat"));
+  const { evicted } = ring.enqueue(frame("bulk", 2));
+  // The incoming bulk frame is the least important — it is dropped, not buffered.
+  assert.equal(evicted?.lane, "bulk");
+  assert.equal(evicted?.seq, 2);
+  assert.equal(ring.size, 2);
+  assert.deepEqual(
+    ring.toArray().map((f) => [f.lane, f.seq]),
+    [
+      ["control", 0],
+      ["control", 1],
+    ],
+    "both control frames survive; the bulk frame never entered the ring",
+  );
+});
+
+test("enqueueFront also drops a lower-priority incoming frame instead of evicting higher-priority traffic", () => {
+  const ring = new OutboundRing({ capacity: 2 });
+  ring.enqueue(frame("control", 0, "heartbeat"));
+  ring.enqueue(frame("interactive", 1));
+  // interactive is still higher priority than bulk, so a bulk front-insert is dropped.
+  const { evicted } = ring.enqueueFront(frame("bulk", 2));
+  assert.equal(evicted?.lane, "bulk");
+  assert.equal(evicted?.seq, 2);
+  assert.equal(ring.size, 2);
+  assert.deepEqual(
+    ring.toArray().map((f) => [f.lane, f.seq]),
+    [
+      ["control", 0],
+      ["interactive", 1],
+    ],
+  );
+});
+
+test("peek is non-destructive and matches the next dequeue", () => {
+  const ring = new OutboundRing({ capacity: 4 });
+  ring.enqueue(frame("bulk", 1));
+  ring.enqueue(frame("control", 2, "heartbeat"));
+  const peeked = ring.peek();
+  assert.equal(peeked?.lane, "control");
+  assert.equal(ring.size, 2);
+  assert.deepEqual(ring.dequeue(), peeked);
+});
+
+test("rejects a non-positive capacity", () => {
+  assert.throws(() => new OutboundRing({ capacity: 0 }), RangeError);
+  assert.throws(() => new OutboundRing({ capacity: -1 }), RangeError);
+  assert.throws(() => new OutboundRing({ capacity: 1.5 }), RangeError);
+});
+
+test("clear empties the ring", () => {
+  const ring = new OutboundRing({ capacity: 4 });
+  ring.enqueue(frame("bulk", 1));
+  ring.enqueue(frame("control", 2, "heartbeat"));
+  ring.clear();
+  assert.equal(ring.size, 0);
+  assert.ok(ring.isEmpty);
+  assert.equal(ring.dequeue(), undefined);
+});

package/src/ring.ts

@@ -0,0 +1,228 @@
+import { QOS_LANES, compareFrameOrder } from "./protocol.ts";
+import type { Frame, QosLane } from "./protocol.ts";
+
+/**
+ * The worker-side outbound buffer: a bounded, QoS-aware ring that holds frames
+ * the worker has produced but not yet handed to the transport. It is the local
+ * buffer / flush-on-reconnect store that gives the client its hub-down
+ * tolerance (invariant #6) — the worker keeps producing while the hub is gone,
+ * and drains in order when the channel comes back.
+ *
+ * Two properties are load-bearing:
+ *
+ *  1. **QoS drain order (invariant #5).** Frames drain in strict lane priority —
+ *     `control` before `interactive` before `bulk` — and FIFO within a lane.
+ *     A bulk-output storm can never head-of-line-block a queued heartbeat or
+ *     blackboard write: the heartbeat rides the control lane and drains first.
+ *     The ordering is DERIVED from S0's canonical {@link compareFrameOrder}, not
+ *     re-specified here (see {@link toArray}'s invariant test).
+ *
+ *  2. **Overflow sheds the single least important frame.** When the ring is
+ *     full, the next enqueue drops the lowest-priority frame among the buffer
+ *     AND the incoming frame: the oldest frame from the lowest-priority
+ *     non-empty lane is evicted (bulk before interactive before control) —
+ *     UNLESS the incoming frame is itself strictly lower priority than
+ *     everything buffered, in which case the incoming frame is dropped and the
+ *     buffer is left untouched. A higher-priority buffered frame (e.g. control)
+ *     is therefore never evicted to admit a lower-priority one (e.g. bulk):
+ *     bulk/interactive traffic can never displace buffered control frames. This
+ *     bounds memory during a long outage without ever losing liveness/
+ *     coordination traffic to a relay storm.
+ */
+export interface OutboundRingOptions {
+  /** Maximum number of buffered frames. Must be a positive integer. */
+  readonly capacity: number;
+}
+
+export interface EnqueueResult {
+  /**
+   * The frame shed by this enqueue, or `null` if the ring had spare capacity.
+   * Usually the oldest frame from the lowest-priority non-empty lane, evicted to
+   * make room; but when the ring is full of strictly higher-priority frames the
+   * INCOMING frame is itself the least important — it is dropped rather than
+   * displace higher-priority traffic, and is returned here with the buffer left
+   * unchanged.
+   */
+  readonly evicted: Frame | null;
+}
+
+// Lanes in strict priority order (highest first). Kept as a local const so the
+// bucket walk is O(number-of-lanes) and independent of insertion.
+const LANES_BY_PRIORITY: readonly QosLane[] = [...QOS_LANES];
+const LANES_BY_EVICTION: readonly QosLane[] = [...QOS_LANES].reverse();
+
+// Priority rank per lane (0 = highest), derived from the canonical QOS_LANES
+// order so lane comparison has a single source of truth. A LARGER rank means
+// lower priority (evicted sooner).
+const LANE_RANK: ReadonlyMap<QosLane, number> = new Map(LANES_BY_PRIORITY.map((lane, index) => [lane, index]));
+
+function laneRank(lane: QosLane): number {
+  return LANE_RANK.get(lane) ?? Number.POSITIVE_INFINITY;
+}
+
+export class OutboundRing {
+  readonly capacity: number;
+  private readonly buckets: Map<QosLane, Frame[]>;
+  private count = 0;
+
+  constructor(options: OutboundRingOptions) {
+    if (!Number.isInteger(options.capacity) || options.capacity < 1) {
+      throw new RangeError(`OutboundRing capacity must be a positive integer, got ${options.capacity}`);
+    }
+    this.capacity = options.capacity;
+    this.buckets = new Map(LANES_BY_PRIORITY.map((lane): [QosLane, Frame[]] => [lane, []]));
+  }
+
+  /** Number of frames currently buffered. */
+  get size(): number {
+    return this.count;
+  }
+
+  /** True when no frames are buffered. */
+  get isEmpty(): boolean {
+    return this.count === 0;
+  }
+
+  /**
+   * Buffer a frame. When the ring is already at capacity, the least important
+   * frame among the buffer and this one is shed (see {@link EnqueueResult.evicted}
+   * and the class-level overflow contract).
+   */
+  enqueue(frame: Frame): EnqueueResult {
+    return this.admit(frame, false);
+  }
+
+  /**
+   * Buffer a frame at the FRONT of its lane (drains before frames already
+   * queued in that lane). Used to make a reconnect's re-`register` precede any
+   * backlog buffered during the outage. Overflow follows the same QoS-correct
+   * policy as {@link enqueue}: the incoming frame is dropped rather than
+   * displace strictly higher-priority buffered traffic.
+   */
+  enqueueFront(frame: Frame): EnqueueResult {
+    return this.admit(frame, true);
+  }
+
+  /**
+   * Shared admission path for {@link enqueue} / {@link enqueueFront}.
+   *
+   * Overflow is QoS-correct: when the ring is full we shed the single
+   * least-important frame among the buffer ∪ the incoming frame. If the incoming
+   * frame is strictly lower priority than every buffered frame, IT is the least
+   * important, so it is dropped (and returned as `evicted`) and the buffer is
+   * untouched — a bulk/interactive frame never evicts buffered control traffic.
+   * Otherwise the oldest frame from the lowest-priority non-empty lane is
+   * evicted to make room.
+   */
+  private admit(frame: Frame, toFront: boolean): EnqueueResult {
+    const bucket = this.buckets.get(frame.lane);
+    if (bucket === undefined) {
+      throw new RangeError(`unknown QoS lane: ${String(frame.lane)}`);
+    }
+    let evicted: Frame | null = null;
+    if (this.count >= this.capacity) {
+      const victimLane = this.lowestNonEmptyLane();
+      if (victimLane === undefined || laneRank(frame.lane) > laneRank(victimLane)) {
+        // The incoming frame is the least important thing in play — drop it
+        // rather than evict a higher-priority buffered frame.
+        return { evicted: frame };
+      }
+      evicted = this.buckets.get(victimLane)?.shift() ?? null;
+      if (evicted !== null) {
+        this.count -= 1;
+      }
+    }
+    if (toFront) {
+      bucket.unshift(frame);
+    } else {
+      bucket.push(frame);
+    }
+    this.count += 1;
+    return { evicted };
+  }
+
+  /** The next frame to drain (highest priority, oldest within its lane) without removing it. */
+  peek(): Frame | undefined {
+    for (const lane of LANES_BY_PRIORITY) {
+      const bucket = this.buckets.get(lane);
+      if (bucket !== undefined && bucket.length > 0) {
+        return bucket[0];
+      }
+    }
+    return undefined;
+  }
+
+  /** Remove and return the next frame to drain, or `undefined` when empty. */
+  dequeue(): Frame | undefined {
+    for (const lane of LANES_BY_PRIORITY) {
+      const bucket = this.buckets.get(lane);
+      if (bucket !== undefined && bucket.length > 0) {
+        this.count -= 1;
+        return bucket.shift();
+      }
+    }
+    return undefined;
+  }
+
+  /** Non-destructive snapshot in drain order (priority lane, then FIFO). */
+  toArray(): Frame[] {
+    const out: Frame[] = [];
+    for (const lane of LANES_BY_PRIORITY) {
+      const bucket = this.buckets.get(lane);
+      if (bucket !== undefined) {
+        out.push(...bucket);
+      }
+    }
+    return out;
+  }
+
+  /**
+   * Remove every buffered frame matching `predicate`, returning the removed
+   * frames. Used to coalesce superseded control frames (e.g. an in-flight
+   * REGISTER replaced by a newer one) so the drain never emits a stale duplicate.
+   */
+  remove(predicate: (frame: Frame) => boolean): Frame[] {
+    const removed: Frame[] = [];
+    for (const lane of LANES_BY_PRIORITY) {
+      const bucket = this.buckets.get(lane);
+      if (bucket === undefined) {
+        continue;
+      }
+      for (let i = bucket.length - 1; i >= 0; i--) {
+        const frame = bucket[i];
+        if (frame !== undefined && predicate(frame)) {
+          removed.push(frame);
+          bucket.splice(i, 1);
+          this.count -= 1;
+        }
+      }
+    }
+    return removed;
+  }
+
+  /** Discard all buffered frames. */
+  clear(): void {
+    for (const bucket of this.buckets.values()) {
+      bucket.length = 0;
+    }
+    this.count = 0;
+  }
+
+  private lowestNonEmptyLane(): QosLane | undefined {
+    for (const lane of LANES_BY_EVICTION) {
+      const bucket = this.buckets.get(lane);
+      if (bucket !== undefined && bucket.length > 0) {
+        return lane;
+      }
+    }
+    return undefined;
+  }
+}
+
+/**
+ * The canonical drain comparator, re-exported from S0 so callers that need to
+ * reason about ordering derive it from one source rather than re-implementing
+ * lane priority. {@link OutboundRing.toArray} is asserted equal to sorting by
+ * this comparator in the ring's tests.
+ */
+export { compareFrameOrder };