@remnic/core 9.27.0 → 9.29.0

package/dist/{chunk-CIQXI47W.js → chunk-FCDWWCLX.js}

@@ -15,21 +15,23 @@ import {
   collectRetiredMemoriesForRebuild
 } from "./chunk-2QMKMVHH.js";
 import {
+  computeSupersessionKey,
+  normalizeSupersessionKey,
   supersessionKeysForFact
 } from "./chunk-DNHVPZOD.js";
-import {
-  assertMemoryFrontmatterId,
-  warnProjectionFallback
-} from "./chunk-HKF5VASQ.js";
 import {
   DEFAULT_CITATION_FORMAT,
   hasCitation,
   stripCitationForTemplate
 } from "./chunk-J6A3CX5N.js";
+import {
+  assertMemoryFrontmatterId,
+  warnProjectionFallback
+} from "./chunk-HKF5VASQ.js";
 import {
   SPECULATIVE_TTL_DAYS,
   confidenceTier
-} from "./chunk-V25OWXAC.js";
+} from "./chunk-HUHX2OCX.js";
 import {
   appendLifecycleEventsSerialized,
   drainPendingLifecycleLedgerForSync,
@@ -40,26 +42,21 @@ import {
   readMaybeEncryptedLines,
   readMemoryActionEventRowsFromLines,
   serializeLifecycleAppendPayload
-} from "./chunk-XKGPIWGI.js";
+} from "./chunk-OFHFH655.js";
 import {
   namespaceIdentityFromToken
 } from "./chunk-EGGE52UU.js";
-import {
-  assertPathInsideRoot,
-  pathIsInside
-} from "./chunk-GCASGYIO.js";
 import {
   withHeldFileLock
 } from "./chunk-WL5EBRDH.js";
 import {
-  inferMemoryStatus,
-  isArchivedMemoryPath,
-  toMemoryPathRel
-} from "./chunk-ILGC6JH6.js";
+  rewriteProjectedEntityReferences,
+  rewriteProjectedMemoryEntityReference
+} from "./chunk-WRJVB3C2.js";
 import {
-  normalizeProjectionPreview,
-  normalizeProjectionTags
-} from "./chunk-SCU65EZI.js";
+  assertPathInsideRoot,
+  pathIsInside
+} from "./chunk-GCASGYIO.js";
 import {
   markProjectedMemoryPathInvalid,
   openProjectionReadonly,
@@ -69,6 +66,15 @@ import {
   readProjectedMemoryTimeline,
   updateProjectedMemoryPath
 } from "./chunk-3CSX3ETE.js";
+import {
+  inferMemoryStatus,
+  isArchivedMemoryPath,
+  toMemoryPathRel
+} from "./chunk-ILGC6JH6.js";
+import {
+  normalizeProjectionPreview,
+  normalizeProjectionTags
+} from "./chunk-SCU65EZI.js";
 import {
   rotateMarkdownFileToArchive
 } from "./chunk-DM2T26WE.js";
@@ -81,6 +87,10 @@ import {
   serializeContinuityIncident,
   upsertContinuityLoopInMarkdown
 } from "./chunk-LDXUBPMO.js";
+import {
+  parseFaithfulnessField,
+  serializeFaithfulnessFields
+} from "./chunk-JYIJNNN3.js";
 import {
   composeMemoryEnvelope,
   isSealedMemoryEnvelope,
@@ -91,9 +101,8 @@ import {
   stripAttributesSuffix
 } from "./chunk-R3DJVOSM.js";
 import {
-  parseFaithfulnessField,
-  serializeFaithfulnessFields
-} from "./chunk-JYIJNNN3.js";
+  normalizeEntityName
+} from "./chunk-YXZG5TVN.js";
 import {
   createVersion
 } from "./chunk-5VQJBH2G.js";
@@ -131,20 +140,20 @@ import {
   reconcileProvenanceRead,
   serializeProvenanceFields
 } from "./chunk-5I4M26Q7.js";
-import {
-  sanitizeMemoryContent
-} from "./chunk-5GKPFL3S.js";
 import {
   matchEntitySchemaSection,
   normalizeEntityStructuredSection,
   sortStructuredSectionsBySchema
-} from "./chunk-4DJQYKMN.js";
+} from "./chunk-ZIKENA2C.js";
+import {
+  sanitizeMemoryContent
+} from "./chunk-5GKPFL3S.js";
 import {
   parseFlexibleIsoTimestamp
 } from "./chunk-P7FMDTKL.js";
 import {
   resolveNamespaceCapabilities
-} from "./chunk-RDQGLJRR.js";
+} from "./chunk-2XRE6FLM.js";
 import {
   isPathInsideStorageRoot
 } from "./chunk-FF4KLI5W.js";
