@nanobpm/agentic 0.1.0

package/src/relay/ring.test.ts

@@ -0,0 +1,138 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { ReplayRing } from "./ring.ts";
+
+test("append assigns monotonic, gap-free offsets from 0", () => {
+  const ring = new ReplayRing({ capacity: 8 });
+  assert.equal(ring.nextOffset, 0);
+  assert.equal(ring.firstOffset, undefined);
+  const a = ring.append("a");
+  const b = ring.append("b");
+  assert.deepEqual(a, { offset: 0, chunk: "a" });
+  assert.deepEqual(b, { offset: 1, chunk: "b" });
+  assert.equal(ring.nextOffset, 2);
+  assert.equal(ring.firstOffset, 0);
+  assert.equal(ring.size, 2);
+});
+
+test("bounded: evicts oldest but keeps offsets monotonic across eviction", () => {
+  const ring = new ReplayRing({ capacity: 3 });
+  for (const c of ["a", "b", "c", "d", "e"]) {
+    ring.append(c);
+  }
+  assert.equal(ring.size, 3);
+  assert.equal(ring.firstOffset, 2); // a(0), b(1) evicted
+  assert.equal(ring.nextOffset, 5);
+  assert.deepEqual(ring.since(0).entries.map((e) => e.offset), [2, 3, 4]);
+});
+
+test("since(from) returns the exact suffix when from is retained (resume-from-offset)", () => {
+  const ring = new ReplayRing({ capacity: 8 });
+  for (const c of ["a", "b", "c", "d"]) {
+    ring.append(c);
+  }
+  const slice = ring.since(2);
+  assert.equal(slice.gap, false);
+  assert.deepEqual(slice.entries, [
+    { offset: 2, chunk: "c" },
+    { offset: 3, chunk: "d" },
+  ]);
+});
+
+test("since(from) flags a gap when from predates the retained window", () => {
+  const ring = new ReplayRing({ capacity: 2 });
+  for (const c of ["a", "b", "c", "d"]) {
+    ring.append(c); // retains offsets 2,3
+  }
+  const slice = ring.since(0);
+  assert.equal(slice.gap, true);
+  assert.deepEqual(slice.entries.map((e) => e.offset), [2, 3]);
+});
+
+test("since(from) at the head returns empty with no gap", () => {
+  const ring = new ReplayRing({ capacity: 4 });
+  ring.append("a");
+  ring.append("b");
+  const slice = ring.since(2); // caller already has everything
+  assert.equal(slice.gap, false);
+  assert.deepEqual(slice.entries, []);
+});
+
+test("since(from) beyond nextOffset returns empty (consumer ahead of stream)", () => {
+  const ring = new ReplayRing({ capacity: 4 });
+  ring.append("a");
+  const slice = ring.since(10);
+  assert.equal(slice.gap, false);
+  assert.deepEqual(slice.entries, []);
+});
+
+test("since on an empty ring returns empty with no gap", () => {
+  const ring = new ReplayRing({ capacity: 4 });
+  const slice = ring.since(0);
+  assert.equal(slice.gap, false);
+  assert.deepEqual(slice.entries, []);
+});
+
+test("clear drops retained chunks but keeps the offset counter monotonic", () => {
+  const ring = new ReplayRing({ capacity: 4 });
+  ring.append("a");
+  ring.append("b");
+  ring.clear();
+  assert.equal(ring.size, 0);
+  assert.equal(ring.firstOffset, undefined);
+  const c = ring.append("c");
+  assert.equal(c.offset, 2); // not reset to 0
+});
+
+test("stays correct across multiple circular-buffer wraps (O(1) eviction)", () => {
+  const ring = new ReplayRing({ capacity: 3 });
+  // Append well past capacity so the head wraps the internal buffer several times.
+  for (let i = 0; i < 10; i += 1) {
+    ring.append(`c${i}`);
+  }
+  assert.equal(ring.size, 3);
+  assert.equal(ring.nextOffset, 10);
+  assert.equal(ring.firstOffset, 7); // offsets 0..6 evicted
+  assert.deepEqual(ring.since(0).entries, [
+    { offset: 7, chunk: "c7" },
+    { offset: 8, chunk: "c8" },
+    { offset: 9, chunk: "c9" },
+  ]);
+  assert.equal(ring.since(0).gap, true);
+  assert.deepEqual(ring.since(8).entries, [
+    { offset: 8, chunk: "c8" },
+    { offset: 9, chunk: "c9" },
+  ]);
+  assert.equal(ring.since(8).gap, false);
+});
+
+test("clear then append reuses the buffer correctly after a wrap", () => {
+  const ring = new ReplayRing({ capacity: 2 });
+  for (const c of ["a", "b", "c"]) {
+    ring.append(c); // wraps once, retains offsets 1,2
+  }
+  ring.clear();
+  assert.equal(ring.size, 0);
+  assert.equal(ring.firstOffset, undefined);
+  const d = ring.append("d");
+  const e = ring.append("e");
+  assert.equal(d.offset, 3);
+  assert.equal(e.offset, 4);
+  assert.equal(ring.firstOffset, 3);
+  assert.deepEqual(ring.since(3).entries, [
+    { offset: 3, chunk: "d" },
+    { offset: 4, chunk: "e" },
+  ]);
+});
+
+test("rejects a non-positive or non-integer capacity", () => {
+  assert.throws(() => new ReplayRing({ capacity: 0 }), RangeError);
+  assert.throws(() => new ReplayRing({ capacity: -1 }), RangeError);
+  assert.throws(() => new ReplayRing({ capacity: 2.5 }), RangeError);
+});
+
+test("rejects a negative or non-integer since(from)", () => {
+  const ring = new ReplayRing({ capacity: 4 });
+  assert.throws(() => ring.since(-1), RangeError);
+  assert.throws(() => ring.since(1.5), RangeError);
+});

