@remnic/core 10.0.69 → 10.0.71

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

@@ -10,22 +10,28 @@
 //      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 { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import { hostname } from "node:os";
 import path from "node:path";
 import test from "node:test";
 
+import type { BufferStorage } from "./buffer-persistence.js";
+import type { SessionObserverState } from "./session-observer-state.js";
+import type { TranscriptManager } from "./transcript.js";
 import { SmartBuffer } from "./buffer.js";
+import { parseConfig } from "./config.js";
+import { ClaimBufferStorage } from "./orchestration/buffer-drain-runner.js";
+import { ExtractionDrain } from "./orchestration/extraction-drain.js";
 import type { ExtractionPreemptHandle } from "./orchestration/extraction-queue-coordinator.js";
-import { BufferSessionFiles } from "./storage/buffer-session-files.js";
+import { ExtractionQueueCoordinator } from "./orchestration/extraction-queue-coordinator.js";
+import type { ExtractionRunResult } from "./orchestration/extraction-run.js";
+import { TurnIngestionCoordinator, type TurnIngestionDeps } from "./orchestration/turn-ingestion.js";
 import { BufferDrainClaims, type DrainLease } from "./storage/buffer-drain-claims.js";
-import type { BufferStorage } from "./buffer-persistence.js";
+import { bufferSessionFileName } from "./storage/buffer-session-files.js";
+import { BufferSessionFiles } from "./storage/buffer-session-files.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 {
@@ -85,18 +91,37 @@ function makeHarness(): Harness {
     buffer,
     claims,
     storage,
-    lease: { ownerId: "worker-1", pid: process.pid, host: hostname(), acquiredAt: now, heartbeatAt: now, leaseMs: 60_000 },
+    lease: {
+      ownerId: "worker-1",
+      pid: process.pid,
+      host: hostname(),
+      acquiredAt: now,
+      heartbeatAt: now,
+      leaseMs: 60_000,
+    },
     cleanup: () => rmSync(stateDir, { recursive: true, force: true }),
   };
 }
 
+/**
+ * SAFETY: the harness stubs two observers this scenario never reads; the cast
+ * re-types the stub to the contract the coordinator declares.
+ */
+function asStub<T>(cause: unknown): T {
+  // SAFETY: the caller supplies the stub shape the scenario exercises.
+  return cause as T;
+}
+
 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");
