@remnic/core 10.0.60 → 10.0.62

package/src/buffer-drain-handover.test.ts

@@ -0,0 +1,307 @@
+// Buffer-drain handover protocol: a live buffer owner (the daemon) must hand
+// a claimed session's turns INTO the drain claim instead of writing a session
+// file, so the out-of-process `remnic buffer drain` can extract them without
+// the daemon resurrecting or losing content. Covers:
+//   1. persist path: claimed key saves hand over + evict the in-memory entry,
+//      merging the owner's newest turns into the claim (identity-deduped).
+//   2. no resurrection: after handover the session file stays gone.
+//   3. extraction gate: a claimed session's queued extraction settles skipped
+//      (claimed_by_buffer_drain) without touching the LLM; turns stay in the
+//      claim for the drain worker.
+//   4. default-key mirror: handing over "default" clears the legacy mirror.
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, readdirSync, readFileSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+import os from "node:os";
+import { hostname } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { SmartBuffer } from "./buffer.js";
+import { BufferSessionFiles } from "./storage/buffer-session-files.js";
+import { BufferDrainClaims, type DrainLease } from "./storage/buffer-drain-claims.js";
+import type { BufferStorage } from "./buffer-persistence.js";
+import type { BufferState } from "./types.js";
+import { TurnIngestionCoordinator, type TurnIngestionDeps } from "./orchestration/turn-ingestion.js";
+import type { BufferEntryState, BufferTurn, PluginConfig } from "./types.js";
+import { parseConfig } from "./config.js";
+import type { ExtractionRunResult } from "./orchestration/extraction-run.js";
+
+function plainIo() {
+  return {
+    read: async (filePath: string) => readFileSync(filePath, "utf8"),
+    write: async (filePath: string, content: string) => {
+      mkdirSync(path.dirname(filePath), { recursive: true });
+      writeFileSync(filePath, content);
+    },
+  };
+}
+
+function turn(content: string, sessionKey = "sess-1", timestamp = "2026-11-01T00:00:00.000Z"): BufferTurn {
+  return { role: "user", content, timestamp, sessionKey };
+}
+
+function entry(turns: ReturnType<typeof turn>[]): BufferEntryState {
+  return { turns, lastExtractionAt: null, extractionCount: 0 };
+}
+
+function makeConfig(): PluginConfig {
+  return parseConfig({
+    bufferSaveDebounceMs: 0,
+    triggerMode: "smart",
+    bufferMaxTurns: 1000,
+    bufferMaxMinutes: 100000,
+    highSignalPatterns: [],
+    extractionMinUserTurns: 1,
+    extractionMinChars: 0,
+  });
+}
+
+interface Harness {
+  stateDir: string;
+  buffer: SmartBuffer;
+  claims: BufferDrainClaims;
+  storage: BufferStorage;
+  lease: DrainLease;
+  cleanup(): void;
+}
+
+/** A SmartBuffer wired exactly like the daemon wires it: storage methods backed by BufferSessionFiles. */
+function makeHarness(): Harness {
+  const stateDir = mkdtempSync(path.join(os.tmpdir(), "remnic-handover-"));
+  const files = new BufferSessionFiles(stateDir, plainIo());
+  const claims = new BufferDrainClaims(stateDir, plainIo());
+  const storage: BufferStorage = {
+    loadBuffer: () => files.load(),
+    saveBuffer: (state: BufferState) => files.reconcile(state),
+    saveBufferSession: (key: string, entryState: BufferEntryState) => files.save(key, entryState),
+    deleteBufferSession: (key: string) => files.remove(key),
+    isBufferSessionClaimed: (key: string) => files.isClaimed(key),
+  };
+  const buffer = new SmartBuffer(makeConfig(), storage);
+  const now = new Date().toISOString();
+  return {
+    stateDir,
+    buffer,
+    claims,
+    storage,
+    lease: { ownerId: "worker-1", pid: process.pid, host: hostname(), acquiredAt: now, heartbeatAt: now, leaseMs: 60_000 },
+    cleanup: () => rmSync(stateDir, { recursive: true, force: true }),
+  };
+}
+
+test("a claimed session's save hands over and evicts instead of writing a session file", async () => {
+  const h = makeHarness();
+  try {
+    await h.buffer.load();
+    await h.buffer.addTurn("sess-1", turn("old-1"));
+    await h.buffer.addTurn("sess-1", turn("old-2"));
+    assert.ok(readdirSync(path.join(h.stateDir, "buffer")).some((name) => name.endsWith(".json")), "seeded turns persisted as a session file");
+
+    const outcome = await h.claims.claimFromSessionFile("sess-1", h.lease);
+    assert.equal(outcome, "claimed");
+
+    // The daemon owner buffers one more turn for the claimed session and its
+    // debounced-off save fires: this is the resurrection path, and it must
+    // hand over instead.
+    await h.buffer.addTurn("sess-1", turn("new-3"));
+    await h.buffer.save();
+
+    const claim = await h.claims.load("sess-1");
+    assert.ok(claim, "claim must exist after handover");
+    assert.deepEqual(
+      claim.entry.turns.map((t) => t.content),
+      ["old-1", "old-2", "new-3"],
+      "the owner's newest turn merges into the claim; nothing duplicates",
+    );
+    const topLevel = readdirSync(path.join(h.stateDir, "buffer")).filter((name) => name.endsWith(".json"));
+    assert.deepEqual(topLevel, [], "a claimed session must never be written back as a session file");
+
+    // The in-memory entry was evicted with the handover: the next observe
+    // starts fresh (its turns flow into the claim at the next handover).
+    await h.buffer.addTurn("sess-1", turn("post-eviction", "sess-1", "2026-11-01T00:05:00.000Z"));
+    await h.buffer.save();
+    const claimAfter = await h.claims.load("sess-1");
+    assert.ok(claimAfter);
+    assert.deepEqual(
+      claimAfter.entry.turns.map((t) => t.content),
+      ["old-1", "old-2", "new-3", "post-eviction"],
+      "post-handover observes keep flowing into the claim",
+    );
+    assert.deepEqual(
+      readdirSync(path.join(h.stateDir, "buffer")).filter((name) => name.endsWith(".json")),
+      [],
+    );
+  } finally {
+    h.cleanup();
+  }
+});
+
+test("handover of the default key clears the legacy top-level mirror", async () => {
+  const h = makeHarness();
+  try {
+    await h.buffer.load();
+    await h.buffer.addTurn("default", turn("legacy", "legacy-session"));
+    const outcome = await h.claims.claimFromSessionFile("default", h.lease);
+    assert.equal(outcome, "claimed");
+    await h.buffer.addTurn("default", turn("legacy-2", "legacy-session"));
+    await h.buffer.save();
+    const claim = await h.claims.load("default");
+    assert.ok(claim);
+    assert.deepEqual(claim.entry.turns.map((t) => t.content), ["legacy", "legacy-2"]);
+    // No duplicate writes: the snapshot must settle empty after handover.
+    assert.deepEqual(
+      readdirSync(path.join(h.stateDir, "buffer")).filter((name) => name.endsWith(".json")),
+      [],
+    );
+  } finally {
+    h.cleanup();
+  }
+});
+
+/**
+ * Narrow a test double to the dependency contract. The fixture provides the
+ * members the drain path reads; the rest are unused by that path.
+ */
+/** The dependency members the drain path reads. */
+interface DrainDepsFixture {
+  buffer: unknown;
+  config: unknown;
+  extractionQueueCoordinator: unknown;
+  extractionWindowBudgetChars: unknown;
+  getStorage: unknown;
+  shouldQueueExtraction: unknown;
+  runExtraction: unknown;
+}
+
+function asDeps<T extends object>(value: DrainDepsFixture): T {
+  // SAFETY: the fixture provides the members the drain path reads; the
+  // remaining contract members are unused by that path.
+  return value as T;
+}
+
+function gateFixture(isClaimed: boolean) {
+  const runs: { turns: BufferTurn[] }[] = [];
+  const config = {
+    extractionChunkDropAfterFailures: 3,
+    extractionMinUserTurns: 1,
+    extractionMinChars: 0,
+    extractionMaxTurnChars: 100_000,
+  };
+  const deps = {
+    buffer: {
+      isSessionClaimed: () => isClaimed,
+      getTurns: () => [],
+      dropExtractionChunk: async () => 0,
+    },
+    config,
+    extractionQueueCoordinator: {
+      enqueue: (fn: () => Promise<void>) => {
+        void fn().catch(() => {});
+        return true;
+      },
+      runPreemptable: (_preemptable: boolean, parent: AbortSignal | undefined, fn: (signal: AbortSignal) => Promise<void>) => fn(parent ?? new AbortController().signal),
+      beginPreemptable: () => {},
+    },
+    extractionWindowBudgetChars: () => 500,
+    getStorage: async () => ({ saveDroppedExtractionChunk: async () => "/dropped" }),
+    shouldQueueExtraction: () => true,
+    runExtraction: (async (turns: BufferTurn[]) => {
+      runs.push({ turns });
+      return { status: "completed", persistedCount: 0, durableOutputCount: 0 };
+    }),
+    // SAFETY: the fixture provides exactly the deps the coordinator reads
+    // for the drain path (buffer, queue coordinator, budget, storage, dedupe
+    // gate and runExtraction); the cast only fills the unused members.
+  };
+  const coordinator = new TurnIngestionCoordinator(asDeps<TurnIngestionDeps>(deps));
+  return { coordinator, runs };
+}
+
+test("a claimed session's queued extraction settles skipped without an LLM call", async () => {
+  const claimed = gateFixture(true);
+  const { promise, resolve, reject } = Promise.withResolvers<void>();
+  void claimed.coordinator.queueBufferedExtraction([turn("blocked")], "trigger_mode", {
+    bufferKey: "sess-1",
+    clearBufferAfterExtraction: true,
+    onTaskSettled: (error, result) => {
+      try {
+        assert.equal(error, undefined);
+        assert.equal(result?.status, "skipped");
+        assert.equal(result?.reason, "claimed_by_buffer_drain");
+        assert.equal(claimed.runs.length, 0, "the LLM must not run for a claimed session");
+        resolve();
+      } catch (err) {
+        reject(err instanceof Error ? err : new Error(String(err)));
+      }
+    },
+  });
+  await promise;
+});
+
+test("an unclaimed session still extracts normally (gate is claim-only)", async () => {
+  const unclaimed = gateFixture(false);
+  const { promise, resolve, reject } = Promise.withResolvers<void>();
+  void unclaimed.coordinator.queueBufferedExtraction([turn("flows")], "trigger_mode", {
+    bufferKey: "sess-2",
+    clearBufferAfterExtraction: true,
+    onTaskSettled: (error, result) => {
+      try {
+        assert.equal(error, undefined);
+        assert.notEqual(result?.reason, "claimed_by_buffer_drain");
+        assert.equal(unclaimed.runs.length, 1);
+        resolve();
+      } catch (err) {
+        reject(err instanceof Error ? err : new Error(String(err)));
+      }
+    },
+  });
+  await promise;
+});
+
+test("the owner keeps the claim while a drain is still running on it", async () => {
+  const h = makeHarness();
+  try {
+    await h.buffer.load();
+    await h.buffer.addTurn("sess-1", turn("old-1"));
+    await h.buffer.addTurn("sess-1", turn("old-2"));
+    const claimOutcome = await h.claims.claimFromSessionFile("sess-1", h.lease);
+    assert.equal(claimOutcome, "claimed");
+
+    // The drainer extracts old-1 (progress write moves it to `drained`) but
+    // old-2 is still pending, and the drainer holds the lease.
+    const loaded = await h.claims.load("sess-1");
+    assert.ok(loaded);
+    await h.claims.writeEntry("sess-1", h.lease.ownerId, entry([turn("old-2")]), loaded.entry);
+
+    // The owner saves while the drain is mid-flight: this must hand over into
+    // the claim (keeping the claim AND the lease), not consume the tombstone.
+    await h.buffer.addTurn("sess-1", turn("new-3"));
+    await h.buffer.save();
+    const saveSession = h.storage.saveBufferSession;
+    assert.ok(saveSession, "the harness wires saveBufferSession");
+    const saveOutcome = await saveSession("sess-1", {
+      turns: [turn("old-1"), turn("old-2"), turn("new-3")],
+      lastExtractionAt: null,
+      extractionCount: 0,
+    });
+    assert.equal(saveOutcome?.status, "handed_over", "a running drain keeps its claim");
+    assert.equal(await h.claims.load("sess-1") !== null, true, "the claim survives the owner's mid-drain save");
+    assert.equal(existsSync(h.claims.leasePathForTest("sess-1")), true, "the lease survives the owner's mid-drain save");
+
+    // The drain finishes: everything extracted, the drainer acks (drops its
+    // lease, leaving the tombstone). Only now does the owner's save consume it.
+    const current = await h.claims.load("sess-1");
+    assert.ok(current);
+    await h.claims.writeEntry("sess-1", h.lease.ownerId, entry([]), current.entry);
+    await h.claims.releaseLease("sess-1", h.lease.ownerId);
+    const finalOutcome = await saveSession("sess-1", {
+      turns: [turn("old-1"), turn("old-2"), turn("new-3")],
+      lastExtractionAt: null,
+      extractionCount: 0,
+    });
+    assert.equal(finalOutcome?.status, "saved", "the acked tombstone is consumed");
+    assert.equal(await h.claims.load("sess-1"), null, "the tombstone is gone after the consume");
+  } finally {
+    h.cleanup();
+  }
+});

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

