@remnic/core 9.35.2 → 9.35.3

package/dist/{chunk-4TGZCYHH.js → chunk-Q3CVY7LV.js}

@@ -11,14 +11,10 @@ import {
 } from "./chunk-UHVXE24Y.js";
 import {
   TombstoneStore,
+  applyTombstoneResurrectionGate,
   buildRetiredFactTombstoneInputs,
   collectRetiredMemoriesForRebuild
-} from "./chunk-QNWXCJ76.js";
-import {
-  computeSupersessionKey,
-  normalizeSupersessionKey,
-  supersessionKeysForFact
-} from "./chunk-DNHVPZOD.js";
+} from "./chunk-ENTCVTQR.js";
 import {
   assertMemoryFrontmatterId,
   warnProjectionFallback
@@ -42,7 +38,7 @@ import {
   readMaybeEncryptedLines,
   readMemoryActionEventRowsFromLines,
   serializeLifecycleAppendPayload
-} from "./chunk-7VUAG236.js";
+} from "./chunk-T3FVAHM7.js";
 import {
   namespaceIdentityFromToken
 } from "./chunk-EGGE52UU.js";
@@ -82,7 +78,7 @@ import {
   TombstoneBlockedCaptureIndexHost,
   buildExplicitCaptureDedupKey,
   parseTombstoneBlockedOfflineSyncMemory
-} from "./chunk-FBUE6PD3.js";
+} from "./chunk-BEQOZOYZ.js";
 import {
   composeMemoryEnvelope,
   isSealedMemoryEnvelope,
@@ -92,9 +88,6 @@ import {
   assemblePersistedBody,
   stripAttributesSuffix
 } from "./chunk-R3DJVOSM.js";
-import {
-  withHeldFileLock
-} from "./chunk-FFAZ2XFU.js";
 import {
   markProjectedMemoryPathInvalid,
   openProjectionReadonly,
@@ -117,7 +110,7 @@ import {
 } from "./chunk-G7D6GZ5J.js";
 import {
   createVersion
-} from "./chunk-6TAUHL33.js";
+} from "./chunk-DLVPUX7U.js";
 import {
   clearInFlightReads,
   deleteInFlightRead,
@@ -125,6 +118,27 @@ import {
   getInFlightRead,
   setInFlightRead
 } from "./chunk-PDJTHRAW.js";
+import {
+  ENTITY_CANONICAL_ID_MIGRATION_FILE,
+  ENTITY_CANONICAL_ID_RECONCILE_CONSUMING_MARKER,
+  ENTITY_CANONICAL_ID_RECONCILE_MARKER,
+  HistoricalEntityCanonicalIdCache,
+  appendCanonicalizedTombstone,
+  canonicalizeEntityRefOption,
+  reconcileIfJournalMovedSync,
+  repairEntityRefAfterJournalMove,
+  requestEntityCanonicalIdReconcileSync,
+  resolveHistoricalEntityCanonicalId,
+  withEntityCanonicalMutationLock
+} from "./chunk-4J7G5SY4.js";
+import {
+  computeSupersessionKey,
+  normalizeSupersessionKey,
+  supersessionKeysForFact
+} from "./chunk-DNHVPZOD.js";
+import {
+  withHeldFileLock
+} from "./chunk-FFAZ2XFU.js";
 import {
   clearMemoryCache,
   getCachedEntities,
@@ -214,11 +228,11 @@ import {
   stat as stat2,
   writeFile as writeFile2,
   mkdir,
-  unlink as unlink3,
+  unlink as unlink4,
   appendFile,
   open
 } from "fs/promises";
-import { appendFileSync, createReadStream, mkdirSync, readFileSync as readFileSync2, statSync } from "fs";
+import { appendFileSync, createReadStream, mkdirSync, readFileSync, statSync } from "fs";
 import { createHash as createHash5 } from "crypto";
 import path9 from "path";
 
@@ -1420,1442 +1434,1641 @@ function selfDeps(self) {
 }
 
 // src/storage/entity-store.ts
-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 { readdir as readdir2, unlink } 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 {};
+var EntityStore = class {
+  constructor(deps) {
+    this.deps = deps;
   }
-}
-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;
+  deps;
+  /** Normalize an entity name using this store's alias table. */
+  normalizeEntityName(raw, type) {
+    return normalizeEntityName(raw, type, this.deps.userAliases);
   }
-  return current;
-}
-var EntityCanonicalIdMigrationStateSchema = z.object({
-  version: z.literal(ENTITY_CANONICAL_ID_MIGRATION_VERSION),
-  complete: z.boolean(),
-  mappings: z.record(z.string().min(1)),
   /**
-   * Pairs the migration refused to resolve, PARKED rather than dropped.
-   * Deleting the record would strand the collision: once an operator removes
-   * the legacy file, no later scan can rediscover the mapping, so references
-   * still naming the legacy id would never be rewritten. Optional so a journal
-   * written by an older build still parses.
+   * Read an entity file by id, resolving through the migration journal with a
+   * fallback to the caller's original id (issue #2213): mid-migration, the
+   * journal maps legacy → canonical BEFORE the file moves — writing the
+   * still-existing legacy file is safe (the rename retry carries it), while
+   * resolving only the canonical path silently drops the mutation.
    */
-  blocked: z.record(z.string().min(1)).optional()
-});
-async function fingerprintPath(filePath) {
-  let fileStat;
-  try {
-    fileStat = await lstat2(filePath);
-  } catch (error) {
-    if (!isErrnoCode(error, "ENOENT")) throw error;
+  async readEntityForMutation(name, method, historicalIds) {
+    const canonical = resolveHistoricalEntityCanonicalId(name, historicalIds);
+    for (const candidate of canonical === name ? [name] : [canonical, name]) {
+      const filePath = path3.join(this.deps.entitiesDir, `${candidate}.md`);
+      try {
+        const entity = parseEntityFile(await this.deps.readStorageSecureFile(filePath), this.deps.entitySchemas);
+        return { filePath, entity };
+      } catch (err) {
+        if (err instanceof SecureStoreLockedError) throw err;
+        if (!isErrnoCode(err, "ENOENT")) throw err;
+      }
+    }
+    log.debug(`${method}: entity file ${canonical}.md not found`);
+    return null;
   }
-  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;
+  /**
+   * Locked read-modify-write for the entity-file mutators (issue #2213):
+   * holding the entity-mutation lock keeps `migrateEntityFilePair` (which
+   * takes the same lock) from moving the file between the fallback read and
+   * this write — an unlocked write could recreate a just-renamed legacy file.
+   * The journal itself is NOT serialized by this lock (`pruneBlocked` can
+   * park a mapping mid-mutation), so the journal identity is REVALIDATED
+   * just before committing — a moved journal restarts resolution against the
+   * fresh table instead of writing into a since-contested claimant — and
+   * checked once more after the write for a move across the write itself.
+   * `mutate` returns false to skip the write. Resolves true when written.
+   */
+  async mutateEntityFile(name, method, mutate) {
+    const stateDir = path3.join(this.deps.baseDir, "state");
+    return withEntityCanonicalMutationLock(stateDir, async () => {
+      for (let attempt = 0; attempt < 3; attempt += 1) {
+        const idsAtResolve = this.deps.currentHistoricalIds();
+        const located = await this.readEntityForMutation(name, method, idsAtResolve);
+        const mutated = located !== null && mutate(located.entity, idsAtResolve);
+        if (this.deps.currentHistoricalIds() !== idsAtResolve) continue;
+        if (!located || !mutated) return false;
+        located.entity.updated = (/* @__PURE__ */ new Date()).toISOString();
+        await this.deps.writeStorageSecureFile(
+          located.filePath,
+          serializeEntityFile(located.entity, this.deps.entitySchemas)
+        );
+        reconcileIfJournalMovedSync(stateDir, idsAtResolve, this.deps.currentHistoricalIds());
+        this.deps.invalidateKnowledgeIndexCache();
+        this.deps.bumpEntityMutationVersion();
+        return true;
+      }
+      requestEntityCanonicalIdReconcileSync(stateDir);
+      throw new Error(
+        `${method}: entity canonical-id journal kept changing; mutation not applied \u2014 retry`
+      );
+    });
   }
-  if (baseStat.isSymbolicLink() || !baseStat.isDirectory()) {
-    throw new Error(`Refusing entity canonical-id migration through unsafe memory root: ${baseDir}.`);
+  /** Add a relationship to an entity file. Deduplicates by target+label. */
+  async addEntityRelationship(name, rel) {
+    await this.mutateEntityFile(name, "addEntityRelationship", (entity, historicalIds) => {
+      const target = resolveHistoricalEntityCanonicalId(rel.target, historicalIds);
+      const duplicate = entity.relationships.some(
+        (r) => resolveHistoricalEntityCanonicalId(r.target, historicalIds) === target && r.label === rel.label
+      );
+      if (duplicate) return false;
+      entity.relationships.push({ ...rel, target });
+      return true;
+    });
   }
-  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);
+  /** Add an activity entry to an entity file; prunes oldest beyond maxEntries. */
+  async addEntityActivity(name, entry, maxEntries) {
+    await this.mutateEntityFile(name, "addEntityActivity", (entity) => {
+      entity.activity.unshift(entry);
+      if (entity.activity.length > maxEntries) entity.activity = entity.activity.slice(0, maxEntries);
+      return true;
+    });
   }
-}
-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;
+  async addEntityAlias(name, alias) {
+    const wrote = await this.mutateEntityFile(name, "addEntityAlias", (entity) => {
+      if (entity.aliases.includes(alias)) return false;
+      entity.aliases.push(alias);
+      return true;
+    });
+    if (wrote) this.deps.bumpMemoryStatusVersion();
   }
-  if (fileStat.isSymbolicLink() || !fileStat.isFile()) {
-    throw new Error(
-      `Refusing entity canonical-id migration through unsafe migration state file: ${migrationStatePath}.`
+  async writeEntity(name, type, facts, options = {}) {
+    await this.deps.ensureDirectories();
+    return withEntityCanonicalMutationLock(
+      path3.join(this.deps.baseDir, "state"),
+      () => this.writeEntityUnlocked(name, type, facts, options)
     );
   }
-  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}.`
+  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,
+        typeType: typeof type
+      });
+      return "";
+    }
+    const safeFacts = Array.isArray(facts) ? [...new Set(
+      facts.filter((fact) => typeof fact === "string").map((fact) => fact.trim()).filter((fact) => fact.length > 0)
+    )] : [];
+    let normalized = this.deps.normalizeEntityName(name, type);
+    const match = await this.deps.findMatchingEntity(name, type);
+    if (match && match !== normalized) {
+      log.debug(`fuzzy match: "${normalized}" \u2192 existing "${match}"`);
+      normalized = match;
+    }
+    const filePath = path3.join(this.deps.entitiesDir, `${normalized}.md`);
+    let entity = {
+      name,
+      type,
+      created: "",
+      updated: (/* @__PURE__ */ new Date()).toISOString(),
+      facts: [],
+      summary: void 0,
+      synthesis: void 0,
+      synthesisUpdatedAt: void 0,
+      synthesisVersion: void 0,
+      synthesisStructuredFactCount: void 0,
+      synthesisStructuredFactDigest: void 0,
+      timeline: [],
+      relationships: [],
+      activity: [],
+      aliases: []
+    };
+    try {
+      const existing = await this.deps.readStorageSecureFile(filePath);
+      entity = parseEntityFile(existing, this.deps.entitySchemas);
+    } catch (err) {
+      if (err instanceof SecureStoreLockedError) throw err;
+      if (!isErrnoCode(err, "ENOENT")) throw err;
+    }
+    const timestamp = options.timestamp?.trim() || (/* @__PURE__ */ new Date()).toISOString();
+    const source = options.source?.trim() || void 0;
+    const sessionKey = options.sessionKey?.trim() || void 0;
+    const principal = options.principal?.trim() || void 0;
+    const structuredSectionMap = new Map(
+      (entity.structuredSections ?? []).map((section) => [section.key, {
+        ...section,
+        facts: [...section.facts]
+      }])
     );
-  }
-  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());
+    for (const section of options.structuredSections ?? []) {
+      const normalizedSection = normalizeEntityStructuredSection(type, section, this.deps.entitySchemas);
+      const normalizedFacts = normalizeStructuredSectionFacts(section.facts);
+      if (normalizedFacts.length === 0) continue;
+      const existingSection = structuredSectionMap.get(normalizedSection.key);
+      if (!existingSection) {
+        structuredSectionMap.set(normalizedSection.key, {
+          key: normalizedSection.key,
+          title: normalizedSection.title,
+          facts: normalizedFacts
+        });
+        continue;
+      }
+      existingSection.facts = normalizeStructuredSectionFacts([...existingSection.facts, ...normalizedFacts]);
+      if (!existingSection.title.trim() && normalizedSection.title.trim()) {
+        existingSection.title = normalizedSection.title;
+      }
     }
-  );
-}
-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 stat3;
-  try {
-    stat3 = await lstat2(filePath);
-  } catch (error) {
-    if (isErrnoCode(error, "ENOENT")) return;
-    throw error;
-  }
-  if (stat3.isSymbolicLink()) {
-    throw new Error(`Refusing entity canonical-id migration through symlink: ${label}.`);
-  }
-}
-async function assertNotMemorySymlink(filePath) {
-  let stat3;
-  try {
-    stat3 = await lstat2(filePath);
-  } catch (error) {
-    if (isErrnoCode(error, "ENOENT")) return;
-    throw error;
-  }
-  if (stat3.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 = {}, blocked = /* @__PURE__ */ new Map()) {
-  const mappings = {};
-  const canonicalOwners = /* @__PURE__ */ new Map();
-  blocked.clear();
-  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.`);
+    for (const fact of safeFacts) {
+      const nextEntry = {
+        timestamp,
+        text: fact,
+        ...source ? { source } : {},
+        ...sessionKey ? { sessionKey } : {},
+        ...principal ? { principal } : {}
+      };
+      const alreadyPresent = entity.timeline.some(
+        (entry) => entry.timestamp === nextEntry.timestamp && entry.text === nextEntry.text && entry.source === nextEntry.source && entry.sessionKey === nextEntry.sessionKey && entry.principal === nextEntry.principal
+      );
+      if (alreadyPresent) continue;
+      entity.timeline.push(nextEntry);
     }
-    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.`);
+    entity.structuredSections = sortStructuredSectionsBySchema(
+      type,
+      Array.from(structuredSectionMap.values()).filter((section) => section.facts.length > 0),
+      this.deps.entitySchemas
+    );
+    entity.facts = compileEntityFacts(entity.timeline, entity.structuredSections);
+    entity.summary = entity.synthesis || entity.summary;
+    entity.name = name;
+    entity.type = type;
+    entity.created = entity.created || timestamp;
+    entity.updated = (/* @__PURE__ */ new Date()).toISOString();
+    await this.deps.snapshotBeforeWrite(filePath, "write");
+    await this.deps.writeStorageSecureFile(filePath, serializeEntityFile(entity, this.deps.entitySchemas));
+    this.deps.invalidateKnowledgeIndexCache();
+    this.deps.bumpMemoryStatusVersion();
+    this.deps.bumpEntityMutationVersion();
+    log.debug(`wrote entity ${normalized}`);
+    return normalized;
+  }
+  async readEntity(name) {
+    const filePath = this.deps.resolveEntityFilePath(name);
+    if (filePath === null) {
+      return "";
     }
-    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) {
-        blocked.set(legacyId, canonicalId);
-        continue;
-      }
+    try {
+      return await this.deps.readStorageSecureFile(filePath);
+    } catch (err) {
+      if (err instanceof SecureStoreLockedError) throw err;
+      if (!isErrnoCode(err, "ENOENT")) throw err;
+      return "";
     }
-    canonicalOwners.set(canonicalId, [...canonicalOwners.get(canonicalId) ?? [], legacyId]);
-    mappings[legacyId] = canonicalId;
   }
-  for (const [canonicalId, claimants] of canonicalOwners) {
-    if (claimants.length < 2) continue;
-    for (const legacyId of claimants) {
-      blocked.set(legacyId, canonicalId);
-      delete mappings[legacyId];
+  /** Return sorted list of entity filenames (without .md extension) */
+  async listEntityNames() {
+    try {
+      const entries = await readdir2(this.deps.entitiesDir);
+      return entries.filter((e) => e.endsWith(".md")).map((e) => e.replace(".md", "")).sort();
+    } catch {
+      return [];
     }
   }
-  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}`);
+  /** Re-serialize every entity file into the compiled-truth timeline shape. */
+  async migrateEntityFilesToCompiledTruthTimeline() {
+    const entityNames = await this.listEntityNames();
+    const stateDir = path3.join(this.deps.baseDir, "state");
+    let migrated = 0;
+    for (const entityName of entityNames) {
+      const wrote = await withEntityCanonicalMutationLock(stateDir, async () => {
+        const raw = await this.readEntity(entityName);
+        if (!raw) return false;
+        const serialized = serializeEntityFile(parseEntityFile(raw, this.deps.entitySchemas), this.deps.entitySchemas);
+        if (raw.trimEnd() === serialized.trimEnd()) return false;
+        const filePath = this.deps.resolveEntityFilePath(entityName);
+        if (filePath === null) return false;
+        await this.deps.writeStorageSecureFile(filePath, serialized);
+        this.deps.bumpEntityMutationVersion();
+        return true;
+      });
+      if (wrote) migrated += 1;
     }
-    if (!rewroteAny) return { rewroteColdMemory };
+    if (migrated > 0) {
+      this.deps.invalidateKnowledgeIndexCache();
+      this.deps.bumpMemoryStatusVersion();
+    }
+    return { total: entityNames.length, migrated };
   }
-  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;
+  /**
+   * Set or rewrite the synthesis layer of an entity file.
+   */
+  async updateEntitySynthesis(name, synthesis, options = {}) {
+    return withEntityCanonicalMutationLock(
+      path3.join(this.deps.baseDir, "state"),
+      () => this.updateEntitySynthesisUnlocked(name, synthesis, options)
+    );
   }
-  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;
+  async updateEntitySynthesisUnlocked(name, synthesis, options = {}) {
+    const filePath = path3.join(this.deps.entitiesDir, `${name}.md`);
+    let entity;
+    try {
+      const content = await this.deps.readStorageSecureFile(filePath);
+      entity = parseEntityFile(content, this.deps.entitySchemas);
+    } catch (err) {
+      if (err instanceof SecureStoreLockedError) throw err;
+      if (!isErrnoCode(err, "ENOENT")) throw err;
+      log.debug(`updateEntitySynthesis: entity file ${name}.md not found`);
+      return;
     }
-  }
-  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;
+    const updatedAt = options.updatedAt?.trim() || entity.synthesisUpdatedAt?.trim() || void 0;
+    const entityUpdatedAt = options.entityUpdatedAt?.trim() || updatedAt || entity.updated || (/* @__PURE__ */ new Date()).toISOString();
+    const synthesisTimelineCount = Number.isInteger(options.synthesisTimelineCount) && (options.synthesisTimelineCount ?? 0) >= 0 ? options.synthesisTimelineCount : void 0;
+    const synthesisStructuredFactCount = Number.isInteger(options.synthesisStructuredFactCount) && (options.synthesisStructuredFactCount ?? 0) >= 0 ? options.synthesisStructuredFactCount : countEntityStructuredFacts(entity);
+    const synthesisStructuredFactDigest = options.synthesisStructuredFactDigest?.trim() || fingerprintEntityStructuredFacts(entity);
+    entity.synthesis = synthesis.trim();
+    entity.summary = entity.synthesis;
+    entity.synthesisUpdatedAt = updatedAt;
+    entity.synthesisTimelineCount = synthesisTimelineCount;
+    entity.synthesisStructuredFactCount = synthesisStructuredFactCount;
+    entity.synthesisStructuredFactDigest = synthesisStructuredFactDigest;
+    entity.synthesisVersion = Math.max(0, entity.synthesisVersion ?? 0) + (options.incrementVersion === false ? 0 : 1);
+    entity.updated = entityUpdatedAt;
+    await this.deps.writeStorageSecureFile(filePath, serializeEntityFile(entity, this.deps.entitySchemas));
+    await this.deps.removeEntitySynthesisQueueEntries([
+      .../* @__PURE__ */ new Set([name, this.deps.normalizeEntityName(entity.name, entity.type)])
+    ]);
+    this.deps.invalidateKnowledgeIndexCache();
+    this.deps.bumpMemoryStatusVersion();
+    this.deps.bumpEntityMutationVersion();
+  }
+  /**
+   * Read all entity files and return lightweight EntityFile objects.
+   * Parsing is fast (~50-100ms for ~1,800 files) since entity files are small.
+   */
+  async readAllEntityFiles() {
+    const currentVersion = this.deps.getMemoryStatusVersion();
+    const schemaCacheKey = buildEntitySchemaCacheKey(this.deps.entitySchemas);
+    const cacheKey = `${this.deps.getEntityCacheSecureStoreKey()}\0${schemaCacheKey}`;
+    const cached = getCachedEntities(this.deps.baseDir, currentVersion, cacheKey);
+    if (cached) return cached;
+    try {
+      const entries = await readdir2(this.deps.entitiesDir);
+      const mdFiles = entries.filter((e) => e.endsWith(".md"));
+      if (mdFiles.length === 0) return [];
+      const BATCH_SIZE = 100;
+      const entities = [];
+      for (let i = 0; i < mdFiles.length; i += BATCH_SIZE) {
+        const batch = mdFiles.slice(i, i + BATCH_SIZE);
+        const results = await Promise.all(
+          batch.map(async (entry) => {
+            try {
+              return await this.deps.readStorageSecureFile(path3.join(this.deps.entitiesDir, entry));
+            } catch (err) {
+              if (err instanceof SecureStoreLockedError) throw err;
+              if (!isErrnoCode(err, "ENOENT")) throw err;
+              return null;
+            }
+          })
+        );
+        for (const content of results) {
+          if (content !== null) entities.push(parseEntityFile(content, this.deps.entitySchemas));
+        }
       }
+      setCachedEntities(this.deps.baseDir, entities, currentVersion, cacheKey);
+      return entities;
+    } catch (err) {
+      if (err instanceof SecureStoreLockedError || !isErrnoCode(err, "ENOENT")) throw err;
+      return [];
     }
   }
-  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);
+  /**
+   * Build the Knowledge Index: a compact markdown table of top-scored entities.
+   * Respects maxEntities and maxChars limits from config.
+   */
+  async buildKnowledgeIndex(config, overrides) {
+    const useDefaultLimits = overrides?.maxEntities === void 0 && overrides?.maxChars === void 0;
+    if (useDefaultLimits && this.deps.knowledgeIndexCache && Date.now() - this.deps.knowledgeIndexCache.builtAt < this.deps.storageManagerClass.KNOWLEDGE_INDEX_CACHE_TTL_MS) {
+      return { result: this.deps.knowledgeIndexCache.result, cached: true };
     }
-  }
-  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);
+    const entities = await this.deps.readAllEntityFiles();
+    if (entities.length === 0) {
+      if (useDefaultLimits) this.deps.knowledgeIndexCache = { result: "", builtAt: Date.now() };
+      return { result: "", cached: false };
     }
