@remnic/core 10.0.27 → 10.0.29

package/dist/chunk-DNIG3JME.js

@@ -0,0 +1,892 @@
+import {
+  isMalformedEntityRecord
+} from "./chunk-PPUNC7UX.js";
+import {
+  ENTITY_CANONICAL_ID_MIGRATION_FILE,
+  ENTITY_CANONICAL_ID_RECONCILE_CONSUMING_MARKER,
+  ENTITY_CANONICAL_ID_RECONCILE_MARKER,
+  assertSafeEntityId,
+  withEntityCanonicalMutationLock
+} from "./chunk-VXWOJPSY.js";
+import {
+  computeSupersessionKey,
+  normalizeSupersessionKey
+} from "./chunk-5WITETWU.js";
+import {
+  withHeldFileLock
+} from "./chunk-5B5WYAHQ.js";
+import {
+  isMacOsReplicationJunkBasename,
+  warnIgnoredMacOsReplicationJunk
+} from "./chunk-QUIRIG2P.js";
+import {
+  assertPathInsideRoot
+} from "./chunk-C7HJ3NEI.js";
+import {
+  RECALL_FALLBACK_DIRS
+} from "./chunk-VS2IYZRU.js";
+import {
+  isErrnoCode
+} from "./chunk-KNA3BXXL.js";
+import {
+  log
+} from "./chunk-3WCASNQZ.js";
+
+// src/storage/entity-canonical-id-migration.ts
+import { createHash, randomUUID } from "crypto";
+import {
+  access,
+  lstat,
+  readFile,
+  readdir,
+  realpath,
+  rename,
+  stat as statFile,
+  unlink,
+  writeFile
+} from "fs/promises";
+import path 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 lstat(filePath);
+  } catch (error) {
+    if (!isErrnoCode(error, "ENOENT")) throw error;
+  }
+  return fileStat ? `${fileStat.dev}:${fileStat.ino}:${fileStat.mtimeMs}:${fileStat.ctimeMs}:${fileStat.size}` : "missing";
+}
+async function fingerprintEntityEntries(entitiesDir) {
+  let names;
+  try {
+    names = (await readdir(entitiesDir)).filter((name) => path.extname(name) === ".md" && !isMacOsReplicationJunkBasename(name)).sort();
+  } catch (error) {
+    if (isErrnoCode(error, "ENOENT")) return "missing";
+    throw error;
+  }
+  const hash = createHash("sha256");
+  for (const name of names) {
+    hash.update(`${name.length}:${name}:`);
+    try {
+      const entry = await lstat(path.join(entitiesDir, name), { bigint: true });
+      hash.update(`${entry.dev}:${entry.ino}:${entry.size}:${entry.mtimeNs}:${entry.ctimeNs}`);
+    } catch (error) {
+      if (!isErrnoCode(error, "ENOENT")) throw error;
+      hash.update("missing");
+    }
+    hash.update("\n");
+  }
+  return hash.digest("hex");
+}
+async function getFingerprint(baseDir, entitiesDir, getEntityMutationVersion) {
+  const [
+    entityDirectoryFingerprint,
+    entityEntriesFingerprint,
+    aliasFingerprint,
+    reconcileFingerprint,
+    consumingFingerprint
+  ] = await Promise.all([
+    fingerprintPath(entitiesDir),
+    fingerprintEntityEntries(entitiesDir),
+    fingerprintPath(path.join(baseDir, "config", "aliases.json")),
+    fingerprintPath(path.join(baseDir, "state", ENTITY_CANONICAL_ID_RECONCILE_MARKER)),
+    fingerprintPath(path.join(baseDir, "state", ENTITY_CANONICAL_ID_RECONCILE_CONSUMING_MARKER))
+  ]);
+  return [
+    entityDirectoryFingerprint,
+    entityEntriesFingerprint,
+    aliasFingerprint,
+    reconcileFingerprint,
+    consumingFingerprint,
+    getEntityMutationVersion()
+  ].join(":");
+}
+async function validateRoots(baseDir, entitiesDir, stateDir, archiveDir) {
+  let baseStat;
+  try {
+    baseStat = await lstat(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 realpath(baseDir);
+  const roots = [
+    entitiesDir,
+    stateDir,
+    ...RECALL_FALLBACK_DIRS.map((directory) => path.join(baseDir, directory)),
+    path.join(baseDir, "cold"),
+    archiveDir
+  ];
+  for (const root of roots) {
+    let rootStat;
+    try {
+      rootStat = await lstat(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 realpath(root), root);
+  }
+}
+function statePath(deps) {
+  return path.join(deps.stateDir, ENTITY_CANONICAL_ID_MIGRATION_FILE);
+}
+async function assertSafeMigrationStateFile(deps) {
+  const migrationStatePath = statePath(deps);
+  let fileStat;
+  try {
+    fileStat = await lstat(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([
+    realpath(deps.stateDir),
+    realpath(migrationStatePath)
+  ]);
+  assertPathInsideRoot(stateRoot, stateFile, migrationStatePath);
+}
+async function assertSafeTombstoneFile(deps, tombstonePath) {
+  let fileStat;
+  try {
+    fileStat = await lstat(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([
+    realpath(deps.stateDir),
+    realpath(tombstonePath)
+  ]);
+  assertPathInsideRoot(stateRoot, tombstoneFile, tombstonePath);
+  return true;
+}
+function lockPath(deps) {
+  return path.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.");
+  for (const mappings of [result.data.mappings, result.data.blocked ?? {}]) {
+    for (const [legacyId, canonicalId] of Object.entries(mappings)) {
+      assertSafeEntityId(legacyId);
+      assertSafeEntityId(canonicalId);
+    }
+  }
+  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 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;
+  }
+}
+async function assertNotSymlink(filePath, label) {
+  let stat;
+  try {
+    stat = await lstat(filePath);
+  } catch (error) {
+    if (isErrnoCode(error, "ENOENT")) return;
+    throw error;
+  }
+  if (stat.isSymbolicLink()) {
+    throw new Error(`Refusing entity canonical-id migration through symlink: ${label}.`);
+  }
+}
+async function assertNotMemorySymlink(filePath) {
+  let stat;
+  try {
+    stat = await lstat(filePath);
+  } catch (error) {
+    if (isErrnoCode(error, "ENOENT")) return;
+    throw error;
+  }
+  if (stat.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 lstat(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 readdir(entitiesDir);
+  for (const entry of entries) {
+    await assertNotSymlink(path.join(entitiesDir, entry), entry);
+  }
+  return entries;
+}
+async function discoverMappings(deps, knownMappings = {}, blocked = /* @__PURE__ */ new Map(), scanNotes) {
+  const mappings = {};
+  const canonicalOwners = /* @__PURE__ */ new Map();
+  blocked.clear();
+  const entityEntries = await readSafeEntityEntries(deps.entitiesDir);
+  for (const entry of entityEntries) {
+    if (isMacOsReplicationJunkBasename(entry)) {
+      scanNotes?.junk.add(entry);
+      continue;
+    }
+    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 (isMalformedEntityRecord(entityContent)) {
+      scanNotes?.malformed.add(entry);
+      continue;
+    }
+    const entity = deps.parseEntityFile(entityContent);
+    if (!entity.name.trim() || !entity.type.trim()) {
+      scanNotes?.malformed.add(entry);
+      continue;
+    }
+    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 canonicalContent = await deps.readStorageSecureFile(canonicalPath);
+      if (entityContent !== canonicalContent) {
+        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 = path.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(`${path.sep}cold${path.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 = path.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(
+    path.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") || isMacOsReplicationJunkBasename(entry)) continue;
+    const entityPath = deps.resolveEntityFilePath(entry.slice(0, -".md".length));
+    if (entityPath === null) continue;
+    const observedEntityFingerprint = await fingerprintPath(entityPath);
+    if (observedEntityFingerprint === "missing") continue;
+    const entityRaw = await deps.readStorageSecureFile(entityPath);
+    if (isMalformedEntityRecord(entityRaw)) continue;
+    const entity = deps.parseEntityFile(entityRaw);
+    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 latestRaw = await deps.readStorageSecureFile(entityPath);
+        if (isMalformedEntityRecord(latestRaw)) return false;
+        const latestEntity = deps.parseEntityFile(latestRaw);
+        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) {
+      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, canonicalContent, legacyEncrypted, canonicalEncrypted] = await Promise.all([
+        deps.readStorageSecureFile(legacyPath),
+        deps.readStorageSecureFile(canonicalPath),
+        deps.isEncryptedStorageFile(legacyPath),
+        deps.isEncryptedStorageFile(canonicalPath)
+      ]);
+      if (legacyContent !== canonicalContent) {
+        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 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);
+    if (isMacOsReplicationJunkBasename(path.basename(legacyPath)) || isMalformedEntityRecord(entityContent)) {
+      return { deferred: false, progressed: false };
+    }
+    let canonicalFingerprintAfterWrite = null;
+    try {
+      await deps.writeStorageSecureFile(canonicalPath, entityContent, entityEncrypted);
+      canonicalFingerprintAfterWrite = await fingerprintPath(canonicalPath);
+      if (await deps.readStorageSecureFile(canonicalPath) !== entityContent) {
+        throw new Error(`Cannot verify migrated entity id ${canonicalId}.`);
+      }
+      if (!await refreshMigrationLock() || !await refreshEntityLock()) {
+        throw new Error("Lost entity canonical-id migration lock.");
+      }
+      await deps.snapshotBeforeWrite(legacyPath, "write");
+      await assertNotSymlink(legacyPath, legacyId);
+      await assertEntityContentUnchanged(deps, legacyPath, entityContent, legacyId);
+      await unlink(legacyPath);
+    } catch (error) {
+      if (!canonicalExists && canonicalFingerprintAfterWrite !== null) {
+        try {
+          if (await fingerprintPath(canonicalPath) === canonicalFingerprintAfterWrite) {
+            await assertNotSymlink(canonicalPath, canonicalId);
+            await unlink(canonicalPath);
+          }
+        } catch {
+        }
+      }
+      throw error;
+    }
+    return { deferred: false, progressed: true };
+  });
+}
+async function migrateLegacyEntityCanonicalIds(deps) {
+  return withHeldFileLock(
+    lockPath(deps),
+    {
+      staleMs: ENTITY_CANONICAL_ID_MIGRATION_LOCK_STALE_MS,
+      maxWaitMs: ENTITY_CANONICAL_ID_MIGRATION_LOCK_MAX_WAIT_MS
+    },
+    async (acquired, lock) => {
+      if (!acquired) throw new Error("Timed out waiting for active entity canonical-id migration.");
+      await deps.validateMemoryScanRoots?.();
+      await readSafeEntityEntries(deps.entitiesDir);
+      const reconcileMarkerPath = path.join(deps.stateDir, ENTITY_CANONICAL_ID_RECONCILE_MARKER);
+      const consumingMarkerPath = path.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;
+        }
+      }
+      let state = await readState(deps);
+      if (!state) {
+        state = {
+          version: ENTITY_CANONICAL_ID_MIGRATION_VERSION,
+          complete: false,
+          mappings: {}
+        };
+      }
+      const blocked = /* @__PURE__ */ new Map();
+      const scanNotes = { junk: /* @__PURE__ */ new Set(), malformed: /* @__PURE__ */ new Set() };
+      const staleParked = /* @__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 (staleParked.size > 0) {
+          const pairs = [...staleParked].map(([legacyId, canonicalId]) => `${legacyId} -> ${canonicalId}`).join(", ");
+          log.warn(
+            `entity canonical-id migration dropped ${staleParked.size} mapping(s) whose entity files are gone: ${pairs}. The stale journal entries were removed; references to those legacy ids do not resolve either way.`
+          );
+        }
+        warnIgnoredMacOsReplicationJunk(deps.entitiesDir, scanNotes.junk.size, (message) => {
+          log.warn(`entity canonical-id migration ${message}`);
+        });
+        if (scanNotes.malformed.size > 0) {
+          const names = [...scanNotes.malformed].sort().join(", ");
+          log.warn(
+            `entity canonical-id migration skipped ${scanNotes.malformed.size} malformed entity file(s): ${names}. Each file was left in place; startup continues. Fix or remove the file to migrate it.`
+          );
+        }
+        if (reconcileRequested) {
+          await unlink(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;
+          let target = canonicalId;
+          const seenTargets = /* @__PURE__ */ new Set();
+          while (active[target] !== void 0 && !seenTargets.has(target)) {
+            seenTargets.add(target);
+            target = active[target];
+          }
+          const targetPath = deps.resolveEntityFilePath(target);
+          if (targetPath === null || !await fileExists(targetPath)) {
+            staleParked.set(legacyId, canonicalId);
+            continue;
+          }
+          active[legacyId] = target;
+          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, scanNotes)
+        );
+        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()
+            );
+            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 publishState(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, scanNotes)
+          );
+          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) {
+            for (const [legacyId, canonicalId] of deferredMappings) {
+              blocked.set(legacyId, canonicalId);
+              staleParked.set(legacyId, canonicalId);
+            }
+            break;
+          }
+          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, scanNotes)
+        );
+        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);
+      }
+      throw new Error("Entity canonical-id migration mappings changed while migration was running; retry migration.");
+    }
+  );
+}
+
+export {
+  getFingerprint,
+  validateRoots,
+  readSafeEntityEntries,
+  migrateLegacyEntityCanonicalIds
+};
+//# sourceMappingURL=chunk-DNIG3JME.js.map