@remnic/core 10.0.92 → 10.0.93

package/dist/{chunk-UDKWFDV2.js → chunk-HLUHEMN4.js}

@@ -18,7 +18,7 @@ import {
 } from "./chunk-3WCASNQZ.js";
 
 // src/storage/content-hash-index.ts
-import { mkdir, stat } from "fs/promises";
+import { mkdir, stat, utimes } from "fs/promises";
 import path from "path";
 var CONTENT_HASH_INDEX_LOCK_STALE_MS = 3e4;
 var CONTENT_HASH_INDEX_FORMAT_HEADER = "# remnic-content-hash-index:v2";
@@ -185,6 +185,24 @@ var ContentHashIndex = class _ContentHashIndex {
     }
     return current.mtimeMs === last.mtimeMs && current.size === last.size && current.dev === last.dev && current.ino === last.ino && current.ctimeMs === last.ctimeMs && current.birthtimeMs === last.birthtimeMs;
   }
+  /**
+   * Change the durable file's mtime without touching its content. A publish
+   * that throws or stays deferred leaves the file as it was, so a peer that
+   * already synced it keeps answering authoritative MISSes for deltas this
+   * instance holds only in memory (#3355). A new stamp makes every holder of the
+   * old fingerprint, this instance included, fail the freshness check and
+   * confirm against the corpus. Best effort: a file that cannot be stamped
+   * leaves the callers' existing retry and rebuild paths as the only repair.
+   */
+  async invalidatePeerFreshness() {
+    try {
+      const { mtimeMs } = await stat(this.filePath);
+      const bumped = new Date(Math.max(Date.now(), mtimeMs + 1));
+      await utimes(this.filePath, bumped, bumped);
+    } catch (err) {
+      log.debug(`content-hash index: could not invalidate peer freshness of ${this.filePath}: ${err}`);
+    }
+  }
   /** Check if content already exists in the index. */
   has(content) {
     return this.hashes.has(_ContentHashIndex.computeHash(content));
@@ -305,9 +323,15 @@ var ContentHashIndex = class _ContentHashIndex {
             `content-hash index: lock not acquired for ${this.filePath}; deferring reconcile save (dirty retained, scheduling durable retry)`
           );
           this.scheduleReconcileRetry();
+          await this.invalidatePeerFreshness();
           return;
         }
-        await publish();
+        try {
+          await publish();
+        } catch (err) {
+          await this.invalidatePeerFreshness();
+          throw err;
+        }
         if (this.dirty) {
           this.scheduleReconcileRetry();
         } else {
@@ -577,4 +601,4 @@ export {
   FactHashIndexNotAuthoritativeError,
   ContentHashIndex
 };
-//# sourceMappingURL=chunk-UDKWFDV2.js.map
+//# sourceMappingURL=chunk-HLUHEMN4.js.map

package/dist/chunk-HLUHEMN4.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, utimes } 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  /**\n   * Change the durable file's mtime without touching its content. A publish\n   * that throws or stays deferred leaves the file as it was, so a peer that\n   * already synced it keeps answering authoritative MISSes for deltas this\n   * instance holds only in memory (#3355). A new stamp makes every holder of the\n   * old fingerprint, this instance included, fail the freshness check and\n   * confirm against the corpus. Best effort: a file that cannot be stamped\n   * leaves the callers' existing retry and rebuild paths as the only repair.\n   */\n  private async invalidatePeerFreshness(): Promise<void> {\n    try {\n      const { mtimeMs } = await stat(this.filePath);\n      const bumped = new Date(Math.max(Date.now(), mtimeMs + 1));\n      await utimes(this.filePath, bumped, bumped);\n    } catch (err) {\n      log.debug(`content-hash index: could not invalidate peer freshness of ${this.filePath}: ${err}`);\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          await this.invalidatePeerFreshness();\n          return;\n        }\n        try {\n          await publish();\n        } catch (err) {\n          await this.invalidatePeerFreshness();\n          throw err;\n        }\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-QFEDITXM.js → chunk-JNDMIAJ4.js}

@@ -4,7 +4,7 @@ import {
 } from "./chunk-AAD2ZS6P.js";
 import {
   gatewayTaskChainOptions
-} from "./chunk-ZU5JDLOH.js";
+} from "./chunk-MMRTPH3J.js";
 import {
   extractJsonCandidates
 } from "./chunk-YBA52OKG.js";
@@ -685,4 +685,4 @@ export {
   serializeFaithfulnessFields,
   parseFaithfulnessField
 };
-//# sourceMappingURL=chunk-QFEDITXM.js.map
+//# sourceMappingURL=chunk-JNDMIAJ4.js.map

package/dist/chunk-JTSSSR4L.js