-  );
-}
-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) {
-      let hop = canonicalId;
-      const seen = /* @__PURE__ */ new Set();
-      while (hop !== void 0 && hop !== previousMapping && !seen.has(hop)) {
-        seen.add(hop);
-        hop = merged[hop];
-      }
-      if (hop !== previousMapping) {
-        throw new Error(`Legacy entity id ${legacyId} changed canonical target during migration.`);
-      }
-      continue;
+    const now = /* @__PURE__ */ new Date();
+    const scored = entities.map((e) => ({
+      name: e.name,
+      type: e.type,
+      score: this.deps.storageManagerClass.scoreEntity(e, now),
+      factCount: e.facts.length,
+      summary: e.synthesis ?? e.summary,
+      topRelationships: e.relationships.slice(0, 3).map((r) => r.target)
+    }));
+    scored.sort((a, b) => b.score - a.score);
+    const maxEntities = typeof overrides?.maxEntities === "number" ? Math.max(0, Math.floor(overrides.maxEntities)) : config.knowledgeIndexMaxEntities;
+    const topN = scored.slice(0, maxEntities);
+    if (topN.length === 0) {
+      if (useDefaultLimits) this.deps.knowledgeIndexCache = { result: "", builtAt: Date.now() };
+      return { result: "", cached: false };
     }
-    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}.`
-      );
+    const header = "## Knowledge Index\n\n| Entity | Type | Summary | Connected to |\n|--------|------|---------|-------------|";
+    const rows = [];
+    let totalChars = header.length;
+    const maxChars = typeof overrides?.maxChars === "number" ? Math.max(0, Math.floor(overrides.maxChars)) : config.knowledgeIndexMaxChars;
+    for (const entity of topN) {
+      const summary = entity.summary || `${entity.factCount} facts`;
+      const connected = entity.topRelationships.length > 0 ? entity.topRelationships.join(", ") : "\u2014";
+      const row = `| ${entity.name} | ${entity.type} | ${summary} | ${connected} |`;
+      if (totalChars + row.length + 1 > maxChars) break;
+      rows.push(row);
+      totalChars += row.length + 1;
     }
-    merged[legacyId] = canonicalId;
-    canonicalOwners.set(canonicalId, legacyId);
+    const result = rows.length === 0 ? "" : `${header}
+${rows.join("\n")}
+`;
+    if (useDefaultLimits) this.deps.knowledgeIndexCache = { result, builtAt: Date.now() };
+    return { result, cached: false };
   }
-  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;
+  /**
+   * Merge fragmented entity files that resolve to the same canonical name.
+   * Preserves relationships, activity, aliases, and summary from all fragments.
+   * Returns count of files merged.
+   */
+  async mergeFragmentedEntities() {
+    return withEntityCanonicalMutationLock(
+      path3.join(this.deps.baseDir, "state"),
+      () => this.mergeFragmentedEntitiesUnlocked()
+    );
   }
-  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) {
-        return { deferred: false, progressed: false, blocked: true };
+  async mergeFragmentedEntitiesUnlocked() {
+    let merged = 0;
+    try {
+      const entries = await readdir2(this.deps.entitiesDir);
+      const mdFiles = entries.filter((e) => e.endsWith(".md"));
+      const groups = /* @__PURE__ */ new Map();
+      for (const file of mdFiles) {
+        const baseName = file.replace(".md", "");
+        const dashIdx = baseName.indexOf("-");
+        if (dashIdx === -1) continue;
+        const type = baseName.slice(0, dashIdx);
+        const restOfName = baseName.slice(dashIdx + 1);
+        const canonical = this.deps.normalizeEntityName(restOfName, type);
+        if (!groups.has(canonical)) groups.set(canonical, []);
+        groups.get(canonical).push(file);
       }
-      if (legacyEncrypted && !canonicalEncrypted) {
-        if (!await refreshMigrationLock() || !await refreshEntityLock()) {
-          throw new Error("Lost entity canonical-id migration lock.");
+      for (const [canonical, files] of groups) {
+        if (files.length <= 1) continue;
+        const mergedEntity = {
+          name: "",
+          type: "other",
+          created: "",
+          updated: "",
+          extraFrontmatterLines: [],
+          preSectionLines: [],
+          facts: [],
+          summary: void 0,
+          synthesis: void 0,
+          synthesisUpdatedAt: void 0,
+          synthesisTimelineCount: void 0,
+          synthesisStructuredFactCount: void 0,
+          synthesisStructuredFactDigest: void 0,
+          synthesisVersion: void 0,
+          timeline: [],
+          relationships: [],
+          activity: [],
+          aliases: [],
+          structuredSections: [],
+          extraSections: []
+        };
+        for (const file of files) {
+          const filePath = path3.join(this.deps.entitiesDir, file);
+          try {
+            const content = await this.deps.readStorageSecureFile(filePath);
+            const parsed = parseEntityFile(content, this.deps.entitySchemas);
+            if (!mergedEntity.type || mergedEntity.type === "other") {
+              mergedEntity.type = parsed.type;
+            }
+            if (!mergedEntity.updated || compareEntityTimestamps(parsed.updated, mergedEntity.updated) > 0) {
+              mergedEntity.updated = parsed.updated;
+            }
+            const parsedCreated = parsed.created || parsed.updated;
+            const mergedCreated = mergedEntity.created?.trim() || "";
+            const parsedCreatedMs = parsedCreated ? Date.parse(parsedCreated) : Number.NaN;
+            const mergedCreatedMs = mergedCreated ? Date.parse(mergedCreated) : Number.NaN;
+            const parsedCreatedIsValid = Number.isFinite(parsedCreatedMs);
+            const mergedCreatedIsValid = Number.isFinite(mergedCreatedMs);
+            if (parsedCreated && (!mergedCreated || parsedCreatedIsValid && !mergedCreatedIsValid || parsedCreatedIsValid && mergedCreatedIsValid && parsedCreatedMs < mergedCreatedMs || !parsedCreatedIsValid && !mergedCreatedIsValid && compareEntityTimestamps(parsedCreated, mergedCreated) < 0)) {
+              mergedEntity.created = parsedCreated;
+            }
+            if (parsed.name.length > mergedEntity.name.length) {
+              mergedEntity.name = parsed.name;
+            }
+            const parsedSynthesisUpdatedAt = parsed.synthesisUpdatedAt?.trim() || void 0;
+            const mergedSynthesisUpdatedAt = mergedEntity.synthesisUpdatedAt?.trim() || void 0;
+            if (parsed.synthesis && (!mergedEntity.synthesis || !mergedSynthesisUpdatedAt && Boolean(parsedSynthesisUpdatedAt) || Boolean(mergedSynthesisUpdatedAt) && Boolean(parsedSynthesisUpdatedAt) && compareEntityTimestamps(parsedSynthesisUpdatedAt, mergedSynthesisUpdatedAt) > 0)) {
+              mergedEntity.synthesis = parsed.synthesis;
+              mergedEntity.summary = parsed.synthesis;
+              mergedEntity.synthesisUpdatedAt = parsedSynthesisUpdatedAt;
+              mergedEntity.synthesisTimelineCount = parsed.synthesisTimelineCount;
+              mergedEntity.synthesisStructuredFactCount = parsed.synthesisStructuredFactCount;
+              mergedEntity.synthesisStructuredFactDigest = parsed.synthesisStructuredFactDigest;
+              mergedEntity.synthesisVersion = parsed.synthesisVersion;
+            } else if (!mergedEntity.summary && parsed.summary) {
+              mergedEntity.summary = parsed.summary;
+              mergedEntity.synthesis = parsed.summary;
+              mergedEntity.synthesisUpdatedAt = parsedSynthesisUpdatedAt;
+              mergedEntity.synthesisTimelineCount = parsed.synthesisTimelineCount;
+              mergedEntity.synthesisStructuredFactCount = parsed.synthesisStructuredFactCount;
+              mergedEntity.synthesisStructuredFactDigest = parsed.synthesisStructuredFactDigest;
+              mergedEntity.synthesisVersion = parsed.synthesisVersion;
+            }
+            mergedEntity.timeline.push(...parsed.timeline);
+            mergedEntity.relationships.push(...parsed.relationships);
+            mergedEntity.activity.push(...parsed.activity);
+            mergedEntity.aliases.push(...parsed.aliases);
+            const mergedStructuredSectionMap = new Map(
+              (mergedEntity.structuredSections ?? []).map((section) => [section.key, {
+                ...section,
+                facts: [...section.facts]
+              }])
+            );
+            for (const section of parsed.structuredSections ?? []) {
+              const existingSection = mergedStructuredSectionMap.get(section.key);
+              if (!existingSection) {
+                mergedStructuredSectionMap.set(section.key, {
+                  key: section.key,
+                  title: section.title,
+                  facts: [...new Set(section.facts.map((fact) => fact.trim()).filter((fact) => fact.length > 0))]
+                });
+                continue;
+              }
+              const mergedFacts = new Set(existingSection.facts.map((fact) => fact.trim()));
+              for (const fact of section.facts) {
+                const trimmed = fact.trim();
+                if (!trimmed) continue;
+                mergedFacts.add(trimmed);
+              }
+              existingSection.facts = Array.from(mergedFacts);
+              if (!existingSection.title.trim() && section.title.trim()) {
+                existingSection.title = section.title;
+              }
+            }
+            mergedEntity.structuredSections = Array.from(mergedStructuredSectionMap.values());
+            mergedEntity.extraFrontmatterLines.push(...parsed.extraFrontmatterLines ?? []);
+            mergedEntity.preSectionLines.push(...parsed.preSectionLines ?? []);
+            mergedEntity.extraSections.push(...(parsed.extraSections ?? []).map((section) => ({
+              title: section.title,
+              lines: [...section.lines]
+            })));
+          } catch (err) {
+            if (err instanceof SecureStoreLockedError) throw err;
+            if (!isErrnoCode(err, "ENOENT")) throw err;
+          }
         }
-        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}.`);
+        const timelineKeys = /* @__PURE__ */ new Set();
+        mergedEntity.timeline = mergedEntity.timeline.filter((entry) => {
+          const key = JSON.stringify([
+            entry.timestamp,
+            entry.source ?? "",
+            entry.sessionKey ?? "",
+            entry.principal ?? "",
+            entry.text
+          ]);
+          if (timelineKeys.has(key)) return false;
+          timelineKeys.add(key);
+          return true;
+        });
+        const relKeys = /* @__PURE__ */ new Set();
+        mergedEntity.relationships = mergedEntity.relationships.filter((r) => {
+          const key = `${r.target}::${r.label}`;
+          if (relKeys.has(key)) return false;
+          relKeys.add(key);
+          return true;
+        });
+        const actKeys = /* @__PURE__ */ new Set();
+        mergedEntity.activity = mergedEntity.activity.filter((a) => {
+          const key = `${a.date}::${a.note}`;
+          if (actKeys.has(key)) return false;
+          actKeys.add(key);
+          return true;
+        }).sort((a, b) => b.date.localeCompare(a.date));
+        mergedEntity.aliases = [...new Set(mergedEntity.aliases)];
+        mergedEntity.structuredSections = sortStructuredSectionsBySchema(
+          mergedEntity.type,
+          mergedEntity.structuredSections ?? [],
+          this.deps.entitySchemas
+        );
+        mergedEntity.facts = compileEntityFacts(mergedEntity.timeline, mergedEntity.structuredSections);
+        const extraSectionKeys = /* @__PURE__ */ new Set();
+        mergedEntity.extraSections = (mergedEntity.extraSections ?? []).filter((section) => {
+          const key = `${section.title}::${section.lines.join("\n")}`;
+          if (extraSectionKeys.has(key)) return false;
+          extraSectionKeys.add(key);
+          return true;
+        });
+        if (!mergedEntity.name) {
+          const dashIdx = canonical.indexOf("-");
+          mergedEntity.name = dashIdx !== -1 ? canonical.slice(dashIdx + 1) : canonical;
         }
