@remnic/core 9.7.15 → 9.8.0

package/dist/chunk-FMLKOL2Z.js

@@ -0,0 +1,636 @@
+import {
+  writeFileAtomically
+} from "./chunk-R6YJI3HE.js";
+import {
+  ensureContainedSpillDir,
+  listContainedSpillFiles
+} from "./chunk-GCASGYIO.js";
+import {
+  withHeldFileLock
+} from "./chunk-WL5EBRDH.js";
+import {
+  isErrnoCode
+} from "./chunk-5UZXUTVO.js";
+import {
+  log
+} from "./chunk-3WCASNQZ.js";
+
+// src/recall-state.ts
+import { appendFile, mkdir, readFile, rename, rm, stat, unlink, writeFile } from "fs/promises";
+import path from "path";
+import { createHash, randomUUID } from "crypto";
+function clampGraphRecallExpandedEntries(entries, maxEntries = 64) {
+  const limit = Math.max(1, Math.floor(maxEntries));
+  if (!Array.isArray(entries)) return [];
+  return entries.filter((item) => !!item && typeof item === "object").map((item) => {
+    const graphType = item.graphType === "entity" || item.graphType === "time" || item.graphType === "causal" ? item.graphType : "entity";
+    const out = {
+      path: typeof item.path === "string" ? item.path : "",
+      score: typeof item.score === "number" && Number.isFinite(item.score) ? item.score : 0,
+      namespace: typeof item.namespace === "string" ? item.namespace : "",
+      seed: typeof item.seed === "string" ? item.seed : "",
+      hopDepth: typeof item.hopDepth === "number" && Number.isFinite(item.hopDepth) ? Math.max(0, Math.floor(item.hopDepth)) : 0,
+      decayedWeight: typeof item.decayedWeight === "number" && Number.isFinite(item.decayedWeight) ? Math.max(0, item.decayedWeight) : 0,
+      graphType
+    };
+    if (typeof item.edgeConfidence === "number" && Number.isFinite(item.edgeConfidence)) {
+      out.edgeConfidence = Math.min(1, Math.max(0, item.edgeConfidence));
+    }
+    return out;
+  }).filter((item) => item.path.length > 0 && item.namespace.length > 0).slice(0, limit);
+}
+function snapshotMatchesExpectedIdentity(current, expected) {
+  if (!expected) return true;
+  if (typeof expected.writeNonce === "string" && expected.writeNonce.length > 0) {
+    return current.writeNonce === expected.writeNonce;
+  }
+  const hasExpectedTraceId = typeof expected.traceId === "string" && expected.traceId.length > 0;
+  if (hasExpectedTraceId) {
+    return current.traceId === expected.traceId;
+  }
+  if (expected.recordedAt !== void 0) {
+    return current.recordedAt === expected.recordedAt;
+  }
+  return true;
+}
+function cloneTierExplain(tierExplain) {
+  if (!tierExplain) return void 0;
+  return structuredClone(tierExplain);
+}
+function cloneLastRecallSnapshot(snapshot) {
+  if (!snapshot) return null;
+  return structuredClone(snapshot);
+}
+var DEFAULT_TIER_MIGRATION_STATUS = {
+  updatedAt: (/* @__PURE__ */ new Date(0)).toISOString(),
+  lastCycle: null,
+  totals: {
+    cycles: 0,
+    scanned: 0,
+    migrated: 0,
+    promoted: 0,
+    demoted: 0,
+    errors: 0
+  }
+};
+var CLAIMED_IMPRESSION_SPILL_SUFFIX = ".claimed";
+var LastRecallStore = class {
+  statePath;
+  impressionsPath;
+  writeStateFile;
+  impressionsRotateBytes;
+  impressionsRotateKeep;
+  // Lock-acquisition timing for the cross-process impression rotation lock.
+  // Only tests set this (small maxWaitMs) to force the acquisition-timeout
+  // (`acquired=false`) branch deterministically; production uses the defaults.
+  impressionsLockOptions;
+  state = {};
+  stateWriteChain = Promise.resolve();
+  // Serializes the rotate-then-append critical section so concurrent record()
+  // calls never interleave rotation renames with each other's appends (#1910).
+  impressionsWriteChain = Promise.resolve();
+  constructor(memoryDir, options = {}) {
+    this.statePath = path.join(memoryDir, "state", "last_recall.json");
+    this.impressionsPath = path.join(memoryDir, "state", "recall_impressions.jsonl");
+    this.impressionsRotateBytes = Math.max(0, Math.floor(options.impressionsRotateBytes ?? 0));
+    this.impressionsRotateKeep = Math.max(1, Math.floor(options.impressionsRotateKeep ?? 5));
+    this.impressionsLockOptions = options.impressionsLockOptions;
+    this.writeStateFile = options.writeStateFile ?? (async (filePath, content) => {
+      await writeFileAtomically(filePath, content);
+    });
+  }
+  async load() {
+    try {
+      const raw = await readFile(this.statePath, "utf-8");
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object") this.state = parsed;
+    } catch {
+      this.state = {};
+    }
+  }
+  get(sessionKey) {
+    return cloneLastRecallSnapshot(this.state[sessionKey] ?? null);
+  }
+  getMostRecent() {
+    const snapshots = Object.values(this.state);
+    if (snapshots.length === 0) return null;
+    snapshots.sort((a, b) => {
+      const byTime = b.recordedAt.localeCompare(a.recordedAt);
+      if (byTime !== 0) return byTime;
+      return a.sessionKey.localeCompare(b.sessionKey);
+    });
+    return cloneLastRecallSnapshot(snapshots[0] ?? null);
+  }
+  /**
+   * Persist last-recall snapshot and append an impression log entry.
+   * Does not store raw query text; uses a stable hash for correlation.
+   */
+  async record(opts) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const queryHash = createHash("sha256").update(opts.query).digest("hex");
+    const liveSnapshot = {
+      sessionKey: opts.sessionKey,
+      recordedAt: now,
+      queryHash,
+      writeNonce: randomUUID(),
+      queryLen: opts.query.length,
+      memoryIds: opts.memoryIds,
+      namespace: opts.namespace,
+      recallNamespaces: opts.recallNamespaces,
+      traceId: opts.traceId,
+      plannerMode: opts.plannerMode,
+      requestedMode: opts.requestedMode,
+      source: opts.source,
+      fallbackUsed: opts.fallbackUsed,
+      sourcesUsed: opts.sourcesUsed,
+      budgetsApplied: opts.budgetsApplied,
+      latencyMs: opts.latencyMs,
+      resultPaths: opts.resultPaths,
+      resultNamespaces: opts.resultNamespaces,
+      policyVersion: opts.policyVersion,
+      identityInjectionMode: opts.identityInjection?.mode,
+      identityInjectedChars: opts.identityInjection?.injectedChars,
+      identityInjectionTruncated: opts.identityInjection?.truncated,
+      tierExplain: opts.tierExplain,
+      backendDegradations: opts.backendDegradations && opts.backendDegradations.length > 0 ? opts.backendDegradations : void 0
+    };
+    const snapshot = cloneLastRecallSnapshot(liveSnapshot);
+    this.state[opts.sessionKey] = snapshot;
+    const keys = Object.keys(this.state);
+    if (keys.length > 50) {
+      const ordered = keys.map((k) => ({ k, at: this.state[k]?.recordedAt ?? "" })).sort((a, b) => b.at.localeCompare(a.at));
+      for (const doomed of ordered.slice(50)) {
+        delete this.state[doomed.k];
+      }
+    }
+    try {
+      await this.flushState();
+    } catch (err) {
+      log.debug(`last recall store write failed: ${err}`);
+    }
+    if (opts.appendImpression !== false) {
+      const line = JSON.stringify(snapshot) + "\n";
+      const chained = this.impressionsWriteChain.catch(() => {
+      }).then(() => this.appendImpressionSerialized(line));
+      this.impressionsWriteChain = chained;
+      try {
+        await chained;
+      } catch (err) {
+        log.debug(`recall impressions append failed: ${err}`);
+      }
+    }
+  }
+  /**
+   * Drain pending spills, rotate (best-effort, sized to the projected payload),
+   * then append one impression line under ONE shared cross-process lock (#1910,
+   * #2033). Both the archive-shift renames AND the append run inside the same
+   * held lock so a peer process holding the lock can never rename the active
+   * inode to `.1` between our open and write — which would land the impression in
+   * a rotated archive that offline-sync excludes, silently dropping it from
+   * active-state/sync consumers.
+   *
+   * On lock-acquisition timeout the impression is NEVER written to the active
+   * file unlocked (#2033): a peer holding the lock is likely mid-rotation, so an
+   * unlocked append can land in the inode it is about to rename to `.1` — the
+   * exact silent-drop this lock prevents. Instead the row is spilled to a
+   * durable node-local per-event file under `<impressions>.pending.d/` and
+   * folded back into the active file by the next append that DOES hold the lock,
+   * preserving durability without racing rotation. Rotation failure under the
+   * held lock is logged and the append still runs. Callers invoke this only
+   * through `impressionsWriteChain` so the sequence is serialized in-process.
+   */
+  get impressionsPendingDir() {
+    return `${this.impressionsPath}.pending.d`;
+  }
+  async spillImpression(line) {
+    await ensureContainedSpillDir(this.impressionsPendingDir);
+    const id = randomUUID();
+    const tempPath = path.join(this.impressionsPendingDir, `${id}.jsonl.tmp`);
+    const finalPath = path.join(this.impressionsPendingDir, `${id}.jsonl`);
+    await writeFile(tempPath, line, "utf-8");
+    await rename(tempPath, finalPath);
+  }
+  /**
+   * Recover a claim a crashed drain left mid-flight (#2033): the crash-safe
+   * drain renames `<uuid>.jsonl` -> `<uuid>.jsonl.claimed` BEFORE committing, so
+   * a `.claimed` file with no matching commit is the ONLY durable copy of those
+   * rows. Rename each orphan back to `<uuid>.jsonl` so it re-enters the normal
+   * collect+claim+commit flow. MUST run under the held rotation lock, before
+   * collecting. listContainedSpillFiles skips symlinked/escaping entries.
+   */
+  async recoverOrphanedImpressionClaims() {
+    const orphans = await listContainedSpillFiles(
+      this.impressionsPendingDir,
+      `.jsonl${CLAIMED_IMPRESSION_SPILL_SUFFIX}`
+    );
+    for (const claimedPath of orphans) {
+      const original = claimedPath.slice(0, -CLAIMED_IMPRESSION_SPILL_SUFFIX.length);
+      await rename(claimedPath, original).catch(() => void 0);
+    }
+  }
+  /**
+   * Recover a crash-orphaned spill temp after its write completed but before
+   * the atomic `.tmp` → `.jsonl` rename. Valid JSONL temps are promoted back
+   * into the normal queue; incomplete temps remain pending and keep offline sync
+   * deferred rather than being discarded.
+   */
+  async recoverOrphanedImpressionTemps() {
+    const temps = await listContainedSpillFiles(this.impressionsPendingDir, ".jsonl.tmp");
+    for (const tempPath of temps) {
+      let content;
+      try {
+        content = await readFile(tempPath, "utf-8");
+        for (const line of content.split("\n")) {
+          if (line.trim().length > 0) JSON.parse(line);
+        }
+      } catch {
+        continue;
+      }
+      const finalPath = tempPath.slice(0, -".tmp".length);
+      await rename(tempPath, finalPath).catch(() => void 0);
+    }
+  }
+  async appendImpressionSerialized(line) {
+    await mkdir(path.dirname(this.impressionsPath), { recursive: true });
+    const lockPath = `${this.impressionsPath}.lock`;
+    await withHeldFileLock(
+      lockPath,
+      { staleMs: 3e4, ...this.impressionsLockOptions },
+      async (acquired) => {
+        if (!acquired) {
+          log.debug("recall impressions rotation lock not acquired; spilling impression to the durable pending queue");
+          await this.spillImpression(line);
+          return;
+        }
+        await this.foldPendingImpressionsAndAppend(line);
+      }
+    );
+  }
+  /**
+   * Fold any durable pending recall-impression spills into the synced active
+   * `recall_impressions.jsonl` WITHOUT recording a new impression (#2033).
+   *
+   * The pending spill dir is offline-sync-excluded, so an impression that a
+   * lock-timed-out `record()` spilled there is absent from an offline-sync
+   * snapshot and lost if this node is discarded before the next `record()`
+   * folds it back. Offline sync calls this before building a snapshot so a
+   * recorded impression always reaches the remote. Fast no-op — no lock and no
+   * dir/lock-file creation — when nothing is pending.
+   *
+   * Returns a {@link DrainPendingImpressionsResult}: `folded` is true when rows
+   * were folded into the active file; `pendingDeferred` is true when durable
+   * spills still remain in the offline-sync-EXCLUDED queue after this call —
+   * because the rotation lock could not be acquired, a spill could not be
+   * claimed, or the drain-only fold deferred rows that would only fit by
+   * rotating into a sync-excluded archive (#2033). A snapshot taken while
+   * `pendingDeferred` is true would silently drop those rows, so the caller MUST
+   * NOT report a clean snapshot — it either retries or aborts.
+   */
+  async drainPendingImpressions() {
+    if (!await this.pendingSpillsRemain()) {
+      return { folded: false, pendingDeferred: false };
+    }
+    const lockPath = `${this.impressionsPath}.lock`;
+    let folded = false;
+    let acquiredLock = false;
+    let spillsRemain = false;
+    await withHeldFileLock(
+      lockPath,
+      { staleMs: 3e4, ...this.impressionsLockOptions },
+      async (acquired) => {
+        if (!acquired) return;
+        acquiredLock = true;
+        folded = await this.foldPendingImpressionsAndAppend(null);
+        spillsRemain = await this.pendingSpillsRemain();
+      }
+    );
+    return { folded, pendingDeferred: !acquiredLock || spillsRemain };
+  }
+  /**
+   * Claim/commit fold of durable pending impression spills into the active file
+   * under the held rotation lock (#2033). `line` is a new impression to append
+   * after the drained rows, or null for a drain-only pre-sync fold.
+   *
+   * Each spill is folded as an INDEPENDENT claim -> append -> finalize unit
+   * rather than materializing the whole queue as one joined payload and
+   * splitting it in a single synchronous pass (#2033). A multi-hundred-MB drain
+   * done as one join/split blocks the event loop long enough for
+   * `withHeldFileLock`'s ownership-refresh timer to miss its window, so a peer
+   * stale-breaks the 30s lock and rotates/appends concurrently — defeating the
+   * rotation lock this drain relies on. The per-file `await`s keep the payload
+   * bounded to one spill at a time and let the refresh timer fire between files.
+   *
+   * The DRAIN-ONLY path (`line === null`, run before an offline-sync snapshot)
+   * NEVER rotates a drained row into an archive. `recall_impressions.jsonl.*`
+   * is offline-sync-EXCLUDED, so rotating a just-drained row into `.1`/`.2` and
+   * then deleting its spill would leave that row only in a path sync omits —
+   * silently lost when the node is discarded after a "successful" sync (#2033).
+   * It folds only the rows that fit the synced active file under the cap and
+   * leaves the rest durable in the pending queue; {@link drainPendingImpressions}
+   * then reports the drain DEFERRED so the caller retries or aborts. The
+   * record() path (`line !== null`) keeps rotating normally — its archives stay
+   * on a live node that is not being discarded.
+   *
+   * Recovers any crash-orphaned claim first. Each impression carries a unique
+   * writeNonce, so a crash-recovered re-commit is a collapsible duplicate, never
+   * a lost row. listContainedSpillFiles rejects symlinked/escaping entries; a
+   * spill that cannot be claimed is skipped this pass. An append failure rolls
+   * that spill's claim back so the row retries on the next lock holder's drain.
+   * Returns true when the active file was written. MUST run under the held
+   * rotation lock.
+   */
+  async foldPendingImpressionsAndAppend(line) {
+    await this.recoverOrphanedImpressionTemps();
+    await this.recoverOrphanedImpressionClaims();
+    const spillFiles = await listContainedSpillFiles(this.impressionsPendingDir);
+    const drainOnly = line === null;
+    const cap = this.impressionsRotateBytes;
+    let activeSize = 0;
+    if (cap > 0) {
+      try {
+        activeSize = (await stat(this.impressionsPath)).size;
+      } catch (err) {
+        if (!isErrnoCode(err, "ENOENT")) throw err;
+      }
+    }
+    let wrote = false;
+    for (const filePath of spillFiles) {
+      const content = await readFile(filePath, "utf-8");
+      const unit = content.length === 0 || content.endsWith("\n") ? content : `${content}
+`;
+      const unitBytes = Buffer.byteLength(unit, "utf-8");
+      if (drainOnly && cap > 0 && activeSize > 0 && activeSize + unitBytes >= cap) break;
+      const claimedPath = `${filePath}${CLAIMED_IMPRESSION_SPILL_SUFFIX}`;
+      try {
+        await rename(filePath, claimedPath);
+      } catch {
+        continue;
+      }
+      try {
+        activeSize = await this.appendImpressionUnit(unit, activeSize, drainOnly);
+      } catch (err) {
+        await rename(claimedPath, filePath).catch(() => void 0);
+        throw err;
+      }
+      await unlink(claimedPath).catch(() => void 0);
+      wrote = true;
+    }
+    if (line !== null) {
+      activeSize = await this.appendImpressionUnit(line, activeSize, false);
+      wrote = true;
+    }
+    return wrote;
+  }
+  /**
+   * Append one whole JSONL unit (a claimed spill's rows or a fresh impression
+   * line) to the active impressions file, returning the resulting active-file
+   * byte size. On the rotating (record) path, when the unit would push the
+   * current active generation to/over `impressionsRotateBytes`, the full active
+   * file is rotated aside FIRST so no generation exceeds the cap (#2033); a lone
+   * unit larger than the cap on an empty active file is written whole because
+   * splitting a JSONL row would corrupt it. `drainOnly` and disabled rotation
+   * (`impressionsRotateBytes <= 0`) both skip rotation — drain-only defers its
+   * overflow in {@link foldPendingImpressionsAndAppend} rather than rotating into
+   * a sync-excluded archive. A rotation error is logged and the append still
+   * runs so a row is never lost; an append failure propagates so the caller
+   * rolls its claim back. MUST run under the held rotation lock.
+   */
+  async appendImpressionUnit(unit, activeSize, drainOnly) {
+    const cap = this.impressionsRotateBytes;
+    const unitBytes = Buffer.byteLength(unit, "utf-8");
+    if (cap > 0 && !drainOnly && activeSize > 0 && activeSize + unitBytes >= cap) {
+      try {
+        await this.shiftImpressionArchives();
+        activeSize = 0;
+      } catch (err) {
+        log.debug(`recall impressions rotation failed (append preserved): ${err}`);
+      }
+    }
+    await appendFile(this.impressionsPath, unit, "utf-8");
+    return activeSize + unitBytes;
+  }
+  /**
+   * True when any live `<uuid>.jsonl` spill, crash-orphaned `.claimed` file,
+   * or crash-orphaned `.jsonl.tmp` spill remains in the offline-sync-EXCLUDED
+   * pending queue (#2033). After a drain acquires the rotation lock, a spill
+   * the fold could not claim (rename race / read-only dir) or a `.claimed`
+   * orphan a failed commit left behind means durable rows are STILL excluded
+   * from a snapshot — the drain must report itself INCOMPLETE so the caller
+   * retries or aborts rather than snapshotting an active file that omits them.
+   */
+  async pendingSpillsRemain() {
+    if ((await listContainedSpillFiles(this.impressionsPendingDir, ".jsonl.tmp")).length > 0) {
+      return true;
+    }
+    const liveSpills = await listContainedSpillFiles(this.impressionsPendingDir);
+    if (liveSpills.length > 0) return true;
+    const claimed = await listContainedSpillFiles(
+      this.impressionsPendingDir,
+      `.jsonl${CLAIMED_IMPRESSION_SPILL_SUFFIX}`
+    );
+    return claimed.length > 0;
+  }
+  /**
+   * Shift `.1..N` archives down one slot and move the active file to `.1`,
+   * dropping anything beyond `keep`. Callers invoke this only while holding the
+   * cross-process rotation lock (issue #1910).
+   */
+  async shiftImpressionArchives() {
+    const keep = this.impressionsRotateKeep;
+    try {
+      await rm(`${this.impressionsPath}.${keep}`, { force: true });
+    } catch {
+    }
+    for (let i = keep - 1; i >= 1; i -= 1) {
+      try {
+        await rename(`${this.impressionsPath}.${i}`, `${this.impressionsPath}.${i + 1}`);
+      } catch (err) {
+        if (!isErrnoCode(err, "ENOENT")) throw err;
+      }
+    }
+    try {
+      await rename(this.impressionsPath, `${this.impressionsPath}.1`);
+    } catch (err) {
+      if (!isErrnoCode(err, "ENOENT")) throw err;
+    }
+  }
+  /**
+   * Attach a RecallTierExplain block to the existing snapshot for a
+   * session without rewriting the entire snapshot.  Used by the
+   * post-recall direct-answer annotation path (issue #518 slice 3c):
+   * recallInternal records the snapshot first, then the orchestrator
+   * fires the direct-answer tier in observation mode and annotates
+   * the stored snapshot with whichever tier served the query.
+   *
+   * No-op when no snapshot exists for the given session; callers do
+   * not need to guard on existence.
+   */
+  async annotateTierExplain(sessionKey, tierExplain, expected) {
+    const current = this.state[sessionKey];
+    if (!current) return;
+    if (!snapshotMatchesExpectedIdentity(current, expected)) return;
+    this.state[sessionKey] = {
+      ...current,
+      tierExplain: cloneTierExplain(tierExplain)
+    };
+    try {
+      await this.flushState();
+    } catch (err) {
+      log.debug(`last recall tier-explain annotate failed: ${err}`);
+    }
+  }
+  flushState() {
+    const run = this.stateWriteChain.catch(() => void 0).then(async () => {
+      await mkdir(path.dirname(this.statePath), { recursive: true });
+      await this.writeStateFile(this.statePath, JSON.stringify(this.state, null, 2));
+    });
+    this.stateWriteChain = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  }
+};
+var TierMigrationStatusStore = class {
+  statePath;
+  state = structuredClone(DEFAULT_TIER_MIGRATION_STATUS);
+  constructor(memoryDir) {
+    this.statePath = path.join(memoryDir, "state", "tier-migration-status.json");
+  }
+  async load() {
+    try {
+      const raw = await readFile(this.statePath, "utf-8");
+      const parsed = JSON.parse(raw);
+      if (!parsed || typeof parsed !== "object") {
+        this.state = structuredClone(DEFAULT_TIER_MIGRATION_STATUS);
+        return;
+      }
+      const totals = parsed.totals && typeof parsed.totals === "object" ? parsed.totals : DEFAULT_TIER_MIGRATION_STATUS.totals;
+      this.state = {
+        updatedAt: typeof parsed.updatedAt === "string" && parsed.updatedAt.length > 0 ? parsed.updatedAt : DEFAULT_TIER_MIGRATION_STATUS.updatedAt,
+        lastCycle: parsed.lastCycle && typeof parsed.lastCycle === "object" ? parsed.lastCycle : null,
+        totals: {
+          cycles: typeof totals.cycles === "number" && Number.isFinite(totals.cycles) ? totals.cycles : 0,
+          scanned: typeof totals.scanned === "number" && Number.isFinite(totals.scanned) ? totals.scanned : 0,
+          migrated: typeof totals.migrated === "number" && Number.isFinite(totals.migrated) ? totals.migrated : 0,
+          promoted: typeof totals.promoted === "number" && Number.isFinite(totals.promoted) ? totals.promoted : 0,
+          demoted: typeof totals.demoted === "number" && Number.isFinite(totals.demoted) ? totals.demoted : 0,
+          errors: typeof totals.errors === "number" && Number.isFinite(totals.errors) ? totals.errors : 0
+        }
+      };
+    } catch {
+      this.state = structuredClone(DEFAULT_TIER_MIGRATION_STATUS);
+    }
+  }
+  get() {
+    return {
+      updatedAt: this.state.updatedAt,
+      lastCycle: this.state.lastCycle ? { ...this.state.lastCycle } : null,
+      totals: { ...this.state.totals }
+    };
+  }
+  async recordCycle(summary) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const migratedDelta = summary.dryRun ? 0 : Math.max(0, summary.migrated);
+    const promotedDelta = summary.dryRun ? 0 : Math.max(0, summary.promoted);
+    const demotedDelta = summary.dryRun ? 0 : Math.max(0, summary.demoted);
+    const next = {
+      updatedAt: now,
+      lastCycle: { ...summary },
+      totals: {
+        cycles: this.state.totals.cycles + 1,
+        scanned: this.state.totals.scanned + Math.max(0, summary.scanned),
+        migrated: this.state.totals.migrated + migratedDelta,
+        promoted: this.state.totals.promoted + promotedDelta,
+        demoted: this.state.totals.demoted + demotedDelta,
+        errors: this.state.totals.errors + Math.max(0, summary.errorCount ?? 0)
+      }
+    };
+    this.state = next;
+    try {
+      await mkdir(path.dirname(this.statePath), { recursive: true });
+      await writeFile(this.statePath, JSON.stringify(next, null, 2), "utf-8");
+    } catch (err) {
+      log.debug(`tier migration status write failed: ${err}`);
+    }
+  }
+};
+var RecallHandleHistoryStore = class {
+  statePath;
+  writeStateFile;
+  state = {};
+  writeChain = Promise.resolve();
+  maxDepth;
+  constructor(memoryDir, options = {}) {
+    this.statePath = path.join(memoryDir, "state", "handle_history.json");
+    this.writeStateFile = options.writeStateFile ?? (async (filePath, content) => {
+      await writeFileAtomically(filePath, content);
+    });
+    this.maxDepth = typeof options.maxDepth === "number" && Number.isFinite(options.maxDepth) ? Math.max(1, Math.min(50, Math.floor(options.maxDepth))) : 5;
+  }
+  async load() {
+    try {
+      const raw = await readFile(this.statePath, "utf-8");
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object") this.state = parsed;
+    } catch {
+      this.state = {};
+    }
+  }
+  /**
+   * Record one recall's admitted memory ids for a session, newest first.
+   * The ring is capped at {@link maxDepth}; older entries drop off the tail.
+   */
+  async record(sessionKey, memoryIds) {
+    if (!sessionKey) return;
+    const ids = memoryIds.filter((id) => typeof id === "string" && id.length > 0);
+    const entry = { at: (/* @__PURE__ */ new Date()).toISOString(), ids };
+    const prior = this.state[sessionKey] ?? [];
+    const next = [entry, ...prior].slice(0, this.maxDepth);
+    this.state[sessionKey] = next;
+    this.capSessions();
+    try {
+      await this.flush();
+    } catch (err) {
+      log.debug(`recall handle history write failed: ${err}`);
+    }
+  }
+  /**
+   * Return the memory-id arrays for a session, newest first, capped at `depth`.
+   * Empty array when the session has no recorded history.
+   */
+  recent(sessionKey, depth = this.maxDepth) {
+    const entries = this.state[sessionKey];
+    if (!entries || entries.length === 0) return [];
+    const limit = Math.max(0, Math.min(depth, entries.length));
+    return entries.slice(0, limit).map((e) => e.ids);
+  }
+  /** Test seam: drop all history (used by the corpus-scan hygiene test). */
+  clearForTest() {
+    this.state = {};
+  }
+  capSessions() {
+    const keys = Object.keys(this.state);
+    if (keys.length <= 50) return;
+    const ordered = keys.map((k) => ({ k, at: this.state[k]?.[0]?.at ?? "" })).sort((a, b) => b.at.localeCompare(a.at));
+    for (const doomed of ordered.slice(50)) {
+      delete this.state[doomed.k];
+    }
+  }
+  flush() {
+    const run = this.writeChain.catch(() => void 0).then(async () => {
+      await mkdir(path.dirname(this.statePath), { recursive: true });
+      await this.writeStateFile(this.statePath, JSON.stringify(this.state, null, 2));
+    });
+    this.writeChain = run.then(() => void 0, () => void 0);
+    return run;
+  }
+};
+
+export {
+  clampGraphRecallExpandedEntries,
+  LastRecallStore,
+  TierMigrationStatusStore,
+  RecallHandleHistoryStore
+};
+//# sourceMappingURL=chunk-FMLKOL2Z.js.map