@@ -0,0 +1,359 @@
+import {
+  assertNamespaceAllowed,
+  assertOperationAuthorizationAllowed,
+  tokenCapabilityStore
+} from "./chunk-OGBQMY46.js";
+import {
+  expandTildePath
+} from "./chunk-6KH5NLQS.js";
+import {
+  EngramAccessInputError
+} from "./chunk-CJCTKL6Y.js";
+
+// src/access-boundary.ts
+import { z } from "zod";
+var OPERATION_NAMES = [
+  "memory_get",
+  "memory_search",
+  "external_wiki_search",
+  "memory_store",
+  "coding_decision",
+  "coding_architecture",
+  // codegraph parity tools (issue #1554) -- each maps to one codegraph_*
+  // boundary operation that delegates to the surface handler in
+  // coding/codegraph-surfaces.ts. Names match the external tool suffixes.
+  "codegraph_index",
+  "codegraph_list_projects",
+  "codegraph_delete_project",
+  "codegraph_index_status",
+  "codegraph_search_graph",
+  "codegraph_trace_path",
+  "codegraph_detect_changes",
+  "codegraph_query_graph",
+  "codegraph_get_schema",
+  "codegraph_get_snippet",
+  "codegraph_get_architecture",
+  "codegraph_search_code",
+  "codegraph_manage_adr",
+  "codegraph_ingest_traces",
+  "memory_correct_plan",
+  "memory_correct_apply",
+  "coding_delta",
+  // Remaining MCP/HTTP handlers migrated through the boundary (issue #1525).
+  "recall",
+  "recall_explain",
+  "set_coding_context",
+  "recall_tier_explain",
+  "recall_xray",
+  "recall_why",
+  "who_knows",
+  "promotion_candidates",
+  "namespace_writable",
+  "wearables_status",
+  "wearables_sync",
+  "transcript_day",
+  "transcript_search",
+  "transcript_memories",
+  "location_status",
+  "location_check",
+  "location_sync",
+  "location_backfill",
+  "location_day",
+  "meetings_list",
+  "meetings_get",
+  "meetings_build",
+  "deep_recall",
+  "memory_expand",
+  "memory_traverse",
+  "memory_ls",
+  "memory_tree",
+  "memory_find",
+  "standup",
+  "action_confidence",
+  "chatgpt_memory_inspector",
+  "day_summary",
+  "capsule_export",
+  "capsule_import",
+  "capsule_list",
+  "memory_governance_run",
+  "entity_synthesis_run",
+  "procedure_mining_run",
+  "pattern_reinforcement_run",
+  "procedural_stats",
+  "procedure_library_maintenance",
+  "memory_timeline",
+  "suggestion_submit",
+  "entity_get",
+  "review_queue_list",
+  "correction_pending",
+  "observe",
+  "lcm_search",
+  "lcm_compaction_flush",
+  "extraction_force_flush",
+  "lcm_compaction_record",
+  "continuity_audit_generate",
+  "continuity_incident_open",
+  "continuity_incident_close",
+  "continuity_incident_list",
+  "continuity_loop_add_or_update",
+  "continuity_loop_review",
+  "identity_anchor_get",
+  "identity_anchor_update",
+  "memory_identity",
+  "work_task",
+  "work_project",
+  "work_board",
+  "shared_context_write_output",
+  "shared_feedback_record",
+  "shared_priorities_append",
+  "relay_mission_append",
+  "relay_mission_read",
+  "shared_context_cross_signals_run",
+  "shared_context_curate_daily",
+  "compounding_weekly_synthesize",
+  "compounding_promote_candidate",
+  "compression_guidelines_optimize",
+  "compression_guidelines_activate",
+  "memory_profile",
+  "memory_entities_list",
+  "memory_questions",
+  "memory_last_recall",
+  "memory_intent_debug",
+  "memory_qmd_debug",
+  "memory_graph_explain",
+  "graph_snapshot",
+  "memory_feedback",
+  "memory_promote",
+  "memory_outcome",
+  "memory_action_apply",
+  "context_checkpoint",
+  "briefing",
+  "review_list",
+  "review_resolve",
+  "contradiction_scan_run",
+  "preference_drift_scan",
+  "memory_summarize_hourly",
+  "conversation_index_update",
+  "profiling_report",
+  "graph_edge_decay_run",
+  "live_connectors_run",
+  "peer_list",
+  "peer_get",
+  "peer_set",
+  "peer_delete",
+  "peer_profile_get",
+  "peer_forget",
+  "console_state",
+  "dreams_status",
+  "dreams_run",
+  "support_passport_memory_preview",
+  "support_passport_cards_list",
+  "support_passport_draft_create",
+  "support_passport_drafts_generate",
+  "support_passport_card_replace",
+  "support_passport_card_approve",
+  "support_passport_card_reject",
+  "support_passport_card_withdraw",
+  "support_passport_grant_create",
+  "support_passport_grants_list",
+  "support_passport_grant_revoke",
+  "support_passport_grant_read",
+  "support_passport_grant_ask",
+  // HTTP-only routes (no direct MCP tool equivalent).
+  "adapters_status",
+  "offline_sync_snapshot",
+  "offline_sync_snapshot_stream",
+  "offline_sync_files",
+  "offline_sync_file_content",
+  "offline_sync_apply_file_content",
+  "offline_sync_apply",
+  "lcm_status",
+  "memory_list",
+  "recall_timings",
+  "entity_list",
+  "maintenance_status",
+  "quality_status",
+  "trust_zones_status",
+  "trust_zones_records",
+  "review_disposition",
+  "review_deck_list",
+  "review_deck_action",
+  "review_deck_undo",
+  "trust_zones_promote",
+  "trust_zones_demo_seed",
+  "citations_observed",
+  "contradiction_detail",
+  "graph_events",
+  // Chat surface — conversational memory inspection/correction (issue #1583).
+  "chat_message",
+  "chat_events"
+];
+var IMPLICIT_HTTP_NAMESPACE_OPERATIONS = /* @__PURE__ */ new Set([
+  "offline_sync_snapshot",
+  "offline_sync_snapshot_stream",
+  "memory_list",
+  "entity_list",
+  "maintenance_status",
+  "quality_status",
+  "trust_zones_status",
+  "graph_events",
+  "citations_observed"
+]);
+var PRINCIPAL_NAMESPACE_OPERATIONS = /* @__PURE__ */ new Set([
+  "support_passport_memory_preview",
+  "support_passport_cards_list",
+  "support_passport_draft_create",
+  "support_passport_drafts_generate",
+  "support_passport_card_replace",
+  "support_passport_card_approve",
+  "support_passport_card_reject",
+  "support_passport_card_withdraw",
+  "support_passport_grant_create",
+  "support_passport_grants_list",
+  "support_passport_grant_revoke"
+]);
+function coerceBooleanLike(value) {
+  if (value === void 0 || value === null || value === "") return void 0;
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") {
+    const lower = value.trim().toLowerCase();
+    if (lower === "true" || lower === "1" || lower === "yes" || lower === "on") return true;
+    if (lower === "false" || lower === "0" || lower === "no" || lower === "off") return false;
+  }
+  throw new EngramAccessInputError(
+    `expected a boolean-like value (true|false|1|0|yes|no|on|off); got ${JSON.stringify(value)}`
+  );
+}
+function coercePositiveInteger(value, label) {
+  if (value === void 0 || value === null || value === "") return void 0;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value <= 0 || !Number.isInteger(value)) {
+      throw new EngramAccessInputError(`${label} expects a positive integer; got ${JSON.stringify(value)}`);
+    }
+    return value;
+  }
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (!/^[+-]?\d+$/.test(trimmed)) {
+      throw new EngramAccessInputError(`${label} expects a positive integer; got ${JSON.stringify(value)}`);
+    }
+    const parsed = Number(trimmed);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+      throw new EngramAccessInputError(`${label} expects a positive integer; got ${JSON.stringify(value)}`);
+    }
+    return parsed;
+  }
+  throw new EngramAccessInputError(`${label} expects a positive integer; got ${JSON.stringify(value)}`);
+}
+function normalizeOptionalPath(value) {
+  if (value === void 0 || value === null || value === "") return void 0;
+  if (typeof value !== "string") {
+    throw new EngramAccessInputError(`expected a path string; got ${JSON.stringify(value)}`);
+  }
+  return expandTildePath(value);
+}
+function formatZodIssues(error) {
+  const parts = [];
+  for (const issue of error.issues) {
+    const hasNumeric = issue.path.some((p) => typeof p === "number");
+    const path = hasNumeric ? issue.path.filter((p) => typeof p === "string").join(".") || "(root)" : issue.path.length > 0 ? issue.path.join(".") : "(root)";
+    const options = enumOptionsFromIssue(issue);
+    const suffix = options ? `. Valid: ${options.join(", ")}` : "";
+    parts.push(`${path}: ${humanReadableIssueMessage(issue, path, hasNumeric)}${suffix}`);
+  }
+  return parts.length > 0 ? `request validation failed: ${parts.join("; ")}` : "request validation failed";
+}
+function enumOptionsFromIssue(issue) {
+  if (issue.code !== "invalid_value") return void 0;
+  const rawValues = "values" in issue ? issue.values : void 0;
+  return Array.isArray(rawValues) ? rawValues.map((opt) => String(opt)) : void 0;
+}
+function humanReadableIssueMessage(issue, pathLabel, hasNumericPath) {
+  if (issue.code !== "invalid_type") return issue.message;
+  const expected = issue.expected;
+  if (issue.message.endsWith("received undefined")) return issue.message;
+  if (hasNumericPath && expected) {
+    return `${pathLabel} must be an array of ${expected}s`;
+  }
+  const fieldName = issue.path.length > 0 ? String(issue.path[issue.path.length - 1]) : "value";
+  switch (expected) {
+    case "string":
+      return `${fieldName} must be a string`;
+    case "boolean":
+      return `${fieldName} must be a boolean`;
+    case "number":
+      return `${fieldName} must be a number`;
+    case "array":
+      return `${fieldName} must be an array`;
+    case "object":
+      return `${fieldName} must be an object`;
+    default:
+      return issue.message;
+  }
+}
+var registry = /* @__PURE__ */ new Map();
+function defineOperation(spec) {
+  if (registry.has(spec.name)) {
+    throw new Error(`access-boundary: operation already registered: ${spec.name}`);
+  }
+  const bound = {
+    spec,
+    run: async (rawInput, ctx) => {
+      const parseResult = spec.schema.safeParse(rawInput);
+      if (!parseResult.success) {
+        throw new EngramAccessInputError(formatZodIssues(parseResult.error));
+      }
+      assertOperationAuthorizationAllowed(tokenCapabilityStore.getStore(), spec);
+      if (operationRequiresAuthorizedNamespace(spec.name)) {
+        const parsedNamespace = parseResult.data.namespace;
+        if (parsedNamespace) {
+          assertNamespaceAllowed(tokenCapabilityStore.getStore(), parsedNamespace);
+        }
+      }
+      return spec.handler(parseResult.data, { ...ctx, rawInput });
+    }
+  };
+  registry.set(spec.name, bound);
+  return bound;
+}
+function getOperation(name) {
+  return registry.get(name);
+}
+function operationRequiresAuthorizedNamespace(name) {
+  if (name === "namespace_writable") return false;
+  if (IMPLICIT_HTTP_NAMESPACE_OPERATIONS.has(name)) return true;
+  let schema = registry.get(name)?.spec.schema;
+  while (schema instanceof z.ZodType && !(schema instanceof z.ZodObject)) {
+    const wrapper = schema;
+    const sides = [wrapper.in, wrapper.out].filter(
+      (side) => side instanceof z.ZodType && !(side instanceof z.ZodTransform)
+    );
+    if (sides.length !== 1) break;
+    schema = sides[0];
+  }
+  return schema instanceof z.ZodObject && Object.hasOwn(schema.shape, "namespace");
+}
+function operationUsesPrincipalNamespace(name) {
+  return PRINCIPAL_NAMESPACE_OPERATIONS.has(name);
+}
+function listRegisteredOperations() {
+  return [...registry.keys()];
+}
+function __resetRegistryForTest() {
+  registry.clear();
+}
+
+export {
+  OPERATION_NAMES,
+  coerceBooleanLike,
+  coercePositiveInteger,
+  normalizeOptionalPath,
+  formatZodIssues,
+  defineOperation,
+  getOperation,
+  operationRequiresAuthorizedNamespace,
+  operationUsesPrincipalNamespace,
+  listRegisteredOperations,
+  __resetRegistryForTest
+};
+//# sourceMappingURL=chunk-JTSSSR4L.js.map

