@remnic/core 9.30.1 → 9.32.0

package/dist/{chunk-4A6YGWQN.js → chunk-TL4TO3EA.js}

@@ -1,9 +1,28 @@
 import {
   scanSignals
 } from "./chunk-H3FZVNRN.js";
+import {
+  bufferTurnArrayIsSuffixOfSnapshot,
+  bufferTurnArraysEqual,
+  bufferTurnsEqual,
+  copyBufferTurn,
+  describeError,
+  liveTurnsFromExtractionSnapshot,
+  matchingQueuedExtractionPrefixLength,
+  probeWithTimeout
+} from "./chunk-ER7W6H4T.js";
+import {
+  ExtractionDeadlineError
+} from "./chunk-YPC7W6GA.js";
+import {
+  resolvePrincipal
+} from "./chunk-3GD2HFR6.js";
 import {
   resolvePresentationCapabilities
 } from "./chunk-2XRE6FLM.js";
+import {
+  throwIfAborted
+} from "./chunk-PVGDJXVK.js";
 import {
   log
 } from "./chunk-3WCASNQZ.js";
@@ -575,6 +594,9 @@ var SmartBuffer = class {
             timestamp: typeof t.timestamp === "string" ? t.timestamp : (/* @__PURE__ */ new Date()).toISOString()
           };
           if (typeof t.sessionKey === "string") copy.sessionKey = t.sessionKey;
+          if (typeof t.sessionOwnerPrincipal === "string") {
+            copy.sessionOwnerPrincipal = t.sessionOwnerPrincipal;
+          }
           if (typeof t.logicalSessionKey === "string") {
             copy.logicalSessionKey = t.logicalSessionKey;
           }
@@ -602,31 +624,91 @@ var SmartBuffer = class {
     const entry = this.peekEntry(bufferKey);
     return entry?.retainedTurns ? [...entry.retainedTurns] : [];
   }
+  /**
+   * Clear deferred retention copies for a force-flushed session. Normal
+   * extraction preserves these copies so a deferred candidate can be retried;
+   * an explicit force flush is the caller's request to drain that context.
+   */
+  async clearRetainedTurnsForSession(sessionKey, ownerPrincipal, options = {}) {
+    if (typeof sessionKey !== "string" || sessionKey.length === 0) return;
+    const normalizedOwnerPrincipal = typeof ownerPrincipal === "string" && ownerPrincipal.trim().length > 0 ? ownerPrincipal.trim() : void 0;
+    const assertLifecycle = () => {
+      throwIfAborted(options.abortSignal, "extraction force-flush aborted");
+      if (typeof options.deadlineMs === "number" && Date.now() >= options.deadlineMs) {
+        throw new ExtractionDeadlineError("retained_turn_cleanup");
+      }
+    };
+    assertLifecycle();
+    await this.enqueueMutation(async () => {
+      assertLifecycle();
+      const hadPendingSave = this.pendingSave;
+      if (this.saveTimer) {
+        clearTimeout(this.saveTimer);
+        this.saveTimer = null;
+      }
+      await this.loadUnlocked();
+      assertLifecycle();
+      const bufferKeys = this.matchingSessionBufferKeysUnlocked(sessionKey);
+      if (bufferKeys.length === 0) {
+        if (hadPendingSave) {
+          assertLifecycle();
+          await this.saveNowRetainingPendingOnFailure("clearRetainedTurnsForSession");
+        }
+        return;
+      }
+      let changed = false;
+      const belongsToOwner = (turn) => {
+        if (turn.sessionKey !== sessionKey) return false;
+        if (normalizedOwnerPrincipal === void 0) return true;
+        if (turn.sessionOwnerPrincipal === normalizedOwnerPrincipal) return true;
+        return turn.sessionOwnerPrincipal === void 0 && resolvePrincipal(turn.sessionKey, this.config) === normalizedOwnerPrincipal;
+      };
+      for (const bufferKey of bufferKeys) {
+        const entry = this.entryFor(bufferKey);
+        const retainedTurns = entry.retainedTurns ?? [];
+        const remainingTurns = retainedTurns.filter((turn) => !belongsToOwner(turn));
+        if (remainingTurns.length === retainedTurns.length) continue;
+        changed = true;
+        if (remainingTurns.length > 0) entry.retainedTurns = remainingTurns;
+        else delete entry.retainedTurns;
+        if (bufferKey === "default") this.state.turns = entry.turns;
+      }
+      if (changed || hadPendingSave) {
+        assertLifecycle();
+        await this.saveNowRetainingPendingOnFailure("clearRetainedTurnsForSession");
+      }
+      assertLifecycle();
+    });
+  }
   async findBufferKeyForSession(sessionKey) {
     const bufferKeys = await this.findBufferKeysForSession(sessionKey);
     return bufferKeys[0] ?? null;
   }