-      }
-      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);
+        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`);
+        await this.deps.writeStorageSecureFile(canonicalPath, serializeEntityFile(mergedEntity, this.deps.entitySchemas));
+        this.deps.bumpEntityMutationVersion();
+        for (const file of files) {
+          const filePath = path3.join(this.deps.entitiesDir, file);
+          if (filePath !== canonicalPath) {
+            try {
+              await unlink(filePath);
+              merged++;
+              log.debug(`merged entity ${file} \u2192 ${canonical}.md`);
+            } catch {
+            }
           }
-        } 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 blocked = /* @__PURE__ */ new Map();
-      const finish = () => {
-        if (blocked.size > 0) {
-          const pairs = [...blocked].map(([legacyId, canonicalId]) => `${legacyId} -> ${canonicalId}`).join(", ");
-          log.warn(
-            `entity canonical-id migration skipped ${blocked.size} unresolvable pair(s): ${pairs}. Both files were kept and the legacy id still resolves; merge or delete one side to migrate it.`
-          );
-        }
-        return deps.readMigrationFingerprint?.();
-      };
-      const pruneBlocked = async () => {
-        const current = state;
-        if (!current) return false;
-        let revived = false;
-        const parked = { ...current.blocked ?? {} };
-        const active = {};
-        for (const [legacyId, canonicalId] of Object.entries(current.mappings)) {
-          if (!blocked.has(legacyId)) active[legacyId] = canonicalId;
-        }
-        for (const [legacyId, canonicalId] of blocked) parked[legacyId] = canonicalId;
-        for (const [legacyId, canonicalId] of Object.entries(parked)) {
-          if (blocked.has(legacyId)) continue;
-          delete parked[legacyId];
-          if (active[legacyId] !== void 0) continue;
-          const legacyPath = deps.resolveEntityFilePath(legacyId);
-          if (legacyPath !== null && await fileExists(legacyPath)) continue;
-          active[legacyId] = canonicalId;
-          revived = true;
-        }
-        const collapsed = collapseMappings(active);
-        for (const [legacyId, canonicalId] of Object.entries(parked)) {
-          const moved = collapsed[canonicalId];
-          if (moved !== void 0 && moved !== legacyId) parked[legacyId] = moved;
-        }
-        const same = (a, b) => Object.keys(a).length === Object.keys(b).length && Object.entries(a).every(([key, value]) => b[key] === value);
-        if (same(collapsed, current.mappings) && same(parked, current.blocked ?? {})) return revived;
-        state = { ...current, mappings: collapsed, blocked: parked };
-        await writeState(deps, state);
-        return revived;
-      };
-      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, blocked)
-        );
-        await pruneBlocked();
-        const mergedBefore = collapseMappings(mergeDiscoveredMappings(state.mappings, discoveredBefore));
-        if (state.complete && Object.keys(discoveredBefore).length === 0 && !mappingsChanged) {
-          if (Object.keys(state.mappings).length === 0) return finish();
-          const rewroteColdMemory2 = await rewriteKnownReferences(
-            deps,
-            state.mappings,
-            () => lock.refresh()
-          );
-          deps.invalidateKnowledgeIndexCache();
-          deps.invalidateAllMemoriesCache();
-          if (rewroteColdMemory2) deps.invalidateColdMemoriesCache();
-          deps.bumpMemoryStatusVersion();
-          return finish();
-        }
-        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, blocked)
-          );
-          const revivedInRescan = await pruneBlocked();
-          if (Object.keys(discoveredAfter2).length === 0 && !revivedInRescan) {
-            await writeState(deps, { ...state, complete: true });
-            return finish();
-          }
-          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.blocked) blocked.set(legacyId, canonicalId);
-            else 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;
-        }
-        await pruneBlocked();
-        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, blocked)
-        );
-        const revivedAfterRewrite = await pruneBlocked();
-        if (Object.keys(discoveredAfter).length === 0 && !revivedAfterRewrite) {
-          await writeState(deps, { ...state, complete: true });
-          return finish();
-        }
-        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.");
+    } catch (err) {
+      if (err instanceof SecureStoreLockedError || !isErrnoCode(err, "ENOENT")) throw err;
     }
-  );
-}
+    return merged;
+  }
+};
 
-// src/storage/entity-store.ts
-var EntityStore = class {
+// src/storage/identity-continuity-store.ts
+import { readdir as readdir3 } from "fs/promises";
+import path4 from "path";
+var IdentityContinuityStore = class {
   constructor(deps) {
     this.deps = deps;
   }
   deps;
-  /** Normalize an entity name using this store's alias table. */
-  normalizeEntityName(raw, type) {
-    return normalizeEntityName(raw, type, this.deps.userAliases);
-  }
-  async writeEntity(name, type, facts, options = {}) {
+  async writeIdentityAnchor(content) {
     await this.deps.ensureDirectories();
-    return withEntityCanonicalMutationLock(
-      path4.join(this.deps.baseDir, "state"),
-      () => this.writeEntityUnlocked(name, type, facts, options)
-    );
+    await this.deps.writeStorageSecureFile(this.deps.identityAnchorPath, content);
   }
-  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,
-        typeType: typeof type
-      });
-      return "";
-    }
-    const safeFacts = Array.isArray(facts) ? [...new Set(
-      facts.filter((fact) => typeof fact === "string").map((fact) => fact.trim()).filter((fact) => fact.length > 0)
-    )] : [];
-    let normalized = this.deps.normalizeEntityName(name, type);
-    const match = await this.deps.findMatchingEntity(name, type);
-    if (match && match !== normalized) {
-      log.debug(`fuzzy match: "${normalized}" \u2192 existing "${match}"`);
-      normalized = match;
+  async readIdentityAnchor() {
+    try {
+      return await this.deps.readStorageSecureFile(this.deps.identityAnchorPath);
+    } catch (err) {
+      if (!isErrnoCode(err, "ENOENT")) throw err;
+      return null;
     }
-    const filePath = path4.join(this.deps.entitiesDir, `${normalized}.md`);
-    let entity = {
-      name,
-      type,
-      created: "",
-      updated: (/* @__PURE__ */ new Date()).toISOString(),
-      facts: [],
-      summary: void 0,
-      synthesis: void 0,
-      synthesisUpdatedAt: void 0,
-      synthesisVersion: void 0,
-      synthesisStructuredFactCount: void 0,
-      synthesisStructuredFactDigest: void 0,
-      timeline: [],
-      relationships: [],
-      activity: [],
-      aliases: []
-    };
+  }
+  async appendContinuityIncident(input) {
+    await this.deps.ensureDirectories();
+    const now = /* @__PURE__ */ new Date();
+    const nowIso = now.toISOString();
+    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`);
+    await this.deps.writeStorageSecureFile(filePath, serializeContinuityIncident(incident));
+    return { ...incident, filePath };
+  }
+  async readContinuityIncidents(limit = 200, state = "all") {
+    const normalizedLimit = Number.isFinite(limit) ? Math.floor(limit) : 0;
+    const cappedLimit = Math.max(0, normalizedLimit);
+    if (cappedLimit === 0) return [];
     try {
-      const existing = await this.deps.readStorageSecureFile(filePath);
-      entity = parseEntityFile(existing, this.deps.entitySchemas);
+      const candidates = await this.readContinuityIncidentFileNames();
+      const incidents = [];
+      for (const file of candidates) {
+        if (incidents.length >= cappedLimit) break;
+        const filePath = path4.join(this.deps.identityIncidentsDir, file);
+        try {
+          const raw = await this.deps.readStorageSecureFile(filePath);
+          const parsed = parseContinuityIncident(raw);
+          if (!parsed) continue;
+          if (state !== "all" && parsed.state !== state) continue;
+          incidents.push({ ...parsed, filePath });
+        } catch (err) {
+          if (err instanceof SecureStoreLockedError) throw err;
+        }
+      }
+      return incidents;
     } catch (err) {
       if (err instanceof SecureStoreLockedError) throw err;
       if (!isErrnoCode(err, "ENOENT")) throw err;
+      return [];
     }
-    const timestamp = options.timestamp?.trim() || (/* @__PURE__ */ new Date()).toISOString();
-    const source = options.source?.trim() || void 0;
-    const sessionKey = options.sessionKey?.trim() || void 0;
-    const principal = options.principal?.trim() || void 0;
-    const structuredSectionMap = new Map(
-      (entity.structuredSections ?? []).map((section) => [section.key, {
-        ...section,
-        facts: [...section.facts]
-      }])
-    );
-    for (const section of options.structuredSections ?? []) {
-      const normalizedSection = normalizeEntityStructuredSection(type, section, this.deps.entitySchemas);
-      const normalizedFacts = normalizeStructuredSectionFacts(section.facts);
-      if (normalizedFacts.length === 0) continue;
-      const existingSection = structuredSectionMap.get(normalizedSection.key);
-      if (!existingSection) {
-        structuredSectionMap.set(normalizedSection.key, {
-          key: normalizedSection.key,
-          title: normalizedSection.title,
-          facts: normalizedFacts
-        });
-        continue;
-      }
-      existingSection.facts = normalizeStructuredSectionFacts([...existingSection.facts, ...normalizedFacts]);
-      if (!existingSection.title.trim() && normalizedSection.title.trim()) {
-        existingSection.title = normalizedSection.title;
-      }
-    }
-    for (const fact of safeFacts) {
-      const nextEntry = {
-        timestamp,
-        text: fact,
-        ...source ? { source } : {},
-        ...sessionKey ? { sessionKey } : {},
-        ...principal ? { principal } : {}
-      };
-      const alreadyPresent = entity.timeline.some(
-        (entry) => entry.timestamp === nextEntry.timestamp && entry.text === nextEntry.text && entry.source === nextEntry.source && entry.sessionKey === nextEntry.sessionKey && entry.principal === nextEntry.principal
-      );
-      if (alreadyPresent) continue;
-      entity.timeline.push(nextEntry);
-    }
-    entity.structuredSections = sortStructuredSectionsBySchema(
-      type,
-      Array.from(structuredSectionMap.values()).filter((section) => section.facts.length > 0),
-      this.deps.entitySchemas
-    );
-    entity.facts = compileEntityFacts(entity.timeline, entity.structuredSections);
-    entity.summary = entity.synthesis || entity.summary;
-    entity.name = name;
-    entity.type = type;
-    entity.created = entity.created || timestamp;
-    entity.updated = (/* @__PURE__ */ new Date()).toISOString();
-    await this.deps.snapshotBeforeWrite(filePath, "write");
-    await this.deps.writeStorageSecureFile(filePath, serializeEntityFile(entity, this.deps.entitySchemas));
-    this.deps.invalidateKnowledgeIndexCache();
-    this.deps.bumpMemoryStatusVersion();
-    log.debug(`wrote entity ${normalized}`);
-    return normalized;
   }
-  async readEntity(name) {
-    const filePath = this.deps.resolveEntityFilePath(name);
-    if (filePath === null) {
-      return "";
-    }
+  async closeContinuityIncident(id, closure) {
+    const directFilePath = await this.findContinuityIncidentFilePathById(id);
+    const target = directFilePath ? await this.readContinuityIncidentFile(directFilePath) : null;
+    if (!target || !directFilePath) return null;
+    if (target.state === "closed") return target;
+    const closed = closeContinuityIncidentRecord(target, closure, (/* @__PURE__ */ new Date()).toISOString());
+    await this.deps.writeStorageSecureFile(directFilePath, serializeContinuityIncident(closed));
+    return { ...closed, filePath: directFilePath };
+  }
+  async writeIdentityAudit(period, key, content) {
+    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`);
+    await this.deps.writeStorageSecureFile(filePath, content);
+    return filePath;
+  }
+  async readIdentityAudit(period, key) {
     try {
-      return await this.deps.readStorageSecureFile(filePath);
+      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`));
     } catch (err) {
-      if (err instanceof SecureStoreLockedError) throw err;
+      if (err instanceof Error && err.message === "Invalid identity audit key") return null;
       if (!isErrnoCode(err, "ENOENT")) throw err;
-      return "";
-    }
-  }
-  /** Return sorted list of entity filenames (without .md extension) */
-  async listEntityNames() {
-    try {
-      const entries = await readdir3(this.deps.entitiesDir);
-      return entries.filter((e) => e.endsWith(".md")).map((e) => e.replace(".md", "")).sort();
-    } catch {
-      return [];
+      return null;
     }
   }
