@remnic/core 10.0.47 → 10.0.49

package/dist/verified-recall.js

@@ -1,22 +1,22 @@
 import {
   compareVerifiedEpisodeResults,
   searchVerifiedEpisodes
-} from "./chunk-VWJ56T63.js";
+} from "./chunk-E3DL3CAL.js";
 import "./chunk-B7RWBZXW.js";
-import "./chunk-L46MG2GE.js";
+import "./chunk-6W3QH3QW.js";
 import "./chunk-UHVXE24Y.js";
 import "./chunk-DM5QZ3YU.js";
 import "./chunk-VY6BD5KB.js";
 import "./chunk-G6OFEGUR.js";
-import "./chunk-PJBYVJKO.js";
-import "./chunk-2V664H6O.js";
+import "./chunk-LXXIV7Y2.js";
+import "./chunk-JS44PBCM.js";
+import "./chunk-5CWH2LKL.js";
 import "./chunk-XKDQTDXN.js";
 import "./chunk-CYEPCZN5.js";
 import "./chunk-XRFLR3XF.js";
 import "./chunk-7VO6E5UD.js";
-import "./chunk-EXYT52NR.js";
-import "./chunk-5CWH2LKL.js";
 import "./chunk-WNEVEMJ3.js";
+import "./chunk-EXYT52NR.js";
 import "./chunk-Y5NLBXPV.js";
 import "./chunk-TFA6HPOA.js";
 import "./chunk-F4TWWUMP.js";
@@ -27,17 +27,17 @@ import "./chunk-PPUNC7UX.js";
 import "./chunk-X3724WL4.js";
 import "./chunk-MRPOZBJC.js";
 import "./chunk-S2HLHAZ4.js";
-import "./chunk-LDXUBPMO.js";
 import "./chunk-DM2T26WE.js";
+import "./chunk-LDXUBPMO.js";
 import "./chunk-FF6N7BXC.js";
 import "./chunk-WXPBDEMW.js";
 import "./chunk-AAD2ZS6P.js";
 import "./chunk-MPJDQC4G.js";
 import "./chunk-ZIKENA2C.js";
-import "./chunk-3ONXXHQO.js";
-import "./chunk-YXZG5TVN.js";
 import "./chunk-3OUGSOJP.js";
 import "./chunk-SCU65EZI.js";
+import "./chunk-3ONXXHQO.js";
+import "./chunk-YXZG5TVN.js";
 import "./chunk-P4GUQSK3.js";
 import "./chunk-3WU7XOFN.js";
 import "./chunk-G7D6GZ5J.js";
@@ -48,12 +48,13 @@ import "./chunk-LWRIGKFM.js";
 import "./chunk-5WITETWU.js";
 import "./chunk-6CIAGZ6X.js";
 import "./chunk-7CT3AI52.js";
-import "./chunk-I3IPXGFQ.js";
+import "./chunk-UUZ7KZAO.js";
+import "./chunk-AJJPXUE6.js";
 import "./chunk-G26YNEOC.js";
+import "./chunk-VILPVT4S.js";
 import "./chunk-AF2XMJKD.js";
 import "./chunk-OR42ZI54.js";
 import "./chunk-IUM3VSHI.js";
-import "./chunk-VILPVT4S.js";
 import "./chunk-23G5P7TA.js";
 import "./chunk-C64XATK7.js";
 import "./chunk-42JKGUFJ.js";
@@ -63,7 +64,7 @@ import "./chunk-L2EXJQJP.js";
 import "./chunk-45GF7Y3V.js";
 import "./chunk-YIJECSIX.js";
 import "./chunk-E2AWJ7KQ.js";
-import "./chunk-UUZ7KZAO.js";
+import "./chunk-7VLBZKNB.js";
 import "./chunk-HADD45AR.js";
 import "./chunk-RNFMFC37.js";
 import "./chunk-YCVB7X56.js";

package/dist/who-knows-cli.js

