@gmickel/gno 1.6.0 → 1.7.1

package/src/embed/backlog.ts

@@ -10,13 +10,16 @@ import type { StoreResult } from "../store/types";
 import type {
   BacklogItem,
   VectorIndexPort,
-  VectorRow,
   VectorStatsPort,
 } from "../store/vector";
 
-import { formatDocForEmbedding } from "../pipeline/contextual";
 import { err, ok } from "../store/types";
-import { embedTextsWithRecovery } from "./batch";
+import { getEmbeddingFingerprint } from "./fingerprint";
+import {
+  chunkRetryKey,
+  embedAndStoreBatch,
+  MAX_EMBED_CHUNK_ATTEMPTS,
+} from "./retry";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types
@@ -56,19 +59,86 @@ export async function embedBacklog(
 ): Promise<StoreResult<EmbedBacklogResult>> {
   const { statsPort, embedPort, vectorIndex, modelUri, collection } = deps;
   const batchSize = deps.batchSize ?? 32;
+  const embedFingerprint = getEmbeddingFingerprint({
+    modelUri,
+    dimensions: vectorIndex.dimensions,
+  });
 
   let embedded = 0;
   let errors = 0;
   let cursor: Cursor | undefined;
+  const retryQueue = new Map<string, { item: BacklogItem; attempts: number }>();
+
+  const enqueueRetryItems = (items: BacklogItem[], attempts: number): void => {
+    for (const item of items) {
+      const key = chunkRetryKey(item);
+      const existing = retryQueue.get(key);
+      retryQueue.set(key, {
+        item,
+        attempts: Math.max(existing?.attempts ?? 0, attempts),
+      });
+    }
+  };
+
+  const drainRetryQueue = async (): Promise<number> => {
+    if (retryQueue.size === 0) {
+      return 0;
+    }
+
+    let retryEmbedded = 0;
+    const entries = [...retryQueue.values()].filter(
+      (entry) => entry.attempts < MAX_EMBED_CHUNK_ATTEMPTS
+    );
+
+    for (let idx = 0; idx < entries.length; idx += batchSize) {
+      const slice = entries.slice(idx, idx + batchSize);
+      for (const entry of slice) {
+        retryQueue.delete(chunkRetryKey(entry.item));
+        entry.attempts += 1;
+      }
+
+      const retryResult = await embedAndStoreBatch({
+        embedPort,
+        vectorIndex,
+        items: slice.map((entry) => entry.item),
+        modelUri,
+        embedFingerprint,
+      });
+
+      embedded += retryResult.embedded;
+      errors += retryResult.errors;
+      retryEmbedded += retryResult.embedded;
+
+      const retryByKey = new Set(
+        retryResult.retryItems.map((item) => chunkRetryKey(item))
+      );
+      for (const entry of slice) {
+        if (!retryByKey.has(chunkRetryKey(entry.item))) {
+          continue;
+        }
+        if (entry.attempts >= MAX_EMBED_CHUNK_ATTEMPTS) {
+          errors += 1;
+        } else {
+          retryQueue.set(chunkRetryKey(entry.item), entry);
+        }
+      }
+    }
+
+    return retryEmbedded;
+  };
 
   try {
     while (true) {
       // Get next batch using seek pagination
-      const batchResult = await statsPort.getBacklog(modelUri, {
-        limit: batchSize,
-        after: cursor,
-        collection,
-      });
+      const batchResult = await statsPort.getBacklog(
+        modelUri,
+        embedFingerprint,
+        {
+          limit: batchSize,
+          after: cursor,
+          collection,
+        }
+      );
 
       if (!batchResult.ok) {
         return err("QUERY_FAILED", batchResult.error.message);
@@ -85,48 +155,25 @@ export async function embedBacklog(
         cursor = { mirrorHash: lastItem.mirrorHash, seq: lastItem.seq };
       }
 
-      // Embed batch with contextual formatting (title prefix)
-      const embedResult = await embedTextsWithRecovery(
+      const beforeEmbedded = embedded;
+      const batchStoreResult = await embedAndStoreBatch({
         embedPort,
-        batch.map((b: BacklogItem) =>
-          formatDocForEmbedding(
-            b.text,
-            b.title ?? undefined,
-            embedPort.modelUri
-          )
-        )
-      );
-
-      if (!embedResult.ok) {
-        errors += batch.length;
-        continue;
-      }
-
-      const vectors: VectorRow[] = [];
-      for (const [idx, item] of batch.entries()) {
-        const embedding = embedResult.value.vectors[idx];
-        if (!embedding) {
-          errors += 1;
-          continue;
-        }
-        vectors.push({
-          mirrorHash: item.mirrorHash,
-          seq: item.seq,
-          model: modelUri,
-          embedding: new Float32Array(embedding),
-        });
-      }
+        vectorIndex,
+        items: batch,
+        modelUri,
+        embedFingerprint,
+      });
+      embedded += batchStoreResult.embedded;
+      errors += batchStoreResult.errors;
+      enqueueRetryItems(batchStoreResult.retryItems, 1);
 
-      if (vectors.length > 0) {
-        const storeResult = await vectorIndex.upsertVectors(vectors);
-        if (!storeResult.ok) {
-          errors += vectors.length;
-          continue;
-        }
-        embedded += vectors.length;
+      if (embedded > beforeEmbedded) {
+        await drainRetryQueue();
       }
     }
 
+    await drainRetryQueue();
+
     // Sync vec index once at end if any vec0 writes failed
     let syncError: string | undefined;
     if (vectorIndex.vecDirty) {

package/src/embed/fingerprint.ts

@@ -0,0 +1,37 @@
+/**
+ * Embedding freshness fingerprint.
+ *
+ * @module src/embed/fingerprint
+ */
+
+import { getEmbeddingCompatibilityProfile } from "../llm/embedding-compatibility";
+
+export const EMBEDDING_CONTEXTUAL_FORMAT_VERSION = "contextual-embedding-v1";
+export const EMBEDDING_CHUNKING_STRATEGY_VERSION = "markdown-char-semantic-v1";
+
+export interface EmbeddingFingerprintInput {
+  modelUri: string;
+  dimensions?: number;
+}
+
+export function getEmbeddingFingerprint(
+  input: EmbeddingFingerprintInput
+): string {
+  const profile = getEmbeddingCompatibilityProfile(input.modelUri);
+  const payload = {
+    chunking: EMBEDDING_CHUNKING_STRATEGY_VERSION,
+    contextualFormatting: EMBEDDING_CONTEXTUAL_FORMAT_VERSION,
+    dimensions: input.dimensions ?? null,
+    modelUri: input.modelUri,
+    profile: {
+      batchEmbeddingTrusted: profile.batchEmbeddingTrusted,
+      documentFormat: profile.documentFormat,
+      id: profile.id,
+      queryFormat: profile.queryFormat,
+    },
+  };
+
+  return new Bun.CryptoHasher("sha256")
+    .update(JSON.stringify(payload))
+    .digest("hex");
+}

package/src/embed/retry.ts

@@ -0,0 +1,137 @@
+import type { EmbeddingPort } from "../llm/types";
+import type { BacklogItem, VectorIndexPort, VectorRow } from "../store/vector";
+
+import { formatDocForEmbedding } from "../pipeline/contextual";
+import { embedTextsWithRecovery } from "./batch";
+
+export const MAX_EMBED_CHUNK_ATTEMPTS = 2;
+export const MAX_EMBED_FAILURE_SAMPLES = 5;
+
+export interface EmbedStoreBatchResult {
+  embedded: number;
+  errors: number;
+  retryItems: BacklogItem[];
+  errorSamples: string[];
+  suggestion?: string;
+  batchFailed: boolean;
+  batchError?: string;
+}
+
+export function chunkRetryKey(item: Pick<BacklogItem, "mirrorHash" | "seq">) {
+  return `${item.mirrorHash}\0${item.seq}`;
+}
+
+export function addUniqueSamples(target: string[], samples: string[]): void {
+  for (const sample of samples) {
+    if (target.length >= MAX_EMBED_FAILURE_SAMPLES) {
+      break;
+    }
+    if (!target.includes(sample)) {
+      target.push(sample);
+    }
+  }
+}
+
+export function formatLlmFailure(
+  error: { message: string; cause?: unknown } | undefined
+): string {
+  if (!error) {
+    return "Unknown embedding failure";
+  }
+  const cause =
+    error.cause &&
+    typeof error.cause === "object" &&
+    "message" in error.cause &&
+    typeof error.cause.message === "string"
+      ? error.cause.message
+      : typeof error.cause === "string"
+        ? error.cause
+        : "";
+  return cause && cause !== error.message
+    ? `${error.message} - ${cause}`
+    : error.message;
+}
+
+export async function embedAndStoreBatch(params: {
+  embedPort: EmbeddingPort;
+  vectorIndex: VectorIndexPort;
+  items: BacklogItem[];
+  modelUri: string;
+  embedFingerprint: string;
+}): Promise<EmbedStoreBatchResult> {
+  const { embedPort, vectorIndex, items, modelUri, embedFingerprint } = params;
+  const embedResult = await embedTextsWithRecovery(
+    embedPort,
+    items.map((item) =>
+      formatDocForEmbedding(item.text, item.title ?? undefined, modelUri)
+    )
+  );
+
+  if (!embedResult.ok) {
+    const formattedError = formatLlmFailure(embedResult.error);
+    return {
+      embedded: 0,
+      errors: embedResult.error.retryable ? 0 : items.length,
+      retryItems: embedResult.error.retryable ? items : [],
+      errorSamples: [formattedError],
+      suggestion: embedResult.error.retryable
+        ? "Try rerunning the same command. If failures persist, rerun with `gno --verbose embed --batch-size 1` to isolate failing chunks."
+        : embedResult.error.suggestion,
+      batchFailed: true,
+      batchError: formattedError,
+    };
+  }
+
+  const vectors: VectorRow[] = [];
+  const retryItems: BacklogItem[] = [];
+  for (const [idx, item] of items.entries()) {
+    const embedding = embedResult.value.vectors[idx];
+    if (!embedding) {
+      retryItems.push(item);
+      continue;
+    }
+    vectors.push({
+      mirrorHash: item.mirrorHash,
+      seq: item.seq,
+      model: modelUri,
+      embedFingerprint,
+      embedding: new Float32Array(embedding),
+    });
+  }
+
+  if (vectors.length === 0) {
+    return {
+      embedded: 0,
+      errors: 0,
+      retryItems,
+      errorSamples: embedResult.value.failureSamples,
+      suggestion: embedResult.value.retrySuggestion,
+      batchFailed: embedResult.value.batchFailed,
+      batchError: embedResult.value.batchError,
+    };
+  }
+
+  const storeResult = await vectorIndex.upsertVectors(vectors);
+  if (!storeResult.ok) {
+    return {
+      embedded: 0,
+      errors: vectors.length,
+      retryItems,
+      errorSamples: [storeResult.error.message],
+      suggestion:
+        "Store write failed. Rerun `gno embed` once more; if it repeats, run `gno doctor` and `gno vec sync`.",
+      batchFailed: embedResult.value.batchFailed,
+      batchError: embedResult.value.batchError,
+    };
+  }
+
+  return {
+    embedded: vectors.length,
+    errors: 0,
+    retryItems,
+    errorSamples: embedResult.value.failureSamples,
+    suggestion: embedResult.value.retrySuggestion,
+    batchFailed: embedResult.value.batchFailed,
+    batchError: embedResult.value.batchError,
+  };
+}

package/src/mcp/tools/index.ts

@@ -456,7 +456,11 @@ export const queryInputSchema = z.object({
   noGraph: z
     .boolean()
     .optional()
-    .describe("Disable bounded one-hop graph neighbor expansion"),
+    .describe("Compatibility no-op unless graph is also true"),
+  graph: z
+    .boolean()
+    .optional()
+    .describe("Enable bounded one-hop graph neighbor expansion"),
   tagsAll: z.array(z.string()).optional().describe("Require ALL of these tags"),
   tagsAny: z.array(z.string()).optional().describe("Require ANY of these tags"),
 });

package/src/mcp/tools/query.ts

@@ -51,6 +51,7 @@ interface QueryInput {
   expand?: boolean;
   rerank?: boolean;
   noGraph?: boolean;
+  graph?: boolean;
   tagsAll?: string[];
   tagsAny?: string[];
 }
@@ -272,6 +273,7 @@ export function handleQuery(
           author: args.author,
           noExpand,
           noRerank,
+          graph: args.graph === true,
           noGraph: args.noGraph || args.fast,
           queryModes,
           tagsAll: normalizeTagFilters(args.tagsAll),

package/src/pipeline/hybrid.ts

@@ -554,7 +554,7 @@ export async function searchHybrid(
     includeSimilar: vectorAvailable,
     limit,
     candidateLimit,
-    disabled: options.noGraph,
+    disabled: !options.graph || options.noGraph,
     lang: options.lang,
     tagsAll: options.tagsAll,
     tagsAny: options.tagsAny,

package/src/pipeline/types.ts

@@ -174,7 +174,9 @@ export type HybridSearchOptions = SearchOptions & {
   candidateLimit?: number;
   /** Enable explain output */
   explain?: boolean;
-  /** Disable bounded one-hop graph candidate expansion */
+  /** Enable bounded one-hop graph candidate expansion */
+  graph?: boolean;
+  /** Compatibility no-op unless graph is also true */
   noGraph?: boolean;
   /** Language hint for prompt selection (does NOT filter retrieval, only affects expansion prompts) */
   queryLanguageHint?: string;

package/src/sdk/embed.ts

@@ -19,15 +19,15 @@ import type {
 import type { GnoEmbedOptions, GnoEmbedResult } from "./types";
 
 import { embedBacklog } from "../embed";
-import { embedTextsWithRecovery } from "../embed/batch";
+import { getEmbeddingFingerprint } from "../embed/fingerprint";
+import {
+  chunkRetryKey,
+  embedAndStoreBatch,
+  MAX_EMBED_CHUNK_ATTEMPTS,
+} from "../embed/retry";
 import { resolveModelUri } from "../llm/registry";
-import { formatDocForEmbedding } from "../pipeline/contextual";
 import { err, ok } from "../store/types";
-import {
-  createVectorIndexPort,
-  createVectorStatsPort,
-  type VectorRow,
-} from "../store/vector";
+import { createVectorIndexPort, createVectorStatsPort } from "../store/vector";
 import { sdkError } from "./errors";
 
 interface EmbedRuntimeOptions {
@@ -121,6 +121,68 @@ async function forceEmbedAll(
   let embedded = 0;
   let errors = 0;
   let cursor: { mirrorHash: string; seq: number } | undefined;
+  const retryQueue = new Map<string, { item: BacklogItem; attempts: number }>();
+  const embedFingerprint = getEmbeddingFingerprint({
+    modelUri,
+    dimensions: vectorIndex.dimensions,
+  });
+
+  const enqueueRetryItems = (items: BacklogItem[], attempts: number): void => {
+    for (const item of items) {
+      const key = chunkRetryKey(item);
+      const existing = retryQueue.get(key);
+      retryQueue.set(key, {
+        item,
+        attempts: Math.max(existing?.attempts ?? 0, attempts),
+      });
+    }
+  };
+
+  const drainRetryQueue = async (): Promise<number> => {
+    if (retryQueue.size === 0) {
+      return 0;
+    }
+
+    let retryEmbedded = 0;
+    const entries = [...retryQueue.values()].filter(
+      (entry) => entry.attempts < MAX_EMBED_CHUNK_ATTEMPTS
+    );
+
+    for (let idx = 0; idx < entries.length; idx += batchSize) {
+      const slice = entries.slice(idx, idx + batchSize);
+      for (const entry of slice) {
+        retryQueue.delete(chunkRetryKey(entry.item));
+        entry.attempts += 1;
+      }
+
+      const retryResult = await embedAndStoreBatch({
+        embedPort,
+        vectorIndex,
+        items: slice.map((entry) => entry.item),
+        modelUri,
+        embedFingerprint,
+      });
+      embedded += retryResult.embedded;
+      errors += retryResult.errors;
+      retryEmbedded += retryResult.embedded;
+
+      const retryByKey = new Set(
+        retryResult.retryItems.map((item) => chunkRetryKey(item))
+      );
+      for (const entry of slice) {
+        if (!retryByKey.has(chunkRetryKey(entry.item))) {
+          continue;
+        }
+        if (entry.attempts >= MAX_EMBED_CHUNK_ATTEMPTS) {
+          errors += 1;
+        } else {
+          retryQueue.set(chunkRetryKey(entry.item), entry);
+        }
+      }
+    }
+
+    return retryEmbedded;
+  };
 
   while (true) {
     const batchResult = await getActiveChunks(db, batchSize, cursor);
@@ -140,45 +202,27 @@ async function forceEmbedAll(
       cursor = { mirrorHash: lastItem.mirrorHash, seq: lastItem.seq };
     }
 
-    const embedResult = await embedTextsWithRecovery(
+    const beforeEmbedded = embedded;
+    const embedResult = await embedAndStoreBatch({
       embedPort,
-      batch.map((item) =>
-        formatDocForEmbedding(
-          item.text,
-          item.title ?? undefined,
-          embedPort.modelUri
-        )
-      )
-    );
-
-    if (!embedResult.ok) {
-      errors += batch.length;
-      continue;
-    }
+      vectorIndex,
+      items: batch,
+      modelUri,
+      embedFingerprint,
+    });
+    embedded += embedResult.embedded;
+    errors += embedResult.errors;
+    enqueueRetryItems(embedResult.retryItems, 1);
 
-    const vectors: VectorRow[] = [];
-    for (const [idx, item] of batch.entries()) {
-      const embedding = embedResult.value.vectors[idx];
-      if (!embedding) {
-        errors += 1;
-        continue;
-      }
-      vectors.push({
-        mirrorHash: item.mirrorHash,
-        seq: item.seq,
-        model: modelUri,
-        embedding: new Float32Array(embedding),
-      });
+    if (embedded > beforeEmbedded) {
+      await drainRetryQueue();
     }
+  }
 
-    if (vectors.length > 0) {
-      const storeResult = await vectorIndex.upsertVectors(vectors);
-      if (!storeResult.ok) {
-        errors += vectors.length;
-        continue;
-      }
-      embedded += vectors.length;
-    }
+  await drainRetryQueue();
+  if (retryQueue.size > 0) {
+    errors += retryQueue.size;
+    retryQueue.clear();
   }
 
   if (vectorIndex.vecDirty) {
@@ -217,24 +261,25 @@ export async function runEmbed(
   const db = runtime.store.getRawDb();
   const stats: VectorStatsPort = createVectorStatsPort(db);
 
-  const backlogResult = force
-    ? await getActiveChunkCount(db)
-    : await stats.countBacklog(modelUri, { collection: options.collection });
-  if (!backlogResult.ok) {
-    throw sdkError("STORE", backlogResult.error.message, {
-      cause: backlogResult.error.cause,
-    });
-  }
+  let totalToEmbed = 0;
+  if (force) {
+    const forceCount = await getActiveChunkCount(db);
+    if (!forceCount.ok) {
+      throw sdkError("STORE", forceCount.error.message, {
+        cause: forceCount.error.cause,
+      });
+    }
 
-  const totalToEmbed = backlogResult.value;
-  if (totalToEmbed === 0 || dryRun) {
-    return {
-      embedded: totalToEmbed,
-      errors: 0,
-      duration: 0,
-      model: modelUri,
-      searchAvailable: await checkVecAvailable(db),
-    };
+    totalToEmbed = forceCount.value;
+    if (totalToEmbed === 0 || dryRun) {
+      return {
+        embedded: totalToEmbed,
+        errors: 0,
+        duration: 0,
+        model: modelUri,
+        searchAvailable: await checkVecAvailable(db),
+      };
+    }
   }
 
   const embedResult = await runtime.llm.createEmbeddingPort(modelUri, {
@@ -266,6 +311,36 @@ export async function runEmbed(
     }
 
     const vectorIndex = vectorResult.value;
+    if (!force) {
+      const embedFingerprint = getEmbeddingFingerprint({
+        modelUri,
+        dimensions: vectorIndex.dimensions,
+      });
+      const backlogResult = await stats.countBacklog(
+        modelUri,
+        embedFingerprint,
+        {
+          collection: options.collection,
+        }
+      );
+      if (!backlogResult.ok) {
+        throw sdkError("STORE", backlogResult.error.message, {
+          cause: backlogResult.error.cause,
+        });
+      }
+
+      totalToEmbed = backlogResult.value;
+      if (totalToEmbed === 0 || dryRun) {
+        return {
+          embedded: totalToEmbed,
+          errors: 0,
+          duration: 0,
+          model: modelUri,
+          searchAvailable: vectorIndex.searchAvailable,
+        };
+      }
+    }
+
     const startedAt = Date.now();
     let result: { embedded: number; errors: number };
     if (force) {

package/src/serve/routes/api.ts

@@ -173,6 +173,7 @@ export interface QueryRequestBody {
   noExpand?: boolean;
   noRerank?: boolean;
   noGraph?: boolean;
+  graph?: boolean;
   /** Comma-separated tags - filter to docs having ALL (AND) */
   tagsAll?: string;
   /** Comma-separated tags - filter to docs having ANY (OR) */
@@ -3311,6 +3312,7 @@ export async function handleQuery(
       queryModes: normalizedQueryModes,
       noExpand: body.noExpand,
       noRerank: body.noRerank,
+      graph: body.graph === true,
       noGraph: body.noGraph,
       tagsAll,
       tagsAny,

package/src/store/migrations/008-vector-fingerprints.ts

@@ -0,0 +1,25 @@
+/**
+ * Migration: vector embedding freshness fingerprints.
+ *
+ * @module src/store/migrations/008-vector-fingerprints
+ */
+
+import type { Database } from "bun:sqlite";
+
+import type { Migration } from "./runner";
+
+export const migration: Migration = {
+  version: 8,
+  name: "vector_fingerprints",
+
+  up(db: Database): void {
+    db.exec(`
+      ALTER TABLE content_vectors ADD COLUMN embed_fingerprint TEXT NOT NULL DEFAULT ''
+    `);
+
+    db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_vectors_freshness
+      ON content_vectors(model, embed_fingerprint, mirror_hash, seq, embedded_at)
+    `);
+  },
+};

package/src/store/migrations/index.ts

@@ -21,6 +21,7 @@ import { migration as m004 } from "./004-doc-links";
 import { migration as m005 } from "./005-graph-indexes";
 import { migration as m006 } from "./006-document-metadata";
 import { migration as m007 } from "./007-document-date-fields";
+import { migration as m008 } from "./008-vector-fingerprints";
 
 /** All migrations in order */
-export const migrations = [m001, m002, m003, m004, m005, m006, m007];
+export const migrations = [m001, m002, m003, m004, m005, m006, m007, m008];