@remnic/core 9.69.55 → 9.69.57

package/dist/chunk-3JLWSFTV.js

@@ -0,0 +1,801 @@
+import {
+  bufferTurnArrayIsSuffixOfSnapshot,
+  bufferTurnArraysEqual,
+  bufferTurnsEqual,
+  copyBufferTurn,
+  describeError,
+  liveTurnsFromExtractionSnapshot,
+  matchingQueuedExtractionPrefixLength,
+  probeWithTimeout
+} from "./chunk-2AD5SXO4.js";
+import {
+  scanSignals
+} from "./chunk-H3FZVNRN.js";
+import {
+  ExtractionDeadlineError
+} from "./chunk-FF2XYADH.js";
+import {
+  resolvePrincipal
+} from "./chunk-MRV7VSQK.js";
+import {
+  resolvePresentationCapabilities
+} from "./chunk-JUOZ62Y7.js";
+import {
+  throwIfAborted
+} from "./chunk-BTTPKDIL.js";
+import {
+  log
+} from "./chunk-3WCASNQZ.js";
+
+// src/buffer.ts
+var MAX_BUFFER_ENTRY_COUNT = 200;
+var BUFFER_SAVE_MAX_DEFER_MULTIPLIER = 5;
+var MAX_SET_TIMEOUT_MS = 2147483647;
+var SmartBuffer = class {
+  constructor(config, storage, surpriseProbe = null) {
+    this.config = config;
+    this.storage = storage;
+    this.state = { turns: [], lastExtractionAt: null, extractionCount: 0 };
+    this.surpriseProbe = surpriseProbe;
+  }
+  config;
+  storage;
+  state;
+  loaded = false;
+  loadPromise = null;
+  surpriseProbe;
+  mutationChain = Promise.resolve();
+  /**
+   * Serialized write chain for `BUFFER_SURPRISE` telemetry events.
+   *
+   * The telemetry path is fire-and-forget (`addTurn` does not await the
+   * ledger append), but multiple concurrent appends would still settle
+   * out of order under variable filesystem latency. The report path
+   * assumes chronological ordering — it slices the tail of the ledger
+   * and treats the most recent entry as the current threshold in force.
+   * Chaining ensures each append only runs after the previous settles,
+   * preserving wall-clock order.
+   *
+   * We include a `.catch` on every link so a rejected append does not
+   * poison the chain (CLAUDE.md rule #40).
+   */
+  surpriseTelemetryWriteChain = Promise.resolve();
+  /**
+   * Debounced buffer-save state (issue #1909). Steady-state buffering used to
+   * serialize + rewrite the whole multi-session buffer on EVERY turn. We now
+   * coalesce those writes onto a trailing-edge timer; correctness boundaries
+   * (extraction trigger, extraction clear, shutdown) still force an immediate
+   * flush. `bufferSaveDebounceMs: 0` restores save-every-turn exactly.
+   */
+  saveTimer = null;
+  pendingSave = false;
+  /** Wall-clock ms when the currently-pending save was first scheduled (issue
+   * #1909). Null when nothing is pending. Used to bound deferral under sustained
+   * activity (see BUFFER_SAVE_MAX_DEFER_MULTIPLIER). */
+  firstPendingAtMs = null;
+  enqueueMutation(op) {
+    const run = this.mutationChain.catch(() => {
+    }).then(op);
+    this.mutationChain = run.catch(() => {
+    });
+    return run;
+  }
+  entryFor(key) {
+    if (!this.state.entries) {
+      this.state.entries = /* @__PURE__ */ Object.create(null);
+    }
+    const entries = this.state.entries;
+    if (Object.hasOwn(entries, key)) {
+      const stored = entries[key];
+      if (stored && typeof stored === "object" && Array.isArray(stored.turns)) {
+        return stored;
+      }
+    }
+    const created = {
+      turns: [],
+      lastExtractionAt: null,
+      extractionCount: 0
+    };
+    entries[key] = created;
+    return created;
+  }
+  peekEntry(key) {
+    const existing = this.state.entries?.[key];
+    if (existing) return existing;
+    if (key !== "default") return null;
+    return {
+      turns: Array.isArray(this.state.turns) ? this.state.turns : [],
+      lastExtractionAt: this.state.lastExtractionAt ?? null,
+      extractionCount: typeof this.state.extractionCount === "number" ? this.state.extractionCount : 0
+    };
+  }
+  normalizeState(state) {
+    const entries = Object.assign(
+      /* @__PURE__ */ Object.create(null),
+      state.entries ?? {}
+    );
+    if (!entries.default) {
+      entries.default = {
+        turns: Array.isArray(state.turns) ? [...state.turns] : [],
+        lastExtractionAt: state.lastExtractionAt ?? null,
+        extractionCount: typeof state.extractionCount === "number" ? state.extractionCount : 0
+      };
+    }
+    return {
+      turns: entries.default.turns,
+      lastExtractionAt: entries.default.lastExtractionAt,
+      extractionCount: entries.default.extractionCount,
+      entries
+    };
+  }
+  entryActivityAt(entry) {
+    const lastTurnAt = entry.turns.reduce((latest, turn) => {
+      const parsed = Date.parse(turn.timestamp);
+      return Number.isFinite(parsed) ? Math.max(latest, parsed) : latest;
+    }, -1);
+    const lastExtractionAt = typeof entry.lastExtractionAt === "string" ? Date.parse(entry.lastExtractionAt) : Number.NaN;
+    return Math.max(
+      lastTurnAt,
+      Number.isFinite(lastExtractionAt) ? lastExtractionAt : -1
+    );
+  }
+  pruneEntries(retainKeys) {
+    const entries = this.state.entries;
+    if (!entries) return;
+    const keys = Object.keys(entries);
+    if (keys.length <= MAX_BUFFER_ENTRY_COUNT) return;
+    const insertionOrder = new Map(keys.map((key, index) => [key, index]));
+    const byOldestActivity = (left, right) => {
+      const leftAt = this.entryActivityAt(entries[left] ?? {
+        turns: [],
+        lastExtractionAt: null,
+        extractionCount: 0
+      });
+      const rightAt = this.entryActivityAt(entries[right] ?? {
+        turns: [],
+        lastExtractionAt: null,
+        extractionCount: 0
+      });
+      if (leftAt !== rightAt) return leftAt - rightAt;
+      return (insertionOrder.get(left) ?? 0) - (insertionOrder.get(right) ?? 0);
+    };
+    const candidates = keys.filter((key) => key !== "default" && !retainKeys.includes(key));
+    const emptyRemovable = candidates.filter((key) => (entries[key]?.turns.length ?? 0) === 0).sort(byOldestActivity);
+    const removableCount = Math.max(0, keys.length - MAX_BUFFER_ENTRY_COUNT);
+    let evicted = emptyRemovable.slice(0, removableCount);
+    if (evicted.length < removableCount) {
+      const nonEmptyRemovable = candidates.filter((key) => (entries[key]?.turns.length ?? 0) > 0).sort(byOldestActivity);
+      evicted = evicted.concat(nonEmptyRemovable.slice(0, removableCount - evicted.length));
+    }
+    for (const key of evicted) {
+      delete entries[key];
+    }
+    if (evicted.length > 0) {
+      log.warn(
+        `buffer: pruned ${evicted.length} oldest session entr${evicted.length === 1 ? "y" : "ies"} past MAX_BUFFER_ENTRY_COUNT=${MAX_BUFFER_ENTRY_COUNT}; buffered turn data for those sessions was dropped`
+      );
+    }
+  }
+  async loadUnlocked() {
+    if (this.loaded) return;
+    if (!this.loadPromise) {
+      this.loadPromise = this.storage.loadBuffer().then((state) => {
+        this.state = this.normalizeState(state);
+        this.loaded = true;
+      }).finally(() => {
+        this.loadPromise = null;
+      });
+    }
+    await this.loadPromise;
+  }
+  async load() {
+    await this.enqueueMutation(async () => this.loadUnlocked());
+  }
+  /** Snapshot of buffered, not-yet-extracted work across sessions (#2151): session count,
+   * pending-turn total, oldest buffered turn. Counts retained (#562) + active turns per entry. */
+  async getBufferSnapshot() {
+    await this.load();
+    let bufferedSessionCount = 0;
+    let pendingTurnCount = 0;
+    let oldestMs = Number.POSITIVE_INFINITY;
+    let oldestTurnTimestamp = null;
+    const consider = (turns) => {
+      if (!Array.isArray(turns) || turns.length === 0) return;
+      bufferedSessionCount += 1;
+      pendingTurnCount += turns.length;
+      const first = turns[0]?.timestamp;
+      const parsed = typeof first === "string" ? Date.parse(first) : Number.NaN;
+      if (Number.isFinite(parsed) && parsed < oldestMs) {
+        oldestMs = parsed;
+        oldestTurnTimestamp = first ?? null;
+      }
+    };
+    const entries = this.state.entries;
+    if (entries) {
+      for (const entry of Object.values(entries)) consider([...entry?.retainedTurns ?? [], ...entry?.turns ?? []]);
+    } else {
+      consider(this.state.turns);
+    }
+    return { bufferedSessionCount, pendingTurnCount, oldestTurnTimestamp };
+  }
+  /**
+   * Reset the buffer to an empty, usable state.
+   * Called when the persisted buffer file is corrupt and load() fails,
+   * so the buffer can still accept new turns for the rest of the session.
+   */
+  resetToEmpty() {
+    this.state = { turns: [], lastExtractionAt: null, extractionCount: 0 };
+    this.loaded = true;
+  }
+  async saveUnlocked() {
+    await this.storage.saveBuffer(this.state);
+  }
+  async save() {
+    await this.enqueueMutation(async () => this.saveUnlocked());
+  }
+  /**
+   * Schedule a coalesced, TRUE trailing-edge buffer save (issue #1909). Only
+   * used for the debounced (`bufferSaveDebounceMs > 0`) steady-state buffering
+   * path; the debounce-off and correctness-boundary paths save inline within the
+   * mutation (see `recordTurnUnlocked`). Each call re-arms the timer from now so
+   * the write lands one full window after the LAST turn, not the first. To keep
+   * sustained activity from deferring the save without bound (which would widen
+   * the crash-loss window), once a pending save has been deferred
+   * BUFFER_SAVE_MAX_DEFER_MULTIPLIER windows it is flushed inline instead of
+   * re-armed. Runs inside the record mutation, so the inline save is awaited.
+   */
+  async scheduleSave() {
+    const ms = Math.min(this.config.bufferSaveDebounceMs, MAX_SET_TIMEOUT_MS);
+    const now = Date.now();
+    this.pendingSave = true;
+    if (this.firstPendingAtMs === null) this.firstPendingAtMs = now;
+    if (now - this.firstPendingAtMs >= ms * BUFFER_SAVE_MAX_DEFER_MULTIPLIER) {
+      clearTimeout(this.saveTimer ?? void 0);
+      this.saveTimer = null;
+      try {
+        await this.saveUnlocked();
+        this.pendingSave = false;
+        this.firstPendingAtMs = null;
+      } catch (err) {
+        log.warn(`buffer.scheduleSave: staleness-cap save failed, keeping it pending: ${describeError(err)}`);
+        this.saveTimer = setTimeout(() => {
+          this.saveTimer = null;
+          void this.flushPendingSave();
+        }, ms);
+        this.saveTimer.unref?.();
+      }
+      return;
+    }
+    clearTimeout(this.saveTimer ?? void 0);
+    this.saveTimer = setTimeout(() => {
+      this.saveTimer = null;
+      void this.flushPendingSave();
+    }, ms);
+    this.saveTimer.unref?.();
+  }
+  /** Cancel any armed debounced save without persisting. */
+  cancelScheduledSave() {
+    if (this.saveTimer) {
+      clearTimeout(this.saveTimer);
+      this.saveTimer = null;
+    }
+    this.pendingSave = false;
+    this.firstPendingAtMs = null;
+  }
+  /**
+   * Persist the current in-memory buffer state inline, keeping the global
+   * pending-save state armed until the write SUCCEEDS (issue #1909). On failure
+   * the save stays pending and — when debounced — a background retry timer is
+   * (re-)armed before the error propagates, so a graceful shutdown flush and the
+   * next timer tick both retry. A failed post-mutation save therefore can never
+   * silently drop buffered turns, including turns from OTHER sessions that were
+   * only in the debounced pending state. The pending flag is cleared (and any
+   * armed timer dropped) only after a durable write.
+   */
+  async saveNowRetainingPendingOnFailure(context) {
+    this.pendingSave = true;
+    if (this.firstPendingAtMs === null) this.firstPendingAtMs = Date.now();
+    try {
+      await this.saveUnlocked();
+    } catch (err) {
+      log.warn(
+        `buffer.${context}: inline save failed, keeping it pending for retry: ${describeError(err)}`
+      );
+      const ms = Math.min(this.config.bufferSaveDebounceMs, MAX_SET_TIMEOUT_MS);
+      if (ms > 0 && !this.saveTimer) {
+        this.saveTimer = setTimeout(() => {
+          this.saveTimer = null;
+          void this.flushPendingSave();
+        }, ms);
+        this.saveTimer.unref?.();
+      }
+      throw err;
+    }
+    this.cancelScheduledSave();
+  }
+  /**
+   * Force any pending debounced save to land now (issue #1909). Idempotent and
+   * safe to call from outside a mutation (timer tick, shutdown/dispose, or the
+   * surprise-promotion path in `addTurnWithOutcome`). Do NOT `await` this from
+   * inside a mutation — it enqueues its own mutation and would deadlock the
+   * serializer.
+   *
+   * `throwOnFailure` (review round 7 finding 5): when set, a failed write is
+   * rethrown AFTER the keep-pending + re-arm bookkeeping, so the surprise
+   * extraction boundary gets the same durability guarantee as the built-in
+   * extract triggers (which propagate saveUnlocked failures) instead of
+   * proceeding to extract_now on a non-durable triggering turn. Default false
+   * keeps the fail-open behavior for the timer/shutdown callers.
+   */
+  async flushPendingSave(opts) {
+    if (this.saveTimer) {
+      clearTimeout(this.saveTimer);
+      this.saveTimer = null;
+    }
+    if (!this.pendingSave) return;
+    try {
+      await this.enqueueMutation(async () => {
+        if (!this.pendingSave) return;
+        await this.saveUnlocked();
+        this.pendingSave = false;
+        this.firstPendingAtMs = null;
+      });
+    } catch (err) {
+      log.warn(`buffer.flushPendingSave: save failed, keeping it pending for retry: ${describeError(err)}`);
+      const ms = Math.min(this.config.bufferSaveDebounceMs, MAX_SET_TIMEOUT_MS);
+      if (ms > 0 && !this.saveTimer) {
+        this.saveTimer = setTimeout(() => {
+          this.saveTimer = null;
+          void this.flushPendingSave();
+        }, ms);
+        this.saveTimer.unref?.();
+      }
+      if (opts?.throwOnFailure) throw err;
+      return;
+    }
+  }
+  async addTurn(bufferKey, turn) {
+    return (await this.addTurnWithOutcome(bufferKey, turn)).decision;
+  }
+  async addTurnWithOutcome(bufferKey, turn) {
+    const mutation = await this.enqueueMutation(() => this.recordTurnUnlocked(bufferKey, turn));
+    let decision = mutation.decision;
+    let extractionTurns;
+    if (decision === "keep_buffering" && resolvePresentationCapabilities(this.config).bufferSurpriseTrigger && this.surpriseProbe !== null && // Matching the existing "smart" branch: surprise is a lower-tier
+    // novelty signal that should not second-guess a high-signal hit
+    // (which already flushes) or fight `every_n` / `time_based` modes.
+    this.config.triggerMode === "smart" && mutation.signalLevel !== "high") {
+      const surprise = await this.computeSurpriseSafe(bufferKey, turn, mutation.priorTurns);
+      if (surprise !== null) {
+        const shouldPromote = surprise > this.config.bufferSurpriseThreshold;
+        let triggered = false;
+        if (shouldPromote) {
+          const currentTurns = await this.getExtractionTurnsIfBufferSnapshotStillCurrent(
+            bufferKey,
+            mutation.activeTurnsSnapshot,
+            mutation.retainedTurnsSnapshot
+          );
+          if (currentTurns) {
+            log.debug(
+              `buffer[${bufferKey}]: surprise=${surprise.toFixed(3)} > threshold=${this.config.bufferSurpriseThreshold} \u2192 extract_now`
+            );
+            decision = "extract_now";
+            triggered = true;
+            extractionTurns = currentTurns;
+            await this.flushPendingSave({ throwOnFailure: true });
+          } else {
+            log.debug(
+              `buffer[${bufferKey}]: surprise=${surprise.toFixed(3)} ignored because buffer changed before probe resolved`
+            );
+          }
+        }
+        this.queueSurpriseTelemetryWrite({
+          bufferKey,
+          turnRole: turn.role,
+          sessionKey: typeof turn.sessionKey === "string" ? turn.sessionKey : null,
+          surpriseScore: surprise,
+          triggered,
+          turnCountInWindow: mutation.turnCountInWindow,
+          // Stamp at decision time so backpressure on the write chain
+          // does not shift the event's apparent moment away from when
+          // the turn was actually scored.
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          // Snapshot the threshold used to compute `triggered` so a
+          // concurrent config mutation cannot retroactively change
+          // what the ledger row claims the decision was against.
+          threshold: this.config.bufferSurpriseThreshold
+        });
+      }
+    }
+    log.debug(
+      `buffer[${bufferKey}]: ${mutation.turnCountInWindow} turns, signal=${mutation.signalLevel}, decision=${decision}`
+    );
+    if (decision !== "keep_buffering" && extractionTurns === void 0) {
+      extractionTurns = [
+        ...mutation.retainedTurnsSnapshot,
+        ...mutation.activeTurnsSnapshot
+      ];
+    }
+    return extractionTurns ? { decision, extractionTurns } : { decision };
+  }
+  async recordTurnUnlocked(bufferKey, turn) {
+    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);
+    const decision = this.evaluate(entry, signal.level);
+    const turnCountInWindow = entry.turns.length;
+    this.pruneEntries([bufferKey]);
+    if (decision === "keep_buffering" && this.config.bufferSaveDebounceMs > 0) {
+      await this.scheduleSave();
+    } else {
+      await this.saveNowRetainingPendingOnFailure("recordTurn");
+    }
+    return {
+      decision,
+      signalLevel: signal.level,
+      priorTurns,
+      activeTurnsSnapshot,
+      retainedTurnsSnapshot,
+      turnCountInWindow
+    };
+  }
+  async getExtractionTurnsIfBufferSnapshotStillCurrent(bufferKey, activeTurnsSnapshot, retainedTurnsSnapshot) {
+    return this.enqueueMutation(async () => {
+      await this.loadUnlocked();
+      const entry = this.peekEntry(bufferKey);
+      if (!entry) return null;
+      const retained = entry.retainedTurns ?? [];
+      const stillCurrent = bufferTurnArrayIsSuffixOfSnapshot(entry.turns, activeTurnsSnapshot) && bufferTurnArraysEqual(retained, retainedTurnsSnapshot);
+      if (!stillCurrent) return null;
+      return [...retained, ...entry.turns];
+    });
+  }
+  /**
+   * Enqueue a telemetry append on the serialized write chain.
+   *
+   * The chain is a classic `writeChain = writeChain.then(fn).catch(...)`
+   * — each link waits for the previous to settle before its append
+   * starts, so out-of-order chronology cannot happen even under
+   * variable filesystem latency. We always attach `.catch` so one
+   * rejection does not poison the chain for the rest of the session
+   * (CLAUDE.md rule #40). The error is logged through
+   * `emitSurpriseEventSafe` itself, which swallows its own rejections.
+   *
+   * Public surface is deliberately narrow — only `addTurn` should call
+   * this, so the surprise telemetry path stays centralized.
+   */
+  queueSurpriseTelemetryWrite(params) {
+    this.surpriseTelemetryWriteChain = this.surpriseTelemetryWriteChain.then(() => this.emitSurpriseEventSafe(params)).catch(() => {
+    });
+  }
+  /**
+   * Append a single `BUFFER_SURPRISE` telemetry row (issue #563 PR 3).
+   *
+   * Deliberately swallows write errors: the buffer must never fail to
+   * record a turn because the observation ledger is read-only, out of
+   * disk, or otherwise unhappy. The log line at debug lets operators
+   * confirm the path fired without polluting the error channel.
+   */
+  async emitSurpriseEventSafe(params) {
+    const storage = this.storage;
+    if (typeof storage.appendBufferSurpriseEvents !== "function") {
+      return;
+    }
+    const event = {
+      event: "BUFFER_SURPRISE",
+      // Use the decision-time stamp captured when the event was
+      // queued, NOT `Date.now()` here — backpressure on the write
+      // chain could otherwise shift timestamps into the future relative
+      // to when the turn was scored.
+      timestamp: params.timestamp,
+      bufferKey: params.bufferKey,
+      sessionKey: params.sessionKey,
+      turnRole: params.turnRole,
+      surpriseScore: params.surpriseScore,
+      // Use the snapshotted threshold from the queue entry, not the
+      // live config — see `SurpriseTelemetryQueueEntry.threshold`
+      // doc for the rationale.
+      threshold: params.threshold,
+      triggeredFlush: params.triggered,
+      turnCountInWindow: params.turnCountInWindow
+    };
+    try {
+      await storage.appendBufferSurpriseEvents([event]);
+    } catch (err) {
+      log.debug(
+        `buffer[${params.bufferKey}]: surprise telemetry write failed, continuing: ${describeError(err)}`
+      );
+    }
+  }
+  /**
+   * Invoke the injected surprise probe defensively. Any error (probe throws,
+   * embedder unavailable, timeout) is swallowed and logged at debug: the
+   * surprise path must never crash the happy-path trigger evaluation. A
+   * `null` return indicates "no score available, fall through to existing
+   * triggers".
+   */
+  async computeSurpriseSafe(bufferKey, turn, priorTurns) {
+    if (!this.surpriseProbe) return null;
+    try {
+      const score = await probeWithTimeout(
+        this.surpriseProbe.scoreTurn(bufferKey, turn, priorTurns),
+        this.config.bufferSurpriseProbeTimeoutMs
+      );
+      if (score === null) return null;
+      if (typeof score !== "number" || !Number.isFinite(score)) {
+        log.debug(
+          `buffer[${bufferKey}]: surprise probe returned non-finite score (${String(score)}), ignoring`
+        );
+        return null;
+      }
+      if (score < 0) return 0;
+      if (score > 1) return 1;
+      return score;
+    } catch (err) {
+      log.debug(
+        `buffer[${bufferKey}]: surprise probe failed, falling back to existing triggers: ${describeError(err)}`
+      );
+      return null;
+    }
+  }
+  evaluate(entry, signalLevel) {
+    if (this.config.triggerMode === "smart") {
+      if (signalLevel === "high") return "extract_now";
+      if (entry.turns.length >= this.config.bufferMaxTurns) {
+        return "extract_batch";
+      }
+      if (entry.lastExtractionAt) {
+        const elapsed = Date.now() - new Date(entry.lastExtractionAt).getTime();
+        if (elapsed >= this.config.bufferMaxMinutes * 6e4) {
+          return "extract_batch";
+        }
+      }
+      return "keep_buffering";
+    }
+    if (this.config.triggerMode === "every_n") {
+      return entry.turns.length >= this.config.bufferMaxTurns ? "extract_batch" : "keep_buffering";
+    }
+    if (this.config.triggerMode === "time_based") {
+      if (!entry.lastExtractionAt) {
+        return entry.turns.length >= this.config.bufferMaxTurns ? "extract_batch" : "keep_buffering";
+      }
+      const elapsed = Date.now() - new Date(entry.lastExtractionAt).getTime();
+      return elapsed >= this.config.bufferMaxMinutes * 6e4 ? "extract_batch" : "keep_buffering";
+    }
+    return "keep_buffering";
+  }
+  getTurns(bufferKey = "default") {
+    const entry = this.peekEntry(bufferKey);
+    if (!entry) return [];
+    const retained = entry.retainedTurns ?? [];
+    return [...retained, ...entry.turns];
+  }
+  /**
+   * Retain a subset of the current turns across `clearAfterExtraction` so a
+   * future extraction pass sees the context behind a deferred candidate
+   * (issue #562, PR 2). Callers pass the turns that were seen during the
+   * current extraction; the buffer keeps the tail (latest `max` turns) as
+   * the retention window. Passing an empty array or `max <= 0` clears the
+   * retention slot instead.
+   */
+  async retainDeferredTurns(bufferKey, turns, max = 10) {
+    await this.enqueueMutation(async () => {
+      await this.loadUnlocked();
+      const entry = this.entryFor(bufferKey);
+      if (!Array.isArray(turns) || turns.length === 0 || max <= 0) {
+        delete entry.retainedTurns;
+      } else {
+        const tail = turns.slice(-max);
+        entry.retainedTurns = tail.map((t) => {
+          const copy = {
+            role: t.role,
+            content: typeof t.content === "string" ? t.content : "",
+            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;
+          }
+          if (t.providerThreadId === null || typeof t.providerThreadId === "string") {
+            copy.providerThreadId = t.providerThreadId;
+          }
+          if (typeof t.turnFingerprint === "string") {
+            copy.turnFingerprint = t.turnFingerprint;
+          }
+          if (typeof t.persistProcessedFingerprint === "boolean") {
+            copy.persistProcessedFingerprint = t.persistProcessedFingerprint;
+          }
+          if (typeof t.sourceConnector === "string") copy.sourceConnector = t.sourceConnector;
+          return copy;
+        });
+      }
+      await this.saveUnlocked();
+    });
+  }
+  /**
+   * Return the current retention window (issue #562, PR 2). Primarily for
+   * tests and diagnostics.
+   */
+  getRetainedDeferredTurns(bufferKey = "default") {
+    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;
+  }
+  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 (hasSessionTurns(directEntry)) {
+      matches.push(sessionKey);
+    }
+    const entries = this.state.entries ?? {};
+    for (const [bufferKey, entry] of Object.entries(entries)) {
+      if (!matches.includes(bufferKey) && hasSessionTurns(entry)) {
+        matches.push(bufferKey);
+      }
+    }
+    return matches;
+  }
+  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);
+        this.saveTimer = null;
+      }
+      await this.loadUnlocked();
+      const entry = this.entryFor(bufferKey);
+      if (Array.isArray(extractedTurns)) {
+        const liveExtractedTurns = liveTurnsFromExtractionSnapshot(
+          entry,
+          extractedTurns
+        );
+        let clearedLiveTurns = false;
+        if (liveExtractedTurns.length > 0) {
+          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`
+            );
+          }
+        }
+        if (!clearedLiveTurns) {
+          await this.saveNowRetainingPendingOnFailure("clearAfterExtraction");
+          return;
+        }
+      } else {
+        entry.turns = [];
+      }
+      entry.lastExtractionAt = (/* @__PURE__ */ new Date()).toISOString();
+      entry.extractionCount += 1;
+      if (bufferKey === "default") {
+        this.state.turns = entry.turns;
+        this.state.lastExtractionAt = entry.lastExtractionAt;
+        this.state.extractionCount = entry.extractionCount;
+      }
+      this.pruneEntries([bufferKey]);
+      await this.saveNowRetainingPendingOnFailure("clearAfterExtraction");
+    });
+  }
+  getExtractionCount(bufferKey = "default") {
+    return this.peekEntry(bufferKey)?.extractionCount ?? 0;
+  }
+  /**
+   * Await any pending `BUFFER_SURPRISE` telemetry writes.
+   *
+   * The telemetry path is fire-and-forget from the hot path's point of
+   * view, but tests and before-exit hooks sometimes need to make sure
+   * the ledger has been flushed before they assert on its contents or
+   * close the process. This method resolves once the current chain
+   * head has settled; new writes scheduled after this call return a
+   * separate, later settlement.
+   *
+   * Never throws — the chain already catches its own rejections.
+   */
+  async flushSurpriseTelemetry() {
+    await this.surpriseTelemetryWriteChain;
+  }
+};
+
+export {
+  SmartBuffer
+};
+//# sourceMappingURL=chunk-3JLWSFTV.js.map