@remnic/core 9.45.2 → 9.45.4

package/src/search/factory.ts

@@ -116,6 +116,11 @@ function qmdOptions(config: PluginConfig): QmdClientOptions {
   };
 }
 
+export function isSearchBackendEnabled(config: PluginConfig): boolean {
+  const backend = config.searchBackend ?? "qmd";
+  return backend !== "noop" && (backend !== "qmd" || resolveQmdCapabilities(config).qmd);
+}
+
 /**
  * Create a SearchBackend from plugin config.
  *
@@ -124,14 +129,9 @@ function qmdOptions(config: PluginConfig): QmdClientOptions {
  * - "qmd" (default) → QmdClient if qmdEnabled, else NoopSearchBackend
  */
 export function createSearchBackend(config: PluginConfig): SearchBackend {
+  if (!isSearchBackendEnabled(config)) return new NoopSearchBackend();
   const nonQmd = resolveNonQmdBackend(config);
   if (nonQmd) return nonQmd;
-
-  // Default: QMD — fall back to noop if qmdEnabled is false
-  if (!resolveQmdCapabilities(config).qmd) {
-    return new NoopSearchBackend();
-  }
-
   return new QmdClient(config.qmdCollection, config.qmdMaxResults, qmdOptions(config));
 }
 

package/src/search/port.ts

