@gmickel/gno 1.17.0 → 1.19.0

package/src/sdk/types.ts

@@ -19,6 +19,17 @@ import type { ContextEvidenceErrorCode } from "../core/context-evidence";
 import type { ContextVerifierErrorCode } from "../core/context-verifier";
 import type { NoteCollisionPolicy } from "../core/note-creation";
 import type { NotePresetId } from "../core/note-presets";
+import type {
+  RetrievalTraceDeleteResult,
+  RetrievalTraceDetail,
+  RetrievalTraceExportRequest,
+  RetrievalTraceExportResult,
+  RetrievalTraceLabelRequest,
+  RetrievalTraceLabelResult,
+  RetrievalTraceListRequest,
+  RetrievalTraceListResult,
+  RetrievalTracePurgeResult as RetrievalTraceManagementPurgeResult,
+} from "../core/retrieval-trace-management";
 import type { DocumentSection } from "../core/sections";
 import type { SyncResult } from "../ingestion";
 import type { DownloadPolicy } from "../llm/policy";
@@ -88,6 +99,8 @@ export type GnoContextErrorCode =
 export interface GnoGetOptions {
   from?: number;
   limit?: number;
+  /** Continue an open retrieval trace returned by search/query. */
+  traceId?: string;
 }
 
 export interface GnoMultiGetOptions {
@@ -221,6 +234,21 @@ export interface GnoClient {
     options?: GnoListOptions
   ): Promise<import("../cli/commands/ls").LsResponse>;
   status(): Promise<IndexStatus>;
+  listRetrievalTraces(
+    options?: RetrievalTraceListRequest
+  ): Promise<RetrievalTraceListResult>;
+  getRetrievalTrace(
+    traceId: string,
+    options?: { detailLimit?: number }
+  ): Promise<RetrievalTraceDetail>;
+  labelRetrievalTrace(
+    input: RetrievalTraceLabelRequest
+  ): Promise<RetrievalTraceLabelResult>;
+  exportRetrievalTraces(
+    input: RetrievalTraceExportRequest
+  ): Promise<RetrievalTraceExportResult>;
+  deleteRetrievalTrace(traceId: string): Promise<RetrievalTraceDeleteResult>;
+  purgeRetrievalTraces(): Promise<RetrievalTraceManagementPurgeResult>;
   update(options?: GnoUpdateOptions): Promise<SyncResult>;
   embed(options?: GnoEmbedOptions): Promise<GnoEmbedResult>;
   index(options?: GnoIndexOptions): Promise<GnoIndexResult>;

package/src/serve/background-runtime.ts

@@ -1,46 +1,20 @@
-// node:path resolve has no Bun equivalent for canonical process-relative paths.
-import { resolve } from "node:path";
+/** Backwards-compatible entrypoint for the shared resident runtime. */
 
 import type { Config } from "../config/types";
 import type { SyncResult } from "../ingestion";
-import type { DocumentEventBus } from "./doc-events";
+import type { SqliteAdapter } from "../store/sqlite/adapter";
 import type { EmbedResult, EmbedScheduler } from "./embed-scheduler";
 import type { ContextHolder } from "./routes/api";
-import type {
-  CollectionWatchCallbacks,
-  CollectionWatchService,
-} from "./watch-service";
+import type { CollectionWatchService } from "./watch-service";
 
-import { getIndexDbPath } from "../app/constants";
-import { INDEX_NAME_REQUIREMENTS, isValidIndexName } from "../app/index-name";
 import {
-  ensureDirectories,
-  formatConfigWarnings,
-  getConfigPaths,
-  isInitialized,
-  loadConfig,
-} from "../config";
-import { defaultSyncService } from "../ingestion";
-import { withContentTypeRules } from "../ingestion";
-import { getActivePreset } from "../llm/registry";
-import { SqliteAdapter } from "../store/sqlite/adapter";
-import {
-  createServerContext,
-  type CreateServerContextOptions,
-  disposeServerContext,
-  type ServerContext,
-} from "./context";
-import { createEmbedScheduler } from "./embed-scheduler";
-import { CollectionWatchService as DefaultCollectionWatchService } from "./watch-service";
+  startResidentRuntime,
+  type ResidentRuntimeDeps,
+  type ResidentRuntimeOptions,
+} from "./resident-runtime";
 
