@remnic/core 9.3.700 → 9.3.701

package/src/namespaces/catalog.test.ts

@@ -11,6 +11,7 @@ import {
   resolveDefaultNamespaceRoot,
   resolveNamespaceStorageRoot,
 } from "./storage.js";
+import { withHeldFileLock } from "../utils/serialize-mutations.js";
 
 function makeConfig(memoryDir: string, overrides: Partial<PluginConfig> = {}): PluginConfig {
   return {
@@ -2171,8 +2172,16 @@ test("registerConfiguredNamespaces skips an unsafe configured name without abort
 
 // ── Round 7 (codex P2 — NBsGP): two catalog instances in the SAME process
 // sharing a memoryDir must not treat each other's rebuild lock as self-held. A
-// touch on instance B must DROP its append while instance A holds the lock,
-// instead of skipping the wait (same PID) and appending into A's window.
+// touch on instance B must DROP its append while a foreign lock is held,
+// instead of skipping the wait (same PID) and appending into the holder's
+// window.
+//
+// Issue #1524 note: the catalog now delegates to the shared withHeldFileLock
+// utility, which generates a per-CALL owner uuid (stronger than the previous
+// per-instance lockOwnerId). ANY foreign lock — including one written by
+// another call on the SAME instance — is therefore not self-held. The test
+// seeds a foreign lock with an arbitrary uuid + a heartbeat that keeps it
+// fresh, then asserts a touch on a fresh instance waits then DROPS.
 test("a same-process second instance does not treat another instance's lock as self-held", async () => {
   const memoryDir = await mkMemoryDir();
   try {
@@ -2183,10 +2192,12 @@ test("a same-process second instance does not treat another instance's lock as s
     await mkdir(stateDir, { recursive: true });
     const lockPath = path.join(stateDir, "namespaces.rebuild.lock");
 
-    // Instance A writes a lock with ITS OWN owner id (a UUID) — same PID as B.
-    const instanceA = new NamespaceCatalog(makeConfig(memoryDir));
-    const aOwnerId = (instanceA as unknown as { lockOwnerId: string }).lockOwnerId;
-    await writeFile(lockPath, `${process.pid} ${aOwnerId} ${new Date().toISOString()}\n`, "utf8");
+    // A foreign held lock: a different PID + a real UUID owner id (so it is
+    // NEVER mistaken for self by any catalog instance in any process) + a fresh
+    // mtime. A heartbeat keeps it fresh so it is never broken as stale during
+    // the touch's bounded wait.
+    const foreignOwner = "00000000-0000-4000-8000-000000000000";
+    await writeFile(lockPath, `999999 ${foreignOwner} ${new Date().toISOString()}\n`, "utf8");
     const hb = setInterval(() => {
       const now = new Date();
       utimes(lockPath, now, now).catch(() => undefined);
@@ -2194,17 +2205,17 @@ test("a same-process second instance does not treat another instance's lock as s
     hb.unref?.();
 
     try {
-      // Instance B (different owner id, same PID) must NOT consider A's lock
-      // self-held; its touch waits then DROPS on timeout (no append).
-      const instanceB = new NamespaceCatalog(makeConfig(memoryDir));
+      // The catalog instance must NOT consider the foreign lock self-held; its
+      // touch waits then DROPS on timeout (no append).
+      const instance = new NamespaceCatalog(makeConfig(memoryDir));
       const started = Date.now();
-      await instanceB.markWrite(ns, { discoveredBy: "write", storageDir: tokenDir });
+      await instance.markWrite(ns, { discoveredBy: "write", storageDir: tokenDir });
       const waited = Date.now() - started;
-      assert.ok(waited >= 4_000, "instance B must wait on instance A's lock, not skip it as self");
+      assert.ok(waited >= 4_000, "the catalog must wait on the foreign lock, not skip it as self");
       assert.equal(
-        await instanceB.getNamespaceRecord(ns),
+        await instance.getNamespaceRecord(ns),
         null,
-        "instance B's touch must DROP while instance A's lock is held (no overwrite race)",
+        "the touch must DROP while the foreign lock is held (no overwrite race)",
       );
     } finally {
       clearInterval(hb);
@@ -2609,6 +2620,98 @@ test("a dropped resolve registration (hook returns false) is retried on a later
   }
 });
 
+// ── In-flight dedup under a DROPPED hook (cursor Medium 06f58a7c, codex P2).
+// The serializer strictly orders queued tasks, but ordering alone does not
+// collapse a burst when the hook returns `false` (dropped registration, e.g. a
+// rebuild-lock timeout): `notifiedResolved` stays unset, so every queued sibling
+// task passes its re-check and re-invokes the hook — N serial lock waits. The
+// `inFlightResolveHooks` marker (set synchronously before queueing) collapses the
+// burst to a single hook invocation; the drop stays retryable on a LATER
+// storageFor(). This test PROVE-FAILS without the marker (calls === N) and PASSES
+// with it (calls === 1).
+test("a burst of concurrent storageFor() with a DROPPED hook fires it ONCE (not once per queued task)", async () => {
+  const memoryDir = await mkMemoryDir();
+  try {
+    let calls = 0;
+    // Gated hook that DROPS (returns false) once released. This is the real
+    // scenario the reviewers flagged: the catalog's onResolve waits on the
+    // rebuild lock (slow), times out, and returns false. While that hook is
+    // in-flight, a burst of cache hits must collapse to the one in-flight
+    // registration instead of each queueing its own serial lock wait.
+    let release!: () => void;
+    const gate = new Promise<void>((r) => {
+      release = r;
+    });
+    const router = new NamespaceStorageRouter(makeConfig(memoryDir), {
+      onResolve: async () => {
+        calls += 1;
+        await gate;
+        return false; // dropped (rebuild-lock timeout analogue)
+      },
+    });
+
+    // A burst of concurrent cache hits while the hook is IN-FLIGHT. Without the
+    // in-flight dedup marker each enqueued task would re-run the dropped hook
+    // once the first settles (N serial lock waits); with it they collapse.
+    const N = 8;
+    await Promise.all(Array.from({ length: N }, () => router.storageFor("project-origin-burst-drop")));
+    // Let the in-flight hook settle as DROPPED.
+    release();
+    await router.whenResolveHooksSettled();
+    assert.equal(calls, 1, "a dropped hook fires ONCE under a burst, not once per queued task");
+
+    // The drop must remain retryable: a later storageFor() re-fires the hook.
+    await router.storageFor("project-origin-burst-drop");
+    await router.whenResolveHooksSettled();
+    assert.equal(calls, 2, "a dropped registration is retried on the next storageFor()");
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+// ── Composite-key in-flight dedup (cursor Medium, codex P2): the in-flight
+// marker must be keyed by (namespace, storageDir), NOT namespace alone. A
+// CHANGED storageDir (migration/realignment) for the same namespace while
+// another dir's hook is pending must still get its OWN hook invocation — it is
+// not collapsed onto the old dir's pending registration. A namespace-only key
+// would silently drop the new-dir notification.
+test("a CHANGED storageDir for the same namespace is not collapsed onto a pending hook", async () => {
+  const memoryDir = await mkMemoryDir();
+  try {
+    const seen: string[] = [];
+    let release!: () => void;
+    const gate = new Promise<void>((r) => {
+      release = r;
+    });
+    const router = new NamespaceStorageRouter(makeConfig(memoryDir), {
+      onResolve: async (_ns, dir) => {
+        seen.push(dir);
+        await gate;
+      },
+    });
+    // notifyResolved is private; reach it via the same cast pattern other tests
+    // use for router internals, so we can drive two distinct dirs directly.
+    const internals = router as unknown as {
+      notifyResolved(namespace: string, storageDir: string): void;
+    };
+    const dirA = path.join(memoryDir, "dir-a");
+    const dirB = path.join(memoryDir, "dir-b");
+    // dirA's hook is IN-FLIGHT (gated). dirB is a DIFFERENT dir for the same
+    // namespace — it must NOT be collapsed onto dirA's pending registration.
+    internals.notifyResolved("project-origin-dir-change", dirA);
+    internals.notifyResolved("project-origin-dir-change", dirB);
+    release();
+    await router.whenResolveHooksSettled();
+    assert.deepEqual(
+      seen.sort(),
+      [dirA, dirB].sort(),
+      "both distinct dirs fire their own hook; the new dir is not collapsed onto the pending one",
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
 // ── Round 7 (codex P2 — NDxiS): a configured non-default namespace must be seeded
 // with the ROUTER-resolved root, not a blanket tokenized dir. When a legacy raw
 // root (`namespaces/<rawname>`) already exists, the router serves it, so the
@@ -2777,8 +2880,35 @@ class SeamCatalog extends NamespaceCatalog {
     (this as unknown as { onBeforeBreakStaleUnlinkForTest?: () => Promise<void> }).onBeforeBreakStaleUnlinkForTest =
       fn;
   }
+  /**
+   * Drive the catalog's break-stale path through the shared util (issue #1524
+   * adoption). The catalog no longer owns a private breakStaleRebuildLock; the
+   * util's breakStaleLock fires inside its acquire loop, which is what
+   * withHeldCatalogLock now invokes. We trigger that path with a SHORT maxWaitMs
+   * so a surviving replacement lock is observed quickly (the production
+   * REBUILD_LOCK_MAX_WAIT_MS would force a 5s wait on the NG7Bg-replacement
+   * case). The seam is forwarded exactly as production does.
+   */
   async callBreakStaleRebuildLock(): Promise<void> {
-    await (this as unknown as { breakStaleRebuildLock: () => Promise<void> }).breakStaleRebuildLock();
+    const seam = (this as unknown as { onBeforeBreakStaleUnlinkForTest?: () => Promise<void> })
+      .onBeforeBreakStaleUnlinkForTest;
+    // Match the catalog's lock config (stale/heartbeat/poll); only maxWaitMs
+    // is shortened for test speed. The break-stale invariant does not depend
+    // on maxWaitMs — the seam fires inside breakStaleLock regardless.
+    await withHeldFileLock(
+      (this as unknown as { rebuildLockPath: string }).rebuildLockPath,
+      {
+        staleMs: 30_000,
+        maxWaitMs: 200,
+        pollMs: 10,
+        heartbeatMs: 10_000,
+        onBeforeBreakStaleUnlinkForTest: seam,
+      },
+      async () => {
+        // No-op: we only need the acquire loop to invoke breakStaleLock so the
+        // seam fires and the replacement/stale-lock invariant is exercised.
+      },
+    );
   }
 }
 
@@ -3354,3 +3484,81 @@ test("listNamespaces prefers configured token owners over stale literal token al
     await rm(memoryDir, { recursive: true, force: true });
   }
 });
+
+// ── Issue #1524 adoption prove-fail: catalog mutations route through the
+// shared MutationSerializer (instance-scoped `criticalSection`). The defect
+// class is a naive bare-.then(fn) chain that silently drops subsequent sections
+// after a rejection — exactly the poison-chain bug the shared util prevents.
+// We force the FIRST serialized section to reject, then assert the SECOND
+// section STILL runs (its record lands in the catalog). Pre-fix (a poison
+// chain) the second section would be skipped.
+test("catalog queueCritical recovers after a prior section rejects (issue #1524 poison-chain prove-fail)", async () => {
+  const memoryDir = await mkMemoryDir();
+  try {
+    const catalog = new NamespaceCatalog(makeConfig(memoryDir));
+    // Reach the private serializer to inject a failing section ahead of a real
+    // one. Both target the SAME key ("catalog") so they share a chain.
+    const serializer = (catalog as unknown as {
+      criticalSection: {
+        serialize<T>(key: string, task: () => Promise<T>): Promise<T>;
+      };
+    }).criticalSection;
+
+    let secondRan = false;
+    const [, second] = await Promise.allSettled([
+      serializer.serialize("catalog", async () => {
+        throw new Error("intentional first-section failure");
+      }),
+      serializer.serialize("catalog", async () => {
+        secondRan = true;
+      }),
+    ]);
+    assert.equal(second.status, "fulfilled", "second section settled (ran or skipped?)");
+    assert.equal(secondRan, true, "second section MUST run after the first rejected (chain recovered)");
+    // And a real catalog op still works through the same chain after the failure.
+    await catalog.markWrite("project-origin-poison-recovery", { discoveredBy: "write" });
+    const record = await catalog.getNamespaceRecord("project-origin-poison-recovery");
+    assert.ok(record, "the catalog is fully usable after a rejected section (chain not poisoned)");
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+// ── Issue #1524 adoption prove-fail: NamespaceStorageRouter resolve-hooks
+// route through the shared MutationSerializer (`resolveSerializer`). Same
+// defect class — a poison chain would skip the second hook after the first
+// rejected. We fire two notifications for the SAME namespace; the first hook
+// rejects, the second MUST still run.
+test("router resolve-hook serializer recovers after a prior hook rejects (issue #1524 poison-chain prove-fail)", async () => {
+  const memoryDir = await mkMemoryDir();
+  try {
+    let secondCalls = 0;
+    let firstCalls = 0;
+    let rejectNext = true;
+    const router = new NamespaceStorageRouter(makeConfig(memoryDir), {
+      onResolve: async () => {
+        if (rejectNext) {
+          firstCalls += 1;
+          rejectNext = false;
+          throw new Error("intentional first-hook failure");
+        }
+        secondCalls += 1;
+      },
+    });
+    // Two storageFor calls for the same namespace. The first triggers the hook
+    // (which rejects); the second queues behind it through the serializer.
+    // Both calls themselves must resolve (the rejection is best-effort inside
+    // the hook wrapper, never surfaced to the storage caller).
+    await router.storageFor("project-origin-router-poison");
+    await router.whenResolveHooksSettled();
+    await router.storageFor("project-origin-router-poison");
+    await router.whenResolveHooksSettled();
+    assert.ok(firstCalls >= 1, "the first (rejecting) hook fired");
+    assert.ok(
+      secondCalls >= 1,
+      "the second hook MUST fire after the first rejected (serializer recovered, not poisoned)",
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});

package/src/namespaces/catalog.ts

@@ -1,21 +1,21 @@
 import path from "node:path";
-import { randomUUID } from "node:crypto";
 import type { Dirent } from "node:fs";
 import {
   appendFile,
   lstat,
   mkdir,
-  open,
   readdir,
   readFile,
   realpath,
   rename,
   stat,
-  unlink,
-  utimes,
   writeFile,
 } from "node:fs/promises";
 import type { PluginConfig } from "../types.js";
+import {
+  MutationSerializer,
+  withHeldFileLock,
+} from "../utils/serialize-mutations.js";
 import { isSafeRouteNamespace } from "../routing/engine.js";
 import { namespaceIdentityFromToken, namespaceIdentityToken, normalizeNamespaceIdentity } from "./identity.js";
 import { resolveDefaultNamespaceRoot, resolveNamespaceStorageRoot } from "./storage.js";
@@ -430,15 +430,16 @@ export class NamespaceCatalog {
   private readonly stateDir: string;
   private readonly catalogPath: string;
   private readonly rebuildLockPath: string;
-  // Per-INSTANCE lock owner id (round 6, codex P2 — NBsGP). The rebuild lock
-  // file records this id, not just `process.pid`, so two NamespaceCatalog
-  // instances in the SAME process sharing a memoryDir are NOT mistaken for each
-  // other: a touch on instance B must still wait for instance A's rebuild lock
-  // (different owner id, same PID) instead of skipping as "self-held".
-  private readonly lockOwnerId: string = randomUUID();
-  // Serialized write chain that recovers from rejection (CLAUDE.md rule #40)
-  // so a single failed append cannot permanently poison subsequent writes.
-  private writeChain: Promise<void> = Promise.resolve();
+  // In-process serialization for catalog mutations (issue #1524 adoption).
+  // Replaces the bespoke `writeChain` field: every touch/rebuild runs through
+  // this serializer so a single failed section never poisons subsequent ones
+  // (CLAUDE.md rule #40 — recovery is the util's contract, not re-implemented
+  // here). Cross-process identity (the lock file's owner-uuid) is now per-CALL
+  // inside the shared util, which is STRONGER than the previous per-instance
+  // `lockOwnerId` — two calls on the SAME instance get different ids, so
+  // neither mistakes the other's lock for self-held (round 6, codex P2 — NBsGP
+  // invariant preserved and tightened).
+  private readonly criticalSection = new MutationSerializer();
   // Test-only seam (round 7 — NEZkA): fires inside a touch's HELD-lock critical
   // section, after the lock is acquired but BEFORE the read→merge→append. A
   // deterministic concurrency test installs a hook here to widen the (otherwise
@@ -1826,24 +1827,23 @@ export class NamespaceCatalog {
    * their respective critical sections — closing the check-then-append gap where a
    * polled-only touch could append into a rebuild's load→rename window.
    *
-   * Acquisition is atomic via `open(..., "wx")`. A lock older than
-   * `REBUILD_LOCK_STALE_MS` is treated as a crashed holder and broken. After
-   * `REBUILD_LOCK_MAX_WAIT_MS` of contention we proceed best-effort WITHOUT the
-   * lock rather than block forever. The lock is always released in `finally`.
+   * Issue #1524 adoption: this is now a thin delegation to the shared
+   * `withHeldFileLock` utility. The acquire loop, mtime heartbeat, stale-break
+   * (NG7Bg replacement-safe), and ownership-checked release (NCzT6) all live in
+   * ONE place — the util — so this module no longer re-implements them. The
+   * catalog's `REBUILD_LOCK_*` constants and the `onBeforeBreakStaleUnlinkForTest`
+   * seam flow straight through. The util generates a per-CALL owner uuid, which
+   * is stricter than the previous per-instance `lockOwnerId` (two calls on the
+   * same instance get different ids, so neither mistakes the other's lock as
+   * self-held — the NBsGP invariant, preserved and tightened).
    *
    * IN-PROCESS SAFETY: every caller invokes this from inside (or wrapping) the
    * per-process `queueCritical` chain, which serializes all catalog mutations in
-   * THIS process. So within one process only one logical holder attempts OS-lock
-   * acquisition at a time — the file lock is never self-contended in-process, and
-   * the lock is acquired and released within a single in-process turn. The file
-   * lock adds only the missing CROSS-process exclusion.
-   *
-   * HEARTBEAT (round 5, cursor/codex Medium/P2): while WE hold the lock a timer
-   * refreshes its mtime every `REBUILD_LOCK_HEARTBEAT_MS`, so a legitimately long
-   * holder (> `REBUILD_LOCK_STALE_MS`) is not treated as a crashed holder and
-   * unlinked by another process — which would let overlapping windows lose
-   * appends. Heartbeat failures are swallowed; the timer is always cleared in
-   * `finally`.
+   * THIS process (now via `MutationSerializer`). So within one process only one
+   * logical holder attempts OS-lock acquisition at a time — the file lock is never
+   * self-contended in-process, and the lock is acquired and released within a
+   * single in-process turn. The file lock adds only the missing CROSS-process
+   * exclusion.
    *
    * ACQUISITION RESULT (round 6, codex P2 — NBPmY): `fn` receives whether WE
    * actually hold the lock. When acquisition TIMED OUT (another holder is active),
@@ -1852,152 +1852,20 @@ export class NamespaceCatalog {
    * caller uses `acquired` to run compute-only (rebuild) or DROP the append
    * (touch) when unlocked.
    */
-  private async withHeldCatalogLock<T>(fn: (acquired: boolean) => Promise<T>): Promise<T> {
-    const acquired = await this.acquireRebuildLock();
-    let heartbeat: ReturnType<typeof setInterval> | undefined;
-    if (acquired) {
-      heartbeat = setInterval(() => {
-        const now = new Date();
-        // Refresh mtime so age-based stale detection sees an active holder.
-        utimes(this.rebuildLockPath, now, now).catch(() => undefined);
-      }, REBUILD_LOCK_HEARTBEAT_MS);
-      // Don't keep the event loop alive solely for the heartbeat.
-      heartbeat.unref?.();
-    }
-    try {
-      return await fn(acquired);
-    } finally {
-      if (heartbeat) clearInterval(heartbeat);
-      if (acquired) {
-        try {
-          // Release ONLY the lock still owned by THIS instance (round 6, codex
-          // P2 — NCzT6). If this rebuild paused long enough that another process
-          // treated our lock as stale, unlinked it, and acquired a REPLACEMENT,
-          // an unconditional unlink here would delete that other holder's active
-          // lock — letting writers/another rebuild proceed during its load/rename
-          // window and recreating the lost-append race. Verify ownership first.
-          if (await this.rebuildLockHeldBySelf()) {
-            await unlink(this.rebuildLockPath);
-          }
-        } catch {
-          // Best-effort release; a stale lock will be broken on next rebuild.
-        }
-      }
-    }
-  }
-
-  /** Try to acquire the rebuild lock; returns true if WE created it. */
-  private async acquireRebuildLock(): Promise<boolean> {
-    const deadline = Date.now() + REBUILD_LOCK_MAX_WAIT_MS;
-    await mkdir(this.stateDir, { recursive: true });
-    for (;;) {
-      try {
-        const handle = await open(this.rebuildLockPath, "wx");
-        try {
-          // Record PID, this instance's owner id, and a timestamp. The owner id
-          // distinguishes same-process instances (NBsGP).
-          await handle.writeFile(
-            `${process.pid} ${this.lockOwnerId} ${new Date().toISOString()}\n`,
-            "utf8",
-          );
-        } catch {
-          // Ignore write failures — the exclusive create already gave us the lock.
-        } finally {
-          await handle.close();
-        }
-        return true;
-      } catch (err) {
-        if ((err as NodeJS.ErrnoException)?.code !== "EEXIST") {
-          // Unexpected FS error — proceed best-effort without the lock.
-          return false;
-        }
-        // Lock exists: break it if stale, otherwise wait briefly.
-        await this.breakStaleRebuildLock();
-        if (Date.now() >= deadline) return false;
-        await new Promise((r) => setTimeout(r, REBUILD_LOCK_POLL_MS));
-      }
-    }
-  }
-
-  /**
-   * Remove the lock file if its mtime is older than the stale threshold.
-   *
-   * REPLACEMENT-SAFE (NG7Bg, codex P2): a plain `stat` → `unlink` has a TOCTOU
-   * window — two processes can both observe the SAME stale lock; one removes it and
-   * creates a FRESH lock, and the other's later `unlink` then deletes that fresh
-   * holder's ACTIVE lock based on the stale identity it read earlier, leaving the
-   * fresh holder running its critical section with no visible lock and reopening the
-   * lost-update race the mutex prevents. We therefore capture the lock's IDENTITY
-   * (its full content line: `<pid> <owner-uuid> <iso>`) when we judge it stale, then
-   * RE-READ immediately before unlinking and only remove it when the content is
-   * byte-identical AND still stale. A replacement lock has a different owner id /
-   * timestamp, so its content differs and we leave it untouched. We never unlink a
-   * lock whose mtime is now fresh (a heartbeat refreshed it) or whose identity
-   * changed (a replacement was created). This is best-effort: any mismatch/vanish
-   * simply skips the break and the caller polls again.
-   */
-  private async breakStaleRebuildLock(): Promise<void> {
-    let staleIdentity: string;
-    try {
-      const info = await stat(this.rebuildLockPath);
-      if (Date.now() - info.mtimeMs <= REBUILD_LOCK_STALE_MS) {
-        // Not stale (e.g. a live holder's heartbeat keeps it fresh) — leave it.
-        return;
-      }
-      // Capture the exact identity we judged stale, so we can confirm it has not
-      // been replaced before we unlink.
-      staleIdentity = await readFile(this.rebuildLockPath, "utf8");
-    } catch {
-      // Lock vanished (released by holder) or stat/read failed — nothing to do.
-      return;
-    }
-    // Test-only seam: simulate a replacement lock being created in the race window
-    // between the staleness judgment and the unlink (NG7Bg). No-op in production.
-    if (this.onBeforeBreakStaleUnlinkForTest) {
-      await this.onBeforeBreakStaleUnlinkForTest();
-    }
-    try {
-      // Re-validate immediately before unlinking: the lock must still carry the
-      // SAME identity AND still be stale. If a replacement lock was created in the
-      // window (different owner/timestamp) or a heartbeat refreshed the mtime, do
-      // NOT unlink — that would delete another process's ACTIVE lock.
-      const current = await readFile(this.rebuildLockPath, "utf8");
-      if (current !== staleIdentity) return; // replaced — leave the fresh lock
-      const recheck = await stat(this.rebuildLockPath);
-      if (Date.now() - recheck.mtimeMs <= REBUILD_LOCK_STALE_MS) return; // refreshed
-      await unlink(this.rebuildLockPath).catch(() => undefined);
-    } catch {
-      // The lock changed/vanished between checks — another process handled it.
-    }
-  }
-
-  /**
-   * Whether the rebuild lock file was written by THIS instance (round 6, codex
-   * P2 — NBsGP). Matches the per-instance owner id, NOT just `process.pid`: two
-   * NamespaceCatalog instances in the same process share a PID, so a PID-only
-   * check would wrongly treat instance A's lock as self-held by instance B and
-   * let B's touch skip the wait and append into A's rebuild window. Falls back to
-   * the legacy PID-only form for lock files written before owner ids existed.
-   */
-  private async rebuildLockHeldBySelf(): Promise<boolean> {
-    try {
-      const body = await readFile(this.rebuildLockPath, "utf8");
-      const parts = body.trim().split(/\s+/);
-      const pid = Number.parseInt(parts[0] ?? "", 10);
-      const ownerId = parts[1];
-      // New format: "<pid> <uuid> <iso>". A UUID at parts[1] uniquely identifies
-      // the writing INSTANCE; only the same instance is self. The strict UUID
-      // shape avoids mistaking a legacy "<pid> <iso>" timestamp (also hyphenated)
-      // for an owner id.
-      const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-      if (ownerId && UUID_RE.test(ownerId)) {
-        return ownerId === this.lockOwnerId;
-      }
-      // Legacy format: "<pid> <iso>" (no owner id). Best-effort PID match.
-      return Number.isFinite(pid) && pid === process.pid;
-    } catch {
-      return false;
-    }
+  private withHeldCatalogLock<T>(fn: (acquired: boolean) => Promise<T>): Promise<T> {
+    return withHeldFileLock(
+      this.rebuildLockPath,
+      {
+        staleMs: REBUILD_LOCK_STALE_MS,
+        maxWaitMs: REBUILD_LOCK_MAX_WAIT_MS,
+        pollMs: REBUILD_LOCK_POLL_MS,
+        heartbeatMs: REBUILD_LOCK_HEARTBEAT_MS,
+        // NG7Bg seam: fires inside the util's breakStaleLock after it judges the
+        // lock stale and captures its identity, before the atomic rename+verify.
+        onBeforeBreakStaleUnlinkForTest: this.onBeforeBreakStaleUnlinkForTest,
+      },
+      fn,
+    );
   }
 
   /**
@@ -2071,21 +1939,20 @@ export class NamespaceCatalog {
 
   /**
    * Serialize an arbitrary read-modify-write critical section through the single
-   * write chain. Every catalog mutation (touch read+merge+append, full rewrite)
-   * runs through this so they are mutually exclusive: a touch always reads the
-   * latest persisted state before appending, and a rebuild rewrite cannot
-   * interleave with a touch's append. The chain recovers from rejection
-   * (CLAUDE.md rule #40) — one failed section never poisons subsequent ones —
-   * while still surfacing the error to that section's awaited promise.
+   * per-instance chain. Every catalog mutation (touch read+merge+append, full
+   * rewrite) runs through this so they are mutually exclusive: a touch always
+   * reads the latest persisted state before appending, and a rebuild rewrite
+   * cannot interleave with a touch's append.
+   *
+   * Issue #1524 adoption: delegates to the shared `MutationSerializer` (stored
+   * as `criticalSection`). The util owns the rejection-recovery invariant
+   * (CLAUDE.md rule #40 — one failed section never poisons subsequent ones, but
+   * the failing section's error still surfaces to ITS awaited promise) and the
+   * no-unbounded-growth cleanup. The key is constant: the catalog has ONE
+   * logical mutation queue (touches and rebuilds mutually exclude in-process).
    */
   private queueCritical<T>(fn: () => Promise<T>): Promise<T> {
-    const run = this.writeChain.then(fn);
-    // Keep the chain alive after a rejection so later sections still run.
-    this.writeChain = run.then(
-      () => undefined,
-      () => undefined,
-    );
-    return run;
+    return this.criticalSection.serialize("catalog", fn);
   }
 
   /**