@@ -45,7 +45,7 @@ export interface SearchExecutionOptions {
 
 export function reportSearchDegradation(
   execution: SearchExecutionOptions | undefined,
-  degradation: SearchDegradation,
+  degradation: SearchDegradation
 ): void {
   try {
     execution?.onDegradation?.(degradation);
@@ -56,7 +56,7 @@ export function reportSearchDegradation(
 
 export function resolveEnsureCollectionArgs(
   collectionOrExecution?: string | SearchExecutionOptions,
-  execution?: SearchExecutionOptions,
+  execution?: SearchExecutionOptions
 ): { collection?: string; execution?: SearchExecutionOptions } {
   if (typeof collectionOrExecution === "string") {
     return { collection: collectionOrExecution, execution };
@@ -108,26 +108,26 @@ export interface SearchBackend {
     collection?: string,
     maxResults?: number,
     options?: SearchQueryOptions,
-    execution?: SearchExecutionOptions,
+    execution?: SearchExecutionOptions
   ): Promise<SearchResult[]>;
   searchGlobal(query: string, maxResults?: number, execution?: SearchExecutionOptions): Promise<SearchResult[]>;
   bm25Search(
     query: string,
     collection?: string,
     maxResults?: number,
-    execution?: SearchExecutionOptions,
+    execution?: SearchExecutionOptions
   ): Promise<SearchResult[]>;
   vectorSearch(
     query: string,
     collection?: string,
     maxResults?: number,
-    execution?: SearchExecutionOptions,
+    execution?: SearchExecutionOptions
   ): Promise<SearchResult[]>;
   hybridSearch(
     query: string,
     collection?: string,
     maxResults?: number,
-    execution?: SearchExecutionOptions,
+    execution?: SearchExecutionOptions
   ): Promise<SearchResult[]>;
 
   // ── Maintenance ──
@@ -177,6 +177,22 @@ export interface SearchBackend {
   embedCollectionStrict?(collection: string): Promise<void>;
 
   // ── Collection management ──
+  /**
+   * True only when the backend can bind, isolate, search, and delete collections
+   * outside Remnic's primary memory roots.
+   */
+  supportsAdditionalCollections?(): boolean;
+  /**
+   * Prevent a collection from participating in unscoped/global searches.
+   * Dedicated corpora must call this immediately after collection creation.
+   */
+  excludeCollectionFromGlobalSearch?(collection: string, execution?: SearchExecutionOptions): Promise<void>;
+  /** Remove a non-primary collection and its backend-owned index state. */
+  deleteCollection?(collection: string, execution?: SearchExecutionOptions): Promise<boolean>;
+  /** Canonical source root currently bound to a named collection. */
+  collectionRoot?(collection: string, execution?: SearchExecutionOptions): Promise<string | null>;
+  /** Collection-scoped status for observability surfaces. */
+  collectionStatus?(collection: string): Promise<Pick<SearchBackendStatus, "totalFiles">>;
   /**
    * Optional non-mutating collection probe. Backends that can distinguish a
    * missing collection from a transient probe failure should implement this so
@@ -184,15 +200,15 @@ export interface SearchBackend {
    */
   checkCollection?(
     collectionOrExecution?: string | SearchExecutionOptions,
-    execution?: SearchExecutionOptions,
+    execution?: SearchExecutionOptions
   ): Promise<"present" | "missing" | "unknown" | "skipped">;
   ensureCollection(
     memoryDir: string,
-    execution?: SearchExecutionOptions,
+    execution?: SearchExecutionOptions
   ): Promise<"present" | "missing" | "unknown" | "skipped">;
   ensureCollection(
     memoryDir: string,
     collection?: string,
-    execution?: SearchExecutionOptions,
+    execution?: SearchExecutionOptions
   ): Promise<"present" | "missing" | "unknown" | "skipped">;
 }

package/src/secure-store/secure-fs.ts

@@ -132,6 +132,20 @@ export function isEncryptedFile(buf: Uint8Array): boolean {
   return b.subarray(0, MAGIC_BYTES.length).equals(MAGIC_BYTES);
 }
 
+type PositionedFileReader = {
+  read: (buffer: Buffer, offset: number, length: number, position: number) => Promise<{ bytesRead: number }>;
+};
+
+async function readPositionedPrefix(handle: PositionedFileReader, buffer: Buffer): Promise<number> {
+  let bytesRead = 0;
+  while (bytesRead < buffer.length) {
+    const result = await handle.read(buffer, bytesRead, buffer.length - bytesRead, bytesRead);
+    if (result.bytesRead === 0) break;
+    bytesRead += result.bytesRead;
+  }
+  return bytesRead;
+}
+
 /**
  * True when the REGULAR file at `probePath` is encrypted at rest (its first
  * bytes are the REMNIC-ENC magic header). ENOENT resolves to false — an absent
@@ -153,14 +167,14 @@ export async function probeEncryptedRegularFileHeader(probePath: string): Promis
   }
   if (!entryStat.isFile()) {
     throw new Error(
-      `refusing to probe non-regular state path ${probePath} `
-      + `(symlink/FIFO/device); opening it could block or escape containment (#2033)`,
+      `refusing to probe non-regular state path ${probePath} ` +
+        `(symlink/FIFO/device); opening it could block or escape containment (#2033)`
     );
   }
   const handle = await openFile(probePath, "r");
   try {
     const header = Buffer.alloc(MAGIC_HEADER_SIZE);
-    const { bytesRead } = await handle.read(header, 0, header.length, 0);
+    const bytesRead = await readPositionedPrefix(handle, header);
     return isEncryptedFile(header.subarray(0, bytesRead));
   } finally {
     await handle.close();
@@ -431,7 +445,7 @@ export async function* readMaybeEncryptedFileFromChunks(
   const headerSize = MAGIC_HEADER_SIZE + ENVELOPE_HEADER_SIZE;
   try {
     const prefix = Buffer.alloc(headerSize);
-    const { bytesRead: prefixBytes } = await handle.read(prefix, 0, prefix.length, 0);
+    const prefixBytes = await readPositionedPrefix(handle, prefix);
     const prefixView = prefix.subarray(0, prefixBytes);
     if (!isEncryptedFile(prefixView)) {
       if (prefixBytes > 0) yield Buffer.from(prefixView);
@@ -459,15 +473,9 @@ export async function* readMaybeEncryptedFileFromChunks(
     if (version !== ENVELOPE_VERSION) {
       throw new Error(`secure-store: unsupported envelope version ${version}`);
     }
-    const salt = envelope.subarray(
-      ENVELOPE_LAYOUT.salt,
-      ENVELOPE_LAYOUT.salt + ENVELOPE_SALT_LENGTH
-    );
+    const salt = envelope.subarray(ENVELOPE_LAYOUT.salt, ENVELOPE_LAYOUT.salt + ENVELOPE_SALT_LENGTH);
     const iv = envelope.subarray(ENVELOPE_LAYOUT.iv, ENVELOPE_LAYOUT.iv + IV_LENGTH);
-    const authTag = envelope.subarray(
-      ENVELOPE_LAYOUT.authTag,
-      ENVELOPE_LAYOUT.authTag + AUTH_TAG_LENGTH
-    );
+    const authTag = envelope.subarray(ENVELOPE_LAYOUT.authTag, ENVELOPE_LAYOUT.authTag + AUTH_TAG_LENGTH);
     const decipher = createDecipheriv("aes-256-gcm", key, iv, { authTagLength: AUTH_TAG_LENGTH });
     decipher.setAAD(Buffer.concat([buildHeaderAad(salt), filePathAad(filePath, memoryDir)]));
     decipher.setAuthTag(authTag);

package/src/secure-store/secure-store.test.ts

@@ -15,7 +15,7 @@
  */
 
 import assert from "node:assert/strict";
-import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, open as openFile, readFile, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { PassThrough } from "node:stream";
@@ -77,6 +77,7 @@ import {
   migrateMemoryDirToEncrypted,
   probeEncryptedRegularFileHeader,
   readMaybeEncryptedFile,
+  readMaybeEncryptedFileFromChunks,
 } from "./secure-fs.js";
 
 /** Cheap scrypt params for tests — still hex-correct but ~milliseconds. */
@@ -965,6 +966,44 @@ test("secure-store migration encrypts memory category dirs but leaves the questi
   }
 });
 
+test("chunked encrypted reads fill the header across positioned short reads", async () => {
+  const dir = await mkdtemp(path.join(tmpdir(), "remnic-chunked-header-"));
+  const filePath = path.join(dir, "encrypted.md");
+  const key = Buffer.alloc(32, 9);
+  const plaintext = Buffer.from("streamed encrypted content survives short header reads");
+  await writeFile(filePath, encryptFileBody(plaintext, key, filePathAad(filePath, dir)));
+
+  const probeHandle = await openFile(filePath, "r");
+  type PositionedRead = (
+    buffer: Buffer,
+    offset: number,
+    length: number,
+    position: number | null
+  ) => Promise<{ bytesRead: number; buffer: Buffer }>;
+  const handlePrototype = Object.getPrototypeOf(probeHandle) as { read: PositionedRead };
+  const originalRead = handlePrototype.read;
+  await probeHandle.close();
+  let shortReadsRemaining = 3;
+  handlePrototype.read = async function (buffer, offset, length, position) {
+    const boundedLength = shortReadsRemaining > 0 ? Math.min(length, 4) : length;
+    shortReadsRemaining -= 1;
+    return await originalRead.call(this, buffer, offset, boundedLength, position);
+  };
+
+  try {
+    assert.equal(await probeEncryptedRegularFileHeader(filePath), true);
+    shortReadsRemaining = 3;
+    const chunks: Buffer[] = [];
+    for await (const chunk of readMaybeEncryptedFileFromChunks(filePath, key, dir, 11)) {
+      chunks.push(chunk);
+    }
+    assert.deepEqual(Buffer.concat(chunks), plaintext);
+  } finally {
+    handlePrototype.read = originalRead;
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test("probeEncryptedRegularFileHeader detects encryption, treats absent as false, and refuses non-regular paths (#2033)", async () => {
   const dir = await mkdtemp(path.join(tmpdir(), "remnic-probe-header-"));
   try {
@@ -994,7 +1033,7 @@ test("probeEncryptedRegularFileHeader detects encryption, treats absent as false
         assert.match(message, /symlink\/FIFO\/device/);
         assert.ok(message.includes(linkPath));
         return true;
-      },
+      }
     );
 
     // A directory is likewise non-regular and refused.

package/src/spaces/index.test.ts

@@ -1,14 +1,15 @@
 import assert from "node:assert/strict";
 import { spawn } from "node:child_process";
 import fs, { existsSync } from "node:fs";
-import { mkdir, mkdtemp, rm, utimes, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, utimes, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
 import { setTimeout as sleep } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
 
-import { createSpace, loadManifest } from "./index.js";
+import { withEntityCanonicalMutationLock } from "../storage/entity-canonical-id-lock.js";
+import { createSpace, loadManifest, pushToSpace, type SpacePushResult } from "./index.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(__dirname, "../../../..");
@@ -238,6 +239,64 @@ test("loadManifest persists bootstrap when manifest disappears between existence
   }
 });
 
+test("pushToSpace serializes entity-page batches with the target canonical mutation lock", async () => {
+  const baseDir = await mkdtemp(path.join(os.tmpdir(), "remnic-spaces-entity-lock-"));
+  const sourceDir = path.join(baseDir, "source");
+  const targetDir = path.join(baseDir, "target");
+  const entityRelativePath = path.join("entities", "serialized-project.md");
+  const sourceEntityPath = path.join(sourceDir, entityRelativePath);
+  const targetEntityPath = path.join(targetDir, entityRelativePath);
+  const entityBytes = Buffer.from(
+    "---\nid: serialized-project\n---\n\n# Serialized Project\n\n**Type:** project\n\nPush bytes.\n",
+    "utf8",
+  );
+  const lockHeld = Promise.withResolvers<void>();
+  const releaseLock = Promise.withResolvers<void>();
+  let lockPromise: Promise<void> | undefined;
+  let pushPromise: Promise<SpacePushResult> | undefined;
+
+  try {
+    const source = createSpace({ baseDir, name: "Source", kind: "project", memoryDir: sourceDir });
+    const target = createSpace({ baseDir, name: "Target", kind: "project", memoryDir: targetDir });
+    await mkdir(path.dirname(sourceEntityPath), { recursive: true });
+    await mkdir(path.join(targetDir, "state"), { recursive: true });
+    await writeFile(sourceEntityPath, entityBytes);
+
+    lockPromise = withEntityCanonicalMutationLock(path.join(targetDir, "state"), async () => {
+      lockHeld.resolve();
+      await releaseLock.promise;
+    });
+    await lockHeld.promise;
+
+    let pushFinished = false;
+    pushPromise = pushToSpace(source.id, target.id, { baseDir });
+    void pushPromise.then(
+      () => {
+        pushFinished = true;
+      },
+      () => {
+        pushFinished = true;
+      },
+    );
+    await new Promise<void>((resolve) => setImmediate(resolve));
+
+    assert.equal(pushFinished, false, "the push must not finish while the target entity lock is held");
+    assert.equal(existsSync(targetEntityPath), false, "the entity page must not land before lock release");
+
+    releaseLock.resolve();
+    await lockPromise;
+    const result = await pushPromise;
+
+    assert.equal(result.memoriesPushed, 1);
+    assert.deepEqual(await readFile(targetEntityPath), entityBytes);
+  } finally {
+    releaseLock.resolve();
+    await lockPromise?.catch(() => undefined);
+    await pushPromise?.catch(() => undefined);
+    await rm(baseDir, { recursive: true, force: true });
+  }
+});
+
 async function runSpaceChild(
   baseDir: string,
   name: string,

package/src/spaces/index.ts

@@ -22,6 +22,7 @@ import {
   repairContentAfterJournalMoveSync,
   requestEntityCanonicalIdReconcileSync,
 } from "../storage/entity-canonical-id-references.js";
+import { withRawEntityPageMutation } from "../storage/entity-canonical-id-lock.js";
 
 // Write-boundary journal cache for promoted copies (issue #2213).
 const historicalIdCache = new HistoricalEntityCanonicalIdCache();
@@ -637,11 +638,11 @@ export function switchSpace(spaceId: string, baseDir?: string): SpaceSwitchResul
 
 // ── Push / Pull ─────────────────────────────────────────────────────────────
 
-export function pushToSpace(
+export async function pushToSpace(
   sourceSpaceId: string,
   targetSpaceId: string,
   options?: { memoryIds?: string[]; force?: boolean; baseDir?: string }
-): SpacePushResult {
+): Promise<SpacePushResult> {
   const startTime = Date.now();
   const manifest = loadManifest(options?.baseDir);
 
@@ -651,7 +652,7 @@ export function pushToSpace(
   if (!source) throw new Error(`Source space "${sourceSpaceId}" not found`);
   if (!target) throw new Error(`Target space "${targetSpaceId}" not found`);
 
-  const result = copyMemories(source.memoryDir, target.memoryDir, {
+  const result = await copyMemories(source.memoryDir, target.memoryDir, {
     filterIds: options?.memoryIds,
     force: options?.force,
   });
@@ -675,11 +676,11 @@ export function pushToSpace(
   };
 }
 
-export function pullFromSpace(
+export async function pullFromSpace(
   sourceSpaceId: string,
   targetSpaceId: string,
   options?: { memoryIds?: string[]; force?: boolean; baseDir?: string }
-): SpacePullResult {
+): Promise<SpacePullResult> {
   const startTime = Date.now();
   const manifest = loadManifest(options?.baseDir);
 
@@ -689,7 +690,7 @@ export function pullFromSpace(
   if (!source) throw new Error(`Source space "${sourceSpaceId}" not found`);
   if (!target) throw new Error(`Target space "${targetSpaceId}" not found`);
 
-  const result = copyMemories(source.memoryDir, target.memoryDir, {
+  const result = await copyMemories(source.memoryDir, target.memoryDir, {
     filterIds: options?.memoryIds,
     force: options?.force,
   });
@@ -744,11 +745,11 @@ export function shareSpace(spaceId: string, members: string[], baseDir?: string)
 
 // ── Promote ──────────────────────────────────────────────────────────────────
 
-export function promoteSpace(
+export async function promoteSpace(
   sourceSpaceId: string,
   targetSpaceId: string,
   options?: { memoryIds?: string[]; force?: boolean; forceOverwrite?: boolean; baseDir?: string }
-): SpacePromoteResult {
+): Promise<SpacePromoteResult> {
   const startTime = Date.now();
   const manifest = loadManifest(options?.baseDir);
 
@@ -765,7 +766,7 @@ export function promoteSpace(
     }
   }
 
-  const result = copyMemories(source.memoryDir, target.memoryDir, {
+  const result = await copyMemories(source.memoryDir, target.memoryDir, {
     filterIds: options?.memoryIds,
     force: options?.forceOverwrite !== undefined ? options.forceOverwrite : (options?.force ?? false),
   });
@@ -791,11 +792,11 @@ export function promoteSpace(
 
 // ── Merge ────────────────────────────────────────────────────────────────────
 
-export function mergeSpaces(
+export async function mergeSpaces(
   sourceSpaceId: string,
   targetSpaceId: string,
   options?: { force?: boolean; baseDir?: string }
-): MergeResult {
+): Promise<MergeResult> {
   const startTime = Date.now();
   const manifest = loadManifest(options?.baseDir);
 
@@ -805,7 +806,7 @@ export function mergeSpaces(
   if (!source) throw new Error(`Source space "${sourceSpaceId}" not found`);
   if (!target) throw new Error(`Target space "${targetSpaceId}" not found`);
 
-  const result = copyMemories(source.memoryDir, target.memoryDir, {
+  const result = await copyMemories(source.memoryDir, target.memoryDir, {
     force: options?.force,
   });
 
@@ -855,15 +856,13 @@ interface CopyOptions {
   force?: boolean;
 }
 
-function copyMemories(
+type CopyResult = { merged: number; conflicts: ConflictEntry[]; skipped: number };
+
+async function copyMemories(
   sourceDir: string,
   targetDir: string,
   options?: CopyOptions
-): { merged: number; conflicts: ConflictEntry[]; skipped: number } {
-  let merged = 0;
-  const conflicts: ConflictEntry[] = [];
-  let skipped = 0;
-
+): Promise<CopyResult> {
   if (!fs.existsSync(sourceDir)) {
     return { merged: 0, conflicts: [], skipped: 0 };
   }
@@ -891,6 +890,33 @@ function copyMemories(
       })
       .map((p) => path.basename(p, ".md")),
   );
+  const firstEntityId = sourceEntityIds.values().next().value;
+  if (firstEntityId === undefined) {
+    return copyPreparedMemories(sourceFiles, sourceRoot, targetRoot, sourceEntityIds, options);
+  }
+  return withRawEntityPageMutation(
+    targetRoot,
+    path.join(targetRoot, "entities", `${firstEntityId}.md`),
+    async () => copyPreparedMemories(
+      sourceFiles,
+      sourceRoot,
+      targetRoot,
+      sourceEntityIds,
+      options,
+    ),
+  );
+}
+
+function copyPreparedMemories(
+  sourceFiles: string[],
+  sourceRoot: string,
+  targetRoot: string,
+  sourceEntityIds: ReadonlySet<string>,
+  options?: CopyOptions,
+): CopyResult {
+  let merged = 0;
+  const conflicts: ConflictEntry[] = [];
+  let skipped = 0;
   // 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,

package/src/storage/entity-alias-config.ts

@@ -0,0 +1,97 @@
+import {
+  closeSync,
+  constants,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+} from "node:fs";
+import path from "node:path";
+
+import { isErrnoCode } from "../utils/errno.js";
+import { assertPathInsideRoot } from "../utils/path-containment.js";
+
+function resolveSafeAliasRoots(baseDir: string, configDir: string): string | undefined {
+  let baseStat;
+  try {
+    baseStat = lstatSync(baseDir);
+  } catch (error) {
+    if (isErrnoCode(error, "ENOENT")) return undefined;
+    throw error;
+  }
+  if (baseStat.isSymbolicLink() || !baseStat.isDirectory()) {
+    throw new Error(`Refusing unsafe entity alias memory root: ${baseDir}.`);
+  }
+
+  let configStat;
+  try {
+    configStat = lstatSync(configDir);
+  } catch (error) {
+    if (isErrnoCode(error, "ENOENT")) return undefined;
+    throw error;
+  }
+  if (configStat.isSymbolicLink() || !configStat.isDirectory()) {
+    throw new Error(`Refusing unsafe entity alias config root: ${configDir}.`);
+  }
+
+  const memoryRoot = realpathSync(baseDir);
+  assertPathInsideRoot(memoryRoot, realpathSync(configDir), configDir);
+  return memoryRoot;
+}
+
+export function readEntityAliasConfigSync(baseDir: string): string | undefined {
+  const configDir = path.join(baseDir, "config");
+  const aliasPath = path.join(configDir, "aliases.json");
+  let memoryRoot = resolveSafeAliasRoots(baseDir, configDir);
+  if (memoryRoot === undefined) return undefined;
+
+  let aliasPreflight;
+  try {
+    aliasPreflight = lstatSync(aliasPath);
+  } catch (error) {
+    if (isErrnoCode(error, "ENOENT")) return undefined;
+    throw error;
+  }
+  if (aliasPreflight.isSymbolicLink() || !aliasPreflight.isFile()) {
+    throw new Error(`Refusing unsafe entity alias config file: ${aliasPath}.`);
+  }
+
+  let fd: number;
+  try {
+    fd = openSync(
+      aliasPath,
+      constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0),
+    );
+  } catch (error) {
+    if (isErrnoCode(error, "ENOENT")) {
+      resolveSafeAliasRoots(baseDir, configDir);
+      return undefined;
+    }
+    if (isErrnoCode(error, "ELOOP")) {
+      throw new Error(`Refusing unsafe entity alias config file: ${aliasPath}.`);
+    }
+    throw error;
+  }
+  try {
+    const opened = fstatSync(fd);
+    memoryRoot = resolveSafeAliasRoots(baseDir, configDir);
+    if (memoryRoot === undefined) {
+      throw new Error(`Refusing unsafe entity alias config root: ${configDir}.`);
+    }
+    const aliasStat = lstatSync(aliasPath);
+    if (
+      !opened.isFile() ||
+      aliasStat.isSymbolicLink() ||
+      !aliasStat.isFile() ||
+      aliasStat.dev !== opened.dev ||
+      aliasStat.ino !== opened.ino
+    ) {
+      throw new Error(`Refusing unsafe entity alias config file: ${aliasPath}.`);
+    }
+    assertPathInsideRoot(memoryRoot, realpathSync(aliasPath), aliasPath);
+    return readFileSync(fd, "utf-8");
+  } finally {
+    closeSync(fd);
+  }
+}

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

@@ -1,33 +1,63 @@
-/**
- * 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 { appendFileSync, mkdirSync, realpathSync } from "node:fs";
 import path from "node:path";
-import { withHeldFileLock } from "../utils/serialize-mutations.js";
+import { invalidateForScope } from "../memory-cache.js";
+import { serializeMutations, 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>(
+export function isEntityPagePath(baseDir: string, filePath: string): boolean {
+  if (path.extname(filePath) !== ".md") return false;
+  const parentDir = path.dirname(path.resolve(filePath));
+  const entitiesDir = path.resolve(baseDir, "entities");
+  if (parentDir === entitiesDir) return true;
+  try {
+    return realpathSync(parentDir) === path.join(realpathSync(baseDir), "entities");
+  } catch {
+    return false;
+  }
+}
+
+function recordRawEntityMutation(baseDir: string, stateDir: string): void {
+  invalidateForScope(baseDir, "entity-write");
+  mkdirSync(stateDir, { recursive: true });
+  appendFileSync(path.join(stateDir, ".entity-mutation-version.log"), "x");
+}
+
+export 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());
-    },
+  const lockPath = path.join(stateDir, "entity-canonical-id-mutation.lock");
+  return serializeMutations(lockPath, () =>
+    withHeldFileLock(
+      lockPath,
+      {
+        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());
+      },
+    ),
   );
 }
+
+export async function withRawEntityPageMutation<T>(
+  baseDir: string,
+  filePath: string,
+  task: (refreshLock: () => Promise<boolean>) => Promise<T>,
+): Promise<T> {
+  if (!isEntityPagePath(baseDir, filePath)) {
+    return task(async () => true);
+  }
+  const stateDir = path.join(baseDir, "state");
+  return withEntityCanonicalMutationLock(stateDir, async (refreshLock) => {
+    try {
+      return await task(refreshLock);
+    } finally {
+      recordRawEntityMutation(baseDir, stateDir);
+    }
+  });
+}