@gmickel/gno 1.37.1 → 1.39.0

package/src/embed/retry.ts

@@ -1,15 +1,36 @@
 import type { EmbeddingPort } from "../llm/types";
+import type { StoreResult } from "../store/types";
 import type { BacklogItem, VectorIndexPort, VectorRow } from "../store/vector";
 
+import { isSqliteLockContention } from "../core/file-lock";
 import { formatDocForEmbedding } from "../pipeline/contextual";
 import { embedTextsWithRecovery } from "./batch";
 
 export const MAX_EMBED_CHUNK_ATTEMPTS = 2;
 export const MAX_EMBED_FAILURE_SAMPLES = 5;
 
+/** Total upsert attempts (initial + retries) when persistence hits SQLITE_BUSY/LOCKED. */
+export const UPSERT_CONTENTION_MAX_ATTEMPTS = 5;
+export const UPSERT_CONTENTION_BASE_DELAY_MS = 250;
+export const UPSERT_CONTENTION_BACKOFF_FACTOR = 2;
+export const UPSERT_CONTENTION_JITTER_RATIO = 0.25;
+export const UPSERT_CONTENTION_MAX_DELAY_MS = 5_000;
+
+export const UPSERT_CONTENTION_ERROR_SAMPLE =
+  "index is busy (SQLITE_BUSY) — another writer holds the database; rerun `gno embed`";
+
+export const STORE_WRITE_FAILURE_SUGGESTION =
+  "Store write failed. Rerun `gno embed` once more; if it repeats, run `gno doctor` and `gno vec sync`.";
+
 export interface EmbedStoreBatchResult {
   embedded: number;
   errors: number;
+  /**
+   * Chunks whose persistence failed after SQLITE_BUSY/SQLITE_LOCKED retries.
+   * Distinct from `errors` (embedding-provider / non-contention store failures).
+   * Default 0.
+   */
+  contentionErrors: number;
   retryItems: BacklogItem[];
   errorSamples: string[];
   suggestion?: string;
@@ -17,6 +38,10 @@ export interface EmbedStoreBatchResult {
   batchError?: string;
 }
 
+// fn-127 integration: CLI consumers (src/cli/commands/embed.ts,
+// src/cli/commands/index-cmd.ts) must surface contentionErrors in their
+// summary and exit non-zero — the integrator wires that.
+
 export function chunkRetryKey(item: Pick<BacklogItem, "mirrorHash" | "seq">) {
   return `${item.mirrorHash}\0${item.seq}`;
 }
@@ -52,12 +77,81 @@ export function formatLlmFailure(
     : error.message;
 }
 
+/**
+ * Classify a store-layer failure as SQLite lock contention.
+ * Matches SQLITE_BUSY/LOCKED on the error itself (stubs) or its `cause`
+ * (upsertVectors preserves the original SQLite error there).
+ */
+export function isUpsertLockContention(error: {
+  code?: unknown;
+  cause?: unknown;
+}): boolean {
+  return isSqliteLockContention(error) || isSqliteLockContention(error.cause);
+}
+
+/**
+ * Delay before the next upsert retry after `failedAttemptIndex` (0-based)
+ * contention failures. Formula: base * factor^attempt ± jitter, capped.
+ */
+export function upsertContentionDelayMs(
+  failedAttemptIndex: number,
+  random: () => number = Math.random
+): number {
+  const exponential =
+    UPSERT_CONTENTION_BASE_DELAY_MS *
+    UPSERT_CONTENTION_BACKOFF_FACTOR ** failedAttemptIndex;
+  const jitterMultiplier =
+    1 + (random() * 2 - 1) * UPSERT_CONTENTION_JITTER_RATIO;
+  return Math.min(
+    UPSERT_CONTENTION_MAX_DELAY_MS,
+    Math.max(0, exponential * jitterMultiplier)
+  );
+}
+
+function resolveContentionDelayMs(
+  failedAttemptIndex: number,
+  delays: number[] | undefined
+): number {
+  if (delays) {
+    return delays[failedAttemptIndex] ?? 0;
+  }
+  return upsertContentionDelayMs(failedAttemptIndex);
+}
+
+/**
+ * Retry `upsertVectors` on SQLITE_BUSY/SQLITE_LOCKED with exponential backoff.
+ * `delays` is a test seam that replaces the computed schedule (missing slots = 0).
+ */
+export async function upsertVectorsWithContentionRetry(
+  vectorIndex: Pick<VectorIndexPort, "upsertVectors">,
+  vectors: VectorRow[],
+  delays?: number[]
+): Promise<StoreResult<void>> {
+  let storeResult = await vectorIndex.upsertVectors(vectors);
+  let attempts = 1;
+  while (
+    !storeResult.ok &&
+    isUpsertLockContention(storeResult.error) &&
+    attempts < UPSERT_CONTENTION_MAX_ATTEMPTS
+  ) {
+    const delayMs = resolveContentionDelayMs(attempts - 1, delays);
+    if (delayMs > 0) {
+      await Bun.sleep(delayMs);
+    }
+    storeResult = await vectorIndex.upsertVectors(vectors);
+    attempts += 1;
+  }
+  return storeResult;
+}
+
 export async function embedAndStoreBatch(params: {
   embedPort: EmbeddingPort;
   vectorIndex: VectorIndexPort;
   items: BacklogItem[];
   modelUri: string;
   embedFingerprint: string;
+  /** Test seam: override contention-retry delays in milliseconds. */
+  delays?: number[];
 }): Promise<EmbedStoreBatchResult> {
   const { embedPort, vectorIndex, items, modelUri, embedFingerprint } = params;
   const embedResult = await embedTextsWithRecovery(
@@ -72,6 +166,7 @@ export async function embedAndStoreBatch(params: {
     return {
       embedded: 0,
       errors: embedResult.error.retryable ? 0 : items.length,
+      contentionErrors: 0,
       retryItems: embedResult.error.retryable ? items : [],
       errorSamples: [formattedError],
       suggestion: embedResult.error.retryable
@@ -103,6 +198,7 @@ export async function embedAndStoreBatch(params: {
     return {
       embedded: 0,
       errors: 0,
+      contentionErrors: 0,
       retryItems,
       errorSamples: embedResult.value.failureSamples,
       suggestion: embedResult.value.retrySuggestion,
@@ -111,15 +207,31 @@ export async function embedAndStoreBatch(params: {
     };
   }
 
-  const storeResult = await vectorIndex.upsertVectors(vectors);
+  const storeResult = await upsertVectorsWithContentionRetry(
+    vectorIndex,
+    vectors,
+    params.delays
+  );
   if (!storeResult.ok) {
+    if (isUpsertLockContention(storeResult.error)) {
+      return {
+        embedded: 0,
+        errors: 0,
+        contentionErrors: vectors.length,
+        retryItems,
+        errorSamples: [UPSERT_CONTENTION_ERROR_SAMPLE],
+        suggestion: UPSERT_CONTENTION_ERROR_SAMPLE,
+        batchFailed: embedResult.value.batchFailed,
+        batchError: embedResult.value.batchError,
+      };
+    }
     return {
       embedded: 0,
       errors: vectors.length,
+      contentionErrors: 0,
       retryItems,
       errorSamples: [storeResult.error.message],
-      suggestion:
-        "Store write failed. Rerun `gno embed` once more; if it repeats, run `gno doctor` and `gno vec sync`.",
+      suggestion: STORE_WRITE_FAILURE_SUGGESTION,
       batchFailed: embedResult.value.batchFailed,
       batchError: embedResult.value.batchError,
     };
@@ -128,6 +240,7 @@ export async function embedAndStoreBatch(params: {
   return {
     embedded: vectors.length,
     errors: 0,
+    contentionErrors: 0,
     retryItems,
     errorSamples: embedResult.value.failureSamples,
     suggestion: embedResult.value.retrySuggestion,

package/src/sdk/client.ts

@@ -276,7 +276,9 @@ async function resolveClientState(
 
   const store = new SqliteAdapter();
   store.setConfigPath(configPath ?? "<inline-config>");
-  unwrapStore(await store.open(dbPath, config.ftsTokenizer));
+  unwrapStore(
+    await store.open(dbPath, config.ftsTokenizer, config.busyTimeoutMs)
+  );
   unwrapStore(await store.syncCollections(config.collections));
   unwrapStore(await store.syncContexts(config.contexts ?? []));
 

package/src/sdk/embed.ts

@@ -117,9 +117,10 @@ async function forceEmbedAll(
   vectorIndex: VectorIndexPort,
   modelUri: string,
   batchSize: number
-): Promise<{ embedded: number; errors: number }> {
+): Promise<{ embedded: number; errors: number; contentionErrors: number }> {
   let embedded = 0;
   let errors = 0;
+  let contentionErrors = 0;
   let cursor: { mirrorHash: string; seq: number } | undefined;
   const retryQueue = new Map<string, { item: BacklogItem; attempts: number }>();
   const embedFingerprint = getEmbeddingFingerprint({
@@ -164,6 +165,7 @@ async function forceEmbedAll(
       });
       embedded += retryResult.embedded;
       errors += retryResult.errors;
+      contentionErrors += retryResult.contentionErrors;
       retryEmbedded += retryResult.embedded;
 
       const retryByKey = new Set(
@@ -212,6 +214,7 @@ async function forceEmbedAll(
     });
     embedded += embedResult.embedded;
     errors += embedResult.errors;
+    contentionErrors += embedResult.contentionErrors;
     enqueueRetryItems(embedResult.retryItems, 1);
 
     if (embedded > beforeEmbedded) {
@@ -232,7 +235,7 @@ async function forceEmbedAll(
     }
   }
 
-  return { embedded, errors };
+  return { embedded, errors, contentionErrors };
 }
 
 async function checkVecAvailable(db: Database): Promise<boolean> {
@@ -343,7 +346,7 @@ export async function runEmbed(
     }
 
     const startedAt = Date.now();
-    let result: { embedded: number; errors: number };
+    let result: { embedded: number; errors: number; contentionErrors: number };
     if (force) {
       result = await forceEmbedAll(
         db,
@@ -369,12 +372,14 @@ export async function runEmbed(
       result = {
         embedded: processed.value.embedded,
         errors: processed.value.errors,
+        contentionErrors: processed.value.contentionErrors ?? 0,
       };
     }
 
     return {
       embedded: result.embedded,
       errors: result.errors,
+      contentionErrors: result.contentionErrors,
       duration: (Date.now() - startedAt) / 1000,
       model: modelUri,
       searchAvailable: vectorIndex.searchAvailable,

package/src/sdk/types.ts

@@ -204,6 +204,8 @@ export interface GnoEmbedOptions {
 export interface GnoEmbedResult {
   embedded: number;
   errors: number;
+  /** Persistence lock-contention failures; distinct from embedding-provider `errors`. */
+  contentionErrors?: number;
   duration: number;
   model: string;
   searchAvailable: boolean;

package/src/serve/embed-scheduler.ts

@@ -130,6 +130,14 @@ export function createEmbedScheduler(deps: EmbedSchedulerDeps): EmbedScheduler {
         console.error("[embed-scheduler] Embed failed:", result.error.message);
         return { embedded: 0, errors: 0 };
       }
+      if ((result.value.contentionErrors ?? 0) > 0) {
+        // Chunks deferred by SQLITE_BUSY stay in the backlog; retry the run
+        // instead of silently leaving embeddings a pass behind (fn-127 R6).
+        console.error(
+          `[embed-scheduler] ${result.value.contentionErrors} chunks deferred by index contention; rescheduling`
+        );
+        needsRerun = true;
+      }
       if (result.value.embedded > 0) onEmbedded?.(result.value);
       return result.value;
     } finally {

package/src/serve/resident-runtime.ts

@@ -212,7 +212,11 @@ export async function startResidentRuntime(
   const paths = (deps.getConfigPaths ?? getConfigPaths)();
   const actualConfigPath = resolve(options.configPath ?? paths.configFile);
   store.setConfigPath(actualConfigPath);
-  const openResult = await store.open(dbPath, initialConfig.ftsTokenizer);
+  const openResult = await store.open(
+    dbPath,
+    initialConfig.ftsTokenizer,
+    initialConfig.busyTimeoutMs
+  );
   if (!openResult.ok) {
     await ownerLock.release();
     return { success: false, error: openResult.error.message };

package/src/store/sqlite/adapter.ts

@@ -114,9 +114,12 @@ import { buildUri, deriveDocid, stripUriIndex } from "../../app/constants";
 import {
   type Collection,
   type Context,
+  DEFAULT_BUSY_TIMEOUT_MS,
   type EgressPolicy,
   type EgressPolicySource,
   type FtsTokenizer,
+  MAX_BUSY_TIMEOUT_MS,
+  MIN_BUSY_TIMEOUT_MS,
   resolveConfiguredEgressPolicy,
 } from "../../config/types";
 import {
@@ -476,6 +479,19 @@ function isDatabaseLockedError(cause: unknown): boolean {
   );
 }
 
+/** Resolve a caller-supplied busy_timeout, defaulting rather than using 0. */
+function resolveBusyTimeoutMs(busyTimeoutMs?: number): number {
+  if (
+    busyTimeoutMs === undefined ||
+    !Number.isInteger(busyTimeoutMs) ||
+    busyTimeoutMs < MIN_BUSY_TIMEOUT_MS ||
+    busyTimeoutMs > MAX_BUSY_TIMEOUT_MS
+  ) {
+    return DEFAULT_BUSY_TIMEOUT_MS;
+  }
+  return busyTimeoutMs;
+}
+
 export class SqliteAdapter implements StorePort, SqliteDbProvider {
   private db: Database | null = null;
   private dbPath = "";
@@ -492,7 +508,8 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
 
   async open(
     dbPath: string,
-    ftsTokenizer: FtsTokenizer
+    ftsTokenizer: FtsTokenizer,
+    busyTimeoutMs: number = DEFAULT_BUSY_TIMEOUT_MS
   ): Promise<StoreResult<MigrationResult>> {
     try {
       this.db = new Database(dbPath, { create: true });
@@ -501,7 +518,9 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
 
       // Enable pragmas for performance and safety
       this.db.exec("PRAGMA foreign_keys = ON");
-      this.db.exec("PRAGMA busy_timeout = 5000");
+      this.db.exec(
+        `PRAGMA busy_timeout = ${resolveBusyTimeoutMs(busyTimeoutMs)}`
+      );
 
       // Keep WAL everywhere so readers can continue while a writer is active.
       // CI still relaxes fsync/temp-store for speed, but MEMORY journal mode
@@ -558,12 +577,17 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
   }
 
   /** Open an existing index with SQLite enforced query-only semantics. */
-  openReadOnly(dbPath: string): StoreResult<void> {
+  openReadOnly(
+    dbPath: string,
+    busyTimeoutMs: number = DEFAULT_BUSY_TIMEOUT_MS
+  ): StoreResult<void> {
     try {
       this.db = new Database(dbPath, { readonly: true, strict: true });
       this.dbPath = dbPath;
       this.db.exec("PRAGMA query_only = ON");
-      this.db.exec("PRAGMA busy_timeout = 5000");
+      this.db.exec(
+        `PRAGMA busy_timeout = ${resolveBusyTimeoutMs(busyTimeoutMs)}`
+      );
       this.contextGeneration += 1;
       return ok(undefined);
     } catch (cause) {

package/src/store/sqlite/scoped-index.ts

@@ -38,7 +38,11 @@ export async function openScopedIndexStore(options: {
 
   const store = new SqliteAdapter();
   store.setConfigPath(options.configPath ?? "<inline-config>");
-  const openResult = await store.open(dbPath, options.config.ftsTokenizer);
+  const openResult = await store.open(
+    dbPath,
+    options.config.ftsTokenizer,
+    options.config.busyTimeoutMs
+  );
   if (!openResult.ok) {
     throw new Error(openResult.error.message);
   }

package/src/store/vector/sqlite-vec.ts

@@ -193,7 +193,8 @@ export async function createVectorIndexPort(
         return Promise.resolve(
           err(
             "VECTOR_WRITE_FAILED",
-            `Vector write failed: ${e instanceof Error ? e.message : String(e)}`
+            `Vector write failed: ${e instanceof Error ? e.message : String(e)}`,
+            e
           )
         );
       }

package/browser-extension/artifacts/gno-browser-clipper-v1.37.1.zip.sha256

@@ -1 +0,0 @@
-6954195a14c9cdff85a265043590873823a0b25b287866c036d83153a95b8b14  gno-browser-clipper-v1.37.1.zip