-export interface BackgroundRuntimeOptions {
-  configPath?: string;
-  index?: string;
-  requireCollections?: boolean;
-  offline?: boolean;
-  eventBus?: DocumentEventBus | null;
-  watchCallbacks?: CollectionWatchCallbacks;
-}
+export type BackgroundRuntimeOptions = ResidentRuntimeOptions;
+export type BackgroundRuntimeDeps = ResidentRuntimeDeps;
 
 export interface BackgroundRuntime {
   store: SqliteAdapter;
@@ -48,16 +22,13 @@ export interface BackgroundRuntime {
   actualConfigPath: string;
   ctxHolder: ContextHolder;
   scheduler: EmbedScheduler;
-  eventBus: DocumentEventBus | null;
+  eventBus: import("./doc-events").DocumentEventBus | null;
   watchService: CollectionWatchService;
   syncAll(options?: {
     gitPull?: boolean;
     runUpdateCmd?: boolean;
     triggerEmbed?: boolean;
-  }): Promise<{
-    syncResult: SyncResult;
-    embedResult: EmbedResult | null;
-  }>;
+  }): Promise<{ syncResult: SyncResult; embedResult: EmbedResult | null }>;
   dispose(): Promise<void>;
 }
 
@@ -65,180 +36,9 @@ export type BackgroundRuntimeResult =
   | { success: true; runtime: BackgroundRuntime }
   | { success: false; error: string };
 
