@gmickel/gno 1.16.0 → 1.17.0

package/src/sdk/client.ts

@@ -22,6 +22,9 @@ import type {
   GnoCreateFolderResult,
   GnoCreateNoteOptions,
   GnoCreateNoteResult,
+  GnoContextInput,
+  GnoContextResult,
+  GnoContextVerificationResult,
   GnoClientInitOptions,
   GnoDuplicateNoteOptions,
   GnoEmbedOptions,
@@ -39,8 +42,21 @@ import type {
   GnoVectorSearchOptions,
 } from "./types";
 
-import { decorateUriForIndex, getIndexDbPath } from "../app/constants";
-import { INDEX_NAME_REQUIREMENTS, isValidIndexName } from "../app/index-name";
+import {
+  decorateUriForIndex,
+  DEFAULT_INDEX_NAME,
+  getIndexDbPath,
+} from "../app/constants";
+import {
+  buildContextCapsule,
+  validateContextCapsuleBuildInput,
+  verifyContextCapsuleRuntime,
+} from "../app/context-runtime";
+import {
+  canonicalizeIndexName,
+  INDEX_NAME_REQUIREMENTS,
+  isValidIndexName,
+} from "../app/index-name";
 import {
   ConfigSchema,
   loadConfig,
@@ -108,7 +124,7 @@ interface OpenedClientState {
   store: SqliteAdapter;
   llm: LlmAdapter;
   downloadPolicy: DownloadPolicy;
-  indexName?: string;
+  indexName: string;
 }
 
 interface RuntimePorts {
@@ -161,7 +177,10 @@ async function resolveClientState(
     configSource = "file";
   }
 
-  const dbPath = options.dbPath ?? getIndexDbPath(options.indexName);
+  const indexName = canonicalizeIndexName(
+    options.indexName ?? DEFAULT_INDEX_NAME
+  );
+  const dbPath = options.dbPath ?? getIndexDbPath(indexName);
   await mkdir(dirname(dbPath), { recursive: true });
 
   const store = new SqliteAdapter();
@@ -179,7 +198,7 @@ async function resolveClientState(
     llm: new LlmAdapter(config, options.cacheDir),
     downloadPolicy:
       options.downloadPolicy ?? resolveDownloadPolicy(process.env, {}),
-    indexName: options.indexName,
+    indexName,
   };
 }
 
@@ -192,7 +211,7 @@ class GnoClientImpl implements GnoClient {
   private readonly store: SqliteAdapter;
   private readonly llm: LlmAdapter;
   private readonly downloadPolicy: DownloadPolicy;
-  private readonly indexName?: string;
+  private readonly indexName: string;
   private closed = false;
 
   constructor(state: OpenedClientState) {
@@ -644,6 +663,49 @@ class GnoClientImpl implements GnoClient {
     }
   }
 
+  async context(input: GnoContextInput): Promise<GnoContextResult> {
+    this.assertOpen();
+    validateContextCapsuleBuildInput(
+      { ...input, indexName: this.indexName },
+      this.indexName,
+      this.config.collections.map((collection) => collection.name)
+    );
+    const collection =
+      input.collections?.length === 1 ? input.collections[0] : undefined;
+    const useModels = input.depthPolicy !== "fast";
+    const ports = await this.createRuntimePorts({
+      embed: useModels,
+      rerank: useModels,
+      collection,
+    });
+    try {
+      return await buildContextCapsule(
+        { ...input, indexName: this.indexName },
+        {
+          store: this.store,
+          config: this.config,
+          indexName: this.indexName,
+          vectorIndex: ports.vectorIndex,
+          embedPort: ports.embedPort,
+          rerankPort: ports.rerankPort,
+        }
+      );
+    } finally {
+      await this.disposeRuntimePorts(ports);
+    }
+  }
+
+  async verifyContext(
+    capsule: GnoContextResult
+  ): Promise<GnoContextVerificationResult> {
+    this.assertOpen();
+    return verifyContextCapsuleRuntime(capsule, {
+      store: this.store,
+      config: this.config,
+      indexName: this.indexName,
+    });
+  }
+
   async get(ref: string, options: GnoGetOptions = {}) {
     this.assertOpen();
     const resolution = resolveEffectiveIndex([ref], this.indexName);

package/src/sdk/index.ts

@@ -31,6 +31,10 @@ export type {
   GnoAskOptions,
   GnoCaptureOptions,
   GnoCaptureResult,
+  GnoContextErrorCode,
+  GnoContextInput,
+  GnoContextResult,
+  GnoContextVerificationResult,
   GnoClient,
   GnoClientInitOptions,
   GnoEmbedOptions,
@@ -51,3 +55,20 @@ export type {
   GnoUpdateOptions,
   GnoVectorSearchOptions,
 } from "./types";
+export {
+  ContextCapsuleContractError,
+  type ContextCapsuleErrorCode,
+  type ContextCapsuleV1,
+} from "../core/context-capsule";
+export {
+  ContextEvidenceError,
+  type ContextEvidenceErrorCode,
+} from "../core/context-evidence";
+export {
+  ContextVerifierError,
+  type ContextVerifierErrorCode,
+} from "../core/context-verifier";
+export {
+  ContextRuntimeError,
+  type ContextRuntimeErrorCode,
+} from "../app/context-runtime";

package/src/sdk/types.ts

@@ -4,8 +4,19 @@
  * @module src/sdk/types
  */
 
+import type {
+  ContextCapsuleBuildInput,
+  ContextRuntimeErrorCode,
+} from "../app/context-runtime";
 import type { Config } from "../config/types";
 import type { CaptureInput, CaptureReceipt } from "../core/capture";
+import type {
+  ContextCapsuleErrorCode,
+  ContextCapsuleV1,
+  ContextCapsuleVerification,
+} from "../core/context-capsule";
+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 { DocumentSection } from "../core/sections";
@@ -65,6 +76,15 @@ export type GnoVectorSearchOptions = SearchOptions & {
   model?: string;
 };
 
+export type GnoContextInput = Omit<ContextCapsuleBuildInput, "indexName">;
+export type GnoContextResult = ContextCapsuleV1;
+export type GnoContextVerificationResult = ContextCapsuleVerification;
+export type GnoContextErrorCode =
+  | ContextRuntimeErrorCode
+  | ContextCapsuleErrorCode
+  | ContextEvidenceErrorCode
+  | ContextVerifierErrorCode;
+
 export interface GnoGetOptions {
   from?: number;
   limit?: number;
@@ -185,6 +205,10 @@ export interface GnoClient {
   ): Promise<SearchResults>;
   query(query: string, options?: GnoQueryOptions): Promise<SearchResults>;
   ask(query: string, options?: GnoAskOptions): Promise<AskResult>;
+  context(input: GnoContextInput): Promise<GnoContextResult>;
+  verifyContext(
+    capsule: ContextCapsuleV1
+  ): Promise<GnoContextVerificationResult>;
   get(
     ref: string,
     options?: GnoGetOptions

package/src/serve/background-runtime.ts

@@ -157,6 +157,7 @@ export async function startBackgroundRuntime(
     config,
     {
       offline: options.offline ?? false,
+      indexName: options.index,
     }
   );
 

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/routes/api.ts

@@ -4509,6 +4509,7 @@ export async function routeApi(
     return handleStatus({
       store,
       config,
+      indexName: "default",
       vectorIndex: null,
       embedPort: null,
       expandPort: null,
@@ -4544,6 +4545,7 @@ export async function routeApi(
       current: {
         config,
         store,
+        indexName: "default",
         vectorIndex: null,
         embedPort: null,
         expandPort: null,

package/src/serve/server.ts

@@ -9,6 +9,7 @@
 import type { ContextHolder } from "./routes/api";
 
 import { startBackgroundRuntime } from "./background-runtime";
+import { handleContextBuild, handleContextVerify } from "./context-capsule";
 import { DocumentEventBus } from "./doc-events";
 // HTML import - Bun handles bundling TSX/CSS automatically via routes
 import homepage from "./public/index.html";
@@ -525,6 +526,28 @@ export async function startServer(
             );
           },
         },
+        "/api/context": {
+          POST: async (req: Request) => {
+            if (!isRequestAllowed(req, port)) {
+              return withSecurityHeaders(forbiddenResponse(), isDev);
+            }
+            return withSecurityHeaders(
+              await handleContextBuild(ctxHolder.current, req),
+              isDev
+            );
+          },
+        },
+        "/api/context/verify": {
+          POST: async (req: Request) => {
+            if (!isRequestAllowed(req, port)) {
+              return withSecurityHeaders(forbiddenResponse(), isDev);
+            }
+            return withSecurityHeaders(
+              await handleContextVerify(ctxHolder.current, req),
+              isDev
+            );
+          },
+        },
         "/api/query/diagnose": {
           POST: async (req: Request) => {
             if (!isRequestAllowed(req, port)) {

package/src/store/sqlite/adapter.ts

@@ -86,12 +86,17 @@ const WHITESPACE_REGEX = /\s+/;
 const SINGLE_LINE_QUERY_PATTERN = /[\r\n]/;
 const DOUBLE_QUOTE_PATTERN = /"/g;
 const DOC_EDGE_TYPE_PATTERN = /^[a-z][a-z0-9_]*$/;
+const SQLITE_SAFE_PARAMETER_BATCH_SIZE = 900;
 const FTS5_FIELD_WEIGHTS = {
   filepath: 1.5,
   title: 4.0,
   body: 1.0,
 } as const;
 
+const uniqueNonEmptyValues = (values: readonly string[]): string[] => [
+  ...new Set(values.filter((value) => value.trim().length > 0)),
+];
+
 /** Content-free activation snapshot query; kept exported for contract tests. */
 export const ACTIVATION_INDEX_SNAPSHOT_SQL = `SELECT
   d.id,
@@ -1384,28 +1389,38 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
     mirrorHashes: string[]
   ): Promise<StoreResult<Map<string, string>>> {
     try {
-      const db = this.ensureOpen();
-
-      if (mirrorHashes.length === 0) {
+      const uniqueHashes = uniqueNonEmptyValues(mirrorHashes);
+      if (uniqueHashes.length === 0) {
         return ok(new Map());
       }
+      const db = this.ensureOpen();
 
       interface DbContentRow {
         mirror_hash: string;
         markdown: string;
       }
 
-      const placeholders = mirrorHashes.map(() => "?").join(", ");
-      const rows = db
-        .query<DbContentRow, string[]>(
-          `SELECT mirror_hash, markdown FROM content
-           WHERE mirror_hash IN (${placeholders})`
-        )
-        .all(...mirrorHashes);
+      const result = new Map<string, string>();
+      for (
+        let offset = 0;
+        offset < uniqueHashes.length;
+        offset += SQLITE_SAFE_PARAMETER_BATCH_SIZE
+      ) {
+        const batch = uniqueHashes.slice(
+          offset,
+          offset + SQLITE_SAFE_PARAMETER_BATCH_SIZE
+        );
+        const placeholders = batch.map(() => "?").join(", ");
+        const rows = db
+          .query<DbContentRow, string[]>(
+            `SELECT mirror_hash, markdown FROM content
+             WHERE mirror_hash IN (${placeholders})`
+          )
+          .all(...batch);
+        for (const row of rows) result.set(row.mirror_hash, row.markdown);
+      }
 
-      return ok(
-        new Map(rows.map((row) => [row.mirror_hash, row.markdown] as const))
-      );
+      return ok(result);
     } catch (cause) {
       return err(
         "QUERY_FAILED",
@@ -1493,9 +1508,7 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
       }
 
       // Dedupe and filter empty strings
-      const uniqueHashes = [
-        ...new Set(mirrorHashes.filter((h) => h.trim().length > 0)),
-      ];
+      const uniqueHashes = uniqueNonEmptyValues(mirrorHashes);
       if (uniqueHashes.length === 0) {
         return ok(new Map());
       }
@@ -1505,11 +1518,16 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
 
       // SQLite SQLITE_LIMIT_VARIABLE_NUMBER defaults to 999
       // Reserve 99 for potential future filter params (collection, language, etc.)
-      const SQLITE_MAX_PARAMS = 900;
-
       // Batch queries to respect SQLite parameter limit
-      for (let i = 0; i < uniqueHashes.length; i += SQLITE_MAX_PARAMS) {
-        const batch = uniqueHashes.slice(i, i + SQLITE_MAX_PARAMS);
+      for (
+        let i = 0;
+        i < uniqueHashes.length;
+        i += SQLITE_SAFE_PARAMETER_BATCH_SIZE
+      ) {
+        const batch = uniqueHashes.slice(
+          i,
+          i + SQLITE_SAFE_PARAMETER_BATCH_SIZE
+        );
         const placeholders = batch.map(() => "?").join(",");
         const sql = `SELECT * FROM content_chunks
                      WHERE mirror_hash IN (${placeholders})