@duckcodeailabs/dql-agent 1.13.4 → 1.13.5

package/dist/answer-loop.js

@@ -15,7 +15,7 @@
  * full pipeline.
  */
 import { createHash } from 'node:crypto';
-import { describeDialectForPrompt, normalizeMetricCapabilityContract, } from '@duckcodeailabs/dql-core';
+import { describeDialectForPrompt, buildSqlOutputExpressionSignature, normalizeMetricCapabilityContract, semanticExecutionFingerprint, } from '@duckcodeailabs/dql-core';
 import { buildSkillBlockHints, buildSkillMetricHints, buildSkillsPrompt, expandQuestionWithSkillVocabulary, selectRelevantSkills } from './skills/loader.js';
 import { conversationTurnContextState, } from './conversation/snapshot.js';
 import { isTrustedConversationTurn } from './conversation/turn-trust.js';
@@ -32,6 +32,9 @@ import { createContextLedger } from './grounding/context-ledger.js';
 import { validateAnswerResultShape } from './answer-shape.js';
 import { analyticalErrorDetail, } from './analytical-error.js';
 import { fanoutWarningsForSql } from './metadata/grain-ledger.js';
+import { buildAggregationSafetyProof, buildSemanticCompilationAggregationSafetyProof, } from './aggregation-safety-proof.js';
+import { buildSemanticProofAuthorityV1 } from './semantic-proof-authority.js';
+import { GENERATED_ANALYTICAL_TUPLE_DRIFT_MESSAGE, validateGeneratedAnalyticalProposal, } from './generated-analytical-proposal.js';
 import { evaluateDbtFirstGeneratedSql } from './metadata/dbt-first-safety.js';
 import { planAnalyticalPath, humanizeAnalyticalEntityId, analyticalPolicyUserFacingReason, } from './metadata/analytical-policy.js';
 import { planCertifiedAdaptation } from './metadata/block-adapt.js';
@@ -47,14 +50,14 @@ 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 { buildResolvedAnalyticalPlan, 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';
+import { QUICK_PROMPT_CONTEXT_BUDGET, canUseLaneRepair, cascadeBudgetTrace, createCascadeBudgetState, promptContextBudgetForQuestion, proposalToolBudgetForQuestion, recordLaneRepair, } from './cascade/budgets.js';
 function semanticCompilerFailure(error) {
     const record = error && typeof error === 'object' ? error : undefined;
     const message = error instanceof Error ? error.message : String(error);
@@ -675,6 +678,141 @@ export function materializeKnowledgeLensSkills(contextPack, available) {
         };
     });
 }
+/**
+ * Older direct AnswerLoop callers supplied the semantic catalog but no frozen
+ * route contract. Migrate that one bounded retrieval result exactly once at
+ * ingress: the chosen KG identity and its normalized capability are copied into
+ * an authoritative RAP before compiler/proof code runs. No downstream stage is
+ * permitted to repeat this name/family selection.
+ */
+async function freezeLegacySemanticSelection(input) {
+    const metricNodes = input.kg.getNodesByKind('metric', 100_000);
+    if (metricNodes.length === 0)
+        return undefined;
+    const questionPlan = input.contextPack?.questionPlan?.requestedShape
+        ? input.contextPack.questionPlan
+        : buildAnalysisQuestionPlan(input.question, input.followUp);
+    const semanticLayer = input.semanticLayer;
+    const match = await matchSemanticMetric(input.question, metricNodes, {
+        measureTerms: [...questionPlan.requestedShape.measures, ...questionPlan.metricTerms],
+        ...(semanticLayer ? { canExecute: (name) => semanticLayer.canComposeMetric(name) } : {}),
+    }).catch(() => null);
+    if (!match)
+        return undefined;
+    const normalizedCapability = normalizeMetricCapabilityContract(match.metric.payload?.analyticalCapability);
+    if (!normalizedCapability)
+        return undefined;
+    const metricDefinition = semanticLayer?.listMetrics().find((metric) => metric.name === match.metric.name
+        || metric.name.endsWith(`.${match.metric.name}`)
+        || match.metric.name.endsWith(`.${metric.name}`));
+    const composed = semanticLayer ? composeSemanticQueryForQuestion({
+        semanticLayer,
+        question: input.question,
+        questionPlan,
+        matchedMetric: match.metric,
+        filterValueColumns: (value) => resolveFilterValueColumns(value, input.schemaContext ?? []),
+        filterValueBindings: (value) => resolveAgentFilterValueBindings(value, input.schemaContext ?? []),
+        ...(input.semanticDriver ? { driver: input.semanticDriver } : {}),
+        ...(input.semanticTableMapping ? { tableMapping: input.semanticTableMapping } : {}),
+    }) : undefined;
+    // A semantic runtime may still resolve the shape later (Research/member-tool
+    // lane). Do not freeze a partial tuple here.
+    if (semanticLayer && !composed)
+        return undefined;
+    const capability = {
+        ...normalizedCapability,
+        dimensions: normalizedCapability.dimensions.map((dimension) => {
+            const definition = semanticLayer?.resolveGroupBy(dimension.dimensionId);
+            const compilerSelected = composed?.dimensions.includes(dimension.dimensionId)
+                || composed?.timeDimension?.name === dimension.dimensionId;
+            return definition
+                ? {
+                    ...dimension,
+                    nativeGroupingReference: definition.qualifiedName ?? definition.name,
+                    ...(compilerSelected && questionPlan.requestedShape.rankingDirection
+                        ? { supportedRoles: [...new Set([...dimension.supportedRoles, 'rank_entity'])] }
+                        : {}),
+                }
+                : dimension;
+        }),
+    };
+    const identity = match.metric.nodeId;
+    const selectedMetricNames = composed?.metrics ?? [match.metric.name];
+    const selectedNodes = selectedMetricNames.flatMap((name) => {
+        const matches = metricNodes.filter((node) => node.name === name || node.name.endsWith(`.${name}`) || name.endsWith(`.${node.name}`));
+        return matches.length === 1 ? matches : [];
+    });
+    if (selectedNodes.length !== selectedMetricNames.length)
+        return undefined;
+    const candidates = selectedNodes.flatMap((node) => {
+        const nodeCapability = normalizeMetricCapabilityContract(node.payload?.analyticalCapability);
+        if (!nodeCapability)
+            return [];
+        const isPrimary = node.nodeId === match.metric.nodeId;
+        return [{
+                id: node.nodeId,
+                kind: 'semantic_metric',
+                semanticObjectType: 'metric',
+                trustTier: 'semantic',
+                name: node.name,
+                aliases: node.tags,
+                definition: node.description,
+                domain: node.domain,
+                primaryEntity: nodeCapability.primaryEntityId,
+                dimensions: nodeCapability.dimensions.map((dimension) => dimension.dimensionId),
+                sourceObjects: nodeCapability.semanticModelId ? [nodeCapability.semanticModelId] : [],
+                relevanceScore: isPrimary ? match.score : 1,
+                matchReasons: [`bounded_${isPrimary ? match.basis ?? 'semantic' : 'compiler'}_retrieval`],
+                compatibility: 'compatible',
+                compatibilityFacts: ['The selected KG identity carries the exact normalized semantic capability embedded in this plan.'],
+                analyticalCapability: isPrimary ? capability : nodeCapability,
+                eligible: true,
+                exactMatch: true,
+            }];
+    });
+    if (candidates.length !== selectedNodes.length)
+        return undefined;
+    return buildResolvedAnalyticalPlan({
+        question: input.question,
+        resolution: {
+            interpretedQuestion: input.question,
+            questionType: questionTypeFromText(input.question),
+            selectedConceptIds: candidates.map((item) => item.id),
+            recommendedExecutionId: identity,
+            queryIntent: {
+                measures: composed?.metrics ?? [match.metric.name],
+                dimensions: composed ? [
+                    ...composed.dimensions,
+                    ...(composed.timeDimension ? [composed.timeDimension.name] : []),
+                ] : [
+                    ...questionPlan.requestedShape.dimensions,
+                    ...(questionPlan.timeTerms.length > 0 && (metricDefinition?.aggTimeDimension ?? capability.timeDimensions[0]?.dimensionId)
+                        ? [metricDefinition?.aggTimeDimension ?? capability.timeDimensions[0].dimensionId]
+                        : []),
+                ],
+                filters: composed?.filters.map((filter) => ({ field: filter.dimension, value: String(filter.values[0] ?? '') })) ?? [],
+                ...(composed?.timeDimension?.granularity
+                    ? { timeGrain: composed.timeDimension.granularity }
+                    : questionPlan.timeTerms.some((term) => /month/i.test(term)) ? { timeGrain: 'month' } : {}),
+                ...(questionPlan.requestedShape.rankingDirection
+                    ? { order: questionPlan.requestedShape.rankingDirection === 'top' ? 'desc' : 'asc' }
+                    : {}),
+                ...(questionPlan.requestedShape.topN ? { limit: questionPlan.requestedShape.topN.n } : {}),
+            },
+            rejectedCandidates: [],
+            confidence: match.score >= 0.7 ? 'high' : 'medium',
+            missingInformation: [],
+            recommendedRoute: 'semantic',
+        },
+        evidence: {
+            snapshotId: input.contextPack?.knowledgeLens?.snapshotId ?? input.contextPack?.id ?? 'legacy-answer-loop-snapshot',
+            sourceFingerprint: capability.sourceFingerprint,
+            candidates,
+        },
+        candidates,
+        mode: 'authoritative',
+    });
+}
 export async function answer(input) {
     const inheritedPlan = !input.resolvedAnalyticalPlan
         && input.followUp?.priorResolvedAnalyticalPlan
@@ -694,6 +832,11 @@ export async function answer(input) {
             resolvedAnalyticalPlan: normalizedInput.resolvedAnalyticalPlan,
         };
     }
