@clue-ai/cli 0.0.5 → 0.0.7

package/src/semantic-ci.mjs

@@ -4,8 +4,20 @@ import {
   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")}`;
@@ -68,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) =>
   [
@@ -77,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(",")}]`;
@@ -149,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.",
@@ -199,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.",
@@ -234,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,
   );
@@ -244,9 +309,11 @@ const normalizeReuseDecision = ({ parsed, operationSourceKey }) => {
       reason: "AI reuse decision omitted this changed route.",
     };
   }
-  const normalizedDecision = ["reuse_previous", "regenerate", "needs_review"].includes(
-    decision.decision,
-  )
+  const normalizedDecision = [
+    "reuse_previous",
+    "regenerate",
+    "needs_review",
+  ].includes(decision.decision)
     ? decision.decision
     : "needs_review";
   return {
@@ -263,109 +330,104 @@ const normalizeReuseDecision = ({ parsed, operationSourceKey }) => {
 
 const callAiReuseDecisionProvider = async ({
   request,
+  env,
   apiKey,
   route,
   previousRoute,
   currentHash,
+  generationContract,
+  agentSkills,
 }) => {
-  const response = await fetch(
-    `${request.ai_provider_base_url.replace(/\/+$/, "")}/chat/completions`,
-    {
-      method: "POST",
-      headers: {
-        "content-type": "application/json",
-        authorization: `Bearer ${apiKey}`,
-      },
-      body: JSON.stringify({
-        model: request.ai_model,
-        messages: [
-          {
-            role: "system",
-            content:
-              "You judge whether previous route semantics can be reused from privacy-safe evidence.",
-          },
-          {
-            role: "user",
-            content: buildAiReuseDecisionPrompt({
-              route,
-              previousRoute,
-              currentHash,
-            }),
-          },
-        ],
-        response_format: { type: "json_object" },
-      }),
-    },
-  );
-  if (!response.ok) {
-    return {
-      decision: "needs_review",
-      confidence: 0,
-      reason: `AI reuse decision failed: provider_${response.status}.`,
-    };
-  }
-  const body = await response.json();
-  const content = body?.choices?.[0]?.message?.content;
-  if (typeof content !== "string" || content.trim() === "") {
-    return {
-      decision: "needs_review",
-      confidence: 0,
-      reason: "AI reuse decision returned empty content.",
-    };
-  }
   try {
+    const parsed = await callJsonAiProvider({
+      config: resolveAiProviderConfig({ env, request, apiKey }),
+      system:
+        "You judge whether previous route semantics can be reused from privacy-safe evidence.",
+      user: buildAiReuseDecisionPrompt({
+        route,
+        previousRoute,
+        currentHash,
+        generationContract,
+        agentSkills,
+      }),
+      toolName: "return_reuse_decision",
+      toolDescription:
+        "Return whether the previous route semantics can be reused.",
+      failureMessage: "AI reuse decision failed",
+      emptyMessage: "AI reuse decision returned empty content.",
+    });
     return normalizeReuseDecision({
-      parsed: JSON.parse(content),
+      parsed,
       operationSourceKey: route.operation_source_key,
     });
-  } catch {
+  } catch (error) {
+    const providerStatusMatch =
+      error instanceof Error
+        ? /AI reuse decision failed: (?<status>\d+)/.exec(error.message)
+        : null;
     return {
       decision: "needs_review",
       confidence: 0,
-      reason: "AI reuse decision returned malformed JSON.",
+      reason: providerStatusMatch?.groups?.status
+        ? `AI reuse decision failed: provider_${providerStatusMatch.groups.status}.`
+        : "AI reuse decision returned malformed JSON.",
     };
   }
 };
 
-const requireAiProviderApiKey = (env) => {
-  const apiKey = env.AI_PROVIDER_API_KEY;
-  if (!apiKey) {
-    throw new Error("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, apiKey, routes }) => {
-  const response = await fetch(
-    `${request.ai_provider_base_url.replace(/\/+$/, "")}/chat/completions`,
-    {
-      method: "POST",
-      headers: {
-        "content-type": "application/json",
-        authorization: `Bearer ${apiKey}`,
-      },
-      body: JSON.stringify({
-        model: request.ai_model,
-        messages: [
-          {
-            role: "system",
-            content: "You generate privacy-safe route semantics JSON.",
-          },
-          { role: "user", content: buildAiPrompt(routes) },
-        ],
-        response_format: { type: "json_object" },
-      }),
-    },
-  );
-  if (!response.ok) {
-    throw new Error(`AI provider failed: ${response.status}`);
-  }
-  const body = await response.json();
-  const content = body?.choices?.[0]?.message?.content;
-  if (typeof content !== "string" || content.trim() === "") {
-    throw new Error("AI provider returned empty semantic generation content");
-  }
-  const parsed = JSON.parse(content);
+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, 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]),
   );
@@ -413,14 +475,24 @@ const assertSnapshotRouteCoverage = ({ routes, snapshotRoutes }) => {
   }
 };
 
-const generateAiRoutesPerRoute = async ({ request, apiKey, routes }) => {
+const generateAiRoutesPerRoute = async ({
+  request,
+  env,
+  apiKey,
+  routes,
+  generationContract,
+  agentSkills,
+}) => {
   const aiRoutes = new Map();
   for (const route of routes) {
     try {
       const routeAiRoutes = await callAiProvider({
         request,
+        env,
         apiKey,
         routes: [route],
+        generationContract,
+        agentSkills,
       });
       const aiRoute = routeAiRoutes.get(route.operation_source_key);
       if (aiRoute?.semantics) {
@@ -447,9 +519,18 @@ const generateAiRoutesPerRoute = async ({ request, 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.",
@@ -476,56 +557,62 @@ const buildAiSelectionPrompt = (selectionCandidates) =>
 
 const callAiSelectionProvider = async ({
   request,
+  env,
   apiKey,
   selectionCandidates,
   routeBySelectionKey,
+  generationContract,
+  agentSkills,
 }) => {
   if (selectionCandidates.length === 0) {
     return new Map();
   }
-  assertNoRawCodeStructure(selectionCandidates, "semantic_selection_prompt");
-  const response = await fetch(
-    `${request.ai_provider_base_url.replace(/\/+$/, "")}/chat/completions`,
-    {
-      method: "POST",
-      headers: {
-        "content-type": "application/json",
-        authorization: `Bearer ${apiKey}`,
-      },
-      body: JSON.stringify({
-        model: request.ai_model,
-        messages: [
-          {
-            role: "system",
-            content:
-              "You select adopted semantic values from privacy-safe candidates.",
-          },
-          {
-            role: "user",
-            content: buildAiSelectionPrompt(selectionCandidates),
-          },
-        ],
-        response_format: { type: "json_object" },
-      }),
-    },
-  );
-  if (!response.ok) {
-    throw new Error(`AI selector failed: ${response.status}`);
-  }
-  const body = await response.json();
-  const content = body?.choices?.[0]?.message?.content;
-  if (typeof content !== "string" || content.trim() === "") {
-    throw new Error("AI selector returned empty semantic selection content");
-  }
-  const parsed = JSON.parse(content);
+  assertNoRawCodeStructureForSelectionCandidates(selectionCandidates);
+  const parsed = await callJsonAiProvider({
+    config: resolveAiProviderConfig({ env, request, apiKey }),
+    system: "You select adopted semantic values from privacy-safe candidates.",
+    user: buildAiSelectionPrompt({
+      selectionCandidates,
+      generationContract,
+      agentSkills,
+    }),
+    toolName: "return_semantic_selection",
+    toolDescription:
+      "Return selected semantic values from privacy-safe candidates.",
+    failureMessage: "AI selector failed",
+    emptyMessage: "AI selector returned empty semantic selection content",
+  });
   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 ?? "")
@@ -888,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") {
@@ -907,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, {
@@ -1072,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,
@@ -1638,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 = [];
@@ -1678,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",
@@ -1697,7 +1811,7 @@ const buildSnapshot = ({
       return rebasePreviousRoute({
         previousRoute: plan.previous_route,
         currentRoute: route,
-        semanticSnapshotVersion,
+        semanticSnapshotVersion: provisionalSemanticSnapshotVersion,
         plan,
       });
     }
@@ -1710,31 +1824,28 @@ const buildSnapshot = ({
         ? `changed_route_needs_review: ${plan.semantic_change_reason}`
         : (aiRoute?.confidence_reason ??
           "AI semantics were unavailable for this route.");
-    const baseRoute = !aiRoute?.semantics || plan.origin === "changed_route_needs_review"
-      ? fallbackSemantics(
-          routeWithVersion,
-          unavailableReason,
-          hashScope,
-        )
-      : {
-          operation_source_key: route.operation_source_key,
-          semantic_snapshot_version: semanticSnapshotVersion,
-          method: route.method,
-          path_template: route.path_template,
-          semantics: sanitizeSemantics(aiRoute.semantics, route),
-          layer_evidence: sanitizeLayerEvidence(
-            aiRoute.layer_evidence,
-            route,
-            hashScope,
-          ),
-          confidence_reason: sanitizeText(
-            String(
-              aiRoute.confidence_reason ||
-                "Generated by AI from privacy-safe route evidence.",
+    const baseRoute =
+      !aiRoute?.semantics || plan.origin === "changed_route_needs_review"
+        ? fallbackSemantics(routeWithVersion, unavailableReason, hashScope)
+        : {
+            operation_source_key: route.operation_source_key,
+            semantic_snapshot_version: provisionalSemanticSnapshotVersion,
+            method: route.method,
+            path_template: route.path_template,
+            semantics: sanitizeSemantics(aiRoute.semantics, route),
+            layer_evidence: sanitizeLayerEvidence(
+              aiRoute.layer_evidence,
+              route,
+              hashScope,
             ),
-            route,
-          ),
-        };
+            confidence_reason: sanitizeText(
+              String(
+                aiRoute.confidence_reason ||
+                  "Generated by AI from privacy-safe route evidence.",
+              ),
+              route,
+            ),
+          };
     const assignmentCollections = buildOperationAssignmentCollections({
       route,
       aiRoute,
@@ -1794,7 +1905,20 @@ const buildSnapshot = ({
   );
 
   const uniqueSourceEvidenceRefs = [];
-  addUniqueBy(uniqueSourceEvidenceRefs, sourceEvidenceRefs, (entry) => entry.id);
+  addUniqueBy(
+    uniqueSourceEvidenceRefs,
+    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,
@@ -1803,43 +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) =>
-        [
-          "unchanged_route_reused",
-          "changed_route_semantic_reused",
-        ].includes(route.semantic_origin),
+      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,
@@ -2039,10 +2168,13 @@ const buildRouteEvidencePromptEntry = ({ route, hashScope }) => ({
 
 const classifyRoutesForSnapshot = async ({
   request,
+  env,
   routes,
   previousSnapshot,
   aiProviderApiKey,
   hashScope,
+  generationContract,
+  agentSkills,
 }) => {
   const previousRoutes = previousRouteMap(previousSnapshot);
   const plans = new Map();
@@ -2076,12 +2208,15 @@ const classifyRoutesForSnapshot = async ({
 
     const decision = await callAiReuseDecisionProvider({
       request,
+      env,
       apiKey: aiProviderApiKey,
       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,
@@ -2093,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",
@@ -2158,7 +2308,13 @@ const rebasePreviousRoute = ({
   };
 };
 
-const fieldPathMatchesKeys = ({ fieldPath, routeKeys, profileIds, mappingIds, catalogKeys }) => {
+const fieldPathMatchesKeys = ({
+  fieldPath,
+  routeKeys,
+  profileIds,
+  mappingIds,
+  catalogKeys,
+}) => {
   for (const routeKey of routeKeys) {
     if (fieldPath.startsWith(`routes[${routeKey}]`)) {
       return true;
@@ -2197,7 +2353,9 @@ const reusablePreviousContext = ({ previousSnapshot, reusedRouteKeys }) => {
     ...safeArray(previousSnapshot?.routes)
       .filter((route) => routeKeys.has(route.operation_source_key))
       .flatMap((route) =>
-        safeArray(route.operation_effects).map((effect) => effect.target_object_key),
+        safeArray(route.operation_effects).map(
+          (effect) => effect.target_object_key,
+        ),
       ),
   ]);
   const catalogs = safeArray(previousSnapshot?.target_object_catalog).filter(
@@ -2274,9 +2432,9 @@ const reusablePreviousContext = ({ previousSnapshot, reusedRouteKeys }) => {
       sourceEvidenceIds.add(ref);
     }
   }
-  const sourceEvidenceRefs = safeArray(previousSnapshot?.source_evidence_refs).filter(
-    (entry) => sourceEvidenceIds.has(entry.id),
-  );
+  const sourceEvidenceRefs = safeArray(
+    previousSnapshot?.source_evidence_refs,
+  ).filter((entry) => sourceEvidenceIds.has(entry.id));
   return {
     profiles,
     mappings,
@@ -2384,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")) {
@@ -2396,7 +2580,9 @@ const semanticSnapshotUrl = (baseUrl) => {
 };
 
 const semanticSnapshotLatestUrl = (request) => {
-  const url = new URL(`${semanticSnapshotUrl(request.clue_api_base_url)}/latest`);
+  const url = new URL(
+    `${semanticSnapshotUrl(request.clue_api_base_url)}/latest`,
+  );
   url.searchParams.set("project_key", request.project_key);
   url.searchParams.set("environment", request.environment);
   url.searchParams.set("repository_id", request.repository.repository_id);
@@ -2409,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), {
@@ -2417,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);
@@ -2475,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,
@@ -2494,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 })
@@ -2503,37 +2784,69 @@ export const runSemanticCi = async ({
     const previousRoute = previousRoutes.get(route.operation_source_key);
     return !previousRoute || previousRoute.route_input_hash !== routeInputHash(route);
   });
-  const aiProviderApiKey = routeNeedsAi ? requireAiProviderApiKey(env) : null;
-  const { plans: routePlans, routesRequiringGeneration, deletedRouteCount } =
-    await classifyRoutesForSnapshot({
-      request,
-      routes,
-      previousSnapshot,
-      aiProviderApiKey,
-      hashScope,
-    });
+  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,
+    deletedRouteCount,
+  } = await classifyRoutesForSnapshot({
+    request,
+    env,
+    routes,
+    previousSnapshot,
+    aiProviderApiKey: aiProviderConfig?.apiKey ?? null,
+    hashScope,
+    generationContract,
+    agentSkills,
+  });
   const promptRoutes = routesRequiringGeneration.map((route) =>
     buildRouteEvidencePromptEntry({ route, hashScope }),
   );
   const aiRoutes = await generateAiRoutesPerRoute({
     request,
-    apiKey: aiProviderApiKey,
+    env,
+    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,
-          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,
@@ -2542,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 {