@remnic/core 9.35.1 → 9.35.3

package/src/spaces/index.ts

@@ -14,6 +14,17 @@ import fs from "node:fs";
 import path from "node:path";
 import { readEnvVar, resolveHomeDir } from "../runtime/env.js";
 import { bumpMemoryCorpusVersionForDir } from "../memory-corpus-version.js";
+import {
+  HistoricalEntityCanonicalIdCache,
+  canonicalizeEntityRefFrontmatter,
+  classifyEntityRefWritePath,
+  readEntityRefFromFrontmatter,
+  repairContentAfterJournalMoveSync,
+  requestEntityCanonicalIdReconcileSync,
+} from "../storage/entity-canonical-id-references.js";
+
+// Write-boundary journal cache for promoted copies (issue #2213).
+const historicalIdCache = new HistoricalEntityCanonicalIdCache();
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
@@ -862,6 +873,29 @@ function copyMemories(
   const targetRoot = fs.realpathSync(targetDir);
 
   const sourceFiles = walkMd(sourceRoot);
+  // Entity pages in THIS copy batch can re-establish collisions the target's
+  // journal already resolved (Codex P1, round 19; mirrors capsule-merge):
+  // once the next migration parks the mapping, a memory canonicalized onto
+  // the target's canonical claimant is permanently misattributed. Memories
+  // whose ref targets a batch-supplied entity id copy byte-faithful behind
+  // the reconcile marker instead.
+  const sourceEntityIds = new Set(
+    sourceFiles
+      .filter((p) => {
+        const rp = safeRealpath(p);
+        if (!rp || !isPathInsideRoot(rp, sourceRoot)) return false;
+        const rel = path.relative(sourceRoot, rp);
+        const mapped = path.resolve(targetRoot, rel);
+        if (!isPathInsideRoot(mapped, targetRoot)) return false;
+        return classifyEntityRefWritePath(targetRoot, mapped) === "entity";
+      })
+      .map((p) => path.basename(p, ".md")),
+  );
+  // The reconcile marker is published ONCE, after every record landed
+  // (Codex P1, round 21): a per-record marker could be consumed by a peer
+  // between a legacy-preserving memory write and its colliding entity page,
+  // canonicalizing the memory onto the wrong claimant irreversibly.
+  let reconcileNeeded = false;
   for (const sourcePath of sourceFiles) {
     const sourceRealPath = safeRealpath(sourcePath);
     if (!sourceRealPath || !isPathInsideRoot(sourceRealPath, sourceRoot)) {
@@ -881,6 +915,21 @@ function copyMemories(
       continue;
     }
 
+    // The target's migration journal is a write boundary for promoted copies
+    // too (issue #2213): a pre-migration source memory can carry a legacy
+    // entityRef the target already renamed, and corpus bumps no longer
+    // re-trigger the migration. Read per record so a mid-batch journal change
+    // applies to later copies. Only memory-tier records canonicalize —
+    // entities/ pages carry relationship targets (reconcile-marker territory,
+    // below) and everything else copies byte-faithful.
+    const targetKind = classifyEntityRefWritePath(targetRoot, targetPath);
+    const idsAtCompare = historicalIdCache.get(path.join(targetRoot, "state"));
+    const sourceRef = targetKind === "memory" ? readEntityRefFromFrontmatter(content) : null;
+    const refHasSourceClaimant = sourceRef !== null && sourceEntityIds.has(sourceRef);
+    const canonicalContent =
+      targetKind === "memory" && !refHasSourceClaimant
+        ? canonicalizeEntityRefFrontmatter(content, idsAtCompare)
+        : content;
     const sourceHash = hashContent(content);
 
     // Filter by IDs if specified
@@ -910,7 +959,21 @@ function copyMemories(
       const targetContent = fs.readFileSync(targetPath, "utf8");
       const targetHash = hashContent(targetContent);
 
-      if (sourceHash !== targetHash) {
+      // A target already holding the CANONICALIZED form is the same memory —
+      // done, and re-promoting after a ref rewrite must not report a conflict.
+      // The verdict is only valid for the snapshot it was computed under
+      // (Codex P1): a mapping parked/removed mid-compare would leave the
+      // target's formerly-canonical ref with nothing left to repair it — a
+      // moved journal falls through to the write path, which resolves at the
+      // write and repairs after it.
+      if (
+        hashContent(canonicalContent) === targetHash
+        && historicalIdCache.get(path.join(targetRoot, "state")) === idsAtCompare
+      ) {
+        skipped++;
+        continue;
+      }
+      if (hashContent(canonicalContent) !== targetHash && sourceHash !== targetHash) {
         conflicts.push({
           memoryId: parseSimpleFrontmatter(content)?.id ?? relativePath,
           sourcePath,
@@ -921,10 +984,10 @@ function copyMemories(
         });
         continue;
       }
-
-      // Same content — skip
-      skipped++;
-      continue;
+      // Fall through and rewrite in place: the target matches the RAW source
+      // while a mapping applies (a skip would leave the legacy entityRef on
+      // disk forever), or it matched the canonical form under a journal that
+      // moved mid-compare (the write path re-resolves and repairs) (#2213).
     }
 
     // Copy file
@@ -934,7 +997,59 @@ function copyMemories(
       skipped++;
       continue;
     }
-    fs.writeFileSync(targetPath, content);
+    const stateDir = path.join(targetRoot, "state");
+    if (targetKind === "memory" && !refHasSourceClaimant) {
+      // Re-resolve at the write and REPAIR afterwards: a peer process can
+      // publish the journal at any point in this loop, and the corpus bump
+      // below no longer re-triggers the migration.
+      const idsAtWrite = historicalIdCache.get(stateDir);
+      const written = canonicalizeEntityRefFrontmatter(content, idsAtWrite);
+      // Snapshot the prior target: a repair failure must restore it (or
+      // remove a newly created file) before propagating — a reported-failed
+      // copy must not replace the prior claimant's bytes (AGENTS.md §14).
+      let priorTarget: string | null = null;
+      try {
+        priorTarget = fs.readFileSync(targetPath, "utf8");
+      } catch {
+        priorTarget = null;
+      }
+      fs.writeFileSync(targetPath, written);
+      try {
+        repairContentAfterJournalMoveSync({
+          stateDir,
+          cache: historicalIdCache,
+          idsAtWrite,
+          rawContent: content,
+          lastWritten: written,
+          rewrite: (next) => fs.writeFileSync(targetPath, next),
+        });
+      } catch (err) {
+        try {
+          if (priorTarget === null) {
+            fs.unlinkSync(targetPath);
+          } else {
+            fs.writeFileSync(targetPath, priorTarget);
+          }
+        } catch {
+          // Best effort — the retryable repair error is the primary signal.
+        }
+        throw err;
+      }
+    } else if (targetKind === "memory") {
+      // Ref targets a batch-supplied entity page (potential collision
+      // claimant): keep the legacy bytes; the DEFERRED marker below lets the
+      // migration settle the collision and rewrite per its verdict (Codex P1).
+      fs.writeFileSync(targetPath, content);
+      reconcileNeeded = true;
+    } else {
+      fs.writeFileSync(targetPath, content);
+      if (targetKind === "entity") {
+        // Entity pages carry relationship TARGETS only rewriteRelationshipTargets
+        // understands — copy bytes faithfully behind the deferred reconcile
+        // pass (issue #2213).
+        reconcileNeeded = true;
+      }
+    }
     merged++;
     // Bump the target's corpus sentinel per write (out-of-band — not through a
     // StorageManager mutation), on the CANONICAL root (targetRoot), matching
@@ -947,6 +1062,12 @@ function copyMemories(
     bumpMemoryCorpusVersionForDir(targetRoot);
   }
 
+  // Every record — including every collision claimant entity page — is on
+  // disk; NOW the reconcile pass can settle collisions safely.
+  if (reconcileNeeded) {
+    requestEntityCanonicalIdReconcileSync(path.join(targetRoot, "state"));
+  }
+
   return { merged, conflicts, skipped };
 }
 

package/src/storage/citation-hash-source.ts

@@ -0,0 +1,97 @@
+/**
+ * Citation-marker stripping for dedup-hash sources (extracted from storage.ts
+ * under the #1995 structural ratchet; behavior unchanged).
+ *
+ * Content persisted with an injected citation block must hash to the SAME
+ * value as its raw form (AGENTS.md #13/#23 hash-consistency rules), so the
+ * hash source strips the configured citation template — literal template
+ * parts matched in order, whitespace around the marker normalized — without
+ * building a regex from template text (AGENTS.md #34).
+ */
+import { DEFAULT_CITATION_FORMAT } from "../source-attribution.js";
+
+function trimTrailingSpacesAndTabs(value: string): string {
+  let end = value.length;
+  while (end > 0 && (value[end - 1] === " " || value[end - 1] === "\t")) {
+    end -= 1;
+  }
+  return end === value.length ? value : value.slice(0, end);
+}
+
+function trimLeadingSpacesAndTabs(value: string): string {
+  let start = 0;
+  while (start < value.length && (value[start] === " " || value[start] === "\t")) {
+    start += 1;
+  }
+  return start === 0 ? value : value.slice(start);
+}
+
+export function stripDefaultCitationMarkersWithoutRegex(value: string): string {
+  return stripCitationMarkersForHashRemoval(value, DEFAULT_CITATION_FORMAT);
+}
+
+function citationTemplateLiteralParts(template: string): string[] {
+  const parts: string[] = [];
+  let cursor = 0;
+  while (cursor < template.length) {
+    const open = template.indexOf("{", cursor);
+    if (open === -1) {
+      parts.push(template.slice(cursor));
+      break;
+    }
+    parts.push(template.slice(cursor, open));
+    const close = template.indexOf("}", open + 1);
+    if (close === -1) {
+      cursor = open + 1;
+    } else {
+      cursor = close + 1;
+    }
+  }
+  return parts.filter((part) => part.length > 0);
+}
+
+export function stripCitationMarkersForHashRemoval(value: string, template: string): string {
+  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;
+}

package/src/storage/entity-canonical-id-lock.ts

@@ -0,0 +1,33 @@
+/**
+ * Entity canonical-id MUTATION lock (issue #2213).
+ *
+ * Serializes every writer whose correctness depends on the canonical-id
+ * journal not moving mid-write: entity file mutations (entity-store),
+ * per-pair file migration and journal pruning (entity-canonical-id-migration),
+ * and the final settle attempt of the post-persist repair helpers
+ * (entity-canonical-id-references). Lives in its own module so the reference
+ * helpers can take the lock without importing the migration module, which
+ * itself imports the reference helpers.
+ */
+import path from "node:path";
+import { withHeldFileLock } from "../utils/serialize-mutations.js";
+
+const ENTITY_CANONICAL_ID_MUTATION_LOCK_STALE_MS = 60_000;
+const ENTITY_CANONICAL_ID_MUTATION_LOCK_MAX_WAIT_MS = 300_000;
+
+export async function withEntityCanonicalMutationLock<T>(
+  stateDir: string,
+  task: (refreshLock: () => Promise<boolean>) => Promise<T>,
+): Promise<T> {
+  return withHeldFileLock(
+    path.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());
+    },
+  );
+}

package/src/storage/entity-canonical-id-migration-adapter.ts

@@ -29,7 +29,7 @@ export interface EntityCanonicalIdMigrationHost {
   invalidateAllMemoriesCache(): void;
   invalidateColdMemoriesCache(): void;
   bumpMemoryStatusVersion(): void;
-  getCorpusScanVersion(): string;
+  getEntityMutationVersion(): number;
 }
 
 export async function runLegacyEntityCanonicalIdMigration(
@@ -37,9 +37,9 @@ export async function runLegacyEntityCanonicalIdMigration(
   parseEntityFile: (content: string) => EntityFile,
   serializeEntityFile: (entity: EntityFile) => string,
   serializeMemoryWithEntityRef: (memory: MemoryFile, entityRef: string) => string,
-): Promise<string> {
+): Promise<string | undefined> {
   const readMigrationFingerprint = () =>
-    getFingerprint(host.baseDir, host.entitiesDir, () => host.getCorpusScanVersion());
+    getFingerprint(host.baseDir, host.entitiesDir, () => String(host.getEntityMutationVersion()));
   const completionFingerprint = await migrateLegacyEntityCanonicalIds({
     stateDir: host.stateDir,
     entitiesDir: host.entitiesDir,
@@ -68,5 +68,9 @@ export async function runLegacyEntityCanonicalIdMigration(
     bumpMemoryStatusVersion: host.bumpMemoryStatusVersion.bind(host),
     readMigrationFingerprint,
   } satisfies EntityCanonicalIdMigrationDependencies);
-  return completionFingerprint ?? readMigrationFingerprint();
+  // An undefined completion fingerprint is a deliberate signal (issue #2213):
+  // a reconcile marker landed while the run scanned, and recomputing the
+  // fingerprint here would seal that pending request into the runner's
+  // completed state. Propagate it so the runner retries instead.
+  return completionFingerprint;
 }

package/src/storage/entity-canonical-id-migration.ts

@@ -11,7 +11,7 @@ import {
   writeFile,
 } from "node:fs/promises";
 import path from "node:path";
-import { readFileSync } from "node:fs";
+import { lstatSync, readFileSync } from "node:fs";
 import { z } from "zod";
 import { computeSupersessionKey, normalizeSupersessionKey } from "../temporal-supersession.js";
 import type { EntityFile, MemoryFile } from "../types.js";
@@ -20,52 +20,23 @@ import { isErrnoCode } from "../utils/errno.js";
 import { withHeldFileLock } from "../utils/serialize-mutations.js";
 import { RECALL_FALLBACK_DIRS } from "../utils/category-dir.js";
 import { assertPathInsideRoot } from "../utils/path-containment.js";
+import { withEntityCanonicalMutationLock } from "./entity-canonical-id-lock.js";
+
+import {
+  ENTITY_CANONICAL_ID_MIGRATION_FILE,
+  ENTITY_CANONICAL_ID_RECONCILE_CONSUMING_MARKER,
+  ENTITY_CANONICAL_ID_RECONCILE_MARKER,
+  resolveHistoricalEntityCanonicalId,
+} from "./entity-canonical-id-references.js";
 
 const ENTITY_CANONICAL_ID_MIGRATION_VERSION = 1;
-export const ENTITY_CANONICAL_ID_MIGRATION_FILE = "entity-canonical-id-migration-v1.json";
 const ENTITY_CANONICAL_ID_MIGRATION_LOCK_STALE_MS = 60_000;
 const ENTITY_CANONICAL_ID_MIGRATION_LOCK_MAX_WAIT_MS = 300_000;
 const TOMBSTONE_LOCK_STALE_MS = 30_000;
 const TOMBSTONE_LOCK_MAX_WAIT_MS = 5_000;
-const ENTITY_CANONICAL_ID_MUTATION_LOCK_STALE_MS = 60_000;
-const ENTITY_CANONICAL_ID_MUTATION_LOCK_MAX_WAIT_MS = 300_000;
 const MEMORY_REWRITE_MAX_PASSES = 3;
 const ENTITY_MAPPING_RESCAN_MAX_PASSES = 3;
 
-export function loadHistoricalEntityCanonicalIds(stateDir: string): Readonly<Record<string, string>> {
-  const statePath = path.join(stateDir, ENTITY_CANONICAL_ID_MIGRATION_FILE);
-  try {
-    const parsed: unknown = JSON.parse(readFileSync(statePath, "utf-8"));
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
-    const mappings = (parsed as { mappings?: unknown }).mappings;
-    if (!mappings || typeof mappings !== "object" || Array.isArray(mappings)) return {};
-    const cleaned: Record<string, string> = {};
-    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 {};
-  }
-}
-
-export function resolveHistoricalEntityCanonicalId(
-  normalized: string,
-  mappings: Readonly<Record<string, string>>,
-): string {
-  let current = normalized;
-  const seen = new Set<string>();
-  while (!seen.has(current)) {
-    seen.add(current);
-    const next = mappings[current];
-    if (!next || next === current) break;
-    current = next;
-  }
-  return current;
-}
-
 const EntityCanonicalIdMigrationStateSchema = z.object({
   version: z.literal(ENTITY_CANONICAL_ID_MIGRATION_VERSION),
   complete: z.boolean(),
@@ -124,16 +95,33 @@ async function fingerprintPath(filePath: string): Promise<string> {
     : "missing";
 }
 
+/**
+ * Completion fingerprint for the migration runner's skip gate. Incorporates
+ * only state that can change what a re-run would DO: the entities directory
+ * (creates/deletes/renames), the alias table (normalization inputs), the
+ * caller-supplied entity-mutation version (store-mediated entity content
+ * edits, which touch neither of the first two), and the reconcile-pending
+ * marker raw-byte writers touch. It must NOT incorporate the memory-corpus
+ * write version: plain memory creates cannot introduce legacy entity
+ * references (writes normalize through the historical mapping table), and
+ * keying the gate to them re-ran the migration after every fact write — the
+ * issue #2213 hot loop.
+ */
 export async function getFingerprint(
   baseDir: string,
   entitiesDir: string,
-  getCorpusScanVersion: () => string,
+  getEntityMutationVersion: () => string,
 ): Promise<string> {
-  const [entityFingerprint, aliasFingerprint] = await Promise.all([
+  const [entityFingerprint, aliasFingerprint, reconcileFingerprint, consumingFingerprint] = await Promise.all([
     fingerprintPath(entitiesDir),
     fingerprintPath(path.join(baseDir, "config", "aliases.json")),
+    fingerprintPath(path.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(path.join(baseDir, "state", ENTITY_CANONICAL_ID_RECONCILE_CONSUMING_MARKER)),
   ]);
-  return `${entityFingerprint}:${aliasFingerprint}:${getCorpusScanVersion()}`;
+  return [entityFingerprint, aliasFingerprint, reconcileFingerprint, consumingFingerprint, getEntityMutationVersion()]
+    .join(":");
 }
 
 export async function validateRoots(
@@ -229,22 +217,6 @@ function lockPath(deps: EntityCanonicalIdMigrationDependencies): string {
   return path.join(deps.stateDir, "entity-canonical-id-migration.lock");
 }
 
-export async function withEntityCanonicalMutationLock<T>(
-  stateDir: string,
-  task: (refreshLock: () => Promise<boolean>) => Promise<T>,
-): Promise<T> {
-  return withHeldFileLock(
-    path.join(stateDir, "entity-canonical-id-mutation.lock"),
-    {
-      staleMs: ENTITY_CANONICAL_ID_MUTATION_LOCK_STALE_MS,
-      maxWaitMs: ENTITY_CANONICAL_ID_MUTATION_LOCK_MAX_WAIT_MS,
-    },
-    async (acquired, lock) => {
-      if (!acquired) throw new Error("Timed out waiting for entity mutation lock.");
-      return task(() => lock.refresh());
-    },
-  );
-}
 
 async function readState(
   deps: EntityCanonicalIdMigrationDependencies
@@ -283,6 +255,23 @@ async function writeState(
   }
 }
 
+/**
+ * Every journal publish — additive merges, completion markers, prunes —
+ * serializes under the entity MUTATION lock (issue #2213 review): entity
+ * writers, post-persist repair settles, and tombstone appends revalidate
+ * the journal identity under that lock, so an unlocked publish could land
+ * inside their resolve→write window and strand the write on a superseded
+ * id space.
+ */
+async function publishState(
+  deps: EntityCanonicalIdMigrationDependencies,
+  state: EntityCanonicalIdMigrationState
+): Promise<void> {
+  await withEntityCanonicalMutationLock(deps.stateDir, async () => {
+    await writeState(deps, state);
+  });
+}
+
 async function fileExists(filePath: string): Promise<boolean> {
   try {
     await access(filePath);
@@ -830,6 +819,23 @@ export async function migrateLegacyEntityCanonicalIds(
       if (!acquired) throw new Error("Timed out waiting for active entity canonical-id migration.");
       await deps.validateMemoryScanRoots?.();
       await readSafeEntityEntries(deps.entitiesDir);
+      // A raw-byte writer (offline sync, consolidation-undo, governance
+      // restore) may have landed memory bytes this process never vetted; the
+      // marker requests ONE reference-reconciliation pass (issue #2213). The
+      // observed generation is RENAMED aside before the pass so a request made
+      // WHILE this run scans creates a fresh marker that survives finish() —
+      // and a `.consuming` file left by a crashed run still owes its pass.
+      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 = {
@@ -841,7 +847,7 @@ export async function migrateLegacyEntityCanonicalIds(
       const blocked: BlockedEntityPairs = new Map();
       // ONE aggregated line per run, not one per pair per restart: this used to
       // abort the daemon, so the operator needs the whole list and the remedy.
-      const finish = (): Promise<string | undefined> | string | undefined => {
+      const finish = async (): Promise<string | undefined> => {
         if (blocked.size > 0) {
           const pairs = [...blocked].map(([legacyId, canonicalId]) => `${legacyId} -> ${canonicalId}`).join(", ");
           log.warn(
@@ -849,7 +855,29 @@ export async function migrateLegacyEntityCanonicalIds(
             + "Both files were kept and the legacy id still resolves; merge or delete one side to migrate it.",
           );
         }
-        return deps.readMigrationFingerprint?.();
+        // Every finish() path either just rewrote references (main/reconcile
+        // paths), has none to rewrite (empty mappings), or observed no marker
+        // (stable no-op) — so the CONSUMED generation is removed here. A fresh
+        // marker written mid-run is untouched, and a crash before this point
+        // leaves `.consuming` set for the next run (the rewrite is idempotent).
+        if (reconcileRequested) {
+          await unlink(consumingMarkerPath).catch((error: unknown) => {
+            if (!isErrnoCode(error, "ENOENT")) throw error;
+          });
+        }
+        // A FRESH marker written while this run scanned means bytes landed the
+        // pass may not have covered. Withholding the completion fingerprint
+        // makes the runner's stability check fail, so it immediately retries —
+        // and the retry consumes the fresh generation. ORDER MATTERS: read the
+        // fingerprint BEFORE the marker check. A marker landing after the
+        // fingerprint read but before the check is caught by the check; one
+        // landing after the check is absent from the returned fingerprint, so
+        // the live marker mismatches the runner's cached completion and the
+        // next ensure() re-invokes. Checking first left a window where the
+        // fingerprint could SEAL a marker the check never saw.
+        const completionFingerprint = await deps.readMigrationFingerprint?.();
+        if (await fileExists(reconcileMarkerPath)) return undefined;
+        return completionFingerprint;
       };
       /**
        * Drop blocked pairs from the working set. Discovery only refuses to
@@ -905,8 +933,12 @@ export async function migrateLegacyEntityCanonicalIds(
           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;
+        // Parking/removing an active mapping mid-entity-write would land an
+        // alias/activity/relationship mutation on a now-unrelated canonical
+        // claimant — the reconcile pass rewrites references, it cannot move
+        // a misplaced mutation. publishState serializes under the lock.
         state = { ...current, mappings: collapsed, blocked: parked };
-        await writeState(deps, state);
+        await publishState(deps, state);
         return revived;
       };
       const previousMappings = state.mappings;
@@ -923,19 +955,39 @@ export async function migrateLegacyEntityCanonicalIds(
           state.mappings,
           await discoverMappings(deps, state.mappings, blocked),
         );
-        await pruneBlocked();
+        const revivedBefore = 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 rewroteColdMemory = await rewriteKnownReferences(
-            deps,
-            state.mappings,
-            () => lock.refresh(),
-          );
-          deps.invalidateKnowledgeIndexCache();
-          deps.invalidateAllMemoriesCache();
-          if (rewroteColdMemory) deps.invalidateColdMemoriesCache();
-          deps.bumpMemoryStatusVersion();
+        // Stable completed journal → no-op (issue #2213). Retained mappings are
+        // read-compat state whose references were already rewritten (to
+        // convergence) before `complete: true` was persisted, so re-running
+        // `rewriteKnownReferences` here re-read the ENTIRE hot+cold+archived
+        // corpus — twice — and invalidated every memory cache on EVERY
+        // `ensureDirectories()`. On a write-active daemon that was a
+        // self-sustaining hot loop (multi-GB/s of re-reads, caches never warm,
+        // recall degraded to the fallback path). A park revived by THIS run's
+        // pruneBlocked still owes its reference rewrite: it falls through to
+        // the main flow below, which demotes `complete` BEFORE rewriting — so
+        // a crash mid-rewrite resumes, which the old in-place rewrite did not.
+        if (
+          state.complete
+          && Object.keys(discoveredBefore).length === 0
+          && !mappingsChanged
+          && !revivedBefore
+        ) {
+          // Stable journal, but a raw-byte writer requested reconciliation:
+          // run ONE bounded rewrite pass over the retained mappings, then let
+          // finish() consume the marker.
+          if (reconcileRequested && Object.keys(state.mappings).length > 0) {
+            const rewroteColdMemory = await rewriteKnownReferences(
+              deps,
+              state.mappings,
+              () => lock.refresh(),
+            );
+            deps.invalidateKnowledgeIndexCache();
+            deps.invalidateAllMemoriesCache();
+            if (rewroteColdMemory) deps.invalidateColdMemoriesCache();
+            deps.bumpMemoryStatusVersion();
+          }
           return finish();
         }
         if (
@@ -944,7 +996,7 @@ export async function migrateLegacyEntityCanonicalIds(
           || Object.keys(mergedBefore).length !== Object.keys(state.mappings).length
         ) {
           state = { ...state, complete: false, mappings: mergedBefore };
-          await writeState(deps, state);
+          await publishState(deps, state);
         }
         if (Object.keys(state.mappings).length === 0) {
           if (!(await lock.refresh())) throw new Error("Lost entity canonical-id migration lock.");
@@ -958,7 +1010,7 @@ export async function migrateLegacyEntityCanonicalIds(
           // that already reflects the deletion - so no later run revisits it.
           const revivedInRescan = await pruneBlocked();
           if (Object.keys(discoveredAfter).length === 0 && !revivedInRescan) {
-            await writeState(deps, { ...state, complete: true });
+            await publishState(deps, { ...state, complete: true });
             return finish();
           }
           state = {
@@ -966,7 +1018,7 @@ export async function migrateLegacyEntityCanonicalIds(
             complete: false,
             mappings: collapseMappings(mergeDiscoveredMappings(state.mappings, discoveredAfter)),
           };
-          await writeState(deps, state);
+          await publishState(deps, state);
           continue;
         }
         let pendingMappings = Object.entries(state.mappings);
@@ -1016,7 +1068,7 @@ export async function migrateLegacyEntityCanonicalIds(
         // retries and those references stay stranded.
         const revivedAfterRewrite = await pruneBlocked();
         if (Object.keys(discoveredAfter).length === 0 && !revivedAfterRewrite) {
-          await writeState(deps, { ...state, complete: true });
+          await publishState(deps, { ...state, complete: true });
           return finish();
         }
         state = {
@@ -1024,7 +1076,7 @@ export async function migrateLegacyEntityCanonicalIds(
           complete: false,
           mappings: collapseMappings(mergeDiscoveredMappings(state.mappings, discoveredAfter)),
         };
-        await writeState(deps, state);
+        await publishState(deps, state);
       }
       throw new Error("Entity canonical-id migration mappings changed while migration was running; retry migration.");
     }