@@ -4,22 +4,22 @@ import {
   renderWhoKnows,
   renderWhoKnowsJson,
   renderWhoKnowsText
-} from "./chunk-BWRX322G.js";
-import "./chunk-JGMJZBFV.js";
-import "./chunk-L46MG2GE.js";
+} from "./chunk-HI53EK3Y.js";
+import "./chunk-AGCEJDG2.js";
+import "./chunk-6W3QH3QW.js";
 import "./chunk-UHVXE24Y.js";
 import "./chunk-DM5QZ3YU.js";
 import "./chunk-VY6BD5KB.js";
 import "./chunk-G6OFEGUR.js";
-import "./chunk-PJBYVJKO.js";
-import "./chunk-2V664H6O.js";
+import "./chunk-LXXIV7Y2.js";
+import "./chunk-JS44PBCM.js";
+import "./chunk-5CWH2LKL.js";
 import "./chunk-XKDQTDXN.js";
 import "./chunk-CYEPCZN5.js";
 import "./chunk-XRFLR3XF.js";
 import "./chunk-7VO6E5UD.js";
-import "./chunk-EXYT52NR.js";
-import "./chunk-5CWH2LKL.js";
 import "./chunk-WNEVEMJ3.js";
+import "./chunk-EXYT52NR.js";
 import "./chunk-Y5NLBXPV.js";
 import "./chunk-TFA6HPOA.js";
 import "./chunk-F4TWWUMP.js";
@@ -30,17 +30,17 @@ import "./chunk-PPUNC7UX.js";
 import "./chunk-X3724WL4.js";
 import "./chunk-MRPOZBJC.js";
 import "./chunk-S2HLHAZ4.js";
-import "./chunk-LDXUBPMO.js";
 import "./chunk-DM2T26WE.js";
+import "./chunk-LDXUBPMO.js";
 import "./chunk-FF6N7BXC.js";
 import "./chunk-WXPBDEMW.js";
 import "./chunk-AAD2ZS6P.js";
 import "./chunk-MPJDQC4G.js";
 import "./chunk-ZIKENA2C.js";
-import "./chunk-3ONXXHQO.js";
-import "./chunk-YXZG5TVN.js";
 import "./chunk-3OUGSOJP.js";
 import "./chunk-SCU65EZI.js";
+import "./chunk-3ONXXHQO.js";
+import "./chunk-YXZG5TVN.js";
 import "./chunk-P4GUQSK3.js";
 import "./chunk-3WU7XOFN.js";
 import "./chunk-G7D6GZ5J.js";
@@ -51,12 +51,13 @@ import "./chunk-LWRIGKFM.js";
 import "./chunk-5WITETWU.js";
 import "./chunk-6CIAGZ6X.js";
 import "./chunk-7CT3AI52.js";
-import "./chunk-I3IPXGFQ.js";
+import "./chunk-UUZ7KZAO.js";
+import "./chunk-AJJPXUE6.js";
 import "./chunk-G26YNEOC.js";
+import "./chunk-VILPVT4S.js";
 import "./chunk-AF2XMJKD.js";
 import "./chunk-OR42ZI54.js";
 import "./chunk-IUM3VSHI.js";
-import "./chunk-VILPVT4S.js";
 import "./chunk-23G5P7TA.js";
 import "./chunk-C64XATK7.js";
 import "./chunk-42JKGUFJ.js";
@@ -66,7 +67,7 @@ import "./chunk-L2EXJQJP.js";
 import "./chunk-45GF7Y3V.js";
 import "./chunk-YIJECSIX.js";
 import "./chunk-E2AWJ7KQ.js";
-import "./chunk-UUZ7KZAO.js";
+import "./chunk-7VLBZKNB.js";
 import "./chunk-HADD45AR.js";
 import "./chunk-RNFMFC37.js";
 import "./chunk-YCVB7X56.js";

package/dist/who-knows.js

