@duckcodeailabs/dql-agent 1.9.5 → 1.10.0

package/dist/answer-loop.js

@@ -41,6 +41,9 @@ import { questionTypeFromText } from './meaning-resolution.js';
 import { cascadeTraceToEvidenceRouteSteps, createCascadeAnswerResult, createCascadeTrace, } from './cascade/cascade.js';
 import { shouldClarifyBeforeGeneration } from './cascade/triage.js';
 import { stampTrustLabel } from './trust/stamp.js';
+import { deriveResolvedAnalyticalPlan } from './resolved-analytical-plan.js';
+import { adaptResolvedAnalyticalPlan, buildPlanExecutionRegistry, } from './plan-execution-adapter.js';
+import { buildGovernedRelationalRegistry, compileGovernedRelationalPlan, finalizeGovernedCompilationReceipt, renderGovernedRelationalDqlArtifact, } from './governed-relational-compiler.js';
 import { QUICK_PROMPT_CONTEXT_BUDGET, canUseLaneRepair, cascadeBudgetTrace, createCascadeBudgetState, deepAlternativeCountForQuestion, promptContextBudgetForQuestion, proposalToolBudgetForQuestion, recordLaneRepair, } from './cascade/budgets.js';
 /**
  * Physical column names whose sampled runtime values include `value`. Used by the
@@ -460,13 +463,126 @@ function tryCrossResultAnswer(input) {
     }
     return answer;
 }
+/**
+ * Materialize exactly the Skill IDs/hashes selected in the immutable context
+ * pack. No downstream answer route may rerun trigger/domain selection or add a
+ * Skill that was not recorded in the KnowledgeLens.
+ *
+ * Acceptance: SKILL-003, AGT-013.
+ */
+export function materializeKnowledgeLensSkills(contextPack, available) {
+    const byIdentity = new Map();
+    for (const skill of available) {
+        byIdentity.set(skill.qualifiedId ?? skill.id, skill);
+        if (!byIdentity.has(skill.id))
+            byIdentity.set(skill.id, skill);
+    }
+    return (contextPack.skills ?? []).map((selected) => {
+        const identity = selected.qualifiedId ?? selected.id;
+        const source = byIdentity.get(identity) ?? byIdentity.get(selected.id);
+        if (source) {
+            // Guidance is the immutable, bounded snapshot body. Retain structured
+            // source fields but never reread or inject a newer disk body mid-run.
+            return { ...source, body: selected.guidance };
+        }
+        return {
+            id: selected.id,
+            localId: selected.id,
+            qualifiedId: selected.qualifiedId,
+            scope: 'project',
+            domain: selected.domain,
+            domains: selected.domains,
+            modelAreaRefs: selected.modelAreaRefs,
+            kind: selected.kind,
+            status: selected.status,
+            owner: selected.owner,
+            triggers: selected.triggers,
+            exclusions: selected.exclusions,
+            description: selected.description,
+            preferredMetrics: selected.preferredMetrics,
+            preferredBlocks: selected.preferredBlocks,
+            preferredDimensions: selected.preferredDimensions,
+            requiredFilters: selected.requiredFilters,
+            clarifyWhen: selected.clarifyWhen,
+            examples: [],
+            sourceRefs: selected.sourceRefs,
+            vocabulary: selected.vocabulary,
+            body: selected.guidance,
+            sourcePath: selected.sourcePath ?? `snapshot:${selected.objectKey}`,
+        };
+    });
+}
 export async function answer(input) {
+    const inheritedPlan = !input.resolvedAnalyticalPlan
+        && input.followUp?.priorResolvedAnalyticalPlan
+        && input.followUp.resolvedAnalyticalPlanDelta
+        ? deriveResolvedAnalyticalPlan(input.followUp.priorResolvedAnalyticalPlan, input.followUp.resolvedAnalyticalPlanDelta)
+        : undefined;
+    const normalizedInput = inheritedPlan
+        ? { ...input, resolvedAnalyticalPlan: inheritedPlan }
+        : input;
+    const resolvedPlanExecutionBinding = normalizedInput.resolvedAnalyticalPlan
+        ? adaptResolvedAnalyticalPlan({
+            plan: normalizedInput.resolvedAnalyticalPlan,
+            registry: buildPlanExecutionRegistry({
+                nodes: [
+                    ...normalizedInput.kg.getNodesByKind('block', 100_000),
+                    ...normalizedInput.kg.getNodesByKind('metric', 100_000),
+                    ...normalizedInput.kg.getNodesByKind('dimension', 100_000),
+                ],
+                objects: normalizedInput.contextPack?.objects,
+            }),
+            semanticLayer: normalizedInput.semanticLayer,
+            expectedSnapshotId: normalizedInput.contextPack?.knowledgeLens.snapshotId,
+        })
+        : undefined;
+    const planBoundInput = resolvedPlanExecutionBinding
+        ? { ...normalizedInput, resolvedPlanExecutionBinding }
+        : normalizedInput;
+    const relationalSchemaContext = planBoundInput.schemaContext?.length
+        ? planBoundInput.schemaContext
+        : (planBoundInput.contextPack?.allowedSqlContext.relations ?? []).map((relation) => ({
+            relation: relation.relation,
+            name: relation.name,
+            columns: relation.columns.map((column) => ({
+                name: column.name,
+                type: column.type,
+                description: column.description,
+            })),
+        }));
+    const governedRelationalCompilation = planBoundInput.resolvedAnalyticalPlan?.mode === 'authoritative'
+        && planBoundInput.resolvedAnalyticalPlan.capability === 'governed_relational'
+        ? compileGovernedRelationalPlan({
+            plan: planBoundInput.resolvedAnalyticalPlan,
+            registry: buildGovernedRelationalRegistry({
+                snapshotId: planBoundInput.resolvedAnalyticalPlan.snapshotId,
+                schemaContext: relationalSchemaContext,
+                manifest: planBoundInput.manifest,
+            }),
+            driver: planBoundInput.semanticDriver,
+        })
+        : undefined;
+    const compiledInput = governedRelationalCompilation
+        ? { ...planBoundInput, governedRelationalCompilation }
+        : planBoundInput;
+    const executionInput = compiledInput.contextPack
+        ? {
+            ...compiledInput,
+            skills: materializeKnowledgeLensSkills(compiledInput.contextPack, compiledInput.skills ?? []),
+            skillsSelectionLocked: true,
+        }
+        : compiledInput;
     // Cross-result follow-up ("of these, the average") — computed from the prior
     // rows, before the cascade, so it never re-queries or times out.
-    const crossResult = tryCrossResultAnswer(input);
-    if (crossResult)
-        return crossResult;
-    const result = applyHollowAnswerGate(await runAnswerLoop(input));
+    const crossResult = tryCrossResultAnswer(executionInput);
+    if (crossResult) {
+        return {
+            ...crossResult,
+            resolvedAnalyticalPlan: executionInput.resolvedAnalyticalPlan,
+            executablePlan: executionInput.resolvedPlanExecutionBinding,
+        };
+    }
+    const result = applyHollowAnswerGate(await runAnswerLoop(executionInput));
     // Attach the canonical trust label once, at the single exit point, so every
     // return site inside runAnswerLoop stays untouched and backward compatible.
     // Freshness-aware trust: for a certified answer, fold the source block's data
@@ -495,6 +611,8 @@ export async function answer(input) {
         ...publicResult,
         domainContext: input.domainContext,
         intentDecision,
+        resolvedAnalyticalPlan: executionInput.resolvedAnalyticalPlan,
+        executablePlan: executionInput.resolvedPlanExecutionBinding,
         trustLabelInfo,
         provenanceFooter: buildProvenanceFooter(result, trustLabelInfo),
         cascade: publicResult.cascade ?? createCascadeAnswerResult({
@@ -514,15 +632,17 @@ export async function answer(input) {
         // Stamp the SELECTED skills that shaped the answer (transparency). Computed
         // here so every return site inside runAnswerLoop stays untouched.
         appliedSkills: result.appliedSkills ??
-            selectRelevantSkills(input.skills ?? [], input.question, {
-                userId: input.userId ?? null,
-                modelAreaIds: input.domainContext?.modelAreaId ? [input.domainContext.modelAreaId] : [],
-                domains: Array.from(new Set([
-                    ...domainContextSearchDomains(input.domainContext),
-                    ...(input.domain ? [input.domain] : []),
-                    ...(input.contextPack?.objects ?? []).slice(0, 20).flatMap((object) => object.domain ? [object.domain] : []),
-                ])),
-            }).map((s) => ({
+            (executionInput.skillsSelectionLocked
+                ? executionInput.skills ?? []
+                : selectRelevantSkills(executionInput.skills ?? [], executionInput.question, {
+                    userId: executionInput.userId ?? null,
+                    modelAreaIds: executionInput.domainContext?.modelAreaId ? [executionInput.domainContext.modelAreaId] : [],
+                    domains: Array.from(new Set([
+                        ...domainContextSearchDomains(executionInput.domainContext),
+                        ...(executionInput.domain ? [executionInput.domain] : []),
+                        ...(executionInput.contextPack?.objects ?? []).slice(0, 20).flatMap((object) => object.domain ? [object.domain] : []),
+                    ])),
+                })).map((s) => ({
                 id: s.id,
                 description: s.description,
             })),
@@ -614,11 +734,13 @@ async function runAnswerLoop(input) {
             ? (input.contextPack?.objects ?? []).slice(0, 20).flatMap((object) => object.domain ? [object.domain] : [])
             : []),
     ]));
-    const selectedSkills = selectRelevantSkills(skills, question, {
-        userId: userId ?? null,
-        domains: inferredDomains,
-        modelAreaIds: input.domainContext?.modelAreaId ? [input.domainContext.modelAreaId] : [],
-    });
+    const selectedSkills = input.skillsSelectionLocked
+        ? skills
+        : selectRelevantSkills(skills, question, {
+            userId: userId ?? null,
+            domains: inferredDomains,
+            modelAreaIds: input.domainContext?.modelAreaId ? [input.domainContext.modelAreaId] : [],
+        });
     const effectiveBlockHints = Array.from(new Set([
         ...blockHints,
         // Only selected skills may influence block ranking. Previously a preferred
@@ -654,6 +776,85 @@ async function runAnswerLoop(input) {
     // columns—not copy a customer-grain worked example into a product-grain ask.
     const promptContextPack = contextPackForRequestedShape(scopedContextPack, question, questionPlan, kg);
     const repairBudgetState = createCascadeBudgetState(input.cascadeBudgetModel);
+    const authoritativePlanBinding = input.resolvedAnalyticalPlan?.mode === 'authoritative'
+        ? input.resolvedPlanExecutionBinding
+        : undefined;
+    const governedRelationalCompilation = input.governedRelationalCompilation;
+    if (governedRelationalCompilation?.status === 'blocked') {
+        const text = `The governed relational plan cannot compile safely: ${governedRelationalCompilation.reason}`;
+        return {
+            kind: 'no_answer',
+            sourceTier: 'no_answer',
+            certification: 'analyst_review_required',
+            reviewStatus: 'none',
+            confidence: 0,
+            text,
+            answer: text,
+            refusalCode: governedRelationalCompilation.code.startsWith('RELATIONSHIP_') ? 'modeling_gap' : 'grounding_gap',
+            refusalDetails: { code: 'grounding_gap', message: `${governedRelationalCompilation.code}: ${governedRelationalCompilation.reason}` },
+            citations: contextPackCitations(input.contextPack, 8),
+            considered,
+            contextPack: input.contextPack,
+            providerUsed: provider.name,
+        };
+    }
+    if (governedRelationalCompilation?.status === 'compiled') {
+        const dqlArtifact = renderGovernedRelationalDqlArtifact(governedRelationalCompilation);
+        let result;
+        let executionError;
+        let receipt = governedRelationalCompilation.receipt;
+        if (input.executeDqlArtifact) {
+            try {
+                result = await input.executeDqlArtifact(dqlArtifact);
+                receipt = finalizeGovernedCompilationReceipt(receipt, result);
+            }
+            catch (error) {
+                executionError = error instanceof Error ? error.message : String(error);
+            }
+        }
+        const text = executionError
+            ? `The governed relational query compiled, but execution failed: ${executionError}`
+            : result
+                ? `Compiled and executed the snapshot-bound governed relational plan. Returned ${result.rowCount} row${result.rowCount === 1 ? '' : 's'}.`
+                : 'Compiled the snapshot-bound governed relational plan. Execution was not requested.';
+        return {
+            kind: executionError ? 'no_answer' : 'uncertified',
+            sourceTier: executionError ? 'no_answer' : 'dbt_manifest',
+            certification: executionError ? 'analyst_review_required' : 'governed',
+            reviewStatus: executionError ? 'analyst_review_required' : 'governed',
+            confidence: executionError ? 0 : 0.9,
+            text,
+            answer: text,
+            ...(executionError ? { executionError, refusalCode: 'grounding_gap' } : {}),
+            proposedSql: governedRelationalCompilation.sql,
+            sql: governedRelationalCompilation.sql,
+            dqlArtifact,
+            result,
+            governedCompilationReceipt: receipt,
+            citations: schemaCitations(schemaContext, 8),
+            considered,
+            contextPack: input.contextPack,
+            providerUsed: provider.name,
+        };
+    }
+    if (authoritativePlanBinding?.status === 'blocked') {
+        const text = `The resolved analytical plan cannot execute safely: ${authoritativePlanBinding.reason}`;
+        return {
+            kind: 'no_answer',
+            sourceTier: 'no_answer',
+            certification: 'analyst_review_required',
+            reviewStatus: 'none',
+            confidence: 0,
+            text,
+            answer: text,
+            refusalCode: authoritativePlanBinding.code === 'PLAN_BLOCKED' ? 'ambiguous' : 'grounding_gap',
+            refusalDetails: { code: authoritativePlanBinding.code, message: authoritativePlanBinding.reason },
+            citations: contextPackCitations(input.contextPack, 8),
+            considered,
+            contextPack: input.contextPack,
+            providerUsed: provider.name,
+        };
+    }
     const fallbackIntent = classifyAgentIntent({
         question,
         followUp: input.followUp,
@@ -673,16 +874,25 @@ async function runAnswerLoop(input) {
         if (node && !semanticMetricNodes.some((candidate) => candidate.nodeId === node.nodeId))
             semanticMetricNodes.push(node);
     }
-    const preferredSemanticMetric = resolvePreferredSemanticMetric([input.preferredExecutionId, ...(input.preferredEvidenceIds ?? [])], semanticMetricNodes, kg);
+    const authoritativeSemanticBinding = authoritativePlanBinding?.status === 'ready'
+        && authoritativePlanBinding.kind === 'semantic'
+        ? authoritativePlanBinding
+        : undefined;
+    const preferredSemanticMetric = authoritativeSemanticBinding?.metricNode
+        ?? (input.resolvedAnalyticalPlan?.mode === 'authoritative'
+            ? undefined
+            : resolvePreferredSemanticMetric([input.preferredExecutionId, ...(input.preferredEvidenceIds ?? [])], semanticMetricNodes, kg));
     const semanticLayerForExec = input.semanticLayer;
     const canExecuteSemanticMetricForMatch = input.canExecuteSemanticMetric
         ?? (semanticLayerForExec ? (name) => semanticLayerForExec.canComposeMetric(name) : undefined);
     let semanticMetricMatch = preferredSemanticMetric
         ? { metric: preferredSemanticMetric, score: 1, basis: 'name' }
-        : await matchSemanticMetric(semanticQuestion, semanticMetricNodes, {
-            measureTerms: [...questionPlan.requestedShape.measures, ...questionPlan.metricTerms],
-            ...(canExecuteSemanticMetricForMatch ? { canExecute: canExecuteSemanticMetricForMatch } : {}),
-        }).catch(() => null);
+        : input.resolvedAnalyticalPlan?.mode === 'authoritative'
+            ? null
+            : await matchSemanticMetric(semanticQuestion, semanticMetricNodes, {
+                measureTerms: [...questionPlan.requestedShape.measures, ...questionPlan.metricTerms],
+                ...(canExecuteSemanticMetricForMatch ? { canExecute: canExecuteSemanticMetricForMatch } : {}),
+            }).catch(() => null);
     // Stage 1: certified artifact match. Blocks can be executed; dashboards,
     // Apps, and notebooks are returned as governed citations/navigation targets.
     const drilldownCertifiedHit = input.followUp?.kind === 'drilldown'
@@ -726,8 +936,16 @@ async function runAnswerLoop(input) {
         excludedArtifactIds,
         kg,
     }) : null;
-    let artifactHit = drilldownCertifiedHit ?? unsafeCatalogCertifiedHit
-        ?? (catalogCertifiedHit ? null : fallbackCertifiedHit);
+    const authoritativeCertifiedBinding = authoritativePlanBinding?.status === 'ready'
+        && authoritativePlanBinding.kind === 'certified'
+        ? authoritativePlanBinding
+        : undefined;
+    let artifactHit = authoritativeCertifiedBinding
+        ? { node: authoritativeCertifiedBinding.node, score: 1 }
+        : input.resolvedAnalyticalPlan?.mode === 'authoritative'
+            ? null
+            : drilldownCertifiedHit ?? unsafeCatalogCertifiedHit
+                ?? (catalogCertifiedHit ? null : fallbackCertifiedHit);
     let certifiedExecutionFallback;
     // Certified remains first when it actually covers the question. If the
     // retrieved block does not fit but a governed semantic metric does, never
@@ -875,8 +1093,10 @@ async function runAnswerLoop(input) {
         const dqlArtifact = buildCertifiedBlockDqlArtifact(artifactHit.node, result, questionPlan.requestedShape.topN?.scope === 'per_group'
             ? undefined
             : questionPlan.requestedShape.topN?.n);
+        const authoritativeCertifiedFailure = Boolean(authoritativeCertifiedBinding && executionError);
         const recoverableCertifiedFailure = artifactHit.node.kind === 'block'
             && executionError !== undefined
+            && !authoritativeCertifiedFailure
             && isRetryableCertifiedExecutionError(executionError);
         if (recoverableCertifiedFailure) {
             // A certified artifact is trusted evidence, not an obligation to return a
@@ -889,16 +1109,17 @@ async function runAnswerLoop(input) {
         }
         else {
             return {
-                kind: certifiedShapePassed ? 'certified' : 'uncertified',
-                sourceTier,
+                kind: authoritativeCertifiedFailure ? 'no_answer' : certifiedShapePassed ? 'certified' : 'uncertified',
+                sourceTier: authoritativeCertifiedFailure ? 'no_answer' : sourceTier,
                 certification: certifiedShapePassed ? 'certified' : 'analyst_review_required',
-                reviewStatus: certifiedShapePassed ? 'certified' : 'analyst_review_required',
+                reviewStatus: authoritativeCertifiedFailure ? 'none' : certifiedShapePassed ? 'certified' : 'analyst_review_required',
                 confidence: certifiedShapePassed ? 0.95 : 0.45,
                 text,
                 answer: text,
                 block: artifactHit.node.kind === 'block' ? artifactHit.node : undefined,
                 result,
                 executionError,
+                ...(authoritativeCertifiedFailure ? { refusalCode: 'grounding_gap' } : {}),
                 sql: result?.sql,
                 dqlArtifact,
                 trustLabel: certifiedShapePassed ? input.contextPack?.trustLabel ?? 'certified' : 'mixed',
@@ -1095,7 +1316,44 @@ async function runAnswerLoop(input) {
     let semanticBridgeAnswer;
     let semanticRuntimeFailure;
     let semanticRuntimeCompiledAnswer = false;
-    if (input.semanticLayer && semanticMetricMatch) {
+    if (authoritativeSemanticBinding && input.semanticLayer) {
+        const selection = authoritativeSemanticBinding.selection;
+        semanticBridgeAnswer = composeSemanticQueryFromMembers({
+            semanticLayer: input.semanticLayer,
+            question,
+            selection,
+            ...(input.semanticDriver ? { driver: input.semanticDriver } : {}),
+            ...(input.semanticTableMapping ? { tableMapping: input.semanticTableMapping } : {}),
+        });
+        if (!semanticBridgeAnswer && input.semanticQueryCompiler) {
+            try {
+                const compiled = await input.semanticQueryCompiler(selection);
+                semanticBridgeAnswer = composeSemanticQueryFromCompiledMembers({
+                    semanticLayer: input.semanticLayer,
+                    question,
+                    selection: compiled.selection ?? selection,
+                    sql: compiled.sql,
+                });
+                semanticRuntimeCompiledAnswer = Boolean(semanticBridgeAnswer && compiled.engine !== 'native');
+            }
+            catch (error) {
+                semanticRuntimeFailure = error instanceof Error ? error.message : String(error);
+            }
+        }
+        if (semanticBridgeAnswer) {
+            semanticBridgeToolCalls.push({
+                name: 'compile_resolved_analytical_plan',
+                status: 'checked',
+                inputSummary: `plan: ${authoritativeSemanticBinding.planId}; metric: ${selection.metrics.join(', ')}`,
+                outputSummary: 'Compiled the exact snapshot-bound member selection without rematching.',
+                order: 1,
+            });
+        }
+        else if (!semanticRuntimeFailure) {
+            semanticRuntimeFailure = `The exact plan ${authoritativeSemanticBinding.planId} is not composable by the pinned semantic runtime.`;
+        }
+    }
+    if (!authoritativeSemanticBinding && input.semanticLayer && semanticMetricMatch) {
         semanticBridgeAnswer = composeSemanticQueryForQuestion({
             semanticLayer: input.semanticLayer,
             question,
@@ -2146,7 +2404,7 @@ async function runAnswerLoop(input) {
         catch (err) {
             executionError = err instanceof Error ? err.message : String(err);
         }
-        if (executionError && !fanoutContradiction) {
+        if (executionError && !fanoutContradiction && !authoritativeSemanticBinding) {
             if (isRetryableGeneratedSqlError(executionError)) {
                 const localRepairSql = repairGeneratedSqlLocally(parsed.sql, executionError, schemaContext);
                 if (localRepairSql && canUseLaneRepair(repairBudgetState, 'execution')) {
@@ -2368,19 +2626,21 @@ async function runAnswerLoop(input) {
         ? semanticMetricMatch?.metric.certification
         : undefined;
     const certifiedMetricAnswer = semanticMetricCertification === 'certified' || semanticMetricCertification === 'reviewed';
+    const governedMetricExecutionFailure = governedMetricAnswer && Boolean(executionError);
     return {
-        kind: 'uncertified',
-        sourceTier: governedMetricAnswer ? 'semantic_layer' : activeTier,
-        certification: governedMetricAnswer ? 'governed' : 'ai_generated',
-        reviewStatus: governedMetricAnswer ? 'governed' : 'draft_ready',
+        kind: governedMetricExecutionFailure ? 'no_answer' : 'uncertified',
+        sourceTier: governedMetricExecutionFailure ? 'no_answer' : governedMetricAnswer ? 'semantic_layer' : activeTier,
+        certification: governedMetricExecutionFailure ? 'analyst_review_required' : governedMetricAnswer ? 'governed' : 'ai_generated',
+        reviewStatus: governedMetricExecutionFailure ? 'none' : governedMetricAnswer ? 'governed' : 'draft_ready',
         semanticMetricCertification,
-        confidence: certifiedMetricAnswer ? 0.8 : governedMetricAnswer ? 0.72 : 0.55,
+        confidence: governedMetricExecutionFailure ? 0 : certifiedMetricAnswer ? 0.8 : governedMetricAnswer ? 0.72 : 0.55,
         text: generatedText,
         answer: generatedText,
         proposedSql: parsed.sql,
         sql: parsed.sql,
         result,
         executionError,
+        ...(governedMetricExecutionFailure ? { refusalCode: 'grounding_gap' } : {}),
         suggestedViz: parsed.viz ?? 'table',
         dqlArtifact: answerDqlArtifact,
         draftBlock,