-  /**
-   * Set or rewrite the synthesis layer of an entity file.
-   */
-  async updateEntitySynthesis(name, synthesis, options = {}) {
-    return withEntityCanonicalMutationLock(
-      path4.join(this.deps.baseDir, "state"),
-      () => this.updateEntitySynthesisUnlocked(name, synthesis, options)
-    );
+  async writeIdentityImprovementLoops(content) {
+    await this.deps.ensureDirectories();
+    await this.deps.writeStorageSecureFile(this.deps.identityImprovementLoopsPath, content);
   }
-  async updateEntitySynthesisUnlocked(name, synthesis, options = {}) {
-    const filePath = path4.join(this.deps.entitiesDir, `${name}.md`);
-    let entity;
+  async readIdentityImprovementLoops() {
     try {
-      const content = await this.deps.readStorageSecureFile(filePath);
-      entity = parseEntityFile(content, this.deps.entitySchemas);
+      return await this.deps.readStorageSecureFile(this.deps.identityImprovementLoopsPath);
     } catch (err) {
-      if (err instanceof SecureStoreLockedError) throw err;
       if (!isErrnoCode(err, "ENOENT")) throw err;
-      log.debug(`updateEntitySynthesis: entity file ${name}.md not found`);
-      return;
+      return null;
     }
-    const updatedAt = options.updatedAt?.trim() || entity.synthesisUpdatedAt?.trim() || void 0;
-    const entityUpdatedAt = options.entityUpdatedAt?.trim() || updatedAt || entity.updated || (/* @__PURE__ */ new Date()).toISOString();
-    const synthesisTimelineCount = Number.isInteger(options.synthesisTimelineCount) && (options.synthesisTimelineCount ?? 0) >= 0 ? options.synthesisTimelineCount : void 0;
-    const synthesisStructuredFactCount = Number.isInteger(options.synthesisStructuredFactCount) && (options.synthesisStructuredFactCount ?? 0) >= 0 ? options.synthesisStructuredFactCount : countEntityStructuredFacts(entity);
-    const synthesisStructuredFactDigest = options.synthesisStructuredFactDigest?.trim() || fingerprintEntityStructuredFacts(entity);
-    entity.synthesis = synthesis.trim();
-    entity.summary = entity.synthesis;
-    entity.synthesisUpdatedAt = updatedAt;
-    entity.synthesisTimelineCount = synthesisTimelineCount;
-    entity.synthesisStructuredFactCount = synthesisStructuredFactCount;
-    entity.synthesisStructuredFactDigest = synthesisStructuredFactDigest;
-    entity.synthesisVersion = Math.max(0, entity.synthesisVersion ?? 0) + (options.incrementVersion === false ? 0 : 1);
-    entity.updated = entityUpdatedAt;
-    await this.deps.writeStorageSecureFile(filePath, serializeEntityFile(entity, this.deps.entitySchemas));
-    await this.deps.removeEntitySynthesisQueueEntries([
-      .../* @__PURE__ */ new Set([name, this.deps.normalizeEntityName(entity.name, entity.type)])
-    ]);
-    this.deps.invalidateKnowledgeIndexCache();
-    this.deps.bumpMemoryStatusVersion();
   }
-  /**
-   * Read all entity files and return lightweight EntityFile objects.
-   * Parsing is fast (~50-100ms for ~1,800 files) since entity files are small.
-   */
-  async readAllEntityFiles() {
-    const currentVersion = this.deps.getMemoryStatusVersion();
-    const schemaCacheKey = buildEntitySchemaCacheKey(this.deps.entitySchemas);
-    const cacheKey = `${this.deps.getEntityCacheSecureStoreKey()}\0${schemaCacheKey}`;
-    const cached = getCachedEntities(this.deps.baseDir, currentVersion, cacheKey);
-    if (cached) return cached;
+  async readIdentityImprovementLoopRegister() {
+    const raw = await this.readIdentityImprovementLoops();
+    if (!raw) return [];
+    return parseContinuityImprovementLoops(raw);
+  }
+  async upsertIdentityImprovementLoop(input) {
+    const nowIso = (/* @__PURE__ */ new Date()).toISOString();
+    const raw = await this.readIdentityImprovementLoops();
+    const { markdown, loop } = upsertContinuityLoopInMarkdown(raw, input, nowIso);
+    await this.writeIdentityImprovementLoops(markdown);
+    return loop;
+  }
+  async reviewIdentityImprovementLoop(id, input) {
+    const raw = await this.readIdentityImprovementLoops();
+    const { markdown, loop } = reviewContinuityLoopInMarkdown(raw, id, input, (/* @__PURE__ */ new Date()).toISOString());
+    if (!loop) return null;
+    await this.writeIdentityImprovementLoops(markdown);
+    return loop;
+  }
+  async readContinuityIncidentFileNames() {
+    const files = await readdir3(this.deps.identityIncidentsDir);
+    return files.filter((file) => file.endsWith(".md")).sort().reverse();
+  }
+  async readContinuityIncidentFile(filePath) {
     try {
-      const entries = await readdir3(this.deps.entitiesDir);
-      const mdFiles = entries.filter((e) => e.endsWith(".md"));
-      if (mdFiles.length === 0) return [];
-      const BATCH_SIZE = 100;
-      const entities = [];
-      for (let i = 0; i < mdFiles.length; i += BATCH_SIZE) {
-        const batch = mdFiles.slice(i, i + BATCH_SIZE);
-        const results = await Promise.all(
-          batch.map(async (entry) => {
-            try {
-              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;
-              return null;
-            }
-          })
-        );
-        for (const content of results) {
-          if (content !== null) entities.push(parseEntityFile(content, this.deps.entitySchemas));
-        }
-      }
-      setCachedEntities(this.deps.baseDir, entities, currentVersion, cacheKey);
-      return entities;
+      const raw = await this.deps.readStorageSecureFile(filePath);
+      const parsed = parseContinuityIncident(raw);
+      return parsed ? { ...parsed, filePath } : null;
     } catch (err) {
-      if (err instanceof SecureStoreLockedError || !isErrnoCode(err, "ENOENT")) throw err;
-      return [];
+      if (err instanceof SecureStoreLockedError) throw err;
+      return null;
     }
   }
-  /**
-   * Build the Knowledge Index: a compact markdown table of top-scored entities.
-   * Respects maxEntities and maxChars limits from config.
-   */
-  async buildKnowledgeIndex(config, overrides) {
-    const useDefaultLimits = overrides?.maxEntities === void 0 && overrides?.maxChars === void 0;
-    if (useDefaultLimits && this.deps.knowledgeIndexCache && Date.now() - this.deps.knowledgeIndexCache.builtAt < this.deps.storageManagerClass.KNOWLEDGE_INDEX_CACHE_TTL_MS) {
-      return { result: this.deps.knowledgeIndexCache.result, cached: true };
-    }
-    const entities = await this.deps.readAllEntityFiles();
-    if (entities.length === 0) {
-      if (useDefaultLimits) this.deps.knowledgeIndexCache = { result: "", builtAt: Date.now() };
-      return { result: "", cached: false };
-    }
-    const now = /* @__PURE__ */ new Date();
-    const scored = entities.map((e) => ({
-      name: e.name,
-      type: e.type,
-      score: this.deps.storageManagerClass.scoreEntity(e, now),
-      factCount: e.facts.length,
-      summary: e.synthesis ?? e.summary,
-      topRelationships: e.relationships.slice(0, 3).map((r) => r.target)
-    }));
-    scored.sort((a, b) => b.score - a.score);
-    const maxEntities = typeof overrides?.maxEntities === "number" ? Math.max(0, Math.floor(overrides.maxEntities)) : config.knowledgeIndexMaxEntities;
-    const topN = scored.slice(0, maxEntities);
-    if (topN.length === 0) {
-      if (useDefaultLimits) this.deps.knowledgeIndexCache = { result: "", builtAt: Date.now() };
-      return { result: "", cached: false };
+  async findContinuityIncidentFilePathById(id) {
+    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 parsed = await this.readContinuityIncidentFile(directPath);
+      if (parsed?.id === id) return directPath;
     }
-    const header = "## Knowledge Index\n\n| Entity | Type | Summary | Connected to |\n|--------|------|---------|-------------|";
-    const rows = [];
-    let totalChars = header.length;
-    const maxChars = typeof overrides?.maxChars === "number" ? Math.max(0, Math.floor(overrides.maxChars)) : config.knowledgeIndexMaxChars;
-    for (const entity of topN) {
-      const summary = entity.summary || `${entity.factCount} facts`;
-      const connected = entity.topRelationships.length > 0 ? entity.topRelationships.join(", ") : "\u2014";
-      const row = `| ${entity.name} | ${entity.type} | ${summary} | ${connected} |`;
-      if (totalChars + row.length + 1 > maxChars) break;
-      rows.push(row);
-      totalChars += row.length + 1;
+    for (const fileName of fileNames) {
+      const filePath = path4.join(this.deps.identityIncidentsDir, fileName);
+      const parsed = await this.readContinuityIncidentFile(filePath);
+      if (parsed?.id === id) return filePath;
     }
-    const result = rows.length === 0 ? "" : `${header}
-${rows.join("\n")}
-`;
-    if (useDefaultLimits) this.deps.knowledgeIndexCache = { result, builtAt: Date.now() };
-    return { result, cached: false };
+    return null;
   }
-  /**
-   * Merge fragmented entity files that resolve to the same canonical name.
-   * Preserves relationships, activity, aliases, and summary from all fragments.
-   * Returns count of files merged.
-   */
-  async mergeFragmentedEntities() {
-    return withEntityCanonicalMutationLock(
-      path4.join(this.deps.baseDir, "state"),
-      () => this.mergeFragmentedEntitiesUnlocked()
-    );
+  sanitizeIdentityAuditKey(key) {
+    const trimmed = key.trim();
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(trimmed) || trimmed.includes("..")) {
+      throw new Error("Invalid identity audit key");
+    }
+    return trimmed;
   }
-  async mergeFragmentedEntitiesUnlocked() {
-    let merged = 0;
-    try {
-      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) {
-        const baseName = file.replace(".md", "");
-        const dashIdx = baseName.indexOf("-");
-        if (dashIdx === -1) continue;
-        const type = baseName.slice(0, dashIdx);
-        const restOfName = baseName.slice(dashIdx + 1);
-        const canonical = this.deps.normalizeEntityName(restOfName, type);
-        if (!groups.has(canonical)) groups.set(canonical, []);
-        groups.get(canonical).push(file);
+};
+
+// src/storage/entity-canonical-id-migration.ts
+import { randomUUID } from "crypto";
+import {
+  access,
+  lstat as lstat2,
+  readFile,
+  readdir as readdir4,
+  realpath as realpath2,
+  rename,
+  stat as statFile,
+  unlink as unlink2,
+  writeFile
+} from "fs/promises";
+import path5 from "path";
+import { z } from "zod";
+var ENTITY_CANONICAL_ID_MIGRATION_VERSION = 1;
+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 MEMORY_REWRITE_MAX_PASSES = 3;
+var ENTITY_MAPPING_RESCAN_MAX_PASSES = 3;
+var EntityCanonicalIdMigrationStateSchema = z.object({
+  version: z.literal(ENTITY_CANONICAL_ID_MIGRATION_VERSION),
+  complete: z.boolean(),
+  mappings: z.record(z.string().min(1)),
+  /**
+   * Pairs the migration refused to resolve, PARKED rather than dropped.
+   * Deleting the record would strand the collision: once an operator removes
+   * the legacy file, no later scan can rediscover the mapping, so references
+   * still naming the legacy id would never be rewritten. Optional so a journal
+   * written by an older build still parses.
+   */
+  blocked: z.record(z.string().min(1)).optional()
+});
+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, getEntityMutationVersion) {
+  const [entityFingerprint, aliasFingerprint, reconcileFingerprint, consumingFingerprint] = await Promise.all([
+    fingerprintPath(entitiesDir),
+    fingerprintPath(path5.join(baseDir, "config", "aliases.json")),
+    fingerprintPath(path5.join(baseDir, "state", ENTITY_CANONICAL_ID_RECONCILE_MARKER)),
+    // A `.consuming` generation stranded by a crashed PEER process must also
+    // re-invoke a live runner whose cached fingerprint predates it.
+    fingerprintPath(path5.join(baseDir, "state", ENTITY_CANONICAL_ID_RECONCILE_CONSUMING_MARKER))
+  ]);
+  return [entityFingerprint, aliasFingerprint, reconcileFingerprint, consumingFingerprint, getEntityMutationVersion()].join(":");
+}
+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) => path5.join(baseDir, directory)),
+    path5.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 path5.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 path5.join(deps.stateDir, "entity-canonical-id-migration.lock");
+}
+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 unlink2(temporary).catch(() => void 0);
+  }
+}
+async function publishState(deps, state) {
+  await withEntityCanonicalMutationLock(deps.stateDir, async () => {
+    await writeState(deps, state);
+  });
+}
+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 stat3;
+  try {
+    stat3 = await lstat2(filePath);
+  } catch (error) {
+    if (isErrnoCode(error, "ENOENT")) return;
+    throw error;
+  }
+  if (stat3.isSymbolicLink()) {
+    throw new Error(`Refusing entity canonical-id migration through symlink: ${label}.`);
+  }
+}
+async function assertNotMemorySymlink(filePath) {
+  let stat3;
+  try {
+    stat3 = await lstat2(filePath);
+  } catch (error) {
+    if (isErrnoCode(error, "ENOENT")) return;
+    throw error;
+  }
+  if (stat3.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 readdir4(entitiesDir);
+  for (const entry of entries) {
+    await assertNotSymlink(path5.join(entitiesDir, entry), entry);
+  }
+  return entries;
+}
+async function discoverMappings(deps, knownMappings = {}, blocked = /* @__PURE__ */ new Map()) {
+  const mappings = {};
+  const canonicalOwners = /* @__PURE__ */ new Map();
+  blocked.clear();
+  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) {
+        blocked.set(legacyId, canonicalId);
+        continue;
+      }
+    }
+    canonicalOwners.set(canonicalId, [...canonicalOwners.get(canonicalId) ?? [], legacyId]);
+    mappings[legacyId] = canonicalId;
+  }
+  for (const [canonicalId, claimants] of canonicalOwners) {
+    if (claimants.length < 2) continue;
+    for (const legacyId of claimants) {
+      blocked.set(legacyId, canonicalId);
+      delete mappings[legacyId];
+    }
+  }
+  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 = path5.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(`${path5.sep}cold${path5.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 = path5.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(
+    path5.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) {
+      let hop = canonicalId;
+      const seen = /* @__PURE__ */ new Set();
+      while (hop !== void 0 && hop !== previousMapping && !seen.has(hop)) {
+        seen.add(hop);
+        hop = merged[hop];
+      }
+      if (hop !== previousMapping) {
+        throw new Error(`Legacy entity id ${legacyId} changed canonical target during migration.`);
+      }
+      continue;
+    }
+    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) {
+        return { deferred: false, progressed: false, blocked: true };
+      }
+      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 unlink2(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 unlink2(legacyPath);
+    } catch (error) {
+      if (!canonicalExists && canonicalFingerprintAfterWrite !== null) {
+        try {
+          if (await fingerprintPath(canonicalPath) === canonicalFingerprintAfterWrite) {
+            await assertNotSymlink(canonicalPath, canonicalId);
+            await unlink2(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);
+      const reconcileMarkerPath = path5.join(deps.stateDir, ENTITY_CANONICAL_ID_RECONCILE_MARKER);
+      const consumingMarkerPath = path5.join(deps.stateDir, ENTITY_CANONICAL_ID_RECONCILE_CONSUMING_MARKER);
+      let reconcileRequested = await fileExists(consumingMarkerPath);
+      if (await fileExists(reconcileMarkerPath)) {
+        try {
+          await rename(reconcileMarkerPath, consumingMarkerPath);
+          reconcileRequested = true;
+        } catch (error) {
+          if (!isErrnoCode(error, "ENOENT")) throw error;
+        }
       }
-      for (const [canonical, files] of groups) {
-        if (files.length <= 1) continue;
-        const mergedEntity = {
-          name: "",
-          type: "other",
-          created: "",
-          updated: "",
-          extraFrontmatterLines: [],
-          preSectionLines: [],
-          facts: [],
-          summary: void 0,
-          synthesis: void 0,
-          synthesisUpdatedAt: void 0,
-          synthesisTimelineCount: void 0,
-          synthesisStructuredFactCount: void 0,
-          synthesisStructuredFactDigest: void 0,
-          synthesisVersion: void 0,
-          timeline: [],
-          relationships: [],
-          activity: [],
-          aliases: [],
-          structuredSections: [],
-          extraSections: []
+      let state = await readState(deps);
+      if (!state) {
+        state = {
+          version: ENTITY_CANONICAL_ID_MIGRATION_VERSION,
+          complete: false,
+          mappings: {}
         };
-        for (const file of files) {
-          const filePath = path4.join(this.deps.entitiesDir, file);
-          try {
-            const content = await this.deps.readStorageSecureFile(filePath);
-            const parsed = parseEntityFile(content, this.deps.entitySchemas);
-            if (!mergedEntity.type || mergedEntity.type === "other") {
-              mergedEntity.type = parsed.type;
-            }
-            if (!mergedEntity.updated || compareEntityTimestamps(parsed.updated, mergedEntity.updated) > 0) {
-              mergedEntity.updated = parsed.updated;
-            }
-            const parsedCreated = parsed.created || parsed.updated;
-            const mergedCreated = mergedEntity.created?.trim() || "";
-            const parsedCreatedMs = parsedCreated ? Date.parse(parsedCreated) : Number.NaN;
-            const mergedCreatedMs = mergedCreated ? Date.parse(mergedCreated) : Number.NaN;
-            const parsedCreatedIsValid = Number.isFinite(parsedCreatedMs);
-            const mergedCreatedIsValid = Number.isFinite(mergedCreatedMs);
-            if (parsedCreated && (!mergedCreated || parsedCreatedIsValid && !mergedCreatedIsValid || parsedCreatedIsValid && mergedCreatedIsValid && parsedCreatedMs < mergedCreatedMs || !parsedCreatedIsValid && !mergedCreatedIsValid && compareEntityTimestamps(parsedCreated, mergedCreated) < 0)) {
-              mergedEntity.created = parsedCreated;
-            }
-            if (parsed.name.length > mergedEntity.name.length) {
-              mergedEntity.name = parsed.name;
-            }
-            const parsedSynthesisUpdatedAt = parsed.synthesisUpdatedAt?.trim() || void 0;
-            const mergedSynthesisUpdatedAt = mergedEntity.synthesisUpdatedAt?.trim() || void 0;
-            if (parsed.synthesis && (!mergedEntity.synthesis || !mergedSynthesisUpdatedAt && Boolean(parsedSynthesisUpdatedAt) || Boolean(mergedSynthesisUpdatedAt) && Boolean(parsedSynthesisUpdatedAt) && compareEntityTimestamps(parsedSynthesisUpdatedAt, mergedSynthesisUpdatedAt) > 0)) {
-              mergedEntity.synthesis = parsed.synthesis;
-              mergedEntity.summary = parsed.synthesis;
-              mergedEntity.synthesisUpdatedAt = parsedSynthesisUpdatedAt;
-              mergedEntity.synthesisTimelineCount = parsed.synthesisTimelineCount;
-              mergedEntity.synthesisStructuredFactCount = parsed.synthesisStructuredFactCount;
-              mergedEntity.synthesisStructuredFactDigest = parsed.synthesisStructuredFactDigest;
-              mergedEntity.synthesisVersion = parsed.synthesisVersion;
-            } else if (!mergedEntity.summary && parsed.summary) {
-              mergedEntity.summary = parsed.summary;
-              mergedEntity.synthesis = parsed.summary;
-              mergedEntity.synthesisUpdatedAt = parsedSynthesisUpdatedAt;
-              mergedEntity.synthesisTimelineCount = parsed.synthesisTimelineCount;
-              mergedEntity.synthesisStructuredFactCount = parsed.synthesisStructuredFactCount;
-              mergedEntity.synthesisStructuredFactDigest = parsed.synthesisStructuredFactDigest;
-              mergedEntity.synthesisVersion = parsed.synthesisVersion;
-            }
-            mergedEntity.timeline.push(...parsed.timeline);
-            mergedEntity.relationships.push(...parsed.relationships);
-            mergedEntity.activity.push(...parsed.activity);
-            mergedEntity.aliases.push(...parsed.aliases);
-            const mergedStructuredSectionMap = new Map(
-              (mergedEntity.structuredSections ?? []).map((section) => [section.key, {
-                ...section,
-                facts: [...section.facts]
-              }])
+      }
+      const blocked = /* @__PURE__ */ new Map();
+      const finish = async () => {
+        if (blocked.size > 0) {
+          const pairs = [...blocked].map(([legacyId, canonicalId]) => `${legacyId} -> ${canonicalId}`).join(", ");
+          log.warn(
+            `entity canonical-id migration skipped ${blocked.size} unresolvable pair(s): ${pairs}. Both files were kept and the legacy id still resolves; merge or delete one side to migrate it.`
+          );
+        }
+        if (reconcileRequested) {
+          await unlink2(consumingMarkerPath).catch((error) => {
+            if (!isErrnoCode(error, "ENOENT")) throw error;
+          });
+        }
+        const completionFingerprint = await deps.readMigrationFingerprint?.();
+        if (await fileExists(reconcileMarkerPath)) return void 0;
+        return completionFingerprint;
+      };
+      const pruneBlocked = async () => {
+        const current = state;
+        if (!current) return false;
+        let revived = false;
+        const parked = { ...current.blocked ?? {} };
+        const active = {};
+        for (const [legacyId, canonicalId] of Object.entries(current.mappings)) {
+          if (!blocked.has(legacyId)) active[legacyId] = canonicalId;
+        }
+        for (const [legacyId, canonicalId] of blocked) parked[legacyId] = canonicalId;
+        for (const [legacyId, canonicalId] of Object.entries(parked)) {
+          if (blocked.has(legacyId)) continue;
+          delete parked[legacyId];
+          if (active[legacyId] !== void 0) continue;
+          const legacyPath = deps.resolveEntityFilePath(legacyId);
+          if (legacyPath !== null && await fileExists(legacyPath)) continue;
+          active[legacyId] = canonicalId;
+          revived = true;
+        }
+        const collapsed = collapseMappings(active);
+        for (const [legacyId, canonicalId] of Object.entries(parked)) {
+          const moved = collapsed[canonicalId];
+          if (moved !== void 0 && moved !== legacyId) parked[legacyId] = moved;
+        }
+        const same = (a, b) => Object.keys(a).length === Object.keys(b).length && Object.entries(a).every(([key, value]) => b[key] === value);
+        if (same(collapsed, current.mappings) && same(parked, current.blocked ?? {})) return revived;
+        state = { ...current, mappings: collapsed, blocked: parked };
+        await publishState(deps, state);
+        return revived;
+      };
+      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, blocked)
+        );
+        const revivedBefore = await pruneBlocked();
+        const mergedBefore = collapseMappings(mergeDiscoveredMappings(state.mappings, discoveredBefore));
+        if (state.complete && Object.keys(discoveredBefore).length === 0 && !mappingsChanged && !revivedBefore) {
+          if (reconcileRequested && Object.keys(state.mappings).length > 0) {
+            const rewroteColdMemory2 = await rewriteKnownReferences(
+              deps,
+              state.mappings,
+              () => lock.refresh()
             );
-            for (const section of parsed.structuredSections ?? []) {
-              const existingSection = mergedStructuredSectionMap.get(section.key);
-              if (!existingSection) {
-                mergedStructuredSectionMap.set(section.key, {
-                  key: section.key,
-                  title: section.title,
-                  facts: [...new Set(section.facts.map((fact) => fact.trim()).filter((fact) => fact.length > 0))]
-                });
-                continue;
-              }
-              const mergedFacts = new Set(existingSection.facts.map((fact) => fact.trim()));
-              for (const fact of section.facts) {
-                const trimmed = fact.trim();
-                if (!trimmed) continue;
-                mergedFacts.add(trimmed);
-              }
-              existingSection.facts = Array.from(mergedFacts);
-              if (!existingSection.title.trim() && section.title.trim()) {
-                existingSection.title = section.title;
-              }
-            }
-            mergedEntity.structuredSections = Array.from(mergedStructuredSectionMap.values());
-            mergedEntity.extraFrontmatterLines.push(...parsed.extraFrontmatterLines ?? []);
-            mergedEntity.preSectionLines.push(...parsed.preSectionLines ?? []);
-            mergedEntity.extraSections.push(...(parsed.extraSections ?? []).map((section) => ({
-              title: section.title,
-              lines: [...section.lines]
-            })));
-          } catch (err) {
-            if (err instanceof SecureStoreLockedError) throw err;
-            if (!isErrnoCode(err, "ENOENT")) throw err;
+            deps.invalidateKnowledgeIndexCache();
+            deps.invalidateAllMemoriesCache();
+            if (rewroteColdMemory2) deps.invalidateColdMemoriesCache();
+            deps.bumpMemoryStatusVersion();
           }
+          return finish();
         }
-        const timelineKeys = /* @__PURE__ */ new Set();
-        mergedEntity.timeline = mergedEntity.timeline.filter((entry) => {
-          const key = JSON.stringify([
-            entry.timestamp,
-            entry.source ?? "",
-            entry.sessionKey ?? "",
-            entry.principal ?? "",
-            entry.text
-          ]);
-          if (timelineKeys.has(key)) return false;
-          timelineKeys.add(key);
-          return true;
-        });
-        const relKeys = /* @__PURE__ */ new Set();
-        mergedEntity.relationships = mergedEntity.relationships.filter((r) => {
-          const key = `${r.target}::${r.label}`;
-          if (relKeys.has(key)) return false;
-          relKeys.add(key);
-          return true;
-        });
-        const actKeys = /* @__PURE__ */ new Set();
-        mergedEntity.activity = mergedEntity.activity.filter((a) => {
-          const key = `${a.date}::${a.note}`;
-          if (actKeys.has(key)) return false;
-          actKeys.add(key);
-          return true;
-        }).sort((a, b) => b.date.localeCompare(a.date));
-        mergedEntity.aliases = [...new Set(mergedEntity.aliases)];
-        mergedEntity.structuredSections = sortStructuredSectionsBySchema(
-          mergedEntity.type,
-          mergedEntity.structuredSections ?? [],
-          this.deps.entitySchemas
-        );
-        mergedEntity.facts = compileEntityFacts(mergedEntity.timeline, mergedEntity.structuredSections);
-        const extraSectionKeys = /* @__PURE__ */ new Set();
-        mergedEntity.extraSections = (mergedEntity.extraSections ?? []).filter((section) => {
-          const key = `${section.title}::${section.lines.join("\n")}`;
-          if (extraSectionKeys.has(key)) return false;
-          extraSectionKeys.add(key);
-          return true;
-        });
-        if (!mergedEntity.name) {
-          const dashIdx = canonical.indexOf("-");
-          mergedEntity.name = dashIdx !== -1 ? canonical.slice(dashIdx + 1) : canonical;
+        if (state.complete || Object.keys(discoveredBefore).length > 0 || Object.keys(mergedBefore).length !== Object.keys(state.mappings).length) {
+          state = { ...state, complete: false, mappings: mergedBefore };
+          await publishState(deps, state);
         }
-        mergedEntity.created = mergedEntity.created || mergedEntity.updated || (/* @__PURE__ */ new Date()).toISOString();
-        mergedEntity.updated = mergedEntity.updated || (/* @__PURE__ */ new Date()).toISOString();
-        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 = path4.join(this.deps.entitiesDir, file);
-          if (filePath !== canonicalPath) {
-            try {
-              await unlink2(filePath);
-              merged++;
-              log.debug(`merged entity ${file} \u2192 ${canonical}.md`);
-            } catch {
-            }
+        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, blocked)
+          );
+          const revivedInRescan = await pruneBlocked();
+          if (Object.keys(discoveredAfter2).length === 0 && !revivedInRescan) {
+            await publishState(deps, { ...state, complete: true });
+            return finish();
+          }
+          state = {
+            ...state,
+            complete: false,
+            mappings: collapseMappings(mergeDiscoveredMappings(state.mappings, discoveredAfter2))
+          };
+          await publishState(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.blocked) blocked.set(legacyId, canonicalId);
+            else 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;
+        }
+        await pruneBlocked();
+        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, blocked)
+        );
+        const revivedAfterRewrite = await pruneBlocked();
+        if (Object.keys(discoveredAfter).length === 0 && !revivedAfterRewrite) {
+          await publishState(deps, { ...state, complete: true });
+          return finish();
         }
+        state = {
+          ...state,
+          complete: false,
+          mappings: collapseMappings(mergeDiscoveredMappings(state.mappings, discoveredAfter))
+        };
+        await publishState(deps, state);
       }
-    } catch (err) {
-      if (err instanceof SecureStoreLockedError || !isErrnoCode(err, "ENOENT")) throw err;
+      throw new Error("Entity canonical-id migration mappings changed while migration was running; retry migration.");
     }
-    return merged;
-  }
-};
+  );
+}
 
-// src/storage/identity-continuity-store.ts
-import { readdir as readdir4 } from "fs/promises";
-import path5 from "path";
-var IdentityContinuityStore = class {
+// src/storage/entity-ref-repair.ts
+import { unlink as unlink3 } from "fs/promises";
+var EntityRefRepair = class {
   constructor(deps) {
     this.deps = deps;
   }
   deps;
-  async writeIdentityAnchor(content) {
-    await this.deps.ensureDirectories();
-    await this.deps.writeStorageSecureFile(this.deps.identityAnchorPath, content);
-  }
-  async readIdentityAnchor() {
+  /**
+   * Shared lookup+apply core for the write-time resurrection gate (#1579 /
+   * #2213): fail-open, add-only; writeMemory's gate + chunk-repair re-gate
+   * consult this one implementation (rule 43).
+   */
+  async gate(fm, hashSource, structuredAttributes) {
+    if (!this.deps.tombstonesEnabled()) return null;
     try {
-      return await this.deps.readStorageSecureFile(this.deps.identityAnchorPath);
+      const store = await this.deps.getTombstoneStore();
+      const supersessionKeys = fm.entityRef && structuredAttributes ? supersessionKeysForFact({ entityRef: fm.entityRef, structuredAttributes }) : [];
+      const match = applyTombstoneResurrectionGate(store, fm, {
+        normalizedText: ContentHashIndex.normalizeContent(hashSource),
+        supersessionKeys,
+        namespace: this.deps.tombstonesNamespace()
+      });
+      if (match) {
+        log.info(
+          `tombstone: blocked resurrection of fact ${fm.id} (tier=${match.matchedTier}, tombstone=${match.tombstoneId}, reason=${match.reason})`
+        );
+      }
+      return match;
     } catch (err) {
-      if (!isErrnoCode(err, "ENOENT")) throw err;
+      log.warn(`tombstone lookup failed for fact ${fm.id} (fail-open): ${err}`);
       return null;
     }
   }
-  async appendContinuityIncident(input) {
-    await this.deps.ensureDirectories();
-    const now = /* @__PURE__ */ new Date();
-    const nowIso = now.toISOString();
-    const date = nowIso.slice(0, 10);
-    const id = this.deps.generateId("incident");
-    const incident = createContinuityIncidentRecord(id, input, nowIso);
-    const filePath = path5.join(this.deps.identityIncidentsDir, `${date}-${id}.md`);
-    await this.deps.writeStorageSecureFile(filePath, serializeContinuityIncident(incident));
-    return { ...incident, filePath };
-  }
-  async readContinuityIncidents(limit = 200, state = "all") {
-    const normalizedLimit = Number.isFinite(limit) ? Math.floor(limit) : 0;
-    const cappedLimit = Math.max(0, normalizedLimit);
-    if (cappedLimit === 0) return [];
+  /** Post-persist repair delegate — see the references module for semantics. */
+  async repair(filePath, fm, rawRef, refIds, body, opts = {}) {
+    const refBeforeRepair = fm.entityRef;
     try {
-      const candidates = await this.readContinuityIncidentFileNames();
-      const incidents = [];
-      for (const file of candidates) {
-        if (incidents.length >= cappedLimit) break;
-        const filePath = path5.join(this.deps.identityIncidentsDir, file);
-        try {
-          const raw = await this.deps.readStorageSecureFile(filePath);
-          const parsed = parseContinuityIncident(raw);
-          if (!parsed) continue;
-          if (state !== "all" && parsed.state !== state) continue;
-          incidents.push({ ...parsed, filePath });
-        } catch (err) {
-          if (err instanceof SecureStoreLockedError) throw err;
+      await repairEntityRefAfterJournalMove({
+        stateDir: this.deps.stateDir,
+        currentIds: () => this.deps.currentHistoricalIds(),
+        idsAtResolve: refIds,
+        rawRef,
+        frontmatter: fm,
+        rewrite: async () => {
+          if (opts.regateFact && fm.category === "fact") {
+            await this.gate(fm, body, void 0);
+          }
+          await this.deps.writeTombstoneBlockedMemory(
+            filePath,
+            `${this.deps.serializeFrontmatter(fm)}
+
+${body}
+`,
+            fm,
+            body
+          );
+          this.deps.invalidateAllMemoriesCache();
         }
-      }
-      return incidents;
-    } catch (err) {
-      if (err instanceof SecureStoreLockedError) throw err;
-      if (!isErrnoCode(err, "ENOENT")) throw err;
-      return [];
-    }
-  }
-  async closeContinuityIncident(id, closure) {
-    const directFilePath = await this.findContinuityIncidentFilePathById(id);
-    const target = directFilePath ? await this.readContinuityIncidentFile(directFilePath) : null;
-    if (!target || !directFilePath) return null;
-    if (target.state === "closed") return target;
-    const closed = closeContinuityIncidentRecord(target, closure, (/* @__PURE__ */ new Date()).toISOString());
-    await this.deps.writeStorageSecureFile(directFilePath, serializeContinuityIncident(closed));
-    return { ...closed, filePath: directFilePath };
-  }
-  async writeIdentityAudit(period, key, content) {
-    await this.deps.ensureDirectories();
-    const safeKey = this.sanitizeIdentityAuditKey(key);
-    const dir = period === "weekly" ? this.deps.identityAuditsWeeklyDir : this.deps.identityAuditsMonthlyDir;
-    const filePath = path5.join(dir, `${safeKey}.md`);
-    await this.deps.writeStorageSecureFile(filePath, content);
-    return filePath;
-  }
-  async readIdentityAudit(period, key) {
-    try {
-      const safeKey = this.sanitizeIdentityAuditKey(key);
-      const dir = period === "weekly" ? this.deps.identityAuditsWeeklyDir : this.deps.identityAuditsMonthlyDir;
-      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;
-      return null;
+      if (opts.onFailRestore) {
+        await this.restore(opts.onFailRestore);
+      } else if (opts.onFailRemove) {
+        await unlink3(opts.onFailRemove).catch(() => void 0);
+        this.deps.invalidateAllMemoriesCache();
+      }
+      throw err;
     }
+    await this.syncProjection(fm.id, refBeforeRepair, fm.entityRef);
   }
-  async writeIdentityImprovementLoops(content) {
-    await this.deps.ensureDirectories();
-    await this.deps.writeStorageSecureFile(this.deps.identityImprovementLoopsPath, content);
-  }
-  async readIdentityImprovementLoops() {
+  /**
+   * Restore a record's pre-mutation bytes through the blocked-capture
+   * surface when a post-persist repair fails (§14).
+   */
+  async restore(before) {
     try {
-      return await this.deps.readStorageSecureFile(this.deps.identityImprovementLoopsPath);
-    } catch (err) {
-      if (!isErrnoCode(err, "ENOENT")) throw err;
-      return null;
+      await this.deps.writeTombstoneBlockedMemory(
+        before.path,
+        `${this.deps.serializeFrontmatter(before.frontmatter)}
+
+${before.content}
+`,
+        before.frontmatter,
+        before.content
+      );
+    } catch (restoreErr) {
+      log.warn(`failed to restore ${before.frontmatter.id} after repair failure: ${restoreErr}`);
     }
+    this.deps.invalidateAllMemoriesCache();
   }
-  async readIdentityImprovementLoopRegister() {
-    const raw = await this.readIdentityImprovementLoops();
-    if (!raw) return [];
-    return parseContinuityImprovementLoops(raw);
-  }
-  async upsertIdentityImprovementLoop(input) {
-    const nowIso = (/* @__PURE__ */ new Date()).toISOString();
-    const raw = await this.readIdentityImprovementLoops();
-    const { markdown, loop } = upsertContinuityLoopInMarkdown(raw, input, nowIso);
-    await this.writeIdentityImprovementLoops(markdown);
-    return loop;
-  }
-  async reviewIdentityImprovementLoop(id, input) {
-    const raw = await this.readIdentityImprovementLoops();
-    const { markdown, loop } = reviewContinuityLoopInMarkdown(raw, id, input, (/* @__PURE__ */ new Date()).toISOString());
-    if (!loop) return null;
-    await this.writeIdentityImprovementLoops(markdown);
-    return loop;
-  }
-  async readContinuityIncidentFileNames() {
-    const files = await readdir4(this.deps.identityIncidentsDir);
-    return files.filter((file) => file.endsWith(".md")).sort().reverse();
-  }
-  async readContinuityIncidentFile(filePath) {
+  /**
+   * Projection rows written under the pre-repair claimant cannot be restored
+   * once the mapping is parked (Codex P1). Fail-open: projection is rebuildable.
+   */
+  async syncProjection(memoryId, refBefore, refAfter) {
+    if (typeof refBefore !== "string" || typeof refAfter !== "string" || refBefore === refAfter) return;
     try {
-      const raw = await this.deps.readStorageSecureFile(filePath);
-      const parsed = parseContinuityIncident(raw);
-      return parsed ? { ...parsed, filePath } : null;
+      await rewriteProjectedMemoryEntityReference(this.deps.baseDir, memoryId, refBefore, refAfter);
     } catch (err) {
-      if (err instanceof SecureStoreLockedError) throw err;
-      return null;
-    }
-  }
-  async findContinuityIncidentFilePathById(id) {
-    const fileNames = await this.readContinuityIncidentFileNames();
-    const directMatch = fileNames.find((name) => name.endsWith(`-${id}.md`));
-    if (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 = path5.join(this.deps.identityIncidentsDir, fileName);
-      const parsed = await this.readContinuityIncidentFile(filePath);
-      if (parsed?.id === id) return filePath;
-    }
-    return null;
-  }
-  sanitizeIdentityAuditKey(key) {
-    const trimmed = key.trim();
-    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(trimmed) || trimmed.includes("..")) {
-      throw new Error("Invalid identity audit key");
+      log.warn(`projection entityRef sync failed for ${memoryId}: ${err}`);
     }
-    return trimmed;
   }
 };
 
 // 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 readMigrationFingerprint = () => getFingerprint(host.baseDir, host.entitiesDir, () => String(host.getEntityMutationVersion()));
   const completionFingerprint = await migrateLegacyEntityCanonicalIds({
     stateDir: host.stateDir,
     entitiesDir: host.entitiesDir,
@@ -2881,7 +3094,7 @@ async function runLegacyEntityCanonicalIdMigration(host, parseEntityFile2, seria
     bumpMemoryStatusVersion: host.bumpMemoryStatusVersion.bind(host),
     readMigrationFingerprint
   });
-  return completionFingerprint ?? readMigrationFingerprint();
+  return completionFingerprint;
 }
 
 // src/storage/entity-canonical-id-migration-runner.ts
@@ -4630,22 +4843,103 @@ var MeetingRecordStore = class {
         `meetings ${kind} '${label}' is a symbolic link \u2014 refusing to follow it even when it resolves inside the memory dir (AGENTS.md pattern #3)`
       );
     }
