@clue-ai/cli 0.0.3

package/src/semantic-ci.mjs

@@ -0,0 +1,1830 @@
+import { createHash, createHmac } from "node:crypto";
+import {
+  validateSemanticCiRequest,
+  validateSemanticSnapshotRequest,
+} from "./contracts.mjs";
+import { analyzeFastApiRoutes } from "./fastapi-analyzer.mjs";
+import { listAllowedPythonFiles } from "./path-policy.mjs";
+
+const sha256 = (value) =>
+  `sha256:${createHash("sha256").update(value).digest("hex")}`;
+const hmacSha256 = (key, value) =>
+  `sha256:${createHmac("sha256", key).update(value).digest("hex")}`;
+const shortHash = (value) =>
+  createHash("sha256").update(value).digest("hex").slice(0, 12);
+
+const EFFECT_KIND_VALUES = new Set([
+  "data_create",
+  "data_update",
+  "data_delete",
+  "data_upsert",
+  "data_read",
+  "data_query",
+  "data_import",
+  "data_export",
+  "state_transition",
+  "validation_check",
+  "access_check",
+  "communication_send",
+  "audit_record",
+  "event_emit",
+  "background_task_schedule",
+  "external_service_call",
+  "payment_operation",
+  "ai_inference",
+  "file_process",
+  "cache_change",
+  "system_config_change",
+  "unknown",
+]);
+
+const RESOLUTION_BASIS_VALUES = new Set([
+  "route_contract",
+  "direct_data_mutation",
+  "repository_call",
+  "orm_model_call",
+  "sql_statement",
+  "read_query",
+  "external_sdk_call",
+  "message_publish",
+  "job_enqueue",
+  "file_operation",
+  "validation_logic",
+  "access_control_logic",
+  "ai_inferred_code_behavior",
+  "explicit_semantic_config",
+  "unknown",
+]);
+
+const SELECTED_SOURCE_VALUES = new Set(["deterministic", "ai"]);
+
+const ACTUAL_OUTCOME_ACTIONS = new Set([
+  "completed",
+  "failed",
+  "validation_error",
+  "blocked",
+  "abandoned",
+]);
+
+const snakeSegmentPattern = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/;
+
+const semanticSnapshotHashScope = (request) =>
+  [
+    "clue_tools_semantic_snapshot",
+    request.project_key,
+    request.repository.repository_id,
+    request.repository.merge_commit,
+    request.repository.workflow_run_id ?? "no_workflow_run",
+  ].join(":");
+
+const opaqueRouteHash = (route, purpose, hashScope) =>
+  hmacSha256(
+    hashScope,
+    [purpose, route.operation_source_key, route.source.source_fingerprint].join(
+      ":",
+    ),
+  );
+
+const fallbackSemantics = (route, reason, hashScope) => ({
+  operation_source_key: route.operation_source_key,
+  semantic_snapshot_version: route.semantic_snapshot_version,
+  method: route.method,
+  path_template: route.path_template,
+  semantics: {
+    route_summary: "unknown",
+    action_candidates: [],
+    outcome_candidates: [],
+    value_event_candidates: [],
+    route_confidence: 0,
+  },
+  layer_evidence: {
+    data_effects: [],
+    side_effects: [],
+    failure_surfaces: ["unknown"],
+    validation_field_paths: [],
+    permission_scopes: [],
+    component_fingerprints: [
+      opaqueRouteHash(route, "route_contract_component", hashScope),
+      opaqueRouteHash(route, "abstract_behavior_component", hashScope),
+      opaqueRouteHash(route, "source_component", hashScope),
+    ],
+  },
+  operation_effects: [],
+  unresolved_operation_effects: [],
+  source_evidence_refs: [],
+  confidence_reason: reason,
+});
+
+const buildAiPrompt = (routes) =>
+  JSON.stringify({
+    task: "Generate privacy-safe semantic meaning candidates for FastAPI operation sources. Return JSON only.",
+    rules: [
+      "Do not create operation_source_key values; only copy the provided keys.",
+      "Do not create ids, refs, hashes, source fingerprints, or field paths.",
+      "Do not include raw source code, raw SQL, file paths, function names, class names, prompts, or completions in the output.",
+      "Use the provided privacy-safe evidence summaries only.",
+      "Return operation_effect_candidates only when source evidence supports a schema-valid target object and effect action.",
+      "Keep multiple effects separate when one route produces multiple meaningful effects.",
+      "Do not encode actual outcomes such as completed, failed, blocked, validation_error, or abandoned into operation_effect_key or expected_domain_effect.",
+    ],
+    output_shape: {
+      routes: [
+        {
+          operation_source_key: "route.POST./reports",
+          semantics: {
+            route_summary: "creates report-related business records",
+            action_candidates: [],
+            outcome_candidates: [],
+            route_confidence: 0.8,
+          },
+          confidence_reason:
+            "Privacy-safe source evidence supports the route meaning.",
+          operation_effect_candidates: [
+            {
+              raw_target_object_text: "Reports",
+              concept: "business record produced in the service",
+              business_role: "core record users create and review",
+              effect_kind: "data_create",
+              effect_action: "create",
+              resolution_basis: "route_contract",
+              resolution_reason:
+                "The route contract and abstract evidence indicate a create effect.",
+              missing_context: [],
+              reasoning_summary:
+                "Abstract explanation without raw implementation details.",
+            },
+          ],
+        },
+      ],
+    },
+    routes: routes.map((route) => ({
+      operation_source_key: route.operation_source_key,
+      method: route.method,
+      path_template: route.path_template,
+      evidence_summaries: route.evidence_summaries,
+    })),
+  });
+
+const requireAiProviderApiKey = (env) => {
+  const apiKey = env.AI_PROVIDER_API_KEY;
+  if (!apiKey) {
+    throw new Error("AI_PROVIDER_API_KEY is required for semantic generation");
+  }
+  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);
+  return new Map(
+    (parsed.routes ?? []).map((route) => [route.operation_source_key, route]),
+  );
+};
+
+const buildAiSelectionPrompt = (selectionCandidates) =>
+  JSON.stringify({
+    task: "Choose adopted semantic values from deterministic and AI candidates. Return JSON only.",
+    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.",
+      "Do not create ids, refs, hashes, source fingerprints, field paths, source locations, raw code, raw SQL, prompts, or completions.",
+      "Prefer the AI candidate when it adds supported business meaning from privacy-safe evidence.",
+      "Prefer deterministic when both candidates are equivalent or the AI candidate is unknown, unsupported, or less schema-safe.",
+      "If neither candidate is safe, include missing_context instead of inventing a value.",
+    ],
+    output_shape: {
+      field_selections: [
+        {
+          operation_source_key: "route.POST./reports",
+          candidate_index: 0,
+          parameter_name: "concept",
+          selected_source: "ai",
+          selection_reason:
+            "AI candidate gives the more specific business concept.",
+          missing_context: [],
+        },
+      ],
+    },
+    selection_candidates: selectionCandidates,
+  });
+
+const callAiSelectionProvider = async ({
+  request,
+  apiKey,
+  selectionCandidates,
+  routeBySelectionKey,
+}) => {
+  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);
+  return normalizeAiSelectionResponse({
+    parsed,
+    routeBySelectionKey,
+  });
+};
+
+const buildSemanticSnapshotVersion = ({ request, generatedAt }) =>
+  `snap_${shortHash(`${request.project_key}:${request.repository.repository_id}:${request.repository.merge_commit}:${request.repository.workflow_run_id ?? generatedAt}`)}`;
+
+const normalizeSnakeSegment = (value) => {
+  const normalized = String(value ?? "")
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .replace(/_+/g, "_");
+  if (!normalized || !/^[a-z]/.test(normalized)) {
+    return null;
+  }
+  return normalized;
+};
+
+const slugSegment = (value) => {
+  const normalized = normalizeSnakeSegment(value);
+  if (!normalized) {
+    return null;
+  }
+  if (
+    !normalized.endsWith("s") &&
+    !normalized.endsWith("data") &&
+    !normalized.endsWith("status")
+  ) {
+    return `${normalized}s`;
+  }
+  return normalized;
+};
+
+const splitIdentifierTokens = (value) =>
+  String(value ?? "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .toLowerCase()
+    .split(/[^a-z0-9]+|_+/)
+    .filter((token) => token.length > 0);
+
+const TECHNICAL_TARGET_TOKENS = new Set([
+  "request",
+  "response",
+  "dto",
+  "schema",
+  "payload",
+  "input",
+  "output",
+  "params",
+  "parameter",
+  "parameters",
+  "body",
+  "model",
+  "service",
+  "repository",
+  "controller",
+  "handler",
+  "usecase",
+]);
+
+const EFFECT_ACTION_TOKENS = new Set([
+  "create",
+  "update",
+  "delete",
+  "upsert",
+  "read",
+  "query",
+  "list",
+  "get",
+  "send",
+  "record",
+  "schedule",
+  "publish",
+  "emit",
+  "import",
+  "export",
+  "process",
+  "generate",
+  "save",
+  "write",
+  "assign",
+  "transition",
+  "approve",
+  "cancel",
+  "archive",
+  "refund",
+  "checkout",
+  "submit",
+  "complete",
+]);
+
+const FORBIDDEN_TARGET_TEXT_PATTERNS = [
+  /\b[A-Za-z0-9_./-]+\.py\b/i,
+  /\b(from\s+[A-Za-z_][A-Za-z0-9_.]*\s+import|import\s+[A-Za-z_][A-Za-z0-9_.]*)\b/i,
+  /\b(class|def)\s+[A-Za-z_][A-Za-z0-9_]*/,
+  /\b(select|insert|update|delete)\s+.+\b(from|into|set)\b/i,
+  /\b(system|user|assistant)\s*:\s*.+\b(prompt|completion|transcript)\b/i,
+  /\b[A-Z][A-Z0-9_]*(?:API_KEY|SECRET|TOKEN|PASSWORD|PRIVATE_KEY)\b(?:\s*=\s*["']?[^"'\s,;}]+)?/,
+  /\b[A-Z][A-Z0-9_]{2,}\s*=\s*["']?[^"'\s,;}]+/,
+  /\b(?:api[_-]?key|secret|token|password)\s*[:=]\s*["']?[^"'\s,;}]+/i,
+  /\b(?:bind|param|parameter)[ _-]?[A-Za-z0-9_]*\s*[:=]\s*["']?[^"'\s,;}]+/i,
+  /[:@$][A-Za-z_][A-Za-z0-9_]*\s*=\s*["']?[^"'\s,;}]+/,
+  /\bBearer\s+(?!\[secret\])[A-Za-z0-9._~+/-]+=*/i,
+  /\bsk-[A-Za-z0-9_-]{8,}\b/,
+];
+
+const hasForbiddenTargetText = (value) =>
+  FORBIDDEN_TARGET_TEXT_PATTERNS.some((pattern) =>
+    pattern.test(String(value ?? "")),
+  );
+
+const normalizeTargetObjectText = (value) => {
+  if (hasForbiddenTargetText(value)) {
+    return null;
+  }
+  const tokens = splitIdentifierTokens(value).filter(
+    (token) => !TECHNICAL_TARGET_TOKENS.has(token),
+  );
+  while (tokens.length > 1 && EFFECT_ACTION_TOKENS.has(tokens[0])) {
+    tokens.shift();
+  }
+  while (
+    tokens.length > 1 &&
+    EFFECT_ACTION_TOKENS.has(tokens[tokens.length - 1])
+  ) {
+    tokens.pop();
+  }
+  const targetKey = slugSegment(tokens.join("_"));
+  return targetKey ? displayNameFromKey(targetKey) : null;
+};
+
+const displayNameFromKey = (key) =>
+  key
+    .split("_")
+    .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+    .join(" ");
+
+const EFFECT_ACTION_ALIASES = new Map([
+  ["creates", "create"],
+  ["created", "create"],
+  ["updates", "update"],
+  ["updated", "update"],
+  ["deletes", "delete"],
+  ["deleted", "delete"],
+  ["reads", "read"],
+  ["queries", "query"],
+  ["imports", "import"],
+  ["exports", "export"],
+  ["sends", "send"],
+  ["sent", "send"],
+  ["records", "record"],
+  ["recorded", "record"],
+  ["emits", "emit"],
+  ["emitted", "emit"],
+  ["schedules", "schedule"],
+  ["scheduled", "schedule"],
+  ["calls", "call"],
+  ["called", "call"],
+  ["processes", "process"],
+  ["processed", "process"],
+  ["infers", "infer"],
+  ["inferred", "infer"],
+  ["changes", "change"],
+  ["changed", "change"],
+  ["transitions", "transition"],
+  ["transitioned", "transition"],
+  ["checks", "check"],
+  ["checked", "check"],
+]);
+
+const normalizeEffectAction = (value, effectKind) => {
+  if (!hasForbiddenTargetText(value)) {
+    const candidate = normalizeSnakeSegment(value);
+    const normalizedCandidate =
+      EFFECT_ACTION_ALIASES.get(candidate) ?? candidate;
+    if (normalizedCandidate && snakeSegmentPattern.test(normalizedCandidate)) {
+      return normalizedCandidate;
+    }
+  }
+  const fromKind = {
+    data_create: "create",
+    data_update: "update",
+    data_delete: "delete",
+    data_upsert: "upsert",
+    data_read: "read",
+    data_query: "query",
+    data_import: "import",
+    data_export: "export",
+    communication_send: "send",
+    audit_record: "record",
+    event_emit: "emit",
+    background_task_schedule: "schedule",
+    external_service_call: "call",
+    payment_operation: "process",
+    ai_inference: "infer",
+    file_process: "process",
+    cache_change: "change",
+    system_config_change: "change",
+    state_transition: "transition",
+    validation_check: "check",
+    access_check: "check",
+  }[effectKind];
+  return fromKind ?? null;
+};
+
+const isValidEffectKey = (key, targetObjectKey) => {
+  if (typeof key !== "string" || !key.includes(".")) {
+    return false;
+  }
+  const [prefix, action] = key.split(".");
+  return (
+    prefix === targetObjectKey &&
+    snakeSegmentPattern.test(prefix) &&
+    snakeSegmentPattern.test(action) &&
+    prefix !== "unknown" &&
+    !ACTUAL_OUTCOME_ACTIONS.has(action)
+  );
+};
+
+const safeArray = (value) => (Array.isArray(value) ? value : []);
+
+const firstNonEmpty = (...values) => {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+  }
+  return null;
+};
+
+const buildSourceEvidenceRefs = (route, hashScope) => {
+  const baseId = `evidence_${shortHash(route.operation_source_key)}_route_contract`;
+  const domainCallTargets = safeArray(
+    route.ai_context?.code_structure?.call_targets,
+  ).filter(
+    (target) =>
+      typeof target === "string" && isDomainBehaviorCallTarget(target),
+  );
+  const refs = [
+    {
+      id: baseId,
+      kind: "route_contract",
+      summary: `${route.method ?? "UNKNOWN"} route exposes a product operation source contract.`,
+      evidence_strength:
+        route.method && route.method !== "GET" ? "medium" : "weak",
+      source_ref_hash: opaqueRouteHash(
+        route,
+        "route_contract_source",
+        hashScope,
+      ),
+      location_hash: opaqueRouteHash(
+        route,
+        "route_contract_location",
+        hashScope,
+      ),
+      metadata: {
+        extractor: "fastapi_route_inventory",
+        schema_version: 2,
+      },
+    },
+  ];
+
+  if (domainCallTargets.length > 0) {
+    refs.push({
+      id: `evidence_${shortHash(route.operation_source_key)}_abstract_behavior`,
+      kind: "abstract_domain_behavior",
+      summary:
+        "Route handler invokes domain behavior that may affect business objects or side effects.",
+      evidence_strength: "medium",
+      source_ref_hash: opaqueRouteHash(
+        route,
+        "abstract_behavior_source",
+        hashScope,
+      ),
+      location_hash: opaqueRouteHash(
+        route,
+        "abstract_behavior_location",
+        hashScope,
+      ),
+      metadata: {
+        extractor: "fastapi_route_inventory",
+        schema_version: 2,
+        domain_call_target_count: domainCallTargets.length,
+      },
+    });
+  }
+
+  return refs;
+};
+
+const isDomainBehaviorCallTarget = (target) => {
+  const normalized = target.toLowerCase();
+  if (
+    /\b(logger|logging|metric|metrics|telemetry|trace|tracer|span|debug|print|cache|uuid|datetime|time|json)\b/.test(
+      normalized,
+    )
+  ) {
+    return false;
+  }
+  const lastSegment = normalized.split(".").at(-1) ?? normalized;
+  if (/^(__|to_|from_|as_)/.test(lastSegment)) {
+    return false;
+  }
+  return /^[a-z_][a-z0-9_]*$/.test(lastSegment);
+};
+
+const tokenStemsFromText = (value) =>
+  String(value ?? "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .toLowerCase()
+    .split(/[^a-z0-9]+|_+/)
+    .filter((token) => token.length >= 3)
+    .flatMap((token) => [
+      token,
+      token.endsWith("s") ? token.slice(0, -1) : `${token}s`,
+    ]);
+
+const localTargetEvidenceStems = (route) => {
+  const codeStructure = route.ai_context?.code_structure ?? {};
+  const localEvidenceValues = [
+    ...safeArray(codeStructure.call_targets),
+    ...safeArray(codeStructure.parameter_annotations),
+    ...safeArray(codeStructure.dependency_hints),
+    codeStructure.response_annotation,
+  ];
+  return new Set(localEvidenceValues.flatMap(tokenStemsFromText));
+};
+
+const candidateHasTargetSpecificEvidence = ({ route, rawTargetObjectText }) => {
+  const targetStems = new Set(tokenStemsFromText(rawTargetObjectText));
+  if (targetStems.size === 0) {
+    return false;
+  }
+  const evidenceStems = localTargetEvidenceStems(route);
+  return [...targetStems].some((stem) => evidenceStems.has(stem));
+};
+
+const normalizeAiOperationEffectCandidates = (aiRoute) =>
+  safeArray(
+    aiRoute?.operation_effect_candidates ?? aiRoute?.operation_effects,
+  ).filter((candidate) => candidate && typeof candidate === "object");
+
+const candidateHasUnsafeSemanticText = (candidate) =>
+  [
+    candidate?.concept,
+    candidate?.business_role,
+    candidate?.raw_target_object_text,
+    candidate?.target_object_text,
+    candidate?.effect_kind,
+    candidate?.effect_action,
+    candidate?.expected_domain_effect,
+    candidate?.resolution_basis,
+    candidate?.resolution_reason,
+    candidate?.reasoning_summary,
+    ...safeArray(candidate?.missing_context),
+  ].some((value) =>
+    FORBIDDEN_TARGET_TEXT_PATTERNS.some((pattern) =>
+      pattern.test(String(value ?? "")),
+    ),
+  );
+
+const selectionKeyForCandidate = (route, candidateIndex) =>
+  `${route.operation_source_key}#${candidateIndex}`;
+
+const normalizeAiSelectionResponse = ({ parsed, routeBySelectionKey }) => {
+  const decisionsByCandidate = new Map();
+  for (const decision of safeArray(parsed?.field_selections)) {
+    if (!decision || typeof decision !== "object") {
+      continue;
+    }
+    if (
+      typeof decision.operation_source_key !== "string" ||
+      !Number.isInteger(decision.candidate_index) ||
+      typeof decision.parameter_name !== "string" ||
+      !SELECTED_SOURCE_VALUES.has(decision.selected_source)
+    ) {
+      continue;
+    }
+    const selectionKey = `${decision.operation_source_key}#${decision.candidate_index}`;
+    const route = routeBySelectionKey.get(selectionKey);
+    if (!route) {
+      continue;
+    }
+    const candidateDecisions =
+      decisionsByCandidate.get(selectionKey) ?? new Map();
+    candidateDecisions.set(decision.parameter_name, {
+      selected_source: decision.selected_source,
+      selection_reason: firstNonEmpty(
+        sanitizeCandidateText(decision.selection_reason, route),
+        "AI selector chose the adopted semantic value from deterministic and AI candidates.",
+      ),
+      missing_context: stringArray(decision.missing_context, route),
+    });
+    decisionsByCandidate.set(selectionKey, candidateDecisions);
+  }
+  return decisionsByCandidate;
+};
+
+const sourceEvidenceRefsForCandidate = ({ candidate, routeEvidenceRefs }) => {
+  const behaviorEvidence = routeEvidenceRefs.filter(
+    (entry) => entry.kind !== "route_contract",
+  );
+  return (
+    behaviorEvidence.length > 0 ? behaviorEvidence : [routeEvidenceRefs[0]]
+  ).map((entry) => entry.id);
+};
+
+const sanitizeCandidateText = (value, route) =>
+  sanitizeText(String(value ?? ""), route).trim();
+
+const hasBehaviorEvidence = (sourceEvidenceRefs, routeEvidenceRefs) => {
+  const routeEvidenceById = new Map(
+    routeEvidenceRefs.map((entry) => [entry.id, entry]),
+  );
+  return sourceEvidenceRefs.some(
+    (ref) => routeEvidenceById.get(ref)?.kind !== "route_contract",
+  );
+};
+
+const deterministicEffectKindForRoute = (route) => {
+  switch (route.method) {
+    case "POST":
+      return "data_create";
+    case "PUT":
+    case "PATCH":
+      return "data_update";
+    case "DELETE":
+      return "data_delete";
+    case "GET":
+    case "HEAD":
+    case "OPTIONS":
+      return "data_query";
+    default:
+      return "unknown";
+  }
+};
+
+const deterministicResolutionBasisForRoute = (
+  sourceEvidenceRefs,
+  routeEvidenceRefs,
+) => {
+  if (hasBehaviorEvidence(sourceEvidenceRefs, routeEvidenceRefs)) {
+    return "ai_inferred_code_behavior";
+  }
+  return "route_contract";
+};
+
+const buildCandidateSemanticValues = ({
+  route,
+  candidate,
+  routeEvidenceRefs,
+}) => {
+  const sourceEvidenceRefs = sourceEvidenceRefsForCandidate({
+    candidate,
+    routeEvidenceRefs,
+  });
+  const rawTargetObjectText = firstNonEmpty(
+    normalizeTargetObjectText(candidate.raw_target_object_text),
+    normalizeTargetObjectText(candidate.target_object_text),
+  );
+  const deterministicConcept =
+    "object associated with a route operation source";
+  const aiConcept = firstNonEmpty(
+    sanitizeCandidateText(candidate.concept, route),
+    "domain object affected by this operation source",
+  );
+  const deterministicBusinessRole =
+    "object participating in the customer workflow";
+  const aiBusinessRole = firstNonEmpty(
+    sanitizeCandidateText(candidate.business_role, route),
+    "object participating in the customer workflow",
+  );
+  const aiEffectKind = EFFECT_KIND_VALUES.has(candidate.effect_kind)
+    ? candidate.effect_kind
+    : "unknown";
+  const deterministicEffectKind = deterministicEffectKindForRoute(route);
+  const aiResolutionBasis = RESOLUTION_BASIS_VALUES.has(
+    candidate.resolution_basis,
+  )
+    ? candidate.resolution_basis
+    : "unknown";
+  const deterministicResolutionBasis = deterministicResolutionBasisForRoute(
+    sourceEvidenceRefs,
+    routeEvidenceRefs,
+  );
+  const deterministicResolutionReason =
+    "Operation effect was detected from privacy-safe source evidence.";
+  const aiResolutionReason = firstNonEmpty(
+    sanitizeCandidateText(candidate.resolution_reason, route),
+    deterministicResolutionReason,
+  );
+  const targetKeyCandidate = rawTargetObjectText
+    ? slugSegment(rawTargetObjectText)
+    : null;
+  const aiEffectAction = normalizeEffectAction(
+    candidate.effect_action,
+    aiEffectKind,
+  );
+  const deterministicEffectAction = normalizeEffectAction(
+    candidate.effect_action,
+    deterministicEffectKind,
+  );
+  const aiExpectedDomainEffect =
+    targetKeyCandidate && aiEffectAction
+      ? `${targetKeyCandidate}.${aiEffectAction}`
+      : null;
+  const deterministicExpectedDomainEffect =
+    targetKeyCandidate && deterministicEffectAction
+      ? `${targetKeyCandidate}.${deterministicEffectAction}`
+      : null;
+
+  return {
+    sourceEvidenceRefs,
+    rawTargetObjectText,
+    targetKeyCandidate,
+    deterministicConcept,
+    aiConcept,
+    deterministicBusinessRole,
+    aiBusinessRole,
+    deterministicEffectKind,
+    aiEffectKind,
+    deterministicResolutionBasis,
+    aiResolutionBasis,
+    deterministicResolutionReason,
+    aiResolutionReason,
+    deterministicExpectedDomainEffect,
+    aiExpectedDomainEffect,
+  };
+};
+
+const buildSelectorCandidates = ({ routes, aiRoutes, hashScope }) => {
+  const selectionCandidates = [];
+  const routeBySelectionKey = new Map();
+
+  for (const route of routes) {
+    const routeEvidenceRefs = buildSourceEvidenceRefs(route, hashScope);
+    const aiRoute = aiRoutes.get(route.operation_source_key);
+    const candidates = normalizeAiOperationEffectCandidates(aiRoute);
+    candidates.forEach((candidate, candidateIndex) => {
+      const values = buildCandidateSemanticValues({
+        route,
+        candidate,
+        routeEvidenceRefs,
+      });
+      if (
+        candidateHasUnsafeSemanticText(candidate) ||
+        !values.rawTargetObjectText ||
+        !values.targetKeyCandidate ||
+        !values.aiExpectedDomainEffect ||
+        !hasBehaviorEvidence(values.sourceEvidenceRefs, routeEvidenceRefs) ||
+        !candidateHasTargetSpecificEvidence({
+          route,
+          rawTargetObjectText: values.rawTargetObjectText,
+        })
+      ) {
+        return;
+      }
+      const selectionKey = selectionKeyForCandidate(route, candidateIndex);
+      routeBySelectionKey.set(selectionKey, route);
+      const evidenceById = new Map(
+        routeEvidenceRefs.map((entry) => [entry.id, entry]),
+      );
+      selectionCandidates.push({
+        operation_source_key: route.operation_source_key,
+        candidate_index: candidateIndex,
+        evidence_summaries: values.sourceEvidenceRefs.map(
+          (ref, evidenceIndex) => {
+            const evidence = evidenceById.get(ref);
+            return {
+              evidence_index: evidenceIndex,
+              kind: evidence.kind,
+              summary: evidence.summary,
+              evidence_strength: evidence.evidence_strength,
+            };
+          },
+        ),
+        semantic_fields: [
+          {
+            parameter_name: "concept",
+            deterministic_candidate: values.deterministicConcept,
+            ai_candidate: values.aiConcept,
+          },
+          {
+            parameter_name: "business_role",
+            deterministic_candidate: values.deterministicBusinessRole,
+            ai_candidate: values.aiBusinessRole,
+          },
+          {
+            parameter_name: "effect_kind",
+            deterministic_candidate: values.deterministicEffectKind,
+            ai_candidate: values.aiEffectKind,
+          },
+          {
+            parameter_name: "expected_domain_effect",
+            deterministic_candidate: values.deterministicExpectedDomainEffect,
+            ai_candidate: values.aiExpectedDomainEffect,
+          },
+          {
+            parameter_name: "resolution.basis",
+            deterministic_candidate: values.deterministicResolutionBasis,
+            ai_candidate: values.aiResolutionBasis,
+          },
+          {
+            parameter_name: "resolution.reason",
+            deterministic_candidate: values.deterministicResolutionReason,
+            ai_candidate: values.aiResolutionReason,
+          },
+        ],
+      });
+    });
+  }
+
+  return { selectionCandidates, routeBySelectionKey };
+};
+
+const canAdoptCandidateValue = (value) =>
+  value !== undefined && value !== null && value !== "" && value !== "unknown";
+
+const selectSemanticSource = ({
+  deterministicValue,
+  aiValue,
+  parameterName,
+  aiSelectionDecision,
+}) => {
+  if (aiSelectionDecision?.selected_source === "ai") {
+    return canAdoptCandidateValue(aiValue) ? "ai" : null;
+  }
+  if (aiSelectionDecision?.selected_source === "deterministic") {
+    return canAdoptCandidateValue(deterministicValue) ? "deterministic" : null;
+  }
+  if (
+    parameterName === "effect_kind" &&
+    deterministicValue !== "unknown" &&
+    deterministicValue === aiValue
+  ) {
+    return "deterministic";
+  }
+  if (
+    parameterName === "resolution.basis" &&
+    deterministicValue !== "unknown" &&
+    deterministicValue === aiValue
+  ) {
+    return "deterministic";
+  }
+  return "ai";
+};
+
+const adoptSemanticValue = ({
+  deterministicValue,
+  aiValue,
+  parameterName,
+  aiSelectionDecision,
+}) => {
+  const selectedSource = selectSemanticSource({
+    deterministicValue,
+    aiValue,
+    parameterName,
+    aiSelectionDecision,
+  });
+  if (selectedSource === "deterministic") {
+    return deterministicValue;
+  }
+  if (selectedSource === "ai") {
+    return aiValue;
+  }
+  return null;
+};
+
+const buildSemanticMeaningCandidate = ({
+  id,
+  fieldPath,
+  parameterName,
+  deterministicValue,
+  aiValue,
+  selectedSource,
+  selectionReason,
+  sourceEvidenceRefs,
+  aiInferenceEvidenceRef,
+  selectionAiInferenceEvidenceRef,
+}) => ({
+  id,
+  field_path: fieldPath,
+  parameter_name: parameterName,
+  deterministic_candidate: {
+    value: deterministicValue,
+    source_evidence_refs: sourceEvidenceRefs,
+    missing_context: [],
+  },
+  ai_candidate: {
+    value: aiValue,
+    source_evidence_refs: sourceEvidenceRefs,
+    ai_inference_evidence_ref: aiInferenceEvidenceRef,
+    missing_context: [],
+  },
+  selected_source: selectedSource,
+  selection_reason:
+    selectionReason ??
+    (selectedSource === "ai"
+      ? "AI candidate was selected from privacy-safe evidence for this semantic field."
+      : "Deterministic candidate was selected because it satisfied the schema and evidence boundary."),
+  selection_ai_inference_evidence_ref: selectionAiInferenceEvidenceRef,
+});
+
+const unresolvedEffect = ({
+  route,
+  candidate,
+  sourceEvidenceRefs,
+  reason,
+  missingContext,
+}) => ({
+  id: `unresolved_effect_${shortHash(`${route.operation_source_key}:${JSON.stringify(candidate)}`)}`,
+  operation_source_key: route.operation_source_key,
+  reason,
+  source_evidence_refs: sourceEvidenceRefs,
+  missing_context: safeArray(missingContext ?? candidate?.missing_context)
+    .filter((entry) => typeof entry === "string" && entry.trim())
+    .map((entry) => sanitizeText(entry.trim(), route)),
+});
+
+const buildOperationAssignmentCollections = ({
+  route,
+  aiRoute,
+  routeEvidenceRefs,
+  catalogByGroup,
+  aiSelectionDecisions,
+}) => {
+  const operationEffects = [];
+  const unresolvedOperationEffects = [];
+  const profiles = [];
+  const mappings = [];
+  const aiInferenceEvidence = [];
+  const semanticMeaningCandidates = [];
+  const emittedEffectKeys = new Set();
+
+  const candidates = normalizeAiOperationEffectCandidates(aiRoute);
+  for (
+    let candidateIndex = 0;
+    candidateIndex < candidates.length;
+    candidateIndex += 1
+  ) {
+    const candidate = candidates[candidateIndex];
+    const selectionDecisions =
+      aiSelectionDecisions.get(
+        selectionKeyForCandidate(route, candidateIndex),
+      ) ?? new Map();
+    const values = buildCandidateSemanticValues({
+      route,
+      candidate,
+      routeEvidenceRefs,
+    });
+    const sourceEvidenceRefs = values.sourceEvidenceRefs;
+    if (candidateHasUnsafeSemanticText(candidate)) {
+      unresolvedOperationEffects.push(
+        unresolvedEffect({
+          route,
+          candidate,
+          sourceEvidenceRefs,
+          reason:
+            "AI operation effect candidate contained raw implementation or secret-like text, so no formal operation effect was emitted.",
+        }),
+      );
+      continue;
+    }
+    const rawTargetObjectText = values.rawTargetObjectText;
+    const targetKeyCandidate = values.targetKeyCandidate;
+    const deterministicConcept = values.deterministicConcept;
+    const aiConcept = values.aiConcept;
+    const concept = adoptSemanticValue({
+      deterministicValue: deterministicConcept,
+      aiValue: aiConcept,
+      parameterName: "concept",
+      aiSelectionDecision: selectionDecisions.get("concept"),
+    });
+    const deterministicBusinessRole = values.deterministicBusinessRole;
+    const aiBusinessRole = values.aiBusinessRole;
+    const businessRole = adoptSemanticValue({
+      deterministicValue: deterministicBusinessRole,
+      aiValue: aiBusinessRole,
+      parameterName: "business_role",
+      aiSelectionDecision: selectionDecisions.get("business_role"),
+    });
+    const aiEffectKind = values.aiEffectKind;
+    const deterministicEffectKind = values.deterministicEffectKind;
+    const aiResolutionBasis = values.aiResolutionBasis;
+    const deterministicResolutionBasis = values.deterministicResolutionBasis;
+    const effectKind = adoptSemanticValue({
+      deterministicValue: deterministicEffectKind,
+      aiValue: aiEffectKind,
+      parameterName: "effect_kind",
+      aiSelectionDecision: selectionDecisions.get("effect_kind"),
+    });
+    const resolutionBasis = adoptSemanticValue({
+      deterministicValue: deterministicResolutionBasis,
+      aiValue: aiResolutionBasis,
+      parameterName: "resolution.basis",
+      aiSelectionDecision: selectionDecisions.get("resolution.basis"),
+    });
+    const deterministicResolutionReason = values.deterministicResolutionReason;
+    const aiResolutionReason = values.aiResolutionReason;
+    const resolutionReason = adoptSemanticValue({
+      deterministicValue: deterministicResolutionReason,
+      aiValue: aiResolutionReason,
+      parameterName: "resolution.reason",
+      aiSelectionDecision: selectionDecisions.get("resolution.reason"),
+    });
+    const expectedDomainEffect = adoptSemanticValue({
+      deterministicValue: values.deterministicExpectedDomainEffect,
+      aiValue: values.aiExpectedDomainEffect,
+      parameterName: "expected_domain_effect",
+      aiSelectionDecision: selectionDecisions.get("expected_domain_effect"),
+    });
+    const effectAction = expectedDomainEffect?.split(".")[1] ?? null;
+
+    if (
+      !rawTargetObjectText ||
+      !targetKeyCandidate ||
+      !effectAction ||
+      !hasBehaviorEvidence(sourceEvidenceRefs, routeEvidenceRefs) ||
+      !candidateHasTargetSpecificEvidence({
+        route,
+        rawTargetObjectText,
+      })
+    ) {
+      unresolvedOperationEffects.push(
+        unresolvedEffect({
+          route,
+          candidate,
+          sourceEvidenceRefs,
+          reason:
+            "Target object, effect action, or supporting behavior evidence was insufficient, so no formal operation effect was emitted.",
+        }),
+      );
+      continue;
+    }
+
+    const requiredSelectionParameters = [
+      "concept",
+      "business_role",
+      "effect_kind",
+      "expected_domain_effect",
+      "resolution.basis",
+      "resolution.reason",
+    ];
+    const missingSelectionParameters = requiredSelectionParameters.filter(
+      (parameterName) => !selectionDecisions.has(parameterName),
+    );
+    if (missingSelectionParameters.length > 0) {
+      unresolvedOperationEffects.push(
+        unresolvedEffect({
+          route,
+          candidate,
+          sourceEvidenceRefs,
+          reason:
+            "Higher-level AI selector did not return complete field-level selection decisions, so no formal operation effect was emitted.",
+        }),
+      );
+      continue;
+    }
+    const selectionMissingContext = requiredSelectionParameters.flatMap(
+      (parameterName) =>
+        selectionDecisions.get(parameterName)?.missing_context ?? [],
+    );
+    if (selectionMissingContext.length > 0) {
+      unresolvedOperationEffects.push(
+        unresolvedEffect({
+          route,
+          candidate,
+          sourceEvidenceRefs,
+          reason:
+            "Higher-level AI selector reported missing context, so no formal operation effect was emitted.",
+          missingContext: selectionMissingContext,
+        }),
+      );
+      continue;
+    }
+    if (
+      !canAdoptCandidateValue(concept) ||
+      !canAdoptCandidateValue(businessRole) ||
+      !canAdoptCandidateValue(effectKind) ||
+      !canAdoptCandidateValue(expectedDomainEffect) ||
+      !canAdoptCandidateValue(resolutionBasis) ||
+      !canAdoptCandidateValue(resolutionReason)
+    ) {
+      unresolvedOperationEffects.push(
+        unresolvedEffect({
+          route,
+          candidate,
+          sourceEvidenceRefs,
+          reason:
+            "Higher-level AI selector chose an unsafe or unknown value, so no formal operation effect was emitted.",
+        }),
+      );
+      continue;
+    }
+
+    const groupKey = `${concept.toLowerCase()}::${businessRole.toLowerCase()}`;
+    const existingCatalog = catalogByGroup.get(groupKey);
+    const targetObjectKey =
+      existingCatalog?.target_object_key ?? targetKeyCandidate;
+    const operationEffectKey = `${targetObjectKey}.${effectAction}`;
+    if (!isValidEffectKey(operationEffectKey, targetObjectKey)) {
+      unresolvedOperationEffects.push(
+        unresolvedEffect({
+          route,
+          candidate,
+          sourceEvidenceRefs,
+          reason:
+            "Generated effect key would violate the target object key naming contract.",
+        }),
+      );
+      continue;
+    }
+    if (emittedEffectKeys.has(operationEffectKey)) {
+      unresolvedOperationEffects.push(
+        unresolvedEffect({
+          route,
+          candidate,
+          sourceEvidenceRefs,
+          reason:
+            "Duplicate operation effect key was detected for this route, so the duplicate candidate was preserved as unresolved evidence.",
+        }),
+      );
+      continue;
+    }
+    emittedEffectKeys.add(operationEffectKey);
+
+    const suffix = `${targetObjectKey}_${effectAction}_${shortHash(route.operation_source_key)}`;
+    const profileId = `target_profile_${suffix}`;
+    const mappingId = `target_mapping_${suffix}`;
+    const aiProfileEvidenceId = `ai_inference_profile_${suffix}`;
+    const aiSelectionEvidenceId = `ai_inference_select_${suffix}`;
+    const profileFieldPrefix = `target_object_profiles[${profileId}]`;
+    const effectFieldPrefix = `routes[${route.operation_source_key}].operation_effects[${operationEffectKey}]`;
+
+    profiles.push({
+      id: profileId,
+      operation_source_key: route.operation_source_key,
+      operation_effect_key: operationEffectKey,
+      raw_target_object_text: rawTargetObjectText,
+      concept,
+      business_role: businessRole,
+      evidence_refs: sourceEvidenceRefs,
+      source_evidence_refs: sourceEvidenceRefs,
+      missing_context: [],
+    });
+
+    aiInferenceEvidence.push({
+      id: aiProfileEvidenceId,
+      task: "target_object_profile_extraction",
+      input_source_evidence_refs: sourceEvidenceRefs,
+      output_field_paths: [
+        `${profileFieldPrefix}.raw_target_object_text`,
+        `${profileFieldPrefix}.concept`,
+        `${profileFieldPrefix}.business_role`,
+      ],
+      reasoning_summary: firstNonEmpty(
+        sanitizeCandidateText(candidate.reasoning_summary, route),
+        "AI candidate described the target object profile from privacy-safe source evidence.",
+      ),
+      missing_context: [],
+    });
+    aiInferenceEvidence.push({
+      id: aiSelectionEvidenceId,
+      task: "semantic_meaning_candidate_selection",
+      input_source_evidence_refs: sourceEvidenceRefs,
+      output_field_paths: [
+        `${profileFieldPrefix}.concept`,
+        `${profileFieldPrefix}.business_role`,
+        `${effectFieldPrefix}.effect_kind`,
+        `${effectFieldPrefix}.expected_domain_effect`,
+        `${effectFieldPrefix}.resolution.basis`,
+        `${effectFieldPrefix}.resolution.reason`,
+      ],
+      reasoning_summary:
+        "Higher-level AI selector adopted schema-valid semantic values while preserving deterministic and AI candidates separately.",
+      missing_context: [],
+    });
+
+    const candidateSpecs = [
+      {
+        parameterName: "concept",
+        fieldPath: `${profileFieldPrefix}.concept`,
+        deterministicValue: deterministicConcept,
+        aiValue: aiConcept,
+        selectedValue: concept,
+      },
+      {
+        parameterName: "business_role",
+        fieldPath: `${profileFieldPrefix}.business_role`,
+        deterministicValue: deterministicBusinessRole,
+        aiValue: aiBusinessRole,
+        selectedValue: businessRole,
+      },
+      {
+        parameterName: "effect_kind",
+        fieldPath: `${effectFieldPrefix}.effect_kind`,
+        deterministicValue: deterministicEffectKind,
+        aiValue: aiEffectKind,
+        selectedValue: effectKind,
+      },
+      {
+        parameterName: "expected_domain_effect",
+        fieldPath: `${effectFieldPrefix}.expected_domain_effect`,
+        deterministicValue: values.deterministicExpectedDomainEffect,
+        aiValue: values.aiExpectedDomainEffect,
+        selectedValue: expectedDomainEffect,
+      },
+      {
+        parameterName: "resolution.basis",
+        fieldPath: `${effectFieldPrefix}.resolution.basis`,
+        deterministicValue: deterministicResolutionBasis,
+        aiValue: aiResolutionBasis,
+        selectedValue: resolutionBasis,
+      },
+      {
+        parameterName: "resolution.reason",
+        fieldPath: `${effectFieldPrefix}.resolution.reason`,
+        deterministicValue: deterministicResolutionReason,
+        aiValue: aiResolutionReason,
+        selectedValue: resolutionReason,
+      },
+    ];
+
+    for (const spec of candidateSpecs) {
+      semanticMeaningCandidates.push(
+        buildSemanticMeaningCandidate({
+          id: `semantic_candidate_${shortHash(`${route.operation_source_key}:${operationEffectKey}:${spec.parameterName}`)}`,
+          fieldPath: spec.fieldPath,
+          parameterName: spec.parameterName,
+          deterministicValue: spec.deterministicValue,
+          aiValue: spec.aiValue,
+          selectedSource: selectSemanticSource({
+            deterministicValue: spec.deterministicValue,
+            aiValue: spec.aiValue,
+            parameterName: spec.parameterName,
+            aiSelectionDecision: selectionDecisions.get(spec.parameterName),
+          }),
+          selectionReason: selectionDecisions.get(spec.parameterName)
+            ?.selection_reason,
+          sourceEvidenceRefs,
+          aiInferenceEvidenceRef: aiProfileEvidenceId,
+          selectionAiInferenceEvidenceRef: aiSelectionEvidenceId,
+        }),
+      );
+    }
+
+    const catalogEntry = existingCatalog ?? {
+      target_object_key: targetObjectKey,
+      display_name: displayNameFromKey(targetObjectKey),
+      concept,
+      business_role: businessRole,
+      aliases: [],
+      raw_target_object_profile_refs: [],
+      grouping_evidence_refs: [],
+      missing_context: [],
+    };
+    if (!catalogEntry.aliases.includes(rawTargetObjectText)) {
+      catalogEntry.aliases.push(rawTargetObjectText);
+    }
+    if (!catalogEntry.raw_target_object_profile_refs.includes(profileId)) {
+      catalogEntry.raw_target_object_profile_refs.push(profileId);
+    }
+    for (const ref of sourceEvidenceRefs) {
+      if (!catalogEntry.grouping_evidence_refs.includes(ref)) {
+        catalogEntry.grouping_evidence_refs.push(ref);
+      }
+    }
+    catalogByGroup.set(groupKey, catalogEntry);
+
+    mappings.push({
+      id: mappingId,
+      operation_source_key: route.operation_source_key,
+      operation_effect_key: operationEffectKey,
+      raw_target_object_profile_ref: profileId,
+      target_object_key: targetObjectKey,
+      grouping_evidence_ref: sourceEvidenceRefs[0],
+      mapping_reason: `The ${operationEffectKey} effect maps to the normalized ${targetObjectKey} catalog entry through privacy-safe source evidence.`,
+      missing_context: [],
+    });
+
+    operationEffects.push({
+      operation_effect_key: operationEffectKey,
+      effect_kind: effectKind,
+      expected_domain_effect: operationEffectKey,
+      target_object_key: targetObjectKey,
+      target_object_profile_ref: profileId,
+      target_object_mapping_ref: mappingId,
+      resolution: {
+        basis: resolutionBasis,
+        reason: resolutionReason,
+      },
+      source_evidence_refs: sourceEvidenceRefs,
+      missing_context: [],
+    });
+  }
+
+  return {
+    operationEffects,
+    unresolvedOperationEffects,
+    profiles,
+    mappings,
+    aiInferenceEvidence,
+    semanticMeaningCandidates,
+  };
+};
+
+const buildSnapshot = ({ request, routes, aiRoutes, aiSelectionDecisions }) => {
+  const generatedAt = new Date().toISOString();
+  const hashScope = semanticSnapshotHashScope(request);
+  const semanticSnapshotVersion = buildSemanticSnapshotVersion({
+    request,
+    generatedAt,
+  });
+  const targetObjectProfiles = [];
+  const targetObjectMappings = [];
+  const sourceEvidenceRefs = [];
+  const aiInferenceEvidence = [];
+  const semanticMeaningCandidates = [];
+  const catalogByGroup = new Map();
+
+  const snapshotRoutes = routes.map((route) => {
+    const routeWithVersion = {
+      ...route,
+      semantic_snapshot_version: semanticSnapshotVersion,
+    };
+    const routeEvidenceRefs = buildSourceEvidenceRefs(
+      routeWithVersion,
+      hashScope,
+    );
+    sourceEvidenceRefs.push(...routeEvidenceRefs);
+    const aiRoute = aiRoutes.get(route.operation_source_key);
+    const baseRoute = !aiRoute?.semantics
+      ? fallbackSemantics(
+          routeWithVersion,
+          "AI semantics were unavailable for this route.",
+          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.",
+            ),
+            route,
+          ),
+        };
+    const assignmentCollections = buildOperationAssignmentCollections({
+      route,
+      aiRoute,
+      routeEvidenceRefs,
+      catalogByGroup,
+      aiSelectionDecisions,
+    });
+    targetObjectProfiles.push(...assignmentCollections.profiles);
+    targetObjectMappings.push(...assignmentCollections.mappings);
+    aiInferenceEvidence.push(...assignmentCollections.aiInferenceEvidence);
+    semanticMeaningCandidates.push(
+      ...assignmentCollections.semanticMeaningCandidates,
+    );
+    return {
+      ...baseRoute,
+      operation_effects: assignmentCollections.operationEffects,
+      unresolved_operation_effects:
+        assignmentCollections.unresolvedOperationEffects,
+      source_evidence_refs: routeEvidenceRefs.map((entry) => entry.id),
+    };
+  });
+
+  return validateSemanticSnapshotRequest({
+    project_key: request.project_key,
+    idempotency_key: sha256(
+      `${request.project_key}:${request.repository.repository_id}:${request.repository.merge_commit}:${request.repository.workflow_run_id ?? generatedAt}`,
+    ),
+    schema_version: 2,
+    semantic_snapshot_version: semanticSnapshotVersion,
+    generated_at: generatedAt,
+    repository: request.repository,
+    service: request.service,
+    analysis_summary: {
+      total_routes_scanned: routes.length,
+      routes_generated: snapshotRoutes.filter(
+        (route) => route.semantics.route_confidence > 0,
+      ).length,
+      uncertain_routes: snapshotRoutes.filter(
+        (route) => route.semantics.route_confidence < 0.5,
+      ).length,
+      failed_routes: 0,
+    },
+    routes: snapshotRoutes,
+    target_object_profiles: targetObjectProfiles,
+    target_object_catalog: [...catalogByGroup.values()],
+    target_object_mappings: targetObjectMappings,
+    source_evidence_refs: sourceEvidenceRefs,
+    ai_inference_evidence: aiInferenceEvidence,
+    semantic_meaning_candidates: semanticMeaningCandidates,
+  });
+};
+
+const sanitizeText = (value, route) => {
+  let result = value;
+  const forbiddenTokens = [
+    route.ai_context.handler_name,
+    route.ai_context.relative_path,
+  ].filter((token) => typeof token === "string" && token.length > 0);
+  for (const token of forbiddenTokens) {
+    result = result.split(token).join("[component]");
+  }
+  result = result
+    .replace(
+      /\b(select|insert|update|delete)\s+.+?\b(from|into|set)\b[^"',;}]+/gi,
+      "[sql]",
+    )
+    .replace(
+      /\b(system|user|assistant)\s*:\s*[^"',;}]*(prompt|completion|transcript)[^"',;}]*/gi,
+      "[prompt]",
+    )
+    .replace(
+      /\b[A-Za-z_][A-Za-z0-9_]*(Controller|Service|Repository|UseCase|Handler|Model)\b/g,
+      "[component]",
+    )
+    .replace(
+      /\b[A-Za-z_][A-Za-z0-9_]*(Request|Response|DTO|Dto|Schema|Payload|Input|Output|Params|Parameters|Body)\b/g,
+      "[component]",
+    )
+    .replace(
+      /\b[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*){2,}\b/g,
+      "[component]",
+    )
+    .replace(
+      /\b[A-Z][A-Z0-9_]*(?:API_KEY|SECRET|TOKEN|PASSWORD|PRIVATE_KEY)\b(?:\s*=\s*["']?[^"'\s,;}]+)?/g,
+      "[secret]",
+    )
+    .replace(/\b[A-Z][A-Z0-9_]{2,}\s*=\s*["']?[^"'\s,;}]+/g, "[env]")
+    .replace(
+      /\b(?:api[_-]?key|secret|token|password)\s*[:=]\s*["']?[^"'\s,;}]+/gi,
+      "[secret]",
+    )
+    .replace(
+      /\b(?:bind|param|parameter)[ _-]?[A-Za-z0-9_]*\s*[:=]\s*["']?[^"'\s,;}]+/gi,
+      "[bind]",
+    )
+    .replace(/[:@$][A-Za-z_][A-Za-z0-9_]*\s*=\s*["']?[^"'\s,;}]+/g, "[bind]")
+    .replace(/\bBearer\s+[A-Za-z0-9._~+/-]+=*/gi, "Bearer [secret]")
+    .replace(/\bsk-[A-Za-z0-9_-]{8,}\b/g, "[secret]")
+    .replace(/\$[A-Z][A-Z0-9_]+/g, "[env]");
+  return result;
+};
+
+const sanitizeSemantics = (value, route) => {
+  const record = sanitizeForClueStorage(value, route);
+  const safeRecord =
+    record && typeof record === "object" && !Array.isArray(record)
+      ? record
+      : {};
+  return {
+    route_summary:
+      typeof safeRecord.route_summary === "string" &&
+      safeRecord.route_summary.trim()
+        ? safeRecord.route_summary
+        : "unknown",
+    action_candidates: Array.isArray(safeRecord.action_candidates)
+      ? safeRecord.action_candidates
+      : [],
+    outcome_candidates: Array.isArray(safeRecord.outcome_candidates)
+      ? safeRecord.outcome_candidates
+      : [],
+    value_event_candidates: [],
+    route_confidence: Number.isFinite(Number(safeRecord.route_confidence))
+      ? Math.max(0, Math.min(1, Number(safeRecord.route_confidence)))
+      : 0,
+  };
+};
+
+const sanitizeForClueStorage = (value, route) => {
+  if (typeof value === "string") {
+    return sanitizeText(value, route);
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => sanitizeForClueStorage(entry, route));
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [
+        key,
+        sanitizeForClueStorage(entry, route),
+      ]),
+    );
+  }
+  return value;
+};
+
+const stringArray = (value, route) =>
+  Array.isArray(value)
+    ? value
+        .filter((entry) => typeof entry === "string" && entry.trim())
+        .map((entry) => sanitizeText(entry.trim(), route))
+    : [];
+
+const confidenceOrUndefined = (value) => {
+  const numberValue = Number(value);
+  if (!Number.isFinite(numberValue)) {
+    return undefined;
+  }
+  return Math.max(0, Math.min(1, numberValue));
+};
+
+const normalizeMutationKind = (value) =>
+  ["create", "update", "delete", "upsert", "read", "unknown"].includes(value)
+    ? value
+    : "unknown";
+
+const sanitizeLayerEvidence = (value, route, hashScope) => {
+  const record =
+    value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  const dataEffects = Array.isArray(record.data_effects)
+    ? record.data_effects
+        .filter(
+          (entry) =>
+            entry &&
+            typeof entry === "object" &&
+            typeof entry.entity_label === "string",
+        )
+        .map((entry) => ({
+          entity_label: sanitizeText(entry.entity_label, route),
+          ...(typeof entry.mutation_kind === "string"
+            ? { mutation_kind: normalizeMutationKind(entry.mutation_kind) }
+            : {}),
+          ...(confidenceOrUndefined(entry.confidence) === undefined
+            ? {}
+            : { confidence: confidenceOrUndefined(entry.confidence) }),
+        }))
+    : [];
+  const sideEffects = Array.isArray(record.side_effects)
+    ? record.side_effects
+        .filter(
+          (entry) =>
+            entry &&
+            typeof entry === "object" &&
+            typeof entry.side_effect_kind === "string",
+        )
+        .map((entry) => ({
+          side_effect_kind: sanitizeText(entry.side_effect_kind, route),
+          ...(confidenceOrUndefined(entry.confidence) === undefined
+            ? {}
+            : { confidence: confidenceOrUndefined(entry.confidence) }),
+        }))
+    : [];
+
+  return {
+    data_effects: dataEffects,
+    side_effects: sideEffects,
+    failure_surfaces: stringArray(record.failure_surfaces, route),
+    validation_field_paths: stringArray(record.validation_field_paths, route),
+    permission_scopes: stringArray(record.permission_scopes, route),
+    component_fingerprints: [
+      opaqueRouteHash(route, "route_contract_component", hashScope),
+      opaqueRouteHash(route, "abstract_behavior_component", hashScope),
+      opaqueRouteHash(route, "source_component", hashScope),
+    ],
+  };
+};
+
+const FORBIDDEN_CODE_STRUCTURE_PATTERNS = [
+  { label: "file path", pattern: /\b[A-Za-z0-9_./-]+\.py\b/i },
+  {
+    label: "import statement",
+    pattern:
+      /\b(from\s+[A-Za-z_][A-Za-z0-9_.]*\s+import|import\s+[A-Za-z_][A-Za-z0-9_.]*)\b/i,
+  },
+  {
+    label: "code definition",
+    pattern: /\b(class|def)\s+[A-Za-z_][A-Za-z0-9_]*/,
+  },
+  {
+    label: "internal component name",
+    pattern:
+      /\b[A-Za-z_][A-Za-z0-9_]*(Controller|Service|Repository|UseCase|Handler|Model)\b/,
+  },
+  {
+    label: "code artifact identifier",
+    pattern:
+      /\b[A-Za-z_][A-Za-z0-9_]*(Request|Response|DTO|Dto|Schema|Payload|Input|Output|Params|Parameters|Body)\b/,
+  },
+  {
+    label: "module path",
+    pattern: /\b[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*){2,}\b/,
+  },
+  {
+    label: "raw sql",
+    pattern: /\b(select|insert|update|delete)\s+.+\b(from|into|set)\b/i,
+  },
+  {
+    label: "raw prompt",
+    pattern:
+      /\b(system|user|assistant)\s*:\s*.+\b(prompt|completion|transcript)\b/i,
+  },
+  {
+    label: "secret",
+    pattern:
+      /\b[A-Z][A-Z0-9_]*(?:API_KEY|SECRET|TOKEN|PASSWORD|PRIVATE_KEY)\b(?:\s*=\s*["']?[^"'\s,;}]+)?/,
+  },
+  {
+    label: "environment variable",
+    pattern: /\b[A-Z][A-Z0-9_]{2,}\s*=\s*["']?[^"'\s,;}]+/,
+  },
+  {
+    label: "credential",
+    pattern:
+      /\b(?:api[_-]?key|secret|token|password)\s*[:=]\s*["']?[^"'\s,;}]+/i,
+  },
+  {
+    label: "bind value",
+    pattern:
+      /\b(?:bind|param|parameter)[ _-]?[A-Za-z0-9_]*\s*[:=]\s*["']?[^"'\s,;}]+/i,
+  },
+  {
+    label: "bind value",
+    pattern: /[:@$][A-Za-z_][A-Za-z0-9_]*\s*=\s*["']?[^"'\s,;}]+/,
+  },
+  {
+    label: "bearer token",
+    pattern: /\bBearer\s+(?!\[secret\])[A-Za-z0-9._~+/-]+=*/i,
+  },
+  { label: "secret token", pattern: /\bsk-[A-Za-z0-9_-]{8,}\b/ },
+];
+
+const assertNoRawCodeStructure = (value, path = "snapshot") => {
+  if (typeof value === "string") {
+    for (const rule of FORBIDDEN_CODE_STRUCTURE_PATTERNS) {
+      if (rule.pattern.test(value)) {
+        throw new Error(`semantic snapshot contains ${rule.label} at ${path}`);
+      }
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) =>
+      assertNoRawCodeStructure(entry, `${path}[${index}]`),
+    );
+    return;
+  }
+  if (value && typeof value === "object") {
+    for (const [key, entry] of Object.entries(value)) {
+      assertNoRawCodeStructure(entry, `${path}.${key}`);
+    }
+  }
+};
+
+const semanticSnapshotUrl = (baseUrl) => {
+  const normalized = baseUrl.replace(/\/+$/, "");
+  if (normalized.endsWith("/api/v1/semantic-snapshots")) {
+    return normalized;
+  }
+  if (normalized.endsWith("/api/v1")) {
+    return `${normalized}/semantic-snapshots`;
+  }
+  return `${normalized}/api/v1/semantic-snapshots`;
+};
+
+const sendSnapshot = async ({ request, env, snapshot }) => {
+  const apiKey = env.CLUE_API_KEY;
+  if (!apiKey) {
+    throw new Error("CLUE_API_KEY is required");
+  }
+  const validatedSnapshot = validateSemanticSnapshotRequest(snapshot);
+  assertNoRawCodeStructure(validatedSnapshot);
+  const response = await fetch(semanticSnapshotUrl(request.clue_api_base_url), {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify(validatedSnapshot),
+  });
+  if (!response.ok) {
+    throw new Error(`Clue semantic snapshot upload failed: ${response.status}`);
+  }
+  return response.json();
+};
+
+export const runSemanticCi = async ({ repoRoot, request: rawRequest, env }) => {
+  const request = validateSemanticCiRequest(rawRequest);
+  const hashScope = semanticSnapshotHashScope(request);
+  const files = await listAllowedPythonFiles({
+    repoRoot,
+    allowedSourcePaths: request.allowed_source_paths,
+    excludedSourcePaths: request.excluded_source_paths,
+  });
+  const routes = await analyzeFastApiRoutes({ repoRoot, files });
+  const promptRoutes = routes.map((route) => ({
+    operation_source_key: route.operation_source_key,
+    method: route.method,
+    path_template: route.path_template,
+    evidence_summaries: buildSourceEvidenceRefs(route, hashScope).map(
+      (entry, index) => ({
+        evidence_index: index,
+        kind: entry.kind,
+        summary: entry.summary,
+        evidence_strength: entry.evidence_strength,
+      }),
+    ),
+  }));
+  const aiProviderApiKey = requireAiProviderApiKey(env);
+  const aiRoutes = await callAiProvider({
+    request,
+    apiKey: aiProviderApiKey,
+    routes: promptRoutes,
+  });
+  const { selectionCandidates, routeBySelectionKey } = buildSelectorCandidates({
+    routes,
+    aiRoutes,
+    hashScope,
+  });
+  const aiSelectionDecisions = await callAiSelectionProvider({
+    request,
+    apiKey: aiProviderApiKey,
+    selectionCandidates,
+    routeBySelectionKey,
+  });
+  const snapshot = buildSnapshot({
+    request,
+    routes,
+    aiRoutes,
+    aiSelectionDecisions,
+  });
+  const upload = await sendSnapshot({ request, env, snapshot });
+  return {
+    accepted: upload.accepted === true,
+    route_count: snapshot.routes.length,
+    upload,
+  };
+};