@duckcodeailabs/dql-agent 1.14.0 → 1.14.2

package/dist/answer-loop.js

@@ -1,3 +1,4 @@
+import { packContext } from './cascade/packer.js';
 /**
  * Dynamic-first governed answer loop.
  *
@@ -26,10 +27,10 @@ import { domainContextSearchDomains } from './domain-context.js';
 import { deriveGeneratedDraftSlug, renderGeneratedSqlDqlArtifact } from './metadata/drafts.js';
 import { buildAnalysisQuestionPlan } from './metadata/analysis-planner.js';
 import { certifiedFitAllowsTier1, certifiedTerminationVerdict, evaluateCertifiedBlockFit } from './metadata/block-fit.js';
-import { buildGovernedMetricFirstSql, matchSemanticMetric, resolveGovernedMetricDefinition, resolveGovernedMetricSql } from './metadata/metric-match.js';
+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';
@@ -383,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;
@@ -421,7 +558,35 @@ const MANIFEST_KINDS = ['dbt_model', 'dbt_source'];
  * surface shows THIS; the validator's machine message (relation ids, repair
  * tool guidance) belongs in refusalDetails/validationWarnings only.
  */
-function renderContextValidationRefusalForUser(code, machineError, memberBindings) {
+/**
+ * Name the ONE aggregation check that actually fired.
+ *
+ * The refusal used to list all four possible causes — "rounding too early,
+ * losing decimal precision, summing a non-additive value, or multiplying rows
+ * across a join" — because the specific one was never plumbed into the message.
+ * The system knows: `aggregationIntegrityIssuesForSql` classifies each issue and
+ * the proof carries the codes. A menu of four causes reads as "something is
+ * wrong somewhere", which is exactly the report a user cannot act on.
+ */
+function aggregationRefusalReason(issueCodes = []) {
+    const codes = new Set(issueCodes.map((code) => code.toUpperCase()));
+    // Ordered by how badly each distorts the number, so a query tripping several
+    // leads with the one that matters most.
+    if (codes.has('FANOUT')) {
+        return 'joining those tables multiplies rows, so the total would be inflated. Aggregate at the row-level grain first, then join';
+    }
+    if (codes.has('NON_ADDITIVE_MEASURE')) {
+        return 'it sums a measure that is not additive (an average or a ratio cannot be added up). Ask for the governed metric, which carries the right rule';
+    }
+    if (codes.has('PREMATURE_ROUNDING')) {
+        return 'it rounds each value before adding them, which loses money at scale. Rounding belongs on the final total';
+    }
+    if (codes.has('LOSSY_NUMERIC_CAST')) {
+        return 'it converts amounts to floating point before adding them, which drifts on decimal currency';
+    }
+    return undefined;
+}
+export function renderContextValidationRefusalForUser(code, machineError, memberBindings, aggregationIssueCodes) {
     switch (code) {
         case 'unknown_relation':
             return 'I drafted a query, but it uses a table that was not part of the metadata retrieved for this question, so I did not run it. Ask again (retrieval usually finds it on a follow-up), name the table or metric explicitly, or re-sync the dbt metadata.';
@@ -438,8 +603,15 @@ function renderContextValidationRefusalForUser(code, machineError, memberBinding
             return 'This comparison needs a baseline period or value that the drafted query did not include. Say what to compare against (for example, the prior month) and I will run it.';
         case 'unsafe_sql':
             return 'The drafted query used a statement type that is not allowed in this governed preview, so I did not run it.';
-        case 'unsafe_aggregation':
-            return 'I drafted a query, but it could change the metric meaning by rounding too early, losing decimal precision, summing a non-additive value, or multiplying rows across a join. I did not run it. Use the governed semantic metric, or review the native grain and join keys before retrying.';
+        case 'unsafe_aggregation': {
+            const reason = aggregationRefusalReason(aggregationIssueCodes);
+            if (reason) {
+                return `I drafted a query but did not run it, because ${reason}. Ask for the governed metric and I will use the safe version.`;
+            }
+            // No classified code reached us — say that plainly rather than listing
+            // every cause as if one of them were known to apply.
+            return 'I drafted a query, but it would change how the metric is calculated, so I did not run it. Ask for the governed semantic metric and I will use the safe version.';
+        }
         case 'insufficient_context':
             if (/could not be parsed|parse error|syntax/i.test(machineError)) {
                 return 'I drafted a query, but its SQL syntax did not match the connected warehouse, so I did not run it. The failed draft is available in Inspect; retrying will generate a warehouse-specific query.';
@@ -601,7 +773,10 @@ function tryCrossResultAnswer(input) {
     const prior = input.followUp?.priorResult;
     if (!prior || !Array.isArray(prior.rows) || prior.rows.length === 0)
         return null;
-    const op = detectResultSetOperation(input.question);
+    // Pass the prior result's shape so a follow-up that names one of its columns
+    // ("what's the average lifetime_spend?") is recognised without requiring a
+    // demonstrative pronoun.
+    const op = detectResultSetOperation(input.question, prior);
     if (!op)
         return null;
     const computed = computeResultSetOperation(op, prior);
@@ -696,6 +871,10 @@ async function freezeLegacySemanticSelection(input) {
     const match = await matchSemanticMetric(input.question, metricNodes, {
         measureTerms: [...questionPlan.requestedShape.measures, ...questionPlan.metricTerms],
         ...(semanticLayer ? { canExecute: (name) => semanticLayer.canComposeMetric(name) } : {}),
+        ...(snapshotVectorMetricShortlist(input.contextPack).length
+            ? { vectorMetricShortlist: snapshotVectorMetricShortlist(input.contextPack) }
+            : {}),
+        ...semanticMetricEmbeddingOptions(input.embeddingProvider),
     }).catch(() => null);
     if (!match)
         return undefined;
@@ -813,6 +992,26 @@ async function freezeLegacySemanticSelection(input) {
         mode: 'authoritative',
     });
 }
+/**
+ * Reuse the immutable context pack's independent vector lane.  Metric matching
+ * never opens the catalog or runs a second metadata retrieval pass; it only
+ * narrows its vector-only candidate admission to IDs already retrieved for this
+ * request snapshot.
+ */
+function snapshotVectorMetricShortlist(contextPack) {
+    const lane = contextPack?.retrievalDiagnostics.lanes?.find((item) => item.lane === 'vector');
+    if (!lane?.candidates.length || !contextPack)
+        return [];
+    const objects = new Map(contextPack.objects.map((object) => [object.objectKey, object]));
+    const result = [];
+    for (const candidate of lane.candidates) {
+        const object = objects.get(candidate.objectKey);
+        if (!object || (object.objectType !== 'semantic_metric' && object.objectType !== 'semantic_measure'))
+            continue;
+        result.push(candidate.objectKey, object.name);
+    }
+    return [...new Set(result)];
+}
 export async function answer(input) {
     const inheritedPlan = !input.resolvedAnalyticalPlan
         && input.followUp?.priorResolvedAnalyticalPlan
@@ -1138,6 +1337,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',
@@ -1201,6 +1414,17 @@ 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 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.
@@ -1242,7 +1466,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
@@ -1258,12 +1482,35 @@ 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) {
+    if (!forcedExploratoryTier && input.analyticalPeriodResolutionFailure) {
         const failure = input.analyticalPeriodResolutionFailure;
         const structuredFailureCode = failure.error && typeof failure.error === 'object'
             && typeof failure.error.code === 'string'
@@ -1299,7 +1546,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 },
@@ -1324,7 +1571,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 },
@@ -1349,7 +1596,7 @@ 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,
@@ -1359,7 +1606,7 @@ async function runAnswerLoop(input) {
             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 },
@@ -1384,7 +1631,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,
@@ -1395,7 +1642,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',
@@ -1422,7 +1669,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;
@@ -1486,9 +1733,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,
@@ -1500,6 +1753,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,
@@ -1536,14 +1798,20 @@ async function runAnswerLoop(input) {
     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 } : {}),
-            }).catch(() => null);
+    let semanticMetricMatch = forcedExploratoryTier
+        ? null
+        : 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);
     // 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'
@@ -1563,8 +1831,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;
@@ -1574,7 +1844,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({
@@ -1591,13 +1863,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.
@@ -1706,7 +2050,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).
@@ -1745,6 +2098,10 @@ async function runAnswerLoop(input) {
             ? undefined
             : questionPlan.requestedShape.topN?.n);
         const authoritativeCertifiedFailure = Boolean(authoritativeCertifiedBinding && executionError);
+        // 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
@@ -1759,18 +2116,38 @@ 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' } : {}),
+                ...(authoritativeCertifiedFailure || authoritativeCertifiedShapeFailure
+                    ? { refusalCode: 'grounding_gap' }
+                    : {}),
+                ...(authoritativeCertifiedShapeFailure ? { certifiedResultShapeFailure: true } : {}),
+                ...(frozenCertifiedRoute ? { route: frozenCertifiedRoute } : {}),
                 sql: result?.sql,
                 dqlArtifact,
                 trustLabel: certifiedShapePassed ? input.contextPack?.trustLabel ?? 'certified' : 'mixed',
@@ -1808,7 +2185,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),
@@ -1866,12 +2243,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);
@@ -1904,7 +2283,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')
@@ -1924,10 +2309,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,
@@ -2279,7 +2664,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) {
@@ -2317,7 +2702,18 @@ async function runAnswerLoop(input) {
             onCompiled: (record) => compiledSemanticRecords.push(record),
         }),
     ];
