@gmickel/gno 1.16.0 → 1.17.0

package/src/app/context-runtime-types.ts

@@ -0,0 +1,65 @@
+import type { Config } from "../config/types";
+import type { ContextCapsuleV1 } from "../core/context-capsule";
+import type { ContextEvidenceCompilerDeps } from "../core/context-evidence";
+import type { ContextVerifierDeps } from "../core/context-verifier";
+import type { EmbeddingPort, RerankPort } from "../llm/types";
+import type { QueryModeInput } from "../pipeline/types";
+import type { StorePort } from "../store/types";
+import type { VectorIndexPort } from "../store/vector";
+
+export type ContextDepthPolicy = "fast" | "balanced" | "thorough";
+
+export interface ContextCapsuleBuildInput {
+  goal: string;
+  query?: string;
+  indexName?: string;
+  collections?: string[];
+  uriPrefix?: string | null;
+  queryModes?: QueryModeInput[];
+  tagsAll?: string[];
+  tagsAny?: string[];
+  categories?: string[];
+  author?: string;
+  lang?: string;
+  since?: string;
+  until?: string;
+  graph?: boolean;
+  limit?: number;
+  candidateLimit?: number;
+  budgetTokens: number;
+  budgetBytes?: number;
+  safetyMarginTokens?: number;
+  safetyMarginBytes?: number;
+  depthPolicy?: ContextDepthPolicy;
+}
+
+export interface ContextCapsuleRuntimeDeps {
+  store: StorePort &
+    ContextEvidenceCompilerDeps<ContextCapsuleV1>["store"] &
+    ContextVerifierDeps["store"];
+  config: Config;
+  indexName?: string;
+  vectorIndex?: VectorIndexPort | null;
+  embedPort?: EmbeddingPort | null;
+  rerankPort?: RerankPort | null;
+  countTokens?: (accountingJson: string) => number;
+  tokenizerFingerprint?: string | null;
+  resolveCurrentRanks?: ContextVerifierDeps["resolveCurrentRanks"];
+}
+
+export type ContextRuntimeErrorCode =
+  | "invalid_goal"
+  | "invalid_budget"
+  | "invalid_filter"
+  | "invalid_uri"
+  | "retrieval_failed";
+
+export class ContextRuntimeError extends Error {
+  readonly code: ContextRuntimeErrorCode;
+
+  constructor(code: ContextRuntimeErrorCode, message: string, cause?: unknown) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = "ContextRuntimeError";
+    this.code = code;
+  }
+}

package/src/app/context-runtime.ts

