@remnic/core 9.3.700 → 9.3.702

package/dist/{chunk-HDLC75NX.js → chunk-IX72AAMZ.js}

@@ -1,6 +1,6 @@
 import {
   StorageManager
-} from "./chunk-X74FJSW7.js";
+} from "./chunk-GFIARMA7.js";
 
 // src/semantic-rule-promotion.ts
 import { createHash, randomUUID } from "crypto";
@@ -529,4 +529,4 @@ export {
   setSemanticRulePromotionTestHooks,
   promoteSemanticRuleFromMemory
 };
-//# sourceMappingURL=chunk-HDLC75NX.js.map
+//# sourceMappingURL=chunk-IX72AAMZ.js.map

package/dist/{chunk-DR2JTSLZ.js → chunk-JMA4RYRN.js}

@@ -1,12 +1,16 @@
 import {
   resolveDefaultNamespaceRoot,
   resolveNamespaceStorageRoot
-} from "./chunk-PQG4T5V3.js";
+} from "./chunk-64XXOQRW.js";
 import {
   namespaceIdentityFromToken,
   namespaceIdentityToken,
   normalizeNamespaceIdentity
 } from "./chunk-ZFXCQPNO.js";
+import {
+  MutationSerializer,
+  withHeldFileLock
+} from "./chunk-LTJAMRGI.js";
 import {
   displayErrorDetail
 } from "./chunk-6KYMPV2O.js";
