@remnic/core 1.1.12 → 1.1.13

package/src/buffer-session.test.ts

@@ -0,0 +1,443 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { SmartBuffer } from "./buffer.js";
+import { parseConfig } from "./config.js";
+import type { BufferState, BufferTurn } from "./types.js";
+
+class FakeStorage {
+  public saved: BufferState | null = null;
+
+  constructor(private readonly initial: BufferState) {}
+
+  async loadBuffer(): Promise<BufferState> {
+    return structuredClone(this.initial);
+  }
+
+  async saveBuffer(state: BufferState): Promise<void> {
+    this.saved = structuredClone(state);
+  }
+}
+
+class DelayedBufferStorage {
+  public saved: BufferState | null = null;
+
+  async loadBuffer(): Promise<BufferState> {
+    await delay(10);
+    return structuredClone(this.saved ?? {
+      turns: [],
+      lastExtractionAt: null,
+      extractionCount: 0,
+    });
+  }
+
+  async saveBuffer(state: BufferState): Promise<void> {
+    await delay(10);
+    this.saved = structuredClone(state);
+  }
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function makeTurn(sessionKey: string, content: string): BufferTurn {
+  return {
+    role: "user",
+    content,
+    timestamp: "2026-04-12T12:00:00.000Z",
+    sessionKey,
+  };
+}
+
+test("SmartBuffer keeps logical session buffers isolated", async () => {
+  const storage = new FakeStorage({
+    turns: [],
+    lastExtractionAt: null,
+    extractionCount: 0,
+  });
+  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "alpha memory"));
+  await buffer.addTurn("thread-b", makeTurn("thread-b", "beta memory"));
+
+  assert.equal(buffer.getTurns("thread-a").length, 1);
+  assert.equal(buffer.getTurns("thread-a")[0]?.content, "alpha memory");
+  assert.equal(buffer.getTurns("thread-b").length, 1);
+  assert.equal(buffer.getTurns("thread-b")[0]?.content, "beta memory");
+});
+
+test("SmartBuffer serializes concurrent addTurn mutations", async () => {
+  const storage = new DelayedBufferStorage();
+  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+
+  await Promise.all([
+    buffer.addTurn("thread-a", makeTurn("thread-a", "alpha memory")),
+    buffer.addTurn("thread-a", makeTurn("thread-a", "beta memory")),
+  ]);
+
+  const turns = storage.saved?.entries?.["thread-a"]?.turns ?? [];
+  assert.equal(turns.length, 2);
+  assert.deepEqual(
+    turns.map((turn) => turn.content).sort(),
+    ["alpha memory", "beta memory"],
+  );
+});
+
+test("SmartBuffer clearAfterExtraction only clears the targeted logical session", async () => {
+  const storage = new FakeStorage({
+    turns: [],
+    lastExtractionAt: null,
+    extractionCount: 0,
+  });
+  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "alpha memory"));
+  await buffer.addTurn("thread-b", makeTurn("thread-b", "beta memory"));
+  await buffer.clearAfterExtraction("thread-a");
+
+  assert.equal(buffer.getTurns("thread-a").length, 0);
+  assert.equal(buffer.getTurns("thread-b").length, 1);
+  assert.equal(buffer.getExtractionCount("thread-a"), 1);
+  assert.equal(buffer.getExtractionCount("thread-b"), 0);
+});
+
+test("SmartBuffer clearAfterExtraction preserves appends after queued snapshots", async () => {
+  const storage = new FakeStorage({
+    turns: [],
+    lastExtractionAt: null,
+    extractionCount: 0,
+  });
+  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "first memory"));
+  const firstSnapshot = buffer.getTurns("thread-a");
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "second memory"));
+  const overlappingSnapshot = buffer.getTurns("thread-a");
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "third memory"));
+
+  await buffer.clearAfterExtraction("thread-a", firstSnapshot);
+  assert.deepEqual(
+    buffer.getTurns("thread-a").map((turn) => turn.content),
+    ["second memory", "third memory"],
+  );
+
+  await buffer.clearAfterExtraction("thread-a", overlappingSnapshot);
+  assert.deepEqual(
+    buffer.getTurns("thread-a").map((turn) => turn.content),
+    ["third memory"],
+  );
+});
+
+test("SmartBuffer clearAfterExtraction chooses the longest queued snapshot overlap", async () => {
+  const storage = new FakeStorage({
+    turns: [],
+    lastExtractionAt: null,
+    extractionCount: 0,
+  });
+  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "repeat"));
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "middle"));
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "repeat"));
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "tail"));
+  const fullSnapshot = buffer.getTurns("thread-a");
+
+  await buffer.clearAfterExtraction("thread-a", fullSnapshot.slice(0, 2));
+  assert.deepEqual(
+    buffer.getTurns("thread-a").map((turn) => turn.content),
+    ["repeat", "tail"],
+  );
+
+  await buffer.clearAfterExtraction("thread-a", fullSnapshot);
+  assert.deepEqual(buffer.getTurns("thread-a"), []);
+});
+
+test("SmartBuffer clearAfterExtraction clears live copies of retained snapshots", async () => {
+  const storage = new FakeStorage({
+    turns: [],
+    lastExtractionAt: null,
+    extractionCount: 0,
+  });
+  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "first memory"));
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "second memory"));
+  const extractionSnapshot = buffer.getTurns("thread-a");
+
+  await buffer.retainDeferredTurns("thread-a", extractionSnapshot, 2);
+  await buffer.clearAfterExtraction("thread-a", extractionSnapshot);
+
+  assert.deepEqual(
+    buffer.getTurns("thread-a").map((turn) => turn.content),
+    ["first memory", "second memory"],
+  );
+  assert.equal(
+    storage.saved?.entries?.["thread-a"]?.turns.length,
+    0,
+    "live turns must be cleared even when retained copies are preserved",
+  );
+});
+
+test("SmartBuffer read-only accessors do not persist phantom entries for unknown buffers", async () => {
+  const storage = new FakeStorage({
+    turns: [],
+    lastExtractionAt: null,
+    extractionCount: 0,
+  });
+  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+
+  assert.deepEqual(buffer.getTurns("missing-thread"), []);
+  assert.equal(buffer.getExtractionCount("missing-thread"), 0);
+
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "alpha memory"));
+
+  assert.ok(storage.saved);
+  assert.deepEqual(Object.keys(storage.saved?.entries ?? {}).sort(), ["default", "thread-a"]);
+});
+
+test("SmartBuffer can recover a logical buffer key from a raw session key", async () => {
+  const storage = new FakeStorage({
+    turns: [],
+    lastExtractionAt: null,
+    extractionCount: 0,
+    entries: {
+      default: {
+        turns: [],
+        lastExtractionAt: null,
+        extractionCount: 0,
+      },
+      "codex-thread:thread-22::principal:cli": {
+        turns: [
+          {
+            ...makeTurn("session-z", "gamma memory"),
+            logicalSessionKey: "codex-thread:thread-22",
+          },
+        ],
+        lastExtractionAt: null,
+        extractionCount: 0,
+      },
+    },
+  });
+  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+
+  const resolved = await buffer.findBufferKeyForSession("session-z");
+
+  assert.equal(resolved, "codex-thread:thread-22::principal:cli");
+});
+
+test("SmartBuffer finds every buffer key that still carries turns for a session", async () => {
+  const storage = new FakeStorage({
+    turns: [],
+    lastExtractionAt: null,
+    extractionCount: 0,
+    entries: {
+      default: {
+        turns: [],
+        lastExtractionAt: null,
+        extractionCount: 0,
+      },
+      "session-z": {
+        turns: [makeTurn("session-z", "raw memory")],
+        lastExtractionAt: null,
+        extractionCount: 0,
+      },
+      "codex-thread:thread-22::principal:cli": {
+        turns: [
+          {
+            ...makeTurn("session-z", "logical memory"),
+            logicalSessionKey: "codex-thread:thread-22",
+          },
+        ],
+        lastExtractionAt: null,
+        extractionCount: 0,
+      },
+    },
+  });
+  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+
+  const resolved = await buffer.findBufferKeysForSession("session-z");
+
+  assert.deepEqual(resolved, [
+    "session-z",
+    "codex-thread:thread-22::principal:cli",
+  ]);
+});
+
+test("SmartBuffer prunes stale logical session buffers to a bounded entry set", async () => {
+  const entries = Object.fromEntries(
+    Array.from({ length: 205 }, (_, index) => [
+      `thread-${index}`,
+      {
+        turns: [],
+        lastExtractionAt: null,
+        extractionCount: 0,
+      },
+    ]),
+  );
+  const storage = new FakeStorage({
+    turns: [],
+    lastExtractionAt: null,
+    extractionCount: 0,
+    entries: {
+      default: {
+        turns: [],
+        lastExtractionAt: null,
+        extractionCount: 0,
+      },
+      ...entries,
+    },
+  });
+  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+
+  await buffer.addTurn("active-thread", makeTurn("active-thread", "pending memory"));
+
+  const persistedKeys = Object.keys(storage.saved?.entries ?? {});
+  assert.equal(persistedKeys.length, 200);
+  assert.ok(persistedKeys.includes("default"));
+  assert.ok(persistedKeys.includes("active-thread"));
+  assert.ok(persistedKeys.includes("thread-204"));
+  assert.ok(!persistedKeys.includes("thread-0"));
+});
+
+// ---------------------------------------------------------------------------
+// Issue #562 PR 2 — defer retention
+// ---------------------------------------------------------------------------
+
+test("retainDeferredTurns preserves turns across clearAfterExtraction", async () => {
+  const storage = new FakeStorage({
+    turns: [],
+    lastExtractionAt: null,
+    extractionCount: 0,
+  });
+  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "deferred context one"));
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "deferred context two"));
+
+  const liveTurns = buffer.getTurns("thread-a");
+  assert.equal(liveTurns.length, 2);
+
+  await buffer.retainDeferredTurns("thread-a", liveTurns);
+  await buffer.clearAfterExtraction("thread-a");
+
+  const afterClear = buffer.getTurns("thread-a");
+  assert.equal(afterClear.length, 2, "Retained turns must survive clearAfterExtraction");
+  assert.equal(afterClear[0]?.content, "deferred context one");
+  assert.equal(afterClear[1]?.content, "deferred context two");
+});
+
+test("retainDeferredTurns respects the max tail size", async () => {
+  const storage = new FakeStorage({
+    turns: [],
+    lastExtractionAt: null,
+    extractionCount: 0,
+  });
+  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+
+  const turns = Array.from({ length: 5 }, (_, i) =>
+    makeTurn("thread-a", `turn ${i}`),
+  );
+
+  await buffer.retainDeferredTurns("thread-a", turns, 2);
+  const retained = buffer.getRetainedDeferredTurns("thread-a");
+  assert.equal(retained.length, 2);
+  assert.equal(retained[0]?.content, "turn 3");
+  assert.equal(retained[1]?.content, "turn 4");
+});
+
+test("retainDeferredTurns with empty array clears the retention slot", async () => {
+  const storage = new FakeStorage({
+    turns: [],
+    lastExtractionAt: null,
+    extractionCount: 0,
+  });
+  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+
+  await buffer.retainDeferredTurns("thread-a", [makeTurn("thread-a", "x")], 5);
+  assert.equal(buffer.getRetainedDeferredTurns("thread-a").length, 1);
+
+  await buffer.retainDeferredTurns("thread-a", []);
+  assert.equal(buffer.getRetainedDeferredTurns("thread-a").length, 0);
+});
+
+test("retainDeferredTurns with max=0 clears the retention slot (slice -0 guard)", async () => {
+  // CLAUDE.md gotcha 27: `slice(-0)` equals `slice(0)` and would return all
+  // entries. The implementation must guard against this.
+  const storage = new FakeStorage({
+    turns: [],
+    lastExtractionAt: null,
+    extractionCount: 0,
+  });
+  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+
+  await buffer.retainDeferredTurns("thread-a", [makeTurn("thread-a", "x")], 5);
+  assert.equal(buffer.getRetainedDeferredTurns("thread-a").length, 1);
+
+  await buffer.retainDeferredTurns(
+    "thread-a",
+    [makeTurn("thread-a", "should-not-appear")],
+    0,
+  );
+  assert.equal(
+    buffer.getRetainedDeferredTurns("thread-a").length,
+    0,
+    "max=0 must clear the slot, not return all turns",
+  );
+});
+
+test("getTurns prepends retained deferred turns before live turns", async () => {
+  const storage = new FakeStorage({
+    turns: [],
+    lastExtractionAt: null,
+    extractionCount: 0,
+  });
+  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+
+  await buffer.retainDeferredTurns(
+    "thread-a",
+    [makeTurn("thread-a", "old deferred context")],
+    10,
+  );
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "new live turn"));
+
+  const all = buffer.getTurns("thread-a");
+  assert.equal(all.length, 2);
+  assert.equal(all[0]?.content, "old deferred context");
+  assert.equal(all[1]?.content, "new live turn");
+});
+
+test("SmartBuffer never prunes logical session buffers that still have pending turns", async () => {
+  const entries = Object.fromEntries(
+    Array.from({ length: 205 }, (_, index) => [
+      `thread-${index}`,
+      {
+        turns: [makeTurn(`thread-${index}`, `memory ${index}`)],
+        lastExtractionAt: null,
+        extractionCount: 0,
+      },
+    ]),
+  );
+  const storage = new FakeStorage({
+    turns: [],
+    lastExtractionAt: null,
+    extractionCount: 0,
+    entries: {
+      default: {
+        turns: [],
+        lastExtractionAt: null,
+        extractionCount: 0,
+      },
+      ...entries,
+    },
+  });
+  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+
+  await buffer.addTurn("active-thread", makeTurn("active-thread", "pending memory"));
+
+  const persistedKeys = Object.keys(storage.saved?.entries ?? {});
+  assert.equal(persistedKeys.length, 207);
+  assert.ok(persistedKeys.includes("default"));
+  assert.ok(persistedKeys.includes("active-thread"));
+  assert.ok(persistedKeys.includes("thread-0"));
+  assert.ok(persistedKeys.includes("thread-204"));
+});

