@remnic/core 9.45.3 → 9.45.4

package/src/tool-scoped-memory.ts

@@ -173,6 +173,16 @@ export function withholdToolScopedFromSharedNamespace({
   return false;
 }
 
+export function canRecallToolScopedMemory(
+  frontmatter: { sourceConnector?: string; toolScoped?: true },
+  requestingConnector?: string,
+): boolean {
+  if (frontmatter.toolScoped !== true) return true;
+  const sourceConnector = frontmatter.sourceConnector?.trim();
+  const requester = requestingConnector?.trim();
+  return !sourceConnector || !requester || sourceConnector === requester;
+}
+
 export interface GlobalFactPromotionInputs {
   scope: string | null | undefined;
   content: string;

package/src/transfer/capsule-import.ts

@@ -11,6 +11,7 @@ import {
   repairContentAfterJournalMove,
   requestEntityCanonicalIdReconcile,
 } from "../storage/entity-canonical-id-references.js";
+import { withRawEntityPageMutation } from "../storage/entity-canonical-id-lock.js";
 import {
   createVersion,
   type VersioningConfig,
@@ -422,6 +423,7 @@ export async function importCapsule(
   // between a legacy-preserving memory write and its colliding entity page,
   // canonicalizing the memory onto the wrong claimant irreversibly.
   let reconcileNeeded = false;
+  const applyRecords = async (): Promise<void> => {
   for (const rec of sortedRecords) {
     const targetRel = computeTargetPath(rec.path, mode, capsule.id);
     // Use rootReal (realpath-resolved) to stay consistent with phase 1's
@@ -537,6 +539,17 @@ export async function importCapsule(
   if (reconcileNeeded) {
     await requestEntityCanonicalIdReconcile(journalStateDir);
   }
+  };
+  const firstEntityId = capsuleEntityIds.values().next().value;
+  if (firstEntityId === undefined) {
+    await applyRecords();
+  } else {
+    await withRawEntityPageMutation(
+      rootReal,
+      path.join(rootReal, "entities", `${firstEntityId}.md`),
+      applyRecords,
+    );
+  }
 
   // Sort skipped for stable output (see comment above).
   skipped.sort((a, b) => a.path.localeCompare(b.path));

package/src/transfer/capsule-merge.ts

@@ -10,6 +10,7 @@ import {
   repairContentAfterJournalMove,
   requestEntityCanonicalIdReconcile,
 } from "../storage/entity-canonical-id-references.js";
+import { withRawEntityPageMutation } from "../storage/entity-canonical-id-lock.js";
 import {
   createVersion,
   type VersioningConfig,
@@ -440,6 +441,7 @@ export async function mergeCapsule(
     a.path.localeCompare(b.path),
   );
 
+  const applyRecords = async (): Promise<void> => {
   for (const rec of sortedRecords) {
     const targetAbs = path.join(rootReal, fromPosixRelPath(rec.path));
     const entry = manifestIndex.get(rec.path)!; // validated above
@@ -531,6 +533,17 @@ export async function mergeCapsule(
   if (reconcileNeeded) {
     await requestEntityCanonicalIdReconcile(journalStateDir);
   }
+  };
+  const firstEntityId = capsuleEntityIds.values().next().value;
+  if (firstEntityId === undefined) {
+    await applyRecords();
+  } else {
+    await withRawEntityPageMutation(
+      rootReal,
+      path.join(rootReal, "entities", `${firstEntityId}.md`),
+      applyRecords,
+    );
+  }
 
   // Sort output lists for determinism.
   merged.sort((a, b) => a.sourcePath.localeCompare(b.sourcePath));

package/src/trust-score-recall-paths.test.ts

@@ -61,6 +61,7 @@ async function writeFact(
   memoryDir: string,
   body: string,
   extraFrontmatterLines: string[] = [],
+  updatedAt = new Date().toISOString(),
 ): Promise<string> {
   const today = new Date().toISOString().slice(0, 10);
   const id = `fact-${Date.now()}-${Math.random().toString(36).slice(2)}`;
@@ -69,7 +70,7 @@ async function writeFact(
     `id: ${id}`,
     "category: fact",
     `created: ${new Date().toISOString()}`,
-    `updated: ${new Date().toISOString()}`,
+    `updated: ${updatedAt}`,
     "source: extraction",
     "confidence: 0.8",
     "confidenceTier: high",
@@ -152,6 +153,79 @@ test("TrustScore quarantine excludes a contradicted memory from injection but su
       typeof quarantined!.trust!.quarantineReason === "string" && quarantined!.trust!.quarantineReason.length > 0,
       "quarantined result carries a human-readable reason",
     );
+    assert.ok(
+      snapshot!.appliedResults.some((result) => result.memoryId === goodId),
+      "the applied witness includes the memory that reached published recall",
+    );
+    assert.equal(
+      snapshot!.appliedResults.some((result) => result.memoryId === badId),
+      false,
+      "the applied witness excludes a candidate removed before the result-limit partition",
+    );
+    assert.equal(
+      snapshot!.headroomResults.some((result) => result.memoryId === badId),
+      false,
+      "the headroom witness excludes quarantined candidates",
+    );
+  } finally {
+    await orchestrator.destroy();
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("X-ray capture preserves recent-scan serving while recording post-trust applied and pre-trust headroom", async () => {
+  const { orchestrator, memoryDir } = await makeOrchestrator({
+    qmdMaxResults: 2,
+  });
+  const now = Date.now();
+  try {
+    const tailId = await writeFact(
+      memoryDir,
+      "Parity recall token: stable tail candidate.",
+      ["mw_success: 5", "mw_fail: 0"],
+      new Date(now - 3_000).toISOString(),
+    );
+    const quarantinedId = await writeFact(
+      memoryDir,
+      "Parity recall token: contradicted applied candidate.",
+      ['faithfulness: {"verdict":"contradicted"}'],
+      new Date(now - 2_000).toISOString(),
+    );
+    const servedId = await writeFact(
+      memoryDir,
+      "Parity recall token: verified served candidate.",
+      ["mw_success: 5", "mw_fail: 0"],
+      new Date(now - 1_000).toISOString(),
+    );
+
+    const withoutCapture = await orchestrator.recall(
+      "parity recall token",
+      "sess-trust-parity",
+      { mode: "full" },
+    );
+    const withCapture = await orchestrator.recall(
+      "parity recall token",
+      "sess-trust-parity",
+      { mode: "full", xrayCapture: true },
+    );
+    const snapshot = orchestrator.getLastXraySnapshot();
+
+    assert.equal(withCapture, withoutCapture);
+    assert.match(withCapture, /verified served candidate/);
+    assert.doesNotMatch(withCapture, /contradicted applied candidate|stable tail candidate/);
+    assert.ok(snapshot);
+    assert.deepEqual(
+      snapshot.appliedResults.map((result) => result.memoryId),
+      [servedId],
+    );
+    assert.deepEqual(
+      snapshot.headroomResults.map((result) => result.memoryId),
+      [tailId],
+    );
+    assert.equal(
+      snapshot.appliedResults.some((result) => result.memoryId === quarantinedId),
+      false,
+    );
   } finally {
     await orchestrator.destroy();
     await rm(memoryDir, { recursive: true, force: true });

package/src/types.ts

@@ -4,6 +4,7 @@ import type { ActivityConfig } from "./activity/types.js";
 import type { WearablesConfig } from "./wearables/types.js";
 import type { ExtractionLivenessConfig } from "./extraction-liveness.js";
 import type { ReplicaPeersConfig } from "./replica-peers-config.js";
+import type { ExternalWikiRoot } from "./external-wiki-config.js";
 
 import type { BufferTurnOwner } from "./buffer-turn-helpers.js";
 export type ReasoningEffort = "none" | "low" | "medium" | "high";
@@ -733,6 +734,7 @@ export interface PluginConfig extends BoundedJsonlStateConfig {
   memoryOsPreset?: MemoryOsPresetName;
   qmdEnabled: boolean;
   qmdCollection: string;
+  wikiMergeIntoRecall: boolean;
   qmdMaxResults: number;
   qmdEmbeddingBacklogThreshold: number;
   qmdColdTierEnabled?: boolean;
@@ -751,11 +753,8 @@ export interface PluginConfig extends BoundedJsonlStateConfig {
   qmdChunkStrategy: "auto" | "regex";
   qmdCandidateLimit?: number;
   qmdQueryRerankEnabled: boolean;
-  // Daemon search plan; "hybrid" (default) = lex+vec+hyde. Issue #1335.
   qmdSearchStrategy: "hybrid" | "lex-vec" | "lex";
-  // Subprocess fallback command; "query" (default) keeps LLM expansion. Issue #1335.
   qmdSubprocessStrategy: "query" | "search";
-  // Per-call daemon search timeout in ms; default 8000. Issue #1335.
   qmdDaemonTimeoutMs: number;
   qmdIndexName?: string;
   qmdForceCpu: boolean;
@@ -785,6 +784,7 @@ export interface PluginConfig extends BoundedJsonlStateConfig {
   /** Optional absolute path to qmd binary. If unset, PATH/fallback discovery is used. */
   qmdPath?: string;
   memoryDir: string;
+  externalWikis: ExternalWikiRoot[];
   debug: boolean;
   identityEnabled: boolean;
   identityContinuityEnabled: boolean;
@@ -2788,6 +2788,8 @@ export interface ImportanceScore {
 }
 
 export interface MemoryFrontmatter extends SourceConnectorProvenance {
+  /** True when write-time classification ties this memory to its source connector's tools or commands. */
+  toolScoped?: true;
   id: string;
   category: MemoryCategory;
   created: string;
@@ -3329,6 +3331,8 @@ export interface ExtractionResult {
   extractionFailure?: string;
   /** Coarse class used by the retry/backoff + circuit-breaker layer (extraction hot loop). */
   extractionFailureClass?: ExtractionFailureClass;
+  /** Local prefilter reason; no provider extraction was attempted. */
+  extractionSkippedReason?: "conversation_only_non_memory" | "mechanical_telemetry";
   /** Trusted source connector resolved over boundedTurns; persisted verbatim by the orchestrator so it is not recomputed (#2183). */
   sourceConnector?: string;
 }

package/dist/capsule-merge-IDWJPCWK.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/transfer/capsule-merge.ts"],"sourcesContent":["import { lstat, mkdir, readFile, realpath, stat, unlink, writeFile } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { gunzipSync } from \"node:zlib\";\nimport { bumpMemoryCorpusVersionForDir } from \"../memory-corpus-version.js\";\nimport {\n  HistoricalEntityCanonicalIdCache,\n  canonicalizeEntityRefFrontmatter,\n  readEntityRefFromFrontmatter,\n  classifyEntityRefWritePath,\n  repairContentAfterJournalMove,\n  requestEntityCanonicalIdReconcile,\n} from \"../storage/entity-canonical-id-references.js\";\nimport {\n  createVersion,\n  type VersioningConfig,\n  type VersioningLogger,\n} from \"../page-versioning.js\";\nimport {\n  assertIsDirectoryNotSymlink,\n  assertRealpathInsideRoot,\n  fromPosixRelPath,\n  isPathInsideRoot,\n  sha256String,\n} from \"./fs-utils.js\";\nimport {\n  parseExportBundle,\n  type CapsuleBlock,\n  type ExportManifestV2,\n  type ExportMemoryRecordV1,\n} from \"./types.js\";\n\n/**\n * Three-way conflict-resolution mode for {@link mergeCapsule}.\n *\n * A \"conflict\" is defined as: the same memory-file path exists in both the\n * source archive and the target directory AND the content hash of the local\n * file differs from the archive's manifest entry for that path.\n *\n * Files that exist only in the archive (no local counterpart) are always\n * written regardless of mode — there is no conflict to resolve.\n *\n * Files that are byte-identical (same content hash in both locations) are\n * recorded as {@link MergeCapsuleResult.skipped} with reason `\"identical\"` and\n * are never re-written regardless of mode; this is a no-op optimisation rather\n * than a conflict.\n *\n *  - `\"skip-conflicts\"` (default) — log the conflict, skip the conflicting\n *    archive entries, but continue importing non-conflicting entries. The\n *    resulting merge is the union of:\n *      - all non-conflicting archive files (written to target)\n *      - all pre-existing local files (left unchanged)\n *\n *  - `\"prefer-source\"` — for conflicting files, snapshot the local content via\n *    page-versioning (gotcha #54: snapshot before overwrite) then overwrite\n *    with the archive content.\n *\n *  - `\"prefer-local\"` — for conflicting files, keep the local content; the\n *    archive entry is skipped.\n */\nexport type MergeCapsuleConflictMode =\n  | \"skip-conflicts\"\n  | \"prefer-source\"\n  | \"prefer-local\";\n\n/**\n * Options accepted by {@link mergeCapsule}.\n *\n * `sourceArchive` — absolute or cwd-relative path to a `.capsule.json.gz`\n * archive produced by `exportCapsule`. Must be a V2 bundle.\n *\n * `targetRoot` — absolute or cwd-relative path to the memory directory that\n * receives the merged records. Must be an existing, non-symlink directory.\n *\n * `conflictMode` — see {@link MergeCapsuleConflictMode}. Defaults to\n * `\"skip-conflicts\"`.\n *\n * `versioning` — optional page-versioning config forwarded to\n * {@link createVersion} in `\"prefer-source\"` mode. When omitted or disabled,\n * overwrites proceed without snapshotting (not recommended for production).\n *\n * `log` — optional logger forwarded to {@link createVersion}.\n */\nexport interface MergeCapsuleOptions {\n  sourceArchive: string;\n  targetRoot: string;\n  conflictMode?: MergeCapsuleConflictMode;\n  versioning?: VersioningConfig;\n  log?: VersioningLogger;\n}\n\nexport interface MergeCapsuleWrittenRecord {\n  /** Capsule-relative posix path. */\n  sourcePath: string;\n  /** Memory-dir-relative posix path written on disk. */\n  targetPath: string;\n  /** Whether a page-versioning snapshot was taken before overwriting. */\n  snapshotted: boolean;\n}\n\nexport interface MergeCapsuleSkippedRecord {\n  /** Capsule-relative posix path. */\n  path: string;\n  /**\n   * Why the archive entry was not written.\n   *\n   * `\"conflict\"` — the entry existed locally with different content and the\n   * active mode did not resolve the conflict with a write (`\"skip-conflicts\"` /\n   * `\"prefer-local\"`).\n   *\n   * `\"identical\"` — the entry's content hash matches what is already on disk;\n   * no write is needed.\n   */\n  reason: \"conflict\" | \"identical\";\n}\n\nexport interface MergeCapsuleConflictRecord {\n  /** Capsule-relative posix path of the conflicting entry. */\n  path: string;\n  /** SHA-256 of the archive's copy. */\n  archiveSha256: string;\n  /** SHA-256 of the local copy. */\n  localSha256: string;\n}\n\nexport interface MergeCapsuleResult {\n  /** Records that were written to the target directory. */\n  merged: MergeCapsuleWrittenRecord[];\n  /**\n   * Records that were NOT written (conflict skipped, or byte-identical).\n   * Includes conflicts that were resolved by `\"prefer-local\"`.\n   */\n  skipped: MergeCapsuleSkippedRecord[];\n  /**\n   * Metadata about every detected conflict, regardless of which mode resolved\n   * it. Callers can use this to report \"N conflicts encountered; M overwritten\".\n   */\n  conflicts: MergeCapsuleConflictRecord[];\n  /** The manifest decoded from the archive. */\n  manifest: ExportManifestV2;\n}\n\n// ---------------------------------------------------------------------------\n// Main entry point\n// ---------------------------------------------------------------------------\n\n/**\n * Merge a V2 capsule archive into an existing memory directory using\n * three-way conflict semantics.\n *\n * Sequence:\n *   1. Read + gunzip + JSON.parse the archive.\n *   2. Validate through `parseExportBundle` (V1 rejected).\n *   3. Verify every record's content sha256 against the manifest.\n *      Any mismatch aborts BEFORE any file is written (gotcha #25).\n *   4. Classify each record as: new (no local copy), identical (same hash),\n *      or conflicting (different hash).\n *   5. Apply the selected {@link MergeCapsuleConflictMode} to conflicting\n *      entries; always write new entries; always skip identical entries.\n *\n * Determinism: `merged`, `skipped`, and `conflicts` are all returned sorted\n * by `path`/`sourcePath` so callers get stable output regardless of bundle\n * order.\n */\nexport async function mergeCapsule(\n  opts: MergeCapsuleOptions,\n): Promise<MergeCapsuleResult> {\n  const archiveAbs = path.resolve(opts.sourceArchive);\n  const rootAbs = path.resolve(opts.targetRoot);\n\n  await assertIsDirectoryNotSymlink(rootAbs, \"mergeCapsule\", \"targetRoot\");\n\n  const conflictMode: MergeCapsuleConflictMode =\n    opts.conflictMode ?? \"skip-conflicts\";\n\n  // Rule 51: reject invalid conflictMode values up-front before any I/O.\n  if (\n    conflictMode !== \"skip-conflicts\" &&\n    conflictMode !== \"prefer-source\" &&\n    conflictMode !== \"prefer-local\"\n  ) {\n    throw new Error(\n      `mergeCapsule: unknown conflictMode ${JSON.stringify(conflictMode)}; ` +\n        `expected \"skip-conflicts\", \"prefer-source\", or \"prefer-local\"`,\n    );\n  }\n\n  // ---------------------------------------------------------------------------\n  // Parse + validate archive\n  // ---------------------------------------------------------------------------\n\n  const raw = await readFile(archiveAbs);\n  let json: string;\n  try {\n    json = gunzipSync(raw).toString(\"utf-8\");\n  } catch (cause) {\n    throw new Error(\n      `mergeCapsule: archive is not a valid gzip file: ${archiveAbs}`,\n      { cause: cause as Error },\n    );\n  }\n\n  let parsedJson: unknown;\n  try {\n    parsedJson = JSON.parse(json);\n  } catch (cause) {\n    throw new Error(\n      `mergeCapsule: archive is not valid JSON after gunzip: ${archiveAbs}`,\n      { cause: cause as Error },\n    );\n  }\n\n  const parsed = parseExportBundle(parsedJson);\n  if (parsed.capsuleVersion !== 2) {\n    throw new Error(\n      \"mergeCapsule: archive is V1; only V2 capsule archives are supported\",\n    );\n  }\n\n  const bundle = parsed.bundle as {\n    manifest: ExportManifestV2;\n    records: ExportMemoryRecordV1[];\n  };\n  const manifest = bundle.manifest;\n  const capsule = manifest.capsule;\n\n  // Build path → manifest entry index for O(1) checksum lookup.\n  const manifestIndex = new Map<string, ExportManifestV2[\"files\"][number]>();\n  for (const f of manifest.files) {\n    manifestIndex.set(f.path, f);\n  }\n  if (manifestIndex.size !== manifest.files.length) {\n    throw new Error(\"mergeCapsule: manifest contains duplicate file paths\");\n  }\n\n  const recordPaths = new Set<string>();\n  for (const rec of bundle.records) {\n    if (recordPaths.has(rec.path)) {\n      throw new Error(\n        `mergeCapsule: bundle contains duplicate record path: ${rec.path}`,\n      );\n    }\n    recordPaths.add(rec.path);\n  }\n\n  // ---------------------------------------------------------------------------\n  // Phase 1: verify checksums + validate paths before ANY filesystem mutation.\n  // (gotcha #25: don't destroy old state before confirming new state succeeds)\n  // ---------------------------------------------------------------------------\n\n  const rootReal = await realpath(rootAbs).catch(() => rootAbs);\n\n  // Tracks normalized, case-folded target paths seen so far in phase 1.  Maps\n  // targetAbs.toLowerCase() → first source path so the collision error can name\n  // both offending entries.  Two manifest entries whose computed target paths\n  // normalise to the same absolute path (e.g. `subdir/file.md` and\n  // `subdir/./file.md`, or differing case on case-insensitive filesystems such\n  // as macOS and Windows) would both refer to the same inode.  In\n  // `skip-conflicts`/`prefer-local` modes one entry would be misclassified as a\n  // local conflict against the OTHER entry's just-written content; in\n  // `prefer-source` the second entry would silently overwrite the first.  We\n  // reject the import up-front before any write (Codex P2 thread on PR #748,\n  // mirroring `capsule-import.ts`).\n  const seenTargetPaths = new Map<string, string>();\n\n  for (const rec of bundle.records) {\n    // Checksum validation.\n    const entry = manifestIndex.get(rec.path);\n    if (!entry) {\n      throw new Error(\n        `mergeCapsule: archive checksum mismatch (record without manifest entry: ${rec.path})`,\n      );\n    }\n    const { sha256, bytes } = sha256String(rec.content);\n    if (sha256 !== entry.sha256 || bytes !== entry.bytes) {\n      throw new Error(\n        `mergeCapsule: archive checksum mismatch for ${rec.path}: ` +\n          `expected sha256=${entry.sha256} bytes=${entry.bytes}, ` +\n          `got sha256=${sha256} bytes=${bytes}`,\n      );\n    }\n\n    // Path-traversal validation (mirrors capsule-import.ts).\n    if (rec.path.includes(\"\\\\\")) {\n      throw new Error(\n        `mergeCapsule: record path contains backslash separators (Windows-style paths are not allowed): ${rec.path}`,\n      );\n    }\n    const posixNormalized = path.posix.normalize(rec.path);\n    if (\n      rec.path.startsWith(\"/\") ||\n      rec.path.split(\"/\").some((seg) => seg === \"..\") ||\n      posixNormalized.startsWith(\"..\") ||\n      posixNormalized.startsWith(\"/\")\n    ) {\n      throw new Error(\n        `mergeCapsule: record path escapes target root: ${rec.path}`,\n      );\n    }\n\n    // Lexical root containment check.\n    const targetAbs = path.join(rootReal, fromPosixRelPath(rec.path));\n    if (!isPathInsideRoot(rootReal, targetAbs)) {\n      throw new Error(\n        `mergeCapsule: record path escapes target root: ${rec.path}`,\n      );\n    }\n\n    // Symlink-aware containment check (shared helper from fs-utils).\n    await assertRealpathInsideRoot(rootReal, targetAbs, rec.path, \"mergeCapsule\");\n\n    // Target-file symlink guard: if the target already exists as a symlink,\n    // reject — writes through symlinks can redirect to unexpected locations.\n    const targetLstat = await lstat(targetAbs).catch(() => null);\n    if (targetLstat !== null && targetLstat.isSymbolicLink()) {\n      throw new Error(\n        `mergeCapsule: record target is a symlink and cannot be written to safely: ${rec.path}`,\n      );\n    }\n\n    // Duplicate normalized target path detection (Codex P2 #748, mirrors\n    // capsule-import.ts).  `path.join` already normalises `.` segments\n    // (e.g. `subdir/./file.md` → `subdir/file.md`).  On case-insensitive\n    // filesystems (macOS default, Windows), two paths that differ only in case\n    // would resolve to the same inode.  We fold the dedup key to lowercase so\n    // that `subdir/File.md` and `subdir/file.md` are detected as duplicates\n    // before any write occurs.  This is intentionally unconditional: the cost\n    // of an extra `.toLowerCase()` on case-sensitive filesystems is negligible,\n    // and a defensive lowercase is far simpler than probing filesystem\n    // case-sensitivity at runtime.  Without this guard, prefer-source mode\n    // would silently overwrite one entry with the other, and skip-conflicts /\n    // prefer-local would misclassify the second entry as a local conflict\n    // against the first entry's freshly written content.\n    const dedupKey = targetAbs.toLowerCase();\n    const firstSourcePath = seenTargetPaths.get(dedupKey);\n    if (firstSourcePath !== undefined) {\n      throw new Error(\n        `mergeCapsule: manifest contains two entries that resolve to the same target path: ` +\n          `\"${firstSourcePath}\" and \"${rec.path}\" both map to \"${rec.path}\"`,\n      );\n    }\n    seenTargetPaths.set(dedupKey, rec.path);\n  }\n\n  // Detect manifest-only entries (missing record). Treat as corruption.\n  for (const f of manifest.files) {\n    if (!recordPaths.has(f.path)) {\n      throw new Error(\n        `mergeCapsule: archive checksum mismatch (manifest entry without record: ${f.path})`,\n      );\n    }\n  }\n\n  // ---------------------------------------------------------------------------\n  // Phase 2: classify records and apply conflict mode.\n  // ---------------------------------------------------------------------------\n\n  const merged: MergeCapsuleWrittenRecord[] = [];\n  const skipped: MergeCapsuleSkippedRecord[] = [];\n  const conflicts: MergeCapsuleConflictRecord[] = [];\n  // Same write-boundary rule as capsule-import (issue #2213): records land\n  // with their entityRef resolved through the target's migration journal,\n  // read through the identity-keyed cache PER RECORD so a peer migration\n  // completing mid-merge is picked up for every record written after it.\n  const journalStateDir = path.join(rootReal, \"state\");\n  const historicalIdCache = new HistoricalEntityCanonicalIdCache();\n  // Entity pages in THIS capsule can re-establish collisions the target's\n  // journal already resolved (Codex P1): once the next migration parks the\n  // mapping, a memory canonicalized onto the canonical claimant is\n  // permanently misattributed. Memories whose ref targets a capsule-supplied\n  // entity id merge byte-faithful behind the reconcile marker instead.\n  const capsuleEntityIds = new Set(\n    bundle.records\n      .filter((record) =>\n        classifyEntityRefWritePath(rootReal, path.join(rootReal, fromPosixRelPath(record.path))) === \"entity\")\n      .map((record) => path.basename(record.path, \".md\")),\n  );\n  // Write a record with its entityRef resolved AT the write, then repair if\n  // the journal moved across the write itself — a parked mapping cannot be\n  // fixed after the fact by the reconcile pass (issue #2213). Only memory-tier\n  // records canonicalize; entities/ pages carry relationship TARGETS only\n  // rewriteRelationshipTargets understands, so they merge byte-faithful with\n  // a reconcile marker; everything else merges losslessly. The corpus bump\n  // lands AFTER the repair so a warm cache rescan never captures pre-repair\n  // bytes.\n  // The reconcile marker is published ONCE, after every record landed\n  // (Codex P1, round 21): a per-record marker could be consumed by a peer\n  // between a legacy-preserving memory write and its colliding entity page,\n  // canonicalizing the memory onto the wrong claimant irreversibly.\n  let reconcileNeeded = false;\n  const writeCanonicalRecord = async (targetAbs: string, rawContent: string): Promise<void> => {\n    const kind = classifyEntityRefWritePath(rootReal, targetAbs);\n    const rawRef = kind === \"memory\" ? readEntityRefFromFrontmatter(rawContent) : null;\n    if (kind === \"memory\" && rawRef !== null && capsuleEntityIds.has(rawRef)) {\n      // Ref targets a capsule-supplied entity page (potential collision\n      // claimant): keep the legacy bytes; the deferred marker lets the\n      // migration settle the collision and rewrite per its verdict (Codex P1).\n      await writeFile(targetAbs, rawContent, \"utf-8\");\n      reconcileNeeded = true;\n      bumpMemoryCorpusVersionForDir(rootReal); // per-write bump (Cursor Medium, #1902)\n      return;\n    }\n    if (kind !== \"memory\") {\n      await writeFile(targetAbs, rawContent, \"utf-8\");\n      if (kind === \"entity\") {\n        reconcileNeeded = true;\n      }\n      bumpMemoryCorpusVersionForDir(rootReal); // per-write bump (Cursor Medium, #1902)\n      return;\n    }\n    const idsAtWrite = historicalIdCache.get(journalStateDir);\n    const written = canonicalizeEntityRefFrontmatter(rawContent, idsAtWrite);\n    // Snapshot the pre-write bytes: a repair failure after the write must\n    // restore them (or remove a newly created target) before propagating —\n    // the merge reports failure, so disk must return to its pre-write state\n    // and warm caches stay consistent (AGENTS.md §14).\n    const originalBytes = await readLocalFile(targetAbs);\n    await writeFile(targetAbs, written, \"utf-8\");\n    try {\n      await repairContentAfterJournalMove({\n        stateDir: journalStateDir,\n        cache: historicalIdCache,\n        idsAtWrite,\n        rawContent,\n        lastWritten: written,\n        rewrite: (content) => writeFile(targetAbs, content, \"utf-8\"),\n      });\n    } catch (err) {\n      if (originalBytes === null) {\n        await unlink(targetAbs).catch(() => undefined);\n      } else {\n        await writeFile(targetAbs, originalBytes, \"utf-8\").catch(() => undefined);\n      }\n      throw err;\n    }\n    bumpMemoryCorpusVersionForDir(rootReal); // per-write bump (Cursor Medium, #1902)\n  };\n\n  // Sort by source path for deterministic output (mirrors capsule-import.ts).\n  const sortedRecords = [...bundle.records].sort((a, b) =>\n    a.path.localeCompare(b.path),\n  );\n\n  for (const rec of sortedRecords) {\n    const targetAbs = path.join(rootReal, fromPosixRelPath(rec.path));\n    const entry = manifestIndex.get(rec.path)!; // validated above\n\n    const localContent = await readLocalFile(targetAbs);\n\n    if (localContent === null) {\n      // No local copy — always write regardless of mode. Resolve at the write\n      // itself and verify the journal afterwards: a peer migration completing\n      // during any of these awaits (or the write) would otherwise strand the\n      // reference — capsule writes bump only the corpus version, which the\n      // migration fingerprint deliberately ignores.\n      await mkdir(path.dirname(targetAbs), { recursive: true });\n      await writeCanonicalRecord(targetAbs, rec.content);\n      merged.push({ sourcePath: rec.path, targetPath: rec.path, snapshotted: false });\n      continue;\n    }\n\n    // Local file exists. A local copy already holding the CANONICALIZED form\n    // (computed AFTER the local read, so a journal published during that\n    // await is reflected) is done. A local copy matching the RAW archive\n    // bytes while a mapping applies is UPGRADED in place — skipping would\n    // leave the legacy entityRef on disk forever, since corpus bumps no\n    // longer trigger migration rewrites (issue #2213).\n    const idsAtCompare = historicalIdCache.get(journalStateDir);\n    const compareRef = readEntityRefFromFrontmatter(rec.content);\n    const canonicalContent =\n      classifyEntityRefWritePath(rootReal, targetAbs) === \"memory\"\n      && !(compareRef !== null && capsuleEntityIds.has(compareRef))\n        ? canonicalizeEntityRefFrontmatter(rec.content, idsAtCompare)\n        : rec.content;\n    const { sha256: localSha256 } = sha256String(localContent);\n    const canonicalSha256 =\n      canonicalContent === rec.content ? entry.sha256 : sha256String(canonicalContent).sha256;\n\n    // The identical verdict is only valid for the snapshot it was computed\n    // under (Codex P1): a mapping parked/removed mid-compare can make the\n    // local copy's formerly-canonical ref stale with nothing left to repair\n    // it. A moved journal falls through to the write path, which resolves at\n    // the write and repairs after it.\n    if (localSha256 === canonicalSha256 && historicalIdCache.get(journalStateDir) === idsAtCompare) {\n      skipped.push({ path: rec.path, reason: \"identical\" });\n      continue;\n    }\n    if (localSha256 === canonicalSha256 || localSha256 === entry.sha256) {\n      await writeCanonicalRecord(targetAbs, rec.content);\n      merged.push({ sourcePath: rec.path, targetPath: rec.path, snapshotted: false });\n      continue;\n    }\n\n    // Content differs → conflict.\n    const { sha256: archiveSha256 } = sha256String(rec.content);\n    conflicts.push({\n      path: rec.path,\n      archiveSha256,\n      localSha256,\n    });\n\n    if (conflictMode === \"skip-conflicts\" || conflictMode === \"prefer-local\") {\n      // Keep local copy, skip archive entry.\n      skipped.push({ path: rec.path, reason: \"conflict\" });\n      continue;\n    }\n\n    // conflictMode === \"prefer-source\": snapshot local then overwrite.\n    let snapshotted = false;\n    if (opts.versioning && opts.versioning.enabled) {\n      // Gotcha #54: snapshot BEFORE overwriting.\n      await createVersion(\n        targetAbs,\n        localContent,\n        \"manual\",\n        opts.versioning,\n        opts.log,\n        `capsule-merge: ${capsule.id}`,\n        rootReal,\n      );\n      snapshotted = true;\n    }\n\n    // Same write-time re-resolve + post-write repair as above — the\n    // snapshot/read awaits give a peer migration a real window.\n    await writeCanonicalRecord(targetAbs, rec.content);\n    merged.push({ sourcePath: rec.path, targetPath: rec.path, snapshotted });\n  }\n\n  // Every record — including every collision claimant entity page — is on\n  // disk; NOW the reconcile pass can settle collisions safely.\n  if (reconcileNeeded) {\n    await requestEntityCanonicalIdReconcile(journalStateDir);\n  }\n\n  // Sort output lists for determinism.\n  merged.sort((a, b) => a.sourcePath.localeCompare(b.sourcePath));\n  skipped.sort((a, b) => a.path.localeCompare(b.path));\n  conflicts.sort((a, b) => a.path.localeCompare(b.path));\n\n  // Per-write corpus bumps happen inside the loop above (Cursor Medium, #1902):\n  // a concurrent readAllMemories during the merge rescans and never serves the\n  // pre-merge corpus mid-batch.\n\n  return { merged, skipped, conflicts, manifest };\n}\n\n// ---------------------------------------------------------------------------\n// Private helpers\n// ---------------------------------------------------------------------------\n\nasync function readLocalFile(absPath: string): Promise<string | null> {\n  const st = await stat(absPath).catch(() => null);\n  if (!st || !st.isFile()) return null;\n  return readFile(absPath, \"utf-8\");\n}\n\n// Re-export CapsuleBlock so callers don't need a deep import from types.ts.\nexport type { CapsuleBlock };\n"],"mappings":"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","names":[]}

package/dist/chunk-3CE77VAP.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/transfer/capsule-import.ts"],"sourcesContent":["import { lstat, mkdir, readFile, realpath, stat, unlink, writeFile } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { createHash, randomUUID } from \"node:crypto\";\nimport { gunzipSync } from \"node:zlib\";\nimport { bumpMemoryCorpusVersionForDir } from \"../memory-corpus-version.js\";\nimport {\n  HistoricalEntityCanonicalIdCache,\n  readEntityRefFromFrontmatter,\n  canonicalizeEntityRefFrontmatter,\n  classifyEntityRefWritePath,\n  repairContentAfterJournalMove,\n  requestEntityCanonicalIdReconcile,\n} from \"../storage/entity-canonical-id-references.js\";\nimport {\n  createVersion,\n  type VersioningConfig,\n  type VersioningLogger,\n} from \"../page-versioning.js\";\nimport {\n  assertIsDirectoryNotSymlink,\n  assertRealpathInsideRoot,\n  fromPosixRelPath,\n  isPathInsideRoot,\n  sha256String,\n} from \"./fs-utils.js\";\nimport {\n  parseExportBundle,\n  type CapsuleBlock,\n  type ExportManifestV2,\n  type ExportMemoryRecordV1,\n} from \"./types.js\";\nimport { isEncryptedCapsuleFile, decryptCapsuleFileInMemory } from \"./capsule-crypto.js\";\n\n/**\n * Conflict-resolution mode for {@link importCapsule}. Inverse of the\n * `mode` selector in PR 4/6's CLI surface.\n *\n *  - `\"skip\"` (default) — when a target file already exists at the same\n *    relative path, leave it untouched. The corresponding record is reported\n *    via {@link ImportCapsuleResult.skipped}.\n *  - `\"overwrite\"` — when a target file exists, snapshot the prior content\n *    via {@link createVersion} (gotcha #54: write-before-delete; gotcha #25:\n *    don't destroy old state until new state is confirmed), then write the\n *    incoming content. The snapshot's `note` includes the source capsule id.\n *  - `\"fork\"` — never overwrite. Every record is rebased under\n *    `forks/<capsule-id>/<original-path>` and any YAML-frontmatter `id:`\n *    field is rewritten to a new fork-scoped value. The original tree is\n *    not touched.\n *\n * The mode is selected once per call and applied uniformly to every record\n * in the bundle. Mixed-mode imports are not supported by design — that\n * would let a single corrupted manifest silently land partial state.\n */\nexport type ImportCapsuleMode = \"skip\" | \"overwrite\" | \"fork\";\n\n/**\n * Options accepted by {@link importCapsule}.\n *\n * `archivePath` — absolute or cwd-relative path to a `.capsule.json.gz`\n * archive produced by `exportCapsule`. The archive must contain a V2\n * bundle (`schemaVersion: 2`); V1 archives are rejected.\n *\n * `root` — absolute or cwd-relative path to the memory directory that\n * will receive the records. Must be an existing directory.\n *\n * `mode` — see {@link ImportCapsuleMode}. Defaults to `\"skip\"`.\n *\n * `versioning` — optional page-versioning config used by `mode: \"overwrite\"`\n * to snapshot prior content before replacing it. Snapshots are skipped when\n * not provided or when `enabled === false`. Tests pass an enabled config\n * to assert snapshot creation; production callers thread the\n * orchestrator's resolved versioning config.\n *\n * `log` — optional logger forwarded to {@link createVersion}.\n *\n * `now` — optional clock override (ms epoch) used to derive deterministic\n * fork ids in tests. Production callers omit this.\n */\nexport interface ImportCapsuleOptions {\n  archivePath: string;\n  root: string;\n  mode?: ImportCapsuleMode;\n  versioning?: VersioningConfig;\n  log?: VersioningLogger;\n  now?: number;\n  /**\n   * Memory directory whose secure-store keyring is used when the archive is\n   * encrypted. Required when `archivePath` ends with `.enc` or when the file\n   * starts with the REMNIC-ENC magic header. If `memoryDir` is omitted and the\n   * archive turns out to be encrypted, `importCapsule` throws a clear error\n   * rather than silently failing.\n   *\n   * When provided and the archive is NOT encrypted, the value is ignored.\n   */\n  memoryDir?: string;\n  /**\n   * Original secure-store passphrase for encrypted format-v2 archives. When\n   * supplied, the importer derives the archive key from the embedded KDF\n   * header, enabling restore without the source machine's unlocked keyring.\n   */\n  passphrase?: string;\n}\n\nexport interface ImportCapsuleSkippedRecord {\n  /** Original record path (capsule-relative, posix). */\n  path: string;\n  /**\n   * Why this record was not written.\n   *\n   * `\"exists\"` — the target path already existed and the mode was `\"skip\"`,\n   * OR the computed fork path already existed in fork mode.\n   *\n   * `\"checksum_mismatch\"` is intentionally absent: a checksum failure aborts\n   * the import entirely (fail-closed) rather than skipping the offending\n   * record, so no `ImportCapsuleSkippedRecord` is ever produced for it.\n   */\n  reason: \"exists\";\n}\n\nexport interface ImportCapsuleImportedRecord {\n  /** Capsule-relative posix path the record carried. */\n  sourcePath: string;\n  /** Memory-dir-relative posix path the file was written to. */\n  targetPath: string;\n  /** Whether a prior version snapshot was taken (overwrite-mode only). */\n  snapshotted: boolean;\n  /** Whether the frontmatter `id:` field was rewritten (fork-mode only). */\n  rewroteId: boolean;\n}\n\nexport interface ImportCapsuleResult {\n  /** Records that landed on disk. */\n  imported: ImportCapsuleImportedRecord[];\n  /** Records that were not written. */\n  skipped: ImportCapsuleSkippedRecord[];\n  /** The manifest decoded from the archive. */\n  manifest: ExportManifestV2;\n}\n\n/**\n * Pure async function that imports a capsule archive into a memory\n * directory. Inverse of {@link import(\"./capsule-export.js\").exportCapsule}.\n *\n * Sequence:\n *   1. Read + gunzip + JSON.parse the archive.\n *   2. Validate the bundle through `parseExportBundle` (V1 rejected).\n *   3. Verify each record's content sha256 against the manifest entry.\n *      Any mismatch aborts the import BEFORE any file is written —\n *      partial-write recovery would require a full rollback we cannot\n *      offer cheaply, so we fail closed (gotcha #25).\n *   4. Apply the selected {@link ImportCapsuleMode} to every record.\n *\n * Determinism guarantees:\n *  - Imported records are returned sorted by `sourcePath`.\n *  - Skipped records are returned sorted by `path`.\n *  - Fork-mode rebases under a stable `forks/<capsule-id>/` prefix so\n *    repeated fork imports of the same capsule shape land in predictable\n *    locations (subsequent fork imports still skip-on-exist because the\n *    target tree is computed from the source path).\n */\nexport async function importCapsule(\n  opts: ImportCapsuleOptions,\n): Promise<ImportCapsuleResult> {\n  const archiveAbs = path.resolve(opts.archivePath);\n  const rootAbs = path.resolve(opts.root);\n  await assertIsDirectoryNotSymlink(rootAbs, \"importCapsule\", \"root\");\n\n  const mode: ImportCapsuleMode = opts.mode ?? \"skip\";\n  // Reject unknown mode values up-front (rule 51). TypeScript callers get a\n  // compile-time check via the union type; JS/CLI callers get a runtime error\n  // here before any write begins — not a silent destructive fallback.\n  if (mode !== \"skip\" && mode !== \"overwrite\" && mode !== \"fork\") {\n    throw new Error(\n      `importCapsule: unknown mode ${JSON.stringify(mode)}; expected \"skip\", \"overwrite\", or \"fork\"`,\n    );\n  }\n\n  // Auto-detect encrypted archives. If the file ends with `.enc` or starts\n  // with the REMNIC-ENC magic header, decrypt it first before gunzip+parse.\n  // Rule 48: default is \"not encrypted\"; we only attempt decryption when the\n  // header is definitively present, never on ambiguous content.\n  const encrypted = await isEncryptedCapsuleFile(archiveAbs);\n  let raw: Buffer;\n  if (encrypted) {\n    if (!opts.memoryDir && !opts.passphrase) {\n      throw new Error(\n        `importCapsule: archive is encrypted but 'memoryDir' was not provided. ` +\n          `Pass the memory directory so the secure-store key can be retrieved, ` +\n          `provide the original passphrase for a format-v2 archive restore, ` +\n          `or run \\`remnic secure-store unlock\\` before importing.`,\n      );\n    }\n    raw = await decryptCapsuleFileInMemory(archiveAbs, opts.memoryDir, {\n      passphrase: opts.passphrase,\n    });\n  } else {\n    raw = await readFile(archiveAbs);\n  }\n  const json = gunzipSync(raw).toString(\"utf-8\");\n  let parsedJson: unknown;\n  try {\n    parsedJson = JSON.parse(json);\n  } catch (cause) {\n    throw new Error(\n      `importCapsule: archive is not valid JSON after gunzip: ${archiveAbs}`,\n      { cause: cause as Error },\n    );\n  }\n\n  const parsed = parseExportBundle(parsedJson);\n  if (parsed.capsuleVersion !== 2) {\n    // PR 1/6 ships a V1 reader; capsule import is V2-only by design. A V1\n    // bundle does not carry a capsule block, so fork-mode (which depends on\n    // `capsule.id` for the rebase prefix) cannot work. Reject up-front per\n    // gotcha #51 instead of silently routing to a different code path.\n    throw new Error(\n      \"importCapsule: archive is V1; only V2 capsule archives are supported\",\n    );\n  }\n  const bundle = parsed.bundle as { manifest: ExportManifestV2; records: ExportMemoryRecordV1[] };\n  const manifest = bundle.manifest;\n  const capsule = manifest.capsule;\n\n  // Build a path → manifest-entry index for O(1) checksum lookup. The\n  // manifest is the source of truth; records-without-manifest-entries and\n  // manifest-entries-without-records are both treated as corruption.\n  const manifestIndex = new Map<string, ExportManifestV2[\"files\"][number]>();\n  for (const f of manifest.files) {\n    manifestIndex.set(f.path, f);\n  }\n  if (manifestIndex.size !== manifest.files.length) {\n    throw new Error(\n      \"importCapsule: manifest contains duplicate file paths\",\n    );\n  }\n  const recordPaths = new Set<string>();\n  for (const rec of bundle.records) {\n    if (recordPaths.has(rec.path)) {\n      throw new Error(\n        `importCapsule: bundle contains duplicate record path: ${rec.path}`,\n      );\n    }\n    recordPaths.add(rec.path);\n  }\n\n  // Phase 1: verify every record matches its manifest entry AND validate all\n  // target paths before any filesystem mutation.  We do both in a single pass\n  // so a corrupted or malicious archive cannot leave the memory dir partially\n  // written (fail-closed per gotcha #25).\n  //\n  // The real root is resolved once via realpath so the subsequent per-record\n  // inside-root checks are symlink-aware: a record path like `facts/a.md`\n  // cannot write outside the intended sandbox via a symlinked subdirectory\n  // (Codex P1 feedback).  If realpath fails (root does not exist) the earlier\n  // assertIsDirectoryNotSymlink call already threw, so this should always succeed.\n  const rootReal = await realpath(rootAbs).catch(() => rootAbs);\n\n  // Tracks normalized, case-folded target paths seen so far in phase 1.  Maps\n  // targetAbs.toLowerCase() → first source path so the collision error can name\n  // both offending entries.  Two manifest entries whose computed target paths\n  // normalize to the same absolute path (e.g. `subdir/file.md` and\n  // `subdir/./file.md`, or differing case on case-insensitive filesystems such\n  // as macOS and Windows) would both try to write the same inode — the second\n  // would silently overwrite the first.  We reject the import up-front before\n  // any write (Codex P2 thread on PR #741, line 283).\n  const seenTargetPaths = new Map<string, string>();\n\n  for (const rec of bundle.records) {\n    // Checksum validation.\n    const entry = manifestIndex.get(rec.path);\n    if (!entry) {\n      throw new Error(\n        `importCapsule: archive checksum mismatch (record without manifest entry: ${rec.path})`,\n      );\n    }\n    const { sha256, bytes } = sha256String(rec.content);\n    if (sha256 !== entry.sha256 || bytes !== entry.bytes) {\n      throw new Error(\n        `importCapsule: archive checksum mismatch for ${rec.path}: ` +\n          `expected sha256=${entry.sha256} bytes=${entry.bytes}, ` +\n          `got sha256=${sha256} bytes=${bytes}`,\n      );\n    }\n\n    // Source path validation: reject any record whose posix source path\n    // contains a `..` segment, an absolute prefix, or any component that would\n    // let fork-mode bypass its isolation invariant.  This check runs before\n    // `computeTargetPath` so that fork mode's `forks/<id>/` rebase cannot be\n    // bypassed by a path like `../../profile.md` (which `path.join` would\n    // silently collapse, landing the file inside root but outside the fork\n    // prefix — Cursor medium thread #741).  Rejecting `..` up-front is simpler\n    // and more robust than normalising after the fact.\n    //\n    // Extended guard (Codex P1 #741 round 5): also reject paths containing\n    // backslash separators (`\\`), which are Windows path separators. On Windows\n    // a path like `..\\\\escape.md` or `subdir\\\\..\\\\..\\\\escape.md` would resolve\n    // to a parent traversal but would bypass a purely posix-split check.\n    // Additionally, after posix-normalizing the path we re-check for a leading\n    // `..` or `/` — this catches edge-cases such as `subdir/../..` where the\n    // individual split segments are not `..` but the normalized result is.\n    if (rec.path.includes(\"\\\\\")) {\n      throw new Error(\n        `importCapsule: record path contains backslash separators (Windows-style paths are not allowed): ${rec.path}`,\n      );\n    }\n    const posixNormalized = path.posix.normalize(rec.path);\n    if (\n      rec.path.startsWith(\"/\") ||\n      rec.path.split(\"/\").some((seg) => seg === \"..\") ||\n      posixNormalized.startsWith(\"..\") ||\n      posixNormalized.startsWith(\"/\")\n    ) {\n      throw new Error(\n        `importCapsule: record path escapes target root: ${rec.path}`,\n      );\n    }\n\n    // Path-traversal validation (moved here from phase 2 per Cursor feedback:\n    // the traversal check must run before ANY write so a malicious archive\n    // with an escaping path that sorts last cannot land partial writes).\n    //\n    // We build targetAbs relative to the real-resolved root (rootReal) so\n    // that the inside-root check is symlink-aware: if `rootReal !== rootAbs`\n    // (the import root is itself behind a symlink), we still compare against\n    // the canonical path (Codex P1).\n    const targetRel = computeTargetPath(rec.path, mode, capsule.id);\n    const targetAbs = path.join(rootReal, fromPosixRelPath(targetRel));\n    if (!isPathInsideRoot(rootReal, targetAbs)) {\n      throw new Error(\n        `importCapsule: record path escapes target root: ${rec.path}`,\n      );\n    }\n\n    // Symlink-aware containment check (Cursor thread #741 line 247/264).\n    // The lexical check above handles `..`-traversal but cannot detect\n    // symlinked subdirectories that point outside the root. We resolve the\n    // nearest existing ancestor of the target via realpath to catch symlinks\n    // anywhere in the path components. If any resolved prefix escapes rootReal,\n    // the import is rejected before any write. This applies to ALL modes,\n    // including fork mode whose rebase prefix may itself traverse a symlink.\n    await assertRealpathInsideRoot(rootReal, targetAbs, rec.path, \"importCapsule\");\n\n    // Target-file symlink check (Codex P1 #741 round 4, line 260).\n    // `assertRealpathInsideRoot` resolves the nearest existing *ancestor* to\n    // catch symlinked parent directories, but if the TARGET FILE itself already\n    // exists and is a symlink, that check passes (the parent is real) while the\n    // write would silently follow the symlink to a path outside root.  We\n    // therefore lstat the target directly: if it exists and is a symlink we\n    // reject the record up-front.  For new files the parent-canonicalization\n    // performed above is sufficient; no realpath of a non-existent file is\n    // needed.\n    const targetLstat = await lstat(targetAbs).catch(() => null);\n    if (targetLstat !== null && targetLstat.isSymbolicLink()) {\n      throw new Error(\n        `importCapsule: record target is a symlink and cannot be written to safely: ${rec.path}`,\n      );\n    }\n\n    // Duplicate normalized target path detection (Codex P2 #741, line 283).\n    // `path.join` already normalises `.` segments (e.g. `subdir/./file.md` →\n    // `subdir/file.md`).  On case-insensitive filesystems (macOS default,\n    // Windows), two paths that differ only in case would resolve to the same\n    // inode.  We fold the dedup key to lowercase so that `subdir/File.md` and\n    // `subdir/file.md` are detected as duplicates before any write occurs.\n    // This is intentionally unconditional: the cost of an extra `.toLowerCase()`\n    // on case-sensitive filesystems is negligible, and a defensive lowercase\n    // is far simpler than probing filesystem case-sensitivity at runtime.\n    const dedupKey = targetAbs.toLowerCase();\n    const firstSourcePath = seenTargetPaths.get(dedupKey);\n    if (firstSourcePath !== undefined) {\n      throw new Error(\n        `importCapsule: manifest contains two entries that resolve to the same target path: ` +\n          `\"${firstSourcePath}\" and \"${rec.path}\" both map to \"${targetRel}\"`,\n      );\n    }\n    seenTargetPaths.set(dedupKey, rec.path);\n  }\n  // Detect manifest-only entries (missing record). Treat as corruption.\n  for (const f of manifest.files) {\n    if (!recordPaths.has(f.path)) {\n      throw new Error(\n        `importCapsule: archive checksum mismatch (manifest entry without record: ${f.path})`,\n      );\n    }\n  }\n\n  // Phase 2: apply the mode. All records were validated in phase 1; we now\n  // write to disk. Per-record errors propagate; each individual write is\n  // atomic (mkdir + writeFile pair).\n  const imported: ImportCapsuleImportedRecord[] = [];\n  const skipped: ImportCapsuleSkippedRecord[] = [];\n  // The target's completed migration journal is a write boundary here too\n  // (issue #2213): a capsule can carry pre-migration memories whose entityRef\n  // the target already renamed, and no recurring reconciliation pass exists\n  // to absorb a stale ref after the fact. Read through the identity-keyed\n  // cache PER RECORD so a peer migration completing mid-import is picked up\n  // for every record written after it (one lstat per record).\n  const journalStateDir = path.join(rootReal, \"state\");\n  const historicalIdCache = new HistoricalEntityCanonicalIdCache();\n  // Entity pages in THIS capsule can re-establish collisions the target's\n  // journal already resolved (Codex P1): once the next migration parks the\n  // mapping, a memory canonicalized onto the canonical claimant is\n  // permanently misattributed. Memories whose ref targets a capsule-supplied\n  // entity id import byte-faithful behind the reconcile marker instead; the\n  // migration settles the collision and rewrites references per its verdict.\n  const capsuleEntityIds = new Set(\n    bundle.records\n      .map((record) => computeTargetPath(record.path, mode, capsule.id))\n      .filter((rel) => classifyEntityRefWritePath(rootReal, path.join(rootReal, fromPosixRelPath(rel))) === \"entity\")\n      .map((rel) => path.basename(rel, \".md\")),\n  );\n\n  // Sort by source path so the imported/skipped lists are deterministic\n  // regardless of bundle order. (`exportCapsule` already sorts; we re-sort\n  // defensively in case a hand-edited archive ships records in another order.)\n  const sortedRecords = [...bundle.records].sort((a, b) =>\n    a.path.localeCompare(b.path),\n  );\n\n  // The reconcile marker is published ONCE, after every record landed\n  // (Codex P1, round 21): a per-record marker could be consumed by a peer\n  // between a legacy-preserving memory write and its colliding entity page,\n  // canonicalizing the memory onto the wrong claimant irreversibly.\n  let reconcileNeeded = false;\n  for (const rec of sortedRecords) {\n    const targetRel = computeTargetPath(rec.path, mode, capsule.id);\n    // Use rootReal (realpath-resolved) to stay consistent with phase 1's\n    // traversal validation and avoid writing through stale symlinks.\n    const targetAbs = path.join(rootReal, fromPosixRelPath(targetRel));\n\n    const exists = await fileExistsAt(targetAbs);\n\n    // Skip logic applies to both `skip` mode (explicit) and `fork` mode\n    // (Cursor medium: fork mode must also be skip-on-exist for the computed\n    // fork path, because production imports generate non-deterministic IDs —\n    // so re-importing the same capsule should not overwrite user edits in the\n    // fork tree or silently change file identities by generating new IDs).\n    if ((mode === \"skip\" || mode === \"fork\") && exists) {\n      skipped.push({ path: rec.path, reason: \"exists\" });\n      continue;\n    }\n\n    let snapshotted = false;\n    if (mode === \"overwrite\" && exists) {\n      // Gotcha #54: snapshot BEFORE overwriting. If snapshot creation fails\n      // we abort this record's import rather than silently destroying\n      // history. The page-versioning module is responsible for atomic\n      // sidecar writes; we just call it.\n      if (opts.versioning && opts.versioning.enabled) {\n        const prior = await readFile(targetAbs, \"utf-8\").catch(() => \"\");\n        await createVersion(\n          targetAbs,\n          prior,\n          \"manual\",\n          opts.versioning,\n          opts.log,\n          `capsule-import: ${capsule.id}`,\n          rootReal,\n        );\n        snapshotted = true;\n      }\n    }\n\n    let contentToWrite = rec.content;\n    let rewroteId = false;\n    if (mode === \"fork\") {\n      const forked = rewriteFrontmatterIdForFork(contentToWrite, capsule.id, opts.now);\n      contentToWrite = forked.content;\n      rewroteId = forked.rewrote;\n    }\n\n    await mkdir(path.dirname(targetAbs), { recursive: true });\n    // Resolve at the write itself (mirrors capsule-merge): a peer migration\n    // can complete during the snapshot/mkdir awaits, and capsule writes bump\n    // only the corpus version, which the migration fingerprint ignores. The\n    // post-write REPAIR re-canonicalizes and rewrites when the journal moved\n    // across the write itself (a parked mapping cannot be fixed after the\n    // fact by the reconcile pass). Only memory-tier records canonicalize;\n    // entities/ pages carry relationship TARGETS only\n    // rewriteRelationshipTargets understands, so they import byte-faithful\n    // with a reconcile marker; everything else imports losslessly.\n    const targetKind = classifyEntityRefWritePath(rootReal, targetAbs);\n    const rawRef = targetKind === \"memory\" ? readEntityRefFromFrontmatter(contentToWrite) : null;\n    if (targetKind === \"memory\" && rawRef !== null && capsuleEntityIds.has(rawRef)) {\n      // Ref targets a capsule-supplied entity page (potential collision\n      // claimant): keep the legacy bytes; the DEFERRED marker below lets the\n      // migration settle the collision and rewrite per its verdict (Codex P1).\n      await writeFile(targetAbs, contentToWrite, \"utf-8\");\n      reconcileNeeded = true;\n    } else if (targetKind === \"memory\") {\n      const idsAtWrite = historicalIdCache.get(journalStateDir);\n      const rawRecord = contentToWrite;\n      contentToWrite = canonicalizeEntityRefFrontmatter(rawRecord, idsAtWrite);\n      // Snapshot the pre-write bytes: a repair failure after the write must\n      // restore them (or remove a newly created target), or the import\n      // reports failure while an overwrite already destroyed the prior state\n      // and the skipped corpus bump leaves warm caches stale (AGENTS.md §14).\n      const originalBytes = await readFile(targetAbs, \"utf-8\").catch(() => null);\n      await writeFile(targetAbs, contentToWrite, \"utf-8\");\n      try {\n        await repairContentAfterJournalMove({\n          stateDir: journalStateDir,\n          cache: historicalIdCache,\n          idsAtWrite,\n          rawContent: rawRecord,\n          lastWritten: contentToWrite,\n          rewrite: (content) => writeFile(targetAbs, content, \"utf-8\"),\n        });\n      } catch (err) {\n        if (originalBytes === null) {\n          await unlink(targetAbs).catch(() => undefined);\n        } else {\n          await writeFile(targetAbs, originalBytes, \"utf-8\").catch(() => undefined);\n        }\n        throw err;\n      }\n    } else {\n      await writeFile(targetAbs, contentToWrite, \"utf-8\");\n      if (targetKind === \"entity\") {\n        reconcileNeeded = true;\n      }\n    }\n    // Bump the corpus sentinel per write (Cursor Medium, #1902): a concurrent\n    // readAllMemories during the import must rescan and see records already on\n    // disk, never the pre-import corpus, mid-batch.\n    bumpMemoryCorpusVersionForDir(rootReal);\n    imported.push({\n      sourcePath: rec.path,\n      targetPath: targetRel,\n      snapshotted,\n      rewroteId,\n    });\n  }\n\n  // Every record — including every collision claimant entity page — is on\n  // disk; NOW the reconcile pass can settle collisions safely.\n  if (reconcileNeeded) {\n    await requestEntityCanonicalIdReconcile(journalStateDir);\n  }\n\n  // Sort skipped for stable output (see comment above).\n  skipped.sort((a, b) => a.path.localeCompare(b.path));\n\n  // Per-record corpus bumps happen inside the loop above (Cursor Medium,\n  // #1902); no after-batch bump needed here.\n\n  return { imported, skipped, manifest };\n}\n\n// ---------------------------------------------------------------------------\n// Path helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Compute the destination relative path for a record under the chosen\n * mode.\n *\n *  - `skip` / `overwrite` — identity: the record's posix path is used as-is.\n *  - `fork` — rebased under `forks/<capsule-id>/<original-path>` so the\n *    original tree is never modified.\n */\nfunction computeTargetPath(\n  sourcePosix: string,\n  mode: ImportCapsuleMode,\n  capsuleId: string,\n): string {\n  if (mode === \"fork\") return `forks/${capsuleId}/${sourcePosix}`;\n  return sourcePosix;\n}\n\nasync function fileExistsAt(absPath: string): Promise<boolean> {\n  const st = await stat(absPath).catch(() => null);\n  return st !== null && st.isFile();\n}\n\n// ---------------------------------------------------------------------------\n// Fork-mode id rewriting\n// ---------------------------------------------------------------------------\n\n/**\n * Rewrite a YAML-frontmatter `id:` field to a fork-scoped value.\n *\n * Strategy: we deliberately do NOT parse the entire YAML — memory files\n * use a deterministic top-of-file frontmatter delimited by `---` lines,\n * and the orchestrator's `parseFrontmatter` reads `id` as a top-level\n * key with a single-line scalar value. We mirror that contract:\n *\n *   - Detect a leading `---\\n` … `\\n---` block at the top of the file.\n *   - Within that block, locate the first `id:` line that is not nested\n *     under another key (cheap heuristic: line starts at column 0).\n *   - Replace its value with a new fork-id derived from `capsuleId` and\n *     a short random suffix (or {@link opts.now} when provided for tests).\n *\n * Files without a frontmatter block, or without an `id:` key inside one,\n * are returned unchanged with `rewrote: false`. This keeps non-memory\n * artifacts (READMEs, transcripts) byte-identical to the source.\n */\nfunction rewriteFrontmatterIdForFork(\n  content: string,\n  capsuleId: string,\n  now: number | undefined,\n): { content: string; rewrote: boolean } {\n  // Detect the dominant line ending in the file so we can preserve it when\n  // rebuilding the frontmatter delimiters. Splitting/joining on `\\n` silently\n  // drops `\\r` from CRLF files, changing the byte content (Cursor thread #741\n  // line 467). We detect the ending of the very first line (the opening `---`)\n  // and use that as the canonical separator for the reconstructed delimiters.\n  // All three cases are covered: CRLF (\\r\\n), LF (\\n), and bare CR (\\r).\n  const crlfMatch = /^---(\\r\\n|\\r|\\n)/.exec(content);\n  // Fall back to LF if the file starts with `---` but has no newline (EOF).\n  const eol = crlfMatch ? crlfMatch[1] : \"\\n\";\n\n  // Frontmatter block detection: `---` on its own line at the very start,\n  // followed by content, followed by `---` on its own line. The closing\n  // delimiter must be at column 0. We capture the trailing terminator\n  // (`\\r?\\n` or end-of-string) as a separate group so we can re-emit it\n  // verbatim, preserving CRLF/LF/EOF shape from the original file.\n  const fmMatch = /^---\\r?\\n([\\s\\S]*?)\\r?\\n---(\\r?\\n|$)/.exec(content);\n  if (!fmMatch) return { content, rewrote: false };\n  const fmBody = fmMatch[1];\n  const fmTrailer = fmMatch[2];\n  const fmStart = fmMatch.index;\n  const fmEnd = fmStart + fmMatch[0].length;\n\n  // Find a top-level `id:` line. Top-level means the line begins at\n  // column 0 inside the frontmatter body (no leading whitespace) and the\n  // key is exactly `id`. We deliberately accept `id:` and `id : ` shapes\n  // but reject `nested_id:` to avoid touching unrelated keys.\n  const idLineRe = /^id:[ \\t]*([^\\r\\n]*)$/m;\n  const idMatch = idLineRe.exec(fmBody);\n  if (!idMatch) return { content, rewrote: false };\n\n  const newId = mintForkId(capsuleId, idMatch[1]?.trim() ?? \"\", now);\n  const replacedBody = fmBody.replace(idLineRe, `id: ${newId}`);\n  // Reconstruct the file: original prefix (always empty here, fmStart === 0\n  // by the `^` anchor) + frontmatter delimiters around the rewritten body.\n  // Use the detected `eol` for the opening/closing `---` lines so that CRLF\n  // files remain CRLF and LF files remain LF, preserving byte-content fidelity\n  // (Cursor thread #741 line 467).  The captured `fmTrailer` (the newline\n  // immediately after the closing `---`, or end-of-string) is re-emitted\n  // verbatim so the byte immediately after the closing fence is unchanged.\n  const prefix = content.slice(0, fmStart);\n  const tail = content.slice(fmEnd);\n  const rebuilt = `${prefix}---${eol}${replacedBody}${eol}---${fmTrailer}${tail}`;\n  return { content: rebuilt, rewrote: true };\n}\n\n/**\n * Derive a deterministic-when-`now`-is-set fork id from the capsule id and\n * the original record id. Production callers omit `now` and get a UUID\n * suffix; tests pass `now` for byte-stable assertions.\n */\nfunction mintForkId(capsuleId: string, originalId: string, now: number | undefined): string {\n  const base = originalId.length > 0 ? originalId : \"fork\";\n  if (now === undefined) {\n    const suffix = randomUUID().slice(0, 8);\n    return `${base}-fork-${capsuleId}-${suffix}`;\n  }\n  // Deterministic suffix: short hash of (capsuleId, originalId, now). Using\n  // sha256 over a sorted-key serialization (gotcha #38) so the suffix does\n  // not depend on Object.entries order.\n  const payload = JSON.stringify({ c: capsuleId, i: originalId, n: now });\n  const suffix = createHash(\"sha256\").update(payload, \"utf-8\").digest(\"hex\").slice(0, 8);\n  return `${base}-fork-${capsuleId}-${suffix}`;\n}\n\n// Note: `CapsuleBlock` is re-exported here purely so callers that want to\n// inspect the manifest block don't have to deep-import from `./types.js`.\nexport type { CapsuleBlock };\n"],"mappings":"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","names":["suffix"]}

package/dist/chunk-3TBLDMJA.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/recall-explain-renderer.ts","../src/recall-xray-renderer.ts"],"sourcesContent":["/**\n * Renderers for RecallTierExplain (issue #518).\n *\n * Pure functions that format a `LastRecallSnapshot` and its\n * optional `tierExplain` field for human text and machine JSON\n * consumption.  CLI / HTTP / MCP surfaces consume these — they do\n * not format explain output themselves, so rendering is tested in\n * one place.\n */\n\nimport type { LastRecallSnapshot } from \"./recall-state.js\";\nimport type { RecallTierExplain } from \"./types.js\";\nimport { isRetrievalTier } from \"./retrieval-tiers.js\";\nimport type {\n  RecallXraySnapshot,\n  RecallFilterTrace,\n  RecallXrayResult,\n} from \"./recall-xray.js\";\nimport { renderXrayMarkdown } from \"./recall-xray-renderer.js\";\n\nfunction sanitizeString(v: unknown): string | null {\n  return typeof v === \"string\" && v.length > 0 ? v : null;\n}\n\nfunction sanitizeFiniteNumber(v: unknown): number | null {\n  return typeof v === \"number\" && Number.isFinite(v) ? v : null;\n}\n\n/**\n * `text` and `json` are the original formats (backwards-compatible\n * since issue #518).  `markdown` was added in issue #570 PR 7 and\n * delegates to the shared X-ray renderer so the three observability\n * surfaces stay in lock-step (CLAUDE.md rule 22).\n */\nexport type RecallExplainFormat = \"text\" | \"json\" | \"markdown\";\n\nexport interface RecallExplainJsonPayload {\n  hasExplain: boolean;\n  snapshotFound: boolean;\n  sessionKey: string | null;\n  recordedAt: string | null;\n  namespace: string | null;\n  memoryIds: string[];\n  source: string | null;\n  sourcesUsed: string[] | null;\n  latencyMs: number | null;\n  tierExplain: RecallTierExplain | null;\n}\n\nfunction normalizeTierExplain(value: unknown): RecallTierExplain | null {\n  if (!value || typeof value !== \"object\" || Array.isArray(value)) return null;\n  const raw = value as Record<string, unknown>;\n  const filteredBy = Array.isArray(raw.filteredBy)\n    ? raw.filteredBy.filter((x): x is string => typeof x === \"string\")\n    : [];\n  const sourceAnchors = Array.isArray(raw.sourceAnchors)\n    ? raw.sourceAnchors\n        .filter(\n          (a): a is { path: string; lineRange?: unknown } =>\n            !!a && typeof a === \"object\" && typeof (a as { path?: unknown }).path === \"string\",\n        )\n        .map((a) => {\n          const lr = (a as { lineRange?: unknown }).lineRange;\n          const lineRange =\n            Array.isArray(lr) &&\n            lr.length === 2 &&\n            Number.isFinite(lr[0]) &&\n            Number.isFinite(lr[1])\n              ? ([lr[0] as number, lr[1] as number] as [number, number])\n              : undefined;\n          return lineRange\n            ? { path: (a as { path: string }).path, lineRange }\n            : { path: (a as { path: string }).path };\n        })\n    : undefined;\n  return {\n    tier: isRetrievalTier(raw.tier) ? raw.tier : \"hybrid\",\n    tierReason: typeof raw.tierReason === \"string\" ? raw.tierReason : \"\",\n    filteredBy,\n    candidatesConsidered: sanitizeFiniteNumber(raw.candidatesConsidered) ?? 0,\n    latencyMs: sanitizeFiniteNumber(raw.latencyMs) ?? 0,\n    ...(sourceAnchors !== undefined ? { sourceAnchors } : {}),\n  };\n}\n\nexport function toRecallExplainJson(\n  snapshot: LastRecallSnapshot | null,\n): RecallExplainJsonPayload {\n  if (!snapshot) {\n    return {\n      hasExplain: false,\n      snapshotFound: false,\n      sessionKey: null,\n      recordedAt: null,\n      namespace: null,\n      memoryIds: [],\n      source: null,\n      sourcesUsed: null,\n      latencyMs: null,\n      tierExplain: null,\n    };\n  }\n  const normalizedExplain = normalizeTierExplain(snapshot.tierExplain);\n  return {\n    hasExplain: normalizedExplain !== null,\n    snapshotFound: true,\n    sessionKey: sanitizeString(snapshot.sessionKey),\n    recordedAt: sanitizeString(snapshot.recordedAt),\n    namespace: sanitizeString(snapshot.namespace),\n    memoryIds: Array.isArray(snapshot.memoryIds)\n      ? snapshot.memoryIds.filter((x): x is string => typeof x === \"string\")\n      : [],\n    source: sanitizeString(snapshot.source),\n    sourcesUsed: Array.isArray(snapshot.sourcesUsed)\n      ? snapshot.sourcesUsed.filter((x): x is string => typeof x === \"string\")\n      : null,\n    latencyMs: sanitizeFiniteNumber(snapshot.latencyMs),\n    tierExplain: normalizedExplain,\n  };\n}\n\n/**\n * Render the shared \"--- tier explain ---\" text block used by both the\n * recall-explain surface and the Recall X-ray surface.  Callers provide\n * the normalized `RecallTierExplain` (or `null` for the\n * not-populated/disabled case) so the block stays character-for-character\n * identical across surfaces (CLAUDE.md rule 22).  The returned strings do\n * NOT include leading blank lines or headers — callers own that framing.\n */\nexport function renderTierExplainTextLines(\n  tierExplain: RecallTierExplain | null,\n): string[] {\n  const lines: string[] = [];\n  if (!tierExplain) {\n    lines.push(\n      \"(not populated — direct-answer tier disabled or did not fire)\",\n    );\n    return lines;\n  }\n  lines.push(`tier: ${tierExplain.tier}`);\n  lines.push(`reason: ${tierExplain.tierReason}`);\n  lines.push(`candidates-considered: ${tierExplain.candidatesConsidered}`);\n  lines.push(`latency-ms: ${tierExplain.latencyMs}`);\n  if (tierExplain.filteredBy.length > 0) {\n    lines.push(`filtered-by: ${tierExplain.filteredBy.join(\", \")}`);\n  } else {\n    lines.push(\"filtered-by: (none)\");\n  }\n  if (tierExplain.sourceAnchors && tierExplain.sourceAnchors.length > 0) {\n    lines.push(\"source-anchors:\");\n    for (const anchor of tierExplain.sourceAnchors) {\n      const range = anchor.lineRange\n        ? `:${anchor.lineRange[0]}-${anchor.lineRange[1]}`\n        : \"\";\n      lines.push(`  - ${anchor.path}${range}`);\n    }\n  }\n  return lines;\n}\n\nexport function toRecallExplainText(\n  snapshot: LastRecallSnapshot | null,\n): string {\n  const lines: string[] = [\"=== Recall Explain ===\"];\n\n  if (!snapshot) {\n    lines.push(\"No recall snapshot recorded yet.\");\n    return lines.join(\"\\n\");\n  }\n\n  const sessionKey = sanitizeString(snapshot.sessionKey);\n  const recordedAt = sanitizeString(snapshot.recordedAt);\n  const namespace = sanitizeString(snapshot.namespace);\n  const source = sanitizeString(snapshot.source);\n  lines.push(`session: ${sessionKey ?? \"(unknown)\"}`);\n  lines.push(`recorded: ${recordedAt ?? \"(unknown)\"}`);\n  if (namespace) lines.push(`namespace: ${namespace}`);\n  if (source) lines.push(`source: ${source}`);\n  const sourcesUsed = Array.isArray(snapshot.sourcesUsed)\n    ? snapshot.sourcesUsed.filter((x): x is string => typeof x === \"string\")\n    : [];\n  if (sourcesUsed.length > 0) {\n    lines.push(`sources-used: ${sourcesUsed.join(\", \")}`);\n  }\n  const latencyMs = sanitizeFiniteNumber(snapshot.latencyMs);\n  if (latencyMs !== null) {\n    lines.push(`latency-ms: ${latencyMs}`);\n  }\n  const memoryIds = Array.isArray(snapshot.memoryIds)\n    ? snapshot.memoryIds.filter((x): x is string => typeof x === \"string\")\n    : [];\n  if (memoryIds.length > 0) {\n    lines.push(`memories: ${memoryIds.join(\", \")}`);\n  }\n\n  const ex = normalizeTierExplain(snapshot.tierExplain);\n  if (!ex) {\n    lines.push(\"\");\n    lines.push(\n      \"tier-explain: (not populated — direct-answer tier disabled or did not fire)\",\n    );\n    return lines.join(\"\\n\");\n  }\n\n  lines.push(\"\");\n  lines.push(\"--- tier explain ---\");\n  for (const line of renderTierExplainTextLines(ex)) {\n    lines.push(line);\n  }\n  return lines.join(\"\\n\");\n}\n\n/**\n * Adapter: convert a `LastRecallSnapshot` into a best-effort\n * `RecallXraySnapshot` so the markdown renderer can produce a\n * consistent, richly-formatted document for callers that have asked\n * for `markdown` format.  The LastRecallSnapshot and the X-ray\n * snapshot share session/namespace/memoryIds; additional X-ray-only\n * fields (filters, score decomposition, graph path, audit id) are\n * left empty because the legacy snapshot doesn't carry them.  The\n * renderer handles missing fields gracefully.\n */\n/**\n * Strip backticks, pipes, and newlines from a host-provided value so it\n * cannot escape its enclosing markdown code span, break the surrounding\n * table row, or inject extra rows when it lands in\n * `renderXrayMarkdown`.  Applied at the adapter boundary because\n * `LastRecallSnapshot` is hydrated from on-disk JSON without schema\n * validation (codex P2 review on #605).\n *\n * Accepts `unknown` so non-string truthy values (numbers, objects,\n * booleans, arrays) coming from a corrupted snapshot are coerced to\n * the empty string rather than crashing on `.replace(...)`.  Callers\n * should treat an empty return as \"drop this field.\"\n */\nfunction sanitizeForMarkdownInline(value: unknown): string {\n  if (typeof value !== \"string\") return \"\";\n  return value.replace(/[`|\\r\\n]/g, \" \").trim();\n}\n\n/**\n * Map the legacy `LastRecallSnapshot.source` field to the\n * `RecallXrayServedBy` union used by the unified x-ray renderer.\n * Mirrors the `mapRecallSourceToXrayServedBy` helper inside\n * `orchestrator.ts` (which is private).  Keep the two in sync when a\n * new source lands — unknown values collapse to `\"hybrid\"` to preserve\n * backwards compatibility with older on-disk snapshots.\n */\nfunction mapLegacySourceToServedBy(\n  source: unknown,\n): \"hybrid\" | \"recent-scan\" {\n  if (source === \"recent_scan\") return \"recent-scan\";\n  return \"hybrid\";\n}\n\nexport function toRecallXraySnapshotFromLegacy(\n  snapshot: LastRecallSnapshot | null,\n): RecallXraySnapshot | null {\n  if (!snapshot) return null;\n  const capturedAt = (() => {\n    if (typeof snapshot.recordedAt !== \"string\") return 0;\n    const ms = Date.parse(snapshot.recordedAt);\n    return Number.isFinite(ms) && ms >= 0 ? ms : 0;\n  })();\n  const memoryIds = Array.isArray(snapshot.memoryIds)\n    ? snapshot.memoryIds.filter((x): x is string => typeof x === \"string\")\n    : [];\n  // Codex P2 + Cursor Medium on #605: every converted result used to\n  // be stamped with `servedBy: \"hybrid\"`, misattributing legacy\n  // snapshots that came from `recent_scan` (or any future source).\n  // Propagate the recorded `source` so markdown `recall-explain`\n  // output matches the `served-by=` string the native x-ray capture\n  // would emit for the same recall.\n  const servedBy = mapLegacySourceToServedBy(snapshot.source);\n  const results: RecallXrayResult[] = memoryIds.map((memoryId) => ({\n    memoryId,\n    path: \"\",\n    servedBy,\n    scoreDecomposition: { final: 0 },\n    admittedBy: [],\n  }));\n  const filters: RecallFilterTrace[] = [];\n  return {\n    schemaVersion: \"1\",\n    // `LastRecallSnapshot` does not preserve the original query text;\n    // synthesize a placeholder so the renderer has a non-empty\n    // string to print.  `queryHash` + `queryLen` stay in the JSON\n    // payload via `toRecallExplainJson` for callers that need them.\n    query:\n      snapshot.queryHash\n        ? `(legacy explain; queryHash=${snapshot.queryHash})`\n        : \"(legacy explain)\",\n    // `snapshotId` is synthesized here; `sessionKey` is already\n    // sanitized before it reaches the ID because we re-use the\n    // sanitized string below.\n    snapshotId: `legacy-${sanitizeForMarkdownInline(snapshot.sessionKey ?? \"unknown\") || \"unknown\"}-${capturedAt}`,\n    capturedAt,\n    // Run the raw on-disk value through the same normalizer the text\n    // and JSON paths use so the markdown adapter cannot render\n    // unvalidated tier-explain payloads (cursor / codex review on\n    // #605).  A malformed tierExplain is dropped to null, matching the\n    // behavior of the non-markdown surfaces.\n    tierExplain: normalizeTierExplain(snapshot.tierExplain) ?? null,\n    results,\n    filters,\n    budget: { chars: 0, used: 0 },\n    // Sanitize legacy session metadata at the adapter boundary so a\n    // malformed on-disk value (containing backticks, pipes, or\n    // newlines) cannot break the enclosing markdown table when\n    // `renderXrayMarkdown` prints it in a raw code-span cell (codex P2\n    // review on #605).\n    ...(snapshot.sessionKey\n      ? (() => {\n          const clean = sanitizeForMarkdownInline(snapshot.sessionKey);\n          return clean ? { sessionKey: clean } : {};\n        })()\n      : {}),\n    ...(snapshot.namespace\n      ? (() => {\n          const clean = sanitizeForMarkdownInline(snapshot.namespace);\n          return clean ? { namespace: clean } : {};\n        })()\n      : {}),\n  };\n}\n\nexport function renderRecallExplain(\n  snapshot: LastRecallSnapshot | null,\n  format: RecallExplainFormat,\n): string {\n  if (format === \"json\") {\n    return JSON.stringify(toRecallExplainJson(snapshot), null, 2);\n  }\n  if (format === \"markdown\") {\n    // Delegate to the shared X-ray renderer so CLI / HTTP / MCP\n    // markdown output all share one implementation (CLAUDE.md rule\n    // 22).  The JSON and text paths remain byte-for-byte\n    // backwards-compatible with pre-#570 behavior.\n    return renderXrayMarkdown(toRecallXraySnapshotFromLegacy(snapshot));\n  }\n  return toRecallExplainText(snapshot);\n}\n\nexport function parseRecallExplainFormat(value: unknown): RecallExplainFormat {\n  if (value === undefined || value === null) return \"text\";\n  if (typeof value !== \"string\") {\n    throw new Error(\n      `--format expects \"text\", \"json\", or \"markdown\", got ${typeof value}`,\n    );\n  }\n  const v = value.trim().toLowerCase();\n  if (v === \"text\" || v === \"json\" || v === \"markdown\") return v;\n  throw new Error(\n    `--format expects \"text\", \"json\", or \"markdown\", got ${JSON.stringify(value)}`,\n  );\n}\n","/**\n * Unified Recall X-ray renderer (issue #570, PR 2).\n *\n * Pure functions that format a `RecallXraySnapshot` for human text,\n * GitHub-flavored markdown, and machine JSON consumption.  CLI / HTTP\n * / MCP surfaces all call into this module — they do NOT format X-ray\n * output themselves, so rendering is tested in one place (CLAUDE.md\n * rule 22).\n *\n * Scope for PR 2 (this slice):\n *   - Pure rendering.  No IO, no transport, no capture.\n *   - `renderXray(snapshot, format)` with format ∈\n *     `{\"json\", \"text\", \"markdown\"}`.\n *   - `parseXrayFormat(value)` — input validator that rejects unknown\n *     formats with a listed-options error (CLAUDE.md rule 51).\n *   - Golden-file-style tests in `recall-xray-renderer.test.ts`.\n */\n\nimport type {\n  RecallFilterTrace,\n  RecallXrayResult,\n  RecallXraySnapshot,\n  RecallXrayServedBy,\n} from \"./recall-xray.js\";\nimport { summarizeDisclosureTokens } from \"./recall-xray.js\";\nimport { renderTierExplainTextLines } from \"./recall-explain-renderer.js\";\nimport { summarizeRetrievedMemoryProvenance } from \"./memory-provenance.js\";\n\nexport type RecallXrayFormat = \"json\" | \"text\" | \"markdown\";\n\nexport const RECALL_XRAY_FORMATS: readonly RecallXrayFormat[] = [\n  \"json\",\n  \"text\",\n  \"markdown\",\n] as const;\n\n/**\n * Validate and coerce a user-provided `--format` / `format` argument to\n * `RecallXrayFormat`.  Unknown values throw an error listing valid\n * options (CLAUDE.md rule 51).  `undefined`/`null` defaults to `\"text\"`.\n */\nexport function parseXrayFormat(value: unknown): RecallXrayFormat {\n  if (value === undefined || value === null) return \"text\";\n  if (typeof value !== \"string\") {\n    throw new Error(\n      `--format expects one of ${RECALL_XRAY_FORMATS.join(\", \")}; got ${typeof value}`,\n    );\n  }\n  const v = value.trim().toLowerCase();\n  if (v === \"json\" || v === \"text\" || v === \"markdown\") return v;\n  throw new Error(\n    `--format expects one of ${RECALL_XRAY_FORMATS.join(\", \")}; got ${JSON.stringify(value)}`,\n  );\n}\n\n/**\n * Top-level dispatcher.  CLI / HTTP / MCP callers should always route\n * through this function so the three formats stay in lock-step.\n */\nexport function renderXray(\n  snapshot: RecallXraySnapshot | null,\n  format: RecallXrayFormat,\n): string {\n  if (format === \"json\") return renderXrayJson(snapshot);\n  if (format === \"markdown\") return renderXrayMarkdown(snapshot);\n  return renderXrayText(snapshot);\n}\n\n// ─── JSON ─────────────────────────────────────────────────────────────────\n\n/**\n * Deterministic JSON encoding of an X-ray snapshot.  Returns a stable\n * v1 envelope when the snapshot is absent so consumers can pattern-match\n * on `snapshotFound` rather than distinguishing `null` vs `{}`.\n */\nexport function renderXrayJson(snapshot: RecallXraySnapshot | null): string {\n  if (!snapshot) {\n    return JSON.stringify(\n      { schemaVersion: \"1\", snapshotFound: false },\n      null,\n      2,\n    );\n  }\n  // `snapshotFound` is injected *before* the rest so downstream JSON\n  // consumers see it near the top of the document.\n  return JSON.stringify(\n    { snapshotFound: true, ...snapshot },\n    null,\n    2,\n  );\n}\n\n// ─── Text ─────────────────────────────────────────────────────────────────\n\nexport function renderXrayText(snapshot: RecallXraySnapshot | null): string {\n  const lines: string[] = [\"=== Recall X-ray ===\"];\n  if (!snapshot) {\n    lines.push(\"No X-ray snapshot captured.\");\n    return lines.join(\"\\n\");\n  }\n\n  lines.push(`query: ${snapshot.query}`);\n  lines.push(`snapshot-id: ${snapshot.snapshotId}`);\n  lines.push(`captured-at: ${formatCapturedAt(snapshot.capturedAt)}`);\n  if (snapshot.sessionKey) lines.push(`session: ${snapshot.sessionKey}`);\n  if (snapshot.namespace) lines.push(`namespace: ${snapshot.namespace}`);\n  if (snapshot.traceId) lines.push(`trace-id: ${snapshot.traceId}`);\n  lines.push(\n    `budget: ${snapshot.budget.used} / ${snapshot.budget.chars} chars`,\n  );\n\n  lines.push(\"\");\n  lines.push(\"--- filters ---\");\n  if (snapshot.filters.length === 0) {\n    lines.push(\"(no filter traces recorded)\");\n  } else {\n    for (const f of snapshot.filters) {\n      lines.push(renderFilterTextLine(f));\n    }\n  }\n\n  lines.push(\"\");\n  lines.push(\"--- results ---\");\n  if (snapshot.results.length === 0) {\n    lines.push(\"(no results admitted)\");\n  } else {\n    snapshot.results.forEach((result, idx) => {\n      for (const line of renderResultTextLines(result, idx + 1)) {\n        lines.push(line);\n      }\n    });\n  }\n\n  lines.push(\"\");\n  lines.push(\"--- tier explain ---\");\n  for (const line of renderTierExplainTextLines(snapshot.tierExplain ?? null)) {\n    lines.push(line);\n  }\n\n  return lines.join(\"\\n\");\n}\n\nfunction renderFilterTextLine(f: RecallFilterTrace): string {\n  const base = `- ${f.name}: ${f.admitted}/${f.considered} admitted`;\n  return f.reason ? `${base} (${f.reason})` : base;\n}\n\nfunction renderResultTextLines(\n  result: RecallXrayResult,\n  rank: number,\n): string[] {\n  const lines: string[] = [];\n  lines.push(`[${rank}] ${result.memoryId} — ${servedByLabel(result.servedBy)}`);\n  if (result.path) lines.push(`    path: ${result.path}`);\n  lines.push(`    score: ${renderScoreDecomposition(result)}`);\n  if (result.provenance) {\n    lines.push(\n      `    provenance: ${summarizeRetrievedMemoryProvenance(result.provenance)}`,\n    );\n    lines.push(`    retrieval-reason: ${result.provenance.retrievalReason}`);\n    if (result.provenance.userContextScopes.length > 0) {\n      lines.push(\n        `    context-scopes: ${result.provenance.userContextScopes.join(\", \")}`,\n      );\n    }\n    if (\n      result.provenance.safety !== \"safe\" ||\n      result.provenance.safetyReasons.length > 0\n    ) {\n      const reasonSuffix =\n        result.provenance.safetyReasons.length > 0\n          ? ` (${result.provenance.safetyReasons.join(\", \")})`\n          : \"\";\n      lines.push(`    safety: ${result.provenance.safety}${reasonSuffix}`);\n    }\n  }\n  if (result.sourceSpan) {\n    const q = truncateForXray(result.sourceSpan.quote, 120);\n    lines.push(\n      `    source: \"${q}\" (observed ${result.sourceSpan.observedAt}) [${result.sourceSpan.provenance}]`,\n    );\n  }\n  if (result.admittedBy.length > 0) {\n    lines.push(`    admitted-by: ${result.admittedBy.join(\", \")}`);\n  }\n  if (result.rejectedBy) {\n    lines.push(`    rejected-by: ${result.rejectedBy}`);\n  }\n  if (result.graphPath && result.graphPath.length > 0) {\n    lines.push(`    graph-path: ${result.graphPath.join(\" -> \")}`);\n    // Issue #681 PR 3/3 — surface per-edge confidence inline so\n    // operators can attribute floor-pruning / PageRank ranking\n    // decisions to specific edges. Skipped when no confidences were\n    // recorded (legacy snapshot or single-node path).\n    if (\n      result.graphEdgeConfidences &&\n      result.graphEdgeConfidences.length > 0\n    ) {\n      lines.push(\n        `    edge-confidences: ${result.graphEdgeConfidences\n          .map((c) => c.toFixed(2))\n          .join(\", \")}`,\n      );\n    }\n  }\n  if (result.auditEntryId) {\n    lines.push(`    audit-entry: ${result.auditEntryId}`);\n  }\n  return lines;\n}\n\n// ─── Markdown ─────────────────────────────────────────────────────────────\n\nexport function renderXrayMarkdown(\n  snapshot: RecallXraySnapshot | null,\n): string {\n  const lines: string[] = [\"# Recall X-ray\"];\n  if (!snapshot) {\n    lines.push(\"\");\n    lines.push(\"_No X-ray snapshot captured._\");\n    return lines.join(\"\\n\");\n  }\n\n  lines.push(\"\");\n  lines.push(`**Query:** ${mdInlineCode(snapshot.query)}`);\n  lines.push(\"\");\n  lines.push(\"| Field | Value |\");\n  lines.push(\"| --- | --- |\");\n  lines.push(`| Snapshot ID | \\`${snapshot.snapshotId}\\` |`);\n  lines.push(`| Captured at | ${formatCapturedAt(snapshot.capturedAt)} |`);\n  if (snapshot.sessionKey) {\n    lines.push(`| Session | \\`${snapshot.sessionKey}\\` |`);\n  }\n  if (snapshot.namespace) {\n    lines.push(`| Namespace | \\`${snapshot.namespace}\\` |`);\n  }\n  if (snapshot.traceId) {\n    lines.push(`| Trace ID | \\`${snapshot.traceId}\\` |`);\n  }\n  lines.push(\n    `| Budget | ${snapshot.budget.used} / ${snapshot.budget.chars} chars |`,\n  );\n\n  lines.push(\"\");\n  lines.push(\"## Filters\");\n  if (snapshot.filters.length === 0) {\n    lines.push(\"\");\n    lines.push(\"_No filter traces recorded._\");\n  } else {\n    lines.push(\"\");\n    lines.push(\"| Filter | Considered | Admitted | Reason |\");\n    lines.push(\"| --- | ---: | ---: | --- |\");\n    for (const f of snapshot.filters) {\n      const reason = f.reason ? mdEscape(f.reason) : \"\";\n      lines.push(`| ${mdEscape(f.name)} | ${f.considered} | ${f.admitted} | ${reason} |`);\n    }\n  }\n\n  lines.push(\"\");\n  lines.push(\"## Results\");\n  if (snapshot.results.length === 0) {\n    lines.push(\"\");\n    lines.push(\"_No results admitted._\");\n  } else {\n    snapshot.results.forEach((result, idx) => {\n      for (const line of renderResultMarkdownLines(result, idx + 1)) {\n        lines.push(line);\n      }\n    });\n\n    // Per-disclosure token-spend summary (issue #677 PR 3/4).  Only\n    // emitted when at least one result carries a disclosure level so\n    // we don't pollute the snapshot for callers who haven't wired the\n    // depth knob through.  Counts and tokens default to 0 for buckets\n    // with no contributions.\n    const summary = summarizeDisclosureTokens(snapshot.results);\n    const hasAnyDisclosure =\n      summary.chunk.count + summary.section.count + summary.raw.count > 0;\n    if (hasAnyDisclosure) {\n      lines.push(\"\");\n      lines.push(\"### Token spend by disclosure\");\n      lines.push(\"\");\n      lines.push(\"| Disclosure | Results | Estimated tokens |\");\n      lines.push(\"| --- | ---: | ---: |\");\n      lines.push(\n        `| chunk | ${summary.chunk.count} | ${summary.chunk.estimatedTokens} |`,\n      );\n      lines.push(\n        `| section | ${summary.section.count} | ${summary.section.estimatedTokens} |`,\n      );\n      lines.push(\n        `| raw | ${summary.raw.count} | ${summary.raw.estimatedTokens} |`,\n      );\n      if (summary.unspecified.count > 0) {\n        lines.push(\n          `| _(unspecified)_ | ${summary.unspecified.count} | ${summary.unspecified.estimatedTokens} |`,\n        );\n      }\n    }\n  }\n\n  lines.push(\"\");\n  lines.push(\"## Tier Explain\");\n  if (!snapshot.tierExplain) {\n    lines.push(\"\");\n    lines.push(\n      \"_Not populated — direct-answer tier disabled or did not fire._\",\n    );\n  } else {\n    const te = snapshot.tierExplain;\n    lines.push(\"\");\n    lines.push(\"| Field | Value |\");\n    lines.push(\"| --- | --- |\");\n    lines.push(`| Tier | \\`${te.tier}\\` |`);\n    lines.push(`| Reason | ${mdEscape(te.tierReason)} |`);\n    lines.push(`| Candidates considered | ${te.candidatesConsidered} |`);\n    lines.push(`| Latency (ms) | ${te.latencyMs} |`);\n    lines.push(\n      `| Filtered by | ${\n        te.filteredBy.length > 0\n          ? te.filteredBy.map(mdInlineCode).join(\", \")\n          : \"_(none)_\"\n      } |`,\n    );\n    if (te.sourceAnchors && te.sourceAnchors.length > 0) {\n      lines.push(\"\");\n      lines.push(\"**Source anchors:**\");\n      for (const anchor of te.sourceAnchors) {\n        const range = anchor.lineRange\n          ? `:${anchor.lineRange[0]}-${anchor.lineRange[1]}`\n          : \"\";\n        lines.push(`- \\`${anchor.path}${range}\\``);\n      }\n    }\n  }\n\n  return lines.join(\"\\n\");\n}\n\nfunction renderResultMarkdownLines(\n  result: RecallXrayResult,\n  rank: number,\n): string[] {\n  const lines: string[] = [];\n  lines.push(\"\");\n  lines.push(\n    `### ${rank}. \\`${result.memoryId}\\` — ${servedByLabel(result.servedBy)}`,\n  );\n  if (result.path) {\n    lines.push(\"\");\n    lines.push(`- **Path:** \\`${result.path}\\``);\n  } else {\n    lines.push(\"\");\n  }\n  lines.push(`- **Score:** ${renderScoreDecomposition(result)}`);\n  if (result.provenance) {\n    lines.push(\n      `- **Provenance:** ${mdEscape(summarizeRetrievedMemoryProvenance(result.provenance))}`,\n    );\n    lines.push(\n      `- **Retrieval reason:** ${mdInlineCode(result.provenance.retrievalReason)}`,\n    );\n    if (result.provenance.userContextScopes.length > 0) {\n      lines.push(\n        `- **Context scopes:** ${result.provenance.userContextScopes\n          .map(mdInlineCode)\n          .join(\", \")}`,\n      );\n    }\n    if (\n      result.provenance.safety !== \"safe\" ||\n      result.provenance.safetyReasons.length > 0\n    ) {\n      const reasonSuffix =\n        result.provenance.safetyReasons.length > 0\n          ? ` (${result.provenance.safetyReasons.map(mdInlineCode).join(\", \")})`\n          : \"\";\n      lines.push(\n        `- **Safety:** ${mdInlineCode(result.provenance.safety)}${reasonSuffix}`,\n      );\n    }\n  }\n  if (result.sourceSpan) {\n    const q = truncateForXray(result.sourceSpan.quote, 120);\n    lines.push(\n      `- **Source:** \"${mdEscape(q)}\" (${mdInlineCode(result.sourceSpan.observedAt)}) \\u2014 ${result.sourceSpan.provenance}`,\n    );\n  }\n  if (result.admittedBy.length > 0) {\n    lines.push(\n      `- **Admitted by:** ${result.admittedBy.map(mdInlineCode).join(\", \")}`,\n    );\n  }\n  if (result.rejectedBy) {\n    lines.push(`- **Rejected by:** ${mdInlineCode(result.rejectedBy)}`);\n  }\n  if (result.graphPath && result.graphPath.length > 0) {\n    lines.push(\n      `- **Graph path:** ${result.graphPath\n        .map(mdInlineCode)\n        .join(\" → \")}`,\n    );\n    // Issue #681 PR 3/3 — render per-edge confidences as a parallel\n    // markdown line so operators can correlate them with the path\n    // arrows above. Skipped when no confidences were recorded.\n    if (\n      result.graphEdgeConfidences &&\n      result.graphEdgeConfidences.length > 0\n    ) {\n      lines.push(\n        `- **Edge confidences:** ${result.graphEdgeConfidences\n          .map((c) => mdInlineCode(c.toFixed(2)))\n          .join(\", \")}`,\n      );\n    }\n  }\n  if (result.auditEntryId) {\n    lines.push(`- **Audit entry:** \\`${result.auditEntryId}\\``);\n  }\n  if (result.disclosure !== undefined) {\n    const tokenLine =\n      typeof result.estimatedTokens === \"number\"\n        ? ` (~${result.estimatedTokens} tokens)`\n        : \"\";\n    lines.push(`- **Disclosure:** \\`${result.disclosure}\\`${tokenLine}`);\n  } else if (typeof result.estimatedTokens === \"number\") {\n    // Disclosure unspecified but tokens recorded — still surface the\n    // budget so the operator can attribute spend.\n    lines.push(`- **Estimated tokens:** ${result.estimatedTokens}`);\n  }\n  return lines;\n}\n\n// ─── Shared helpers ───────────────────────────────────────────────────────\n\nfunction servedByLabel(servedBy: RecallXrayServedBy): string {\n  return `served-by=${servedBy}`;\n}\n\nfunction renderScoreDecomposition(result: RecallXrayResult): string {\n  const parts: string[] = [`final=${formatScore(result.scoreDecomposition.final)}`];\n  const s = result.scoreDecomposition;\n  if (s.vector !== undefined) parts.push(`vector=${formatScore(s.vector)}`);\n  if (s.bm25 !== undefined) parts.push(`bm25=${formatScore(s.bm25)}`);\n  if (s.importance !== undefined) {\n    parts.push(`importance=${formatScore(s.importance)}`);\n  }\n  if (s.mmrPenalty !== undefined) {\n    parts.push(`mmr_penalty=${formatScore(s.mmrPenalty)}`);\n  }\n  if (s.tierPrior !== undefined) {\n    parts.push(`tier_prior=${formatScore(s.tierPrior)}`);\n  }\n  if (s.reinforcementBoost !== undefined && s.reinforcementBoost > 0) {\n    parts.push(`reinforcement_boost=${formatScore(s.reinforcementBoost)}`);\n  }\n  return parts.join(\" \");\n}\n\nfunction formatScore(value: number): string {\n  // Deterministic 4-decimal formatting keeps golden files stable\n  // without printing spurious trailing zeros via toString().\n  if (!Number.isFinite(value)) return \"0.0000\";\n  return value.toFixed(4);\n}\n\nfunction formatCapturedAt(ts: number): string {\n  if (!Number.isFinite(ts) || ts < 0) return \"(unknown)\";\n  // `new Date(n).toISOString()` throws a RangeError for finite numbers\n  // outside the valid Date range (roughly |n| > 8.64e15).  That case\n  // can surface when snapshots are corrupted or captured with a\n  // custom clock, so coerce it to the same \"(unknown)\" fallback\n  // rather than crashing the renderer.\n  try {\n    return new Date(ts).toISOString();\n  } catch {\n    return \"(unknown)\";\n  }\n}\n\nfunction mdEscape(value: string): string {\n  // Pipe is the only character that breaks GFM table rendering; escape\n  // backslash first so we do not re-escape the escape character.\n  return value.replace(/\\\\/g, \"\\\\\\\\\").replace(/\\|/g, \"\\\\|\");\n}\n\n/**\n * Truncate a quote for X-ray display (issue #1575 PR 3). Collapses internal\n * whitespace runs (including newlines/carriage returns) to single spaces so\n * a multi-line source excerpt cannot split what is meant to be a single X-ray\n * row, then caps at `maxChars` on a word boundary with an ellipsis marker.\n * The JSON \\`sourceSpan.quote\\` stays verbatim — this is display-only.\n */\nfunction truncateForXray(text: string, maxChars: number): string {\n  const collapsed = text.replace(/\\s+/g, \" \").trim();\n  if (collapsed.length <= maxChars) return collapsed;\n  const slice = collapsed.slice(0, maxChars);\n  const lastSpace = slice.lastIndexOf(\" \");\n  const cut = lastSpace > Math.floor(maxChars * 0.5) ? slice.slice(0, lastSpace) : slice;\n  return `${cut}\\u2026`;\n}\n\nfunction mdInlineCode(value: string): string {\n  if (value.length === 0) return \"``\";\n  // Use exactly enough backticks to unambiguously wrap content that\n  // itself contains backticks (GFM rule).\n  const longestRun = /`+/g;\n  let maxLen = 0;\n  for (const match of value.matchAll(longestRun)) {\n    if (match[0].length > maxLen) maxLen = match[0].length;\n  }\n  const fence = \"`\".repeat(maxLen + 1);\n  const pad = value.startsWith(\"`\") || value.endsWith(\"`\") ? \" \" : \"\";\n  return `${fence}${pad}${value}${pad}${fence}`;\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-4J7G5SY4.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/storage/entity-canonical-id-references.ts","../src/storage/entity-canonical-id-lock.ts"],"sourcesContent":["/**\n * Write-boundary surface of the entity canonical-id migration (issue #2213).\n *\n * The migration itself (entity-canonical-id-migration.ts) renames legacy\n * entity files and rewrites references ONCE, to convergence, then retires.\n * Everything here exists so nothing can re-introduce a legacy reference\n * afterwards without the migration having to rescan the corpus:\n *\n * - store-mediated writes canonicalize the caller-supplied `entityRef`\n *   ({@link canonicalizeEntityRefOption});\n * - bulk writers that persist raw record bytes (capsule import/merge)\n *   canonicalize the frontmatter line ({@link canonicalizeEntityRefFrontmatter});\n * - raw-byte writers that CANNOT parse what they write (offline sync,\n *   consolidation-undo, governance restores) request one bounded\n *   reconciliation pass instead ({@link requestEntityCanonicalIdReconcile}).\n */\nimport path from \"node:path\";\nimport {\n  closeSync,\n  constants,\n  fstatSync,\n  lstatSync,\n  realpathSync,\n  openSync,\n  readFileSync,\n  renameSync,\n  rmSync,\n  writeFileSync,\n} from \"node:fs\";\nimport { randomUUID } from \"node:crypto\";\nimport { log } from \"../logger.js\";\nimport { isErrnoCode } from \"../utils/errno.js\";\nimport { RECALL_FALLBACK_DIRS } from \"../utils/category-dir.js\";\nimport { withEntityCanonicalMutationLock } from \"./entity-canonical-id-lock.js\";\nimport { normalizeSupersessionKey } from \"../temporal-supersession.js\";\n\nexport const ENTITY_CANONICAL_ID_MIGRATION_FILE = \"entity-canonical-id-migration-v1.json\";\n\n/**\n * Parse a journal document into a mapping table. A document without a valid\n * `mappings` object is a LEGITIMATELY empty table; an unreadable/unparsable\n * document THROWS so callers can distinguish \"empty\" from \"failed\".\n */\nfunction parseJournalMappings(raw: string): Readonly<Record<string, string>> {\n  const parsed: unknown = JSON.parse(raw);\n  if (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed) || !(\"mappings\" in parsed)) return {};\n  const mappings = parsed.mappings;\n  if (!mappings || typeof mappings !== \"object\" || Array.isArray(mappings)) return {};\n  // Null prototype: journal-supplied ids like `constructor` must be own\n  // entries, never collide with Object.prototype (Codex P2, round 20).\n  const cleaned: Record<string, string> = Object.create(null) as Record<string, string>;\n  for (const [legacyId, canonicalId] of Object.entries(mappings)) {\n    if (legacyId.length > 0 && typeof canonicalId === \"string\" && canonicalId.length > 0) {\n      cleaned[legacyId] = canonicalId;\n    }\n  }\n  return cleaned;\n}\n\ntype JournalRead =\n  | { kind: \"ok\"; raw: string; key: string }\n  | { kind: \"missing\" }\n  | { kind: \"refused\" }\n  | { kind: \"error\" };\n\n/**\n * Open the journal WITHOUT following symlinks and read content + identity\n * from the same opened inode (repo rule: reject symlink traversal from\n * memory directories). O_NOFOLLOW makes the open refuse a symlinked FINAL\n * component (ELOOP); the parent `state/` directory is verified AFTER the\n * open, together with a path↔fd identity pairing, so a parent swapped\n * around the open cannot hold: a swap still in place fails the parent\n * lstat, and a swap reverted fails the dev/ino pairing against the real\n * journal. Platforms without O_NOFOLLOW get the same post-open checks.\n */\nfunction readJournalFileNoFollow(statePath: string): JournalRead {\n  let fd: number;\n  try {\n    fd = openSync(statePath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));\n  } catch (error) {\n    if (isErrnoCode(error, \"ENOENT\")) return { kind: \"missing\" };\n    if (isErrnoCode(error, \"ELOOP\")) return { kind: \"refused\" };\n    return { kind: \"error\" };\n  }\n  try {\n    const s = fstatSync(fd);\n    if (!s.isFile()) return { kind: \"refused\" };\n    const parent = lstatSync(path.dirname(statePath));\n    if (parent.isSymbolicLink() || !parent.isDirectory()) return { kind: \"refused\" };\n    const l = lstatSync(statePath);\n    if (l.isSymbolicLink() || l.dev !== s.dev || l.ino !== s.ino) return { kind: \"refused\" };\n    return {\n      kind: \"ok\",\n      raw: readFileSync(fd, \"utf-8\"),\n      key: `${s.dev}:${s.ino}:${s.mtimeMs}:${s.ctimeMs}:${s.size}`,\n    };\n  } catch {\n    return { kind: \"error\" };\n  } finally {\n    closeSync(fd);\n  }\n}\n\nexport function loadHistoricalEntityCanonicalIds(stateDir: string): Readonly<Record<string, string>> {\n  const result = readJournalFileNoFollow(path.join(stateDir, ENTITY_CANONICAL_ID_MIGRATION_FILE));\n  if (result.kind !== \"ok\") return {};\n  try {\n    return parseJournalMappings(result.raw);\n  } catch {\n    return {};\n  }\n}\n\n/**\n * Append a tombstone with its identity canonicalized against the CURRENT\n * journal, then recheck: a peer publishing a mapping inside the\n * resolve-to-append window would leave the guard under the legacy id while\n * lookups canonicalize. Each identity change appends the replacement FIRST\n * (AGENTS.md §14 — the retired fact must never be without an active guard),\n * then revokes the superseded one — a park makes the prior canonical\n * claimant a distinct entity, and a stale keyed guard under it would\n * suppress that entity's facts. When the journal will not settle, one final\n * replacement runs under the entity MUTATION lock (parks publish under it).\n */\nexport async function appendCanonicalizedTombstone(\n  stateDir: string,\n  input: { entityRef?: string; supersessionKey?: string },\n  currentIds: () => Readonly<Record<string, string>>,\n  append: (identity: TombstoneIdentity) => Promise<string | null>,\n  revoke: (tombstoneId: string) => Promise<unknown>,\n  label: string,\n): Promise<string | null> {\n  let refIds = currentIds();\n  let identity = canonicalizeTombstoneIdentity(input.entityRef, input.supersessionKey, refIds);\n  let result = await append(identity);\n  const replaceIfChanged = async (next: TombstoneIdentity): Promise<boolean> => {\n    if (next.entityRef === identity.entityRef && next.supersessionKey === identity.supersessionKey) {\n      return false;\n    }\n    identity = next;\n    const superseded = result;\n    result = await append(next);\n    if (superseded !== null) {\n      try {\n        await revoke(superseded);\n      } catch (err) {\n        log.warn(`failed to revoke superseded tombstone ${superseded} for ${label}: ${err}`);\n      }\n    }\n    return true;\n  };\n  for (let attempt = 0; attempt < 3; attempt += 1) {\n    const fresh = currentIds();\n    if (fresh === refIds) return result;\n    refIds = fresh;\n    if (!(await replaceIfChanged(canonicalizeTombstoneIdentity(input.entityRef, input.supersessionKey, fresh)))) {\n      return result;\n    }\n  }\n  await withEntityCanonicalMutationLock(stateDir, async () => {\n    await replaceIfChanged(canonicalizeTombstoneIdentity(input.entityRef, input.supersessionKey, currentIds()));\n  });\n  return result;\n}\n\n/**\n * Journal mapping table keyed by the journal FILE's identity, so a long-lived\n * StorageManager never canonicalizes against a stale snapshot after ANY other\n * writer changes the journal — a peer process completing a migration, or\n * `pruneBlocked()` parking a contested mapping (which rewrites the journal\n * without bumping any shared version). `writeState` publishes via\n * temp-file-plus-rename, so every journal write swaps the inode and the key\n * always moves — the identity is taken from the fstat of the SAME opened\n * inode the content is read from (no stat→read window). Reload cost is one\n * open per lookup and one journal parse per actual change.\n *\n * Failure semantics: last-known data is served ONLY for the SAME state dir\n * (module-level instances can face several stores — another store's table\n * must never leak in), and a failed read/parse never commits the journal's\n * identity, so the next lookup retries instead of caching an empty table\n * under a valid key.\n */\nexport class HistoricalEntityCanonicalIdCache {\n  private mappings: Readonly<Record<string, string>> = {};\n  private key: string | null = null;\n  private stateDir: string | null = null;\n\n  get(stateDir: string): Readonly<Record<string, string>> {\n    const lastKnown = this.stateDir === stateDir ? this.mappings : {};\n    const result = readJournalFileNoFollow(path.join(stateDir, ENTITY_CANONICAL_ID_MIGRATION_FILE));\n    if (result.kind === \"refused\") {\n      // Symlinked/non-regular journal: never follow it, never adopt its\n      // identity — serve this store's last-known table. If it later becomes\n      // a regular file its identity differs from the stored key and reloads.\n      log.warn(\"ignoring non-regular entity canonical-id journal (symlink refused)\");\n      return lastKnown;\n    }\n    if (result.kind === \"error\") {\n      // A TRANSIENT open/read failure (EACCES/EIO) must not dump a valid\n      // table for {}: a write during the outage would skip canonicalization\n      // AND its post-write identity check would compare equal. Serve this\n      // store's last-known table; only a genuine ENOENT means \"no journal\".\n      return lastKnown;\n    }\n    const key = result.kind === \"missing\" ? \"missing\" : result.key;\n    if (key !== this.key || stateDir !== this.stateDir) {\n      let table: Readonly<Record<string, string>> = {};\n      if (result.kind === \"ok\") {\n        try {\n          table = parseJournalMappings(result.raw);\n        } catch {\n          // Parse failed under a VALID identity: do not commit the key —\n          // the next lookup retries instead of pinning an empty table.\n          return lastKnown;\n        }\n      }\n      this.mappings = table;\n      this.key = key;\n      this.stateDir = stateDir;\n    }\n    return this.mappings;\n  }\n}\n\nexport function resolveHistoricalEntityCanonicalId(\n  normalized: string,\n  mappings: Readonly<Record<string, string>>,\n): string {\n  let current = normalized;\n  const seen = new Set<string>();\n  while (!seen.has(current)) {\n    seen.add(current);\n    // Own properties only: an unmapped id like `constructor` must not read\n    // Object.prototype and return a function (Codex P2, round 20).\n    const next = Object.hasOwn(mappings, current) ? mappings[current] : undefined;\n    if (!next || next === current) break;\n    current = next;\n  }\n  return current;\n}\n\n/**\n * Canonicalize the `entityRef` a memory-write caller supplied (issue #2213).\n *\n * Extraction and capture callers pass whatever id the LLM or user produced,\n * which can name a legacy id this migration already renamed. Resolving at the\n * WRITE boundary means store-mediated writes can never re-introduce legacy\n * references — which is what let the completed migration retire its recurring\n * full-corpus reference rewrite. It also keeps write-time tombstone lookups on\n * the same id space as migrated tombstones. Unknown ids pass through verbatim.\n */\nexport function canonicalizeEntityRefOption<T extends { entityRef?: string }>(\n  options: T,\n  mappings: Readonly<Record<string, string>>,\n): T {\n  // Non-strings (absent, or a JS caller's null/junk) pass through untouched:\n  // this boundary canonicalizes ids, it does not take over input validation\n  // the write path never performed — serialization already drops falsy refs.\n  if (typeof options.entityRef !== \"string\") return options;\n  return { ...options, entityRef: resolveHistoricalEntityCanonicalId(options.entityRef, mappings) };\n}\n\n/**\n * Canonicalize the effective `entityRef:` line inside a raw memory record's\n * leading frontmatter block (issue #2213). Bulk writers that persist record\n * bytes verbatim — capsule import/merge — are a write boundary too: a capsule\n * can carry pre-migration memories whose refs the target's completed journal\n * already renamed, and no later reconciliation pass exists to absorb them.\n *\n * Line selection mirrors the frontmatter parser and the migration's own\n * serializer: the LAST `entityRef` key wins (indentation tolerated), its\n * indent is preserved, and CRLF records keep their line endings. The closing\n * delimiter must be a standalone `---` line. Non-frontmatter content, records\n * without an `entityRef` line, and ids the journal does not map all pass\n * through byte-identical.\n */\nexport function canonicalizeEntityRefFrontmatter(\n  content: string,\n  mappings: Readonly<Record<string, string>>,\n): string {\n  if (Object.keys(mappings).length === 0) return content;\n  const loc = locateEntityRefLine(content);\n  if (loc === null) return content;\n  const canonical = resolveHistoricalEntityCanonicalId(loc.value, mappings);\n  if (canonical === loc.value) return content;\n  const line = loc.lines[loc.index]!;\n  const indent = /^\\s*/.exec(line)?.[0] ?? \"\";\n  loc.lines[loc.index] = `${indent}entityRef: ${canonical}${line.endsWith(\"\\r\") ? \"\\r\" : \"\"}`;\n  return loc.lines.join(\"\\n\") + content.slice(loc.closeIndex);\n}\n\n/** The raw `entityRef` value in a record's leading frontmatter, or null. */\nexport function readEntityRefFromFrontmatter(content: string): string | null {\n  return locateEntityRefLine(content)?.value ?? null;\n}\n\nfunction locateEntityRefLine(\n  content: string,\n): { lines: string[]; index: number; value: string; closeIndex: number } | null {\n  if (!/^---\\r?\\n/.test(content)) return null;\n  const close = /\\r?\\n---(?:\\r?\\n|$)/g;\n  close.lastIndex = content.indexOf(\"\\n\") + 1;\n  const closeMatch = close.exec(content);\n  if (!closeMatch) return null;\n  const lines = content.slice(0, closeMatch.index).split(\"\\n\");\n  let index = -1;\n  for (let i = 1; i < lines.length; i += 1) {\n    if (/^\\s*entityRef\\s*:/.test(lines[i] ?? \"\")) index = i;\n  }\n  if (index === -1) return null;\n  const line = lines[index]!;\n  const value = line.slice(line.indexOf(\":\") + 1).replace(/\\r$/, \"\").trim();\n  if (value.length === 0) return null;\n  return { lines, index, value, closeIndex: closeMatch.index };\n}\n\n/**\n * Reconcile-pending marker (issue #2213). Raw-byte memory writers that CANNOT\n * canonicalize inline — offline-sync file replication (opaque, possibly\n * encrypted buffers), consolidation-undo restores, governance-run restores —\n * touch this marker instead. The next migration invocation honors it by\n * running ONE bounded reference-reconciliation pass over the completed\n * journal's retained mappings, then clears it. This replaces the retired\n * every-run corpus rewrite with a signal that fires only when a raw writer\n * actually landed unvetted bytes.\n */\nexport const ENTITY_CANONICAL_ID_RECONCILE_MARKER = \"entity-canonical-id-reconcile.pending\";\n/** The generation a migration run renamed aside for consumption; a crash can strand it. */\nexport const ENTITY_CANONICAL_ID_RECONCILE_CONSUMING_MARKER = `${ENTITY_CANONICAL_ID_RECONCILE_MARKER}.consuming`;\n\nexport function requestEntityCanonicalIdReconcileSync(stateDir: string): void {\n  const markerPath = path.join(stateDir, ENTITY_CANONICAL_ID_RECONCILE_MARKER);\n  const temporary = `${markerPath}.${process.pid}.${randomUUID()}.tmp`;\n  try {\n    // Never write THROUGH a symlinked marker OR a symlinked state dir (repo\n    // rule: reject symlink traversal from memory directories). The parent is\n    // lstat-verified as a real directory — direct restore/import callers can\n    // reach this helper without validateRoots() — and temp-file-plus-rename\n    // handles the final component: rename() replaces a planted link ITSELF\n    // rather than following it, with no O_NOFOLLOW dependency.\n    const parent = lstatSync(stateDir);\n    if (parent.isSymbolicLink() || !parent.isDirectory()) {\n      log.warn(`refusing to write entity canonical-id reconcile marker: ${stateDir} is not a real directory`);\n      return;\n    }\n    const parentRealPath = realpathSync(stateDir);\n    writeFileSync(temporary, `${new Date().toISOString()}\\n`, { mode: 0o600 });\n    // Revalidate the parent between the temp write and publication (Codex\n    // P2, round 20): a state-dir swapped for a symlink after the check above\n    // would have landed the temp file through the link. Node has no openat,\n    // so the residual window is the realpath→rename gap — this recheck\n    // reduces check-then-use to the platform primitive's own atomicity.\n    const recheck = lstatSync(stateDir);\n    if (recheck.isSymbolicLink() || !recheck.isDirectory() || realpathSync(stateDir) !== parentRealPath) {\n      rmSync(temporary, { force: true });\n      log.warn(`refusing to publish entity canonical-id reconcile marker: ${stateDir} changed during write`);\n      return;\n    }\n    renameSync(temporary, markerPath);\n  } catch (error) {\n    rmSync(temporary, { force: true });\n    // Best effort by design: a marker failure must not fail the restore/sync\n    // that requested it (AGENTS.md §4). The reference stays legacy-but-readable\n    // until the next mapping change.\n    log.warn(`could not request entity canonical-id reconcile: ${error}`);\n  }\n}\n\nexport async function requestEntityCanonicalIdReconcile(stateDir: string): Promise<void> {\n  requestEntityCanonicalIdReconcileSync(stateDir);\n}\n\n/**\n * Post-persist TOCTOU guard (issue #2213). A writer resolves `entityRef`\n * against one journal generation, then awaits (snapshots, locks, fsyncs)\n * before its bytes land — a peer migration can publish AND finish its final\n * reference scan inside that window, leaving the just-written file behind.\n * Callers pass the mapping table captured at resolve time plus a fresh cache\n * read taken AFTER the write: the cache returns the identical object while\n * the journal file is unchanged, so an identity mismatch means the journal\n * moved mid-write and one bounded reconcile pass is requested.\n */\nexport function reconcileIfJournalMovedSync(\n  stateDir: string,\n  idsAtResolve: Readonly<Record<string, string>>,\n  idsAfterWrite: Readonly<Record<string, string>>,\n): void {\n  if (idsAtResolve === idsAfterWrite) return;\n  requestEntityCanonicalIdReconcileSync(stateDir);\n}\n\nexport async function reconcileIfJournalMoved(\n  stateDir: string,\n  idsAtResolve: Readonly<Record<string, string>>,\n  idsAfterWrite: Readonly<Record<string, string>>,\n): Promise<void> {\n  reconcileIfJournalMovedSync(stateDir, idsAtResolve, idsAfterWrite);\n}\n\n/**\n * Classify a raw write target for entity-reference handling (issue #2213):\n * - `\"memory\"` — hot recall / cold / archive record whose FRONTMATTER\n *   `entityRef` the writer must canonicalize at the write (and repair after).\n * - `\"entity\"` — an `entities/` page. Its migrated surface is relationship\n *   TARGETS in the body, which only `rewriteRelationshipTargets` understands;\n *   raw writers persist bytes faithfully and request the bounded reconcile\n *   pass instead of attempting a frontmatter rewrite.\n * - `\"outside\"` — transcripts, profiles, runtime state, and every other file\n *   outside the migration's scan scope: write byte-identical, no marker.\n */\nexport type EntityRefWritePathKind = \"memory\" | \"entity\" | \"outside\";\n\nexport function classifyEntityRefWritePath(baseDir: string, filePath: string): EntityRefWritePathKind {\n  if (!filePath.endsWith(\".md\")) return \"outside\";\n  const rel = path.relative(baseDir, filePath);\n  if (rel.startsWith(\"..\") || path.isAbsolute(rel)) return \"outside\";\n  const top = rel.split(path.sep)[0] ?? \"\";\n  if (top === \"entities\") return \"entity\";\n  return RECALL_FALLBACK_DIRS.includes(top) || top === \"cold\" || top === \"archive\" ? \"memory\" : \"outside\";\n}\n\n/** True when `filePath` is in the migration's scan scope at all. */\nexport function pathMayCarryEntityRefs(baseDir: string, filePath: string): boolean {\n  return classifyEntityRefWritePath(baseDir, filePath) !== \"outside\";\n}\n\n/**\n * Canonicalize a tombstone's identity fields at the append chokepoint\n * (issue #2213): emitters (forget, temporal supersession, pattern\n * reinforcement, supersede) build inputs from records that may have been\n * read before a peer migration completed. The supersession key embeds the\n * NORMALIZED entity segment (`entity::attr`), so it is re-prefixed when the\n * ref moved — otherwise the keyed guard lands in the legacy id space while\n * write-time lookups canonicalize, and a paraphrase resurrects.\n */\nexport interface TombstoneIdentity {\n  entityRef: string | undefined;\n  supersessionKey: string | undefined;\n}\n\nexport function canonicalizeTombstoneIdentity(\n  entityRef: string | undefined,\n  supersessionKey: string | undefined,\n  refIds: Readonly<Record<string, string>>,\n): TombstoneIdentity {\n  if (typeof entityRef !== \"string\") return { entityRef, supersessionKey };\n  const canonical = resolveHistoricalEntityCanonicalId(entityRef, refIds);\n  if (canonical === entityRef) return { entityRef, supersessionKey };\n  if (supersessionKey) {\n    const stalePrefix = `${normalizeSupersessionKey(entityRef)}::`;\n    if (supersessionKey.startsWith(stalePrefix)) {\n      supersessionKey = `${normalizeSupersessionKey(canonical)}::${supersessionKey.slice(stalePrefix.length)}`;\n    }\n  }\n  return { entityRef: canonical, supersessionKey };\n}\n\n/**\n * Post-persist repair (issue #2213): when the journal moved across a persist,\n * re-resolve the caller's ORIGINAL ref against the fresh table and rewrite\n * the file in place (bounded). When the journal will not settle, take the\n * entity MUTATION lock — parks/removals (the direction the reconcile pass\n * cannot repair, because the removed mapping is gone from the table) publish\n * under it — settle once, then request the marker for additive moves only.\n */\nexport async function repairEntityRefAfterJournalMove(options: {\n  stateDir: string;\n  currentIds: () => Readonly<Record<string, string>>;\n  idsAtResolve: Readonly<Record<string, string>>;\n  rawRef: string;\n  frontmatter: { entityRef?: string };\n  rewrite: () => Promise<void>;\n}): Promise<void> {\n  let refIds = options.idsAtResolve;\n  for (let attempt = 0; attempt < 3; attempt += 1) {\n    const fresh = options.currentIds();\n    if (fresh === refIds) return;\n    refIds = fresh;\n    const desired = resolveHistoricalEntityCanonicalId(options.rawRef, fresh);\n    if (desired === options.frontmatter.entityRef) return;\n    options.frontmatter.entityRef = desired;\n    await options.rewrite();\n  }\n  await withEntityCanonicalMutationLock(options.stateDir, async () => {\n    const desired = resolveHistoricalEntityCanonicalId(options.rawRef, options.currentIds());\n    if (desired !== options.frontmatter.entityRef) {\n      options.frontmatter.entityRef = desired;\n      await options.rewrite();\n    }\n  });\n  await requestEntityCanonicalIdReconcile(options.stateDir);\n}\n\n/**\n * Content-form counterpart of {@link repairEntityRefAfterJournalMove} for\n * async writers that persist raw record bytes (capsule import/merge,\n * binary-lifecycle redirects): same bounded loop, same locked settle.\n */\nexport async function repairContentAfterJournalMove(options: {\n  stateDir: string;\n  cache: HistoricalEntityCanonicalIdCache;\n  idsAtWrite: Readonly<Record<string, string>>;\n  rawContent: string;\n  lastWritten: string;\n  rewrite: (content: string) => Promise<void>;\n}): Promise<void> {\n  let refIds = options.idsAtWrite;\n  let written = options.lastWritten;\n  for (let attempt = 0; attempt < 3; attempt += 1) {\n    const fresh = options.cache.get(options.stateDir);\n    if (fresh === refIds) return;\n    refIds = fresh;\n    const desired = canonicalizeEntityRefFrontmatter(options.rawContent, fresh);\n    if (desired === written) return;\n    written = desired;\n    await options.rewrite(desired);\n  }\n  await withEntityCanonicalMutationLock(options.stateDir, async () => {\n    const desired = canonicalizeEntityRefFrontmatter(options.rawContent, options.cache.get(options.stateDir));\n    if (desired !== written) {\n      written = desired;\n      await options.rewrite(desired);\n    }\n  });\n  await requestEntityCanonicalIdReconcile(options.stateDir);\n}\n\n/**\n * Sync variant (space promotion, curation, review actions). Sync callers\n * cannot take the async mutation lock, so exhaustion surfaces a retryable\n * error after requesting the marker — a silent return could leave the bytes\n * on a parked canonical claimant the reconcile pass cannot restore.\n */\nexport function repairContentAfterJournalMoveSync(options: {\n  stateDir: string;\n  cache: HistoricalEntityCanonicalIdCache;\n  idsAtWrite: Readonly<Record<string, string>>;\n  rawContent: string;\n  lastWritten: string;\n  rewrite: (content: string) => void;\n}): void {\n  let refIds = options.idsAtWrite;\n  let written = options.lastWritten;\n  for (let attempt = 0; attempt < 3; attempt += 1) {\n    const fresh = options.cache.get(options.stateDir);\n    if (fresh === refIds) return;\n    refIds = fresh;\n    const desired = canonicalizeEntityRefFrontmatter(options.rawContent, fresh);\n    if (desired === written) return;\n    written = desired;\n    options.rewrite(desired);\n  }\n  requestEntityCanonicalIdReconcileSync(options.stateDir);\n  throw new Error(\n    \"entity canonical-id journal kept changing during post-write repair; retry the write\",\n  );\n}\n","/**\n * Entity canonical-id MUTATION lock (issue #2213).\n *\n * Serializes every writer whose correctness depends on the canonical-id\n * journal not moving mid-write: entity file mutations (entity-store),\n * per-pair file migration and journal pruning (entity-canonical-id-migration),\n * and the final settle attempt of the post-persist repair helpers\n * (entity-canonical-id-references). Lives in its own module so the reference\n * helpers can take the lock without importing the migration module, which\n * itself imports the reference helpers.\n */\nimport path from \"node:path\";\nimport { withHeldFileLock } from \"../utils/serialize-mutations.js\";\n\nconst ENTITY_CANONICAL_ID_MUTATION_LOCK_STALE_MS = 60_000;\nconst ENTITY_CANONICAL_ID_MUTATION_LOCK_MAX_WAIT_MS = 300_000;\n\nexport async function withEntityCanonicalMutationLock<T>(\n  stateDir: string,\n  task: (refreshLock: () => Promise<boolean>) => Promise<T>,\n): Promise<T> {\n  return withHeldFileLock(\n    path.join(stateDir, \"entity-canonical-id-mutation.lock\"),\n    {\n      staleMs: ENTITY_CANONICAL_ID_MUTATION_LOCK_STALE_MS,\n      maxWaitMs: ENTITY_CANONICAL_ID_MUTATION_LOCK_MAX_WAIT_MS,\n    },\n    async (acquired, lock) => {\n      if (!acquired) throw new Error(\"Timed out waiting for entity mutation lock.\");\n      return task(() => lock.refresh());\n    },\n  );\n}\n"],"mappings":"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","names":["path","path","path","path"]}

package/dist/chunk-57QKLRBV.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/mcp-read-only-tools.ts"],"sourcesContent":["/**\n * Conservative allowlist of canonical MCP tool suffixes that are\n * unambiguously read-only. Tools in this set are tagged with\n * `annotations: { readOnlyHint: true }` so ChatGPT (and other MCP\n * clients that honor the hint) can skip per-call confirmation.\n *\n * The list is suffix-based so it covers both the `remnic.*` and\n * `engram.*` naming forms. Anything not on it stays unannotated:\n * uncertainty is resolved as \"might mutate\".\n *\n * Excluded by construction: anything that writes, runs a pipeline,\n * flushes, applies, records, imports, or destructively deletes.\n */\nexport const MCP_READ_ONLY_TOOL_SUFFIXES: Readonly<Record<string, true>> = {\n  recall: true,\n  recall_explain: true,\n  recall_tier_explain: true,\n  recall_xray: true,\n  briefing: true,\n  wearables_status: true,\n  transcript_day: true,\n  transcript_search: true,\n  transcript_memories: true,\n  meetings_list: true,\n  meetings_get: true,\n  action_confidence: true,\n  capsule_list: true,\n  procedural_stats: true,\n  memory_get: true,\n  memory_timeline: true,\n  entity_get: true,\n  review_queue_list: true,\n  lcm_search: true,\n  continuity_incident_list: true,\n  identity_anchor_get: true,\n  memory_identity: true,\n  memory_search: true,\n  memory_profile: true,\n  memory_entities_list: true,\n  memory_questions: true,\n  memory_last_recall: true,\n  memory_intent_debug: true,\n  memory_qmd_debug: true,\n  memory_graph_explain: true,\n  graph_snapshot: true,\n  review_list: true,\n  profiling_report: true,\n  peer_list: true,\n  peer_get: true,\n  peer_profile_get: true,\n  console_state: true,\n  dreams_status: true,\n  codegraph_list_projects: true,\n  codegraph_index_status: true,\n  codegraph_search_graph: true,\n  codegraph_trace_path: true,\n  codegraph_detect_changes: true,\n  codegraph_query_graph: true,\n  codegraph_get_schema: true,\n  codegraph_get_snippet: true,\n  codegraph_get_architecture: true,\n  codegraph_search_code: true,\n};\n"],"mappings":";AAaO,IAAM,8BAA8D;AAAA,EACzE,QAAQ;AAAA,EACR,gBAAgB;AAAA,EAChB,qBAAqB;AAAA,EACrB,aAAa;AAAA,EACb,UAAU;AAAA,EACV,kBAAkB;AAAA,EAClB,gBAAgB;AAAA,EAChB,mBAAmB;AAAA,EACnB,qBAAqB;AAAA,EACrB,eAAe;AAAA,EACf,cAAc;AAAA,EACd,mBAAmB;AAAA,EACnB,cAAc;AAAA,EACd,kBAAkB;AAAA,EAClB,YAAY;AAAA,EACZ,iBAAiB;AAAA,EACjB,YAAY;AAAA,EACZ,mBAAmB;AAAA,EACnB,YAAY;AAAA,EACZ,0BAA0B;AAAA,EAC1B,qBAAqB;AAAA,EACrB,iBAAiB;AAAA,EACjB,eAAe;AAAA,EACf,gBAAgB;AAAA,EAChB,sBAAsB;AAAA,EACtB,kBAAkB;AAAA,EAClB,oBAAoB;AAAA,EACpB,qBAAqB;AAAA,EACrB,kBAAkB;AAAA,EAClB,sBAAsB;AAAA,EACtB,gBAAgB;AAAA,EAChB,aAAa;AAAA,EACb,kBAAkB;AAAA,EAClB,WAAW;AAAA,EACX,UAAU;AAAA,EACV,kBAAkB;AAAA,EAClB,eAAe;AAAA,EACf,eAAe;AAAA,EACf,yBAAyB;AAAA,EACzB,wBAAwB;AAAA,EACxB,wBAAwB;AAAA,EACxB,sBAAsB;AAAA,EACtB,0BAA0B;AAAA,EAC1B,uBAAuB;AAAA,EACvB,sBAAsB;AAAA,EACtB,uBAAuB;AAAA,EACvB,4BAA4B;AAAA,EAC5B,uBAAuB;AACzB;","names":[]}