@remnic/core 10.0.83 → 10.0.85

package/dist/chunk-UDKWFDV2.js.map

@@ -0,0 +1 @@
+{"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   * Tombstone-blocked capture write-lock backoff (COS-392). These do not\n   * change the fact-hash index lock. Omitted fields use the 50ms / 2s / 60s\n   * defaults. Converge copies its config here before replicating a file.\n   */\n  readonly captureWriteLockInitialDelayMs?: number;\n  readonly captureWriteLockMaxDelayMs?: number;\n  readonly captureWriteLockDeadlineMs?: number;\n  /** Apply abort signal. Checked before each probe, during backoff, and before the write. */\n  readonly captureWriteLockSignal?: AbortSignal;\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\n/**\n * One dedup lookup: whether the shared index holds the hash, and whether that\n * answer can be trusted as a clean MISS. Both fields describe the same instant.\n */\nexport interface ContentHashLookup {\n  readonly present: boolean;\n  readonly authoritative: boolean;\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  /**\n   * Fact-ONLY hash partition (issue #2474). `hashes` above is category-blind\n   * (every write category registers there); this subset carries only\n   * `category === \"fact\"` hashes so fact-only membership checks\n   * (`hasFact*`) can never be satisfied by an unrelated decision/preference\n   * sharing the same normalized body. In-memory only — never serialized to\n   * fact-hashes.txt; `clear()` drops it and every authoritative rebuild\n   * repopulates it via `addFactByHash`. Subset invariant: `factHashes ⊆\n   * hashes` — `addFact*` registers in both, and the removal sites that drop\n   * a shared hash also drop the partition entry (removal stays caller-paired\n   * because shared-index removal is category-blind: archiving a non-fact\n   * must not evict an active fact's fact-only membership).\n   */\n  private factHashes: 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    // The fact-only partition is rebuilt with the shared set on every\n    // authoritative corpus rebuild, so it clears here too (issue #2474).\n    this.factHashes.clear();\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  // ── Fact-only partition (issue #2474) ─────────────────────────────────\n  // Folded here from StorageManager's parallel `factOnlyHashes` set, which had\n  // to be kept in lockstep by hand on every add/remove/rebuild site. The\n  // partition lives on the index instance, so every path that mutates the\n  // shared set and needs fact-only truth mutates it in the same breath.\n\n  /** Register fact content in BOTH the shared index and the fact-only partition. */\n  addFact(content: string): void {\n    this.addFactByHash(ContentHashIndex.computeHash(content));\n  }\n\n  /** Register a pre-computed fact hash in both the shared index and the fact-only partition. */\n  addFactByHash(hash: string): void {\n    this.addByHash(hash);\n    this.factHashes.add(hash);\n  }\n\n  /** Fact-ONLY membership: has this content been registered as a fact? */\n  hasFact(content: string): boolean {\n    return this.factHashes.has(ContentHashIndex.computeHash(content));\n  }\n\n  /** Fact-ONLY membership for a pre-computed SHA-256 hash. */\n  hasFactByHash(hash: string): boolean {\n    return this.factHashes.has(hash);\n  }\n\n  /**\n   * Drop fact-only partition membership WITHOUT touching the shared index.\n   * The shared removal stays caller-owned: a shared hash is dropped only when\n   * no other active memory holds it, while fact-only membership follows the\n   * fact's own lifecycle (supersede/archive/promotion).\n   */\n  removeFactByHash(hash: string): void {\n    this.factHashes.delete(hash);\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-HQPFACXO.js → chunk-UH3FPX3L.js}

@@ -1,7 +1,7 @@
 import {
   graphFilePath,
   readEdgesStrict
-} from "./chunk-BFBS7OFQ.js";
+} from "./chunk-DC55RIEZ.js";
 import {
   assertGraphLockHeld,
   withGraphWriteLock,
@@ -138,4 +138,4 @@ export {
   restoreRemovedNodeEdges,
   rollbackNodeEdgeRewrite
 };
-//# sourceMappingURL=chunk-HQPFACXO.js.map
+//# sourceMappingURL=chunk-UH3FPX3L.js.map

package/dist/{chunk-4EACCIPO.js → chunk-UHPHH74F.js}

@@ -4,7 +4,7 @@ import {
 import {
   computeCorpusWatermarks,
   resolveCorpusNamespaceRoots
-} from "./chunk-TFLPDNQV.js";
+} from "./chunk-CCU7URRP.js";
 
 // src/operator-doctor-corpus.ts
 var DIGEST_PREFIX_LENGTH = 12;
@@ -78,4 +78,4 @@ export {
   corpusWatermarksFromCheck,
   summarizeCorpusAndReplica
 };
-//# sourceMappingURL=chunk-4EACCIPO.js.map
+//# sourceMappingURL=chunk-UHPHH74F.js.map

package/dist/{chunk-DQEMWVMT.js → chunk-UVYI6VIX.js}

@@ -246,4 +246,4 @@ export {
   decryptCapsuleFile,
   decryptCapsuleFileInMemory
 };
-//# sourceMappingURL=chunk-DQEMWVMT.js.map
+//# sourceMappingURL=chunk-UVYI6VIX.js.map

package/dist/{chunk-6QYPL6NI.js → chunk-V45TEVDA.js}

@@ -1,9 +1,9 @@
 import {
   hasMemoryData
-} from "./chunk-WV254W4V.js";
+} from "./chunk-Y3IYKNBY.js";
 import {
   resolveNamespaceStorageRoot
-} from "./chunk-KESJ5XX3.js";
+} from "./chunk-MYCCO6AA.js";
 import {
   getConfiguredNamespaces
 } from "./chunk-I6QGI65T.js";
