@duckcodeailabs/dql-agent 1.9.4 → 1.10.0

package/dist/answer-loop.js

@@ -17,6 +17,7 @@
 import { describeDialectForPrompt, } from '@duckcodeailabs/dql-core';
 import { buildSkillBlockHints, buildSkillMetricHints, buildSkillsPrompt, expandQuestionWithSkillVocabulary, selectRelevantSkills } from './skills/loader.js';
 import { detectResultSetOperation, computeResultSetOperation } from './conversation/result-ops.js';
+import { classifyGovernedQueryShape } from './semantic-bridge/query-shape.js';
 import { domainContextSearchDomains } from './domain-context.js';
 import { deriveGeneratedDraftSlug, renderGeneratedSqlDqlArtifact } from './metadata/drafts.js';
 import { buildAnalysisQuestionPlan } from './metadata/analysis-planner.js';
@@ -40,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
@@ -459,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
@@ -494,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({
@@ -513,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,
             })),
@@ -613,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
@@ -653,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,
@@ -672,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'
@@ -725,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
@@ -874,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
@@ -888,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',
@@ -1094,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,
@@ -1152,16 +1411,19 @@ async function runAnswerLoop(input) {
         // spend another model call re-selecting the same member or silently fall
         // into exploratory SQL; surface the compiler's actionable error instead.
         if (!semanticBridgeAnswer && !semanticRuntimeFailure) {
-            const selection = await selectSemanticMembersViaLlm({
-                provider,
-                semanticLayer: input.semanticLayer,
-                question,
-                signal: input.signal,
-                reasoningEffort: input.reasoningEffort,
-            });
-            if (selection) {
+            const requestedGroupingDims = requestedGroupingDimensions(questionPlan);
+            const wantedBreakdown = questionPlan.requestedShape.dimensions.length > 0
+                || questionPlan.dimensionTerms.length > 0;
+            const requiredGroupingCount = requestedGroupingDims.length;
+            // Capture the narrowed semantic layer so the async closure below keeps the
+            // non-undefined type (TS resets narrowing across closure boundaries).
+            const bridgeLayer = input.semanticLayer;
+            // Compose a member selection: native first, then the runtime compiler for
+            // metrics native can't express. Side effects (runtime flags, tool calls)
+            // are recorded here so a retry reruns them cleanly.
+            const composeSelection = async (selection) => {
                 let composed = composeSemanticQueryFromMembers({
-                    semanticLayer: input.semanticLayer,
+                    semanticLayer: bridgeLayer,
                     question,
                     selection,
                     ...(input.semanticDriver ? { driver: input.semanticDriver } : {}),
@@ -1171,7 +1433,7 @@ async function runAnswerLoop(input) {
                     try {
                         const compiled = await input.semanticQueryCompiler(selection);
                         composed = composeSemanticQueryFromCompiledMembers({
-                            semanticLayer: input.semanticLayer,
+                            semanticLayer: bridgeLayer,
                             question,
                             selection: compiled.selection ?? selection,
                             sql: compiled.sql,
@@ -1191,18 +1453,44 @@ async function runAnswerLoop(input) {
                         semanticRuntimeFailure = error instanceof Error ? error.message : String(error);
                     }
                 }
-                // Coverage guard: if the question asked for a breakdown but the LLM
-                // selection produced none, the governed answer would silently DROP the
-                // requested grouping (governed-but-wrong). Fall through to Lane-3
-                // generation, which can express the breakdown.
-                const wantedBreakdown = questionPlan.requestedShape.dimensions.length > 0
-                    || questionPlan.dimensionTerms.length > 0;
-                const requiredGroupingCount = requestedGroupingDimensions(questionPlan).length;
-                const dropsBreakdown = Boolean(composed)
-                    && wantedBreakdown
-                    && composed.dimensions.length < Math.max(1, requiredGroupingCount)
-                    && !composed.timeDimension;
-                if (composed && !dropsBreakdown) {
+                return composed;
+            };
+            // A governed answer that silently DROPS the requested grouping is governed-
+            // but-wrong. Detect it so we retry (forcing the breakdown) rather than
+            // adopting a scalar answer to a breakdown question.
+            const dropsBreakdown = (composed) => Boolean(composed) && wantedBreakdown
+                && composed.dimensions.length < Math.max(1, requiredGroupingCount)
+                && !composed.timeDimension;
+            let selection = await selectSemanticMembersViaLlm({
+                provider,
+                semanticLayer: input.semanticLayer,
+                question,
+                signal: input.signal,
+                reasoningEffort: input.reasoningEffort,
+            });
+            if (selection) {
+                let composed = await composeSelection(selection);
+                // Retry ONCE forcing the requested breakdown dimensions before giving up
+                // on the governed lane — the model sometimes omits a group-by it could
+                // have kept. If it still can't, the Tier-2.5 gate decides refuse-vs-SQL.
+                if (composed && dropsBreakdown(composed) && requestedGroupingDims.length > 0 && !semanticRuntimeFailure) {
+                    const retry = await selectSemanticMembersViaLlm({
+                        provider,
+                        semanticLayer: input.semanticLayer,
+                        question,
+                        signal: input.signal,
+                        reasoningEffort: input.reasoningEffort,
+                        requireDimensions: requestedGroupingDims,
+                    });
+                    if (retry) {
+                        const retryComposed = await composeSelection(retry);
+                        if (retryComposed && !dropsBreakdown(retryComposed)) {
+                            composed = retryComposed;
+                            selection = retry;
+                        }
+                    }
+                }
+                if (composed && !dropsBreakdown(composed)) {
                     semanticBridgeAnswer = composed;
                     semanticBridgeToolCalls.push({
                         name: 'query_semantic_model',
@@ -1345,6 +1633,40 @@ async function runAnswerLoop(input) {
         // measure and only generates the join/grouping around it. Keeps the number
         // consistent with the governed metric. Degrades to plain generation when the metric
         // has no resolvable definition. The grain ledger + validation still gate the output.
+        // Structured-selection gate: a governed metric matched but the compiler-owned
+        // lanes above all failed. Refuse-with-reason ONLY when we are CONFIDENT the
+        // failure is a MODELING gap — the requested breakdown resolves to a DECLARED
+        // dimension the semantic models can't join to this metric (no_join_path). In
+        // that one case free SQL would misjoin or reference an ambiguous column, so we
+        // list the connected dimensions instead of guessing. Everything else — a
+        // paraphrase the compile tool can still resolve, a raw column answerable by
+        // safe single-table SQL, a genuine compiler gap (per-group topN/arithmetic/
+        // window/HAVING), or a derived metric needing the runtime — keeps its existing
+        // path (the compile_semantic_query tool + metric-anchored generation below).
+        if (input.semanticLayer && semanticMetricMatch) {
+            const shape = classifyGovernedQueryShape(questionPlan, semanticMetricMatch.metric.name, input.semanticLayer);
+            const modelingGap = shape === 'genuine_gap'
+                ? undefined
+                : resolveModelingGap(questionPlan, semanticMetricMatch.metric.name, input.semanticLayer);
+            if (modelingGap) {
+                return buildModelingGapRefusal({
+                    question,
+                    metricName: modelingGap.metricName,
+                    incompatibleDimension: modelingGap.incompatibleDim,
+                    semanticLayer: input.semanticLayer,
+                    questionPlan,
+                    contextPack: input.contextPack,
+                    considered,
+                    memoryContext: input.memoryContext,
+                    artifactHits,
+                    businessHits,
+                    semanticHits,
+                    manifestHits,
+                    toolCalls: semanticBridgeToolCalls,
+                    providerName: provider.name,
+                });
+            }
+        }
         const metricAnchor = semanticMetricMatch && input.semanticLayer
             ? resolveGovernedMetricDefinition(semanticMetricMatch.metric, semanticMetricNodes, input.semanticLayer)
             : undefined;
@@ -2082,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')) {
@@ -2304,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,
@@ -4972,6 +5296,115 @@ function isRetryableCertifiedExecutionError(error) {
         || /\bcolumn\b.*\b(?:not\s+found|does\s+not\s+exist|not\s+recognized|unknown)\b/i.test(error)
         || /\btable\b.*\b(?:not\s+found|does\s+not\s+exist|unknown)\b/i.test(error);
 }
+/**
+ * A governed metric matched, the compiler-owned lanes couldn't build the exact
+ * shape, and the shape is one the compiler SHOULD handle — so the gap is a
+ * missing join/model relationship, not a reason to guess SQL. Refuse with the
+ * connected dimensions so the user knows exactly what to add. Mirrors the
+ * AGT-005 semantic-runtime-failure no_answer shape.
+ */
+/**
+ * Confident modeling-gap detector: does the requested breakdown resolve to a
+ * DECLARED dimension the semantic models can't join to this metric? Only then is
+ * a compose failure a real modeling gap (list the connected dims, refuse) rather
+ * than a paraphrase the compile tool can resolve or a raw column safe SQL can
+ * answer. Matching is intentionally CONSERVATIVE (name/label/qualified equality),
+ * so an uncertain match falls through to generation — never a false refusal.
+ */
+function resolveModelingGap(questionPlan, metricName, semanticLayer) {
+    const canonical = semanticLayer.listMetrics().find((metric) => metric.name === metricName
+        || metric.name.endsWith(`.${metricName}`)
+        || metricName.endsWith(`.${metric.name}`))?.name ?? metricName;
+    let explained;
+    try {
+        explained = semanticLayer.explainCompatibleDimensions([canonical]);
+    }
+    catch {
+        return undefined;
+    }
+    const { compatible, incompatible } = explained;
+    // A declared dimension the join graph can't reach from this metric. Ignore
+    // metric_unresolved (a name-resolution miss, not a user-facing modeling gap).
+    const gappy = incompatible.filter((dim) => dim.reason === 'no_join_path' || dim.reason === 'not_shared_across_metrics');
+    if (gappy.length === 0)
+        return undefined;
+    const requested = [
+        ...questionPlan.requestedShape.dimensions,
+        ...questionPlan.dimensionTerms,
+    ].map((value) => value.trim()).filter(Boolean);
+    if (requested.length === 0)
+        return undefined;
+    const lastSegment = (name) => name?.split(/[._]/).pop();
+    const matchesDim = (phrase, dim) => conceptsEquivalent(phrase, dim.name)
+        || (dim.label ? conceptsEquivalent(phrase, dim.label) : false)
+        || (dim.qualifiedName ? conceptsEquivalent(phrase, dim.qualifiedName) : false)
+        || (lastSegment(dim.qualifiedName) ? conceptsEquivalent(phrase, lastSegment(dim.qualifiedName)) : false);
+    for (const phrase of requested) {
+        // A phrase that also matches a CONNECTED dimension is not a gap — the compose/
+        // retry lane owns it. Only refuse when the phrase matches an unconnected dim
+        // and nothing connected.
+        if (compatible.some((dim) => matchesDim(phrase, dim)))
+            continue;
+        const hit = gappy.find((dim) => matchesDim(phrase, dim));
+        if (hit) {
+            const connected = compatible.map((dim) => dim.label || dim.name).slice(0, 12);
+            return { metricName: canonical, incompatibleDim: hit.name, connected };
+        }
+    }
+    return undefined;
+}
+function buildModelingGapRefusal(input) {
+    const compatible = (() => {
+        try {
+            return input.semanticLayer.explainCompatibleDimensions([input.metricName]).compatible;
+        }
+        catch {
+            return [];
+        }
+    })();
+    const connected = compatible.map((dimension) => dimension.label || dimension.name).slice(0, 12);
+    const requested = [
+        ...input.questionPlan.requestedShape.dimensions,
+        ...input.questionPlan.dimensionTerms,
+    ].filter((value, index, all) => value && all.indexOf(value) === index);
+    const requestedText = input.incompatibleDimension
+        ? `by ${input.incompatibleDimension}`
+        : requested.length > 0 ? `by ${requested.join(', ')}` : 'by the requested breakdown';
+    const text = [
+        `“${input.metricName}” can’t be grouped ${requestedText} — the semantic models don’t declare a join path between them.`,
+        connected.length > 0
+            ? `It CAN be grouped by: ${connected.join(', ')}.`
+            : 'No compatible group-by dimension is modeled for this metric.',
+        'To enable this breakdown, add the relationship (a join/entity) in the dbt semantic models and recompile. Nothing was executed.',
+    ].join(' ');
+    return {
+        kind: 'no_answer',
+        sourceTier: 'no_answer',
+        certification: 'analyst_review_required',
+        reviewStatus: 'none',
+        confidence: 0,
+        text,
+        answer: text,
+        refusalCode: 'modeling_gap',
+        refusalDetails: { code: 'modeling_gap', message: text },
+        citations: [],
+        memoryContext: input.memoryContext,
+        evidence: buildNoAnswerEvidence({
+            question: input.question,
+            reason: text,
+            artifactHits: input.artifactHits,
+            businessHits: input.businessHits,
+            semanticHits: input.semanticHits,
+            manifestHits: input.manifestHits,
+            considered: input.considered,
+            memoryContext: input.memoryContext ?? [],
+            toolCalls: input.toolCalls,
+        }),
+        contextPack: input.contextPack,
+        considered: input.considered,
+        providerUsed: input.providerName,
+    };
+}
 function repairGeneratedSqlLocally(sql, error, schemaContext) {
     // Ambiguous column: a bare column exists in more than one joined table (e.g. a
     // conformed `report_as_of_dt` on both the fact and a joined dimension), and the