@@ -0,0 +1,170 @@
+/** Shared application boundary for Context Capsule build and verification. */
+
+import type {
+  ContextCapsuleV1,
+  ContextCapsuleVerification,
+} from "../core/context-capsule";
+import type {
+  ContextCapsuleBuildInput,
+  ContextCapsuleRuntimeDeps,
+} from "./context-runtime-types";
+
+import {
+  canonicalContextCapsuleJson,
+  ContextCapsuleContractError,
+} from "../core/context-capsule";
+import { compileContextEvidence } from "../core/context-evidence";
+import {
+  canonicalContextCapsuleVerificationJson,
+  parseCanonicalContextCapsuleForVerification,
+  verifyContextCapsule,
+} from "../core/context-verifier";
+import { searchHybrid } from "../pipeline/hybrid";
+import {
+  currentContextFingerprints,
+  projectContextCapsule,
+} from "./context-runtime-contract";
+import { normalizeContextBuildInput } from "./context-runtime-input";
+import { ContextRuntimeError } from "./context-runtime-types";
+import { canonicalizeIndexName } from "./index-name";
+
+export type {
+  ContextCapsuleBuildInput,
+  ContextCapsuleRuntimeDeps,
+  ContextDepthPolicy,
+  ContextRuntimeErrorCode,
+} from "./context-runtime-types";
+export { ContextRuntimeError } from "./context-runtime-types";
+
+/** Build one strict Capsule through the shared compiler composition. */
+export const buildContextCapsule = async (
+  input: ContextCapsuleBuildInput,
+  deps: ContextCapsuleRuntimeDeps
+): Promise<ContextCapsuleV1> => {
+  const now = new Date();
+  const normalized = normalizeContextBuildInput(
+    input,
+    deps.indexName,
+    now,
+    deps.config.collections.map((collection) => collection.name)
+  );
+  const noRerank = normalized.depthPolicy === "fast";
+  const plan = await compileContextEvidence<ContextCapsuleV1>(
+    {
+      goal: normalized.goal,
+      query: normalized.query,
+      indexName: normalized.indexName,
+      collections: normalized.collections,
+      uriPrefix: normalized.uriPrefix,
+      queryModes: normalized.queryModes,
+      tagsAll: normalized.tagsAll,
+      tagsAny: normalized.tagsAny,
+      categories: normalized.categories,
+      author: normalized.author ?? undefined,
+      lang: normalized.lang ?? undefined,
+      since: normalized.since,
+      until: normalized.until,
+      graph: normalized.graph,
+      limit: normalized.limit,
+      candidateLimit: normalized.candidateLimit,
+      temporalNow: now,
+      limits: {
+        requestedBytes: normalized.budgetBytes,
+        requestedTokens: normalized.budgetTokens,
+        safetyMarginBytes: normalized.safetyMarginBytes,
+        safetyMarginTokens: normalized.safetyMarginTokens,
+      },
+    },
+    {
+      store: deps.store,
+      retrieve: async (request) => {
+        const requestNoRerank = noRerank || request.noRerank === true;
+        const result = await searchHybrid(
+          {
+            store: deps.store,
+            config: deps.config,
+            vectorIndex: deps.vectorIndex ?? null,
+            embedPort: deps.embedPort ?? null,
+            expandPort: null,
+            rerankPort: requestNoRerank ? null : (deps.rerankPort ?? null),
+          },
+          request.query,
+          { ...request, noRerank: requestNoRerank }
+        );
+        if (!result.ok) {
+          throw new ContextRuntimeError(
+            "retrieval_failed",
+            result.error.message,
+            result.error.cause
+          );
+        }
+        return result.value;
+      },
+      projectCanonical: (draft, snapshots) =>
+        projectContextCapsule(draft, snapshots, normalized, deps),
+    }
+  );
+  if (!plan.projection) {
+    const budgetExhausted = plan.omissions.some(
+      (item) => item.reason === "global_budget"
+    );
+    throw new ContextCapsuleContractError(
+      budgetExhausted ? "invalid_budget" : "no_evidence",
+      budgetExhausted
+        ? "No evidence fit the requested Context Capsule budget"
+        : "No in-scope evidence was available for the Context Capsule"
+    );
+  }
+  return plan.projection.value;
+};
+
+/** Verify one Capsule through the same runtime fingerprint boundary. */
+export const verifyContextCapsuleRuntime = async (
+  input: unknown,
+  deps: ContextCapsuleRuntimeDeps
+): Promise<ContextCapsuleVerification> => {
+  // Parse before any store access. verifyContextCapsule repeats this guard to
+  // retain its standalone fail-closed contract.
+  const capsule = parseCanonicalContextCapsuleForVerification(input, {
+    countTokens: deps.countTokens,
+    tokenizerFingerprint: deps.tokenizerFingerprint,
+  });
+  if (
+    deps.indexName !== undefined &&
+    canonicalizeIndexName(deps.indexName) !== capsule.scope.indexName
+  ) {
+    throw new ContextRuntimeError(
+      "invalid_filter",
+      `Context Capsule index ${capsule.scope.indexName} does not match runtime index ${deps.indexName}`
+    );
+  }
+  return verifyContextCapsule(input, {
+    store: deps.store,
+    currentFingerprints: currentContextFingerprints(capsule, deps),
+    resolveCurrentRanks: deps.resolveCurrentRanks,
+    countTokens: deps.countTokens,
+    tokenizerFingerprint: deps.tokenizerFingerprint,
+  });
+};
+
+export const canonicalBuiltContextCapsuleJson = (
+  capsule: ContextCapsuleV1
+): string => canonicalContextCapsuleJson(capsule);
+
+export const canonicalVerifiedContextCapsuleJson = (
+  receipt: ContextCapsuleVerification
+): string => canonicalContextCapsuleVerificationJson(receipt);
+
+/** Pure validation used by CLI before opening the selected store. */
+export const validateContextCapsuleBuildInput = (
+  input: ContextCapsuleBuildInput,
+  defaultIndexName?: string,
+  configuredCollectionNames?: readonly string[]
+): void => {
+  normalizeContextBuildInput(
+    input,
+    defaultIndexName,
+    new Date(),
+    configuredCollectionNames
+  );
+};