+    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");
@@ -112,7 +137,7 @@ test("a claimed session's save hands over and evicts instead of writing a sessio
     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",
+      "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");
@@ -126,11 +151,11 @@ test("a claimed session's save hands over and evicts instead of writing a sessio
     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",
+      "post-handover observes keep flowing into the claim"
     );
     assert.deepEqual(
       readdirSync(path.join(h.stateDir, "buffer")).filter((name) => name.endsWith(".json")),
-      [],
+      []
     );
   } finally {
     h.cleanup();
@@ -148,11 +173,14 @@ test("handover of the default key clears the legacy top-level mirror", async ()
     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"]);
+    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();
@@ -200,15 +228,20 @@ function gateFixture(isClaimed: boolean) {
         void fn().catch(() => {});
         return true;
       },
-      runPreemptable: (_preempt: ExtractionPreemptHandle | undefined, _preemptable: boolean, parent: AbortSignal | undefined, fn: (signal: AbortSignal) => Promise<void>) => fn(parent ?? new AbortController().signal),
+      runPreemptable: (
+        _preempt: ExtractionPreemptHandle | undefined,
+        _preemptable: boolean,
+        parent: AbortSignal | undefined,
+        fn: (signal: AbortSignal) => Promise<void>
+      ) => fn(parent ?? new AbortController().signal),
     },
     extractionWindowBudgetChars: () => 500,
     getStorage: async () => ({ saveDroppedExtractionChunk: async () => "/dropped" }),
     shouldQueueExtraction: () => true,
-    runExtraction: (async (turns: BufferTurn[]) => {
+    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.
@@ -285,8 +318,12 @@ test("the owner keeps the claim while a drain is still running on it", async ()
       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");
+    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.
@@ -305,3 +342,311 @@ test("the owner keeps the claim while a drain is still running on it", async ()
     h.cleanup();
   }
 });
+
+// ── In-process claim drain: isolated per-task execution (no global swap) ───
+
+test("claim-backed queue tasks drain their own claims without a global buffer swap", async () => {
+  const h = makeHarness();
+  try {
+    await h.buffer.load();
+    const t0 = "2026-11-01T00:00:00.000Z";
+    await h.buffer.addTurn("sess-a", turn("a1", "sess-a", t0));
+    await h.buffer.addTurn("sess-b", turn("b1", "sess-b", t0));
+    await h.buffer.addTurn("sess-live", turn("live-1", "sess-live", t0));
+    await h.buffer.save();
+    const now = new Date().toISOString();
+    const mkLease = (ownerId: string): DrainLease => ({
+      ownerId,
+      pid: process.pid,
+      host: hostname(),
+      acquiredAt: now,
+      heartbeatAt: now,
+      leaseMs: 60_000,
+    });
+    assert.equal(await h.claims.claimFromSessionFile("sess-a", mkLease("drain-a")), "claimed");
+    assert.equal(await h.claims.claimFromSessionFile("sess-b", mkLease("drain-b")), "claimed");
+
+    // Identity tracker: a global swap (withBufferStorage) would replace this
+    // instance mid-task; the live deps read it live, exactly like selfDeps.
+    const liveHolder = { current: h.buffer };
+
+    // Per-key claim buffers over the SAME claim store (what the runner wires).
+    const claimBufferFor = async (key: string, ownerId: string): Promise<SmartBuffer> => {
+      const claim = await h.claims.load(key);
+      if (!claim) throw new Error(`test setup: claim for ${key} missing`);
+      const claimStorage = new ClaimBufferStorage(h.claims, key, ownerId, claim.entry);
+      return new SmartBuffer(makeConfig(), claimStorage);
+    };
+    const claimBuffers = new Map<string, SmartBuffer>([
+      ["sess-a", await claimBufferFor("sess-a", "drain-a")],
+      ["sess-b", await claimBufferFor("sess-b", "drain-b")],
+    ]);
+    for (const claimBuffer of claimBuffers.values()) await claimBuffer.load();
+
+    const realQueue = new ExtractionQueueCoordinator(1);
+    const runs: { task: string; turns: string[]; liveAtCall: SmartBuffer }[] = [];
+    const liveRuns = new Set<string>();
+    const makeDrainStub =
+      (task: string, claimBuffer: SmartBuffer | undefined) =>
+      // Mimic extraction-run: read the turns handed over, clear them through
+      // the CURRENT live instance (a swap would clear into a claim buffer).
+      async (turns: BufferTurn[]): Promise<ExtractionRunResult> => {
+        runs.push({ task, turns: turns.map((t) => t.content), liveAtCall: liveHolder.current });
+        const target = claimBuffer ?? liveHolder.current;
+        await target.clearAfterExtraction(task, turns, { allowNonPrefix: true });
+        if (!claimBuffer) liveRuns.add(task);
+        return { status: "completed", persistedCount: turns.length, durableOutputCount: turns.length };
+      };
+
+    const liveStub = makeDrainStub("sess-live", undefined);
+    const executionFor = (key: string) => {
+      const claimBuffer = claimBuffers.get(key)!;
+      const drain = new ExtractionDrain(
+        {
+          config: {
+            extractionMinUserTurns: 1,
+            extractionMinChars: 0,
+            extractionMaxTurnChars: 100_000,
+            extractionChunkDropAfterFailures: 3,
+          },
+          extractionWindowBudgetChars: () => 500,
+          runExtraction: makeDrainStub(key, claimBuffer),
+          getStorage: async () => ({ saveDroppedExtractionChunk: async () => "/dropped" }),
+          buffer: claimBuffer,
+        },
+        { dropFailedChunks: false }
+      );
+      return { buffer: claimBuffer, drain };
+    };
+    // SAFETY: the harness supplies exactly the members this scenario's
+    // TurnIngestionCoordinator reads; the remaining contract members are
+    // unreachable on this path.
+    const noopStorage = async () => ({ saveDroppedExtractionChunk: async () => "/dropped" });
+    const deps: TurnIngestionDeps = {
+      get buffer() {
+        return liveHolder.current;
+      },
+      bulkImportWriteNamespace: () => "bulk-import",
+      config: makeConfig(),
+      extractionQueueCoordinator: realQueue,
+      getStorage: async () => {
+        throw new Error("no storage on this path");
+      },
+      heartbeatObserverChains: new Map(),
+      lcmEngine: null,
+      passiveCorrectionDedup: new Set(),
+      passiveCorrectionTelemetry: {
+        detected: 0,
+        queued: 0,
+        autoApplied: 0,
+        suppressedReasonCounts: {},
+      },
+      passiveCorrectionService: () => {
+        throw new Error("passive corrections unreachable in this scenario");
+      },
+      shouldQueueExtraction: () => true,
+      runExtraction: liveStub,
+      queueBufferedExtraction: async () => undefined,
+      resolveMemoryIdOrHandle: () => "memory-1",
+      sessionObserver: asStub<SessionObserverState>({ turns: [], lastTurnAt: null }),
+      transcript: asStub<TranscriptManager>({ append: async () => undefined }),
+    };
+    const coordinator = new TurnIngestionCoordinator(deps);
+
+    const settled: Promise<void>[] = [];
+    const enqueueClaimTask = (key: string, ownerId: string): void => {
+      const claimBuffer = claimBuffers.get(key);
+      settled.push(
+        new Promise<void>((resolve, reject) => {
+          void coordinator
+            .queueBufferedExtraction(
+              // The claim's turns, grouped upstream (grouping is the runner's
+              // next commit; the seam carries whatever list it is given).
+              (claimBuffer?.getTurns(key) ?? []).map((t) => ({ ...t })),
+              "trigger_mode",
+              {
+                bufferKey: key,
+                clearBufferAfterExtraction: true,
+                clearMatchingTurns: true,
+                skipDedupeCheck: true,
+                skipCharThreshold: true,
+                skipUserTurnThreshold: true,
+                execution: executionFor(key),
+                onTaskSettled: (error) => (error ? reject(error) : resolve()),
+              }
+            )
+            .catch(reject);
+        })
+      );
+    };
+    enqueueClaimTask("sess-a", "drain-a");
+    enqueueClaimTask("sess-b", "drain-b");
+    // The live foreground capture arrives while the claim tasks hold the queue.
+    settled.push(
+      new Promise<void>((resolve, reject) => {
+        void coordinator
+          .queueBufferedExtraction([turn("live-2", "sess-live", "2026-11-01T00:01:00.000Z")], "trigger_mode", {
+            bufferKey: "sess-live",
+            clearBufferAfterExtraction: true,
+            onTaskSettled: (error) => (error ? reject(error) : resolve()),
+          })
+          .catch(reject);
+      })
+    );
+    await Promise.all(settled);
+
+    // No swap ever happened: every stub saw the live instance, and the live
+    // task's clear went through the live buffer (its turns are gone from it).
+    for (const run of runs) {
+      assert.equal(run.liveAtCall, h.buffer, "the live buffer instance must never be swapped mid-task");
+    }
+    assert.deepEqual(
+      runs.find((r) => r.task === "sess-a")?.turns,
+      ["a1"],
+      "task a extracted only its own claim's turns"
+    );
+    assert.deepEqual(
+      runs.find((r) => r.task === "sess-b")?.turns,
+      ["b1"],
+      "task b extracted only its own claim's turns"
+    );
+    assert.equal(liveRuns.has("sess-live"), true, "the live task ran through the live path");
+    assert.deepEqual(
+      h.buffer.getTurns("sess-live").map((t) => t.content),
+      ["live-1"],
+      "the live task cleared only its queued snapshot through the live buffer"
+    );
+    // Claim progress landed in the RIGHT claim files (no cross-talk), and the
+    // claims' turns were extracted from the claims, not from any live copy.
+    assert.deepEqual((await h.claims.load("sess-a"))?.entry.turns ?? [], [], "claim a is drained in place");
+    assert.deepEqual((await h.claims.load("sess-b"))?.entry.turns ?? [], [], "claim b is drained in place");
+    assert.deepEqual(
+      h.buffer.getTurns("sess-a").map((t) => t.content),
+      ["a1"],
+      "the live buffer's in-memory copy is untouched by the claim drain"
+    );
+  } finally {
+    h.cleanup();
+  }
+});
+
+/** Claim keys in the order `listPage` scans them: sorted claim file names
+ *  (`list()` itself is directory-enumeration order, which is not sorted). */
+async function claimKeysInListPageOrder(claims: BufferDrainClaims): Promise<string[]> {
+  const keys = (await claims.list()).map((listed) => listed.key);
+  const nameOf = new Map(keys.map((key) => [key, bufferSessionFileName(key)] as const));
+  const names = [...nameOf.values()].sort();
+  return keys.sort((left, right) => names.indexOf(nameOf.get(left)!) - names.indexOf(nameOf.get(right)!));
+}
+
+test("listPage never spends its page limit on empty tombstone claims", async () => {
+  const h = makeHarness();
+  try {
+    await h.buffer.load();
+    const keys = ["tomb-a", "tomb-b", "tomb-c", "tomb-d", "tomb-e", "tomb-pending"];
+    for (const key of keys) await h.buffer.addTurn(key, turn(`t-${key}`, key));
+    await h.buffer.save();
+    for (const key of keys) assert.equal(await h.claims.claimFromSessionFile(key, h.lease), "claimed");
+    // Claim file names are hashed: the LAST claim in listing order is the one
+    // left pending, so a limit counted against tombstones cannot reach it.
+    const order = await claimKeysInListPageOrder(h.claims);
+    const pending = order[order.length - 1]!;
+    for (const key of order) {
+      if (key === pending) continue;
+      const loaded = await h.claims.load(key);
+      await h.claims.writeEntry(key, h.lease.ownerId, entry([]), loaded!.entry);
+      assert.equal(await h.claims.ack(key, h.lease.ownerId), "acked");
+    }
+    const page = await h.claims.listPage(undefined, 1);
+    assert.deepEqual(
+      page.entries.map((listed) => listed.key),
+      [pending],
+      "the one pending claim is returned on the first page, past the tombstones"
+    );
+    assert.ok(page.entries.every((listed) => listed.turnCount > 0), "a page never lists an empty tombstone");
+  } finally {
+    h.cleanup();
+  }
+});
+
+test("listPage bounds the claim bodies it reads per call and resumes past a long tombstone run", async () => {
+  const h = makeHarness();
+  try {
+    await h.buffer.load();
+    // limit 1 reads at most 8 bodies per call: eight tombstones fill the
+    // budget exactly, so the pending claim behind them needs a second page.
+    const keys = Array.from({ length: 9 }, (_, index) => `run-${index}`);
+    for (const key of keys) await h.buffer.addTurn(key, turn(`t-${key}`, key));
+    await h.buffer.save();
+    for (const key of keys) assert.equal(await h.claims.claimFromSessionFile(key, h.lease), "claimed");
+    const order = await claimKeysInListPageOrder(h.claims);
+    const pending = order[order.length - 1]!;
+    for (const key of order) {
+      if (key === pending) continue;
+      const loaded = await h.claims.load(key);
+      await h.claims.writeEntry(key, h.lease.ownerId, entry([]), loaded!.entry);
+      assert.equal(await h.claims.ack(key, h.lease.ownerId), "acked");
+    }
+    const first = await h.claims.listPage(undefined, 1);
+    assert.deepEqual(first.entries, [], "the scan budget is spent on tombstones: nothing listed this call");
+    assert.notEqual(first.nextCursor, undefined, "the cursor advanced past every scanned name");
+    const second = await h.claims.listPage(first.nextCursor, 1);
+    assert.deepEqual(
+      second.entries.map((listed) => listed.key),
+      [pending],
+      "the next page resumes after the scanned run and reaches the pending claim"
+    );
+  } finally {
+    h.cleanup();
+  }
+});
+
+test("listPage returns exactly its limit when more pending claims exist", async () => {
+  const h = makeHarness();
+  try {
+    await h.buffer.load();
+    const keys = ["limit-a", "limit-b", "limit-c"];
+    for (const key of keys) await h.buffer.addTurn(key, turn(`t-${key}`, key));
+    await h.buffer.save();
+    for (const key of keys) assert.equal(await h.claims.claimFromSessionFile(key, h.lease), "claimed");
+    const page = await h.claims.listPage(undefined, 2);
+    assert.equal(page.entries.length, 2, "a page never exceeds its limit");
+    assert.notEqual(page.nextCursor, undefined, "a full page leaves a cursor for the remainder");
+  } finally {
+    h.cleanup();
+  }
+});
+
+test("listPage's cursor is the LAST CONSUMED claim, so a page boundary never skips one", async () => {
+  const h = makeHarness();
+  try {
+    await h.buffer.load();
+    for (const key of ["page-sess-a", "page-sess-b", "page-sess-c"]) {
+      await h.buffer.addTurn(key, turn(`t-${key}`, key));
+    }
+    await h.buffer.save();
+    for (const key of ["page-sess-a", "page-sess-b", "page-sess-c"]) {
+      assert.equal(await h.claims.claimFromSessionFile(key, h.lease), "claimed");
+    }
+    // Claim file names are hashed, so pagination is asserted order-free.
+    const seen = new Set<string>();
+    let cursor: string | undefined;
+    let pages = 0;
+    for (;;) {
+      const page = await h.claims.listPage(cursor, 2);
+      pages += 1;
+      for (const entry of page.entries) seen.add(entry.key);
+      if (page.nextCursor === undefined) break;
+      cursor = page.nextCursor;
+      if (pages > 10) throw new Error("pagination never exhausted");
+    }
+    assert.deepEqual(
+      [...seen].sort(),
+      ["page-sess-a", "page-sess-b", "page-sess-c"],
+      "every page-boundary claim must be visited exactly once across rotating pages"
+    );
+    assert.equal(seen.size, pages === 2 ? 3 : 3, "no claim repeats across the rotation");
+  } finally {
+    h.cleanup();
+  }
+});