@gmickel/gno 1.16.0 → 1.18.0

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

@@ -0,0 +1,362 @@
+/** Strict shared input normalization for every Context Capsule surface. */
+
+import type { QueryModeInput } from "../pipeline/types";
+import type { ContextCapsuleBuildInput } from "./context-runtime-types";
+
+import { isValidLanguageHint } from "../config/types";
+import { normalizeTag, validateTag } from "../core/tags";
+import { resolveTemporalRange } from "../pipeline/temporal";
+import { buildUri, parseUri } from "./constants";
+import { ContextRuntimeError } from "./context-runtime-types";
+import { canonicalizeIndexName } from "./index-name";
+
+const COLLECTION_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const QUERY_MODES = new Set(["term", "intent", "hyde"]);
+const MAX_FILTER_VALUES = 128;
+const MAX_FILTER_LENGTH = 256;
+const MAX_TEXT_LENGTH = 16_384;
+const DEFAULT_LIMIT = 20;
+const DEFAULT_CANDIDATE_LIMIT = 40;
+
+const compareCodeUnits = (left: string, right: string): number =>
+  left < right ? -1 : left > right ? 1 : 0;
+
+const canonicalStrings = (
+  values: readonly string[] | undefined,
+  label: string
+): string[] => {
+  if (
+    values !== undefined &&
+    (!Array.isArray(values) ||
+      values.some((value) => typeof value !== "string"))
+  ) {
+    throw new ContextRuntimeError("invalid_filter", `${label} must be strings`);
+  }
+  return [
+    ...new Set((values ?? []).map((value) => value.normalize("NFC").trim())),
+  ].sort(compareCodeUnits);
+};
+
+const canonicalFilters = (
+  values: readonly string[] | undefined,
+  label: string
+): string[] => {
+  const normalized = canonicalStrings(values, label);
+  if (
+    normalized.length > MAX_FILTER_VALUES ||
+    normalized.some(
+      (value) =>
+        value.length === 0 ||
+        value.length > MAX_FILTER_LENGTH ||
+        value.includes("\r")
+    )
+  ) {
+    throw new ContextRuntimeError(
+      "invalid_filter",
+      `${label} contains an invalid value`
+    );
+  }
+  return normalized;
+};
+
+const canonicalTagFilters = (
+  values: readonly string[] | undefined,
+  label: string
+): string[] => {
+  if (
+    values !== undefined &&
+    (!Array.isArray(values) ||
+      values.some((value) => typeof value !== "string"))
+  ) {
+    throw new ContextRuntimeError("invalid_filter", `${label} must be strings`);
+  }
+  const normalized = [
+    ...new Set((values ?? []).map((value) => normalizeTag(value))),
+  ].sort(compareCodeUnits);
+  if (
+    normalized.length > MAX_FILTER_VALUES ||
+    normalized.some(
+      (value) =>
+        value.length > MAX_FILTER_LENGTH ||
+        value.includes("\r") ||
+        !validateTag(value)
+    )
+  ) {
+    throw new ContextRuntimeError(
+      "invalid_filter",
+      `${label} contains an invalid tag`
+    );
+  }
+  return normalized;
+};
+
+const positiveSafeInteger = (
+  value: number,
+  label: string,
+  code: "invalid_budget" | "invalid_filter" = "invalid_budget"
+): number => {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new ContextRuntimeError(
+      code,
+      `${label} must be a positive safe integer`
+    );
+  }
+  return value;
+};
+
+const canonicalQueryModes = (
+  values: QueryModeInput[] | undefined
+): QueryModeInput[] => {
+  if (values === undefined) return [];
+  if (!Array.isArray(values) || values.length > MAX_FILTER_VALUES) {
+    throw new ContextRuntimeError("invalid_filter", "Invalid query modes");
+  }
+  const normalized = values.map((value) => {
+    if (
+      value === null ||
+      typeof value !== "object" ||
+      !QUERY_MODES.has(value.mode) ||
+      typeof value.text !== "string"
+    ) {
+      throw new ContextRuntimeError("invalid_filter", "Invalid query mode");
+    }
+    const text = value.text.normalize("NFC").trim();
+    if (!text || text.length > 4096 || text.includes("\r")) {
+      throw new ContextRuntimeError(
+        "invalid_filter",
+        "Invalid query mode text"
+      );
+    }
+    return { mode: value.mode, text };
+  });
+  if (normalized.filter((value) => value.mode === "hyde").length > 1) {
+    throw new ContextRuntimeError(
+      "invalid_filter",
+      "Only one hyde query mode is allowed"
+    );
+  }
+  return normalized;
+};
+
+const validateUriPrefix = (
+  value: string | null | undefined,
+  indexName: string,
+  collections: readonly string[]
+): string | null => {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== "string") {
+    throw new ContextRuntimeError("invalid_uri", "URI prefix must be a string");
+  }
+  const parsed = parseUri(value);
+  if (
+    !parsed ||
+    parsed.collection.length === 0 ||
+    (parsed.indexName !== undefined &&
+      canonicalizeIndexName(parsed.indexName) !== indexName) ||
+    (collections.length > 0 && !collections.includes(parsed.collection))
+  ) {
+    throw new ContextRuntimeError(
+      "invalid_uri",
+      "URI prefix must be a canonical GNO reference inside the requested index and collections"
+    );
+  }
+  if (buildUri(parsed.collection, parsed.path, { indexName }) !== value) {
+    throw new ContextRuntimeError(
+      "invalid_uri",
+      "URI prefix must use its canonical indexed GNO representation"
+    );
+  }
+  return value;
+};
+
+export const normalizeContextBuildInput = (
+  input: ContextCapsuleBuildInput,
+  defaultIndexName: string | undefined,
+  now: Date,
+  configuredCollectionNames?: readonly string[]
+) => {
+  if (!input || typeof input !== "object" || typeof input.goal !== "string") {
+    throw new ContextRuntimeError("invalid_goal", "Context goal is required");
+  }
+  const rawQuery = input.query ?? input.goal;
+  const goal = input.goal.normalize("NFC").trim();
+  const query =
+    typeof rawQuery === "string" ? rawQuery.normalize("NFC").trim() : "";
+  if (
+    !goal ||
+    !query ||
+    goal.length > MAX_TEXT_LENGTH ||
+    query.length > MAX_TEXT_LENGTH ||
+    goal.includes("\r") ||
+    query.includes("\r")
+  ) {
+    throw new ContextRuntimeError(
+      "invalid_goal",
+      "Context goal and query must be non-empty canonical text"
+    );
+  }
+  let indexName: string;
+  try {
+    indexName = canonicalizeIndexName(
+      input.indexName ?? defaultIndexName ?? "default"
+    );
+  } catch (cause) {
+    throw new ContextRuntimeError(
+      "invalid_filter",
+      "Context index name is invalid",
+      cause
+    );
+  }
+  const collections = canonicalStrings(input.collections, "collections");
+  if (
+    collections.length > MAX_FILTER_VALUES ||
+    collections.some((value) => !COLLECTION_PATTERN.test(value))
+  ) {
+    throw new ContextRuntimeError(
+      "invalid_filter",
+      "Invalid collection filter"
+    );
+  }
+  if (configuredCollectionNames) {
+    const configured = new Set(configuredCollectionNames);
+    const unknown = collections.find(
+      (collection) => !configured.has(collection)
+    );
+    if (unknown) {
+      throw new ContextRuntimeError(
+        "invalid_filter",
+        `Collection not found: ${unknown}`
+      );
+    }
+    const prefixCollection =
+      input.uriPrefix === undefined || input.uriPrefix === null
+        ? null
+        : parseUri(input.uriPrefix)?.collection;
+    if (prefixCollection && !configured.has(prefixCollection)) {
+      throw new ContextRuntimeError(
+        "invalid_filter",
+        `Collection not found: ${prefixCollection}`
+      );
+    }
+  }
+  const uriPrefix = validateUriPrefix(input.uriPrefix, indexName, collections);
+  const budgetTokens = positiveSafeInteger(
+    input.budgetTokens,
+    "Context token budget"
+  );
+  const budgetBytes =
+    input.budgetBytes === undefined
+      ? Math.min(Number.MAX_SAFE_INTEGER, budgetTokens * 4)
+      : positiveSafeInteger(input.budgetBytes, "Context byte budget");
+  const safetyMarginTokens = input.safetyMarginTokens ?? 0;
+  const safetyMarginBytes = input.safetyMarginBytes ?? 0;
+  if (
+    !Number.isSafeInteger(safetyMarginTokens) ||
+    !Number.isSafeInteger(safetyMarginBytes) ||
+    safetyMarginTokens < 0 ||
+    safetyMarginBytes < 0 ||
+    safetyMarginTokens >= budgetTokens ||
+    safetyMarginBytes >= budgetBytes
+  ) {
+    throw new ContextRuntimeError(
+      "invalid_budget",
+      "Context safety margins must be non-negative and smaller than their budgets"
+    );
+  }
+  if (
+    (input.since !== undefined && typeof input.since !== "string") ||
+    (input.until !== undefined && typeof input.until !== "string")
+  ) {
+    throw new ContextRuntimeError(
+      "invalid_filter",
+      "Context date filters are invalid"
+    );
+  }
+  const temporalRange = resolveTemporalRange(
+    query,
+    input.since,
+    input.until,
+    now
+  );
+  if (
+    (input.since !== undefined && temporalRange.since === undefined) ||
+    (input.until !== undefined && temporalRange.until === undefined) ||
+    (temporalRange.since !== undefined &&
+      temporalRange.until !== undefined &&
+      temporalRange.since > temporalRange.until)
+  ) {
+    throw new ContextRuntimeError(
+      "invalid_filter",
+      "Context date filters are invalid or reversed"
+    );
+  }
+  const depthPolicy = input.depthPolicy ?? "balanced";
+  if (!["fast", "balanced", "thorough"].includes(depthPolicy)) {
+    throw new ContextRuntimeError(
+      "invalid_filter",
+      "Invalid Context depth policy"
+    );
+  }
+  const limit = input.limit ?? DEFAULT_LIMIT;
+  const candidateLimit =
+    input.candidateLimit ??
+    (depthPolicy === "thorough"
+      ? DEFAULT_CANDIDATE_LIMIT * 2
+      : DEFAULT_CANDIDATE_LIMIT);
+  positiveSafeInteger(limit, "Context result limit", "invalid_filter");
+  positiveSafeInteger(
+    candidateLimit,
+    "Context candidate limit",
+    "invalid_filter"
+  );
+  if (input.graph !== undefined && typeof input.graph !== "boolean") {
+    throw new ContextRuntimeError(
+      "invalid_filter",
+      "Context graph flag must be boolean"
+    );
+  }
+  const author =
+    typeof input.author === "string"
+      ? input.author.normalize("NFC").trim()
+      : null;
+  const lang =
+    typeof input.lang === "string" ? input.lang.normalize("NFC").trim() : null;
+  if (
+    (input.author !== undefined &&
+      (!author || author.length > MAX_FILTER_LENGTH)) ||
+    (input.lang !== undefined && (!lang || !isValidLanguageHint(lang)))
+  ) {
+    throw new ContextRuntimeError(
+      "invalid_filter",
+      "Context author or language filter is invalid"
+    );
+  }
+  return {
+    ...input,
+    goal,
+    query,
+    indexName,
+    collections,
+    uriPrefix,
+    queryModes: canonicalQueryModes(input.queryModes),
+    tagsAll: canonicalTagFilters(input.tagsAll, "tagsAll"),
+    tagsAny: canonicalTagFilters(input.tagsAny, "tagsAny"),
+    categories: canonicalFilters(input.categories, "categories"),
+    author,
+    lang,
+    since: temporalRange.since,
+    until: temporalRange.until,
+    graph: input.graph ?? false,
+    limit,
+    candidateLimit,
+    budgetTokens,
+    budgetBytes,
+    safetyMarginTokens,
+    safetyMarginBytes,
+    depthPolicy,
+  };
+};
+
+export type NormalizedContextBuildInput = ReturnType<
+  typeof normalizeContextBuildInput
+>;

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