@duckcodeailabs/dql-agent 1.9.5 → 1.10.1

package/dist/answer-loop.js

@@ -14,7 +14,8 @@
  * step. Tests can mock the provider with a canned response and exercise the
  * full pipeline.
  */
-import { describeDialectForPrompt, } from '@duckcodeailabs/dql-core';
+import { createHash } from 'node:crypto';
+import { describeDialectForPrompt, normalizeMetricCapabilityContract, } 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';
@@ -41,6 +42,13 @@ 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 { adaptAnalyticalFreshnessRequest, adaptAnalyticalSemanticGraph, adaptResolvedAnalyticalPlan, buildPlanExecutionRegistry, } from './plan-execution-adapter.js';
+import { buildGovernedRelationalRegistry, compileGovernedRelationalExecutionGraph, compileGovernedRelationalPlan, finalizeGovernedCompilationReceipt, renderGovernedRelationalDqlArtifact, } from './governed-relational-compiler.js';
+import { buildAnalyticalExecutionGraph, executeAnalyticalExecutionGraph, } from './analytical-execution-graph.js';
+import { buildAnalyticalResultFacts, renderDeterministicAnalyticalNarrative, validateAnalyticalNarrativeClaims, } from './analytical-result-facts.js';
+import { resolveAnalyticalPeriods, } from './analytical-period-resolution.js';
+import { classifyAnalyticalFailure, createAnalyticalFailure, } from './analytical-failure-repair.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 +468,281 @@ 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) {
-    // 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 inheritedPlan = !input.resolvedAnalyticalPlan
+        && input.followUp?.priorResolvedAnalyticalPlan
+        && input.followUp.resolvedAnalyticalPlanDelta
+        ? deriveResolvedAnalyticalPlan(input.followUp.priorResolvedAnalyticalPlan, input.followUp.resolvedAnalyticalPlanDelta)
+        : undefined;
+    let normalizedInput = inheritedPlan
+        ? { ...input, resolvedAnalyticalPlan: inheritedPlan }
+        : input;
+    // Cross-result computations are intentionally independent of the KG and
+    // warehouse. Preserve this earliest exit before building any execution
+    // registry so lightweight follow-up callers do not need runtime services.
+    const earlyCrossResult = tryCrossResultAnswer(normalizedInput);
+    if (earlyCrossResult) {
+        return {
+            ...earlyCrossResult,
+            resolvedAnalyticalPlan: normalizedInput.resolvedAnalyticalPlan,
+        };
+    }
+    const executionRegistry = buildPlanExecutionRegistry({
+        nodes: [
+            ...normalizedInput.kg.getNodesByKind('block', 100_000),
+            ...normalizedInput.kg.getNodesByKind('metric', 100_000),
+            ...normalizedInput.kg.getNodesByKind('dimension', 100_000),
+        ],
+        objects: normalizedInput.contextPack?.objects,
+    });
+    const unresolvedPlan = normalizedInput.resolvedAnalyticalPlan;
+    const unresolvedCapability = unresolvedPlan
+        ? analyticalCapabilityForPlan(unresolvedPlan, normalizedInput.contextPack, executionRegistry)
+        : undefined;
+    if (unresolvedPlan?.schemaVersion === 2
+        && unresolvedPlan.analyticalFrame?.timeContext?.periods.some((period) => !period.start || !period.end)
+        && unresolvedCapability) {
+        let freshness = normalizedInput.analyticalFreshnessObservation;
+        let freshnessError;
+        if (!freshness
+            && unresolvedPlan.analyticalFrame.timeContext.completenessPolicy !== 'partial_current'
+            && normalizedInput.resolveAnalyticalFreshness
+            && unresolvedPlan.analyticalFrame.timeContext.timeDimensionId) {
+            try {
+                const freshnessRequest = {
+                    version: 1,
+                    snapshotId: unresolvedPlan.snapshotId,
+                    metricId: unresolvedCapability.metricId,
+                    timeDimensionId: unresolvedPlan.analyticalFrame.timeContext.timeDimensionId,
+                    ...(unresolvedCapability.freshness?.observedThroughFieldId
+                        ? { observedThroughFieldId: unresolvedCapability.freshness.observedThroughFieldId }
+                        : {}),
+                };
+                const adapterBinding = unresolvedPlan.capability === 'semantic_execution' && normalizedInput.semanticLayer
+                    ? adaptAnalyticalFreshnessRequest({
+                        plan: unresolvedPlan,
+                        request: freshnessRequest,
+                        registry: executionRegistry,
+                        semanticLayer: normalizedInput.semanticLayer,
+                        expectedSnapshotId: normalizedInput.contextPack?.knowledgeLens.snapshotId,
+                    })
+                    : undefined;
+                if (adapterBinding?.status === 'blocked') {
+                    throw { code: adapterBinding.code, message: adapterBinding.reason };
+                }
+                freshness = await normalizedInput.resolveAnalyticalFreshness({
+                    ...freshnessRequest,
+                    ...(adapterBinding?.status === 'ready'
+                        ? { authorizedAdapterRequest: adapterBinding.request }
+                        : {}),
+                });
+            }
+            catch (error) {
+                freshnessError = error;
+            }
+        }
+        const periodResolution = freshnessError
+            ? {
+                status: 'blocked',
+                code: 'FRESHNESS_REQUIRED',
+                reason: 'The selected route could not obtain its authorized freshness observation.',
+            }
+            : resolveAnalyticalPeriods({
+                frame: unresolvedPlan.analyticalFrame,
+                snapshotId: unresolvedPlan.snapshotId,
+                referenceInstant: normalizedInput.analyticalReferenceInstant ?? new Date().toISOString(),
+                ...(freshness ? { freshnessObservation: freshness } : {}),
+            });
+        if (periodResolution.status === 'resolved') {
+            normalizedInput = {
+                ...normalizedInput,
+                resolvedAnalyticalPlan: deriveResolvedAnalyticalPlan(unresolvedPlan, {
+                    question: unresolvedPlan.question,
+                    analyticalFrame: periodResolution.frame,
+                }),
+                ...(periodResolution.freshnessObservation
+                    ? { analyticalFreshnessObservation: periodResolution.freshnessObservation }
+                    : {}),
+            };
+        }
+        else {
+            normalizedInput = {
+                ...normalizedInput,
+                analyticalPeriodResolutionFailure: {
+                    code: periodResolution.code,
+                    reason: periodResolution.reason,
+                    ...(freshnessError ? { error: freshnessError } : {}),
+                },
+            };
+        }
+    }
+    const resolvedPlanExecutionBinding = normalizedInput.resolvedAnalyticalPlan
+        ? adaptResolvedAnalyticalPlan({
+            plan: normalizedInput.resolvedAnalyticalPlan,
+            registry: executionRegistry,
+            semanticLayer: normalizedInput.semanticLayer,
+            expectedSnapshotId: normalizedInput.contextPack?.knowledgeLens.snapshotId,
+        })
+        : undefined;
+    const analyticalCapability = normalizedInput.resolvedAnalyticalPlan
+        ? analyticalCapabilityForPlan(normalizedInput.resolvedAnalyticalPlan, normalizedInput.contextPack, executionRegistry)
+        : undefined;
+    const analyticalRoute = normalizedInput.resolvedAnalyticalPlan
+        ? analyticalRouteForPlan(normalizedInput.resolvedAnalyticalPlan)
+        : undefined;
+    const analyticalAdapterId = analyticalCapability && analyticalRoute
+        ? analyticalCapability.executionCapabilities.find((candidate) => candidate.route === analyticalRoute)?.adapterId
+        : undefined;
+    const analyticalGraphBuild = normalizedInput.resolvedAnalyticalPlan?.schemaVersion === 2
+        && normalizedInput.resolvedAnalyticalPlan.analyticalFrame
+        && !normalizedInput.analyticalPeriodResolutionFailure
+        && analyticalCapability
+        && analyticalRoute
+        ? buildAnalyticalExecutionGraph({
+            plan: normalizedInput.resolvedAnalyticalPlan,
+            capability: analyticalCapability,
+            route: analyticalRoute,
+            ...(analyticalAdapterId ? { adapterId: analyticalAdapterId } : {}),
+        })
+        : undefined;
+    const analyticalExecutionGraph = analyticalGraphBuild?.status === 'ready'
+        ? analyticalGraphBuild.graph
+        : undefined;
+    const analyticalExecutionGraphFailure = normalizedInput.resolvedAnalyticalPlan?.schemaVersion === 2
+        ? analyticalGraphBuild?.status === 'blocked'
+            ? {
+                code: analyticalGraphBuild.code,
+                reason: analyticalGraphBuild.reason,
+                ...(analyticalGraphBuild.field ? { field: analyticalGraphBuild.field } : {}),
+            }
+            : !analyticalCapability
+                ? { code: 'CAPABILITY_MISMATCH', reason: 'The selected v2 plan capability is not present in the immutable context pack.' }
+                : !analyticalRoute
+                    ? { code: 'ROUTE_MISMATCH', reason: 'The selected v2 plan has no executable analytical route.' }
+                    : undefined
+        : undefined;
+    const semanticGraphExecutionBinding = analyticalExecutionGraph?.route === 'semantic'
+        && normalizedInput.resolvedAnalyticalPlan
+        && normalizedInput.semanticLayer
+        ? adaptAnalyticalSemanticGraph({
+            graph: analyticalExecutionGraph,
+            plan: normalizedInput.resolvedAnalyticalPlan,
+            registry: executionRegistry,
+            semanticLayer: normalizedInput.semanticLayer,
+            expectedSnapshotId: normalizedInput.contextPack?.knowledgeLens.snapshotId,
+        })
+        : undefined;
+    const planBoundInput = resolvedPlanExecutionBinding || analyticalExecutionGraph || analyticalExecutionGraphFailure
+        ? { ...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 relationalRegistry = planBoundInput.resolvedAnalyticalPlan?.capability === 'governed_relational'
+        ? buildGovernedRelationalRegistry({
+            snapshotId: planBoundInput.resolvedAnalyticalPlan.snapshotId,
+            schemaContext: relationalSchemaContext,
+            manifest: planBoundInput.manifest,
+        })
+        : undefined;
+    const governedAnalyticalGraphCompilation = analyticalExecutionGraph?.route === 'governed_sql'
+        && planBoundInput.resolvedAnalyticalPlan
+        && relationalRegistry
+        ? compileGovernedRelationalExecutionGraph({
+            graph: analyticalExecutionGraph,
+            plan: planBoundInput.resolvedAnalyticalPlan,
+            registry: relationalRegistry,
+            driver: planBoundInput.semanticDriver,
+        })
+        : undefined;
+    const governedRelationalCompilation = !governedAnalyticalGraphCompilation
+        && planBoundInput.resolvedAnalyticalPlan?.mode === 'authoritative'
+        && planBoundInput.resolvedAnalyticalPlan.capability === 'governed_relational'
+        ? compileGovernedRelationalPlan({
+            plan: planBoundInput.resolvedAnalyticalPlan,
+            registry: relationalRegistry,
+            driver: planBoundInput.semanticDriver,
+        })
+        : undefined;
+    const compiledInput = governedRelationalCompilation || governedAnalyticalGraphCompilation || semanticGraphExecutionBinding || analyticalExecutionGraph || analyticalExecutionGraphFailure || normalizedInput.analyticalPeriodResolutionFailure
+        ? {
+            ...planBoundInput,
+            ...(governedRelationalCompilation ? { governedRelationalCompilation } : {}),
+            ...(governedAnalyticalGraphCompilation ? { governedAnalyticalGraphCompilation } : {}),
+            ...(semanticGraphExecutionBinding ? { semanticGraphExecutionBinding } : {}),
+            ...(analyticalExecutionGraph ? { analyticalExecutionGraph } : {}),
+            ...(analyticalExecutionGraphFailure ? { analyticalExecutionGraphFailure } : {}),
+            ...(normalizedInput.analyticalPeriodResolutionFailure
+                ? { analyticalPeriodResolutionFailure: normalizedInput.analyticalPeriodResolutionFailure }
+                : {}),
+        }
+        : planBoundInput;
+    const executionInput = compiledInput.contextPack
+        ? {
+            ...compiledInput,
+            skills: materializeKnowledgeLensSkills(compiledInput.contextPack, compiledInput.skills ?? []),
+            skillsSelectionLocked: true,
+        }
+        : compiledInput;
+    const loopResult = await runAnswerLoop(executionInput);
+    const result = applyHollowAnswerGate(validateCertifiedAnalyticalGraphAnswer(loopResult, executionInput.analyticalExecutionGraph, executionInput.resolvedAnalyticalPlan?.analyticalFrame));
     // 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 +771,9 @@ export async function answer(input) {
         ...publicResult,
         domainContext: input.domainContext,
         intentDecision,
+        resolvedAnalyticalPlan: executionInput.resolvedAnalyticalPlan,
+        executablePlan: executionInput.resolvedPlanExecutionBinding,
+        analyticalFreshnessObservation: executionInput.analyticalFreshnessObservation,
         trustLabelInfo,
         provenanceFooter: buildProvenanceFooter(result, trustLabelInfo),
         cascade: publicResult.cascade ?? createCascadeAnswerResult({
@@ -514,15 +793,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 +895,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 +937,232 @@ 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;
+    if (input.analyticalPeriodResolutionFailure) {
+        const failure = input.analyticalPeriodResolutionFailure;
+        const structuredFailureCode = failure.error && typeof failure.error === 'object'
+            && typeof failure.error.code === 'string'
+            && /^[A-Z0-9_]+$/.test(failure.error.code)
+            ? failure.error.code
+            : undefined;
+        const analyticalFailure = analyticalFailureForInput(input, {
+            error: failure.error ?? { code: failure.code, message: failure.reason },
+            ...(failure.code === 'FRESHNESS_MISMATCH' ? { code: 'SNAPSHOT_DRIFT' } : {}),
+            phase: 'planning',
+            failedBindings: input.resolvedAnalyticalPlan?.analyticalFrame?.timeContext?.timeDimensionId
+                ? [{
+                        qualifiedId: input.resolvedAnalyticalPlan.analyticalFrame.timeContext.timeDimensionId,
+                        role: 'time_axis',
+                        reasonCode: structuredFailureCode ?? failure.code,
+                    }]
+                : undefined,
+        });
+        return {
+            kind: 'no_answer',
+            sourceTier: 'no_answer',
+            certification: 'analyst_review_required',
+            reviewStatus: 'none',
+            confidence: 0,
+            text: analyticalFailure.message,
+            answer: analyticalFailure.message,
+            refusalCode: analyticalFailure.code === 'PERMISSION_DENIED' ? 'policy_blocked' : 'grounding_gap',
+            refusalDetails: { code: failure.code, message: analyticalFailure.message },
+            analyticalFailure,
+            citations: contextPackCitations(input.contextPack, 8),
+            considered,
+            contextPack: input.contextPack,
+            providerUsed: provider.name,
+        };
+    }
+    if (input.analyticalExecutionGraphFailure) {
+        const failure = input.analyticalExecutionGraphFailure;
+        const analyticalFailure = analyticalFailureForInput(input, {
+            error: { code: failure.code, message: failure.reason },
+            phase: 'compilation',
+            ...(failure.field ? { failedBindings: [{ role: failure.field, reasonCode: failure.code }] } : {}),
+        });
+        const text = analyticalFailure.message;
+        return {
+            kind: 'no_answer',
+            sourceTier: 'no_answer',
+            certification: 'analyst_review_required',
+            reviewStatus: 'none',
+            confidence: 0,
+            text,
+            answer: text,
+            refusalCode: 'modeling_gap',
+            refusalDetails: { code: failure.code, message: analyticalFailure.message },
+            analyticalFailure,
+            citations: contextPackCitations(input.contextPack, 8),
+            considered,
+            contextPack: input.contextPack,
+            providerUsed: provider.name,
+        };
+    }
+    if (input.semanticGraphExecutionBinding?.status === 'blocked') {
+        const failure = input.semanticGraphExecutionBinding;
+        const analyticalFailure = analyticalFailureForInput(input, {
+            error: { code: failure.code, message: failure.reason },
+            phase: 'validation',
+            failedBindings: failure.candidateIds?.map((qualifiedId) => ({ qualifiedId, reasonCode: failure.code })),
+        });
+        const text = analyticalFailure.message;
+        return {
+            kind: 'no_answer',
+            sourceTier: 'no_answer',
+            certification: 'analyst_review_required',
+            reviewStatus: 'none',
+            confidence: 0,
+            text,
+            answer: text,
+            refusalCode: 'grounding_gap',
+            refusalDetails: { code: failure.code, message: analyticalFailure.message },
+            analyticalFailure,
+            citations: contextPackCitations(input.contextPack, 8),
+            considered,
+            contextPack: input.contextPack,
+            providerUsed: provider.name,
+        };
+    }
+    if (input.semanticGraphExecutionBinding?.status === 'ready' && input.analyticalExecutionGraph) {
+        return executeSemanticAnalyticalGraph({
+            input,
+            binding: input.semanticGraphExecutionBinding,
+            graph: input.analyticalExecutionGraph,
+            considered,
+            providerName: provider.name,
+        });
+    }
+    if (input.governedAnalyticalGraphCompilation?.status === 'blocked') {
+        const failure = input.governedAnalyticalGraphCompilation;
+        const analyticalFailure = analyticalFailureForInput(input, {
+            error: { code: failure.code, message: failure.reason },
+            phase: 'compilation',
+            failedBindings: failure.candidateIds?.map((qualifiedId) => ({ qualifiedId, reasonCode: failure.code })),
+        });
+        const text = analyticalFailure.message;
+        return {
+            kind: 'no_answer',
+            sourceTier: 'no_answer',
+            certification: 'analyst_review_required',
+            reviewStatus: 'none',
+            confidence: 0,
+            text,
+            answer: text,
+            refusalCode: failure.code.startsWith('RELATIONSHIP_') ? 'modeling_gap' : 'grounding_gap',
+            refusalDetails: { code: failure.code, message: analyticalFailure.message },
+            analyticalFailure,
+            citations: contextPackCitations(input.contextPack, 8),
+            considered,
+            contextPack: input.contextPack,
+            providerUsed: provider.name,
+        };
+    }
+    if (input.governedAnalyticalGraphCompilation?.status === 'compiled' && input.analyticalExecutionGraph) {
+        return executeGovernedRelationalAnalyticalGraph({
+            input,
+            compilation: input.governedAnalyticalGraphCompilation,
+            graph: input.analyticalExecutionGraph,
+            considered,
+            providerName: provider.name,
+            schemaContext,
+        });
+    }
+    const governedRelationalCompilation = input.governedRelationalCompilation;
+    if (governedRelationalCompilation?.status === 'blocked') {
+        const analyticalFailure = analyticalFailureForInput(input, {
+            error: { code: governedRelationalCompilation.code, message: governedRelationalCompilation.reason },
+            phase: 'compilation',
+            failedBindings: governedRelationalCompilation.candidateIds?.map((qualifiedId) => ({
+                qualifiedId,
+                reasonCode: governedRelationalCompilation.code,
+            })),
+        });
+        const text = analyticalFailure.message;
+        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: analyticalFailure.message },
+            analyticalFailure,
+            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 analyticalFailure;
+        let receipt = governedRelationalCompilation.receipt;
+        if (input.executeDqlArtifact) {
+            try {
+                result = await input.executeDqlArtifact(dqlArtifact);
+                receipt = finalizeGovernedCompilationReceipt(receipt, result);
+            }
+            catch (error) {
+                analyticalFailure = analyticalFailureForInput(input, {
+                    error,
+                    phase: 'execution',
+                    dqlArtifact,
+                    compiledSql: governedRelationalCompilation.sql,
+                });
+                executionError = analyticalFailure.message;
+            }
+        }
+        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' } : {}),
+            ...(analyticalFailure ? { analyticalFailure } : {}),
+            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 +1182,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 +1244,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 +1401,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 +1417,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 +1624,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 +2712,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 +2934,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,
@@ -2452,6 +3020,529 @@ function resultColumnNames(result) {
         .filter(Boolean);
     return columns?.length ? columns : undefined;
 }
+function analyticalCapabilityForPlan(plan, contextPack, registry = []) {
+    const candidates = contextPack?.retrievalDiagnostics.meaningEvidence?.candidates ?? [];
+    const exactExecution = candidates.filter((candidate) => candidate.objectKey === plan.executionId || candidate.qualifiedId === plan.executionId);
+    const metricId = plan.analyticalFrame?.metricConceptIds[0];
+    const pool = exactExecution.length > 0
+        ? exactExecution
+        : candidates.filter((candidate) => candidate.analyticalCapability?.metricId === metricId);
+    const normalized = pool.flatMap((candidate) => {
+        const capability = normalizeMetricCapabilityContract(candidate.analyticalCapability);
+        return capability ? [capability] : [];
+    });
+    for (const entry of registry) {
+        if ((plan.executionId && entry.identities.includes(plan.executionId)) ||
+            entry.node.payload?.qualifiedId === plan.analyticalFrame?.metricConceptIds[0]) {
+            const capability = normalizeMetricCapabilityContract(entry.node.payload?.analyticalCapability);
+            if (capability)
+                normalized.push(capability);
+        }
+    }
+    const byFingerprint = new Map(normalized.map((capability) => [capability.sourceFingerprint, capability]));
+    return byFingerprint.size === 1 ? [...byFingerprint.values()][0] : undefined;
+}
+function analyticalRouteForPlan(plan) {
+    if (plan.capability === 'certified_execution' && plan.recommendedRoute === 'certified')
+        return 'certified';
+    if (plan.capability === 'semantic_execution' && plan.recommendedRoute === 'semantic')
+        return 'semantic';
+    if (plan.capability === 'governed_relational' && plan.recommendedRoute === 'governed_sql')
+        return 'governed_sql';
+    if (plan.capability === 'bounded_exploration' && plan.recommendedRoute === 'exploratory')
+        return 'exploratory';
+    return undefined;
+}
+function validateCertifiedAnalyticalGraphAnswer(answer, graph, frame) {
+    if (!graph || graph.route !== 'certified')
+        return answer;
+    if (!frame)
+        return certifiedGraphValidationFailure(answer, graph, 'The certified graph has no v2 analytical frame.');
+    if (!answer.result)
+        return { ...answer, analyticalExecutionGraph: graph };
+    const source = graph.nodes.find((node) => node.kind === 'source_invocation' && node.strategy === 'complete_asset');
+    if (!source) {
+        return certifiedGraphValidationFailure(answer, graph, 'The certified graph has no complete-asset source node.');
+    }
+    const columns = resultColumnNames(answer.result) ?? [];
+    const expected = source.outputAliases.completeAssetOutputIds ?? [];
+    if (columns.length !== expected.length || expected.some((outputId) => !columns.includes(outputId))) {
+        return certifiedGraphValidationFailure(answer, graph, `The certified result does not satisfy the requested outputs: ${expected.join(', ')}.`);
+    }
+    const rows = answer.result.rows.map((row) => {
+        if (Array.isArray(row))
+            return Object.fromEntries(columns.map((column, index) => [column, row[index]]));
+        return row && typeof row === 'object' ? row : {};
+    });
+    const executed = executeAnalyticalExecutionGraph({
+        graph,
+        sourceResults: {
+            [source.id]: {
+                columns,
+                rows,
+                receiptFingerprint: answer.result.executionReceipt?.resultFingerprint
+                    ?? hashAnalyticalValue({ columns, rows, rowCount: answer.result.rowCount }),
+            },
+        },
+    });
+    if (executed.status === 'failed') {
+        return certifiedGraphValidationFailure(answer, graph, executed.reason);
+    }
+    const story = buildValidatedAnalyticalStory(frame, graph, executed);
+    if ('failure' in story)
+        return certifiedGraphValidationFailure(answer, graph, story.failure);
+    return {
+        ...answer,
+        text: story.narrative.text,
+        answer: story.narrative.text,
+        analyticalExecutionGraph: graph,
+        analyticalExecutionReceipt: executed.receipt,
+        analyticalFacts: story.factSet,
+        analyticalNarrative: story.narrative,
+        result: analyticalGraphResultPayload(executed),
+    };
+}
+function certifiedGraphValidationFailure(answer, graph, reason) {
+    const analyticalFailure = createAnalyticalFailure({
+        code: 'RESULT_CONTRACT_MISMATCH',
+        phase: 'result_validation',
+        snapshotId: graph.snapshotId,
+        runId: graph.graphId,
+        planFingerprint: graph.planFingerprint,
+        dqlSource: answer.dqlArtifact?.source,
+        compiledSql: answer.sql ?? answer.proposedSql ?? answer.dqlArtifact?.compiledSql,
+    });
+    const text = analyticalFailure.message;
+    return {
+        ...answer,
+        kind: 'no_answer',
+        sourceTier: 'no_answer',
+        certification: 'analyst_review_required',
+        reviewStatus: 'none',
+        confidence: 0,
+        text,
+        answer: text,
+        result: undefined,
+        executionError: analyticalFailure.message,
+        refusalCode: 'grounding_gap',
+        refusalDetails: { code: 'RESULT_CONTRACT_MISMATCH', message: analyticalFailure.message },
+        analyticalFailure,
+        analyticalExecutionGraph: graph,
+    };
+}
+async function executeSemanticAnalyticalGraph(input) {
+    const layer = input.input.semanticLayer;
+    if (!layer) {
+        return analyticalGraphFailureAnswer(input, 'SEMANTIC_LAYER_REQUIRED', 'The pinned semantic layer is unavailable.');
+    }
+    const sourceResults = {};
+    const compiledSql = [];
+    const artifacts = [];
+    for (const invocation of input.binding.invocations) {
+        let composed = composeSemanticQueryFromMembers({
+            semanticLayer: layer,
+            question: input.input.question,
+            selection: invocation.selection,
+            ...(input.input.semanticDriver ? { driver: input.input.semanticDriver } : {}),
+            ...(input.input.semanticTableMapping ? { tableMapping: input.input.semanticTableMapping } : {}),
+        });
+        if (!composed && input.input.semanticQueryCompiler) {
+            try {
+                const compiled = await input.input.semanticQueryCompiler(invocation.selection);
+                composed = composeSemanticQueryFromCompiledMembers({
+                    semanticLayer: layer,
+                    question: input.input.question,
+                    selection: compiled.selection ?? invocation.selection,
+                    sql: compiled.sql,
+                });
+            }
+            catch (error) {
+                return analyticalGraphFailureAnswer(input, 'COMPILATION_FAILED', error instanceof Error ? error.message : String(error), {
+                    phase: 'compilation',
+                    ...(compiledSql.length ? { compiledSql: renderAnalyticalStatements(compiledSql) } : {}),
+                });
+            }
+        }
+        if (!composed) {
+            return analyticalGraphFailureAnswer(input, 'COMPILATION_FAILED', `The pinned semantic adapter could not compile ${invocation.nodeId}.`, {
+                phase: 'compilation',
+                ...(compiledSql.length ? { compiledSql: renderAnalyticalStatements(compiledSql) } : {}),
+                failedBindings: [{ role: 'source_invocation', reasonCode: 'SEMANTIC_COMPILE_FAILED' }],
+            });
+        }
+        compiledSql.push(composed.sql);
+        artifacts.push(composed.dqlArtifact);
+        const executor = input.input.executeDqlArtifact
+            ? () => input.input.executeDqlArtifact(composed.dqlArtifact)
+            : input.input.executeGeneratedSql
+                ? () => input.input.executeGeneratedSql(composed.sql, composed.dqlArtifact)
+                : undefined;
+        if (!executor)
+            continue;
+        let result;
+        try {
+            result = await executor();
+        }
+        catch (error) {
+            return analyticalGraphFailureAnswer(input, 'EXECUTION_FAILED', error instanceof Error ? error.message : String(error), { phase: 'execution', dqlArtifact: composed.dqlArtifact, compiledSql: composed.sql });
+        }
+        const normalized = normalizeAnalyticalSourceResult({
+            result,
+            outputAliases: invocation.outputAliases,
+            sourceNames: [
+                ...(invocation.selection.dimensions ?? []),
+                ...(invocation.selection.timeDimension ? [invocation.selection.timeDimension.name] : []),
+                invocation.selection.metrics[0],
+            ],
+            sql: composed.sql,
+        });
+        if ('failure' in normalized) {
+            return analyticalGraphFailureAnswer(input, 'RESULT_CONTRACT_MISMATCH', normalized.failure, {
+                phase: 'result_validation',
+                dqlArtifact: composed.dqlArtifact,
+                compiledSql: composed.sql,
+            });
+        }
+        sourceResults[invocation.nodeId] = normalized.source;
+    }
+    const sql = renderAnalyticalStatements(compiledSql);
+    if (Object.keys(sourceResults).length === 0) {
+        return {
+            kind: 'uncertified',
+            sourceTier: 'semantic_layer',
+            certification: 'governed',
+            reviewStatus: 'governed',
+            confidence: 0.9,
+            text: `Compiled ${compiledSql.length} snapshot-bound semantic period ${compiledSql.length === 1 ? 'query' : 'queries'}; execution was not requested.`,
+            answer: `Compiled ${compiledSql.length} snapshot-bound semantic period ${compiledSql.length === 1 ? 'query' : 'queries'}; execution was not requested.`,
+            proposedSql: sql,
+            sql,
+            ...(artifacts.length === 1 ? { dqlArtifact: artifacts[0] } : {}),
+            analyticalExecutionGraph: input.graph,
+            citations: contextPackCitations(input.input.contextPack, 8),
+            considered: input.considered,
+            contextPack: input.input.contextPack,
+            providerUsed: input.providerName,
+        };
+    }
+    const executed = executeAnalyticalExecutionGraph({ graph: input.graph, sourceResults });
+    if (executed.status === 'failed') {
+        return analyticalGraphFailureAnswer(input, executed.code, executed.reason, {
+            phase: 'result_validation',
+            compiledSql: sql,
+            ...(artifacts.length === 1 ? { dqlArtifact: artifacts[0] } : {}),
+            failedBindings: [{ role: executed.nodeId, reasonCode: executed.code }],
+        });
+    }
+    const frame = input.input.resolvedAnalyticalPlan?.analyticalFrame;
+    if (!frame)
+        return analyticalGraphFailureAnswer(input, 'RESULT_CONTRACT_MISMATCH', 'The executed graph has no v2 analytical frame.', {
+            phase: 'result_validation',
+            compiledSql: sql,
+        });
+    const story = buildValidatedAnalyticalStory(frame, input.graph, executed);
+    if ('failure' in story)
+        return analyticalGraphFailureAnswer(input, 'RESULT_CONTRACT_MISMATCH', story.failure, {
+            phase: 'result_validation',
+            compiledSql: sql,
+        });
+    const result = analyticalGraphResultPayload(executed);
+    return {
+        kind: 'uncertified',
+        sourceTier: 'semantic_layer',
+        certification: 'governed',
+        reviewStatus: 'governed',
+        confidence: 0.95,
+        text: story.narrative.text,
+        answer: story.narrative.text,
+        proposedSql: sql,
+        sql,
+        ...(artifacts.length === 1 ? { dqlArtifact: artifacts[0] } : {}),
+        result,
+        analyticalExecutionGraph: input.graph,
+        analyticalExecutionReceipt: executed.receipt,
+        analyticalFacts: story.factSet,
+        analyticalNarrative: story.narrative,
+        citations: contextPackCitations(input.input.contextPack, 8),
+        considered: input.considered,
+        contextPack: input.input.contextPack,
+        providerUsed: input.providerName,
+    };
+}
+async function executeGovernedRelationalAnalyticalGraph(input) {
+    const sourceResults = {};
+    const artifacts = [];
+    for (const statement of input.compilation.statements) {
+        const compiled = {
+            status: 'compiled',
+            ast: statement.ast,
+            sql: statement.sql,
+            parameterValues: statement.parameterValues,
+            receipt: statement.receipt,
+        };
+        const artifact = renderGovernedRelationalDqlArtifact(compiled);
+        artifacts.push(artifact);
+        if (!input.input.executeDqlArtifact)
+            continue;
+        let result;
+        try {
+            result = await input.input.executeDqlArtifact(artifact);
+        }
+        catch (error) {
+            return analyticalGraphFailureAnswer(input, 'EXECUTION_FAILED', error instanceof Error ? error.message : String(error), { phase: 'execution', dqlArtifact: artifact, compiledSql: statement.sql });
+        }
+        let receipt;
+        try {
+            receipt = finalizeGovernedCompilationReceipt(statement.receipt, result);
+        }
+        catch (error) {
+            return analyticalGraphFailureAnswer(input, 'RESULT_CONTRACT_MISMATCH', error instanceof Error ? error.message : String(error), { phase: 'result_validation', dqlArtifact: artifact, compiledSql: statement.sql });
+        }
+        const normalized = normalizeAnalyticalSourceResult({
+            result,
+            outputAliases: statement.outputAliases,
+            sourceNames: [
+                ...statement.outputAliases.dimensions.map((dimension) => dimension.outputId),
+                statement.outputAliases.metric.outputId,
+            ],
+            sql: statement.sql,
+            receiptFingerprint: receipt.result.resultFingerprint,
+        });
+        if ('failure' in normalized) {
+            return analyticalGraphFailureAnswer(input, 'RESULT_CONTRACT_MISMATCH', normalized.failure, {
+                phase: 'result_validation',
+                dqlArtifact: artifact,
+                compiledSql: statement.sql,
+            });
+        }
+        sourceResults[statement.nodeId] = normalized.source;
+    }
+    const statements = input.compilation.statements.map((statement) => statement.sql);
+    const sql = renderAnalyticalStatements(statements);
+    if (Object.keys(sourceResults).length === 0) {
+        return {
+            kind: 'uncertified',
+            sourceTier: 'dbt_manifest',
+            certification: 'governed',
+            reviewStatus: 'governed',
+            confidence: 0.9,
+            text: `Compiled ${statements.length} governed relational period ${statements.length === 1 ? 'statement' : 'statements'}; execution was not requested.`,
+            answer: `Compiled ${statements.length} governed relational period ${statements.length === 1 ? 'statement' : 'statements'}; execution was not requested.`,
+            proposedSql: sql,
+            sql,
+            ...(artifacts.length === 1 ? { dqlArtifact: artifacts[0] } : {}),
+            analyticalExecutionGraph: input.graph,
+            governedAnalyticalGraphCompilationReceipt: input.compilation.receipt,
+            citations: schemaCitations(input.schemaContext, 8),
+            considered: input.considered,
+            contextPack: input.input.contextPack,
+            providerUsed: input.providerName,
+        };
+    }
+    const executed = executeAnalyticalExecutionGraph({ graph: input.graph, sourceResults });
+    if (executed.status === 'failed') {
+        return analyticalGraphFailureAnswer(input, executed.code, executed.reason, {
+            phase: 'result_validation',
+            compiledSql: sql,
+            ...(artifacts.length === 1 ? { dqlArtifact: artifacts[0] } : {}),
+            failedBindings: [{ role: executed.nodeId, reasonCode: executed.code }],
+        });
+    }
+    const frame = input.input.resolvedAnalyticalPlan?.analyticalFrame;
+    if (!frame)
+        return analyticalGraphFailureAnswer(input, 'RESULT_CONTRACT_MISMATCH', 'The executed graph has no v2 analytical frame.', {
+            phase: 'result_validation',
+            compiledSql: sql,
+        });
+    const story = buildValidatedAnalyticalStory(frame, input.graph, executed);
+    if ('failure' in story)
+        return analyticalGraphFailureAnswer(input, 'RESULT_CONTRACT_MISMATCH', story.failure, {
+            phase: 'result_validation',
+            compiledSql: sql,
+        });
+    const result = analyticalGraphResultPayload(executed);
+    return {
+        kind: 'uncertified',
+        sourceTier: 'dbt_manifest',
+        certification: 'governed',
+        reviewStatus: 'governed',
+        confidence: 0.95,
+        text: story.narrative.text,
+        answer: story.narrative.text,
+        proposedSql: sql,
+        sql,
+        ...(artifacts.length === 1 ? { dqlArtifact: artifacts[0] } : {}),
+        result,
+        analyticalExecutionGraph: input.graph,
+        analyticalExecutionReceipt: executed.receipt,
+        analyticalFacts: story.factSet,
+        analyticalNarrative: story.narrative,
+        governedAnalyticalGraphCompilationReceipt: input.compilation.receipt,
+        citations: schemaCitations(input.schemaContext, 8),
+        considered: input.considered,
+        contextPack: input.input.contextPack,
+        providerUsed: input.providerName,
+    };
+}
+function normalizeAnalyticalSourceResult(input) {
+    const columns = resultColumnNames(input.result) ?? [];
+    const desired = [
+        ...input.outputAliases.dimensions.map((dimension) => dimension.outputId),
+        ...(input.outputAliases.metric ? [input.outputAliases.metric.outputId] : []),
+    ];
+    if (columns.length !== desired.length || input.sourceNames.length !== desired.length) {
+        return { failure: `Expected ${desired.length} source columns but the adapter returned ${columns.length}.` };
+    }
+    const used = new Set();
+    const mapping = desired.map((outputId, index) => {
+        const candidates = [outputId, input.sourceNames[index]].map(normalizeOutputIdentity);
+        const exact = columns.find((column) => !used.has(column) && candidates.includes(normalizeOutputIdentity(column)));
+        const selected = exact ?? columns[index];
+        if (selected)
+            used.add(selected);
+        return { outputId, sourceColumn: selected };
+    });
+    if (mapping.some((item) => !item.sourceColumn) || new Set(mapping.map((item) => item.sourceColumn)).size !== mapping.length) {
+        return { failure: 'The adapter result columns cannot be mapped uniquely to the graph output aliases.' };
+    }
+    const rows = input.result.rows.map((row) => {
+        const source = Array.isArray(row)
+            ? Object.fromEntries(columns.map((column, index) => [column, row[index]]))
+            : row && typeof row === 'object'
+                ? row
+                : {};
+        return Object.fromEntries(mapping.map((item) => [item.outputId, source[item.sourceColumn]]));
+    });
+    return {
+        source: {
+            columns: desired,
+            rows,
+            receiptFingerprint: input.receiptFingerprint
+                ?? input.result.executionReceipt?.resultFingerprint
+                ?? hashAnalyticalValue({ sql: input.sql, columns, rows, rowCount: input.result.rowCount }),
+        },
+    };
+}
+function buildValidatedAnalyticalStory(frame, graph, result) {
+    const facts = buildAnalyticalResultFacts({
+        frame,
+        graph,
+        receipt: result.receipt,
+        columns: result.columns,
+        rows: result.rows,
+    });
+    if (facts.status === 'blocked')
+        return { failure: facts.reason };
+    const narrative = renderDeterministicAnalyticalNarrative({ frame, factSet: facts.factSet });
+    const validation = validateAnalyticalNarrativeClaims({ factSet: facts.factSet, claims: narrative.claims });
+    if (validation.status === 'invalid')
+        return { failure: validation.reason };
+    return { factSet: facts.factSet, narrative };
+}
+function analyticalGraphResultPayload(result) {
+    return {
+        columns: result.columns,
+        rows: result.rows.map((row) => result.columns.map((column) => row[column])),
+        rowCount: result.rows.length,
+    };
+}
+function analyticalGraphFailureAnswer(input, code, reason, artifacts = {}) {
+    const analyticalFailure = analyticalFailureForInput(input.input, {
+        error: { code, message: reason },
+        code: stableFailureCodeForGraph(code, reason),
+        phase: artifacts.phase ?? analyticalFailurePhaseForGraphCode(code),
+        runId: input.graph.graphId,
+        dqlArtifact: artifacts.dqlArtifact,
+        compiledSql: artifacts.compiledSql,
+        failedBindings: artifacts.failedBindings,
+    });
+    const text = analyticalFailure.message;
+    return {
+        kind: 'no_answer',
+        sourceTier: 'no_answer',
+        certification: 'analyst_review_required',
+        reviewStatus: 'none',
+        confidence: 0,
+        text,
+        answer: text,
+        executionError: analyticalFailure.message,
+        refusalCode: 'grounding_gap',
+        refusalDetails: { code, message: analyticalFailure.message },
+        analyticalFailure,
+        analyticalExecutionGraph: input.graph,
+        ...(artifacts.compiledSql ? { proposedSql: artifacts.compiledSql, sql: artifacts.compiledSql } : {}),
+        ...(artifacts.dqlArtifact ? { dqlArtifact: artifacts.dqlArtifact } : {}),
+        citations: contextPackCitations(input.input.contextPack, 8),
+        considered: input.considered,
+        contextPack: input.input.contextPack,
+        providerUsed: input.providerName,
+    };
+}
+function analyticalFailureForInput(input, diagnostic) {
+    const plan = input.resolvedAnalyticalPlan;
+    return createAnalyticalFailure({
+        error: diagnostic.error,
+        code: diagnostic.code,
+        phase: diagnostic.phase,
+        snapshotId: plan?.snapshotId ?? input.contextPack?.knowledgeLens.snapshotId ?? 'snapshot-unavailable',
+        runId: diagnostic.runId ?? plan?.planId,
+        planFingerprint: plan?.fingerprint,
+        dqlSource: diagnostic.dqlArtifact?.source,
+        compiledSql: diagnostic.compiledSql ?? diagnostic.dqlArtifact?.compiledSql,
+        failedBindings: diagnostic.failedBindings,
+    });
+}
+function stableFailureCodeForGraph(code, reason) {
+    if (code === 'SOURCE_RESULT_MISSING'
+        || code === 'SUB_RECEIPT_REQUIRED'
+        || code === 'RESULT_CONTRACT_MISMATCH'
+        || code === 'DECIMAL_VALUE_REQUIRED'
+        || code === 'ROW_BOUND_EXCEEDED')
+        return 'RESULT_CONTRACT_MISMATCH';
+    if (code === 'SNAPSHOT_MISMATCH')
+        return 'SNAPSHOT_DRIFT';
+    return classifyAnalyticalFailure({ code, message: reason }, code === 'EXECUTION_FAILED' ? 'COMPILATION_FAILED' : 'COMPILATION_FAILED');
+}
+function analyticalFailurePhaseForGraphCode(code) {
+    if (code === 'SOURCE_RESULT_MISSING'
+        || code === 'SUB_RECEIPT_REQUIRED'
+        || code === 'RESULT_CONTRACT_MISMATCH'
+        || code === 'DECIMAL_VALUE_REQUIRED'
+        || code === 'ROW_BOUND_EXCEEDED')
+        return 'result_validation';
+    if (code === 'EXECUTION_FAILED')
+        return 'execution';
+    return 'compilation';
+}
+function renderAnalyticalStatements(statements) {
+    if (statements.length <= 1)
+        return statements[0] ?? '';
+    return statements.map((statement, index) => `-- analytical source ${index + 1}\n${statement}`).join('\n\n');
+}
+function normalizeOutputIdentity(value) {
+    return value
+        .replace(/["`[\]]/g, '')
+        .split('.')
+        .at(-1)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+}
+function hashAnalyticalValue(value) {
+    return createHash('sha256').update(stableAnalyticalValue(value)).digest('hex');
+}
+function stableAnalyticalValue(value) {
+    if (value === undefined || value === null)
+        return 'null';
+    if (typeof value === 'bigint')
+        return JSON.stringify(value.toString());
+    if (typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableAnalyticalValue).join(',')}]`;
+    const record = value;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableAnalyticalValue(record[key])}`).join(',')}}`;
+}
 const SYSTEM_PROMPT = `You are the DQL Analytics Agent.
 
 Rules: