@remnic/core 10.0.60 → 10.0.61

package/dist/transfer/capsule-import.js

@@ -1,6 +1,6 @@
 import {
   importCapsule
-} from "../chunk-A3UFV4K3.js";
+} from "../chunk-JIYJIH5N.js";
 import "../chunk-564YP3DW.js";
 import "../chunk-M5GVCJSJ.js";
 import "../chunk-RBOJCG4T.js";
@@ -11,7 +11,7 @@ import "../chunk-7CT3AI52.js";
 import "../chunk-C64XATK7.js";
 import "../chunk-42JKGUFJ.js";
 import "../chunk-WEHSQBFR.js";
-import "../chunk-X7Y7WX73.js";
+import "../chunk-UVYI6VIX.js";
 import "../chunk-BJMBJZ2Y.js";
 import "../chunk-UKJAGEXH.js";
 import "../chunk-FP2373TW.js";

package/dist/transfer/export-okf.js

@@ -4,19 +4,21 @@ import {
   exportOkfBundle,
   firstHeading,
   parseIncludeStatus
-} from "../chunk-6BKSUA6P.js";
+} from "../chunk-SVTIWBSA.js";
 import {
   OKF_EXPORT_VERSION
 } from "../chunk-I7TR2OCU.js";
 import "../chunk-D24OXEPB.js";
 import "../chunk-3UXOZBHV.js";
-import "../chunk-I6UTOUBK.js";
+import "../chunk-N7RAABFM.js";
 import "../chunk-UHVXE24Y.js";
 import "../chunk-DM5QZ3YU.js";
 import "../chunk-WVEEVYMH.js";
+import "../chunk-JCL7RO2G.js";
 import "../chunk-G6OFEGUR.js";
-import "../chunk-JEDS2QYV.js";
-import "../chunk-VQ6H4DL6.js";
+import "../chunk-OH55F76C.js";
+import "../chunk-L334PSLW.js";
+import "../chunk-CYEPCZN5.js";
 import "../chunk-DLZGSZVC.js";
 import "../chunk-OVZIYLBZ.js";
 import "../chunk-EXYT52NR.js";
@@ -24,7 +26,6 @@ import "../chunk-DOJBV6WR.js";
 import "../chunk-PFUXPTBT.js";
 import "../chunk-WNEVEMJ3.js";
 import "../chunk-Y5NLBXPV.js";
-import "../chunk-CYEPCZN5.js";
 import "../chunk-TFA6HPOA.js";
 import "../chunk-F4TWWUMP.js";
 import "../chunk-72A4L5JJ.js";
@@ -68,6 +69,7 @@ import "../chunk-OR42ZI54.js";
 import "../chunk-23G5P7TA.js";
 import "../chunk-C64XATK7.js";
 import "../chunk-42JKGUFJ.js";
+import "../chunk-U7MIMS2Y.js";
 import "../chunk-AVVCPA7U.js";
 import "../chunk-I55KAVET.js";
 import "../chunk-L2EXJQJP.js";

package/dist/verified-recall.js

@@ -1,15 +1,17 @@
 import {
   compareVerifiedEpisodeResults,
   searchVerifiedEpisodes
-} from "./chunk-66CC6L6R.js";
+} from "./chunk-DP22K7IC.js";
 import "./chunk-B7RWBZXW.js";
-import "./chunk-I6UTOUBK.js";
+import "./chunk-N7RAABFM.js";
 import "./chunk-UHVXE24Y.js";
 import "./chunk-DM5QZ3YU.js";
 import "./chunk-WVEEVYMH.js";
+import "./chunk-JCL7RO2G.js";
 import "./chunk-G6OFEGUR.js";
-import "./chunk-JEDS2QYV.js";
-import "./chunk-VQ6H4DL6.js";
+import "./chunk-OH55F76C.js";
+import "./chunk-L334PSLW.js";
+import "./chunk-CYEPCZN5.js";
 import "./chunk-DLZGSZVC.js";
 import "./chunk-OVZIYLBZ.js";
 import "./chunk-EXYT52NR.js";
@@ -17,7 +19,6 @@ import "./chunk-DOJBV6WR.js";
 import "./chunk-PFUXPTBT.js";
 import "./chunk-WNEVEMJ3.js";
 import "./chunk-Y5NLBXPV.js";
-import "./chunk-CYEPCZN5.js";
 import "./chunk-TFA6HPOA.js";
 import "./chunk-F4TWWUMP.js";
 import "./chunk-72A4L5JJ.js";
@@ -61,6 +62,7 @@ import "./chunk-OR42ZI54.js";
 import "./chunk-23G5P7TA.js";
 import "./chunk-C64XATK7.js";
 import "./chunk-42JKGUFJ.js";
+import "./chunk-U7MIMS2Y.js";
 import "./chunk-AVVCPA7U.js";
 import "./chunk-I55KAVET.js";
 import "./chunk-L2EXJQJP.js";

package/dist/who-knows-cli.js

@@ -4,15 +4,17 @@ import {
   renderWhoKnows,
   renderWhoKnowsJson,
   renderWhoKnowsText
-} from "./chunk-PIVSUPF2.js";
-import "./chunk-J53IBVMF.js";
-import "./chunk-I6UTOUBK.js";
+} from "./chunk-IIUEHIQ2.js";
+import "./chunk-A4FZLM6Q.js";
+import "./chunk-N7RAABFM.js";
 import "./chunk-UHVXE24Y.js";
 import "./chunk-DM5QZ3YU.js";
 import "./chunk-WVEEVYMH.js";
+import "./chunk-JCL7RO2G.js";
 import "./chunk-G6OFEGUR.js";