+    if (!normalizedInput.resolvedAnalyticalPlan) {
+        const migratedPlan = await freezeLegacySemanticSelection(normalizedInput);
+        if (migratedPlan)
+            normalizedInput = { ...normalizedInput, resolvedAnalyticalPlan: migratedPlan };
+    }
     const executionRegistry = buildPlanExecutionRegistry({
         nodes: [
             ...normalizedInput.kg.getNodesByKind('block', 100_000),
@@ -731,7 +874,7 @@ export async function answer(input) {
                         request: freshnessRequest,
                         registry: executionRegistry,
                         semanticLayer: normalizedInput.semanticLayer,
-                        expectedSnapshotId: normalizedInput.contextPack?.knowledgeLens.snapshotId,
+                        expectedSnapshotId: normalizedInput.contextPack?.knowledgeLens?.snapshotId,
                     })
                     : undefined;
                 if (adapterBinding?.status === 'blocked') {
@@ -788,7 +931,7 @@ export async function answer(input) {
             plan: normalizedInput.resolvedAnalyticalPlan,
             registry: executionRegistry,
             semanticLayer: normalizedInput.semanticLayer,
-            expectedSnapshotId: normalizedInput.contextPack?.knowledgeLens.snapshotId,
+            expectedSnapshotId: normalizedInput.contextPack?.knowledgeLens?.snapshotId,
         })
         : undefined;
     const analyticalCapability = normalizedInput.resolvedAnalyticalPlan
@@ -801,9 +944,11 @@ export async function answer(input) {
         ? analyticalCapability.executionCapabilities.find((candidate) => candidate.route === analyticalRoute)?.adapterId
         : undefined;
     const multiMetricPlan = (normalizedInput.resolvedAnalyticalPlan?.analyticalFrame?.metricConceptIds.length ?? 0) > 1;
+    const generatedProposalPlan = normalizedInput.resolvedAnalyticalPlan?.capability === 'bounded_exploration';
     const analyticalGraphBuild = normalizedInput.resolvedAnalyticalPlan?.schemaVersion === 2
         && normalizedInput.resolvedAnalyticalPlan.analyticalFrame
         && !multiMetricPlan
+        && !generatedProposalPlan
         && !normalizedInput.analyticalPeriodResolutionFailure
         && analyticalCapability
         && analyticalRoute
@@ -819,6 +964,7 @@ export async function answer(input) {
         : undefined;
     const analyticalExecutionGraphFailure = normalizedInput.resolvedAnalyticalPlan?.schemaVersion === 2
         && !multiMetricPlan
+        && !generatedProposalPlan
         ? analyticalGraphBuild?.status === 'blocked'
             ? {
                 code: analyticalGraphBuild.code,
@@ -839,7 +985,7 @@ export async function answer(input) {
             plan: normalizedInput.resolvedAnalyticalPlan,
             registry: executionRegistry,
             semanticLayer: normalizedInput.semanticLayer,
-            expectedSnapshotId: normalizedInput.contextPack?.knowledgeLens.snapshotId,
+            expectedSnapshotId: normalizedInput.contextPack?.knowledgeLens?.snapshotId,
         })
         : undefined;
     const planBoundInput = resolvedPlanExecutionBinding || analyticalExecutionGraph || analyticalExecutionGraphFailure
@@ -1017,17 +1163,27 @@ function deriveAiRoute(result, metricMatch) {
         };
     }
     // Uncertified: a governed metric matched → semantic_metric; else generated preview.
-    if (result.sourceTier === 'semantic_layer' && metricMatch) {
+    if (result.sourceTier === 'semantic_layer' && (metricMatch || result.analyticalExecutionGraph?.route === 'semantic')) {
+        const metricName = metricMatch?.metric.name
+            ?? result.dqlArtifact?.metrics?.join(', ')
+            ?? result.analyticalExecutionGraph?.metricId;
         return {
             tier: 'semantic_metric',
-            label: `Answered from metric ${metricMatch.metric.name}`,
-            ref: metricMatch.metric.name,
+            label: metricName ? `Answered from metric ${metricName}` : 'Answered from the snapshot-bound semantic plan',
+            ...(metricName ? { ref: metricName } : {}),
         };
     }
     return result.dqlArtifact
         ? { tier: 'generated_sql', label: 'Prepared review-required DQL artifact with SQL preview.' }
         : { tier: 'generated_sql', label: 'Prepared review-required SQL preview.' };
 }
+/** "customers_customer_name" → "customers" for a question the user has to read. */
+function humanizeDeicticDimension(dimension) {
+    const leaf = dimension.split(/[.:]/).pop() ?? dimension;
+    const words = leaf.replace(/[_-]+/g, ' ').trim().toLowerCase();
+    const last = words.split(' ').filter(Boolean).pop() ?? words;
+    return last.endsWith('s') ? last : `${last}s`;
+}
 async function runAnswerLoop(input) {
     const { question, userId, domain, provider, kg, skills = [], blockHints = [] } = input;
     // AGT-004: with no explicit domain selection, let direct question evidence
@@ -1198,6 +1354,7 @@ async function runAnswerLoop(input) {
             input,
             binding: input.semanticGraphExecutionBinding,
             graph: input.analyticalExecutionGraph,
+            capability: normalizeMetricCapabilityContract(input.semanticGraphExecutionBinding.metricNode.payload?.analyticalCapability),
             considered,
             providerName: provider.name,
         });
@@ -1313,7 +1470,22 @@ async function runAnswerLoop(input) {
         };
     }
     if (authoritativePlanBinding?.status === 'blocked') {
-        const text = `The resolved analytical plan cannot execute safely: ${authoritativePlanBinding.reason}`;
+        // An ambiguous singular reference is answerable the moment the user says
+        // which one they meant, so offer the candidates rather than dead-ending.
+        // The old refusal shipped the binder's internal sentence as the answer
+        // text, which reached the user as a generic "could not be completed" card.
+        const choices = input.followUp?.deicticChoices;
+        const clarificationOptions = choices
+            ? choices.values.slice(0, 8).map((value) => ({
+                id: `member:${choices.dimension}:${value}`,
+                label: value,
+                kind: 'member',
+                question: `${question} (${value})`,
+            }))
+            : undefined;
+        const text = clarificationOptions?.length
+            ? `The previous answer listed ${choices.values.length} ${humanizeDeicticDimension(choices.dimension)}. Which one did you mean?`
+            : `The resolved analytical plan cannot execute safely: ${authoritativePlanBinding.reason}`;
         return {
             kind: 'no_answer',
             sourceTier: 'no_answer',
@@ -1322,8 +1494,12 @@ async function runAnswerLoop(input) {
             confidence: 0,
             text,
             answer: text,
-            refusalCode: authoritativePlanBinding.code === 'PLAN_BLOCKED' ? 'ambiguous' : 'grounding_gap',
+            // Offering real choices makes this a clarify turn, not a terminal block.
+            refusalCode: clarificationOptions?.length || authoritativePlanBinding.code === 'PLAN_BLOCKED'
+                ? 'ambiguous'
+                : 'grounding_gap',
             refusalDetails: { code: authoritativePlanBinding.code, message: authoritativePlanBinding.reason },
+            ...(clarificationOptions?.length ? { clarificationOptions } : {}),
             citations: contextPackCitations(input.contextPack, 8),
             considered,
             contextPack: input.contextPack,
@@ -1795,6 +1971,7 @@ async function runAnswerLoop(input) {
     let semanticBridgeAnswer;
     let semanticRuntimeFailure;
     let semanticExecutionTrace;
+    let aggregationCompilerReceipt;
     let semanticAttemptedArtifact;
     let semanticRuntimeCompiledAnswer = false;
     if (authoritativeSemanticBinding && input.semanticLayer) {
@@ -1902,7 +2079,7 @@ async function runAnswerLoop(input) {
         // AGT-005: a governed runtime failure is terminal for this selected metric. Do not
         // 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) {
+        if (!semanticBridgeAnswer && !semanticRuntimeFailure && input.allowProviderSemanticMemberSelection === true) {
             const requestedGroupingDims = requestedGroupingDimensions(questionPlan);
             const wantedBreakdown = questionPlan.requestedShape.dimensions.length > 0
                 || questionPlan.dimensionTerms.length > 0;
@@ -2219,6 +2396,7 @@ async function runAnswerLoop(input) {
                 reasoningEffort: input.reasoningEffort,
                 analysisDepth: input.analysisDepth,
                 toolCalls: proposalToolCalls,
+                providerPayloadGuard: input.providerPayloadGuard,
             });
         }
         catch (err) {
@@ -2230,7 +2408,19 @@ async function runAnswerLoop(input) {
                 throw input.signal.reason ?? err;
             if (err instanceof Error && (err.name === 'AbortError' || err.name === 'TimeoutError'))
                 throw err;
-            const text = `Provider error: ${err.message}`;
+            // DQL's own orchestration budget refusing a dispatch is NOT an upstream
+            // outage. Reporting it as one ("Claude subscription failed: the 25-second
+            // soft target elapsed") blames the user's AI provider for DQL's timer and
+            // sends them to debug the wrong system.
+            const budgetCode = err && typeof err === 'object' && 'code' in err
+                ? String(err.code)
+                : '';
+            const orchestrationBudget = budgetCode === 'RUN_SOFT_TARGET_EXCEEDED'
+                || budgetCode === 'PROVIDER_DISPATCH_BUDGET_EXHAUSTED'
+                || budgetCode === 'RUN_DEADLINE_INSUFFICIENT';
+            const text = orchestrationBudget
+                ? 'DQL stopped this run at its own time budget before the query could be settled. The AI provider did not fail. Retry, or use Research for a longer budget.'
+                : `Provider error: ${err.message}`;
             return {
                 kind: 'no_answer',
                 sourceTier: 'no_answer',
@@ -2240,7 +2430,10 @@ async function runAnswerLoop(input) {
                 text,
                 answer: text,
                 refusalCode: 'provider_error',
-                refusalDetails: { code: 'provider_error', message: text },
+                refusalDetails: {
+                    code: orchestrationBudget ? 'orchestration_budget_exhausted' : 'provider_error',
+                    message: orchestrationBudget ? `${text} (${err.message})` : text,
+                },
                 citations: [],
                 memoryContext: input.memoryContext,
                 evidence: buildNoAnswerEvidence({
@@ -2307,7 +2500,10 @@ async function runAnswerLoop(input) {
             executeGeneratedSql: input.executeGeneratedSql,
             signal: input.signal,
             reasoningEffort: input.reasoningEffort,
-            maxAlternatives: deepAlternativeCountForQuestion(questionPlan, intent),
+            // One initial generation plus one diverse candidate stays within the
+            // ordinary two-round ceiling. Candidates are validated without preview
+            // execution below; only the selected SQL reaches the gateway once.
+            maxAlternatives: 1,
         });
         if (selection.selected) {
             proposed = selection.selected.raw;
@@ -2368,13 +2564,16 @@ async function runAnswerLoop(input) {
             proposed = await generateProposalWithOptionalTools({
                 provider,
                 messages: [...messages, { role: 'system', content: FORCE_JOIN_INSTRUCTION }],
-                tools: stageBTools,
+                // One tool round per ordinary Ask. The second generation is a bounded
+                // composition correction over already-retrieved evidence.
+                tools: [],
                 questionPlan,
                 intent,
                 signal: input.signal,
                 reasoningEffort: input.reasoningEffort,
                 analysisDepth: input.analysisDepth,
                 toolCalls: proposalToolCalls,
+                providerPayloadGuard: input.providerPayloadGuard,
             });
             parsed = parseProposal(proposed);
         }
@@ -2446,6 +2645,48 @@ async function runAnswerLoop(input) {
         };
     }
     if (parsed.sql) {
+        const frozenPlan = input.resolvedAnalyticalPlan;
+        if (!governedMetricAnswer && frozenPlan?.mode === 'authoritative' && frozenPlan.schemaVersion === 2) {
+            const targetFingerprint = input.generatedProposalTargetFingerprint ?? '';
+            const validation = validateGeneratedAnalyticalProposal({
+                plan: frozenPlan,
+                expectedTargetFingerprint: targetFingerprint,
+                contextPack: input.contextPack,
+                dialect: input.semanticDriver,
+                proposal: {
+                    version: 1,
+                    planId: frozenPlan.planId,
+                    planFingerprint: frozenPlan.fingerprint,
+                    snapshotId: frozenPlan.snapshotId,
+                    executionId: frozenPlan.executionId ?? '',
+                    capabilityFingerprint: frozenPlan.selectedCapabilityFingerprint ?? '',
+                    targetFingerprint,
+                    sql: parsed.sql,
+                },
+            });
+            if (!validation.ok) {
+                return {
+                    kind: 'no_answer',
+                    sourceTier: 'no_answer',
+                    certification: 'analyst_review_required',
+                    reviewStatus: 'none',
+                    confidence: 0,
+                    text: GENERATED_ANALYTICAL_TUPLE_DRIFT_MESSAGE,
+                    answer: GENERATED_ANALYTICAL_TUPLE_DRIFT_MESSAGE,
+                    refusalCode: 'policy_blocked',
+                    refusalDetails: {
+                        code: validation.code,
+                        message: `${validation.message}: ${validation.driftCodes.join(', ')}`,
+                    },
+                    validationWarnings: validation.driftCodes,
+                    citations: contextPackCitations(input.contextPack, 8),
+                    memoryContext: input.memoryContext,
+                    contextPack: input.contextPack,
+                    considered,
+                    providerUsed: provider.name,
+                };
+            }
+        }
         const tightenedFlow = tightenSourceTargetFlowProjection(parsed.sql, question, questionPlan);
         if (tightenedFlow && tightenedFlow.sql !== parsed.sql) {
             parsed.sql = tightenedFlow.sql;
@@ -2479,8 +2720,52 @@ async function runAnswerLoop(input) {
     // semantic environment. A thin local retrieval pack cannot safely reject it
     // and replace it with a guessed leaf-measure SQL. Warehouse execution remains
     // the final binder/runtime check.
+    const toolOwnedMetricNames = semanticBridgeAnswer?.metrics
+        ?? compiledSemanticRecords.flatMap((record) => record.metrics);
+    const semanticProofAuthority = input.resolvedAnalyticalPlan
+        ? exactSemanticProofAuthority(input.resolvedAnalyticalPlan, semanticMetricNodes)
+        : (input.allowProviderSemanticMemberSelection === true || compiledSemanticRecords.length > 0)
+            ? exactToolSemanticProofAuthority(toolOwnedMetricNames, semanticMetricNodes)
+            : { metricObjects: [] };
+    const semanticProofContext = semanticRouteAggregationProofContext(input.contextPack, input.resolvedAnalyticalPlan, semanticProofAuthority.capability, semanticProofAuthority.metricObjects);
+    const toolOwnedSemanticProofContext = !input.resolvedAnalyticalPlan
+        && semanticProofAuthority.capability
+        && (input.allowProviderSemanticMemberSelection === true || compiledSemanticRecords.length > 0)
+        ? {
+            ...(semanticProofContext ?? {}),
+            questionPlan: {
+                ...(semanticProofContext?.questionPlan ?? buildAnalysisQuestionPlan(question)),
+                requestedShape: {
+                    ...(semanticProofContext?.questionPlan?.requestedShape ?? buildAnalysisQuestionPlan(question).requestedShape),
+                    grain: semanticBridgeAnswer?.dimensions[0] ?? semanticProofAuthority.capability.defaultResultGrainId,
+                    dimensions: semanticBridgeAnswer?.dimensions ?? [],
+                },
+            },
+        }
+        : semanticProofContext;
+    const semanticAggregationProof = governedMetricAnswer && !certifiedAdaptation
+        ? buildAggregationSafetyProof(parsed.sql, toolOwnedSemanticProofContext, input.semanticDriver, input.resolvedAnalyticalPlan?.fingerprint)
+        : undefined;
+    const semanticExecutionRequested = governedMetricAnswer
+        && !certifiedAdaptation
+        && Boolean(input.executeGeneratedSql || input.executeDqlArtifact);
+    const semanticAggregationAuthorityBlocked = semanticExecutionRequested
+        && semanticAggregationProof?.status !== 'safe';
     const initialValidation = semanticRuntimeCompiledAnswer
-        ? { ok: true, warnings: ['SQL compiled by the configured semantic runtime.'] }
+        ? semanticAggregationProof?.status === 'safe' || !semanticExecutionRequested
+            ? {
+                ok: true,
+                warnings: ['SQL compiled by the configured semantic runtime.'],
+                aggregationSafetyProof: semanticAggregationProof,
+            }
+            : {
+                ok: false,
+                code: 'unsafe_aggregation',
+                error: semanticAggregationSafetyFailure(semanticAggregationProof),
+                warnings: ['Semantic runtime compilation did not establish complete aggregation authority.'],
+                offending: undefined,
+                aggregationSafetyProof: semanticAggregationProof,
+            }
         : contextLedger.validateSql(parsed.sql, {
             question,
             intent,
@@ -2489,6 +2774,9 @@ async function runAnswerLoop(input) {
             memberBindings: input.followUp?.memberBindings,
             enforceAggregationIntegrity: !governedMetricAnswer,
         });
+    let aggregationSafetyProof = 'aggregationSafetyProof' in initialValidation
+        ? initialValidation.aggregationSafetyProof
+        : undefined;
     const rankedGrainGap = missingRankedGrainOutput(questionPlan, parsed.sql, semanticBridgeAnswer?.dimensions);
     contextValidation = initialValidation.ok && rankedGrainGap
         ? {
@@ -2498,14 +2786,37 @@ async function runAnswerLoop(input) {
             warnings: initialValidation.warnings,
         }
         : initialValidation.ok
-            ? { ok: true, warnings: initialValidation.warnings }
+            ? { ok: true, warnings: initialValidation.warnings, aggregationSafetyProof }
             : {
                 ok: false,
                 code: initialValidation.code,
                 error: initialValidation.error,
                 warnings: initialValidation.warnings,
                 offending: initialValidation.offending,
+                aggregationSafetyProof,
             };
+    // The route-specific semantic proof is authoritative for execution. Context
+    // validation can prove SQL names without proving that the selected metric's
+    // exact capability, grain, additivity and joins own this aggregate. Never let
+    // a broad context pack or warehouse success elevate that blocked state.
+    if (contextValidation.ok
+        && semanticAggregationAuthorityBlocked) {
+        aggregationSafetyProof = semanticAggregationProof;
+        contextValidation = {
+            ok: false,
+            code: 'unsafe_aggregation',
+            error: semanticAggregationSafetyFailure(semanticAggregationProof),
+            warnings: [
+                ...contextValidation.warnings,
+                'The selected semantic route lacks an exact positive aggregation proof.',
+            ],
+            aggregationSafetyProof: semanticAggregationProof,
+        };
+    }
+    else if (semanticAggregationProof) {
+        aggregationSafetyProof = semanticAggregationProof;
+        contextValidation = { ...contextValidation, aggregationSafetyProof: semanticAggregationProof };
+    }
     // A canonical member value that resolves to exactly one inspected column is
     // compiler-owned request state, not creative SQL. If the proposal omitted
     // that predicate entirely, inject it deterministically before spending the
@@ -2529,6 +2840,7 @@ async function runAnswerLoop(input) {
             const reboundGrainGap = rebound.ok
                 ? missingRankedGrainOutput(questionPlan, parsed.sql, semanticBridgeAnswer?.dimensions)
                 : undefined;
+            aggregationSafetyProof = rebound.aggregationSafetyProof;
             contextValidation = rebound.ok && !reboundGrainGap
                 ? { ok: true, warnings: [...rebound.warnings, ...injected.notes] }
                 : rebound.ok
@@ -2676,7 +2988,20 @@ async function runAnswerLoop(input) {
     // provider get the same single chance; any provider failure keeps the honest
     // refusal below. This mirrors the engine-level repair loop, applied to the
     // context-validation gate that previously refused on first failure.
-    if (!contextValidation.ok && !governedMetricAnswer && canUseLaneRepair(repairBudgetState, 'validation')) {
+    // Semantic aggregation authority cannot be created by a provider rewrite. In
+    // particular, clearing governedMetricAnswer after a blocked semantic proof
+    // must not turn that refusal into the generic SQL-repair lane: the provider
+    // could return grounded raw-row SQL and silently downgrade the attempt to an
+    // uncertified execution. Keep this semantic proof failure terminal while
+    // retaining only the separate typed warehouse SQL-only repair capability.
+    // Unsafe aggregation/rounding is never rewritten automatically until the SQL
+    // parser supplies exact nested-expression AST spans.
+    if (!contextValidation.ok
+        && contextValidation.code !== 'unsafe_aggregation'
+        && input.resolvedAnalyticalPlan?.mode !== 'authoritative'
+        && !semanticAggregationAuthorityBlocked
+        && !governedMetricAnswer
+        && canUseLaneRepair(repairBudgetState, 'validation')) {
         recordLaneRepair(repairBudgetState, 'validation');
         try {
             const failedSql = parsed.sql ?? '';
@@ -2782,7 +3107,9 @@ async function runAnswerLoop(input) {
             answer: text,
             proposedSql: parsed.sql,
             sql: parsed.sql,
-            trustLabel: input.contextPack?.trustLabel,
+            trustLabel: contextValidation.code === 'unsafe_aggregation'
+                ? 'blocked'
+                : input.contextPack?.trustLabel,
             sourceCertifiedBlock: followUpSourceBlock?.name ?? input.followUp?.sourceBlockName,
             contextPackId: input.contextPack?.id,
             validationWarnings: [
@@ -2808,6 +3135,7 @@ async function runAnswerLoop(input) {
             contextPack: input.contextPack,
             considered,
             providerUsed: provider.name,
+            aggregationSafetyProof,
         };
     }
     // The dbt-first join guard adjudicates GENERATED SQL — joins an LLM invented,
@@ -3050,6 +3378,7 @@ async function runAnswerLoop(input) {
                             memberBindings: input.followUp?.memberBindings,
                         });
                         if (repairedValidation.ok) {
+                            aggregationSafetyProof = repairedValidation.aggregationSafetyProof;
                             repairAttempts += 1;
                             // Adopt the corrected SQL, but do NOT let the repair prose become the answer.
                             repairNarrative = repaired.text?.trim() || undefined;
@@ -3282,6 +3611,7 @@ async function runAnswerLoop(input) {
         contextPack: input.contextPack,
         considered,
         providerUsed: provider.name,
+        aggregationSafetyProof,
         // Carry the governed metric match so the exit point can name a
         // `semantic_metric` route (spec 17, part C).
         _semanticMetricMatch: governedMetricAnswer ? semanticMetricMatch ?? undefined : undefined,
@@ -3322,6 +3652,23 @@ function resultColumnNames(result) {
     return columns?.length ? columns : undefined;
 }
 function analyticalCapabilityForPlan(plan, contextPack, registry = []) {
+    const selected = normalizeMetricCapabilityContract(plan.selectedCapability);
+    if (selected) {
+        const selectedMetricId = plan.analyticalFrame?.metricConceptIds[0]
+            ?? plan.query.measures[0]?.qualifiedId;
+        const exactRegistryAuthority = registry.some((entry) => Boolean(plan.executionId)
+            && entry.identities.includes(plan.executionId)
+            && normalizeMetricCapabilityContract(entry.node.payload?.analyticalCapability)?.sourceFingerprint
+                === selected.sourceFingerprint);
+        if (plan.selectedCapabilityFingerprint !== selected.sourceFingerprint
+            || (selectedMetricId && selected.metricId !== selectedMetricId && !exactRegistryAuthority))
+            return undefined;
+        return selected;
+    }
+    // New authoritative v2 plans always carry the exact normalized capability.
+    // A missing authority is terminal rather than permission to rematch by name.
+    if (plan.mode === 'authoritative' && plan.schemaVersion === 2)
+        return undefined;
     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];
@@ -3343,6 +3690,142 @@ function analyticalCapabilityForPlan(plan, contextPack, registry = []) {
     const byFingerprint = new Map(normalized.map((capability) => [capability.sourceFingerprint, capability]));
     return byFingerprint.size === 1 ? [...byFingerprint.values()][0] : undefined;
 }
+function semanticRouteAggregationProofContext(contextPack, plan, capability, exactMetricObjects = []) {
+    if (!plan || !capability) {
+        return exactMetricObjects.length > 0
+            ? { ...(contextPack ?? {}), objects: exactMetricObjects }
+            : contextPack;
+    }
+    const baseQuestionPlan = buildAnalysisQuestionPlan(plan.question);
+    if ((plan.selectedCapabilityFingerprint !== undefined
+        && plan.selectedCapabilityFingerprint !== capability.sourceFingerprint)
+        || (plan.analyticalFrame !== undefined
+            && plan.analyticalFrame.metricConceptIds[0] !== capability.metricId))
+        return {
+            ...(contextPack ?? {}),
+            objects: [],
+            questionPlan: {
+                ...baseQuestionPlan,
+                requestedShape: { ...baseQuestionPlan.requestedShape, dimensions: [] },
+            },
+        };
+    const contextMetricObjects = (contextPack?.objects ?? []).filter((object) => {
+        const objectCapability = normalizeMetricCapabilityContract(object.payload?.analyticalCapability);
+        if (!objectCapability || objectCapability.sourceFingerprint !== capability.sourceFingerprint)
+            return false;
+        return [object.objectKey, object.fullName, object.name, object.payload?.qualifiedId]
+            .filter((value) => Boolean(value))
+            .includes(plan.executionId ?? capability.metricId);
+    });
+    const relationshipIds = new Set(plan.relationshipPathIds);
+    const relationshipObjects = (contextPack?.objects ?? []).filter((object) => object.objectType.includes('relationship')
+        && [object.objectKey, object.fullName, object.name, object.payload?.qualifiedId]
+            .filter((value) => Boolean(value))
+            .some((value) => relationshipIds.has(value)));
+    const frozenDimensions = plan.analyticalFrame?.dimensions
+        .filter((dimension) => dimension.role === 'group_by' || dimension.role === 'rank_entity')
+        .map((dimension) => dimension.dimensionId);
+    const legacyCapabilityDimensions = !plan.analyticalFrame && plan.query.dimensions.length > 0
+        ? capability.dimensions.filter((dimension) => dimension.supportedRoles.includes('group_by'))
+        : [];
+    const dimensions = frozenDimensions
+        ?? (legacyCapabilityDimensions.length === plan.query.dimensions.length
+            ? legacyCapabilityDimensions.map((dimension) => dimension.dimensionId)
+            : plan.query.dimensions.flatMap((dimension) => dimension.qualifiedId ? [dimension.qualifiedId] : []));
+    const legacyGrains = legacyCapabilityDimensions.map((dimension) => dimension.entityId)
+        .filter((entityId) => capability.resultGrainIds.includes(entityId));
+    const grain = plan.analyticalFrame?.entityGrainIds[0]
+        ?? plan.entityGrain
+        ?? (legacyGrains.length === 1 ? legacyGrains[0] : undefined)
+        ?? (dimensions.length === 0 ? capability.defaultResultGrainId : undefined);
+    const exactObjects = new Map();
+    for (const object of [...contextMetricObjects, ...exactMetricObjects, ...relationshipObjects]) {
+        const authorityKey = `${object.objectKey}:${normalizeMetricCapabilityContract(object.payload?.analyticalCapability)?.sourceFingerprint ?? ''}`;
+        if (!exactObjects.has(authorityKey))
+            exactObjects.set(authorityKey, object);
+    }
+    return {
+        ...(contextPack ?? {}),
+        objects: [...exactObjects.values()],
+        questionPlan: {
+            ...baseQuestionPlan,
+            requestedShape: {
+                ...baseQuestionPlan.requestedShape,
+                dimensions,
+                ...(grain ? { grain } : {}),
+            },
+        },
+    };
+}
+function exactSemanticProofAuthority(plan, metricNodes) {
+    if (!plan)
+        return { metricObjects: [] };
+    const embedded = normalizeMetricCapabilityContract(plan.selectedCapability);
+    const planMetricIds = new Set([
+        plan.executionId,
+        ...plan.query.measures.flatMap((binding) => binding.qualifiedId ? [binding.qualifiedId] : []),
+    ].filter((value) => Boolean(value)));
+    const exactNodes = metricNodes.filter((metric) => {
+        const identities = [
+            metric.nodeId,
+            metric.payload?.qualifiedId,
+            metric.payload?.localId,
+        ].filter((value) => typeof value === 'string' && Boolean(value));
+        return identities.some((identity) => planMetricIds.has(identity));
+    });
+    const capabilities = exactNodes.flatMap((metric) => {
+        const capability = normalizeMetricCapabilityContract(metric.payload?.analyticalCapability);
+        return capability ? [capability] : [];
+    });
+    const selected = embedded ?? (new Map(capabilities.map((capability) => [capability.sourceFingerprint, capability])).size === 1
+        ? capabilities[0]
+        : undefined);
+    if (!selected || (plan.selectedCapabilityFingerprint && plan.selectedCapabilityFingerprint !== selected.sourceFingerprint)) {
+        return { metricObjects: [] };
+    }
+    return {
+        capability: selected,
+        metricObjects: exactNodes.flatMap((metric) => metric.payload ? [{
+                objectKey: metric.nodeId,
+                objectType: 'semantic_metric',
+                name: metric.name,
+                ...(metric.domain ? { domain: metric.domain } : {}),
+                ...(metric.status ? { status: metric.status } : {}),
+                payload: metric.payload,
+            }] : []),
+    };
+}
+function exactToolSemanticProofAuthority(metricNames, metricNodes) {
+    const exactNodes = [...new Set(metricNames)].flatMap((name) => {
+        const matches = metricNodes.filter((node) => node.name === name || node.name.endsWith(`.${name}`) || name.endsWith(`.${node.name}`));
+        return matches.length === 1 ? matches : [];
+    });
+    if (exactNodes.length !== new Set(metricNames).size)
+        return { metricObjects: [] };
+    const capabilities = exactNodes.flatMap((node) => {
+        const capability = normalizeMetricCapabilityContract(node.payload?.analyticalCapability);
+        return capability ? [capability] : [];
+    });
+    if (capabilities.length !== exactNodes.length)
+        return { metricObjects: [] };
+    return {
+        capability: capabilities[0],
+        metricObjects: exactNodes.map((metric) => ({
+            objectKey: metric.nodeId,
+            objectType: 'semantic_metric',
+            name: metric.name,
+            ...(metric.domain ? { domain: metric.domain } : {}),
+            ...(metric.status ? { status: metric.status } : {}),
+            payload: metric.payload,
+        })),
+    };
+}
+function semanticAggregationSafetyFailure(proof) {
+    const issues = proof?.issueCodes.length
+        ? proof.issueCodes.join(', ')
+        : 'AGGREGATION_PROOF_MISSING';
+    return `The selected semantic route did not establish an exact aggregation safety proof (${issues}). No SQL was executed.`;
+}
 function analyticalRouteForPlan(plan) {
     if (plan.capability === 'certified_execution' && plan.recommendedRoute === 'certified')
         return 'certified';
@@ -3440,6 +3923,8 @@ async function executeSemanticAnalyticalGraph(input) {
     const compiledSql = [];
     const artifacts = [];
     let semanticExecutionTrace;
+    let aggregationCompilerReceipt;
+    let aggregationSafetyProof;
     for (const invocation of input.binding.invocations) {
         const attemptedArtifact = semanticAttemptArtifact(layer, input.input.question, invocation.selection);
         let composed = composeSemanticQueryFromMembers({
@@ -3453,6 +3938,7 @@ async function executeSemanticAnalyticalGraph(input) {
             try {
                 const compiled = await input.input.semanticQueryCompiler(invocation.selection);
                 semanticExecutionTrace = compiled.trace;
+                aggregationCompilerReceipt = compiled.aggregationCompilerReceipt;
                 composed = composeSemanticQueryFromCompiledMembers({
                     semanticLayer: layer,
                     question: input.input.question,
@@ -3503,6 +3989,42 @@ async function executeSemanticAnalyticalGraph(input) {
                 failedBindings: [{ role: 'source_invocation', reasonCode: 'SEMANTIC_COMPILE_FAILED' }],
             });
         }
+        const compilerProof = semanticRatioCompilerProofBinding(layer, invocation.selection.metrics, input.capability, input.input.resolvedAnalyticalPlan, semanticTraceTargetFingerprint(semanticExecutionTrace), composed.sql, aggregationCompilerReceipt);
+        const proof = buildSemanticCompilationAggregationSafetyProof({
+            sql: composed.sql,
+            capability: input.capability,
+            semanticAuthority: input.input.resolvedAnalyticalPlan
+                ? buildSemanticProofAuthorityV1({
+                    plan: input.input.resolvedAnalyticalPlan,
+                    capability: input.capability,
+                    contextPack: input.input.contextPack,
+                    compilerReceipt: aggregationCompilerReceipt,
+                })
+                : undefined,
+            relationshipProofs: input.input.resolvedAnalyticalPlan?.relationshipProofs,
+            executionId: input.input.resolvedAnalyticalPlan?.executionId,
+            snapshotId: input.input.resolvedAnalyticalPlan?.snapshotId,
+            capabilityFingerprint: input.input.resolvedAnalyticalPlan?.selectedCapabilityFingerprint,
+            route: 'semantic',
+            adapterId: input.graph.adapterId,
+            ...compilerProof.binding,
+            ...(compilerProof.issueCodes.length
+                ? { compilerAuthorityIssueCodes: compilerProof.issueCodes }
+                : {}),
+            contextPack: semanticRouteAggregationProofContext(input.input.contextPack, input.input.resolvedAnalyticalPlan, input.capability),
+            dialect: input.input.semanticDriver,
+            planFingerprint: input.binding.planFingerprint,
+        });
+        aggregationSafetyProof = proof;
+        if (proof.status !== 'safe') {
+            return analyticalGraphFailureAnswer(input, 'EXECUTION_GRAPH_MISMATCH', semanticAggregationSafetyFailure(proof), {
+                phase: 'validation',
+                dqlArtifact: composed.dqlArtifact,
+                compiledSql: composed.sql,
+                semanticExecutionTrace,
+                aggregationSafetyProof: proof,
+            });
+        }
         compiledSql.push(composed.sql);
         artifacts.push(composed.dqlArtifact);
         const executor = input.input.executeDqlArtifact
@@ -3562,6 +4084,7 @@ async function executeSemanticAnalyticalGraph(input) {
             sql,
             ...(artifacts.length === 1 ? { dqlArtifact: artifacts[0] } : {}),
             analyticalExecutionGraph: input.graph,
+            aggregationSafetyProof,
             ...(semanticExecutionTrace
                 ? { semanticExecutionTrace: semanticTraceAfterExecution(semanticExecutionTrace, { executed: false }) }
                 : {}),
@@ -3606,6 +4129,7 @@ async function executeSemanticAnalyticalGraph(input) {
         ...(artifacts.length === 1 ? { dqlArtifact: artifacts[0] } : {}),
         result,
         analyticalExecutionGraph: input.graph,
+        aggregationSafetyProof,
         analyticalExecutionReceipt: executed.receipt,
         analyticalFacts: story.factSet,
         analyticalNarrative: story.narrative,
@@ -3618,6 +4142,137 @@ async function executeSemanticAnalyticalGraph(input) {
         providerUsed: input.providerName,
     };
 }
+function semanticRatioCompilerProofBinding(layer, selectedMetricNames, capability, plan, targetFingerprint, compiledSql, receipt) {
+    if (capability.aggregation.trim().toLowerCase() !== 'ratio')
+        return { issueCodes: [] };
+    if (receipt) {
+        const outputAlias = capability.declaredOutputIds?.length === 1
+            ? capability.declaredOutputIds[0]
+            : capability.metricId.split(/[:.]/).at(-1);
+        const { receiptFingerprint, ...receiptBody } = receipt;
+        const compiledExpression = outputAlias
+            ? buildSqlOutputExpressionSignature(compiledSql, outputAlias)
+            : undefined;
+        const dimensionIds = [...new Set(plan.analyticalFrame?.dimensions.map((dimension) => dimension.dimensionId) ?? [])].sort();
+        const relationshipPathIds = [...plan.relationshipPathIds].sort();
+        const relationshipProofFingerprints = [...new Set(plan.relationshipProofs?.map((proof) => proof.authorityFingerprint) ?? [])].sort();
+        const expectedOrderBy = semanticCompilerReceiptOrder(plan, capability);
+        if (receipt.version !== 1
+            || receipt.executionId !== plan.executionId
+            || receipt.capabilityFingerprint !== plan.selectedCapabilityFingerprint
+            || receipt.metricId !== capability.metricId
+            || receipt.operator !== 'ratio'
+            || receipt.planFingerprint !== plan.fingerprint
+            || receipt.snapshotId !== plan.snapshotId
+            || !targetFingerprint
+            || receipt.targetFingerprint !== targetFingerprint
+            || receipt.compiledSqlFingerprint !== semanticExecutionFingerprint(compiledSql)
+            || !compiledExpression
+            || receipt.compiledExpressionFingerprint !== semanticExecutionFingerprint(compiledExpression.canonicalExpression)
+            || receipt.orderedMeasureIds.join('|') !== capability.measureIds.join('|')
+            || [...receipt.dimensionIds].sort().join('|') !== dimensionIds.join('|')
+            || [...receipt.relationshipPathIds].sort().join('|') !== relationshipPathIds.join('|')
+            || [...receipt.relationshipProofFingerprints].sort().join('|') !== relationshipProofFingerprints.join('|')
+            || receipt.orderBy.length !== expectedOrderBy.length
+            || receipt.orderBy.some((order, index) => {
+                const expected = expectedOrderBy[index];
+                return !expected
+                    || normalizeSemanticProofId(order.expression) !== normalizeSemanticProofId(expected.expression)
+                    || order.direction !== expected.direction;
+            })
+            || receipt.outputAlias !== outputAlias
+            || receiptFingerprint !== semanticExecutionFingerprint(receiptBody)) {
+            return { issueCodes: ['SEMANTIC_COMPILER_RECEIPT_AUTHORITY_MISMATCH'] };
+        }
+        return {
+            binding: {
+                compilerMetricExpressionSql: receipt.metricExpressionSql,
+                compilerMetricId: receipt.metricId,
+                compilerMeasureIds: receipt.orderedMeasureIds,
+                compilerRelation: receipt.physicalRelation,
+                compilerRelationAliases: receipt.relationAliases,
+            },
+            issueCodes: [],
+        };
+    }
+    const selected = new Set(selectedMetricNames.map(normalizeSemanticProofId));
+    const capabilityMetric = normalizeSemanticProofId(capability.metricId);
+    const metrics = layer.listMetrics(undefined, { includeMeasures: false }).filter((metric) => {
+        const names = [metric.name, metric.cube ? `${metric.cube}.${metric.name}` : undefined]
+            .filter((value) => Boolean(value))
+            .map(normalizeSemanticProofId);
+        return names.includes(capabilityMetric)
+            && names.some((name) => selected.has(name));
+    });
+    if (metrics.length !== 1 || !metrics[0].sql.trim())
+        return { issueCodes: ['SEMANTIC_COMPILER_RECEIPT_AUTHORITY_MISSING'] };
+    const metric = metrics[0];
+    const measures = capability.measureIds.map((measureId) => {
+        const normalizedId = normalizeSemanticProofId(measureId);
+        const matches = layer.listMeasures().filter((measure) => {
+            const names = [measure.name, measure.cube ? `${measure.cube}.${measure.name}` : undefined]
+                .filter((value) => Boolean(value))
+                .map(normalizeSemanticProofId);
+            return names.includes(normalizedId)
+                && (!metric.cube || !measure.cube || measure.cube === metric.cube);
+        });
+        return matches.length === 1 ? matches[0] : undefined;
+    });
+    if (measures.some((measure) => !measure))
+        return { issueCodes: ['SEMANTIC_COMPILER_RECEIPT_AUTHORITY_MISSING'] };
+    const relations = Array.from(new Set(measures.map((measure) => measure.table.trim()).filter(Boolean)));
+    if (relations.length !== 1)
+        return { issueCodes: ['SEMANTIC_COMPILER_RECEIPT_AUTHORITY_MISSING'] };
+    return {
+        binding: {
+            compilerMetricExpressionSql: metric.sql,
+            compilerMetricId: capability.metricId,
+            compilerMeasureIds: [...capability.measureIds],
+            compilerRelation: relations[0],
+            ...(metric.cube ? { compilerRelationAliases: [metric.cube] } : {}),
+        },
+        issueCodes: [],
+    };
+}
+function semanticCompilerReceiptOrder(plan, capability) {
+    const ranking = plan.analyticalFrame?.ranking;
+    if (!ranking || ranking.byMetricId !== capability.metricId)
+        return [];
+    const metricOutput = plan.analyticalFrame?.requestedOutputs.find((output) => output.kind === 'metric_value'
+        && output.metricId === ranking.byMetricId
+        && (!ranking.byPeriodId || output.periodId === ranking.byPeriodId));
+    if (!metricOutput)
+        return [];
+    const order = [{ expression: metricOutput.id, direction: ranking.direction }];
+    if (ranking.tiePolicy !== 'stable_secondary_key')
+        return order;
+    const dimensionOutputs = plan.analyticalFrame.requestedOutputs
+        .filter((output) => output.kind === 'dimension');
+    return [
+        ...order,
+        ...dimensionOutputs.map((output) => ({ expression: output.id, direction: 'asc' })),
+    ];
+}
+function semanticTraceTargetFingerprint(trace) {
+    const targetBinding = trace?.targetBinding;
+    if (!targetBinding || typeof targetBinding !== 'object' || Array.isArray(targetBinding))
+        return undefined;
+    const executionTarget = targetBinding.executionTarget;
+    if (!executionTarget || typeof executionTarget !== 'object' || Array.isArray(executionTarget))
+        return undefined;
+    const identityFingerprint = executionTarget.identityFingerprint;
+    return typeof identityFingerprint === 'string' && identityFingerprint.trim()
+        ? identityFingerprint
+        : undefined;
+}
+function normalizeSemanticProofId(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/^semantic(?:::|:)/, '')
+        .replace(/^(?:metric|measure)[.:]/, '')
+        .replaceAll(':', '.');
+}
 async function executeGovernedRelationalAnalyticalGraph(input) {
     const sourceResults = {};
     const artifacts = [];
@@ -3822,6 +4477,7 @@ function analyticalGraphFailureAnswer(input, code, reason, artifacts = {}) {
         ...(artifacts.compiledSql ? { proposedSql: artifacts.compiledSql, sql: artifacts.compiledSql } : {}),
         ...(artifacts.dqlArtifact ? { dqlArtifact: artifacts.dqlArtifact } : {}),
         ...(artifacts.semanticExecutionTrace ? { semanticExecutionTrace: artifacts.semanticExecutionTrace } : {}),
+        ...(artifacts.aggregationSafetyProof ? { aggregationSafetyProof: artifacts.aggregationSafetyProof } : {}),
         citations: contextPackCitations(input.input.contextPack, 8),
         considered: input.considered,
         contextPack: input.input.contextPack,
@@ -3834,7 +4490,7 @@ function analyticalFailureForInput(input, diagnostic) {
         error: diagnostic.error,
         code: diagnostic.code,
         phase: diagnostic.phase,
-        snapshotId: plan?.snapshotId ?? input.contextPack?.knowledgeLens.snapshotId ?? 'snapshot-unavailable',
+        snapshotId: plan?.snapshotId ?? input.contextPack?.knowledgeLens?.snapshotId ?? 'snapshot-unavailable',
         runId: diagnostic.runId ?? plan?.planId,
         planFingerprint: plan?.fingerprint,
         dqlSource: diagnostic.dqlArtifact?.source,
@@ -6405,6 +7061,7 @@ async function generateProposalWithOptionalTools(input) {
         ...options,
         toolPolicy,
         maxToolCalls: toolBudget.maxToolCalls,
+        providerPayloadGuard: input.providerPayloadGuard,
         onToolCall: (event) => {
             const sink = input.toolCalls;
             if (sink)
@@ -6502,22 +7159,9 @@ async function scoreDeepGeneratedProposalCandidate(input, candidate) {
         validationOk = validation.ok;
         if (validation.ok) {
             score += 100;
-            if (input.executeGeneratedSql) {
-                try {
-                    result = await input.executeGeneratedSql(parsed.sql);
-                    score += 40;
-                    if (result.rowCount > 0)
-                        score += 8;
-                    const resultShape = validateAnswerResultShape(input.questionPlan, result);
-                    score -= resultShape.warnings.length * 6;
-                    if (generatedResultShapeIsPartial(resultShape))
-                        score -= 120;
-                }
-                catch (error) {
-                    executionError = error instanceof Error ? error.message : String(error);
-                    score -= 20;
-                }
-            }
+            // Budget authority: candidate comparison is parser/context validation
+            // only. Executing each candidate would violate the one-SQL-call ordinary
+            // Ask budget and make telemetry dependent on speculative work.
         }
         else {
             validationError = validation.error;