@gmickel/gno 1.46.0 → 2.0.0

package/src/sdk/client.ts

@@ -1,10 +1,9 @@
+import { mkdir } from "node:fs/promises";
 /**
  * GNO SDK client.
  *
  * @module src/sdk/client
  */
-
-import { mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
 
 import type { Config } from "../config/types";
@@ -160,6 +159,10 @@ import {
   withContentTypeRules,
 } from "../ingestion";
 import { updateFrontmatterTags } from "../ingestion/frontmatter";
+import {
+  withInferenceScope,
+  finishInferenceCleanup,
+} from "../llm/inference-scope";
 import { LlmAdapter } from "../llm/nodeLlamaCpp/adapter";
 import { resolveDownloadPolicy } from "../llm/policy";
 import { resolveModelUri } from "../llm/registry";
@@ -170,6 +173,7 @@ import {
 } from "../pipeline/answer";
 import { formatQueryForEmbedding } from "../pipeline/contextual";
 import { searchHybrid } from "../pipeline/hybrid";
+import { RequestHydration } from "../pipeline/hydration";
 import { searchBm25 } from "../pipeline/search";
 import { searchVectorWithEmbedding } from "../pipeline/vsearch";
 import { SqliteAdapter } from "../store/sqlite/adapter";
@@ -591,6 +595,10 @@ class GnoClientImpl implements GnoClient {
   }
 
   private async disposeRuntimePorts(ports: RuntimePorts): Promise<void> {
+    return finishInferenceCleanup(() => this.disposeRuntimePortsOwned(ports));
+  }
+
+  private async disposeRuntimePortsOwned(ports: RuntimePorts): Promise<void> {
     if (ports.embedPort) {
       await ports.embedPort.dispose();
     }
@@ -618,6 +626,15 @@ class GnoClientImpl implements GnoClient {
   async search(
     query: string,
     options: GnoSearchOptions = {}
+  ): Promise<SearchResults> {
+    return withInferenceScope(options, () =>
+      this.searchRequest(query, options)
+    );
+  }
+
+  private async searchRequest(
+    query: string,
+    options: GnoSearchOptions
   ): Promise<SearchResults> {
     this.assertOpen();
     let traceSession: RetrievalTraceSession | null = null;
@@ -661,6 +678,15 @@ class GnoClientImpl implements GnoClient {
   async vsearch(
     query: string,
     options: GnoVectorSearchOptions = {}
+  ): Promise<SearchResults> {
+    return withInferenceScope(options, () =>
+      this.vsearchRequest(query, options)
+    );
+  }
+
+  private async vsearchRequest(
+    query: string,
+    options: GnoVectorSearchOptions
   ): Promise<SearchResults> {
     this.assertOpen();
 
@@ -745,6 +771,13 @@ class GnoClientImpl implements GnoClient {
   async query(
     query: string,
     options: GnoQueryOptions = {}
+  ): Promise<SearchResults> {
+    return withInferenceScope(options, () => this.queryRequest(query, options));
+  }
+
+  private async queryRequest(
+    query: string,
+    options: GnoQueryOptions
   ): Promise<SearchResults> {
     this.assertOpen();
 
@@ -852,6 +885,13 @@ class GnoClientImpl implements GnoClient {
   }
 
   async ask(query: string, options: GnoAskOptions = {}): Promise<AskResult> {
+    return withInferenceScope(options, () => this.askRequest(query, options));
+  }
+
+  private async askRequest(
+    query: string,
+    options: GnoAskOptions
+  ): Promise<AskResult> {
     this.assertOpen();
 
     const normalizedInput = normalizeStructuredQueryInput(
@@ -911,6 +951,7 @@ class GnoClientImpl implements GnoClient {
     let ports: RuntimePorts | null = null;
     let traceSession: RetrievalTraceSession | null = null;
 
+    const hydration = new RequestHydration(this.store);
     try {
       const { projectHints, ...askOptions } = options;
       const projectAffinity = await resolveSdkProjectAffinity(
@@ -960,6 +1001,7 @@ class GnoClientImpl implements GnoClient {
           { ...askOptions, projectAffinity },
           {
             store: this.store,
+            hydration,
             config: this.config,
             indexName: this.indexName,
             vectorIndex: ports.vectorIndex,
@@ -987,6 +1029,7 @@ class GnoClientImpl implements GnoClient {
         await searchHybrid(
           {
             store: this.store,
+            hydration,
             config: this.config,
             vectorIndex: ports.vectorIndex,
             embedPort: ports.embedPort,
@@ -1033,7 +1076,7 @@ class GnoClientImpl implements GnoClient {
       ) {
         await traceSession?.recordCapability("answer_generation", "attempted");
         const rawAnswer = await generateGroundedAnswer(
-          { genPort: ports.answerPort, store: this.store },
+          { genPort: ports.answerPort, store: this.store, hydration },
           query,
           searchResult.results,
           options.maxAnswerTokens ?? 512
@@ -1100,6 +1143,7 @@ class GnoClientImpl implements GnoClient {
       await finishRetrievalTraceAfterError(traceSession, cause);
       throw cause;
     } finally {
+      hydration.release();
       if (ports) await this.disposeRuntimePorts(ports);
     }
   }

package/src/sdk/embed.ts

@@ -18,13 +18,14 @@ import type {
 } from "../store/vector";
 import type { GnoEmbedOptions, GnoEmbedResult } from "./types";
 
-import { embedBacklog } from "../embed";
+import { embedBacklog, prepareEmbeddingBacklog } from "../embed/backlog";
 import { getEmbeddingFingerprint } from "../embed/fingerprint";
 import {
   chunkRetryKey,
   embedAndStoreBatch,
   MAX_EMBED_CHUNK_ATTEMPTS,
 } from "../embed/retry";
+import { countVariantBacklog } from "../embed/variant-plan";
 import { resolveModelUri } from "../llm/registry";
 import { err, ok } from "../store/types";
 import { createVectorIndexPort, createVectorStatsPort } from "../store/vector";
@@ -71,7 +72,7 @@ function getActiveChunks(
     const sql = after
       ? `
         SELECT c.mirror_hash as mirrorHash, c.seq, c.text,
-          (SELECT d.title FROM documents d WHERE d.mirror_hash = c.mirror_hash AND d.active = 1 LIMIT 1) as title,
+          (SELECT d.title FROM documents d WHERE d.mirror_hash = c.mirror_hash AND d.active = 1 ORDER BY d.id LIMIT 1) as title,
           'force' as reason
         FROM content_chunks c
         WHERE EXISTS (
@@ -84,7 +85,7 @@ function getActiveChunks(
       `
       : `
         SELECT c.mirror_hash as mirrorHash, c.seq, c.text,
-          (SELECT d.title FROM documents d WHERE d.mirror_hash = c.mirror_hash AND d.active = 1 LIMIT 1) as title,
+          (SELECT d.title FROM documents d WHERE d.mirror_hash = c.mirror_hash AND d.active = 1 ORDER BY d.id LIMIT 1) as title,
           'force' as reason
         FROM content_chunks c
         WHERE EXISTS (
@@ -238,16 +239,6 @@ async function forceEmbedAll(
   return { embedded, errors, contentionErrors };
 }
 
-async function checkVecAvailable(db: Database): Promise<boolean> {
-  try {
-    const sqliteVec = await import("sqlite-vec");
-    sqliteVec.load(db);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 export async function runEmbed(
   runtime: EmbedRuntimeOptions,
   options: GnoEmbedOptions = {}
@@ -265,26 +256,6 @@ export async function runEmbed(
   const stats: VectorStatsPort = createVectorStatsPort(db);
 
   let totalToEmbed = 0;
-  if (force) {
-    const forceCount = await getActiveChunkCount(db);
-    if (!forceCount.ok) {
-      throw sdkError("STORE", forceCount.error.message, {
-        cause: forceCount.error.cause,
-      });
-    }
-
-    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, {
     egressCollections: options.collection ? [options.collection] : "all",
     policy: runtime.downloadPolicy,
@@ -297,16 +268,22 @@ export async function runEmbed(
 
   const embedPort = embedResult.value;
   try {
-    const probeResult = await embedPort.embed("dimension probe");
-    if (!probeResult.ok) {
-      throw sdkError("MODEL", probeResult.error.message, {
-        cause: probeResult.error.cause,
-      });
+    const initializedPort = await embedPort.init();
+    if (!initializedPort.ok)
+      throw sdkError("MODEL", initializedPort.error.message);
+    let dimensions = embedPort.dimensions();
+    if (!embedPort.getIdentity?.()) {
+      const probeResult = await embedPort.embed("dimension probe");
+      if (!probeResult.ok)
+        throw sdkError("MODEL", probeResult.error.message, {
+          cause: probeResult.error.cause,
+        });
+      dimensions = probeResult.value.length;
     }
 
     const vectorResult = await createVectorIndexPort(db, {
       model: modelUri,
-      dimensions: probeResult.value.length,
+      dimensions,
     });
     if (!vectorResult.ok) {
       throw sdkError("STORE", vectorResult.error.message, {
@@ -315,6 +292,53 @@ export async function runEmbed(
     }
 
     const vectorIndex = vectorResult.value;
+    const prepared = await prepareEmbeddingBacklog({
+      statsPort: stats,
+      embedPort,
+      vectorIndex,
+      modelUri,
+      collection: options.collection,
+      batchSize,
+      force,
+    });
+    if (!prepared.ok) throw sdkError("STORE", prepared.error.message);
+    if (prepared.value.variantStore) {
+      const count = countVariantBacklog(prepared.value);
+      const startedAt = Date.now();
+      if (dryRun)
+        return {
+          embedded: count,
+          errors: 0,
+          duration: 0,
+          model: modelUri,
+          searchAvailable: prepared.value.variantStore.searchAvailable,
+        };
+      const processed = await embedBacklog(prepared.value);
+      if (!processed.ok) throw sdkError("STORE", processed.error.message);
+      if (processed.value.syncError)
+        throw sdkError("STORE", processed.value.syncError);
+      return {
+        embedded: processed.value.embedded,
+        errors: processed.value.errors,
+        contentionErrors: processed.value.contentionErrors ?? 0,
+        duration: (Date.now() - startedAt) / 1000,
+        model: modelUri,
+        searchAvailable: prepared.value.variantStore.searchAvailable,
+      };
+    }
+    if (force) {
+      const count = await getActiveChunkCount(db);
+      if (!count.ok) throw sdkError("STORE", count.error.message);
+      totalToEmbed = count.value;
+      if (dryRun || !totalToEmbed)
+        return {
+          embedded: totalToEmbed,
+          errors: 0,
+          duration: 0,
+          model: modelUri,
+          searchAvailable: vectorIndex.searchAvailable,
+        };
+    }
     if (!force) {
       const embedFingerprint = getEmbeddingFingerprint({
         modelUri,

package/src/serve/background-runtime.ts

@@ -29,7 +29,7 @@ export interface BackgroundRuntime {
     runUpdateCmd?: boolean;
     triggerEmbed?: boolean;
   }): Promise<{ syncResult: SyncResult; embedResult: EmbedResult | null }>;
-  dispose(): Promise<void>;
+  dispose(closeSurface?: () => Promise<unknown>): Promise<void>;
 }
 
 export type BackgroundRuntimeResult =

package/src/serve/context.ts

@@ -15,16 +15,22 @@ import type {
   RerankPort,
 } from "../llm/types";
 import type { SqliteAdapter } from "../store/sqlite/adapter";
+import type { VectorIndexPort } from "../store/vector";
 import type { DocumentEventBus } from "./doc-events";
 import type { EmbedScheduler } from "./embed-scheduler";
 import type { CollectionWatchService } from "./watch-service";
 
 import { DEFAULT_INDEX_NAME } from "../app/constants";
 import { canonicalizeIndexName } from "../app/index-name";
+import {
+  lazyEmbeddingPort,
+  lazyGenerationPort,
+  lazyRerankPort,
+} from "../llm/lazy-ports";
 import { LlmAdapter } from "../llm/nodeLlamaCpp/adapter";
 import { resolveDownloadPolicy } from "../llm/policy";
 import { getActivePreset } from "../llm/registry";
-import { createVectorIndexPort, type VectorIndexPort } from "../store/vector";
+import { createLazyVectorIndex } from "../store/vector/lazy";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Download State (in-memory, single user)
@@ -64,6 +70,7 @@ export function resetDownloadState(): void {
 // ─────────────────────────────────────────────────────────────────────────────
 
 export interface ServerContext {
+  llm?: LlmAdapter;
   store: SqliteAdapter;
   config: Config;
   /** Canonical identity of the already-open resident store. */
@@ -91,7 +98,7 @@ export interface CreateServerContextOptions {
 
 /**
  * Initialize server context with LLM ports.
- * Attempts to load models; missing models are logged but don't fail.
+ * Model resolution, downloads and loading wait until actual inference.
  */
 export async function createServerContext(
   store: SqliteAdapter,
@@ -104,9 +111,9 @@ export async function createServerContext(
   let rerankPort: RerankPort | null = null;
   let vectorIndex: VectorIndexPort | null = null;
 
+  const llm = new LlmAdapter(config);
   try {
     const preset = getActivePreset(config);
-    const llm = new LlmAdapter(config);
 
     // Resolve download policy from env (serve has no CLI flags)
     const policy = resolveDownloadPolicy(process.env, {
@@ -127,64 +134,40 @@ export async function createServerContext(
       },
     });
 
-    // Try to create embedding port
-    const embedResult = await llm.createEmbeddingPort(
+    const resolvePort = async <T>(operation: () => Promise<T>): Promise<T> => {
+      try {
+        return await operation();
+      } finally {
+        downloadState.active = false;
+        downloadState.currentType = null;
+      }
+    };
+    embedPort = lazyEmbeddingPort(preset.embed, () =>
+      resolvePort(() =>
+        llm.createEmbeddingPort(preset.embed, createPortOptions("embed"))
+      )
+    );
+    vectorIndex = await createLazyVectorIndex(
+      store.getRawDb(),
       preset.embed,
-      createPortOptions("embed")
+      embedPort
     );
-    if (embedResult.ok) {
-      embedPort = embedResult.value;
-      const initResult = await embedPort.init();
-      if (initResult.ok) {
-        // Create vector index
-        const dimensions = embedPort.dimensions();
-        const db = store.getRawDb();
-        const vectorResult = await createVectorIndexPort(db, {
-          model: preset.embed,
-          dimensions,
-        });
-        if (vectorResult.ok) {
-          vectorIndex = vectorResult.value;
-          console.log("Vector search enabled");
-        }
-      }
-    }
-
-    // Try to create expansion port
-    const expandResult = await llm.createExpansionPort(
-      preset.expand ?? preset.gen,
-      createPortOptions("expand")
+    const expandUri = preset.expand ?? preset.gen;
+    expandPort = lazyGenerationPort(expandUri, () =>
+      resolvePort(() =>
+        llm.createExpansionPort(expandUri, createPortOptions("expand"))
+      )
     );
-    if (expandResult.ok) {
-      expandPort = expandResult.value;
-      console.log("Query expansion enabled");
-    }
-
-    // Try to create answer generation port
-    const answerResult = await llm.createGenerationPort(
-      preset.gen,
-      createPortOptions("gen")
+    answerPort = lazyGenerationPort(preset.gen, () =>
+      resolvePort(() =>
+        llm.createGenerationPort(preset.gen, createPortOptions("gen"))
+      )
     );
-    if (answerResult.ok) {
-      answerPort = answerResult.value;
-      console.log("AI answer generation enabled");
-    }
-
-    // Try to create rerank port
-    const rerankResult = await llm.createRerankPort(
-      preset.rerank,
-      createPortOptions("rerank")
+    rerankPort = lazyRerankPort(preset.rerank, () =>
+      resolvePort(() =>
+        llm.createRerankPort(preset.rerank, createPortOptions("rerank"))
+      )
     );
-    if (rerankResult.ok) {
-      rerankPort = rerankResult.value;
-      console.log("Reranking enabled");
-    }
-
-    // Reset download state after initialization
-    if (downloadState.active) {
-      downloadState.active = false;
-      downloadState.currentType = null;
-    }
   } catch (e) {
     // Log but don't fail - models are optional
     console.log(
@@ -201,6 +184,7 @@ export async function createServerContext(
   };
 
   return {
+    llm,
     store,
     config,
     indexName: canonicalizeIndexName(options.indexName ?? DEFAULT_INDEX_NAME),
@@ -237,6 +221,7 @@ export async function disposeServerContext(ctx: ServerContext): Promise<void> {
       }
     }
   }
+  await ctx.llm?.dispose();
 }
 
 /**

package/src/serve/embed-scheduler.ts

@@ -7,11 +7,14 @@
 
 import type { Database } from "bun:sqlite";
 
-import type { ModelLease } from "../llm/nodeLlamaCpp/lifecycle";
 import type { EmbeddingPort } from "../llm/types";
 import type { VectorIndexPort } from "../store/vector";
 
 import { embedBacklog } from "../embed";
+import {
+  withBackgroundInference,
+  withOwnedInferenceScope,
+} from "../llm/inference-scope";
 import { createVectorStatsPort } from "../store/vector";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -47,7 +50,6 @@ export interface EmbedSchedulerDeps {
   getVectorIndex: () => VectorIndexPort | null;
   /** Getter for current model URI (survives preset changes) */
   getModelUri: () => string;
-  acquireModelLease?: () => ModelLease;
   onEmbedded?: (result: EmbedResult) => void;
   embedBacklogFn?: typeof embedBacklog;
 }
@@ -68,6 +70,8 @@ export interface EmbedScheduler {
 
   /** Cleanup on server shutdown */
   dispose(): Promise<void>;
+  /** Stop new turns while allowing the current pass to settle before cancellation. */
+  stop?(): Promise<void>;
 }
 
 /**
@@ -80,7 +84,6 @@ export function createEmbedScheduler(deps: EmbedSchedulerDeps): EmbedScheduler {
     getEmbedPort,
     getVectorIndex,
     getModelUri,
-    acquireModelLease,
     onEmbedded,
     embedBacklogFn = embedBacklog,
   } = deps;
@@ -96,6 +99,7 @@ export function createEmbedScheduler(deps: EmbedSchedulerDeps): EmbedScheduler {
   let currentRun: Promise<EmbedResult | null> | null = null;
   let lastRunAt: number | null = null;
   let lastResult: EmbedResult | null = null;
+  const controller = new AbortController();
 
   const stats = createVectorStatsPort(db);
 
@@ -116,33 +120,48 @@ export function createEmbedScheduler(deps: EmbedSchedulerDeps): EmbedScheduler {
       return { embedded: 0, errors: 0 };
     }
 
-    const lease = acquireModelLease?.();
+    let result: Awaited<ReturnType<typeof embedBacklogFn>>;
     try {
-      const result = await embedBacklogFn({
-        statsPort: stats,
-        embedPort,
-        vectorIndex,
-        modelUri,
-        batchSize: BATCH_SIZE,
-      });
-
-      if (!result.ok) {
-        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 {
-      lease?.release();
+      result = await withBackgroundInference(() =>
+        withOwnedInferenceScope({ signal: controller.signal }, () =>
+          embedBacklogFn({
+            statsPort: stats,
+            embedPort,
+            vectorIndex,
+            modelUri,
+            batchSize: BATCH_SIZE,
+            identityStillCurrent: () =>
+              getEmbedPort() === embedPort &&
+              getVectorIndex() === vectorIndex &&
+              getModelUri() === modelUri,
+          })
+        )
+      );
+    } catch (cause) {
+      if (controller.signal.aborted) return { embedded: 0, errors: 0 };
+      throw cause;
+    }
+
+    if (!result.ok) {
+      needsRerun = true;
+      console.error("[embed-scheduler] Embed failed:", result.error.message);
+      return { embedded: 0, errors: 0 };
+    }
+    if (
+      getEmbedPort() !== embedPort ||
+      getVectorIndex() !== vectorIndex ||
+      getModelUri() !== modelUri
+    )
+      needsRerun = true;
+    if ((result.value.contentionErrors ?? 0) > 0 || result.value.errors > 0) {
+      // Provider failures and contended checkpoints remain durably pending.
+      console.error(
+        `[embed-scheduler] ${result.value.errors} embedding errors, ${result.value.contentionErrors ?? 0} contended writes; rescheduling`
+      );
+      needsRerun = true;
     }
+    if (result.value.embedded > 0) onEmbedded?.(result.value);
+    return result.value;
   }
 
   /**
@@ -241,7 +260,16 @@ export function createEmbedScheduler(deps: EmbedSchedulerDeps): EmbedScheduler {
     return operation;
   }
 
+  const stop = async (): Promise<void> => {
+    disposed = true;
+    if (timer) clearTimeout(timer);
+    timer = null;
+    nextRunAt = null;
+    await currentRun;
+  };
+
   return {
+    stop,
     notifySyncComplete(docIds: string[]): void {
       // Resolve embedPort at call time to check availability
       if (disposed || !getEmbedPort()) {
@@ -302,13 +330,8 @@ export function createEmbedScheduler(deps: EmbedSchedulerDeps): EmbedScheduler {
     },
 
     async dispose(): Promise<void> {
-      disposed = true;
-      if (timer) {
-        clearTimeout(timer);
-        timer = null;
-        nextRunAt = null;
-      }
-      await currentRun;
+      controller.abort();
+      await stop();
     },
   };
 }