-import "./chunk-JEDS2QYV.js";
-import "./chunk-VQ6H4DL6.js";
+import "./chunk-OH55F76C.js";
+import "./chunk-L334PSLW.js";
+import "./chunk-CYEPCZN5.js";
 import "./chunk-DLZGSZVC.js";
 import "./chunk-OVZIYLBZ.js";
 import "./chunk-EXYT52NR.js";
@@ -20,7 +22,6 @@ import "./chunk-DOJBV6WR.js";
 import "./chunk-PFUXPTBT.js";
 import "./chunk-WNEVEMJ3.js";
 import "./chunk-Y5NLBXPV.js";
-import "./chunk-CYEPCZN5.js";
 import "./chunk-TFA6HPOA.js";
 import "./chunk-F4TWWUMP.js";
 import "./chunk-72A4L5JJ.js";
@@ -64,6 +65,7 @@ import "./chunk-OR42ZI54.js";
 import "./chunk-23G5P7TA.js";
 import "./chunk-C64XATK7.js";
 import "./chunk-42JKGUFJ.js";
+import "./chunk-U7MIMS2Y.js";
 import "./chunk-AVVCPA7U.js";
 import "./chunk-I55KAVET.js";
 import "./chunk-L2EXJQJP.js";

package/dist/who-knows.js

@@ -9,14 +9,16 @@ import {
   loadWhoKnowsEntities,
   tokenizeTopic,
   validateWhoKnowsInput
-} from "./chunk-J53IBVMF.js";
-import "./chunk-I6UTOUBK.js";
+} from "./chunk-A4FZLM6Q.js";
+import "./chunk-N7RAABFM.js";
 import "./chunk-UHVXE24Y.js";
 import "./chunk-DM5QZ3YU.js";
 import "./chunk-WVEEVYMH.js";
+import "./chunk-JCL7RO2G.js";
 import "./chunk-G6OFEGUR.js";
-import "./chunk-JEDS2QYV.js";
-import "./chunk-VQ6H4DL6.js";
+import "./chunk-OH55F76C.js";
+import "./chunk-L334PSLW.js";
+import "./chunk-CYEPCZN5.js";
 import "./chunk-DLZGSZVC.js";
 import "./chunk-OVZIYLBZ.js";
 import "./chunk-EXYT52NR.js";
@@ -24,7 +26,6 @@ import "./chunk-DOJBV6WR.js";
 import "./chunk-PFUXPTBT.js";
 import "./chunk-WNEVEMJ3.js";
 import "./chunk-Y5NLBXPV.js";
-import "./chunk-CYEPCZN5.js";
 import "./chunk-TFA6HPOA.js";
 import "./chunk-F4TWWUMP.js";
 import "./chunk-72A4L5JJ.js";
@@ -68,6 +69,7 @@ import "./chunk-OR42ZI54.js";
 import "./chunk-23G5P7TA.js";
 import "./chunk-C64XATK7.js";
 import "./chunk-42JKGUFJ.js";
+import "./chunk-U7MIMS2Y.js";
 import "./chunk-AVVCPA7U.js";
 import "./chunk-I55KAVET.js";
 import "./chunk-L2EXJQJP.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "10.0.60",
+  "version": "10.0.61",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -1900,6 +1900,16 @@
       "remnic-source": "./src/orchestration/maintenance.ts",
       "import": "./dist/orchestration/maintenance.js"
     },
+    "./orchestration/buffer-drain-runner": {
+      "types": "./dist/orchestration/buffer-drain-runner.d.ts",
+      "remnic-source": "./src/orchestration/buffer-drain-runner.ts",
+      "import": "./dist/orchestration/buffer-drain-runner.js"
+    },
+    "./orchestration/buffer-drain-runner.js": {
+      "types": "./dist/orchestration/buffer-drain-runner.d.ts",
+      "remnic-source": "./src/orchestration/buffer-drain-runner.ts",
+      "import": "./dist/orchestration/buffer-drain-runner.js"
+    },
     "./orchestration/compression-guideline-coordinator": {
       "types": "./dist/orchestration/compression-guideline-coordinator.d.ts",
       "remnic-source": "./src/orchestration/compression-guideline-coordinator.ts",
@@ -2780,6 +2790,26 @@
       "remnic-source": "./src/storage.ts",
       "import": "./dist/storage.js"
     },
+    "./storage/buffer-drain-claims": {
+      "types": "./dist/storage/buffer-drain-claims.d.ts",
+      "remnic-source": "./src/storage/buffer-drain-claims.ts",
+      "import": "./dist/storage/buffer-drain-claims.js"
+    },
+    "./storage/buffer-drain-claims.js": {
+      "types": "./dist/storage/buffer-drain-claims.d.ts",
+      "remnic-source": "./src/storage/buffer-drain-claims.ts",
+      "import": "./dist/storage/buffer-drain-claims.js"
+    },
+    "./storage/buffer-session-files": {
+      "types": "./dist/storage/buffer-session-files.d.ts",
+      "remnic-source": "./src/storage/buffer-session-files.ts",
+      "import": "./dist/storage/buffer-session-files.js"
+    },
+    "./storage/buffer-session-files.js": {
+      "types": "./dist/storage/buffer-session-files.d.ts",
+      "remnic-source": "./src/storage/buffer-session-files.ts",
+      "import": "./dist/storage/buffer-session-files.js"
+    },
     "./store-contract": {
       "types": "./dist/store-contract.d.ts",
       "remnic-source": "./src/store-contract.ts",
@@ -3346,7 +3376,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^10.0.60"
+    "@remnic/coding-graph": "^10.0.61"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

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-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-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 (