@remnic/core 9.63.4 → 9.63.6

package/dist/chunk-NRFU5MVH.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/storage/content-hash-index.ts"],"sourcesContent":["// Content-hash dedup index for facts, extracted from storage.ts (issue #1909 /\n// PR #2016 write-hot-paths). Self-contained: cross-process locked reconcile /\n// rebuild saves plus the deferred durable-retry machinery. storage.ts imports\n// these back and re-exports the class + companion types that were previously\n// part of its public API.\nimport { mkdir, stat } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { computeContentHash, normalizeContent } from \"../content-hash.js\";\nimport { log } from \"../logger.js\";\nimport { SecureStoreLockedError, readMaybeEncryptedFile, writeMaybeEncryptedFile } from \"../secure-store/secure-fs.js\";\nimport { isErrnoCode } from \"../utils/errno.js\";\nimport { withHeldFileLock } from \"../utils/serialize-mutations.js\";\n\n/**\n * Stale threshold (ms) for the per-file advisory lock guarding a fact-hash\n * index merge-save (issue #1909 review round 7). The critical section is a\n * single read+atomic-rewrite of one index file (≤ a few MB), so a holder older\n * than this is treated as crashed. Generous to tolerate slow/encrypted disks\n * without breaking a legitimately in-progress publish.\n */\nconst CONTENT_HASH_INDEX_LOCK_STALE_MS = 30_000;\n/** Version marker for the normalized Unicode hash index format. */\nconst CONTENT_HASH_INDEX_FORMAT_HEADER = \"# remnic-content-hash-index:v2\";\n\nfunction parseHashIndex(raw: string): { versioned: boolean; hashes: Set<string> } {\n  const lines = raw\n    .split(\"\\n\")\n    .map((line) => line.trim())\n    .filter((line) => line.length > 0);\n  if (lines[0] !== CONTENT_HASH_INDEX_FORMAT_HEADER) {\n    return { versioned: false, hashes: new Set() };\n  }\n  return { versioned: true, hashes: new Set(lines.slice(1)) };\n}\n\nfunction serializeHashIndex(hashes: Set<string>): string {\n  return `${CONTENT_HASH_INDEX_FORMAT_HEADER}\\n${[...hashes].join(\"\\n\")}\\n`;\n}\n\n/**\n * Durable-retry policy for a deferred content-hash reconcile save whose\n * cross-process lock acquire timed out (issue #1909 / PR #2016). When the lock\n * is contended past `withHeldFileLock`'s bounded wait, the added hashes are held\n * only in this process's memory; relying on \"some later batch save\" is not\n * durable (the run may be the last before idle/shutdown), and a long-lived peer\n * that already built its authoritative in-memory index will not see the write.\n * So we schedule a bounded, exponentially-backed-off background retry that keeps\n * re-attempting the locked publish until it lands. Bounded because the durable\n * fact `.md` is already on disk and a process restart rebuilds the index from\n * the corpus regardless — exhausting retries degrades to that rebuild safety\n * net, never to data loss or a fatal append failure.\n */\nconst CONTENT_HASH_INDEX_RETRY_MAX_ATTEMPTS = 5;\n/** Base backoff (ms) before the first deferred reconcile-save retry; doubles each attempt. */\nconst CONTENT_HASH_INDEX_RETRY_BASE_MS = 500;\n/** Ceiling (ms) for the exponential reconcile-save retry backoff. */\nexport const CONTENT_HASH_INDEX_RETRY_MAX_DELAY_MS = 5_000;\n\n/**\n * Tuning for {@link ContentHashIndex} cross-process lock waits and the\n * deferred reconcile-save durable retry (issue #1909 / PR #2016). All optional;\n * production uses the module defaults. Tests inject small values so the\n * lock-timeout + retry path is exercised deterministically without real\n * multi-second waits.\n */\nexport interface ContentHashIndexLockOptions {\n  /** Bounded wait to acquire the per-file advisory lock; passed to `withHeldFileLock` (default 5000ms). */\n  readonly maxWaitMs?: number;\n  /** Poll interval while waiting for a busy lock (default 50ms). */\n  readonly pollMs?: number;\n  /** Base backoff before the first deferred-save retry (default 500ms). */\n  readonly retryBaseMs?: number;\n  /** Max deferred-save retries before falling back to the corpus-rebuild safety net (default 5). */\n  readonly retryMaxAttempts?: number;\n}\n\n/**\n * Thrown when the fact-hash index cannot be made authoritative — the\n * cross-process rebuild lock could not be acquired within the bounded retry\n * budget (PR #2016). Callers that require an authoritative dedup answer surface\n * this instead of silently trusting a stale loaded snapshot.\n */\nexport class FactHashIndexNotAuthoritativeError extends Error {\n  constructor(stateDir: string) {\n    super(\n      `fact-hash index is not authoritative: the cross-process rebuild lock for ${stateDir} could not be acquired within the bounded retry budget`\n    );\n    this.name = \"FactHashIndexNotAuthoritativeError\";\n  }\n}\n\ntype DiskFingerprint = {\n  mtimeMs: number;\n  size: number;\n  dev: number;\n  ino: number;\n  ctimeMs: number;\n  birthtimeMs: number;\n};\nexport interface ContentHashPathEntry {\n  readonly path: string;\n  readonly contentHash: string;\n}\n\n/**\n * Content-hash dedup index for facts.\n * Normalizes content (lowercase, strip punctuation, collapse whitespace),\n * computes SHA-256, and stores hashes in a line-delimited file.\n * Prevents writing semantically identical facts.\n */\nexport class ContentHashIndex {\n  private hashes: Set<string> = new Set();\n  private dirty = false;\n  /** True when load() found the pre-Unicode, markerless on-disk format. */\n  private formatMigrationRequired = false;\n  /**\n   * Hashes explicitly removed since the last successful save (issue #1909 review\n   * round 8 thread 3). Tracked separately so `saveMergingWithDisk` can be\n   * removal-AWARE: under the file lock it reads the latest on-disk set, DROPS\n   * these, then unions our additions — so a removal batch cannot resurrect a\n   * hash (union alone would) and cannot clobber a concurrent extraction's\n   * appended hash (blind overwrite would). Consumed + cleared by every save.\n   */\n  private removed: Set<string> = new Set();\n  /**\n   * Hashes added by THIS instance since the last successful save (issue #1909\n   * review round 9 finding 3). Tracked separately from the loaded snapshot so a\n   * reconciling save publishes `(on-disk \\ removed) ∪ added` — it re-applies only\n   * OUR additions, never the stale loaded entries. Without this, seeding the\n   * merge from `this.hashes` (loaded ∪ added) would resurrect a hash a peer\n   * removed on disk while this instance held a stale snapshot.\n   */\n  private added: Set<string> = new Set();\n  private readonly filePath: string;\n  private readonly secureStoreKeyProvider: () => Buffer | null;\n  private readonly secureStoreWriteKeyProvider: () => Buffer | null;\n  private readonly memoryDir: string;\n  private readonly lockOptions: ContentHashIndexLockOptions;\n  /**\n   * Deferred reconcile-save durable-retry state (issue #1909 / PR #2016). At\n   * most ONE retry is ever armed (`reconcileRetryTimer` is the reentrancy guard)\n   * so successive timed-out saves cannot stack duplicate/parallel retries.\n   * `reconcileRetryBarrier` resolves when the chain settles (published or gave\n   * up) — awaited by tests and any caller wanting the eventual result.\n   */\n  private reconcileRetryTimer: NodeJS.Timeout | null = null;\n  private reconcileRetryAttempts = 0;\n  private reconcileRetryBarrier: Promise<void> | null = null;\n  private reconcileRetryResolve: (() => void) | null = null;\n  /**\n   * On-disk fingerprint captured at the last point THIS instance's in-memory\n   * set matched disk — after `load()`, `save()`, or a reconcile publish. A peer\n   * process that advances the durable index changes its file generation even\n   * when byte size and mtime collide, so the freshness check remains safe\n   * without an O(file-size) read on the hot path.\n   */\n  private lastSyncedFingerprint: DiskFingerprint | null = null;\n  constructor(\n    stateDir: string,\n    secureStoreKeyProvider: () => Buffer | null = () => null,\n    secureStoreWriteKeyProvider: () => Buffer | null = secureStoreKeyProvider,\n    memoryDir: string = path.dirname(stateDir),\n    lockOptions: ContentHashIndexLockOptions = {}\n  ) {\n    this.filePath = path.join(stateDir, \"fact-hashes.txt\");\n    this.secureStoreKeyProvider = secureStoreKeyProvider;\n    this.secureStoreWriteKeyProvider = secureStoreWriteKeyProvider;\n    this.memoryDir = memoryDir;\n    this.lockOptions = lockOptions;\n  }\n  /** Whether a caller with an authoritative corpus must rebuild this legacy index. */\n  get requiresFormatMigration(): boolean {\n    return this.formatMigrationRequired;\n  }\n\n  /** Load existing hashes from disk. Safe to call multiple times. */\n  async load(): Promise<void> {\n    try {\n      const raw = await readMaybeEncryptedFile(this.filePath, this.secureStoreKeyProvider(), this.memoryDir);\n      const parsed = parseHashIndex(raw);\n      this.formatMigrationRequired = !parsed.versioned;\n      if (!parsed.versioned) {\n        // Hashes from the pre-NFC format are unsafe after normalization changes.\n        // Ignore them until an authoritative corpus rebuild publishes v2.\n        this.hashes.clear();\n        log.warn(`content-hash index: ignored legacy unversioned index at ${this.filePath}`);\n      } else {\n        for (const hash of parsed.hashes) this.hashes.add(hash);\n      }\n      log.debug(`content-hash index: loaded ${this.hashes.size} hashes`);\n    } catch (err) {\n      if (err instanceof SecureStoreLockedError) throw err;\n      if (!isErrnoCode(err, \"ENOENT\")) throw err;\n      log.debug(\"content-hash index: no existing index — starting fresh\");\n    }\n    // The loaded set now reflects the on-disk file — baseline the fingerprint so\n    // a later peer write is detectable (PR #2016 review).\n    await this.captureSyncedFingerprint();\n  }\n\n  /** Cheap `stat` of the durable index file; null when it does not exist yet. */\n  private async statIndexFile(): Promise<DiskFingerprint | null> {\n    try {\n      const s = await stat(this.filePath);\n      return {\n        mtimeMs: s.mtimeMs,\n        size: s.size,\n        dev: s.dev,\n        ino: s.ino,\n        ctimeMs: s.ctimeMs,\n        birthtimeMs: s.birthtimeMs,\n      };\n    } catch (err) {\n      if (isErrnoCode(err, \"ENOENT\")) return null;\n      throw err;\n    }\n  }\n\n  /** Record the current on-disk fingerprint as this instance's synced baseline. */\n  private async captureSyncedFingerprint(): Promise<void> {\n    try {\n      this.lastSyncedFingerprint = await this.statIndexFile();\n    } catch (err) {\n      // A stat failure other than ENOENT leaves no baseline; the next freshness\n      // check reports non-current and the caller confirms against the corpus.\n      this.lastSyncedFingerprint = null;\n      log.debug(`content-hash index: could not fingerprint ${this.filePath}: ${err}`);\n    }\n  }\n\n  /**\n   * True when the durable index file is unchanged since this instance last\n   * synced it (load / save / reconcile). False when a peer advanced it, when\n   * the file appeared or vanished, or when freshness cannot be established\n   * (stat error) — the caller then treats the in-memory snapshot as\n   * non-authoritative and confirms a dedup miss against the durable corpus.\n   * The stat includes file identity and generation metadata so same-size,\n   * same-mtime atomic replacements are detected without reading the file body.\n   */\n  async isDiskFingerprintCurrent(): Promise<boolean> {\n    let current: DiskFingerprint | null;\n    try {\n      current = await this.statIndexFile();\n    } catch {\n      return false;\n    }\n    const last = this.lastSyncedFingerprint;\n    if (last === null || current === null) {\n      return last === null && current === null;\n    }\n    return (\n      current.mtimeMs === last.mtimeMs &&\n      current.size === last.size &&\n      current.dev === last.dev &&\n      current.ino === last.ino &&\n      current.ctimeMs === last.ctimeMs &&\n      current.birthtimeMs === last.birthtimeMs\n    );\n  }\n\n  /** Check if content already exists in the index. */\n  has(content: string): boolean {\n    return this.hashes.has(ContentHashIndex.computeHash(content));\n  }\n\n  /** Add content hash to the index. */\n  add(content: string): void {\n    const hash = ContentHashIndex.computeHash(content);\n    // A re-add supersedes a pending removal of the same hash (round 8 thread 3).\n    this.removed.delete(hash);\n    // Record OUR durable delta even when the local snapshot already holds the\n    // hash (PR #2016 thread SD-nG): local membership can be STALE — a peer\n    // removed this hash on disk while this instance kept it in memory. Skipping\n    // `added`/`dirty` on that path let the reconciling save compute\n    // (on-disk \\ removed) ∪ added and silently drop the reintroduced hash, so\n    // the peer never saw it again. Set semantics keep this idempotent (no\n    // duplicate entries) and the `removed.delete` above preserves remove/add\n    // ordering.\n    this.hashes.add(hash);\n    this.added.add(hash);\n    this.dirty = true;\n  }\n\n  get size(): number {\n    return this.hashes.size;\n  }\n\n  /** Clear all loaded hashes so the next save rewrites the index from scratch. */\n  clear(): void {\n    if (this.hashes.size > 0) {\n      this.hashes.clear();\n    }\n    // A full clear is always paired with a plain overwrite save() (rebuild);\n    // pending per-hash add/remove deltas are subsumed by writing the rebuilt set.\n    // Cancel any armed deferred-reconcile retry (PR #2016) so it cannot fire in\n    // the clear→rebuild→save window and union the pre-clear on-disk rows back.\n    this.added.clear();\n    this.removed.clear();\n    this.cancelReconcileRetry();\n    this.dirty = true;\n  }\n\n  /** Persist index to disk if changed (plain whole-file overwrite). */\n  async save(): Promise<void> {\n    if (!this.dirty) return;\n    await mkdir(path.dirname(this.filePath), { recursive: true });\n    // Snapshot the deltas + overwrite body THIS save publishes BEFORE the write\n    // yields the event loop. `writeMaybeEncryptedFile` materializes `serialized`\n    // eagerly, then the disk await lets a concurrent same-process add()/remove()\n    // land a late delta (PR #2016 thread PRRT_kwDORJXyws6SEBri). Clearing the\n    // LIVE added/removed sets afterward — as the previous unconditional\n    // clear()+`dirty = false` did — would drop that late hash from the index AND\n    // leave no retry, so peers never see it until a corpus rebuild. Consume only\n    // what we published; late deltas stay pending. Mirrors saveMergingWithDisk.\n    const publishedAdded = new Set<string>(this.added);\n    const publishedRemoved = new Set<string>(this.removed);\n    const serialized = serializeHashIndex(this.hashes);\n    await writeMaybeEncryptedFile(this.filePath, serialized, this.secureStoreWriteKeyProvider(), {}, this.memoryDir);\n    this.formatMigrationRequired = false;\n    // Consume ONLY the deltas this overwrite published; anything that arrived\n    // during the awaits above remains pending for the next save.\n    for (const h of publishedAdded) this.added.delete(h);\n    for (const h of publishedRemoved) this.removed.delete(h);\n    // Honest dirty state: true iff late deltas remain unpersisted.\n    this.dirty = this.added.size > 0 || this.removed.size > 0;\n    // This overwrite is now the on-disk state — re-baseline the freshness\n    // fingerprint so our own write is not later mistaken for a peer's (PR #2016).\n    await this.captureSyncedFingerprint();\n    if (this.dirty) {\n      // Late deltas landed mid-save: arm a bounded durable retry so they reach\n      // disk even without a further batch save — never a silent in-memory-only\n      // hash. The locked reconcile republishes only OUR delta onto the overwrite.\n      this.scheduleReconcileRetry();\n    } else {\n      // Clean overwrite supersedes any pending deferred reconcile work.\n      this.cancelReconcileRetry();\n    }\n    log.debug(`content-hash index: saved ${this.hashes.size} hashes`);\n  }\n\n  /**\n   * Persist the index by RECONCILING with the latest on-disk state under a\n   * cross-process lock (issue #1909). Used by the extraction-persist batch save\n   * for BOTH append and removal batches, so appends and removals to the same\n   * index serialize against each other:\n   *   final = (on-disk \\ this.removed) ∪ this.added\n   * Note it re-applies only OUR local additions (`added`), NOT the loaded\n   * snapshot (review round 9 finding 3): seeding from `this.hashes` would\n   * resurrect a hash a peer removed on disk while we held a stale snapshot. This\n   * preserves a concurrent writer's appended hashes (a blind overwrite would\n   * drop them), never resurrects a removed hash, and never loses our additions.\n   *\n   * Hardening:\n   *  - Dirty short-circuit (round 7 finding 3): when this instance neither added\n   *    nor removed anything this run, skip the O(file) read+rewrite entirely.\n   *  - Cross-process lock (round 7 finding 2): serialize the read→reconcile→write\n   *    window on a per-file advisory lock. If the lock is NOT acquired (timeout),\n   *    do NOT publish (round 9 finding 2): keep `dirty` set AND schedule a bounded\n   *    durable background retry (PR #2016) that keeps re-attempting the locked\n   *    publish until the deferred additions land — never an unlocked write that\n   *    could clobber a peer, and never a silent \"batch save complete\" that leaves\n   *    the addition in this process's memory only.\n   */\n  async saveMergingWithDisk(): Promise<void> {\n    if (!this.dirty) return;\n    // The advisory lock file lives beside the index — ensure the dir exists\n    // before acquiring it (the index dir may not exist on a first write).\n    await mkdir(path.dirname(this.filePath), { recursive: true });\n    const publish = async (): Promise<void> => {\n      // Snapshot the deltas this publish is responsible for. The read+rewrite\n      // below yields the event loop, so a concurrent add()/remove() can land\n      // new deltas while we await disk (PR #2016 thread SD7Tj). Consuming the\n      // LIVE sets afterward would drop those late deltas AND clear `dirty`,\n      // stranding them in no save at all. We consume only what we published;\n      // anything that arrived meanwhile stays pending for the next save.\n      const publishedAdded = new Set<string>(this.added);\n      const publishedRemoved = new Set<string>(this.removed);\n      const merged = new Set<string>(publishedAdded);\n      try {\n        const raw = await readMaybeEncryptedFile(this.filePath, this.secureStoreKeyProvider(), this.memoryDir);\n        const parsed = parseHashIndex(raw);\n        if (parsed.versioned) {\n          for (const hash of parsed.hashes) {\n            // Keep prior/concurrent on-disk hashes EXCEPT the ones we removed.\n            if (!publishedRemoved.has(hash)) merged.add(hash);\n          }\n        } else {\n          // Do not carry hashes from the pre-NFC format into a v2 write.\n          log.warn(`content-hash index: discarded legacy unversioned entries from ${this.filePath}`);\n        }\n      } catch (err) {\n        if (err instanceof SecureStoreLockedError) throw err;\n        if (!isErrnoCode(err, \"ENOENT\")) throw err;\n        // ENOENT → no on-disk index yet; write our additions as-is.\n      }\n      await mkdir(path.dirname(this.filePath), { recursive: true });\n      await writeMaybeEncryptedFile(\n        this.filePath,\n        serializeHashIndex(merged),\n        this.secureStoreWriteKeyProvider(),\n        {},\n        this.memoryDir\n      );\n      this.formatMigrationRequired = false;\n      // Consume ONLY the deltas we just published; deltas that arrived during\n      // the awaits above remain pending.\n      for (const h of publishedAdded) this.added.delete(h);\n      for (const h of publishedRemoved) this.removed.delete(h);\n      // Fold any still-pending deltas onto the reconciled set so the in-memory\n      // view stays consistent with what the next save will publish.\n      for (const h of this.added) merged.add(h);\n      for (const h of this.removed) merged.delete(h);\n      this.hashes = merged;\n      // Honest dirty state: true iff late deltas remain to be persisted. A\n      // subsequent batch save or the shutdown flush drains them.\n      this.dirty = this.added.size > 0 || this.removed.size > 0;\n      // The reconciled set is now the on-disk state — re-baseline the freshness\n      // fingerprint (captured under the held lock) so our own publish is not\n      // later mistaken for a peer's advance (PR #2016 review).\n      await this.captureSyncedFingerprint();\n    };\n    await withHeldFileLock(\n      `${this.filePath}.lock`,\n      {\n        staleMs: CONTENT_HASH_INDEX_LOCK_STALE_MS,\n        ...(this.lockOptions.maxWaitMs !== undefined ? { maxWaitMs: this.lockOptions.maxWaitMs } : {}),\n        ...(this.lockOptions.pollMs !== undefined ? { pollMs: this.lockOptions.pollMs } : {}),\n      },\n      async (acquired) => {\n        if (!acquired) {\n          // Never publish unlocked (round 9 finding 2): keep dirty AND schedule a\n          // durable background retry (PR #2016). Relying on an unguaranteed later\n          // batch save silently left the addition in this process's memory only;\n          // the retry keeps re-attempting the locked publish until the addition\n          // lands on disk.\n          log.warn(\n            `content-hash index: lock not acquired for ${this.filePath}; deferring reconcile save (dirty retained, scheduling durable retry)`\n          );\n          this.scheduleReconcileRetry();\n          return;\n        }\n        await publish();\n        if (this.dirty) {\n          // A concurrent add()/remove() landed during publish's disk awaits, so\n          // deltas remain unpersisted (PR #2016 thread SD7Tj). Arm a bounded\n          // durable retry so they reach disk even if no further batch save comes\n          // — never leave a settled barrier over pending work.\n          this.scheduleReconcileRetry();\n        } else {\n          // Published cleanly: any pending deferred retry is now satisfied.\n          this.cancelReconcileRetry();\n        }\n      }\n    );\n    log.debug(`content-hash index: reconcile-saved ${this.hashes.size} hashes`);\n  }\n\n  /**\n   * Rebuild-and-publish the index from an authoritative source (the durable\n   * corpus) under the SAME per-file cross-process lock the reconciling\n   * append/removal saves (`saveMergingWithDisk`) use (issue #1909 / PR #2016).\n   * The `populate` callback runs WHILE the lock is held and MUST repopulate this\n   * index from the corpus (`clear()` then `addByHash(...)` for every corpus\n   * hash); the rebuilt set is then published with a plain overwrite that is now\n   * serialized against every locked writer.\n   *\n   * This closes the finding where the previous unlocked clear→scan→save() could\n   * overwrite a peer's newer lock-merged or deferred additions: a locked writer\n   * that committed BEFORE the rebuild acquired the lock has its memory `.md` on\n   * disk and is re-scanned; one that commits AFTER the rebuild releases\n   * reconciles its additions on top of the freshly-published set. No union with\n   * the raw on-disk file is performed, so the rebuild keeps its\n   * garbage-collection property (orphaned hashes for deleted memories drop).\n   *\n   * Lock-acquisition failure is explicit and non-destructive: `populate` is NOT\n   * run and nothing is written (never an unlocked overwrite). Returns true when\n   * the rebuild was published under the lock, false when the lock timed out —\n   * the caller keeps the index non-authoritative and retries on next use. Uses\n   * the same non-reentrant file lock as the reconcile path, so it can never\n   * deadlock with the deferred reconcile-retry: a concurrent locked writer (or a\n   * fired retry) simply yields `acquired=false` after the bounded wait.\n   */\n  async rebuildUnderLock(populate: () => Promise<void>): Promise<boolean> {\n    // The advisory lock file lives beside the index — ensure the dir exists\n    // before acquiring it (the index dir may not exist on a first rebuild).\n    await mkdir(path.dirname(this.filePath), { recursive: true });\n    let published = false;\n    await withHeldFileLock(\n      `${this.filePath}.lock`,\n      {\n        staleMs: CONTENT_HASH_INDEX_LOCK_STALE_MS,\n        ...(this.lockOptions.maxWaitMs !== undefined ? { maxWaitMs: this.lockOptions.maxWaitMs } : {}),\n        ...(this.lockOptions.pollMs !== undefined ? { pollMs: this.lockOptions.pollMs } : {}),\n      },\n      async (acquired) => {\n        if (!acquired) {\n          // Never publish unlocked: a concurrent locked writer holds the lock,\n          // so overwriting now could clobber its addition. Leave the index as-is\n          // and let the caller retry the authoritative rebuild on next use.\n          log.warn(\n            `content-hash index: lock not acquired for ${this.filePath}; deferring authoritative rebuild (index left non-authoritative, retried on next use)`\n          );\n          return;\n        }\n        await populate();\n        // Publish under the held lock. save() takes no lock (no re-entrancy) and\n        // is a full overwrite that supersedes any pending add/remove deltas.\n        await this.save();\n        published = true;\n      }\n    );\n    return published;\n  }\n\n  /**\n   * True while a background durable reconcile-save retry is armed (PR #2016).\n   * Test/introspection hook.\n   */\n  get hasPendingReconcileRetry(): boolean {\n    return this.reconcileRetryTimer !== null;\n  }\n\n  /** True while this index has in-memory changes not yet published to disk. */\n  get hasPendingChanges(): boolean {\n    return this.dirty;\n  }\n\n  /**\n   * Resolve once any armed background reconcile-save retry chain has settled —\n   * either it published the deferred additions, or it exhausted its bounded\n   * attempts and fell back to the corpus-rebuild safety net. Resolves\n   * immediately when nothing is armed. Lets a caller (or a test) await the\n   * eventual durability outcome of a lock-timed-out save.\n   */\n  async whenReconcileRetrySettled(): Promise<void> {\n    await (this.reconcileRetryBarrier ?? Promise.resolve());\n  }\n\n  /**\n   * Drive any deferred lock-timeout reconcile save to completion INLINE at a\n   * lifecycle boundary (PR #2016 finding 3). The background retry timer is\n   * `unref`'d so it never keeps a long-lived daemon alive — but a short-lived\n   * writer (a one-shot CLI) can exit before it fires, leaving a durable fact\n   * `.md` whose hash never reached `fact-hashes.txt` for peers that already\n   * built their in-memory index. `orchestrator.destroy()` calls this so the\n   * addition publishes before the process exits; long-lived hosts only reach it\n   * at their own shutdown, so their in-flight retries keep running in the\n   * background until then. Bounded by the same attempt ceiling as the background\n   * retry; a permanently contended lock falls back to the corpus-rebuild-on-\n   * restart safety net (the fact `.md` is already durable). No deadlock: each\n   * attempt is the same non-reentrant, bounded-wait file lock.\n   */\n  async flushReconcileRetry(): Promise<void> {\n    if (!this.dirty) return;\n    const maxAttempts = this.lockOptions.retryMaxAttempts ?? CONTENT_HASH_INDEX_RETRY_MAX_ATTEMPTS;\n    const baseMs = this.lockOptions.retryBaseMs ?? CONTENT_HASH_INDEX_RETRY_BASE_MS;\n    for (let attempt = 0; this.dirty && attempt < maxAttempts; attempt += 1) {\n      // Cancel the unref'd background timer — we drive the locked publish inline.\n      if (this.reconcileRetryTimer) {\n        clearTimeout(this.reconcileRetryTimer);\n        this.reconcileRetryTimer = null;\n      }\n      await this.saveMergingWithDisk();\n      if (!this.dirty) break;\n      if (attempt < maxAttempts - 1) {\n        const wait = Math.min(baseMs * 2 ** attempt, CONTENT_HASH_INDEX_RETRY_MAX_DELAY_MS);\n        await new Promise<void>((resolve) => setTimeout(resolve, wait));\n      }\n    }\n    // Clear any timer the final saveMergingWithDisk armed and settle the barrier\n    // so awaiters unblock — the bounded inline drain has done its best.\n    if (this.reconcileRetryTimer) {\n      clearTimeout(this.reconcileRetryTimer);\n      this.reconcileRetryTimer = null;\n    }\n    this.reconcileRetryAttempts = 0;\n    this.settleReconcileRetry();\n  }\n\n  /**\n   * Schedule ONE bounded, exponentially-backed-off background retry of the\n   * deferred reconcile save (PR #2016). Reentrant-safe: an already-armed timer\n   * short-circuits, so successive timed-out saves never stack duplicate retries.\n   * When attempts are exhausted the chain settles without publishing — the\n   * durable fact `.md` is on disk and a process restart rebuilds the index from\n   * the corpus, so this degrades to that safety net, never a fatal failure.\n   */\n  private scheduleReconcileRetry(): void {\n    if (this.reconcileRetryTimer) return; // one retry in flight — no duplicate/reentrant retries\n    const maxAttempts = this.lockOptions.retryMaxAttempts ?? CONTENT_HASH_INDEX_RETRY_MAX_ATTEMPTS;\n    if (this.reconcileRetryAttempts >= maxAttempts) {\n      log.warn(\n        `content-hash index: exhausted ${maxAttempts} deferred reconcile-save retries for ${this.filePath}; ` +\n          `${this.added.size} addition(s) remain dirty in-memory (a process restart rebuilds the index from the durable corpus)`\n      );\n      this.reconcileRetryAttempts = 0;\n      this.settleReconcileRetry();\n      return;\n    }\n    if (!this.reconcileRetryBarrier) {\n      this.reconcileRetryBarrier = new Promise<void>((resolve) => {\n        this.reconcileRetryResolve = resolve;\n      });\n    }\n    const attempt = this.reconcileRetryAttempts + 1;\n    const baseMs = this.lockOptions.retryBaseMs ?? CONTENT_HASH_INDEX_RETRY_BASE_MS;\n    const delay = Math.min(baseMs * 2 ** (attempt - 1), CONTENT_HASH_INDEX_RETRY_MAX_DELAY_MS);\n    this.reconcileRetryTimer = setTimeout(() => {\n      this.reconcileRetryTimer = null;\n      this.reconcileRetryAttempts = attempt;\n      void this.saveMergingWithDisk()\n        .catch((err) => {\n          // A publish-time I/O/encryption error (not a lock timeout) is best-effort:\n          // log and let the corpus-rebuild safety net cover it rather than loop.\n          log.warn(`content-hash index: deferred reconcile-save retry failed for ${this.filePath}: ${err}`);\n        })\n        .finally(() => {\n          // If the attempt neither published (dirty cleared → cancelReconcileRetry)\n          // nor re-armed a further retry, the chain has ended — settle the barrier.\n          if (this.dirty && !this.reconcileRetryTimer) this.settleReconcileRetry();\n        });\n    }, delay);\n    this.reconcileRetryTimer.unref?.();\n  }\n\n  /** Cancel any armed reconcile-save retry and settle the barrier (a publish landed). */\n  private cancelReconcileRetry(): void {\n    if (this.reconcileRetryTimer) {\n      clearTimeout(this.reconcileRetryTimer);\n      this.reconcileRetryTimer = null;\n    }\n    this.reconcileRetryAttempts = 0;\n    this.settleReconcileRetry();\n  }\n\n  /** Resolve and clear the retry barrier if one is outstanding. */\n  private settleReconcileRetry(): void {\n    const resolve = this.reconcileRetryResolve;\n    this.reconcileRetryBarrier = null;\n    this.reconcileRetryResolve = null;\n    resolve?.();\n  }\n\n  /** Remove a hash from the index (used when archiving/deleting). */\n  remove(content: string): void {\n    const hash = ContentHashIndex.computeHash(content);\n    // Record the removal (round 8 thread 3) even when the hash is not in our\n    // in-memory set — a reconciling save must still drop it from the latest\n    // on-disk state. A removal supersedes a pending add. Always mark dirty.\n    this.added.delete(hash);\n    this.removed.add(hash);\n    this.hashes.delete(hash);\n    this.dirty = true;\n  }\n\n  /**\n   * Remove a pre-computed SHA-256 hash directly from the index without\n   * re-hashing.  Use this when the caller already holds the stored hash\n   * (e.g. `memory.frontmatter.contentHash`) to avoid the double-hash bug\n   * where `remove(hash)` would compute `hash(hash)` and never match the\n   * entry.\n   */\n  removeByHash(hash: string): void {\n    this.added.delete(hash);\n    this.removed.add(hash);\n    this.hashes.delete(hash);\n    this.dirty = true;\n  }\n\n  /**\n   * Add a pre-computed SHA-256 hash directly to the index without re-hashing.\n   * Use this when the caller already holds the stored hash\n   * (e.g. `memory.frontmatter.contentHash`) so that the index records the raw\n   * content hash rather than re-hashing the citation-annotated body.\n   *\n   * @internal Only called from `StorageManager.ensureFactHashIndexAuthoritative`.\n   * Not part of the public API — prefer `add(content)` for external callers.\n   */\n  addByHash(hash: string): void {\n    // A re-add supersedes a pending removal of the same hash.\n    this.removed.delete(hash);\n    // Record OUR durable delta even when the local snapshot already holds the\n    // hash (PR #2016 thread PRRT_kwDORJXyws6SEHve). Outside a rebuild\n    // (StorageManager.addActiveFactContentHash on reactivation) local\n    // membership can be STALE: a peer removed this hash on disk while this\n    // instance kept it in memory. Skipping added/dirty on that path let the\n    // reconciling save compute (on-disk \\ removed) ∪ added and silently drop\n    // the reintroduced hash, so the peer never saw it again. Set semantics keep\n    // this idempotent (no duplicate entries) and the removed.delete above\n    // preserves remove/add ordering. Mirrors add().\n    this.hashes.add(hash);\n    this.added.add(hash);\n    this.dirty = true;\n  }\n\n  /**\n   * Resolve a pre-computed semantic hash to one deterministic corpus path.\n   *\n   * This lookup is separate from durable hash membership: `this.hashes` stays\n   * one hash per line and `has(content)` keeps its existing raw-content contract.\n   * Reconciliation supplies short-lived manifest rows where hash and path coexist.\n   */\n  static resolvePathByHash(hash: string, entries: Iterable<ContentHashPathEntry>): string | undefined {\n    const canonicalHash = hash.toLowerCase();\n    if (!/^[a-f0-9]{64}$/.test(canonicalHash)) return undefined;\n    let canonicalPath: string | undefined;\n    for (const entry of entries) {\n      if (entry.contentHash.toLowerCase() !== canonicalHash || entry.path.length === 0) continue;\n      if (canonicalPath === undefined || entry.path < canonicalPath) canonicalPath = entry.path;\n    }\n    return canonicalPath;\n  }\n\n  /** Normalize content (delegates to content-hash.ts for a single source of truth). */\n  static normalizeContent(content: string): string {\n    return normalizeContent(content);\n  }\n\n  /** Compute SHA-256 hash (delegates to content-hash.ts for a single source of truth). */\n  static computeHash(content: string): string {\n    return computeContentHash(content);\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-XMMESCPD.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/memory-cache.ts"],"sourcesContent":["import type { EntityFile, MemoryFile } from \"./types.js\";\nimport { clearQmdRecallCache, qmdRecallCacheSize } from \"./qmd-recall-cache.js\";\n\ninterface CacheEntry {\n  memories: Map<string, MemoryFile>; // keyed by file path\n  version: number;\n  loadedAt: number;\n  // Secure-store key identity that decrypted these memories (issue #1902, Codex\n  // P1). \"\" for plaintext/locked stores. A manager only reads an entry whose\n  // keyId matches its own, so a locked/unkeyed instance never sees content\n  // another instance decrypted under a key for the same baseDir.\n  keyId: string;\n  // Effective TTL (ms) this entry was stored under (issue #1902, Codex Medium),\n  // so the opportunistic sweep can evict abandoned corpora that are never\n  // revisited. 0 = no TTL (never swept by age).\n  ttlMs: number;\n}\n\n// Module-level singleton — shared across all StorageManager instances and sessions\nconst hotCacheByDir = new Map<string, CacheEntry>();\nconst archiveCacheByDir = new Map<string, CacheEntry>();\n\n/**\n * Evict every hot entry whose own TTL has elapsed (issue #1902, Codex Medium).\n * Called opportunistically on each set so a long-running process that reads many\n * namespace/temporary roots and never revisits some of them still releases their\n * (potentially hundreds-of-MB) corpora within the TTL, instead of holding them\n * resident until an explicit global clear. O(entries) over a small map.\n */\nfunction sweepExpiredHotEntries(now: number): void {\n  for (const [dir, entry] of hotCacheByDir) {\n    if (entry.ttlMs > 0 && now - entry.loadedAt > entry.ttlMs) hotCacheByDir.delete(dir);\n  }\n}\n\nexport function getCachedMemories(\n  baseDir: string,\n  currentVersion: number,\n  keyId = \"\",\n  ttlMs = 0,\n): MemoryFile[] | null {\n  // Don't serve from cache when version tracking is unavailable (version=0).\n  // This ensures tests and fresh installs without a version file always read disk.\n  if (currentVersion === 0) return null;\n  const entry = hotCacheByDir.get(baseDir);\n  if (!entry || entry.version !== currentVersion || entry.keyId !== keyId) return null;\n  // TTL safety net (issue #1902): bound staleness from external filesystem edits\n  // that bypass the version sentinel. ttlMs <= 0 disables the check. On expiry\n  // evict the entry (not just return null) so a revisited-but-stale dir releases\n  // its resident corpus instead of lingering until an explicit clear.\n  if (ttlMs > 0 && Date.now() - entry.loadedAt > ttlMs) {\n    hotCacheByDir.delete(baseDir);\n    return null;\n  }\n  return [...entry.memories.values()];\n}\n\nexport function setCachedMemories(\n  baseDir: string,\n  memories: MemoryFile[],\n  version: number,\n  keyId = \"\",\n  ttlMs = 0,\n): void {\n  const map = new Map<string, MemoryFile>();\n  for (const m of memories) map.set(m.path, m);\n  const now = Date.now();\n  hotCacheByDir.set(baseDir, { memories: map, version, loadedAt: now, keyId, ttlMs });\n  // Release abandoned corpora that expired but were never revisited (Codex Medium).\n  sweepExpiredHotEntries(now);\n}\n\nexport function updateCacheOnWrite(baseDir: string, memory: MemoryFile, keyId = \"\"): void {\n  const entry = hotCacheByDir.get(baseDir);\n  // Only mutate an entry that belongs to THIS key identity (issue #1902, Codex\n  // Medium). A concurrent differently-keyed manager may have replaced the\n  // single hotCacheByDir slot during an awaited parse; inserting our decrypted\n  // MemoryFile into its entry would leak plaintext across the key boundary.\n  if (entry && entry.keyId === keyId) entry.memories.set(memory.path, memory);\n}\n\nexport function updateCacheOnDelete(baseDir: string, filePath: string, keyId = \"\"): void {\n  const entry = hotCacheByDir.get(baseDir);\n  if (entry && entry.keyId === keyId) entry.memories.delete(filePath);\n}\n// Archive cache — same pattern, separate store\nexport function getCachedArchivedMemories(\n  baseDir: string,\n  currentVersion: number,\n  keyId = \"\",\n): MemoryFile[] | null {\n  if (currentVersion === 0) return null;\n  const entry = archiveCacheByDir.get(baseDir);\n  if (!entry || entry.version !== currentVersion || entry.keyId !== keyId) return null;\n  return [...entry.memories.values()];\n}\n\nexport function setCachedArchivedMemories(\n  baseDir: string,\n  memories: MemoryFile[],\n  version: number,\n  keyId = \"\",\n): void {\n  const map = new Map<string, MemoryFile>();\n  for (const m of memories) map.set(m.path, m);\n  // ttlMs: 0 — the archive cache has no age TTL; it is version-keyed and cleared\n  // via invalidation. The field satisfies the shared CacheEntry shape (#1902).\n  archiveCacheByDir.set(baseDir, { memories: map, version, loadedAt: Date.now(), keyId, ttlMs: 0 });\n}\n\n// Entity cache — same pattern as memory cache, but keyed by schema-aware parse inputs.\nconst entityCacheByDir = new Map<string, { entities: EntityFile[]; version: number; loadedAt: number }>();\n\n/**\n * Single normalization point for the entity-cache schema key (issue #1535).\n * BOTH the set/get key builder and the prefix invalidation derive from here so\n * `undefined` vs `\"\"` (or any future normalization rule) can never diverge\n * between the write path and the invalidate path (rule 38 cousin).\n */\nfunction normalizeEntitySchemaKey(schemaKey: string | undefined): string {\n  return schemaKey ?? \"\";\n}\n\n/** Prefix shared by every entity-cache key for a dir, regardless of schemaKey. */\nfunction entityCacheKeyPrefix(baseDir: string): string {\n  return `${baseDir}\\u0000`;\n}\n\nfunction buildEntityCacheKey(baseDir: string, schemaKey?: string): string {\n  return `${entityCacheKeyPrefix(baseDir)}${normalizeEntitySchemaKey(schemaKey)}`;\n}\n\nexport function getCachedEntities(\n  baseDir: string,\n  currentVersion: number,\n  schemaKey: string = \"\",\n): EntityFile[] | null {\n  if (currentVersion === 0) return null;\n  const entry = entityCacheByDir.get(buildEntityCacheKey(baseDir, schemaKey));\n  if (!entry || entry.version !== currentVersion) return null;\n  return entry.entities;\n}\n\nexport function setCachedEntities(\n  baseDir: string,\n  entities: EntityFile[],\n  version: number,\n  schemaKey: string = \"\",\n): void {\n  entityCacheByDir.set(buildEntityCacheKey(baseDir, schemaKey), {\n    entities,\n    version,\n    loadedAt: Date.now(),\n  });\n}\n\nexport function invalidateCachedEntities(baseDir: string): void {\n  const prefix = entityCacheKeyPrefix(baseDir);\n  for (const key of entityCacheByDir.keys()) {\n    if (key.startsWith(prefix)) entityCacheByDir.delete(key);\n  }\n}\n\n// Derived caches — pre-filtered views invalidated alongside the main cache.\n// These avoid O(146K) filter+map on every verified recall/rules call.\ninterface DerivedCacheEntry<T> {\n  data: T;\n  sourceVersion: number; // matches the hot cache version it was derived from\n  keyId: string; // secure-store key identity of the corpus it was derived from (#1902)\n  loadedAt: number; // build time — bounds staleness from external edits via ttlMs (#1902)\n}\n\nconst episodeMapByDir = new Map<string, DerivedCacheEntry<Map<string, MemoryFile>>>();\nconst ruleMemoriesByDir = new Map<string, DerivedCacheEntry<{ all: MemoryFile[]; byId: Map<string, MemoryFile> }>>();\n\nexport function getCachedEpisodeMap(\n  baseDir: string,\n  currentVersion: number,\n  keyId = \"\",\n  ttlMs = 0,\n): Map<string, MemoryFile> | null {\n  if (currentVersion === 0) return null;\n  const entry = episodeMapByDir.get(baseDir);\n  if (!entry || entry.sourceVersion !== currentVersion || entry.keyId !== keyId) return null;\n  // TTL safety net (issue #1902): the version sentinel doesn't move on a direct\n  // external edit, so bound how long a derived view is served before a rebuild\n  // (which re-reads via readAllMemories, itself TTL-bounded). ttlMs <= 0 disables.\n  if (ttlMs > 0 && Date.now() - entry.loadedAt > ttlMs) {\n    episodeMapByDir.delete(baseDir);\n    return null;\n  }\n  return entry.data;\n}\n\n/** Build and cache the episode memory map from the full memory list. */\nexport function setCachedEpisodeMap(\n  baseDir: string,\n  memories: MemoryFile[],\n  version: number,\n  cache = true,\n  keyId = \"\",\n): Map<string, MemoryFile> {\n  const map = new Map<string, MemoryFile>();\n  for (const m of memories) {\n    if (m.frontmatter.status === \"archived\" || m.frontmatter.status === \"forgotten\") continue;\n    if (m.frontmatter.memoryKind !== \"episode\") continue;\n    map.set(m.frontmatter.id, m);\n  }\n  if (cache) episodeMapByDir.set(baseDir, { data: map, sourceVersion: version, keyId, loadedAt: Date.now() });\n  return map;\n}\n\n/** Get pre-filtered rule memories. Derived from hot cache. */\nexport function getCachedRuleMemories(\n  baseDir: string,\n  currentVersion: number,\n  keyId = \"\",\n  ttlMs = 0,\n): { all: MemoryFile[]; byId: Map<string, MemoryFile> } | null {\n  if (currentVersion === 0) return null;\n  const entry = ruleMemoriesByDir.get(baseDir);\n  if (!entry || entry.sourceVersion !== currentVersion || entry.keyId !== keyId) return null;\n  // TTL safety net (issue #1902): bound staleness from direct external edits\n  // that don't move the version sentinel. ttlMs <= 0 disables.\n  if (ttlMs > 0 && Date.now() - entry.loadedAt > ttlMs) {\n    ruleMemoriesByDir.delete(baseDir);\n    return null;\n  }\n  return entry.data;\n}\n\n/** Build and cache the rule memories from the full memory list. */\nexport function setCachedRuleMemories(\n  baseDir: string,\n  memories: MemoryFile[],\n  version: number,\n  cache = true,\n  keyId = \"\",\n): { all: MemoryFile[]; byId: Map<string, MemoryFile> } {\n  const byId = new Map<string, MemoryFile>();\n  const all: MemoryFile[] = [];\n  for (const m of memories) {\n    byId.set(m.frontmatter.id, m);\n    if (\n      m.frontmatter.category === \"rule\" &&\n      m.frontmatter.status !== \"archived\" &&\n      m.frontmatter.status !== \"forgotten\"\n    ) {\n      all.push(m);\n    }\n  }\n  const result = { all, byId };\n  if (cache) ruleMemoriesByDir.set(baseDir, { data: result, sourceVersion: version, keyId, loadedAt: Date.now() });\n  return result;\n}\n\n// QMD search result cache — short-lived (60s TTL) to avoid stale results\n// while reducing redundant daemon calls for repeated/similar queries.\ninterface QmdCacheEntry {\n  results: unknown[];\n  cachedAt: number;\n}\nconst QMD_CACHE_TTL_MS = 60_000;\nconst qmdSearchCache = new Map<string, QmdCacheEntry>();\n\nexport function getCachedQmdSearch(cacheKey: string): unknown[] | null {\n  const entry = qmdSearchCache.get(cacheKey);\n  if (!entry) return null;\n  if (Date.now() - entry.cachedAt > QMD_CACHE_TTL_MS) {\n    qmdSearchCache.delete(cacheKey);\n    return null;\n  }\n  return entry.results;\n}\n\nexport function setCachedQmdSearch(cacheKey: string, results: unknown[]): void {\n  qmdSearchCache.set(cacheKey, { results, cachedAt: Date.now() });\n  // Evict old entries to prevent unbounded growth\n  if (qmdSearchCache.size > 200) {\n    const now = Date.now();\n    for (const [key, entry] of qmdSearchCache) {\n      if (now - entry.cachedAt > QMD_CACHE_TTL_MS) qmdSearchCache.delete(key);\n    }\n  }\n}\n\n/**\n * Mutation scopes (issue #1904). A cache layer declares (via `evictOn`) which\n * of these mutation kinds evict it, so the invalidation chokepoint can clear\n * only the layers a given write actually affects instead of nuking every\n * layer on every write (the permanently-cold-cache regression #1904 fixes).\n */\nexport type MemoryMutationScope =\n  | \"memory-create\" // a new memory doc added; no existing doc's recall-visibility changes\n  | \"memory-mutate\" // existing doc changed/moved/removed/status-changed (update, supersede,\n  //   archive, invalidate, frontmatter, cold-tier change, bulk delete)\n  | \"entity-write\" // an entity file changed\n  | \"secure-key-change\"; // encryption key rotated; everything is now unreadable → evict all\n\n/**\n * Cache-layer registry (issue #1535).\n *\n * EVERY process-level cache that can serve memory-derived content is\n * enumerated here, and the single invalidation chokepoint\n * (`invalidateAllForDir`) iterates this list. Adding a new cache layer to\n * this module (or qmd-recall-cache.ts) REQUIRES registering it here —\n * otherwise mutations will never invalidate it (the exact bug this registry\n * exists to prevent) and the enumerate-all-layers fitness test in\n * tests/cache-invalidation-coherence.test.ts fails.\n */\nexport interface MemoryCacheLayer {\n  /** Stable identifier used by tests and diagnostics. */\n  readonly name: string;\n  /** \"dir\" layers evict only entries for the given baseDir. \"global\" layers\n   *  are fully cleared on any mutation: their keys embed queries, namespaces,\n   *  and strategies rather than a storage dir, so a per-dir selective clear\n   *  is not possible without recording the dir in each entry. Full clear is\n   *  the simple-and-correct choice — these caches are re-warmable\n   *  (issue #1535, implementation guide option (b)). */\n  readonly scope: \"dir\" | \"global\";\n  /** Which mutation scopes evict this layer (issue #1904). A `memory-create`\n   *  only refreshes the full-memory-list views (hot + derived episode/rule); a\n   *  `memory-mutate`/`entity-write`/`secure-key-change` evicts every layer whose\n   *  content it can affect. Adding a layer REQUIRES declaring this. */\n  readonly evictOn: Partial<Record<MemoryMutationScope, true>>;\n  /** Evict entries for baseDir (\"dir\" scope) or everything (\"global\" scope). */\n  readonly invalidateForDir: (baseDir: string) => void;\n  /** Evict every entry across all dirs. */\n  readonly clearAll: () => void;\n  /** True when the layer still holds entries for baseDir (\"dir\" scope) or\n   *  any entries at all (\"global\" scope). */\n  readonly hasEntriesFor: (baseDir: string) => boolean;\n}\n\nexport const ALL_CACHE_LAYERS: readonly MemoryCacheLayer[] = [\n  {\n    name: \"hot-memories\",\n    scope: \"dir\",\n    evictOn: { \"memory-create\": true, \"memory-mutate\": true, \"secure-key-change\": true },\n    invalidateForDir: (baseDir) => void hotCacheByDir.delete(baseDir),\n    clearAll: () => hotCacheByDir.clear(),\n    hasEntriesFor: (baseDir) => hotCacheByDir.has(baseDir),\n  },\n  {\n    name: \"archive-memories\",\n    scope: \"dir\",\n    evictOn: { \"memory-mutate\": true, \"secure-key-change\": true },\n    invalidateForDir: (baseDir) => void archiveCacheByDir.delete(baseDir),\n    clearAll: () => archiveCacheByDir.clear(),\n    hasEntriesFor: (baseDir) => archiveCacheByDir.has(baseDir),\n  },\n  {\n    name: \"entities\",\n    scope: \"dir\",\n    evictOn: { \"entity-write\": true, \"secure-key-change\": true },\n    invalidateForDir: (baseDir) => invalidateCachedEntities(baseDir),\n    clearAll: () => entityCacheByDir.clear(),\n    hasEntriesFor: (baseDir) => {\n      const prefix = entityCacheKeyPrefix(baseDir);\n      for (const key of entityCacheByDir.keys()) {\n        if (key.startsWith(prefix)) return true;\n      }\n      return false;\n    },\n  },\n  {\n    name: \"derived-episode-map\",\n    scope: \"dir\",\n    evictOn: { \"memory-create\": true, \"memory-mutate\": true, \"secure-key-change\": true },\n    invalidateForDir: (baseDir) => void episodeMapByDir.delete(baseDir),\n    clearAll: () => episodeMapByDir.clear(),\n    hasEntriesFor: (baseDir) => episodeMapByDir.has(baseDir),\n  },\n  {\n    name: \"derived-rule-memories\",\n    scope: \"dir\",\n    evictOn: { \"memory-create\": true, \"memory-mutate\": true, \"secure-key-change\": true },\n    invalidateForDir: (baseDir) => void ruleMemoriesByDir.delete(baseDir),\n    clearAll: () => ruleMemoriesByDir.clear(),\n    hasEntriesFor: (baseDir) => ruleMemoriesByDir.has(baseDir),\n  },\n  {\n    name: \"qmd-search\",\n    scope: \"global\",\n    evictOn: { \"memory-mutate\": true, \"entity-write\": true, \"secure-key-change\": true },\n    invalidateForDir: () => qmdSearchCache.clear(),\n    clearAll: () => qmdSearchCache.clear(),\n    hasEntriesFor: () => qmdSearchCache.size > 0,\n  },\n  {\n    name: \"qmd-recall\",\n    scope: \"global\",\n    evictOn: { \"memory-mutate\": true, \"entity-write\": true, \"secure-key-change\": true },\n    invalidateForDir: () => clearQmdRecallCache(),\n    clearAll: () => clearQmdRecallCache(),\n    hasEntriesFor: () => qmdRecallCacheSize() > 0,\n  },\n];\n\n/**\n * The single invalidation chokepoint (issue #1535, rule 37).\n *\n * Every memory/entity mutation path must route through this function —\n * storage.ts calls it from its internal invalidation funnels\n * (invalidateAllMemoriesCache / invalidateColdMemoriesCache /\n * bumpMemoryStatusVersion / setSecureStoreKey). Nothing may clear an\n * individual layer ad hoc: partial clears are how the stale-recall bug\n * happened (qmdRecallCache was never invalidated on mutations, so recall\n * served pre-edit bundles for the remainder of its fresh/stale TTL window).\n */\nexport function invalidateAllForDir(baseDir: string): void {\n  for (const layer of ALL_CACHE_LAYERS) {\n    layer.invalidateForDir(baseDir);\n  }\n}\n\n/**\n * Scope-aware invalidation chokepoint (issue #1904). Evicts only the layers\n * whose `evictOn` includes `scope`, so the highest-frequency write\n * (`memory-create`, fired continuously by extraction) stops nuking the QMD\n * result caches and the version-keyed entity cache it cannot affect. This is\n * the single scoped entry point — like `invalidateAllForDir`, it iterates the\n * `ALL_CACHE_LAYERS` registry rather than clearing any layer ad hoc, so the\n * single-chokepoint invariant (#1535) holds: a new layer only participates by\n * declaring `evictOn`.\n */\nexport function invalidateForScope(baseDir: string, scope: MemoryMutationScope): void {\n  for (const layer of ALL_CACHE_LAYERS) {\n    if (layer.evictOn[scope]) layer.invalidateForDir(baseDir);\n  }\n}\n\n/**\n * Companion to {@link invalidateForScope} for the single-file write fast path\n * (issue #1902 + #1904): it patches the hot-memories entry in place and\n * re-keys it, so this evicts every OTHER layer the scope would clear but leaves\n * hot-memories alone. A `memory-create` thus evicts only the derived\n * episode/rule views (hot patched, QMD/entities/archive kept warm), which is\n * the whole point of #1904 — a create must not evict the QMD result caches.\n */\nexport function invalidateForScopeExceptHot(baseDir: string, scope: MemoryMutationScope): void {\n  for (const layer of ALL_CACHE_LAYERS) {\n    if (layer.name === \"hot-memories\") continue;\n    if (layer.evictOn[scope]) layer.invalidateForDir(baseDir);\n  }\n}\n\n/**\n * Invalidate every cache layer for `baseDir` EXCEPT the hot-memories layer\n * (issue #1902). Single-file write paths use this instead of\n * `invalidateAllForDir` because they patch the hot-memories entry in place\n * (via `updateCacheOnWrite`/`updateCacheOnDelete`) and re-key it to the bumped\n * version — so dropping it here would defeat the whole warm-cache fast path.\n * The derived episode/rule views and the global QMD caches are cheap to\n * rebuild and are not patched, so they are still evicted here. Every other\n * layer remains reachable for the wholesale `invalidateAllForDir` /\n * `clearMemoryCache` chokepoint used by bulk/ambiguous mutations.\n */\nexport function invalidateDerivedAndGlobalForDir(baseDir: string): void {\n  // Preserve the layers a single-file write intentionally keeps warm (issue\n  // #1902, Codex Medium): hot-memories is patched + re-keyed in place; the\n  // entities layer is keyed on memory-status, which plain create/content writes\n  // deliberately do NOT bump (so entity retrieval stays warm); and the\n  // archive-memories layer is version-keyed on the archive tier, untouched by a\n  // hot-tier write. Evict ONLY the derived (episode/rule) and global (QMD) views.\n  for (const layer of ALL_CACHE_LAYERS) {\n    if (\n      layer.name === \"hot-memories\" ||\n      layer.name === \"entities\" ||\n      layer.name === \"archive-memories\"\n    ) {\n      continue;\n    }\n    layer.invalidateForDir(baseDir);\n  }\n}\n\nexport function clearMemoryCache(baseDir?: string): void {\n  if (baseDir) {\n    invalidateAllForDir(baseDir);\n    return;\n  }\n  for (const layer of ALL_CACHE_LAYERS) {\n    layer.clearAll();\n  }\n}\n\n/**\n * Clear ONLY the two global QMD result caches (qmd-search + qmd-recall), leaving\n * every dir-scoped layer (hot/archive/entities/derived) untouched. Called after\n * a successful QMD maintenance update+embed (#1904, Codex): a newly-persisted\n * fact becomes searchable at that moment, so any cached pre-index recall/search\n * bundle is now stale and must not be served. This lets the create path keep the\n * QMD caches warm during index lag (perf win) while guaranteeing invalidation\n * the moment the fact is actually indexed — no extended stale window.\n */\nexport function clearQmdResultCaches(): void {\n  qmdSearchCache.clear();\n  clearQmdRecallCache();\n}\n\nexport function getMemoryCacheStats(baseDir: string): {\n  hotSize: number;\n  archiveSize: number;\n  hotVersion: number | null;\n  archiveVersion: number | null;\n} {\n  const hot = hotCacheByDir.get(baseDir);\n  const archive = archiveCacheByDir.get(baseDir);\n  return {\n    hotSize: hot?.memories.size ?? 0,\n    archiveSize: archive?.memories.size ?? 0,\n    hotVersion: hot?.version ?? null,\n    archiveVersion: archive?.version ?? null,\n  };\n}\n"],"mappings":"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","names":[]}