package/src/buffer-surprise-report.ts

@@ -0,0 +1,176 @@
+/**
+ * Buffer-surprise telemetry report (issue #563 PR 3).
+ *
+ * Reads the append-only `state/buffer-surprise-ledger.jsonl` file written
+ * by `SmartBuffer` and summarizes the recent distribution of surprise
+ * scores for the Doctor surface. This module is intentionally standalone
+ * and pure — the only I/O is reading the ledger via the injected
+ * `readEvents` callback, so it can be exercised directly in tests
+ * without touching the filesystem.
+ *
+ * # Output shape
+ *
+ * `BufferSurpriseDistribution` has fields sized for a one-screen Doctor
+ * display:
+ *
+ *   - `count`            — rows considered in the summary window.
+ *   - `triggeredCount`   — rows whose `triggeredFlush === true`.
+ *   - `triggeredRate`    — `triggeredCount / count`, or `0` when empty.
+ *   - `mean`             — arithmetic mean of `surpriseScore`.
+ *   - `median`           — middle value (50th percentile).
+ *   - `p90`              — 90th percentile (tail of novelty).
+ *   - `min`, `max`       — window extremes.
+ *   - `currentThreshold` — threshold from the MOST RECENT row, or `null`.
+ *
+ * All percentile math uses the nearest-rank method (no interpolation) so
+ * the report is stable across small windows.
+ *
+ * # Why a pure function + injected reader?
+ *
+ * The Doctor surface is exercised both at runtime (through the CLI and
+ * gateway tools) and in tests. A pure distribution helper fed from an
+ * arbitrary `readEvents` callback keeps the report logic trivially
+ * testable without spinning up a real `StorageManager`.
+ */
+
+import type { BufferSurpriseEvent } from "./types.js";
+
+export interface BufferSurpriseDistribution {
+  count: number;
+  triggeredCount: number;
+  triggeredRate: number;
+  mean: number;
+  median: number;
+  p90: number;
+  min: number;
+  max: number;
+  currentThreshold: number | null;
+}
+
+export interface BufferSurpriseReportOptions {
+  /**
+   * Maximum number of recent rows to include. Defaults to `200` — large
+   * enough to see a distribution, small enough to read in one sitting.
+   */
+  limit?: number;
+  /** Lower-bound ISO timestamp; rows at or before this are excluded. */
+  since?: string;
+}
+
+/**
+ * Reader callback shape. The helper does not want to know whether the
+ * rows come from a file, a queue, or an in-memory buffer.
+ */
+export type BufferSurpriseReader = (
+  options: BufferSurpriseReportOptions,
+) => Promise<readonly BufferSurpriseEvent[]>;
+
+/**
+ * Summarize the recent buffer-surprise distribution. Returns the empty
+ * distribution shape when the ledger has no applicable rows — callers can
+ * detect this via `count === 0` and render "no data yet".
+ */
+export async function reportBufferSurpriseDistribution(
+  readEvents: BufferSurpriseReader,
+  options: BufferSurpriseReportOptions = {},
+): Promise<BufferSurpriseDistribution> {
+  const limit = normalizeReportLimit(options.limit);
+  const raw = await readEvents({ limit, since: options.since });
+
+  // Filter for sanity: finite numeric scores in [0, 1], event tag match,
+  // and the optional `since` lower bound. Malformed rows are skipped.
+  const sinceMs =
+    typeof options.since === "string" && options.since.length > 0
+      ? Date.parse(options.since)
+      : Number.NaN;
+  const rows = raw.filter((row): row is BufferSurpriseEvent => {
+    if (!row || row.event !== "BUFFER_SURPRISE") return false;
+    const ts = Date.parse(row.timestamp);
+    if (!Number.isFinite(ts)) return false;
+    if (typeof row.surpriseScore !== "number") return false;
+    if (!Number.isFinite(row.surpriseScore)) return false;
+    if (row.surpriseScore < 0 || row.surpriseScore > 1) return false;
+    // `triggeredFlush` must be a real boolean — not a string or other
+    // truthy value. A row with `triggeredFlush: "false"` (string from a
+    // JSON-parsing bug upstream) would otherwise be counted as
+    // triggered, inflating the rate and misleading operators tuning the
+    // threshold from real traffic.
+    if (typeof row.triggeredFlush !== "boolean") return false;
+    if (Number.isFinite(sinceMs)) {
+      if (!Number.isFinite(ts) || ts <= sinceMs) return false;
+    }
+    return true;
+  }).sort((left, right) => Date.parse(left.timestamp) - Date.parse(right.timestamp));
+
+  const windowStart = Math.max(0, rows.length - limit);
+  const windowRows = rows.slice(windowStart);
+
+  if (windowRows.length === 0) {
+    return {
+      count: 0,
+      triggeredCount: 0,
+      triggeredRate: 0,
+      mean: 0,
+      median: 0,
+      p90: 0,
+      min: 0,
+      max: 0,
+      currentThreshold: null,
+    };
+  }
+
+  const scores = windowRows.map((r) => r.surpriseScore).sort((a, b) => a - b);
+  const triggeredCount = windowRows.reduce(
+    (acc, r) => acc + (r.triggeredFlush ? 1 : 0),
+    0,
+  );
+  const sum = scores.reduce((acc, v) => acc + v, 0);
+  const mean = sum / scores.length;
+
+  // Nearest-rank percentiles keep the output stable for small windows.
+  const median = percentile(scores, 0.5);
+  const p90 = percentile(scores, 0.9);
+
+  // "Current" threshold is whichever was in force for the most recent row
+  // — not necessarily the one configured right now, but the value the
+  // ledger rows were judged against. That's what operators need to reason
+  // about the distribution.
+  const mostRecent = windowRows[windowRows.length - 1];
+  const currentThreshold =
+    mostRecent && typeof mostRecent.threshold === "number"
+      ? mostRecent.threshold
+      : null;
+
+  return {
+    count: scores.length,
+    triggeredCount,
+    triggeredRate: triggeredCount / scores.length,
+    mean,
+    median,
+    p90,
+    min: scores[0]!,
+    max: scores[scores.length - 1]!,
+    currentThreshold,
+  };
+}
+
+function normalizeReportLimit(limit: number | undefined): number {
+  if (limit === undefined) return 200;
+  if (typeof limit !== "number" || !Number.isFinite(limit)) return 200;
+  const floored = Math.floor(limit);
+  return floored > 0 ? floored : 200;
+}
+
+/**
+ * Nearest-rank percentile of a pre-sorted ascending array.
+ *
+ * Returns `sorted[ceil(p * n) - 1]`, with `p` clamped to `[0, 1]`.
+ * This avoids the interpolation ambiguity of R-7/R-8 percentiles and is
+ * stable when the window is small (e.g. 3-5 rows).
+ */
+function percentile(sorted: readonly number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  const clamped = Math.max(0, Math.min(1, p));
+  const rank = Math.max(1, Math.ceil(clamped * sorted.length));
+  return sorted[rank - 1]!;
+}