-  }
-  async assertNoEscape(rootReal, candidate) {
-    let candidateReal;
-    try {
-      candidateReal = await this.io.realpath(candidate);
-    } catch {
-      return;
+  }
+  async assertNoEscape(rootReal, candidate) {
+    let candidateReal;
+    try {
+      candidateReal = await this.io.realpath(candidate);
+    } catch {
+      return;
+    }
+    if (!pathIsInside(rootReal, candidateReal)) {
+      throw new Error(
+        "meeting record path resolves outside the memory dir \u2014 refusing to follow a symlink/traversal (AGENTS.md pattern #3)"
+      );
+    }
+  }
+};
+var SORT_STR = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+
+// src/storage/citation-hash-source.ts
+function trimTrailingSpacesAndTabs(value) {
+  let end = value.length;
+  while (end > 0 && (value[end - 1] === " " || value[end - 1] === "	")) {
+    end -= 1;
+  }
+  return end === value.length ? value : value.slice(0, end);
+}
+function trimLeadingSpacesAndTabs(value) {
+  let start = 0;
+  while (start < value.length && (value[start] === " " || value[start] === "	")) {
+    start += 1;
+  }
+  return start === 0 ? value : value.slice(start);
+}
+function stripDefaultCitationMarkersWithoutRegex(value) {
+  return stripCitationMarkersForHashRemoval(value, DEFAULT_CITATION_FORMAT);
+}
+function citationTemplateLiteralParts(template) {
+  const parts = [];
+  let cursor = 0;
+  while (cursor < template.length) {
+    const open2 = template.indexOf("{", cursor);
+    if (open2 === -1) {
+      parts.push(template.slice(cursor));
+      break;
+    }
+    parts.push(template.slice(cursor, open2));
+    const close = template.indexOf("}", open2 + 1);
+    if (close === -1) {
+      cursor = open2 + 1;
+    } else {
+      cursor = close + 1;
+    }
+  }
+  return parts.filter((part) => part.length > 0);
+}
+function stripCitationMarkersForHashRemoval(value, template) {
+  const parts = citationTemplateLiteralParts(template);
+  if (parts.length === 0) return value;
+  const first = parts[0];
+  const lowerValue = value.toLowerCase();
+  const lowerFirst = first.toLowerCase();
+  const lowerParts = parts.map((part) => part.toLowerCase());
+  if (!lowerValue.includes(lowerFirst)) return value;
+  let result = "";
+  let cursor = 0;
+  let removed = false;
+  while (cursor < value.length) {
+    const markerStart = lowerValue.indexOf(lowerFirst, cursor);
+    if (markerStart === -1) {
+      result += value.slice(cursor);
+      break;
+    }
+    const boundedEnd = first.startsWith("[") ? value.indexOf("]", markerStart + first.length) : -1;
+    if (first.startsWith("[") && boundedEnd === -1) {
+      result += value.slice(cursor);
+      break;
+    }
+    const searchLimit = boundedEnd === -1 ? value.length : boundedEnd + 1;
+    let markerEnd = markerStart + first.length;
+    let matched = true;
+    for (let i = 1; i < lowerParts.length; i += 1) {
+      const partIndex = lowerValue.indexOf(lowerParts[i], markerEnd);
+      if (partIndex === -1 || partIndex + parts[i].length > searchLimit) {
+        matched = false;
+        break;
+      }
+      markerEnd = partIndex + parts[i].length;
     }
-    if (!pathIsInside(rootReal, candidateReal)) {
-      throw new Error(
-        "meeting record path resolves outside the memory dir \u2014 refusing to follow a symlink/traversal (AGENTS.md pattern #3)"
-      );
+    if (!matched) {
+      result += value.slice(cursor);
+      break;
     }
+    result += trimTrailingSpacesAndTabs(value.slice(cursor, markerStart));
+    cursor = markerEnd;
+    removed = true;
   }
-};
-var SORT_STR = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+  return removed ? trimLeadingSpacesAndTabs(result) : value;
+}
 
 // src/storage/entity-timeline.ts
 import { createHash as createHash4 } from "crypto";
