@remnic/core 10.0.84 → 10.0.86

package/src/buffer-eviction-backpressure.test.ts

@@ -0,0 +1,211 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { SmartBuffer, BufferAdmissionRefusedError } from "./buffer.js";
+import { parseConfig } from "./config.js";
+import { log } from "./logger.js";
+import { TurnIngestionCoordinator } from "./orchestration/turn-ingestion.js";
+import type { BufferEntryState, BufferState, BufferTurn } from "./types.js";
+
+class FakeStorage {
+  public saved: BufferState | null = null;
+  public saveCount = 0;
+
+  constructor(private readonly initial: BufferState) {}
+
+  async loadBuffer(): Promise<BufferState> {
+    return structuredClone(this.initial);
+  }
+
+  async saveBuffer(state: BufferState): Promise<void> {
+    this.saveCount += 1;
+    this.saved = structuredClone(state);
+  }
+}
+
+function makeTurn(key: string, content: string, accepted = false): BufferTurn {
+  const turn: BufferTurn = {
+    role: "user",
+    content,
+    timestamp: new Date().toISOString(),
+    sessionKey: key,
+  };
+  if (accepted) turn.acceptedCapture = true;
+  return turn;
+}
+
+function entry(turns: BufferTurn[]): BufferEntryState {
+  return { turns, lastExtractionAt: null, extractionCount: 0 };
+}
+
+function emptyEntry(): BufferEntryState {
+  return { turns: [], lastExtractionAt: null, extractionCount: 0 };
+}
+
+/** default + the given entries; default stays empty unless given. */
+function seededState(entries: Record<string, BufferEntryState>): BufferState {
+  const defaultEntry = entries.default ?? emptyEntry();
+  return {
+    turns: defaultEntry.turns,
+    lastExtractionAt: defaultEntry.lastExtractionAt,
+    extractionCount: defaultEntry.extractionCount,
+    entries: { default: defaultEntry, ...entries },
+  };
+}
+
+function makeBuffer(state: BufferState, maxSessions: number) {
+  const config = parseConfig({ bufferSaveDebounceMs: 0, bufferMaxSessions: maxSessions });
+  const storage = new FakeStorage(state);
+  const buffer = new SmartBuffer(config, storage);
+  return { buffer, storage };
+}
+
+const CAP = 4;
+
+function savedKeys(storage: FakeStorage): string[] {
+  return Object.keys(storage.saved?.entries ?? {});
+}
+
+test("live capture at a cap full of non-empty backlog is refused, never evicts buffered turns", async () => {
+  const { buffer } = makeBuffer(
+    seededState({
+      a: entry([makeTurn("a", "backlog a")]),
+      b: entry([makeTurn("b", "backlog b")]),
+      c: entry([makeTurn("c", "backlog c")]),
+    }),
+    CAP,
+  );
+
+  await assert.rejects(
+    buffer.addTurn("new-session", makeTurn("new-session", "live turn")),
+    BufferAdmissionRefusedError,
+  );
+
+  assert.deepEqual(buffer.getTurns("a").map((t) => t.content), ["backlog a"], "oldest backlog lost to live admission");
+  assert.deepEqual(buffer.getTurns("b").map((t) => t.content), ["backlog b"]);
+  assert.deepEqual(buffer.getTurns("c").map((t) => t.content), ["backlog c"]);
+  assert.equal(buffer.getTurns("new-session").length, 0, "refused turn was not buffered");
+
+  // Accepted captures are subject to the same no-backlog-loss limit: refusal
+  // happens before acceptance, preserving accepted-capture non-eviction.
+  assert.equal(
+    await buffer.addTurnBounded("accepted-1", makeTurn("accepted-1", "accepted", true)),
+    null,
+    "accepted capture is refused rather than evicting native backlog",
+  );
+  assert.deepEqual(buffer.getTurns("a").map((t) => t.content), ["backlog a"]);
+  assert.deepEqual(buffer.getTurns("b").map((t) => t.content), ["backlog b"]);
+  assert.deepEqual(buffer.getTurns("c").map((t) => t.content), ["backlog c"]);
+});
+
+test("an already-admitted session keeps accepting turns at a full cap", async () => {
+  const { buffer, storage } = makeBuffer(
+    seededState({
+      a: entry([makeTurn("a", "backlog a")]),
+      b: entry([makeTurn("b", "backlog b")]),
+      c: entry([makeTurn("c", "backlog c")]),
+    }),
+    CAP,
+  );
+
+  const decision = await buffer.addTurn("b", makeTurn("b", "another b turn"));
+  assert.equal(decision, "keep_buffering");
+  assert.deepEqual(buffer.getTurns("b").map((t) => t.content), ["backlog b", "another b turn"]);
+  assert.deepEqual(buffer.getTurns("a").map((t) => t.content), ["backlog a"], "existing-session admission must not evict peers");
+  assert.deepEqual(buffer.getTurns("c").map((t) => t.content), ["backlog c"]);
+  assert.equal(savedKeys(storage).length, CAP, "entry count stays at the cap");
+});
+
+test("empty entries are still evicted first to admit a new live session", async () => {
+  const { buffer, storage } = makeBuffer(
+    seededState({
+      "empty-oldest": emptyEntry(),
+      n1: entry([makeTurn("n1", "native 1")]),
+      n2: entry([makeTurn("n2", "native 2")]),
+    }),
+    CAP,
+  );
+
+  const decision = await buffer.addTurn("new-session", makeTurn("new-session", "live turn"));
+  assert.equal(decision, "keep_buffering");
+  const keys = savedKeys(storage);
+  assert.ok(!keys.includes("empty-oldest"), "oldest empty entry reclaimed");
+  assert.ok(keys.includes("new-session"), "new session admitted");
+  assert.deepEqual(buffer.getTurns("n1").map((t) => t.content), ["native 1"], "empty eviction must not touch backlog");
+  assert.deepEqual(buffer.getTurns("n2").map((t) => t.content), ["native 2"]);
+});
+
+test("a retained-only entry is non-evictable backlog: live admission is refused instead", async () => {
+  const retainedOnly: BufferEntryState = {
+    turns: [],
+    retainedTurns: [makeTurn("r", "deferred retry turn")],
+    lastExtractionAt: null,
+    extractionCount: 0,
+  };
+  const { buffer } = makeBuffer(
+    seededState({
+      r: retainedOnly,
+      n1: entry([makeTurn("n1", "native 1")]),
+      n2: entry([makeTurn("n2", "native 2")]),
+    }),
+    CAP,
+  );
+
+  await assert.rejects(
+    buffer.addTurn("new-session", makeTurn("new-session", "live turn")),
+    BufferAdmissionRefusedError,
+  );
+  assert.equal(
+    buffer.getRetainedDeferredTurns("r").length,
+    1,
+    "retained retry turns must not be evicted as 'empty'",
+  );
+});
+test("concurrent multi-session admissions reserve capacity without partial batches", async () => {
+  const { buffer } = makeBuffer(seededState({}), 2);
+  const results = await Promise.all([
+    buffer.addTurnsBounded([{ bufferKey: "batch-a", turns: [makeTurn("batch-a", "a")] }]),
+    buffer.addTurnsBounded([{ bufferKey: "batch-b", turns: [makeTurn("batch-b", "b")] }]),
+  ]);
+
+  assert.equal(results.filter((result) => result !== null).length, 1);
+  assert.equal(results.filter((result) => result === null).length, 1);
+  assert.equal(buffer.getTurns("batch-a").length + buffer.getTurns("batch-b").length, 1);
+});
+
+test("processTurn propagates retryable admission refusal without queueing extraction", async () => {
+  const { buffer } = makeBuffer(
+    seededState({
+      a: entry([makeTurn("a", "backlog a")]),
+      b: entry([makeTurn("b", "backlog b")]),
+      c: entry([makeTurn("c", "backlog c")]),
+    }),
+    CAP,
+  );
+  const config = parseConfig({
+    memoryDir: "/tmp/unused-buffer-eviction-backpressure",
+    bufferSaveDebounceMs: 0,
+    bufferMaxSessions: CAP,
+  });
+  const queued: BufferTurn[][] = [];
+  type CoordinatorDeps = ConstructorParameters<typeof TurnIngestionCoordinator>[0];
+  // SAFETY: this fixture exercises only admission + refusal; the remaining
+  // coordinator deps are never reached on this path.
+  const deps = Object.assign({} as CoordinatorDeps, {
+    buffer,
+    config,
+    queueBufferedExtraction: async (turns: BufferTurn[]) => {
+      queued.push(turns);
+    },
+  });
+  const coordinator = new TurnIngestionCoordinator(deps);
+
+  await assert.rejects(
+    coordinator.processTurn("user", "live turn", "new-session"),
+    BufferAdmissionRefusedError,
+    "caller must receive retryable refusal rather than successful acknowledgment",
+  );
+
+  assert.equal(queued.length, 0, "a refused turn must not queue extraction");
+  assert.equal(buffer.getTurns("new-session").length, 0, "a refused turn must not be buffered");
+  assert.deepEqual(buffer.getTurns("a").map((x) => x.content), ["backlog a"], "backlog dropped during refused admission");
+});