package/src/relay/ring.ts

@@ -0,0 +1,136 @@
+/**
+ * The bounded replay ring — S5's resume-from-offset store for one relay stream.
+ *
+ * A live terminal stream is an append-only sequence of chunks. Each appended
+ * chunk is assigned a monotonic, gap-free `offset` (starting at 0). The ring
+ * retains only the most recent `capacity` chunks: older chunks are evicted so a
+ * long-running stream cannot grow unbounded.
+ *
+ * Resume-from-offset (the load-bearing property): when a consumer reconnects it
+ * asks for everything from the next offset it still needs. {@link ReplayRing.since}
+ * returns exactly the retained tail from that offset, and flags a `gap` when the
+ * requested offset predates what is still retained (i.e. the consumer was
+ * disconnected long enough that some chunks were evicted before it could resume).
+ * The stream itself survives the reconnect — the ring is the durable-enough
+ * window that makes resume possible.
+ */
+import { addSafeInt, isNonNegInt, isPosInt } from "./validate.ts";
+
+/** A single retained chunk and the offset it was assigned. */
+export interface ReplayEntry {
+  readonly offset: number;
+  readonly chunk: string;
+}
+
+export interface ReplayRingOptions {
+  /** Maximum number of retained chunks. Must be a positive integer. */
+  readonly capacity: number;
+}
+
+/** The result of a {@link ReplayRing.since} query. */
+export interface ReplaySlice {
+  /** The retained entries with `offset >= from`, in offset order. */
+  readonly entries: readonly ReplayEntry[];
+  /**
+   * `true` when `from` predates the oldest retained offset: some chunks the
+   * consumer asked for were already evicted, so the replay is not gap-free. The
+   * consumer should treat the returned tail as a best-effort resume, not a
+   * continuous stream from `from`.
+   */
+  readonly gap: boolean;
+}
+
+export class ReplayRing {
+  readonly capacity: number;
+  // Fixed-size circular buffer: eviction overwrites the oldest slot and advances
+  // the head in O(1), instead of Array.shift() (O(n) on every append once the
+  // ring is at steady-state capacity — a hotspot for high-throughput streams).
+  readonly #buffer: (ReplayEntry | undefined)[] = [];
+  #head = 0;
+  #count = 0;
+  #nextOffset = 0;
+
+  constructor(options: ReplayRingOptions) {
+    if (!isPosInt(options.capacity)) {
+      throw new RangeError(`ReplayRing capacity must be a positive integer, got ${options.capacity}`);
+    }
+    this.capacity = options.capacity;
+    this.#buffer.length = options.capacity;
+  }
+
+  /** Number of chunks currently retained. */
+  get size(): number {
+    return this.#count;
+  }
+
+  /** The offset the next {@link append} will assign (also the total ever appended). */
+  get nextOffset(): number {
+    return this.#nextOffset;
+  }
+
+  /** The oldest retained offset, or `undefined` when nothing is retained. */
+  get firstOffset(): number | undefined {
+    return this.#count === 0 ? undefined : this.#buffer[this.#head]?.offset;
+  }
+
+  /**
+   * Append a chunk, assigning it the next offset. When the ring is at capacity
+   * the oldest retained chunk is evicted first (the offset counter still
+   * advances, so offsets stay monotonic and gap-free across eviction).
+   */
+  append(chunk: string): ReplayEntry {
+    // Fail fast before mutating any state: compute the next offset first so an
+    // overflow throws atomically (the ring is left untouched) rather than after
+    // a partial append. Offsets accumulate forever, so guard the running total.
+    const offset = this.#nextOffset;
+    const nextOffset = addSafeInt(offset, 1, "ReplayRing offset");
+    const entry: ReplayEntry = { offset, chunk };
+    if (this.#count < this.capacity) {
+      this.#buffer[(this.#head + this.#count) % this.capacity] = entry;
+      this.#count += 1;
+    } else {
+      // At capacity: overwrite the oldest slot and advance the head — O(1).
+      this.#buffer[this.#head] = entry;
+      this.#head = (this.#head + 1) % this.capacity;
+    }
+    this.#nextOffset = nextOffset;
+    return entry;
+  }
+
+  /**
+   * Return the retained tail from offset `from` (inclusive), for resume. `from`
+   * is clamped to what is retained:
+   *  - `from <= firstOffset` → the whole retained window; `gap` is `true` when
+   *    `from` is strictly before the oldest retained offset (evicted chunks).
+   *  - `firstOffset < from <= nextOffset` → the exact suffix from `from`; no gap.
+   *  - `from > nextOffset` → empty (the consumer is ahead of the stream); no gap.
+   */
+  since(from: number): ReplaySlice {
+    if (!isNonNegInt(from)) {
+      throw new RangeError(`since(from) requires a non-negative integer, got ${from}`);
+    }
+    const first = this.firstOffset;
+    if (first === undefined || from >= this.#nextOffset) {
+      // Nothing retained, or the consumer already has everything.
+      return { entries: [], gap: first !== undefined && from < first };
+    }
+    const gap = from < first;
+    const startOffset = gap ? first : from;
+    const startIndex = startOffset - first;
+    const entries: ReplayEntry[] = [];
+    for (let i = startIndex; i < this.#count; i += 1) {
+      const entry = this.#buffer[(this.#head + i) % this.capacity];
+      if (entry !== undefined) {
+        entries.push(entry);
+      }
+    }
+    return { entries, gap };
+  }
+
+  /** Drop every retained chunk. The offset counter is NOT reset (offsets stay monotonic). */
+  clear(): void {
+    this.#buffer.fill(undefined);
+    this.#head = 0;
+    this.#count = 0;
+  }
+}