-type BackgroundRuntimeDeps = {
-  isInitialized?: typeof isInitialized;
-  loadConfig?: typeof loadConfig;
-  getConfigPaths?: typeof getConfigPaths;
-  ensureDirectories?: typeof ensureDirectories;
-  storeFactory?: () => SqliteAdapter;
-  createServerContext?: (
-    store: SqliteAdapter,
-    config: Config,
-    options?: CreateServerContextOptions
-  ) => Promise<ServerContext>;
-  disposeServerContext?: (ctx: ServerContext) => Promise<void>;
-  createEmbedScheduler?: typeof createEmbedScheduler;
-  syncAllService?: typeof defaultSyncService.syncAll;
-  watchServiceFactory?: (options: {
-    collections: Config["collections"];
-    store: SqliteAdapter;
-    scheduler: EmbedScheduler | null;
-    eventBus?: DocumentEventBus | null;
-    callbacks?: CollectionWatchCallbacks;
-    syncOptions?: Parameters<typeof withContentTypeRules>[0];
-  }) => CollectionWatchService;
-};
-
 export async function startBackgroundRuntime(
   options: BackgroundRuntimeOptions = {},
   deps: BackgroundRuntimeDeps = {}
 ): Promise<BackgroundRuntimeResult> {
-  if (options.index !== undefined && !isValidIndexName(options.index)) {
-    return {
-      success: false,
-      error: `Invalid index name: ${INDEX_NAME_REQUIREMENTS}.`,
-    };
-  }
-  const syncAllService = deps.syncAllService
-    ? (...args: Parameters<typeof defaultSyncService.syncAll>) =>
-        deps.syncAllService!(...args)
-    : defaultSyncService.syncAll.bind(defaultSyncService);
-  const initialized = await (deps.isInitialized ?? isInitialized)(
-    options.configPath
-  );
-  if (!initialized) {
-    return { success: false, error: "GNO not initialized. Run: gno init" };
-  }
-
-  const configResult = await (deps.loadConfig ?? loadConfig)(
-    options.configPath
-  );
-  if (!configResult.ok) {
-    return { success: false, error: configResult.error.message };
-  }
-  for (const warning of formatConfigWarnings(configResult.warnings)) {
-    console.warn(warning);
-  }
-  const config = configResult.value;
-
-  if (options.requireCollections && config.collections.length === 0) {
-    return {
-      success: false,
-      error: "No collections configured. Run: gno collection add <path>",
-    };
-  }
-
-  await (deps.ensureDirectories ?? ensureDirectories)();
-
-  const store = deps.storeFactory ? deps.storeFactory() : new SqliteAdapter();
-  const dbPath = getIndexDbPath(options.index);
-  const paths = (deps.getConfigPaths ?? getConfigPaths)();
-  const actualConfigPath = resolve(options.configPath ?? paths.configFile);
-  store.setConfigPath(actualConfigPath);
-
-  const openResult = await store.open(dbPath, config.ftsTokenizer);
-  if (!openResult.ok) {
-    return { success: false, error: openResult.error.message };
-  }
-
-  const syncCollResult = await store.syncCollections(config.collections);
-  if (!syncCollResult.ok) {
-    await store.close();
-    return { success: false, error: syncCollResult.error.message };
-  }
-  const syncCtxResult = await store.syncContexts(config.contexts ?? []);
-  if (!syncCtxResult.ok) {
-    await store.close();
-    return { success: false, error: syncCtxResult.error.message };
-  }
-
-  const ctx = await (deps.createServerContext ?? createServerContext)(
-    store,
-    config,
-    {
-      offline: options.offline ?? false,
-      indexName: options.index,
-    }
-  );
-
-  const ctxHolder: ContextHolder = {
-    current: ctx,
-    config,
-    scheduler: null,
-    eventBus: options.eventBus ?? null,
-    watchService: null,
-  };
-
-  const scheduler = (deps.createEmbedScheduler ?? createEmbedScheduler)({
-    db: store.getRawDb(),
-    getEmbedPort: () => ctxHolder.current.embedPort,
-    getVectorIndex: () => ctxHolder.current.vectorIndex,
-    getModelUri: () => getActivePreset(ctxHolder.config).embed,
-  });
-  ctxHolder.scheduler = scheduler;
-  ctxHolder.current.scheduler = scheduler;
-  ctxHolder.current.eventBus = options.eventBus ?? null;
-
-  const watchService = (
-    deps.watchServiceFactory ??
-    ((watchOptions) => new DefaultCollectionWatchService(watchOptions))
-  )({
-    collections: config.collections,
-    store,
-    scheduler,
-    eventBus: options.eventBus ?? null,
-    callbacks: options.watchCallbacks,
-    syncOptions: withContentTypeRules({}, config),
-  });
-  watchService.start();
-  ctxHolder.watchService = watchService;
-  ctxHolder.current.watchService = watchService;
-
-  let disposed = false;
-
-  return {
-    success: true,
-    runtime: {
-      store,
-      config,
-      actualConfigPath,
-      ctxHolder,
-      scheduler,
-      eventBus: options.eventBus ?? null,
-      watchService,
-      async syncAll(syncOptions = {}) {
-        const syncResult = await syncAllService(
-          config.collections,
-          store,
-          withContentTypeRules(
-            {
-              gitPull: syncOptions.gitPull,
-              runUpdateCmd: syncOptions.runUpdateCmd,
-            },
-            config
-          )
-        );
-
-        let embedResult: EmbedResult | null = null;
-        if (syncOptions.triggerEmbed !== false) {
-          embedResult = await scheduler.triggerNow();
-        }
-
-        return { syncResult, embedResult };
-      },
-      async dispose() {
-        if (disposed) {
-          return;
-        }
-        disposed = true;
-        await Promise.resolve(watchService.dispose());
-        options.eventBus?.close();
-        scheduler.dispose();
-        await (deps.disposeServerContext ?? disposeServerContext)(
-          ctxHolder.current
-        );
-        await store.close();
-      },
-    },
-  };
+  return startResidentRuntime(options, deps);
 }

package/src/serve/context-capsule.ts

@@ -1,5 +1,6 @@
 /** REST adapters for the shared Context Capsule application boundary. */
 
+import type { RetrievalTraceSession } from "../core/retrieval-trace-session";
 import type { GnoContextErrorCode } from "../sdk/types";
 import type { ServerContext } from "./context";
 
@@ -20,6 +21,8 @@ import {
   parseContextVerifySurfaceInput,
 } from "../app/context-surface";
 import { ContextCapsuleContractError } from "../core/context-capsule";