@@ -726,4 +726,4 @@ export {
   runNamespaceMaintenancePlan,
   runNamespaceMaintenanceBatchPlan
 };
-//# sourceMappingURL=chunk-6QYPL6NI.js.map
+//# sourceMappingURL=chunk-V45TEVDA.js.map

package/dist/{chunk-GCAQ3VUJ.js → chunk-VCVEMQJK.js}

@@ -1,6 +1,6 @@
 import {
   StorageManager
-} from "./chunk-WAD32CZG.js";
+} from "./chunk-ELWI2R6H.js";
 import {
   bumpMemoryCorpusVersionForDir
 } from "./chunk-M5GVCJSJ.js";
@@ -769,4 +769,4 @@ export {
   listMemoryGovernanceRuns,
   readMemoryGovernanceRunArtifact
 };
-//# sourceMappingURL=chunk-GCAQ3VUJ.js.map
+//# sourceMappingURL=chunk-VCVEMQJK.js.map

package/dist/{chunk-6L63IN3M.js → chunk-VEFGHRKV.js}

@@ -400,4 +400,4 @@ export {
   getCausalTrajectoryStoreStatus,
   searchCausalTrajectories
 };
-//# sourceMappingURL=chunk-6L63IN3M.js.map
+//# sourceMappingURL=chunk-VEFGHRKV.js.map

package/dist/{chunk-E33UJHY3.js → chunk-WFDWLWDK.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-AJG2TAMR.js";
 import {
   deepRecallRequestSchema
-} from "./chunk-HWHNQVRV.js";
+} from "./chunk-GYNRNKMW.js";
 import {
   EngramAccessInputError
 } from "./chunk-LGEH473S.js";
