@remnic/core 10.0.72 → 10.0.74

package/src/buffer-record-snapshots.test.ts

@@ -0,0 +1,195 @@
+import assert from "node:assert/strict";
+/**
+ * recordTurnUnlocked snapshot retention — issue: the per-turn mutation built
+ * `priorTurns` + `activeTurnsSnapshot` + `retainedTurnsSnapshot` (two full
+ * `copyBufferTurn` maps) on EVERY admitted turn, even when the decision path
+ * consumes none of them: a plain `keep_buffering` turn with no surprise probe
+ * eligible branch discards all three. The mutation now builds the snapshots
+ * only when the decision path needs them (`keep_buffering` under an
+ * eligible surprise branch, or any extraction decision), so steady-state
+ * buffering performs no per-turn snapshot copies.
+ *
+ * Harness: an instance-level spy wraps the (private) recordTurnUnlocked and
+ * captures each AddTurnMutationResult, so tests assert on exactly what the
+ * mutation returned — no production instrumentation.
+ */
+import test from "node:test";
+
+import { type BufferSurpriseProbe, SmartBuffer } from "./buffer.js";
+import { parseConfig } from "./config.js";
+import type { BufferState, BufferTurn } from "./types.js";
+
+class FakeStorage {
+  public saved: BufferState | null = null;
+  public saveCount = 0;
+
+  constructor(private readonly initial: BufferState) {}
+
+  async loadBuffer(): Promise<BufferState> {
+    return structuredClone(this.initial);
+  }
+
+  async saveBuffer(state: BufferState): Promise<void> {
+    this.saveCount += 1;
+    this.saved = structuredClone(state);
+  }
+}
+
+function makeTurn(sessionKey: string, content: string): BufferTurn {
+  return {
+    role: "user",
+    content,
+    timestamp: "2026-04-20T12:00:00.000Z",
+    sessionKey,
+  };
+}
+
+function emptyBuffer(): BufferState {
+  return { turns: [], lastExtractionAt: null, extractionCount: 0 };
+}
+
+type MutationCapture = {
+  priorTurns: BufferTurn[];
+  activeTurnsSnapshot: BufferTurn[];
+  retainedTurnsSnapshot: BufferTurn[];
+  decision: string;
+};
+
+type RecordSpy = (bufferKey: string, turn: BufferTurn) => Promise<MutationCapture>;
+
+function spyMutations(buffer: SmartBuffer): MutationCapture[] {
+  const captures: MutationCapture[] = [];
+  // SAFETY: recordTurnUnlocked is a TS-private prototype method with a stable
+  // runtime shape; the spy re-exposes the identical signature on the instance.
+  const original = Object.getPrototypeOf(buffer).recordTurnUnlocked as RecordSpy;
+  Object.defineProperty(buffer, "recordTurnUnlocked", {
+    value: async (bufferKey: string, turn: BufferTurn): Promise<MutationCapture> => {
+      const result = await original.call(buffer, bufferKey, turn);
+      captures.push(result);
+      return result;
+    },
+    configurable: true,
+    writable: true,
+  });
+  return captures;
+}
+
+function fixedScoreProbe(score: number | null): BufferSurpriseProbe & { calls: number } {
+  const probe = {
+    calls: 0,
+    async scoreTurn(_key: string, _turn: BufferTurn, _prior: readonly BufferTurn[]): Promise<number | null> {
+      probe.calls += 1;
+      return score;
+    },
+  };
+  return probe;
+}
+
+test("plain keep_buffering turn performs no snapshot copies", async () => {
+  const storage = new FakeStorage(emptyBuffer());
+  const config = parseConfig({
+    bufferMaxTurns: 5,
+    triggerMode: "smart",
+    bufferSaveDebounceMs: 0,
+  });
+  const buffer = new SmartBuffer(config, storage);
+  const captures = spyMutations(buffer);
+
+  const decision = await buffer.addTurn("sess-1", makeTurn("sess-1", "ordinary content"));
+
+  assert.equal(decision, "keep_buffering");
+  assert.equal(captures.length, 1);
+  assert.equal(captures[0].priorTurns.length, 0, "no priorTurns copy for a decision that never reads it");
+  assert.equal(captures[0].activeTurnsSnapshot.length, 0, "no active-turn snapshot copies while buffering");
+  assert.equal(captures[0].retainedTurnsSnapshot.length, 0, "no retained-turn snapshot copies while buffering");
+});
+
+test("extraction decisions still carry full snapshots", async () => {
+  const storage = new FakeStorage(emptyBuffer());
+  const config = parseConfig({
+    bufferMaxTurns: 2,
+    triggerMode: "every_n",
+    bufferSaveDebounceMs: 0,
+  });
+  const buffer = new SmartBuffer(config, storage);
+  const captures = spyMutations(buffer);
+
+  await buffer.addTurn("sess-1", makeTurn("sess-1", "one"));
+  const outcome = await buffer.addTurnWithOutcome("sess-1", makeTurn("sess-1", "two"));
+
+  assert.equal(outcome.decision, "extract_batch");
+  assert.notEqual(outcome.extractionTurns, undefined);
+  assert.equal(outcome.extractionTurns?.length, 2);
+  const last = captures[captures.length - 1];
+  assert.equal(last.decision, "extract_batch");
+  assert.equal(last.priorTurns.length, 1, "prior turn kept for extraction decisions");
+  assert.equal(last.activeTurnsSnapshot.length, 2, "active snapshot kept for extraction decisions");
+  assert.deepEqual(
+    last.activeTurnsSnapshot.map((t) => t.content),
+    ["one", "two"]
+  );
+});
+
+test("surprise-eligible keep_buffering still builds the snapshots the probe path reads", async () => {
+  const storage = new FakeStorage(emptyBuffer());
+  const probe = fixedScoreProbe(null);
+  const config = parseConfig({
+    bufferSurpriseTriggerEnabled: true,
+    bufferMaxTurns: 5,
+    triggerMode: "smart",
+    bufferSaveDebounceMs: 0,
+  });
+  const buffer = new SmartBuffer(config, storage, probe);
+  const captures = spyMutations(buffer);
+
+  const decision = await buffer.addTurn("sess-1", makeTurn("sess-1", "ordinary content"));
+
+  assert.equal(decision, "keep_buffering");
+  assert.equal(probe.calls, 1, "the surprise probe must still be consulted");
+  const capture = captures[0];
+  assert.equal(capture.priorTurns.length, 0, "first turn has no priors");
+  assert.equal(capture.activeTurnsSnapshot.length, 1, "snapshot kept while the surprise branch may promote");
+  assert.equal(capture.retainedTurnsSnapshot.length, 0, "nothing retained yet");
+});
+
+test("surprise promotion still extracts from a consistent snapshot", async () => {
+  const storage = new FakeStorage(emptyBuffer());
+  const probe = fixedScoreProbe(0.99);
+  const config = parseConfig({
+    bufferSurpriseTriggerEnabled: true,
+    bufferMaxTurns: 5,
+    triggerMode: "smart",
+    bufferSurpriseThreshold: 0.5,
+    bufferSaveDebounceMs: 0,
+  });
+  const buffer = new SmartBuffer(config, storage, probe);
+
+  const outcome = await buffer.addTurnWithOutcome("sess-1", makeTurn("sess-1", "novel"));
+
+  assert.equal(outcome.decision, "extract_now");
+  assert.deepEqual(
+    outcome.extractionTurns?.map((t) => t.content),
+    ["novel"]
+  );
+});
+
+test("keep_buffering under every_n never builds snapshots even with a probe present", async () => {
+  const storage = new FakeStorage(emptyBuffer());
+  const probe = fixedScoreProbe(0.99);
+  const config = parseConfig({
+    bufferSurpriseTriggerEnabled: true,
+    bufferMaxTurns: 5,
+    triggerMode: "every_n",
+    bufferSaveDebounceMs: 0,
+  });
+  const buffer = new SmartBuffer(config, storage, probe);
+  const captures = spyMutations(buffer);
+
+  const decision = await buffer.addTurn("sess-1", makeTurn("sess-1", "ordinary content"));
+
+  assert.equal(decision, "keep_buffering");
+  assert.equal(probe.calls, 0, "surprise branch is smart-mode only");
+  assert.equal(captures[0].activeTurnsSnapshot.length, 0);
+  assert.equal(captures[0].retainedTurnsSnapshot.length, 0);
+  assert.equal(captures[0].priorTurns.length, 0);
+});

