@gmickel/gno 1.16.0 → 1.17.0

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

@@ -0,0 +1,325 @@
+/** Validation, projection, and fingerprint rules for Context runtime surfaces. */
+
+import type { ContextCanonicalProjection } from "../core/context-budget";
+import type { ContextCapsuleV1 } from "../core/context-capsule";
+import type { ContextCapabilityState } from "../core/context-capsule-retrieval-schema";
+import type { ContextCapsulePayloadV1 } from "../core/context-capsule-schema";
+import type { ContextCanonicalPlanDraft } from "../core/context-compiler";
+import type { ContextEvidenceValue } from "../core/context-evidence";
+import type { NormalizedContextBuildInput } from "./context-runtime-input";
+import type { ContextCapsuleRuntimeDeps } from "./context-runtime-types";
+
+import {
+  ContextCapsuleContractError,
+  createContextCapsuleV1,
+} from "../core/context-capsule";
+import { sha256Text } from "../core/context-capsule-validation";
+import {
+  fingerprintContextRows,
+  toContextCapsuleEvidence,
+} from "../core/context-evidence";
+import { canonicalVerifierJson } from "../core/context-verifier-canonical";
+import { resolveModelUri } from "../llm/registry";
+
+const fingerprint = (value: unknown): string =>
+  sha256Text(canonicalVerifierJson(value));
+
+const configFingerprint = (deps: ContextCapsuleRuntimeDeps): string =>
+  fingerprint(deps.config);
+
+const configuredContextFingerprint = (
+  deps: ContextCapsuleRuntimeDeps
+): string =>
+  fingerprintContextRows(
+    (deps.config.contexts ?? []).map((context) => ({
+      ...context,
+      syncedAt: "",
+    }))
+  );
+
+const retrievalFingerprint = (
+  capsule: Pick<
+    ContextCapsuleV1,
+    "goal" | "query" | "scope" | "retrieval" | "capabilities"
+  >,
+  contextFingerprint: string
+): string =>
+  fingerprint({
+    capabilities: capsule.capabilities,
+    contextFingerprint,
+    goal: capsule.goal,
+    query: capsule.query,
+    retrieval: capsule.retrieval,
+    scope: capsule.scope,
+  });
+
+const capabilityState = (
+  requested: boolean,
+  used: boolean,
+  unavailableReasons: string[],
+  usedReasons: string[] = []
+): ContextCapabilityState => ({
+  requested,
+  attempted: requested,
+  outcome: used ? "used" : requested ? "unavailable" : "not_requested",
+  fallbackReasons: requested ? (used ? usedReasons : unavailableReasons) : [],
+});
+
+const capsuleCapabilityStates = (
+  draft: ContextCanonicalPlanDraft<ContextEvidenceValue>,
+  input: NormalizedContextBuildInput
+) => ({
+  semanticSearch: capabilityState(
+    input.depthPolicy !== "fast",
+    draft.retrieval.semanticSearch,
+    ["embedding_unavailable"]
+  ),
+  reranking: capabilityState(
+    input.depthPolicy !== "fast",
+    draft.retrieval.reranked,
+    ["reranking_unavailable"]
+  ),
+  graphExpansion: capabilityState(
+    input.graph,
+    draft.retrieval.graphExpansion,
+    draft.retrieval.graphFallbackReasons.length > 0
+      ? draft.retrieval.graphFallbackReasons
+      : ["graph_unavailable"],
+    draft.retrieval.graphFallbackReasons
+  ),
+});
+
+const capsuleCapabilities = (
+  states: ReturnType<typeof capsuleCapabilityStates>,
+  exactTokens: boolean,
+  configuredContext: boolean
+) => ({
+  lexicalSearch: true as const,
+  semanticSearch: states.semanticSearch.outcome === "used",
+  reranking: states.reranking.outcome === "used",
+  graphExpansion: states.graphExpansion.outcome === "used",
+  exactTokenCount: exactTokens,
+  configuredContext,
+  egressPolicy: false,
+});
+
+const capsuleFallbacks = (
+  capabilities: ReturnType<typeof capsuleCapabilities>,
+  states: ReturnType<typeof capsuleCapabilityStates>
+): ContextCapsulePayloadV1["fallbacks"] => [
+  ...(states.semanticSearch.outcome === "unavailable"
+    ? [
+        {
+          code: "embedding_unavailable" as const,
+          capability: "semantic_search" as const,
+        },
+      ]
+    : []),
+  ...(states.reranking.outcome === "unavailable"
+    ? [
+        {
+          code: "reranking_unavailable" as const,
+          capability: "reranking" as const,
+        },
+      ]
+    : []),
+  ...(states.graphExpansion.outcome === "unavailable"
+    ? [
+        {
+          code: "graph_unavailable" as const,
+          capability: "graph_expansion" as const,
+        },
+      ]
+    : []),
+  ...(capabilities.exactTokenCount
+    ? []
+    : [
+        {
+          code: "tokenizer_unavailable" as const,
+          capability: "token_count" as const,
+        },
+      ]),
+  { code: "egress_policy_unavailable", capability: "egress_policy" },
+];
+
+export const projectContextCapsule = (
+  draft: ContextCanonicalPlanDraft<ContextEvidenceValue>,
+  snapshots: { indexFingerprint: string; contextFingerprint: string },
+  input: NormalizedContextBuildInput,
+  deps: ContextCapsuleRuntimeDeps
+): ContextCanonicalProjection<ContextCapsuleV1> | null => {
+  if (draft.selection.selected.length === 0) return null;
+  const evidence = draft.selection.selected.map((candidate, index) =>
+    toContextCapsuleEvidence(candidate, index + 1)
+  );
+  const evidenceIdsByFacet = new Map<string, string[]>();
+  for (const item of evidence) {
+    for (const facet of item.facets) {
+      const ids = evidenceIdsByFacet.get(facet) ?? [];
+      ids.push(item.evidenceId);
+      evidenceIdsByFacet.set(facet, ids);
+    }
+  }
+  const exactTokens =
+    deps.countTokens !== undefined && deps.tokenizerFingerprint != null;
+  const capabilityStates = capsuleCapabilityStates(draft, input);
+  const capabilities = capsuleCapabilities(
+    capabilityStates,
+    exactTokens,
+    draft.configuredContexts.length > 0
+  );
+  const base = {
+    schemaVersion: "1.0" as const,
+    coordinateSpace: "canonical_mirror" as const,
+    goal: draft.goal,
+    query: draft.query,
+    scope: {
+      indexName: draft.indexName,
+      collections: draft.collections,
+      uriPrefix: draft.uriPrefix,
+      tagsAll: input.tagsAll,
+      tagsAny: input.tagsAny,
+      categories: input.categories,
+      since: input.since ?? null,
+      until: input.until ?? null,
+    },
+    retrieval: {
+      depthPolicy: input.depthPolicy,
+      facets: draft.retrieval.facets,
+      queryVariants: draft.retrieval.queryVariants,
+      expansionPolicy: "deterministic_only" as const,
+      request: {
+        author: input.author,
+        lang: input.lang,
+        queryModes: input.queryModes,
+        limit: input.limit,
+        candidateLimit: input.candidateLimit,
+        graphRequested: input.graph,
+      },
+      capabilityStates,
+      indexSnapshot: {
+        before: snapshots.indexFingerprint,
+        after: snapshots.indexFingerprint,
+        stable: true as const,
+      },
+    },
+    capabilities,
+  };
+  const payload: ContextCapsulePayloadV1 = {
+    ...base,
+    budget: {
+      authority: "canonical_json",
+      requestedTokens: input.budgetTokens,
+      requestedBytes: input.budgetBytes,
+      safetyMarginTokens: input.safetyMarginTokens,
+      safetyMarginBytes: input.safetyMarginBytes,
+      usedTokens: 1,
+      usedBytes: 0,
+      estimator: exactTokens ? "active_tokenizer" : "unicode_conservative",
+      tokenizerFingerprint: exactTokens
+        ? (deps.tokenizerFingerprint ?? null)
+        : null,
+    },
+    fingerprints: {
+      config: configFingerprint(deps),
+      retrieval: retrievalFingerprint(base, snapshots.contextFingerprint),
+      embeddingModel: capabilities.semanticSearch
+        ? sha256Text(deps.embedPort?.modelUri ?? "")
+        : null,
+      rerankModel: capabilities.reranking
+        ? sha256Text(deps.rerankPort?.modelUri ?? "")
+        : null,
+      tokenizer: exactTokens ? (deps.tokenizerFingerprint ?? null) : null,
+    },
+    fallbacks: capsuleFallbacks(capabilities, capabilityStates),
+    guidance: {
+      extractiveOnly: true,
+      evidenceTrust: "untrusted_data",
+      instructionBoundary: "hard_delimited",
+      configuredContexts: draft.configuredContexts,
+    },
+    evidence,
+    coverage: {
+      complete: draft.selection.coverage.unresolvedFacets.length === 0,
+      requestedFacets: draft.retrieval.facets,
+      coveredFacets: draft.selection.coverage.coveredFacets.map((facet) => ({
+        facet,
+        evidenceIds: evidenceIdsByFacet.get(facet) ?? [],
+      })),
+      unresolvedFacets: draft.selection.coverage.unresolvedFacets,
+      gaps: draft.selection.coverage.gaps,
+    },
+    omissions: {
+      total: draft.selection.omissions.length,
+      items: draft.selection.omissions.slice(0, 20),
+      reasonCounts: draft.selection.reasonCounts,
+      truncated: draft.selection.omissions.length > 20,
+    },
+    truncated: draft.selection.omissions.some(
+      (item) => item.reason === "global_budget"
+    ),
+    warnings: [
+      ...(draft.selection.coverage.unresolvedFacets.length > 0
+        ? [{ code: "incomplete_coverage" as const }]
+        : []),
+      ...(draft.selection.omissions.length > 20
+        ? [{ code: "omissions_truncated" as const }]
+        : []),
+      ...(exactTokens ? [] : [{ code: "token_estimate_used" as const }]),
+    ],
+  };
+  try {
+    const value = createContextCapsuleV1(payload, {
+      countTokens: deps.countTokens,
+    });
+    return {
+      value,
+      usedBytes: value.budget.usedBytes,
+      usedTokens: value.budget.usedTokens,
+    };
+  } catch (error) {
+    if (
+      error instanceof ContextCapsuleContractError &&
+      error.code === "invalid_budget"
+    ) {
+      return null;
+    }
+    throw error;
+  }
+};
+
+export const currentContextFingerprints = (
+  capsule: ContextCapsuleV1,
+  deps: ContextCapsuleRuntimeDeps
+) => ({
+  config: configFingerprint(deps),
+  retrieval: retrievalFingerprint(capsule, configuredContextFingerprint(deps)),
+  embeddingModel: capsule.capabilities.semanticSearch
+    ? sha256Text(
+        resolveModelUri(
+          deps.config,
+          "embed",
+          undefined,
+          capsule.scope.collections.length === 1
+            ? capsule.scope.collections[0]
+            : undefined
+        )
+      )
+    : null,
+  rerankModel: capsule.capabilities.reranking
+    ? sha256Text(
+        resolveModelUri(
+          deps.config,
+          "rerank",
+          undefined,
+          capsule.scope.collections.length === 1
+            ? capsule.scope.collections[0]
+            : undefined
+        )
+      )
+    : null,
+  tokenizer:
+    capsule.capabilities.exactTokenCount && deps.tokenizerFingerprint
+      ? deps.tokenizerFingerprint
+      : null,
+});

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