package/src/buffer-eviction.ts

@@ -10,11 +10,10 @@ export interface BufferEvictionHooks {
 }
 
 /**
- * Pick the keys to evict so `entries` returns to `maxCount`: the oldest empty
- * sessions first; retained failed extractions (#1908) keep their turns, so if
- * empty entries alone cannot reach the cap the oldest NON-empty sessions go
- * too rather than growing unboundedly. "default", the retained keys and
- * entries holding an accepted capture are never chosen.
+ * Pick empty entries to evict so `entries` returns to `maxCount`. Backlog
+ * (active or retained turns) is never evicted; admission must refuse when
+ * empty entries cannot free a slot. "default", retained keys and entries
+ * holding an accepted capture are never chosen.
  */
 export function selectEvictedBufferKeys(
   entries: Readonly<Record<string, BufferEntryState>>,
@@ -35,17 +34,12 @@ export function selectEvictedBufferKeys(
   const candidates = keys.filter(
     (key) => key !== "default" && !retainKeys.includes(key) && !hooks.holdsAcceptedCapture(entries[key]),
   );
+  // Backlog = active turns OR retained retry turns (#1908); only an entry
+  // holding neither counts as empty.
   const emptyRemovable = candidates
-    .filter((key) => (entries[key]?.turns.length ?? 0) === 0)
+    .filter((key) => (entries[key]?.turns.length ?? 0) === 0 && (entries[key]?.retainedTurns?.length ?? 0) === 0)
     .sort(byOldestActivity);
 
   const removableCount = Math.max(0, keys.length - maxCount);
-  const evicted = emptyRemovable.slice(0, removableCount);
-  if (evicted.length < removableCount) {
-    const nonEmptyRemovable = candidates
-      .filter((key) => (entries[key]?.turns.length ?? 0) > 0)
-      .sort(byOldestActivity);
-    return evicted.concat(nonEmptyRemovable.slice(0, removableCount - evicted.length));
-  }
-  return evicted;
+  return emptyRemovable.slice(0, removableCount);
 }

package/src/buffer-incremental-persistence.test.ts

@@ -22,7 +22,7 @@ import { mkdtemp, rm } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 
-import { SmartBuffer } from "./buffer.js";
+import { SmartBuffer, BufferAdmissionRefusedError } from "./buffer.js";
 import { parseConfig } from "./config.js";
 import { StorageManager } from "./storage.js";
 import type { BufferEntryState, BufferState, BufferTurn } from "./types.js";
@@ -161,34 +161,28 @@ test("clearAfterExtraction persists the cleared session state", async () => {
   assert.equal(record?.entry.extractionCount, 1);
 });
 
-test("evicted sessions get their files deleted", async () => {
+test("empty evicted sessions get their files deleted", async () => {
   const storage = new IncrementalStorage(emptyState());
-  const buffer = new SmartBuffer(parseConfig({ triggerMode: "every_n", bufferMaxTurns: 100, bufferMaxSessions: 200 }), storage);
-
-  // normalizeState always materializes a "default" entry, so 198 seeded
-  // sessions + default = 199; new-session reaches exactly 200 (the
-  // addTurnBounded cap). One more UNBOUNDED addTurn pushes to 201 and
-  // pruneEntries evicts the oldest non-default session (s0).
-  for (let i = 0; i < 198; i++) {
-    const key = `s${i}`;
-    await buffer.addTurnBounded(key, makeTurn(key, `content ${i}`));
-  }
+  const buffer = new SmartBuffer(parseConfig({ triggerMode: "every_n", bufferMaxTurns: 100, bufferMaxSessions: 4 }), storage);
+
+  // Clear one persisted entry to make it genuinely empty. Accepted-capture
+  // admission may reclaim this slot, but never a session with buffered turns.
+  await buffer.addTurn("empty-old", makeTurn("empty-old", "will be extracted"));
+  await buffer.flushPendingSave();
+  await buffer.clearAfterExtraction("empty-old");
+  await buffer.addTurnBounded("native-1", makeTurn("native-1", "native 1"));
+  await buffer.addTurnBounded("native-2", makeTurn("native-2", "native 2"));
   await buffer.flushPendingSave();
 
-  const outcome = await buffer.addTurnBounded("new-session", makeTurn("new-session", "fresh"));
-  assert.notEqual(outcome, null, "addTurnBounded refused below capacity");
-  await buffer.addTurn("overflow", makeTurn("overflow", "one too many"));
-  // The evicted key's file deletion lands on the next persist, like any
-  // other buffered state change.
+  const accepted = await buffer.addTurnBounded("accepted", {
+    ...makeTurn("accepted", "durable accepted"),
+    acceptedCapture: true,
+  });
+  assert.notEqual(accepted, null, "empty entry should be reclaimed to admit accepted capture");
   await buffer.flushPendingSave();
-  assert.ok(storage.deleted.includes("s0"), "oldest session was not evicted under capacity pressure");
-  assert.ok(
-    storage.deleted.length > 0,
-    "capacity pressure evicted entries without deleting their session files",
-  );
-  for (const key of storage.deleted) {
-    assert.equal(storage.sessions.has(key), false, `evicted session ${key} still has a file record`);
-  }
+  assert.ok(storage.deleted.includes("empty-old"), "reclaimed empty entry's file was not deleted");
+  assert.equal(buffer.getTurns("native-1").length, 1);
+  assert.equal(buffer.getTurns("native-2").length, 1);
 });
 
 test("the default entry cap leaves headroom for live sessions during backlog drains (#3303)", async () => {
@@ -273,9 +267,7 @@ test("legacy-only storage keeps the whole-state saveBuffer behavior", async () =
   assert.equal(storage.lastSaved?.entries?.["thread-b"]?.turns[0]?.content, "beta");
 });
 
-test("durable capture at the entry cap evicts native entries instead of refusing (COS-244c)", async () => {
-  // Stalled extraction left the cap full of native (non-accepted)
-  // sessions; addTurnBounded refused every new accepted session.
+test("durable capture at the entry cap is refused without evicting native backlog (COS-244c)", async () => {
   const storage = new IncrementalStorage(emptyState());
   const buffer = new SmartBuffer(
     parseConfig({ triggerMode: "every_n", bufferMaxTurns: 100, bufferMaxSessions: 4 }),
@@ -286,17 +278,13 @@ test("durable capture at the entry cap evicts native entries instead of refusing
   await buffer.flushPendingSave();
 
   const accepted = (key: string): BufferTurn => ({ ...makeTurn(key, "accepted"), acceptedCapture: true });
+  assert.equal(await buffer.addTurnBounded("accepted-0", accepted("accepted-0")), null);
+  await buffer.flushPendingSave();
+  assert.equal(storage.deleted.length, 0, "accepted refusal must not evict native session files");
   for (let i = 0; i < 3; i++) {
-    const outcome = await buffer.addTurnBounded(`accepted-${i}`, accepted(`accepted-${i}`));
-    assert.notEqual(outcome, null, `accepted-${i} refused while native entries were evictable`);
+    assert.ok(buffer.getTurns(`native-${i}`).some((turn) => turn.content === `native ${i}`));
   }
-  await buffer.flushPendingSave();
-  assert.ok(storage.deleted.includes("native-0"), "oldest native entry was not evicted");
-
-  // Accepted work is still never evicted: with only accepted entries left the
-  // cap refuses rather than dropping accepted captures.
-  assert.equal(await buffer.addTurnBounded("accepted-3", accepted("accepted-3")), null);
-  for (let i = 0; i < 3; i++) assert.ok(!storage.deleted.includes(`accepted-${i}`));
+  assert.equal(buffer.getTurns("accepted-0").length, 0, "refused capture was never accepted");
 });
 
 test("at-cap admission evicts nothing when eviction cannot free a slot (COS-244c)", async () => {

package/src/buffer-persistence.ts

@@ -1,4 +1,5 @@
-import type { BufferEntryState, BufferState, BufferSurpriseEvent, BufferTurn } from "./types.js";
+import type { DrainedTurnSets } from "./buffer-turn-helpers.js";
+import type { BufferEntryState, BufferState, BufferSurpriseEvent } from "./types.js";
 import type { BufferSessionSaveOutcome } from "./storage/buffer-drain-claims.js";
 
 /**
@@ -26,8 +27,8 @@ export interface BufferStorage {
 export interface BufferPersistOutcome {
   /** Sessions whose in-memory entry moved into a drain claim: the caller must evict them (a claimed session no longer lives in this process). */
   handedOver: string[];
-  /** Per session, the turns a drain already extracted: the caller subtracts them from its in-memory copy. */
-  drainedTurns: Map<string, BufferTurn[]>;
+  /** Per session, the turns a drain extracted, kept in their original lists. */
+  drainedTurns: Map<string, DrainedTurnSets>;
 }
 
 /**
@@ -73,17 +74,20 @@ export class BufferSessionPersistence {
     storage: BufferStorage,
     state: BufferState,
     peekEntry: (key: string) => BufferEntryState | undefined,
+    reconcile?: { key: string; drained: DrainedTurnSets },
   ): Promise<BufferPersistOutcome> {
+    const drainedTurns = new Map<string, DrainedTurnSets>(
+      reconcile ? [[reconcile.key, reconcile.drained]] : [],
+    );
     const saveSession = storage.saveBufferSession?.bind(storage);
     const deleteSession = storage.deleteBufferSession?.bind(storage);
     if (!saveSession || !deleteSession) {
       await storage.saveBuffer(state);
       this.dirty.clear();
       this.deleted.clear();
-      return { handedOver: [], drainedTurns: new Map() };
+      return { handedOver: [], drainedTurns };
     }
     const handedOver: string[] = [];
-    const drainedTurns = new Map<string, BufferTurn[]>();
     for (const key of [...this.deleted]) {
       await deleteSession(key);
       this.deleted.delete(key);
@@ -104,7 +108,12 @@ export class BufferSessionPersistence {
       if (outcome?.status === "handed_over") handedOver.push(key);
       // A drain tombstone: the turns it extracted must leave this process's
       // copy too, or the owner would extract them a second time.
-      if (outcome?.drainedTurns && outcome.drainedTurns.length > 0) drainedTurns.set(key, outcome.drainedTurns);
+      if (
+        outcome?.drainedTurns &&
+        (outcome.drainedTurns.turns.length > 0 || outcome.drainedTurns.retainedTurns.length > 0)
+      ) {
+        drainedTurns.set(key, outcome.drainedTurns);
+      }
     }
     return { handedOver, drainedTurns };
   }

package/src/buffer-session.test.ts

@@ -1,6 +1,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { SmartBuffer } from "./buffer.js";
+import { SmartBuffer, BufferAdmissionRefusedError } from "./buffer.js";
 import { parseConfig } from "./config.js";
 import type { BufferSurpriseProbe } from "./buffer.js";
 import type { BufferState, BufferTurn } from "./types.js";
@@ -642,13 +642,14 @@ test("getTurns prepends retained deferred turns before live turns", async () =>
   assert.equal(all[1]?.content, "new live turn");
 });
 
-test("SmartBuffer prefers pruning empty entries and bounds pending-turn buffers at the cap (#1908 policy)", async () => {
+test("SmartBuffer refuses new sessions instead of dropping backlog at the cap (#1908 policy)", async () => {
   // Pre-#1908 this contract was "never prune non-empty entries". With retry
   // retention (failed extractions keep their turns), unbounded non-empty
   // growth during a provider outage would eventually OOM the daemon — the
-  // documented policy (#1908 step 7) is: retain up to MAX_BUFFER_ENTRY_COUNT
-  // session entries, then prune the OLDEST sessions with a loud warning.
-  // Empty entries are still evicted first.
+  // documented policy (#1908 step 7) bounds the ENTRY COUNT, not by dropping
+  // buffered turns: a NEW session is refused (retryable backpressure) when
+  // only non-empty backlog fills the cap. Empty entries are still evicted
+  // first, and already-admitted sessions keep buffering.
   const entries = Object.fromEntries(
     Array.from({ length: 205 }, (_, index) => [
       `thread-${index}`,
@@ -674,21 +675,32 @@ test("SmartBuffer prefers pruning empty entries and bounds pending-turn buffers
   });
   const buffer = new SmartBuffer(parseConfig({ bufferSaveDebounceMs: 0, bufferMaxSessions: 200 }), storage as unknown as ConstructorParameters<typeof SmartBuffer>[1]);
 
-  await buffer.addTurn("active-thread", makeTurn("active-thread", "pending memory"));
+  await assert.rejects(
+    buffer.addTurn("active-thread", makeTurn("active-thread", "pending memory")),
+    BufferAdmissionRefusedError,
+    "a new session must be refused while only non-empty backlog fills the cap",
+  );
+
+  // Already-admitted sessions keep buffering; the save reflects the
+  // post-refusal state: nothing was evicted, nothing refused was buffered.
+  await buffer.addTurn("thread-204", makeTurn("thread-204", "another turn"));
+  assert.equal(buffer.getTurns("thread-204").length, 2);
 
   const persistedKeys = Object.keys(storage.saved?.entries ?? {});
-  assert.ok(persistedKeys.length <= 201, `bounded at the cap plus default (got ${persistedKeys.length})`);
+  assert.ok(persistedKeys.length <= 206, `entry count stays at the seeded cap state (got ${persistedKeys.length})`);
   assert.ok(persistedKeys.includes("default"), "default entry never pruned");
-  assert.ok(persistedKeys.includes("active-thread"), "the just-written key is retained");
-  assert.ok(!persistedKeys.includes("thread-0"), "oldest pending entry pruned once over the cap");
+  assert.ok(persistedKeys.includes("thread-0"), "oldest backlog keeps its turns for extraction");
   assert.ok(persistedKeys.includes("thread-204"), "newest pending entry survives");
+  assert.ok(!persistedKeys.includes("active-thread"), "the refused turn was never buffered");
 });
 
-test("pruneEntries evicts oldest NON-empty session entries past the cap (#1908 retry-retention bound)", async () => {
+test("pruneEntries never evicts non-empty backlog; live admission is refused past the cap (#1908 retry-retention bound)", async () => {
   // Retained failed extractions keep their turns in the buffer, so during a
   // provider outage non-empty entries can exceed MAX_BUFFER_ENTRY_COUNT (200).
-  // The cap is the documented bound: the oldest non-empty sessions must be
-  // evicted (loudly) rather than growing without bound (codex review).
+  // The cap is still the documented bound: buffered turn data is never the
+  // release valve — a NEW session is refused (retryable backpressure) until
+  // extraction drains an entry, so the daemon cannot OOM on unbounded growth
+  // and no buffered turn is dropped (codex review).
   const entries: NonNullable<BufferState["entries"]> = {};
   for (let i = 0; i < 210; i += 1) {
     const at = new Date(1_700_000_000_000 + i * 60_000).toISOString();
@@ -701,13 +713,17 @@ 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({ bufferSaveDebounceMs: 0, bufferMaxSessions: 200 }), storage as unknown as ConstructorParameters<typeof SmartBuffer>[1]);
   await buffer.load();
-  await buffer.addTurn("session-newest", makeTurn("session-newest", "new turn"));
+  await assert.rejects(
+    buffer.addTurn("session-newest", makeTurn("session-newest", "new turn")),
+    BufferAdmissionRefusedError,
+    "live admission refuses rather than evicting oldest non-empty backlog",
+  );
 
   const savedKeys = Object.keys(storage.saved?.entries ?? {});
-  assert.ok(savedKeys.length <= 200, `entries bounded at MAX_BUFFER_ENTRY_COUNT (got ${savedKeys.length})`);
-  assert.ok(savedKeys.includes("session-newest"), "the just-written key is retained");
-  assert.equal(buffer.getTurns("session-000").length, 0, "oldest non-empty entry was evicted");
+  assert.ok(savedKeys.length <= 211, `entries bounded at MAX_BUFFER_ENTRY_COUNT plus default (got ${savedKeys.length})`);
+  assert.equal(buffer.getTurns("session-000").length, 1, "oldest non-empty entry keeps its turn for extraction");
   assert.ok(buffer.getTurns("session-209").length > 0, "newest pre-existing entry survives");
+  assert.ok(!savedKeys.includes("session-newest"), "the refused turn was never buffered");
 });
 
 // ---------------------------------------------------------------------------

package/src/buffer-turn-helpers.ts

@@ -1,5 +1,11 @@
 import type { BufferEntryState, BufferState, BufferTurn } from "./types.js";
 
+/** Extracted identities retain whether they came from active or retained turns. */
+export interface DrainedTurnSets {
+  turns: BufferTurn[];
+  retainedTurns: BufferTurn[];
+}
+
 export interface BufferTurnOwner {
   /**
    * Server-resolved principal that owns this session at the authenticated
@@ -392,3 +398,44 @@ export function probeWithTimeout<T>(inflight: Promise<T>, timeoutMs: number): Pr
     if (timer) clearTimeout(timer);
   });
 }
+
+export const isAcceptedTurn = (t: { acceptedCapture?: boolean; writeNamespaceOverride?: string }): boolean =>
+  t.acceptedCapture === true || t.writeNamespaceOverride !== undefined;
+
+export function entryActivityAt(entry: BufferEntryState): number {
+  const lastTurnAt = entry.turns.reduce((latest, turn) => {
+    const parsed = Date.parse(turn.timestamp);
+    return Number.isFinite(parsed) ? Math.max(latest, parsed) : latest;
+  }, -1);
+  const lastExtractionAt =
+    entry.lastExtractionAt === null ? Number.NaN : Date.parse(entry.lastExtractionAt);
+  return Math.max(
+    lastTurnAt,
+    Number.isFinite(lastExtractionAt) ? lastExtractionAt : -1,
+  );
+}
+
+export function entryHoldsAcceptedCapture(entry: BufferEntryState | undefined): boolean {
+  return (entry?.turns ?? []).some(isAcceptedTurn) || (entry?.retainedTurns ?? []).some(isAcceptedTurn);
+}
+
+export function normalizeBufferState(state: BufferState): BufferState {
+  // SAFETY: persisted-state contract — entries, when present, is a record of BufferEntryState.
+  const entries = Object.assign(
+    Object.create(null),
+    state.entries ?? {},
+  ) as NonNullable<BufferState["entries"]>;
+  if (!entries.default) {
+    entries.default = {
+      turns: Array.isArray(state.turns) ? [...state.turns] : [],
+      lastExtractionAt: state.lastExtractionAt ?? null,
+      extractionCount: state.extractionCount ?? 0,
+    };
+  }
+  return {
+    turns: entries.default.turns,
+    lastExtractionAt: entries.default.lastExtractionAt,
+    extractionCount: entries.default.extractionCount,
+    entries,
+  };
+}

package/src/buffer-types.ts

@@ -1,6 +1,33 @@
 /** Types split out of buffer.ts (structural ratchet, issue #1995). */
 
-import type { BufferTurn } from "./types.js";
+import type { BufferTurn, CodingContext, SignalLevel } from "./types.js";
+import type { ResolvedScopeProfilePlan } from "./namespaces/scope-profiles.js";
+
+export type TriggerDecision = "extract_now" | "extract_batch" | "keep_buffering";
+
+export interface AddTurnOutcome {
+  decision: TriggerDecision;
+  extractionTurns?: BufferTurn[];
+}
+
+export interface AddTurnMutationResult {
+  decision: TriggerDecision;
+  signalLevel: SignalLevel;
+  priorTurns: BufferTurn[];
+  activeTurnsSnapshot: BufferTurn[];
+  retainedTurnsSnapshot: BufferTurn[];
+  turnCountInWindow: number;
+}
+
+export interface RetainedTurnCleanupOptions {
+  abortSignal?: AbortSignal;
+  deadlineMs?: number;
+  /** Keep cleanup within the accepted namespace. */
+  writeNamespaceOverride?: string;
+  /** Match the original profile and project binding, not just its write namespace. */
+  scopeProfileWritePlan?: ResolvedScopeProfilePlan | null;
+  codingContext?: CodingContext;
+}
 
 /**
  * Optional surprise probe injected into `SmartBuffer`.