package/src/app/context-surface.ts

@@ -0,0 +1,145 @@
+/** Closed wire contracts shared by Context Capsule REST and MCP surfaces. */
+
+import { z } from "zod";
+
+import type { ContextCapsuleBuildInput } from "./context-runtime-types";
+
+import { ContextCapsuleContractError } from "../core/context-capsule";
+
+const queryModeSchema = z
+  .object({
+    mode: z.enum(["term", "intent", "hyde"]),
+    text: z.string(),
+  })
+  .strict();
+
+const stringList = z.array(z.string());
+const positiveInteger = z.number().int().positive();
+const nonnegativeInteger = z.number().int().nonnegative();
+
+/** Host-owned index identity is deliberately absent from this public input. */
+export const contextBuildSurfaceSchema = z
+  .object({
+    goal: z.string(),
+    query: z.string().optional(),
+    collections: stringList.optional(),
+    uriPrefix: z.string().nullable().optional(),
+    queryModes: z.array(queryModeSchema).optional(),
+    tagsAll: stringList.optional(),
+    tagsAny: stringList.optional(),
+    categories: stringList.optional(),
+    author: z.string().optional(),
+    lang: z.string().optional(),
+    since: z.string().optional(),
+    until: z.string().optional(),
+    graph: z.boolean().optional(),
+    limit: positiveInteger.optional(),
+    candidateLimit: positiveInteger.optional(),
+    budgetTokens: positiveInteger,
+    budgetBytes: positiveInteger.optional(),
+    safetyMarginTokens: nonnegativeInteger.optional(),
+    safetyMarginBytes: nonnegativeInteger.optional(),
+    depthPolicy: z.enum(["fast", "balanced", "thorough"]).optional(),
+    format: z.enum(["json", "md"]).optional(),
+  })
+  .strict();
+
+export const contextVerifySurfaceSchema = z
+  .object({
+    capsule: z.record(z.string(), z.unknown()),
+    format: z.enum(["json", "md"]).optional(),
+  })
+  .strict();
+
+export type ContextSurfaceFormat = "json" | "md";
+
+export interface ParsedContextBuildSurfaceInput {
+  input: ContextCapsuleBuildInput;
+  format: ContextSurfaceFormat;
+}
+
+export interface ParsedContextVerifySurfaceInput {
+  capsule: Record<string, unknown>;
+  format: ContextSurfaceFormat;
+}
+
+const CONTEXT_SURFACE_ERROR_MESSAGES = {
+  capsule_mutated_during_verify:
+    "The Context Capsule changed during verification.",
+  chunk_coordinate_mismatch:
+    "Indexed evidence coordinates do not match the source.",
+  chunk_load_failed: "Context Capsule evidence chunks could not be loaded.",
+  collection_load_failed: "Context Capsule collections could not be loaded.",
+  content_load_failed: "Context Capsule source content could not be loaded.",
+  context_changed_during_compile:
+    "Configured context changed during compilation.",
+  context_changed_during_verify:
+    "Configured context changed during verification.",
+  context_load_failed: "Configured context could not be loaded.",
+  document_load_failed: "Context Capsule documents could not be loaded.",
+  identity_mismatch: "The Context Capsule identity does not match its content.",
+  index_changed_during_compile: "The index changed during compilation.",
+  index_changed_during_verify: "The index changed during verification.",
+  index_snapshot_failed: "The index snapshot could not be loaded.",
+  index_snapshot_mismatch:
+    "Indexed evidence does not match the captured snapshot.",
+  invalid_budget: "The Context Capsule budget is invalid.",
+  invalid_filter: "A Context Capsule filter is invalid.",
+  invalid_goal: "The Context Capsule goal is invalid.",
+  invalid_input: "The Context Capsule request is invalid.",
+  invalid_uri: "The Context Capsule URI is invalid.",
+  no_evidence: "No in-scope evidence was available for the Context Capsule.",
+  retrieval_failed: "Context Capsule retrieval failed.",
+  runtime_error: "The Context Capsule request failed.",
+  stored_provenance_mismatch:
+    "Stored evidence provenance does not match the source.",
+  tokenizer_unavailable: "The required tokenizer is unavailable.",
+} as const;
+
+export type ContextSurfaceErrorCode =
+  keyof typeof CONTEXT_SURFACE_ERROR_MESSAGES;
+
+const invalidInput = (error: z.ZodError): ContextCapsuleContractError =>
+  new ContextCapsuleContractError(
+    "invalid_input",
+    error.issues
+      .map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`)
+      .join("; ")
+  );
+
+export const parseContextBuildSurfaceInput = (
+  value: unknown,
+  indexName: string
+): ParsedContextBuildSurfaceInput => {
+  const parsed = contextBuildSurfaceSchema.safeParse(value);
+  if (!parsed.success) throw invalidInput(parsed.error);
+  const { format = "json", ...input } = parsed.data;
+  return { input: { ...input, indexName }, format };
+};
+
+export const parseContextVerifySurfaceInput = (
+  value: unknown
+): ParsedContextVerifySurfaceInput => {
+  const parsed = contextVerifySurfaceSchema.safeParse(value);
+  if (!parsed.success) throw invalidInput(parsed.error);
+  return {
+    capsule: parsed.data.capsule,
+    format: parsed.data.format ?? "json",
+  };
+};
+
+export const contextSurfaceError = (
+  error: unknown
+): { code: ContextSurfaceErrorCode; message: string } => {
+  const candidate =
+    error !== null &&
+    typeof error === "object" &&
+    "code" in error &&
+    typeof error.code === "string"
+      ? error.code
+      : "runtime_error";
+  const code = Object.hasOwn(CONTEXT_SURFACE_ERROR_MESSAGES, candidate)
+    ? (candidate as ContextSurfaceErrorCode)
+    : "runtime_error";
+  return { code, message: CONTEXT_SURFACE_ERROR_MESSAGES[code] };
+};

package/src/cli/commands/context-build.ts

@@ -0,0 +1,149 @@
+/** Context Capsule build command over the shared application runtime. */
+
+import type { ContextCapsuleBuildInput } from "../../app/context-runtime";
+import type { EmbeddingPort, RerankPort } from "../../llm/types";
+import type { VectorIndexPort } from "../../store/vector";
+
+import { formatContextCapsuleMarkdown } from "../../app/context-format";
+import {
+  buildContextCapsule,
+  canonicalBuiltContextCapsuleJson,
+  validateContextCapsuleBuildInput,
+} from "../../app/context-runtime";
+import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
+import { resolveDownloadPolicy } from "../../llm/policy";
+import { resolveModelUri } from "../../llm/registry";
+import { createVectorIndexPort } from "../../store/vector";
+import { CliError } from "../errors";
+import { getGlobals } from "../program";
+import {
+  createProgressRenderer,
+  createThrottledProgressRenderer,
+} from "../progress";
+import { initStore } from "./shared";
+
+export interface ContextBuildCommandOptions extends Omit<
+  ContextCapsuleBuildInput,
+  "goal"
+> {
+  configPath?: string;
+  format: "json" | "md";
+}
+
+const validationCodes = new Set([
+  "identity_mismatch",
+  "invalid_budget",
+  "invalid_filter",
+  "invalid_goal",
+  "invalid_input",
+  "invalid_uri",
+]);
+
+export const contextCliError = (error: unknown): CliError => {
+  const contextCode =
+    error !== null &&
+    typeof error === "object" &&
+    "code" in error &&
+    typeof error.code === "string"
+      ? error.code
+      : "runtime_error";
+  return new CliError(
+    validationCodes.has(contextCode) ? "VALIDATION" : "RUNTIME",
+    error instanceof Error ? error.message : String(error),
+    { details: { contextCode } }
+  );
+};
+
+// oxlint-disable-next-line max-lines-per-function -- owns one bounded model/store lifecycle
+export const contextBuild = async (
+  goal: string,
+  options: ContextBuildCommandOptions
+): Promise<string> => {
+  try {
+    validateContextCapsuleBuildInput({ goal, ...options }, options.indexName);
+  } catch (error) {
+    throw contextCliError(error);
+  }
+  const initResult = await initStore({
+    configPath: options.configPath,
+    indexName: options.indexName,
+    syncConfig: true,
+  });
+  if (!initResult.ok) {
+    throw new CliError("RUNTIME", initResult.error);
+  }
+  const { config, store } = initResult;
+  const llm = new LlmAdapter(config);
+  let embedPort: EmbeddingPort | null = null;
+  let rerankPort: RerankPort | null = null;
+  let vectorIndex: VectorIndexPort | null = null;
+  try {
+    validateContextCapsuleBuildInput(
+      { goal, ...options },
+      options.indexName,
+      config.collections.map((collection) => collection.name)
+    );
+    if (options.depthPolicy !== "fast") {
+      const globals = getGlobals();
+      const policy = resolveDownloadPolicy(process.env, {
+        offline: globals.offline,
+      });
+      const showProgress = process.stderr.isTTY && !globals.quiet;
+      const progress = showProgress
+        ? createThrottledProgressRenderer(createProgressRenderer())
+        : undefined;
+      const collection =
+        options.collections?.length === 1 ? options.collections[0] : undefined;
+      const embedUri = resolveModelUri(config, "embed", undefined, collection);
+      const embedResult = await llm.createEmbeddingPort(embedUri, {
+        policy,
+        onProgress: progress ? (value) => progress("embed", value) : undefined,
+      });
+      if (embedResult.ok) {
+        embedPort = embedResult.value;
+        const initialized = await embedPort.init();
+        if (initialized.ok) {
+          const vectorResult = await createVectorIndexPort(store.getRawDb(), {
+            model: embedUri,
+            dimensions: embedPort.dimensions(),
+          });
+          if (vectorResult.ok) vectorIndex = vectorResult.value;
+        }
+      }
+      const rerankUri = resolveModelUri(
+        config,
+        "rerank",
+        undefined,
+        collection
+      );
+      const rerankResult = await llm.createRerankPort(rerankUri, {
+        policy,
+        onProgress: progress ? (value) => progress("rerank", value) : undefined,
+      });
+      if (rerankResult.ok) rerankPort = rerankResult.value;
+      if (showProgress && progress) process.stderr.write("\n");
+    }
+    const capsule = await buildContextCapsule(
+      { goal, ...options },
+      {
+        store,
+        config,
+        indexName: options.indexName,
+        vectorIndex,
+        embedPort,
+        rerankPort,
+      }
+    );
+    return options.format === "md"
+      ? formatContextCapsuleMarkdown(capsule)
+      : canonicalBuiltContextCapsuleJson(capsule);
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    throw contextCliError(error);
+  } finally {
+    await embedPort?.dispose();
+    await rerankPort?.dispose();
+    await llm.dispose();
+    await store.close();
+  }
+};

package/src/cli/commands/context-verify.ts

@@ -0,0 +1,90 @@
+/** Context Capsule verification command over the shared application runtime. */
+
+import { formatContextCapsuleVerificationMarkdown } from "../../app/context-format";
+import {
+  canonicalVerifiedContextCapsuleJson,
+  verifyContextCapsuleRuntime,
+} from "../../app/context-runtime";
+import { canonicalizeIndexName } from "../../app/index-name";
+import { parseCanonicalContextCapsuleForVerification } from "../../core/context-verifier";
+import { CliError } from "../errors";
+import { contextCliError } from "./context-build";
+import { initStore } from "./shared";
+
+export interface ContextVerifyCommandOptions {
+  configPath?: string;
+  indexName?: string;
+  format: "json" | "md";
+}
+
+const readCapsule = async (source: string): Promise<unknown> => {
+  let raw: string;
+  try {
+    raw =
+      source === "-" ? await Bun.stdin.text() : await Bun.file(source).text();
+  } catch (error) {
+    throw new CliError(
+      "RUNTIME",
+      `Failed to read Context Capsule: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+  }
+  try {
+    return JSON.parse(raw) as unknown;
+  } catch (error) {
+    throw new CliError("VALIDATION", "Context Capsule must be valid JSON", {
+      details: {
+        contextCode: "invalid_input",
+        cause: error instanceof Error ? error.message : String(error),
+      },
+    });
+  }
+};
+
+export const contextVerify = async (
+  source: string,
+  options: ContextVerifyCommandOptions
+): Promise<string> => {
+  const input = await readCapsule(source);
+  let capsule: ReturnType<typeof parseCanonicalContextCapsuleForVerification>;
+  try {
+    capsule = parseCanonicalContextCapsuleForVerification(input);
+  } catch (error) {
+    throw contextCliError(error);
+  }
+  if (
+    options.indexName !== undefined &&
+    canonicalizeIndexName(options.indexName) !== capsule.scope.indexName
+  ) {
+    throw new CliError(
+      "VALIDATION",
+      `Context Capsule index ${capsule.scope.indexName} does not match --index ${options.indexName}`,
+      { details: { contextCode: "invalid_filter" } }
+    );
+  }
+  const initResult = await initStore({
+    configPath: options.configPath,
+    indexName: capsule.scope.indexName,
+    syncConfig: true,
+  });
+  if (!initResult.ok) {
+    throw new CliError("RUNTIME", initResult.error);
+  }
+  const { config, store } = initResult;
+  try {
+    const receipt = await verifyContextCapsuleRuntime(capsule, {
+      store,
+      config,
+      indexName: capsule.scope.indexName,
+    });
+    return options.format === "md"
+      ? formatContextCapsuleVerificationMarkdown(receipt)
+      : canonicalVerifiedContextCapsuleJson(receipt);
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    throw contextCliError(error);
+  } finally {
+    await store.close();
+  }
+};

package/src/cli/options.ts

@@ -33,6 +33,8 @@ export const CMD = {
   collectionList: "collection.list",
   contextList: "context.list",
   contextCheck: "context.check",
+  contextBuild: "context.build",
+  contextVerify: "context.verify",
   modelsList: "models.list",
   tagsList: "tags.list",
   linksList: "links.list",
@@ -60,6 +62,8 @@ const FORMAT_SUPPORT: Record<CommandId, OutputFormat[]> = {
   [CMD.collectionList]: ["terminal", "json", "md"],
   [CMD.contextList]: ["terminal", "json", "md"],
   [CMD.contextCheck]: ["terminal", "json", "md"],
+  [CMD.contextBuild]: ["terminal", "json", "md"],
+  [CMD.contextVerify]: ["terminal", "json", "md"],
   [CMD.modelsList]: ["terminal", "json"],
   [CMD.tagsList]: ["terminal", "json", "md"],
   [CMD.linksList]: ["terminal", "json", "md"],