@@ -40,4 +40,4 @@ async function respondDeepRecall(req, res, respondJson, readJsonBody, service, s
 export {
   respondDeepRecall
 };
-//# sourceMappingURL=chunk-E33UJHY3.js.map
+//# sourceMappingURL=chunk-WFDWLWDK.js.map

package/dist/{chunk-4KLQI3L2.js → chunk-WLNWFHX3.js}

@@ -261,4 +261,4 @@ export {
   ProbeTimeoutError,
   probeWithTimeout
 };
-//# sourceMappingURL=chunk-4KLQI3L2.js.map
+//# sourceMappingURL=chunk-WLNWFHX3.js.map

package/dist/chunk-WLNWFHX3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/buffer-turn-helpers.ts"],"sourcesContent":["import type { BufferEntryState, BufferState, BufferTurn } from \"./types.js\";\n\n/** Extracted identities retain whether they came from active or retained turns. */\nexport interface DrainedTurnSets {\n  turns: BufferTurn[];\n  retainedTurns: BufferTurn[];\n}\n\nexport interface BufferTurnOwner {\n  /**\n   * Server-resolved principal that owns this session at the authenticated\n   * observe/write boundary. Persisted with the buffered turn so lifecycle\n   * flushes do not have to infer ownership from a client-chosen session key.\n   */\n  sessionOwnerPrincipal?: string;\n}\n\nexport interface AmbientCaptureProvenance {\n  /**\n   * True when this turn's content came from an always-on ambient capture\n   * device (a wearable recorder, a room microphone) and may therefore carry\n   * speech the user never authored: TV, podcasts, music, overheard\n   * conversation (issue #2294). Set by the ingesting subsystem, never from\n   * tool arguments — extraction reads it to warn the model about media audio\n   * and to clamp high-impact personal facts to the speculative tier.\n   */\n  ambientCapture?: boolean;\n}\n\nexport function describeError(err: unknown): string {\n  if (err instanceof Error) return err.message;\n  if (err === null) return \"null\";\n  if (err === undefined) return \"undefined\";\n  if (typeof err === \"string\") return err;\n  try {\n    return JSON.stringify(err);\n  } catch {\n    return String(err);\n  }\n}\n\nexport function copyBufferTurn(turn: BufferTurn): BufferTurn {\n  const copy: BufferTurn = {\n    role: turn.role,\n    content: turn.content,\n    timestamp: turn.timestamp,\n  };\n  if (typeof turn.sessionKey === \"string\") copy.sessionKey = turn.sessionKey;\n  if (typeof turn.logicalSessionKey === \"string\") {\n    copy.logicalSessionKey = turn.logicalSessionKey;\n  }\n  if (turn.providerThreadId === null || typeof turn.providerThreadId === \"string\") {\n    copy.providerThreadId = turn.providerThreadId;\n  }\n  if (typeof turn.sessionOwnerPrincipal === \"string\") {\n    copy.sessionOwnerPrincipal = turn.sessionOwnerPrincipal;\n  }\n  if (typeof turn.turnFingerprint === \"string\") {\n    copy.turnFingerprint = turn.turnFingerprint;\n  }\n  if (typeof turn.persistProcessedFingerprint === \"boolean\") {\n    copy.persistProcessedFingerprint = turn.persistProcessedFingerprint;\n  }\n  if (typeof turn.sourceConnector === \"string\") {\n    copy.sourceConnector = turn.sourceConnector;\n  }\n  if (turn.originRole === \"user\" || turn.originRole === \"assistant\" || turn.originRole === \"tool\") {\n    copy.originRole = turn.originRole;\n  }\n  if (typeof turn.ambientCapture === \"boolean\") {\n    copy.ambientCapture = turn.ambientCapture;\n  }\n  if (turn.sourceValidAt !== undefined) {\n    copy.sourceValidAt = turn.sourceValidAt;\n  }\n  if (turn.parts !== undefined) {\n    copy.parts = turn.parts;\n  }\n  if (turn.rawContent !== undefined) {\n    copy.rawContent = turn.rawContent;\n  }\n  if (turn.sourceFormat !== undefined) {\n    copy.sourceFormat = turn.sourceFormat;\n  }\n  // #3251 scope pins: strings copy by value; the plan object is an immutable\n  // config-derived identity passed by reference.\n  if (turn.writeNamespaceOverride !== undefined) {\n    copy.writeNamespaceOverride = turn.writeNamespaceOverride;\n  }\n  if (turn.principalOverride !== undefined) {\n    copy.principalOverride = turn.principalOverride;\n  }\n  if (turn.scopeProfileWritePlan !== undefined) {\n    copy.scopeProfileWritePlan = turn.scopeProfileWritePlan;\n  }\n  if (turn.acceptedCapture === true) {\n    copy.acceptedCapture = true;\n  }\n  const ctx = turn.codingContext;\n  if (ctx) {\n    // All four fields are identity inputs (branchScope uses branch) — copy\n    // explicitly as-is; never a spread of external input.\n    copy.codingContext = {\n      projectId: ctx.projectId,\n      branch: ctx.branch,\n      rootPath: ctx.rootPath,\n      defaultBranch: ctx.defaultBranch,\n    };\n  }\n  return copy;\n}\n\n/**\n * Remove the turns that a drain already extracted (`drained`) from `turns`.\n * Identity-based (role/content/timestamp/session/...): the same comparison\n * the buffer uses to match live turns, so a stale owner can subtract exactly\n * what the drain took and keep everything else.\n */\nexport function subtractBufferTurns(turns: readonly BufferTurn[], drained: readonly BufferTurn[]): BufferTurn[] {\n  if (drained.length === 0) return [...turns];\n  const kept = [...turns];\n  for (const gone of drained) {\n    const at = kept.findIndex((live) => bufferTurnsEqual(live, gone));\n    if (at >= 0) kept.splice(at, 1);\n  }\n  return kept;\n}\n\n/** Per-key pending counts over the IN-MEMORY buffer state (counts only — no\n *  turn payloads). The claim store's answer stays authoritative for claimed\n *  keys; callers must filter through `BufferDrainClaims.isClaimed` before\n *  treating a count here as work. */\nexport interface BufferEntryCounts {\n  turns: number;\n  retainedTurns: number;\n}\n\nexport function bufferEntryCounts(state: BufferState): Map<string, BufferEntryCounts> {\n  const out = new Map<string, BufferEntryCounts>();\n  const entries = state.entries;\n  if (!entries) return out;\n  for (const [key, entry] of Object.entries(entries)) {\n    out.set(key, { turns: entry.turns.length, retainedTurns: entry.retainedTurns?.length ?? 0 });\n  }\n  return out;\n}\n\nexport function bufferTurnsEqual(left: BufferTurn | undefined, right: BufferTurn): boolean {\n  if (!left) return false;\n  return (\n    left.role === right.role &&\n    left.content === right.content &&\n    left.timestamp === right.timestamp &&\n    left.sessionKey === right.sessionKey &&\n    left.sessionOwnerPrincipal === right.sessionOwnerPrincipal &&\n    left.logicalSessionKey === right.logicalSessionKey &&\n    left.providerThreadId === right.providerThreadId &&\n    left.turnFingerprint === right.turnFingerprint &&\n    left.persistProcessedFingerprint === right.persistProcessedFingerprint &&\n    left.sourceConnector === right.sourceConnector &&\n    left.originRole === right.originRole &&\n    left.ambientCapture === right.ambientCapture &&\n    left.sourceValidAt === right.sourceValidAt &&\n    left.acceptedCapture === right.acceptedCapture &&\n    left.codingContext?.projectId === right.codingContext?.projectId &&\n    left.codingContext?.rootPath === right.codingContext?.rootPath &&\n    left.codingContext?.branch === right.codingContext?.branch &&\n    left.codingContext?.defaultBranch === right.codingContext?.defaultBranch &&\n    // #3251 scope pins compare by identity triple, not deep plan equality: a\n    // restart-rehydrated plan must still match the pin it was accepted under.\n    left.writeNamespaceOverride === right.writeNamespaceOverride &&\n    left.principalOverride === right.principalOverride &&\n    scopeProfilePlanIdentity(left.scopeProfileWritePlan) ===\n      scopeProfilePlanIdentity(right.scopeProfileWritePlan)\n  );\n}\n\n/**\n * Canonical identity key for a turn, injective over `bufferTurnsEqual`\n * equality classes. Every compared field is a primitive (or the #3251 plan\n * identity string), so set-membership replaces pairwise comparison and turn\n * merges run O(n + m) instead of O(n × m). JSON.stringify of a string is\n * injective (it escapes control characters), and the raw `\\u0001` sentinels\n * distinguish undefined from null — a distinction `===` makes and plain\n * stringification would lose.\n */\nexport function bufferTurnIdentityKey(turn: BufferTurn): string {\n  const opt = (value: string | null | undefined): string =>\n    value === undefined ? \"\\u0001undefined\" : value === null ? \"\\u0001null\" : JSON.stringify(value);\n  const optFlag = (value: boolean | undefined): string =>\n    value === undefined ? \"\\u0001undefined\" : String(value);\n  const ctx = turn.codingContext;\n  return JSON.stringify([\n    turn.role,\n    turn.content,\n    turn.timestamp,\n    opt(turn.sessionKey),\n    opt(turn.sessionOwnerPrincipal),\n    opt(turn.logicalSessionKey),\n    turn.providerThreadId === undefined ? \"\\u0001undefined\" : turn.providerThreadId === null ? \"\\u0001null\" : JSON.stringify(turn.providerThreadId),\n    opt(turn.turnFingerprint),\n    optFlag(turn.persistProcessedFingerprint),\n    opt(turn.sourceConnector),\n    opt(turn.originRole),\n    optFlag(turn.ambientCapture),\n    opt(turn.sourceValidAt),\n    optFlag(turn.acceptedCapture),\n    opt(ctx?.projectId),\n    opt(ctx?.rootPath),\n    opt(ctx?.branch),\n    opt(ctx?.defaultBranch),\n    opt(turn.writeNamespaceOverride),\n    opt(turn.principalOverride),\n    opt(turn.scopeProfileWritePlan ? scopeProfilePlanIdentity(turn.scopeProfileWritePlan) : undefined),\n  ]);\n}\n\n/**\n * Identity-dedupe `incoming` turns into `existing` (same contract as the\n * claim-merge `mergeTurns`): identical turns are dropped — the EXISTING\n * entry is kept — genuinely-new turns append in arrival order, and\n * duplicates within `incoming` collapse to their first occurrence. O(n + m)\n * via `bufferTurnIdentityKey` membership instead of pairwise equality.\n */\nexport function mergeBufferTurnsByIdentity(\n  existing: readonly BufferTurn[],\n  incoming: readonly BufferTurn[],\n): BufferTurn[] {\n  const merged = [...existing];\n  const seen = new Set(merged.map(bufferTurnIdentityKey));\n  for (const turn of incoming) {\n    const key = bufferTurnIdentityKey(turn);\n    if (seen.has(key)) continue;\n    seen.add(key);\n    merged.push(turn);\n  }\n  return merged;\n}\n\n/** Replace only the processed snapshot; callers without one retain legacy whole-slot semantics. */\nexport function selectRetainedDeferredTurns(\n  existing: readonly BufferTurn[],\n  turns: BufferTurn[],\n  max: number,\n  originalTurns?: readonly BufferTurn[],\n): BufferTurn[] {\n  const others = originalTurns === undefined ? [] : existing.filter(\n    (turn) => !originalTurns.some((original) => bufferTurnsEqual(turn, original)),\n  );\n  if (!Array.isArray(turns) || max <= 0) return others;\n  return [...others, ...turns.slice(-max).map(copyBufferTurn)];\n}\n\nexport function hasPinnedCaptureScope(turn: BufferTurn): boolean {\n  return turn.acceptedCapture === true ||\n    turn.writeNamespaceOverride !== undefined ||\n    turn.scopeProfileWritePlan !== undefined;\n}\n\n/** Stable identity string for a pinned scope-profile plan (#3251). */\nexport function scopeProfilePlanIdentity(\n  plan: BufferTurn[\"scopeProfileWritePlan\"],\n): string {\n  if (!plan) return \"\";\n  return `${plan.profileId}\\u0000${plan.writeLayer}\\u0000${plan.writeNamespace}`;\n}\n\nexport interface ExtractionScopeGroup {\n  writeNamespaceOverride?: string;\n  principalOverride?: string;\n  scopeProfileWritePlan?: BufferTurn[\"scopeProfileWritePlan\"];\n  codingContext?: BufferTurn[\"codingContext\"];\n  turns: BufferTurn[];\n}\n\n/**\n * Partition extraction turns by their durable scope pins (#3251). Turns\n * captured under different namespaces / principals / scope profiles /\n * project bindings must never be extracted together — each group runs its\n * own extraction under its own scope. Native (unpinned) turns form their own\n * group and keep today's single-store routing.\n */\nexport function groupTurnsByExtractionScope(turns: BufferTurn[]): ExtractionScopeGroup[] {\n  const groups = new Map<string, ExtractionScopeGroup>();\n  for (const turn of turns) {\n    const key = [\n      turn.writeNamespaceOverride ?? \"\",\n      turn.principalOverride ?? \"\",\n      scopeProfilePlanIdentity(turn.scopeProfileWritePlan),\n      // Accepted captures are deliberately accepted content: they must never\n      // share a scope group with ordinary turns, or a group-level capture\n      // policy (the explicit-mode gate, the planless-accepted null pin) is\n      // applied to ordinary conversation turns because `.some(acceptedCapture)`\n      // only looked at the merged group.\n      turn.acceptedCapture === true ? \"accepted\" : \"\",\n      turn.codingContext?.projectId ?? \"\",\n      turn.codingContext?.rootPath ?? \"\",\n      turn.codingContext?.branch ?? \"\",\n      turn.codingContext?.defaultBranch ?? \"\",\n    ].join(\"\\u0000\");\n    const group = groups.get(key);\n    if (group) {\n      group.turns.push(turn);\n    } else {\n      const created: ExtractionScopeGroup = { turns: [turn] };\n      if (turn.writeNamespaceOverride !== undefined) created.writeNamespaceOverride = turn.writeNamespaceOverride;\n      if (turn.principalOverride !== undefined) created.principalOverride = turn.principalOverride;\n      if (turn.scopeProfileWritePlan !== undefined) created.scopeProfileWritePlan = turn.scopeProfileWritePlan;\n      if (turn.codingContext !== undefined) created.codingContext = turn.codingContext;\n      groups.set(key, created);\n    }\n  }\n  return [...groups.values()];\n}\n\nexport function bufferTurnArraysEqual(\n  left: readonly BufferTurn[],\n  right: readonly BufferTurn[],\n): boolean {\n  return left.length === right.length && left.every((turn, index) => bufferTurnsEqual(turn, right[index]));\n}\n\nexport function bufferTurnArrayIsSuffixOfSnapshot(\n  liveTurns: readonly BufferTurn[],\n  snapshot: readonly BufferTurn[],\n): boolean {\n  if (liveTurns.length === 0 || liveTurns.length > snapshot.length) {\n    return false;\n  }\n  const offset = snapshot.length - liveTurns.length;\n  return liveTurns.every((turn, index) => bufferTurnsEqual(turn, snapshot[offset + index]));\n}\n\nexport function liveTurnsFromExtractionSnapshot(\n  entry: BufferEntryState,\n  extractedTurns: readonly BufferTurn[],\n): readonly BufferTurn[] {\n  const retainedTurns = entry.retainedTurns ?? [];\n  if (\n    retainedTurns.length > 0 &&\n    extractedTurns.length >= retainedTurns.length &&\n    retainedTurns.every((turn, index) => bufferTurnsEqual(extractedTurns[index], turn))\n  ) {\n    const withoutRetainedPrefix = extractedTurns.slice(retainedTurns.length);\n    if (withoutRetainedPrefix.length > 0 && matchingPrefixLength(entry.turns, withoutRetainedPrefix) > 0) {\n      return withoutRetainedPrefix;\n    }\n  }\n  return extractedTurns;\n}\n\nfunction matchingPrefixLength(\n  liveTurns: readonly BufferTurn[],\n  extractedTurns: readonly BufferTurn[],\n): number {\n  let index = 0;\n  while (\n    index < liveTurns.length &&\n    index < extractedTurns.length &&\n    bufferTurnsEqual(liveTurns[index], extractedTurns[index])\n  ) {\n    index += 1;\n  }\n  return index;\n}\n\nexport function matchingQueuedExtractionPrefixLength(\n  liveTurns: readonly BufferTurn[],\n  extractedTurns: readonly BufferTurn[],\n): number {\n  let bestMatchedCount = 0;\n  for (let start = 0; start < extractedTurns.length; start += 1) {\n    const matchedCount = matchingPrefixLength(liveTurns, extractedTurns.slice(start));\n    if (matchedCount > bestMatchedCount) {\n      bestMatchedCount = matchedCount;\n      if (bestMatchedCount === liveTurns.length) break;\n    }\n  }\n  return bestMatchedCount;\n}\n\nexport class ProbeTimeoutError extends Error {\n  constructor(timeoutMs: number) {\n    super(`probe exceeded ${timeoutMs}ms`);\n    this.name = \"ProbeTimeoutError\";\n  }\n}\n\nexport function probeWithTimeout<T>(inflight: Promise<T>, timeoutMs: number): Promise<T> {\n  let timer: NodeJS.Timeout | null = null;\n  const timeout = new Promise<T>((_, reject) => {\n    timer = setTimeout(() => reject(new ProbeTimeoutError(timeoutMs)), timeoutMs);\n    if (typeof (timer as NodeJS.Timeout).unref === \"function\") {\n      (timer as NodeJS.Timeout).unref();\n    }\n  });\n  return Promise.race([inflight, timeout]).finally(() => {\n    if (timer) clearTimeout(timer);\n  });\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-KQLBXUUQ.js → chunk-WYG5UNDY.js}

@@ -5,7 +5,7 @@ import {
 import {
   PROMOTION_CANDIDATES_DEFAULT_MIN_ACCESS,
   isSubjectGuardMode
-} from "./chunk-IZJQNDGI.js";
+} from "./chunk-R6HMAIKM.js";
 
 // src/subject-config.ts
 function assertObjectBlock(value, key, shape) {
@@ -52,4 +52,4 @@ function parseSubjectRuntimeConfig(cfg) {
 export {
   parseSubjectRuntimeConfig
 };
-//# sourceMappingURL=chunk-KQLBXUUQ.js.map
+//# sourceMappingURL=chunk-WYG5UNDY.js.map

package/dist/{chunk-MPGLM2VU.js → chunk-X7REO4CH.js}

@@ -1,6 +1,6 @@
 import {
   defineOperation
-} from "./chunk-6LCWKS62.js";
+} from "./chunk-HVFX2N2G.js";
 import {
   EngramAccessInputError
 } from "./chunk-LGEH473S.js";
@@ -92,4 +92,4 @@ defineOperation({
     };
   }
 });
