@remnic/core 10.0.83 → 10.0.85

package/src/orchestration/fact-dedup-window.ts

@@ -19,9 +19,6 @@ import { log } from "../logger.js";
  * OUTSIDE the window exactly like the consolidation LLM call stays outside
  * commitConsolidatedProfile.
  */
-export interface FactDedupProbe {
-  hasContentHashDedup(storage: StorageManager, key: string): Promise<boolean>;
-}
 
 interface FactDedupMatchOptions {
   readonly category: string;
@@ -55,22 +52,18 @@ function matchesActiveConnectorDuplicate(memory: MemoryFile, opts: FactDedupMatc
  * silently drop content.
  */
 export async function confirmActiveFactDuplicate(
-  probe: FactDedupProbe,
   storage: StorageManager,
   opts: FactDedupMatchOptions,
 ): Promise<boolean> {
-  let needsCorpusConfirm: boolean;
   try {
-    if (!(await probe.hasContentHashDedup(storage, opts.contentHashDedupKey))) {
-      if (await storage.isFactContentHashAuthoritative()) return false;
-      needsCorpusConfirm = true;
-    } else {
-      needsCorpusConfirm = true;
-    }
+    // One lookup returns the MISS together with the authority behind it, so a
+    // stale MISS is never paired with authority from another moment: any
+    // second read of authority can rebuild the index and bless it (#3312).
+    const lookup = await storage.lookupContentHash(opts.contentHashDedupKey);
+    if (!lookup.present && lookup.authoritative) return false;
   } catch {
     // Dedup lookup failed (e.g. the authoritative rebuild could not run). Do
     // NOT fail-open into a possible duplicate — confirm against the corpus.
-    needsCorpusConfirm = true;
   }
   try {
     // #2016 cold-tier finding: the authoritative content-hash rebuild unions

package/src/orchestration/full-corpus-heap-guard.test.ts

@@ -0,0 +1,52 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { fullCorpusHeapPressure } from "./full-corpus-heap-guard.js";
+
+test("fullCorpusHeapPressure postpones only when usage is strictly above the limit", () => {
+  assert.deepEqual(fullCorpusHeapPressure({ used_heap_size: 61, heap_size_limit: 100 }, 0.6), {
+    postpone: true,
+    ratio: 0.61,
+  });
+  assert.deepEqual(fullCorpusHeapPressure({ used_heap_size: 60, heap_size_limit: 100 }, 0.6), {
+    postpone: false,
+    ratio: 0.6,
+  });
+  assert.deepEqual(fullCorpusHeapPressure({ used_heap_size: 59, heap_size_limit: 100 }, 0.6), {
+    postpone: false,
+    ratio: 0.59,
+  });
+});
+
+test("fullCorpusHeapPressure never fires at limit ratio 1", () => {
+  const pressure = fullCorpusHeapPressure({ used_heap_size: 100, heap_size_limit: 100 }, 1);
+  assert.equal(pressure.postpone, false);
+  assert.equal(pressure.ratio, 1);
+});
+
+test("fullCorpusHeapPressure ignores unusable statistics or limits", () => {
+  assert.deepEqual(fullCorpusHeapPressure({ used_heap_size: 90, heap_size_limit: 0 }, 0.6), {
+    postpone: false,
+    ratio: 0,
+  });
+  assert.deepEqual(fullCorpusHeapPressure({ used_heap_size: 90, heap_size_limit: -1 }, 0.6), {
+    postpone: false,
+    ratio: 0,
+  });
+  assert.deepEqual(fullCorpusHeapPressure({ used_heap_size: Number.NaN, heap_size_limit: 100 }, 0.6), {
+    postpone: false,
+    ratio: 0,
+  });
+  assert.deepEqual(fullCorpusHeapPressure({ used_heap_size: -1, heap_size_limit: 100 }, 0.6), {
+    postpone: false,
+    ratio: 0,
+  });
+  assert.deepEqual(fullCorpusHeapPressure({ used_heap_size: 90, heap_size_limit: 100 }, Number.NaN), {
+    postpone: false,
+    ratio: 0,
+  });
+  assert.deepEqual(
+    fullCorpusHeapPressure({ used_heap_size: Number.POSITIVE_INFINITY, heap_size_limit: 100 }, 0.6),
+    { postpone: false, ratio: 0 },
+  );
+});

package/src/projection-rebuild-config.test.ts

@@ -0,0 +1,79 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  DEFAULT_PROJECTION_REBUILD_HEAP_USAGE_LIMIT,
+  parseProjectionRebuildHeapUsageLimit,
+  parseProjectionRebuildScheduleConfig,
+} from "./projection-rebuild-config.js";
+
+const parseIntegerAtLeast: Parameters<typeof parseProjectionRebuildScheduleConfig>[1] = (
+  value,
+  fallback,
+  min,
+  keyName,
+) => {
+  if (value === undefined || value === null) return fallback;
+  const n = Number(value);
+  if (!Number.isFinite(n) || !Number.isInteger(n) || n < min) {
+    throw new Error(`${keyName} must be an integer >= ${min}; got ${JSON.stringify(value)}`);
+  }
+  return n;
+};
+
+test("parseProjectionRebuildHeapUsageLimit defaults and accepts (0, 1]", () => {
+  assert.equal(parseProjectionRebuildHeapUsageLimit(undefined), DEFAULT_PROJECTION_REBUILD_HEAP_USAGE_LIMIT);
+  assert.equal(parseProjectionRebuildHeapUsageLimit(null), DEFAULT_PROJECTION_REBUILD_HEAP_USAGE_LIMIT);
+  assert.equal(DEFAULT_PROJECTION_REBUILD_HEAP_USAGE_LIMIT, 0.6);
+  assert.equal(parseProjectionRebuildHeapUsageLimit(0.5), 0.5);
+  assert.equal(parseProjectionRebuildHeapUsageLimit("0.75"), 0.75);
+  assert.equal(parseProjectionRebuildHeapUsageLimit(1), 1);
+});
+
+test("parseProjectionRebuildHeapUsageLimit rejects 0, negatives, and non-numbers", () => {
+  assert.throws(() => parseProjectionRebuildHeapUsageLimit(0), /projectionRebuildHeapUsageLimit/);
+  assert.throws(() => parseProjectionRebuildHeapUsageLimit(-0.1), /projectionRebuildHeapUsageLimit/);
+  assert.throws(() => parseProjectionRebuildHeapUsageLimit(1.01), /projectionRebuildHeapUsageLimit/);
+  assert.throws(() => parseProjectionRebuildHeapUsageLimit(Number.NaN), /projectionRebuildHeapUsageLimit/);
+  assert.throws(() => parseProjectionRebuildHeapUsageLimit("abc"), /projectionRebuildHeapUsageLimit/);
+  assert.throws(() => parseProjectionRebuildHeapUsageLimit({}), /projectionRebuildHeapUsageLimit/);
+});
+
+test("parseProjectionRebuildScheduleConfig defaults and coerces booleans", () => {
+  const defaults = parseProjectionRebuildScheduleConfig({}, parseIntegerAtLeast);
+  assert.equal(defaults.projectionRebuildEnabled, true);
+  assert.equal(defaults.projectionRebuildIntervalMs, 6 * 60 * 60 * 1000);
+  assert.equal(defaults.projectionRebuildHeapUsageLimit, 0.6);
+
+  const disabled = parseProjectionRebuildScheduleConfig(
+    { projectionRebuildEnabled: "false", projectionRebuildIntervalMs: 120_000, projectionRebuildHeapUsageLimit: 0.4 },
+    parseIntegerAtLeast,
+  );
+  assert.equal(disabled.projectionRebuildEnabled, false);
+  assert.equal(disabled.projectionRebuildIntervalMs, 120_000);
+  assert.equal(disabled.projectionRebuildHeapUsageLimit, 0.4);
+});
+
+test("parseProjectionRebuildScheduleConfig floors the interval via the integer parser", () => {
+  assert.throws(
+    () =>
+      parseProjectionRebuildScheduleConfig(
+        { projectionRebuildIntervalMs: 59_999 },
+        parseIntegerAtLeast,
+      ),
+    /projectionRebuildIntervalMs/,
+  );
+  assert.throws(
+    () =>
+      parseProjectionRebuildScheduleConfig(
+        { projectionRebuildIntervalMs: 90_000.5 },
+        parseIntegerAtLeast,
+      ),
+    /projectionRebuildIntervalMs/,
+  );
+  const ok = parseProjectionRebuildScheduleConfig(
+    { projectionRebuildIntervalMs: 60_000 },
+    parseIntegerAtLeast,
+  );
+  assert.equal(ok.projectionRebuildIntervalMs, 60_000);
+});

package/src/storage/buffer-drain-claims.test.ts

@@ -5,10 +5,11 @@ import { hostname } from "node:os";
 import path from "node:path";
 import test from "node:test";
 
-import { BufferDrainClaims, type DrainLease } from "./buffer-drain-claims.js";
-import { bufferSessionFileName } from "./buffer-session-files.js";
+import { BufferDrainClaims, type AckOutcome, type DrainLease } from "./buffer-drain-claims.js";
+import { BufferSessionFiles, bufferSessionFileName } from "./buffer-session-files.js";
+import { ClaimBufferStorage } from "../orchestration/buffer-drain-runner.js";
 import type { BufferEntryState } from "../types.js";
-
+import { withHeldFileLock } from "../utils/serialize-mutations.js";
 /** Plain-file BufferFileIo double: claims logic is file-atomic, not crypto-aware. */
 function plainIo() {
   return {
@@ -25,6 +26,7 @@ function plainIo() {
   };
 }
 
+
 function turn(content: string, timestamp = "2026-11-01T00:00:00.000Z") {
   return { role: "user" as const, content, timestamp, sessionKey: "sess-1" };
 }
@@ -146,6 +148,43 @@ test("mergeIntoClaim appends unseen turns and dedupes turns already claimed", as
   }
 });
 
+test("claim merge and reload preserve duplicate occurrence counts after partial extraction", async () => {
+  const s = setup();
+  try {
+    const same = turn("duplicate pending turn");
+    s.seedSession("sess-1", entry([same, same]));
+    await s.claims.claimFromSessionFile("sess-1", makeLease());
+    const initial = await s.claims.load("sess-1");
+    assert.ok(initial);
+
+    await s.claims.writeEntry("sess-1", "worker-1", entry([same]), initial.entry);
+    assert.deepEqual(await s.claims.drainedTurns("sess-1"), { turns: [same], retainedTurns: [] });
+    await s.claims.mergeIntoClaim("sess-1", entry([same, same]));
+
+    const reloaded = new BufferDrainClaims(s.stateDir, plainIo());
+    assert.deepEqual((await reloaded.load("sess-1"))?.entry.turns, [same]);
+    assert.deepEqual(await reloaded.drainedTurns("sess-1"), { turns: [same], retainedTurns: [] });
+  } finally {
+    s.cleanup();
+  }
+});
+
+test("claim merge and reload retain every pending duplicate occurrence", async () => {
+  const s = setup();
+  try {
+    const initial = turn("initial pending turn");
+    const duplicate = turn("new duplicate", "2026-11-01T00:01:00.000Z");
+    s.seedSession("sess-1", entry([initial]));
+    await s.claims.claimFromSessionFile("sess-1", makeLease());
+    await s.claims.mergeIntoClaim("sess-1", entry([initial, duplicate, duplicate]));
+
+    const reloaded = new BufferDrainClaims(s.stateDir, plainIo());
+    assert.deepEqual((await reloaded.load("sess-1"))?.entry.turns, [initial, duplicate, duplicate]);
+  } finally {
+    s.cleanup();
+  }
+});
+
 test("mergeIntoClaim also dedupes retainedTurns", async () => {
   const s = setup();
   try {
@@ -160,6 +199,24 @@ test("mergeIntoClaim also dedupes retainedTurns", async () => {
   }
 });
 
+test("mergeIntoClaim preserves retained work when the same identity drained from active turns", async () => {
+  const s = setup();
+  try {
+    const same = turn("source identity");
+    s.seedSession("sess-1", entry([same]));
+    await s.claims.claimFromSessionFile("sess-1", makeLease());
+    const claimed = await s.claims.load("sess-1");
+    assert.ok(claimed);
+    await s.claims.writeEntry("sess-1", "worker-1", entry([]), claimed.entry);
+
+    await s.claims.mergeIntoClaim("sess-1", { ...entry([]), retainedTurns: [same] });
+
+    assert.deepEqual((await s.claims.load("sess-1"))?.entry.retainedTurns, [same]);
+  } finally {
+    s.cleanup();
+  }
+});
+
 test("writeEntry replaces the claim content; ack keeps a tombstone the owner consumes", async () => {
   const s = setup();
   try {
@@ -167,7 +224,7 @@ test("writeEntry replaces the claim content; ack keeps a tombstone the owner con
     await s.claims.claimFromSessionFile("sess-1", makeLease());
     await s.claims.writeEntry("sess-1", "worker-1", entry([turn("b")]));
     assert.deepEqual((await s.claims.load("sess-1"))?.entry.turns.map((t) => t.content), ["b"]);
-    assert.deepEqual((await s.claims.drainedTurns("sess-1")).map((t) => t.content), ["a"], "extracted turns are recorded");
+    assert.deepEqual((await s.claims.drainedTurns("sess-1")).turns.map((t) => t.content), ["a"], "extracted turns are recorded");
     assert.equal(await s.claims.ack("sess-1", "not-the-owner"), "busy");
     assert.equal(await s.claims.ack("sess-1", "worker-1"), "not_empty");
     await s.claims.writeEntry("sess-1", "worker-1", entry([]));
@@ -175,7 +232,7 @@ test("writeEntry replaces the claim content; ack keeps a tombstone the owner con
     // The claim file stays as a tombstone: a live owner with a stale copy
     // subtracts the drained turns instead of writing them back.
     assert.equal(s.claims.isClaimed("sess-1"), true);
-    assert.deepEqual((await s.claims.drainedTurns("sess-1")).map((t) => t.content), ["a", "b"]);
+    assert.deepEqual((await s.claims.drainedTurns("sess-1")).turns.map((t) => t.content), ["a", "b"]);
     assert.equal(existsSync(s.claims.leasePathForTest("sess-1")), false, "the lease is released");
     await s.claims.release("sess-1");
     assert.equal(s.claims.isClaimed("sess-1"), false);
@@ -184,6 +241,145 @@ test("writeEntry replaces the claim content; ack keeps a tombstone the owner con
   }
 });
 
+test("a tombstone subtracts only its original list when a stale entry has an identical retained copy", async () => {
+  const s = setup();
+  try {
+    const same = turn("one source identity");
+    s.seedSession("sess-1", entry([same]));
+    await s.claims.claimFromSessionFile("sess-1", makeLease());
+    const claim = await s.claims.load("sess-1");
+    assert.ok(claim);
+    await s.claims.writeEntry("sess-1", "worker-1", entry([]), claim.entry);
+    assert.equal(await s.claims.ack("sess-1", "worker-1"), "acked");
+
+    const files = new BufferSessionFiles(s.stateDir, plainIo());
+    const staleLiveEntry: BufferEntryState = {
+      ...entry([same]),
+      retainedTurns: [same],
+    };
+    const outcome = await files.save("sess-1", staleLiveEntry);
+    assert.deepEqual(outcome.drainedTurns, { turns: [same], retainedTurns: [] });
+    const persisted = JSON.parse(readFileSync(s.sessionFile("sess-1"), "utf8"));
+    assert.deepEqual(persisted.turns, [], "the extracted active occurrence is removed");
+    assert.deepEqual(persisted.retainedTurns, [same], "an identical retained occurrence is not removed by active provenance");
+  } finally {
+    s.cleanup();
+  }
+});
+
+test("adopt rejects a reused owner id from a different process identity", async () => {
+  const s = setup();
+  try {
+    s.seedSession("sess-1", entry([turn("a")]));
+    const original = { ...makeLease("reused-owner"), pid: process.pid };
+    assert.equal(await s.claims.claimFromSessionFile("sess-1", original), "claimed");
+
+    const outcome = await s.claims.adopt("sess-1", {
+      ...makeLease("reused-owner"),
+      pid: process.pid + 1,
+    });
+
+    assert.equal(outcome, "busy");
+    assert.equal(JSON.parse(readFileSync(s.claims.leasePathForTest("sess-1"), "utf8")).pid, process.pid);
+  } finally {
+    s.cleanup();
+  }
+});
+
+test("adopt takes over an expired lease even when the owner id is reused by another process", async () => {
+  const s = setup();
+  try {
+    s.seedSession("sess-1", entry([turn("a")]));
+    const expired = { ...makeLease("reused-owner"), heartbeatAt: "2026-11-01T00:00:00.000Z" };
+    assert.equal(await s.claims.claimFromSessionFile("sess-1", expired), "claimed");
+
+    const outcome = await s.claims.adopt("sess-1", { ...makeLease("reused-owner"), pid: process.pid + 1 });
+
+    assert.equal(outcome, "adopted");
+    assert.equal(JSON.parse(readFileSync(s.claims.leasePathForTest("sess-1"), "utf8")).pid, process.pid + 1);
+  } finally {
+    s.cleanup();
+  }
+});
+
+test("reused owner IDs cannot authorize stale operations from another process", async () => {
+  const s = setup();
+  try {
+    s.seedSession("sess-1", entry([turn("pending")]));
+    assert.equal(await s.claims.claimFromSessionFile("sess-1", makeLease("reused-owner")), "claimed");
+    const claim = await s.claims.load("sess-1");
+    assert.ok(claim);
+    const replacement = { ...makeLease("reused-owner"), pid: process.pid + 1 };
+    writeFileSync(s.claims.leasePathForTest("sess-1"), JSON.stringify(replacement));
+
+    await assert.rejects(
+      s.claims.writeEntry("sess-1", "reused-owner", entry([]), claim.entry),
+      /no longer owned/,
+    );
+    assert.equal(await s.claims.heartbeat("sess-1", "reused-owner", 60_000), "lost");
+    assert.equal(await s.claims.ack("sess-1", "reused-owner"), "busy");
+    await s.claims.releaseLease("sess-1", "reused-owner");
+    assert.equal(await s.claims.drainedTurnsForOwner("sess-1", "reused-owner"), null);
+    assert.equal(JSON.parse(readFileSync(s.claims.leasePathForTest("sess-1"), "utf8")).pid, replacement.pid);
+    assert.deepEqual((await s.claims.load("sess-1"))?.entry.turns, [turn("pending")]);
+  } finally {
+    s.cleanup();
+  }
+});
+
+test("releaseLease preserves a replacement lease acquired under the claim lock", async () => {
+  const stateDir = mkdtempSync(path.join(os.tmpdir(), "remnic-drain-release-race-"));
+  const claims = new BufferDrainClaims(stateDir, plainIo());
+  const key = "sess-1";
+  const sessionPath = path.join(stateDir, "buffer", bufferSessionFileName(key));
+  const claimPath = path.join(stateDir, "buffer", "drain", bufferSessionFileName(key));
+  let release: Promise<void> | undefined;
+  try {
+    mkdirSync(path.dirname(sessionPath), { recursive: true });
+    writeFileSync(sessionPath, JSON.stringify({ key, ...entry([turn("a")]) }));
+    assert.equal(await claims.claimFromSessionFile(key, makeLease("owner-one")), "claimed");
+
+    await withHeldFileLock(`${claimPath}.lock`, { staleMs: 5_000 }, async (acquired) => {
+      assert.equal(acquired, true);
+      release = claims.releaseLease(key, "owner-one");
+      writeFileSync(claims.leasePathForTest(key), JSON.stringify(makeLease("owner-two")));
+    });
+    await release;
+
+    assert.equal(JSON.parse(readFileSync(claims.leasePathForTest(key), "utf8")).ownerId, "owner-two");
+  } finally {
+    rmSync(stateDir, { recursive: true, force: true });
+  }
+});
+
+test("ack preserves a replacement lease acquired under the claim lock", async () => {
+  const stateDir = mkdtempSync(path.join(os.tmpdir(), "remnic-drain-ack-race-"));
+  const claims = new BufferDrainClaims(stateDir, plainIo());
+  const key = "sess-1";
+  const sessionPath = path.join(stateDir, "buffer", bufferSessionFileName(key));
+  const claimPath = path.join(stateDir, "buffer", "drain", bufferSessionFileName(key));
+  let ack: Promise<AckOutcome> | undefined;
+  try {
+    mkdirSync(path.dirname(sessionPath), { recursive: true });
+    writeFileSync(sessionPath, JSON.stringify({ key, ...entry([turn("a")]) }));
+    assert.equal(await claims.claimFromSessionFile(key, makeLease("owner-one")), "claimed");
+    const claimed = await claims.load(key);
+    assert.ok(claimed);
+    await claims.writeEntry(key, "owner-one", entry([]), claimed.entry);
+
+    await withHeldFileLock(`${claimPath}.lock`, { staleMs: 5_000 }, async (acquired) => {
+      assert.equal(acquired, true);
+      ack = claims.ack(key, "owner-one");
+      writeFileSync(claims.leasePathForTest(key), JSON.stringify(makeLease("owner-two")));
+    });
+    await ack;
+
+    assert.equal(JSON.parse(readFileSync(claims.leasePathForTest(key), "utf8")).ownerId, "owner-two");
+  } finally {
+    rmSync(stateDir, { recursive: true, force: true });
+  }
+});
+
 test("releaseLease keeps the claim content so a later run resumes it", async () => {
   const s = setup();
   try {
@@ -396,7 +592,7 @@ test("writeEntry rejects progress from a drainer that lost the lease", async ()
       /no longer owned/,
     );
     await s.claims.writeEntry("sess-1", "worker-two", entry([]), loaded.entry);
-    assert.deepEqual((await s.claims.drainedTurns("sess-1")).map((t) => t.content), ["t1"], "the new owner's progress lands");
+    assert.deepEqual((await s.claims.drainedTurns("sess-1")).turns.map((t) => t.content), ["t1"], "the new owner's progress lands");
   } finally {
     s.cleanup();
   }
@@ -415,6 +611,7 @@ test("a retained turn the drainer extracted is tombstoned, not dropped", async (
     const claim = await s.claims.load("sess-1");
     assert.ok(claim);
     assert.deepEqual((claim.drainedRetained ?? []).map((t) => t.content), ["r1"], "the extracted retained copy is recorded");
+    assert.deepEqual((await s.claims.drainedTurns("sess-1")).retainedTurns.map((t) => t.content), ["r1"]);
     // A live owner still holding a stale retained copy cannot resurrect it.
     await s.claims.mergeIntoClaim("sess-1", { turns: [], retainedTurns: [turn("r1")], lastExtractionAt: null, extractionCount: 0 });
     const after = await s.claims.load("sess-1");
@@ -446,3 +643,130 @@ test("a turn the drainer retained for retry is not recorded as drained", async (
     s.cleanup();
   }
 });
+
+test("a turn moved to retained and extracted from there cannot return from a stale active copy", async () => {
+  const s = setup();
+  try {
+    const moved = turn("moved to retained, then extracted");
+    s.seedSession("sess-1", entry([moved]));
+    await s.claims.claimFromSessionFile("sess-1", makeLease());
+    const loaded = await s.claims.load("sess-1");
+    assert.ok(loaded);
+    await s.claims.writeEntry("sess-1", "worker-1", { ...entry([]), retainedTurns: [moved] }, loaded.entry);
+    const reloaded = await s.claims.load("sess-1");
+    assert.ok(reloaded);
+    await s.claims.writeEntry("sess-1", "worker-1", entry([]), reloaded.entry);
+
+    // A live owner still holds the turn in its active list and hands it over.
+    await s.claims.mergeIntoClaim("sess-1", entry([moved]));
+
+    const claim = await s.claims.load("sess-1");
+    assert.deepEqual(claim?.entry.turns, [], "the extracted turn is not pending again");
+    assert.deepEqual(claim?.entry.retainedTurns ?? [], []);
+  } finally {
+    s.cleanup();
+  }
+});
+
+test("a turn moved to active and extracted from there cannot return from a stale retained copy", async () => {
+  const s = setup();
+  try {
+    const moved = turn("moved to active, then extracted");
+    s.seedSession("sess-1", { ...entry([]), retainedTurns: [moved] });
+    await s.claims.claimFromSessionFile("sess-1", makeLease());
+    const loaded = await s.claims.load("sess-1");
+    assert.ok(loaded);
+    await s.claims.writeEntry("sess-1", "worker-1", entry([moved]), loaded.entry);
+    const reloaded = await s.claims.load("sess-1");
+    assert.ok(reloaded);
+    await s.claims.writeEntry("sess-1", "worker-1", entry([]), reloaded.entry);
+
+    await s.claims.mergeIntoClaim("sess-1", { ...entry([]), retainedTurns: [moved] });
+
+    const claim = await s.claims.load("sess-1");
+    assert.deepEqual(claim?.entry.turns, []);
+    assert.deepEqual(claim?.entry.retainedTurns ?? [], [], "the extracted turn is not pending again");
+  } finally {
+    s.cleanup();
+  }
+});
+
+test("a turn that moves to retained and back is still tombstoned in its original list", async () => {
+  const s = setup();
+  try {
+    const roundTrip = turn("moves out and back");
+    s.seedSession("sess-1", entry([roundTrip]));
+    await s.claims.claimFromSessionFile("sess-1", makeLease());
+    const loaded = await s.claims.load("sess-1");
+    assert.ok(loaded);
+    await s.claims.writeEntry("sess-1", "worker-1", { ...entry([]), retainedTurns: [roundTrip] }, loaded.entry);
+    const retained = await s.claims.load("sess-1");
+    assert.ok(retained);
+    await s.claims.writeEntry("sess-1", "worker-1", entry([roundTrip]), retained.entry);
+    const back = await s.claims.load("sess-1");
+    assert.ok(back);
+    await s.claims.writeEntry("sess-1", "worker-1", entry([]), back.entry);
+
+    assert.deepEqual(await s.claims.drainedTurns("sess-1"), { turns: [roundTrip], retainedTurns: [] });
+  } finally {
+    s.cleanup();
+  }
+});
+
+test("mergeIntoClaim keeps the claim's own pending occurrence after a partial extraction", async () => {
+  const s = setup();
+  try {
+    const same = turn("duplicate pending turn");
+    s.seedSession("sess-1", entry([same, same]));
+    await s.claims.claimFromSessionFile("sess-1", makeLease());
+    const loaded = await s.claims.load("sess-1");
+    assert.ok(loaded);
+    await s.claims.writeEntry("sess-1", "worker-1", entry([same]), loaded.entry);
+
+    // The live owner hands over a copy that adds nothing new.
+    await s.claims.mergeIntoClaim("sess-1", entry([]));
+
+    assert.deepEqual((await s.claims.load("sess-1"))?.entry.turns, [same], "the remainder is not subtracted a second time");
+  } finally {
+    s.cleanup();
+  }
+});
+
+test("repeated progress writes record each extracted occurrence once", async () => {
+  const s = setup();
+  try {
+    const same = turn("duplicate pending turn");
+    s.seedSession("sess-1", entry([same, same]));
+    await s.claims.claimFromSessionFile("sess-1", makeLease());
+    const loaded = await s.claims.load("sess-1");
+    assert.ok(loaded);
+    // The drain runner's buffer keeps ONE snapshot of the claim for the whole run.
+    const storage = new ClaimBufferStorage(s.claims, "sess-1", "worker-1", loaded.entry);
+    await storage.saveBufferSession("sess-1", entry([same]));
+    await storage.saveBufferSession("sess-1", entry([]));
+
+    assert.deepEqual(await s.claims.drainedTurns("sess-1"), { turns: [same, same], retainedTurns: [] });
+  } finally {
+    s.cleanup();
+  }
+});
+
+test("a late arrival of an ambiguous identity does not replace a source occurrence", async () => {
+  const s = setup();
+  try {
+    const same = turn("same identity in both lists");
+    s.seedSession("sess-1", { ...entry([same]), retainedTurns: [same] });
+    await s.claims.claimFromSessionFile("sess-1", makeLease());
+    const loaded = await s.claims.load("sess-1");
+    assert.ok(loaded);
+    await s.claims.mergeIntoClaim("sess-1", entry([same, same]));
+
+    await s.claims.writeEntry("sess-1", "worker-1", { ...entry([]), retainedTurns: [same] }, loaded.entry);
+
+    const claim = await s.claims.load("sess-1");
+    assert.deepEqual(claim?.entry.turns, [same, same], "the source occurrence and the late arrival both stay pending");
+    assert.deepEqual(claim?.entry.retainedTurns, [same]);
+  } finally {
+    s.cleanup();
+  }
+});