@duckcodeailabs/dql-agent 1.14.2 → 1.14.3-rc.1

package/dist/answer-loop.js

@@ -35,7 +35,7 @@ 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 { GENERATED_ANALYTICAL_TUPLE_DRIFT_MESSAGE, frozenRequiredOutputBindingProofsForPlan, validateFrozenRequiredOutputProjection, 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';
@@ -1161,9 +1161,17 @@ export async function answer(input) {
     const analyticalExecutionGraph = analyticalGraphBuild?.status === 'ready'
         ? analyticalGraphBuild.graph
         : undefined;
+    // A v2 plan can also be synthesized for legacy/direct AnswerLoop callers so
+    // they can opt into the deterministic compiler. That compatibility bridge is
+    // not a router freeze: it must not turn a missing optional graph/adapter into
+    // a terminal answer before the established, safe legacy semantic execution
+    // path is considered. Router-selected semantic plans carry the explicit
+    // `selectedCascadeTier` signal and remain immutable/terminal below.
+    const routerFrozenSemanticPlan = Boolean(frozenSemanticRouteForInput(normalizedInput));
     const analyticalExecutionGraphFailure = normalizedInput.resolvedAnalyticalPlan?.schemaVersion === 2
         && !multiMetricPlan
         && !generatedProposalPlan
+        && routerFrozenSemanticPlan
         ? analyticalGraphBuild?.status === 'blocked'
             ? {
                 code: analyticalGraphBuild.code,
@@ -1248,7 +1256,23 @@ export async function answer(input) {
         }
         : compiledInput;
     const loopResult = await runAnswerLoop(executionInput);
-    const result = applyHollowAnswerGate(validateCertifiedAnalyticalGraphAnswer(loopResult, executionInput.analyticalExecutionGraph, executionInput.resolvedAnalyticalPlan?.analyticalFrame));
+    let result = applyHollowAnswerGate(validateCertifiedAnalyticalGraphAnswer(loopResult, executionInput.analyticalExecutionGraph, executionInput.resolvedAnalyticalPlan?.analyticalFrame));
+    const frozenSemanticRoute = frozenSemanticRouteForInput(executionInput);
+    // A final defensive boundary keeps future return sites from accidentally
+    // restoring the old semantic -> generated fallthrough. Do not relabel an
+    // actual generated result as semantic: replace it with an inspectable,
+    // same-tier terminal failure instead.
+    const returnedNonSemanticRoute = frozenSemanticRoute && ((result.route !== undefined && result.route.tier !== 'semantic_metric')
+        || (result.route === undefined && result.kind !== 'no_answer' && result.sourceTier !== 'semantic_layer'));
+    if (returnedNonSemanticRoute && frozenSemanticRoute) {
+        result = frozenSemanticPlanFailureAnswer({
+            answerInput: executionInput,
+            considered: result.considered ?? [],
+            providerName: executionInput.provider.name,
+            code: 'EXECUTION_GRAPH_MISMATCH',
+            reason: `The pinned semantic plan ${frozenSemanticRoute.ref ?? 'selected by the router'} returned a non-semantic answer route. DQL did not substitute generated SQL.`,
+        });
+    }
     // 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
@@ -1256,7 +1280,7 @@ export async function answer(input) {
     // stale data" / "Certified · upstream failed". Non-certified or fresh answers
     // are unaffected.
     const { _semanticMetricMatch, ...publicResult } = result;
-    const chosenRoute = result.route ?? deriveAiRoute(result, _semanticMetricMatch);
+    const chosenRoute = frozenSemanticRoute ?? result.route ?? deriveAiRoute(result, _semanticMetricMatch);
     // P0 — record the high-level action this turn warranted, so callers can route
     // (compose_app → app build, investigate → research) and the UI can show the
     // agent's reasoning. Computed once at the single exit from the finished answer.
@@ -1390,6 +1414,69 @@ function deriveAiRoute(result, metricMatch) {
         ? { tier: 'generated_sql', label: 'Prepared review-required DQL artifact with SQL preview.' }
         : { tier: 'generated_sql', label: 'Prepared review-required SQL preview.' };
 }
+/**
+ * The router owns the cascade decision.  Once it freezes a semantic plan, the
+ * answer loop may either execute that exact plan or return a semantic-tier
+ * terminal failure.  It must never let an unavailable semantic adapter fall
+ * through to the legacy generated-SQL lane merely because the latter can still
+ * construct a preview.
+ */
+function frozenSemanticRouteForInput(input) {
+    const plan = input.resolvedAnalyticalPlan;
+    // `freezeLegacySemanticSelection()` upgrades older direct AnswerLoop callers
+    // to a typed plan so they can use the deterministic semantic compiler. That
+    // migration is not the router's immutable cascade freeze. The server-owned
+    // cascade explicitly carries `selectedCascadeTier: 'semantic'`; only that
+    // signal activates the no-downgrade boundary below. Otherwise direct legacy
+    // callers retain their established deterministic semantic behavior.
+    if (input.selectedCascadeTier !== 'semantic'
+        || plan?.mode !== 'authoritative'
+        || plan.capability !== 'semantic_execution')
+        return undefined;
+    const executionId = plan.executionId ?? plan.selectedConceptIds[0];
+    return {
+        tier: 'semantic_metric',
+        label: executionId
+            ? `Frozen semantic plan ${executionId}`
+            : 'Frozen semantic plan',
+        ...(executionId ? { ref: executionId } : {}),
+    };
+}
+function frozenSemanticPlanFailureAnswer(input) {
+    const { answerInput, considered, providerName, code, reason } = input;
+    const route = frozenSemanticRouteForInput(answerInput);
+    // Callers use this only for an authoritative semantic plan. Keep the
+    // fallback defensive so an internal misuse still produces a safe no-answer.
+    const analyticalFailure = analyticalFailureForInput(answerInput, {
+        error: { code, message: reason },
+        phase: 'compilation',
+        failedBindings: answerInput.resolvedAnalyticalPlan?.executionId
+            ? [{
+                    qualifiedId: answerInput.resolvedAnalyticalPlan.executionId,
+                    role: 'metric',
+                    reasonCode: code,
+                }]
+            : undefined,
+    });
+    return {
+        kind: 'no_answer',
+        sourceTier: 'no_answer',
+        certification: 'analyst_review_required',
+        reviewStatus: 'none',
+        confidence: 0,
+        text: analyticalFailure.message,
+        answer: analyticalFailure.message,
+        executionError: analyticalFailure.message,
+        refusalCode: 'grounding_gap',
+        refusalDetails: { code, message: analyticalFailure.message },
+        analyticalFailure,
+        ...(route ? { route } : {}),
+        citations: contextPackCitations(answerInput.contextPack, 8),
+        considered,
+        contextPack: answerInput.contextPack,
+        providerUsed: providerName,
+    };
+}
 /** "customers_customer_name" → "customers" for a question the user has to read. */
 function humanizeDeicticDimension(dimension) {
     const leaf = dimension.split(/[.:]/).pop() ?? dimension;
@@ -1419,6 +1506,7 @@ async function runAnswerLoop(input) {
     // or provider is dispatched.  Full retrieval stays on `input.contextPack`
     // for receipts and diagnostics only.
     const forcedExploratoryTier = input.selectedCascadeTier === 'exploratory_sql';
+    const frozenSemanticRoute = frozenSemanticRouteForInput(input);
     const exploratoryClosureContextPack = forcedExploratoryTier
         ? scopeContextPackToExploratoryCandidateClosure(scopedContextPack, input.exploratoryCandidateIds)
         : undefined;
@@ -1510,6 +1598,31 @@ async function runAnswerLoop(input) {
     const authoritativePlanBinding = !forcedExploratoryTier && input.resolvedAnalyticalPlan?.mode === 'authoritative'
         ? input.resolvedPlanExecutionBinding
         : undefined;
+    // `freezeLegacySemanticSelection()` attaches an authoritative-shaped v2
+    // plan for direct AnswerLoop compatibility. It is not the router-owned
+    // semantic cascade decision. Only an explicit selected semantic tier may
+    // make an adapter/graph miss terminal; direct callers retain the established
+    // deterministic metric path, which still applies the ordinary SQL safety
+    // validation before it can execute.
+    const legacyDirectSemanticPlan = input.selectedCascadeTier === undefined
+        && input.resolvedAnalyticalPlan?.mode === 'authoritative'
+        && input.resolvedAnalyticalPlan.recommendedRoute === 'semantic'
+        && !frozenSemanticRoute;
+    // A semantic freeze is an immutable execution authority, not a hint for the
+    // legacy loop.  In particular, projects that have indexed semantic metadata
+    // but have not configured the corresponding local semantic adapter used to
+    // continue into generated SQL.  Stop here with the selected plan's typed
+    // diagnostic instead; no provider, tool, or SQL work is allowed to replace
+    // it after freeze.
+    if (!forcedExploratoryTier && frozenSemanticRoute && !input.semanticLayer) {
+        return frozenSemanticPlanFailureAnswer({
+            answerInput: input,
+            considered,
+            providerName: provider.name,
+            code: 'SEMANTIC_LAYER_REQUIRED',
+            reason: `The pinned semantic adapter for ${frozenSemanticRoute.ref ?? 'the selected semantic plan'} is unavailable.`,
+        });
+    }
     if (!forcedExploratoryTier && input.analyticalPeriodResolutionFailure) {
         const failure = input.analyticalPeriodResolutionFailure;
         const structuredFailureCode = failure.error && typeof failure.error === 'object'
@@ -1601,7 +1714,11 @@ async function runAnswerLoop(input) {
             input,
             binding: input.semanticGraphExecutionBinding,
             graph: input.analyticalExecutionGraph,
-            capability: normalizeMetricCapabilityContract(input.semanticGraphExecutionBinding.metricNode.payload?.analyticalCapability),
+            // The execution registry identifies the adapter metric, but its compact
+            // node payload may omit the relationship-path metadata that was frozen
+            // on the RAP. Re-deriving aggregation proof from that projection makes
+            // an already accepted native MetricFlow grouping fail post-freeze.
+            capability: input.semanticGraphExecutionBinding.capability,
             considered,
             providerName: provider.name,
         });
@@ -1716,7 +1833,7 @@ async function runAnswerLoop(input) {
             providerUsed: provider.name,
         };
     }
-    if (authoritativePlanBinding?.status === 'blocked') {
+    if (authoritativePlanBinding?.status === 'blocked' && !legacyDirectSemanticPlan) {
         // 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
@@ -1792,7 +1909,7 @@ async function runAnswerLoop(input) {
         ? authoritativePlanBinding
         : undefined;
     const preferredSemanticMetric = authoritativeSemanticBinding?.metricNode
-        ?? (input.resolvedAnalyticalPlan?.mode === 'authoritative'
+        ?? (input.resolvedAnalyticalPlan?.mode === 'authoritative' && !legacyDirectSemanticPlan
             ? undefined
             : resolvePreferredSemanticMetric([input.preferredExecutionId, ...(input.preferredEvidenceIds ?? [])], semanticMetricNodes, kg));
     const semanticLayerForExec = input.semanticLayer;
@@ -1802,7 +1919,7 @@ async function runAnswerLoop(input) {
         ? null
         : preferredSemanticMetric
             ? { metric: preferredSemanticMetric, score: 1, basis: 'name' }
-            : input.resolvedAnalyticalPlan?.mode === 'authoritative'
+            : input.resolvedAnalyticalPlan?.mode === 'authoritative' && !legacyDirectSemanticPlan
                 ? null
                 : await matchSemanticMetric(semanticQuestion, semanticMetricNodes, {
                     measureTerms: [...questionPlan.requestedShape.measures, ...questionPlan.metricTerms],
@@ -1981,6 +2098,7 @@ async function runAnswerLoop(input) {
     if (artifactHit && businessContextTerminal) {
         let result;
         let executionError;
+        let executionFailureDetail;
         if (artifactHit.node.kind === 'block' && input.executeCertifiedBlock) {
             try {
                 result = await input.executeCertifiedBlock(artifactHit.node, {
@@ -1993,6 +2111,7 @@ async function runAnswerLoop(input) {
                 result = trimResultToRequestedTopN(result, questionPlan);
             }
             catch (err) {
+                executionFailureDetail = analyticalErrorDetail(err);
                 executionError = err instanceof Error ? err.message : String(err);
             }
         }
@@ -2098,6 +2217,9 @@ async function runAnswerLoop(input) {
             ? undefined
             : questionPlan.requestedShape.topN?.n);
         const authoritativeCertifiedFailure = Boolean(authoritativeCertifiedBinding && executionError);
+        const observabilityExecutionFailure = authoritativeCertifiedFailure
+            ? observabilityFailureForFrozenExecution(executionFailureDetail)
+            : undefined;
         // A selected certified block which returns an incomplete tuple is a
         // same-tier terminal failure. It is not a reason to reinterpret meaning,
         // label the partial rows generated, or retry another route after freeze.
@@ -2143,6 +2265,7 @@ async function runAnswerLoop(input) {
                 block: artifactHit.node.kind === 'block' ? artifactHit.node : undefined,
                 result,
                 executionError,
+                ...(observabilityExecutionFailure ? { observabilityExecutionFailure } : {}),
                 ...(authoritativeCertifiedFailure || authoritativeCertifiedShapeFailure
                     ? { refusalCode: 'grounding_gap' }
                     : {}),
@@ -2637,8 +2760,21 @@ async function runAnswerLoop(input) {
             contextPack: input.contextPack,
             considered,
             providerUsed: provider.name,
+            ...(frozenSemanticRoute ? { route: frozenSemanticRoute } : {}),
         };
     }
+    // The semantic branch above has exhausted the exact plan's compiler and
+    // adapter choices.  Do not let `metricFirst` or the ordinary generated
+    // proposal branch reinterpret the question after a semantic freeze.
+    if (frozenSemanticRoute && !semanticBridgeAnswer) {
+        return frozenSemanticPlanFailureAnswer({
+            answerInput: input,
+            considered,
+            providerName: provider.name,
+            code: 'COMPILATION_FAILED',
+            reason: `The pinned semantic adapter could not compose ${frozenSemanticRoute.ref ?? 'the selected semantic plan'} without changing the frozen plan.`,
+        });
+    }
     const metricFirst = semanticMetricMatch
         ? buildGovernedMetricFirstSql({
             metric: semanticMetricMatch.metric,
@@ -2970,14 +3106,36 @@ async function runAnswerLoop(input) {
         || (input.contextPack?.allowedSqlContext?.relations.length ?? 0) > 0
         || (input.contextPack?.allowedSqlContext?.sourceBlockSql.length ?? 0) > 0
         || contextBlocks.length > 0;
+    // A selected bounded-exploration RAP is stronger than the advisory legacy
+    // analytical-path diagnosis.  The latter may still call raw output terms a
+    // semantic "missing dimension" even after the router has proven one safe
+    // physical relation and frozen the exploratory tuple.  Do not let that
+    // advisory pre-freeze diagnosis suppress the one explicitly authorized
+    // same-plan model-decline repair; the host re-validates the exact proposal
+    // against the frozen closure before it can execute.
+    const frozenExploratoryRepair = frozenExploratoryModelRepairAuthority(input);
     if (!parsed.sql && !governedMetricAnswer && wantsGeneratedData && hasGeneratableContext
-        && (analyticalPlan?.safe !== false || analyticalPlanAllowsDbtExploration(analyticalPlan))) {
+        && (frozenExploratoryRepair
+            || analyticalPlan?.safe !== false
+            || analyticalPlanAllowsDbtExploration(analyticalPlan))) {
         try {
             proposed = await generateProposalWithOptionalTools({
                 provider,
-                messages: [...messages, { role: 'system', content: FORCE_JOIN_INSTRUCTION }],
-                // One tool round per ordinary Ask. The second generation is a bounded
-                // composition correction over already-retrieved evidence.
+                messages: [...messages, {
+                        role: 'system',
+                        content: [
+                            FORCE_JOIN_INSTRUCTION,
+                            ...(frozenExploratoryRepair
+                                ? [renderFrozenExploratoryRepairContract(input.resolvedAnalyticalPlan, questionPlan)]
+                                : []),
+                        ].join('\n\n'),
+                    }],
+                // A router-frozen exploratory plan may consume exactly one additional
+                // provider transport to correct a model decline.  The host carries the
+                // immutable plan and output tuple into this retry; it is neither a
+                // replan nor a route change.  Legacy direct callers retain their
+                // historical composition correction, but do not receive the typed
+                // repair authority below.
                 tools: [],
                 questionPlan,
                 intent,
@@ -2986,6 +3144,13 @@ async function runAnswerLoop(input) {
                 analysisDepth: input.analysisDepth,
                 toolCalls: proposalToolCalls,
                 providerPayloadGuard: input.providerPayloadGuard,
+                ...(frozenExploratoryRepair
+                    ? {
+                        dispatchPhase: 'repair',
+                        egressPurpose: 'repair_sql',
+                        maxProviderDispatches: 1,
+                    }
+                    : {}),
             });
             parsed = parseProposal(proposed);
         }
@@ -3060,6 +3225,49 @@ async function runAnswerLoop(input) {
     }
     if (parsed.sql) {
         const frozenPlan = input.resolvedAnalyticalPlan;
+        // The result contract is host-owned even in tests or embedded callers
+        // that provide their own execution adapter.  Stop before capability
+        // preparation when a generated alias is backed by a different physical
+        // column than the frozen plan (for example `product_id AS order_id`).
+        // The local runtime repeats this check while minting the capability and
+        // persists the matching proof on its receipt.
+        if (input.selectedCascadeTier === 'exploratory_sql' && frozenPlan) {
+            const requiredOutputValidation = validateFrozenRequiredOutputProjection({
+                plan: frozenPlan,
+                sql: parsed.sql,
+                ...(input.semanticDriver ? { dialect: input.semanticDriver } : {}),
+            });
+            if (!requiredOutputValidation.ok) {
+                const failedOutputs = [...new Set([
+                        ...requiredOutputValidation.missingOutputs,
+                        ...requiredOutputValidation.bindingMismatches,
+                    ])];
+                const message = `The generated exploratory query did not prove the frozen source binding for required output ${failedOutputs.join(', ')}, so DQL did not execute it.`;
+                return {
+                    kind: 'no_answer',
+                    sourceTier: 'no_answer',
+                    certification: 'analyst_review_required',
+                    reviewStatus: 'none',
+                    confidence: 0,
+                    text: message,
+                    answer: message,
+                    refusalCode: 'policy_blocked',
+                    refusalDetails: {
+                        code: 'OUTPUT_BINDING_TUPLE_DRIFT',
+                        message,
+                    },
+                    validationWarnings: [
+                        'OUTPUT_BINDING_TUPLE_DRIFT',
+                        ...failedOutputs.map((output) => `Frozen output binding not proven: ${output}`),
+                    ],
+                    citations: contextPackCitations(input.contextPack, 8),
+                    memoryContext: input.memoryContext,
+                    contextPack: input.contextPack,
+                    considered,
+                    providerUsed: provider.name,
+                };
+            }
+        }
         if (!governedMetricAnswer && frozenPlan?.mode === 'authoritative' && frozenPlan.schemaVersion === 2) {
             const targetFingerprint = input.generatedProposalTargetFingerprint ?? '';
             const validation = validateGeneratedAnalyticalProposal({
@@ -3664,12 +3872,14 @@ async function runAnswerLoop(input) {
     let executionError;
     let warehouseFailure;
     let exploratoryClosureDenied = false;
+    let semanticFanoutProbeFailure;
     let repairAttempts = 0;
     // A forced proposal may originate from the bounded analyst loop, but it
     // cannot bypass a router-owned exploratory decision.  In that case the host
     // still prepares and freezes the exact validated SQL before execution.
     const exploratoryExecutionSelected = input.selectedCascadeTier === 'exploratory_sql';
-    let preparedExploratoryExecution;
+    let initialExploratoryExecution;
+    let exploratoryRepairExecution;
     // Repair candidates that were generated but rejected before execution. These
     // are diagnostics ABOUT the recovery attempt, not the reason the run failed,
     // so they are reported alongside the original error rather than replacing it.
@@ -3684,7 +3894,7 @@ async function runAnswerLoop(input) {
         executionError = deepCandidateExecutionError;
         warehouseFailure = normalizeWarehouseSqlFailure(deepCandidateExecutionError, input.semanticDriver);
     }
-    const executeCurrentSql = async () => {
+    const executeCurrentSql = async (authorizationAttempt) => {
         const requestedLimit = questionPlan.requestedShape.topN?.scope === 'per_group'
             ? 200
             : questionPlan.requestedShape.topN?.n ?? 200;
@@ -3725,17 +3935,23 @@ async function runAnswerLoop(input) {
                 });
             }
             // This is the only point at which a router-selected exploratory proposal
-            // crosses from validated text into executable authority. The callback
-            // rechecks the snapshot, physical target, and qualified runtime columns,
-            // then returns a one-shot capability bound to these exact SQL bytes.
-            preparedExploratoryExecution ??= await input.prepareExploratorySqlExecution(parsed.sql, boundedArtifact);
-            return input.executeAgenticGeneratedSql(preparedExploratoryExecution.capability, parsed.sql, boundedArtifact);
+            // crosses from validated text into executable authority. The first call
+            // receives the original one-shot capability. A retryable warehouse
+            // failure may mint exactly one *new* repair capability, explicitly bound
+            // to the first SQL fingerprint; it never reopens meaning or routing.
+            const prepared = authorizationAttempt
+                ? await input.prepareExploratorySqlExecution(parsed.sql, boundedArtifact, authorizationAttempt)
+                : (initialExploratoryExecution ??= await input.prepareExploratorySqlExecution(parsed.sql, boundedArtifact));
+            if (authorizationAttempt)
+                exploratoryRepairExecution = prepared;
+            return input.executeAgenticGeneratedSql(prepared.capability, parsed.sql, boundedArtifact);
         }
         if (!input.executeGeneratedSql)
             throw new Error('No generated SQL executor is configured.');
         return input.executeGeneratedSql(parsed.sql, boundedArtifact);
     };
     if ((input.executeGeneratedSql
+        || input.executeDqlArtifact
         || (input.forcedGeneratedProposal && input.executeAgenticGeneratedSql)
         || exploratoryExecutionSelected) && !result) {
         // Fanout gate for native semantic direct-joins: a duplicate join-key row on
@@ -3744,17 +3960,31 @@ async function runAnswerLoop(input) {
         // answers). Probe first; on structural contradiction, refuse with the cause
         // instead of presenting wrong numbers — and never hand the error to SQL
         // repair, which would regenerate the same multiplying join.
-        let fanoutContradiction = false;
+        let semanticFanoutBlocked = false;
         if (!executionError
             && !input.forcedGeneratedProposal
             && !exploratoryExecutionSelected
-            && input.executeGeneratedSql
             && semanticBridgeAnswer?.composeResult?.fanoutProbeSql
             && semanticBridgeAnswer.sql.trim() === parsed.sql?.trim()) {
-            const inflationError = await probeSemanticJoinFanout(semanticBridgeAnswer.composeResult.fanoutProbeSql, semanticBridgeAnswer.composeResult.tables, input.executeGeneratedSql);
-            if (inflationError) {
-                executionError = inflationError;
-                fanoutContradiction = true;
+            // A DQL-artifact executor owns the semantic artifact, not an arbitrary
+            // one-row structural SQL probe. If the host did not also provide the
+            // read-only SQL executor needed for that probe, native direct joins fail
+            // closed rather than treating an artifact handoff as proof of uniqueness.
+            const fanoutProbe = input.executeGeneratedSql
+                ? await probeSemanticJoinFanout(semanticBridgeAnswer.composeResult.fanoutProbeSql, semanticBridgeAnswer.composeResult.tables, input.executeGeneratedSql)
+                : {
+                    status: 'blocked',
+                    code: 'SEMANTIC_FANOUT_PROBE_ERROR',
+                    message: 'DQL did not execute this governed semantic answer because the host could not verify native join fanout before aggregation. Configure the semantic runtime or a read-only SQL probe executor, then retry.',
+                };
+            if (fanoutProbe.status === 'blocked') {
+                // A governed semantic route freezes before execution. If DQL cannot
+                // prove its native join is fanout-safe, it must fail closed rather than
+                // execute, label the result governed, or quietly repair into a
+                // different plan.
+                executionError = fanoutProbe.message;
+                semanticFanoutProbeFailure = fanoutProbe;
+                semanticFanoutBlocked = true;
             }
         }
         try {
@@ -3776,9 +4006,15 @@ async function runAnswerLoop(input) {
             executionError = warehouseFailure.redactedMessage;
         }
         if (executionError
-            && !input.forcedGeneratedProposal
-            && !exploratoryExecutionSelected
-            && !fanoutContradiction
+            // A host-supplied SQL proposal normally bypasses repair. A router-owned
+            // exploratory proposal is the exception: its frozen plan may authorize
+            // one corrected SQL statement after a retryable warehouse failure.
+            && (!input.forcedGeneratedProposal || exploratoryExecutionSelected)
+            // A router-selected exploratory plan may receive one bounded
+            // same-plan repair. The repair still goes through a fresh host
+            // authorization; it does not reuse the consumed initial capability.
+            && (!exploratoryExecutionSelected || Boolean(initialExploratoryExecution))
+            && !semanticFanoutBlocked
             && !authoritativeSemanticBinding) {
             warehouseFailure ??= normalizeWarehouseSqlFailure(executionError, input.semanticDriver);
             if (isRetryableGeneratedSqlError(warehouseFailure)) {
@@ -3804,7 +4040,13 @@ async function runAnswerLoop(input) {
                             ],
                         };
                         try {
-                            result = await executeCurrentSql();
+                            result = await executeCurrentSql(exploratoryExecutionSelected
+                                ? {
+                                    version: 1,
+                                    index: 1,
+                                    parentSqlFingerprint: initialExploratoryExecution.freeze.sqlFingerprint,
+                                }
+                                : undefined);
                             executionError = undefined;
                             warehouseFailure = undefined;
                         }
@@ -3836,6 +4078,18 @@ async function runAnswerLoop(input) {
                         schemaContext,
                         signal: input.signal,
                         reasoningEffort: input.reasoningEffort,
+                        // Only the router-frozen exploratory lane has authority to spend
+                        // the exceptional post-warehouse repair transport. Legacy callers
+                        // keep their prior unlabelled repair behavior.
+                        ...(exploratoryExecutionSelected
+                            && Boolean(initialExploratoryExecution)
+                            && frozenExploratoryModelRepairAuthority(input)
+                            ? {
+                                dispatchPhase: 'repair',
+                                egressPurpose: 'repair_sql',
+                                maxProviderDispatches: 1,
+                            }
+                            : {}),
                     });
                     const repaired = parseProposal(repairedRaw);
                     if (repaired.sql) {
@@ -3854,7 +4108,12 @@ async function runAnswerLoop(input) {
                             repairNarrative = repaired.text?.trim() || undefined;
                             parsed.sql = repaired.sql;
                             parsed.viz = repaired.viz ?? parsed.viz;
-                            applyParsedProposalMetadata(parsed, repaired);
+                            // A repair fixes SQL bytes only. On the router-owned
+                            // exploratory lane, model prose or metadata must never mutate
+                            // the host-selected frame, route, outputs, or trust state after
+                            // the plan froze.
+                            if (!exploratoryExecutionSelected)
+                                applyParsedProposalMetadata(parsed, repaired);
                             contextValidation = {
                                 ok: true,
                                 warnings: [
@@ -3863,7 +4122,13 @@ async function runAnswerLoop(input) {
                                 ],
                             };
                             try {
-                                result = await executeCurrentSql();
+                                result = await executeCurrentSql(exploratoryExecutionSelected
+                                    ? {
+                                        version: 1,
+                                        index: 1,
+                                        parentSqlFingerprint: initialExploratoryExecution.freeze.sqlFingerprint,
+                                    }
+                                    : undefined);
                                 executionError = undefined;
                                 warehouseFailure = undefined;
                             }
@@ -3893,12 +4158,14 @@ async function runAnswerLoop(input) {
         // A router-selected physical-closure denial happens before a capability
         // exists. Its rejected bytes are diagnostics for the host, never a SQL
         // preview that a user can review, copy, or turn into a draft.
-        sql: exploratoryClosureDenied ? undefined : parsed.sql,
+        sql: exploratoryClosureDenied || semanticFanoutProbeFailure ? undefined : parsed.sql,
         suggestedViz: parsed.viz ?? 'table',
         assumptions: [
             ...(exploratoryClosureDenied
                 ? ['The router-selected physical closure rejected the generated SQL before capability minting.']
-                : ['The SQL preview is uncertified until an analyst reviews and promotes the DQL artifact.']),
+                : semanticFanoutProbeFailure
+                    ? ['The native semantic join could not be proven fanout-safe before plan freeze, so DQL did not execute or expose its SQL.']
+                    : ['The SQL preview is uncertified until an analyst reviews and promotes the DQL artifact.']),
             ...(certifiedExecutionFallback
                 ? [`Certified block ${certifiedExecutionFallback.node.name} failed execution and was bypassed: ${certifiedExecutionFallback.error}`]
                 : []),
@@ -3922,6 +4189,23 @@ async function runAnswerLoop(input) {
         }
     }
     const resultShape = result ? validateAnswerResultShape(questionPlan, result) : undefined;
+    // A router-selected exploratory plan carries a host-bound output
+    // projection. The ordinary generated-answer UX may show a partial result
+    // with a warning, but a frozen exploratory plan may not: displaying it
+    // would silently change the tuple DQL authorized. Keep the connector rows
+    // out of the answer/artifact when a broken executor returns them anyway.
+    const missingFrozenExploratoryOutputs = exploratoryExecutionSelected && result
+        ? missingFrozenRequiredOutputProjection(input.resolvedAnalyticalPlan, result)
+        : [];
+    const activeExploratoryOutputFreeze = exploratoryRepairExecution?.freeze ?? initialExploratoryExecution?.freeze;
+    const missingFrozenExploratoryBindingProofs = exploratoryExecutionSelected && result
+        ? missingFrozenRequiredOutputBindingProof(input.resolvedAnalyticalPlan, activeExploratoryOutputFreeze)
+        : [];
+    const frozenExploratoryOutputFailures = [...new Set([
+            ...missingFrozenExploratoryOutputs,
+            ...missingFrozenExploratoryBindingProofs,
+        ])];
+    const frozenExploratoryOutputContractFailure = frozenExploratoryOutputFailures.length > 0;
     // ANY question whose SQL executed but dropped multiple requested columns used to
     // REFUSE outright ("no governed answer"), throwing away a result that actually
     // ran. Instead, SURFACE the partial result (review-required) with a warning that
@@ -3944,13 +4228,16 @@ async function runAnswerLoop(input) {
         ...repairNotes,
         ...(resultShape?.warnings ?? []),
         ...(partialShapeWarning ? [partialShapeWarning] : []),
+        ...(frozenExploratoryOutputContractFailure
+            ? [`The executed exploratory result violated the frozen output contract: ${frozenExploratoryOutputFailures.join(', ')}.`]
+            : []),
         ...(topNTrimNote ? [topNTrimNote] : []),
         ...(executionError ? ['The preview execution error must be reviewed before reuse.'] : []),
     ];
     const generatedOutputs = parsed.outputs?.length ? parsed.outputs : resultColumnNames(result);
     const generatedRequestedFilters = mergeProposalStringLists(input.followUp?.filters, parsed.requestedFilters);
     const generatedRequestedDimensions = mergeProposalStringLists(input.followUp?.dimensions, parsed.requestedDimensions);
-    const baseDqlArtifact = exploratoryClosureDenied
+    const baseDqlArtifact = exploratoryClosureDenied || semanticFanoutProbeFailure || frozenExploratoryOutputContractFailure
         ? undefined
         : result?.dqlArtifact ?? semanticBridgeAnswer?.dqlArtifact ?? buildGeneratedSqlDqlArtifact({
             question,
@@ -3979,7 +4266,7 @@ async function runAnswerLoop(input) {
         : undefined;
     let draftBlock;
     let draftCaptureError;
-    if (!exploratoryClosureDenied && input.captureGeneratedDraft && parsed.sql) {
+    if (!exploratoryClosureDenied && !semanticFanoutProbeFailure && !frozenExploratoryOutputContractFailure && input.captureGeneratedDraft && parsed.sql) {
         try {
             draftBlock = await input.captureGeneratedDraft({
                 question,
@@ -4026,10 +4313,21 @@ async function runAnswerLoop(input) {
         : undefined;
     const certifiedMetricAnswer = semanticMetricCertification === 'certified' || semanticMetricCertification === 'reviewed';
     const governedMetricExecutionFailure = governedMetricAnswer && Boolean(executionError);
-    const terminalExecutionFailure = governedMetricExecutionFailure || exploratoryClosureDenied;
+    const terminalExecutionFailure = governedMetricExecutionFailure || exploratoryClosureDenied || frozenExploratoryOutputContractFailure;
+    const semanticFanoutTraceError = semanticFanoutProbeFailure
+        ? Object.assign(new Error(semanticFanoutProbeFailure.message), {
+            code: semanticFanoutProbeFailure.code,
+            details: { phase: 'validation' },
+        })
+        : executionError;
+    const terminalFailureMessage = frozenExploratoryOutputContractFailure
+        ? `The exploratory execution result did not retain proven frozen output binding ${frozenExploratoryOutputFailures.join(', ')}, so DQL did not display it.`
+        : exploratoryClosureDenied
+            ? 'The generated SQL referenced a relation outside the router-selected physical closure, so DQL did not execute it.'
+            : semanticFanoutProbeFailure?.message;
     const finalSemanticExecutionTrace = semanticTraceAfterExecution(semanticExecutionTrace, {
         executed: Boolean(result),
-        ...(executionError ? { error: executionError } : {}),
+        ...(semanticFanoutTraceError ? { error: semanticFanoutTraceError } : {}),
         ...(result ? { result } : {}),
     });
     return {
@@ -4039,21 +4337,25 @@ async function runAnswerLoop(input) {
         reviewStatus: terminalExecutionFailure ? 'none' : governedMetricAnswer ? 'governed' : 'draft_ready',
         semanticMetricCertification,
         confidence: terminalExecutionFailure ? 0 : certifiedMetricAnswer ? 0.8 : governedMetricAnswer ? 0.72 : 0.55,
-        text: exploratoryClosureDenied
-            ? 'The generated SQL referenced a relation outside the router-selected physical closure, so DQL did not execute it.'
-            : generatedText,
-        answer: exploratoryClosureDenied
-            ? 'The generated SQL referenced a relation outside the router-selected physical closure, so DQL did not execute it.'
-            : generatedText,
-        ...(exploratoryClosureDenied ? {} : { proposedSql: parsed.sql, sql: parsed.sql }),
-        result,
+        text: terminalFailureMessage ?? generatedText,
+        answer: terminalFailureMessage ?? generatedText,
+        ...(exploratoryClosureDenied || semanticFanoutProbeFailure || frozenExploratoryOutputContractFailure ? {} : { proposedSql: parsed.sql, sql: parsed.sql }),
+        result: frozenExploratoryOutputContractFailure ? undefined : result,
         executionError,
         ...(warehouseFailure ? { warehouseFailure } : {}),
         ...(finalSemanticExecutionTrace ? { semanticExecutionTrace: finalSemanticExecutionTrace } : {}),
-        ...(terminalExecutionFailure ? { refusalCode: 'grounding_gap' } : {}),
+        ...(terminalExecutionFailure ? {
+            refusalCode: semanticFanoutProbeFailure ? 'policy_blocked' : 'grounding_gap',
+        } : {}),
+        ...(semanticFanoutProbeFailure ? {
+            refusalDetails: {
+                code: semanticFanoutProbeFailure.code,
+                message: semanticFanoutProbeFailure.message,
+            },
+        } : {}),
         suggestedViz: parsed.viz ?? 'table',
-        ...(exploratoryClosureDenied ? {} : { dqlArtifact: answerDqlArtifact }),
-        ...(exploratoryClosureDenied ? {} : {
+        ...(exploratoryClosureDenied || semanticFanoutProbeFailure || frozenExploratoryOutputContractFailure ? {} : { dqlArtifact: answerDqlArtifact }),
+        ...(exploratoryClosureDenied || semanticFanoutProbeFailure || frozenExploratoryOutputContractFailure ? {} : {
             draftBlock,
             draftBlockId: draftBlock?.path,
             promoteCommand: draftBlock ? `dql certify --from-draft ${draftBlock.path}` : undefined,
@@ -4095,7 +4397,8 @@ async function runAnswerLoop(input) {
         considered,
         providerUsed: provider.name,
         aggregationSafetyProof,
-        ...(preparedExploratoryExecution ? { exploratoryExecutionFreeze: preparedExploratoryExecution.freeze } : {}),
+        ...(initialExploratoryExecution ? { exploratoryExecutionFreeze: initialExploratoryExecution.freeze } : {}),
+        ...(exploratoryRepairExecution ? { exploratoryRepairExecutionFreeze: exploratoryRepairExecution.freeze } : {}),
         // Carry the governed metric match so the exit point can name a
         // `semantic_metric` route (spec 17, part C).
         _semanticMetricMatch: governedMetricAnswer ? semanticMetricMatch ?? undefined : undefined,
@@ -4135,6 +4438,70 @@ function resultColumnNames(result) {
         .filter(Boolean);
     return columns?.length ? columns : undefined;
 }
+/**
+ * Check only the host-bound aliases from a frozen plan. This is intentionally
+ * stricter than the conversational shape helper: synonym matching is useful
+ * for ordinary narration, but it cannot substitute a requested order/product
+ * identifier after exploratory SQL has been authorized.
+ */
+function missingFrozenRequiredOutputProjection(plan, result) {
+    const required = plan?.outputContract?.requiredOutputs ?? [];
+    if (required.length === 0)
+        return [];
+    const columns = new Set((resultColumnNames(result) ?? []).map(canonicalFrozenOutputAlias));
+    return required.flatMap((binding) => {
+        const alias = binding.outputName
+            ?? binding.qualifiedId?.split(/[:.]/).at(-1)
+            ?? binding.requested;
+        const normalized = canonicalFrozenOutputAlias(alias);
+        return normalized && columns.has(normalized) ? [] : [alias];
+    });
+}
+/**
+ * A column name in a returned result does not prove where it came from.  The
+ * result is accepted only when the server-owned authorization receipt carries
+ * the exact frozen output-source binding that was parser-validated for the SQL
+ * handed to the connector.  Old persisted receipts remain readable; they
+ * simply cannot authorize a new result for a plan that has explicit outputs.
+ */
+function missingFrozenRequiredOutputBindingProof(plan, freeze) {
+    const required = plan?.outputContract?.requiredOutputs ?? [];
+    if (required.length === 0)
+        return [];
+    const expected = frozenRequiredOutputBindingProofsForPlan(plan);
+    const missingSourceBindingAliases = required
+        .filter((binding) => !expected.some((proof) => canonicalFrozenOutputAlias(proof.outputName)
+        === canonicalFrozenOutputAlias(binding.outputName
+            ?? binding.qualifiedId?.split(/[:.]/).at(-1)
+            ?? binding.requested)))
+        .map((binding) => binding.outputName
+        ?? binding.qualifiedId?.split(/[:.]/).at(-1)
+        ?? binding.requested);
+    const actual = freeze?.requiredOutputBindings ?? [];
+    const missingProofAliases = expected
+        .filter((proof) => !actual.some((candidate) => sameFrozenRequiredOutputBindingProof(candidate, proof)))
+        .map((proof) => proof.outputName);
+    return [...new Set([...missingSourceBindingAliases, ...missingProofAliases])];
+}
+function sameFrozenRequiredOutputBindingProof(actual, expected) {
+    return actual.version === 1
+        && actual.qualifiedId === expected.qualifiedId
+        && canonicalFrozenOutputAlias(actual.outputName) === canonicalFrozenOutputAlias(expected.outputName)
+        && canonicalFrozenSourceIdentifier(actual.relation) === canonicalFrozenSourceIdentifier(expected.relation)
+        && canonicalFrozenSourceIdentifier(actual.column) === canonicalFrozenSourceIdentifier(expected.column);
+}
+function canonicalFrozenOutputAlias(value) {
+    return value.toLowerCase()
+        .replace(/["`]/g, '')
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+}
+function canonicalFrozenSourceIdentifier(value) {
+    return value.toLowerCase()
+        .replace(/["`\[\]]/g, '')
+        .replace(/\s*\.\s*/g, '.')
+        .trim();
+}
 function analyticalCapabilityForPlan(plan, contextPack, registry = []) {
     const selected = normalizeMetricCapabilityContract(plan.selectedCapability);
     if (selected) {
@@ -4501,8 +4868,11 @@ async function executeSemanticAnalyticalGraph(input) {
         });
         aggregationSafetyProof = proof;
         if (proof.status !== 'safe') {
-            return analyticalGraphFailureAnswer(input, 'EXECUTION_GRAPH_MISMATCH', semanticAggregationSafetyFailure(proof), {
-                phase: 'validation',
+            return analyticalGraphFailureAnswer(input, 'COMPILATION_FAILED', semanticAggregationSafetyFailure(proof), {
+                // This is compiler/plan validation before a warehouse statement is
+                // dispatched. It must be represented as semantic.compile, never as
+                // result normalization or a SQL execution failure.
+                phase: 'compilation',
                 dqlArtifact: composed.dqlArtifact,
                 compiledSql: composed.sql,
                 semanticExecutionTrace,
@@ -4528,11 +4898,25 @@ async function executeSemanticAnalyticalGraph(input) {
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
+            // A missing local execution target fails at the host's pre-execution
+            // boundary. It must not be recast as a semantic compiler failure merely
+            // because the semantic graph owns the callback. Preserve the narrow,
+            // producer-tagged fact for the durable Ask receipt; it does not alter
+            // the frozen route, trust, or user-facing analytical failure.
+            const observabilityExecutionFailure = observabilityFailureForFrozenExecution(analyticalErrorDetail(error));
             return analyticalGraphFailureAnswer(input, 'EXECUTION_FAILED', message, {
                 phase: 'execution',
                 dqlArtifact: composed.dqlArtifact,
                 compiledSql: composed.sql,
                 semanticExecutionTrace: semanticTraceAfterExecution(semanticExecutionTrace, { executed: false, error }),
+                // The exact aggregation proof already passed before the connector
+                // call. Preserve it so presentation never recasts a warehouse binder
+                // error as a failed semantic aggregation proof.
+                aggregationSafetyProof,
+                // This producer-tagged fact is diagnostic only: it does not alter
+                // routing, trust, or the immutable frozen plan.
+                warehouseFailure: normalizeWarehouseSqlFailure(error, input.input.semanticDriver),
+                ...(observabilityExecutionFailure ? { observabilityExecutionFailure } : {}),
             });
         }
         const normalized = normalizeAnalyticalSourceResult({
@@ -4962,6 +5346,10 @@ function analyticalGraphFailureAnswer(input, code, reason, artifacts = {}) {
         ...(artifacts.dqlArtifact ? { dqlArtifact: artifacts.dqlArtifact } : {}),
         ...(artifacts.semanticExecutionTrace ? { semanticExecutionTrace: artifacts.semanticExecutionTrace } : {}),
         ...(artifacts.aggregationSafetyProof ? { aggregationSafetyProof: artifacts.aggregationSafetyProof } : {}),
+        ...(artifacts.warehouseFailure ? { warehouseFailure: artifacts.warehouseFailure } : {}),
+        ...(artifacts.observabilityExecutionFailure
+            ? { observabilityExecutionFailure: artifacts.observabilityExecutionFailure }
+            : {}),
         citations: contextPackCitations(input.input.contextPack, 8),
         considered: input.considered,
         contextPack: input.input.contextPack,
@@ -5133,6 +5521,38 @@ Rules:
 // combined dataset — show them separately" refusal into the join the user asked
 // for, while still allowing an honest refusal if context is truly missing.
 const FORCE_JOIN_INSTRUCTION = `Your previous attempt declined to produce SQL. Re-read the supplied schema, metadata, and any "Knowledge graph join routes": this question CAN be answered by joining the grounded tables along their documented keys. Do NOT refuse, and do NOT suggest showing the datasets separately — compose ONE read-only SELECT/WITH that joins the relevant tables to answer it directly, following the JSON contract from rule 3. State the grain and the exact join path in the summary. Only if a required table, column, or join key is truly absent from the supplied context may you still ask a clarifying question.`;
+/**
+ * A model-decline correction is only a repair when the router already froze a
+ * bounded exploratory RAP and the host supplied the matching capability
+ * mint/consume closures.  Anything weaker is a new planning attempt and must
+ * not borrow the repair transport allowance.
+ */
+function frozenExploratoryModelRepairAuthority(input) {
+    const plan = input.resolvedAnalyticalPlan;
+    return input.selectedCascadeTier === 'exploratory_sql'
+        && plan?.mode === 'authoritative'
+        && plan.capability === 'bounded_exploration'
+        && Boolean(plan.planId && plan.fingerprint && plan.snapshotId)
+        && Boolean(input.prepareExploratorySqlExecution && input.executeAgenticGeneratedSql);
+}
+/**
+ * The corrective prompt repeats only host-owned tuple facts.  It never asks
+ * the model to choose a new route, relation closure, output contract, or
+ * trust label; SQL authorization re-proves those facts after the response.
+ */
+function renderFrozenExploratoryRepairContract(plan, questionPlan) {
+    const requiredOutputs = plan.outputContract?.requiredOutputs?.filter((output) => output.status === 'resolved' && output.outputName && output.qualifiedId)
+        .map((output) => `${output.outputName} <- ${output.qualifiedId}`)
+        ?? [];
+    return [
+        'This is the one permitted correction for an already frozen, review-required exploratory plan.',
+        renderRequestedShapeForRepair(questionPlan),
+        requiredOutputs.length > 0
+            ? `Frozen required output bindings (preserve exactly): ${requiredOutputs.join('; ')}`
+            : 'Preserve the frozen requested tuple exactly.',
+        'Use only the relations and columns already supplied in the bounded context. Do not add a relation, change the ranking, remove an output, change the limit, or alter the analytical meaning. The host will validate the same frozen snapshot and closure before execution.',
+    ].join('\n');
+}
 /**
  * Produces the prompt-facing subset of a broad local context pack. Global
  * records remain available, while a record explicitly owned by another domain
@@ -7842,6 +8262,11 @@ async function requestSqlRepair(input) {
         // bumping would let an internal preview-repair exceed that cap. Escalation-level
         // repairs bump-then-clamp in the host (resolveRunReasoningEffort).
         reasoningEffort: input.reasoningEffort,
+        ...(input.dispatchPhase ? { dispatchPhase: input.dispatchPhase } : {}),
+        ...(input.egressPurpose ? { egressPurpose: input.egressPurpose } : {}),
+        ...(input.maxProviderDispatches !== undefined
+            ? { maxProviderDispatches: input.maxProviderDispatches }
+            : {}),
     });
 }
 async function generateProposalWithOptionalTools(input) {
@@ -7849,6 +8274,11 @@ async function generateProposalWithOptionalTools(input) {
     const options = {
         signal: input.signal,
         reasoningEffort: input.reasoningEffort,
+        ...(input.dispatchPhase ? { dispatchPhase: input.dispatchPhase } : {}),
+        ...(input.egressPurpose ? { egressPurpose: input.egressPurpose } : {}),
+        ...(input.maxProviderDispatches !== undefined
+            ? { maxProviderDispatches: input.maxProviderDispatches }
+            : {}),
     };
     // No tools → plain generation (nothing for the loop to drive).
     if (tools.length === 0) {
@@ -8245,10 +8675,25 @@ function isRetryableGeneratedSqlError(failure) {
     return failure.retryDisposition === 'model_repair';
 }
 /**
- * Only SQL-shape/binding failures may leave the certified lane. Connectivity,
- * authorization, cancellation, and timeout failures would affect every query
- * route and must remain terminal rather than triggering wasteful provider work.
+ * Only SQL-shape/binding failures may leave a frozen governed lane.
+ * Connectivity, authorization, cancellation, and timeout failures would affect
+ * every query route and must remain terminal rather than triggering wasteful
+ * provider work.
  */
+function observabilityFailureForFrozenExecution(detail) {
+    // Do not infer this from user-facing error text. The local runtime tags the
+    // physical pre-execution boundary; this projection only carries that exact
+    // typed fact into the redacted trace after a governed plan has frozen.
+    if (detail?.origin !== 'host' || detail.stage !== 'execute' || detail.code !== 'connection_not_configured') {
+        return undefined;
+    }
+    return {
+        version: 1,
+        phase: 'execution',
+        cause: 'connection_not_configured',
+        safeAction: 'configure_connection',
+    };
+}
 function isRetryableCertifiedExecutionError(error) {
     return /\b(?:binder|parser|catalog)\s+error\b/i.test(error)
         // DuckDB says "ambiguous reference"; Snowflake says "ambiguous column name".
@@ -9213,29 +9658,45 @@ function uniqueAssets(assets) {
     return Array.from(byId.values());
 }
 /**
- * Execute the semantic layer's fanout probe and translate a structural
- * contradiction into an actionable refusal message. Probe failures (missing
- * permissions, dialect quirks) return undefined — the probe protects against
- * silent inflation but must never become a new way for a healthy query to fail.
+ * Execute the semantic layer's fanout probe before a governed native semantic
+ * join freezes. A native join that cannot be checked is not a governed-safe
+ * join: fail closed with a redacted typed failure instead of executing a query
+ * that could multiply aggregates. MetricFlow/dbt Cloud paths have their own
+ * compiler guarantees and do not use this native direct-join guard.
  */
 export async function probeSemanticJoinFanout(probeSql, joinedTables, executeSql) {
     try {
         const payload = await executeSql(probeSql);
         const counts = parseFanoutProbeCounts(payload);
-        if (!counts || counts.base <= 0 || counts.joined <= counts.base)
-            return undefined;
+        if (!counts || counts.base <= 0) {
+            return {
+                status: 'blocked',
+                code: 'SEMANTIC_FANOUT_PROBE_UNPARSEABLE',
+                message: 'DQL did not execute this governed semantic answer because its join-safety probe did not return verifiable row counts. Check the declared relationship or run the metric through MetricFlow / dbt Cloud, then retry.',
+            };
+        }
+        if (counts.joined <= counts.base)
+            return { status: 'safe' };
         const factor = counts.joined / counts.base;
         const tables = joinedTables.filter(Boolean).join(', ');
-        return [
-            `Blocked a governed semantic answer whose join inflates results: joining ${tables || 'the declared tables'}`,
-            `turned ${counts.base.toLocaleString('en-US')} base rows into ${counts.joined.toLocaleString('en-US')} (×${factor >= 10 ? Math.round(factor) : factor.toFixed(1)}).`,
-            'The declared join key is not unique on the joined side, so every aggregated value would be multiplied.',
-            'Deduplicate the joined model (for example, filter a slowly-changing dimension to current records)',
-            'or execute this metric through MetricFlow / dbt Cloud, then retry. No numbers were shown because they would be wrong.',
-        ].join(' ');
+        return {
+            status: 'blocked',
+            code: 'SEMANTIC_FANOUT_DUPLICATE_KEY',
+            message: [
+                `Blocked a governed semantic answer whose join inflates results: joining ${tables || 'the declared tables'}`,
+                `turned ${counts.base.toLocaleString('en-US')} base rows into ${counts.joined.toLocaleString('en-US')} (×${factor >= 10 ? Math.round(factor) : factor.toFixed(1)}).`,
+                'The declared join key is not unique on the joined side, so every aggregated value would be multiplied.',
+                'Deduplicate the joined model (for example, filter a slowly-changing dimension to current records)',
+                'or execute this metric through MetricFlow / dbt Cloud, then retry. No numbers were shown because they would be wrong.',
+            ].join(' '),
+        };
     }
     catch {
-        return undefined;
+        return {
+            status: 'blocked',
+            code: 'SEMANTIC_FANOUT_PROBE_ERROR',
+            message: 'DQL did not execute this governed semantic answer because it could not verify join fanout before aggregation. Check the declared relationship or run the metric through MetricFlow / dbt Cloud, then retry.',
+        };
     }
 }
 function parseFanoutProbeCounts(payload) {