@clue-ai/cli 0.0.6 → 0.0.8

package/src/semantic-ci.mjs

@@ -1,12 +1,23 @@
 import { createHash, createHmac } from "node:crypto";
-import { callJsonAiProvider, resolveAiProviderConfig } from "./ai-provider.mjs";
 import {
   validateSemanticCiRequest,
   validateSemanticSnapshotRequest,
   validateSemanticSnapshotResponse,
 } from "./contracts.mjs";
+import {
+  callJsonAiProvider,
+  resolveAiProviderConfig,
+} from "./ai-provider.mjs";
 import { analyzeFastApiRoutes } from "./fastapi-analyzer.mjs";
 import { listAllowedPythonFiles } from "./path-policy.mjs";
+import {
+  SEMANTIC_AGENT_ROLE_IDS,
+  SEMANTIC_AGENT_RUNNER_VERSION,
+  semanticAgentPromptEnvelope,
+  semanticAgentSkillBundle,
+  validateSemanticAgentSkillBundle,
+} from "./semantic-agent-runner.mjs";
+import { clueClientCiSemanticAiRuntime } from "./semantic-ai-config.mjs";
 
 const sha256 = (value) =>
   `sha256:${createHash("sha256").update(value).digest("hex")}`;
@@ -69,6 +80,12 @@ const ACTUAL_OUTCOME_ACTIONS = new Set([
 ]);
 
 const snakeSegmentPattern = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/;
+const SEMANTIC_SNAPSHOT_SCHEMA_VERSION = 2;
+const SEMANTIC_ANALYZER_VERSION = "fastapi-route-analyzer-v1";
+const SEMANTIC_ROUTE_PROMPT_CONTRACT_VERSION = "route-semantics-v1";
+const SEMANTIC_REUSE_PROMPT_CONTRACT_VERSION = "route-reuse-v1";
+const SEMANTIC_SELECTOR_PROMPT_CONTRACT_VERSION = "semantic-selector-v1";
+const SEMANTIC_PRIVACY_SANITIZER_VERSION = "privacy-sanitizer-v1";
 
 const semanticSnapshotHashScope = (request) =>
   [
@@ -78,6 +95,15 @@ const semanticSnapshotHashScope = (request) =>
     request.service.service_key,
   ].join(":");
 
+const semanticGenerationContract = () => ({
+  schema_version: SEMANTIC_SNAPSHOT_SCHEMA_VERSION,
+  analyzer_version: SEMANTIC_ANALYZER_VERSION,
+  route_prompt_contract_version: SEMANTIC_ROUTE_PROMPT_CONTRACT_VERSION,
+  reuse_prompt_contract_version: SEMANTIC_REUSE_PROMPT_CONTRACT_VERSION,
+  selector_prompt_contract_version: SEMANTIC_SELECTOR_PROMPT_CONTRACT_VERSION,
+  privacy_sanitizer_version: SEMANTIC_PRIVACY_SANITIZER_VERSION,
+});
+
 const canonicalJson = (value) => {
   if (Array.isArray(value)) {
     return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
@@ -150,9 +176,14 @@ const fallbackSemantics = (route, reason, hashScope) => ({
   confidence_reason: reason,
 });
 
-const buildAiPrompt = (routes) =>
+const buildAiPrompt = ({ routes, generationContract, agentSkills }) =>
   JSON.stringify({
+    ...semanticAgentPromptEnvelope({
+      bundle: agentSkills,
+      roleId: SEMANTIC_AGENT_ROLE_IDS.routeSemanticGenerator,
+    }),
     task: "Generate privacy-safe semantic meaning candidates for FastAPI operation sources. Return JSON only.",
+    generation_contract: generationContract,
     rules: [
       "Do not create operation_source_key values; only copy the provided keys.",
       "Do not create ids, refs, hashes, source fingerprints, or field paths.",
@@ -200,9 +231,20 @@ const buildAiPrompt = (routes) =>
     })),
   });
 
