@gmickel/gno 1.16.0 → 1.18.0

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,179 +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,
-    }
-  );
-
-  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

@@ -0,0 +1,136 @@
+/** REST adapters for the shared Context Capsule application boundary. */
+
+import type { GnoContextErrorCode } from "../sdk/types";
+import type { ServerContext } from "./context";
+
+import {
+  formatContextCapsuleMarkdown,
+  formatContextCapsuleVerificationMarkdown,
+} from "../app/context-format";
+import {
+  buildContextCapsule,
+  canonicalBuiltContextCapsuleJson,
+  canonicalVerifiedContextCapsuleJson,
+  validateContextCapsuleBuildInput,
+  verifyContextCapsuleRuntime,
+} from "../app/context-runtime";
+import {
+  contextSurfaceError,
+  parseContextBuildSurfaceInput,
+  parseContextVerifySurfaceInput,
+} from "../app/context-surface";
+import { ContextCapsuleContractError } from "../core/context-capsule";
+
+const JSON_HEADERS = { "content-type": "application/json; charset=utf-8" };
+const MARKDOWN_HEADERS = {
+  "content-type": "text/markdown; charset=utf-8",
+};
+
+const parseJsonBody = async (request: Request): Promise<unknown> => {
+  try {
+    return await request.json();
+  } catch {
+    throw new ContextCapsuleContractError("invalid_input", "Invalid JSON body");
+  }
+};
+
+export type ContextRestErrorCode = GnoContextErrorCode | "runtime_error";
+
+export const CONTEXT_REST_ERROR_STATUS = {
+  invalid_goal: 400,
+  invalid_budget: 400,
+  invalid_filter: 400,
+  invalid_uri: 400,
+  invalid_input: 400,
+  identity_mismatch: 400,
+  no_evidence: 404,
+  tokenizer_unavailable: 503,
+  chunk_coordinate_mismatch: 409,
+  stored_provenance_mismatch: 409,
+  index_snapshot_mismatch: 409,
+  index_changed_during_compile: 409,
+  context_changed_during_compile: 409,
+  capsule_mutated_during_verify: 409,
+  context_changed_during_verify: 409,
+  index_changed_during_verify: 409,
+  retrieval_failed: 500,
+  chunk_load_failed: 500,
+  collection_load_failed: 500,
+  content_load_failed: 500,
+  context_load_failed: 500,
+  document_load_failed: 500,
+  index_snapshot_failed: 500,
+  runtime_error: 500,
+} as const satisfies Record<ContextRestErrorCode, number>;
+
+export const contextRestStatusForCode = (code: string): number =>
+  code in CONTEXT_REST_ERROR_STATUS
+    ? CONTEXT_REST_ERROR_STATUS[code as ContextRestErrorCode]
+    : 500;
+
+const errorResponse = (error: unknown): Response => {
+  const publicError = contextSurfaceError(error);
+  return new Response(JSON.stringify({ error: publicError }), {
+    status: contextRestStatusForCode(publicError.code),
+    headers: JSON_HEADERS,
+  });
+};
+
+export const handleContextBuild = async (
+  context: ServerContext,
+  request: Request
+): Promise<Response> => {
+  try {
+    const { input, format } = parseContextBuildSurfaceInput(
+      await parseJsonBody(request),
+      context.indexName
+    );
+    validateContextCapsuleBuildInput(
+      input,
+      context.indexName,
+      context.config.collections.map((collection) => collection.name)
+    );
+    const capsule = await buildContextCapsule(input, {
+      store: context.store,
+      config: context.config,
+      indexName: context.indexName,
+      vectorIndex: context.vectorIndex,
+      embedPort: context.embedPort,
+      rerankPort: context.rerankPort,
+    });
+    return format === "md"
+      ? new Response(formatContextCapsuleMarkdown(capsule), {
+          headers: MARKDOWN_HEADERS,
+        })
+      : new Response(canonicalBuiltContextCapsuleJson(capsule), {
+          headers: JSON_HEADERS,
+        });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};
+
+export const handleContextVerify = async (
+  context: ServerContext,
+  request: Request
+): Promise<Response> => {
+  try {
+    const { capsule, format } = parseContextVerifySurfaceInput(
+      await parseJsonBody(request)
+    );
+    const receipt = await verifyContextCapsuleRuntime(capsule, {
+      store: context.store,
+      config: context.config,
+      indexName: context.indexName,
+    });
+    return format === "md"
+      ? new Response(formatContextCapsuleVerificationMarkdown(receipt), {
+          headers: MARKDOWN_HEADERS,
+        })
+      : new Response(canonicalVerifiedContextCapsuleJson(receipt), {
+          headers: JSON_HEADERS,
+        });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};

package/src/serve/context.ts

@@ -19,6 +19,8 @@ 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 { LlmAdapter } from "../llm/nodeLlamaCpp/adapter";
 import { resolveDownloadPolicy } from "../llm/policy";
 import { getActivePreset } from "../llm/registry";
@@ -64,6 +66,8 @@ export function resetDownloadState(): void {
 export interface ServerContext {
   store: SqliteAdapter;
   config: Config;
+  /** Canonical identity of the already-open resident store. */
+  indexName: string;
   vectorIndex: VectorIndexPort | null;
   embedPort: EmbeddingPort | null;
   expandPort: GenerationPort | null;
@@ -82,6 +86,7 @@ export interface ServerContext {
 
 export interface CreateServerContextOptions {
   offline?: boolean;
+  indexName?: string;
 }
 
 /**
@@ -197,6 +202,7 @@ export async function createServerContext(
   return {
     store,
     config,
+    indexName: canonicalizeIndexName(options.indexName ?? DEFAULT_INDEX_NAME),
     vectorIndex,
     embedPort,
     expandPort,
@@ -242,5 +248,8 @@ export async function reloadServerContext(
   options: CreateServerContextOptions = {}
 ): Promise<ServerContext> {
   await disposeServerContext(ctx);
-  return createServerContext(ctx.store, newConfig ?? ctx.config, options);
+  return createServerContext(ctx.store, newConfig ?? ctx.config, {
+    ...options,
+    indexName: options.indexName ?? ctx.indexName,
+  });
 }

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";