@remnic/core 9.7.15 → 9.9.0

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");
+});

package/src/buffer-surprise-trigger.test.ts

@@ -22,6 +22,7 @@ import type { BufferState, BufferTurn } from "./types.js";
 
 class FakeStorage {
   public saved: BufferState | null = null;
+  public saveCount = 0;
 
   constructor(private readonly initial: BufferState) {}
 
@@ -30,6 +31,7 @@ class FakeStorage {
   }
 
   async saveBuffer(state: BufferState): Promise<void> {
+    this.saveCount += 1;
     this.saved = structuredClone(state);
   }
 }
@@ -355,6 +357,7 @@ async function assertProbeRejectionHandled(
     bufferSurpriseThreshold: 0.35,
     bufferMaxTurns: 5,
     triggerMode: "smart",
+    bufferSaveDebounceMs: 0,
   });
   const buffer = new SmartBuffer(config, storage as any, probe);
 
@@ -476,6 +479,7 @@ test("flag on: probe that never resolves is timed out, turn is still saved", asy
     bufferSurpriseProbeTimeoutMs: 30,
     bufferMaxTurns: 5,
     triggerMode: "smart",
+    bufferSaveDebounceMs: 0,
   });
   const buffer = new SmartBuffer(config, storage as any, probe);
 
@@ -523,6 +527,7 @@ test("flag on: slow probe does not hold the buffer mutation queue", async () =>
     bufferSurpriseProbeTimeoutMs: 1000,
     bufferMaxTurns: 5,
     triggerMode: "smart",
+    bufferSaveDebounceMs: 0,
   });
   const buffer = new SmartBuffer(config, storage as any, probe);
 
@@ -750,3 +755,39 @@ test("flag on: stale snapshot clears do not mark live turns as freshly extracted
     "a skipped stale-snapshot clear must not advance extraction metadata",
   );
 });
+
+// ---------------------------------------------------------------------------
+// Issue #1909 (review finding 1) — surprise promotion forces a durable flush
+// ---------------------------------------------------------------------------
+
+test("debounce on: surprise-promoted extract_now flushes the buffer before extraction", async () => {
+  const storage = new FakeStorage(emptyBuffer());
+  const probe = fixedScoreProbe(0.99); // promotes keep_buffering -> extract_now
+  const config = parseConfig({
+    bufferSurpriseTriggerEnabled: true,
+    bufferSurpriseThreshold: 0.35,
+    // High turn cap so the built-in trigger keeps buffering; only the surprise
+    // probe promotes. Large debounce so a scheduled save would NOT have landed.
+    bufferMaxTurns: 100,
+    triggerMode: "smart",
+    bufferSaveDebounceMs: 10_000,
+  });
+  const buffer = new SmartBuffer(
+    config,
+    storage as unknown as ConstructorParameters<typeof SmartBuffer>[1],
+    probe,
+  );
+
+  const outcome = await buffer.addTurnWithOutcome("sess-1", makeTurn("sess-1", "novel turn"));
+  assert.equal(outcome.decision, "extract_now", "surprise promotes the turn");
+  assert.equal(
+    storage.saveCount,
+    1,
+    "the buffer was flushed to disk EXACTLY once before extraction (timer cancelled, single flush)",
+  );
+  assert.equal(
+    storage.saved?.entries?.["sess-1"]?.turns.length,
+    1,
+    "the persisted buffer contains the turn that triggered extraction",
+  );
+});