package/dist/chunk-JTSSSR4L.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/access-boundary.ts"],"sourcesContent":["/**\n * Single input-validation and error boundary for the CLI/MCP/HTTP access\n * surfaces (issue #1525, epic #1520 Phase 1).\n *\n * Every operation that crosses the access-service facade passes through ONE\n * registry entry: a zod-validated request envelope, a shared error mapper,\n * and the \"reject invalid input and list valid options\" behavior that\n * CLAUDE.md rules 14/17/24/28/36/48/51 previously had to be re-implemented\n * per handler. The three surfaces become thin adapters — one operation\n * definition, three transports — so a validation fix lands everywhere at\n * once.\n *\n * Host-agnostic (rule 31): operation names carry no `openclaw-*`/`engram-*`\n * prefix. Session/namespace tenancy stays in the handler layer (resolved via\n * ScopePlan #1521); the boundary validates SHAPE, not tenancy.\n */\n\nimport { z } from \"zod\";\n// The input error lives in the leaf module; importing it from access-service\n// here (a re-export) drags the whole service hub into this module's init and\n// leaves `registry` TDZ-uninitialized when the cycle re-enters (#3354).\nimport { EngramAccessInputError } from \"./access-errors.js\";\nimport type { EngramAccessService } from \"./access-service.js\";\nimport {\n  assertNamespaceAllowed,\n  assertOperationAuthorizationAllowed,\n  tokenCapabilityStore,\n} from \"./access-token-capabilities.js\";\nimport { expandTildePath } from \"./utils/path.js\";\n\n// ---------------------------------------------------------------------------\n// Canonical operation names — host-agnostic (rule 31)\n// ---------------------------------------------------------------------------\n\n/**\n * Canonical operation ids. One id is shared by the MCP tool, the HTTP route,\n * and the CLI command that expose the same operation. Add to this union as\n * each domain-group migration PR (memory ops → connectors → namespaces …)\n * lands; the fitness test in `access-surface-catalog.test.ts` treats the\n * registered set as the migration state.\n */\nexport const OPERATION_NAMES = [\n  \"memory_get\",\n  \"memory_search\",\n  \"external_wiki_search\",\n  \"memory_store\",\n  \"coding_decision\",\n  \"coding_architecture\",\n  // codegraph parity tools (issue #1554) -- each maps to one codegraph_*\n  // boundary operation that delegates to the surface handler in\n  // coding/codegraph-surfaces.ts. Names match the external tool suffixes.\n  \"codegraph_index\",\n  \"codegraph_list_projects\",\n  \"codegraph_delete_project\",\n  \"codegraph_index_status\",\n  \"codegraph_search_graph\",\n  \"codegraph_trace_path\",\n  \"codegraph_detect_changes\",\n  \"codegraph_query_graph\",\n  \"codegraph_get_schema\",\n  \"codegraph_get_snippet\",\n  \"codegraph_get_architecture\",\n  \"codegraph_search_code\",\n  \"codegraph_manage_adr\",\n  \"codegraph_ingest_traces\",\n  \"memory_correct_plan\",\n  \"memory_correct_apply\",\n  \"coding_delta\",\n  // Remaining MCP/HTTP handlers migrated through the boundary (issue #1525).\n  \"recall\",\n  \"recall_explain\",\n  \"set_coding_context\",\n  \"recall_tier_explain\",\n  \"recall_xray\",\n  \"recall_why\",\n  \"who_knows\",\n  \"promotion_candidates\",\n  \"namespace_writable\",\n  \"wearables_status\",\n  \"wearables_sync\",\n  \"transcript_day\",\n  \"transcript_search\",\n  \"transcript_memories\",\n  \"location_status\",\n  \"location_check\",\n  \"location_sync\",\n  \"location_backfill\",\n  \"location_day\",\n  \"meetings_list\",\n  \"meetings_get\",\n  \"meetings_build\",\n  \"deep_recall\",\n  \"memory_expand\",\n  \"memory_traverse\",\n  \"memory_ls\",\n  \"memory_tree\",\n  \"memory_find\",\n  \"standup\",\n  \"action_confidence\",\n  \"chatgpt_memory_inspector\",\n  \"day_summary\",\n  \"capsule_export\",\n  \"capsule_import\",\n  \"capsule_list\",\n  \"memory_governance_run\",\n  \"entity_synthesis_run\",\n  \"procedure_mining_run\",\n  \"pattern_reinforcement_run\",\n  \"procedural_stats\",\n  \"procedure_library_maintenance\",\n  \"memory_timeline\",\n  \"suggestion_submit\",\n  \"entity_get\",\n  \"review_queue_list\",\n  \"correction_pending\",\n  \"observe\",\n  \"lcm_search\",\n  \"lcm_compaction_flush\",\n  \"extraction_force_flush\",\n  \"lcm_compaction_record\",\n  \"continuity_audit_generate\",\n  \"continuity_incident_open\",\n  \"continuity_incident_close\",\n  \"continuity_incident_list\",\n  \"continuity_loop_add_or_update\",\n  \"continuity_loop_review\",\n  \"identity_anchor_get\",\n  \"identity_anchor_update\",\n  \"memory_identity\",\n  \"work_task\",\n  \"work_project\",\n  \"work_board\",\n  \"shared_context_write_output\",\n  \"shared_feedback_record\",\n  \"shared_priorities_append\",\n  \"relay_mission_append\",\n  \"relay_mission_read\",\n  \"shared_context_cross_signals_run\",\n  \"shared_context_curate_daily\",\n  \"compounding_weekly_synthesize\",\n  \"compounding_promote_candidate\",\n  \"compression_guidelines_optimize\",\n  \"compression_guidelines_activate\",\n  \"memory_profile\",\n  \"memory_entities_list\",\n  \"memory_questions\",\n  \"memory_last_recall\",\n  \"memory_intent_debug\",\n  \"memory_qmd_debug\",\n  \"memory_graph_explain\",\n  \"graph_snapshot\",\n  \"memory_feedback\",\n  \"memory_promote\",\n  \"memory_outcome\",\n  \"memory_action_apply\",\n  \"context_checkpoint\",\n  \"briefing\",\n  \"review_list\",\n  \"review_resolve\",\n  \"contradiction_scan_run\",\n  \"preference_drift_scan\",\n  \"memory_summarize_hourly\",\n  \"conversation_index_update\",\n  \"profiling_report\",\n  \"graph_edge_decay_run\",\n  \"live_connectors_run\",\n  \"peer_list\",\n  \"peer_get\",\n  \"peer_set\",\n  \"peer_delete\",\n  \"peer_profile_get\",\n  \"peer_forget\",\n  \"console_state\",\n  \"dreams_status\",\n  \"dreams_run\",\n  \"support_passport_memory_preview\",\n  \"support_passport_cards_list\",\n  \"support_passport_draft_create\",\n  \"support_passport_drafts_generate\",\n  \"support_passport_card_replace\",\n  \"support_passport_card_approve\",\n  \"support_passport_card_reject\",\n  \"support_passport_card_withdraw\",\n  \"support_passport_grant_create\",\n  \"support_passport_grants_list\",\n  \"support_passport_grant_revoke\",\n  \"support_passport_grant_read\",\n  \"support_passport_grant_ask\",\n  // HTTP-only routes (no direct MCP tool equivalent).\n  \"adapters_status\",\n  \"offline_sync_snapshot\",\n  \"offline_sync_snapshot_stream\",\n  \"offline_sync_files\",\n  \"offline_sync_file_content\",\n  \"offline_sync_apply_file_content\",\n  \"offline_sync_apply\",\n  \"lcm_status\",\n  \"memory_list\",\n  \"recall_timings\",\n  \"entity_list\",\n  \"maintenance_status\",\n  \"quality_status\",\n  \"trust_zones_status\",\n  \"trust_zones_records\",\n  \"review_disposition\",\n  \"review_deck_list\",\n  \"review_deck_action\",\n  \"review_deck_undo\",\n  \"trust_zones_promote\",\n  \"trust_zones_demo_seed\",\n  \"citations_observed\",\n  \"contradiction_detail\",\n  \"graph_events\",\n  // Chat surface — conversational memory inspection/correction (issue #1583).\n  \"chat_message\",\n  \"chat_events\",\n] as const;\n\n/**\n * Canonical operation ids. One id is shared by the MCP tool, the HTTP route,\n * and the CLI command that expose the same operation. Derived from\n * {@link OPERATION_NAMES} (single source of truth) so the runtime catalog\n * used for token-capability validation cannot drift from the type. The\n * fitness test in `access-surface-catalog.test.ts` treats the registered set\n * as the migration state.\n */\nexport type OperationName = (typeof OPERATION_NAMES)[number];\n\nconst IMPLICIT_HTTP_NAMESPACE_OPERATIONS = new Set<OperationName>([\n  \"offline_sync_snapshot\",\n  \"offline_sync_snapshot_stream\",\n  \"memory_list\",\n  \"entity_list\",\n  \"maintenance_status\",\n  \"quality_status\",\n  \"trust_zones_status\",\n  \"graph_events\",\n  \"citations_observed\",\n]);\n\nconst PRINCIPAL_NAMESPACE_OPERATIONS = new Set<OperationName>([\n  \"support_passport_memory_preview\",\n  \"support_passport_cards_list\",\n  \"support_passport_draft_create\",\n  \"support_passport_drafts_generate\",\n  \"support_passport_card_replace\",\n  \"support_passport_card_approve\",\n  \"support_passport_card_reject\",\n  \"support_passport_card_withdraw\",\n  \"support_passport_grant_create\",\n  \"support_passport_grants_list\",\n  \"support_passport_grant_revoke\",\n]);\n\n// ---------------------------------------------------------------------------\n// Operation context — what every handler receives\n// ---------------------------------------------------------------------------\n\n/**\n * Per-call context. `service` is the facade the handler delegates to; the\n * boundary never reaches past it. `authenticatedPrincipal` is resolved by\n * the SURFACE (MCP header / HTTP identity / CLI flag) before the boundary\n * runs, so handlers stay principal-source-agnostic. `hooks` carries\n * transport-level callbacks (e.g. HTTP write-quota enforcement) that must\n * fire atomically inside the service call; surfaces that have no such hook\n * leave it undefined.\n */\nexport interface OperationContext {\n  readonly service: EngramAccessService;\n  readonly authenticatedPrincipal?: string;\n  readonly operatorPrincipal?: string;\n  /** Per-request cancellation supplied by transports that own a request lifecycle. */\n  readonly abortSignal?: AbortSignal;\n  /** Server-resolved connector identity (Phase 1 provenance). Set by the HTTP auth boundary from the matched token's connector; flows to write handlers so frontmatter records which connector submitted the memory. Client-supplied values are always overridden. */\n  readonly sourceConnector?: string;\n  /**\n   * The PRE-validation raw envelope exactly as the transport supplied it\n   * (issue #2829). Handlers use it to retain input spellings the schema's\n   * transforms canonicalize — e.g. the memory-store category aliases — so\n   * diagnostics can name what the caller actually sent. Never trust it for\n   * behavior; only the parsed `input` is validated.\n   */\n  readonly rawInput?: unknown;\n  readonly hooks?: OperationHooks;\n}\n\n/**\n * Transport-level callbacks a handler forwards into the service call. Kept\n * narrow on purpose: the boundary owns validation + dispatch shape, not\n * transport policy. Add fields here only when a surface genuinely needs a\n * callback the service itself consumes.\n */\nexport interface OperationHooks {\n  /** HTTP write-quota gate; throws to reject the write when exhausted. */\n  readonly enforceWriteQuota?: () => void | Promise<void>;\n  /** Commit-boundary accounting for writes that can fail after durability. */\n  readonly recordWriteCommit?: () => void;\n}\n\n// ---------------------------------------------------------------------------\n// Operation spec + bound operation\n// ---------------------------------------------------------------------------\n\nexport interface OperationSpec<In, Out> {\n  /** Canonical operation id; matches an {@link OperationName}. */\n  readonly name: OperationName;\n  readonly description: string;\n  /**\n   * Zod schema validating the raw request envelope. Input type may differ\n   * from the output `In` — schemas that canonicalize during parsing (issue\n   * #2829 category aliases) are first-class, declared truthfully instead of\n   * cast into an input-equals-output shape.\n   */\n  readonly schema: z.ZodType<In, unknown>;\n  /** Handler invoked with the parsed input; throws EngramAccessInputError for domain faults. */\n  readonly handler: (input: In, ctx: OperationContext) => Promise<Out>;\n  /**\n   * Marks an operation as inherently FLEET-WIDE / global — it runs across ALL\n   * namespaces (or against a single non-namespaced global layer) and carries no\n   * `namespace` argument, so the MCP `tools/call` effective-namespace chokepoint\n   * never applies. When set, {@link defineOperation}'s run wrapper rejects any\n   * namespace-SCOPED token (fail closed) via assertFleetWideOperationAllowed\n   * BEFORE the handler — no side effect on denial. Unrestricted/legacy tokens\n   * (cron, internal callers, no capability record) are unaffected (issue #1850).\n   */\n  readonly fleetWide?: boolean;\n  /**\n   * Alternate op allow-list: when set, the token may invoke this operation if\n   * its ops allow-list permits ANY of these ops (instead of the default rule\n   * that requires the op's own {@link name}). Lets a read-only diagnostic be\n   * granted by the write ops it diagnoses — e.g. `namespace_writable` is\n   * runnable by any token permitted to `observe`/`memory_store`, so a token\n   * minted before the diagnostic op existed can still call it. Unrestricted /\n   * legacy tokens (no ops axis) are unaffected. Keeps the boundary and any HTTP\n   * transport for the same op enforcing ONE policy.\n   */\n  readonly allowedByOps?: readonly OperationName[];\n}\n\nexport interface BoundOperation<In = unknown, Out = unknown> {\n  readonly spec: OperationSpec<In, Out>;\n  /** Validate the raw envelope, then invoke the handler. Throws EngramAccessInputError on any validation failure. */\n  readonly run: (rawInput: unknown, ctx: OperationContext) => Promise<Out>;\n}\n\n// ---------------------------------------------------------------------------\n// Shared normalizers the boundary owns (rules 17, 28, 36, 48, 51)\n// ---------------------------------------------------------------------------\n\n/**\n * Coerce boolean-like strings at the edge (rule 36). Accepts actual booleans\n * and the string spellings clients send (\"true\"/\"false\"/\"1\"/\"0\"/\"yes\"/\"no\"/\n * \"on\"/\"off\", case-insensitive). Rejects anything else loudly — `Boolean(\"false\")`\n * would silently be `true`, which is the bug rule 36 exists to prevent.\n *\n * `undefined`/`null`/`\"\"` → `undefined`, so callers can keep treating an\n * absent flag as \"use the default\" without a separate presence check.\n */\nexport function coerceBooleanLike(value: unknown): boolean | undefined {\n  if (value === undefined || value === null || value === \"\") return undefined;\n  if (typeof value === \"boolean\") return value;\n  if (typeof value === \"string\") {\n    const lower = value.trim().toLowerCase();\n    if (lower === \"true\" || lower === \"1\" || lower === \"yes\" || lower === \"on\") return true;\n    if (lower === \"false\" || lower === \"0\" || lower === \"no\" || lower === \"off\") return false;\n  }\n  throw new EngramAccessInputError(\n    `expected a boolean-like value (true|false|1|0|yes|no|on|off); got ${JSON.stringify(value)}`,\n  );\n}\n\n/**\n * Coerce + validate a positive integer from a numeric string or number\n * (rule 28). Loosely-typed MCP/CLI clients send `\"5\"`; `typeof saved === \"number\"`\n * on read-back would reject it later, so we coerce at the edge and reject\n * booleans/objects loudly (`Number(true) === 1` would silently pass otherwise).\n *\n * `undefined`/`null`/`\"\"` → `undefined`.\n */\nexport function coercePositiveInteger(value: unknown, label: string): number | undefined {\n  if (value === undefined || value === null || value === \"\") return undefined;\n  if (typeof value === \"number\") {\n    if (!Number.isFinite(value) || value <= 0 || !Number.isInteger(value)) {\n      throw new EngramAccessInputError(`${label} expects a positive integer; got ${JSON.stringify(value)}`);\n    }\n    return value;\n  }\n  if (typeof value === \"string\") {\n    const trimmed = value.trim();\n    if (!/^[+-]?\\d+$/.test(trimmed)) {\n      throw new EngramAccessInputError(`${label} expects a positive integer; got ${JSON.stringify(value)}`);\n    }\n    const parsed = Number(trimmed);\n    if (!Number.isSafeInteger(parsed) || parsed <= 0) {\n      throw new EngramAccessInputError(`${label} expects a positive integer; got ${JSON.stringify(value)}`);\n    }\n    return parsed;\n  }\n  throw new EngramAccessInputError(`${label} expects a positive integer; got ${JSON.stringify(value)}`);\n}\n\n/**\n * Expand `~` in a path-shaped input (rule 17). Node `fs` does NOT expand `~`;\n * ad-hoc regex drifts. `undefined`/`null`/`\"\"` → `undefined`.\n */\nexport function normalizeOptionalPath(value: unknown): string | undefined {\n  if (value === undefined || value === null || value === \"\") return undefined;\n  if (typeof value !== \"string\") {\n    throw new EngramAccessInputError(`expected a path string; got ${JSON.stringify(value)}`);\n  }\n  return expandTildePath(value);\n}\n\n// ---------------------------------------------------------------------------\n// Error formatting — rule 51: list valid options, never silently default\n// ---------------------------------------------------------------------------\n\n/**\n * Turn a zod failure into an {@link EngramAccessInputError} whose message\n * names the offending field and — for enum/union issues — lists the valid\n * options, so the caller can correct rather than guess (rule 51).\n */\nexport function formatZodIssues(error: z.ZodError): string {\n  const parts: string[] = [];\n  for (const issue of error.issues) {\n    // Collapse array-index paths (e.g. [\"currentContextScopes\", 1]) to\n    // the field name so the message reads \"field: must be ...\" not\n    // \"field.1: must be ...\".\n    const hasNumeric = issue.path.some((p) => typeof p === \"number\");\n    const path = hasNumeric\n      ? issue.path.filter((p) => typeof p === \"string\").join(\".\") || \"(root)\"\n      : issue.path.length > 0 ? issue.path.join(\".\") : \"(root)\";\n    const options = enumOptionsFromIssue(issue);\n    const suffix = options ? `. Valid: ${options.join(\", \")}` : \"\";\n    parts.push(`${path}: ${humanReadableIssueMessage(issue, path, hasNumeric)}${suffix}`);\n  }\n  return parts.length > 0\n    ? `request validation failed: ${parts.join(\"; \")}`\n    : \"request validation failed\";\n}\n\nfunction enumOptionsFromIssue(issue: z.core.$ZodIssue): readonly string[] | undefined {\n  // zod 4 exposes accepted enum values on invalid_value issues as `values`\n  // (the v3 `options` spelling is kept as a fallback). Reading them here\n  // keeps \"list valid options\" in ONE place rather than per handler.\n  if (issue.code !== \"invalid_value\") return undefined;\n  const rawValues = \"values\" in issue ? issue.values : undefined;\n  return Array.isArray(rawValues) ? rawValues.map((opt) => String(opt)) : undefined;\n}\n\n/**\n * Human-readable \"must be a <type>\" message for generic type mismatches\n * (rule 51). zod 4 removed parse-time error maps, so the boundary applies\n * this post-parse in formatZodIssues instead — same messages, one place.\n * The caller supplies the collapsed path label and its numeric-segment\n * verdict so this helper runs no representation checks of its own.\n */\nfunction humanReadableIssueMessage(issue: z.core.$ZodIssue, pathLabel: string, hasNumericPath: boolean): string {\n  if (issue.code !== \"invalid_type\") return issue.message;\n  const expected = issue.expected;\n  // zod 4 issues carry no `received` field; its message ends \"received undefined\"\n  // for an absent value, which is a missing field, not a type mismatch.\n  if (issue.message.endsWith(\"received undefined\")) return issue.message;\n  if (hasNumericPath && expected) {\n    return `${pathLabel} must be an array of ${expected}s`;\n  }\n  const fieldName = issue.path.length > 0 ? String(issue.path[issue.path.length - 1]) : \"value\";\n  switch (expected) {\n    case \"string\": return `${fieldName} must be a string`;\n    case \"boolean\": return `${fieldName} must be a boolean`;\n    case \"number\": return `${fieldName} must be a number`;\n    case \"array\": return `${fieldName} must be an array`;\n    case \"object\": return `${fieldName} must be an object`;\n    default: return issue.message;\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Registry\n// ---------------------------------------------------------------------------\n\nconst registry = new Map<OperationName, BoundOperation>();\n\n/**\n * Register an operation. Throws if the name is already registered — duplicate\n * registration is a programming error, not a runtime input fault, so it throws\n * a plain Error (not the input-error class surfaces translate for clients).\n */\nexport function defineOperation<In, Out>(spec: OperationSpec<In, Out>): BoundOperation<In, Out> {\n  if (registry.has(spec.name)) {\n    throw new Error(`access-boundary: operation already registered: ${spec.name}`);\n  }\n  const bound: BoundOperation<In, Out> = {\n    spec,\n    run: async (rawInput, ctx) => {\n      const parseResult = spec.schema.safeParse(rawInput);\n      if (!parseResult.success) {\n        throw new EngramAccessInputError(formatZodIssues(parseResult.error));\n      }\n      assertOperationAuthorizationAllowed(tokenCapabilityStore.getStore(), spec);\n      // Post-parse namespace re-check (issue #3225 B1): the transports authorize\n      // the RAW namespace before preprocessing. Re-check the PARSED value so a\n      // namespace that only appears after validation cannot bypass the token\n      // allow-list. Absent namespaces keep the transport check; no default is\n      // invented here.\n      if (operationRequiresAuthorizedNamespace(spec.name)) {\n        // SAFETY: namespace-bearing schemas parse `namespace` as a non-empty\n        // string, an explicit null (transport null-for-absent idiom), or\n        // undefined; falsy spellings mean absent and keep the transport check.\n        const parsedNamespace = (parseResult.data as { namespace?: string | null }).namespace;\n        if (parsedNamespace) {\n          assertNamespaceAllowed(tokenCapabilityStore.getStore(), parsedNamespace);\n        }\n      }\n      return spec.handler(parseResult.data, { ...ctx, rawInput });\n    },\n  };\n  // Store under the canonical name; the cast is safe because In/Out are\n  // erased at the registry boundary and recovered by callers via getOperation.\n  registry.set(spec.name, bound as unknown as BoundOperation);\n  return bound;\n}\n\n/** Look up a registered operation by canonical name. */\nexport function getOperation(name: OperationName): BoundOperation | undefined {\n  return registry.get(name);\n}\n\n/** Whether a probe must authorize an operation's effective namespace. */\nexport function operationRequiresAuthorizedNamespace(name: OperationName): boolean {\n  if (name === \"namespace_writable\") return false;\n  if (IMPLICIT_HTTP_NAMESPACE_OPERATIONS.has(name)) return true;\n  let schema: unknown = registry.get(name)?.spec.schema;\n  // zod 4 has no ZodEffects. Transforms and preprocessors wrap as pipes with\n  // the base schema on the side opposite the ZodTransform. Unwrap until the\n  // base object appears — one unwrap left suggestion_submit looking\n  // namespace-free after the category transform, so the loop stays.\n  while (schema instanceof z.ZodType && !(schema instanceof z.ZodObject)) {\n    // SAFETY: pipe wrappers expose their two sides as `in` / `out`.\n    const wrapper = schema as { in?: unknown; out?: unknown };\n    const sides = [wrapper.in, wrapper.out].filter(\n      (side) => side instanceof z.ZodType && !(side instanceof z.ZodTransform),\n    );\n    if (sides.length !== 1) break;\n    schema = sides[0];\n  }\n  return schema instanceof z.ZodObject && Object.hasOwn(schema.shape, \"namespace\");\n}\n\n/** Whether an operation resolves its namespace from the authenticated principal. */\nexport function operationUsesPrincipalNamespace(name: OperationName): boolean {\n  return PRINCIPAL_NAMESPACE_OPERATIONS.has(name);\n}\n\n/** All registered operation names. */\nexport function listRegisteredOperations(): readonly OperationName[] {\n  return [...registry.keys()];\n}\n\n/** Test-only: clear the registry so pilot definitions can be re-registered. */\nexport function __resetRegistryForTest(): void {\n  registry.clear();\n}\n"],"mappings":";;;;;;;;;;;;;AAiBA,SAAS,SAAS;AAwBX,IAAM,kBAAkB;AAAA,EAC7B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA;AAAA;AAAA,EAIA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA,EAEA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AA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","names":[]}