package/src/buffer-turn-helpers.test.ts

@@ -0,0 +1,205 @@
+import assert from "node:assert/strict";
+/**
+ * mergeTurns identity comparison — issue: the claim-merge hot path
+ * (buffer-drain-claims.ts `mergeIntoClaim`) deduped incoming turns with
+ * `merged.some(isEqual)`: O(existing × incoming) per observe while a claim
+ * only grows during a stalled drain. The identity comparison now goes
+ * through a Set of identity keys built from the exact `bufferTurnsEqual`
+ * fields, so the merge is O(n + m) with byte-identical merge semantics:
+ * dedupe identical turns (including duplicates within `incoming`), append
+ * genuinely-new turns in arrival order, existing entries always win.
+ *
+ * The identity key must be injective over `bufferTurnsEqual` equality
+ * classes — including the undefined-vs-null distinctions on optional fields
+ * (`providerThreadId`) and the plan-identity triple (#3251).
+ */
+import test from "node:test";
+
+import { bufferTurnIdentityKey, bufferTurnsEqual, mergeBufferTurnsByIdentity } from "./buffer-turn-helpers.js";
+import type { ScopeProfileLayerResolution } from "./namespaces/scope-profiles.js";
+import type { BufferTurn } from "./types.js";
+
+function turn(overrides: Partial<BufferTurn> & { content: string }): BufferTurn {
+  return { role: "user", timestamp: "2026-11-01T00:00:00.000Z", ...overrides };
+}
+
+test("bufferTurnIdentityKey matches bufferTurnsEqual exactly (same key ⇔ equal)", () => {
+  const base = turn({ content: "hello", sessionKey: "s1" });
+  const same = turn({ content: "hello", sessionKey: "s1" });
+  const different = [
+    turn({ content: "hello", sessionKey: "s2" }),
+    turn({ content: "world", sessionKey: "s1" }),
+    turn({ content: "hello", sessionKey: "s1", role: "assistant" as const }),
+    turn({ content: "hello", sessionKey: "s1", timestamp: "2026-11-02T00:00:00.000Z" }),
+    turn({ content: "hello", sessionKey: "s1", providerThreadId: null }),
+    turn({ content: "hello", sessionKey: "s1", providerThreadId: "t1" }),
+    turn({ content: "hello", sessionKey: "s1", turnFingerprint: "fp" }),
+    turn({ content: "hello", sessionKey: "s1", persistProcessedFingerprint: true }),
+    turn({ content: "hello", sessionKey: "s1", persistProcessedFingerprint: false }),
+    turn({ content: "hello", sessionKey: "s1", sourceConnector: "cli" }),
+    turn({ content: "hello", sessionKey: "s1", originRole: "user" as const }),
+    turn({ content: "hello", sessionKey: "s1", ambientCapture: true }),
+    turn({ content: "hello", sessionKey: "s1", ambientCapture: false }),
+    turn({ content: "hello", sessionKey: "s1", sourceValidAt: "2026-01-01T00:00:00.000Z" }),
+    turn({ content: "hello", sessionKey: "s1", acceptedCapture: true }),
+    turn({ content: "hello", sessionKey: "s1", acceptedCapture: false }),
+    turn({ content: "hello", sessionKey: "s1", writeNamespaceOverride: "ns" }),
+    turn({ content: "hello", sessionKey: "s1", principalOverride: "p1" }),
+    turn({
+      content: "hello",
+      sessionKey: "s1",
+      codingContext: { projectId: "proj", branch: "main", rootPath: "/r", defaultBranch: "main" },
+    }),
+    turn({
+      content: "hello",
+      sessionKey: "s1",
+      codingContext: { projectId: "proj", branch: "dev", rootPath: "/r", defaultBranch: "main" },
+    }),
+  ];
+
+  assert.equal(bufferTurnIdentityKey(base), bufferTurnIdentityKey(same));
+  assert.equal(bufferTurnsEqual(base, same), true);
+  for (const other of different) {
+    assert.notEqual(
+      bufferTurnIdentityKey(base),
+      bufferTurnIdentityKey(other),
+      `key must differ for ${JSON.stringify(other)}`
+    );
+    assert.equal(bufferTurnsEqual(base, other), false);
+  }
+});
+
+test("bufferTurnIdentityKey: undefined and null providerThreadId are distinct classes", () => {
+  const absent = turn({ content: "x" });
+  const explicitNull = turn({ content: "x", providerThreadId: null });
+  const present = turn({ content: "x", providerThreadId: "t" });
+  const keys = new Set([
+    bufferTurnIdentityKey(absent),
+    bufferTurnIdentityKey(explicitNull),
+    bufferTurnIdentityKey(present),
+  ]);
+  assert.equal(keys.size, 3);
+  assert.equal(bufferTurnsEqual(absent, explicitNull), false);
+  assert.equal(bufferTurnsEqual(absent, present), false);
+});
+
+test("bufferTurnIdentityKey: null and undefined scope plan share the empty identity (#3251)", () => {
+  const noPlan = turn({ content: "x" });
+  const nullPlan = turn({ content: "x", scopeProfileWritePlan: null });
+  assert.equal(bufferTurnIdentityKey(noPlan), bufferTurnIdentityKey(nullPlan));
+  assert.equal(bufferTurnsEqual(noPlan, nullPlan), true);
+});
+
+test("mergeBufferTurnsByIdentity appends genuinely-new turns in arrival order", () => {
+  const existing = [turn({ content: "a" }), turn({ content: "b" })];
+  const incoming = [turn({ content: "c" }), turn({ content: "d" })];
+  const merged = mergeBufferTurnsByIdentity(existing, incoming);
+  assert.deepEqual(
+    merged.map((t) => t.content),
+    ["a", "b", "c", "d"]
+  );
+});
+
+test("mergeBufferTurnsByIdentity dedupes turns identical to an existing entry", () => {
+  const existing = [turn({ content: "a" }), turn({ content: "b" })];
+  const incoming = [turn({ content: "b" }), turn({ content: "c" })];
+  const merged = mergeBufferTurnsByIdentity(existing, incoming);
+  assert.deepEqual(
+    merged.map((t) => t.content),
+    ["a", "b", "c"]
+  );
+  // The kept entry is the EXISTING object, not the incoming copy.
+  assert.equal(merged[1], existing[1]);
+});
+
+test("mergeBufferTurnsByIdentity dedupes duplicates within incoming (first wins)", () => {
+  const existing: BufferTurn[] = [];
+  const first = turn({ content: "dup" });
+  const second = turn({ content: "dup" });
+  const merged = mergeBufferTurnsByIdentity(existing, [first, second]);
+  assert.equal(merged.length, 1);
+  assert.equal(merged[0], first);
+});
+
+test("mergeBufferTurnsByIdentity keeps existing entries verbatim, duplicates included", () => {
+  const dupA = turn({ content: "a" });
+  const dupB = turn({ content: "a" });
+  const existing = [dupA, dupB];
+  const merged = mergeBufferTurnsByIdentity(existing, [turn({ content: "a" }), turn({ content: "b" })]);
+  assert.equal(merged.length, 3, "existing duplicates are preserved; incoming duplicate dropped");
+  assert.equal(merged[0], dupA);
+  assert.equal(merged[1], dupB);
+  assert.equal(merged[2].content, "b");
+});
+
+test("mergeBufferTurnsByIdentity keeps existing order and does not mutate inputs", () => {
+  const existing = [turn({ content: "b" }), turn({ content: "a" })];
+  const incoming = [turn({ content: "a" }), turn({ content: "c" })];
+  const merged = mergeBufferTurnsByIdentity(existing, incoming);
+  assert.deepEqual(
+    merged.map((t) => t.content),
+    ["b", "a", "c"]
+  );
+  assert.equal(existing.length, 2);
+  assert.deepEqual(
+    existing.map((t) => t.content),
+    ["b", "a"]
+  );
+});
+
+// Identity fields only: scopeProfilePlanIdentity reads profileId, writeLayer
+// and writeNamespace; the remaining members are inert for identity tests.
+function pinnedPlan(namespace: string): NonNullable<BufferTurn["scopeProfileWritePlan"]> {
+  const layer: ScopeProfileLayerResolution = {
+    id: "userProject",
+    kind: "user-project",
+    namespace,
+    readable: true,
+    writable: true,
+    promotable: false,
+    reason: "identity-test layer",
+  };
+  return {
+    profileId: "p",
+    profile: {
+      readOrder: ["userProject"],
+      writeDefault: "userProject",
+      promotionTargets: [],
+      autoPromote: { enabled: false, targets: [], categories: [], minConfidenceTier: "speculative" },
+    },
+    baseNamespace: namespace,
+    writeLayer: "userProject",
+    writeNamespace: namespace,
+    readNamespaces: [namespace],
+    layers: [layer],
+    promotionTargets: [],
+    warnings: [],
+  };
+}
+
+test("mergeBufferTurnsByIdentity stays consistent with bufferTurnsEqual on scope-pinned turns", () => {
+  const pinned = turn({
+    content: "cap",
+    acceptedCapture: true,
+    writeNamespaceOverride: "ns-a",
+    scopeProfileWritePlan: pinnedPlan("ns-a"),
+  });
+  const samePinned = turn({
+    content: "cap",
+    acceptedCapture: true,
+    writeNamespaceOverride: "ns-a",
+    scopeProfileWritePlan: pinnedPlan("ns-a"),
+  });
+  const otherPinned = turn({
+    content: "cap",
+    acceptedCapture: true,
+    writeNamespaceOverride: "ns-b",
+    scopeProfileWritePlan: pinnedPlan("ns-b"),
+  });
+  assert.equal(bufferTurnsEqual(pinned, samePinned), true);
+  assert.equal(bufferTurnsEqual(pinned, otherPinned), false);
+  const merged = mergeBufferTurnsByIdentity([pinned], [samePinned, otherPinned]);
+  assert.equal(merged.length, 2);
+  assert.equal(merged[0], pinned);
+  assert.equal(merged[1], otherPinned);
+});