@@ -9,21 +9,21 @@ import {
   loadWhoKnowsEntities,
   tokenizeTopic,
   validateWhoKnowsInput
-} from "./chunk-JGMJZBFV.js";
-import "./chunk-L46MG2GE.js";
+} from "./chunk-AGCEJDG2.js";
+import "./chunk-6W3QH3QW.js";
 import "./chunk-UHVXE24Y.js";
 import "./chunk-DM5QZ3YU.js";
 import "./chunk-VY6BD5KB.js";
 import "./chunk-G6OFEGUR.js";
-import "./chunk-PJBYVJKO.js";
-import "./chunk-2V664H6O.js";
+import "./chunk-LXXIV7Y2.js";
+import "./chunk-JS44PBCM.js";
+import "./chunk-5CWH2LKL.js";
 import "./chunk-XKDQTDXN.js";
 import "./chunk-CYEPCZN5.js";
 import "./chunk-XRFLR3XF.js";
 import "./chunk-7VO6E5UD.js";
-import "./chunk-EXYT52NR.js";
-import "./chunk-5CWH2LKL.js";
 import "./chunk-WNEVEMJ3.js";
+import "./chunk-EXYT52NR.js";
 import "./chunk-Y5NLBXPV.js";
 import "./chunk-TFA6HPOA.js";
 import "./chunk-F4TWWUMP.js";
@@ -34,17 +34,17 @@ import "./chunk-PPUNC7UX.js";
 import "./chunk-X3724WL4.js";
 import "./chunk-MRPOZBJC.js";
 import "./chunk-S2HLHAZ4.js";
-import "./chunk-LDXUBPMO.js";
 import "./chunk-DM2T26WE.js";
+import "./chunk-LDXUBPMO.js";
 import "./chunk-FF6N7BXC.js";
 import "./chunk-WXPBDEMW.js";
 import "./chunk-AAD2ZS6P.js";
 import "./chunk-MPJDQC4G.js";
 import "./chunk-ZIKENA2C.js";
-import "./chunk-3ONXXHQO.js";
-import "./chunk-YXZG5TVN.js";
 import "./chunk-3OUGSOJP.js";
 import "./chunk-SCU65EZI.js";
+import "./chunk-3ONXXHQO.js";
+import "./chunk-YXZG5TVN.js";
 import "./chunk-P4GUQSK3.js";
 import "./chunk-3WU7XOFN.js";
 import "./chunk-G7D6GZ5J.js";
@@ -55,12 +55,13 @@ import "./chunk-LWRIGKFM.js";
 import "./chunk-5WITETWU.js";
 import "./chunk-6CIAGZ6X.js";
 import "./chunk-7CT3AI52.js";
-import "./chunk-I3IPXGFQ.js";
+import "./chunk-UUZ7KZAO.js";
+import "./chunk-AJJPXUE6.js";
 import "./chunk-G26YNEOC.js";
+import "./chunk-VILPVT4S.js";
 import "./chunk-AF2XMJKD.js";
 import "./chunk-OR42ZI54.js";
 import "./chunk-IUM3VSHI.js";
-import "./chunk-VILPVT4S.js";
 import "./chunk-23G5P7TA.js";
 import "./chunk-C64XATK7.js";
 import "./chunk-42JKGUFJ.js";
@@ -70,7 +71,7 @@ import "./chunk-L2EXJQJP.js";
 import "./chunk-45GF7Y3V.js";
 import "./chunk-YIJECSIX.js";
 import "./chunk-E2AWJ7KQ.js";
-import "./chunk-UUZ7KZAO.js";
+import "./chunk-7VLBZKNB.js";
 import "./chunk-HADD45AR.js";
 import "./chunk-RNFMFC37.js";
 import "./chunk-YCVB7X56.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "10.0.47",
+  "version": "10.0.49",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -3347,7 +3347,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^10.0.47"
+    "@remnic/coding-graph": "^10.0.49"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/access-service-peer-capture-backoff.test.ts