-const buildAiReuseDecisionPrompt = ({ route, previousRoute, currentHash }) =>
+const buildAiReuseDecisionPrompt = ({
+  route,
+  previousRoute,
+  currentHash,
+  generationContract,
+  agentSkills,
+}) =>
   JSON.stringify({
+    ...semanticAgentPromptEnvelope({
+      bundle: agentSkills,
+      roleId: SEMANTIC_AGENT_ROLE_IDS.reuseJudge,
+    }),
     task: "Decide whether previous privacy-safe route semantics still apply after a route source change. Return JSON only.",
+    generation_contract: generationContract,
     rules: [
       "Only decide for the provided operation_source_key.",
       "Return decision as reuse_previous, regenerate, or needs_review.",
@@ -235,6 +277,28 @@ const buildAiReuseDecisionPrompt = ({ route, previousRoute, currentHash }) =>
   });
 
 const normalizeReuseDecision = ({ parsed, operationSourceKey }) => {
+  if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.decisions)) {
+    return {
+      decision: "needs_review",
+      confidence: 0,
+      reason: "AI reuse decision did not return the required decisions array.",
+    };
+  }
+  const unknownDecision = parsed.decisions.find(
+    (entry) =>
+      !entry ||
+      typeof entry !== "object" ||
+      typeof entry.operation_source_key !== "string" ||
+      (entry.operation_source_key !== operationSourceKey &&
+        entry.operation_source_key.trim() !== ""),
+  );
+  if (unknownDecision) {
+    return {
+      decision: "needs_review",
+      confidence: 0,
+      reason: "AI reuse decision returned an unexpected route key.",
+    };
+  }
   const decision = safeArray(parsed?.decisions).find(
     (entry) => entry?.operation_source_key === operationSourceKey,
   );