-//# sourceMappingURL=chunk-MPGLM2VU.js.map
+//# sourceMappingURL=chunk-X7REO4CH.js.map

package/dist/{chunk-MPDLLLOG.js → chunk-XO23OKMK.js}

@@ -27,17 +27,19 @@ var BufferSessionPersistence = class {
    * exposure as a whole-file rewrite), never drop sessions the state says
    * exist.
    */
-  async persist(storage, state, peekEntry) {
+  async persist(storage, state, peekEntry, reconcile) {
+    const drainedTurns = new Map(
+      reconcile ? [[reconcile.key, reconcile.drained]] : []
+    );
     const saveSession = storage.saveBufferSession?.bind(storage);
     const deleteSession = storage.deleteBufferSession?.bind(storage);
     if (!saveSession || !deleteSession) {
       await storage.saveBuffer(state);
       this.dirty.clear();
       this.deleted.clear();
-      return { handedOver: [], drainedTurns: /* @__PURE__ */ new Map() };
+      return { handedOver: [], drainedTurns };
     }
     const handedOver = [];
-    const drainedTurns = /* @__PURE__ */ new Map();
     for (const key of [...this.deleted]) {
       await deleteSession(key);
       this.deleted.delete(key);
@@ -51,7 +53,9 @@ var BufferSessionPersistence = class {
       const outcome = await saveSession(key, entry);
       this.dirty.delete(key);
       if (outcome?.status === "handed_over") handedOver.push(key);
-      if (outcome?.drainedTurns && outcome.drainedTurns.length > 0) drainedTurns.set(key, outcome.drainedTurns);
+      if (outcome?.drainedTurns && (outcome.drainedTurns.turns.length > 0 || outcome.drainedTurns.retainedTurns.length > 0)) {
+        drainedTurns.set(key, outcome.drainedTurns);
+      }
     }
     return { handedOver, drainedTurns };
   }
@@ -60,4 +64,4 @@ var BufferSessionPersistence = class {
 export {
   BufferSessionPersistence
 };
-//# sourceMappingURL=chunk-MPDLLLOG.js.map
+//# sourceMappingURL=chunk-XO23OKMK.js.map

package/dist/chunk-XO23OKMK.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/buffer-persistence.ts"],"sourcesContent":["import type { DrainedTurnSets } from \"./buffer-turn-helpers.js\";\nimport type { BufferEntryState, BufferState, BufferSurpriseEvent } from \"./types.js\";\nimport type { BufferSessionSaveOutcome } from \"./storage/buffer-drain-claims.js\";\n\n/**\n * The buffer persistence surface SmartBuffer depends on.\n *\n * `saveBufferSession` / `deleteBufferSession` are the per-session incremental\n * writes (one file per session); when a storage backend does not provide\n * them, the buffer falls back to the whole-state `saveBuffer`. Both are\n * optional in the type so a storage double only has to implement what it\n * actually supports.\n */\nexport interface BufferStorage {\n  loadBuffer(): Promise<BufferState>;\n  saveBuffer(state: BufferState): Promise<void>;\n  /** Reports \"handed_over\" when the session is claimed by `remnic buffer drain` and the entry moved into the claim instead of a session file. Legacy doubles may return void (treated as \"saved\"). */\n  saveBufferSession?(key: string, entry: BufferEntryState): Promise<BufferSessionSaveOutcome | void>;\n  deleteBufferSession?(key: string): Promise<void>;\n  /** Sync claim check for the extraction gate; omitted when the backend has no drain-claim store. */\n  isBufferSessionClaimed?(key: string): boolean;\n  /** Optional surprise-telemetry sink; older storage and test doubles omit it. */\n  appendBufferSurpriseEvents?(events: BufferSurpriseEvent[]): Promise<number>;\n}\n\n/** What one persist pass changed beyond plain writes. */\nexport interface BufferPersistOutcome {\n  /** Sessions whose in-memory entry moved into a drain claim: the caller must evict them (a claimed session no longer lives in this process). */\n  handedOver: string[];\n  /** Per session, the turns a drain extracted, kept in their original lists. */\n  drainedTurns: Map<string, DrainedTurnSets>;\n}\n\n/**\n * Tracks which sessions' persisted files are stale and writes only those.\n *\n * Marks are cleared only after a durable write of that session. All calls\n * happen under SmartBuffer's serialized mutation chain: one writer.\n */\nexport class BufferSessionPersistence {\n  private readonly dirty = new Set<string>();\n  private readonly deleted = new Set<string>();\n\n  markDirty(key: string): void {\n    this.dirty.add(key);\n    this.deleted.delete(key);\n  }\n\n  markDeleted(key: string): void {\n    this.deleted.add(key);\n    this.dirty.delete(key);\n  }\n\n  /** Eviction removed `key` from memory: its session file must go, any pending write is moot. */\n  markEvicted(keys: readonly string[]): void {\n    for (const key of keys) this.markDeleted(key);\n  }\n\n  hasPending(): boolean {\n    return this.dirty.size > 0 || this.deleted.size > 0;\n  }\n\n  /**\n   * Persist buffer state. On session-capable storage this writes ONLY the\n   * sessions whose state changed since the last successful persist and\n   * deletes files for evicted/reset sessions, so the observe path never\n   * re-serializes other sessions' turns. On legacy storage it falls back to\n   * the whole-state saveBuffer. Files are deleted before dirty writes: a\n   * crash mid-persist can then only resurrect already-evicted data (the same\n   * exposure as a whole-file rewrite), never drop sessions the state says\n   * exist.\n   */\n  async persist(\n    storage: BufferStorage,\n    state: BufferState,\n    peekEntry: (key: string) => BufferEntryState | undefined,\n    reconcile?: { key: string; drained: DrainedTurnSets },\n  ): Promise<BufferPersistOutcome> {\n    const drainedTurns = new Map<string, DrainedTurnSets>(\n      reconcile ? [[reconcile.key, reconcile.drained]] : [],\n    );\n    const saveSession = storage.saveBufferSession?.bind(storage);\n    const deleteSession = storage.deleteBufferSession?.bind(storage);\n    if (!saveSession || !deleteSession) {\n      await storage.saveBuffer(state);\n      this.dirty.clear();\n      this.deleted.clear();\n      return { handedOver: [], drainedTurns };\n    }\n    const handedOver: string[] = [];\n    for (const key of [...this.deleted]) {\n      await deleteSession(key);\n      this.deleted.delete(key);\n    }\n    for (const key of [...this.dirty]) {\n      const entry = peekEntry(key);\n      if (!entry) {\n        // A dirty key without state must not be written from a fabricated\n        // empty entry: treat it as a deletion instead.\n        this.markDeleted(key);\n        continue;\n      }\n      const outcome = await saveSession(key, entry);\n      this.dirty.delete(key);\n      // \"handed_over\": the entry moved into a drain claim. Content is durable\n      // in the claim, so this key's pending state is settled — the caller\n      // evicts the in-memory entry on its side.\n      if (outcome?.status === \"handed_over\") handedOver.push(key);\n      // A drain tombstone: the turns it extracted must leave this process's\n      // copy too, or the owner would extract them a second time.\n      if (\n        outcome?.drainedTurns &&\n        (outcome.drainedTurns.turns.length > 0 || outcome.drainedTurns.retainedTurns.length > 0)\n      ) {\n        drainedTurns.set(key, outcome.drainedTurns);\n      }\n    }\n    return { handedOver, drainedTurns };\n  }\n}\n"],"mappings":";AAuCO,IAAM,2BAAN,MAA+B;AAAA,EACnB,QAAQ,oBAAI,IAAY;AAAA,EACxB,UAAU,oBAAI,IAAY;AAAA,EAE3C,UAAU,KAAmB;AAC3B,SAAK,MAAM,IAAI,GAAG;AAClB,SAAK,QAAQ,OAAO,GAAG;AAAA,EACzB;AAAA,EAEA,YAAY,KAAmB;AAC7B,SAAK,QAAQ,IAAI,GAAG;AACpB,SAAK,MAAM,OAAO,GAAG;AAAA,EACvB;AAAA;AAAA,EAGA,YAAY,MAA+B;AACzC,eAAW,OAAO,KAAM,MAAK,YAAY,GAAG;AAAA,EAC9C;AAAA,EAEA,aAAsB;AACpB,WAAO,KAAK,MAAM,OAAO,KAAK,KAAK,QAAQ,OAAO;AAAA,EACpD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,MAAM,QACJ,SACA,OACA,WACA,WAC+B;AAC/B,UAAM,eAAe,IAAI;AAAA,MACvB,YAAY,CAAC,CAAC,UAAU,KAAK,UAAU,OAAO,CAAC,IAAI,CAAC;AAAA,IACtD;AACA,UAAM,cAAc,QAAQ,mBAAmB,KAAK,OAAO;AAC3D,UAAM,gBAAgB,QAAQ,qBAAqB,KAAK,OAAO;AAC/D,QAAI,CAAC,eAAe,CAAC,eAAe;AAClC,YAAM,QAAQ,WAAW,KAAK;AAC9B,WAAK,MAAM,MAAM;AACjB,WAAK,QAAQ,MAAM;AACnB,aAAO,EAAE,YAAY,CAAC,GAAG,aAAa;AAAA,IACxC;AACA,UAAM,aAAuB,CAAC;AAC9B,eAAW,OAAO,CAAC,GAAG,KAAK,OAAO,GAAG;AACnC,YAAM,cAAc,GAAG;AACvB,WAAK,QAAQ,OAAO,GAAG;AAAA,IACzB;AACA,eAAW,OAAO,CAAC,GAAG,KAAK,KAAK,GAAG;AACjC,YAAM,QAAQ,UAAU,GAAG;AAC3B,UAAI,CAAC,OAAO;AAGV,aAAK,YAAY,GAAG;AACpB;AAAA,MACF;AACA,YAAM,UAAU,MAAM,YAAY,KAAK,KAAK;AAC5C,WAAK,MAAM,OAAO,GAAG;AAIrB,UAAI,SAAS,WAAW,cAAe,YAAW,KAAK,GAAG;AAG1D,UACE,SAAS,iBACR,QAAQ,aAAa,MAAM,SAAS,KAAK,QAAQ,aAAa,cAAc,SAAS,IACtF;AACA,qBAAa,IAAI,KAAK,QAAQ,YAAY;AAAA,MAC5C;AAAA,IACF;AACA,WAAO,EAAE,YAAY,aAAa;AAAA,EACpC;AACF;","names":[]}

package/dist/{chunk-Z3DDQXM4.js → chunk-XSFQN7TP.js}

@@ -1,12 +1,12 @@
 import {
   RECALL_NAVIGATION_MCP_TOOLS
 } from "./chunk-TE6S7KDF.js";
-import {
-  MEMORY_BROWSE_MCP_TOOLS
-} from "./chunk-EIB4FJVR.js";
 import {
   MCP_READ_ONLY_TOOL_SUFFIXES
 } from "./chunk-MZUQVWVC.js";
+import {
+  MEMORY_BROWSE_MCP_TOOLS
+} from "./chunk-EIB4FJVR.js";
 import {
   EXTERNAL_WIKI_MCP_TOOLS
 } from "./chunk-A5KNZSNA.js";
@@ -16,15 +16,18 @@ import {
 import {
   buildCitationGuidance
 } from "./chunk-D24OXEPB.js";
-import {
-  RECALL_WHY_MCP_TOOLS
-} from "./chunk-ZXF3O7P4.js";
 import {
   REMNIC_CHATGPT_MEMORY_INSPECTOR_MIME_TYPE,
   REMNIC_CHATGPT_MEMORY_INSPECTOR_TOOL,
   REMNIC_CHATGPT_MEMORY_INSPECTOR_WIDGET_HTML,
   REMNIC_CHATGPT_MEMORY_INSPECTOR_WIDGET_URI
 } from "./chunk-E4RMZGRS.js";
+import {
+  RECALL_WHY_MCP_TOOLS
+} from "./chunk-ZXF3O7P4.js";
+import {
+  McpFrameReader
+} from "./chunk-IGLJNHOX.js";
 import {
   applyToolOutputSchemas
 } from "./chunk-2FLFJTCI.js";
@@ -49,16 +52,16 @@ import {
 } from "./chunk-KIUVEMBI.js";
 import {
   getOperation
-} from "./chunk-6LCWKS62.js";
+} from "./chunk-HVFX2N2G.js";
 import {
   WHO_KNOWS_MCP_TOOLS
-} from "./chunk-FUOAIJKQ.js";
+} from "./chunk-Y43X3E24.js";
 import {
   PROMOTION_CANDIDATES_MCP_TOOLS
-} from "./chunk-IZJQNDGI.js";
+} from "./chunk-R6HMAIKM.js";
 import {
   validateRequest
-} from "./chunk-HWHNQVRV.js";
+} from "./chunk-GYNRNKMW.js";
 import {
   assertOperationAllowed,
   capabilityAllowsOp,
@@ -72,6 +75,7 @@ import {
   readEnvVar
 } from "./chunk-P2QRMMVQ.js";
 import {
+  EngramAccessForbiddenError,
   EngramAccessInputError,
   unknownToolError
 } from "./chunk-LGEH473S.js";
@@ -79,6 +83,9 @@ import {
   abortError,
   isAbortError
 } from "./chunk-R2MBW2S4.js";
+import {
+  log
+} from "./chunk-3WCASNQZ.js";
 
 // src/access-mcp.ts
 import { randomUUID as randomUUID2 } from "crypto";
@@ -1647,6 +1654,13 @@ function throwMcpAbort(signal, message) {
   if (isAbortError(signal.reason)) throw signal.reason;
   throw abortError(message);
 }
+function mcpToolErrorMessage(err) {
+  if (err instanceof EngramAccessInputError || err instanceof EngramAccessForbiddenError) {
+    return err.message;
+  }
+  log.error("engram MCP tools/call internal error", err);
+  return "internal error";
+}
 var MCP_SUPPORTED_PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
 var MCP_DEFAULT_PROTOCOL_VERSION = MCP_SUPPORTED_PROTOCOL_VERSIONS[0] ?? "2025-06-18";
 function isReadOnlyToolName(name) {
@@ -3480,7 +3494,7 @@ var EngramMcpServer = class {
     this.tools = applyToolOutputSchemas(this.tools, CANONICAL_MCP_PREFIX, LEGACY_MCP_PREFIX);
   }
   service;
-  buffer = Buffer.alloc(0);
+  frames = new McpFrameReader();
   flushTask = null;
   tools;
   resources;
@@ -3719,7 +3733,7 @@ var EngramMcpServer = class {
         };
       } catch (err) {
         if (isAbortError(err)) throw err;
-        const message = err instanceof Error ? err.message : String(err);
+        const message = mcpToolErrorMessage(err instanceof Error ? err : new Error(String(err)));
         return {
           jsonrpc: "2.0",
           id,
@@ -3741,7 +3755,7 @@ var EngramMcpServer = class {
   }
   async runStdio(input, output) {
     input.on("data", (chunk) => {
-      this.buffer = Buffer.concat([this.buffer, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
+      this.frames.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
       this.scheduleFlush(output);
     });
     await new Promise((resolve, reject) => {
@@ -3767,36 +3781,21 @@ var EngramMcpServer = class {
       if (this.flushTask === task) {
         this.flushTask = null;
       }
-      if (this.buffer.length > 0) {
+      if (this.frames.hasUnread()) {
         this.scheduleFlush(output);
       }
     });
     this.flushTask = task;
   }
   async flushBuffer(output) {
-    while (true) {
-      const headerEnd = this.buffer.indexOf("\r\n\r\n");
-      if (headerEnd < 0) return;
-      const headerText = this.buffer.slice(0, headerEnd).toString("utf-8");
-      const headers = headerText.split("\r\n");
-      const contentLengthHeader = headers.find((line) => line.toLowerCase().startsWith("content-length:"));
-      if (!contentLengthHeader) {
-        this.buffer = Buffer.alloc(0);
-        return;
-      }
-      const contentLength = Number.parseInt(contentLengthHeader.split(":")[1]?.trim() ?? "0", 10);
-      if (!Number.isFinite(contentLength) || contentLength < 0) {
-        this.buffer = Buffer.alloc(0);
-        return;
+    for (let frame = this.frames.next(); frame; frame = this.frames.next()) {
+      if (frame.kind === "too-large") {
+        this.writeMessage(output, { jsonrpc: "2.0", id: null, error: { code: -32600, message: "frame too large" } });
+        continue;
       }
-      const messageStart = headerEnd + 4;
-      const messageEnd = messageStart + contentLength;
-      if (this.buffer.length < messageEnd) return;
-      const body = this.buffer.slice(messageStart, messageEnd).toString("utf-8");
-      this.buffer = this.buffer.slice(messageEnd);
       let parsed;
       try {
-        parsed = JSON.parse(body);
+        parsed = JSON.parse(frame.text);
       } catch {
         this.writeMessage(output, {
           jsonrpc: "2.0",
@@ -3892,7 +3891,7 @@ ${body}`;
       const visible = this.tools.filter(
         (t) => caps?.ops === void 0 || capabilityAllowsOp(caps, MCP_MIGRATED_OPERATIONS[toLegacyToolName(t.name)] ?? "")
       ).map((t) => t.name);
-      throw new Error(unknownToolError(name, visible));
+      throw new EngramAccessInputError(unknownToolError(name, visible));
     }
     const op = getOperation(migrated);
     if (!op) {
@@ -3986,4 +3985,4 @@ export {
   MCP_MIGRATED_OPERATIONS,
   EngramMcpServer
 };
-//# sourceMappingURL=chunk-Z3DDQXM4.js.map
+//# sourceMappingURL=chunk-XSFQN7TP.js.map