+import { startRetrievalTraceRequest } from "../core/retrieval-trace-request";
+import { withRetrievalTraceHeader } from "./retrieval-trace";
 
 const JSON_HEADERS = { "content-type": "application/json; charset=utf-8" };
 const MARKDOWN_HEADERS = {
@@ -80,6 +83,7 @@ export const handleContextBuild = async (
   context: ServerContext,
   request: Request
 ): Promise<Response> => {
+  let traceSession: RetrievalTraceSession | null = null;
   try {
     const { input, format } = parseContextBuildSurfaceInput(
       await parseJsonBody(request),
@@ -90,6 +94,42 @@ export const handleContextBuild = async (
       context.indexName,
       context.config.collections.map((collection) => collection.name)
     );
+    const started = await startRetrievalTraceRequest({
+      store: context.store,
+      config: context.config,
+      query: input.query ?? input.goal,
+      goal: input.goal,
+      filters: {
+        limit: input.limit,
+        collection:
+          input.collections?.length === 1 ? input.collections[0] : undefined,
+        collections: [...(input.collections ?? [])].sort(),
+        lang: input.lang,
+        tagsAll: input.tagsAll,
+        tagsAny: input.tagsAny,
+        since: input.since,
+        until: input.until,
+        categories: input.categories,
+        author: input.author,
+        graph: input.graph,
+        candidateLimit: input.candidateLimit,
+        queryModes: input.queryModes,
+        uriPrefix: input.uriPrefix ?? undefined,
+      },
+      pipeline: "context",
+      indexName: context.indexName,
+      modelUris: [
+        context.embedPort?.modelUri,
+        context.rerankPort?.modelUri,
+      ].filter((value): value is string => Boolean(value)),
+    });
+    if (!started.ok) {
+      throw Object.assign(
+        new Error(`Retrieval trace start failed: ${started.error.message}`),
+        { code: "retrieval_failed" }
+      );
+    }
+    traceSession = started.value;
     const capsule = await buildContextCapsule(input, {
       store: context.store,
       config: context.config,
@@ -97,16 +137,35 @@ export const handleContextBuild = async (
       vectorIndex: context.vectorIndex,
       embedPort: context.embedPort,
       rerankPort: context.rerankPort,
+      traceSession: traceSession ?? undefined,
     });
-    return format === "md"
-      ? new Response(formatContextCapsuleMarkdown(capsule), {
-          headers: MARKDOWN_HEADERS,
-        })
-      : new Response(canonicalBuiltContextCapsuleJson(capsule), {
-          headers: JSON_HEADERS,
-        });
+    const finished = await traceSession?.finish(
+      request.signal.aborted ? "cancelled" : "completed"
+    );
+    if (finished && !finished.ok) {
+      throw Object.assign(
+        new Error(
+          `Retrieval trace finalization failed: ${finished.error.message}`
+        ),
+        { code: "retrieval_failed" }
+      );
+    }
+    const response =
+      format === "md"
+        ? new Response(formatContextCapsuleMarkdown(capsule), {
+            headers: MARKDOWN_HEADERS,
+          })
+        : new Response(canonicalBuiltContextCapsuleJson(capsule), {
+            headers: JSON_HEADERS,
+          });
+    return withRetrievalTraceHeader(response, traceSession);
   } catch (error) {
-    return errorResponse(error);
+    if (traceSession) {
+      await traceSession.finish(
+        request.signal.aborted ? "cancelled" : "failed"
+      );
+    }
+    return withRetrievalTraceHeader(errorResponse(error), traceSession);
   }
 };
 

package/src/serve/embed-scheduler.ts

@@ -7,6 +7,7 @@
 
 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";
 
@@ -46,6 +47,9 @@ 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;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -63,7 +67,7 @@ export interface EmbedScheduler {
   getState(): EmbedSchedulerState;
 
   /** Cleanup on server shutdown */
-  dispose(): void;
+  dispose(): Promise<void>;
 }
 
 /**
@@ -71,7 +75,15 @@ export interface EmbedScheduler {
  * Uses getters to resolve dependencies at execution time (survives context reloads).
  */
 export function createEmbedScheduler(deps: EmbedSchedulerDeps): EmbedScheduler {
-  const { db, getEmbedPort, getVectorIndex, getModelUri } = deps;
+  const {
+    db,
+    getEmbedPort,
+    getVectorIndex,
+    getModelUri,
+    acquireModelLease,
+    onEmbedded,
+    embedBacklogFn = embedBacklog,
+  } = deps;
 
   // State
   let pendingCount = 0; // Track pending triggers (not actual docIds - we embed full backlog)
@@ -81,6 +93,7 @@ export function createEmbedScheduler(deps: EmbedSchedulerDeps): EmbedScheduler {
   let firstPendingAt: number | null = null;
   let nextRunAt: number | null = null; // Accurate timer due time
   let disposed = false;
+  let currentRun: Promise<EmbedResult | null> | null = null;
   let lastRunAt: number | null = null;
   let lastResult: EmbedResult | null = null;
 
@@ -103,20 +116,25 @@ export function createEmbedScheduler(deps: EmbedSchedulerDeps): EmbedScheduler {
       return { embedded: 0, errors: 0 };
     }
 
-    const result = await embedBacklog({
-      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 };
+    const lease = acquireModelLease?.();
+    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.embedded > 0) onEmbedded?.(result.value);
+      return result.value;
+    } finally {
+      lease?.release();
     }
-
-    return result.value;
   }
 
   /**
@@ -166,41 +184,53 @@ export function createEmbedScheduler(deps: EmbedSchedulerDeps): EmbedScheduler {
   /**
    * Execute the embed run with concurrency guard.
    */
-  async function executeRun(): Promise<EmbedResult | null> {
+  function executeRun(): Promise<EmbedResult | null> {
     if (disposed || running) {
       needsRerun = true;
-      return null;
+      return Promise.resolve(null);
     }
 
-    running = true;
-    timer = null;
-    nextRunAt = null;
-
-    // Clear pending state at START so new notifications accumulate
-    pendingCount = 0;
-    firstPendingAt = null;
+    const operation = (async (): Promise<EmbedResult | null> => {
+      running = true;
+      timer = null;
+      nextRunAt = null;
 
-    let result: EmbedResult;
-    try {
-      result = await runEmbed();
-      lastRunAt = Date.now();
-      lastResult = result;
-    } finally {
-      running = false;
-    }
+      // Clear pending state at START so new notifications accumulate
+      pendingCount = 0;
+      firstPendingAt = null;
+
+      let result: EmbedResult;
+      try {
+        result = await runEmbed();
+        lastRunAt = Date.now();
+        lastResult = result;
+      } finally {
+        running = false;
+      }
 
-    // Check if we need to rerun (notifications arrived while running)
-    // Must be AFTER running=false so scheduleRun() actually schedules
-    if ((needsRerun || pendingCount > 0) && !disposed) {
-      needsRerun = false;
-      // Set firstPendingAt if we have pending work
-      if (pendingCount > 0 && firstPendingAt === null) {
-        firstPendingAt = Date.now();
+      // Check if we need to rerun (notifications arrived while running)
+      // Must be AFTER running=false so scheduleRun() actually schedules
+      if ((needsRerun || pendingCount > 0) && !disposed) {
+        needsRerun = false;
+        // Set firstPendingAt if we have pending work
+        if (pendingCount > 0 && firstPendingAt === null) {
+          firstPendingAt = Date.now();
+        }
+        scheduleRun();
       }
-      scheduleRun();
-    }
 
-    return result;
+      return result;
+    })();
+    currentRun = operation;
+    void operation.then(
+      () => {
+        if (currentRun === operation) currentRun = null;
+      },
+      () => {
+        if (currentRun === operation) currentRun = null;
+      }
+    );
+    return operation;
   }
 
   return {
@@ -263,13 +293,14 @@ export function createEmbedScheduler(deps: EmbedSchedulerDeps): EmbedScheduler {
       return state;
     },
 
-    dispose(): void {
+    async dispose(): Promise<void> {
       disposed = true;
       if (timer) {
         clearTimeout(timer);
         timer = null;
         nextRunAt = null;
       }
+      await currentRun;
     },
   };
 }

package/src/serve/index.ts

@@ -11,3 +11,12 @@ export {
   type BackgroundRuntimeResult,
   startBackgroundRuntime,
 } from "./background-runtime";
+export {
+  type ResidentGeneration,
+  type ResidentMode,
+  type ResidentRequestHandle,
+  type ResidentRuntime,
+  type ResidentRuntimeOptions,
+  type ResidentRuntimeResult,
+  startResidentRuntime,
+} from "./resident-runtime";