@@ -271,6 +335,8 @@ const callAiReuseDecisionProvider = async ({
   route,
   previousRoute,
   currentHash,
+  generationContract,
+  agentSkills,
 }) => {
   try {
     const parsed = await callJsonAiProvider({
@@ -281,6 +347,8 @@ const callAiReuseDecisionProvider = async ({
         route,
         previousRoute,
         currentHash,
+        generationContract,
+        agentSkills,
       }),
       toolName: "return_reuse_decision",
       toolDescription:
@@ -307,26 +375,59 @@ const callAiReuseDecisionProvider = async ({
   }
 };
 
-const requireAiProviderApiKey = (env) => {
-  const apiKey = env.CLUE_AI_PROVIDER_API_KEY;
-  if (!apiKey) {
-    throw new Error(
-      "CLUE_AI_PROVIDER_API_KEY is required for semantic generation",
-    );
+const assertAiRouteResponseContract = ({ parsed, expectedRouteKeys }) => {
+  if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.routes)) {
+    throw new SyntaxError("AI route semantics response must include routes");
+  }
+  const expected = new Set(expectedRouteKeys);
+  const actual = new Set();
+  for (const route of parsed.routes) {
+    if (!route || typeof route !== "object") {
+      throw new SyntaxError("AI route semantics response includes invalid route");
+    }
+    if (
+      typeof route.operation_source_key !== "string" ||
+      !expected.has(route.operation_source_key)
+    ) {
+      throw new SyntaxError(
+        "AI route semantics response included an unexpected route key",
+      );
+    }
+    if (actual.has(route.operation_source_key)) {
+      throw new SyntaxError(
+        "AI route semantics response included a duplicate route key",
+      );
+    }
+    actual.add(route.operation_source_key);
+    if (!route.semantics || typeof route.semantics !== "object") {
+      throw new SyntaxError(
+        "AI route semantics response omitted required semantics",
+      );
+    }
   }
-  return apiKey;
 };
 
-const callAiProvider = async ({ request, env, apiKey, routes }) => {
+const callAiProvider = async ({
+  request,
+  env,
+  apiKey,
+  routes,
+  generationContract,
+  agentSkills,
+}) => {
   const parsed = await callJsonAiProvider({
     config: resolveAiProviderConfig({ env, request, apiKey }),
     system: "You generate privacy-safe route semantics JSON.",
-    user: buildAiPrompt(routes),
+    user: buildAiPrompt({ routes, generationContract, agentSkills }),
     toolName: "return_route_semantics",
     toolDescription: "Return privacy-safe route semantics JSON.",
     failureMessage: "AI provider failed",
     emptyMessage: "AI provider returned empty semantic generation content",
   });
+  assertAiRouteResponseContract({
+    parsed,
+    expectedRouteKeys: routes.map((route) => route.operation_source_key),
+  });
   return new Map(
     (parsed.routes ?? []).map((route) => [route.operation_source_key, route]),
   );
@@ -374,7 +475,14 @@ const assertSnapshotRouteCoverage = ({ routes, snapshotRoutes }) => {
   }
 };
 
-const generateAiRoutesPerRoute = async ({ request, env, apiKey, routes }) => {
+const generateAiRoutesPerRoute = async ({
+  request,
+  env,
+  apiKey,
+  routes,
+  generationContract,
+  agentSkills,
+}) => {
   const aiRoutes = new Map();
   for (const route of routes) {
     try {
@@ -383,6 +491,8 @@ const generateAiRoutesPerRoute = async ({ request, env, apiKey, routes }) => {
         env,
         apiKey,
         routes: [route],
+        generationContract,
+        agentSkills,
       });
       const aiRoute = routeAiRoutes.get(route.operation_source_key);
       if (aiRoute?.semantics) {
@@ -409,9 +519,18 @@ const generateAiRoutesPerRoute = async ({ request, env, apiKey, routes }) => {
   return aiRoutes;
 };
 
-const buildAiSelectionPrompt = (selectionCandidates) =>
+const buildAiSelectionPrompt = ({
+  selectionCandidates,
+  generationContract,
+  agentSkills,
+}) =>
   JSON.stringify({
+    ...semanticAgentPromptEnvelope({
+      bundle: agentSkills,
+      roleId: SEMANTIC_AGENT_ROLE_IDS.semanticSelector,
+    }),
     task: "Choose adopted semantic values from deterministic and AI candidates. Return JSON only.",
+    generation_contract: generationContract,
     rules: [
       "Only copy operation_source_key, candidate_index, and parameter_name values from the provided selection_candidates.",
       "For each semantic field, return selected_source as deterministic or ai.",
@@ -442,15 +561,21 @@ const callAiSelectionProvider = async ({
   apiKey,
   selectionCandidates,
   routeBySelectionKey,
+  generationContract,
+  agentSkills,
 }) => {
   if (selectionCandidates.length === 0) {
     return new Map();
   }
-  assertNoRawCodeStructure(selectionCandidates, "semantic_selection_prompt");
+  assertNoRawCodeStructureForSelectionCandidates(selectionCandidates);
   const parsed = await callJsonAiProvider({
     config: resolveAiProviderConfig({ env, request, apiKey }),
     system: "You select adopted semantic values from privacy-safe candidates.",
-    user: buildAiSelectionPrompt(selectionCandidates),
+    user: buildAiSelectionPrompt({
+      selectionCandidates,
+      generationContract,
+      agentSkills,
+    }),
     toolName: "return_semantic_selection",
     toolDescription:
       "Return selected semantic values from privacy-safe candidates.",
@@ -460,11 +585,34 @@ const callAiSelectionProvider = async ({
   return normalizeAiSelectionResponse({
     parsed,
     routeBySelectionKey,
+    validSelectionParametersByKey: validSelectionParametersByKey(
+      selectionCandidates,
+    ),
   });
 };
 
-const buildSemanticSnapshotVersion = ({ request, generatedAt }) =>
-  `snap_${shortHash(`${request.project_key}:${request.repository.repository_id}:${request.repository.merge_commit}:${request.repository.workflow_run_id ?? generatedAt}`)}`;
+const buildSemanticSnapshotVersion = ({
+  request,
+  generationContract,
+  snapshotRoutes,
+}) =>
+  `snap_${shortHash(
+    canonicalJson({
+      project_key: request.project_key,
+      repository_id: request.repository.repository_id,
+      service_key: request.service.service_key,
+      generation_contract: generationContract,
+      routes: snapshotRoutes
+        .map((route) => ({
+          operation_source_key: route.operation_source_key,
+          route_input_hash: route.route_input_hash,
+          route_semantic_hash: route.route_semantic_hash,
+        }))
+        .sort((left, right) =>
+          left.operation_source_key.localeCompare(right.operation_source_key),
+        ),
+    }),
+  )}`;
 
 const normalizeSnakeSegment = (value) => {
   const normalized = String(value ?? "")
@@ -827,7 +975,30 @@ const candidateHasUnsafeSemanticText = (candidate) =>
 const selectionKeyForCandidate = (route, candidateIndex) =>
   `${route.operation_source_key}#${candidateIndex}`;
 
-const normalizeAiSelectionResponse = ({ parsed, routeBySelectionKey }) => {
+const validSelectionParametersByKey = (selectionCandidates) =>
+  new Map(
+    selectionCandidates.map((candidate) => [
+      selectionKeyForCandidate(candidate, candidate.candidate_index),
+      new Set(
+        safeArray(candidate.semantic_fields)
+          .map((field) => field?.parameter_name)
+          .filter((parameterName) => typeof parameterName === "string"),
+      ),
+    ]),
+  );
+
+const normalizeAiSelectionResponse = ({
+  parsed,
+  routeBySelectionKey,
+  validSelectionParametersByKey,
+}) => {
+  if (
+    !parsed ||
+    typeof parsed !== "object" ||
+    !Array.isArray(parsed.field_selections)
+  ) {
+    throw new SyntaxError("AI selector response must include field_selections");
+  }
   const decisionsByCandidate = new Map();
   for (const decision of safeArray(parsed?.field_selections)) {
     if (!decision || typeof decision !== "object") {
@@ -846,6 +1017,10 @@ const normalizeAiSelectionResponse = ({ parsed, routeBySelectionKey }) => {
     if (!route) {
       continue;
     }
+    const validParameters = validSelectionParametersByKey.get(selectionKey);
+    if (!validParameters?.has(decision.parameter_name)) {
+      continue;
+    }
     const candidateDecisions =
       decisionsByCandidate.get(selectionKey) ?? new Map();
     candidateDecisions.set(decision.parameter_name, {
@@ -1011,7 +1186,8 @@ const buildSelectorCandidates = ({ routes, aiRoutes, hashScope }) => {
         candidateHasUnsafeSemanticText(candidate) ||
         !values.rawTargetObjectText ||
         !values.targetKeyCandidate ||
-        !values.aiExpectedDomainEffect ||
+        (!values.aiExpectedDomainEffect &&
+          !values.deterministicExpectedDomainEffect) ||
         !hasBehaviorEvidence(values.sourceEvidenceRefs, routeEvidenceRefs) ||
         !candidateHasTargetSpecificEvidence({
           route,
@@ -1577,13 +1753,12 @@ const buildSnapshot = ({
   routePlans = new Map(),
   previousSnapshot,
   deletedRouteCount = 0,
+  generationContract,
+  aiRuntime,
 }) => {
   const generatedAt = new Date().toISOString();
   const hashScope = semanticSnapshotHashScope(request);
-  const semanticSnapshotVersion = buildSemanticSnapshotVersion({
-    request,
-    generatedAt,
-  });
+  const provisionalSemanticSnapshotVersion = "snap_pending";
   const targetObjectProfiles = [];
   const targetObjectMappings = [];
   const sourceEvidenceRefs = [];
@@ -1617,7 +1792,7 @@ const buildSnapshot = ({
   const snapshotRoutes = routes.map((route) => {
     const routeWithVersion = {
       ...route,
-      semantic_snapshot_version: semanticSnapshotVersion,
+      semantic_snapshot_version: provisionalSemanticSnapshotVersion,
     };
     const plan = routePlans.get(route.operation_source_key) ?? {
       origin: "new_route_ai_generated",
@@ -1636,7 +1811,7 @@ const buildSnapshot = ({
       return rebasePreviousRoute({
         previousRoute: plan.previous_route,
         currentRoute: route,
-        semanticSnapshotVersion,
+        semanticSnapshotVersion: provisionalSemanticSnapshotVersion,
         plan,
       });
     }
@@ -1654,7 +1829,7 @@ const buildSnapshot = ({
         ? fallbackSemantics(routeWithVersion, unavailableReason, hashScope)
         : {
             operation_source_key: route.operation_source_key,
-            semantic_snapshot_version: semanticSnapshotVersion,
+            semantic_snapshot_version: provisionalSemanticSnapshotVersion,
             method: route.method,
             path_template: route.path_template,
             semantics: sanitizeSemantics(aiRoute.semantics, route),
@@ -1735,6 +1910,15 @@ const buildSnapshot = ({
     sourceEvidenceRefs,
     (entry) => entry.id,
   );
+  const semanticSnapshotVersion = buildSemanticSnapshotVersion({
+    request,
+    generationContract,
+    snapshotRoutes,
+  });
+  const versionedSnapshotRoutes = snapshotRoutes.map((route) => ({
+    ...route,
+    semantic_snapshot_version: semanticSnapshotVersion,
+  }));
 
   const snapshot = validateSemanticSnapshotRequest({
     project_key: request.project_key,
@@ -1743,42 +1927,48 @@ const buildSnapshot = ({
     ),
     schema_version: 2,
     semantic_snapshot_version: semanticSnapshotVersion,
+    generation_contract: generationContract,
+    ai_runtime: aiRuntime,
     generated_at: generatedAt,
     repository: request.repository,
-    service: request.service,
+    service: {
+      service_key: request.service.service_key,
+      framework: request.service.framework,
+      language: request.service.language,
+    },
     analysis_summary: {
       total_routes_scanned: routes.length,
-      routes_generated: snapshotRoutes.filter(
+      routes_generated: versionedSnapshotRoutes.filter(
         (route) => route.semantics.route_confidence > 0,
       ).length,
-      uncertain_routes: snapshotRoutes.filter(
+      uncertain_routes: versionedSnapshotRoutes.filter(
         (route) => route.semantics.route_confidence < 0.5,
       ).length,
       failed_routes: failedRouteCount,
-      routes_reused: snapshotRoutes.filter((route) =>
+      routes_reused: versionedSnapshotRoutes.filter((route) =>
         ["unchanged_route_reused", "changed_route_semantic_reused"].includes(
           route.semantic_origin,
         ),
       ).length,
-      routes_ai_generated: snapshotRoutes.filter((route) =>
+      routes_ai_generated: versionedSnapshotRoutes.filter((route) =>
         [
           "new_route_ai_generated",
           "changed_route_semantic_regenerated",
         ].includes(route.semantic_origin),
       ).length,
       routes_deleted: deletedRouteCount,
-      routes_needs_review: snapshotRoutes.filter(
+      routes_needs_review: versionedSnapshotRoutes.filter(
         (route) => route.semantic_origin === "changed_route_needs_review",
       ).length,
-      changed_routes_semantic_reused: snapshotRoutes.filter(
+      changed_routes_semantic_reused: versionedSnapshotRoutes.filter(
         (route) => route.semantic_origin === "changed_route_semantic_reused",
       ).length,
-      changed_routes_semantic_regenerated: snapshotRoutes.filter(
+      changed_routes_semantic_regenerated: versionedSnapshotRoutes.filter(
         (route) =>
           route.semantic_origin === "changed_route_semantic_regenerated",
       ).length,
     },
-    routes: snapshotRoutes,
+    routes: versionedSnapshotRoutes,
     target_object_profiles: targetObjectProfiles,
     target_object_catalog: [...catalogByGroup.values()],
     target_object_mappings: targetObjectMappings,
@@ -1983,6 +2173,8 @@ const classifyRoutesForSnapshot = async ({
   previousSnapshot,
   aiProviderApiKey,
   hashScope,
+  generationContract,
+  agentSkills,
 }) => {
   const previousRoutes = previousRouteMap(previousSnapshot);
   const plans = new Map();
@@ -2021,8 +2213,10 @@ const classifyRoutesForSnapshot = async ({
       route: buildRouteEvidencePromptEntry({ route, hashScope }),
       previousRoute,
       currentHash,
+      generationContract,
+      agentSkills,
     });
-    if (decision.decision === "reuse_previous") {
+    if (decision.decision === "reuse_previous" && decision.confidence >= 0.75) {
       plans.set(route.operation_source_key, {
         origin: "changed_route_semantic_reused",
         route_input_hash: currentHash,
@@ -2034,6 +2228,21 @@ const classifyRoutesForSnapshot = async ({
       });
       continue;
     }
+    if (decision.decision === "reuse_previous") {
+      plans.set(route.operation_source_key, {
+        origin: "changed_route_needs_review",
+        route_input_hash: currentHash,
+        previous_route: previousRoute,
+        previous_route_input_hash: previousRoute.route_input_hash,
+        previous_route_semantic_hash:
+          previousRoute.route_semantic_hash ?? routeSemanticHash(previousRoute),
+        semantic_change_reason: sanitizeText(
+          `AI reuse decision confidence was too low for automatic reuse: ${decision.reason}`,
+          route,
+        ),
+      });
+      continue;
+    }
     if (decision.decision === "regenerate") {
       plans.set(route.operation_source_key, {
         origin: "changed_route_semantic_regenerated",
@@ -2333,6 +2542,32 @@ const assertNoRawCodeStructure = (value, path = "snapshot") => {
   }
 };
 
+const assertNoRawCodeStructureForSelectionCandidates = (
+  selectionCandidates,
+) => {
+  for (const candidate of selectionCandidates) {
+    safeArray(candidate.evidence_summaries).forEach((entry, index) => {
+      assertNoRawCodeStructure(
+        {
+          kind: entry?.kind,
+          summary: entry?.summary,
+          evidence_strength: entry?.evidence_strength,
+        },
+        `semantic_selection_prompt[${index}].evidence_summaries`,
+      );
+    });
+    safeArray(candidate.semantic_fields).forEach((field, index) => {
+      assertNoRawCodeStructure(
+        {
+          deterministic_candidate: field?.deterministic_candidate,
+          ai_candidate: field?.ai_candidate,
+        },
+        `semantic_selection_prompt[${index}].semantic_fields`,
+      );
+    });
+  }
+};
+
 const semanticSnapshotUrl = (baseUrl) => {
   const normalized = baseUrl.replace(/\/+$/, "");
   if (normalized.endsWith("/api/v1/semantic-snapshots")) {
@@ -2360,6 +2595,8 @@ const fetchLatestSnapshot = async ({ request, env }) => {
   if (!apiKey) {
     return null;
   }
+  const allowFullRegeneration =
+    env.CLUE_SEMANTIC_ALLOW_FULL_REGEN_WITHOUT_CACHE === "1";
   let response;
   try {
     response = await fetch(semanticSnapshotLatestUrl(request), {
@@ -2368,19 +2605,34 @@ const fetchLatestSnapshot = async ({ request, env }) => {
         authorization: `Bearer ${apiKey}`,
       },
     });
-  } catch {
-    return null;
+  } catch (error) {
+    if (allowFullRegeneration) {
+      return null;
+    }
+    throw new Error(
+      `previous semantic snapshot lookup failed: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
   }
   if (response.status === 404 || response.status === 204) {
     return null;
   }
   if (!response.ok) {
-    return null;
+    if (allowFullRegeneration) {
+      return null;
+    }
+    throw new Error(
+      `previous semantic snapshot lookup failed: ${response.status}`,
+    );
   }
   const body = await response.json();
   const candidate = body?.snapshot ?? body;
   if (!candidate || !Array.isArray(candidate.routes)) {
-    return null;
+    if (allowFullRegeneration) {
+      return null;
+    }
+    throw new Error("previous semantic snapshot lookup returned invalid body");
   }
   const parsed = validateSemanticSnapshotRequest(candidate);
   assertNoRawCodeStructure(parsed);
@@ -2426,14 +2678,89 @@ const sendSnapshot = async ({ request, env, snapshot }) => {
   }
 };
 
+const assertSemanticSnapshotAudit = ({
+  routes,
+  snapshot,
+  generationContract,
+  aiRuntime,
+}) => {
+  const auditedSnapshot = validateSemanticSnapshotRequest(snapshot);
+  assertSnapshotRouteCoverage({ routes, snapshotRoutes: auditedSnapshot.routes });
+  assertNoRawCodeStructure(auditedSnapshot);
+  if (canonicalJson(auditedSnapshot.generation_contract) !== canonicalJson(generationContract)) {
+    throw new Error("semantic snapshot generation contract mismatch");
+  }
+  if (canonicalJson(auditedSnapshot.ai_runtime) !== canonicalJson(aiRuntime)) {
+    throw new Error("semantic snapshot AI runtime metadata mismatch");
+  }
+  const routeByKey = new Map(
+    routes.map((route) => [route.operation_source_key, route]),
+  );
+  const allowedOrigins = new Set([
+    "new_route_ai_generated",
+    "unchanged_route_reused",
+    "changed_route_semantic_reused",
+    "changed_route_semantic_regenerated",
+    "changed_route_needs_review",
+  ]);
+  for (const route of auditedSnapshot.routes) {
+    const currentRoute = routeByKey.get(route.operation_source_key);
+    if (!currentRoute) {
+      throw new Error(
+        `semantic snapshot audit found unknown route: ${route.operation_source_key}`,
+      );
+    }
+    const expectedInputHash = routeInputHash(currentRoute);
+    if (route.route_input_hash !== expectedInputHash) {
+      throw new Error(
+        `semantic snapshot audit found stale route_input_hash: ${route.operation_source_key}`,
+      );
+    }
+    if (!allowedOrigins.has(route.semantic_origin)) {
+      throw new Error(
+        `semantic snapshot audit found invalid semantic_origin: ${route.operation_source_key}`,
+      );
+    }
+    if (route.route_semantic_hash !== routeSemanticHash(route)) {
+      throw new Error(
+        `semantic snapshot audit found stale route_semantic_hash: ${route.operation_source_key}`,
+      );
+    }
+    if (
+      (route.semantic_origin === "unchanged_route_reused" ||
+        route.semantic_origin === "changed_route_semantic_reused") &&
+      (!route.previous_route_input_hash ||
+        !route.previous_route_semantic_hash ||
+        !route.previous_semantic_snapshot_version)
+    ) {
+      throw new Error(
+        `semantic snapshot audit found incomplete reuse metadata: ${route.operation_source_key}`,
+      );
+    }
+    if (
+      route.semantic_origin === "changed_route_needs_review" &&
+      !route.semantic_change_reason
+    ) {
+      throw new Error(
+        `semantic snapshot audit found missing review reason: ${route.operation_source_key}`,
+      );
+    }
+  }
+};
+
 export const runSemanticCi = async ({
   repoRoot,
   request: rawRequest,
   env,
   previousSnapshot: providedPreviousSnapshot,
+  agentSkills: rawAgentSkills,
 }) => {
   const request = validateSemanticCiRequest(rawRequest);
   const hashScope = semanticSnapshotHashScope(request);
+  const generationContract = semanticGenerationContract();
+  const agentSkills = validateSemanticAgentSkillBundle(
+    rawAgentSkills ?? semanticAgentSkillBundle(),
+  );
   const files = await listAllowedPythonFiles({
     repoRoot,
     allowedSourcePaths: request.allowed_source_paths,
@@ -2445,6 +2772,9 @@ export const runSemanticCi = async ({
       "semantic CI discovered zero routes; check framework, backend root path, and allowed_source_paths",
     );
   }
+  if (!env.CLUE_API_KEY) {
+    throw new Error("CLUE_API_KEY is required");
+  }
   const previousSnapshot =
     providedPreviousSnapshot === undefined
       ? await fetchLatestSnapshot({ request, env })
@@ -2452,11 +2782,25 @@ export const runSemanticCi = async ({
   const previousRoutes = previousRouteMap(previousSnapshot);
   const routeNeedsAi = routes.some((route) => {
     const previousRoute = previousRoutes.get(route.operation_source_key);
-    return (
-      !previousRoute || previousRoute.route_input_hash !== routeInputHash(route)
-    );
+    return !previousRoute || previousRoute.route_input_hash !== routeInputHash(route);
   });
-  const aiProviderApiKey = routeNeedsAi ? requireAiProviderApiKey(env) : null;
+  if (routeNeedsAi && !env.CLUE_AI_PROVIDER_API_KEY) {
+    throw new Error("CLUE_AI_PROVIDER_API_KEY is required for semantic generation");
+  }
+  const aiProviderConfig = routeNeedsAi
+    ? resolveAiProviderConfig({ env, request })
+    : null;
+  const aiRuntime =
+    aiProviderConfig === null && previousSnapshot?.ai_runtime
+      ? previousSnapshot.ai_runtime
+      : clueClientCiSemanticAiRuntime({
+          provider: aiProviderConfig?.provider ?? "not_used",
+          model: aiProviderConfig?.model ?? "not_used",
+          roleIds: SEMANTIC_AGENT_ROLE_IDS
+            ? Object.values(SEMANTIC_AGENT_ROLE_IDS)
+            : [],
+          runnerVersion: SEMANTIC_AGENT_RUNNER_VERSION,
+        });
   const {
     plans: routePlans,
     routesRequiringGeneration,
@@ -2466,8 +2810,10 @@ export const runSemanticCi = async ({
     env,
     routes,
     previousSnapshot,
-    aiProviderApiKey,
+    aiProviderApiKey: aiProviderConfig?.apiKey ?? null,
     hashScope,
+    generationContract,
+    agentSkills,
   });
   const promptRoutes = routesRequiringGeneration.map((route) =>
     buildRouteEvidencePromptEntry({ route, hashScope }),
@@ -2475,24 +2821,32 @@ export const runSemanticCi = async ({
   const aiRoutes = await generateAiRoutesPerRoute({
     request,
     env,
-    apiKey: aiProviderApiKey,
+    apiKey: aiProviderConfig?.apiKey ?? null,
     routes: promptRoutes,
+    generationContract,
+    agentSkills,
   });
   const { selectionCandidates, routeBySelectionKey } = buildSelectorCandidates({
     routes: routesRequiringGeneration,
     aiRoutes,
     hashScope,
   });
-  const aiSelectionDecisions =
-    selectionCandidates.length === 0
-      ? new Map()
-      : await callAiSelectionProvider({
-          request,
-          env,
-          apiKey: aiProviderApiKey,
-          selectionCandidates,
-          routeBySelectionKey,
-        });
+  let aiSelectionDecisions = new Map();
+  if (selectionCandidates.length > 0) {
+    try {
+      aiSelectionDecisions = await callAiSelectionProvider({
+        request,
+        env,
+        apiKey: aiProviderConfig?.apiKey ?? null,
+        selectionCandidates,
+        routeBySelectionKey,
+        generationContract,
+        agentSkills,
+      });
+    } catch {
+      aiSelectionDecisions = new Map();
+    }
+  }
   const snapshot = buildSnapshot({
     request,
     routes,
@@ -2501,6 +2855,14 @@ export const runSemanticCi = async ({
     routePlans,
     previousSnapshot,
     deletedRouteCount,
+    generationContract,
+    aiRuntime,
+  });
+  assertSemanticSnapshotAudit({
+    routes,
+    snapshot,
+    generationContract,
+    aiRuntime,
   });
   const upload = await sendSnapshot({ request, env, snapshot });
   return {