feat: explain deterministic unknown selection

lib/graph/orchestrator.js

@@ -17,6 +17,7 @@ import { applyValidatedProposal } from "./apply-proposal.js";
 import { buildGraphUpdatePrompt } from "./prompt-builder.js";
 import { parseGraphUpdateProposal } from "./update-proposal.js";
 import {
+  explainUnknownSelection,
   selectActiveUnknownCandidate,
   validateGraphReferences,
 } from "./utils.js";
@@ -31,7 +32,12 @@ function toValidationErrors(error) {
   );
 }
 
-function buildDiagnostics({ analysis, graph, graphReferenceValidation }) {
+function buildDiagnostics({
+  analysis,
+  graph,
+  graphReferenceValidation,
+  unknownSelectionExplanation,
+}) {
   return {
     promptVersion: analysis?.promptVersion ?? null,
     modelName: analysis?.modelName ?? null,
@@ -43,6 +49,7 @@ function buildDiagnostics({ analysis, graph, graphReferenceValidation }) {
     compatibilityApplied: analysis?.compatibilityApplied ?? false,
     compatibilityChanges: analysis?.compatibilityChanges ?? [],
     compatibilityWarnings: analysis?.compatibilityWarnings ?? [],
+    unknownSelectionExplanation: unknownSelectionExplanation ?? null,
   };
 }
 
@@ -54,6 +61,7 @@ function buildUpdateDiagnostics({
   graph,
   graphReferenceValidation,
   selectedQuestion,
+  unknownSelectionExplanation,
 }) {
   return {
     promptVersion: promptVersion ?? "v0.4",
@@ -71,6 +79,7 @@ function buildUpdateDiagnostics({
       selectedQuestion?.investigationStrategy ??
       selectedQuestion?.strategy ??
       null,
+    unknownSelectionExplanation: unknownSelectionExplanation ?? null,
   };
 }
 
@@ -131,6 +140,10 @@ export async function startCase(body) {
   situationGraphSchema.parse(situationGraph);
 
   const graphReferenceValidation = validateGraphReferences(situationGraph);
+  const unknownSelectionExplanation = explainUnknownSelection(
+    situationGraph,
+    [],
+  );
   if (!graphReferenceValidation.valid) {
     return {
       success: false,
@@ -139,6 +152,7 @@ export async function startCase(body) {
         analysis,
         graph: situationGraph,
         graphReferenceValidation,
+        unknownSelectionExplanation,
       }),
       validationErrors: graphReferenceValidation.errors,
       statusCode: 500,
@@ -153,6 +167,7 @@ export async function startCase(body) {
       analysis,
       graph: situationGraph,
       graphReferenceValidation,
+      unknownSelectionExplanation,
     }),
   };
 }
@@ -290,6 +305,10 @@ async function updateCaseWithDependencies(body, dependencies = {}) {
             graph: situationGraph,
             graphReferenceValidation: graphReferenceValidation,
             selectedQuestion: null,
+            unknownSelectionExplanation: explainUnknownSelection(
+              situationGraph,
+              situationGraph.resolvedNodeIds || [],
+            ),
           }),
         },
         statusCode:
@@ -320,6 +339,10 @@ async function updateCaseWithDependencies(body, dependencies = {}) {
         graph: applicationResult.updatedSituationGraph,
         graphReferenceValidation: applicationResult.graphReferenceValidation,
         selectedQuestion: applicationResult.selectedQuestion,
+        unknownSelectionExplanation: explainUnknownSelection(
+          applicationResult.updatedSituationGraph,
+          applicationResult.updatedSituationGraph.resolvedNodeIds || [],
+        ),
       }),
     };
   }
@@ -336,6 +359,10 @@ async function updateCaseWithDependencies(body, dependencies = {}) {
       graph: situationGraph,
       graphReferenceValidation,
       selectedQuestion: null,
+      unknownSelectionExplanation: explainUnknownSelection(
+        situationGraph,
+        situationGraph.resolvedNodeIds || [],
+      ),
     }),
   };
 }