package/src/buffer-turn-helpers.ts

@@ -169,6 +169,68 @@ export function bufferTurnsEqual(left: BufferTurn | undefined, right: BufferTurn
   );
 }
 
+/**
+ * Canonical identity key for a turn, injective over `bufferTurnsEqual`
+ * equality classes. Every compared field is a primitive (or the #3251 plan
+ * identity string), so set-membership replaces pairwise comparison and turn
+ * merges run O(n + m) instead of O(n × m). JSON.stringify of a string is
+ * injective (it escapes control characters), and the raw `\u0001` sentinels
+ * distinguish undefined from null — a distinction `===` makes and plain
+ * stringification would lose.
+ */
+export function bufferTurnIdentityKey(turn: BufferTurn): string {
+  const opt = (value: string | null | undefined): string =>
+    value === undefined ? "\u0001undefined" : value === null ? "\u0001null" : JSON.stringify(value);
+  const optFlag = (value: boolean | undefined): string =>
+    value === undefined ? "\u0001undefined" : String(value);
+  const ctx = turn.codingContext;
+  return JSON.stringify([
+    turn.role,
+    turn.content,
+    turn.timestamp,
+    opt(turn.sessionKey),
+    opt(turn.sessionOwnerPrincipal),
+    opt(turn.logicalSessionKey),
+    turn.providerThreadId === undefined ? "\u0001undefined" : turn.providerThreadId === null ? "\u0001null" : JSON.stringify(turn.providerThreadId),
+    opt(turn.turnFingerprint),
+    optFlag(turn.persistProcessedFingerprint),
+    opt(turn.sourceConnector),
+    opt(turn.originRole),
+    optFlag(turn.ambientCapture),
+    opt(turn.sourceValidAt),
+    optFlag(turn.acceptedCapture),
+    opt(ctx?.projectId),
+    opt(ctx?.rootPath),
+    opt(ctx?.branch),
+    opt(ctx?.defaultBranch),
+    opt(turn.writeNamespaceOverride),
+    opt(turn.principalOverride),
+    opt(turn.scopeProfileWritePlan ? scopeProfilePlanIdentity(turn.scopeProfileWritePlan) : undefined),
+  ]);
+}
+
+/**
+ * Identity-dedupe `incoming` turns into `existing` (same contract as the
+ * claim-merge `mergeTurns`): identical turns are dropped — the EXISTING
+ * entry is kept — genuinely-new turns append in arrival order, and
+ * duplicates within `incoming` collapse to their first occurrence. O(n + m)
+ * via `bufferTurnIdentityKey` membership instead of pairwise equality.
+ */
+export function mergeBufferTurnsByIdentity(
+  existing: readonly BufferTurn[],
+  incoming: readonly BufferTurn[],
+): BufferTurn[] {
+  const merged = [...existing];
+  const seen = new Set(merged.map(bufferTurnIdentityKey));
+  for (const turn of incoming) {
+    const key = bufferTurnIdentityKey(turn);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    merged.push(turn);
+  }
+  return merged;
+}
+
 /** Replace only the processed snapshot; callers without one retain legacy whole-slot semantics. */
 export function selectRetainedDeferredTurns(
   existing: readonly BufferTurn[],

package/src/buffer.ts

@@ -646,16 +646,16 @@ export class SmartBuffer {
   private async recordTurnUnlocked(bufferKey: string, turn: BufferTurn): Promise<AddTurnMutationResult> {
     await this.loadUnlocked();
     const entry = this.entryFor(bufferKey);
-    const priorTurns = entry.turns.slice();
-    entry.turns.push(turn);
-    const activeTurnsSnapshot = entry.turns.map(copyBufferTurn);
-    const retainedTurnsSnapshot = (entry.retainedTurns ?? []).map(copyBufferTurn);
-    if (bufferKey === "default") {
-      this.state.turns = entry.turns;
-    }
-
     const signal = scanSignals(turn.content, this.config.highSignalPatterns);
+    entry.turns.push(turn);
     const decision = this.evaluate(entry, signal.level);
+    // Snapshots serve only extraction decisions and surprise-eligible keep_buffering turns (probe, smart mode, sub-high signal); steady-state buffering copies nothing.
+    const surpriseEligible = this.surpriseProbe !== null && this.config.triggerMode === "smart" && signal.level !== "high";
+    const snapshotsNeeded = decision !== "keep_buffering" || surpriseEligible;
+    const priorTurns = snapshotsNeeded ? entry.turns.slice(0, -1) : [];
+    const activeTurnsSnapshot = snapshotsNeeded ? entry.turns.map(copyBufferTurn) : [];
+    const retainedTurnsSnapshot = snapshotsNeeded ? (entry.retainedTurns ?? []).map(copyBufferTurn) : [];
+    if (bufferKey === "default") this.state.turns = entry.turns;
     const turnCountInWindow = entry.turns.length;
 
     this.persistence.markDirty(bufferKey);

package/src/orchestration/extraction-queue-coordinator.ts

@@ -115,10 +115,27 @@ export class ExtractionQueueCoordinator {
    * Enqueue a task and start the processor when capacity is free. This is
    * the production entry point — the orchestrator's `queueBufferedExtraction`
    * builds each task closure and hands it here with its buffer key.
+   *
+   * Per-key coalescing: a queued-not-started task for key K is superseded by
+   * a newer enqueue for K instead of stacking another full turn snapshot
+   * behind it (extraction reads live state at run time, so the newest
+   * closure is the authoritative one). Keyless tasks are independent work
+   * and never coalesce.
    */
   enqueue(task: ExtractionQueueTask, options?: ExtractionQueueEnqueueOptions): boolean {
     if (!this.accepting) return false;
-    const entry: QueueEntry = { run: task, key: options?.key };
+    const key = options?.key;
+    if (key !== undefined) {
+      const queuedAt = this.queue.findIndex((entry) => entry.key === key);
+      if (!options?.front && queuedAt >= 0) {
+        this.queue[queuedAt] = { run: task, key };
+        return true;
+      }
+      if (options?.front && queuedAt >= 0) {
+        this.queue.splice(queuedAt, 1);
+      }
+    }
+    const entry: QueueEntry = { run: task, key };
     if (options?.front) {
       this.preemptRunning(options.key);
       this.queue.unshift(entry);

package/src/orchestrator-extraction-queue.test.ts

@@ -35,6 +35,148 @@ function createCoordinator(): ExtractionQueueCoordinator {
   return new ExtractionQueueCoordinator();
 }
 
+// ── Per-key coalescing: a queued-not-started task is superseded by a newer
+// enqueue for the same key instead of stacking another full snapshot ────────
+
+test("a newer enqueue for a queued-not-started key replaces the queued task", async () => {
+  const coordinator = createCoordinator();
+  const busy = Promise.withResolvers<void>();
+  const releaseBusy = Promise.withResolvers<void>();
+  const ran: string[] = [];
+  coordinator.enqueue(async () => {
+    busy.resolve();
+    await releaseBusy.promise;
+  });
+  await busy.promise;
+
+  coordinator.enqueue(async () => {
+    ran.push("stale");
+  }, { key: "s1" });
+  coordinator.enqueue(async () => {
+    ran.push("fresh");
+  }, { key: "s1" });
+
+  assert.equal(coordinator.length, 1, "the stale snapshot must be replaced, not stacked");
+
+  releaseBusy.resolve();
+  assert.equal(await coordinator.waitForIdle(5_000), true);
+  assert.deepEqual(ran, ["fresh"], "only the newest task for the key runs");
+  assert.equal(coordinator.isProcessing, false);
+});
+
+test("coalescing keeps the superseded entry's position for other keys", async () => {
+  const coordinator = createCoordinator();
+  const busy = Promise.withResolvers<void>();
+  const releaseBusy = Promise.withResolvers<void>();
+  const ran: string[] = [];
+  coordinator.enqueue(async () => {
+    busy.resolve();
+    await releaseBusy.promise;
+  });
+  await busy.promise;
+
+  coordinator.enqueue(async () => {
+    ran.push("k1");
+  }, { key: "k1" });
+  coordinator.enqueue(async () => {
+    ran.push("k2-stale");
+  }, { key: "k2" });
+  coordinator.enqueue(async () => {
+    ran.push("k2-fresh");
+  }, { key: "k2" });
+  coordinator.enqueue(async () => {
+    ran.push("k3");
+  }, { key: "k3" });
+
+  releaseBusy.resolve();
+  assert.equal(await coordinator.waitForIdle(5_000), true);
+  assert.deepEqual(ran, ["k1", "k2-fresh", "k3"], "k2 keeps its queue slot; the newest payload wins");
+});
+
+test("a front enqueue supersedes a queued same-key task and keeps preemption", async () => {
+  const coordinator = createCoordinator();
+  const busy = Promise.withResolvers<void>();
+  const releaseBusy = Promise.withResolvers<void>();
+  const ran: string[] = [];
+  let preempted = false;
+  coordinator.enqueue(async (preempt) => {
+    const controller = new AbortController();
+    preempt?.arm(() => {
+      preempted = true;
+      controller.abort();
+    });
+    busy.resolve();
+    try {
+      await releaseBusy.promise;
+    } finally {
+      preempt?.disarm();
+    }
+  });
+  await busy.promise;
+
+  coordinator.enqueue(async () => {
+    ran.push("queued-stale");
+  }, { key: "s1" });
+  coordinator.enqueue(async () => {
+    ran.push("flush-fresh");
+  }, { key: "s1", front: true });
+
+  assert.equal(coordinator.length, 1, "the superseded queued task must be dropped");
+
+  releaseBusy.resolve();
+  assert.equal(await coordinator.waitForIdle(5_000), true);
+  assert.equal(preempted, true, "front enqueue still preempts the running automatic work");
+  assert.deepEqual(ran, ["flush-fresh"]);
+});
+
+test("keyless tasks never coalesce", async () => {
+  const coordinator = createCoordinator();
+  const busy = Promise.withResolvers<void>();
+  const releaseBusy = Promise.withResolvers<void>();
+  const ran: string[] = [];
+  coordinator.enqueue(async () => {
+    busy.resolve();
+    await releaseBusy.promise;
+  });
+  await busy.promise;
+
+  coordinator.enqueue(async () => {
+    ran.push("first");
+  });
+  coordinator.enqueue(async () => {
+    ran.push("second");
+  });
+  assert.equal(coordinator.length, 2, "tasks without a key are independent work");
+
+  releaseBusy.resolve();
+  assert.equal(await coordinator.waitForIdle(5_000), true);
+  assert.deepEqual(ran, ["first", "second"]);
+});
+
+test("a coalesced enqueue of a running key waits behind the active task", async () => {
+  const coordinator = createCoordinator();
+  const busy = Promise.withResolvers<void>();
+  const releaseBusy = Promise.withResolvers<void>();
+  const order: string[] = [];
+  coordinator.enqueue(async () => {
+    busy.resolve();
+    await releaseBusy.promise;
+    order.push("running");
+  }, { key: "s1" });
+  await busy.promise;
+
+  coordinator.enqueue(async () => {
+    order.push("queued-first");
+  }, { key: "s1" });
+  coordinator.enqueue(async () => {
+    order.push("queued-second");
+  }, { key: "s1" });
+
+  releaseBusy.resolve();
+  assert.equal(await coordinator.waitForIdle(5_000), true);
+  assert.deepEqual(order, ["running", "queued-second"]);
+});
+
 // ── Issue #549 ─────────────────────────────────────────────────────────────
 
 test("processQueue logs an AbortError task at debug, not error (#549)", async () => {