-    if (semanticBridgeAnswer) {
+    if (input.forcedGeneratedProposal) {
+        // The analyst loop already did its provider/tool work. Re-entering ordinary
+        // generation here would create a second proposal whose SQL is not covered
+        // by the request-scoped execution capability.
+        parsed = {
+            sql: input.forcedGeneratedProposal.sql,
+            text: input.forcedGeneratedProposal.summary
+                ?? 'Prepared from identifiers observed during this bounded analyst run. Review-required until an analyst promotes it.',
+            ...(input.forcedGeneratedProposal.suggestedViz ? { viz: input.forcedGeneratedProposal.suggestedViz } : {}),
+        };
+    }
+    else if (semanticBridgeAnswer) {
         governedMetricAnswer = true;
         parsed = {
             sql: semanticBridgeAnswer.sql,
@@ -2503,7 +2899,7 @@ async function runAnswerLoop(input) {
     let deepCandidateResult;
     let deepCandidateExecutionError;
     let deepCandidateNotes = [];
-    if (!governedMetricAnswer && input.analysisDepth === 'deep' && parsed.sql) {
+    if (!input.forcedGeneratedProposal && !governedMetricAnswer && input.analysisDepth === 'deep' && parsed.sql) {
         const selection = await selectDeepGeneratedProposalCandidate({
             provider,
             messages,
@@ -2705,7 +3101,12 @@ async function runAnswerLoop(input) {
                 };
             }
         }
-        const tightenedFlow = tightenSourceTargetFlowProjection(parsed.sql, question, questionPlan);
+        // The analyst capability binds the exact composed bytes. Any projection
+        // tightening is a new SQL proposal and therefore must wait for a fresh
+        // analyst pass/capability rather than silently rewriting this one.
+        const tightenedFlow = input.forcedGeneratedProposal
+            ? undefined
+            : tightenSourceTargetFlowProjection(parsed.sql, question, questionPlan);
         if (tightenedFlow && tightenedFlow.sql !== parsed.sql) {
             parsed.sql = tightenedFlow.sql;
             parsed.outputs = tightenedFlow.outputs;
@@ -2723,7 +3124,7 @@ async function runAnswerLoop(input) {
     // model emitted to its real warehouse relation from the runtime schema BEFORE
     // governance validation. Same resolver the build path uses — one grounding,
     // no weak path. `allowedSqlContext` relations are already qualified.
-    if (parsed.sql) {
+    if (parsed.sql && !input.forcedGeneratedProposal) {
         parsed.sql = contextLedger.qualifySql(parsed.sql).sql;
     }
     // Validation gate. Governed metric SQL synthesized from the semantic layer is
@@ -2840,7 +3241,8 @@ async function runAnswerLoop(input) {
     // that predicate entirely, inject it deterministically before spending the
     // bounded AI validation repair. Misbound or ambiguous predicates are never
     // rewritten here; they continue through the guarded correction/refusal path.
-    if (!contextValidation.ok
+    if (!input.forcedGeneratedProposal
+        && !contextValidation.ok
         && contextValidation.code === 'misbound_filter'
         && !contextValidation.offending?.relation
         && !contextValidation.offending?.column
@@ -2892,7 +3294,8 @@ async function runAnswerLoop(input) {
     //      stands instead of guessing a measure.
     //   2) Otherwise fall back to a CLEAN governed-metric definition (direct or exact
     //      leaf-measure; no fuzzy family guess that could answer the wrong measure).
-    if (!contextValidation.ok && contextValidation.code !== 'unsafe_aggregation' && semanticMetricRoute && semanticMetricMatch && !rankedGrainGap) {
+    if (!input.forcedGeneratedProposal
+        && !contextValidation.ok && contextValidation.code !== 'unsafe_aggregation' && semanticMetricRoute && semanticMetricMatch && !rankedGrainGap) {
         const grounded = contextLedger.validateRuntimeGrounding(parsed.sql);
         // Runtime grounding proves that relations and columns exist; it cannot prove
         // that a resolved business member was bound to the right dimension. Never
@@ -2922,7 +3325,8 @@ async function runAnswerLoop(input) {
     // nothing, or found the table and something else rejected the SQL — which are
     // three different fixes.
     let regroundDiagnostic;
-    if (!contextValidation.ok && contextValidation.code !== 'unsafe_aggregation' && !governedMetricAnswer && input.expandGroundingContext && canUseLaneRepair(repairBudgetState, 'reground')) {
+    if (!input.forcedGeneratedProposal
+        && !contextValidation.ok && contextValidation.code !== 'unsafe_aggregation' && !governedMetricAnswer && input.expandGroundingContext && canUseLaneRepair(repairBudgetState, 'reground')) {
         recordLaneRepair(repairBudgetState, 'reground');
         try {
             const expansion = await input.expandGroundingContext({
@@ -3019,6 +3423,7 @@ async function runAnswerLoop(input) {
         && input.resolvedAnalyticalPlan?.mode !== 'authoritative'
         && !semanticAggregationAuthorityBlocked
         && !governedMetricAnswer
+        && !input.forcedGeneratedProposal
         && canUseLaneRepair(repairBudgetState, 'validation')) {
         recordLaneRepair(repairBudgetState, 'validation');
         try {
@@ -3094,7 +3499,7 @@ async function runAnswerLoop(input) {
         // Business-language chat text; the validator's machine message (with
         // relation ids and tool guidance for the repair prompt) stays in
         // refusalDetails + validationWarnings for the Inspect surface.
-        const text = renderContextValidationRefusalForUser(contextValidation.code, contextValidation.error, input.followUp?.memberBindings);
+        const text = renderContextValidationRefusalForUser(contextValidation.code, contextValidation.error, input.followUp?.memberBindings, contextValidation.aggregationSafetyProof?.issueCodes);
         const analysisPlan = buildAnalysisPlan({
             question,
             intent,
@@ -3258,7 +3663,13 @@ async function runAnswerLoop(input) {
     let result;
     let executionError;
     let warehouseFailure;
+    let exploratoryClosureDenied = false;
     let repairAttempts = 0;
+    // A forced proposal may originate from the bounded analyst loop, but it
+    // cannot bypass a router-owned exploratory decision.  In that case the host
+    // still prepares and freezes the exact validated SQL before execution.
+    const exploratoryExecutionSelected = input.selectedCascadeTier === 'exploratory_sql';
+    let preparedExploratoryExecution;
     // 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.
@@ -3273,7 +3684,7 @@ async function runAnswerLoop(input) {
         executionError = deepCandidateExecutionError;
         warehouseFailure = normalizeWarehouseSqlFailure(deepCandidateExecutionError, input.semanticDriver);
     }
-    const executeCurrentSql = () => {
+    const executeCurrentSql = async () => {
         const requestedLimit = questionPlan.requestedShape.topN?.scope === 'per_group'
             ? 200
             : questionPlan.requestedShape.topN?.n ?? 200;
@@ -3283,8 +3694,6 @@ async function runAnswerLoop(input) {
             && semanticBridgeAnswer?.sql.trim() === parsed.sql?.trim()) {
             return input.executeDqlArtifact({ ...semanticArtifact, limit: requestedLimit });
         }
-        if (!input.executeGeneratedSql)
-            throw new Error('No generated SQL executor is configured.');
         const artifact = buildGeneratedSqlDqlArtifact({
             question,
             sql: parsed.sql,
@@ -3300,9 +3709,35 @@ async function runAnswerLoop(input) {
             validationWarnings: [...contextValidation.warnings, ...deepCandidateNotes],
             outputs: parsed.outputs,
         });
-        return input.executeGeneratedSql(parsed.sql, artifact ? { ...artifact, limit: requestedLimit } : undefined);
+        const boundedArtifact = artifact ? { ...artifact, limit: requestedLimit } : undefined;
+        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',
+                });
+            }
+            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 callback
+            // rechecks the snapshot, physical target, and qualified runtime columns,
+            // then returns a one-shot capability bound to these exact SQL bytes.
+            preparedExploratoryExecution ??= await input.prepareExploratorySqlExecution(parsed.sql, boundedArtifact);
+            return input.executeAgenticGeneratedSql(preparedExploratoryExecution.capability, parsed.sql, boundedArtifact);
+        }
+        if (!input.executeGeneratedSql)
+            throw new Error('No generated SQL executor is configured.');
+        return input.executeGeneratedSql(parsed.sql, boundedArtifact);
     };
-    if (input.executeGeneratedSql && !result) {
+    if ((input.executeGeneratedSql
+        || (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"
@@ -3311,6 +3746,9 @@ async function runAnswerLoop(input) {
         // repair, which would regenerate the same multiplying join.
         let fanoutContradiction = false;
         if (!executionError
+            && !input.forcedGeneratedProposal
+            && !exploratoryExecutionSelected
+            && input.executeGeneratedSql
             && semanticBridgeAnswer?.composeResult?.fanoutProbeSql
             && semanticBridgeAnswer.sql.trim() === parsed.sql?.trim()) {
             const inflationError = await probeSemanticJoinFanout(semanticBridgeAnswer.composeResult.fanoutProbeSql, semanticBridgeAnswer.composeResult.tables, input.executeGeneratedSql);
@@ -3324,10 +3762,24 @@ 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 && !fanoutContradiction && !authoritativeSemanticBinding) {
+        if (executionError
+            && !input.forcedGeneratedProposal
+            && !exploratoryExecutionSelected
+            && !fanoutContradiction
+            && !authoritativeSemanticBinding) {
             warehouseFailure ??= normalizeWarehouseSqlFailure(executionError, input.semanticDriver);
             if (isRetryableGeneratedSqlError(warehouseFailure)) {
                 const localRepairSql = repairGeneratedSqlLocally(parsed.sql, executionError, schemaContext);
@@ -3438,10 +3890,15 @@ 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 ? 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.']
+                : ['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}`]
                 : []),
@@ -3493,21 +3950,23 @@ async function runAnswerLoop(input) {
     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
+        ? 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;
@@ -3520,7 +3979,7 @@ async function runAnswerLoop(input) {
         : undefined;
     let draftBlock;
     let draftCaptureError;
-    if (input.captureGeneratedDraft && parsed.sql) {
+    if (!exploratoryClosureDenied && input.captureGeneratedDraft && parsed.sql) {
         try {
             draftBlock = await input.captureGeneratedDraft({
                 question,
@@ -3567,32 +4026,38 @@ async function runAnswerLoop(input) {
         : undefined;
     const certifiedMetricAnswer = semanticMetricCertification === 'certified' || semanticMetricCertification === 'reviewed';
     const governedMetricExecutionFailure = governedMetricAnswer && Boolean(executionError);
+    const terminalExecutionFailure = governedMetricExecutionFailure || exploratoryClosureDenied;
     const finalSemanticExecutionTrace = semanticTraceAfterExecution(semanticExecutionTrace, {
         executed: Boolean(result),
         ...(executionError ? { error: executionError } : {}),
         ...(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,
+        confidence: terminalExecutionFailure ? 0 : certifiedMetricAnswer ? 0.8 : governedMetricAnswer ? 0.72 : 0.55,
+        text: exploratoryClosureDenied
+            ? 'The generated SQL referenced a relation outside the router-selected physical closure, so DQL did not execute it.'
+            : generatedText,
+        answer: exploratoryClosureDenied
+            ? 'The generated SQL referenced a relation outside the router-selected physical closure, so DQL did not execute it.'
+            : generatedText,
+        ...(exploratoryClosureDenied ? {} : { proposedSql: parsed.sql, sql: parsed.sql }),
         result,
         executionError,
         ...(warehouseFailure ? { warehouseFailure } : {}),
         ...(finalSemanticExecutionTrace ? { semanticExecutionTrace: finalSemanticExecutionTrace } : {}),
-        ...(governedMetricExecutionFailure ? { refusalCode: 'grounding_gap' } : {}),
+        ...(terminalExecutionFailure ? { refusalCode: 'grounding_gap' } : {}),
         suggestedViz: parsed.viz ?? 'table',
-        dqlArtifact: answerDqlArtifact,
-        draftBlock,
-        draftBlockId: draftBlock?.path,
-        promoteCommand: draftBlock ? `dql certify --from-draft ${draftBlock.path}` : undefined,
+        ...(exploratoryClosureDenied ? {} : { dqlArtifact: answerDqlArtifact }),
+        ...(exploratoryClosureDenied ? {} : {
+            draftBlock,
+            draftBlockId: draftBlock?.path,
+            promoteCommand: draftBlock ? `dql certify --from-draft ${draftBlock.path}` : undefined,
+        }),
         trustLabel: input.contextPack?.trustLabel,
         sourceCertifiedBlock,
         contextPackId: input.contextPack?.id,
@@ -3630,6 +4095,7 @@ async function runAnswerLoop(input) {
         considered,
         providerUsed: provider.name,
         aggregationSafetyProof,
+        ...(preparedExploratoryExecution ? { exploratoryExecutionFreeze: preparedExploratoryExecution.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,
@@ -4718,6 +5184,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`
@@ -4733,7 +5340,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);
             }
@@ -5251,15 +5864,26 @@ function renderContextPackForPrompt(contextPack, budget) {
     const warnings = contextPack.warnings.length
         ? `Warnings:\n${contextPack.warnings.slice(0, budget.warningLimit).map((warning) => `- ${warning}`).join('\n')}\n`
         : '';
-    const objects = contextPack.objects.slice(0, budget.contextObjectLimit).map((object) => {
-        const detail = [
-            object.objectType,
-            object.domain ? `domain: ${object.domain}` : '',
-            object.status ? `status: ${object.status}` : '',
-            object.description ? `description: ${object.description}` : '',
-        ].filter(Boolean).join('; ');
-        return `- ${object.objectKey} (${detail})`;
-    }).join('\n');
+    // Pack by value per token instead of truncating at a fixed position. The
+    // objects arrive already ranked, so position IS the value — but cost is not
+    // uniform: one object with a long description can crowd out several cheap
+    // ones that rank just below it, and the old `slice` cut by rank alone. This
+    // keeps the same ordering pressure while letting an inexpensive object that
+    // ranked 19th still fit. The budget is derived from the existing item limit
+    // so the window stays the size the caller already tuned for.
+    const objects = packContext(contextPack.objects.map((object, index) => ({
+        id: object.objectKey,
+        score: contextPack.objects.length - index,
+        render: () => {
+            const detail = [
+                object.objectType,
+                object.domain ? `domain: ${object.domain}` : '',
+                object.status ? `status: ${object.status}` : '',
+                object.description ? `description: ${object.description}` : '',
+            ].filter(Boolean).join('; ');
+            return `- ${object.objectKey} (${detail})`;
+        },
+    })), Math.max(1, budget.contextObjectLimit) * 45).text;
     const conflicts = contextPack.retrievalDiagnostics.candidateConflicts.length
         ? `\nCandidate conflicts:\n${contextPack.retrievalDiagnostics.candidateConflicts.slice(0, 4).map((conflict) => `- ${conflict.reason} ${conflict.prompt}`).join('\n')}`
         : '';
@@ -5275,7 +5899,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(),
@@ -5569,6 +6192,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
@@ -5785,6 +6474,28 @@ function flowFieldCovers(field, term) {
 function normalizeFlowField(value) {
     return value.toLowerCase().replace(/[_-]+/g, ' ').replace(/[^a-z0-9 ]+/g, ' ').replace(/\s+/g, ' ').trim();
 }
+/**
+ * Remove the model's QUERY PLAN scaffolding from user-facing prose.
+ *
+ * Rule 4 of the SQL prompt tells the model to state its grain, measures, join
+ * path, and join keys BEFORE writing SQL. That instruction is load-bearing —
+ * it is what prevents wrong-grain answers and fan-out joins — but it is
+ * reasoning, not an answer, and it was reaching the reader verbatim:
+ *
+ *   "QUERY PLAN: grain = one row per customer, filtered to the named customer
+ *    (Matthew Meyer, honorific stripped) ... FROM dev.customers c, filtered on
+ *    c.customer_name ILIKE '%Matthew Meyer%'."
+ *
+ * Someone who asked why a customer tops a list should not be handed a join
+ * plan. The plan stays in the artifact and the trace; it leaves the prose.
+ */
+export function stripQueryPlanScaffolding(text) {
+    return text
+        // A QUERY PLAN section runs to the next blank line or the end of the prose.
+        .replace(/(?:^|\n)\s*(?:\*\*)?QUERY PLAN(?:\*\*)?\s*[::][\s\S]*?(?=\n\s*\n|$)/gi, '')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
 /**
  * Public for tests. Prefer the structured W2.7 JSON proposal contract, then
  * fall back to the legacy prose + ```sql block + Viz line format.
@@ -5798,11 +6509,11 @@ export function parseProposal(raw) {
     const vizMatch = raw.match(/^Viz:\s*([a-z_]+)/im);
     const viz = vizMatch ? vizMatch[1].trim().toLowerCase() : undefined;
     // Strip the SQL block + Viz line from the prose to keep the summary clean.
-    const text = raw
+    const text = stripQueryPlanScaffolding(raw
         .replace(/```json[\s\S]*?```/gi, '')
         .replace(/```sql[\s\S]*?```/gi, '')
         .replace(/^Viz:.*$/gim, '')
-        .trim();
+        .trim());
     return { text, sql, viz };
 }
 function parseStructuredProposal(raw) {
@@ -5830,7 +6541,7 @@ function parsedProposalFromJson(value) {
         return undefined;
     const record = value;
     const sql = firstJsonString(record.sql, record.query)?.trim();
-    const text = firstJsonString(record.summary, record.text, record.answer, record.description)?.trim() ?? '';
+    const text = stripQueryPlanScaffolding(firstJsonString(record.summary, record.text, record.answer, record.description)?.trim() ?? '');
     const viz = firstJsonString(record.viz, record.visualization, record.chartType)
         ?.trim()
         .toLowerCase()
@@ -6634,7 +7345,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);
@@ -6697,12 +7413,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);