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

package/dist/answer-loop.js

@@ -30,12 +30,12 @@ import { certifiedFitAllowsTier1, certifiedTerminationVerdict, evaluateCertified
 import { buildGovernedMetricFirstSql, matchSemanticMetric, resolveGovernedMetricDefinition, resolveGovernedMetricSql, semanticMetricEmbeddingOptions } from './metadata/metric-match.js';
 import { decideAgentAction } from './intent-controller.js';
 import { createContextLedger } from './grounding/context-ledger.js';
-import { validateAnswerResultShape } from './answer-shape.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 { 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';
@@ -384,6 +384,142 @@ function certifiedInvocationInputs(block, plan) {
     }
     return Object.keys(parameters).length > 0 ? { parameters, parameterSources } : {};
 }
+/**
+ * Return only output aliases that the selected certified artifact itself
+ * declares.  This is deliberately built after the router has frozen the plan:
+ * retrieval context, tags, examples, and sibling metrics never enter the
+ * result-shape proof.
+ *
+ * A block may express an entity role (`customer`) through a readable label
+ * column (`customer_name`), or a declared dimension role through a physical
+ * projection alias (`product_type`).  Those are valid execution contracts only
+ * when the selected block owns both sides of the binding.
+ */
+function frozenCertifiedResultShapeBindings(plan, block, questionPlan, options = {}) {
+    if (!plan || block.kind !== 'block')
+        return [];
+    const canonical = (value) => value
+        .toLowerCase()
+        .replace(/[_\-./]+/g, ' ')
+        .replace(/[^a-z0-9 ]+/g, ' ')
+        .split(/\s+/)
+        .filter(Boolean)
+        .map((token) => token.endsWith('ies') && token.length > 4
+        ? `${token.slice(0, -3)}y`
+        : token.endsWith('s') && token.length > 3
+            ? token.slice(0, -1)
+            : token)
+        .join('_');
+    const declared = (block.outputContract?.length
+        ? block.outputContract.map((output) => ({ name: output.name, role: output.role }))
+        : (block.declaredOutputs ?? []).map((name) => ({ name })))
+        .filter((output) => Boolean(output.name?.trim()));
+    const declaredByCanonical = new Map(declared.map((output) => [canonical(output.name), output]));
+    const bindings = [];
+    const add = (binding) => {
+        const key = `${binding.role}\0${canonical(binding.requested)}\0${canonical(binding.output)}`;
+        const existing = bindings.find((candidate) => `${candidate.role}\0${canonical(candidate.requested)}\0${canonical(candidate.output)}` === key);
+        if (existing) {
+            const aliases = [...(existing.aliases ?? []), ...(binding.aliases ?? [])]
+                .map((alias) => alias.trim())
+                .filter(Boolean);
+            if (aliases.length > 0)
+                existing.aliases = Array.from(new Set(aliases));
+            return;
+        }
+        bindings.push(binding);
+    };
+    // Measures are only admitted when the frozen plan retained the block's
+    // strict, artifact-local declared output identity.  Do not infer an alias
+    // from output role here: that would reintroduce lifetime_spend -> revenue.
+    for (const measure of plan.query.measures) {
+        if (!measure.outputName)
+            continue;
+        const output = declaredByCanonical.get(canonical(measure.outputName));
+        if (output)
+            add({ requested: measure.requested, output: output.name, role: 'measure' });
+    }
+    const requestedDimensions = Array.from(new Set([
+        ...plan.query.dimensions.map((binding) => binding.requested),
+        ...questionPlan.requestedShape.dimensions,
+    ].map((value) => canonical(value)).filter(Boolean)));
+    const declaredEntities = new Set((block.entities ?? []).map(canonical).filter(Boolean));
+    const declaredDimensions = new Set((block.dimensions ?? []).map(canonical).filter(Boolean));
+    const typedDimensionOutputs = declared.filter((output) => output.role === 'dimension');
+    for (const requested of requestedDimensions) {
+        // The declared entity role can be rendered as a standard display label,
+        // e.g. `customer` -> `customer_name`.  Require both the authored entity
+        // declaration and the output's explicit entity-label shape.
+        if (declaredEntities.has(requested)) {
+            const entityLabel = declared.find((output) => {
+                const outputName = canonical(output.name);
+                return output.role === 'entity_label'
+                    || outputName === `${requested}_name`
+                    || outputName === `${requested}_label`;
+            });
+            if (entityLabel)
+                add({ requested, output: entityLabel.name, role: 'entity_label' });
+        }
+        // An exact declared output is an artifact-local business-dimension binding
+        // even when an older authored block predates explicit `role = dimension`.
+        // This is not a pooled or lexical alias: both the requested business
+        // dimension and the selected artifact's own projection must agree.
+        const exactDeclaredDimension = declaredByCanonical.get(requested);
+        if (declaredDimensions.has(requested) && exactDeclaredDimension) {
+            add({ requested, output: exactDeclaredDimension.name, role: 'dimension' });
+            // Otherwise a physical output can stand for a business dimension only when
+            // the block declares that dimension and has one unambiguous typed
+            // dimension projection. Multiple physical outputs require an authored
+            // alias rather than a guess.
+        }
+        else if (declaredDimensions.has(requested) && typedDimensionOutputs.length === 1) {
+            add({ requested, output: typedDimensionOutputs[0].name, role: 'dimension' });
+        }
+    }
+    // An exact *unique* authored example can prove that a parser token is a
+    // member value of the selected block's already-declared dimension.  For
+    // example, the block-owned example "revenue by food and drink" returns the
+    // declared `category` output; `food` is not an independently requested
+    // physical column.  Keep this binding intentionally local to the frozen
+    // block and its resolved dimension: no tags, descriptions, sibling evidence,
+    // or general lexical aliases are admitted here.  Measures remain strict.
+    if (options.uniqueExactExampleContract === true) {
+        const plannedDimensions = new Set(plan.query.dimensions.map((binding) => canonical(binding.requested)));
+        const resolvedDimensionBindings = bindings.filter((binding) => binding.role === 'dimension'
+            && plannedDimensions.has(canonical(binding.requested))
+            && declaredByCanonical.has(canonical(binding.output)));
+        if (resolvedDimensionBindings.length === 1) {
+            const dimensionBinding = resolvedDimensionBindings[0];
+            const protectedTerms = new Set([
+                ...questionPlan.requestedShape.measures,
+                ...plan.query.measures.map((binding) => binding.requested),
+                ...questionPlan.requestedShape.filters,
+            ].map(canonical).filter(Boolean));
+            const structuralRoles = new Set([
+                'product', 'customer', 'account', 'user', 'member', 'category', 'segment',
+                'region', 'channel', 'order', 'day', 'week', 'month', 'quarter', 'year',
+            ]);
+            const memberNoise = Array.from(new Set([
+                ...questionPlan.requestedShape.dimensions,
+                ...questionPlan.requestedShape.requiredOutputs,
+            ].map(canonical).filter(Boolean))).filter((token) => token !== canonical(dimensionBinding.requested)
+                && !declaredByCanonical.has(token)
+                && !declaredEntities.has(token)
+                && !declaredDimensions.has(token)
+                && !protectedTerms.has(token)
+                && !structuralRoles.has(token));
+            if (memberNoise.length > 0) {
+                add({
+                    requested: dimensionBinding.requested,
+                    output: dimensionBinding.output,
+                    role: 'dimension',
+                    aliases: memberNoise,
+                });
+            }
+        }
+    }
+    return bindings;
+}
 function damerauLevenshteinDistance(left, right) {
     const rows = left.length + 1;
     const columns = right.length + 1;
@@ -1025,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,
@@ -1112,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
@@ -1120,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.
@@ -1201,6 +1361,20 @@ function cascadeExecutionStatus(result) {
  */
 function deriveAiRoute(result, metricMatch) {
     if (result.kind === 'no_answer') {
+        // Preserve the frozen certified tier as provenance when that exact block
+        // executed but failed its own result contract. The route is not a trust
+        // badge: `certification` remains review-required and no generated fallback
+        // may be selected after freeze.
+        if (result.certifiedResultShapeFailure && result.sourceTier === 'certified_artifact') {
+            const ref = result.sourceCertifiedBlock ?? result.block?.name ?? result.citations[0]?.name;
+            return {
+                tier: 'certified_block',
+                label: ref
+                    ? `Certified block ${ref} did not return the complete requested output shape.`
+                    : 'The selected certified block did not return the complete requested output shape.',
+                ref,
+            };
+        }
         if (result.exploratoryCandidate) {
             return {
                 tier: 'no_answer',
@@ -1240,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;
@@ -1264,6 +1501,18 @@ async function runAnswerLoop(input) {
     const scopedContextPack = questionDomainScope.length > 0
         ? scopeContextPackToQuestionDomains(input.contextPack, questionDomainScope, input.manifest)
         : input.contextPack;
+    // The router has already chosen the physical exploratory closure.  Treat it
+    // as an execution authority boundary here, before any prompt is constructed
+    // 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;
+    const executionContextPack = forcedExploratoryTier
+        ? exploratoryClosureContextPack
+        : scopedContextPack;
     // Select the RELEVANT skills (not all) for this question; keep pinned project
     // skills (SQL conventions). Block hints still come from the full set so a
     // preferred-block mapping is never lost.
@@ -1305,7 +1554,7 @@ async function runAnswerLoop(input) {
     const semanticHits = kg.search({ query: question, ...searchScope, kinds: SEMANTIC_KINDS, limit: 12 });
     const manifestHits = kg.search({ query: question, ...searchScope, kinds: MANIFEST_KINDS, limit: 12 });
     const considered = mergeHits(artifactHits, semanticHits, manifestHits, kg.search({ query: question, domain, limit: 10 })).slice(0, 30);
-    const schemaContext = schemaContextWithAllowedSqlContext(schemaContextWithinQuestionScope(input.schemaContext ?? [], input.contextPack, scopedContextPack), scopedContextPack);
+    const schemaContext = schemaContextWithAllowedSqlContext(schemaContextWithinQuestionScope(input.schemaContext ?? [], input.contextPack, executionContextPack), executionContextPack);
     const catalogRoute = input.contextPack?.routeDecision;
     const baseQuestionPlan = input.contextPack?.questionPlan?.requestedShape
         ? input.contextPack.questionPlan
@@ -1321,12 +1570,60 @@ async function runAnswerLoop(input) {
     // "exact certified" route into the generation prompt. The model should decide
     // from compatible certified evidence, semantic members, and dbt/runtime
     // columns—not copy a customer-grain worked example into a product-grain ask.
-    const promptContextPack = contextPackForRequestedShape(scopedContextPack, question, questionPlan, kg);
+    const promptContextPack = contextPackForRequestedShape(executionContextPack, question, questionPlan, kg);
     const repairBudgetState = createCascadeBudgetState(input.cascadeBudgetModel);
-    const authoritativePlanBinding = input.resolvedAnalyticalPlan?.mode === 'authoritative'
+    // A pre-freeze exploratory selection is already the router's result of
+    // evaluating certified → semantic → relational eligibility.  Do not let the
+    // legacy answer loop independently rediscover a broad block or metric and
+    // replace that decision before it has attempted the selected bounded SQL
+    // path.  Frozen tiers retain their existing plan binding behavior.
+    if (forcedExploratoryTier && input.contextPack && !exploratoryClosureContextPack) {
+        const text = 'The router-selected exploratory path no longer has a complete same-snapshot physical relation closure, so DQL did not send SQL generation or execute a query.';
+        return {
+            kind: 'no_answer',
+            sourceTier: 'no_answer',
+            certification: 'analyst_review_required',
+            reviewStatus: 'none',
+            confidence: 0,
+            text,
+            answer: text,
+            refusalCode: 'grounding_gap',
+            refusalDetails: { code: 'grounding_gap', message: text },
+            citations: contextPackCitations(input.contextPack, 8),
+            contextPack: input.contextPack,
+            considered,
+            providerUsed: provider.name,
+        };
+    }
+    const authoritativePlanBinding = !forcedExploratoryTier && input.resolvedAnalyticalPlan?.mode === 'authoritative'
         ? input.resolvedPlanExecutionBinding
         : undefined;
-    if (input.analyticalPeriodResolutionFailure) {
+    // `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'
             && typeof failure.error.code === 'string'
@@ -1362,7 +1659,7 @@ async function runAnswerLoop(input) {
             providerUsed: provider.name,
         };
     }
-    if (input.analyticalExecutionGraphFailure) {
+    if (!forcedExploratoryTier && input.analyticalExecutionGraphFailure) {
         const failure = input.analyticalExecutionGraphFailure;
         const analyticalFailure = analyticalFailureForInput(input, {
             error: { code: failure.code, message: failure.reason },
@@ -1387,7 +1684,7 @@ async function runAnswerLoop(input) {
             providerUsed: provider.name,
         };
     }
-    if (input.semanticGraphExecutionBinding?.status === 'blocked') {
+    if (!forcedExploratoryTier && input.semanticGraphExecutionBinding?.status === 'blocked') {
         const failure = input.semanticGraphExecutionBinding;
         const analyticalFailure = analyticalFailureForInput(input, {
             error: { code: failure.code, message: failure.reason },
@@ -1412,17 +1709,21 @@ async function runAnswerLoop(input) {
             providerUsed: provider.name,
         };
     }
-    if (input.semanticGraphExecutionBinding?.status === 'ready' && input.analyticalExecutionGraph) {
+    if (!forcedExploratoryTier && input.semanticGraphExecutionBinding?.status === 'ready' && input.analyticalExecutionGraph) {
         return executeSemanticAnalyticalGraph({
             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,
         });
     }
-    if (input.governedAnalyticalGraphCompilation?.status === 'blocked') {
+    if (!forcedExploratoryTier && input.governedAnalyticalGraphCompilation?.status === 'blocked') {
         const failure = input.governedAnalyticalGraphCompilation;
         const analyticalFailure = analyticalFailureForInput(input, {
             error: { code: failure.code, message: failure.reason },
@@ -1447,7 +1748,7 @@ async function runAnswerLoop(input) {
             providerUsed: provider.name,
         };
     }
-    if (input.governedAnalyticalGraphCompilation?.status === 'compiled' && input.analyticalExecutionGraph) {
+    if (!forcedExploratoryTier && input.governedAnalyticalGraphCompilation?.status === 'compiled' && input.analyticalExecutionGraph) {
         return executeGovernedRelationalAnalyticalGraph({
             input,
             compilation: input.governedAnalyticalGraphCompilation,
@@ -1458,7 +1759,7 @@ async function runAnswerLoop(input) {
         });
     }
     const governedRelationalCompilation = input.governedRelationalCompilation;
-    if (governedRelationalCompilation?.status === 'blocked') {
+    if (!forcedExploratoryTier && governedRelationalCompilation?.status === 'blocked') {
         const analyticalFailure = analyticalFailureForInput(input, {
             error: { code: governedRelationalCompilation.code, message: governedRelationalCompilation.reason },
             phase: 'compilation',
@@ -1485,7 +1786,7 @@ async function runAnswerLoop(input) {
             providerUsed: provider.name,
         };
     }
-    if (governedRelationalCompilation?.status === 'compiled') {
+    if (!forcedExploratoryTier && governedRelationalCompilation?.status === 'compiled') {
         const dqlArtifact = renderGovernedRelationalDqlArtifact(governedRelationalCompilation);
         let result;
         let executionError;
@@ -1532,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
@@ -1549,9 +1850,15 @@ async function runAnswerLoop(input) {
         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}`;
+        const frozenCertifiedPlan = input.resolvedAnalyticalPlan?.mode === 'authoritative'
+            && input.resolvedAnalyticalPlan.capability === 'certified_execution';
+        const frozenCertifiedRef = input.resolvedAnalyticalPlan?.executionId;
         return {
             kind: 'no_answer',
-            sourceTier: 'no_answer',
+            // A binding/adapter failure after the router selected a certified
+            // execution authority is still a certified-tier terminal.  It must not
+            // be relabelled as generated merely because no rows were produced.
+            sourceTier: frozenCertifiedPlan ? 'certified_artifact' : 'no_answer',
             certification: 'analyst_review_required',
             reviewStatus: 'none',
             confidence: 0,
@@ -1563,6 +1870,15 @@ async function runAnswerLoop(input) {
                 : 'grounding_gap',
             refusalDetails: { code: authoritativePlanBinding.code, message: authoritativePlanBinding.reason },
             ...(clarificationOptions?.length ? { clarificationOptions } : {}),
+            ...(frozenCertifiedPlan ? {
+                route: {
+                    tier: 'certified_block',
+                    label: frozenCertifiedRef
+                        ? `The selected certified block ${frozenCertifiedRef} could not execute its frozen plan.`
+                        : 'The selected certified block could not execute its frozen plan.',
+                    ...(frozenCertifiedRef ? { ref: frozenCertifiedRef } : {}),
+                },
+            } : {}),
             citations: contextPackCitations(input.contextPack, 8),
             considered,
             contextPack: input.contextPack,
@@ -1593,24 +1909,26 @@ 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;
     const canExecuteSemanticMetricForMatch = input.canExecuteSemanticMetric
         ?? (semanticLayerForExec ? (name) => semanticLayerForExec.canComposeMetric(name) : undefined);
-    let semanticMetricMatch = preferredSemanticMetric
-        ? { metric: preferredSemanticMetric, score: 1, basis: 'name' }
-        : input.resolvedAnalyticalPlan?.mode === 'authoritative'
-            ? null
-            : await matchSemanticMetric(semanticQuestion, semanticMetricNodes, {
-                measureTerms: [...questionPlan.requestedShape.measures, ...questionPlan.metricTerms],
-                ...(canExecuteSemanticMetricForMatch ? { canExecute: canExecuteSemanticMetricForMatch } : {}),
-                ...(snapshotVectorMetricShortlist(input.contextPack).length
-                    ? { vectorMetricShortlist: snapshotVectorMetricShortlist(input.contextPack) }
-                    : {}),
-                ...semanticMetricEmbeddingOptions(input.embeddingProvider),
-            }).catch(() => null);
+    let semanticMetricMatch = forcedExploratoryTier
+        ? null
+        : preferredSemanticMetric
+            ? { metric: preferredSemanticMetric, score: 1, basis: 'name' }
+            : input.resolvedAnalyticalPlan?.mode === 'authoritative' && !legacyDirectSemanticPlan
+                ? null
+                : await matchSemanticMetric(semanticQuestion, semanticMetricNodes, {
+                    measureTerms: [...questionPlan.requestedShape.measures, ...questionPlan.metricTerms],
+                    ...(canExecuteSemanticMetricForMatch ? { canExecute: canExecuteSemanticMetricForMatch } : {}),
+                    ...(snapshotVectorMetricShortlist(input.contextPack).length
+                        ? { vectorMetricShortlist: snapshotVectorMetricShortlist(input.contextPack) }
+                        : {}),
+                    ...semanticMetricEmbeddingOptions(input.embeddingProvider),
+                }).catch(() => null);
     // Stage 1: certified artifact match. Blocks can be executed; dashboards,
     // Apps, and notebooks are returned as governed citations/navigation targets.
     const drilldownCertifiedHit = input.followUp?.kind === 'drilldown'
@@ -1630,8 +1948,10 @@ async function runAnswerLoop(input) {
             && objectNameInQuestion(question, node)
             && /\b(run|use|open|show|execute|certified|saved|block)\b/i.test(question));
     });
-    const shouldTryCertifiedRoute = shouldUseCertifiedRoute(catalogRoute, intent)
-        || explicitlyRequestedCertifiedBlock;
+    const shouldTryCertifiedRoute = !forcedExploratoryTier
+        && (shouldUseCertifiedRoute(catalogRoute, intent)
+            || questionPlan.mode === 'definition'
+            || explicitlyRequestedCertifiedBlock);
     const catalogCertifiedHit = shouldTryCertifiedRoute
         ? certifiedHitFromContextPack(input.contextPack, kg)
         : null;
@@ -1641,7 +1961,9 @@ async function runAnswerLoop(input) {
     // metric, so a high-scoring `top_beverage_customers` catalog hit could answer a
     // product-type → product-name flow request with customer rows.
     const unsafeCatalogCertifiedHit = catalogCertifiedHit?.node.kind === 'block'
-        && !hasCertifiedNodeFit(question, questionPlan, catalogCertifiedHit.node)
+        && !hasCertifiedNodeFit(question, questionPlan, catalogCertifiedHit.node, {
+            uniqueExactExampleContract: hasUniqueExactCatalogExample(question, input.contextPack, catalogCertifiedHit.node),
+        })
         ? null
         : catalogCertifiedHit;
     const fallbackCertifiedHit = shouldTryCertifiedRoute ? pickCertifiedArtifact({
@@ -1658,13 +1980,85 @@ async function runAnswerLoop(input) {
         && authoritativePlanBinding.kind === 'certified'
         ? authoritativePlanBinding
         : undefined;
+    const namedDefinitionArtifact = input.resolvedAnalyticalPlan?.mode === 'authoritative'
+        ? null
+        : uniqueNamedCertifiedDefinitionArtifact(question, kg, authorizedDomains);
     let artifactHit = authoritativeCertifiedBinding
         ? { node: authoritativeCertifiedBinding.node, score: 1 }
         : input.resolvedAnalyticalPlan?.mode === 'authoritative'
             ? null
-            : drilldownCertifiedHit ?? unsafeCatalogCertifiedHit
+            : namedDefinitionArtifact ?? drilldownCertifiedHit ?? unsafeCatalogCertifiedHit
                 ?? (catalogCertifiedHit ? null : fallbackCertifiedHit);
     let certifiedExecutionFallback;
+    // A named certified artifact-definition request is documentation about that
+    // artifact, not a request to execute its SQL.  The planner strips the
+    // artifact identifier from its output contract, and this deterministic path
+    // returns only authored metadata.  It is deliberately narrower than a bare
+    // "what is revenue" question: the user must name the certified block and use
+    // an explicit definition form before execution is bypassed.
+    if (artifactHit?.node.kind === 'block'
+        && artifactHit.node.status === 'certified'
+        && isUniqueNamedCertifiedDefinitionQuestion(question, artifactHit.node, kg, authorizedDomains)) {
+        const artifact = artifactHit.node;
+        const outputs = [...new Set([
+                ...(artifact.outputContract ?? []).map((output) => output.name),
+                ...(artifact.declaredOutputs ?? []),
+                ...(artifact.outputs ?? []).map((output) => output.name),
+            ].map((output) => output.trim()).filter(Boolean))].slice(0, 16);
+        const metadataLines = [
+            artifact.description ?? artifact.llmContext ?? 'No authored description is available for this certified artifact.',
+            outputs.length > 0 ? `Declared outputs: ${outputs.join(', ')}.` : undefined,
+            artifact.grain ? `Grain: ${artifact.grain}.` : undefined,
+            artifact.owner ? `Owner: ${artifact.owner}.` : undefined,
+            'This is certified artifact metadata, not a query result.',
+        ].filter((line) => Boolean(line));
+        const citations = [{
+                nodeId: artifact.nodeId,
+                kind: artifact.kind,
+                name: artifact.name,
+                gitSha: artifact.gitSha,
+                sourceTier: 'certified_artifact',
+                provenance: artifact.provenance,
+            }];
+        const analysisPlan = buildAnalysisPlan({
+            question,
+            intent: 'definition_lookup',
+            routeReason: 'The question explicitly requested the meaning of one named certified artifact; no SQL execution was requested.',
+            selectedNodes: [artifact],
+            schemaContext,
+        });
+        const text = `Certified artifact **${artifact.name}**\n\n${metadataLines.join('\n\n')}`;
+        return {
+            kind: 'certified',
+            sourceTier: 'certified_artifact',
+            certification: 'certified',
+            reviewStatus: 'certified',
+            confidence: 0.99,
+            text,
+            answer: text,
+            block: artifact,
+            sourceCertifiedBlock: artifact.name,
+            trustLabel: 'certified',
+            citations,
+            memoryContext: input.memoryContext,
+            analysisPlan,
+            evidence: buildCertifiedEvidence({
+                question,
+                artifact,
+                businessHits,
+                semanticHits,
+                manifestHits,
+                considered,
+                executorWasAvailable: false,
+                citations,
+                memoryContext: input.memoryContext ?? [],
+                analysisPlan,
+            }),
+            contextPack: input.contextPack,
+            considered,
+            providerUsed: provider.name,
+        };
+    }
     // Certified remains first when it actually covers the question. If the
     // retrieved block does not fit but a governed semantic metric does, never
     // let the broad catalog match pre-empt Lane 2.
@@ -1704,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, {
@@ -1716,6 +2111,7 @@ async function runAnswerLoop(input) {
                 result = trimResultToRequestedTopN(result, questionPlan);
             }
             catch (err) {
+                executionFailureDetail = analyticalErrorDetail(err);
                 executionError = err instanceof Error ? err.message : String(err);
             }
         }
@@ -1773,7 +2169,16 @@ async function runAnswerLoop(input) {
                 providerUsed: provider.name,
             };
         }
-        const resultShapeWarnings = result ? validateAnswerResultShape(questionPlan, result).warnings : [];
+        const resultShapeWarnings = result
+            ? validateAnswerResultShape(questionPlan, result, {
+                outputBindings: authoritativeCertifiedBinding
+                    ? frozenCertifiedResultShapeBindings(input.resolvedAnalyticalPlan, artifactHit.node, questionPlan, {
+                        uniqueExactExampleContract: hasUniqueExactCatalogExample(question, input.contextPack, artifactHit.node),
+                    })
+                    : [],
+                requireBoundMeasures: Boolean(authoritativeCertifiedBinding),
+            }).warnings
+            : [];
         // When a certified block's execution was ATTEMPTED and FAILED, the answer
         // cannot wear the certified badge — a failed run has no data to stand behind.
         // Downgrade to analyst_review_required (the error is surfaced in the text).
@@ -1812,6 +2217,13 @@ 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.
+        const authoritativeCertifiedShapeFailure = Boolean(authoritativeCertifiedBinding && !executionError && resultShapeWarnings.length > 0);
         const recoverableCertifiedFailure = artifactHit.node.kind === 'block'
             && executionError !== undefined
             && !authoritativeCertifiedFailure
@@ -1826,18 +2238,39 @@ async function runAnswerLoop(input) {
             artifactHit = null;
         }
         else {
+            const frozenCertifiedRoute = authoritativeCertifiedBinding
+                ? {
+                    tier: 'certified_block',
+                    label: certifiedShapePassed
+                        ? `Answered from certified block ${artifactHit.node.name}`
+                        : `The selected certified block ${artifactHit.node.name} could not complete its frozen output contract.`,
+                    ref: artifactHit.node.name,
+                }
+                : undefined;
             return {
-                kind: authoritativeCertifiedFailure ? 'no_answer' : certifiedShapePassed ? 'certified' : 'uncertified',
-                sourceTier: authoritativeCertifiedFailure ? 'no_answer' : sourceTier,
+                kind: authoritativeCertifiedFailure || authoritativeCertifiedShapeFailure
+                    ? 'no_answer'
+                    : certifiedShapePassed ? 'certified' : 'uncertified',
+                // Preserve the selected certified authority even when its own
+                // execution/result contract fails. The failure is terminal and has
+                // review-required trust, but it is not generated SQL.
+                sourceTier,
                 certification: certifiedShapePassed ? 'certified' : 'analyst_review_required',
-                reviewStatus: authoritativeCertifiedFailure ? 'none' : certifiedShapePassed ? 'certified' : 'analyst_review_required',
+                reviewStatus: authoritativeCertifiedFailure || authoritativeCertifiedShapeFailure
+                    ? 'none'
+                    : certifiedShapePassed ? 'certified' : 'analyst_review_required',
                 confidence: certifiedShapePassed ? 0.95 : 0.45,
                 text,
                 answer: text,
                 block: artifactHit.node.kind === 'block' ? artifactHit.node : undefined,
                 result,
                 executionError,
-                ...(authoritativeCertifiedFailure ? { refusalCode: 'grounding_gap' } : {}),
+                ...(observabilityExecutionFailure ? { observabilityExecutionFailure } : {}),
+                ...(authoritativeCertifiedFailure || authoritativeCertifiedShapeFailure
+                    ? { refusalCode: 'grounding_gap' }
+                    : {}),
+                ...(authoritativeCertifiedShapeFailure ? { certifiedResultShapeFailure: true } : {}),
+                ...(frozenCertifiedRoute ? { route: frozenCertifiedRoute } : {}),
                 sql: result?.sql,
                 dqlArtifact,
                 trustLabel: certifiedShapePassed ? input.contextPack?.trustLabel ?? 'certified' : 'mixed',
@@ -1875,7 +2308,7 @@ async function runAnswerLoop(input) {
     // a governed metric can answer. Match by name + synonyms + measure family + hybrid
     // rank over the FTS semantic hits, then ALL metric KG nodes (revenue ⇄
     // cumulative_revenue). Certified-first is still preserved (checked above).
-    const clarifyBeforeGeneration = shouldClarifyBeforeGeneration({
+    const clarifyBeforeGeneration = !forcedExploratoryTier && shouldClarifyBeforeGeneration({
         intent,
         routeDecision: catalogRoute,
         hasSemanticMetricMatch: Boolean(semanticMetricMatch),
@@ -1933,12 +2366,14 @@ async function runAnswerLoop(input) {
     // wins over raw dbt manifest context; memory is appended last as advisory.
     // A confident metric match forces the semantic tier even when FTS returned no
     // semantic hits, so the governed metric (not refusal) answers the question.
-    const activeTier = sourceTierFromContextPack(input.contextPack)
-        ?? (semanticHits.length > 0 || semanticMetricMatch
-            ? 'semantic_layer'
-            : manifestHits.length > 0
-                ? 'dbt_manifest'
-                : 'dbt_manifest');
+    const activeTier = forcedExploratoryTier
+        ? 'dbt_manifest'
+        : sourceTierFromContextPack(input.contextPack)
+            ?? (semanticHits.length > 0 || semanticMetricMatch
+                ? 'semantic_layer'
+                : manifestHits.length > 0
+                    ? 'dbt_manifest'
+                    : 'dbt_manifest');
     const reviewRequiredArtifactHits = artifactHits
         .filter((hit) => hit.score >= CERTIFIED_HIT_THRESHOLD && !isCertifiedHit(hit, kg))
         .slice(0, 4);
@@ -1971,7 +2406,13 @@ async function runAnswerLoop(input) {
             { hits: businessHits.slice(0, 4), reserve: 3 },
             { hits: manifestHits, reserve: 3 },
         ], 14);
-    const contextNodes = mergeNodes(followUpSourceBlock && input.followUp?.kind === 'drilldown' ? [followUpSourceBlock] : [], (contextHits.length > 0 ? contextHits : considered.slice(0, 6)).map((h) => h.node)).filter((node) => questionDomainScope.length === 0 || !node.domain || questionDomainScope.includes(node.domain));
+    // A frozen exploratory selection gets its relation/column/proof context only
+    // from `executionContextPack`.  KG hit prose is useful diagnostics, but it
+    // is not execution authority and must not tell a provider about another
+    // same-snapshot relation it could then attempt to query.
+    const contextNodes = forcedExploratoryTier
+        ? []
+        : mergeNodes(followUpSourceBlock && input.followUp?.kind === 'drilldown' ? [followUpSourceBlock] : [], (contextHits.length > 0 ? contextHits : considered.slice(0, 6)).map((h) => h.node)).filter((node) => questionDomainScope.length === 0 || !node.domain || questionDomainScope.includes(node.domain));
     const kgJoinPathHints = buildKgJoinPathHints(kg, contextNodes, questionPlan);
     const contextBlocks = contextNodes.filter((node) => {
         if (node.kind !== 'block')
@@ -1991,10 +2432,10 @@ async function runAnswerLoop(input) {
     const messages = [
         { role: 'system', content: SYSTEM_PROMPT },
     ];
-    const skillsPrompt = buildSkillsPrompt(selectedSkills, userId ?? null);
+    const skillsPrompt = forcedExploratoryTier ? '' : buildSkillsPrompt(selectedSkills, userId ?? null);
     if (skillsPrompt)
         messages.push({ role: 'system', content: skillsPrompt });
-    const analyticalPlan = input.manifest
+    const analyticalPlan = !forcedExploratoryTier && input.manifest
         ? planAnalyticalPath(input.manifest, {
             entityIds: inferAnalyticalEntityIds(question, contextNodes, input.manifest),
             ownerDomain: input.domainContext?.activeDomain ?? input.domain,
@@ -2319,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,
@@ -2346,7 +2800,7 @@ async function runAnswerLoop(input) {
     // (pre-validated, since the wrapper only restricts an already-certified result)
     // and is labeled BELOW certified. Falls through to generation on any miss.
     let certifiedAdaptation;
-    if (!semanticBridgeAnswer && !metricFirst && input.executeGeneratedSql) {
+    if (!forcedExploratoryTier && !semanticBridgeAnswer && !metricFirst && input.executeGeneratedSql) {
         const fit = input.contextPack?.routeDecision?.blockFit;
         const sourceBlock = input.contextPack?.allowedSqlContext?.sourceBlockSql?.[0];
         if (fit && sourceBlock?.sql) {
@@ -2652,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,
@@ -2668,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);
         }
@@ -2742,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({
@@ -3345,7 +3871,15 @@ async function runAnswerLoop(input) {
     let result;
     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 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.
@@ -3360,7 +3894,7 @@ async function runAnswerLoop(input) {
         executionError = deepCandidateExecutionError;
         warehouseFailure = normalizeWarehouseSqlFailure(deepCandidateExecutionError, input.semanticDriver);
     }
-    const executeCurrentSql = () => {
+    const executeCurrentSql = async (authorizationAttempt) => {
         const requestedLimit = questionPlan.requestedShape.topN?.scope === 'per_group'
             ? 200
             : questionPlan.requestedShape.topN?.n ?? 200;
@@ -3386,7 +3920,7 @@ async function runAnswerLoop(input) {
             outputs: parsed.outputs,
         });
         const boundedArtifact = artifact ? { ...artifact, limit: requestedLimit } : undefined;
-        if (input.forcedGeneratedProposal) {
+        if (input.forcedGeneratedProposal && !exploratoryExecutionSelected) {
             if (!input.agenticSqlExecutionCapability || !input.executeAgenticGeneratedSql) {
                 throw Object.assign(new Error('The analyst-approved SQL has no live execution capability, so DQL did not execute it.'), {
                     code: 'AGENTIC_EXECUTION_CAPABILITY_REQUIRED',
@@ -3394,27 +3928,63 @@ async function runAnswerLoop(input) {
             }
             return input.executeAgenticGeneratedSql(input.agenticSqlExecutionCapability, parsed.sql, boundedArtifact);
         }
+        if (exploratoryExecutionSelected) {
+            if (!input.prepareExploratorySqlExecution || !input.executeAgenticGeneratedSql) {
+                throw Object.assign(new Error('The selected exploratory SQL has no host-authorized execution capability, so DQL did not execute it.'), {
+                    code: 'EXPLORATORY_EXECUTION_CAPABILITY_REQUIRED',
+                });
+            }
+            // This is the only point at which a router-selected exploratory proposal
+            // 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.forcedGeneratedProposal && input.executeAgenticGeneratedSql)) && !result) {
+    if ((input.executeGeneratedSql
+        || input.executeDqlArtifact
+        || (input.forcedGeneratedProposal && input.executeAgenticGeneratedSql)
+        || exploratoryExecutionSelected) && !result) {
         // Fanout gate for native semantic direct-joins: a duplicate join-key row on
         // the joined side multiplies fact rows BEFORE aggregation, so every summed
         // value inflates silently (seen in the field as trillions-scale "governed"
         // 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
-            && input.executeGeneratedSql
+            && !exploratoryExecutionSelected
             && 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 {
@@ -3422,10 +3992,30 @@ async function runAnswerLoop(input) {
                 result = await executeCurrentSql();
         }
         catch (err) {
+            const executionCode = err && typeof err === 'object'
+                && typeof err.code === 'string'
+                ? err.code
+                : undefined;
+            // A router-selected exploratory proposal that leaves its candidate
+            // closure is not an executable draft. It is a pre-capability safety
+            // denial: do not present its SQL/artifact as review-required work after
+            // the host rejected it.
+            exploratoryClosureDenied = exploratoryExecutionSelected
+                && executionCode === 'UNAUTHORIZED_SQL';
             warehouseFailure = normalizeWarehouseSqlFailure(err, input.semanticDriver);
             executionError = warehouseFailure.redactedMessage;
         }
-        if (executionError && !input.forcedGeneratedProposal && !fanoutContradiction && !authoritativeSemanticBinding) {
+        if (executionError
+            // 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)) {
                 const localRepairSql = repairGeneratedSqlLocally(parsed.sql, executionError, schemaContext);
@@ -3450,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;
                         }
@@ -3482,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) {
@@ -3500,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: [
@@ -3509,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;
                             }
@@ -3536,10 +4155,17 @@ async function runAnswerLoop(input) {
             : 'The question asks for a custom analysis, ranking, breakdown, comparison, or grain that should not be answered by a loose certified block match.'),
         selectedNodes: contextNodes,
         schemaContext,
-        sql: parsed.sql,
+        // 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 || semanticFanoutProbeFailure ? undefined : parsed.sql,
         suggestedViz: parsed.viz ?? 'table',
         assumptions: [
-            'The SQL preview is uncertified until an analyst reviews and promotes the DQL artifact.',
+            ...(exploratoryClosureDenied
+                ? ['The router-selected physical closure rejected the generated SQL before capability minting.']
+                : 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}`]
                 : []),
@@ -3563,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
@@ -3585,27 +4228,32 @@ 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 = result?.dqlArtifact ?? semanticBridgeAnswer?.dqlArtifact ?? buildGeneratedSqlDqlArtifact({
-        question,
-        sql: parsed.sql,
-        intent,
-        domain,
-        followUp: input.followUp,
-        contextPack: input.contextPack,
-        sourceBlock: followUpSourceBlock ?? undefined,
-        sourceDqlArtifact: input.followUp?.priorDqlArtifact,
-        proposedEntity: parsed.proposedEntity,
-        requestedFilters: generatedRequestedFilters,
-        requestedDimensions: generatedRequestedDimensions,
-        validationWarnings,
-        outputs: generatedOutputs,
-    });
+    const baseDqlArtifact = exploratoryClosureDenied || semanticFanoutProbeFailure || frozenExploratoryOutputContractFailure
+        ? undefined
+        : result?.dqlArtifact ?? semanticBridgeAnswer?.dqlArtifact ?? buildGeneratedSqlDqlArtifact({
+            question,
+            sql: parsed.sql,
+            intent,
+            domain,
+            followUp: input.followUp,
+            contextPack: input.contextPack,
+            sourceBlock: followUpSourceBlock ?? undefined,
+            sourceDqlArtifact: input.followUp?.priorDqlArtifact,
+            proposedEntity: parsed.proposedEntity,
+            requestedFilters: generatedRequestedFilters,
+            requestedDimensions: generatedRequestedDimensions,
+            validationWarnings,
+            outputs: generatedOutputs,
+        });
     const requestedTopN = questionPlan.requestedShape.topN?.scope === 'per_group'
         ? undefined
         : questionPlan.requestedShape.topN?.n;
@@ -3618,7 +4266,7 @@ async function runAnswerLoop(input) {
         : undefined;
     let draftBlock;
     let draftCaptureError;
-    if (input.captureGeneratedDraft && parsed.sql) {
+    if (!exploratoryClosureDenied && !semanticFanoutProbeFailure && !frozenExploratoryOutputContractFailure && input.captureGeneratedDraft && parsed.sql) {
         try {
             draftBlock = await input.captureGeneratedDraft({
                 question,
@@ -3665,32 +4313,53 @@ async function runAnswerLoop(input) {
         : undefined;
     const certifiedMetricAnswer = semanticMetricCertification === 'certified' || semanticMetricCertification === 'reviewed';
     const governedMetricExecutionFailure = governedMetricAnswer && Boolean(executionError);
+    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 {
-        kind: governedMetricExecutionFailure ? 'no_answer' : 'uncertified',
-        sourceTier: governedMetricExecutionFailure ? 'no_answer' : governedMetricAnswer ? 'semantic_layer' : activeTier,
-        certification: governedMetricExecutionFailure ? 'analyst_review_required' : governedMetricAnswer ? 'governed' : 'ai_generated',
-        reviewStatus: governedMetricExecutionFailure ? 'none' : governedMetricAnswer ? 'governed' : 'draft_ready',
+        kind: terminalExecutionFailure ? 'no_answer' : 'uncertified',
+        sourceTier: terminalExecutionFailure ? 'no_answer' : governedMetricAnswer ? 'semantic_layer' : activeTier,
+        certification: terminalExecutionFailure ? 'analyst_review_required' : governedMetricAnswer ? 'governed' : 'ai_generated',
+        reviewStatus: terminalExecutionFailure ? 'none' : governedMetricAnswer ? 'governed' : 'draft_ready',
         semanticMetricCertification,
-        confidence: governedMetricExecutionFailure ? 0 : certifiedMetricAnswer ? 0.8 : governedMetricAnswer ? 0.72 : 0.55,
-        text: generatedText,
-        answer: generatedText,
-        proposedSql: parsed.sql,
-        sql: parsed.sql,
-        result,
+        confidence: terminalExecutionFailure ? 0 : certifiedMetricAnswer ? 0.8 : governedMetricAnswer ? 0.72 : 0.55,
+        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 } : {}),
-        ...(governedMetricExecutionFailure ? { refusalCode: 'grounding_gap' } : {}),
+        ...(terminalExecutionFailure ? {
+            refusalCode: semanticFanoutProbeFailure ? 'policy_blocked' : 'grounding_gap',
+        } : {}),
+        ...(semanticFanoutProbeFailure ? {
+            refusalDetails: {
+                code: semanticFanoutProbeFailure.code,
+                message: semanticFanoutProbeFailure.message,
+            },
+        } : {}),
         suggestedViz: parsed.viz ?? 'table',
-        dqlArtifact: answerDqlArtifact,
-        draftBlock,
-        draftBlockId: draftBlock?.path,
-        promoteCommand: draftBlock ? `dql certify --from-draft ${draftBlock.path}` : undefined,
+        ...(exploratoryClosureDenied || semanticFanoutProbeFailure || frozenExploratoryOutputContractFailure ? {} : { dqlArtifact: answerDqlArtifact }),
+        ...(exploratoryClosureDenied || semanticFanoutProbeFailure || frozenExploratoryOutputContractFailure ? {} : {
+            draftBlock,
+            draftBlockId: draftBlock?.path,
+            promoteCommand: draftBlock ? `dql certify --from-draft ${draftBlock.path}` : undefined,
+        }),
         trustLabel: input.contextPack?.trustLabel,
         sourceCertifiedBlock,
         contextPackId: input.contextPack?.id,
@@ -3728,6 +4397,8 @@ async function runAnswerLoop(input) {
         considered,
         providerUsed: provider.name,
         aggregationSafetyProof,
+        ...(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,
@@ -3767,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) {
@@ -4133,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,
@@ -4160,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({
@@ -4594,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,
@@ -4765,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
@@ -4816,6 +5604,147 @@ function scopeContextPackToQuestionDomains(contextPack, domains, manifest) {
         },
     };
 }
+/**
+ * Make the router-selected exploratory physical closure the only SQL authority
+ * visible to generation and execution.  The broad context pack remains on the
+ * run as diagnostics, but must not make a same-snapshot neighbouring relation
+ * executable merely because it ranked well for the surrounding question.
+ *
+ * Matching is canonical-ID only.  In particular this deliberately does not
+ * fall back to relation/model leaf names: duplicate `orders` relations across
+ * schemas/domains must not inherit each other's proof.
+ */
+export function scopeContextPackToExploratoryCandidateClosure(contextPack, candidateIds) {
+    if (!contextPack || !candidateIds?.length)
+        return undefined;
+    const requestedIds = new Set(candidateIds.map(normalizeExploratoryCandidateIdentity).filter(Boolean));
+    if (requestedIds.size === 0)
+        return undefined;
+    const intersects = (values) => {
+        for (const value of values) {
+            const normalized = normalizeExploratoryCandidateIdentity(value ?? '');
+            if (normalized && requestedIds.has(normalized))
+                return true;
+        }
+        return false;
+    };
+    const objectIdentities = (object) => {
+        const payload = object.payload ?? {};
+        return [
+            object.objectKey,
+            object.fullName,
+            payload.qualifiedId,
+            payload.uniqueId,
+            payload.id,
+            payload.localId,
+            payload.relation,
+            payload.table,
+            payload.model,
+            ...metadataStringValues(payload.sourceObjects),
+            ...metadataStringValues(payload.sourceRelations),
+            ...metadataStringValues(payload.tableDependencies),
+        ].filter((value) => typeof value === 'string');
+    };
+    const objectRelationReferences = (object) => {
+        const payload = object.payload ?? {};
+        return [
+            payload.relation,
+            payload.table,
+            payload.model,
+            ...metadataStringValues(payload.sourceObjects),
+            ...metadataStringValues(payload.sourceRelations),
+            ...metadataStringValues(payload.tableDependencies),
+        ].filter((value) => typeof value === 'string');
+    };
+    const directObjects = contextPack.objects.filter((object) => intersects(objectIdentities(object)));
+    const requestedRelations = new Set();
+    for (const object of directObjects) {
+        for (const relation of objectRelationReferences(object)) {
+            const normalized = normalizeExploratoryCandidateIdentity(relation);
+            if (normalized)
+                requestedRelations.add(normalized);
+        }
+    }
+    for (const relation of contextPack.allowedSqlContext.relations) {
+        if (intersects([relation.objectKey, relation.relation])) {
+            requestedRelations.add(normalizeExploratoryCandidateIdentity(relation.relation));
+        }
+    }
+    const relations = contextPack.allowedSqlContext.relations.filter((relation) => {
+        const normalized = normalizeExploratoryCandidateIdentity(relation.relation);
+        return requestedIds.has(normalized)
+            || requestedRelations.has(normalized)
+            || Boolean(relation.objectKey && directObjects.some((object) => object.objectKey === relation.objectKey));
+    });
+    // A router-selected exploratory attempt without a physical relation is not
+    // executable. Returning undefined is intentionally fail-closed; callers may
+    // preserve the full pack for receipts but may not use it as SQL authority.
+    if (relations.length === 0)
+        return undefined;
+    const relationIds = new Set(relations.map((relation) => normalizeExploratoryCandidateIdentity(relation.relation)));
+    const relationshipEndpointIds = new Set();
+    for (const object of directObjects.filter((object) => object.objectType === 'relationship')) {
+        const payload = object.payload ?? {};
+        for (const endpoint of [payload.from, payload.to]) {
+            if (typeof endpoint === 'string') {
+                const normalized = normalizeExploratoryCandidateIdentity(endpoint);
+                if (normalized)
+                    relationshipEndpointIds.add(normalized);
+            }
+        }
+    }
+    const objects = contextPack.objects.filter((object) => {
+        if (directObjects.includes(object))
+            return true;
+        const identities = objectIdentities(object).map(normalizeExploratoryCandidateIdentity);
+        if (identities.some((identity) => relationIds.has(identity) || relationshipEndpointIds.has(identity)))
+            return true;
+        return objectRelationReferences(object)
+            .map(normalizeExploratoryCandidateIdentity)
+            .some((identity) => relationIds.has(identity));
+    });
+    const objectKeys = new Set(objects.map((object) => object.objectKey));
+    const relationKeys = new Set(relations.map((relation) => normalizeRelationKey(relation.relation)));
+    const selectedRelations = contextPack.retrievalDiagnostics.selectedRelations?.filter((relation) => relationKeys.has(normalizeRelationKey(relation.relation)));
+    const selectedJoinPaths = contextPack.retrievalDiagnostics.selectedJoinPaths?.filter((path) => relationKeys.has(normalizeRelationKey(path.leftRelation))
+        && relationKeys.has(normalizeRelationKey(path.rightRelation)));
+    return {
+        ...contextPack,
+        focusObjectKey: contextPack.focusObjectKey && objectKeys.has(contextPack.focusObjectKey)
+            ? contextPack.focusObjectKey
+            : objects[0]?.objectKey ?? null,
+        objects,
+        skills: [],
+        edges: contextPack.edges.filter((edge) => objectKeys.has(edge.fromKey) && objectKeys.has(edge.toKey)),
+        citations: contextPack.citations.filter((citation) => objectKeys.has(citation.objectKey)),
+        evidenceSummaries: contextPack.evidenceSummaries.filter((summary) => !summary.objectKey || objectKeys.has(summary.objectKey)),
+        evidenceRoles: contextPack.evidenceRoles.filter((role) => objectKeys.has(role.objectKey)),
+        allowedSqlContext: {
+            relations,
+            // Authored block SQL is not a physical exploratory authority.  The
+            // selected dbt/runtime relation closure above is the whole prompt/SQL
+            // boundary for this tier.
+            sourceBlockSql: [],
+        },
+        retrievalDiagnostics: {
+            ...contextPack.retrievalDiagnostics,
+            selectedObjects: objects.length,
+            selectedEvidence: contextPack.retrievalDiagnostics.selectedEvidence.filter((evidence) => objectKeys.has(evidence.objectKey)),
+            selectedRelations,
+            selectedJoinPaths,
+            schemaShapeCandidates: contextPack.retrievalDiagnostics.schemaShapeCandidates?.filter((candidate) => objectKeys.has(candidate.objectKey)),
+            certifiedCandidateFits: contextPack.retrievalDiagnostics.certifiedCandidateFits.filter((candidate) => objectKeys.has(candidate.objectKey)),
+        },
+    };
+}
+function metadataStringValues(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === 'string')
+        : [];
+}
+function normalizeExploratoryCandidateIdentity(value) {
+    return value.trim().replace(/["`\[\]]/g, '').replace(/\s*\.\s*/g, '.').toLowerCase();
+}
 /**
  * Build the prompt-facing evidence pack after enforcing the certified output
  * contract. Incompatible blocks remain in the returned answer's `considered`
@@ -4831,7 +5760,13 @@ function contextPackForRequestedShape(contextPack, question, questionPlan, kg) {
         const blockName = object.name || object.objectKey.replace(/^dql:block:/, '');
         const node = kg.getNode(`block:${blockName}`);
         if (node?.kind === 'block') {
-            const fit = evaluateCertifiedBlockFit({ question, plan: questionPlan, block: node });
+            const fit = evaluateCertifiedBlockFit({
+                question,
+                plan: questionPlan,
+                block: node,
+                exactExampleMatch: hasUniqueExactCatalogExample(question, contextPack, node),
+                uniqueExactExampleContract: hasUniqueExactCatalogExample(question, contextPack, node),
+            });
             if (fit.kind === 'context_only' || fit.kind === 'not_applicable') {
                 incompatibleBlockKeys.add(object.objectKey);
             }
@@ -5384,7 +6319,6 @@ function renderContextPackForPrompt(contextPack, budget) {
         : '';
     const sourceSql = renderSourceBlockSqlContext(contextPack, budget);
     return [
-        `context_pack_id: ${contextPack.id}`,
         `trust_label: ${contextPack.trustLabel}`,
         contextPack.trustLabelInfo ? `trust_label_canonical: ${contextPack.trustLabelInfo.display}` : '',
         renderDomainBriefingForPrompt(contextPack).trim(),
@@ -5678,6 +6612,72 @@ function certifiedHitFromContextPack(contextPack, kg) {
     const node = nodeId ? kg.getNode(nodeId) : null;
     return node ? { node, score: 1, snippet: object.snippet } : null;
 }
+/**
+ * Preserve the catalog's unique exact-example proof when the answer boundary
+ * rechecks the frozen block.  The context pack is the same retrieval snapshot
+ * that produced `exactObjectKey`; broad KG search is intentionally not used to
+ * manufacture example uniqueness.
+ */
+function hasUniqueExactCatalogExample(question, contextPack, node) {
+    const normalizedQuestion = normalizeQuestion(question);
+    if (!normalizedQuestion || !contextPack)
+        return false;
+    const matches = contextPack.objects.filter((object) => {
+        if (object.objectType !== 'dql_block')
+            return false;
+        if (object.status !== 'certified' && object.status !== 'approved' && object.payload?.certification !== 'certified')
+            return false;
+        const examples = Array.isArray(object.payload?.examples) ? object.payload.examples : [];
+        return examples.some((example) => example
+            && typeof example === 'object'
+            && normalizeQuestion(String(example.question ?? '')) === normalizedQuestion);
+    });
+    return matches.length === 1 && normalizeQuestion(matches[0].name) === normalizeQuestion(node.name);
+}
+/**
+ * A metadata-only definition answer is safe only for one certified artifact
+ * named exactly by the user.  Do not let FTS ranking decide this: a generic
+ * definition phrase must never select a neighbouring block.  Payload aliases
+ * are authored block aliases; descriptions and tags are deliberately excluded.
+ */
+function uniqueNamedCertifiedDefinitionArtifact(question, kg, authorizedDomains) {
+    const subject = namedArtifactDefinitionSubject(question);
+    if (!subject)
+        return null;
+    const matches = kg.getNodesByKind('block', 1000).filter((node) => {
+        if (node.status !== 'certified')
+            return false;
+        if (authorizedDomains.length > 0 && node.domain && !authorizedDomains.includes(node.domain))
+            return false;
+        return certifiedArtifactNames(node).some((name) => normalizeQuestion(name) === subject);
+    });
+    return matches.length === 1 ? { node: matches[0], score: 1, snippet: undefined } : null;
+}
+function isUniqueNamedCertifiedDefinitionQuestion(question, node, kg, authorizedDomains) {
+    const selected = uniqueNamedCertifiedDefinitionArtifact(question, kg, authorizedDomains);
+    return selected?.node.nodeId === node.nodeId;
+}
+function namedArtifactDefinitionSubject(question) {
+    const match = /^\s*what\s+does\s+(?:the\s+)?(.+?)\s+(?:measure|mean|define|represent)\s*[?.!]*\s*$/i.exec(question);
+    if (!match?.[1])
+        return undefined;
+    // Remove an optional explicit artifact noun while preserving the exact
+    // authored identifier. `top_customers block` and `top_customers` therefore
+    // resolve identically, while arbitrary definition questions have no subject
+    // match and remain on the normal route.
+    const subject = match[1]
+        .replace(/\b(?:certified\s+)?(?:block|artifact|model|metric)\b/gi, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    const normalized = normalizeQuestion(subject);
+    return normalized || undefined;
+}
+function certifiedArtifactNames(node) {
+    const aliases = Array.isArray(node.payload?.aliases)
+        ? node.payload.aliases.filter((alias) => typeof alias === 'string')
+        : [];
+    return [node.name, ...aliases];
+}
 /**
  * Reduce a possibly-composed prompt to the user's actual question for display.
  * Callers (e.g. the Build-SQL-draft modal) sometimes prepend a multi-line instruction
@@ -6765,7 +7765,12 @@ function isBusinessDefinitionQuestion(question) {
 }
 /** Definition that may terminate with documentation instead of executing data. */
 function isPureBusinessDefinitionQuestion(question) {
-    return questionTypeFromText(question) === 'definition';
+    return questionTypeFromText(question) === 'definition'
+        // `questionTypeFromText` intentionally recognizes ranking before generic
+        // definitions, so a named artifact such as `top_customers` would otherwise
+        // look like a ranking request even in the explicit "what does … measure?"
+        // form. Object-name matching remains mandatory at the terminal site.
+        || /^\s*what\s+does\s+(?:the\s+)?[^?.!]{1,160}\s+(?:measure|mean|define|represent)\s*[?.!]*\s*$/i.test(question);
 }
 function isBreakdownOrDrilldownQuestion(question) {
     return /\b(break\s*down|breakdown|drill\s*(?:down|into)|slice|segment|split|by\s+[a-z][\w\s-]{1,40})\b/i.test(question);
@@ -6828,12 +7833,21 @@ function hasCertifiedNodeFit(question, plan, node, options = {}) {
         plan,
         block: node,
         exactExampleMatch: exactExampleMatch || exactObjectRequest,
+        uniqueExactExampleContract: options.uniqueExactExampleContract === true,
         definitionLookup,
     });
     // Delegate the termination decision to THE single authority instead of a
     // loop-local re-derivation (the seams between such copies produced certified
     // answers that ignored member-scoped follow-ups).
-    return certifiedTerminationVerdict({ fit, allowInferredContract: options.allowInferredContract }).allow;
+    return certifiedTerminationVerdict({
+        fit,
+        // A named `what does <artifact> measure?` request is an artifact metadata
+        // lookup, not a query-result claim. The termination authority still
+        // rejects missing declared measures and unsupported filters before this
+        // narrow bypass is considered.
+        ...(definitionLookup ? { bypass: 'definition_lookup' } : {}),
+        allowInferredContract: options.allowInferredContract,
+    }).allow;
 }
 function objectNameInQuestion(question, node) {
     const questionText = normalizeQuestion(question);
@@ -7248,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) {
@@ -7255,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) {
@@ -7651,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".
@@ -8619,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) {