@clue-ai/cli 0.0.17 → 0.0.19

package/src/semantic-ci.mjs

@@ -97,6 +97,9 @@ const PURPOSE_CHANGE_STATES = new Set([
   "new_route",
 ]);
 
+const shouldPurposeRecheckAllRoutes = (env) =>
+  env.CLUE_SEMANTIC_PURPOSE_RECHECK_ALL === "1";
+
 const semanticSnapshotHashScope = (request) =>
   [
     "clue_tools_semantic_snapshot",
@@ -641,6 +644,9 @@ const generateAiRoutesPerRoute = async ({
         );
       }
     } catch (error) {
+      if (error instanceof SyntaxError) {
+        throw error;
+      }
       aiRoutes.set(
         route.operation_source_key,
         unavailableAiRoute(
@@ -2063,31 +2069,37 @@ const buildSnapshot = ({
       };
     }
 
+    const effectivePlan =
+      !aiRoute?.semantics && plan.active_semantic_source === "new_confirmed"
+        ? unconfirmedFallbackPlan({ plan, reason: unavailableReason })
+        : plan;
+
     return withStabilityMetadata({
       currentRoute: route,
-      plan,
+      plan: effectivePlan,
       route: {
-      ...baseRoute,
-      operation_effects: assignmentCollections.operationEffects,
-      unresolved_operation_effects:
-        assignmentCollections.unresolvedOperationEffects,
-      source_evidence_refs: routeEvidenceRefs.map((entry) => entry.id),
-      route_input_hash: plan.route_input_hash,
-      previous_route_input_hash: plan.previous_route_input_hash,
-      previous_route_semantic_hash: plan.previous_route_semantic_hash,
-      semantic_origin:
-        plan.origin === "changed_route_needs_review" && aiRoute?.semantics
-          ? "changed_route_needs_review"
-          : plan.origin,
-      semantic_change_reason: plan.semantic_change_reason,
-      previous_semantic_snapshot_version:
-        plan.previous_route?.semantic_snapshot_version,
-      route_semantic_hash: routeSemanticHash({
         ...baseRoute,
         operation_effects: assignmentCollections.operationEffects,
         unresolved_operation_effects:
           assignmentCollections.unresolvedOperationEffects,
-      }),
+        source_evidence_refs: routeEvidenceRefs.map((entry) => entry.id),
+        route_input_hash: effectivePlan.route_input_hash,
+        previous_route_input_hash: effectivePlan.previous_route_input_hash,
+        previous_route_semantic_hash: effectivePlan.previous_route_semantic_hash,
+        semantic_origin:
+          effectivePlan.origin === "changed_route_needs_review" &&
+          aiRoute?.semantics
+            ? "changed_route_needs_review"
+            : effectivePlan.origin,
+        semantic_change_reason: effectivePlan.semantic_change_reason,
+        previous_semantic_snapshot_version:
+          effectivePlan.previous_route?.semantic_snapshot_version,
+        route_semantic_hash: routeSemanticHash({
+          ...baseRoute,
+          operation_effects: assignmentCollections.operationEffects,
+          unresolved_operation_effects:
+            assignmentCollections.unresolvedOperationEffects,
+        }),
       },
     });
   });
@@ -2460,8 +2472,16 @@ const routeSourceForPolicy = (route) =>
 const classifyClueInfrastructureRoute = (route) => {
   const source = routeSourceForPolicy(route);
   const reservedPath = isReservedClueBrowserTokenPath(route.path_template);
-  const proxiesToClueBrowserTokenApi =
+  const directlyCallsClueBrowserTokenApi =
     /\/(?:api\/v[0-9]+\/)?ingest\/browser-tokens\b/i.test(source);
+  const usesClueBrowserTokenRequestContract =
+    /\bCLUE_API_BASE_URL\b/.test(source) &&
+    /\bCLUE_PROJECT_KEY\b/.test(source) &&
+    /\bCLUE_ENVIRONMENT\b/.test(source) &&
+    /\bserviceKey\b/.test(source) &&
+    /\b(?:client|httpx)\.post\b/.test(source);
+  const proxiesToClueBrowserTokenApi =
+    directlyCallsClueBrowserTokenApi || usesClueBrowserTokenRequestContract;
   const usesServerSideClueApiKey = /\bCLUE_API_KEY\b|x-clue-api-key/i.test(
     source,
   );
@@ -2478,6 +2498,8 @@ const classifyClueInfrastructureRoute = (route) => {
       evidence: {
         reserved_clue_path: true,
         proxies_to_clue_browser_token_api: true,
+        uses_clue_browser_token_request_contract:
+          usesClueBrowserTokenRequestContract,
         uses_server_side_clue_api_key: true,
       },
     };
@@ -2488,6 +2510,8 @@ const classifyClueInfrastructureRoute = (route) => {
     evidence: {
       reserved_clue_path: reservedPath,
       proxies_to_clue_browser_token_api: proxiesToClueBrowserTokenApi,
+      uses_clue_browser_token_request_contract:
+        usesClueBrowserTokenRequestContract,
       uses_server_side_clue_api_key: usesServerSideClueApiKey,
     },
   };
@@ -2537,6 +2561,7 @@ const classifyRoutesForSnapshot = async ({
   hashScope,
   generationContract,
   agentSkills,
+  purposeRecheckAllRoutes = false,
 }) => {
   const previousRoutes = previousRouteMap(previousSnapshot);
   const plans = new Map();
@@ -2562,6 +2587,80 @@ const classifyRoutesForSnapshot = async ({
       previousRoute.route_input_hash === currentHash &&
       hasReusablePreviousRouteSemantics(previousRoute)
     ) {
+      if (purposeRecheckAllRoutes) {
+        const decision = await callAiReuseDecisionProvider({
+          request,
+          env,
+          apiKey: aiProviderApiKey,
+          route: buildRouteEvidencePromptEntry({ route, hashScope }),
+          previousRoute,
+          currentHash,
+          generationContract,
+          agentSkills,
+        });
+        if (
+          decision.purpose_change_state === "same_purpose" &&
+          decision.confidence >= PURPOSE_STABILITY_CONFIDENCE_THRESHOLD
+        ) {
+          plans.set(route.operation_source_key, {
+            origin: "unchanged_route_reused",
+            purpose_change_state: "same_purpose",
+            active_semantic_source: "previous_reused",
+            stability_confidence: decision.confidence,
+            stability_missing_context: decision.missing_context,
+            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(
+              `Periodic full purpose check confirmed previous semantics still apply: ${decision.reason}`,
+              route,
+            ),
+          });
+          continue;
+        }
+        if (
+          decision.decision === "regenerate" &&
+          decision.confidence >= PURPOSE_STABILITY_CONFIDENCE_THRESHOLD
+        ) {
+          plans.set(route.operation_source_key, {
+            origin: "changed_route_semantic_regenerated",
+            purpose_change_state: decision.purpose_change_state,
+            active_semantic_source: "new_confirmed",
+            stability_confidence: decision.confidence,
+            stability_missing_context: decision.missing_context,
+            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(decision.reason, route),
+          });
+          routesRequiringGeneration.push(route);
+          continue;
+        }
+        plans.set(route.operation_source_key, {
+          origin: "changed_route_needs_review",
+          purpose_change_state: "insufficient_evidence",
+          active_semantic_source: "previous_kept_pending_review",
+          stability_confidence: decision.confidence,
+          stability_missing_context: decision.missing_context,
+          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(
+            `Periodic full purpose check could not prove a purpose-level change: ${decision.reason}`,
+            route,
+          ),
+        });
+        continue;
+      }
       plans.set(route.operation_source_key, {
         origin: "unchanged_route_reused",
         purpose_change_state: "same_purpose",
@@ -2775,6 +2874,19 @@ const withStabilityMetadata = ({ route, currentRoute, plan }) => ({
   evidence_packet_summary: buildEvidencePacketSummary(currentRoute),
 });
 
+const unconfirmedFallbackPlan = ({ plan, reason }) => ({
+  ...plan,
+  origin: "fallback",
+  purpose_change_state: "insufficient_evidence",
+  active_semantic_source: "new_unconfirmed",
+  stability_confidence: 0,
+  stability_missing_context: [
+    ...safeArray(plan.stability_missing_context),
+    "AI route semantic generation did not produce usable active semantics.",
+  ],
+  semantic_change_reason: reason,
+});
+
 const fieldPathMatchesKeys = ({
   fieldPath,
   routeKeys,
@@ -3168,6 +3280,31 @@ const sendSnapshot = async ({ request, env, snapshot }) => {
   }
 };
 
+const routeHasUsableActiveSemantics = (route) =>
+  route.semantics.route_confidence > 0 ||
+  safeArray(route.operation_effects).length > 0 ||
+  ["previous_reused", "previous_kept_pending_review"].includes(
+    route.active_semantic_source,
+  );
+
+const assertSemanticSnapshotUploadable = (snapshot) => {
+  const authFailureRoute = snapshot.routes.find((route) =>
+    /provider_(401|403)\b/.test(route.confidence_reason ?? ""),
+  );
+  if (authFailureRoute) {
+    throw new Error(
+      `semantic snapshot generation failed before upload: AI provider authentication failed for ${authFailureRoute.operation_source_key}`,
+    );
+  }
+  const usableRouteCount = snapshot.routes.filter(routeHasUsableActiveSemantics)
+    .length;
+  if (snapshot.routes.length > 0 && usableRouteCount === 0) {
+    throw new Error(
+      "semantic snapshot generation produced zero usable route semantics; refusing upload",
+    );
+  }
+};
+
 const assertSemanticSnapshotAudit = ({
   routes,
   snapshot,
@@ -3186,12 +3323,17 @@ const assertSemanticSnapshotAudit = ({
   const routeByKey = new Map(
     routes.map((route) => [route.operation_source_key, route]),
   );
+  const previousActiveSources = new Set([
+    "previous_reused",
+    "previous_kept_pending_review",
+  ]);
   const allowedOrigins = new Set([
     "new_route_ai_generated",
     "unchanged_route_reused",
     "changed_route_semantic_reused",
     "changed_route_semantic_regenerated",
     "changed_route_needs_review",
+    "fallback",
   ]);
   for (const route of auditedSnapshot.routes) {
     const currentRoute = routeByKey.get(route.operation_source_key);
@@ -3216,6 +3358,75 @@ const assertSemanticSnapshotAudit = ({
         `semantic snapshot audit found stale route_semantic_hash: ${route.operation_source_key}`,
       );
     }
+    if (auditedSnapshot.schema_version >= 3) {
+      if (route.semantic_stability.purpose_change_state !== route.purpose_change_state) {
+        throw new Error(
+          `semantic snapshot audit found mismatched purpose stability metadata: ${route.operation_source_key}`,
+        );
+      }
+      if (
+        previousActiveSources.has(route.active_semantic_source) &&
+        (!route.previous_route_input_hash ||
+          !route.previous_route_semantic_hash ||
+          !route.previous_semantic_snapshot_version)
+      ) {
+        throw new Error(
+          `semantic snapshot audit found incomplete previous active semantic metadata: ${route.operation_source_key}`,
+        );
+      }
+      if (
+        previousActiveSources.has(route.active_semantic_source) &&
+        route.route_semantic_hash !== route.previous_route_semantic_hash
+      ) {
+        throw new Error(
+          `semantic snapshot audit found changed active semantics for previous-backed route: ${route.operation_source_key}`,
+        );
+      }
+      if (
+        route.active_semantic_source === "previous_kept_pending_review" &&
+        (route.purpose_change_state !== "insufficient_evidence" ||
+          route.semantic_origin !== "changed_route_needs_review")
+      ) {
+        throw new Error(
+          `semantic snapshot audit found inconsistent pending-review semantics: ${route.operation_source_key}`,
+        );
+      }
+      if (
+        route.active_semantic_source === "previous_reused" &&
+        route.purpose_change_state !== "same_purpose"
+      ) {
+        throw new Error(
+          `semantic snapshot audit found inconsistent reused semantics: ${route.operation_source_key}`,
+        );
+      }
+      if (
+        route.purpose_change_state === "purpose_added" &&
+        (!route.previous_route_input_hash || !route.previous_route_semantic_hash)
+      ) {
+        throw new Error(
+          `semantic snapshot audit found missing previous metadata for added purpose: ${route.operation_source_key}`,
+        );
+      }
+      if (
+        route.active_semantic_source === "new_confirmed" &&
+        route.semantics.route_confidence === 0 &&
+        safeArray(route.operation_effects).length === 0
+      ) {
+        throw new Error(
+          `semantic snapshot audit found confirmed semantics without usable evidence: ${route.operation_source_key}`,
+        );
+      }
+      if (
+        route.active_semantic_source === "new_unconfirmed" &&
+        (route.semantic_origin !== "fallback" ||
+          route.purpose_change_state !== "insufficient_evidence" ||
+          route.semantic_stability.confidence !== 0)
+      ) {
+        throw new Error(
+          `semantic snapshot audit found inconsistent unconfirmed fallback semantics: ${route.operation_source_key}`,
+        );
+      }
+    }
     if (
       (route.semantic_origin === "unchanged_route_reused" ||
         route.semantic_origin === "changed_route_semantic_reused") &&
@@ -3272,12 +3483,14 @@ export const runSemanticCi = async ({
       ? await fetchLatestSnapshot({ request, env })
       : validatePreviousSnapshotForReuse(providedPreviousSnapshot);
   const previousRoutes = previousRouteMap(previousSnapshot);
+  const purposeRecheckAllRoutes = shouldPurposeRecheckAllRoutes(env);
   const routeNeedsAi = routes.some((route) => {
     const previousRoute = previousRoutes.get(route.operation_source_key);
     return (
       !previousRoute ||
       previousRoute.route_input_hash !== routeInputHash(route) ||
-      !hasReusablePreviousRouteSemantics(previousRoute)
+      !hasReusablePreviousRouteSemantics(previousRoute) ||
+      purposeRecheckAllRoutes
     );
   });
   if (routeNeedsAi && !env.CLUE_AI_PROVIDER_API_KEY) {
@@ -3310,6 +3523,7 @@ export const runSemanticCi = async ({
     hashScope,
     generationContract,
     agentSkills,
+    purposeRecheckAllRoutes,
   });
   const promptRoutes = routesRequiringGeneration.map((route) =>
     buildRouteEvidencePromptEntry({ route, hashScope }),
@@ -3360,6 +3574,7 @@ export const runSemanticCi = async ({
     generationContract,
     aiRuntime,
   });
+  assertSemanticSnapshotUploadable(snapshot);
   const upload = await sendSnapshot({ request, env, snapshot });
   return {
     accepted: upload.accepted === true,