@remnic/core 9.7.15 → 9.8.0

package/src/active-recall.test.ts

@@ -21,6 +21,7 @@ function baseConfig(overrides: Partial<ActiveRecallConfig> = {}): ActiveRecallCo
     queryMode: "recent",
     promptStyle: "balanced",
     customInstruction: null,
+    promptReplacement: null,
     promptAppend: null,
     maxSummaryChars: 64,
     recentUserTurns: 2,
@@ -130,6 +131,40 @@ test("buildActiveRecallPrompt varies by prompt style and optional sections", ()
   assert.match(prompt, /Prefer hard evidence/);
 });
 
+test("buildActiveRecallPrompt treats prompt replacement as a complete replacement", () => {
+  const prompt = buildActiveRecallPrompt({
+    config: baseConfig({
+      customInstruction: "ignored custom instruction",
+      promptReplacement: "Use only the supplied evidence.",
+      promptAppend: "ignored append",
+    }),
+    queryBundle: "current: What happened?",
+    recallContext: "The deploy was rolled back.",
+    graphContext: ["entity edge"],
+    causalContext: ["causal link"],
+    daySummary: "Debugged worker drain all morning.",
+    recallExplain: "graph_mode",
+  });
+  assert.equal(prompt, "Use only the supplied evidence.");
+});
+
+test("buildActiveRecallPrompt gives replacement precedence over legacy custom instruction", () => {
+  const prompt = buildActiveRecallPrompt({
+    config: baseConfig({
+      customInstruction: "legacy guidance",
+      promptReplacement: "Use only the supplied evidence.",
+    }),
+    queryBundle: "current: What happened?",
+    recallContext: "The deploy was rolled back.",
+    graphContext: [],
+    causalContext: [],
+    daySummary: null,
+    recallExplain: null,
+  });
+
+  assert.equal(prompt, "Use only the supplied evidence.");
+});
+
 test("normalizeActiveRecallSummary collapses NONE variants and truncates codepoint-safe", () => {
   assert.equal(normalizeActiveRecallSummary("NONE", 20), null);
   assert.equal(normalizeActiveRecallSummary("  no relevant memory  ", 20), null);

package/src/active-recall.ts

@@ -30,6 +30,7 @@ export interface ActiveRecallConfig {
   queryMode: ActiveRecallQueryMode;
   promptStyle: ActiveRecallPromptStyle;
   customInstruction: string | null;
+  promptReplacement: string | null;
   promptAppend: string | null;
   maxSummaryChars: number;
   recentUserTurns: number;
@@ -133,6 +134,7 @@ function buildCacheKey(input: ActiveRecallInput, config: ActiveRecallConfig, que
     queryMode: config.queryMode,
     promptStyle: config.promptStyle,
     customInstruction: config.customInstruction,
+    promptReplacement: config.promptReplacement,
     promptAppend: config.promptAppend,
     maxSummaryChars: config.maxSummaryChars,
     entityGraphDepth: config.entityGraphDepth,
@@ -262,6 +264,11 @@ export function buildActiveRecallPrompt(params: {
   daySummary: string | null;
   recallExplain: string | null;
 }): string {
+  const promptReplacement = params.config.promptReplacement?.trim();
+  if (promptReplacement) {
+    return promptReplacement;
+  }
+
   const sections = [
     params.config.customInstruction?.trim() || STYLE_INSTRUCTIONS[params.config.promptStyle],
     `Query bundle:\n${params.queryBundle}`,

package/src/bounded-jsonl-state.ts

@@ -0,0 +1,93 @@
+/**
+ * Bounded JSONL state configuration (issue #1910).
+ *
+ * Extracted from `config.ts`/`types.ts` so the god-file line-count ratchets
+ * (issue #1995) do not grow: `PluginConfig` extends the interface below and
+ * `parseConfig` spreads `parseBoundedJsonlStateConfig`. No behavior change —
+ * the knobs, defaults, and coercion rules are identical to the inline forms.
+ */
+
+/** Knobs that bound the unbounded JSONL state files (issue #1910). */
+export interface BoundedJsonlStateConfig {
+  /**
+   * Auto-compact `state/memory-lifecycle-ledger.jsonl` when it exceeds this many
+   * bytes, triggered off the debounced maintenance path. `0` disables. Default
+   * 64MB.
+   */
+  memoryLifecycleLedgerCompactBytes: number;
+  /**
+   * Minimum interval between auto-compactions of the lifecycle ledger, so a
+   * heavy rebuild cannot run back-to-back. Floored at 60s. Default 6h.
+   */
+  memoryLifecycleLedgerCompactMinIntervalMs: number;
+  /**
+   * Rotate `state/recall_impressions.jsonl` to `.1..N` when it exceeds this many
+   * bytes. `0` disables. Default 32MB.
+   */
+  recallImpressionsRotateBytes: number;
+  /**
+   * Number of rotated recall-impression archives to keep (`.1 .. .N`). Floored
+   * at 1 when rotation is enabled. Default 5.
+   */
+  recallImpressionsRotateKeep: number;
+}
+
+/** Integer coercion contract shared with `config.ts` (`parseIntegerAtLeast`). */
+type IntegerParser = (value: unknown, fallback: number, min: number, keyName: string) => number;
+
+/**
+ * Upper bound for `recallImpressionsRotateKeep`. Each retained slot costs one
+ * rename under the held cross-process impressions lock on every rotation, so an
+ * accidentally huge value (a `1000000` typo) would stall recall recording and
+ * block other writers. 1000 archives is already far past any real retention
+ * need; a larger request is REJECTED before it reaches the rotation loop (#2033).
+ */
+export const RECALL_IMPRESSIONS_ROTATE_KEEP_MAX = 1000;
+
+/**
+ * Parse the bounded-state knobs. Numeric knobs accept CLI/overlay string forms
+ * (Gotcha #28) via `coerceNumber`, then require an integer >= min. A
+ * present-but-malformed or fractional value is REJECTED (throws) rather than
+ * silently taking the default; only an absent value falls back. `0` survives
+ * when `min` is 0, so the documented disable stays effective on every surface
+ * (byte thresholds floor at 0, the min-interval at 60s, and the keep count at 1
+ * so rotation always retains at least one archive).
+ */
+export function parseBoundedJsonlStateConfig(
+  cfg: Record<string, unknown>,
+  parseIntegerAtLeast: IntegerParser,
+): BoundedJsonlStateConfig {
+  const recallImpressionsRotateKeep = parseIntegerAtLeast(
+    cfg.recallImpressionsRotateKeep,
+    5,
+    1,
+    "recallImpressionsRotateKeep",
+  );
+  if (recallImpressionsRotateKeep > RECALL_IMPRESSIONS_ROTATE_KEEP_MAX) {
+    throw new Error(
+      `recallImpressionsRotateKeep must be an integer between 1 and `
+      + `${RECALL_IMPRESSIONS_ROTATE_KEEP_MAX}; got ${JSON.stringify(cfg.recallImpressionsRotateKeep)}`,
+    );
+  }
+  return {
+    memoryLifecycleLedgerCompactBytes: parseIntegerAtLeast(
+      cfg.memoryLifecycleLedgerCompactBytes,
+      64 * 1024 * 1024,
+      0,
+      "memoryLifecycleLedgerCompactBytes",
+    ),
+    memoryLifecycleLedgerCompactMinIntervalMs: parseIntegerAtLeast(
+      cfg.memoryLifecycleLedgerCompactMinIntervalMs,
+      6 * 60 * 60 * 1000,
+      60_000,
+      "memoryLifecycleLedgerCompactMinIntervalMs",
+    ),
+    recallImpressionsRotateBytes: parseIntegerAtLeast(
+      cfg.recallImpressionsRotateBytes,
+      32 * 1024 * 1024,
+      0,
+      "recallImpressionsRotateBytes",
+    ),
+    recallImpressionsRotateKeep,
+  };
+}

package/src/buffer-session.test.ts

@@ -7,6 +7,7 @@ import type { BufferState, BufferTurn } from "./types.js";
 
 class FakeStorage {
   public saved: BufferState | null = null;
+  public saveCount = 0;
 
   constructor(private readonly initial: BufferState) {}
 
@@ -15,6 +16,7 @@ class FakeStorage {
   }
 
   async saveBuffer(state: BufferState): Promise<void> {
+    this.saveCount += 1;
     this.saved = structuredClone(state);
   }
 }
@@ -97,7 +99,7 @@ test("SmartBuffer keeps dangerous keys isolated from safe-prefix lookalikes", as
 
 test("SmartBuffer serializes concurrent addTurn mutations", async () => {
   const storage = new DelayedBufferStorage();
-  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+  const buffer = new SmartBuffer(parseConfig({ bufferSaveDebounceMs: 0 }), storage as unknown as ConstructorParameters<typeof SmartBuffer>[1]);
 
   await Promise.all([
     buffer.addTurn("thread-a", makeTurn("thread-a", "alpha memory")),
@@ -270,7 +272,7 @@ test("SmartBuffer read-only accessors do not persist phantom entries for unknown
     lastExtractionAt: null,
     extractionCount: 0,
   });
-  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+  const buffer = new SmartBuffer(parseConfig({ bufferSaveDebounceMs: 0 }), storage as unknown as ConstructorParameters<typeof SmartBuffer>[1]);
 
   assert.deepEqual(buffer.getTurns("missing-thread"), []);
   assert.equal(buffer.getExtractionCount("missing-thread"), 0);
@@ -373,7 +375,7 @@ test("SmartBuffer prunes stale logical session buffers to a bounded entry set",
       ...entries,
     },
   });
-  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+  const buffer = new SmartBuffer(parseConfig({ bufferSaveDebounceMs: 0 }), storage as unknown as ConstructorParameters<typeof SmartBuffer>[1]);
 
   await buffer.addTurn("active-thread", makeTurn("active-thread", "pending memory"));
 
@@ -522,7 +524,7 @@ test("SmartBuffer prefers pruning empty entries and bounds pending-turn buffers
       ...entries,
     },
   });
-  const buffer = new SmartBuffer(parseConfig({}), storage as unknown as ConstructorParameters<typeof SmartBuffer>[1]);
+  const buffer = new SmartBuffer(parseConfig({ bufferSaveDebounceMs: 0 }), storage as unknown as ConstructorParameters<typeof SmartBuffer>[1]);
 
   await buffer.addTurn("active-thread", makeTurn("active-thread", "pending memory"));
 
@@ -549,7 +551,7 @@ test("pruneEntries evicts oldest NON-empty session entries past the cap (#1908 r
     };
   }
   const storage = new FakeStorage({ turns: [], lastExtractionAt: null, extractionCount: 0, entries });
-  const buffer = new SmartBuffer(parseConfig({}), storage as unknown as ConstructorParameters<typeof SmartBuffer>[1]);
+  const buffer = new SmartBuffer(parseConfig({ bufferSaveDebounceMs: 0 }), storage as unknown as ConstructorParameters<typeof SmartBuffer>[1]);
   await buffer.load();
   await buffer.addTurn("session-newest", makeTurn("session-newest", "new turn"));
 
@@ -559,3 +561,418 @@ test("pruneEntries evicts oldest NON-empty session entries past the cap (#1908 r
   assert.equal(buffer.getTurns("session-000").length, 0, "oldest non-empty entry was evicted");
   assert.ok(buffer.getTurns("session-209").length > 0, "newest pre-existing entry survives");
 });
+
+// ---------------------------------------------------------------------------
+// Issue #1909 (Part D) — debounced buffer save
+// ---------------------------------------------------------------------------
+
+function emptyBufferState(): BufferState {
+  return { turns: [], lastExtractionAt: null, extractionCount: 0 };
+}
+
+interface DebouncedBufferInternals {
+  saveTimer: NodeJS.Timeout | null;
+  pendingSave: boolean;
+}
+
+test("debounce on: N keep_buffering turns coalesce into one save on flush", async () => {
+  const storage = new FakeStorage(emptyBufferState());
+  // Large window + high turn cap so every turn keeps buffering (no trigger).
+  const buffer = new SmartBuffer(
+    parseConfig({ bufferSaveDebounceMs: 10_000, triggerMode: "smart", bufferMaxTurns: 100 }),
+    storage as unknown as ConstructorParameters<typeof SmartBuffer>[1],
+  );
+
+  for (let i = 0; i < 5; i += 1) {
+    const decision = await buffer.addTurn("thread-a", makeTurn("thread-a", `turn ${i}`));
+    assert.equal(decision, "keep_buffering");
+  }
+  assert.equal(storage.saveCount, 0, "steady-state buffering does zero full serializations");
+
+  await buffer.flushPendingSave();
+  assert.equal(storage.saveCount, 1, "the trailing-edge flush writes exactly once");
+  assert.equal(storage.saved?.entries?.["thread-a"]?.turns.length, 5, "flush persists all buffered turns");
+
+  // Idempotent: a second flush with nothing pending does not write again.
+  await buffer.flushPendingSave();
+  assert.equal(storage.saveCount, 1, "flushPendingSave is idempotent");
+});
+
+test("debounce on: an extraction-triggering turn forces an immediate save", async () => {
+  const storage = new FakeStorage(emptyBufferState());
+  const buffer = new SmartBuffer(
+    parseConfig({ bufferSaveDebounceMs: 10_000, triggerMode: "smart", bufferMaxTurns: 1 }),
+    storage as unknown as ConstructorParameters<typeof SmartBuffer>[1],
+  );
+
+  const decision = await buffer.addTurn("thread-a", makeTurn("thread-a", "trigger"));
+  assert.notEqual(decision, "keep_buffering", "the turn triggers extraction");
+  assert.equal(storage.saveCount, 1, "the triggering turn is durable immediately, not on the debounce edge");
+  assert.equal(storage.saved?.entries?.["thread-a"]?.turns.length, 1);
+});
+
+test("debounce on: clearAfterExtraction cancels the pending timer and persists post-clear state", async () => {
+  const storage = new FakeStorage(emptyBufferState());
+  const buffer = new SmartBuffer(
+    parseConfig({ bufferSaveDebounceMs: 10_000, triggerMode: "smart", bufferMaxTurns: 100 }),
+    storage as unknown as ConstructorParameters<typeof SmartBuffer>[1],
+  );
+
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "buffered turn"));
+  assert.equal(storage.saveCount, 0, "the buffered turn's save is still pending on the timer");
+
+  await buffer.clearAfterExtraction("thread-a");
+  assert.equal(storage.saveCount, 1, "clearAfterExtraction persists exactly once (post-clear state)");
+  assert.equal(storage.saved?.entries?.["thread-a"]?.turns.length, 0, "the persisted state is cleared");
+
+  // The pending debounce timer was cancelled — it must not fire a stale write.
+  const internals = buffer as unknown as DebouncedBufferInternals;
+  assert.equal(internals.saveTimer, null, "no armed timer remains after clear");
+  assert.equal(internals.pendingSave, false, "no pending save remains after clear");
+});
+
+test("debounce off (bufferSaveDebounceMs: 0) reproduces save-every-turn", async () => {
+  const storage = new FakeStorage(emptyBufferState());
+  const buffer = new SmartBuffer(
+    parseConfig({ bufferSaveDebounceMs: 0, triggerMode: "smart", bufferMaxTurns: 100 }),
+    storage as unknown as ConstructorParameters<typeof SmartBuffer>[1],
+  );
+
+  for (let i = 0; i < 4; i += 1) {
+    await buffer.addTurn("thread-a", makeTurn("thread-a", `turn ${i}`));
+  }
+  assert.equal(storage.saveCount, 4, "with debounce disabled every turn saves immediately");
+  assert.equal(storage.saved?.entries?.["thread-a"]?.turns.length, 4);
+});
+
+test("parseConfig validates bufferSaveDebounceMs (accepts valid, defaults undefined)", () => {
+  assert.equal(parseConfig({}).bufferSaveDebounceMs, 3_000, "undefined → default 3000ms");
+  assert.equal(parseConfig({ bufferSaveDebounceMs: 0 }).bufferSaveDebounceMs, 0, "0 = save every turn");
+  assert.equal(parseConfig({ bufferSaveDebounceMs: 5_000 }).bufferSaveDebounceMs, 5_000);
+  assert.equal(
+    parseConfig({ bufferSaveDebounceMs: 2_147_483_647 }).bufferSaveDebounceMs,
+    2_147_483_647,
+    "max (32-bit setTimeout limit) accepted",
+  );
+  // CLI numeric strings coerce, then validate.
+  assert.equal(parseConfig({ bufferSaveDebounceMs: "5000" }).bufferSaveDebounceMs, 5_000, "numeric string coerces");
+});
+
+test("debounce on: each turn re-arms the trailing edge (save fires one window after the LAST turn)", async (t) => {
+  t.mock.timers.enable({ apis: ["setTimeout", "Date"], now: 0 });
+  const storage = new FakeStorage(emptyBufferState());
+  const buffer = new SmartBuffer(
+    parseConfig({ bufferSaveDebounceMs: 100, triggerMode: "smart", bufferMaxTurns: 10_000 }),
+    storage as unknown as ConstructorParameters<typeof SmartBuffer>[1],
+  );
+  const settle = () => new Promise<void>((resolve) => setImmediate(resolve));
+
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "turn 0")); // schedules save at t=100
+  t.mock.timers.tick(90); // t=90, before the first window closes
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "turn 1")); // re-arms to t=190
+  t.mock.timers.tick(90); // t=180 — the ORIGINAL 100ms deadline is past
+  await settle();
+  assert.equal(storage.saveCount, 0, "re-arm pushed the deadline; no save at the original window");
+
+  t.mock.timers.tick(20); // t=200 — 110ms after the last turn (past the re-armed 190)
+  await settle();
+  assert.equal(storage.saveCount, 1, "the save fires one window after the LAST turn (true trailing edge)");
+  assert.equal(storage.saved?.entries?.["thread-a"]?.turns.length, 2);
+});
+
+test("debounce on: sustained activity forces an inline save at the 5x staleness cap", async (t) => {
+  t.mock.timers.enable({ apis: ["setTimeout", "Date"], now: 0 });
+  const storage = new FakeStorage(emptyBufferState());
+  // Window 100ms → cap at 5x = 500ms of continuously-deferred pending state.
+  const buffer = new SmartBuffer(
+    parseConfig({ bufferSaveDebounceMs: 100, triggerMode: "smart", bufferMaxTurns: 10_000 }),
+    storage as unknown as ConstructorParameters<typeof SmartBuffer>[1],
+  );
+
+  // Add a turn every 80ms (< window) so the trailing-edge timer never fires —
+  // each turn re-arms it. The pending save is deferred continuously.
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "turn 0")); // firstPendingAt = 0
+  for (let elapsed = 80; elapsed <= 480; elapsed += 80) {
+    t.mock.timers.tick(80);
+    await buffer.addTurn("thread-a", makeTurn("thread-a", `turn @${elapsed}`));
+    assert.equal(storage.saveCount, 0, `still deferred at t=${elapsed} (< 5x window)`);
+  }
+
+  // Next turn crosses t=560 (>= 500ms cap): scheduleSave forces an inline save.
+  t.mock.timers.tick(80); // t=560
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "turn @560"));
+  assert.equal(storage.saveCount, 1, "the 5x staleness cap forced an inline save mid-activity");
+});
+
+class FailOnceBufferStorage {
+  public saved: BufferState | null = null;
+  public saveCount = 0;
+  public failNext = true;
+
+  async loadBuffer(): Promise<BufferState> {
+    return emptyBufferState();
+  }
+
+  async saveBuffer(state: BufferState): Promise<void> {
+    if (this.failNext) {
+      this.failNext = false;
+      throw new Error("simulated buffer write failure");
+    }
+    this.saveCount += 1;
+    this.saved = structuredClone(state);
+  }
+}
+
+test("debounce on: a failed flush keeps the save pending so a retry (or shutdown) persists", async () => {
+  // Issue #1909 review round 2 finding 1: flushPendingSave must not clear
+  // pendingSave until the write SUCCEEDS — otherwise a failed write diverges
+  // memory from disk and a later shutdown flush early-returns, dropping turns.
+  const storage = new FailOnceBufferStorage();
+  const buffer = new SmartBuffer(
+    parseConfig({ bufferSaveDebounceMs: 10_000, triggerMode: "smart", bufferMaxTurns: 10_000 }),
+    storage as unknown as ConstructorParameters<typeof SmartBuffer>[1],
+  );
+
+  await buffer.addTurn("thread-a", makeTurn("thread-a", "buffered turn")); // schedules a save
+  // First flush: the underlying write throws (swallowed, fail-open).
+  await buffer.flushPendingSave();
+  const internals = buffer as unknown as DebouncedBufferInternals;
+  assert.equal(internals.pendingSave, true, "a failed save leaves the save pending for retry");
+  assert.equal(storage.saveCount, 0, "nothing was persisted on the failed attempt");
+
+  // Retry (mirrors the re-armed timer or graceful-shutdown flush) succeeds.
+  await buffer.flushPendingSave();
+  assert.equal(storage.saveCount, 1, "the retry performed exactly one successful write");
+  assert.equal(
+    storage.saved?.entries?.["thread-a"]?.turns.length,
+    1,
+    "the previously-unpersisted turn is now durable",
+  );
+  assert.equal(internals.pendingSave, false, "pending is cleared only after the write succeeds");
+});
+
+test("parseConfig rejects invalid bufferSaveDebounceMs (round 8: throw, do not clamp/floor)", () => {
+  // Review round 8: reject invalid user input explicitly instead of silently
+  // flooring fractions / clamping negatives to 0 / clamping oversized to the
+  // timer max (AGENTS.md #1/#39).
+  const cases: unknown[] = [
+    -1, // negative
+    0.5, // fraction
+    3_000_000_000, // above the 32-bit setTimeout limit
+    Number.NaN,
+    Number.POSITIVE_INFINITY,
+    "abc", // non-numeric string
+    -0.0001,
+    2_147_483_648, // one past max
+    null, // explicit null is invalid (only undefined defaults) — round 9 finding 1
+  ];
+  for (const value of cases) {
+    assert.throws(
+      () => parseConfig({ bufferSaveDebounceMs: value }),
+      /bufferSaveDebounceMs must be an integer in \[0, 2147483647\]/,
+      `expected ${JSON.stringify(value)} to be rejected`,
+    );
+  }
+  // Boundary + coercion: valid inputs pass.
+  assert.equal(parseConfig({ bufferSaveDebounceMs: 0 }).bufferSaveDebounceMs, 0);
+  assert.equal(parseConfig({ bufferSaveDebounceMs: 2_147_483_647 }).bufferSaveDebounceMs, 2_147_483_647);
+  assert.equal(parseConfig({ bufferSaveDebounceMs: "5000" }).bufferSaveDebounceMs, 5_000);
+  assert.equal(parseConfig({}).bufferSaveDebounceMs, 3_000, "undefined → default");
+});
+
+test("debounce cap: the buffer never arms setTimeout above the 32-bit limit", async () => {
+  // Deterministic (no real waiting): capture the delay the buffer passes to
+  // setTimeout. An unclamped value > 2^31-1 is overflow-clamped by Node to 1ms;
+  // the buffer-side Math.min prevents that even when a directly-constructed
+  // config bypassed parseConfig's cap.
+  const config = parseConfig({ triggerMode: "smart", bufferMaxTurns: 10_000 });
+  config.bufferSaveDebounceMs = 3_000_000_000;
+  const storage = new FakeStorage(emptyBufferState());
+  const buffer = new SmartBuffer(
+    config,
+    storage as unknown as ConstructorParameters<typeof SmartBuffer>[1],
+  );
+
+  const timerGlobal = globalThis as unknown as { setTimeout: typeof setTimeout };
+  const realSetTimeout = timerGlobal.setTimeout;
+  const armedDelays: number[] = [];
+  const fakeHandle = { unref() {}, ref() {} } as unknown as NodeJS.Timeout;
+  timerGlobal.setTimeout = ((_fn: (...a: unknown[]) => void, delay?: number) => {
+    if (typeof delay === "number") armedDelays.push(delay);
+    // Do not schedule the real callback — we only assert on the delay argument.
+    return fakeHandle;
+  }) as typeof setTimeout;
+  try {
+    await buffer.addTurn("thread-a", makeTurn("thread-a", "x")); // arms the debounced save
+  } finally {
+    timerGlobal.setTimeout = realSetTimeout;
+  }
+
+  assert.ok(armedDelays.length >= 1, "a debounced save timer was armed");
+  for (const delay of armedDelays) {
+    assert.ok(
+      delay <= 2_147_483_647,
+      `armed setTimeout delay ${delay} must be clamped to the 32-bit limit`,
+    );
+  }
+});
+
+test("debounce on: a failed clearAfterExtraction save keeps pending so other sessions' turns are not lost", async () => {
+  // Issue #1909 review round 13: clearAfterExtraction must NOT clear the global
+  // pending-save state/timer before its post-clear save is durable. If any
+  // session has a debounced save pending and the post-clear write throws, the
+  // pending state must be retained + re-armed so shutdown/the timer retries —
+  // otherwise buffered turns from OTHER sessions that only ever existed in the
+  // debounced state are lost.
+  const storage = new FailOnceBufferStorage();
+  const buffer = new SmartBuffer(
+    parseConfig({ bufferSaveDebounceMs: 10_000, triggerMode: "smart", bufferMaxTurns: 10_000 }),
+    storage as unknown as ConstructorParameters<typeof SmartBuffer>[1],
+  );
+
+  // Session A buffers a turn — only a debounced save is pending (nothing on disk).
+  await buffer.addTurn("session-a", makeTurn("session-a", "A only lives in the pending save"));
+  // Session B buffers a turn too — the pending debounced save now covers A + B.
+  await buffer.addTurn("session-b", makeTurn("session-b", "B is about to be extracted"));
+  assert.equal(storage.saveCount, 0, "both turns are still only in the debounced pending save");
+
+  const internals = buffer as unknown as DebouncedBufferInternals;
+
+  // Extract + clear session B. The post-clear save FAILS (FailOnce). The global
+  // pending state must survive so A (and the cleared-B state) can still land.
+  await assert.rejects(
+    () => buffer.clearAfterExtraction("session-b"),
+    /simulated buffer write failure/,
+    "the failed post-clear save propagates (matching the inline-write guarantee)",
+  );
+  assert.equal(storage.saveCount, 0, "nothing was persisted on the failed clear");
+  assert.equal(
+    internals.pendingSave,
+    true,
+    "a failed clear keeps the save pending (would be false + lost without the round 13 fix)",
+  );
+  assert.notEqual(internals.saveTimer, null, "a background retry timer is re-armed after the failure");
+
+  // Retry (mirrors the re-armed timer or graceful shutdown) succeeds.
+  await buffer.flushPendingSave();
+  assert.equal(storage.saveCount, 1, "the retry performed exactly one successful write");
+  assert.equal(internals.pendingSave, false, "pending is cleared only after the durable write");
+  assert.equal(
+    storage.saved?.entries?.["session-a"]?.turns.length,
+    1,
+    "session A's turn is retained through the failed clear and later persisted",
+  );
+  assert.equal(
+    storage.saved?.entries?.["session-b"]?.turns.length ?? 0,
+    0,
+    "session B's turns were cleared by the extraction",
+  );
+});
+
+/**
+ * Storage that can hold ONE saveBuffer call open on a gate so a test can
+ * interleave other buffer mutations while a flush's write is in flight. The
+ * persisted snapshot is captured at call time (matching FakeStorage), so it
+ * reflects exactly the state the flush intended to write.
+ */
+class GatedSaveStorage {
+  public saved: BufferState | null = null;
+  public saveCount = 0;
+  private blockNext = false;
+  private release: (() => void) | null = null;
+  private signalStarted: (() => void) | null = null;
+  private startedPromise: Promise<void> | null = null;
+
+  constructor(private readonly initial: BufferState) {}
+
+  async loadBuffer(): Promise<BufferState> {
+    return structuredClone(this.initial);
+  }
+
+  blockNextSave(): void {
+    this.blockNext = true;
+    this.startedPromise = new Promise<void>((resolve) => {
+      this.signalStarted = resolve;
+    });
+  }
+
+  saveStarted(): Promise<void> {
+    return this.startedPromise ?? Promise.resolve();
+  }
+
+  releaseSave(): void {
+    this.release?.();
+    this.release = null;
+  }
+
+  async saveBuffer(state: BufferState): Promise<void> {
+    this.saveCount += 1;
+    const snapshot = structuredClone(state);
+    if (this.blockNext) {
+      this.blockNext = false;
+      const gate = new Promise<void>((resolve) => {
+        this.release = resolve;
+      });
+      this.signalStarted?.();
+      await gate;
+    }
+    this.saved = snapshot;
+  }
+}
+
+test("debounce on: a turn recorded around a forced flush is not dropped by the flush's clear (PR #2016)", async () => {
+  // Issue #1909 PR #2016 review: flushPendingSave used to clear
+  // pendingSave/firstPendingAtMs AFTER the serialized write mutation resolved,
+  // i.e. OUTSIDE the serializer. A turn recorded around that flush re-arms a
+  // debounced save (pendingSave = true); if the flush's late clear then wiped
+  // that flag, the interleaved turn's own scheduled flush would early-return
+  // and its persistence would be lost. The fix makes write + clear atomic on
+  // the existing serializer mutex. This drives the interleave deterministically
+  // and proves BOTH the pre-flush turn and the interleaved turn reach disk.
+  const storage = new GatedSaveStorage(emptyBufferState());
+  const buffer = new SmartBuffer(
+    parseConfig({ bufferSaveDebounceMs: 10_000, triggerMode: "smart", bufferMaxTurns: 10_000 }),
+    storage as unknown as ConstructorParameters<typeof SmartBuffer>[1],
+  );
+
+  // Pre-flush turn: schedules a debounced save (pendingSave = true, timer armed).
+  assert.equal(
+    await buffer.addTurn("thread-a", makeTurn("thread-a", "pre-flush")),
+    "keep_buffering",
+  );
+
+  // Force a flush whose write blocks mid-flight, holding the serializer.
+  storage.blockNextSave();
+  const flushP = buffer.flushPendingSave();
+  await storage.saveStarted();
+
+  // Interleave a turn while the flush write is in flight. It queues behind the
+  // flush's write mutation on the serializer and records only after it settles.
+  const addP = buffer.addTurn("thread-a", makeTurn("thread-a", "post-flush"));
+
+  // Let the flush write land and everything settle.
+  storage.releaseSave();
+  await Promise.all([flushP, addP]);
+
+  const internals = buffer as unknown as DebouncedBufferInternals;
+  assert.deepEqual(
+    buffer.getTurns("thread-a").map((t) => t.content),
+    ["pre-flush", "post-flush"],
+    "both turns are held in memory",
+  );
+  assert.equal(
+    internals.pendingSave,
+    true,
+    "the interleaved turn's debounced save survives the flush's clear (owns its own flush)",
+  );
+
+  // The interleaved turn's pending save must still land — the flush's clear must
+  // not have silently dropped it.
+  await buffer.flushPendingSave();
+  assert.deepEqual(
+    storage.saved?.entries?.["thread-a"]?.turns.map((t) => t.content) ?? [],
+    ["pre-flush", "post-flush"],
+    "the pre-flush turn and the interleaved turn both persist",
+  );
+  assert.equal(internals.pendingSave, false, "pending is cleared only after the durable write");
+});