@gmickel/gno 2.6.0 → 2.7.0

package/src/cli/program.ts

@@ -41,7 +41,11 @@ import {
   type GlobalOptions,
   parseGlobalOptions,
 } from "./context";
-import { DETACHED_CHILD_FLAG } from "./detach";
+import {
+  DETACHED_CHILD_FLAG,
+  formatBackgroundIssue,
+  residentIssues,
+} from "./detach";
 import { CliError } from "./errors";
 import {
   assertFormatSupported,
@@ -3544,6 +3548,10 @@ function wireManagementCommands(program: Command): void {
       .option("--model <uri>", "embedding model URI")
       .option("--batch-size <num>", "batch size", "32")
       .option("--force", "regenerate all embeddings")
+      .option(
+        "--new-partition",
+        "confirm building a separate vector partition for an incompatible runtime"
+      )
       .option("--dry-run", "show what would be done")
       .option("--json", "JSON output")
   ).action(
@@ -3567,6 +3575,7 @@ function wireManagementCommands(program: Command): void {
         force: Boolean(cmdOpts.force),
         dryRun: Boolean(cmdOpts.dryRun),
         yes: globals.yes,
+        newPartition: Boolean(cmdOpts.newPartition),
         json: format === "json",
         verbose: globals.verbose,
         offline: globals.offline,
@@ -3675,6 +3684,43 @@ function wireVecCommands(program: Command): void {
     );
   });
 
+  // vec drop
+  addWriteLeaseFlags(
+    vecCmd
+      .command("drop <partition>")
+      .description(
+        "Drop an abandoned shadow vector partition (id prefix from gno status)"
+      )
+      .option("--json", "JSON output")
+  ).action(async (partition: string, cmdOpts: Record<string, unknown>) => {
+    const format = getFormat(cmdOpts);
+    const globals = getGlobals();
+
+    const { vecDrop, formatVecDrop } = await import("./commands/vec");
+    const lease = parseWriteLeaseFlags(cmdOpts);
+    const result = await withCliWriteLease(
+      {
+        indexName: globals.index,
+        lockWaitMs: lease.lockWaitMs,
+        noWait: lease.noWait,
+      },
+      () =>
+        vecDrop(partition, {
+          configPath: globals.config,
+          indexName: globals.index,
+        })
+    );
+    throwIfWriteLeaseBusy(result, format === "json");
+
+    if (!result.success) {
+      throw new CliError("VALIDATION", result.error);
+    }
+
+    process.stdout.write(
+      `${formatVecDrop(result, { json: format === "json" })}\n`
+    );
+  });
+
   // vec rebuild
   addWriteLeaseFlags(
     vecCmd
@@ -5017,6 +5063,9 @@ async function runDaemonStatus(deps: DaemonStatusDeps): Promise<void> {
     } else {
       process.stdout.write(` (${status.log_size_bytes} bytes)\n`);
     }
+    for (const issue of residentIssues(status)) {
+      process.stdout.write(`  issue    ${formatBackgroundIssue(issue)}\n`);
+    }
     if (findings) {
       process.stdout.write(
         `  findings ${formatFindingsRunStatusLine(findings)}\n`
@@ -5372,6 +5421,9 @@ async function runServeStatus(deps: ServeStatusDeps): Promise<void> {
     } else {
       process.stdout.write(` (${status.log_size_bytes} bytes)\n`);
     }
+    for (const issue of residentIssues(status)) {
+      process.stdout.write(`  issue    ${formatBackgroundIssue(issue)}\n`);
+    }
 
     if (foreign) {
       // Terminal mode: emit the operator-facing warning on stderr. JSON

package/src/core/capture-sync.ts

@@ -10,6 +10,7 @@ import type { Collection, Config } from "../config/types";
 import type { StorePort } from "../store/types";
 import type { CaptureIndexStatus } from "./capture";
 
+import { buildUri } from "../app/constants";
 import {
   type CollectionSyncResult,
   defaultSyncService,
@@ -30,9 +31,14 @@ export class CaptureSyncError extends Error {
   /** The sync failure itself, without the write half of the message. */
   readonly syncError: string;
 
-  constructor(input: { absPath: string; relPath: string; cause: string }) {
+  constructor(input: {
+    absPath: string;
+    relPath: string;
+    uri: string;
+    cause: string;
+  }) {
     super(
-      `Capture written to ${input.absPath} but lexical sync failed: ${input.cause}. Run gno update to retry indexing.`
+      `Capture written to ${input.uri} but lexical sync failed: ${input.cause}. Run gno update to retry indexing.`
     );
     this.name = "CaptureSyncError";
     this.absPath = input.absPath;
@@ -82,6 +88,7 @@ export async function syncCapturedFile(
     throw new CaptureSyncError({
       absPath: input.absPath,
       relPath: input.relPath,
+      uri: buildUri(input.collection.name, input.relPath),
       cause,
     });
   };

package/src/core/host-paths.ts

@@ -0,0 +1,31 @@
+/**
+ * Host path redaction for callers that are not on the owner's machine.
+ *
+ * Result payloads name a source file's host location in `absPath`
+ * (`source.absPath` on search/get results, top-level on capture, memory and
+ * peek receipts). A remote caller identifies documents by `uri` and
+ * collection-relative `relPath` instead, so every `absPath` key is removed
+ * before a payload leaves a remote-reachable surface.
+ */
+
+const HOST_PATH_FIELD = "absPath";
+
+const isPlainObject = (value: object): boolean => {
+  const proto = Object.getPrototypeOf(value) as object | null;
+  return proto === Object.prototype || proto === null;
+};
+
+/** Deep copy of a JSON-shaped value with every `absPath` key removed. */
+export function withoutHostPaths<T>(value: T): T {
+  if (Array.isArray(value)) {
+    return value.map((item: unknown) => withoutHostPaths(item)) as T;
+  }
+  if (value === null || typeof value !== "object" || !isPlainObject(value)) {
+    return value;
+  }
+  const copy: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (key !== HOST_PATH_FIELD) copy[key] = withoutHostPaths(entry);
+  }
+  return copy as T;
+}

package/src/core/memory-remember.ts

@@ -24,6 +24,7 @@ import type {
   RememberResult,
 } from "./memory-types";
 
+import { buildUri } from "../app/constants";
 import { defaultSyncService, withContentTypeRules } from "../ingestion";
 import { withWriteLock } from "./file-lock";
 import { atomicCreate } from "./file-ops";
@@ -399,7 +400,7 @@ export async function rememberFact(
     if (sync.status === "failed") {
       throw new MemoryError(
         "MEMORY_SYNC_FAILED",
-        `Memory record written to ${absPath} but lexical sync failed: ${sync.error}. Run gno update to retry indexing.`
+        `Memory record written to ${buildUri(collection.name, relPath)} but lexical sync failed: ${sync.error}. Run gno update to retry indexing.`
       );
     }
     const written = (doc as { value: DocumentRow }).value;
@@ -415,13 +416,13 @@ export async function rememberFact(
       if (!projected) {
         throw new MemoryError(
           "MEMORY_SUPERSEDE_PROJECTION_FAILED",
-          `Successor written to ${absPath} but its supersedes edge did not project${projectionErrors ? ` (${projectionErrors})` : ""}; the predecessor still reads as current. Run gno update to retry the projection.`
+          `Successor written to ${buildUri(collection.name, relPath)} but its supersedes edge did not project${projectionErrors ? ` (${projectionErrors})` : ""}; the predecessor still reads as current. Run gno update to retry the projection.`
         );
       }
     } else if (projectionErrors.length > 0) {
       throw new MemoryError(
         "MEMORY_SYNC_FAILED",
-        `Memory record written to ${absPath} but typed-edge projection failed: ${projectionErrors}. Run gno update to retry indexing.`
+        `Memory record written to ${buildUri(collection.name, relPath)} but typed-edge projection failed: ${projectionErrors}. Run gno update to retry indexing.`
       );
     }
     const record: MemoryFact = {

package/src/core/shutdown-budget.ts

@@ -4,6 +4,12 @@ export const SHUTDOWN_ABORT_MS = 5_000;
 export const SHUTDOWN_EXIT_MS = 1_000;
 // The detached parent must not be killed before it can reap its native child.
 export const RESIDENT_STOP_GRACE_MS = 12_000;
+/**
+ * Longest synchronous SQLite busy wait a resident allows itself. A signal is
+ * handled only after the wait in progress ends, so this plus the shutdown
+ * clock must fit inside the stop grace (asserted in shutdown-budget tests).
+ */
+export const RESIDENT_BUSY_TIMEOUT_MS = 500;
 
 /** Observe settlement without abandoning rejection handling or retaining a timer. */
 export async function settlesBy(

package/src/core/vector-partition-status.ts

@@ -0,0 +1,52 @@
+import type {
+  VectorPartitionStatus,
+  VectorRuntimeStatus,
+} from "../store/vector/status";
+
+const shortId = (id: string): string => id.slice(0, 12);
+
+function runtimeLine(runtime: VectorRuntimeStatus): string {
+  const label = runtime.label ? ` (${runtime.label})` : "";
+  if (runtime.state === "vectors")
+    return `  This runtime${label} reads ${shortId(runtime.partition ?? "")}`;
+  if (runtime.state === "unavailable")
+    return `  This runtime${label} uses lexical retrieval only: ${runtime.reason}`;
+  return "  This runtime has not resolved a partition yet; run a query or `gno embed`";
+}
+
+/**
+ * The caller's runtime, then one line per partition. The healthy case (one
+ * current partition this runtime reads) prints nothing, so default status
+ * output is unchanged.
+ */
+export function formatVectorPartitionLines(
+  partitions?: VectorPartitionStatus[],
+  runtime?: VectorRuntimeStatus
+): string[] {
+  if (!partitions?.length) return [];
+  const [only] = partitions;
+  if (
+    partitions.length === 1 &&
+    only?.retrieval &&
+    !only.legacy &&
+    !only.incompatibleRuntimes.length
+  )
+    return [];
+  const lines = ["Vector partitions:"];
+  if (runtime) lines.push(runtimeLine(runtime));
+  for (const p of partitions) {
+    const role = p.retrieval
+      ? " (used by this runtime's retrieval)"
+      : p.droppable
+        ? ` (drop with: gno vec drop ${shortId(p.id)})`
+        : "";
+    lines.push(
+      `  ${p.retrieval ? "*" : " "} ${shortId(p.id)} ${p.state}${p.legacy ? " legacy" : ""}, ${p.owners} chunks, ${p.provenance}${role}`
+    );
+    if (p.compatibleRuntimes.length)
+      lines.push(`      read by: ${p.compatibleRuntimes.join("; ")}`);
+    if (p.incompatibleRuntimes.length)
+      lines.push(`      incompatible: ${p.incompatibleRuntimes.join("; ")}`);
+  }
+  return lines;
+}

package/src/embed/backlog.ts

@@ -1,3 +1,5 @@
+import type { Database } from "bun:sqlite";
+
 import type { EmbeddingPort } from "../llm/types";
 /**
  * Shared embedding backlog processor.
@@ -12,21 +14,26 @@ import type {
   VectorStatsPort,
 } from "../store/vector";
 import type { VectorVariantStore } from "../store/vector/variants";
+import type { AcquireWriteTurn } from "./retry";
 
 import {
   assertInferenceActive,
   isBackgroundInference,
 } from "../llm/inference-scope";
+import { formatDocForEmbedding } from "../pipeline/contextual";
 import { err, ok } from "../store/types";
+import {
+  embeddingPartitionIdentity,
+  recordReferenceRuntime,
+  resolveRuntimePartition,
+} from "../store/vector/runtime-compat";
 import { getVectorStatsDatabase } from "../store/vector/stats";
 import { createVectorVariantStore } from "../store/vector/variants";
-import {
-  getEmbeddingFingerprint,
-  getVariantModelFingerprint,
-} from "./fingerprint";
+import { getEmbeddingFingerprint } from "./fingerprint";
 import {
   chunkRetryKey,
   embedAndStoreBatch,
+  inWriteTurn,
   MAX_EMBED_CHUNK_ATTEMPTS,
 } from "./retry";
 import { embedVariantBacklog } from "./variant-backlog";
@@ -47,6 +54,14 @@ export interface EmbedBacklogDeps {
   variantStore?: VectorVariantStore;
   /** Recheck the effective runtime identity after asynchronous inference. */
   identityStillCurrent?: () => boolean;
+  /**
+   * Write gate for callers that do not already hold the shared writer lease
+   * (the resident scheduler): taken around each page's writes and released
+   * after. null means another writer holds it; the pass stops as deferred.
+   */
+  acquireWriteTurn?: AcquireWriteTurn;
+  /** Explicit confirmation to build a separate vector partition (never implied by --yes). */
+  allowNewPartition?: boolean;
 }
 
 export interface EmbedBacklogResult {
@@ -59,6 +74,8 @@ export interface EmbedBacklogResult {
   contentionErrors?: number;
   /** Error message if vec index sync failed (embeddings stored, but search may be stale) */
   syncError?: string;
+  /** The pass stopped early because another writer held the write gate. */
+  deferred?: boolean;
 }
 
 interface Cursor {
@@ -78,7 +95,18 @@ export async function embedBacklog(
   deps: EmbedBacklogDeps
 ): Promise<StoreResult<EmbedBacklogResult>> {
   assertInferenceActive();
-  const prepared = await prepareEmbeddingBacklog(deps);
+  if (deps.acquireWriteTurn && !deps.variantStore) {
+    // Model loading stays outside the write turn; preparation's partition
+    // writes below take one like every other background write.
+    const initialized = await deps.embedPort.init();
+    if (!initialized.ok) return err("INTERNAL", initialized.error.message);
+  }
+  const turn = await inWriteTurn(deps.acquireWriteTurn, () =>
+    prepareEmbeddingBacklog(deps)
+  );
+  if (turn.deferred)
+    return ok({ embedded: 0, errors: 0, contentionErrors: 0, deferred: true });
+  const prepared = turn.value;
   if (!prepared.ok) return prepared;
   deps = prepared.value;
   if (deps.variantStore) return embedVariantBacklog(deps, deps.variantStore);
@@ -201,7 +229,10 @@ export async function embedBacklog(
         embedFingerprint,
         identityStillCurrent: deps.identityStillCurrent,
         statsPort,
+        acquireWriteTurn: deps.acquireWriteTurn,
       });
+      if (batchStoreResult.deferred)
+        return ok({ embedded, errors, contentionErrors, deferred: true });
       embedded += batchStoreResult.embedded;
       errors += batchStoreResult.errors;
       contentionErrors += batchStoreResult.contentionErrors;
@@ -225,7 +256,12 @@ export async function embedBacklog(
     // Sync vec index once at end if any vec0 writes failed
     let syncError: string | undefined;
     if (vectorIndex.vecDirty) {
-      const syncResult = await vectorIndex.syncVecIndex();
+      const turn = await inWriteTurn(deps.acquireWriteTurn, () =>
+        vectorIndex.syncVecIndex()
+      );
+      if (turn.deferred)
+        return ok({ embedded, errors, contentionErrors, deferred: true });
+      const syncResult = turn.value;
       if (syncResult.ok) {
         const { added, removed } = syncResult.value;
         if (added > 0 || removed > 0) {
@@ -248,6 +284,59 @@ export async function embedBacklog(
   }
 }
 
+function formatEstimate(ms: number): string {
+  const seconds = Math.max(1, Math.round(ms / 1000));
+  if (seconds < 90) return `about ${seconds} s`;
+  const minutes = Math.round(seconds / 60);
+  return minutes < 90
+    ? `about ${minutes} min`
+    : `about ${(minutes / 60).toFixed(1)} h`;
+}
+
+/** Time this port on a few current chunks when no compatibility sample ran. */
+async function measureEmbedRate(
+  db: Database,
+  port: EmbeddingPort
+): Promise<number | undefined> {
+  const inputs = db
+    .query<{ text: string; title: string | null }, []>(`
+      SELECT c.text, d.title FROM documents d
+      JOIN content_chunks c ON c.mirror_hash = d.mirror_hash
+      WHERE d.active = 1 ORDER BY d.id, c.seq LIMIT 8
+    `)
+    .all()
+    .map((row) =>
+      formatDocForEmbedding(row.text, row.title ?? undefined, port.modelUri)
+    );
+  if (!inputs.length) return undefined;
+  const startedAt = performance.now();
+  const result = await port.embedBatch(inputs);
+  return result.ok
+    ? (performance.now() - startedAt) / inputs.length
+    : undefined;
+}
+
+/** R3: a fork names itself, its full size and a measured estimate before it runs. */
+async function separatePartitionMessage(
+  db: Database,
+  port: EmbeddingPort,
+  reason: string,
+  msPerChunk: number | undefined
+): Promise<string> {
+  const chunks = db
+    .query<{ count: number }, []>(`
+      SELECT count(*) AS count FROM documents d
+      JOIN content_chunks c ON c.mirror_hash = d.mirror_hash WHERE d.active = 1
+    `)
+    .get()!.count;
+  const rate = msPerChunk ?? (await measureEmbedRate(db, port));
+  const estimate =
+    rate === undefined
+      ? "no estimate: embedding could not be timed"
+      : `estimated ${formatEstimate(rate * chunks)} at the measured ${Math.round(rate)} ms per chunk`;
+  return `Embedding would build a separate vector partition (${reason}). It re-embeds all ${chunks} chunks (${estimate}). Confirm with \`gno embed --new-partition\`; --yes alone does not confirm.`;
+}
+
 /** Resolve authority before counts, dry runs, forced work, or early returns. */
 export async function prepareEmbeddingBacklog(
   deps: EmbedBacklogDeps
@@ -259,19 +348,36 @@ export async function prepareEmbeddingBacklog(
       const initialized = await deps.embedPort.init();
       if (!initialized.ok) return err("INTERNAL", initialized.error.message);
       const identity = deps.embedPort.getIdentity?.();
-      if (identity) {
+      const primary = embeddingPartitionIdentity(deps.embedPort);
+      if (identity && primary) {
         const identitySnapshot = JSON.stringify(identity);
-        const dimensions = deps.embedPort.dimensions();
-        const variantStore = await createVectorVariantStore(db, {
-          model: deps.modelUri,
-          modelFingerprint: getVariantModelFingerprint(
-            { modelUri: deps.modelUri, dimensions },
-            identity
-          ),
-          contextSize: identity.contextSize,
-          truncationPolicy: identity.truncationPolicy,
-          dimensions,
-        });
+        const dimensions = primary.dimensions;
+        const resolved = await resolveRuntimePartition(
+          db,
+          deps.embedPort,
+          primary
+        );
+        if (resolved.blocked && !deps.allowNewPartition)
+          return err(
+            "VECTOR_PARTITION_FORK",
+            await separatePartitionMessage(
+              db,
+              deps.embedPort,
+              resolved.blocked.reason,
+              resolved.msPerChunk
+            )
+          );
+        const variantStore = await createVectorVariantStore(
+          db,
+          resolved.blocked?.separate ?? resolved.identity,
+          identity.runtimeLabel
+        );
+        if (resolved.blocked || resolved.verdict === "unverified") {
+          // Vectors without a current owner cannot be measured; they must not
+          // survive to be reused by the runtime that becomes the reference.
+          variantStore.collectGarbage();
+          recordReferenceRuntime(db, variantStore.partitionId, identity);
+        }
         variantStore.selectForEmbedding();
         return ok({
           ...deps,

package/src/embed/fingerprint.ts

@@ -36,16 +36,19 @@ export function getEmbeddingFingerprint(
     .digest("hex");
 }
 
-/** Partition provenance combines actual weights/runtime with the unchanged formatter policy. */
+/**
+ * Partition identity: actual weights plus the formatter policy. Runtime details
+ * (Bun, native binding, backend, threads) are provenance, never identity; the
+ * measured compatibility check decides whether a runtime may share vectors.
+ */
 export function getVariantModelFingerprint(
   input: EmbeddingFingerprintInput,
-  identity: { modelFingerprint: string; runtimeFingerprint: string }
+  identity: { modelFingerprint: string }
 ): string {
   return new Bun.CryptoHasher("sha256")
     .update(
       JSON.stringify([
         identity.modelFingerprint,
-        identity.runtimeFingerprint,
         getEmbeddingFingerprint(input),
       ])
     )

package/src/embed/retry.ts

@@ -15,6 +15,28 @@ import { getVectorStatsDatabase } from "../store/vector/stats";
 import { embedTextsWithRecovery } from "./batch";
 
 export const MAX_EMBED_CHUNK_ATTEMPTS = 2;
+
+/**
+ * Write gate for callers that do not already hold the shared writer lease
+ * (the resident scheduler). Returns a release, or null when another writer
+ * holds the lease.
+ */
+export type AcquireWriteTurn = () => Promise<(() => Promise<void>) | null>;
+
+/** Run `write` inside one write turn, or report that the gate is held elsewhere. */
+export async function inWriteTurn<T>(
+  acquire: AcquireWriteTurn | undefined,
+  write: () => Promise<T>
+): Promise<{ deferred: true } | { deferred: false; value: T }> {
+  if (!acquire) return { deferred: false, value: await write() };
+  const release = await acquire();
+  if (!release) return { deferred: true };
+  try {
+    return { deferred: false, value: await write() };
+  } finally {
+    await release();
+  }
+}
 export const MAX_EMBED_FAILURE_SAMPLES = 5;
 
 /** Total upsert attempts (initial + retries) when persistence hits SQLITE_BUSY/LOCKED. */
@@ -44,6 +66,8 @@ export interface EmbedStoreBatchResult {
   suggestion?: string;
   batchFailed: boolean;
   batchError?: string;
+  /** The write gate was held elsewhere; nothing was persisted. */
+  deferred?: boolean;
 }
 
 // fn-127 integration: CLI consumers (src/cli/commands/embed.ts,
@@ -173,6 +197,8 @@ export async function embedAndStoreBatch(params: {
   identityStillCurrent?: () => boolean;
   /** Test seam: override contention-retry delays in milliseconds. */
   delays?: number[];
+  /** Gate held only around persistence, never around inference. */
+  acquireWriteTurn?: AcquireWriteTurn;
 }): Promise<EmbedStoreBatchResult> {
   const { embedPort, vectorIndex, items, modelUri, embedFingerprint } = params;
   const db = params.statsPort && getVectorStatsDatabase(params.statsPort);
@@ -282,35 +308,48 @@ export async function embedAndStoreBatch(params: {
       );
     });
   };
-  const storeResult = await upsertVectorsWithContentionRetry(
-    {
-      upsertVectors: async (rows) => {
-        if (vectorIndex.upsertVectorsChecked) {
-          const result = await vectorIndex.upsertVectorsChecked(
-            rows,
-            (candidates) => {
-              committedRows = checkpoint(candidates);
-              return committedRows;
-            }
-          );
-          if (!result.ok) return result;
-          written = result.value;
-          return ok(undefined);
-        }
-        if (db)
-          return err("INVALID_INPUT", "Atomic vector checkpoint unavailable");
-        const valid = checkpoint(rows);
-        const result = await vectorIndex.upsertVectors(valid);
-        if (result.ok) {
-          written = valid.length;
-          committedRows = valid;
-        }
-        return result;
+  const turn = await inWriteTurn(params.acquireWriteTurn, () =>
+    upsertVectorsWithContentionRetry(
+      {
+        upsertVectors: async (rows) => {
+          if (vectorIndex.upsertVectorsChecked) {
+            const result = await vectorIndex.upsertVectorsChecked(
+              rows,
+              (candidates) => {
+                committedRows = checkpoint(candidates);
+                return committedRows;
+              }
+            );
+            if (!result.ok) return result;
+            written = result.value;
+            return ok(undefined);
+          }
+          if (db)
+            return err("INVALID_INPUT", "Atomic vector checkpoint unavailable");
+          const valid = checkpoint(rows);
+          const result = await vectorIndex.upsertVectors(valid);
+          if (result.ok) {
+            written = valid.length;
+            committedRows = valid;
+          }
+          return result;
+        },
       },
-    },
-    vectors,
-    params.delays
+      vectors,
+      params.delays
+    )
   );
+  if (turn.deferred)
+    return {
+      embedded: 0,
+      errors: 0,
+      contentionErrors: 0,
+      retryItems: [],
+      errorSamples: [],
+      batchFailed: false,
+      deferred: true,
+    };
+  const storeResult = turn.value;
   if (!storeResult.ok) {
     if (isUpsertLockContention(storeResult.error)) {
       return {

package/src/embed/variant-backlog.ts

@@ -8,6 +8,7 @@ import {
 } from "../llm/inference-scope";
 import { err, ok } from "../store/types";
 import { getVectorStatsDatabase } from "../store/vector/stats";
+import { inWriteTurn } from "./retry";
 import { variantBacklogPage } from "./variant-plan";
 import { embedVariantBatch } from "./variant-retry";
 
@@ -59,7 +60,9 @@ export async function embedVariantBacklog(
         owners,
         identityStillCurrent,
         force: deps.force,
+        acquireWriteTurn: deps.acquireWriteTurn,
       });
+      if (result.deferred) return ok({ ...total, deferred: true });
       total.embedded += result.embedded;
       total.errors += result.errors;
       total.contentionErrors += result.contentionErrors;
@@ -83,16 +86,18 @@ export async function embedVariantBacklog(
     // Capture the epoch before checking completeness; activate rechecks under write lock.
     const epoch = store.epoch();
     if (identityStillCurrent() && !store.pending({ limit: 1 }).length) {
-      try {
-        if (!store.isActive()) store.syncIndex();
-        if (!identityStillCurrent()) return ok(total);
-        store.activate(epoch);
-      } catch (cause) {
-        return ok({
-          ...total,
-          syncError: cause instanceof Error ? cause.message : String(cause),
-        });
-      }
+      const turn = await inWriteTurn(deps.acquireWriteTurn, async () => {
+        try {
+          if (!store.isActive()) store.syncIndex();
+          if (identityStillCurrent()) store.activate(epoch);
+          return undefined;
+        } catch (cause) {
+          return cause instanceof Error ? cause.message : String(cause);
+        }
+      });
+      if (turn.deferred) return ok({ ...total, deferred: true });
+      if (turn.value !== undefined)
+        return ok({ ...total, syncError: turn.value });
     }
     assertInferenceActive();
     return ok(total);