@@ -163,7 +163,7 @@ test("clearAfterExtraction persists the cleared session state", async () => {
 
 test("evicted sessions get their files deleted", async () => {
   const storage = new IncrementalStorage(emptyState());
-  const buffer = new SmartBuffer(parseConfig({ triggerMode: "every_n", bufferMaxTurns: 100 }), storage);
+  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
@@ -191,6 +191,24 @@ test("evicted sessions get their files deleted", async () => {
   }
 });
 
+test("the default entry cap leaves headroom for live sessions during backlog drains (#3303)", async () => {
+  // w9C: live session captures were dropped when the extraction worker was busy
+  // on a backlog doc and the 200-session default cap refused new sessions. The
+  // default must leave enough headroom that live captures survive a backlog.
+  const storage = new IncrementalStorage(emptyState());
+  const buffer = new SmartBuffer(parseConfig({ triggerMode: "every_n", bufferMaxTurns: 100 }), storage);
+
+  for (let i = 0; i < 200; i++) {
+    await buffer.addTurnBounded(`backlog-${i}`, makeTurn(`backlog-${i}`, `backlog doc ${i}`));
+  }
+  await buffer.flushPendingSave();
+
+  // A live session arriving while the backlog occupies 200 entries must be
+  // admitted, not dropped.
+  const outcome = await buffer.addTurnBounded("live-session", makeTurn("live-session", "live turn"));
+  assert.notEqual(outcome, null, "a live session at the default cap must not be dropped");
+});
+
 test("resetToEmpty drops every session file on the next persist", async () => {
   const storage = new IncrementalStorage(emptyState());
   const buffer = new SmartBuffer(parseConfig({ triggerMode: "every_n", bufferMaxTurns: 100 }), storage);

package/src/buffer-persistence.ts

@@ -1,4 +1,5 @@
-import type { BufferEntryState, BufferState, BufferSurpriseEvent } from "./types.js";
+import type { BufferEntryState, BufferState, BufferSurpriseEvent, BufferTurn } from "./types.js";
+import type { BufferSessionSaveOutcome } from "./storage/buffer-drain-claims.js";
 
 /**
  * The buffer persistence surface SmartBuffer depends on.
@@ -12,12 +13,23 @@ import type { BufferEntryState, BufferState, BufferSurpriseEvent } from "./types
 export interface BufferStorage {
   loadBuffer(): Promise<BufferState>;
   saveBuffer(state: BufferState): Promise<void>;
-  saveBufferSession?(key: string, entry: BufferEntryState): Promise<void>;
+  /** Reports "handed_over" when the session is claimed by `remnic buffer drain` and the entry moved into the claim instead of a session file. Legacy doubles may return void (treated as "saved"). */
+  saveBufferSession?(key: string, entry: BufferEntryState): Promise<BufferSessionSaveOutcome | void>;
   deleteBufferSession?(key: string): Promise<void>;
+  /** Sync claim check for the extraction gate; omitted when the backend has no drain-claim store. */
+  isBufferSessionClaimed?(key: string): boolean;
   /** Optional surprise-telemetry sink; older storage and test doubles omit it. */
   appendBufferSurpriseEvents?(events: BufferSurpriseEvent[]): Promise<number>;
 }
 
+/** What one persist pass changed beyond plain writes. */
+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[]>;
+}
+
 /**
  * Tracks which sessions' persisted files are stale and writes only those.
  *
@@ -61,15 +73,17 @@ export class BufferSessionPersistence {
     storage: BufferStorage,
     state: BufferState,
     peekEntry: (key: string) => BufferEntryState | undefined,
-  ): Promise<void> {
+  ): Promise<BufferPersistOutcome> {
     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;
+      return { handedOver: [], drainedTurns: new Map() };
     }
+    const handedOver: string[] = [];
+    const drainedTurns = new Map<string, BufferTurn[]>();
     for (const key of [...this.deleted]) {
       await deleteSession(key);
       this.deleted.delete(key);
@@ -82,8 +96,16 @@ export class BufferSessionPersistence {
         this.markDeleted(key);
         continue;
       }
-      await saveSession(key, entry);
+      const outcome = await saveSession(key, entry);
       this.dirty.delete(key);
+      // "handed_over": the entry moved into a drain claim. Content is durable
+      // in the claim, so this key's pending state is settled — the caller
+      // evicts the in-memory entry on its side.
+      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);
     }
+    return { handedOver, drainedTurns };
   }
 }

package/src/buffer-session.test.ts

@@ -428,7 +428,7 @@ test("SmartBuffer prunes stale logical session buffers to a bounded entry set",
       ...entries,
     },
   });
-  const buffer = new SmartBuffer(parseConfig({ bufferSaveDebounceMs: 0 }), storage as unknown as ConstructorParameters<typeof SmartBuffer>[1]);
+  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"));
 
@@ -672,7 +672,7 @@ test("SmartBuffer prefers pruning empty entries and bounds pending-turn buffers
       ...entries,
     },
   });
-  const buffer = new SmartBuffer(parseConfig({ bufferSaveDebounceMs: 0 }), storage as unknown as ConstructorParameters<typeof SmartBuffer>[1]);
+  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"));
 
@@ -699,7 +699,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({ bufferSaveDebounceMs: 0 }), storage as unknown as ConstructorParameters<typeof SmartBuffer>[1]);
+  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"));
 

package/src/buffer-turn-helpers.ts

@@ -104,6 +104,22 @@ export function copyBufferTurn(turn: BufferTurn): BufferTurn {
   return copy;
 }
 
+/**
+ * Remove the turns that a drain already extracted (`drained`) from `turns`.
+ * Identity-based (role/content/timestamp/session/...): the same comparison
+ * the buffer uses to match live turns, so a stale owner can subtract exactly
+ * what the drain took and keep everything else.
+ */
+export function subtractBufferTurns(turns: readonly BufferTurn[], drained: readonly BufferTurn[]): BufferTurn[] {
+  if (drained.length === 0) return [...turns];
+  const kept = [...turns];
+  for (const gone of drained) {
+    const at = kept.findIndex((live) => bufferTurnsEqual(live, gone));
+    if (at >= 0) kept.splice(at, 1);
+  }
+  return kept;
+}
+
 export function bufferTurnsEqual(left: BufferTurn | undefined, right: BufferTurn): boolean {
   if (!left) return false;
   return (

package/src/buffer.ts

@@ -13,7 +13,7 @@ import type {
 } from "./types.js";
 import { resolvePresentationCapabilities, resolveNamespaceCapabilities } from "./capabilities.js";
 import { resolvePrincipal } from "./namespaces/principal.js";
-import { scopeProfilePlanIdentity } from "./buffer-turn-helpers.js";
+import { scopeProfilePlanIdentity, subtractBufferTurns } from "./buffer-turn-helpers.js";
 import { ExtractionDeadlineError } from "./orchestration/extraction-run.js";
 import type { ExtractionBufferSnapshot } from "./extraction-liveness.js";
 import {
@@ -49,7 +49,9 @@ export interface RetainedTurnCleanupOptions {
   codingContext?: import("./types.js").CodingContext;
 }
 
-const MAX_BUFFER_ENTRY_COUNT = 200;
+// Raised from 200 in #3303: live captures were being dropped at busy hours
+// while the single extraction worker drained a backlog.
+const FALLBACK_MAX_BUFFER_SESSIONS = 1000;
 const isAcceptedTurn = (t: { acceptedCapture?: boolean; writeNamespaceOverride?: string }): boolean =>
   t.acceptedCapture === true || t.writeNamespaceOverride !== undefined;
 
@@ -129,6 +131,14 @@ export class SmartBuffer {
     this.surpriseProbe = surpriseProbe;
   }
 
+  /** Distinct sessions admitted before backpressure; configurable (#3303, raised from 200). */
+  private get maxSessionEntries(): number {
+    // parseConfig defaults, validates, and floors bufferMaxSessions at the I/O
+    // boundary; FALLBACK_MAX_BUFFER_SESSIONS covers direct constructions with
+    // configs from before the knob existed.
+    return this.config.bufferMaxSessions ?? FALLBACK_MAX_BUFFER_SESSIONS;
+  }
+
   private enqueueMutation<T>(op: () => Promise<T>): Promise<T> {
     const run = this.mutationChain.catch(() => {}).then(op);
     this.mutationChain = run.catch(() => {});
@@ -206,11 +216,11 @@ export class SmartBuffer {
     );
   }
 
-  /** Evict oldest entries past MAX_BUFFER_ENTRY_COUNT and queue their session files for deletion. */
+  /** Evict oldest entries past this.maxSessionEntries and queue their session files for deletion. */
   private pruneEntries(retainKeys: string[]): void {
     const entries = this.state.entries;
     if (!entries) return;
-    const evicted = selectEvictedBufferKeys(entries, retainKeys, MAX_BUFFER_ENTRY_COUNT, {
+    const evicted = selectEvictedBufferKeys(entries, retainKeys, this.maxSessionEntries, {
       activityAt: (entry) => this.entryActivityAt(entry),
       holdsAcceptedCapture: (entry) => this.entryHoldsAcceptedCapture(entry),
     });
@@ -222,7 +232,7 @@ export class SmartBuffer {
       // be observable, not silent.
       log.warn(
         `buffer: pruned ${evicted.length} oldest session entr${evicted.length === 1 ? "y" : "ies"} ` +
-          `past MAX_BUFFER_ENTRY_COUNT=${MAX_BUFFER_ENTRY_COUNT}; buffered turn data for those sessions was dropped`,
+          `past the session-entry cap (${this.maxSessionEntries}); buffered turn data for those sessions was dropped`,
       );
     }
   }
@@ -289,7 +299,37 @@ export class SmartBuffer {
   }
 
   private async saveUnlocked(): Promise<void> {
-    await this.persistence.persist(this.storage, this.state, (key) => this.peekEntry(key) ?? undefined);
+    const { handedOver, drainedTurns } = await this.persistence.persist(this.storage, this.state, (key) => this.peekEntry(key) ?? undefined);
+    // A drain tombstone: the turns the drain extracted leave this copy too,
+    // so a stale owner never extracts (or persists) them a second time.
+    for (const [key, drained] of drainedTurns) {
+      const entry = this.peekEntry(key);
+      if (!entry) continue;
+      entry.turns = subtractBufferTurns(entry.turns, drained);
+      if (entry.retainedTurns && entry.retainedTurns.length > 0) {
+        entry.retainedTurns = subtractBufferTurns(entry.retainedTurns, drained);
+        if (entry.retainedTurns.length === 0) delete entry.retainedTurns;
+      }
+      if (key === "default") this.state.turns = entry.turns;
+    }
+    if (handedOver.length === 0) return;
+    // A drain claim now owns these sessions' turns (durable in the claim
+    // file): drop the in-memory entries so this process cannot resurrect
+    // them. A later observe for the same key starts a fresh entry whose
+    // turns flow into the claim at the next handover.
+    const entries = this.state.entries;
+    if (!entries) return;
+    for (const key of handedOver) {
+      delete entries[key];
+      if (key === "default") {
+        this.state.turns = [];
+      }
+    }
+  }
+
+  /** Sync gate for the extraction queue: is this session claimed by a buffer drain? */
+  isSessionClaimed(key: string): boolean {
+    return this.storage.isBufferSessionClaimed?.(key) === true;
   }
 
   async save(): Promise<void> {
@@ -457,9 +497,9 @@ export class SmartBuffer {
       await this.loadUnlocked();
       if (this.peekEntry(bufferKey) === null) {
         this.makeRoomForEntryUnlocked();
-        if (Object.keys(this.state.entries ?? {}).length >= MAX_BUFFER_ENTRY_COUNT) {
+        if (Object.keys(this.state.entries ?? {}).length >= this.maxSessionEntries) {
           log.warn(
-            `buffer[${bufferKey}]: durable capture refused at MAX_BUFFER_ENTRY_COUNT=${MAX_BUFFER_ENTRY_COUNT}`,
+            `buffer[${bufferKey}]: durable capture refused at the session-entry cap (${this.maxSessionEntries})`,
           );
           return null;
         }
@@ -475,7 +515,7 @@ export class SmartBuffer {
     const entries = this.state.entries;
     if (!entries) return;
     const keys = Object.keys(entries);
-    if (keys.length < MAX_BUFFER_ENTRY_COUNT) return;
+    if (keys.length < this.maxSessionEntries) return;
     const byOldestActivity = (left: string, right: string): number =>
       this.entryActivityAt(entries[left] ?? { turns: [], lastExtractionAt: null, extractionCount: 0 }) -
       this.entryActivityAt(entries[right] ?? { turns: [], lastExtractionAt: null, extractionCount: 0 });
@@ -488,7 +528,7 @@ export class SmartBuffer {
       )
       .sort(byOldestActivity);
     for (const key of emptyRemovable) {
-      if (Object.keys(entries).length < MAX_BUFFER_ENTRY_COUNT) break;
+      if (Object.keys(entries).length < this.maxSessionEntries) break;
       delete entries[key];
       this.persistence.markDeleted(key);
     }

package/src/config.ts

@@ -1591,6 +1591,7 @@ export function parseConfig(
     ...parseSecurityConfig(cfg, rawOperatorConfig),
     bufferMaxTurns:
       typeof cfg.bufferMaxTurns === "number" ? cfg.bufferMaxTurns : 5,
+    bufferMaxSessions: parsePositiveInteger(cfg.bufferMaxSessions, "bufferMaxSessions") ?? 1000,
     bufferMaxMinutes:
       typeof cfg.bufferMaxMinutes === "number" ? cfg.bufferMaxMinutes : 15,
     // Surprise-gated buffer flush (issue #563, D-MEM). See types.ts for

package/src/index.ts

@@ -346,7 +346,7 @@ export { MeilisearchBackend } from "./search/meilisearch-backend.js";
 // ---------------------------------------------------------------------------
 
 export { buildEntityRecallSection } from "./entity-retrieval.js";
-export { isNamespacePolicyCovered, resolvePrincipal } from "./namespaces/principal.js";
+export { defaultNamespaceForPrincipal, isNamespacePolicyCovered, resolvePrincipal } from "./namespaces/principal.js";
 export {
   NamespaceCatalog,
   type NamespaceRecord,

package/src/orchestration/buffer-drain-gate.test.ts

@@ -0,0 +1,40 @@
+/**
+ * `skipClaimedSession` gate: a buffer without a claim registry never reports a
+ * claim (the legacy/test-double shape), and a claimed session settles as
+ * skipped without running an extraction.
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+import { skipClaimedSession, type ClaimAwareBuffer } from "./buffer-drain-gate.js";
+import type { ExtractionRunResult } from "./extraction-run.js";
+
+test("a buffer without isSessionClaimed is never treated as claimed", () => {
+  const settled: ExtractionRunResult[] = [];
+  const buffer: ClaimAwareBuffer = {};
+  const result = skipClaimedSession(buffer, "sess-1", (r) => settled.push(r));
+  assert.equal(result, false);
+  assert.deepEqual(settled, []);
+});
+
+test("an unclaimed session with the method proceeds", () => {
+  const settled: ExtractionRunResult[] = [];
+  const result = skipClaimedSession({ isSessionClaimed: () => false }, "sess-1", (r) => settled.push(r));
+  assert.equal(result, false);
+  assert.deepEqual(settled, []);
+});
+
+test("a claimed session settles as skipped without extracting", () => {
+  const settled: ExtractionRunResult[] = [];
+  const result = skipClaimedSession({ isSessionClaimed: () => true }, "sess-1", (r) => settled.push(r));
+  assert.equal(result, true);
+  assert.equal(settled.length, 1);
+  assert.equal(settled[0].status, "skipped");
+  assert.equal(settled[0].reason, "claimed_by_buffer_drain");
+});
+
+test("a buffer-less deps bundle (older host or test double) is never claimed", () => {
+  const settled: ExtractionRunResult[] = [];
+  const result = skipClaimedSession(undefined, "sess-1", (r) => settled.push(r));
+  assert.equal(result, false);
+  assert.deepEqual(settled, []);
+});