@@ -5097,85 +5391,6 @@ function normalizeMemoryWriteTimestamp(field, value) {
   }
   return new Date(parsed).toISOString();
 }
-function trimTrailingSpacesAndTabs(value) {
-  let end = value.length;
-  while (end > 0 && (value[end - 1] === " " || value[end - 1] === "	")) {
-    end -= 1;
-  }
-  return end === value.length ? value : value.slice(0, end);
-}
-function trimLeadingSpacesAndTabs(value) {
-  let start = 0;
-  while (start < value.length && (value[start] === " " || value[start] === "	")) {
-    start += 1;
-  }
-  return start === 0 ? value : value.slice(start);
-}
-function stripDefaultCitationMarkersWithoutRegex(value) {
-  return stripCitationMarkersForHashRemoval(value, DEFAULT_CITATION_FORMAT);
-}
-function citationTemplateLiteralParts(template) {
-  const parts = [];
-  let cursor = 0;
-  while (cursor < template.length) {
-    const open2 = template.indexOf("{", cursor);
-    if (open2 === -1) {
-      parts.push(template.slice(cursor));
-      break;
-    }
-    parts.push(template.slice(cursor, open2));
-    const close = template.indexOf("}", open2 + 1);
-    if (close === -1) {
-      cursor = open2 + 1;
-    } else {
-      cursor = close + 1;
-    }
-  }
-  return parts.filter((part) => part.length > 0);
-}
-function stripCitationMarkersForHashRemoval(value, template) {
-  const parts = citationTemplateLiteralParts(template);
-  if (parts.length === 0) return value;
-  const first = parts[0];
-  const lowerValue = value.toLowerCase();
-  const lowerFirst = first.toLowerCase();
-  const lowerParts = parts.map((part) => part.toLowerCase());
-  if (!lowerValue.includes(lowerFirst)) return value;
-  let result = "";
-  let cursor = 0;
-  let removed = false;
-  while (cursor < value.length) {
-    const markerStart = lowerValue.indexOf(lowerFirst, cursor);
-    if (markerStart === -1) {
-      result += value.slice(cursor);
-      break;
-    }
-    const boundedEnd = first.startsWith("[") ? value.indexOf("]", markerStart + first.length) : -1;
-    if (first.startsWith("[") && boundedEnd === -1) {
-      result += value.slice(cursor);
-      break;
-    }
-    const searchLimit = boundedEnd === -1 ? value.length : boundedEnd + 1;
-    let markerEnd = markerStart + first.length;
-    let matched = true;
-    for (let i = 1; i < lowerParts.length; i += 1) {
-      const partIndex = lowerValue.indexOf(lowerParts[i], markerEnd);
-      if (partIndex === -1 || partIndex + parts[i].length > searchLimit) {
-        matched = false;
-        break;
-      }
-      markerEnd = partIndex + parts[i].length;
-    }
-    if (!matched) {
-      result += value.slice(cursor);
-      break;
-    }
-    result += trimTrailingSpacesAndTabs(value.slice(cursor, markerStart));
-    cursor = markerEnd;
-    removed = true;
-  }
-  return removed ? trimLeadingSpacesAndTabs(result) : value;
-}
 function serializeFrontmatter(fm) {
   assertMemoryFrontmatterId(fm);
   const lines = [
@@ -6142,7 +6357,6 @@ var StorageManager3 = class _StorageManager extends TombstoneBlockedCaptureIndex
     this.entitySchemas = entitySchemas;
     this.hotMemoriesCacheEnabled = hotMemoriesCacheEnabledOverride ?? _StorageManager.hotMemoriesCacheDefaultByDir.get(baseDir) ?? _StorageManager.hotMemoriesCacheDefault;
     this.loadAliasesSync();
-    this.loadHistoricalEntityCanonicalIdsSync();
   }
   baseDir;
   entitySchemas;
@@ -6162,6 +6376,8 @@ var StorageManager3 = class _StorageManager extends TombstoneBlockedCaptureIndex
   // every plain create). In-process fallback when the on-disk sentinel is
   // unavailable; canonical source is state/.memory-corpus-version.log.
   static memoryCorpusVersionByDir = /* @__PURE__ */ new Map();
+  // Entity-mutation sentinel: see getEntityMutationVersion.
+  static entityMutationVersionByDir = /* @__PURE__ */ new Map();
   static secureStoreEntityCacheKeyIds = /* @__PURE__ */ new WeakMap();
   static nextSecureStoreEntityCacheKeyId = 1;
   // In-process fallback for the cold-write sentinel (used when the disk file
@@ -6613,8 +6829,7 @@ var StorageManager3 = class _StorageManager extends TombstoneBlockedCaptureIndex
     return path9.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 path9.join(this.stateDir, `.${kind}-version.log`);
   }
   bumpSharedVersion(kind, fallbackMap) {
     const filePath = this.versionFilePath(kind);
@@ -6647,13 +6862,21 @@ var StorageManager3 = class _StorageManager extends TombstoneBlockedCaptureIndex
     return this.readSharedVersion("memory-status", _StorageManager.memoryStatusVersionByDir);
   }
   /**
-   * Corpus version sentinel for the hot-memories result cache (issue #1902).
-   * Distinct from memory-status: it bumps on EVERY memory-file mutation
-   * (create/update/delete/bulk) so the version-keyed hot cache stays coherent
-   * across processes, WITHOUT bumping memory-status — which would needlessly
-   * invalidate the version-keyed entity cache on every plain fact create (the
-   * ki-spike regression the sibling perf work removes). memory-status keeps its
-   * lifecycle/status/entity semantics unchanged.
+   * Entity-mutation sentinel: advanced only by entity-store content writes.
+   * The migration fingerprint keys on this instead of memory-status, so
+   * supersede/archive/delete no longer re-trigger discovery scans (#2213).
+   */
+  getEntityMutationVersion() {
+    return this.readSharedVersion("entity-mutation", _StorageManager.entityMutationVersionByDir);
+  }
+  bumpEntityMutationVersion() {
+    this.bumpSharedVersion("entity-mutation", _StorageManager.entityMutationVersionByDir);
+  }
+  /**
+   * Corpus version sentinel for the hot-memories result cache (#1902).
+   * Distinct from memory-status: bumps on EVERY memory-file mutation so the
+   * version-keyed hot cache stays coherent across processes, WITHOUT
+   * invalidating the version-keyed entity cache on every plain fact create.
    */
   getMemoryCorpusVersion() {
     return this.readSharedVersion("memory-corpus", _StorageManager.memoryCorpusVersionByDir);
@@ -6663,12 +6886,10 @@ var StorageManager3 = class _StorageManager extends TombstoneBlockedCaptureIndex
     deleteInFlightReadsForDir(this.baseDir);
   }
   /**
-   * Corpus bump that reports whether THIS process's append was the only one
-   * since the pre-bump size (issue #1902, Codex P1). appendFileSync is atomic
-   * per write, but a peer process can append concurrently; the `exclusive`
-   * flag lets patchHotMemoriesCache refuse to re-key its locally patched
-   * (peer-incomplete) corpus at a version that already reflects a peer's
-   * still-unread write.
+   * Corpus bump reporting whether THIS process's append was the only one
+   * since the pre-bump size (#1902, Codex P1): the `exclusive` flag lets
+   * patchHotMemoriesCache refuse to re-key its locally patched corpus at a
+   * version already reflecting a peer's still-unread concurrent append.
    */
   bumpMemoryCorpusVersionExclusive() {
     const filePath = this.versionFilePath("memory-corpus");
@@ -6749,7 +6970,7 @@ var StorageManager3 = class _StorageManager extends TombstoneBlockedCaptureIndex
       writeFile: (p, c) => this.writeStorageSecureFile(p, c),
       readFile: (p) => readMaybeEncryptedFile(p, this._secureStoreKey, this.baseDir),
       readDir: (d) => readdir5(d),
-      deleteFile: (p) => unlink3(p),
+      deleteFile: (p) => unlink4(p),
       realpath: (p) => realpath3(p),
       lstat: (p) => lstat3(p).then((st) => ({ isSymbolicLink: st.isSymbolicLink() }))
     });