@@ -19,19 +23,14 @@ import {
 
 // src/namespaces/catalog.ts
 import path from "path";
-import { randomUUID } from "crypto";
 import {
   appendFile,
   lstat,
   mkdir,
-  open,
   readdir,
   readFile,
   realpath,
   rename,
-  stat,
-  unlink,
-  utimes,
   writeFile
 } from "fs/promises";
 var NAMESPACE_KINDS = [
@@ -240,15 +239,16 @@ var NamespaceCatalog = class {
   stateDir;
   catalogPath;
   rebuildLockPath;
-  // 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".
-  lockOwnerId = randomUUID();
-  // Serialized write chain that recovers from rejection (CLAUDE.md rule #40)
-  // so a single failed append cannot permanently poison subsequent writes.
-  writeChain = 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).
+  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
@@ -1091,24 +1091,23 @@ var NamespaceCatalog = class {
    * 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),
@@ -1117,120 +1116,20 @@ var NamespaceCatalog = class {
    * caller uses `acquired` to run compute-only (rebuild) or DROP the append
    * (touch) when unlocked.
    */
-  async withHeldCatalogLock(fn) {
-    const acquired = await this.acquireRebuildLock();
-    let heartbeat;
-    if (acquired) {
-      heartbeat = setInterval(() => {
-        const now = /* @__PURE__ */ new Date();
-        utimes(this.rebuildLockPath, now, now).catch(() => void 0);
-      }, REBUILD_LOCK_HEARTBEAT_MS);
-      heartbeat.unref?.();
-    }
-    try {
-      return await fn(acquired);
-    } finally {
-      if (heartbeat) clearInterval(heartbeat);
-      if (acquired) {
-        try {
-          if (await this.rebuildLockHeldBySelf()) {
-            await unlink(this.rebuildLockPath);
-          }
-        } catch {
-        }
-      }
-    }
-  }
-  /** Try to acquire the rebuild lock; returns true if WE created it. */
-  async acquireRebuildLock() {
-    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 {
-          await handle.writeFile(
-            `${process.pid} ${this.lockOwnerId} ${(/* @__PURE__ */ new Date()).toISOString()}
-`,
-            "utf8"
-          );
-        } catch {
-        } finally {
-          await handle.close();
-        }
-        return true;
-      } catch (err) {
-        if (err?.code !== "EEXIST") {
-          return false;
-        }
-        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.
-   */
-  async breakStaleRebuildLock() {
-    let staleIdentity;
-    try {
-      const info = await stat(this.rebuildLockPath);
-      if (Date.now() - info.mtimeMs <= REBUILD_LOCK_STALE_MS) {
-        return;
-      }
-      staleIdentity = await readFile(this.rebuildLockPath, "utf8");
-    } catch {
-      return;
-    }
-    if (this.onBeforeBreakStaleUnlinkForTest) {
-      await this.onBeforeBreakStaleUnlinkForTest();
-    }
-    try {
-      const current = await readFile(this.rebuildLockPath, "utf8");
-      if (current !== staleIdentity) return;
-      const recheck = await stat(this.rebuildLockPath);
-      if (Date.now() - recheck.mtimeMs <= REBUILD_LOCK_STALE_MS) return;
-      await unlink(this.rebuildLockPath).catch(() => void 0);
-    } catch {
-    }
-  }
-  /**
-   * 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.
-   */
-  async rebuildLockHeldBySelf() {
-    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];
-      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;
-      }
-      return Number.isFinite(pid) && pid === process.pid;
-    } catch {
-      return false;
-    }
+  withHeldCatalogLock(fn) {
+    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
+    );
   }
   /**
    * Merge a prior record's preserved metadata (timestamps, principal hints)
@@ -1288,20 +1187,20 @@ var NamespaceCatalog = class {
   }
   /**
    * 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).
    */
   queueCritical(fn) {
-    const run = this.writeChain.then(fn);
-    this.writeChain = run.then(
-      () => void 0,
-      () => void 0
-    );
-    return run;
+    return this.criticalSection.serialize("catalog", fn);
   }
   /**
    * Append a single record to the JSONL log WITHOUT re-serializing through the
@@ -1336,14 +1235,14 @@ function isPathInside(root, child) {
 }
 
 // src/maintenance/namespace-planner.ts
-import { createHash, randomUUID as randomUUID2 } from "crypto";
-import { lstat as lstat2, mkdir as mkdir2, open as open2, readFile as readFile2, readdir as readdir2, rename as rename2, rm, rmdir, utimes as utimes2, writeFile as writeFile2 } from "fs/promises";
+import { createHash, randomUUID } from "crypto";
+import { lstat as lstat2, mkdir as mkdir2, open, readFile as readFile2, readdir as readdir2, rename as rename2, rm, rmdir, utimes, writeFile as writeFile2 } from "fs/promises";
 import path2 from "path";
 var DEFAULT_MAX_NAMESPACES_PER_CYCLE = 20;
 var DEFAULT_LOCK_STALE_MS = 10 * 6e4;
 var LOCK_BASE = "maintenance-locks";
 var STATUS_BASE = "namespace-maintenance-status";
-var namespaceMaintenanceFs = { open: open2, rm };
+var namespaceMaintenanceFs = { open, rm };
 function configuredNamespaces(config) {
   return Array.from(
     new Set(
@@ -1589,7 +1488,7 @@ async function tryAcquireNamespaceMaintenanceLock(config, jobName, namespace) {
   const filePath = lockPath(config, jobName, namespace);
   await mkdir2(path2.dirname(filePath), { recursive: true });
   try {
-    const lockId = randomUUID2();
+    const lockId = randomUUID();
     await mkdir2(filePath);
     const ownerPath = path2.join(filePath, `${lockId}.json`);
     let handle;
@@ -1620,8 +1519,8 @@ async function tryAcquireNamespaceMaintenanceLock(config, jobName, namespace) {
           const parsed = JSON.parse(await readFile2(ownerPath, "utf8"));
           if (parsed.lockId === lockId) {
             const now = /* @__PURE__ */ new Date();
-            await utimes2(ownerPath, now, now);
-            await utimes2(filePath, now, now);
+            await utimes(ownerPath, now, now);
+            await utimes(filePath, now, now);
           }
         } catch {
         }
@@ -2051,4 +1950,4 @@ export {
   runNamespaceMaintenancePlan,
   runNamespaceMaintenanceBatchPlan
 };
-//# sourceMappingURL=chunk-DR2JTSLZ.js.map
+//# sourceMappingURL=chunk-JMA4RYRN.js.map