@remnic/core 10.0.63 → 10.0.64

package/src/orchestrator-flush.test.ts

@@ -13,6 +13,7 @@ import { SmartBuffer } from "./buffer.js";
 import { parseConfig } from "./config.js";
 import { stableHash } from "./coding/git-context.js";
 import type { BufferState, BufferTurn, PluginConfig } from "./types.js";
+import type { MetaState } from "./types.js";
 import type { ImportTurn } from "./bulk-import/types.js";
 import type { LcmEngine } from "./lcm/index.js";
 import type { ExtractionRunResult } from "./orchestration/extraction-run.js";
@@ -20,6 +21,24 @@ import { namespaceIdentityToken } from "./namespaces/identity.js";
 import { readNamespaceMaintenanceStatuses } from "./maintenance/namespace-planner.js";
 import { stubPersistExtraction } from "./testing/orchestrator-lite.js";
 
+/** Adds the `updateMeta` seam to a StorageManager stub that only has loadMeta/saveMeta. */
+function withMetaSeam<S extends { loadMeta: () => Promise<MetaState>; saveMeta: (meta: MetaState) => Promise<void> }>(
+  storage: S,
+): S & { updateMeta: (mutate: (meta: MetaState) => boolean | void | Promise<boolean | void>) => Promise<void> } {
+  // SAFETY: the constraint above declares exactly the loadMeta/saveMeta shape every
+  // stub here provides; re-typing to `S & { updateMeta }` adds one member and keeps
+  // all other members of S unchanged.
+  const updatable = storage as S & {
+    updateMeta: (mutate: (meta: MetaState) => boolean | void | Promise<boolean | void>) => Promise<void>;
+  };
+  updatable.updateMeta = async (mutate) => {
+    const meta = await storage.loadMeta();
+    if ((await mutate(meta)) === false) return;
+    await storage.saveMeta(meta);
+  };
+  return updatable;
+}
+
 function makeTurn(sessionKey: string, content: string, sessionOwnerPrincipal?: string): BufferTurn {
   return {
     role: "user",
@@ -1525,7 +1544,7 @@ test("runExtraction writes buffered turns to active scope profile write layer",
   orchestrator.storageRouter = {
     storageFor: async (namespace: string) => {
       requestedNamespace = namespace;
-      return {
+      return withMetaSeam({
         listEntityNames: async () => [],
         loadMeta: async () => ({
           extractionCount: 0,
@@ -1541,7 +1560,7 @@ test("runExtraction writes buffered turns to active scope profile write layer",
           ],
         }),
         saveMeta: async () => undefined,
-      };
+      });
     },
   };
   orchestrator.extraction = {
@@ -1570,7 +1589,7 @@ test("runExtraction skips batches whose persisted fingerprint already exists in
     },
   };
   orchestrator.storageRouter = {
-    storageFor: async () => ({
+    storageFor: async () => withMetaSeam({
       listEntityNames: async () => [],
       loadMeta: async () => ({
         extractionCount: 0,
@@ -1651,7 +1670,7 @@ test("runExtraction fails closed on invalid extraction results when required", a
       },
     };
     orchestrator.storageRouter = {
-      storageFor: async () => ({
+      storageFor: async () => withMetaSeam({
         listEntityNames: async () => [],
         loadMeta: async () => ({
           extractionCount: 0,
@@ -1689,18 +1708,7 @@ test("runExtraction persists processed fingerprints for empty extraction results
 
   let clearCalls = 0;
   let saveMetaCalls = 0;
-  let savedMeta:
-    | {
-        extractionCount: number;
-        lastExtractionAt: string | null;
-        totalMemories: number;
-        totalEntities: number;
-        processedExtractionFingerprints: Array<{
-          fingerprint: string;
-          observedAt: string;
-        }>;
-      }
-    | undefined;
+  let savedMeta: MetaState | undefined;
 
   const meta = {
     extractionCount: 0,
@@ -1722,10 +1730,10 @@ test("runExtraction persists processed fingerprints for empty extraction results
     },
   };
   orchestrator.storageRouter = {
-    storageFor: async () => ({
+    storageFor: async () => withMetaSeam({
       listEntityNames: async () => [],
       loadMeta: async () => meta,
-      saveMeta: async (nextMeta: typeof meta) => {
+      saveMeta: async (nextMeta: MetaState) => {
         saveMetaCalls += 1;
         savedMeta = structuredClone(nextMeta);
       },
@@ -1762,9 +1770,9 @@ test("runExtraction persists processed fingerprints for empty extraction results
   assert.equal(savedMeta?.extractionCount, 1);
   assert.equal(savedMeta?.totalMemories, 0);
   assert.equal(savedMeta?.totalEntities, 0);
-  assert.equal(savedMeta?.processedExtractionFingerprints.length, 1);
+  assert.equal(savedMeta?.processedExtractionFingerprints?.length, 1);
   assert.equal(
-    savedMeta?.processedExtractionFingerprints[0]?.fingerprint,
+    savedMeta?.processedExtractionFingerprints?.[0]?.fingerprint,
     orchestrator.buildExtractionFingerprint(turns, "logical-thread:empty"),
   );
 });
@@ -1797,7 +1805,7 @@ test("runExtraction does not persist processed fingerprints for failed empty ext
     },
   };
   orchestrator.storageRouter = {
-    storageFor: async () => ({
+    storageFor: async () => withMetaSeam({
       listEntityNames: async () => [],
       loadMeta: async () => meta,
       saveMeta: async () => {
@@ -1853,7 +1861,7 @@ test("runExtraction clears the buffer on a failed extraction when extractionRetr
   orchestrator.config = config;
   orchestrator.buffer = { clearAfterExtraction: async () => { clearCalls += 1; } };
   orchestrator.storageRouter = {
-    storageFor: async () => ({
+    storageFor: async () => withMetaSeam({
       listEntityNames: async () => [],
       loadMeta: async () => ({ extractionCount: 0, lastExtractionAt: null, lastConsolidationAt: null, totalMemories: 0, totalEntities: 0, processedExtractionFingerprints: [] }),
       saveMeta: async () => {},
@@ -1870,6 +1878,45 @@ test("runExtraction clears the buffer on a failed extraction when extractionRetr
   assert.equal(clearCalls, 1, "retry disabled → buffer cleared (pre-#1908 behavior)");
 });
 
+test("runExtraction retains buffers and keeps in-memory backoff when the meta lock is unavailable", async () => {
+  // Lock contention makes updateMeta fail closed without running the mutator.
+  // The retry gate reads the in-memory mirror, so the failure must still park
+  // backoff there and retain the buffer — a cleared buffer with no retry state
+  // silently drops the turns (base behavior retained them).
+  const config = parseConfig({});
+  config.extractionMinChars = 0;
+  config.extractionMinUserTurns = 1;
+
+  let clearCalls = 0;
+  let updateMetaCalls = 0;
+  // SAFETY: runExtraction is driven only through the stub members assigned below;
+  // the prototype harness leaves the rest of Orchestrator unreachable in this test.
+  const orchestrator = Object.create(Orchestrator.prototype) as any;
+  orchestrator.config = config;
+  orchestrator.buffer = { clearAfterExtraction: async () => { clearCalls += 1; } };
+  orchestrator.storageRouter = {
+    storageFor: async () => ({
+      listEntityNames: async () => [],
+      loadMeta: async () => ({ extractionCount: 0, lastExtractionAt: null, lastConsolidationAt: null, totalMemories: 0, totalEntities: 0, processedExtractionFingerprints: [] }),
+      saveMeta: async () => {},
+      updateMeta: async () => {
+        updateMetaCalls += 1;
+        throw new Error("meta update skipped: meta.json.lock not acquired (test)");
+      },
+    }),
+  };
+  orchestrator.extraction = {
+    extract: async () => ({ facts: [], entities: [], questions: [], profileUpdates: [], extractionFailure: "gateway_unavailable" }),
+  };
+  stubPersistExtraction(orchestrator);
+  const turns = [{ ...makeTurn("session-lock-fail", "failed gateway under lock contention"), logicalSessionKey: "logical-thread:lock-fail", turnFingerprint: "fp-lock-fail", persistProcessedFingerprint: true }];
+  const result = await orchestrator.runExtraction(turns, { bufferKey: "logical-thread:lock-fail" });
+  assert.equal(result.status, "skipped");
+  assert.equal(result.reason, "empty_extraction_result");
+  assert.equal(updateMetaCalls, 1);
+  assert.equal(clearCalls, 0, "buffer must be retained when retry state could not persist");
+});
+
 test("runExtraction preserves empty-result buffers when fingerprint persistence fails", async () => {
   const config = parseConfig({});
   config.extractionMinChars = 0;
@@ -1897,7 +1944,7 @@ test("runExtraction preserves empty-result buffers when fingerprint persistence
     },
   };
   orchestrator.storageRouter = {
-    storageFor: async () => ({
+    storageFor: async () => withMetaSeam({
       listEntityNames: async () => [],
       loadMeta: async () => meta,
       saveMeta: async () => {
@@ -1961,7 +2008,7 @@ test("runExtraction keeps the empty live path fail-open when liveness metadata w
     },
   };
   orchestrator.storageRouter = {
-    storageFor: async () => ({
+    storageFor: async () => withMetaSeam({
       listEntityNames: async () => [],
       loadMeta: async () => meta,
       saveMeta: async () => {
@@ -2003,7 +2050,7 @@ test("runExtraction preserves deduped buffers when the caller aborts during meta
     },
   };
   orchestrator.storageRouter = {
-    storageFor: async () => ({
+    storageFor: async () => withMetaSeam({
       listEntityNames: async () => [],
       loadMeta: async () => {
         abortController.abort();
@@ -2075,7 +2122,7 @@ test("runExtraction still clears the buffer when fingerprint persistence fails a
     },
   };
   orchestrator.storageRouter = {
-    storageFor: async () => ({
+    storageFor: async () => withMetaSeam({
       listEntityNames: async () => [],
       loadMeta: async () => ({
         extractionCount: 0,
@@ -2138,18 +2185,7 @@ test("runExtraction persists fingerprint and extraction counters through one coh
   let clearCalls = 0;
   let loadMetaCalls = 0;
   let saveMetaCalls = 0;
-  let savedMeta:
-    | {
-        extractionCount: number;
-        lastExtractionAt: string | null;
-        totalMemories: number;
-        totalEntities: number;
-        processedExtractionFingerprints: Array<{
-          fingerprint: string;
-          observedAt: string;
-        }>;
-      }
-    | undefined;
+  let savedMeta: MetaState | undefined;
 
   const meta = {
     extractionCount: 0,
@@ -2171,13 +2207,13 @@ test("runExtraction persists fingerprint and extraction counters through one coh
     },
   };
   orchestrator.storageRouter = {
-    storageFor: async () => ({
+    storageFor: async () => withMetaSeam({
       listEntityNames: async () => [],
       loadMeta: async () => {
         loadMetaCalls += 1;
         return meta;
       },
-      saveMeta: async (nextMeta: typeof meta) => {
+      saveMeta: async (nextMeta: MetaState) => {
         saveMetaCalls += 1;
         savedMeta = structuredClone(nextMeta);
       },
@@ -2216,14 +2252,17 @@ test("runExtraction persists fingerprint and extraction counters through one coh
     },
   );
 
-  assert.equal(loadMetaCalls, 1);
+  // The counters and fingerprint land on a FRESHLY loaded meta (the serialized
+  // updateMeta re-read), so more than one load is expected; the single save is
+  // the coherent-write contract under test.
+  assert.ok(loadMetaCalls >= 2, 'expected a fresh meta read before the save');
   assert.equal(saveMetaCalls, 1);
   assert.equal(clearCalls, 1);
   assert.equal(savedMeta?.extractionCount, 1);
   assert.equal(savedMeta?.totalMemories, 1);
-  assert.equal(savedMeta?.processedExtractionFingerprints.length, 1);
+  assert.equal(savedMeta?.processedExtractionFingerprints?.length, 1);
   assert.equal(
-    savedMeta?.processedExtractionFingerprints[0]?.fingerprint,
+    savedMeta?.processedExtractionFingerprints?.[0]?.fingerprint,
     orchestrator.buildExtractionFingerprint(
       [
         {
@@ -2246,18 +2285,7 @@ test("runExtraction loads meta before updating extraction counters when fingerpr
   let clearCalls = 0;
   let loadMetaCalls = 0;
   let saveMetaCalls = 0;
-  let savedMeta:
-    | {
-        extractionCount: number;
-        lastExtractionAt: string | null;
-        totalMemories: number;
-        totalEntities: number;
-        processedExtractionFingerprints: Array<{
-          fingerprint: string;
-          observedAt: string;
-        }>;
-      }
-    | undefined;
+  let savedMeta: MetaState | undefined;
 
   const meta = {
     extractionCount: 0,
@@ -2279,13 +2307,13 @@ test("runExtraction loads meta before updating extraction counters when fingerpr
     },
   };
   orchestrator.storageRouter = {
-    storageFor: async () => ({
+    storageFor: async () => withMetaSeam({
       listEntityNames: async () => [],
       loadMeta: async () => {
         loadMetaCalls += 1;
         return meta;
       },
-      saveMeta: async (nextMeta: typeof meta) => {
+      saveMeta: async (nextMeta: MetaState) => {
         saveMetaCalls += 1;
         savedMeta = structuredClone(nextMeta);
       },
@@ -2314,12 +2342,15 @@ test("runExtraction loads meta before updating extraction counters when fingerpr
     bufferKey: "logical-thread:thread-15",
   });
 
-  assert.equal(loadMetaCalls, 1);
+  // The counters and fingerprint land on a FRESHLY loaded meta (the serialized
+  // updateMeta re-read), so more than one load is expected; the single save is
+  // the coherent-write contract under test.
+  assert.ok(loadMetaCalls >= 2, 'expected a fresh meta read before the save');
   assert.equal(saveMetaCalls, 1);
   assert.equal(clearCalls, 1);
   assert.equal(savedMeta?.extractionCount, 1);
   assert.equal(savedMeta?.totalMemories, 1);
-  assert.equal(savedMeta?.processedExtractionFingerprints.length, 0);
+  assert.equal(savedMeta?.processedExtractionFingerprints?.length, 0);
 });
 
 test("runExtraction completes after late threading failures and saves the processed fingerprint", async () => {
@@ -2330,18 +2361,7 @@ test("runExtraction completes after late threading failures and saves the proces
 
   let clearCalls = 0;
   let saveMetaCalls = 0;
-  let savedMeta:
-    | {
-        extractionCount: number;
-        lastExtractionAt: string | null;
-        totalMemories: number;
-        totalEntities: number;
-        processedExtractionFingerprints: Array<{
-          fingerprint: string;
-          observedAt: string;
-        }>;
-      }
-    | undefined;
+  let savedMeta: MetaState | undefined;
 
   const meta = {
     extractionCount: 0,
@@ -2363,10 +2383,10 @@ test("runExtraction completes after late threading failures and saves the proces
     },
   };
   orchestrator.storageRouter = {
-    storageFor: async () => ({
+    storageFor: async () => withMetaSeam({
       listEntityNames: async () => [],
       loadMeta: async () => meta,
-      saveMeta: async (nextMeta: typeof meta) => {
+      saveMeta: async (nextMeta: MetaState) => {
         saveMetaCalls += 1;
         savedMeta = structuredClone(nextMeta);
       },
@@ -2420,9 +2440,9 @@ test("runExtraction completes after late threading failures and saves the proces
   assert.equal(result.postPersistMetadataFailed, false);
   assert.equal(saveMetaCalls, 1);
   assert.equal(clearCalls, 1);
-  assert.equal(savedMeta?.processedExtractionFingerprints.length, 1);
+  assert.equal(savedMeta?.processedExtractionFingerprints?.length, 1);
   assert.equal(
-    savedMeta?.processedExtractionFingerprints[0]?.fingerprint,
+    savedMeta?.processedExtractionFingerprints?.[0]?.fingerprint,
     orchestrator.buildExtractionFingerprint(
       [
         {
@@ -2465,7 +2485,7 @@ test("runExtraction completes and clears the buffer when the post-persist meta s
     },
   };
   orchestrator.storageRouter = {
-    storageFor: async () => ({
+    storageFor: async () => withMetaSeam({
       listEntityNames: async () => [],
       loadMeta: async () => meta,
       saveMeta: async () => {
@@ -2549,7 +2569,7 @@ test("runExtraction still runs follow-on extraction helpers when the post-persis
     },
   };
   orchestrator.storageRouter = {
-    storageFor: async () => ({
+    storageFor: async () => withMetaSeam({
       listEntityNames: async () => [],
       loadMeta: async () => meta,
       saveMeta: async () => {
@@ -2654,13 +2674,15 @@ test("runExtraction aborts before late buffer clearing when the caller cancels",
     },
   };
   orchestrator.storageRouter = {
-    storageFor: async () => ({
+    storageFor: async () => withMetaSeam({
       listEntityNames: async () => [],
       loadMeta: async () => ({
         extractionCount: 0,
         lastExtractionAt: null,
+        lastConsolidationAt: null,
         totalMemories: 0,
         totalEntities: 0,
+        processedExtractionFingerprints: [],
       }),
       saveMeta: async () => undefined,
     }),
@@ -2716,13 +2738,15 @@ test("runExtraction still clears the session buffer after persistence even if re
     },
   };
   orchestrator.storageRouter = {
-    storageFor: async () => ({
+    storageFor: async () => withMetaSeam({
       listEntityNames: async () => [],
       loadMeta: async () => ({
         extractionCount: 0,
         lastExtractionAt: null,
+        lastConsolidationAt: null,
         totalMemories: 0,
         totalEntities: 0,
+        processedExtractionFingerprints: [],
       }),
       saveMeta: async () => undefined,
     }),

package/src/storage-update-meta.test.ts

@@ -0,0 +1,114 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { StorageManager } from "./storage.js";
+import { withHeldFileLock } from "./utils/serialize-mutations.js";
+
+// Real wall-clock is deliberate here: the lock helper's acquire budget and
+// heartbeat polling run on platform timers, and the contention windows below
+// exist to bracket updateMeta's real 2s acquire budget. Fake timers cannot
+// drive the helper's internal polling loop.
+function delay(ms: number): Promise<void> {
+  const { promise, resolve } = Promise.withResolvers<void>();
+  setTimeout(resolve, ms);
+  return promise;
+}
+
+/** Await the real signal "holder owns the lock file", not a guessed duration. */
+async function waitForLockFile(lockPath: string): Promise<void> {
+  const deadline = Date.now() + 2_000;
+  for (;;) {
+    try {
+      await stat(lockPath);
+      return;
+    } catch {
+      if (Date.now() >= deadline) throw new Error(`lock file never appeared: ${lockPath}`);
+      await delay(20);
+    }
+  }
+}
+
+async function makeStorage(): Promise<{
+  storage: StorageManager;
+  lockPath: string;
+  cleanup: () => Promise<void>;
+}> {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-meta-lock-"));
+  await mkdir(path.join(root, "state"), { recursive: true });
+  return {
+    storage: new StorageManager(root),
+    lockPath: path.join(root, "state", "meta.json.lock"),
+    cleanup: () => rm(root, { recursive: true, force: true }),
+  };
+}
+
+test("updateMeta fails closed when meta.json.lock stays held past the acquire budget", async () => {
+  const { storage, lockPath, cleanup } = await makeStorage();
+  try {
+    await storage.updateMeta((meta) => {
+      meta.extractionCount = 1;
+    });
+
+    // A live external holder (a different owner id through the same helper the
+    // out-of-process drain workers use) keeps the lock past updateMeta's 2s
+    // wait budget. The update must fail instead of writing unlocked.
+    const hold = withHeldFileLock(
+      lockPath,
+      { staleMs: 30_000, maxWaitMs: 30_000, pollMs: 50 },
+      async () => {
+        await delay(2_600);
+      },
+    );
+    await waitForLockFile(lockPath);
+
+    await assert.rejects(
+      storage.updateMeta((meta) => {
+        meta.extractionCount = 2;
+      }),
+      /not acquired/,
+    );
+    assert.equal(
+      (await storage.loadMeta()).extractionCount,
+      1,
+      "a timed-out update must not perform an unlocked read-modify-write",
+    );
+
+    await hold;
+    await storage.updateMeta((meta) => {
+      meta.extractionCount = 3;
+    });
+    assert.equal((await storage.loadMeta()).extractionCount, 3);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("concurrent updateMeta additive updates both survive short external contention", async () => {
+  const { storage, lockPath, cleanup } = await makeStorage();
+  try {
+    const hold = withHeldFileLock(
+      lockPath,
+      { staleMs: 30_000, maxWaitMs: 30_000, pollMs: 50 },
+      async () => {
+        await delay(300);
+      },
+    );
+    await waitForLockFile(lockPath);
+    await Promise.all([
+      storage.updateMeta((meta) => {
+        meta.totalMemories += 5;
+      }),
+      storage.updateMeta((meta) => {
+        meta.totalEntities += 7;
+      }),
+    ]);
+    await hold;
+    const meta = await storage.loadMeta();
+    assert.equal(meta.totalMemories, 5);
+    assert.equal(meta.totalEntities, 7);
+  } finally {
+    await cleanup();
+  }
+});

package/src/storage.ts

@@ -34,6 +34,7 @@ import { appendContextTransformRecords, readContextTransformRecords } from "./st
 import type { ContextTransformTelemetryRecord } from "./active-context-transform.js";
 import { readMaybeEncryptedLines, readMemoryActionEventRowsFromLines } from "./storage/secure-line-reader.js";
 import { parseOfflineSyncDigestCache, type OfflineSyncDigestCacheEntry } from "./offline-sync-digest-cache.js";
+import { updateMetaSerialized, withHeldFileLock } from "./utils/serialize-mutations.js";
 import {
   appendLifecycleEventsSerialized,
   type DrainPendingLifecycleForSyncResult,
@@ -5558,12 +5559,8 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       if (err instanceof SecureStoreLockedError) throw err;
       if (!isErrnoCode(err, "ENOENT")) throw err;
       return {
-        extractionCount: 0,
-        lastExtractionAt: null,
-        lastConsolidationAt: null,
-        totalMemories: 0,
-        totalEntities: 0,
-        processedExtractionFingerprints: [],
+        extractionCount: 0, lastExtractionAt: null, lastConsolidationAt: null,
+        totalMemories: 0, totalEntities: 0, processedExtractionFingerprints: [],
       };
     }
   }
@@ -5573,6 +5570,10 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     await this.writeStorageSecureFile(path.join(this.stateDir, "meta.json"), JSON.stringify(state, null, 2));
   }
 
+  async updateMeta(mutate: (meta: MetaState) => boolean | void | Promise<boolean | void>): Promise<void> {
+    await updateMetaSerialized(this.stateDir, () => this.loadMeta(), (meta) => this.saveMeta(meta), mutate);
+  }
+
   async appendMemoryActionEvents(events: MemoryActionEvent[]): Promise<number> {
     if (events.length === 0) return 0;
     await this.ensureDirectories();

package/src/utils/serialize-mutations.ts

@@ -733,3 +733,56 @@ async function refreshHeldLock(
   }
   return lockHeldBySelf(held);
 }
+
+/**
+ * Process-wide chains serializing meta updates per state dir inside one
+ * process. The cross-process advisory lock below only orders DIFFERENT
+ * processes; without the chain, two same-process updates would contend on the
+ * lock file and one could time out to failure.
+ */
+const metaUpdateChains = new Map<string, Promise<unknown>>();
+
+/**
+ * Serialized meta read-modify-write for one state dir (`<stateDir>/meta.json`).
+ * Parallel extraction workers (the daemon's bounded queue and out-of-process
+ * buffer-drain workers) each load meta, mutate counters, fingerprints or retry
+ * state, and save; unlocked, a slow writer's save silently reverts a fast
+ * writer's update. The chain orders same-process callers and the advisory lock
+ * file (`meta.json.lock`) orders different processes; a worker that cannot
+ * take the lock inside the budget FAILS the update instead of writing
+ * unlocked — callers are fail-open, so the outcome is a logged miss retried by
+ * the next extraction, never a silent lost update. The mutator may return
+ * `false` to skip the save (nothing changed).
+ */
+export async function updateMetaSerialized<M>(
+  dir: string,
+  loadMeta: () => Promise<M>,
+  saveMeta: (meta: M) => Promise<void>,
+  mutate: (meta: M) => boolean | void | Promise<boolean | void>,
+): Promise<void> {
+  const previous = metaUpdateChains.get(dir) ?? Promise.resolve();
+  const run = previous.then(() =>
+    withHeldFileLock(
+      path.join(dir, "meta.json.lock"),
+      // Bounded: a meta update is a short read-merge-write, never a scan.
+      { staleMs: 5_000, maxWaitMs: 2_000, pollMs: 50 },
+      async (acquired) => {
+        // A lock we could not take (busy peer past the wait budget, or a
+        // filesystem error) must NOT fall back to an unlocked
+        // read-modify-write: that silently reintroduces the lost-update race
+        // this function exists to close. Fail instead — every caller treats
+        // meta updates as fail-open, so the outcome is a logged miss that
+        // the next extraction retries, never a silent clobber.
+        if (!acquired) {
+          throw new Error(`meta update skipped: meta.json.lock not acquired (${dir})`);
+        }
+        const meta = await loadMeta();
+        if ((await mutate(meta)) === false) return;
+        await saveMeta(meta);
+      },
+    ),
+  );
+  // Every waiter keeps its own result/error; the chain only carries completion.
+  metaUpdateChains.set(dir, run.then(() => undefined, () => undefined));
+  await run;
+}