@@ -6767,7 +6988,7 @@ var StorageManager3 = class _StorageManager extends TombstoneBlockedCaptureIndex
       writeFile: (p, c) => this.writeStorageSecureFile(p, c),
       readFile: (p) => readMaybeEncryptedFile(p, this._secureStoreKey, this.baseDir),
       readDir: (d) => readdir5(d),
-      deleteFile: (p) => unlink3(p),
+      deleteFile: (p) => unlink4(p),
       realpath: (p) => realpath3(p),
       lstat: (p) => lstat3(p).then((st) => ({ isSymbolicLink: st.isSymbolicLink() }))
     });
@@ -7204,7 +7425,14 @@ var StorageManager3 = class _StorageManager extends TombstoneBlockedCaptureIndex
     try {
       const store = await this.getTombstoneStore();
       const strippedRawContent = stripCitationForTemplate(input.rawContent, this.citationTemplate);
-      return await store.appendTombstone({ ...input, rawContent: strippedRawContent });
+      return await appendCanonicalizedTombstone(
+        this.stateDir,
+        input,
+        () => this.currentHistoricalIds(),
+        (identity) => store.appendTombstone({ ...input, rawContent: strippedRawContent, ...identity }),
+        (tombstoneId) => store.revoke(tombstoneId, input.createdBy),
+        input.sourceMemoryId
+      );
     } catch (err) {
       log.warn(`tombstone append failed (memory=${input.sourceMemoryId}): ${err}`);
       return null;
@@ -7500,16 +7728,37 @@ var StorageManager3 = class _StorageManager extends TombstoneBlockedCaptureIndex
    * store loaded last rewrite every other store's canonical entity ids.
    */
   userAliases = {};
-  historicalEntityCanonicalIds = {};
+  historicalEntityCanonicalIds = new HistoricalEntityCanonicalIdCache();
+  currentHistoricalIds() {
+    return this.historicalEntityCanonicalIds.get(this.stateDir);
+  }
+  /** Post-persist repair subsystem (issue #2213) — storage/entity-ref-repair.ts. */
+  _entityRefRepair;
+  get entityRefRepair() {
+    if (!this._entityRefRepair) {
+      this._entityRefRepair = new EntityRefRepair({
+        stateDir: this.stateDir,
+        baseDir: this.baseDir,
+        currentHistoricalIds: () => this.currentHistoricalIds(),
+        serializeFrontmatter,
+        writeTombstoneBlockedMemory: (pathname, fileContent, frontmatter, content) => this.writeTombstoneBlockedMemory(pathname, fileContent, frontmatter, content),
+        invalidateAllMemoriesCache: () => this.invalidateAllMemoriesCache(),
+        getTombstoneStore: () => this.getTombstoneStore(),
+        tombstonesEnabled: () => this.tombstonesConfig.enabled,
+        tombstonesNamespace: () => this.tombstonesConfig.namespace
+      });
+    }
+    return this._entityRefRepair;
+  }
   entityCanonicalIdMigration = new EntityCanonicalIdMigrationRunner(
     () => !(this._secureStoreRequired && !this.isSecureStoreUnlocked()),
     () => this.runLegacyEntityCanonicalIdMigration(),
-    () => getFingerprint(this.baseDir, this.entitiesDir, () => this.getCorpusScanVersion())
+    () => getFingerprint(this.baseDir, this.entitiesDir, () => String(this.getEntityMutationVersion()))
   );
   normalizeEntityName(raw, type) {
     return resolveHistoricalEntityCanonicalId(
       this.entityStore.normalizeEntityName(raw, type),
-      this.historicalEntityCanonicalIds
+      this.currentHistoricalIds()
     );
   }
   /**
@@ -7533,7 +7782,7 @@ var StorageManager3 = class _StorageManager extends TombstoneBlockedCaptureIndex
     const aliasPath = path9.join(this.baseDir, "config", "aliases.json");
     this.userAliases = {};
     try {
-      const raw = readFileSync2(aliasPath, "utf-8");
+      const raw = readFileSync(aliasPath, "utf-8");
       const parsed = JSON.parse(raw);
       if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
         const cleaned = {};
@@ -7551,9 +7800,6 @@ var StorageManager3 = class _StorageManager extends TombstoneBlockedCaptureIndex
       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,
@@ -7561,7 +7807,6 @@ var StorageManager3 = class _StorageManager extends TombstoneBlockedCaptureIndex
       (entity) => serializeEntityFile(entity, this.entitySchemas),
       createMemoryEntityRefSerializer(serializeFrontmatter)
     );
-    this.loadHistoricalEntityCanonicalIdsSync();
     return completionFingerprint;
   }
   async ensureDirectories() {
@@ -7622,6 +7867,9 @@ var StorageManager3 = class _StorageManager extends TombstoneBlockedCaptureIndex
   }
   async writeMemory(category, content, options = {}) {
     await this.ensureDirectories();
+    const rawEntityRef = options.entityRef;
+    let refIds = typeof options.entityRef === "string" ? this.currentHistoricalIds() : null;
+    if (refIds) options = canonicalizeEntityRefOption(options, refIds);
     const now = /* @__PURE__ */ new Date();
     const today = now.toISOString().slice(0, 10);
     const id = `${category}-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
@@ -7695,40 +7943,31 @@ var StorageManager3 = class _StorageManager extends TombstoneBlockedCaptureIndex
       fm.contentHash = ContentHashIndex.computeHash(hashSource);
       factHashSourceForTombstone = hashSource;
     }
+    if (refIds && typeof rawEntityRef === "string" && this.currentHistoricalIds() !== refIds) {
+      refIds = this.currentHistoricalIds();
+      fm.entityRef = resolveHistoricalEntityCanonicalId(rawEntityRef, refIds);
+    }
     let tombstoneBlocked = false;
-    if (category === "fact" && this.tombstonesConfig.enabled && factHashSourceForTombstone !== null && // Block facts that would become ACTIVE or are already pending_review
-    // (issue #1579 thread ObteQ: wearable/native imports write fact
-    // candidates with status: pending_review; without checking them here,
-    // promoteWearableMemory could later flip a retired fact active without
-    // a tombstone check). A caller that explicitly requests a terminal
-    // non-active status (rejected/retracted/superseded) is respected.
-    (fm.status === void 0 || fm.status === "active" || fm.status === "pending_review")) {
-      try {
-        const tombstoneStore = await this.getTombstoneStore();
-        const keyedSupersession = options.entityRef && options.structuredAttributes ? supersessionKeysForFact({
-          entityRef: options.entityRef,
-          structuredAttributes: options.structuredAttributes
-        }) : [];
-        const match = tombstoneStore.lookup({
-          contentHash: fm.contentHash,
-          normalizedText: ContentHashIndex.normalizeContent(factHashSourceForTombstone),
-          ...options.entityRef ? { entityRef: options.entityRef } : {},
-          ...keyedSupersession.length > 0 ? { supersessionKeys: keyedSupersession } : {},
-          namespace: this.tombstonesConfig.namespace
-        });
-        if (match) {
-          tombstoneBlocked = true;
-          fm.status = "pending_review";
-          fm.blockedBy = match.tombstoneId;
-          fm.tombstoneBlockTier = match.matchedTier;
-          log.info(
-            `tombstone: blocked resurrection of fact ${id} (tier=${match.matchedTier}, tombstone=${match.tombstoneId}, reason=${match.reason})`
-          );
-        }
-      } catch (err) {
-        log.warn(`tombstone lookup failed for fact ${id} (fail-open): ${err}`);
+    let gateRef;
+    let statusBeforeBlock;
+    const applyTombstoneGate = async () => {
+      if (tombstoneBlocked) {
+        if (fm.entityRef === gateRef) return;
+        tombstoneBlocked = false;
+        fm.status = statusBeforeBlock;
+        delete fm.blockedBy;
+        delete fm.tombstoneBlockTier;
+      }
+      if (category !== "fact" || factHashSourceForTombstone === null) return;
+      const statusBefore = fm.status;
+      const match = await this.entityRefRepair.gate(fm, factHashSourceForTombstone, options.structuredAttributes);
+      if (match) {
+        gateRef = fm.entityRef;
+        statusBeforeBlock = statusBefore;
+        tombstoneBlocked = true;
       }
-    }
+    };
+    await applyTombstoneGate();
     const fileContent = `${serializeFrontmatter(fm)}
 
 ${sanitized.text}
@@ -7757,6 +7996,37 @@ ${sanitized.text}
         duplicateOf: duplicateBlocked.frontmatter.id
       };
     }
+    if (refIds && typeof rawEntityRef === "string") {
+      const refBeforeRepair = fm.entityRef;
+      try {
+        await repairEntityRefAfterJournalMove({
+          stateDir: this.stateDir,
+          currentIds: () => this.currentHistoricalIds(),
+          idsAtResolve: refIds,
+          rawRef: rawEntityRef,
+          frontmatter: fm,
+          rewrite: async () => {
+            await applyTombstoneGate();
+            await this.writeTombstoneBlockedMemory(
+              filePath,
+              `${serializeFrontmatter(fm)}
+
+${sanitized.text}
+`,
+              fm,
+              sanitized.text,
+              async () => this.invalidateAllMemoriesCache()
+            );
+            this.invalidateAllMemoriesCache();
+          }
+        });
+      } catch (err) {
+        await unlink4(filePath).catch(() => void 0);
+        this.invalidateAllMemoriesCache();
+        throw err;
+      }
+      await this.entityRefRepair.syncProjection(id, refBeforeRepair, fm.entityRef);
+    }
     await this.patchHotMemoriesCache({ addedPath: filePath }, "memory-create");
     this.notifyMemoryWrite(filePath);
     await this.appendGeneratedMemoryLifecycleEventFailOpen("storage.writeMemory", {
@@ -8472,11 +8742,46 @@ ${sanitized.text}
     return path9.join(root, dir, this.resolveMemoryDateDir(memory), `${memory.frontmatter.id}.md`);
   }
   async writeMemoryFileAtomic(targetPath, memory) {
-    const fileContent = `${serializeFrontmatter(memory.frontmatter)}
+    const refIdsAtWrite = this.currentHistoricalIds();
+    const rawRef = memory.frontmatter.entityRef;
+    const frontmatter = canonicalizeEntityRefOption(memory.frontmatter, refIdsAtWrite);
+    const persist = () => writeMaybeEncryptedFile(
+      targetPath,
+      `${serializeFrontmatter(frontmatter)}
 
 ${memory.content}
-`;
-    await writeMaybeEncryptedFile(targetPath, fileContent, this.resolveWriteKey(), {}, this.baseDir);
+`,
+      this.resolveWriteKey(),
+      {},
+      this.baseDir
+    );
+    const priorDest = await readFile2(targetPath).catch(() => null);
+    await persist();
+    if (typeof rawRef === "string") {
+      const refBeforeRepair = frontmatter.entityRef;
+      try {
+        await repairEntityRefAfterJournalMove({
+          stateDir: this.stateDir,
+          currentIds: () => this.currentHistoricalIds(),
+          idsAtResolve: refIdsAtWrite,
+          rawRef,
+          frontmatter,
+          rewrite: persist
+        });
+      } catch (err) {
+        if (priorDest === null) {
+          await unlink4(targetPath).catch(() => void 0);
+        } else {
+          await writeFile2(targetPath, priorDest).catch(() => void 0);
+        }
+        this.invalidateAllMemoriesCache();
+        throw err;
+      }
+      await this.entityRefRepair.syncProjection(memory.frontmatter.id, refBeforeRepair, frontmatter.entityRef);
+    }
+    if (memory.frontmatter.entityRef !== frontmatter.entityRef) {
+      memory.frontmatter.entityRef = frontmatter.entityRef;
+    }
     this.invalidateAllMemoriesCache();
     this.notifyCatalogWrite();
   }