-  async findBufferKeysForSession(sessionKey) {
-    if (typeof sessionKey !== "string" || sessionKey.length === 0) return [];
-    await this.mutationChain.catch(() => {
-    });
-    await this.load();
+  matchingSessionBufferKeysUnlocked(sessionKey) {
     const matches = [];
+    const hasSessionTurns = (entry) => [...entry?.turns ?? [], ...entry?.retainedTurns ?? []].some(
+      (turn) => typeof turn.sessionKey === "string" && turn.sessionKey === sessionKey
+    );
     const directEntry = this.peekEntry(sessionKey);
-    if ((directEntry?.turns.length ?? 0) > 0) {
+    if (hasSessionTurns(directEntry)) {
       matches.push(sessionKey);
     }
     const entries = this.state.entries ?? {};
     for (const [bufferKey, entry] of Object.entries(entries)) {
-      if (!matches.includes(bufferKey) && entry.turns.some(
-        (turn) => typeof turn.sessionKey === "string" && turn.sessionKey === sessionKey
-      )) {
+      if (!matches.includes(bufferKey) && hasSessionTurns(entry)) {
         matches.push(bufferKey);
       }
     }
     return matches;
   }
-  async clearAfterExtraction(bufferKey = "default", extractedTurns) {
+  async findBufferKeysForSession(sessionKey) {
+    if (typeof sessionKey !== "string" || sessionKey.length === 0) return [];
+    await this.mutationChain.catch(() => {
+    });
+    await this.load();
+    return this.matchingSessionBufferKeysUnlocked(sessionKey);
+  }
+  async clearAfterExtraction(bufferKey = "default", extractedTurns, options) {
     await this.enqueueMutation(async () => {
       if (this.saveTimer) {
         clearTimeout(this.saveTimer);
@@ -641,14 +723,29 @@ var SmartBuffer = class {
         );
         let clearedLiveTurns = false;
         if (liveExtractedTurns.length > 0) {
-          const matchedCount = matchingQueuedExtractionPrefixLength(
-            entry.turns,
-            liveExtractedTurns
-          );
-          if (matchedCount > 0) {
-            entry.turns = entry.turns.slice(matchedCount);
-            clearedLiveTurns = true;
+          if (options?.allowNonPrefix === true) {
+            const remainingTurns = [...entry.turns];
+            for (const extractedTurn of liveExtractedTurns) {
+              const matchingIndex = remainingTurns.findIndex(
+                (liveTurn) => bufferTurnsEqual(liveTurn, extractedTurn)
+              );
+              if (matchingIndex >= 0) {
+                remainingTurns.splice(matchingIndex, 1);
+                clearedLiveTurns = true;
+              }
+            }
+            if (clearedLiveTurns) entry.turns = remainingTurns;
           } else {
+            const matchedCount = matchingQueuedExtractionPrefixLength(
+              entry.turns,
+              liveExtractedTurns
+            );
+            if (matchedCount > 0) {
+              entry.turns = entry.turns.slice(matchedCount);
+              clearedLiveTurns = true;
+            }
+          }
+          if (!clearedLiveTurns) {
             log.debug(
               `buffer[${bufferKey}]: extraction clear skipped because live turns changed before clear`
             );
@@ -691,110 +788,8 @@ var SmartBuffer = class {
     await this.surpriseTelemetryWriteChain;
   }
 };
-function describeError(err) {
-  if (err instanceof Error) return err.message;
-  if (err === null) return "null";
-  if (err === void 0) return "undefined";
-  if (typeof err === "string") return err;
-  try {
-    return JSON.stringify(err);
-  } catch {
-    return String(err);
-  }
-}
-function copyBufferTurn(turn) {
-  const copy = {
-    role: turn.role,
-    content: turn.content,
-    timestamp: turn.timestamp
-  };
-  if (typeof turn.sessionKey === "string") copy.sessionKey = turn.sessionKey;
-  if (typeof turn.logicalSessionKey === "string") {
-    copy.logicalSessionKey = turn.logicalSessionKey;
-  }
-  if (turn.providerThreadId === null || typeof turn.providerThreadId === "string") {
-    copy.providerThreadId = turn.providerThreadId;
-  }
-  if (typeof turn.turnFingerprint === "string") {
-    copy.turnFingerprint = turn.turnFingerprint;
-  }
-  if (typeof turn.persistProcessedFingerprint === "boolean") {
-    copy.persistProcessedFingerprint = turn.persistProcessedFingerprint;
-  }
-  if (typeof turn.sourceConnector === "string") {
-    copy.sourceConnector = turn.sourceConnector;
-  }
-  return copy;
-}
-function bufferTurnsEqual(left, right) {
-  if (!left) return false;
-  return left.role === right.role && left.content === right.content && left.timestamp === right.timestamp && left.sessionKey === right.sessionKey && left.logicalSessionKey === right.logicalSessionKey && left.providerThreadId === right.providerThreadId && left.turnFingerprint === right.turnFingerprint && left.persistProcessedFingerprint === right.persistProcessedFingerprint && left.sourceConnector === right.sourceConnector;
-}
-function bufferTurnArraysEqual(left, right) {
-  return left.length === right.length && left.every((turn, index) => bufferTurnsEqual(turn, right[index]));
-}
-function bufferTurnArrayIsSuffixOfSnapshot(liveTurns, snapshot) {
-  if (liveTurns.length === 0 || liveTurns.length > snapshot.length) {
-    return false;
-  }
-  const offset = snapshot.length - liveTurns.length;
-  return liveTurns.every(
-    (turn, index) => bufferTurnsEqual(turn, snapshot[offset + index])
-  );
-}
-function liveTurnsFromExtractionSnapshot(entry, extractedTurns) {
-  const retainedTurns = entry.retainedTurns ?? [];
-  if (retainedTurns.length > 0 && extractedTurns.length >= retainedTurns.length && retainedTurns.every(
-    (turn, index) => bufferTurnsEqual(extractedTurns[index], turn)
-  )) {
-    const withoutRetainedPrefix = extractedTurns.slice(retainedTurns.length);
-    if (withoutRetainedPrefix.length > 0 && matchingPrefixLength(entry.turns, withoutRetainedPrefix) > 0) {
-      return withoutRetainedPrefix;
-    }
-  }
-  return extractedTurns;
-}
-function matchingPrefixLength(liveTurns, extractedTurns) {
-  let index = 0;
-  while (index < liveTurns.length && index < extractedTurns.length && bufferTurnsEqual(liveTurns[index], extractedTurns[index])) {
-    index += 1;
-  }
-  return index;
-}
-function matchingQueuedExtractionPrefixLength(liveTurns, extractedTurns) {
-  let bestMatchedCount = 0;
-  for (let start = 0; start < extractedTurns.length; start += 1) {
-    const matchedCount = matchingPrefixLength(
-      liveTurns,
-      extractedTurns.slice(start)
-    );
-    if (matchedCount > bestMatchedCount) {
-      bestMatchedCount = matchedCount;
-      if (bestMatchedCount === liveTurns.length) break;
-    }
-  }
-  return bestMatchedCount;
-}
-var ProbeTimeoutError = class extends Error {
-  constructor(timeoutMs) {
-    super(`probe exceeded ${timeoutMs}ms`);
-    this.name = "ProbeTimeoutError";
-  }
-};
-function probeWithTimeout(inflight, timeoutMs) {
-  let timer = null;
-  const timeout = new Promise((_, reject) => {
-    timer = setTimeout(() => reject(new ProbeTimeoutError(timeoutMs)), timeoutMs);
-    if (typeof timer.unref === "function") {
-      timer.unref();
-    }
-  });
-  return Promise.race([inflight, timeout]).finally(() => {
-    if (timer) clearTimeout(timer);
-  });
-}
 
 export {
   SmartBuffer
 };
-//# sourceMappingURL=chunk-4A6YGWQN.js.map
+//# sourceMappingURL=chunk-TL4TO3EA.js.map

package/dist/chunk-TL4TO3EA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/buffer.ts"],"sourcesContent":["import { log } from \"./logger.js\";\nimport { throwIfAborted } from \"./abort-error.js\";\nimport { scanSignals } from \"./signal.js\";\nimport type { StorageManager } from \"./storage.js\";\nimport type {\n  BufferEntryState,\n  BufferState,\n  BufferSurpriseEvent,\n  BufferTurn,\n  PluginConfig,\n  SignalLevel,\n} from \"./types.js\";\nimport { resolvePresentationCapabilities } from \"./capabilities.js\";\nimport { resolvePrincipal } from \"./namespaces/principal.js\";\nimport { ExtractionDeadlineError } from \"./orchestration/extraction-run.js\";\nimport type { ExtractionBufferSnapshot } from \"./extraction-liveness.js\";\nimport {\n  bufferTurnArrayIsSuffixOfSnapshot,\n  bufferTurnArraysEqual,\n  bufferTurnsEqual,\n  copyBufferTurn,\n  describeError,\n  liveTurnsFromExtractionSnapshot,\n  matchingQueuedExtractionPrefixLength,\n  probeWithTimeout,\n} from \"./buffer-turn-helpers.js\";\n\nexport type TriggerDecision = \"extract_now\" | \"extract_batch\" | \"keep_buffering\";\n\nexport interface AddTurnOutcome {\n  decision: TriggerDecision;\n  extractionTurns?: BufferTurn[];\n}\n\nexport interface RetainedTurnCleanupOptions {\n  abortSignal?: AbortSignal;\n  deadlineMs?: number;\n}\n\n/**\n * Optional surprise probe injected into `SmartBuffer`.\n *\n * Computes a D-MEM-style novelty score in `[0, 1]` for an incoming turn.\n * The buffer treats the probe as purely additive: if it is not provided, if\n * the feature flag is off, or if the probe throws/times out, the buffer\n * falls back to the existing signal/turn-count/time triggers unchanged.\n *\n * Callers are responsible for sampling recent memories and passing them\n * through the embedding pipeline — the buffer does not want to know about\n * storage, embeddings, or QMD.\n *\n * @param bufferKey Identifier for the active buffer (session/thread).\n * @param turn      The incoming turn whose novelty is being scored.\n * @param recentTurns Turns already buffered for this key (most recent first\n *                    is NOT guaranteed — treat as unordered corpus).\n * @returns A surprise score in `[0, 1]`, or `null` if no score could be\n *          produced (e.g. empty corpus, probe declined to embed).\n */\nexport interface BufferSurpriseProbe {\n  scoreTurn(\n    bufferKey: string,\n    turn: BufferTurn,\n    recentTurns: readonly BufferTurn[],\n  ): Promise<number | null>;\n}\n\nconst MAX_BUFFER_ENTRY_COUNT = 200;\n\n/**\n * Upper bound on how long a debounced buffer save may be deferred under\n * sustained activity (issue #1909). Each new turn re-arms the trailing-edge\n * timer, so a steady stream of turns could otherwise push the save out\n * indefinitely and widen the crash-loss window without bound. Once a pending\n * save has been deferred this many debounce windows, the next scheduled save\n * forces an inline flush instead of re-arming.\n */\nconst BUFFER_SAVE_MAX_DEFER_MULTIPLIER = 5;\n\n/**\n * Node's maximum 32-bit `setTimeout` delay (2^31-1 ms, ~24.8 days). A larger\n * value is overflow-clamped by Node to 1ms with a TimeoutOverflowWarning, so we\n * clamp defensively at every timer arm (issue #1909 review round 5) even though\n * parseConfig already caps `bufferSaveDebounceMs` — a directly-constructed config\n * could still exceed it.\n */\nconst MAX_SET_TIMEOUT_MS = 2_147_483_647;\n\n/**\n * Minimal data carried on the serialized telemetry write chain\n * (issue #563 PR 3).\n *\n * We intentionally do NOT capture the full `BufferTurn` here: under\n * slow filesystem latency the chain can back up, and retaining\n * `turn.content` for every pending append causes memory pressure on\n * large conversations. Only the fields the ledger row actually needs\n * cross the chain boundary.\n */\ninterface SurpriseTelemetryQueueEntry {\n  bufferKey: string;\n  turnRole: \"user\" | \"assistant\";\n  sessionKey: string | null;\n  surpriseScore: number;\n  triggered: boolean;\n  turnCountInWindow: number;\n  /**\n   * ISO timestamp captured at the moment the turn was scored, NOT when\n   * the ledger append eventually runs. Backpressure on the serialized\n   * write chain could otherwise shift event timestamps away from the\n   * real decision moment and distort the distribution report (p90\n   * inflated, current-threshold row misidentified).\n   */\n  timestamp: string;\n  /**\n   * Threshold value in force when `triggered` was computed. Must be\n   * snapshot here rather than read from `config` at emit time — a\n   * concurrent config change between queue and write would otherwise\n   * record `triggered=true` against a newer threshold the operator\n   * never set, distorting precision/recall interpretation.\n   */\n  threshold: number;\n}\n\ninterface AddTurnMutationResult {\n  decision: TriggerDecision;\n  signalLevel: SignalLevel;\n  priorTurns: BufferTurn[];\n  activeTurnsSnapshot: BufferTurn[];\n  retainedTurnsSnapshot: BufferTurn[];\n  turnCountInWindow: number;\n}\n\nexport class SmartBuffer {\n  private state: BufferState;\n  private loaded = false;\n  private loadPromise: Promise<void> | null = null;\n  private readonly surpriseProbe: BufferSurpriseProbe | null;\n  private mutationChain: Promise<unknown> = Promise.resolve();\n  /**\n   * Serialized write chain for `BUFFER_SURPRISE` telemetry events.\n   *\n   * The telemetry path is fire-and-forget (`addTurn` does not await the\n   * ledger append), but multiple concurrent appends would still settle\n   * out of order under variable filesystem latency. The report path\n   * assumes chronological ordering — it slices the tail of the ledger\n   * and treats the most recent entry as the current threshold in force.\n   * Chaining ensures each append only runs after the previous settles,\n   * preserving wall-clock order.\n   *\n   * We include a `.catch` on every link so a rejected append does not\n   * poison the chain (CLAUDE.md rule #40).\n   */\n  private surpriseTelemetryWriteChain: Promise<unknown> = Promise.resolve();\n\n  /**\n   * Debounced buffer-save state (issue #1909). Steady-state buffering used to\n   * serialize + rewrite the whole multi-session buffer on EVERY turn. We now\n   * coalesce those writes onto a trailing-edge timer; correctness boundaries\n   * (extraction trigger, extraction clear, shutdown) still force an immediate\n   * flush. `bufferSaveDebounceMs: 0` restores save-every-turn exactly.\n   */\n  private saveTimer: NodeJS.Timeout | null = null;\n  private pendingSave = false;\n  /** Wall-clock ms when the currently-pending save was first scheduled (issue\n   * #1909). Null when nothing is pending. Used to bound deferral under sustained\n   * activity (see BUFFER_SAVE_MAX_DEFER_MULTIPLIER). */\n  private firstPendingAtMs: number | null = null;\n\n  constructor(\n    private readonly config: PluginConfig,\n    private readonly storage: StorageManager,\n    surpriseProbe: BufferSurpriseProbe | null = null,\n  ) {\n    this.state = { turns: [], lastExtractionAt: null, extractionCount: 0 };\n    this.surpriseProbe = surpriseProbe;\n  }\n\n  private enqueueMutation<T>(op: () => Promise<T>): Promise<T> {\n    const run = this.mutationChain.catch(() => {}).then(op);\n    this.mutationChain = run.catch(() => {});\n    return run;\n  }\n\n  private entryFor(key: string): BufferEntryState {\n    if (!this.state.entries) {\n      this.state.entries = Object.create(null) as NonNullable<BufferState[\"entries\"]>;\n    }\n    const entries = this.state.entries as NonNullable<BufferState[\"entries\"]>;\n    if (Object.hasOwn(entries, key)) {\n      const stored = entries[key];\n      // Guard against corrupted state/buffer.json — if the stored entry\n      // is not a valid object shape, discard it and recreate.\n      if (stored && typeof stored === \"object\" && Array.isArray(stored.turns)) {\n        return stored;\n      }\n      // Corrupted — fall through to recreate.\n    }\n    const created: BufferEntryState = {\n      turns: [],\n      lastExtractionAt: null,\n      extractionCount: 0,\n    };\n    entries[key] = created;\n    return created;\n  }\n\n  private peekEntry(key: string): BufferEntryState | null {\n    const existing = this.state.entries?.[key];\n    if (existing) return existing;\n    if (key !== \"default\") return null;\n    return {\n      turns: Array.isArray(this.state.turns) ? this.state.turns : [],\n      lastExtractionAt: this.state.lastExtractionAt ?? null,\n      extractionCount:\n        typeof this.state.extractionCount === \"number\" ? this.state.extractionCount : 0,\n    };\n  }\n\n  private normalizeState(state: BufferState): BufferState {\n    const entries = Object.assign(\n      Object.create(null),\n      state.entries ?? {},\n    ) as NonNullable<BufferState[\"entries\"]>;\n    if (!entries.default) {\n      entries.default = {\n        turns: Array.isArray(state.turns) ? [...state.turns] : [],\n        lastExtractionAt: state.lastExtractionAt ?? null,\n        extractionCount:\n          typeof state.extractionCount === \"number\" ? state.extractionCount : 0,\n      };\n    }\n    return {\n      turns: entries.default.turns,\n      lastExtractionAt: entries.default.lastExtractionAt,\n      extractionCount: entries.default.extractionCount,\n      entries,\n    };\n  }\n\n  private entryActivityAt(entry: BufferEntryState): number {\n    const lastTurnAt = entry.turns.reduce((latest, turn) => {\n      const parsed = Date.parse(turn.timestamp);\n      return Number.isFinite(parsed) ? Math.max(latest, parsed) : latest;\n    }, -1);\n    const lastExtractionAt =\n      typeof entry.lastExtractionAt === \"string\"\n        ? Date.parse(entry.lastExtractionAt)\n        : Number.NaN;\n    return Math.max(\n      lastTurnAt,\n      Number.isFinite(lastExtractionAt) ? lastExtractionAt : -1,\n    );\n  }\n\n  private pruneEntries(retainKeys: string[]): void {\n    const entries = this.state.entries;\n    if (!entries) return;\n    const keys = Object.keys(entries);\n    if (keys.length <= MAX_BUFFER_ENTRY_COUNT) return;\n\n    const insertionOrder = new Map(keys.map((key, index) => [key, index]));\n    const byOldestActivity = (left: string, right: string): number => {\n      const leftAt = this.entryActivityAt(entries[left] ?? {\n        turns: [],\n        lastExtractionAt: null,\n        extractionCount: 0,\n      });\n      const rightAt = this.entryActivityAt(entries[right] ?? {\n        turns: [],\n        lastExtractionAt: null,\n        extractionCount: 0,\n      });\n      if (leftAt !== rightAt) return leftAt - rightAt;\n      return (insertionOrder.get(left) ?? 0) - (insertionOrder.get(right) ?? 0);\n    };\n    const candidates = keys.filter((key) => key !== \"default\" && !retainKeys.includes(key));\n    const emptyRemovable = candidates\n      .filter((key) => (entries[key]?.turns.length ?? 0) === 0)\n      .sort(byOldestActivity);\n\n    const removableCount = Math.max(0, keys.length - MAX_BUFFER_ENTRY_COUNT);\n    let evicted = emptyRemovable.slice(0, removableCount);\n    if (evicted.length < removableCount) {\n      // Retained failed extractions (#1908 retry retention) keep their turns in\n      // the buffer, so empty entries alone may not bring the map back under the\n      // cap during a provider outage. The cap is the documented bound — evict\n      // the oldest NON-empty sessions too rather than growing unboundedly\n      // (codex review).\n      const nonEmptyRemovable = candidates\n        .filter((key) => (entries[key]?.turns.length ?? 0) > 0)\n        .sort(byOldestActivity);\n      evicted = evicted.concat(nonEmptyRemovable.slice(0, removableCount - evicted.length));\n    }\n    for (const key of evicted) {\n      delete entries[key];\n    }\n    if (evicted.length > 0) {\n      // Loud degradation (extraction hot-loop hardening, Step 7): during a\n      // prolonged provider outage the breaker holds extraction off and buffered\n      // sessions accumulate. Eviction of the oldest empty session entries past\n      // MAX_BUFFER_ENTRY_COUNT is bounded and expected, but must be observable —\n      // not silent — so operators can see buffer pressure.\n      log.warn(\n        `buffer: pruned ${evicted.length} oldest session entr${evicted.length === 1 ? \"y\" : \"ies\"} ` +\n          `past MAX_BUFFER_ENTRY_COUNT=${MAX_BUFFER_ENTRY_COUNT}; buffered turn data for those sessions was dropped`,\n      );\n    }\n  }\n\n  private async loadUnlocked(): Promise<void> {\n    if (this.loaded) return;\n    if (!this.loadPromise) {\n      this.loadPromise = this.storage.loadBuffer()\n        .then((state) => {\n          this.state = this.normalizeState(state);\n          this.loaded = true;\n        })\n        .finally(() => {\n          this.loadPromise = null;\n        });\n    }\n    await this.loadPromise;\n  }\n\n  async load(): Promise<void> {\n    await this.enqueueMutation(async () => this.loadUnlocked());\n  }\n\n  /** Snapshot of buffered, not-yet-extracted work across sessions (#2151): session count,\n   * pending-turn total, oldest buffered turn. Counts retained (#562) + active turns per entry. */\n  async getBufferSnapshot(): Promise<ExtractionBufferSnapshot> {\n    await this.load();\n    let bufferedSessionCount = 0;\n    let pendingTurnCount = 0;\n    let oldestMs = Number.POSITIVE_INFINITY;\n    let oldestTurnTimestamp: string | null = null;\n    const consider = (turns: BufferTurn[] | undefined): void => {\n      if (!Array.isArray(turns) || turns.length === 0) return;\n      bufferedSessionCount += 1;\n      pendingTurnCount += turns.length;\n      const first = turns[0]?.timestamp;\n      const parsed = typeof first === \"string\" ? Date.parse(first) : Number.NaN;\n      if (Number.isFinite(parsed) && parsed < oldestMs) {\n        oldestMs = parsed;\n        oldestTurnTimestamp = first ?? null;\n      }\n    };\n    const entries = this.state.entries;\n    if (entries) {\n      // Retained turns (deferred #562) are pending too - count with active (oldest-first), like getTurns().\n      for (const entry of Object.values(entries)) consider([...(entry?.retainedTurns ?? []), ...(entry?.turns ?? [])]);\n    } else {\n      consider(this.state.turns);\n    }\n    return { bufferedSessionCount, pendingTurnCount, oldestTurnTimestamp };\n  }\n\n  /**\n   * Reset the buffer to an empty, usable state.\n   * Called when the persisted buffer file is corrupt and load() fails,\n   * so the buffer can still accept new turns for the rest of the session.\n   */\n  resetToEmpty(): void {\n    this.state = { turns: [], lastExtractionAt: null, extractionCount: 0 };\n    this.loaded = true;\n  }\n\n  private async saveUnlocked(): Promise<void> {\n    await this.storage.saveBuffer(this.state);\n  }\n\n  async save(): Promise<void> {\n    await this.enqueueMutation(async () => this.saveUnlocked());\n  }\n\n  /**\n   * Schedule a coalesced, TRUE trailing-edge buffer save (issue #1909). Only\n   * used for the debounced (`bufferSaveDebounceMs > 0`) steady-state buffering\n   * path; the debounce-off and correctness-boundary paths save inline within the\n   * mutation (see `recordTurnUnlocked`). Each call re-arms the timer from now so\n   * the write lands one full window after the LAST turn, not the first. To keep\n   * sustained activity from deferring the save without bound (which would widen\n   * the crash-loss window), once a pending save has been deferred\n   * BUFFER_SAVE_MAX_DEFER_MULTIPLIER windows it is flushed inline instead of\n   * re-armed. Runs inside the record mutation, so the inline save is awaited.\n   */\n  private async scheduleSave(): Promise<void> {\n    const ms = Math.min(this.config.bufferSaveDebounceMs, MAX_SET_TIMEOUT_MS);\n    const now = Date.now();\n    this.pendingSave = true;\n    if (this.firstPendingAtMs === null) this.firstPendingAtMs = now;\n    if (now - this.firstPendingAtMs >= ms * BUFFER_SAVE_MAX_DEFER_MULTIPLIER) {\n      // Staleness cap hit: persist now rather than deferring further. Drop the\n      // armed timer, attempt the write, and only mark clean on success — a\n      // failure keeps the save pending + re-arms so shutdown/the next timer\n      // retries (issue #1909 review round 2), never diverging memory from disk.\n      clearTimeout(this.saveTimer ?? undefined);\n      this.saveTimer = null;\n      try {\n        await this.saveUnlocked();\n        this.pendingSave = false;\n        this.firstPendingAtMs = null;\n      } catch (err) {\n        log.warn(`buffer.scheduleSave: staleness-cap save failed, keeping it pending: ${describeError(err)}`);\n        this.saveTimer = setTimeout(() => {\n          this.saveTimer = null;\n          void this.flushPendingSave();\n        }, ms);\n        this.saveTimer.unref?.();\n      }\n      return;\n    }\n    // True trailing edge: drop any armed timer and re-arm from now.\n    clearTimeout(this.saveTimer ?? undefined);\n    this.saveTimer = setTimeout(() => {\n      this.saveTimer = null;\n      void this.flushPendingSave();\n    }, ms);\n    this.saveTimer.unref?.();\n  }\n\n  /** Cancel any armed debounced save without persisting. */\n  private cancelScheduledSave(): void {\n    if (this.saveTimer) {\n      clearTimeout(this.saveTimer);\n      this.saveTimer = null;\n    }\n    this.pendingSave = false;\n    this.firstPendingAtMs = null;\n  }\n\n  /**\n   * Persist the current in-memory buffer state inline, keeping the global\n   * pending-save state armed until the write SUCCEEDS (issue #1909). On failure\n   * the save stays pending and — when debounced — a background retry timer is\n   * (re-)armed before the error propagates, so a graceful shutdown flush and the\n   * next timer tick both retry. A failed post-mutation save therefore can never\n   * silently drop buffered turns, including turns from OTHER sessions that were\n   * only in the debounced pending state. The pending flag is cleared (and any\n   * armed timer dropped) only after a durable write.\n   */\n  private async saveNowRetainingPendingOnFailure(context: string): Promise<void> {\n    this.pendingSave = true;\n    if (this.firstPendingAtMs === null) this.firstPendingAtMs = Date.now();\n    try {\n      await this.saveUnlocked();\n    } catch (err) {\n      log.warn(\n        `buffer.${context}: inline save failed, keeping it pending for retry: ${describeError(err)}`,\n      );\n      const ms = Math.min(this.config.bufferSaveDebounceMs, MAX_SET_TIMEOUT_MS);\n      if (ms > 0 && !this.saveTimer) {\n        this.saveTimer = setTimeout(() => {\n          this.saveTimer = null;\n          void this.flushPendingSave();\n        }, ms);\n        this.saveTimer.unref?.();\n      }\n      throw err;\n    }\n    this.cancelScheduledSave();\n  }\n\n  /**\n   * Force any pending debounced save to land now (issue #1909). Idempotent and\n   * safe to call from outside a mutation (timer tick, shutdown/dispose, or the\n   * surprise-promotion path in `addTurnWithOutcome`). Do NOT `await` this from\n   * inside a mutation — it enqueues its own mutation and would deadlock the\n   * serializer.\n   *\n   * `throwOnFailure` (review round 7 finding 5): when set, a failed write is\n   * rethrown AFTER the keep-pending + re-arm bookkeeping, so the surprise\n   * extraction boundary gets the same durability guarantee as the built-in\n   * extract triggers (which propagate saveUnlocked failures) instead of\n   * proceeding to extract_now on a non-durable triggering turn. Default false\n   * keeps the fail-open behavior for the timer/shutdown callers.\n   */\n  async flushPendingSave(opts?: { throwOnFailure?: boolean }): Promise<void> {\n    if (this.saveTimer) {\n      clearTimeout(this.saveTimer);\n      this.saveTimer = null;\n    }\n    if (!this.pendingSave) return;\n    try {\n      await this.enqueueMutation(async () => {\n        // Re-check under the serializer: a concurrent flush may have already\n        // persisted this pending save. Skip the redundant write (no phantom\n        // writes).\n        if (!this.pendingSave) return;\n        await this.saveUnlocked();\n        // Clear the pending flag INSIDE the same serialized mutation as the\n        // write (issue #1909 review). Clearing it after the enqueue await\n        // resolved raced an addTurn interleaving between the write and the\n        // clear: that turn's scheduleSave re-armed pendingSave + a timer, then\n        // this clear wiped it and the debounced flush was lost. Atomic\n        // write+clear means any addTurn runs wholly before (its turn is in the\n        // write) or wholly after (its pendingSave survives and its timer\n        // persists it).\n        this.pendingSave = false;\n        this.firstPendingAtMs = null;\n      });\n    } catch (err) {\n      // The write failed: memory and disk diverge (issue #1909 review round 2).\n      // Keep the save PENDING (do NOT clear pendingSave/firstPendingAtMs) so a\n      // graceful shutdown flush and the re-armed timer both retry it — clearing\n      // the flag here would drop the buffered turns permanently. Re-arm a\n      // background retry when debounced.\n      log.warn(`buffer.flushPendingSave: save failed, keeping it pending for retry: ${describeError(err)}`);\n      const ms = Math.min(this.config.bufferSaveDebounceMs, MAX_SET_TIMEOUT_MS);\n      if (ms > 0 && !this.saveTimer) {\n        this.saveTimer = setTimeout(() => {\n          this.saveTimer = null;\n          void this.flushPendingSave();\n        }, ms);\n        this.saveTimer.unref?.();\n      }\n      // Surprise-extraction boundary needs the durability guarantee — surface\n      // the failure so the caller does not proceed with a non-durable flush.\n      if (opts?.throwOnFailure) throw err;\n      return; // fail-open for timer/shutdown callers\n    }\n  }\n\n  async addTurn(bufferKey: string, turn: BufferTurn): Promise<TriggerDecision> {\n    return (await this.addTurnWithOutcome(bufferKey, turn)).decision;\n  }\n\n  async addTurnWithOutcome(\n    bufferKey: string,\n    turn: BufferTurn,\n  ): Promise<AddTurnOutcome> {\n    const mutation = await this.enqueueMutation(() => this.recordTurnUnlocked(bufferKey, turn));\n    let decision = mutation.decision;\n    let extractionTurns: BufferTurn[] | undefined;\n\n    // Surprise-gated flush (issue #563). Additive only: if the probe is\n    // disabled, unavailable, or the score is below threshold, the decision\n    // from the existing trigger logic stands. The probe only ever *promotes*\n    // `keep_buffering` → `extract_now`; it never suppresses an existing\n    // flush. This preserves the invariant that enabling surprise cannot\n    // *reduce* extraction frequency.\n    if (\n      decision === \"keep_buffering\" &&\n      resolvePresentationCapabilities(this.config).bufferSurpriseTrigger &&\n      this.surpriseProbe !== null &&\n      // Matching the existing \"smart\" branch: surprise is a lower-tier\n      // novelty signal that should not second-guess a high-signal hit\n      // (which already flushes) or fight `every_n` / `time_based` modes.\n      this.config.triggerMode === \"smart\" &&\n      mutation.signalLevel !== \"high\"\n    ) {\n      const surprise = await this.computeSurpriseSafe(bufferKey, turn, mutation.priorTurns);\n      if (surprise !== null) {\n        const shouldPromote = surprise > this.config.bufferSurpriseThreshold;\n        let triggered = false;\n        if (shouldPromote) {\n          const currentTurns = await this.getExtractionTurnsIfBufferSnapshotStillCurrent(\n            bufferKey,\n            mutation.activeTurnsSnapshot,\n            mutation.retainedTurnsSnapshot,\n          );\n          if (currentTurns) {\n            log.debug(\n              `buffer[${bufferKey}]: surprise=${surprise.toFixed(3)} > threshold=${this.config.bufferSurpriseThreshold} → extract_now`,\n            );\n            decision = \"extract_now\";\n            triggered = true;\n            extractionTurns = currentTurns;\n            // Issue #1909 (review): the record mutation for a `keep_buffering`\n            // turn only SCHEDULED a debounced save. Surprise now promotes it to\n            // extract_now AFTER that mutation, so force the buffer durable before\n            // the caller runs extraction — otherwise state/buffer.json lags the\n            // extracted turns by up to the debounce window on a crash. Safe to\n            // await here: we are outside the record mutation (deadlock-free).\n            // throwOnFailure (round 7 finding 5): match the built-in extract\n            // triggers — a failed durability write must NOT silently proceed to\n            // extract_now on a non-durable turn.\n            await this.flushPendingSave({ throwOnFailure: true });\n          } else {\n            log.debug(\n              `buffer[${bufferKey}]: surprise=${surprise.toFixed(3)} ignored because buffer changed before probe resolved`,\n            );\n          }\n        }\n        // Emit telemetry on every scored turn — both triggering and\n        // non-triggering — so operators can fit the threshold to real\n        // traffic distributions. Fire-and-forget: `addTurn` does NOT\n        // await the ledger append, so slow/contended filesystems cannot\n        // add JSONL-append latency to every `processTurn`. But we DO\n        // serialize writes through a promise chain so concurrent\n        // appends settle in wall-clock order — the report path assumes\n        // chronological tail rows and reads the most recent as the\n        // \"current\" threshold.\n        //\n        // Project only the fields we need into the queue entry rather\n        // than capturing the full `BufferTurn` — under slow filesystem\n        // latency the chain can back up, and we must not retain the\n        // (potentially large) `turn.content` string for every pending\n        // append.\n        this.queueSurpriseTelemetryWrite({\n          bufferKey,\n          turnRole: turn.role,\n          sessionKey:\n            typeof turn.sessionKey === \"string\" ? turn.sessionKey : null,\n          surpriseScore: surprise,\n          triggered,\n          turnCountInWindow: mutation.turnCountInWindow,\n          // Stamp at decision time so backpressure on the write chain\n          // does not shift the event's apparent moment away from when\n          // the turn was actually scored.\n          timestamp: new Date().toISOString(),\n          // Snapshot the threshold used to compute `triggered` so a\n          // concurrent config mutation cannot retroactively change\n          // what the ledger row claims the decision was against.\n          threshold: this.config.bufferSurpriseThreshold,\n        });\n      }\n    }\n\n    log.debug(\n      `buffer[${bufferKey}]: ${mutation.turnCountInWindow} turns, signal=${mutation.signalLevel}, decision=${decision}`,\n    );\n    return extractionTurns ? { decision, extractionTurns } : { decision };\n  }\n\n  private async recordTurnUnlocked(bufferKey: string, turn: BufferTurn): Promise<AddTurnMutationResult> {\n    await this.loadUnlocked();\n    const entry = this.entryFor(bufferKey);\n    const priorTurns = entry.turns.slice();\n    entry.turns.push(turn);\n    const activeTurnsSnapshot = entry.turns.map(copyBufferTurn);\n    const retainedTurnsSnapshot = (entry.retainedTurns ?? []).map(copyBufferTurn);\n    if (bufferKey === \"default\") {\n      this.state.turns = entry.turns;\n    }\n\n    const signal = scanSignals(turn.content, this.config.highSignalPatterns);\n    const decision = this.evaluate(entry, signal.level);\n    const turnCountInWindow = entry.turns.length;\n\n    this.pruneEntries([bufferKey]);\n    if (decision === \"keep_buffering\" && this.config.bufferSaveDebounceMs > 0) {\n      // Steady-state buffering: coalesce the whole-state serialize onto a\n      // trailing-edge timer (issue #1909) instead of rewriting per turn.\n      await this.scheduleSave();\n    } else {\n      // Persist immediately within this mutation (awaited) when either:\n      //  - the turn triggered extraction (the buffer must be durable), or\n      //  - debounce is disabled (bufferSaveDebounceMs <= 0), which reproduces\n      //    the legacy save-every-turn behavior byte-for-byte.\n      // Round 8 thread 4: the write is attempted BEFORE the pending state is\n      // cleared, and a failed write leaves it pending (+ a re-armed timer) for\n      // shutdown/timer retry instead of dropping the in-memory turns.\n      await this.saveNowRetainingPendingOnFailure(\"recordTurn\");\n    }\n    return {\n      decision,\n      signalLevel: signal.level,\n      priorTurns,\n      activeTurnsSnapshot,\n      retainedTurnsSnapshot,\n      turnCountInWindow,\n    };\n  }\n\n  private async getExtractionTurnsIfBufferSnapshotStillCurrent(\n    bufferKey: string,\n    activeTurnsSnapshot: readonly BufferTurn[],\n    retainedTurnsSnapshot: readonly BufferTurn[],\n  ): Promise<BufferTurn[] | null> {\n    return this.enqueueMutation(async () => {\n      await this.loadUnlocked();\n      const entry = this.peekEntry(bufferKey);\n      if (!entry) return null;\n      const retained = entry.retainedTurns ?? [];\n      const stillCurrent =\n        bufferTurnArrayIsSuffixOfSnapshot(entry.turns, activeTurnsSnapshot) &&\n        bufferTurnArraysEqual(retained, retainedTurnsSnapshot);\n      if (!stillCurrent) return null;\n      return [...retained, ...entry.turns];\n    });\n  }\n\n  /**\n   * Enqueue a telemetry append on the serialized write chain.\n   *\n   * The chain is a classic `writeChain = writeChain.then(fn).catch(...)`\n   * — each link waits for the previous to settle before its append\n   * starts, so out-of-order chronology cannot happen even under\n   * variable filesystem latency. We always attach `.catch` so one\n   * rejection does not poison the chain for the rest of the session\n   * (CLAUDE.md rule #40). The error is logged through\n   * `emitSurpriseEventSafe` itself, which swallows its own rejections.\n   *\n   * Public surface is deliberately narrow — only `addTurn` should call\n   * this, so the surprise telemetry path stays centralized.\n   */\n  private queueSurpriseTelemetryWrite(params: SurpriseTelemetryQueueEntry): void {\n    this.surpriseTelemetryWriteChain = this.surpriseTelemetryWriteChain\n      .then(() => this.emitSurpriseEventSafe(params))\n      .catch(() => {\n        // `emitSurpriseEventSafe` already handles the logging. We\n        // swallow here only so one failure does not break the chain\n        // for future writes.\n      });\n  }\n\n  /**\n   * Append a single `BUFFER_SURPRISE` telemetry row (issue #563 PR 3).\n   *\n   * Deliberately swallows write errors: the buffer must never fail to\n   * record a turn because the observation ledger is read-only, out of\n   * disk, or otherwise unhappy. The log line at debug lets operators\n   * confirm the path fired without polluting the error channel.\n   */\n  private async emitSurpriseEventSafe(\n    params: SurpriseTelemetryQueueEntry,\n  ): Promise<void> {\n    const storage = this.storage as StorageManager & {\n      appendBufferSurpriseEvents?: (\n        events: BufferSurpriseEvent[],\n      ) => Promise<number>;\n    };\n    if (typeof storage.appendBufferSurpriseEvents !== \"function\") {\n      // Older StorageManager / test double without the telemetry sink.\n      // Silently skip — core path is still covered by the log line above.\n      return;\n    }\n    const event: BufferSurpriseEvent = {\n      event: \"BUFFER_SURPRISE\",\n      // Use the decision-time stamp captured when the event was\n      // queued, NOT `Date.now()` here — backpressure on the write\n      // chain could otherwise shift timestamps into the future relative\n      // to when the turn was scored.\n      timestamp: params.timestamp,\n      bufferKey: params.bufferKey,\n      sessionKey: params.sessionKey,\n      turnRole: params.turnRole,\n      surpriseScore: params.surpriseScore,\n      // Use the snapshotted threshold from the queue entry, not the\n      // live config — see `SurpriseTelemetryQueueEntry.threshold`\n      // doc for the rationale.\n      threshold: params.threshold,\n      triggeredFlush: params.triggered,\n      turnCountInWindow: params.turnCountInWindow,\n    };\n    try {\n      await storage.appendBufferSurpriseEvents([event]);\n    } catch (err) {\n      // Same guard as `computeSurpriseSafe`: non-Error rejections must\n      // not crash the telemetry helper, which would defeat the whole\n      // point of isolating the ledger write from the hot path.\n      log.debug(\n        `buffer[${params.bufferKey}]: surprise telemetry write failed, continuing: ${describeError(err)}`,\n      );\n    }\n  }\n\n  /**\n   * Invoke the injected surprise probe defensively. Any error (probe throws,\n   * embedder unavailable, timeout) is swallowed and logged at debug: the\n   * surprise path must never crash the happy-path trigger evaluation. A\n   * `null` return indicates \"no score available, fall through to existing\n   * triggers\".\n   */\n  private async computeSurpriseSafe(\n    bufferKey: string,\n    turn: BufferTurn,\n    priorTurns: readonly BufferTurn[],\n  ): Promise<number | null> {\n    if (!this.surpriseProbe) return null;\n    try {\n      // Hard timeout around the probe so a hung embedder cannot stall\n      // `addTurn()` before `save()`. A slow probe would otherwise\n      // prevent the just-appended turn from ever being persisted. The\n      // timeout is a soft bound — we race it against the probe, take\n      // whichever settles first, and treat the timeout as\n      // \"probe unavailable, fall through\" rather than an error that\n      // surfaces to the caller.\n      const score = await probeWithTimeout(\n        this.surpriseProbe.scoreTurn(bufferKey, turn, priorTurns),\n        this.config.bufferSurpriseProbeTimeoutMs,\n      );\n      if (score === null) return null;\n      if (typeof score !== \"number\" || !Number.isFinite(score)) {\n        log.debug(\n          `buffer[${bufferKey}]: surprise probe returned non-finite score (${String(score)}), ignoring`,\n        );\n        return null;\n      }\n      // Defensive clamp: formula lives in buffer-surprise.ts, but we never\n      // want a misbehaving probe to inject an out-of-range value into the\n      // threshold comparison.\n      if (score < 0) return 0;\n      if (score > 1) return 1;\n      return score;\n    } catch (err) {\n      // `err` may be any thrown value — `throw null` and\n      // `Promise.reject(\"x\")` are both legal. Accessing `.message` on a\n      // non-Error would itself throw and defeat the failure-isolation\n      // contract, so describe the value safely.\n      log.debug(\n        `buffer[${bufferKey}]: surprise probe failed, falling back to existing triggers: ${describeError(err)}`,\n      );\n      return null;\n    }\n  }\n\n  private evaluate(entry: BufferEntryState, signalLevel: SignalLevel): TriggerDecision {\n    if (this.config.triggerMode === \"smart\") {\n      if (signalLevel === \"high\") return \"extract_now\";\n\n      if (entry.turns.length >= this.config.bufferMaxTurns) {\n        return \"extract_batch\";\n      }\n\n      if (entry.lastExtractionAt) {\n        const elapsed =\n          Date.now() - new Date(entry.lastExtractionAt).getTime();\n        if (elapsed >= this.config.bufferMaxMinutes * 60_000) {\n          return \"extract_batch\";\n        }\n      }\n\n      return \"keep_buffering\";\n    }\n\n    if (this.config.triggerMode === \"every_n\") {\n      return entry.turns.length >= this.config.bufferMaxTurns\n        ? \"extract_batch\"\n        : \"keep_buffering\";\n    }\n\n    if (this.config.triggerMode === \"time_based\") {\n      if (!entry.lastExtractionAt) {\n        return entry.turns.length >= this.config.bufferMaxTurns\n          ? \"extract_batch\"\n          : \"keep_buffering\";\n      }\n      const elapsed =\n        Date.now() - new Date(entry.lastExtractionAt).getTime();\n      return elapsed >= this.config.bufferMaxMinutes * 60_000\n        ? \"extract_batch\"\n        : \"keep_buffering\";\n    }\n\n    return \"keep_buffering\";\n  }\n\n  getTurns(bufferKey = \"default\"): BufferTurn[] {\n    const entry = this.peekEntry(bufferKey);\n    if (!entry) return [];\n    const retained = entry.retainedTurns ?? [];\n    // Retained turns (from a previous defer verdict, issue #562 PR 2) are\n    // prepended so the chronological order — oldest context first — is\n    // preserved for the next extraction pass.\n    return [...retained, ...entry.turns];\n  }\n\n  /**\n   * Retain a subset of the current turns across `clearAfterExtraction` so a\n   * future extraction pass sees the context behind a deferred candidate\n   * (issue #562, PR 2). Callers pass the turns that were seen during the\n   * current extraction; the buffer keeps the tail (latest `max` turns) as\n   * the retention window. Passing an empty array or `max <= 0` clears the\n   * retention slot instead.\n   */\n  async retainDeferredTurns(\n    bufferKey: string,\n    turns: BufferTurn[],\n    max = 10,\n  ): Promise<void> {\n    await this.enqueueMutation(async () => {\n      await this.loadUnlocked();\n      const entry = this.entryFor(bufferKey);\n      if (!Array.isArray(turns) || turns.length === 0 || max <= 0) {\n        delete entry.retainedTurns;\n      } else {\n        // Guard `slice(-max)` against `max === 0` (CLAUDE.md gotcha 27):\n        // `slice(-0)` equals `slice(0)` and would return ALL entries. We\n        // already early-return above when max <= 0.\n        const tail = turns.slice(-max);\n        // Copy explicit fields only — never spread an external object into a\n        // plain object because spread preserves any own `__proto__` /\n        // `constructor` keys that may have arrived via JSON deserialization\n        // of untrusted input (CodeQL js/prototype-polluting-assignment).\n        entry.retainedTurns = tail.map<BufferTurn>((t) => {\n          const copy: BufferTurn = {\n            role: t.role,\n            content: typeof t.content === \"string\" ? t.content : \"\",\n            timestamp:\n              typeof t.timestamp === \"string\"\n                ? t.timestamp\n                : new Date().toISOString(),\n          };\n          if (typeof t.sessionKey === \"string\") copy.sessionKey = t.sessionKey;\n          if (typeof t.sessionOwnerPrincipal === \"string\") {\n            copy.sessionOwnerPrincipal = t.sessionOwnerPrincipal;\n          }\n          if (typeof t.logicalSessionKey === \"string\") {\n            copy.logicalSessionKey = t.logicalSessionKey;\n          }\n          if (\n            t.providerThreadId === null ||\n            typeof t.providerThreadId === \"string\"\n          ) {\n            copy.providerThreadId = t.providerThreadId;\n          }\n          if (typeof t.turnFingerprint === \"string\") {\n            copy.turnFingerprint = t.turnFingerprint;\n          }\n          if (typeof t.persistProcessedFingerprint === \"boolean\") {\n            copy.persistProcessedFingerprint = t.persistProcessedFingerprint;\n          }\n          if (typeof t.sourceConnector === \"string\") copy.sourceConnector = t.sourceConnector;\n          return copy;\n        });\n      }\n      await this.saveUnlocked();\n    });\n  }\n\n\n  /**\n   * Return the current retention window (issue #562, PR 2). Primarily for\n   * tests and diagnostics.\n   */\n  getRetainedDeferredTurns(bufferKey = \"default\"): BufferTurn[] {\n    const entry = this.peekEntry(bufferKey);\n    return entry?.retainedTurns ? [...entry.retainedTurns] : [];\n  }\n\n  /**\n   * Clear deferred retention copies for a force-flushed session. Normal\n   * extraction preserves these copies so a deferred candidate can be retried;\n   * an explicit force flush is the caller's request to drain that context.\n   */\n  async clearRetainedTurnsForSession(\n    sessionKey: string,\n    ownerPrincipal?: string,\n    options: RetainedTurnCleanupOptions = {},\n  ): Promise<void> {\n    if (typeof sessionKey !== \"string\" || sessionKey.length === 0) return;\n    const normalizedOwnerPrincipal =\n      typeof ownerPrincipal === \"string\" && ownerPrincipal.trim().length > 0\n        ? ownerPrincipal.trim()\n        : undefined;\n    const assertLifecycle = (): void => {\n      throwIfAborted(options.abortSignal, \"extraction force-flush aborted\");\n      if (typeof options.deadlineMs === \"number\" && Date.now() >= options.deadlineMs) {\n        throw new ExtractionDeadlineError(\"retained_turn_cleanup\");\n      }\n    };\n    assertLifecycle();\n    await this.enqueueMutation(async () => {\n      assertLifecycle();\n      const hadPendingSave = this.pendingSave;\n      if (this.saveTimer) {\n        clearTimeout(this.saveTimer);\n        this.saveTimer = null;\n      }\n      await this.loadUnlocked();\n      assertLifecycle();\n      const bufferKeys = this.matchingSessionBufferKeysUnlocked(sessionKey);\n      if (bufferKeys.length === 0) {\n        if (hadPendingSave) {\n          assertLifecycle();\n          await this.saveNowRetainingPendingOnFailure(\"clearRetainedTurnsForSession\");\n        }\n        return;\n      }\n      let changed = false;\n      const belongsToOwner = (turn: BufferTurn): boolean => {\n        if (turn.sessionKey !== sessionKey) return false;\n        if (normalizedOwnerPrincipal === undefined) return true;\n        if (turn.sessionOwnerPrincipal === normalizedOwnerPrincipal) return true;\n        return (\n          turn.sessionOwnerPrincipal === undefined &&\n          resolvePrincipal(turn.sessionKey, this.config) === normalizedOwnerPrincipal\n        );\n      };\n      for (const bufferKey of bufferKeys) {\n        const entry = this.entryFor(bufferKey);\n        const retainedTurns = entry.retainedTurns ?? [];\n        const remainingTurns = retainedTurns.filter((turn) => !belongsToOwner(turn));\n        if (remainingTurns.length === retainedTurns.length) continue;\n        changed = true;\n        if (remainingTurns.length > 0) entry.retainedTurns = remainingTurns;\n        else delete entry.retainedTurns;\n        if (bufferKey === \"default\") this.state.turns = entry.turns;\n      }\n      if (changed || hadPendingSave) {\n        assertLifecycle();\n        await this.saveNowRetainingPendingOnFailure(\"clearRetainedTurnsForSession\");\n      }\n      assertLifecycle();\n    });\n  }\n\n  async findBufferKeyForSession(sessionKey: string): Promise<string | null> {\n    const bufferKeys = await this.findBufferKeysForSession(sessionKey);\n    return bufferKeys[0] ?? null;\n  }\n\n  private matchingSessionBufferKeysUnlocked(sessionKey: string): string[] {\n    const matches: string[] = [];\n    const hasSessionTurns = (entry: BufferEntryState | null | undefined): boolean =>\n      [...(entry?.turns ?? []), ...(entry?.retainedTurns ?? [])].some(\n        (turn) => typeof turn.sessionKey === \"string\" && turn.sessionKey === sessionKey,\n      );\n    const directEntry = this.peekEntry(sessionKey);\n    if (hasSessionTurns(directEntry)) {\n      matches.push(sessionKey);\n    }\n\n    const entries = this.state.entries ?? {};\n    for (const [bufferKey, entry] of Object.entries(entries)) {\n      if (!matches.includes(bufferKey) && hasSessionTurns(entry)) {\n        matches.push(bufferKey);\n      }\n    }\n\n    return matches;\n  }\n\n  async findBufferKeysForSession(sessionKey: string): Promise<string[]> {\n    if (typeof sessionKey !== \"string\" || sessionKey.length === 0) return [];\n    await this.mutationChain.catch(() => {});\n    await this.load();\n    return this.matchingSessionBufferKeysUnlocked(sessionKey);\n  }\n\n  async clearAfterExtraction(\n    bufferKey = \"default\",\n    extractedTurns?: readonly BufferTurn[],\n    options?: { allowNonPrefix?: boolean },\n  ): Promise<void> {\n    await this.enqueueMutation(async () => {\n      // Drop any armed debounce TIMER so it cannot fire mid-mutation and race\n      // our post-clear write, but KEEP the pending-save state (issue #1909\n      // review round 13): the post-clear save below can fail, and clearing the\n      // pending flag here would strand buffered turns — including turns from\n      // OTHER sessions that only ever entered the debounced pending state — with\n      // nothing left to retry them. saveNowRetainingPendingOnFailure clears the\n      // pending state only after a durable write, or re-arms it on failure.\n      if (this.saveTimer) {\n        clearTimeout(this.saveTimer);\n        this.saveTimer = null;\n      }\n      await this.loadUnlocked();\n      const entry = this.entryFor(bufferKey);\n      if (Array.isArray(extractedTurns)) {\n        const liveExtractedTurns = liveTurnsFromExtractionSnapshot(\n          entry,\n          extractedTurns,\n        );\n        let clearedLiveTurns = false;\n        if (liveExtractedTurns.length > 0) {\n          if (options?.allowNonPrefix === true) {\n            const remainingTurns = [...entry.turns];\n            for (const extractedTurn of liveExtractedTurns) {\n              const matchingIndex = remainingTurns.findIndex((liveTurn) =>\n                bufferTurnsEqual(liveTurn, extractedTurn),\n              );\n              if (matchingIndex >= 0) {\n                remainingTurns.splice(matchingIndex, 1);\n                clearedLiveTurns = true;\n              }\n            }\n            if (clearedLiveTurns) entry.turns = remainingTurns;\n          } else {\n            const matchedCount = matchingQueuedExtractionPrefixLength(\n              entry.turns,\n              liveExtractedTurns,\n            );\n            if (matchedCount > 0) {\n              entry.turns = entry.turns.slice(matchedCount);\n              clearedLiveTurns = true;\n            }\n          }\n          if (!clearedLiveTurns) {\n            log.debug(\n              `buffer[${bufferKey}]: extraction clear skipped because live turns changed before clear`,\n            );\n          }\n        }\n        if (!clearedLiveTurns) {\n          await this.saveNowRetainingPendingOnFailure(\"clearAfterExtraction\");\n          return;\n        }\n      } else {\n        entry.turns = [];\n      }\n      entry.lastExtractionAt = new Date().toISOString();\n      entry.extractionCount += 1;\n      if (bufferKey === \"default\") {\n        this.state.turns = entry.turns;\n        this.state.lastExtractionAt = entry.lastExtractionAt;\n        this.state.extractionCount = entry.extractionCount;\n      }\n      this.pruneEntries([bufferKey]);\n      await this.saveNowRetainingPendingOnFailure(\"clearAfterExtraction\");\n    });\n  }\n\n  getExtractionCount(bufferKey = \"default\"): number {\n    return this.peekEntry(bufferKey)?.extractionCount ?? 0;\n  }\n\n  /**\n   * Await any pending `BUFFER_SURPRISE` telemetry writes.\n   *\n   * The telemetry path is fire-and-forget from the hot path's point of\n   * view, but tests and before-exit hooks sometimes need to make sure\n   * the ledger has been flushed before they assert on its contents or\n   * close the process. This method resolves once the current chain\n   * head has settled; new writes scheduled after this call return a\n   * separate, later settlement.\n   *\n   * Never throws — the chain already catches its own rejections.\n   */\n  async flushSurpriseTelemetry(): Promise<void> {\n    await this.surpriseTelemetryWriteChain;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-VI2JQPNQ.js → chunk-U7QYBSQJ.js}

@@ -7,7 +7,7 @@ import {
 } from "./chunk-FQC3DHH2.js";
 import {
   StorageManager
-} from "./chunk-RGIWINDN.js";
+} from "./chunk-FHBITMRY.js";
 import {
   parseContinuityImprovementLoops
 } from "./chunk-LDXUBPMO.js";
@@ -1283,4 +1283,4 @@ export {
   defaultTierMigrationCycleBudget,
   CompoundingEngine
 };
-//# sourceMappingURL=chunk-VI2JQPNQ.js.map
+//# sourceMappingURL=chunk-U7QYBSQJ.js.map

package/dist/chunk-ULARSG5Z.js

@@ -0,0 +1,203 @@
+import {
+  combineNamespaces,
+  expandScopeProfileReadNamespaces,
+  lcmReadSessionIdsForNamespaces,
+  resolveCodingNamespaceOverlay,
+  resolveScopeProfilePlan
+} from "./chunk-BUE5E2HL.js";
+import {
+  namespaceIdentityFromToken,
+  namespaceIdentityToken
+} from "./chunk-EGGE52UU.js";
+import {
+  canReadNamespace,
+  canWriteNamespace,
+  defaultNamespaceForPrincipal,
+  recallNamespacesForPrincipal,
+  resolvePrincipal
+} from "./chunk-3GD2HFR6.js";
+import {
+  resolveNamespaceCapabilities
+} from "./chunk-2XRE6FLM.js";
+
+// src/scopes/scope-plan.ts
+import path from "path";
+function resolveScopePlan(options) {
+  const { config, sessionKey } = options;
+  const namespaceOverride = options.namespace?.trim() || void 0;
+  const principal = typeof options.principalOverride === "string" && options.principalOverride.length > 0 ? options.principalOverride : resolvePrincipal(sessionKey, config);
+  const namespaceOverrideReadable = namespaceOverride !== void 0 && canReadNamespace(principal, namespaceOverride, config);
+  const readableRecallNamespaces = recallNamespacesForPrincipal(principal, config);
+  const namespacesEnabled = options.namespacesEnabled;
+  const codingOverlay = namespaceOverrideReadable || !namespacesEnabled ? null : resolveCodingNamespaceOverlay(
+    options.codingContext ?? null,
+    config.codingMode,
+    config.defaultNamespace
+  );
+  const principalSelfNamespace = defaultNamespaceForPrincipal(principal, config);
+  const codingSelfNamespace = codingOverlay ? combineNamespaces(principalSelfNamespace, codingOverlay.namespace) : null;
+  const scopeProfilePlan = namespaceOverrideReadable ? null : resolveScopeProfilePlan({
+    config,
+    principal,
+    codingContext: options.codingContext ?? null,
+    codingOverlay
+  });
+  const profileEffectiveNamespace = scopeProfilePlan?.writeNamespace || scopeProfilePlan?.readNamespaces[0];
+  const baseNamespace = namespaceOverrideReadable ? namespaceOverride : profileEffectiveNamespace ?? codingSelfNamespace ?? principalSelfNamespace;
+  let readNamespaces;
+  if (namespaceOverrideReadable) {
+    readNamespaces = [namespaceOverride];
+  } else if (scopeProfilePlan) {
+    readNamespaces = expandScopeProfileReadNamespaces({
+      profilePlan: scopeProfilePlan,
+      principalSelfNamespace: scopeProfilePlan.baseNamespace,
+      config,
+      principal,
+      codingOverlay,
+      legacyRecallNamespaces: readableRecallNamespaces
+    });
+  } else if (codingOverlay && codingSelfNamespace) {
+    const mapped = readableRecallNamespaces.map(
+      (ns) => ns === principalSelfNamespace ? codingSelfNamespace : ns
+    );
+    const fallbackNs = codingOverlay.readFallbacks.map(
+      (fallback) => combineNamespaces(principalSelfNamespace, fallback)
+    );
+    readNamespaces = Array.from(/* @__PURE__ */ new Set([...mapped, ...fallbackNs]));
+  } else {
+    readNamespaces = readableRecallNamespaces;
+  }
+  const readFallbacks = codingOverlay ? codingOverlay.readFallbacks.map((fb) => combineNamespaces(principalSelfNamespace, fb)) : [];
+  const codingOverlaySelfReadable = codingOverlay !== null && (scopeProfilePlan ? scopeProfilePlan.layers.some((layer) => layer.id === "userProject" && layer.readable) : readableRecallNamespaces.includes(principalSelfNamespace));
+  let lcmReadNamespaces;
+  if (namespaceOverrideReadable) {
+    lcmReadNamespaces = [namespaceOverride];
+  } else if (scopeProfilePlan) {
+    lcmReadNamespaces = readNamespaces;
+  } else if (codingOverlay && codingSelfNamespace && codingOverlaySelfReadable) {
+    const fallbackNs = codingOverlay.readFallbacks.map(
+      (fallback) => combineNamespaces(principalSelfNamespace, fallback)
+    );
+    lcmReadNamespaces = [codingSelfNamespace, ...fallbackNs];
+  } else {
+    lcmReadNamespaces = [config.defaultNamespace];
+  }
+  const lcmReadSessionIds = scopeProfilePlan && !sessionKey ? [] : lcmReadSessionIdsForNamespaces(lcmReadNamespaces, sessionKey, config.defaultNamespace);
+  return {
+    principal,
+    namespaceOverride: namespaceOverrideReadable ? namespaceOverride : void 0,
+    baseNamespace,
+    readNamespaces,
+    readFallbacks,
+    lcmReadNamespaces,
+    lcmReadSessionIds,
+    codingOverlay: codingOverlay ? { namespace: codingOverlay.namespace, readFallbacks: codingOverlay.readFallbacks } : null,
+    scopeProfilePlan
+  };
+}
+function getConfiguredNamespaces(config) {
+  return Array.from(
+    new Set(
+      [
+        config.defaultNamespace,
+        config.sharedNamespace,
+        ...config.namespacePolicies.map((policy) => policy.name)
+      ].map((value) => value.trim()).filter(Boolean)
+    )
+  );
+}
+function resolveNamespaceFromStorageDir(storageDir, options) {
+  const { config } = options;
+  if (!resolveNamespaceCapabilities(config).namespaces) return config.defaultNamespace;
+  const resolvedStorageDir = path.resolve(storageDir);
+  const resolvedMemoryDir = path.resolve(config.memoryDir);
+  if (resolvedStorageDir === resolvedMemoryDir) return config.defaultNamespace;
+  const m = resolvedStorageDir.match(/[\\/]namespaces[\\/]([^\\/]+)$/);
+  if (!m?.[1]) return config.defaultNamespace;
+  const dirName = m[1];
+  if (options.configuredNamespaces.includes(dirName)) {
+    return dirName;
+  }
+  options.loadHints?.();
+  const hints = options.hints;
+  const hintedNamespaces = hints?.get(resolvedStorageDir);
+  if (hintedNamespaces?.has(dirName)) {
+    return dirName;
+  }
+  if (hintedNamespaces?.size === 1) {
+    const [hintedNamespace] = hintedNamespaces;
+    if (hintedNamespace) return hintedNamespace;
+  }
+  const decoded = namespaceIdentityFromToken(dirName);
+  if (decoded && namespaceIdentityToken(decoded) === dirName) {
+    return decoded;
+  }
+  return dirName;
+}
+function resolveWritableNamespaceValue(namespace, sessionKey, authenticatedPrincipal, config) {
+  const requested = namespace?.trim();
+  let resolved;
+  if (!requested) {
+    resolved = config.defaultNamespace;
+  } else if (!resolveNamespaceCapabilities(config).namespaces && requested !== config.defaultNamespace) {
+    return { ok: false, reason: "unsupported", namespace: requested };
+  } else {
+    resolved = requested;
+  }
+  const trusted = authenticatedPrincipal?.trim();
+  const principal = typeof trusted === "string" && trusted.length > 0 ? trusted : resolvePrincipal(sessionKey, config);
+  if (!canWriteNamespace(principal, resolved, config)) {
+    return { ok: false, reason: "not_writable", namespace: resolved };
+  }
+  return { ok: true, namespace: resolved };
+}
+function resolveScopedWritableNamespaceValue(input) {
+  const requested = input.namespace?.trim();
+  if (requested) {
+    return resolveWritableNamespaceValue(
+      requested,
+      input.sessionKey,
+      input.authenticatedPrincipal,
+      input.config
+    );
+  }
+  if (input.scopeProfile) {
+    const selectedLayer = input.scopeProfile.layers.find(
+      (layer) => layer.id === input.scopeProfile?.writeLayer
+    );
+    const writeNamespaceReadable = input.scopeProfile.writeNamespace.length > 0 && input.scopeProfile.readNamespaces.includes(input.scopeProfile.writeNamespace);
+    if (!selectedLayer?.writable || !writeNamespaceReadable) {
+      return {
+        ok: false,
+        reason: "not_writable",
+        namespace: input.scopeProfile.writeNamespace
+      };
+    }
+    return { ok: true, namespace: input.scopeProfile.writeNamespace };
+  }
+  if (!input.codingOverlay) {
+    return resolveWritableNamespaceValue(
+      void 0,
+      input.sessionKey,
+      input.authenticatedPrincipal,
+      input.config
+    );
+  }
+  const baseNamespace = defaultNamespaceForPrincipal(input.principal, input.config);
+  if (!canWriteNamespace(input.principal, baseNamespace, input.config)) {
+    return { ok: false, reason: "not_writable", namespace: baseNamespace };
+  }
+  return {
+    ok: true,
+    namespace: combineNamespaces(baseNamespace, input.codingOverlay.namespace)
+  };
+}
+
+export {
+  resolveScopePlan,
+  getConfiguredNamespaces,
+  resolveNamespaceFromStorageDir,
+  resolveWritableNamespaceValue,
+  resolveScopedWritableNamespaceValue
+};
+//# sourceMappingURL=chunk-ULARSG5Z.js.map