@gmickel/gno 1.16.0 → 1.18.0

package/src/app/context-format.ts

@@ -0,0 +1,249 @@
+/** Deterministic readable projections for Context Capsule surfaces. */
+
+import type {
+  ContextCapsuleV1,
+  ContextCapsuleVerification,
+} from "../core/context-capsule";
+
+import { canonicalContextCapsuleJson } from "../core/context-capsule";
+import { canonicalContextCapsuleVerificationJson } from "../core/context-verifier";
+
+const nullable = (value: string | number | null): string =>
+  value === null ? "unavailable" : String(value);
+const json = (value: unknown): string => JSON.stringify(value);
+const indentedJson = (value: unknown): string[] =>
+  JSON.stringify(value, null, 2)
+    .split("\n")
+    .map((line) => `    ${line}`);
+
+const longestRun = (value: string, character: "`" | "~"): number => {
+  let longest = 0;
+  let current = 0;
+  for (const codePoint of value) {
+    if (codePoint === character) {
+      current += 1;
+      longest = Math.max(longest, current);
+    } else {
+      current = 0;
+    }
+  }
+  return longest;
+};
+
+const untrustedFence = (value: string): string => {
+  const backtickLength = Math.max(3, longestRun(value, "`") + 1);
+  const tildeLength = Math.max(3, longestRun(value, "~") + 1);
+  const character = backtickLength <= tildeLength ? "`" : "~";
+  return character.repeat(Math.min(backtickLength, tildeLength));
+};
+
+const untrustedBlock = (label: string, value: string): string[] => {
+  const fence = untrustedFence(value);
+  return [`${fence}${label}`, value, fence];
+};
+
+const capabilityLines = (capsule: ContextCapsuleV1): string[] =>
+  Object.entries(capsule.retrieval.capabilityStates).flatMap(
+    ([capability, state]) => [
+      `- ${capability}: ${state.outcome}`,
+      `  - requested: ${state.requested}`,
+      `  - attempted: ${state.attempted}`,
+      `  - fallback reasons: ${
+        state.fallbackReasons.length > 0
+          ? state.fallbackReasons.join(", ")
+          : "none"
+      }`,
+    ]
+  );
+
+const configuredContextLines = (
+  capsule: ContextCapsuleV1,
+  contextIds: readonly string[]
+): string[] => {
+  const contexts = capsule.guidance.configuredContexts.filter((context) =>
+    contextIds.includes(context.contextId)
+  );
+  return contexts.length === 0
+    ? ["    []"]
+    : indentedJson(
+        contexts.map(({ contextId, scopeType, scopeKey, text }) => ({
+          contextId,
+          scopeType,
+          scopeKey,
+          text,
+        }))
+      );
+};
+
+const evidenceBlock = (
+  capsule: ContextCapsuleV1,
+  item: ContextCapsuleV1["evidence"][number]
+): string[] => {
+  const metadata = [
+    `{"title":${json(item.title)},"heading":${json(item.heading)}}`,
+    "configuredContexts:",
+    ...configuredContextLines(capsule, item.contextIds).map((line) =>
+      line.startsWith("    ") ? line.slice(4) : line
+    ),
+  ].join("\n");
+  return [
+    `## Evidence ${item.selectionRank}`,
+    "",
+    `- Evidence ID: \`${item.evidenceId}\``,
+    `- URI: \`${item.uri}\``,
+    `- Docid: \`${item.docid}\``,
+    `- Collection: \`${item.collection}\``,
+    `- Lines: ${item.startLine}-${item.endLine}`,
+    `- Retrieval rank: ${item.retrievalRank}`,
+    `- Selection rank: ${item.selectionRank}`,
+    `- Modified: ${nullable(item.modifiedAt)}`,
+    `- Document date: ${nullable(item.documentDate)}`,
+    `- Observed: ${nullable(item.observedAt)}`,
+    `- Facets: ${item.facets.length > 0 ? item.facets.join(", ") : "none"}`,
+    `- Trust: ${item.trust}`,
+    `- Egress: ${item.egress}`,
+    `- Source hash: \`${item.sourceHash}\``,
+    `- Mirror hash: \`${item.mirrorHash}\``,
+    `- Passage hash: \`${item.passageHash}\``,
+    "",
+    ...untrustedBlock(`gno-untrusted-metadata-${item.evidenceId}`, metadata),
+    "",
+    ...untrustedBlock(`gno-untrusted-evidence-${item.evidenceId}`, item.text),
+    "",
+  ];
+};
+
+const omissionLines = (capsule: ContextCapsuleV1): string[] => [
+  `- Total: ${capsule.omissions.total}`,
+  `- Visible items: ${capsule.omissions.items.length}`,
+  `- Bounded-list truncated: ${capsule.omissions.truncated}`,
+  ...Object.entries(capsule.omissions.reasonCounts).map(
+    ([reason, count]) => `- ${reason}: ${count}`
+  ),
+];
+
+export const formatContextCapsuleMarkdown = (
+  capsule: ContextCapsuleV1
+): string => {
+  const lines = [
+    "# GNO Context Capsule",
+    "",
+    `- Schema: ${capsule.schemaVersion}`,
+    `- Coordinate space: ${capsule.coordinateSpace}`,
+    `- Capsule ID: \`${capsule.capsuleId}\``,
+    `- Goal: ${json(capsule.goal)}`,
+    `- Query: ${json(capsule.query)}`,
+    `- Index: \`${capsule.scope.indexName}\``,
+    `- Collections: ${
+      capsule.scope.collections.length > 0
+        ? capsule.scope.collections.join(", ")
+        : "all"
+    }`,
+    `- URI prefix: ${nullable(capsule.scope.uriPrefix)}`,
+    `- Tags all: ${json(capsule.scope.tagsAll)}`,
+    `- Tags any: ${json(capsule.scope.tagsAny)}`,
+    `- Categories: ${json(capsule.scope.categories)}`,
+    `- Since/until: ${nullable(capsule.scope.since)} / ${nullable(capsule.scope.until)}`,
+    "",
+    "## Budget and retrieval",
+    "",
+    `- Budget: ${capsule.budget.usedTokens}/${capsule.budget.requestedTokens} tokens; ${capsule.budget.usedBytes}/${capsule.budget.requestedBytes} bytes`,
+    `- Safety margin: ${capsule.budget.safetyMarginTokens} tokens; ${capsule.budget.safetyMarginBytes} bytes`,
+    `- Estimator: ${capsule.budget.estimator}`,
+    `- Tokenizer fingerprint: ${nullable(capsule.budget.tokenizerFingerprint)}`,
+    `- Depth: ${capsule.retrieval.depthPolicy}`,
+    `- Facets: ${json(capsule.retrieval.facets)}`,
+    `- Query variants: ${json(capsule.retrieval.queryVariants)}`,
+    `- Request: ${json(capsule.retrieval.request)}`,
+    `- Index snapshot: ${json(capsule.retrieval.indexSnapshot)}`,
+    "",
+    "## Capabilities and fallbacks",
+    "",
+    ...capabilityLines(capsule),
+    `- Effective capabilities: ${json(capsule.capabilities)}`,
+    `- Fallbacks: ${json(capsule.fallbacks)}`,
+    "",
+    "## Fingerprints",
+    "",
+    ...Object.entries(capsule.fingerprints).map(
+      ([name, value]) => `- ${name}: ${nullable(value)}`
+    ),
+    "",
+    ...capsule.evidence.flatMap((item) => evidenceBlock(capsule, item)),
+    "## Coverage, omissions, and truncation",
+    "",
+    `- Coverage complete: ${capsule.coverage.complete}`,
+    `- Requested facets: ${json(capsule.coverage.requestedFacets)}`,
+    `- Covered facets: ${json(capsule.coverage.coveredFacets)}`,
+    `- Unresolved facets: ${json(capsule.coverage.unresolvedFacets)}`,
+    `- Gaps: ${json(capsule.coverage.gaps)}`,
+    `- Capsule truncated: ${capsule.truncated}`,
+    `- Warnings: ${json(capsule.warnings)}`,
+    ...omissionLines(capsule),
+    `- Omission items: ${json(capsule.omissions.items)}`,
+    "",
+    "## Canonical manifest",
+    "",
+    ...untrustedBlock(
+      "gno-untrusted-manifest-json",
+      JSON.stringify(JSON.parse(canonicalContextCapsuleJson(capsule)), null, 2)
+    ),
+    "",
+  ];
+  return lines.join("\n");
+};
+
+export const formatContextCapsuleVerificationMarkdown = (
+  receipt: ContextCapsuleVerification
+): string => {
+  const lines = [
+    "# GNO Context Capsule verification",
+    "",
+    `- Schema: ${receipt.schemaVersion}`,
+    `- Coordinate space: ${receipt.coordinateSpace}`,
+    `- Capsule ID: \`${receipt.capsuleId}\``,
+    `- Operation: ${receipt.operationStatus}`,
+    `- Content: ${receipt.contentStatus} (${receipt.contentCode})`,
+    `- Ranking: ${receipt.rankingStatus} (${receipt.rankingCode})`,
+    `- Fingerprints: ${receipt.fingerprintStatus}`,
+    `- Fingerprint reasons: ${
+      receipt.fingerprintReasons.length > 0
+        ? receipt.fingerprintReasons.join(", ")
+        : "none"
+    }`,
+    `- Index snapshot: ${json(receipt.indexSnapshot)}`,
+    "",
+    "## Current fingerprints",
+    "",
+    ...Object.entries(receipt.currentFingerprints).map(
+      ([name, value]) => `- ${name}: ${nullable(value)}`
+    ),
+    "",
+    "## Evidence",
+    "",
+    ...receipt.evidence.flatMap((item) => [
+      `### \`${item.evidenceId}\``,
+      "",
+      `- URI: \`${item.uri}\``,
+      `- Content: ${item.contentStatus} (${item.contentCode})`,
+      `- Ranking: ${item.rankingStatus} (${item.rankingCode})`,
+      `- Current rank: ${nullable(item.currentRetrievalRank)}`,
+      `- Current source hash: ${nullable(item.currentSourceHash)}`,
+      `- Current mirror hash: ${nullable(item.currentMirrorHash)}`,
+      `- Current passage hash: ${nullable(item.currentPassageHash)}`,
+      "",
+    ]),
+    "## Canonical receipt",
+    "",
+    ...untrustedBlock(
+      "gno-untrusted-receipt-json",
+      JSON.stringify(
+        JSON.parse(canonicalContextCapsuleVerificationJson(receipt)),
+        null,
+        2
+      )
+    ),
+    "",
+  ];
+  return lines.join("\n");
+};

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