@@ -0,0 +1,236 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { EngramAccessService } from "./access-service.js";
+import { CAPTURE_WRITE_LOCK_BUSY_MESSAGE } from "./capture-write-lock-backoff.js";
+import { buildCapturePathLockIdentity, TombstoneBlockedCaptureWriteLock } from "./capture-write-lock.js";
+import { parseConfig } from "./config.js";
+import { Orchestrator } from "./orchestrator.js";
+import { buildExplicitCaptureDedupKey } from "./storage/tombstone-blocked-capture-index.js";
+import { OFFLINE_SYNC_CHANGESET_FORMAT } from "./offline-sync.js";
+
+// Real contention exceeds the legacy deadline but fits inside the configured peer budget.
+
+/** Longer than the legacy 3s capture-lock deadline, shorter than the converge deadline. */
+const CONTENTION_HOLD_MS = 3_600;
+/** The converge deadline a peer apply is scoped to. */
+const CONVERGE_DEADLINE_MS = 8_000;
+/** An ordinary capture must still give up near the legacy 3s bound. */
+const LEGACY_BOUND_MS = 4_500;
+
+const PEER_REL_PATH = "facts/2026-08-13/peer-apply-target.md";
+const ORDINARY_CONTENT = "ordinary capture body";
+
+function peerContent(): Buffer {
+  return Buffer.from(
+    [
+      "---",
+      "id: peer-apply-target",
+      "category: fact",
+      "created: 2026-08-13T00:00:00.000Z",
+      "---",
+      "",
+      "Peer applied body",
+      "",
+    ].join("\n")
+  );
+}
+
+async function createPeerService(root: string) {
+  const orchestrator = new Orchestrator(
+    parseConfig({
+      memoryDir: root,
+      namespacesEnabled: false,
+      defaultNamespace: "global",
+      converge: {
+        conflictPolicy: "newest-wins",
+        captureWriteLockInitialDelayMs: 20,
+        captureWriteLockMaxDelayMs: 50,
+        captureWriteLockDeadlineMs: CONVERGE_DEADLINE_MS,
+      },
+    })
+  );
+  const storage = await orchestrator.getStorage();
+  await storage.ensureDirectories();
+  assert.equal(storage.dir, root, "the fixture uses one cached flat-root storage");
+  return { storage, service: new EngramAccessService(orchestrator) };
+}
+
+/** Hold a capture lock and release it after `holdMs`. */
+function holdCaptureLock(stateDir: string, identity: string, holdMs: number) {
+  const holder = new TombstoneBlockedCaptureWriteLock({ stateDir });
+  const released = Promise.withResolvers<void>();
+  const acquired = Promise.withResolvers<void>();
+  let timer: NodeJS.Timeout | undefined;
+  const holding = holder.withCaptureWriteLock(async () => {
+    acquired.resolve();
+    timer = setTimeout(() => released.resolve(), holdMs);
+    await released.promise;
+  }, identity);
+  return {
+    acquired: acquired.promise,
+    release: (): void => {
+      clearTimeout(timer);
+      released.resolve();
+    },
+    done: holding,
+  };
+}
+
+function peerApplyRequest(content: Buffer) {
+  return {
+    sourceId: "remnic-converge",
+    path: PEER_REL_PATH,
+    sha256: createHash("sha256").update(content).digest("hex"),
+    bytes: content.length,
+    mtimeMs: 1_700_000_000_000,
+    offset: 0,
+    content,
+  };
+}
+
+for (const kind of ["chunk", "changeset"] as const) {
+  test(
+    `peer ${kind} apply waits out a busy capture lock instead of the legacy deadline`,
+    { timeout: 30_000 },
+    async () => {
+      const root = await mkdtemp(path.join(os.tmpdir(), "remnic-peer-capture-backoff-"));
+      const { service } = await createPeerService(root);
+      const content = peerContent();
+      const holder = holdCaptureLock(
+        path.join(root, "state"),
+        buildCapturePathLockIdentity(path.resolve(root, PEER_REL_PATH)),
+        CONTENTION_HOLD_MS
+      );
+      try {
+        await holder.acquired;
+        const startedAt = Date.now();
+        const apply =
+          kind === "chunk"
+            ? service.offlineSyncApplyFileContent(peerApplyRequest(content))
+            : service.offlineSyncApply({
+                returnCurrentFiles: false,
+                changeset: {
+                  format: OFFLINE_SYNC_CHANGESET_FORMAT,
+                  schemaVersion: 1,
+                  createdAt: "2026-08-13T00:00:00.000Z",
+                  sourceId: "remnic-converge",
+                  includeTranscripts: false,
+                  changes: [
+                    {
+                      type: "upsert",
+                      path: PEER_REL_PATH,
+                      file: {
+                        path: PEER_REL_PATH,
+                        sha256: createHash("sha256").update(content).digest("hex"),
+                        bytes: content.length,
+                        mtimeMs: 1_700_000_000_000,
+                        contentBase64: content.toString("base64"),
+                      },
+                    },
+                  ],
+                },
+              });
+        const outcome = await apply.then(
+          () => ({ ok: true as const }),
+          (error) => ({ ok: false as const, error })
+        );
+        assert.equal(
+          outcome.ok,
+          true,
+          outcome.ok
+            ? ""
+            : `peer apply failed: ${outcome.error instanceof Error ? outcome.error.message : String(outcome.error)}`
+        );
+        assert.ok(Date.now() - startedAt >= 2_500, "peer apply must wait out the capture-lock contention");
+        assert.equal(await readFile(path.join(root, PEER_REL_PATH), "utf8"), content.toString("utf8"));
+      } finally {
+        holder.release();
+        await holder.done.catch(() => undefined);
+        await rm(root, { recursive: true, force: true });
+      }
+    }
+  );
+}
+
+test(
+  "an ordinary capture keeps the legacy capture-lock bound while a peer apply is in flight",
+  { timeout: 30_000 },
+  async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "remnic-peer-capture-isolation-"));
+    const { storage, service } = await createPeerService(root);
+    const content = peerContent();
+    const stateDir = path.join(root, "state");
+    const peerHolder = holdCaptureLock(
+      stateDir,
+      buildCapturePathLockIdentity(path.resolve(root, PEER_REL_PATH)),
+      CONTENTION_HOLD_MS
+    );
+    const ordinaryHolder = holdCaptureLock(
+      stateDir,
+      buildExplicitCaptureDedupKey(ORDINARY_CONTENT, "fact", undefined),
+      CONTENTION_HOLD_MS
+    );
+    let peerApply: Promise<{ ok: true; value: unknown } | { ok: false; error: unknown }> | undefined;
+    try {
+      await Promise.all([peerHolder.acquired, ordinaryHolder.acquired]);
+      peerApply = service.offlineSyncApplyFileContent(peerApplyRequest(content)).then(
+        (value) => ({ ok: true as const, value }),
+        (error) => ({ ok: false as const, error })
+      );
+      const startedAt = Date.now();
+      const outcome = await storage.writeMemory("fact", ORDINARY_CONTENT).then(
+        () => ({ ok: true as const }),
+        (error) => ({ ok: false as const, error })
+      );
+      assert.equal(outcome.ok, false, "ordinary capture must not succeed while the capture lock is held");
+      assert.equal(
+        outcome.ok ? "" : outcome.error instanceof Error ? outcome.error.message : String(outcome.error),
+        CAPTURE_WRITE_LOCK_BUSY_MESSAGE
+      );
+      assert.ok(
+        Date.now() - startedAt < LEGACY_BOUND_MS,
+        "ordinary capture must keep the legacy capture-lock bound, not the converge deadline"
+      );
+    } finally {
+      peerHolder.release();
+      ordinaryHolder.release();
+      await Promise.all([peerHolder.done.catch(() => undefined), ordinaryHolder.done.catch(() => undefined)]);
+      await peerApply;
+      await rm(root, { recursive: true, force: true });
+    }
+  }
+);
+test("a failed peer apply does not leak converge capture-lock limits", { timeout: 30_000 }, async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-peer-capture-error-scope-"));
+  const { storage, service } = await createPeerService(root);
+  const content = peerContent();
+  const holder = holdCaptureLock(
+    path.join(root, "state"),
+    buildExplicitCaptureDedupKey(ORDINARY_CONTENT, "fact", undefined),
+    CONTENTION_HOLD_MS
+  );
+  try {
+    await assert.rejects(
+      service.offlineSyncApplyFileContent({
+        ...peerApplyRequest(content),
+        sha256: "0".repeat(64),
+      })
+    );
+    await holder.acquired;
+    const startedAt = Date.now();
+    await assert.rejects(storage.writeMemory("fact", ORDINARY_CONTENT), new RegExp(CAPTURE_WRITE_LOCK_BUSY_MESSAGE));
+    assert.ok(
+      Date.now() - startedAt < LEGACY_BOUND_MS,
+      "ordinary capture after a failed peer apply must keep the legacy lock bound"
+    );
+  } finally {
+    holder.release();
+    await holder.done.catch(() => undefined);
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/src/access-service.ts

@@ -136,6 +136,8 @@ import {
   applySupportPassportOfflineSyncChangeset,
   applySupportPassportOfflineSyncFileContent,
 } from "./support-passport/offline-sync-guard.js";
+import { withCaptureWriteLockBackoff } from "./capture-write-lock-scope.js";
+import { resolveConvergeCaptureWriteLockBackoff } from "./converge-config.js";
 import type { WearablesService } from "./wearables/service.js";
 import { exportWorkBoardMarkdown, exportWorkBoardSnapshot, importWorkBoardSnapshot } from "./work/board.js";
 import { wrapWorkLayerContext } from "./work/boundary.js";
@@ -5623,7 +5625,8 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
     const resolvedNamespace = this.writableNamespaceFor(options.namespace, undefined, options.principal);
     const storage = await this.orchestrator.getStorage(resolvedNamespace);
     try {
-      const result = await applySupportPassportOfflineSyncFileContent(storage, options);
+      const result = await withCaptureWriteLockBackoff(storage, resolveConvergeCaptureWriteLockBackoff(this.orchestrator.config.converge),
+        () => applySupportPassportOfflineSyncFileContent(storage, options));
       return {
         namespace: resolvedNamespace,
         ...result,
@@ -5671,7 +5674,8 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
     const resolvedNamespace = this.writableNamespaceFor(options.namespace, undefined, options.principal);
     const storage = await this.orchestrator.getStorage(resolvedNamespace);
     try {
-      const result = await applySupportPassportOfflineSyncChangeset(storage, options);
+      const result = await withCaptureWriteLockBackoff(storage, resolveConvergeCaptureWriteLockBackoff(this.orchestrator.config.converge),
+        () => applySupportPassportOfflineSyncChangeset(storage, options));
       return {
         namespace: resolvedNamespace,
         ...result,

package/src/capture-write-lock-scope.test.ts

@@ -0,0 +1,32 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { scopedCaptureWriteLockLimits, withCaptureWriteLockBackoff } from "./capture-write-lock-scope.js";
+
+const limits = { initialDelayMs: 20, maxDelayMs: 50, deadlineMs: 8_000 };
+const expected = {
+  captureWriteLockInitialDelayMs: 20,
+  captureWriteLockMaxDelayMs: 50,
+  captureWriteLockDeadlineMs: 8_000,
+};
+
+test("capture backoff scope belongs only to its storage and restores nested state after rejection", async () => {
+  const storage = { dir: "synthetic-shared-root" };
+  const other = { dir: storage.dir };
+  const result = await withCaptureWriteLockBackoff(storage, limits, async () => {
+    await Promise.resolve();
+    assert.deepEqual(scopedCaptureWriteLockLimits(storage), expected);
+    assert.equal(scopedCaptureWriteLockLimits(other), undefined);
+    await assert.rejects(
+      withCaptureWriteLockBackoff(other, { ...limits, deadlineMs: 4_000 }, async () => {
+        assert.equal(scopedCaptureWriteLockLimits(other)?.captureWriteLockDeadlineMs, 4_000);
+        assert.equal(scopedCaptureWriteLockLimits(storage), undefined);
+        throw new Error("peer apply failed");
+      }),
+      /peer apply failed/
+    );
+    return scopedCaptureWriteLockLimits(storage);
+  });
+  assert.deepEqual(result, expected);
+  assert.equal(scopedCaptureWriteLockLimits(storage), undefined);
+  assert.equal(scopedCaptureWriteLockLimits(other), undefined);
+});

package/src/capture-write-lock-scope.ts

@@ -0,0 +1,30 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { CaptureWriteLockBackoffLimits, CaptureWriteLockLimitSource } from "./capture-write-lock-backoff.js";
+import type { StorageManager } from "./storage.js";
+
+type CaptureLockOwner = Pick<StorageManager, "dir">;
+
+const captureScope = new AsyncLocalStorage<{ storage: CaptureLockOwner; limits: CaptureWriteLockLimitSource }>();
+
+export function withCaptureWriteLockBackoff<T>(
+  storage: CaptureLockOwner,
+  limits: CaptureWriteLockBackoffLimits,
+  run: () => Promise<T>
+): Promise<T> {
+  return captureScope.run(
+    {
+      storage,
+      limits: {
+        captureWriteLockInitialDelayMs: limits.initialDelayMs,
+        captureWriteLockMaxDelayMs: limits.maxDelayMs,
+        captureWriteLockDeadlineMs: limits.deadlineMs,
+      },
+    },
+    run
+  );
+}
+
+export function scopedCaptureWriteLockLimits(storage: CaptureLockOwner): CaptureWriteLockLimitSource | undefined {
+  const scope = captureScope.getStore();
+  return scope?.storage === storage ? scope.limits : undefined;
+}

package/src/embedding-generation-marker.ts

@@ -0,0 +1,51 @@
+// Node-local warm-cache generation marker (`<stateDir>/embeddings.generation`).
+// Two-phase publication barrier: in-flight before a publication's first
+// destructive write, fresh unique value after its last write (PR #3176), so a
+// completed stamp is only ever stable while generation bytes are unchanged.
+// Single owner of the atomic protocol and logging — the store's own mutations
+// and the offline-sync direct write/delete paths (issue #3182) share it.
+// Plain fs always (tmp + rename): the marker is node-local raw bytes, never
+// sync traffic or secure-store content.
+import { randomUUID } from "node:crypto";
+import { rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { log } from "./logger.js";
+
+export const GENERATION_MARKER_BASENAME = "embeddings.generation";
+
+/** Reserved in-flight marker value; never equals a completion marker. */
+export const GENERATION_MARKER_IN_FLIGHT = "in-flight";
+
+export function generationMarkerPath(stateDirAbs: string): string {
+  return path.join(stateDirAbs, GENERATION_MARKER_BASENAME);
+}
+
+/** Strict atomic marker write; recovery uses it for a fresh completed value. */
+export async function writeGenerationMarkerRaw(markerAbs: string, value: string): Promise<void> {
+  const tempPath = `${markerAbs}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  try {
+    await writeFile(tempPath, value, "utf-8");
+    await rename(tempPath, markerAbs);
+  } catch (err) {
+    await rm(tempPath, { force: true }).catch(() => undefined);
+    throw err;
+  }
+}
+
+/** Barrier first half: strict, so bytes can never change under a stable stamp. */
+export async function beginGenerationMarker(markerAbs: string): Promise<void> {
+  await writeGenerationMarkerRaw(markerAbs, GENERATION_MARKER_IN_FLIGHT);
+}
+
+/**
+ * Barrier second half: written after the last content write. Best-effort:
+ * a failure leaves the in-flight marker, whose stamp identityStamp()
+ * never repeats, so cached probes revalidate on every search until a
+ * publication completes.
+ */
+export async function completeGenerationMarker(markerAbs: string): Promise<void> {
+  await writeGenerationMarkerRaw(markerAbs, randomUUID()).catch((err) => {
+    log.warn(`embedding index: could not write generation completion marker: ${err instanceof Error ? err.message : String(err)}`);
+  });
+}