package/src/relay/scheduler.test.ts

@@ -0,0 +1,233 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import type { Frame, QosLane } from "../protocol/index.ts";
+import { QosScheduler, compareFrameOrder } from "./scheduler.ts";
+
+let seq = 0;
+function frame(lane: QosLane, tag: string): Frame {
+  return { lane, family: "relay", seq: seq++, payload: { tag } };
+}
+
+function tagsOf(frames: Frame[]): string[] {
+  return frames.map((f) => {
+    const p = f.payload;
+    if (typeof p === "object" && p !== null) {
+      const tag = Reflect.get(p, "tag");
+      if (typeof tag === "string") {
+        return tag;
+      }
+    }
+    return "";
+  });
+}
+
+test("drains in strict lane priority: control > interactive > bulk", () => {
+  seq = 0;
+  const out: Frame[] = [];
+  // Credit 0 holds the bulk lane so this asserts the guarantee directly: control
+  // and interactive drain eagerly and are NOT head-of-line-blocked by buffered
+  // bulk. Once credit is granted the bulk tail follows, strictly last.
+  const s = new QosScheduler({ sink: (f) => out.push(f), credit: 0 });
+  s.enqueue(frame("bulk", "b1"));
+  s.enqueue(frame("control", "c1"));
+  s.enqueue(frame("interactive", "i1"));
+  s.enqueue(frame("bulk", "b2"));
+  s.enqueue(frame("control", "c2"));
+  // Bulk is still buffered; every control/interactive frame has already sailed past it.
+  assert.deepEqual(tagsOf(out), ["c1", "i1", "c2"]);
+  assert.equal(s.pendingBulk, 2);
+  s.grantCredit(100);
+  // Full drain: every control/interactive frame precedes every bulk frame.
+  assert.deepEqual(tagsOf(out), ["c1", "i1", "c2", "b1", "b2"]);
+});
+
+test("bulk is strictly ranked below control/interactive and drains in S0 compareFrameOrder", () => {
+  seq = 0;
+  const out: Frame[] = [];
+  // Credit 0 holds the bulk lane while the higher lanes drain eagerly (low
+  // latency). The load-bearing guarantee: every bulk frame is emitted only AFTER
+  // every control/interactive frame — bulk never head-of-line-blocks them.
+  const s = new QosScheduler({ sink: (f) => out.push(f), credit: 0 });
+  const bulk = [frame("bulk", "b0"), frame("bulk", "b1"), frame("bulk", "b2")];
+  const high = [frame("control", "c0"), frame("interactive", "i0"), frame("control", "c1")];
+  for (const f of [bulk[0], high[0], bulk[1], high[1], bulk[2], high[2]]) {
+    s.enqueue(f);
+  }
+  // Only the higher-lane frames have drained; all bulk is still held.
+  assert.deepEqual(new Set(tagsOf(out)), new Set(["c0", "i0", "c1"]));
+  assert.equal(s.pendingBulk, 3);
+  s.grantCredit(100);
+  // Bulk now drains, in S0 compareFrameOrder (ascending seq within the lane),
+  // and strictly after every higher-lane frame.
+  const firstBulkIndex = out.findIndex((f) => f.lane === "bulk");
+  assert.ok(out.slice(0, firstBulkIndex).every((f) => f.lane !== "bulk"));
+  const drainedBulk = out.filter((f) => f.lane === "bulk");
+  assert.deepEqual(tagsOf(drainedBulk), tagsOf([...bulk].sort(compareFrameOrder)));
+});
+
+test("a bulk storm never head-of-line-blocks a control frame (zero credit)", () => {
+  seq = 0;
+  const out: Frame[] = [];
+  const s = new QosScheduler({ sink: (f) => out.push(f), credit: 0 });
+  for (let i = 0; i < 1000; i++) {
+    s.enqueue(frame("bulk", `b${i}`));
+  }
+  // No credit → not one bulk frame has been emitted...
+  assert.equal(out.length, 0);
+  assert.equal(s.pendingBulk, 1000 <= 1024 ? 1000 : 1024);
+  // ...yet a heartbeat on the control lane sails straight through.
+  s.enqueue(frame("control", "hb"));
+  assert.deepEqual(tagsOf(out), ["hb"]);
+});
+
+test("credit gates the bulk lane; grantCredit releases exactly that many", () => {
+  seq = 0;
+  const out: Frame[] = [];
+  const s = new QosScheduler({ sink: (f) => out.push(f), credit: 0 });
+  s.enqueue(frame("bulk", "b0"));
+  s.enqueue(frame("bulk", "b1"));
+  s.enqueue(frame("bulk", "b2"));
+  assert.equal(out.length, 0);
+  s.grantCredit(2);
+  assert.deepEqual(tagsOf(out), ["b0", "b1"]);
+  assert.equal(s.credit, 0);
+  assert.equal(s.pendingBulk, 1);
+  s.grantCredit(5); // more than remains
+  assert.deepEqual(tagsOf(out), ["b0", "b1", "b2"]);
+  assert.equal(s.credit, 4); // leftover credit is retained
+});
+
+test("initial credit lets bulk flow immediately", () => {
+  seq = 0;
+  const out: Frame[] = [];
+  const s = new QosScheduler({ sink: (f) => out.push(f), credit: 3 });
+  s.enqueue(frame("bulk", "b0"));
+  s.enqueue(frame("bulk", "b1"));
+  assert.deepEqual(tagsOf(out), ["b0", "b1"]);
+  assert.equal(s.credit, 1);
+});
+
+test("bulk overflow sheds the OLDEST bulk frame; control is never shed", () => {
+  seq = 0;
+  const out: Frame[] = [];
+  const s = new QosScheduler({ sink: (f) => out.push(f), credit: 0, bulkCapacity: 3 });
+  s.enqueue(frame("bulk", "b0"));
+  s.enqueue(frame("bulk", "b1"));
+  s.enqueue(frame("bulk", "b2"));
+  s.enqueue(frame("bulk", "b3")); // overflow → b0 shed
+  assert.equal(s.shed, 1);
+  assert.equal(s.pendingBulk, 3);
+  s.grantCredit(100);
+  assert.deepEqual(tagsOf(out), ["b1", "b2", "b3"]);
+});
+
+test("bulk circular buffer wraps correctly across interleaved overflow and draining", () => {
+  seq = 0;
+  const out: Frame[] = [];
+  // Exercises the ring's head wrap-around (defect-class guard for the O(1)
+  // circular buffer that replaced Array.shift()): fill past capacity, drain a
+  // partial slice so the head advances, then refill past capacity again so the
+  // write index wraps around the buffer.
+  const s = new QosScheduler({ sink: (f) => out.push(f), credit: 0, bulkCapacity: 3 });
+  for (const t of ["b0", "b1", "b2", "b3", "b4"]) {
+    s.enqueue(frame("bulk", t)); // b0, b1 shed → holds b2, b3, b4
+  }
+  assert.equal(s.shed, 2);
+  assert.equal(s.pendingBulk, 3);
+  s.grantCredit(2); // drain b2, b3 → head advances, b4 remains
+  assert.deepEqual(tagsOf(out), ["b2", "b3"]);
+  assert.equal(s.pendingBulk, 1);
+  for (const t of ["b5", "b6", "b7"]) {
+    s.enqueue(frame("bulk", t)); // holds b4,b5,b6 then b4 shed → b5,b6,b7 (write index wraps)
+  }
+  assert.equal(s.shed, 3); // b4 was shed on the third refill
+  assert.equal(s.pendingBulk, 3);
+  s.grantCredit(100);
+  assert.deepEqual(tagsOf(out), ["b2", "b3", "b5", "b6", "b7"]); // b4 evicted, never emitted
+  assert.equal(s.pendingBulk, 0);
+});
+
+test("flush is a no-op when every lane is empty (guards the allocation-free empty-lane path)", () => {
+  seq = 0;
+  let sinkCalls = 0;
+  const s = new QosScheduler({ sink: () => sinkCalls++, credit: 100 });
+  // No frames enqueued: flush() must touch nothing and emit nothing. This guards
+  // the empty-lane fast path (splice(0) skipped under a length check) — draining
+  // an empty scheduler stays correct and side-effect-free.
+  s.flush();
+  assert.equal(sinkCalls, 0);
+  assert.equal(s.pending, 0);
+  // A bulk-only backlog (control/interactive empty) still flushes correctly: the
+  // guarded empty higher lanes are skipped, the bulk tail drains under credit.
+  s.enqueue(frame("bulk", "b0"));
+  assert.equal(sinkCalls, 1);
+  assert.equal(s.pending, 0);
+});
+
+test("a throwing sink mid bulk-drain preserves the un-emitted tail and its credit", () => {
+  seq = 0;
+  const out: Frame[] = [];
+  // Defect-class guard: flush() removes a bulk frame and spends its credit only
+  // as it emits it. If #sink() throws mid-drain, the not-yet-taken tail must stay
+  // buffered with its credit intact — a transient send failure must not silently
+  // drop the rest of the backlog or burn credit for frames that never went out.
+  let fail = true;
+  const s = new QosScheduler({
+    sink: (f) => {
+      if (fail && tagsOf([f])[0] === "b2") {
+        throw new Error("send failed");
+      }
+      out.push(f);
+    },
+    credit: 0,
+  });
+  for (const t of ["b0", "b1", "b2", "b3", "b4"]) {
+    s.enqueue(frame("bulk", t));
+  }
+  assert.equal(s.pendingBulk, 5);
+  // Grant enough credit to drain all five; the sink throws on b2 mid-drain.
+  assert.throws(() => s.grantCredit(5), /send failed/);
+  // remove-before-sink means the failed frame (b2) is gone, but the not-yet-
+  // emitted tail (b3, b4) is still buffered — never silently dropped.
+  assert.deepEqual(tagsOf(out), ["b0", "b1"]);
+  assert.equal(s.pendingBulk, 2);
+  // Credit was spent only for the frames actually taken (b0, b1, and the
+  // attempted b2); the un-emitted tail keeps its credit, so 5 - 3 = 2 remains.
+  assert.equal(s.credit, 2);
+  // A subsequent flush with a working sink drains the preserved tail, in order.
+  fail = false;
+  s.flush();
+  assert.deepEqual(tagsOf(out), ["b0", "b1", "b3", "b4"]);
+  assert.equal(s.pendingBulk, 0);
+});
+
+test("clear discards buffered frames across all lanes", () => {
+  seq = 0;
+  const out: Frame[] = [];
+  const s = new QosScheduler({ sink: (f) => out.push(f), credit: 0 });
+  s.enqueue(frame("bulk", "b0"));
+  s.enqueue(frame("bulk", "b1"));
+  assert.equal(s.pending, 2);
+  s.clear();
+  assert.equal(s.pending, 0);
+  s.grantCredit(100);
+  assert.equal(out.length, 0);
+});
+
+test("rejects invalid credit and bulkCapacity", () => {
+  assert.throws(() => new QosScheduler({ sink: () => {}, credit: -1 }), RangeError);
+  assert.throws(() => new QosScheduler({ sink: () => {}, bulkCapacity: 0 }), RangeError);
+  // Unsafe integers lose precision under credit arithmetic, so they are rejected too.
+  assert.throws(() => new QosScheduler({ sink: () => {}, credit: Number.MAX_SAFE_INTEGER + 1 }), RangeError);
+  const s = new QosScheduler({ sink: () => {} });
+  assert.throws(() => s.grantCredit(-1), RangeError);
+  assert.throws(() => s.grantCredit(Number.MAX_SAFE_INTEGER + 1), RangeError);
+});
+
+test("rejects credit that overflows the safe-integer range under accumulation", () => {
+  // Each grant is individually safe, but the running total must not silently
+  // exceed Number.MAX_SAFE_INTEGER and lose precision — grantCredit fails fast.
+  const s = new QosScheduler({ sink: () => {}, credit: Number.MAX_SAFE_INTEGER });
+  assert.throws(() => s.grantCredit(1), RangeError);
+  assert.equal(s.credit, Number.MAX_SAFE_INTEGER, "credit is left untouched on overflow");
+});