@@ -195,24 +204,40 @@ function assertInjectedStorageRooted(label, memoryDir, injected) {
 
 // src/storage.ts
 import {
-  lstat as lstat2,
-  readdir as readdir4,
-  readFile,
-  realpath as realpath2,
+  lstat as lstat3,
+  readdir as readdir5,
+  readFile as readFile2,
+  realpath as realpath3,
   stat as stat3,
-  writeFile,
+  writeFile as writeFile2,
   mkdir as mkdir2,
-  unlink as unlink2,
+  unlink as unlink3,
   appendFile,
   open
 } from "fs/promises";
-import { appendFileSync, createReadStream, mkdirSync, readFileSync, statSync } from "fs";
+import { appendFileSync, createReadStream, mkdirSync, readFileSync as readFileSync2, statSync } from "fs";
 import { createHash as createHash5 } from "crypto";
-import path9 from "path";
+import path10 from "path";
 
 // src/storage/memory-read-store.ts
 import { lstat, readdir, realpath, stat } from "fs/promises";
 import path2 from "path";
+
+// src/storage/memory-frontmatter-metadata.ts
+var rawFrontmatterByMemory = /* @__PURE__ */ new WeakMap();
+function extractRawFrontmatter(raw) {
+  return raw.match(/^---\n([\s\S]*?)\n---\n?/)?.[1] ?? null;
+}
+function rememberRawFrontmatter(owner, raw) {
+  const frontmatter = extractRawFrontmatter(raw);
+  if (frontmatter !== null) rawFrontmatterByMemory.set(owner, frontmatter);
+  return owner;
+}
+function readRawFrontmatter(owner) {
+  return rawFrontmatterByMemory.get(owner);
+}
+
+// src/storage/memory-read-store.ts
 function isPropagatableReadError(err) {
   const code = err.code;
   return typeof code === "string" && code !== "ENOENT";
@@ -491,7 +516,7 @@ var MemoryReadStore = class {
       const raw = await readMaybeEncryptedFile(filePath, this.deps._secureStoreKey, this.deps.baseDir);
       const parsed = parseFrontmatter(raw);
       if (parsed) {
-        return {
+        return rememberRawFrontmatter({
           path: filePath,
           frontmatter: normalizeFrontmatterForPath(
             parsed.frontmatter,
@@ -499,7 +524,7 @@ var MemoryReadStore = class {
             parsed.content
           ),
           content: parsed.content
-        };
+        }, raw);
       }
       const normalizedPath = filePath.split(path2.sep).join("/");
       if (normalizedPath.includes("/entities/") && filePath.endsWith(".md")) {
@@ -714,10 +739,10 @@ var MARKDOWN_LIST_ITEM_CAN_INTERRUPT = /^(?:[-+*]|1[.)])[ \t]+/;
 var MARKDOWN_THEMATIC_BREAK = /^(?:(?:\*[ \t]*){3,}|(?:-[ \t]*){3,}|(?:_[ \t]*){3,})$/;
 var MARKDOWN_SETEXT_UNDERLINE = /^(?:=+|-+)$/;
 var MARKDOWN_BLOCK_QUOTE = /^>/;
-var MARKDOWN_LINK_REFERENCE = /^\[(?:\\.|[^\\\[\]])+\]:\s*(?:<[^>\n]*>|([^\s]+))(?:\s+(?:"[^"\n]*"|'[^'\n]*'|\([^)\n]*\)))?$/;
-var MARKDOWN_LINK_REFERENCE_LABEL = /^\[(?:\\.|[^\\\[\]])+\]:\s*$/;
+var MARKDOWN_LINK_REFERENCE = /^\[(?:\\.|[^\\\[\]])+\]:[ \t]*(?:<[^>\n]*>|([^\s]+))(?:[ \t]+(?:"[^"\n]*"|'[^'\n]*'|\([^)\n]*\)))?$/;
+var MARKDOWN_LINK_REFERENCE_LABEL = /^\[(?:\\.|[^\\\[\]])+\]:[ \t]*$/;
 var MARKDOWN_LINK_REFERENCE_CONTINUATION = /^ {1,3}(?:"[^"\n]*"|'[^'\n]*'|\([^)\n]*\))$/;
-var MARKDOWN_LINK_REFERENCE_DESTINATION_CONTINUATION = /^ {1,3}(?:<[^>\n]*>|(?!["'(])[^\s]+(?:\s+(?:"[^"\n]*"|'[^'\n]*'|\([^)\n]*\)))?)$/;
+var MARKDOWN_LINK_REFERENCE_DESTINATION_CONTINUATION = /^ {1,3}(?:<[^>\n]*>|(?!["'(])[^\s]+(?:[ \t]+(?:"[^"\n]*"|'[^'\n]*'|\([^)\n]*\)))?)$/;
 var UTF8_BOM = "\uFEFF";
 function isLastUpdatedHeader(line) {
   const withoutBom = line.startsWith(UTF8_BOM) ? line.slice(1) : line;
@@ -1036,7 +1061,7 @@ function shouldCloseHtmlBlock(line, endMarker) {
 function canStartGenericHtmlBlock(lines, index, previousHtmlTerminator) {
   const previousLine = lines[index - 1]?.content.trim() ?? "";
   if (previousLine === "") return true;
-  return isMetadataBoundary(previousLine, previousHtmlTerminator) && !isLastUpdatedHeader(previousLine) && !MARKDOWN_LIST_ITEM.test(previousLine) && !MARKDOWN_BLOCK_QUOTE.test(previousLine);
+  return isCompletedIndentedCodeBlock(lines, index) || isMetadataBoundary(previousLine, previousHtmlTerminator) && !isLastUpdatedHeader(previousLine) && !MARKDOWN_LIST_ITEM.test(previousLine) && !MARKDOWN_BLOCK_QUOTE.test(previousLine);
 }
 function isHtmlBlockBoundary(lines, index, htmlTerminatorIndexes) {
   if (htmlTerminatorIndexes.has(index)) return true;
@@ -1392,8 +1417,748 @@ function selfDeps(self) {
 }
 
 // src/storage/entity-store.ts
-import { readdir as readdir2, unlink } from "fs/promises";
+import { readdir as readdir3, unlink as unlink2 } from "fs/promises";
+import path4 from "path";
+
+// src/storage/entity-canonical-id-migration.ts
+import { randomUUID } from "crypto";
+import {
+  access,
+  lstat as lstat2,
+  readFile,
+  readdir as readdir2,
+  realpath as realpath2,
+  rename,
+  stat as statFile,
+  unlink,
+  writeFile
+} from "fs/promises";
 import path3 from "path";
+import { readFileSync } from "fs";
+import { z } from "zod";
+var ENTITY_CANONICAL_ID_MIGRATION_VERSION = 1;
+var ENTITY_CANONICAL_ID_MIGRATION_FILE = "entity-canonical-id-migration-v1.json";
+var ENTITY_CANONICAL_ID_MIGRATION_LOCK_STALE_MS = 6e4;
+var ENTITY_CANONICAL_ID_MIGRATION_LOCK_MAX_WAIT_MS = 3e5;
+var TOMBSTONE_LOCK_STALE_MS = 3e4;
+var TOMBSTONE_LOCK_MAX_WAIT_MS = 5e3;
+var ENTITY_CANONICAL_ID_MUTATION_LOCK_STALE_MS = 6e4;
+var ENTITY_CANONICAL_ID_MUTATION_LOCK_MAX_WAIT_MS = 3e5;
+var MEMORY_REWRITE_MAX_PASSES = 3;
+var ENTITY_MAPPING_RESCAN_MAX_PASSES = 3;
+function loadHistoricalEntityCanonicalIds(stateDir) {
+  const statePath2 = path3.join(stateDir, ENTITY_CANONICAL_ID_MIGRATION_FILE);
+  try {
+    const parsed = JSON.parse(readFileSync(statePath2, "utf-8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    const mappings = parsed.mappings;
+    if (!mappings || typeof mappings !== "object" || Array.isArray(mappings)) return {};
+    const cleaned = {};
+    for (const [legacyId, canonicalId] of Object.entries(mappings)) {
+      if (legacyId.length > 0 && typeof canonicalId === "string" && canonicalId.length > 0) {
+        cleaned[legacyId] = canonicalId;
+      }
+    }
+    return cleaned;
+  } catch {
+    return {};
+  }
+}
+function resolveHistoricalEntityCanonicalId(normalized, mappings) {
+  let current = normalized;
+  const seen = /* @__PURE__ */ new Set();
+  while (!seen.has(current)) {
+    seen.add(current);
+    const next = mappings[current];
+    if (!next || next === current) break;
+    current = next;
+  }
+  return current;
+}
+var EntityCanonicalIdMigrationStateSchema = z.object({
+  version: z.literal(ENTITY_CANONICAL_ID_MIGRATION_VERSION),
+  complete: z.boolean(),
+  mappings: z.record(z.string().min(1))
+});
+async function fingerprintPath(filePath) {
+  let fileStat;
+  try {
+    fileStat = await lstat2(filePath);
+  } catch (error) {
+    if (!isErrnoCode(error, "ENOENT")) throw error;
+  }
+  return fileStat ? `${fileStat.dev}:${fileStat.ino}:${fileStat.mtimeMs}:${fileStat.ctimeMs}:${fileStat.size}` : "missing";
+}
+async function getFingerprint(baseDir, entitiesDir, getCorpusScanVersion) {
+  const [entityFingerprint, aliasFingerprint] = await Promise.all([
+    fingerprintPath(entitiesDir),
+    fingerprintPath(path3.join(baseDir, "config", "aliases.json"))
+  ]);
+  return `${entityFingerprint}:${aliasFingerprint}:${getCorpusScanVersion()}`;
+}
+async function validateRoots(baseDir, entitiesDir, stateDir, archiveDir) {
+  let baseStat;
+  try {
+    baseStat = await lstat2(baseDir);
+  } catch (error) {
+    if (isErrnoCode(error, "ENOENT")) return;
+    throw error;
+  }
+  if (baseStat.isSymbolicLink() || !baseStat.isDirectory()) {
+    throw new Error(`Refusing entity canonical-id migration through unsafe memory root: ${baseDir}.`);
+  }
+  const memoryRoot = await realpath2(baseDir);
+  const roots = [
+    entitiesDir,
+    stateDir,
+    ...RECALL_FALLBACK_DIRS.map((directory) => path3.join(baseDir, directory)),
+    path3.join(baseDir, "cold"),
+    archiveDir
+  ];
+  for (const root of roots) {
+    let rootStat;
+    try {
+      rootStat = await lstat2(root);
+    } catch (error) {
+      if (isErrnoCode(error, "ENOENT")) continue;
+      throw error;
+    }
+    if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+      throw new Error(`Refusing entity canonical-id migration through unsafe memory root: ${root}.`);
+    }
+    assertPathInsideRoot(memoryRoot, await realpath2(root), root);
+  }
+}
+function statePath(deps) {
+  return path3.join(deps.stateDir, ENTITY_CANONICAL_ID_MIGRATION_FILE);
+}
+async function assertSafeMigrationStateFile(deps) {
+  const migrationStatePath = statePath(deps);
+  let fileStat;
+  try {
+    fileStat = await lstat2(migrationStatePath);
+  } catch (error) {
+    if (isErrnoCode(error, "ENOENT")) return;
+    throw error;
+  }
+  if (fileStat.isSymbolicLink() || !fileStat.isFile()) {
+    throw new Error(
+      `Refusing entity canonical-id migration through unsafe migration state file: ${migrationStatePath}.`
+    );
+  }
+  const [stateRoot, stateFile] = await Promise.all([
+    realpath2(deps.stateDir),
+    realpath2(migrationStatePath)
+  ]);
+  assertPathInsideRoot(stateRoot, stateFile, migrationStatePath);
+}
+async function assertSafeTombstoneFile(deps, tombstonePath) {
+  let fileStat;
+  try {
+    fileStat = await lstat2(tombstonePath);
+  } catch (error) {
+    if (isErrnoCode(error, "ENOENT")) return false;
+    throw error;
+  }
+  if (fileStat.isSymbolicLink() || !fileStat.isFile()) {
+    throw new Error(
+      `Refusing entity canonical-id migration through unsafe tombstone ledger: ${tombstonePath}.`
+    );
+  }
+  const [stateRoot, tombstoneFile] = await Promise.all([
+    realpath2(deps.stateDir),
+    realpath2(tombstonePath)
+  ]);
+  assertPathInsideRoot(stateRoot, tombstoneFile, tombstonePath);
+  return true;
+}
+function lockPath(deps) {
+  return path3.join(deps.stateDir, "entity-canonical-id-migration.lock");
+}
+async function withEntityCanonicalMutationLock(stateDir, task) {
+  return withHeldFileLock(
+    path3.join(stateDir, "entity-canonical-id-mutation.lock"),
+    {
+      staleMs: ENTITY_CANONICAL_ID_MUTATION_LOCK_STALE_MS,
+      maxWaitMs: ENTITY_CANONICAL_ID_MUTATION_LOCK_MAX_WAIT_MS
+    },
+    async (acquired, lock) => {
+      if (!acquired) throw new Error("Timed out waiting for entity mutation lock.");
+      return task(() => lock.refresh());
+    }
+  );
+}
+async function readState(deps) {
+  await assertSafeMigrationStateFile(deps);
+  let raw;
+  try {
+    raw = await readFile(statePath(deps), "utf-8");
+  } catch (error) {
+    if (isErrnoCode(error, "ENOENT")) return null;
+    throw error;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error("Invalid entity canonical-id migration state.");
+  }
+  const result = EntityCanonicalIdMigrationStateSchema.safeParse(parsed);
+  if (!result.success) throw new Error("Invalid entity canonical-id migration state.");
+  return result.data;
+}
+async function writeState(deps, state) {
+  const destination = statePath(deps);
+  const temporary = `${destination}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(state, null, 2)}
+`, "utf-8");
+    await rename(temporary, destination);
+  } finally {
+    await unlink(temporary).catch(() => void 0);
+  }
+}
+async function fileExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch (error) {
+    if (isErrnoCode(error, "ENOENT")) return false;
+    throw error;
+  }
+}
+async function sameFileIdentity(leftPath, rightPath) {
+  try {
+    const [left, right] = await Promise.all([statFile(leftPath), statFile(rightPath)]);
+    return left.dev === right.dev && left.ino === right.ino;
+  } catch (error) {
+    if (isErrnoCode(error, "ENOENT")) return false;
+    throw error;
+  }
+}
+function assertSafeEntityId(entityId) {
+  if (/[\/\\\0]/.test(entityId)) {
+    throw new Error(`Refusing entity canonical-id migration through unsafe entity id: ${entityId}.`);
+  }
+}
+async function assertNotSymlink(filePath, label) {
+  let stat4;
+  try {
+    stat4 = await lstat2(filePath);
+  } catch (error) {
+    if (isErrnoCode(error, "ENOENT")) return;
+    throw error;
+  }
+  if (stat4.isSymbolicLink()) {
+    throw new Error(`Refusing entity canonical-id migration through symlink: ${label}.`);
+  }
+}
+async function assertNotMemorySymlink(filePath) {
+  let stat4;
+  try {
+    stat4 = await lstat2(filePath);
+  } catch (error) {
+    if (isErrnoCode(error, "ENOENT")) return;
+    throw error;
+  }
+  if (stat4.isSymbolicLink()) {
+    throw new Error(`Refusing entity canonical-id migration through symlinked memory: ${filePath}.`);
+  }
+}
+async function assertEntityContentUnchanged(deps, filePath, expectedContent, legacyId) {
+  const latestContent = await deps.readStorageSecureFile(filePath);
+  if (latestContent !== expectedContent) {
+    throw new Error(`Legacy entity id ${legacyId} changed while migration was running; retry migration.`);
+  }
+}
+async function readSafeEntityEntries(entitiesDir) {
+  const rootStat = await lstat2(entitiesDir);
+  if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+    throw new Error("Refusing entity canonical-id migration through a symlinked or non-directory entities root.");
+  }
+  const entries = await readdir2(entitiesDir);
+  for (const entry of entries) {
+    await assertNotSymlink(path3.join(entitiesDir, entry), entry);
+  }
+  return entries;
+}
+async function discoverMappings(deps, knownMappings = {}) {
+  const mappings = {};
+  const canonicalOwners = /* @__PURE__ */ new Map();
+  const entityEntries = await readSafeEntityEntries(deps.entitiesDir);
+  for (const entry of entityEntries) {
+    if (!entry.endsWith(".md")) continue;
+    const legacyId = entry.slice(0, -".md".length);
+    assertSafeEntityId(legacyId);
+    const legacyPath = deps.resolveEntityFilePath(legacyId);
+    if (legacyPath === null) continue;
+    const entityContent = await deps.readStorageSecureFile(legacyPath);
+    if (!/^#[ \t]+[^\r\n \t]/m.test(entityContent) || !/^\*\*Type:\*\*[ \t]*[^\r\n \t]/m.test(entityContent)) {
+      throw new Error(`Cannot migrate malformed entity file ${entry}: missing name heading or type.`);
+    }
+    const entity = deps.parseEntityFile(entityContent);
+    if (!entity.name.trim() || !entity.type.trim()) {
+      throw new Error(`Cannot migrate malformed entity file ${entry}: missing name or type.`);
+    }
+    const canonicalId = deps.normalizeEntityName(entity.name, entity.type);
+    assertSafeEntityId(canonicalId);
+    if (legacyId === canonicalId) continue;
+    const canonicalPath = deps.resolveEntityFilePath(canonicalId);
+    if (canonicalPath === null) continue;
+    const canonicalExists = await fileExists(canonicalPath);
+    if (canonicalExists && await sameFileIdentity(legacyPath, canonicalPath) && knownMappings[legacyId] === canonicalId) continue;
+    if (canonicalExists) {
+      const canonicalContent2 = await deps.readStorageSecureFile(canonicalPath);
+      if (entityContent !== canonicalContent2) {
+        throw new Error(`Cannot migrate legacy entity id ${legacyId}: ${canonicalId} already exists.`);
+      }
+    }
+    const previousOwner = canonicalOwners.get(canonicalId);
+    if (previousOwner !== void 0 && previousOwner !== legacyId) {
+      throw new Error(
+        `Cannot migrate legacy entity ids ${previousOwner} and ${legacyId}: both normalize to ${canonicalId}.`
+      );
+    }
+    canonicalOwners.set(canonicalId, legacyId);
+    mappings[legacyId] = canonicalId;
+  }
+  return mappings;
+}
+async function rewriteReferences(deps, mappings, refreshLock) {
+  let rewroteColdMemory = false;
+  for (let pass = 0; pass < MEMORY_REWRITE_MAX_PASSES; pass += 1) {
+    deps.invalidateAllMemoriesCache();
+    deps.invalidateColdMemoriesCache();
+    const [hotMemories, coldMemories, archivedMemories] = await Promise.all([
+      deps.readAllMemories(),
+      deps.readAllColdMemories(),
+      deps.readArchivedMemories()
+    ]);
+    const seenPaths = /* @__PURE__ */ new Set();
+    let rewroteAny = false;
+    for (const memory of [...hotMemories, ...coldMemories, ...archivedMemories]) {
+      const memoryPath = path3.resolve(memory.path);
+      if (seenPaths.has(memoryPath)) continue;
+      seenPaths.add(memoryPath);
+      const previousEntityRef = memory.frontmatter.entityRef;
+      const canonicalId = previousEntityRef ? mappings[previousEntityRef] : void 0;
+      if (!previousEntityRef || !canonicalId) continue;
+      await assertNotMemorySymlink(memory.path);
+      const observedMemoryFingerprint = await fingerprintPath(memory.path);
+      if (observedMemoryFingerprint === "missing") continue;
+      if (!await refreshLock()) throw new Error("Lost entity canonical-id migration lock.");
+      const latestMemory = await deps.readMemoryByPath(memory.path);
+      if (!latestMemory) continue;
+      const latestMemoryFingerprint = await fingerprintPath(latestMemory.path);
+      if (latestMemoryFingerprint !== observedMemoryFingerprint) continue;
+      const latestPreviousEntityRef = latestMemory.frontmatter.entityRef;
+      const latestCanonicalId = latestPreviousEntityRef ? mappings[latestPreviousEntityRef] : void 0;
+      if (!latestPreviousEntityRef || !latestCanonicalId) continue;
+      const memoryEncrypted = await deps.isEncryptedStorageFile(latestMemory.path);
+      if (await fingerprintPath(latestMemory.path) !== latestMemoryFingerprint) continue;
+      await deps.snapshotBeforeWrite(latestMemory.path, "write");
+      if (await fingerprintPath(latestMemory.path) !== latestMemoryFingerprint) continue;
+      await deps.writeStorageSecureFile(
+        latestMemory.path,
+        deps.serializeMemoryWithEntityRef(latestMemory, latestCanonicalId),
+        memoryEncrypted
+      );
+      await deps.rewriteProjectedMemoryEntityReference(
+        latestMemory.frontmatter.id,
+        latestPreviousEntityRef,
+        latestCanonicalId
+      );
+      rewroteAny = true;
+      rewroteColdMemory ||= latestMemory.path.includes(`${path3.sep}cold${path3.sep}`);
+    }
+    if (!rewroteAny) return { rewroteColdMemory };
+  }
+  throw new Error("Memory references changed while entity canonical-id migration was running; retry migration.");
+}
+function rewriteTombstoneLine(line, mappings, normalizedMappings) {
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return line;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return line;
+  const tombstone = parsed;
+  let changed = false;
+  if (typeof tombstone.entityRef === "string") {
+    const canonicalId = mappings[tombstone.entityRef];
+    if (canonicalId) {
+      tombstone.entityRef = canonicalId;
+      changed = true;
+    }
+  }
+  if (typeof tombstone.supersessionKey === "string") {
+    const separator = tombstone.supersessionKey.indexOf("::");
+    if (separator < 0) return changed ? JSON.stringify(tombstone) : line;
+    const normalizedLegacyId = normalizeSupersessionKey(tombstone.supersessionKey.slice(0, separator));
+    const canonicalId = normalizedMappings.get(normalizedLegacyId);
+    if (canonicalId) {
+      const canonicalKey = computeSupersessionKey(canonicalId, tombstone.supersessionKey.slice(separator + 2));
+      if (canonicalKey) {
+        tombstone.supersessionKey = canonicalKey;
+        changed = true;
+      }
+    }
+  }
+  return changed ? JSON.stringify(tombstone) : line;
+}
+async function rewriteTombstoneReferences(deps, mappings, refreshLock) {
+  const tombstonePath = path3.join(deps.stateDir, "tombstones.jsonl");
+  const normalizedMappings = /* @__PURE__ */ new Map();
+  for (const [legacyId, canonicalId] of Object.entries(mappings)) {
+    const normalizedLegacyId = normalizeSupersessionKey(legacyId);
+    if (normalizedLegacyId && !normalizedMappings.has(normalizedLegacyId)) {
+      normalizedMappings.set(normalizedLegacyId, canonicalId);
+    }
+  }
+  await withHeldFileLock(
+    path3.join(deps.stateDir, "tombstones.lock"),
+    {
+      staleMs: TOMBSTONE_LOCK_STALE_MS,
+      maxWaitMs: TOMBSTONE_LOCK_MAX_WAIT_MS
+    },
+    async (acquired, tombstoneLock) => {
+      if (!acquired) throw new Error("Timed out waiting for active tombstone migration.");
+      if (!await assertSafeTombstoneFile(deps, tombstonePath)) return;
+      const tombstoneEncrypted = await deps.isEncryptedStorageFile(tombstonePath);
+      const original = await deps.readStorageSecureFile(tombstonePath);
+      let changed = false;
+      const rewritten = original.split("\n").map((line) => {
+        const next = rewriteTombstoneLine(line, mappings, normalizedMappings);
+        changed ||= next !== line;
+        return next;
+      }).join("\n");
+      if (!changed) return;
+      if (!await refreshLock()) throw new Error("Lost entity canonical-id migration lock.");
+      if (!await tombstoneLock.refresh()) throw new Error("Lost tombstone migration lock.");
+      await deps.snapshotBeforeWrite(tombstonePath, "write");
+      await deps.writeStorageSecureFile(tombstonePath, rewritten, tombstoneEncrypted);
+    }
+  );
+}
+async function rewriteRelationshipTargets(deps, mappings, refreshLock) {
+  let rewritten = false;
+  const entries = await readSafeEntityEntries(deps.entitiesDir);
+  for (const entry of entries) {
+    if (!entry.endsWith(".md")) continue;
+    const entityPath = deps.resolveEntityFilePath(entry.slice(0, -".md".length));
+    if (entityPath === null) continue;
+    const observedEntityFingerprint = await fingerprintPath(entityPath);
+    if (observedEntityFingerprint === "missing") continue;
+    const entity = deps.parseEntityFile(await deps.readStorageSecureFile(entityPath));
+    const relationships = entity.relationships.map((relationship) => {
+      const target = mappings[relationship.target];
+      return target ? { ...relationship, target } : relationship;
+    });
+    if (relationships.every((relationship, index) => relationship === entity.relationships[index])) continue;
+    const rewroteEntity = await withEntityCanonicalMutationLock(
+      deps.stateDir,
+      async (refreshEntityLock) => {
+        if (!await refreshLock()) throw new Error("Lost entity canonical-id migration lock.");
+        const latestEntity = deps.parseEntityFile(await deps.readStorageSecureFile(entityPath));
+        if (await fingerprintPath(entityPath) !== observedEntityFingerprint) return false;
+        const latestRelationships = latestEntity.relationships.map((relationship) => {
+          const target = mappings[relationship.target];
+          return target ? { ...relationship, target } : relationship;
+        });
+        if (latestRelationships.every((relationship, index) => relationship === latestEntity.relationships[index])) {
+          return false;
+        }
+        const entityEncrypted = await deps.isEncryptedStorageFile(entityPath);
+        if (!await refreshEntityLock()) throw new Error("Lost entity mutation lock.");
+        if (await fingerprintPath(entityPath) !== observedEntityFingerprint) return false;
+        await deps.snapshotBeforeWrite(entityPath, "write");
+        if (await fingerprintPath(entityPath) !== observedEntityFingerprint) return false;
+        await deps.writeStorageSecureFile(
+          entityPath,
+          deps.serializeEntityFile({ ...latestEntity, relationships: latestRelationships }),
+          entityEncrypted
+        );
+        return true;
+      }
+    );
+    rewritten ||= rewroteEntity;
+  }
+  return rewritten;
+}
+async function rewriteKnownReferences(deps, mappings, refreshLock) {
+  await rewriteRelationshipTargets(deps, mappings, refreshLock);
+  let rewroteColdMemory = (await rewriteReferences(deps, mappings, refreshLock)).rewroteColdMemory;
+  await rewriteTombstoneReferences(deps, mappings, refreshLock);
+  await deps.rewriteProjectedEntityReferences(mappings);
+  const finalMemoryPass = await rewriteReferences(deps, mappings, refreshLock);
+  rewroteColdMemory ||= finalMemoryPass.rewroteColdMemory;
+  return rewroteColdMemory;
+}
+function wouldCreateMappingCycle(mappings, legacyId, canonicalId) {
+  let current = canonicalId;
+  const seen = /* @__PURE__ */ new Set();
+  while (true) {
+    if (current === legacyId) return true;
+    if (seen.has(current)) return false;
+    seen.add(current);
+    const next = mappings[current];
+    if (!next || next === current) return false;
+    current = next;
+  }
+}
+function rejectMappingCycles(existing, discovered) {
+  const accepted = {};
+  const merged = { ...existing };
+  for (const [legacyId, canonicalId] of Object.entries(discovered)) {
+    if (merged[legacyId] === void 0 && wouldCreateMappingCycle(merged, legacyId, canonicalId)) continue;
+    accepted[legacyId] = canonicalId;
+    merged[legacyId] = canonicalId;
+  }
+  return accepted;
+}
+function mergeDiscoveredMappings(existing, discovered) {
+  const merged = { ...existing };
+  const canonicalOwners = /* @__PURE__ */ new Map();
+  for (const [legacyId, canonicalId] of Object.entries(discovered)) {
+    const previousMapping = merged[legacyId];
+    if (previousMapping !== void 0 && previousMapping !== canonicalId) {
+      throw new Error(`Legacy entity id ${legacyId} changed canonical target during migration.`);
+    }
+    if (previousMapping === void 0 && wouldCreateMappingCycle(merged, legacyId, canonicalId)) continue;
+    const previousOwner = canonicalOwners.get(canonicalId);
+    if (previousOwner !== void 0 && previousOwner !== legacyId) {
+      throw new Error(
+        `Cannot migrate legacy entity ids ${previousOwner} and ${legacyId}: both normalize to ${canonicalId}.`
+      );
+    }
+    merged[legacyId] = canonicalId;
+    canonicalOwners.set(canonicalId, legacyId);
+  }
+  return merged;
+}
+function collapseMappings(mappings) {
+  const collapsed = {};
+  for (const legacyId of Object.keys(mappings)) {
+    let current = legacyId;
+    const seen = /* @__PURE__ */ new Set();
+    while (true) {
+      const next = mappings[current];
+      if (!next || next === current) break;
+      if (seen.has(current)) {
+        throw new Error(`Entity canonical-id migration mapping cycle includes ${legacyId}.`);
+      }
+      seen.add(current);
+      current = next;
+    }
+    if (current !== legacyId) collapsed[legacyId] = current;
+  }
+  return collapsed;
+}
+async function migrateEntityFilePair(deps, legacyId, canonicalId, refreshMigrationLock) {
+  return withEntityCanonicalMutationLock(deps.stateDir, async (refreshEntityLock) => {
+    assertSafeEntityId(legacyId);
+    assertSafeEntityId(canonicalId);
+    const legacyPath = deps.resolveEntityFilePath(legacyId);
+    const canonicalPath = deps.resolveEntityFilePath(canonicalId);
+    if (legacyPath === null || canonicalPath === null) {
+      throw new Error("Invalid entity canonical-id migration path.");
+    }
+    await assertNotSymlink(legacyPath, legacyId);
+    await assertNotSymlink(canonicalPath, canonicalId);
+    const legacyExists = await fileExists(legacyPath);
+    const canonicalExists = await fileExists(canonicalPath);
+    if (!legacyExists && !canonicalExists) return { deferred: true, progressed: false };
+    if (legacyExists && canonicalExists) {
+      if (await sameFileIdentity(legacyPath, canonicalPath)) return { deferred: false, progressed: false };
+      const [legacyContent, canonicalContent2, legacyEncrypted, canonicalEncrypted] = await Promise.all([
+        deps.readStorageSecureFile(legacyPath),
+        deps.readStorageSecureFile(canonicalPath),
+        deps.isEncryptedStorageFile(legacyPath),
+        deps.isEncryptedStorageFile(canonicalPath)
+      ]);
+      if (legacyContent !== canonicalContent2) {
+        throw new Error(`Cannot migrate legacy entity id ${legacyId}: ${canonicalId} already exists.`);
+      }
+      if (legacyEncrypted && !canonicalEncrypted) {
+        if (!await refreshMigrationLock() || !await refreshEntityLock()) {
+          throw new Error("Lost entity canonical-id migration lock.");
+        }
+        await deps.snapshotBeforeWrite(canonicalPath, "write");
+        await deps.writeStorageSecureFile(canonicalPath, legacyContent, true);
+        if (await deps.readStorageSecureFile(canonicalPath) !== legacyContent) {
+          throw new Error(`Cannot verify migrated entity id ${canonicalId}.`);
+        }
+      }
+      if (!await refreshMigrationLock() || !await refreshEntityLock()) {
+        throw new Error("Lost entity canonical-id migration lock.");
+      }
+      await deps.snapshotBeforeWrite(legacyPath, "write");
+      await assertNotSymlink(legacyPath, legacyId);
+      await assertEntityContentUnchanged(deps, legacyPath, legacyContent, legacyId);
+      await unlink(legacyPath);
+      return { deferred: false, progressed: true };
+    }
+    if (!legacyExists) return { deferred: false, progressed: false };
+    if (!await refreshMigrationLock() || !await refreshEntityLock()) {
+      throw new Error("Lost entity canonical-id migration lock.");
+    }
+    const entityEncrypted = await deps.isEncryptedStorageFile(legacyPath);
+    const entityContent = await deps.readStorageSecureFile(legacyPath);
+    await assertNotSymlink(legacyPath, legacyId);
+    await assertEntityContentUnchanged(deps, legacyPath, entityContent, legacyId);
+    let canonicalFingerprintAfterWrite = null;
+    try {
+      await deps.writeStorageSecureFile(canonicalPath, entityContent, entityEncrypted);
+      canonicalFingerprintAfterWrite = await fingerprintPath(canonicalPath);
+      if (await deps.readStorageSecureFile(canonicalPath) !== entityContent) {
+        throw new Error(`Cannot verify migrated entity id ${canonicalId}.`);
+      }
+      if (!await refreshMigrationLock() || !await refreshEntityLock()) {
+        throw new Error("Lost entity canonical-id migration lock.");
+      }
+      await deps.snapshotBeforeWrite(legacyPath, "write");
+      await assertNotSymlink(legacyPath, legacyId);
+      await assertEntityContentUnchanged(deps, legacyPath, entityContent, legacyId);
+      await unlink(legacyPath);
+    } catch (error) {
+      if (!canonicalExists && canonicalFingerprintAfterWrite !== null) {
+        try {
+          if (await fingerprintPath(canonicalPath) === canonicalFingerprintAfterWrite) {
+            await assertNotSymlink(canonicalPath, canonicalId);
+            await unlink(canonicalPath);
+          }
+        } catch {
+        }
+      }
+      throw error;
+    }
+    return { deferred: false, progressed: true };
+  });
+}
+async function migrateLegacyEntityCanonicalIds(deps) {
+  return withHeldFileLock(
+    lockPath(deps),
+    {
+      staleMs: ENTITY_CANONICAL_ID_MIGRATION_LOCK_STALE_MS,
+      maxWaitMs: ENTITY_CANONICAL_ID_MIGRATION_LOCK_MAX_WAIT_MS
+    },
+    async (acquired, lock) => {
+      if (!acquired) throw new Error("Timed out waiting for active entity canonical-id migration.");
+      await deps.validateMemoryScanRoots?.();
+      await readSafeEntityEntries(deps.entitiesDir);
+      let state = await readState(deps);
+      if (!state) {
+        state = {
+          version: ENTITY_CANONICAL_ID_MIGRATION_VERSION,
+          complete: false,
+          mappings: {}
+        };
+      }
+      const previousMappings = state.mappings;
+      const collapsedMappings = collapseMappings(previousMappings);
+      const mappingsChanged = Object.keys(collapsedMappings).length !== Object.keys(previousMappings).length || Object.entries(collapsedMappings).some(
+        ([legacyId, canonicalId]) => previousMappings[legacyId] !== canonicalId
+      );
+      state = { ...state, mappings: collapsedMappings };
+      for (let migrationPass = 0; migrationPass < ENTITY_MAPPING_RESCAN_MAX_PASSES; migrationPass += 1) {
+        if (!await lock.refresh()) throw new Error("Lost entity canonical-id migration lock.");
+        const discoveredBefore = rejectMappingCycles(
+          state.mappings,
+          await discoverMappings(deps, state.mappings)
+        );
+        const mergedBefore = collapseMappings(mergeDiscoveredMappings(state.mappings, discoveredBefore));
+        if (state.complete && Object.keys(discoveredBefore).length === 0 && !mappingsChanged) {
+          if (Object.keys(state.mappings).length === 0) return deps.readMigrationFingerprint?.();
+          const rewroteColdMemory2 = await rewriteKnownReferences(
+            deps,
+            state.mappings,
+            () => lock.refresh()
+          );
+          deps.invalidateKnowledgeIndexCache();
+          deps.invalidateAllMemoriesCache();
+          if (rewroteColdMemory2) deps.invalidateColdMemoriesCache();
+          deps.bumpMemoryStatusVersion();
+          return deps.readMigrationFingerprint?.();
+        }
+        if (state.complete || Object.keys(discoveredBefore).length > 0 || Object.keys(mergedBefore).length !== Object.keys(state.mappings).length) {
+          state = { ...state, complete: false, mappings: mergedBefore };
+          await writeState(deps, state);
+        }
+        if (Object.keys(state.mappings).length === 0) {
+          if (!await lock.refresh()) throw new Error("Lost entity canonical-id migration lock.");
+          const discoveredAfter2 = rejectMappingCycles(
+            state.mappings,
+            await discoverMappings(deps, state.mappings)
+          );
+          if (Object.keys(discoveredAfter2).length === 0) {
+            await writeState(deps, { ...state, complete: true });
+            return deps.readMigrationFingerprint?.();
+          }
+          state = {
+            ...state,
+            complete: false,
+            mappings: collapseMappings(mergeDiscoveredMappings(state.mappings, discoveredAfter2))
+          };
+          await writeState(deps, state);
+          continue;
+        }
+        let pendingMappings = Object.entries(state.mappings);
+        while (pendingMappings.length > 0) {
+          const deferredMappings = [];
+          let progressed = false;
+          for (const [legacyId, canonicalId] of pendingMappings) {
+            const result = await migrateEntityFilePair(
+              deps,
+              legacyId,
+              canonicalId,
+              () => lock.refresh()
+            );
+            if (result.deferred) {
+              deferredMappings.push([legacyId, canonicalId]);
+            }
+            progressed ||= result.progressed;
+          }
+          if (deferredMappings.length === 0) break;
+          if (!progressed) {
+            const [legacyId, canonicalId] = deferredMappings[0];
+            throw new Error(
+              `Cannot migrate legacy entity id ${legacyId}: both files are missing and no intermediate mapping can advance migration.`
+            );
+          }
+          pendingMappings = deferredMappings;
+        }
+        const rewroteColdMemory = await rewriteKnownReferences(
+          deps,
+          state.mappings,
+          () => lock.refresh()
+        );
+        deps.invalidateKnowledgeIndexCache();
+        deps.invalidateAllMemoriesCache();
+        if (rewroteColdMemory) deps.invalidateColdMemoriesCache();
+        deps.bumpMemoryStatusVersion();
+        if (!await lock.refresh()) throw new Error("Lost entity canonical-id migration lock.");
+        const discoveredAfter = rejectMappingCycles(
+          state.mappings,
+          await discoverMappings(deps, state.mappings)
+        );
+        if (Object.keys(discoveredAfter).length === 0) {
+          await writeState(deps, { ...state, complete: true });
+          return deps.readMigrationFingerprint?.();
+        }
+        state = {
+          ...state,
+          complete: false,
+          mappings: collapseMappings(mergeDiscoveredMappings(state.mappings, discoveredAfter))
+        };
+        await writeState(deps, state);
+      }
+      throw new Error("Entity canonical-id migration mappings changed while migration was running; retry migration.");
+    }
+  );
+}
+
+// src/storage/entity-store.ts
 var EntityStore = class {
   constructor(deps) {
     this.deps = deps;
@@ -1405,6 +2170,12 @@ var EntityStore = class {
   }
   async writeEntity(name, type, facts, options = {}) {
     await this.deps.ensureDirectories();
+    return withEntityCanonicalMutationLock(
+      path4.join(this.deps.baseDir, "state"),
+      () => this.writeEntityUnlocked(name, type, facts, options)
+    );
+  }
+  async writeEntityUnlocked(name, type, facts, options = {}) {
     if (typeof name !== "string" || !name.trim() || typeof type !== "string" || !type.trim()) {
       log.warn("writeEntity: invalid entity payload, skipping", {
         nameType: typeof name,
@@ -1421,7 +2192,7 @@ var EntityStore = class {
       log.debug(`fuzzy match: "${normalized}" \u2192 existing "${match}"`);
       normalized = match;
     }
-    const filePath = path3.join(this.deps.entitiesDir, `${normalized}.md`);
+    const filePath = path4.join(this.deps.entitiesDir, `${normalized}.md`);
     let entity = {
       name,
       type,
@@ -1522,7 +2293,7 @@ var EntityStore = class {
   /** Return sorted list of entity filenames (without .md extension) */
   async listEntityNames() {
     try {
-      const entries = await readdir2(this.deps.entitiesDir);
+      const entries = await readdir3(this.deps.entitiesDir);
       return entries.filter((e) => e.endsWith(".md")).map((e) => e.replace(".md", "")).sort();
     } catch {
       return [];
@@ -1532,7 +2303,13 @@ var EntityStore = class {
    * Set or rewrite the synthesis layer of an entity file.
    */
   async updateEntitySynthesis(name, synthesis, options = {}) {
-    const filePath = path3.join(this.deps.entitiesDir, `${name}.md`);
+    return withEntityCanonicalMutationLock(
+      path4.join(this.deps.baseDir, "state"),
+      () => this.updateEntitySynthesisUnlocked(name, synthesis, options)
+    );
+  }
+  async updateEntitySynthesisUnlocked(name, synthesis, options = {}) {
+    const filePath = path4.join(this.deps.entitiesDir, `${name}.md`);
     let entity;
     try {
       const content = await this.deps.readStorageSecureFile(filePath);
@@ -1574,7 +2351,7 @@ var EntityStore = class {
     const cached = getCachedEntities(this.deps.baseDir, currentVersion, cacheKey);
     if (cached) return cached;
     try {
-      const entries = await readdir2(this.deps.entitiesDir);
+      const entries = await readdir3(this.deps.entitiesDir);
       const mdFiles = entries.filter((e) => e.endsWith(".md"));
       if (mdFiles.length === 0) return [];
       const BATCH_SIZE = 100;
@@ -1584,7 +2361,7 @@ var EntityStore = class {
         const results = await Promise.all(
           batch.map(async (entry) => {
             try {
-              return await this.deps.readStorageSecureFile(path3.join(this.deps.entitiesDir, entry));
+              return await this.deps.readStorageSecureFile(path4.join(this.deps.entitiesDir, entry));
             } catch (err) {
               if (err instanceof SecureStoreLockedError) throw err;
               if (!isErrnoCode(err, "ENOENT")) throw err;
@@ -1657,9 +2434,15 @@ ${rows.join("\n")}
    * Returns count of files merged.
    */
   async mergeFragmentedEntities() {
+    return withEntityCanonicalMutationLock(
+      path4.join(this.deps.baseDir, "state"),
+      () => this.mergeFragmentedEntitiesUnlocked()
+    );
+  }
+  async mergeFragmentedEntitiesUnlocked() {
     let merged = 0;
     try {
-      const entries = await readdir2(this.deps.entitiesDir);
+      const entries = await readdir3(this.deps.entitiesDir);
       const mdFiles = entries.filter((e) => e.endsWith(".md"));
       const groups = /* @__PURE__ */ new Map();
       for (const file of mdFiles) {
@@ -1697,7 +2480,7 @@ ${rows.join("\n")}
           extraSections: []
         };
         for (const file of files) {
-          const filePath = path3.join(this.deps.entitiesDir, file);
+          const filePath = path4.join(this.deps.entitiesDir, file);
           try {
             const content = await this.deps.readStorageSecureFile(filePath);
             const parsed = parseEntityFile(content, this.deps.entitySchemas);
@@ -1828,13 +2611,13 @@ ${rows.join("\n")}
         }
         mergedEntity.created = mergedEntity.created || mergedEntity.updated || (/* @__PURE__ */ new Date()).toISOString();
         mergedEntity.updated = mergedEntity.updated || (/* @__PURE__ */ new Date()).toISOString();
-        const canonicalPath = path3.join(this.deps.entitiesDir, `${canonical}.md`);
+        const canonicalPath = path4.join(this.deps.entitiesDir, `${canonical}.md`);
         await this.deps.writeStorageSecureFile(canonicalPath, serializeEntityFile(mergedEntity, this.deps.entitySchemas));
         for (const file of files) {
-          const filePath = path3.join(this.deps.entitiesDir, file);
+          const filePath = path4.join(this.deps.entitiesDir, file);
           if (filePath !== canonicalPath) {
             try {
-              await unlink(filePath);
+              await unlink2(filePath);
               merged++;
               log.debug(`merged entity ${file} \u2192 ${canonical}.md`);
             } catch {
@@ -1850,8 +2633,8 @@ ${rows.join("\n")}
 };
 
 // src/storage/identity-continuity-store.ts
-import { readdir as readdir3 } from "fs/promises";
-import path4 from "path";
+import { readdir as readdir4 } from "fs/promises";
+import path5 from "path";
 var IdentityContinuityStore = class {
   constructor(deps) {
     this.deps = deps;
@@ -1876,7 +2659,7 @@ var IdentityContinuityStore = class {
     const date = nowIso.slice(0, 10);
     const id = this.deps.generateId("incident");
     const incident = createContinuityIncidentRecord(id, input, nowIso);
-    const filePath = path4.join(this.deps.identityIncidentsDir, `${date}-${id}.md`);
+    const filePath = path5.join(this.deps.identityIncidentsDir, `${date}-${id}.md`);
     await this.deps.writeStorageSecureFile(filePath, serializeContinuityIncident(incident));
     return { ...incident, filePath };
   }
@@ -1889,7 +2672,7 @@ var IdentityContinuityStore = class {
       const incidents = [];
       for (const file of candidates) {
         if (incidents.length >= cappedLimit) break;
-        const filePath = path4.join(this.deps.identityIncidentsDir, file);
+        const filePath = path5.join(this.deps.identityIncidentsDir, file);
         try {
           const raw = await this.deps.readStorageSecureFile(filePath);
           const parsed = parseContinuityIncident(raw);
@@ -1920,7 +2703,7 @@ var IdentityContinuityStore = class {
     await this.deps.ensureDirectories();
     const safeKey = this.sanitizeIdentityAuditKey(key);
     const dir = period === "weekly" ? this.deps.identityAuditsWeeklyDir : this.deps.identityAuditsMonthlyDir;
-    const filePath = path4.join(dir, `${safeKey}.md`);
+    const filePath = path5.join(dir, `${safeKey}.md`);
     await this.deps.writeStorageSecureFile(filePath, content);
     return filePath;
   }
@@ -1928,7 +2711,7 @@ var IdentityContinuityStore = class {
     try {
       const safeKey = this.sanitizeIdentityAuditKey(key);
       const dir = period === "weekly" ? this.deps.identityAuditsWeeklyDir : this.deps.identityAuditsMonthlyDir;
-      return await this.deps.readStorageSecureFile(path4.join(dir, `${safeKey}.md`));
+      return await this.deps.readStorageSecureFile(path5.join(dir, `${safeKey}.md`));
     } catch (err) {
       if (err instanceof Error && err.message === "Invalid identity audit key") return null;
       if (!isErrnoCode(err, "ENOENT")) throw err;
@@ -1967,7 +2750,7 @@ var IdentityContinuityStore = class {
     return loop;
   }
   async readContinuityIncidentFileNames() {
-    const files = await readdir3(this.deps.identityIncidentsDir);
+    const files = await readdir4(this.deps.identityIncidentsDir);
     return files.filter((file) => file.endsWith(".md")).sort().reverse();
   }
   async readContinuityIncidentFile(filePath) {
@@ -1984,12 +2767,12 @@ var IdentityContinuityStore = class {
     const fileNames = await this.readContinuityIncidentFileNames();
     const directMatch = fileNames.find((name) => name.endsWith(`-${id}.md`));
     if (directMatch) {
-      const directPath = path4.join(this.deps.identityIncidentsDir, directMatch);
+      const directPath = path5.join(this.deps.identityIncidentsDir, directMatch);
       const parsed = await this.readContinuityIncidentFile(directPath);
       if (parsed?.id === id) return directPath;
     }
     for (const fileName of fileNames) {
-      const filePath = path4.join(this.deps.identityIncidentsDir, fileName);
+      const filePath = path5.join(this.deps.identityIncidentsDir, fileName);
       const parsed = await this.readContinuityIncidentFile(filePath);
       if (parsed?.id === id) return filePath;
     }
@@ -2004,6 +2787,127 @@ var IdentityContinuityStore = class {
   }
 };
 
+// src/storage/entity-canonical-id-migration-adapter.ts
+async function runLegacyEntityCanonicalIdMigration(host, parseEntityFile2, serializeEntityFile2, serializeMemoryWithEntityRef2) {
+  const readMigrationFingerprint = () => getFingerprint(host.baseDir, host.entitiesDir, () => host.getCorpusScanVersion());
+  const completionFingerprint = await migrateLegacyEntityCanonicalIds({
+    stateDir: host.stateDir,
+    entitiesDir: host.entitiesDir,
+    normalizeEntityName: host.normalizeEntityName.bind(host),
+    resolveEntityFilePath: host.resolveEntityFilePath.bind(host),
+    readStorageSecureFile: host.readStorageSecureFile.bind(host),
+    writeStorageSecureFile: host.writeStorageSecureFile.bind(host),
+    isEncryptedStorageFile: host.isEncryptedFileHeader.bind(host),
+    snapshotBeforeWrite: host.snapshotBeforeWrite.bind(host),
+    parseEntityFile: parseEntityFile2,
+    serializeEntityFile: serializeEntityFile2,
+    serializeMemoryWithEntityRef: serializeMemoryWithEntityRef2,
+    readMemoryByPath: host.readMemoryByPath.bind(host),
+    readAllMemories: host.readAllMemories.bind(host),
+    readAllColdMemories: host.readAllColdMemories.bind(host),
+    readArchivedMemories: host.readArchivedMemories.bind(host),
+    validateMemoryScanRoots: () => validateRoots(host.baseDir, host.entitiesDir, host.stateDir, host.archiveDir),
+    rewriteProjectedEntityReferences: (mappings) => rewriteProjectedEntityReferences(host.baseDir, mappings),
+    rewriteProjectedMemoryEntityReference: (memoryId, previousEntityRef, nextEntityRef) => rewriteProjectedMemoryEntityReference(host.baseDir, memoryId, previousEntityRef, nextEntityRef),
+    invalidateKnowledgeIndexCache: host.invalidateKnowledgeIndexCache.bind(host),
+    invalidateAllMemoriesCache: host.invalidateAllMemoriesCache.bind(host),
+    invalidateColdMemoriesCache: host.invalidateColdMemoriesCache.bind(host),
+    bumpMemoryStatusVersion: host.bumpMemoryStatusVersion.bind(host),
+    readMigrationFingerprint
+  });
+  return completionFingerprint ?? readMigrationFingerprint();
+}
+
+// src/storage/entity-canonical-id-migration-runner.ts
+var EntityCanonicalIdMigrationRunner = class {
+  constructor(canRun, runMigration, readFingerprint = async () => "static") {
+    this.canRun = canRun;
+    this.runMigration = runMigration;
+    this.readFingerprint = readFingerprint;
+  }
+  canRun;
+  runMigration;
+  readFingerprint;
+  inFlight = null;
+  directoriesInitialized = false;
+  migrationComplete = false;
+  completedFingerprint = null;
+  async markDirectoriesInitialized() {
+    this.directoriesInitialized = true;
+    await this.ensure();
+  }
+  ensure() {
+    if (!this.canRun()) return Promise.resolve();
+    if (this.inFlight) return this.inFlight;
+    const migration = this.runOrReuse();
+    this.inFlight = migration;
+    void migration.then(
+      () => this.clearInFlight(migration),
+      () => this.clearInFlight(migration)
+    );
+    return migration;
+  }
+  triggerAfterUnlock() {
+    if (!this.directoriesInitialized) return Promise.resolve();
+    return this.ensure();
+  }
+  async runOrReuse() {
+    let fingerprintAtStart = await this.readFingerprint();
+    if (this.migrationComplete && fingerprintAtStart === this.completedFingerprint) return;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      const completionFingerprint = await this.runMigration();
+      const fingerprintAfterMigration = await this.readFingerprint();
+      const fingerprintAfterStabilityRead = await this.readFingerprint();
+      const returnedFingerprint = typeof completionFingerprint === "string" ? completionFingerprint : fingerprintAfterMigration;
+      if (returnedFingerprint === fingerprintAfterMigration && fingerprintAfterMigration === fingerprintAfterStabilityRead && (typeof completionFingerprint === "string" || fingerprintAfterMigration === fingerprintAtStart)) {
+        this.migrationComplete = true;
+        this.completedFingerprint = fingerprintAfterStabilityRead;
+        return;
+      }
+      fingerprintAtStart = fingerprintAfterStabilityRead;
+    }
+    this.migrationComplete = false;
+    this.completedFingerprint = null;
+    throw new Error("Entity canonical-id migration fingerprint changed while migration was completing; retry migration.");
+  }
+  clearInFlight(migration) {
+    if (this.inFlight === migration) this.inFlight = null;
+  }
+};
+
+// src/storage/memory-migration-serialization.ts
+function serializeMemoryWithEntityRef(memory, entityRef, fallback) {
+  const rawFrontmatter = readRawFrontmatter(memory);
+  if (rawFrontmatter === void 0) return fallback(memory, entityRef);
+  const lines = rawFrontmatter.split("\n");
+  let entityRefLine = -1;
+  for (let index = 0; index < lines.length; index += 1) {
+    if (/^\s*entityRef\s*:/.test(lines[index] ?? "")) entityRefLine = index;
+  }
+  if (entityRefLine >= 0) {
+    const indent = lines[entityRefLine].match(/^\s*/)?.[0] ?? "";
+    lines[entityRefLine] = `${indent}entityRef: ${entityRef}`;
+  } else {
+    lines.push(`entityRef: ${entityRef}`);
+  }
+  return `---
+${lines.join("\n")}
+---
+
+${memory.content}
+`;
+}
+function createMemoryEntityRefSerializer(serializeFrontmatter2) {
+  return (memory, entityRef) => serializeMemoryWithEntityRef(
+    memory,
+    entityRef,
+    (fallbackMemory, fallbackEntityRef) => `${serializeFrontmatter2({ ...fallbackMemory.frontmatter, entityRef: fallbackEntityRef })}
+
+${fallbackMemory.content}
+`
+  );
+}
+
 // src/utils/yaml-scalar.ts
 function decodeYamlScalar(value) {
   const trimmed = value.trim();
@@ -2019,9 +2923,9 @@ function decodeYamlScalar(value) {
 }
 
 // src/orchestration/qmd-result-resolver.ts
-import path5 from "path";
+import path6 from "path";
 function qmdCollectionPathParts(resultPath) {
-  if (!resultPath || path5.isAbsolute(resultPath)) return null;
+  if (!resultPath || path6.isAbsolute(resultPath)) return null;
   const normalized = resultPath.replace(/\\/g, "/").replace(/^\/+/, "");
   const slashIndex = normalized.indexOf("/");
   if (slashIndex <= 0 || slashIndex >= normalized.length - 1) return null;
@@ -2034,9 +2938,9 @@ function qmdCollectionPathParts(resultPath) {
 }
 function qmdResultPathCandidates(storageDir, resultPath) {
   const candidates = /* @__PURE__ */ new Set();
-  const storageRoot = path5.resolve(storageDir);
+  const storageRoot = path6.resolve(storageDir);
   const addCandidate = (candidate) => {
-    const resolved = path5.resolve(candidate);
+    const resolved = path6.resolve(candidate);
     if (isPathInsideStorageRoot(storageRoot, resolved)) {
       candidates.add(resolved);
     }
@@ -2044,18 +2948,18 @@ function qmdResultPathCandidates(storageDir, resultPath) {
   const addRelativeCandidates = (relativePath) => {
     const normalized = relativePath.replace(/\\/g, "/").replace(/^\/+/, "");
     if (!normalized) return;
-    addCandidate(path5.join(storageRoot, normalized));
+    addCandidate(path6.join(storageRoot, normalized));
     if (/^\d{4}-\d{2}-\d{2}\//.test(normalized)) {
-      addCandidate(path5.join(storageRoot, "facts", normalized));
+      addCandidate(path6.join(storageRoot, "facts", normalized));
     }
   };
-  if (path5.isAbsolute(resultPath)) {
+  if (path6.isAbsolute(resultPath)) {
     addCandidate(resultPath);
-    const relative2 = path5.relative(storageRoot, path5.resolve(resultPath));
-    if (relative2 && !relative2.startsWith("..") && !path5.isAbsolute(relative2)) {
-      const normalized = relative2.split(path5.sep).join("/");
+    const relative2 = path6.relative(storageRoot, path6.resolve(resultPath));
+    if (relative2 && !relative2.startsWith("..") && !path6.isAbsolute(relative2)) {
+      const normalized = relative2.split(path6.sep).join("/");
       if (/^\d{4}-\d{2}-\d{2}\//.test(normalized)) {
-        addCandidate(path5.join(storageRoot, "facts", normalized));
+        addCandidate(path6.join(storageRoot, "facts", normalized));
       }
     }
   } else {
@@ -2090,7 +2994,7 @@ var QmdResultResolver = class {
       const seenStorageDirs = /* @__PURE__ */ new Set();
       const addStorage = (storage) => {
         const storageDir = storageDirOrNull(storage);
-        const storageKey = storageDir ? path5.resolve(storageDir) : `storage-without-dir-${storages.length}`;
+        const storageKey = storageDir ? path6.resolve(storageDir) : `storage-without-dir-${storages.length}`;
         if (seenStorageDirs.has(storageKey)) return;
         seenStorageDirs.add(storageKey);
         storages.push(storage);
@@ -2120,7 +3024,7 @@ var QmdResultResolver = class {
           continue;
         }
         try {
-          const coldRoot = path5.join(storageDir, "cold");
+          const coldRoot = path6.join(storageDir, "cold");
           for (const candidate of qmdResultPathCandidates(
             coldRoot,
             parts.relativePath
@@ -2179,9 +3083,9 @@ var QmdResultResolver = class {
           error: err.message
         });
       }
-      if (!path5.isAbsolute(resultPath)) return null;
+      if (!path6.isAbsolute(resultPath)) return null;
     }
-    if (path5.isAbsolute(resultPath)) {
+    if (path6.isAbsolute(resultPath)) {
       if (!fallbackStorageDir) {
         return await fallbackStorage.readMemoryByPath(resultPath);
       }
@@ -2221,7 +3125,7 @@ var QmdResultResolver = class {
     );
     if (!memory) return null;
     let ownerNamespace = null;
-    if (path5.isAbsolute(memory.path)) {
+    if (path6.isAbsolute(memory.path)) {
       const ownerStorage = await this.storageForAbsoluteQmdResultPath(
         memory.path,
         fallbackStorage,
@@ -2245,17 +3149,17 @@ var QmdResultResolver = class {
     };
   }
   async storageForAbsoluteQmdResultPath(resultPath, fallbackStorage, recallNamespaces = []) {
-    const resolvedPath = path5.resolve(resultPath);
+    const resolvedPath = path6.resolve(resultPath);
     const config = this.getConfig();
-    const memoryRoot = path5.resolve(config.memoryDir);
-    const namespacesRoot = path5.join(memoryRoot, "namespaces");
+    const memoryRoot = path6.resolve(config.memoryDir);
+    const namespacesRoot = path6.join(memoryRoot, "namespaces");
     const fallbackStorageDir = storageDirOrNull(fallbackStorage);
     const matches = [];
     const seenDirs = /* @__PURE__ */ new Set();
     const maybeAddStorage = (storage, namespace) => {
       const storageDir = storageDirOrNull(storage);
       if (!storageDir) return;
-      const candidateRoot = path5.resolve(storageDir);
+      const candidateRoot = path6.resolve(storageDir);
       if (seenDirs.has(candidateRoot)) return;
       if (!isPathInsideStorageRoot(candidateRoot, resolvedPath)) return;
       if (candidateRoot === memoryRoot && isPathInsideStorageRoot(namespacesRoot, resolvedPath)) {
@@ -2273,7 +3177,7 @@ var QmdResultResolver = class {
       candidateNamespaces.add(ns);
     }
     if (isPathInsideStorageRoot(namespacesRoot, resolvedPath)) {
-      const relativeToNamespaces = path5.relative(namespacesRoot, resolvedPath);
+      const relativeToNamespaces = path6.relative(namespacesRoot, resolvedPath);
       const [namespaceSegment] = relativeToNamespaces.split(/[\\/]/);
       if (namespaceSegment) {
         candidateNamespaces.add(
@@ -2922,7 +3826,7 @@ function fuseDay(date, inputs, options = {}) {
 
 // src/wearables/fusion/store.ts
 import { createHash as createHash2 } from "crypto";
-import * as path6 from "path";
+import * as path7 from "path";
 var FUSION_KIND = "wearable-fusion";
 function hashFusionBody(conversations) {
   return createHash2("sha256").update(JSON.stringify(conversations), "utf-8").digest("hex");
@@ -3109,7 +4013,7 @@ var FusionArtifactStore = class {
         `invalid wearable fusion date '${String(date)}' \u2014 expected YYYY-MM-DD`
       );
     }
-    return path6.join(this.wearablesDir, FUSION_DIR_NAME, `${date}.md`);
+    return path7.join(this.wearablesDir, FUSION_DIR_NAME, `${date}.md`);
   }
   async writeFusedDay(date, serialized) {
     const filePath = this.fusedDayPath(date);
@@ -3146,7 +4050,7 @@ var FusionArtifactStore = class {
   }
   /** List dates with stored fused artifacts, newest first. */
   async listFusedDays() {
-    const fusionDir = path6.join(this.wearablesDir, FUSION_DIR_NAME);
+    const fusionDir = path7.join(this.wearablesDir, FUSION_DIR_NAME);
     await this.assertPathContained(fusionDir);
     let entries;
     try {
@@ -3190,10 +4094,10 @@ var FusionArtifactStore = class {
     try {
       rootReal = await this.io.realpath(this.memoryDir);
     } catch {
-      rootReal = path6.resolve(this.memoryDir);
+      rootReal = path7.resolve(this.memoryDir);
     }
     await this.assertNoEscape(rootReal, this.wearablesDir);
-    await this.assertNoEscape(rootReal, path6.dirname(targetPath));
+    await this.assertNoEscape(rootReal, path7.dirname(targetPath));
     await this.assertNoEscape(rootReal, targetPath);
     await this.assertFusionDirNotSymlinked();
   }
@@ -3207,7 +4111,7 @@ var FusionArtifactStore = class {
    * (a fresh write creates a real directory lexically under the root).
    */
   async assertFusionDirNotSymlinked() {
-    const fusionDir = path6.join(this.wearablesDir, FUSION_DIR_NAME);
+    const fusionDir = path7.join(this.wearablesDir, FUSION_DIR_NAME);
     let stat4;
     try {
       stat4 = await this.io.lstat(fusionDir);
@@ -3343,7 +4247,7 @@ function reconstructFusionInputs(date, dayTranscripts) {
 
 // src/meetings/store.ts
 import { createHash as createHash3 } from "crypto";
-import * as path7 from "path";
+import * as path8 from "path";
 var MEETINGS_DIR_NAME = "meetings";
 var MEETING_KIND = "meeting";
 var MEETING_FORMAT_VERSION = 1;
@@ -3512,7 +4416,7 @@ var MeetingRecordStore = class {
   constructor(memoryDir, io) {
     this.memoryDir = memoryDir;
     this.io = io;
-    this.meetingsDir = path7.join(memoryDir, MEETINGS_DIR_NAME);
+    this.meetingsDir = path8.join(memoryDir, MEETINGS_DIR_NAME);
   }
   memoryDir;
   io;
@@ -3528,7 +4432,7 @@ var MeetingRecordStore = class {
     if (idDate !== date) {
       throw new Error(`meeting id '${id}' does not belong to date '${date}'`);
     }
-    return path7.join(this.meetingsDir, date, `${id}.md`);
+    return path8.join(this.meetingsDir, date, `${id}.md`);
   }
   /** Idempotently persist a record: skip the write when contentHash is unchanged. */
   async saveMeetingRecord(record) {
@@ -3559,7 +4463,7 @@ var MeetingRecordStore = class {
     if (!isValidTranscriptDate(date)) {
       throw new Error(`invalid meeting date '${String(date)}' \u2014 expected YYYY-MM-DD`);
     }
-    const dayDir = path7.join(this.meetingsDir, date);
+    const dayDir = path8.join(this.meetingsDir, date);
     await this.assertPathContained(dayDir);
     let entries;
     try {
@@ -3627,10 +4531,10 @@ var MeetingRecordStore = class {
     try {
       rootReal = await this.io.realpath(this.memoryDir);
     } catch {
-      rootReal = path7.resolve(this.memoryDir);
+      rootReal = path8.resolve(this.memoryDir);
     }
     await this.assertNoEscape(rootReal, this.meetingsDir);
-    await this.assertNoEscape(rootReal, path7.dirname(targetPath));
+    await this.assertNoEscape(rootReal, path8.dirname(targetPath));
     await this.assertNoEscape(rootReal, targetPath);
     await this.assertNotSymlink(this.meetingsDir, "directory");
     const dayDir = this.dayDirWithin(targetPath);
@@ -3640,11 +4544,11 @@ var MeetingRecordStore = class {
   /** The `<meetings>/<date>` directory on the path to `targetPath`, or null when
    *  `targetPath` is the meetings root itself. */
   dayDirWithin(targetPath) {
-    const rel = path7.relative(this.meetingsDir, targetPath);
-    if (rel === "" || rel.startsWith("..") || path7.isAbsolute(rel)) return null;
-    const first = rel.split(path7.sep)[0];
+    const rel = path8.relative(this.meetingsDir, targetPath);
+    if (rel === "" || rel.startsWith("..") || path8.isAbsolute(rel)) return null;
+    const first = rel.split(path8.sep)[0];
     if (first === void 0 || first.length === 0) return null;
-    return path7.join(this.meetingsDir, first);
+    return path8.join(this.meetingsDir, first);
   }
   async assertNotSymlink(target, kind) {
     let stat4;
@@ -3655,7 +4559,7 @@ var MeetingRecordStore = class {
       throw err;
     }
     if (stat4.isSymbolicLink) {
-      const label = path7.relative(this.memoryDir, target) || MEETINGS_DIR_NAME;
+      const label = path8.relative(this.memoryDir, target) || MEETINGS_DIR_NAME;
       throw new Error(
         `meetings ${kind} '${label}' is a symbolic link \u2014 refusing to follow it even when it resolves inside the memory dir (AGENTS.md pattern #3)`
       );
@@ -4073,7 +4977,7 @@ function isEntitySynthesisStale(entity) {
 
 // src/storage/content-hash-index.ts
 import { mkdir, stat as stat2 } from "fs/promises";
-import path8 from "path";
+import path9 from "path";
 var CONTENT_HASH_INDEX_LOCK_STALE_MS = 3e4;
 var CONTENT_HASH_INDEX_RETRY_MAX_ATTEMPTS = 5;
 var CONTENT_HASH_INDEX_RETRY_BASE_MS = 500;
@@ -4133,8 +5037,8 @@ var ContentHashIndex = class _ContentHashIndex {
    * re-read on the hot path.
    */
   lastSyncedFingerprint = null;
-  constructor(stateDir, secureStoreKeyProvider = () => null, secureStoreWriteKeyProvider = secureStoreKeyProvider, memoryDir = path8.dirname(stateDir), lockOptions = {}) {
-    this.filePath = path8.join(stateDir, "fact-hashes.txt");
+  constructor(stateDir, secureStoreKeyProvider = () => null, secureStoreWriteKeyProvider = secureStoreKeyProvider, memoryDir = path9.dirname(stateDir), lockOptions = {}) {
+    this.filePath = path9.join(stateDir, "fact-hashes.txt");
     this.secureStoreKeyProvider = secureStoreKeyProvider;
     this.secureStoreWriteKeyProvider = secureStoreWriteKeyProvider;
     this.memoryDir = memoryDir;
@@ -4226,7 +5130,7 @@ var ContentHashIndex = class _ContentHashIndex {
   /** Persist index to disk if changed (plain whole-file overwrite). */
   async save() {
     if (!this.dirty) return;
-    await mkdir(path8.dirname(this.filePath), { recursive: true });
+    await mkdir(path9.dirname(this.filePath), { recursive: true });
     const publishedAdded = new Set(this.added);
     const publishedRemoved = new Set(this.removed);
     const serialized = [...this.hashes].join("\n") + "\n";
@@ -4273,7 +5177,7 @@ var ContentHashIndex = class _ContentHashIndex {
    */
   async saveMergingWithDisk() {
     if (!this.dirty) return;
-    await mkdir(path8.dirname(this.filePath), { recursive: true });
+    await mkdir(path9.dirname(this.filePath), { recursive: true });
     const publish = async () => {
       const publishedAdded = new Set(this.added);
       const publishedRemoved = new Set(this.removed);
@@ -4292,7 +5196,7 @@ var ContentHashIndex = class _ContentHashIndex {
         if (err instanceof SecureStoreLockedError) throw err;
         if (!isErrnoCode(err, "ENOENT")) throw err;
       }
-      await mkdir(path8.dirname(this.filePath), { recursive: true });
+      await mkdir(path9.dirname(this.filePath), { recursive: true });
       await writeMaybeEncryptedFile(
         this.filePath,
         [...merged].join("\n") + "\n",
@@ -4359,7 +5263,7 @@ var ContentHashIndex = class _ContentHashIndex {
    * fired retry) simply yields `acquired=false` after the bounded wait.
    */
   async rebuildUnderLock(populate) {
-    await mkdir(path8.dirname(this.filePath), { recursive: true });
+    await mkdir(path9.dirname(this.filePath), { recursive: true });
     let published = false;
     await withHeldFileLock(
       `${this.filePath}.lock`,
@@ -5160,17 +6064,17 @@ function inferEntityTypeFromContent(content) {
 }
 var KNOWN_ENTITY_FILENAME_PREFIXES = /* @__PURE__ */ new Set(["company", "other", "person", "place", "project", "tool", "topic"]);
 function inferEntityTypeFromFilename(pathRel) {
-  const basename = path9.basename(pathRel, ".md").toLowerCase();
+  const basename = path10.basename(pathRel, ".md").toLowerCase();
   const separator = basename.indexOf("-");
   if (separator <= 0) return void 0;
   const candidate = basename.slice(0, separator);
   return KNOWN_ENTITY_FILENAME_PREFIXES.has(candidate) ? candidate : void 0;
 }
 function normalizeFrontmatterForPath(frontmatter, pathRel, content = "") {
-  const normalizedPath = pathRel.split(path9.sep).join("/");
+  const normalizedPath = pathRel.split(path10.sep).join("/");
   let normalizedFrontmatter = frontmatter;
   if (normalizedPath === "entities" || normalizedPath.startsWith("entities/") || normalizedPath.includes("/entities/")) {
-    const basename = path9.basename(pathRel, ".md");
+    const basename = path10.basename(pathRel, ".md");
     const inferredType = inferEntityTypeFromContent(content) || inferEntityTypeFromFilename(pathRel) || "entity";
     const existingTags = Array.isArray(frontmatter.tags) ? frontmatter.tags : [];
     normalizedFrontmatter = {
@@ -5191,27 +6095,6 @@ function normalizeFrontmatterForPath(frontmatter, pathRel, content = "") {
 function inferCurrentStateStatus(frontmatter, pathRel, fallbackStatus) {
   return inferMemoryStatus(frontmatter, pathRel, fallbackStatus);
 }
-var BUILTIN_ALIASES = {
-  openclaw: "openclaw",
-  "open-claw": "openclaw"
-};
-function normalizeEntityName(raw, type, aliases) {
-  const rawStr = typeof raw === "string" ? raw : "";
-  const typeStr = typeof type === "string" && type.trim().length > 0 ? type : "entity";
-  let name = rawStr.toLowerCase().trim();
-  const typePrefix = `${typeStr.toLowerCase()}-`;
-  if (name.startsWith(typePrefix)) {
-    name = name.slice(typePrefix.length);
-  }
-  let normalized = name.replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
-  const userAlias = aliases !== void 0 && Object.hasOwn(aliases, normalized) ? aliases[normalized] : void 0;
-  if (typeof userAlias === "string" && userAlias.length > 0) {
-    normalized = userAlias;
-  } else if (Object.hasOwn(BUILTIN_ALIASES, normalized)) {
-    normalized = BUILTIN_ALIASES[normalized];
-  }
-  return `${typeStr.toLowerCase()}-${normalized}`;
-}
 function levenshtein(a, b) {
   const m = a.length;
   const n = b.length;
@@ -5657,6 +6540,7 @@ var StorageManager3 = class _StorageManager {
     this.entitySchemas = entitySchemas;
     this.hotMemoriesCacheEnabled = hotMemoriesCacheEnabledOverride ?? _StorageManager.hotMemoriesCacheDefaultByDir.get(baseDir) ?? _StorageManager.hotMemoriesCacheDefault;
     this.loadAliasesSync();
+    this.loadHistoricalEntityCanonicalIdsSync();
   }
   baseDir;
   entitySchemas;
@@ -5836,8 +6720,8 @@ var StorageManager3 = class _StorageManager {
   }
   /** Whether `filePath` resolves to `stateDir` itself or a path contained in it. */
   isStateFilePath(filePath) {
-    const rel = path9.relative(this.stateDir, path9.resolve(filePath));
-    return rel === "" || !rel.startsWith("..") && !path9.isAbsolute(rel);
+    const rel = path10.relative(this.stateDir, path10.resolve(filePath));
+    return rel === "" || !rel.startsWith("..") && !path10.isAbsolute(rel);
   }
   // ── Tombstone store (issue #1579) ───────────────────────────────────────
   // Instance-scoped (rule 11) + namespace-scoped (rule 42) tombstone index.
@@ -5880,17 +6764,34 @@ var StorageManager3 = class _StorageManager {
    * Set or clear the at-rest encryption key.
    *
    * Pass a 32-byte Buffer to enable encryption; pass null to clear
-   * (lock) the store.  The caller is responsible for key lifecycle —
+   * (lock) the store. The caller is responsible for key lifecycle —
    * this method does not zero the buffer on replacement; the keyring
-   * module (`keyring.ts`) owns zeroization.
+   * module (`keyring.ts`) owns zeroization. The setter remains synchronous
+   * for existing consumers; call `setSecureStoreKeyAndWait` when unlock must
+   * await migration.
    */
   setSecureStoreKey(key, encryptOnWrite = true) {
+    if (!this.applySecureStoreKey(key, encryptOnWrite) || key === null) return;
+    void this.entityCanonicalIdMigration.triggerAfterUnlock().catch((error) => {
+      log.warn(
+        `secure-store unlock migration failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    });
+  }
+  async setSecureStoreKeyAndWait(key, encryptOnWrite = true) {
+    if (!this.applySecureStoreKey(key, encryptOnWrite) || key === null) return;
+    await this.entityCanonicalIdMigration.triggerAfterUnlock();
+  }
+  applySecureStoreKey(key, encryptOnWrite) {
+    const sameKey = this._secureStoreKey === key || this._secureStoreKey !== null && key !== null && this._secureStoreKey.equals(key);
+    if (sameKey && this._secureStoreEncryptOnWrite === encryptOnWrite) return false;
     this._secureStoreKey = key;
     this._secureStoreEncryptOnWrite = encryptOnWrite;
     invalidateAllForDir(this.baseDir);
     this.invalidateKnowledgeIndexCache();
     this.secureFileEncryptionSniffCache.clear();
     this.behaviorSignalsKeyCache = null;
+    return true;
   }
   getEntityCacheSecureStoreKey() {
     if (!this._secureStoreKey) return "secure-store:locked";
@@ -5937,8 +6838,8 @@ var StorageManager3 = class _StorageManager {
    * /srv/cold/remnic), skipping the patch and stranding a stale hot entry.
    */
   isColdOrArchiveTierPath(p) {
-    const rel = path9.relative(this.baseDir, p);
-    return rel === "cold" || rel === "archive" || rel.startsWith(`cold${path9.sep}`) || rel.startsWith(`archive${path9.sep}`);
+    const rel = path10.relative(this.baseDir, p);
+    return rel === "cold" || rel === "archive" || rel.startsWith(`cold${path10.sep}`) || rel.startsWith(`archive${path10.sep}`);
   }
   /**
    * Mark the secure-store as required for this storage instance.
@@ -6025,7 +6926,7 @@ var StorageManager3 = class _StorageManager {
         void 0,
         this.baseDir
       );
-      const rel = path9.relative(this.baseDir, filePath).split(path9.sep).join("/");
+      const rel = path10.relative(this.baseDir, filePath).split(path10.sep).join("/");
       return `${rel}:${version.versionId}`;
     } catch (err) {
       log.warn(
@@ -6105,13 +7006,13 @@ var StorageManager3 = class _StorageManager {
   }
   identityFilePath(workspaceDir, namespace) {
     const rawNamespace = typeof namespace === "string" ? namespace.trim() : "";
-    if (!rawNamespace) return path9.join(workspaceDir, "IDENTITY.md");
+    if (!rawNamespace) return path10.join(workspaceDir, "IDENTITY.md");
     const safeNamespace = rawNamespace.replace(/[^a-zA-Z0-9._-]/g, "-");
-    return path9.join(workspaceDir, `IDENTITY.${safeNamespace}.md`);
+    return path10.join(workspaceDir, `IDENTITY.${safeNamespace}.md`);
   }
   versionFilePath(kind) {
     const fileName = kind === "memory-status" ? ".memory-status-version.log" : kind === "artifact-write" ? ".artifact-write-version.log" : kind === "cold-write" ? ".cold-write-version.log" : ".memory-corpus-version.log";
-    return path9.join(this.stateDir, fileName);
+    return path10.join(this.stateDir, fileName);
   }
   bumpSharedVersion(kind, fallbackMap) {
     const filePath = this.versionFilePath(kind);
@@ -6203,7 +7104,7 @@ var StorageManager3 = class _StorageManager {
   // memories.
   // -------------------------------------------------------------------------
   get wearablesDir() {
-    return path9.join(this.baseDir, WEARABLES_DIR_NAME);
+    return path10.join(this.baseDir, WEARABLES_DIR_NAME);
   }
   /**
    * Resolve the on-disk path for a source/day transcript. Throws on
@@ -6219,7 +7120,7 @@ var StorageManager3 = class _StorageManager {
     if (!isValidTranscriptDate(date)) {
       throw new Error(`invalid wearable transcript date '${String(date)}' \u2014 expected YYYY-MM-DD`);
     }
-    return path9.join(this.wearablesDir, sourceId, `${date}.md`);
+    return path10.join(this.wearablesDir, sourceId, `${date}.md`);
   }
   async writeWearableDayTranscript(sourceId, date, serialized) {
     const targetPath = this.wearableTranscriptPath(sourceId, date);
@@ -6245,10 +7146,10 @@ var StorageManager3 = class _StorageManager {
     return this._fusionStore = new FusionArtifactStore(this.wearablesDir, this.baseDir, {
       writeFile: (p, c) => this.writeStorageSecureFile(p, c),
       readFile: (p) => readMaybeEncryptedFile(p, this._secureStoreKey, this.baseDir),
-      readDir: (d) => readdir4(d),
-      deleteFile: (p) => unlink2(p),
-      realpath: (p) => realpath2(p),
-      lstat: (p) => lstat2(p).then((st) => ({ isSymbolicLink: st.isSymbolicLink() }))
+      readDir: (d) => readdir5(d),
+      deleteFile: (p) => unlink3(p),
+      realpath: (p) => realpath3(p),
+      lstat: (p) => lstat3(p).then((st) => ({ isSymbolicLink: st.isSymbolicLink() }))
     });
   }
   _meetingRecordStore;
@@ -6263,10 +7164,10 @@ var StorageManager3 = class _StorageManager {
     return this._meetingRecordStore = new MeetingRecordStore(this.baseDir, {
       writeFile: (p, c) => this.writeStorageSecureFile(p, c),
       readFile: (p) => readMaybeEncryptedFile(p, this._secureStoreKey, this.baseDir),
-      readDir: (d) => readdir4(d),
-      deleteFile: (p) => unlink2(p),
-      realpath: (p) => realpath2(p),
-      lstat: (p) => lstat2(p).then((st) => ({ isSymbolicLink: st.isSymbolicLink() }))
+      readDir: (d) => readdir5(d),
+      deleteFile: (p) => unlink3(p),
+      realpath: (p) => realpath3(p),
+      lstat: (p) => lstat3(p).then((st) => ({ isSymbolicLink: st.isSymbolicLink() }))
     });
   }
   /**
@@ -6335,25 +7236,25 @@ var StorageManager3 = class _StorageManager {
     });
   }
   get factsDir() {
-    return path9.join(this.baseDir, "facts");
+    return path10.join(this.baseDir, "facts");
   }
   get correctionsDir() {
-    return path9.join(this.baseDir, "corrections");
+    return path10.join(this.baseDir, "corrections");
   }
   get proceduresDir() {
-    return path9.join(this.baseDir, "procedures");
+    return path10.join(this.baseDir, "procedures");
   }
   get reasoningTracesDir() {
-    return path9.join(this.baseDir, "reasoning-traces");
+    return path10.join(this.baseDir, "reasoning-traces");
   }
   get entitiesDir() {
-    return path9.join(this.baseDir, "entities");
+    return path10.join(this.baseDir, "entities");
   }
   resolveEntityFilePath(name) {
     if (typeof name !== "string") return null;
-    const filePath = path9.resolve(this.entitiesDir, `${name}.md`);
-    const relative2 = path9.relative(this.entitiesDir, filePath);
-    if (relative2 === "" || relative2.startsWith("..") || path9.isAbsolute(relative2)) {
+    const filePath = path10.resolve(this.entitiesDir, `${name}.md`);
+    const relative2 = path10.relative(this.entitiesDir, filePath);
+    if (relative2 === "" || relative2.startsWith("..") || path10.isAbsolute(relative2)) {
       return null;
     }
     return filePath;
@@ -6374,10 +7275,10 @@ var StorageManager3 = class _StorageManager {
     });
   }
   assertManagedStoragePath(filePath, method) {
-    const resolved = path9.resolve(filePath);
-    const base = path9.resolve(this.baseDir);
-    const rel = path9.relative(base, resolved);
-    if (rel === "" || rel === ".." || rel.startsWith(`..${path9.sep}`) || path9.isAbsolute(rel)) {
+    const resolved = path10.resolve(filePath);
+    const base = path10.resolve(this.baseDir);
+    const rel = path10.relative(base, resolved);
+    if (rel === "" || rel === ".." || rel.startsWith(`..${path10.sep}`) || path10.isAbsolute(rel)) {
       throw new Error(`${method}: file path escapes memory dir`);
     }
     return resolved;
@@ -6389,7 +7290,7 @@ var StorageManager3 = class _StorageManager {
   async digestOfflineSyncFile(filePath) {
     const target = this.assertManagedStoragePath(filePath, "storage.digestOfflineSyncFile");
     const st = await stat3(target);
-    const relPath = path9.relative(this.baseDir, target).split(path9.sep).join("/");
+    const relPath = path10.relative(this.baseDir, target).split(path10.sep).join("/");
     const cache = await this.loadOfflineSyncDigestCache();
     const cached = cache.get(relPath);
     if (cached && cached.statBytes === st.size && cached.mtimeMs === st.mtimeMs && cached.ctimeMs === st.ctimeMs && !cached.encrypted) {
@@ -6435,7 +7336,7 @@ var StorageManager3 = class _StorageManager {
   async readOfflineSyncDigestCache() {
     const cache = /* @__PURE__ */ new Map();
     try {
-      const raw = await readFile(this.offlineSyncDigestCachePath, "utf-8");
+      const raw = await readFile2(this.offlineSyncDigestCachePath, "utf-8");
       const parsed = JSON.parse(raw);
       if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return cache;
       const entries = parsed.entries;
@@ -6450,7 +7351,7 @@ var StorageManager3 = class _StorageManager {
         const bytes = typeof record.bytes === "number" ? record.bytes : NaN;
         const sha256 = typeof record.sha256 === "string" ? record.sha256 : "";
         const encrypted = record.encrypted === true;
-        if (cachePath.length === 0 || cachePath === ".." || cachePath.startsWith("../") || path9.isAbsolute(cachePath) || !Number.isFinite(statBytes) || !Number.isFinite(mtimeMs) || !Number.isFinite(ctimeMs) || !Number.isFinite(bytes) || !/^[a-f0-9]{64}$/i.test(sha256)) {
+        if (cachePath.length === 0 || cachePath === ".." || cachePath.startsWith("../") || path10.isAbsolute(cachePath) || !Number.isFinite(statBytes) || !Number.isFinite(mtimeMs) || !Number.isFinite(ctimeMs) || !Number.isFinite(bytes) || !/^[a-f0-9]{64}$/i.test(sha256)) {
           continue;
         }
         cache.set(cachePath, { statBytes, mtimeMs, ctimeMs, encrypted, sha256, bytes });
@@ -6492,8 +7393,8 @@ var StorageManager3 = class _StorageManager {
       const cache = this.offlineSyncDigestCache;
       if (!cache) return;
       const entries = [...cache.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([entryPath, entry]) => ({ path: entryPath, ...entry }));
-      await mkdir2(path9.dirname(this.offlineSyncDigestCachePath), { recursive: true });
-      await writeFile(this.offlineSyncDigestCachePath, `${JSON.stringify({ version: 1, entries })}
+      await mkdir2(path10.dirname(this.offlineSyncDigestCachePath), { recursive: true });
+      await writeFile2(this.offlineSyncDigestCachePath, `${JSON.stringify({ version: 1, entries })}
 `, "utf-8");
     }).catch((err) => {
       log.warn(
@@ -6527,7 +7428,7 @@ var StorageManager3 = class _StorageManager {
   }
   async deleteOfflineSyncFile(filePath) {
     const target = this.assertManagedStoragePath(filePath, "storage.deleteOfflineSyncFile");
-    await unlink2(target).catch((error) => {
+    await unlink3(target).catch((error) => {
       if (isErrnoCode(error, "ENOENT")) return;
       throw error;
     });
@@ -6537,10 +7438,10 @@ var StorageManager3 = class _StorageManager {
     this.invalidateAllMemoriesCache();
     this.invalidateKnowledgeIndexCache();
     this.factHashIndexAuthoritative = false;
-    if (filePath.includes(`${path9.sep}cold${path9.sep}`)) {
+    if (filePath.includes(`${path10.sep}cold${path10.sep}`)) {
       this.invalidateColdMemoriesCache();
     }
-    if (filePath.includes(`${path9.sep}artifacts${path9.sep}`)) {
+    if (filePath.includes(`${path10.sep}artifacts${path10.sep}`)) {
       this.bumpArtifactWriteVersion();
     }
     this.bumpMemoryStatusVersion();
@@ -6611,7 +7512,7 @@ var StorageManager3 = class _StorageManager {
   }
   async appendStorageSecureFileUnlocked(filePath, content) {
     const writeKey = this.resolveWriteKey();
-    await mkdir2(path9.dirname(filePath), { recursive: true });
+    await mkdir2(path10.dirname(filePath), { recursive: true });
     if (writeKey === null) {
       try {
         if (await this.isEncryptedFileHeader(filePath)) {
@@ -6637,13 +7538,13 @@ var StorageManager3 = class _StorageManager {
     this.notifyCatalogWriteForPath(filePath);
   }
   get stateDir() {
-    return path9.join(this.baseDir, "state");
+    return path10.join(this.baseDir, "state");
   }
   get offlineSyncDigestCachePath() {
-    return path9.join(this.baseDir, ".offline-sync", "digest-cache.v1.json");
+    return path10.join(this.baseDir, ".offline-sync", "digest-cache.v1.json");
   }
   get entitySynthesisQueuePath() {
-    return path9.join(this.stateDir, "entity-synthesis-queue.json");
+    return path10.join(this.stateDir, "entity-synthesis-queue.json");
   }
   // ── Tombstone store access (issue #1579) ─────────────────────────────────
   /**
@@ -6653,7 +7554,7 @@ var StorageManager3 = class _StorageManager {
    * helpers are injected into the store).
    */
   get tombstonesPath() {
-    return path9.join(this.stateDir, "tombstones.jsonl");
+    return path10.join(this.stateDir, "tombstones.jsonl");
   }
   /**
    * Configure the tombstone invariant for this storage instance. Installed
@@ -6926,55 +7827,55 @@ var StorageManager3 = class _StorageManager {
     return null;
   }
   get questionsDir() {
-    return path9.join(this.baseDir, "questions");
+    return path10.join(this.baseDir, "questions");
   }
   get artifactsDir() {
-    return path9.join(this.baseDir, "artifacts");
+    return path10.join(this.baseDir, "artifacts");
   }
   get identityDir() {
-    return path9.join(this.baseDir, "identity");
+    return path10.join(this.baseDir, "identity");
   }
   get identityAnchorPath() {
-    return path9.join(this.identityDir, "identity-anchor.md");
+    return path10.join(this.identityDir, "identity-anchor.md");
   }
   get identityIncidentsDir() {
-    return path9.join(this.identityDir, "incidents");
+    return path10.join(this.identityDir, "incidents");
   }
   get identityAuditsWeeklyDir() {
-    return path9.join(this.identityDir, "audits", "weekly");
+    return path10.join(this.identityDir, "audits", "weekly");
   }
   get identityAuditsMonthlyDir() {
-    return path9.join(this.identityDir, "audits", "monthly");
+    return path10.join(this.identityDir, "audits", "monthly");
   }
   get identityImprovementLoopsPath() {
-    return path9.join(this.identityDir, "improvement-loops.md");
+    return path10.join(this.identityDir, "improvement-loops.md");
   }
   get identityReflectionsPath() {
-    return path9.join(this.identityDir, "reflections.md");
+    return path10.join(this.identityDir, "reflections.md");
   }
   get profilePath() {
-    return path9.join(this.baseDir, "profile.md");
+    return path10.join(this.baseDir, "profile.md");
   }
   get memoryActionsPath() {
-    return path9.join(this.stateDir, "memory-actions.jsonl");
+    return path10.join(this.stateDir, "memory-actions.jsonl");
   }
   get memoryLifecycleLedgerPath() {
-    return path9.join(this.stateDir, "memory-lifecycle-ledger.jsonl");
+    return path10.join(this.stateDir, "memory-lifecycle-ledger.jsonl");
   }
   get compressionGuidelinesPath() {
-    return path9.join(this.stateDir, "compression-guidelines.md");
+    return path10.join(this.stateDir, "compression-guidelines.md");
   }
   get compressionGuidelineDraftPath() {
-    return path9.join(this.stateDir, "compression-guidelines.draft.md");
+    return path10.join(this.stateDir, "compression-guidelines.draft.md");
   }
   get compressionGuidelineStatePath() {
-    return path9.join(this.stateDir, "compression-guideline-state.json");
+    return path10.join(this.stateDir, "compression-guideline-state.json");
   }
   get compressionGuidelineDraftStatePath() {
-    return path9.join(this.stateDir, "compression-guideline-draft-state.json");
+    return path10.join(this.stateDir, "compression-guideline-draft-state.json");
   }
   get behaviorSignalsPath() {
-    return path9.join(this.stateDir, "behavior-signals.jsonl");
+    return path10.join(this.stateDir, "behavior-signals.jsonl");
   }
   /**
    * In-memory dedup key set for behavior-signals appends (issue #1909),
@@ -7006,7 +7907,7 @@ var StorageManager3 = class _StorageManager {
    * governance sweeps can treat it uniformly.
    */
   get bufferSurpriseLedgerPath() {
-    return path9.join(this.stateDir, "buffer-surprise-ledger.jsonl");
+    return path10.join(this.stateDir, "buffer-surprise-ledger.jsonl");
   }
   /**
    * Entity alias table loaded from THIS store's config/aliases.json.
@@ -7016,8 +7917,17 @@ var StorageManager3 = class _StorageManager {
    * store loaded last rewrite every other store's canonical entity ids.
    */
   userAliases = {};
+  historicalEntityCanonicalIds = {};
+  entityCanonicalIdMigration = new EntityCanonicalIdMigrationRunner(
+    () => !(this._secureStoreRequired && !this.isSecureStoreUnlocked()),
+    () => this.runLegacyEntityCanonicalIdMigration(),
+    () => getFingerprint(this.baseDir, this.entitiesDir, () => this.getCorpusScanVersion())
+  );
   normalizeEntityName(raw, type) {
-    return this.entityStore.normalizeEntityName(raw, type);
+    return resolveHistoricalEntityCanonicalId(
+      this.entityStore.normalizeEntityName(raw, type),
+      this.historicalEntityCanonicalIds
+    );
   }
   /**
    * Read-only view of this store's user alias table, for call sites that
@@ -7037,10 +7947,10 @@ var StorageManager3 = class _StorageManager {
     this.loadAliasesSync();
   }
   loadAliasesSync() {
-    const aliasPath = path9.join(this.baseDir, "config", "aliases.json");
+    const aliasPath = path10.join(this.baseDir, "config", "aliases.json");
     this.userAliases = {};
     try {
-      const raw = readFileSync(aliasPath, "utf-8");
+      const raw = readFileSync2(aliasPath, "utf-8");
       const parsed = JSON.parse(raw);
       if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
         const cleaned = {};
@@ -7058,11 +7968,26 @@ var StorageManager3 = class _StorageManager {
       log.debug("no config/aliases.json found \u2014 using built-in aliases only");
     }
   }
+  loadHistoricalEntityCanonicalIdsSync() {
+    this.historicalEntityCanonicalIds = loadHistoricalEntityCanonicalIds(this.stateDir);
+  }
+  async runLegacyEntityCanonicalIdMigration() {
+    const completionFingerprint = await runLegacyEntityCanonicalIdMigration(
+      this,
+      (content) => parseEntityFile(content, this.entitySchemas),
+      (entity) => serializeEntityFile(entity, this.entitySchemas),
+      createMemoryEntityRefSerializer(serializeFrontmatter)
+    );
+    this.loadHistoricalEntityCanonicalIdsSync();
+    return completionFingerprint;
+  }
   async ensureDirectories() {
+    await mkdir2(this.baseDir, { recursive: true });
+    await validateRoots(this.baseDir, this.entitiesDir, this.stateDir, this.archiveDir);
     const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-    await mkdir2(path9.join(this.factsDir, today), { recursive: true });
-    await mkdir2(path9.join(this.proceduresDir, today), { recursive: true });
-    await mkdir2(path9.join(this.reasoningTracesDir, today), { recursive: true });
+    await mkdir2(path10.join(this.factsDir, today), { recursive: true });
+    await mkdir2(path10.join(this.proceduresDir, today), { recursive: true });
+    await mkdir2(path10.join(this.reasoningTracesDir, today), { recursive: true });
     await mkdir2(this.correctionsDir, { recursive: true });
     await mkdir2(this.entitiesDir, { recursive: true });
     await mkdir2(this.stateDir, { recursive: true });
@@ -7072,10 +7997,12 @@ var StorageManager3 = class _StorageManager {
     await mkdir2(this.identityIncidentsDir, { recursive: true });
     await mkdir2(this.identityAuditsWeeklyDir, { recursive: true });
     await mkdir2(this.identityAuditsMonthlyDir, { recursive: true });
-    await mkdir2(path9.join(this.baseDir, "config"), { recursive: true });
+    await mkdir2(path10.join(this.baseDir, "config"), { recursive: true });
+    await this.entityCanonicalIdMigration.ensure();
     if (this.hotMemoriesCacheEnabled && this.getMemoryCorpusVersion() === 0) {
       this.bumpMemoryCorpusVersion();
     }
+    await this.entityCanonicalIdMigration.markDirectoriesInitialized();
   }
   /**
    * Resolve the on-disk write path for a memory of the given category, creating
@@ -7092,11 +8019,11 @@ var StorageManager3 = class _StorageManager {
   async resolveCategoryWritePath(category, id, today) {
     if (category === "correction") {
       await mkdir2(this.correctionsDir, { recursive: true });
-      return path9.join(this.correctionsDir, `${id}.md`);
+      return path10.join(this.correctionsDir, `${id}.md`);
     }
-    const datedDir = path9.join(getCategoryDir(this.baseDir, category), today);
+    const datedDir = path10.join(getCategoryDir(this.baseDir, category), today);
     await mkdir2(datedDir, { recursive: true });
-    return path9.join(datedDir, `${id}.md`);
+    return path10.join(datedDir, `${id}.md`);
   }
   async writeMemory(category, content, options = {}) {
     await this.ensureDirectories();
@@ -7401,7 +8328,7 @@ ${sanitized.text}
     await this.ensureDirectories();
     const now = /* @__PURE__ */ new Date();
     const day = now.toISOString().slice(0, 10);
-    const dir = path9.join(this.artifactsDir, day);
+    const dir = path10.join(this.artifactsDir, day);
     await mkdir2(dir, { recursive: true });
     const id = `artifact-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
     const fm = {
@@ -7426,7 +8353,7 @@ ${sanitized.text}
       log.warn(`artifact content rejected for ${id}; violations=${sanitized.violations.join(", ")}`);
       return "";
     }
-    const filePath = path9.join(dir, `${id}.md`);
+    const filePath = path10.join(dir, `${id}.md`);
     await this.writeStorageSecureFile(filePath, `${serializeFrontmatter(fm)}
 
 ${sanitized.text}
@@ -7697,7 +8624,7 @@ ${sanitized.text}
    * per-process in-memory cache safe across process boundaries.
    */
   invalidateColdMemoriesCache() {
-    const coldRoot = path9.join(this.baseDir, "cold");
+    const coldRoot = path10.join(this.baseDir, "cold");
     _StorageManager.coldMemoriesCache.delete(coldRoot);
     this.bumpColdWriteVersion();
     invalidateAllForDir(this.baseDir);
@@ -7757,7 +8684,7 @@ ${sanitized.text}
             const raw = await readMaybeEncryptedFile(fullPath, this._secureStoreKey, this.baseDir);
             const parsed = parseFrontmatter(raw);
             if (!parsed) return null;
-            return {
+            return rememberRawFrontmatter({
               path: fullPath,
               frontmatter: normalizeFrontmatterForPath(
                 parsed.frontmatter,
@@ -7765,7 +8692,7 @@ ${sanitized.text}
                 parsed.content
               ),
               content: parsed.content
-            };
+            }, raw);
           } catch (err) {
             if (err instanceof SecureStoreLockedError) throw err;
             return null;
@@ -7812,7 +8739,7 @@ ${sanitized.text}
     const correctionPaths = [];
     const factPaths = [];
     for (const filePath of filePaths) {
-      if (filePath === this.correctionsDir || filePath.startsWith(`${this.correctionsDir}${path9.sep}`)) {
+      if (filePath === this.correctionsDir || filePath.startsWith(`${this.correctionsDir}${path10.sep}`)) {
         correctionPaths.push(filePath);
       } else {
         factPaths.push(filePath);
@@ -7873,9 +8800,9 @@ ${sanitized.text}
     const root = this.archiveDir;
     const readDir = async (dir) => {
       try {
-        const entries = await readdir4(dir, { withFileTypes: true });
+        const entries = await readdir5(dir, { withFileTypes: true });
         for (const entry of entries) {
-          const fullPath = path9.join(dir, entry.name);
+          const fullPath = path10.join(dir, entry.name);
           if (entry.isDirectory()) {
             await readDir(fullPath);
           } else if (entry.name.endsWith(".md")) {
@@ -7883,7 +8810,7 @@ ${sanitized.text}
               const raw = await readMaybeEncryptedFile(fullPath, this._secureStoreKey, this.baseDir);
               const parsed = parseFrontmatter(raw);
               if (parsed) {
-                memories.push({
+                memories.push(rememberRawFrontmatter({
                   path: fullPath,
                   frontmatter: normalizeFrontmatterForPath(
                     parsed.frontmatter,
@@ -7891,7 +8818,7 @@ ${sanitized.text}
                     parsed.content
                   ),
                   content: parsed.content
-                });
+                }, raw));
               }
             } catch (err) {
               if (err instanceof SecureStoreLockedError) throw err;
@@ -7908,7 +8835,7 @@ ${sanitized.text}
     return this.memoryReadStore.readMemoryByPath(filePath);
   }
   resolveTierRootDir(tier) {
-    return tier === "cold" ? path9.join(this.baseDir, "cold") : this.baseDir;
+    return tier === "cold" ? path10.join(this.baseDir, "cold") : this.baseDir;
   }
   resolveMemoryDateDir(memory) {
     const preferred = memory.frontmatter.created || memory.frontmatter.updated;
@@ -7923,13 +8850,13 @@ ${sanitized.text}
   buildTierMemoryPath(memory, tier) {
     const root = this.resolveTierRootDir(tier);
     if (this.isArtifactMemory(memory)) {
-      return path9.join(root, "artifacts", this.resolveMemoryDateDir(memory), `${memory.frontmatter.id}.md`);
+      return path10.join(root, "artifacts", this.resolveMemoryDateDir(memory), `${memory.frontmatter.id}.md`);
     }
     if (memory.frontmatter.category === "correction") {
-      return path9.join(root, "corrections", `${memory.frontmatter.id}.md`);
+      return path10.join(root, "corrections", `${memory.frontmatter.id}.md`);
     }
     const dir = categoryDirName(memory.frontmatter.category);
-    return path9.join(root, dir, this.resolveMemoryDateDir(memory), `${memory.frontmatter.id}.md`);
+    return path10.join(root, dir, this.resolveMemoryDateDir(memory), `${memory.frontmatter.id}.md`);
   }
   async writeMemoryFileAtomic(targetPath, memory) {
     const fileContent = `${serializeFrontmatter(memory.frontmatter)}
@@ -7942,11 +8869,11 @@ ${memory.content}
   }
   async moveMemoryToPath(memory, targetPath) {
     await this.writeMemoryFileAtomic(targetPath, memory);
-    const sourcePath = path9.resolve(memory.path);
-    const destPath = path9.resolve(targetPath);
+    const sourcePath = path10.resolve(memory.path);
+    const destPath = path10.resolve(targetPath);
     if (sourcePath !== destPath) {
       try {
-        await unlink2(memory.path);
+        await unlink3(memory.path);
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         if (!message.includes("ENOENT")) {
@@ -7959,15 +8886,15 @@ ${memory.content}
   }
   async migrateMemoryToTier(memory, targetTier) {
     const targetPath = this.buildTierMemoryPath(memory, targetTier);
-    const sourcePath = path9.resolve(memory.path);
-    const destPath = path9.resolve(targetPath);
+    const sourcePath = path10.resolve(memory.path);
+    const destPath = path10.resolve(targetPath);
     if (sourcePath === destPath) {
       return { changed: false, targetPath };
     }
     const existing = await this.readMemoryByPath(targetPath);
     if (existing?.frontmatter.id === memory.frontmatter.id) {
       try {
-        await unlink2(memory.path);
+        await unlink3(memory.path);
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         if (!message.includes("ENOENT")) {
@@ -7987,7 +8914,7 @@ ${memory.content}
     return { changed: true, targetPath };
   }
   get archiveDir() {
-    return path9.join(this.baseDir, "archive");
+    return path10.join(this.baseDir, "archive");
   }
   /**
    * Archive a memory by moving it from facts/ to archive/YYYY-MM-DD/.
@@ -7998,7 +8925,7 @@ ${memory.content}
     try {
       const now = lifecycle?.at ?? /* @__PURE__ */ new Date();
       const today = now.toISOString().slice(0, 10);
-      const destDir = path9.join(this.archiveDir, today);
+      const destDir = path10.join(this.archiveDir, today);
       await mkdir2(destDir, { recursive: true });
       const updatedFm = {
         ...memory.frontmatter,
@@ -8010,9 +8937,9 @@ ${memory.content}
 
 ${memory.content}
 `;
-      const destPath = path9.join(destDir, path9.basename(memory.path));
+      const destPath = path10.join(destDir, path10.basename(memory.path));
       await this.writeStorageSecureFile(destPath, fileContent);
-      await unlink2(memory.path);
+      await unlink3(memory.path);
       markProjectedMemoryPathInvalid(this.baseDir, memory.frontmatter.id);
       this.invalidateAllMemoriesCache();
       await this.appendGeneratedMemoryLifecycleEventFailOpen(
@@ -8040,7 +8967,7 @@ ${memory.content}
   }
   async readEntities() {
     try {
-      const entries = await readdir4(this.entitiesDir);
+      const entries = await readdir5(this.entitiesDir);
       return entries.filter((e) => e.endsWith(".md")).map((e) => e.replace(".md", ""));
     } catch {
       return [];
@@ -8092,7 +9019,7 @@ ${memory.content}
     const memory = memories.find((m) => m.frontmatter.id === id);
     if (!memory) return false;
     try {
-      await unlink2(memory.path);
+      await unlink3(memory.path);
       markProjectedMemoryPathInvalid(this.baseDir, id);
       this.invalidateAllMemoriesCache();
       this.bumpMemoryStatusVersion();
@@ -8158,7 +9085,7 @@ ${memory.content}
 `;
     await this.writeStorageSecureFile(memory.path, fileContent);
     await this.patchHotMemoriesCache({ addedPath: memory.path });
-    if (memory.path.includes(`${path9.sep}cold${path9.sep}`)) {
+    if (memory.path.includes(`${path10.sep}cold${path10.sep}`)) {
       this.invalidateColdMemoriesCache();
     }
     try {
@@ -8213,7 +9140,7 @@ ${memory.content}
       const expiresAt = new Date(m.frontmatter.expiresAt).getTime();
       if (expiresAt < now) {
         try {
-          await unlink2(m.path);
+          await unlink3(m.path);
           markProjectedMemoryPathInvalid(this.baseDir, m.frontmatter.id);
           this.bumpMemoryCorpusVersion();
           deleted.push(m);
@@ -8229,7 +9156,7 @@ ${memory.content}
     return deleted;
   }
   async loadBuffer() {
-    const bufferPath = path9.join(this.stateDir, "buffer.json");
+    const bufferPath = path10.join(this.stateDir, "buffer.json");
     try {
       const raw = await this.readStorageSecureFile(bufferPath);
       return JSON.parse(raw);
@@ -8241,11 +9168,11 @@ ${memory.content}
   }
   async saveBuffer(state) {
     await this.ensureDirectories();
-    const bufferPath = path9.join(this.stateDir, "buffer.json");
+    const bufferPath = path10.join(this.stateDir, "buffer.json");
     await this.writeStorageSecureFile(bufferPath, JSON.stringify(state, null, 2));
   }
   async loadMeta() {
-    const metaPath = path9.join(this.stateDir, "meta.json");
+    const metaPath = path10.join(this.stateDir, "meta.json");
     try {
       const raw = await this.readStorageSecureFile(metaPath);
       const parsed = JSON.parse(raw);
@@ -8278,7 +9205,7 @@ ${memory.content}
   }
   async saveMeta(state) {
     await this.ensureDirectories();
-    const metaPath = path9.join(this.stateDir, "meta.json");
+    const metaPath = path10.join(this.stateDir, "meta.json");
     await this.writeStorageSecureFile(metaPath, JSON.stringify(state, null, 2));
   }
   async appendMemoryActionEvents(events) {
@@ -8345,7 +9272,7 @@ ${memory.content}
       },
       (payload) => this.appendStorageSecureFile(target, payload),
       async () => {
-        await mkdir2(path9.dirname(target), { recursive: true });
+        await mkdir2(path10.dirname(target), { recursive: true });
       }
     );
   }
@@ -8443,7 +9370,7 @@ ${memory.content}
   async appendReextractJobs(events) {
     if (events.length === 0) return 0;
     await this.ensureDirectories();
-    const filePath = path9.join(this.stateDir, "reextract-jobs.jsonl");
+    const filePath = path10.join(this.stateDir, "reextract-jobs.jsonl");
     const lines = events.map((event) => JSON.stringify(event)).join("\n") + "\n";
     try {
       await this.appendStorageSecureFile(filePath, lines);
@@ -8456,7 +9383,7 @@ ${memory.content}
   }
   async readReextractJobs(limit = 200) {
     const safeLimit = Number.isFinite(limit) ? Math.max(1, Math.min(1e3, Math.floor(limit))) : 200;
-    const filePath = path9.join(this.stateDir, "reextract-jobs.jsonl");
+    const filePath = path10.join(this.stateDir, "reextract-jobs.jsonl");
     try {
       const raw = await this.readStorageSecureFile(filePath);
       const lines = raw.split("\n").filter((line) => line.trim().length > 0);
@@ -8617,8 +9544,8 @@ ${memory.content}
       activationState: "active"
     });
     await Promise.all([
-      unlink2(this.compressionGuidelineDraftPath).catch(() => void 0),
-      unlink2(this.compressionGuidelineDraftStatePath).catch(() => void 0)
+      unlink3(this.compressionGuidelineDraftPath).catch(() => void 0),
+      unlink3(this.compressionGuidelineDraftStatePath).catch(() => void 0)
     ]);
     return true;
   }
@@ -8686,7 +9613,7 @@ ${question}
 
 **Context:** ${context}
 `;
-    const filePath = path9.join(this.questionsDir, `${id}.md`);
+    const filePath = path10.join(this.questionsDir, `${id}.md`);
     await this.writeStorageSecureFile(filePath, content);
     log.debug(`wrote question ${id} to ${filePath}`);
     this.invalidateQuestionsCache();
@@ -8704,7 +9631,7 @@ ${question}
     if (!match) return null;
     const frontmatterStr = match[1];
     const body = match[2].trim();
-    const id = this.extractFrontmatterValue(frontmatterStr, "id") ?? path9.basename(filePath, ".md");
+    const id = this.extractFrontmatterValue(frontmatterStr, "id") ?? path10.basename(filePath, ".md");
     const created = this.extractFrontmatterValue(frontmatterStr, "created") ?? "";
     const priority = parseFloat(this.extractFrontmatterValue(frontmatterStr, "priority") ?? "0.5");
     const resolved = this.extractFrontmatterValue(frontmatterStr, "resolved") === "true";
@@ -8738,14 +9665,14 @@ ${question}
   async readIdentity(workspaceDir, namespace) {
     const identityPath = this.identityFilePath(workspaceDir, namespace);
     try {
-      return await readFile(identityPath, "utf-8");
+      return await readFile2(identityPath, "utf-8");
     } catch {
       return "";
     }
   }
   async writeIdentity(workspaceDir, content, namespace) {
     const identityPath = this.identityFilePath(workspaceDir, namespace);
-    await writeFile(identityPath, content, "utf-8");
+    await writeFile2(identityPath, content, "utf-8");
     log.debug(`wrote consolidated IDENTITY.md (${content.length} chars)`);
   }
   /** Max size for IDENTITY.md before we stop appending reflections (15KB leaves room under 20KB gateway limit) */
@@ -8756,22 +9683,22 @@ ${question}
     const identityPath = this.identityFilePath(workspaceDir, opts?.namespace);
     let existing = "";
     try {
-      existing = await readFile(identityPath, "utf-8");
+      existing = await readFile2(identityPath, "utf-8");
     } catch {
     }
     const hygiene = opts?.hygiene;
-    const rotateEnabled = hygiene?.enabled === true && hygiene.rotateEnabled === true && Array.isArray(hygiene.rotatePaths) && hygiene.rotatePaths.includes(path9.basename(identityPath));
+    const rotateEnabled = hygiene?.enabled === true && hygiene.rotateEnabled === true && Array.isArray(hygiene.rotatePaths) && hygiene.rotatePaths.includes(path10.basename(identityPath));
     if (rotateEnabled) {
       const maxBytes = hygiene.rotateMaxBytes;
       if (existing.length > maxBytes) {
-        const archiveDir = path9.join(workspaceDir, hygiene.archiveDir);
+        const archiveDir = path10.join(workspaceDir, hygiene.archiveDir);
         const { newContent } = await rotateMarkdownFileToArchive({
           filePath: identityPath,
           archiveDir,
           archivePrefix: "IDENTITY",
           keepTailChars: hygiene.rotateKeepTailChars
         });
-        await writeFile(identityPath, newContent, "utf-8");
+        await writeFile2(identityPath, newContent, "utf-8");
         existing = newContent;
         log.info(`rotated IDENTITY.md to archive (size=${existing.length} chars, maxBytes=${maxBytes})`);
       }
@@ -8804,7 +9731,7 @@ ${question}
 
 ${reflection}
 `;
-    await writeFile(identityPath, existing + section, "utf-8");
+    await writeFile2(identityPath, existing + section, "utf-8");
     log.debug(`appended reflection to ${identityPath}`);
   }
   async readIdentityReflections() {
@@ -8860,7 +9787,7 @@ ${reflection}
    * Deduplicates by target+label.
    */
   async addEntityRelationship(name, rel) {
-    const filePath = path9.join(this.entitiesDir, `${name}.md`);
+    const filePath = path10.join(this.entitiesDir, `${name}.md`);
     let entity;
     try {
       const content = await this.readStorageSecureFile(filePath);
@@ -8883,7 +9810,7 @@ ${reflection}
    * Prepends to the beginning, prunes oldest entries beyond maxEntries.
    */
   async addEntityActivity(name, entry, maxEntries) {
-    const filePath = path9.join(this.entitiesDir, `${name}.md`);
+    const filePath = path10.join(this.entitiesDir, `${name}.md`);
     let entity;
     try {
       const content = await this.readStorageSecureFile(filePath);
@@ -8902,11 +9829,8 @@ ${reflection}
     await this.writeStorageSecureFile(filePath, serializeEntityFile(entity, this.entitySchemas));
     this.invalidateKnowledgeIndexCache();
   }
-  /**
-   * Add an alias to an entity file. Deduplicates.
-   */
   async addEntityAlias(name, alias) {
-    const filePath = path9.join(this.entitiesDir, `${name}.md`);
+    const filePath = path10.join(this.entitiesDir, `${name}.md`);
     let entity;
     try {
       const content = await this.readStorageSecureFile(filePath);
@@ -8922,6 +9846,7 @@ ${reflection}
     entity.updated = (/* @__PURE__ */ new Date()).toISOString();
     await this.writeStorageSecureFile(filePath, serializeEntityFile(entity, this.entitySchemas));
     this.invalidateKnowledgeIndexCache();
+    this.bumpMemoryStatusVersion();
   }
   async updateEntitySynthesis(name, synthesis, options = {}) {
     return this.entityStore.updateEntitySynthesis(name, synthesis, options);
@@ -8933,7 +9858,7 @@ ${reflection}
     const updatedAt = (/* @__PURE__ */ new Date()).toISOString();
     let synthesisTimelineCount;
     try {
-      const filePath = path9.join(this.entitiesDir, `${name}.md`);
+      const filePath = path10.join(this.entitiesDir, `${name}.md`);
       const content = await this.readStorageSecureFile(filePath);
       synthesisTimelineCount = parseEntityFile(content, this.entitySchemas).timeline.length;
     } catch (err) {
@@ -9016,7 +9941,7 @@ ${reflection}
       if (!raw) continue;
       const serialized = serializeEntityFile(parseEntityFile(raw, this.entitySchemas), this.entitySchemas);
       if (raw.trimEnd() === serialized.trimEnd()) continue;
-      await this.writeStorageSecureFile(path9.join(this.entitiesDir, `${entityName}.md`), serialized);
+      await this.writeStorageSecureFile(path10.join(this.entitiesDir, `${entityName}.md`), serialized);
       migrated += 1;
     }
     if (migrated > 0) {
@@ -9084,7 +10009,7 @@ ${reflection}
       const updatedAt = new Date(m.frontmatter.updated).getTime();
       if (updatedAt < cutoff) {
         try {
-          await unlink2(m.path);
+          await unlink3(m.path);
           markProjectedMemoryPathInvalid(this.baseDir, m.frontmatter.id);
           this.bumpMemoryCorpusVersion();
           deleted.push(m);
@@ -9109,14 +10034,14 @@ ${reflection}
     if (entries.length === 0) return 0;
     const memories = await this.readAllMemories();
     const memoryMap = new Map(memories.map((m) => [m.frontmatter.id, m]));
-    const memoryPathMap = new Map(memories.map((m) => [path9.resolve(m.path), m]));
+    const memoryPathMap = new Map(memories.map((m) => [path10.resolve(m.path), m]));
     let updated = 0;
     const prevVersion = this.getMemoryCorpusVersion();
     const keyId = this.hotCacheKeyId();
     const warm = this.hotMemoriesCacheEnabled && getCachedMemories(this.baseDir, prevVersion, keyId, this.hotCacheTtlMs()) !== null;
     const appliedPatches = /* @__PURE__ */ new Map();
     for (const entry of entries) {
-      const memory = entry.memoryPath ? memoryPathMap.get(path9.resolve(entry.memoryPath)) : memoryMap.get(entry.memoryId);
+      const memory = entry.memoryPath ? memoryPathMap.get(path10.resolve(entry.memoryPath)) : memoryMap.get(entry.memoryId);
       if (!memory) continue;
       const newFm = {
         ...memory.frontmatter,
@@ -9132,7 +10057,7 @@ ${memory.content}
         if (warm) {
           updateCacheOnWrite(this.baseDir, { ...memory, frontmatter: newFm }, keyId);
         }
-        appliedPatches.set(path9.resolve(memory.path), {
+        appliedPatches.set(path10.resolve(memory.path), {
           accessCount: entry.newCount,
           lastAccessed: entry.lastAccessed
         });
@@ -9148,7 +10073,7 @@ ${memory.content}
         const cur = getCachedMemories(this.baseDir, prevVersion, keyId);
         if (cur) {
           const reapplied = cur.map((m) => {
-            const patch = appliedPatches.get(path9.resolve(m.path));
+            const patch = appliedPatches.get(path10.resolve(m.path));
             return patch ? { ...m, frontmatter: { ...m.frontmatter, accessCount: patch.accessCount, lastAccessed: patch.lastAccessed } } : m;
           });
           setCachedMemories(this.baseDir, reapplied, produced, keyId, this.hotCacheTtlMs());
@@ -9180,7 +10105,7 @@ ${memory.content}
     const pathsById = /* @__PURE__ */ new Map();
     const filePathsById = /* @__PURE__ */ new Map();
     for (const filePath of filePaths) {
-      const memoryId = path9.basename(filePath, ".md");
+      const memoryId = path10.basename(filePath, ".md");
       if (!wantedIds.has(memoryId)) continue;
       const paths = filePathsById.get(memoryId) ?? [];
       paths.push(filePath);
@@ -9195,7 +10120,7 @@ ${memory.content}
           qmdResultPathCandidates(this.baseDir, preferredPath)
         );
         const directMatch = existingPaths.find(
-          (filePath) => directCandidates.has(path9.resolve(filePath))
+          (filePath) => directCandidates.has(path10.resolve(filePath))
         );
         if (directMatch) {
           preferredMatches.push(directMatch);
@@ -9208,7 +10133,7 @@ ${memory.content}
             candidates.add(candidate);
           }
         }
-        const match = existingPaths.find((filePath) => candidates.has(path9.resolve(filePath)));
+        const match = existingPaths.find((filePath) => candidates.has(path10.resolve(filePath)));
         if (match) preferredMatches.push(match);
       }
       if (preferredMatches.length > 0) {
@@ -9427,14 +10352,14 @@ Reason: ${reason}`;
   // Memory Summarization (Phase 4A)
   // ---------------------------------------------------------------------------
   get summariesDir() {
-    return path9.join(this.baseDir, "summaries");
+    return path10.join(this.baseDir, "summaries");
   }
   /**
    * Write a memory summary.
    */
   async writeSummary(summary) {
     await mkdir2(this.summariesDir, { recursive: true });
-    const filePath = path9.join(this.summariesDir, `${summary.id}.json`);
+    const filePath = path10.join(this.summariesDir, `${summary.id}.json`);
     await this.writeStorageSecureFile(filePath, JSON.stringify(summary, null, 2));
     log.debug(`wrote summary ${summary.id}`);
   }
@@ -9443,11 +10368,11 @@ Reason: ${reason}`;
    */
   async readSummaries() {
     try {
-      const files = await readdir4(this.summariesDir);
+      const files = await readdir5(this.summariesDir);
       const summaries = [];
       for (const file of files) {
         if (!file.endsWith(".json")) continue;
-        const filePath = path9.join(this.summariesDir, file);
+        const filePath = path10.join(this.summariesDir, file);
         const raw = await this.readStorageSecureFile(filePath);
         summaries.push(JSON.parse(raw));
       }
@@ -9509,7 +10434,7 @@ ${memory.content}
    * Save topic scores to meta.json.
    */
   async saveTopics(topics) {
-    const metaPath = path9.join(this.stateDir, "topics.json");
+    const metaPath = path10.join(this.stateDir, "topics.json");
     await mkdir2(this.stateDir, { recursive: true });
     await this.writeStorageSecureFile(
       metaPath,
@@ -9521,7 +10446,7 @@ ${memory.content}
    * Load topic scores from meta.json.
    */
   async loadTopics() {
-    const metaPath = path9.join(this.stateDir, "topics.json");
+    const metaPath = path10.join(this.stateDir, "topics.json");
     try {
       const raw = await this.readStorageSecureFile(metaPath);
       return JSON.parse(raw);
@@ -9637,11 +10562,10 @@ export {
   parseFrontmatterStringValue,
   parseFrontmatter,
   normalizeFrontmatterForPath,
-  normalizeEntityName,
   parseEntityFile,
   serializeEntityFile,
   buildEntitySchemaCacheKey,
   isValidBufferSurpriseEvent,
   StorageManager3 as StorageManager
 };
-//# sourceMappingURL=chunk-CIQXI47W.js.map
+//# sourceMappingURL=chunk-FCDWWCLX.js.map