@@ -8486,7 +8791,7 @@ ${memory.content}
     const destPath = path9.resolve(targetPath);
     if (sourcePath !== destPath) {
       try {
-        await unlink3(memory.path);
+        await unlink4(memory.path);
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         if (!message.includes("ENOENT")) {
@@ -8507,7 +8812,7 @@ ${memory.content}
     const existing = await this.readMemoryByPath(targetPath);
     if (existing?.frontmatter.id === memory.frontmatter.id) {
       try {
-        await unlink3(memory.path);
+        await unlink4(memory.path);
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         if (!message.includes("ENOENT")) {
@@ -8541,19 +8846,42 @@ ${memory.content}
         const today = now.toISOString().slice(0, 10);
         const destDir = path9.join(this.archiveDir, today);
         await mkdir(destDir, { recursive: true });
-        const updatedFm = {
-          ...current.frontmatter,
-          status: "archived",
-          archivedAt: now.toISOString(),
-          updated: now.toISOString()
-        };
+        const refIdsAtWrite = this.currentHistoricalIds();
+        const updatedFm = canonicalizeEntityRefOption(
+          {
+            ...current.frontmatter,
+            status: "archived",
+            archivedAt: now.toISOString(),
+            updated: now.toISOString()
+          },
+          refIdsAtWrite
+        );
         const fileContent = `${serializeFrontmatter(updatedFm)}
 
 ${current.content}
 `;
         const destPath = path9.join(destDir, path9.basename(current.path));
+        const priorDest = await this.readStorageSecureFile(destPath).catch(() => null);
         await this.writeStorageSecureFile(destPath, fileContent);
-        await unlink3(current.path);
+        if (typeof current.frontmatter.entityRef === "string") {
+          try {
+            await this.entityRefRepair.repair(
+              destPath,
+              updatedFm,
+              current.frontmatter.entityRef,
+              refIdsAtWrite,
+              current.content
+            );
+          } catch (err) {
+            if (priorDest === null) {
+              await unlink4(destPath).catch(() => void 0);
+            } else {
+              await this.writeStorageSecureFile(destPath, priorDest).catch(() => void 0);
+            }
+            throw err;
+          }
+        }
+        await unlink4(current.path);
         markDurable();
         markProjectedMemoryPathInvalid(this.baseDir, current.frontmatter.id);
         this.invalidateAllMemoriesCache();
@@ -8582,13 +8910,9 @@ ${current.content}
     };
     return await this.runTombstoneBlockedArchive(memory, archiveCurrent);
   }
+  /** Alias of listEntityNames (kept for legacy callers; sorted). */
   async readEntities() {
-    try {
-      const entries = await readdir5(this.entitiesDir);
-      return entries.filter((e) => e.endsWith(".md")).map((e) => e.replace(".md", ""));
-    } catch {
-      return [];
-    }
+    return this.entityStore.listEntityNames();
   }
   async readEntity(name) {
     return this.entityStore.readEntity(name);
@@ -8638,7 +8962,7 @@ ${current.content}
     return await this.runTombstoneBlockedInvalidation(
       memory,
       async (current, rebuildMarker, markDurable) => {
-        await unlink3(current.path);
+        await unlink4(current.path);
         markDurable();
         markProjectedMemoryPathInvalid(this.baseDir, id);
         this.invalidateAllMemoriesCache();
@@ -8656,13 +8980,17 @@ ${current.content}
     const mergedLineage = [...memory.frontmatter.lineage ?? [], ...options?.lineage ?? []].filter(
       (v, i, a) => a.indexOf(v) === i
     );
-    const updated = {
-      ...memory.frontmatter,
-      updated: (/* @__PURE__ */ new Date()).toISOString(),
-      supersedes: options?.supersedes ?? memory.frontmatter.supersedes,
-      lineage: mergedLineage.length > 0 ? mergedLineage : void 0,
-      ...memory.frontmatter.sourceConnector === void 0 && options?.sourceConnector ? { sourceConnector: options.sourceConnector } : {}
-    };
+    const refIdsAtWrite = this.currentHistoricalIds();
+    const updated = canonicalizeEntityRefOption(
+      {
+        ...memory.frontmatter,
+        updated: (/* @__PURE__ */ new Date()).toISOString(),
+        supersedes: options?.supersedes ?? memory.frontmatter.supersedes,
+        lineage: mergedLineage.length > 0 ? mergedLineage : void 0,
+        ...memory.frontmatter.sourceConnector === void 0 && options?.sourceConnector ? { sourceConnector: options.sourceConnector } : {}
+      },
+      refIdsAtWrite
+    );
     const sanitized = sanitizeMemoryContent(newContent);
     if (!sanitized.clean) {
       log.warn(`updated memory content sanitized for ${id}; violations=${sanitized.violations.join(", ")}`);
@@ -8674,6 +9002,16 @@ ${sanitized.text}
     await this.writeTombstoneBlockedUpdate(memory, fileContent, updated, sanitized.text, async () => {
       this.invalidateAllMemoriesCache();
     });
+    if (typeof memory.frontmatter.entityRef === "string") {
+      await this.entityRefRepair.repair(
+        memory.path,
+        updated,
+        memory.frontmatter.entityRef,
+        refIdsAtWrite,
+        sanitized.text,
+        { onFailRestore: memory }
+      );
+    }
     await this.patchHotMemoriesCache({ addedPath: memory.path });
     await this.appendGeneratedMemoryLifecycleEventFailOpen("storage.updateMemory", {
       memoryId: id,
@@ -8696,10 +9034,12 @@ ${sanitized.text}
    */
   async writeMemoryFrontmatter(memory, patch, lifecycle) {
     const beforeStatus = memory.frontmatter.status ?? "active";
-    const updated = {
-      ...memory.frontmatter,
-      ...patch
-    };
+    const resolveIds = this.currentHistoricalIds();
+    const updated = canonicalizeEntityRefOption(
+      { ...memory.frontmatter, ...patch },
+      resolveIds
+    );
+    const refIds = typeof updated.entityRef === "string" ? resolveIds : null;
     const afterStatus = updated.status ?? "active";
     const fileContent = `${serializeFrontmatter(updated)}
 
@@ -8711,6 +9051,17 @@ ${memory.content}
         this.invalidateColdMemoriesCache();
       }
     });
+    const rawMergedRef = typeof patch.entityRef === "string" ? patch.entityRef : memory.frontmatter.entityRef;
+    if (refIds && typeof rawMergedRef === "string") {
+      await this.entityRefRepair.repair(
+        memory.path,
+        updated,
+        rawMergedRef,
+        refIds,
+        memory.content,
+        { onFailRestore: memory }
+      );
+    }
     await this.patchHotMemoriesCache({ addedPath: memory.path });
     if (memory.path.includes(`${path9.sep}cold${path9.sep}`)) {
       this.invalidateColdMemoriesCache();
@@ -9164,8 +9515,8 @@ ${memory.content}
       activationState: "active"
     });
     await Promise.all([
-      unlink3(this.compressionGuidelineDraftPath).catch(() => void 0),
-      unlink3(this.compressionGuidelineDraftStatePath).catch(() => void 0)
+      unlink4(this.compressionGuidelineDraftPath).catch(() => void 0),
+      unlink4(this.compressionGuidelineDraftStatePath).catch(() => void 0)
     ]);
     return true;
   }
@@ -9399,96 +9750,27 @@ ${reflection}
     await this.writeStorageSecureFile(this.identityReflectionsPath, `${existing.trimEnd()}${section}`);
     log.debug(`appended namespace-local reflection to ${this.identityReflectionsPath}`);
   }
-  // ---------------------------------------------------------------------------
-  // Entity mutation helpers (Knowledge Graph v7.0)
-  // ---------------------------------------------------------------------------
-  /**
-   * Add a relationship to an entity file.
-   * Deduplicates by target+label.
-   */
+  // Entity-file mutators live on EntityStore (issue #2213): journal-resolved
+  // with legacy-file fallback, under the entity-mutation lock.
   async addEntityRelationship(name, rel) {
-    const filePath = path9.join(this.entitiesDir, `${name}.md`);
-    let entity;
-    try {
-      const content = await this.readStorageSecureFile(filePath);
-      entity = parseEntityFile(content, this.entitySchemas);
-    } catch (err) {
-      if (err instanceof SecureStoreLockedError) throw err;
-      if (!isErrnoCode(err, "ENOENT")) throw err;
-      log.debug(`addEntityRelationship: entity file ${name}.md not found`);
-      return;
-    }
-    const exists = entity.relationships.some((r) => r.target === rel.target && r.label === rel.label);
-    if (exists) return;
-    entity.relationships.push(rel);
-    entity.updated = (/* @__PURE__ */ new Date()).toISOString();
-    await this.writeStorageSecureFile(filePath, serializeEntityFile(entity, this.entitySchemas));
-    this.invalidateKnowledgeIndexCache();
+    return this.entityStore.addEntityRelationship(name, rel);
   }
-  /**
-   * Add an activity entry to an entity file.
-   * Prepends to the beginning, prunes oldest entries beyond maxEntries.
-   */
   async addEntityActivity(name, entry, maxEntries) {
-    const filePath = path9.join(this.entitiesDir, `${name}.md`);
-    let entity;
-    try {
-      const content = await this.readStorageSecureFile(filePath);
-      entity = parseEntityFile(content, this.entitySchemas);
-    } catch (err) {
-      if (err instanceof SecureStoreLockedError) throw err;
-      if (!isErrnoCode(err, "ENOENT")) throw err;
-      log.debug(`addEntityActivity: entity file ${name}.md not found`);
-      return;
-    }
-    entity.activity.unshift(entry);
-    if (entity.activity.length > maxEntries) {
-      entity.activity = entity.activity.slice(0, maxEntries);
-    }
-    entity.updated = (/* @__PURE__ */ new Date()).toISOString();
-    await this.writeStorageSecureFile(filePath, serializeEntityFile(entity, this.entitySchemas));
-    this.invalidateKnowledgeIndexCache();
+    return this.entityStore.addEntityActivity(name, entry, maxEntries);
   }
   async addEntityAlias(name, alias) {
-    const filePath = path9.join(this.entitiesDir, `${name}.md`);
-    let entity;
-    try {
-      const content = await this.readStorageSecureFile(filePath);
-      entity = parseEntityFile(content, this.entitySchemas);
-    } catch (err) {
-      if (err instanceof SecureStoreLockedError) throw err;
-      if (!isErrnoCode(err, "ENOENT")) throw err;
-      log.debug(`addEntityAlias: entity file ${name}.md not found`);
-      return;
-    }
-    if (entity.aliases.includes(alias)) return;
-    entity.aliases.push(alias);
-    entity.updated = (/* @__PURE__ */ new Date()).toISOString();
-    await this.writeStorageSecureFile(filePath, serializeEntityFile(entity, this.entitySchemas));
-    this.invalidateKnowledgeIndexCache();
-    this.bumpMemoryStatusVersion();
+    return this.entityStore.addEntityAlias(name, alias);
   }
   async updateEntitySynthesis(name, synthesis, options = {}) {
     return this.entityStore.updateEntitySynthesis(name, synthesis, options);
   }
-  /**
-   * Backward-compatible alias for legacy callers/tests.
-   */
+  /** Backward-compatible alias for legacy callers/tests. */
   async updateEntitySummary(name, summary) {
     const updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    let synthesisTimelineCount;
-    try {
-      const filePath = path9.join(this.entitiesDir, `${name}.md`);
-      const content = await this.readStorageSecureFile(filePath);
-      synthesisTimelineCount = parseEntityFile(content, this.entitySchemas).timeline.length;
-    } catch (err) {
-      if (err instanceof SecureStoreLockedError) throw err;
-      if (!isErrnoCode(err, "ENOENT")) throw err;
-      synthesisTimelineCount = void 0;
-    }
+    const raw = await this.readEntity(name);
     await this.updateEntitySynthesis(name, summary, {
       entityUpdatedAt: updatedAt,
-      synthesisTimelineCount,
+      synthesisTimelineCount: raw ? parseEntityFile(raw, this.entitySchemas).timeline.length : void 0,
       updatedAt
     });
   }
@@ -9554,24 +9836,7 @@ ${reflection}
     );
   }
   async migrateEntityFilesToCompiledTruthTimeline() {
-    const entityNames = await this.listEntityNames();
-    let migrated = 0;
-    for (const entityName of entityNames) {
-      const raw = await this.readEntity(entityName);
-      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);
-      migrated += 1;
-    }
-    if (migrated > 0) {
-      this.invalidateKnowledgeIndexCache();
-      this.bumpMemoryStatusVersion();
-    }
-    return {
-      total: entityNames.length,
-      migrated
-    };
+    return this.entityStore.migrateEntityFilesToCompiledTruthTimeline();
   }
   // ---------------------------------------------------------------------------
   // Scoring + Knowledge Index (Knowledge Graph v7.0)
@@ -9666,17 +9931,27 @@ ${reflection}
     for (const entry of entries) {
       const memory = entry.memoryPath ? memoryPathMap.get(path9.resolve(entry.memoryPath)) : memoryMap.get(entry.memoryId);
       if (!memory) continue;
-      const newFm = {
-        ...memory.frontmatter,
-        accessCount: entry.newCount,
-        lastAccessed: entry.lastAccessed
-      };
+      const rowIds = this.currentHistoricalIds();
+      const newFm = canonicalizeEntityRefOption(
+        { ...memory.frontmatter, accessCount: entry.newCount, lastAccessed: entry.lastAccessed },
+        rowIds
+      );
       try {
         const fileContent = `${serializeFrontmatter(newFm)}
 
 ${memory.content}
 `;
         await this.writeStorageSecureFile(memory.path, fileContent);
+        if (typeof memory.frontmatter.entityRef === "string") {
+          await this.entityRefRepair.repair(
+            memory.path,
+            newFm,
+            memory.frontmatter.entityRef,
+            rowIds,
+            memory.content,
+            { onFailRestore: memory }
+          );
+        }
         if (warm) {
           updateCacheOnWrite(this.baseDir, { ...memory, frontmatter: newFm }, keyId);
         }
@@ -9842,6 +10117,9 @@ ${memory.content}
    */
   async writeChunk(parentId, chunkIndex, chunkTotal, category, content, options = {}) {
     await this.ensureDirectories();
+    const rawEntityRef = options.entityRef;
+    let refIds = typeof options.entityRef === "string" ? this.currentHistoricalIds() : null;
+    if (refIds) options = canonicalizeEntityRefOption(options, refIds);
     const now = /* @__PURE__ */ new Date();
     const today = now.toISOString().slice(0, 10);
     const id = `${parentId}-chunk-${chunkIndex}`;
@@ -9883,12 +10161,22 @@ ${memory.content}
     if (!sanitized.clean) {
       log.warn(`chunk content sanitized for ${id}; violations=${sanitized.violations.join(", ")}`);
     }
+    const filePath = await this.resolveCategoryWritePath(category, id, today);
     const fileContent = `${serializeFrontmatter(fm)}
 
 ${sanitized.text}
 `;
-    const filePath = await this.resolveCategoryWritePath(category, id, today);
-    return await this.writeTombstoneBlockedChunk(
+    let priorChunk = null;
+    try {
+      const priorRaw = await readMaybeEncryptedFile(filePath, this._secureStoreKey, this.baseDir);
+      const parsedPrior = parseFrontmatter(priorRaw);
+      if (parsedPrior) {
+        priorChunk = { path: filePath, frontmatter: parsedPrior.frontmatter, content: parsedPrior.content };
+      }
+    } catch {
+      priorChunk = null;
+    }
+    const written = await this.writeTombstoneBlockedChunk(
       filePath,
       fileContent,
       fm,
@@ -9899,6 +10187,13 @@ ${sanitized.text}
         log.debug(`wrote chunk ${id} (${chunkIndex + 1}/${chunkTotal}) to ${filePath}`);
       }
     );
+    if (written === id && refIds && typeof rawEntityRef === "string") {
+      await this.entityRefRepair.repair(filePath, fm, rawEntityRef, refIds, sanitized.text, {
+        regateFact: true,
+        ...priorChunk ? { onFailRestore: priorChunk } : { onFailRemove: filePath }
+      });
+    }
+    return written;
   }
   /**
    * Get all chunks for a given parent memory ID.
@@ -9920,19 +10215,27 @@ ${sanitized.text}
     const oldMemory = memories.find((m) => m.frontmatter.id === oldMemoryId);
     if (!oldMemory) return false;
     const now = (/* @__PURE__ */ new Date()).toISOString();
-    const updatedFm = {
-      ...oldMemory.frontmatter,
-      status: "superseded",
-      supersededBy: newMemoryId,
-      supersededAt: now,
-      updated: now
-    };
+    const refIdsAtWrite = this.currentHistoricalIds();
+    const updatedFm = canonicalizeEntityRefOption(
+      { ...oldMemory.frontmatter, status: "superseded", supersededBy: newMemoryId, supersededAt: now, updated: now },
+      refIdsAtWrite
+    );
     const fileContent = `${serializeFrontmatter(updatedFm)}
 
 ${oldMemory.content}
 `;
     try {
       await this.writeStorageSecureFile(oldMemory.path, fileContent);
+      if (typeof oldMemory.frontmatter.entityRef === "string") {
+        await this.entityRefRepair.repair(
+          oldMemory.path,
+          updatedFm,
+          oldMemory.frontmatter.entityRef,
+          refIdsAtWrite,
+          oldMemory.content,
+          { onFailRestore: oldMemory }
+        );
+      }
       this.bumpMemoryCorpusVersion();
       await this.appendGeneratedMemoryLifecycleEventFailOpen("storage.supersedeMemory", {
         memoryId: oldMemoryId,
@@ -9952,7 +10255,7 @@ ${oldMemory.content}
             id: oldMemoryId,
             content: stripCitationForTemplate(oldMemory.content, this.citationTemplate),
             contentHash: oldMemory.frontmatter.contentHash,
-            entityRef: oldMemory.frontmatter.entityRef,
+            entityRef: updatedFm.entityRef,
             structuredAttributes: oldMemory.frontmatter.structuredAttributes
           },
           {
@@ -10028,18 +10331,27 @@ Reason: ${reason}`;
       const memory = memoryMap.get(id);
       if (!memory) continue;
       const now = (/* @__PURE__ */ new Date()).toISOString();
-      const updatedFm = {
-        ...memory.frontmatter,
-        status: "archived",
-        archivedAt: now,
-        updated: now
-      };
+      const rowIds = this.currentHistoricalIds();
+      const updatedFm = canonicalizeEntityRefOption(
+        { ...memory.frontmatter, status: "archived", archivedAt: now, updated: now },
+        rowIds
+      );
       try {
         const fileContent = `${serializeFrontmatter(updatedFm)}
 
 ${memory.content}
 `;
         await this.writeStorageSecureFile(memory.path, fileContent);
+        if (typeof memory.frontmatter.entityRef === "string") {
+          await this.entityRefRepair.repair(
+            memory.path,
+            updatedFm,
+            memory.frontmatter.entityRef,
+            rowIds,
+            memory.content,
+            { onFailRestore: memory }
+          );
+        }
         this.bumpMemoryCorpusVersion();
         await this.appendGeneratedMemoryLifecycleEventFailOpen("storage.archiveMemories", {
           memoryId: id,
@@ -10200,4 +10512,4 @@ export {
   isValidBufferSurpriseEvent,
   StorageManager3 as StorageManager
 };
-//# sourceMappingURL=chunk-4TGZCYHH.js.map
+//# sourceMappingURL=chunk-Q3CVY7LV.js.map