@duckcodeailabs/dql-agent 1.6.31 → 1.6.32

package/dist/answer-loop.js

@@ -14,52 +14,132 @@
  * step. Tests can mock the provider with a canned response and exercise the
  * full pipeline.
  */
-import { composeEffectiveTrust, } from '@duckcodeailabs/dql-core';
 import { buildSkillBlockHints, buildSkillsPrompt, selectRelevantSkills } from './skills/loader.js';
-import { matchSemanticMetric, resolveGovernedMetricSql } from './metadata/metric-match.js';
+import { deriveGeneratedDraftSlug, renderGeneratedSqlDqlArtifact } from './metadata/drafts.js';
+import { buildAnalysisQuestionPlan } from './metadata/analysis-planner.js';
+import { certifiedFitAllowsTier1, evaluateCertifiedBlockFit } from './metadata/block-fit.js';
+import { buildGovernedMetricFirstSql, matchSemanticMetric, resolveGovernedMetricSql } from './metadata/metric-match.js';
 import { decideAgentAction } from './intent-controller.js';
-import { validateSqlAgainstLocalContext } from './metadata/sql-context-validation.js';
-import { buildGroundingFromRuntimeRelations, resolveRelationsInSql, validateSqlAgainstGrounding } from './metadata/sql-grounding.js';
+import { createContextLedger } from './grounding/context-ledger.js';
+import { validateAnswerResultShape } from './answer-shape.js';
 import { compactSqlSnippet, extractSimpleSelectShape, selectExpressionOutputName, } from './metadata/sql-shape.js';
+import { composeSemanticQueryForQuestion, composeSemanticQueryFromMembers } from './semantic-bridge/compose.js';
+import { selectSemanticMembersViaLlm } from './semantic-bridge/member-select.js';
+import { normalizeValueIndexText } from './grounding/value-index.js';
+import { cascadeTraceToEvidenceRouteSteps, createCascadeAnswerResult, createCascadeTrace, } from './cascade/cascade.js';
+import { shouldClarifyBeforeGeneration } from './cascade/triage.js';
+import { stampTrustLabel } from './trust/stamp.js';
+import { QUICK_PROMPT_CONTEXT_BUDGET, canUseLaneRepair, cascadeBudgetTrace, createCascadeBudgetState, promptContextBudgetForQuestion, proposalToolBudgetForQuestion, recordLaneRepair, } from './cascade/budgets.js';
+/**
+ * Physical column names whose sampled runtime values include `value`. Used by the
+ * semantic bridge to bind a filter literal to the dimension that actually carries
+ * it — a generic, project-agnostic replacement for hard-coded value→dimension maps.
+ */
+function resolveFilterValueColumns(value, schemaContext) {
+    const needle = normalizeValueIndexText(value);
+    if (!needle)
+        return [];
+    const columns = [];
+    for (const table of schemaContext) {
+        for (const column of table.columns) {
+            if (column.sampleValues?.some((sample) => normalizeValueIndexText(sample) === needle)) {
+                columns.push(column.name);
+            }
+        }
+    }
+    return columns;
+}
 const CERTIFIED_HIT_THRESHOLD = 0.18;
 const HARD_NEGATIVE_RATIO = 0.5;
 const EXECUTABLE_ARTIFACT_KINDS = ['block', 'dashboard', 'app', 'notebook'];
+// Dashboards, apps, and notebooks are governed NAVIGATION targets — collections
+// of tiles / a standing surface, not an executable data query. They can ground or
+// be cited, but they never produce the row-level answer to an analytical question,
+// so they must not terminate a data ask as a "certified answer" with no data.
+const NAVIGATION_ARTIFACT_KINDS = ['dashboard', 'app', 'notebook'];
 const BUSINESS_CONTEXT_KINDS = ['term', 'business_view'];
 const ARTIFACT_KINDS = [...EXECUTABLE_ARTIFACT_KINDS, ...BUSINESS_CONTEXT_KINDS];
 const SEMANTIC_KINDS = ['metric', 'dimension', 'measure', 'entity', 'semantic_model', 'saved_query'];
 const MANIFEST_KINDS = ['dbt_model', 'dbt_source'];
+function refusalCodeForValidation(code) {
+    if (code === 'unknown_relation' || code === 'unknown_column' || code === 'insufficient_context' || code === 'missing_baseline') {
+        return 'grounding_gap';
+    }
+    if (code === 'ambiguous_filter')
+        return 'ambiguous';
+    return 'model_declined';
+}
+function formatOffendingValidationToken(offending) {
+    if (!offending?.relation && !offending?.column)
+        return '';
+    const parts = [
+        offending.relation ? `relation=${offending.relation}` : undefined,
+        offending.column ? `column=${offending.column}` : undefined,
+    ].filter((part) => Boolean(part));
+    return `Offending metadata token: ${parts.join(', ')}`;
+}
+function formatValidationWarningsForPrompt(warnings) {
+    const useful = warnings.filter((warning) => warning.trim().length > 0).slice(0, 6);
+    return useful.length > 0 ? `Additional inspected-context notes:\n${useful.map((warning) => `- ${warning}`).join('\n')}` : '';
+}
 /**
- * Map an answer-loop result's source tier + certification + review state to a
- * canonical trust-label id from the one shared vocabulary in dql-core.
- * Additive and lenient — keeps the legacy `trustLabel` string untouched.
+ * Central honesty gate — applied once at the single answer() exit so EVERY return
+ * site (certified, semantic-metric, generated) is covered by construction. A DATA
+ * answer must have PRODUCED ROWS: when execution was attempted (a result or an
+ * execution error came back) but no rows resulted, it may never read as a confident
+ * answer.
+ *  - A generated / governed-metric (uncertified) answer downgrades to a low-
+ *    confidence, review-required no-data state with an honest message — the SQL is
+ *    still surfaced so the user can inspect and fix it.
+ *  - A CERTIFIED block keeps its badge (an empty certified result can be a correct
+ *    "none matched" answer) but gains a non-blocking note to verify data currency.
+ * An UN-executed answer (offline SQL preview / certified citation with no executor)
+ * is left untouched — that is a legitimate preview, not a hollow answer.
  */
-function canonicalTrustLabelId(result) {
+function applyHollowAnswerGate(result) {
     if (result.kind === 'no_answer')
-        return 'insufficient_context';
-    if (result.certification === 'certified' || result.kind === 'certified')
-        return 'certified';
-    if (result.sourceTier === 'business_context' && result.reviewStatus === 'certified')
-        return 'reviewed';
-    if (result.certification === 'ai_generated' ||
-        result.certification === 'analyst_review_required' ||
-        result.reviewStatus === 'analyst_review_required' ||
-        result.reviewStatus === 'draft_ready') {
-        return 'ai_generated';
+        return result;
+    const attempted = result.result !== undefined || result.executionError !== undefined;
+    const producedRows = Boolean(result.result && typeof result.result.rowCount === 'number' && result.result.rowCount > 0);
+    if (!attempted || producedRows)
+        return result;
+    if (result.kind === 'certified') {
+        const note = result.executionError
+            ? 'This certified block failed to execute — review the source data before relying on it.'
+            : 'This certified block returned 0 rows — verify the source data is current before relying on it.';
+        return {
+            ...result,
+            text: [result.text, note].filter(Boolean).join('\n\n'),
+            answer: [result.answer ?? result.text, note].filter(Boolean).join('\n\n'),
+            validationWarnings: [...(result.validationWarnings ?? []), note],
+        };
     }
-    return 'insufficient_context';
+    const honestText = [
+        result.executionError
+            ? `The governed query could not be executed (${result.executionError}).`
+            : 'The governed query executed but returned no rows.',
+        'This usually means a filter, grain, or join is off — review the SQL preview and refine before reuse.',
+    ].join('\n\n');
+    const warning = result.executionError
+        ? 'The governed query failed to execute and returned no data — review before reuse.'
+        : 'The governed query executed but returned no rows — review the SQL, filters, and joins before reuse.';
+    return {
+        ...result,
+        reviewStatus: 'analyst_review_required',
+        confidence: Math.min(result.confidence ?? 0.2, 0.2),
+        text: honestText,
+        answer: honestText,
+        validationWarnings: [...(result.validationWarnings ?? []), warning],
+    };
 }
 export async function answer(input) {
-    const result = await runAnswerLoop(input);
+    const result = applyHollowAnswerGate(await runAnswerLoop(input));
     // 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
     // health (stale/failed upstream) into the label so it reads "Certified ·
     // stale data" / "Certified · upstream failed". Non-certified or fresh answers
     // are unaffected.
-    const id = canonicalTrustLabelId(result);
-    const dataState = id === 'certified'
-        ? (result.block?.dataState)
-        : undefined;
     const { _semanticMetricMatch, ...publicResult } = result;
     const chosenRoute = result.route ?? deriveAiRoute(result, _semanticMetricMatch);
     // P0 — record the high-level action this turn warranted, so callers can route
@@ -80,7 +160,21 @@ export async function answer(input) {
     return {
         ...publicResult,
         intentDecision,
-        trustLabelInfo: composeEffectiveTrust({ id, dataState }),
+        trustLabelInfo: stampTrustLabel(result),
+        cascade: publicResult.cascade ?? createCascadeAnswerResult({
+            routeTier: chosenRoute.tier,
+            label: chosenRoute.label,
+            ref: chosenRoute.ref,
+            artifactKind: result.dqlArtifact?.kind,
+            refusalCode: result.refusalCode,
+            reason: result.refusalDetails?.message ?? (result.kind === 'no_answer' ? result.text : undefined),
+            rowCount: result.result?.rowCount,
+            executionStatus: cascadeExecutionStatus(result),
+            draftBlockId: result.draftBlockId ?? result.draftBlock?.path,
+            metrics: result.dqlArtifact?.metrics,
+            dimensions: result.dqlArtifact?.dimensions,
+            hasSqlPreview: Boolean(result.proposedSql ?? result.sql),
+        }),
         // Stamp the SELECTED skills that shaped the answer (transparency). Computed
         // here so every return site inside runAnswerLoop stays untouched.
         appliedSkills: result.appliedSkills ??
@@ -93,6 +187,17 @@ export async function answer(input) {
         route: chosenRoute,
     };
 }
+function cascadeExecutionStatus(result) {
+    if (result.kind === 'no_answer')
+        return 'not_applicable';
+    if (result.executionError)
+        return 'failed';
+    if (result.result)
+        return 'executed';
+    if (result.block || result.dqlArtifact || result.proposedSql || result.sql)
+        return 'not_requested';
+    return 'not_applicable';
+}
 /**
  * Derive the UI-facing route from a finished answer (spec 17, part C). The
  * semantic-metric tier is named explicitly when the loop matched a governed
@@ -118,7 +223,7 @@ function deriveAiRoute(result, metricMatch) {
             ref,
         };
     }
-    // Uncertified: a governed metric matched → semantic_metric; else generated SQL.
+    // Uncertified: a governed metric matched → semantic_metric; else generated preview.
     if (result.sourceTier === 'semantic_layer' && metricMatch) {
         return {
             tier: 'semantic_metric',
@@ -126,7 +231,9 @@ function deriveAiRoute(result, metricMatch) {
             ref: metricMatch.metric.name,
         };
     }
-    return { tier: 'generated_sql', label: 'Answered with generated SQL (review required).' };
+    return result.dqlArtifact
+        ? { tier: 'generated_sql', label: 'Prepared review-required DQL artifact with SQL preview.' }
+        : { tier: 'generated_sql', label: 'Prepared review-required SQL preview.' };
 }
 async function runAnswerLoop(input) {
     const { question, userId, domain, provider, kg, skills = [], blockHints = [] } = input;
@@ -152,6 +259,10 @@ async function runAnswerLoop(input) {
     const considered = mergeHits(artifactHits, semanticHits, manifestHits, kg.search({ query: question, domain, limit: 10 })).slice(0, 30);
     const schemaContext = schemaContextWithAllowedSqlContext(input.schemaContext ?? [], input.contextPack);
     const catalogRoute = input.contextPack?.routeDecision;
+    const questionPlan = input.contextPack?.questionPlan?.requestedShape
+        ? input.contextPack.questionPlan
+        : buildAnalysisQuestionPlan(question, input.followUp);
+    const repairBudgetState = createCascadeBudgetState(input.cascadeBudgetModel);
     const fallbackIntent = classifyAgentIntent({
         question,
         followUp: input.followUp,
@@ -160,13 +271,14 @@ async function runAnswerLoop(input) {
         manifestHits,
         schemaContext,
     });
-    const intent = catalogRoute ? agentIntentFromCatalogRoute(catalogRoute) : fallbackIntent;
+    let intent = catalogRoute ? agentIntentFromCatalogRoute(catalogRoute) : fallbackIntent;
     // 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'
         ? pickCertifiedDrilldownArtifact({
             executableArtifactHits,
             question,
+            questionPlan,
             followUp: input.followUp,
             excludedArtifactIds,
             kg,
@@ -179,23 +291,74 @@ async function runAnswerLoop(input) {
                 executableArtifactHits,
                 businessHits,
                 question,
+                questionPlan,
                 blockHints: input.followUp?.kind === 'drilldown' ? [] : effectiveBlockHints,
                 excludedArtifactIds,
                 kg,
             })
         : null);
-    if (artifactHit) {
+    // A certified TERM / BUSINESS VIEW is documentation, not data: it can be the
+    // terminal answer only for a definition-style question with no data ask. A
+    // question that requests a data shape (dimensions/measures/outputs/top-N) or
+    // continues an ongoing data conversation must be ANSWERED WITH DATA — the
+    // matched business context falls through as grounding for the executable
+    // tiers (certified block → governed metric → generated SQL), never instead
+    // of them. "Certified" always means "a governed, executable definition
+    // produced this result", not "a certified document sounded related".
+    const businessContextTerminal = (() => {
+        if (!artifactHit || artifactHit.node.kind === 'block')
+            return true;
+        // An ongoing data conversation (prior turn produced result columns/values)
+        // must be answered with data even when the phrasing looks definitional
+        // ("so Matthew is the top — what is his 360 profile view?").
+        if (input.followUp?.priorResultValues || input.followUp?.priorResultColumns?.length)
+            return false;
+        // A dashboard / app / notebook is a NAVIGATION target, not executable data.
+        // It can only terminate a question that explicitly asks to open/see THAT
+        // artifact by name ("open the Jaffle Growth Command Center"); any analytical
+        // ask ("top customers who bought the top products with revenue") must fall
+        // through to the executable + generated tiers and use the artifact only as
+        // grounding — never returned as a no-data "certified answer".
+        if (NAVIGATION_ARTIFACT_KINDS.includes(artifactHit.node.kind)) {
+            return objectNameInQuestion(question, artifactHit.node);
+        }
+        // Cold questions fall through only on STRONG data-shape signals — bare
+        // measure/dimension words are normal in definition asks ("what is revenue
+        // health?") and must keep answering from the certified business context.
+        // "Strong" = outputs requested BEYOND the measure/dimension words themselves
+        // (e.g. product_name), explicit filters, or a top-N.
+        const requested = questionPlan.requestedShape;
+        const nonTrivialOutputs = requested.requiredOutputs.filter((output) => !requested.measures.includes(output) && !requested.dimensions.includes(output));
+        const strongShape = nonTrivialOutputs.length > 0
+            || requested.filters.length > 0
+            || Boolean(requested.topN);
+        return !strongShape;
+    })();
+    if (artifactHit && businessContextTerminal) {
         let result;
         let executionError;
         if (artifactHit.node.kind === 'block' && input.executeCertifiedBlock) {
             try {
                 result = await input.executeCertifiedBlock(artifactHit.node);
+                result = trimResultToRequestedTopN(result, questionPlan);
             }
             catch (err) {
                 executionError = err instanceof Error ? err.message : String(err);
             }
         }
-        const text = composeCertifiedAnswer(artifactHit.node, question, result, executionError);
+        const resultShapeWarnings = result ? validateAnswerResultShape(questionPlan, result).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).
+        // Note: a matched-but-unexecuted block (no executor / dry-run) legitimately
+        // stays a certified *citation* — non-execution is a separate axis surfaced via
+        // cascade.executionStatus ('not_requested') and freshness dataState, not a
+        // reason to strip source trust.
+        const certifiedShapePassed = executionError === undefined && resultShapeWarnings.length === 0;
+        const certifiedText = composeCertifiedAnswer(artifactHit.node, question, result, executionError);
+        const text = resultShapeWarnings.length > 0
+            ? `${certifiedText}\n\nReview required: ${resultShapeWarnings.join(' ')}`
+            : certifiedText;
         const sourceTier = artifactHit.node.sourceTier === 'business_context'
             ? 'business_context'
             : 'certified_artifact';
@@ -218,21 +381,24 @@ async function runAnswerLoop(input) {
             sql: result?.sql,
             suggestedViz: result?.chartConfig ? chartNameFromConfig(result.chartConfig) : undefined,
         });
+        const dqlArtifact = buildCertifiedBlockDqlArtifact(artifactHit.node, result);
         return {
-            kind: 'certified',
+            kind: certifiedShapePassed ? 'certified' : 'uncertified',
             sourceTier,
-            certification: 'certified',
-            reviewStatus: 'certified',
-            confidence: 0.95,
+            certification: certifiedShapePassed ? 'certified' : 'analyst_review_required',
+            reviewStatus: certifiedShapePassed ? 'certified' : 'analyst_review_required',
+            confidence: certifiedShapePassed ? 0.95 : 0.45,
             text,
             answer: text,
             block: artifactHit.node.kind === 'block' ? artifactHit.node : undefined,
             result,
             executionError,
             sql: result?.sql,
-            trustLabel: input.contextPack?.trustLabel ?? 'certified',
+            dqlArtifact,
+            trustLabel: certifiedShapePassed ? input.contextPack?.trustLabel ?? 'certified' : 'mixed',
             sourceCertifiedBlock: artifactHit.node.kind === 'block' ? artifactHit.node.name : undefined,
             contextPackId: input.contextPack?.id,
+            validationWarnings: resultShapeWarnings,
             selectedEvidence: input.contextPack?.evidenceRoles?.slice(0, 12),
             citations,
             memoryContext: input.memoryContext,
@@ -246,6 +412,7 @@ async function runAnswerLoop(input) {
                 considered,
                 result,
                 executionError,
+                resultShapeWarnings,
                 executorWasAvailable: Boolean(input.executeCertifiedBlock),
                 citations,
                 memoryContext: input.memoryContext ?? [],
@@ -264,8 +431,19 @@ async function runAnswerLoop(input) {
     // cumulative_revenue). Certified-first is still preserved (checked above).
     const semanticMetricNodes = collectMetricCandidates(semanticHits, considered, kg);
     let semanticMetricMatch = await matchSemanticMetric(question, semanticMetricNodes).catch(() => null);
-    // Clarify only when there is ALSO no confident governed-metric match.
-    if ((intent === 'clarify' || catalogRoute?.route === 'clarify') && !semanticMetricMatch) {
+    const clarifyBeforeGeneration = shouldClarifyBeforeGeneration({
+        intent,
+        routeDecision: catalogRoute,
+        hasSemanticMetricMatch: Boolean(semanticMetricMatch),
+        schemaContextCount: schemaContext.length,
+        allowedRelationCount: input.contextPack?.allowedSqlContext?.relations.length ?? 0,
+        sourceBlockSqlCount: input.contextPack?.allowedSqlContext?.sourceBlockSql.length ?? 0,
+        metadataObjectCount: considered.length,
+    });
+    // Clarify only when there is ALSO no confident governed-metric match and no
+    // usable schema/catalog context. A conservative catalog "clarify" decision is
+    // not a terminal lane if runtime or SQL context can still answer with review.
+    if (clarifyBeforeGeneration) {
         const text = composeCatalogClarificationText(question, catalogRoute) ?? composeClarificationText(question, considered, schemaContext);
         const analysisPlan = buildAnalysisPlan({
             question,
@@ -298,12 +476,15 @@ async function runAnswerLoop(input) {
                 considered,
                 memoryContext: input.memoryContext ?? [],
                 analysisPlan,
+                budgetTrace: cascadeBudgetTrace(repairBudgetState),
             }),
             contextPack: input.contextPack,
             considered,
             providerUsed: provider.name,
         };
     }
+    if (intent === 'clarify')
+        intent = questionPlan.routeIntent;
     // Stage 2/3: generate only after certified artifacts miss. Semantic context
     // 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
@@ -329,9 +510,15 @@ async function runAnswerLoop(input) {
         ? [...matchedMetricHit, ...trustedArtifactContext, ...reviewRequiredArtifactHits, ...businessHits.slice(0, 4), ...semanticHits, ...manifestHits].slice(0, 14)
         : [...trustedArtifactContext, ...reviewRequiredArtifactHits, ...businessHits.slice(0, 4), ...manifestHits].slice(0, 14);
     const contextNodes = mergeNodes(followUpSourceBlock && input.followUp?.kind === 'drilldown' ? [followUpSourceBlock] : [], (contextHits.length > 0 ? contextHits : considered.slice(0, 6)).map((h) => h.node));
+    const kgJoinPathHints = buildKgJoinPathHints(kg, contextNodes, questionPlan);
     const contextBlocks = contextNodes.filter((n) => n.kind === 'block');
     const contextBusiness = contextNodes.filter((n) => BUSINESS_CONTEXT_KINDS.includes(n.kind));
     const contextOther = contextNodes.filter((n) => n.kind !== 'block' && !BUSINESS_CONTEXT_KINDS.includes(n.kind));
+    const promptBudget = promptContextBudgetForQuestion({
+        questionPlan,
+        requestedDepth: input.analysisDepth,
+        reasoningEffort: input.reasoningEffort,
+    });
     const messages = [
         { role: 'system', content: SYSTEM_PROMPT },
     ];
@@ -340,28 +527,123 @@ async function runAnswerLoop(input) {
         messages.push({ role: 'system', content: skillsPrompt });
     messages.push({
         role: 'system',
-        content: renderContextPrompt(contextBlocks, contextBusiness, contextOther, activeTier, input.memoryContext ?? [], input.extraContext, input.followUp, schemaContext, intent, input.contextPack),
+        content: renderContextPrompt(contextBlocks, contextBusiness, contextOther, activeTier, input.memoryContext ?? [], input.extraContext, input.followUp, schemaContext, intent, input.contextPack, input.conversationSnapshot, kgJoinPathHints, promptBudget),
     });
     messages.push({ role: 'user', content: question });
-    const localProposal = buildSchemaAwareProposal({
-        question,
-        intent,
-        schemaContext,
-        followUp: input.followUp,
-        contextPack: input.contextPack,
-    }) ?? buildContextPackAwareProposal({
-        question,
-        intent,
+    // ── Tier 2: semantic-layer metrics + dimensions (governed hierarchy) ──────
+    // Certified blocks already missed (Stage 1). Before LLM generation, a
+    // confidently matched governed metric whose definition can
+    // express the question's full requested shape (scalar KPI, or a group-by whose
+    // dimensions all resolve to columns on the metric's own table) answers
+    // deterministically. Only when no metric fits does the question fall through
+    // to SQL generation, where the metric still grounds the prompt as context.
+    let governedMetricAnswer = false;
+    const semanticBridgeToolCalls = [];
+    let semanticBridgeAnswer;
+    if (input.semanticLayer && semanticMetricMatch) {
+        semanticBridgeAnswer = composeSemanticQueryForQuestion({
+            semanticLayer: input.semanticLayer,
+            question,
+            questionPlan,
+            matchedMetric: semanticMetricMatch.metric,
+            filterValueColumns: (value) => resolveFilterValueColumns(value, schemaContext),
+            ...(input.semanticDriver ? { driver: input.semanticDriver } : {}),
+            ...(input.semanticTableMapping ? { tableMapping: input.semanticTableMapping } : {}),
+        });
+        // Lane-2 LLM fallback: the deterministic token matcher missed, but a metric
+        // matched so the semantic layer IS relevant. Spend ONE call to have the model
+        // pick members (the query_semantic_model contract); the compiler still owns the
+        // SQL, so a paraphrased metric question stays governed instead of dropping to
+        // Lane-3 generation.
+        if (!semanticBridgeAnswer) {
+            const selection = await selectSemanticMembersViaLlm({
+                provider,
+                semanticLayer: input.semanticLayer,
+                question,
+                signal: input.signal,
+                reasoningEffort: input.reasoningEffort,
+            });
+            if (selection) {
+                const composed = composeSemanticQueryFromMembers({
+                    semanticLayer: input.semanticLayer,
+                    question,
+                    selection,
+                    ...(input.semanticDriver ? { driver: input.semanticDriver } : {}),
+                    ...(input.semanticTableMapping ? { tableMapping: input.semanticTableMapping } : {}),
+                });
+                // Coverage guard: if the question asked for a breakdown but the LLM
+                // selection produced none, the governed answer would silently DROP the
+                // requested grouping (governed-but-wrong). Fall through to Lane-3
+                // generation, which can express the breakdown.
+                const wantedBreakdown = questionPlan.requestedShape.dimensions.length > 0
+                    || questionPlan.dimensionTerms.length > 0;
+                const dropsBreakdown = Boolean(composed)
+                    && wantedBreakdown
+                    && composed.dimensions.length === 0
+                    && !composed.timeDimension;
+                if (composed && !dropsBreakdown) {
+                    semanticBridgeAnswer = composed;
+                    semanticBridgeToolCalls.push({
+                        name: 'query_semantic_model',
+                        status: 'checked',
+                        inputSummary: `metrics: ${selection.metrics.join(', ')}${selection.dimensions?.length ? `; by ${selection.dimensions.join(', ')}` : ''}`,
+                        outputSummary: 'LLM-selected semantic members compiled via composeQuery',
+                        order: semanticBridgeToolCalls.length + 1,
+                    });
+                }
+            }
+        }
+    }
+    const metricFirst = semanticMetricMatch
+        ? buildGovernedMetricFirstSql({
+            metric: semanticMetricMatch.metric,
+            pool: semanticMetricNodes,
+            requestedShape: questionPlan.requestedShape,
+            schemaTables: schemaContext.map((table) => ({
+                relation: table.relation,
+                name: table.name,
+                columns: table.columns.map((column) => ({ name: column.name })),
+            })),
+            semanticLayer: input.semanticLayer,
+        })
+        : undefined;
+    let contextLedger = createContextLedger({
         contextPack: input.contextPack,
+        schemaContext,
     });
     let proposed = '';
     let parsed;
-    if (localProposal) {
-        parsed = localProposal;
+    const proposalToolCalls = [...semanticBridgeToolCalls];
+    if (semanticBridgeAnswer) {
+        governedMetricAnswer = true;
+        parsed = {
+            sql: semanticBridgeAnswer.sql,
+            text: `Answered from governed semantic metric${semanticBridgeAnswer.metrics.length === 1 ? '' : 's'} ${semanticBridgeAnswer.metrics.join(', ')}${semanticBridgeAnswer.dimensions.length > 0 ? ` by ${semanticBridgeAnswer.dimensions.join(', ')}` : ''}. This result is uncertified until reviewed and promoted.`,
+            viz: semanticBridgeAnswer.dimensions.length === 0 && !semanticBridgeAnswer.timeDimension ? 'single_value' : undefined,
+        };
+    }
+    else if (metricFirst) {
+        semanticMetricMatch = { ...semanticMetricMatch, metric: metricFirst.metric };
+        governedMetricAnswer = true;
+        parsed = {
+            sql: metricFirst.sql,
+            text: `Answered from the governed metric ${metricFirst.metric.name}${metricFirst.dimensions.length > 0 ? ` by ${metricFirst.dimensions.join(', ')}` : ''}. This result is uncertified until reviewed and promoted.`,
+            viz: metricFirst.dimensions.length === 0 ? 'single_value' : undefined,
+        };
     }
     else {
         try {
-            proposed = await provider.generate(messages, { signal: input.signal, reasoningEffort: input.reasoningEffort });
+            proposed = await generateProposalWithOptionalTools({
+                provider,
+                messages,
+                tools: input.answerLoopTools,
+                questionPlan,
+                intent,
+                signal: input.signal,
+                reasoningEffort: input.reasoningEffort,
+                analysisDepth: input.analysisDepth,
+                toolCalls: proposalToolCalls,
+            });
         }
         catch (err) {
             const text = `Provider error: ${err.message}`;
@@ -373,6 +655,8 @@ async function runAnswerLoop(input) {
                 confidence: 0,
                 text,
                 answer: text,
+                refusalCode: 'provider_error',
+                refusalDetails: { code: 'provider_error', message: text },
                 citations: [],
                 memoryContext: input.memoryContext,
                 evidence: buildNoAnswerEvidence({
@@ -384,6 +668,7 @@ async function runAnswerLoop(input) {
                     manifestHits,
                     considered,
                     memoryContext: input.memoryContext ?? [],
+                    toolCalls: proposalToolCalls,
                 }),
                 contextPack: input.contextPack,
                 considered,
@@ -392,11 +677,35 @@ async function runAnswerLoop(input) {
         }
         parsed = parseProposal(proposed);
     }
-    // True when `parsed.sql` was synthesized deterministically from a governed
-    // semantic-layer metric (not the LLM). Such SQL is trusted and grounded against
-    // the runtime schema, so it skips the hallucination-guard context validation
-    // that exists to catch model-invented relations/columns.
-    let governedMetricAnswer = false;
+    let deepCandidateResult;
+    let deepCandidateExecutionError;
+    let deepCandidateNotes = [];
+    if (!governedMetricAnswer && input.analysisDepth === 'deep' && parsed.sql) {
+        const selection = await selectDeepGeneratedProposalCandidate({
+            provider,
+            messages,
+            question,
+            questionPlan,
+            intent,
+            initial: { raw: proposed, parsed },
+            contextLedger,
+            executeGeneratedSql: input.executeGeneratedSql,
+            signal: input.signal,
+            reasoningEffort: input.reasoningEffort,
+        });
+        if (selection.selected) {
+            proposed = selection.selected.raw;
+            parsed = selection.selected.parsed;
+            deepCandidateResult = selection.selected.result;
+            deepCandidateExecutionError = selection.selected.executionError;
+        }
+        deepCandidateNotes = selection.notes;
+    }
+    // `governedMetricAnswer` (declared above): true when `parsed.sql` was
+    // synthesized deterministically from a governed semantic-layer metric (not the
+    // LLM). Such SQL is trusted and grounded against the runtime schema, so it
+    // skips the hallucination-guard context validation that exists to catch
+    // model-invented relations/columns.
     if (!parsed.sql) {
         // Spec 17, part C — if a governed metric matched confidently but the model
         // declined SQL, answer from the metric definition (deterministic, offline)
@@ -406,7 +715,7 @@ async function runAnswerLoop(input) {
         // (`order_item.revenue`). resolveGovernedMetricSql resolves a thin metric to
         // that synthesizable sibling so the route lands on a real number, not refusal.
         const resolved = activeTier === 'semantic_layer' && semanticMetricMatch
-            ? resolveGovernedMetricSql(semanticMetricMatch.metric, semanticMetricNodes)
+            ? resolveGovernedMetricSql(semanticMetricMatch.metric, semanticMetricNodes, input.semanticLayer)
             : undefined;
         if (resolved) {
             // Point the match at the metric we actually answered from so the route
@@ -421,8 +730,54 @@ async function runAnswerLoop(input) {
             };
         }
     }
+    // Forced-join retry. The model declined SQL (rule 8 escape) — but a composite
+    // "top X who did top Y" that spans several concepts often trips the model into
+    // "there's no combined dataset — show them separately", which is a FALSE refusal
+    // when the grounded tables and KG join routes to connect them are right there in
+    // context. If the question genuinely wants generated data and we DO have usable
+    // relations/schema to build the join, re-issue ONCE with an explicit instruction
+    // to compose the join rather than refuse. A truly absent table/column/join key
+    // still falls through to the honest no_answer below.
+    const wantsGeneratedData = questionPlan.requestedShape.measures.length > 0
+        || questionPlan.requestedShape.dimensions.length > 0
+        || questionPlan.requestedShape.requiredOutputs.length > 0
+        || Boolean(questionPlan.requestedShape.topN);
+    const hasGeneratableContext = schemaContext.length > 0
+        || (input.contextPack?.allowedSqlContext?.relations.length ?? 0) > 0
+        || (input.contextPack?.allowedSqlContext?.sourceBlockSql.length ?? 0) > 0
+        || contextBlocks.length > 0;
+    if (!parsed.sql && !governedMetricAnswer && wantsGeneratedData && hasGeneratableContext) {
+        try {
+            proposed = await generateProposalWithOptionalTools({
+                provider,
+                messages: [...messages, { role: 'system', content: FORCE_JOIN_INSTRUCTION }],
+                tools: input.answerLoopTools,
+                questionPlan,
+                intent,
+                signal: input.signal,
+                reasoningEffort: input.reasoningEffort,
+                analysisDepth: input.analysisDepth,
+                toolCalls: proposalToolCalls,
+            });
+            parsed = parseProposal(proposed);
+        }
+        catch {
+            // keep the original decline; fall through to the honest no_answer.
+        }
+    }
     if (!parsed.sql) {
-        const text = parsed.text || 'No answer (the model declined to propose SQL).';
+        // Deterministic honest refusal. The model's own decline prose is STOCHASTIC
+        // ("there's no combined dataset — show them separately" one run, a different
+        // phrasing the next), which reads as flaky and inconsistent across surfaces.
+        // When the question wanted data AND usable context existed (a groundable ask
+        // the model still declined even after the forced-join retry), surface ONE
+        // consistent, actionable message so the same question yields the same outcome
+        // every run and every surface — instead of passing through the model's varying
+        // text. A genuinely context-less ask keeps the plain honest message.
+        const declinedDespiteContext = wantsGeneratedData && hasGeneratableContext;
+        const text = declinedDespiteContext
+            ? 'I could not compose a governed query for this from the available tables and metrics. This usually needs a clearer join path or an explicit metric and grouping — name the specific measure and how to break it down, and I can generate a review-required draft.'
+            : parsed.text || 'No answer (the model declined to propose SQL).';
         return {
             kind: 'no_answer',
             sourceTier: 'no_answer',
@@ -430,6 +785,11 @@ async function runAnswerLoop(input) {
             reviewStatus: 'none',
             confidence: 0.1,
             text,
+            refusalCode: 'model_declined',
+            refusalDetails: {
+                code: 'model_declined',
+                message: text,
+            },
             answer: text,
             citations: [],
             memoryContext: input.memoryContext,
@@ -452,32 +812,30 @@ 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.
-    let grounding;
-    if (parsed.sql && schemaContext.length > 0) {
-        grounding = buildGroundingFromRuntimeRelations(schemaContext.map((table) => ({
-            relation: table.relation,
-            name: table.name,
-            columns: table.columns.map((column) => ({ name: column.name, type: column.type, description: column.description })),
-        })));
-        parsed.sql = resolveRelationsInSql(parsed.sql, grounding, { prefer: 'qualified' }).sql;
+    if (parsed.sql) {
+        parsed.sql = contextLedger.qualifySql(parsed.sql).sql;
     }
     // Validation gate. Governed metric SQL synthesized from the semantic layer is
     // already trusted (deterministic + grounded); model SQL is validated against the
     // inspected context to catch hallucinated relations/columns.
     const semanticMetricRoute = activeTier === 'semantic_layer' && Boolean(semanticMetricMatch);
+    const scalarGovernedMetricRecoveryAllowed = questionPlan.requestedShape.dimensions.length === 0
+        && questionPlan.requestedShape.filters.length === 0
+        && !questionPlan.requestedShape.topN;
     let contextValidation;
     if (governedMetricAnswer) {
         contextValidation = { ok: true, warnings: [] };
     }
     else {
-        const c = validateSqlAgainstLocalContext(parsed.sql, input.contextPack, {
+        const c = contextLedger.validateSql(parsed.sql, {
             question,
             intent,
             filterValues: input.followUp?.filters,
+            trustedFilterValues: trustedFollowUpFilterValues(input.followUp),
         });
         contextValidation = c.ok
             ? { ok: true, warnings: c.warnings }
-            : { ok: false, error: c.error, warnings: c.warnings };
+            : { ok: false, code: c.code, error: c.error, warnings: c.warnings, offending: c.offending };
     }
     // Spec 17, part C — semantic-metric route recovery. A metric question is often
     // catalog-routed to clarify, leaving a thin contextPack that rejects otherwise-valid
@@ -489,41 +847,132 @@ async function runAnswerLoop(input) {
     //   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 && semanticMetricRoute && semanticMetricMatch) {
-        const grounded = grounding ? validateSqlAgainstGrounding(parsed.sql, grounding) : undefined;
+        const grounded = contextLedger.validateRuntimeGrounding(parsed.sql);
         if (grounded?.ok) {
             contextValidation = { ok: true, warnings: grounded.warnings };
         }
-        else {
-            const recovered = resolveGovernedMetricSql(semanticMetricMatch.metric, semanticMetricNodes);
+        else if (scalarGovernedMetricRecoveryAllowed) {
+            const recovered = resolveGovernedMetricSql(semanticMetricMatch.metric, semanticMetricNodes, input.semanticLayer);
             if (recovered) {
                 semanticMetricMatch = { ...semanticMetricMatch, metric: recovered.metric };
-                parsed.sql = grounding
-                    ? resolveRelationsInSql(recovered.sql, grounding, { prefer: 'qualified' }).sql
-                    : recovered.sql;
+                parsed.sql = contextLedger.qualifySql(recovered.sql).sql;
                 parsed.viz = parsed.viz ?? 'single_value';
                 parsed.text = parsed.text
                     || `Answered from the governed metric ${recovered.metric.name}. This result is uncertified until reviewed and promoted.`;
                 governedMetricAnswer = true;
                 contextValidation = {
                     ok: true,
-                    warnings: ['Generated SQL failed context validation; answered from the governed metric definition instead.'],
+                    warnings: ['SQL preview failed context validation; answered from the governed metric definition instead.'],
                 };
             }
         }
     }
+    if (!contextValidation.ok && !governedMetricAnswer && input.expandGroundingContext && canUseLaneRepair(repairBudgetState, 'reground')) {
+        recordLaneRepair(repairBudgetState, 'reground');
+        try {
+            const expansion = await input.expandGroundingContext({
+                question,
+                sql: parsed.sql,
+                code: contextValidation.code ?? 'insufficient_context',
+                offending: contextValidation.offending,
+                contextPack: contextLedger.contextPack,
+                schemaContext: contextLedger.schemaContext,
+            });
+            const merged = contextLedger.withExpansion(expansion);
+            if (merged.notes.length > 0) {
+                contextLedger = merged.ledger;
+                parsed.sql = contextLedger.qualifySql(parsed.sql).sql;
+                const revalidated = contextLedger.validateSql(parsed.sql, {
+                    question,
+                    intent,
+                    filterValues: input.followUp?.filters,
+                    trustedFilterValues: trustedFollowUpFilterValues(input.followUp),
+                });
+                contextValidation = revalidated.ok
+                    ? {
+                        ok: true,
+                        warnings: [
+                            ...revalidated.warnings,
+                            ...merged.notes.map((note) => `Re-grounded metadata context before repair: ${note}`),
+                        ],
+                    }
+                    : {
+                        ok: false,
+                        code: revalidated.code,
+                        error: revalidated.error,
+                        warnings: [
+                            ...revalidated.warnings,
+                            ...merged.notes.map((note) => `Re-grounded metadata context before repair: ${note}`),
+                        ],
+                        offending: revalidated.offending,
+                    };
+            }
+        }
+        catch {
+            // Re-grounding is best-effort; the bounded self-repair below still runs.
+        }
+    }
+    // One bounded self-repair before refusing: hand the model the EXACT guard
+    // error (e.g. `column "product_name" outside the inspected columns for
+    // order_items`) so it can correct itself — usually by joining the relation
+    // that actually carries the column. Deterministic paths that never called the
+    // provider get the same single chance; any provider failure keeps the honest
+    // refusal below. This mirrors the engine-level repair loop, applied to the
+    // context-validation gate that previously refused on first failure.
+    if (!contextValidation.ok && !governedMetricAnswer && canUseLaneRepair(repairBudgetState, 'reground')) {
+        recordLaneRepair(repairBudgetState, 'reground');
+        try {
+            const failedSql = parsed.sql ?? '';
+            const repairPrompt = [
+                `Your SQL was rejected before execution: ${contextValidation.error}`,
+                formatOffendingValidationToken(contextValidation.offending),
+                formatValidationWarningsForPrompt(contextValidation.warnings),
+                'Correct it using ONLY the relations and columns from the inspected context above.',
+                'If a needed column lives on a different relation, JOIN that relation using the suggested join paths.',
+                'If the requested column does not exist anywhere in the inspected context, return the closest answerable SQL and say what is missing.',
+                'Return a single ```json fenced object: {"summary":"...","sql":"SELECT ...","viz":"table","outputs":["column"],"dql":{"entity":"...","dimensions":["..."],"filters":["..."]}}.',
+            ].join('\n');
+            const repairRaw = await provider.generate([...messages, { role: 'assistant', content: failedSql }, { role: 'user', content: repairPrompt }], { signal: input.signal, reasoningEffort: input.reasoningEffort });
+            const reparsed = parseProposal(repairRaw);
+            if (reparsed.sql) {
+                reparsed.sql = contextLedger.qualifySql(reparsed.sql).sql;
+                const revalidated = contextLedger.validateSql(reparsed.sql, {
+                    question,
+                    intent,
+                    filterValues: input.followUp?.filters,
+                    trustedFilterValues: trustedFollowUpFilterValues(input.followUp),
+                });
+                if (revalidated.ok) {
+                    const repairedSql = reparsed.sql;
+                    parsed.sql = repairedSql;
+                    parsed.text = reparsed.text || parsed.text;
+                    parsed.viz = reparsed.viz ?? parsed.viz;
+                    applyParsedProposalMetadata(parsed, reparsed);
+                    contextValidation = {
+                        ok: true,
+                        warnings: [...revalidated.warnings, 'Repaired after context-validation failure (1 repair).'],
+                    };
+                }
+            }
+        }
+        catch {
+            // Repair is best-effort — the refusal below stays the honest fallback.
+        }
+    }
     if (!contextValidation.ok) {
-        const text = `I could not safely prepare this generated SQL from the inspected context. ${contextValidation.error}`;
+        const text = `I could not safely prepare this review-required DQL artifact from the inspected context. The SQL preview failed validation: ${contextValidation.error}`;
         const analysisPlan = buildAnalysisPlan({
             question,
             intent,
-            routeReason: catalogRoute?.reason ?? 'Generated SQL failed metadata context validation before preview execution or draft capture.',
+            routeReason: catalogRoute?.reason ?? 'SQL preview for the review-required DQL artifact failed metadata context validation before preview execution or draft capture.',
             selectedNodes: contextNodes,
             schemaContext,
             sql: parsed.sql,
             suggestedViz: parsed.viz ?? 'table',
             assumptions: [
-                'Generated SQL was rejected before execution because it did not match inspected metadata context.',
+                'SQL preview was rejected before execution because it did not match inspected metadata context.',
                 ...contextValidation.warnings,
+                ...deepCandidateNotes,
             ],
         });
         return {
@@ -533,13 +982,19 @@ async function runAnswerLoop(input) {
             reviewStatus: 'none',
             confidence: 0.15,
             text,
+            refusalCode: refusalCodeForValidation(contextValidation.code),
+            refusalDetails: {
+                code: contextValidation.code ?? 'insufficient_context',
+                message: contextValidation.error,
+                offending: contextValidation.offending,
+            },
             answer: text,
             proposedSql: parsed.sql,
             sql: parsed.sql,
             trustLabel: input.contextPack?.trustLabel,
             sourceCertifiedBlock: followUpSourceBlock?.name ?? input.followUp?.sourceBlockName,
             contextPackId: input.contextPack?.id,
-            validationWarnings: contextValidation.warnings,
+            validationWarnings: [...contextValidation.warnings, ...deepCandidateNotes],
             selectedEvidence: input.contextPack?.evidenceRoles?.slice(0, 12),
             citations: [],
             memoryContext: input.memoryContext,
@@ -557,7 +1012,7 @@ async function runAnswerLoop(input) {
             }),
             contextPack: input.contextPack,
             considered,
-            providerUsed: localProposal ? 'schema_planner' : provider.name,
+            providerUsed: provider.name,
         };
     }
     const generatedCitations = [
@@ -585,26 +1040,56 @@ async function runAnswerLoop(input) {
     // The repair turn returns error-recovery prose ("the column X was not recognized…"),
     // NOT a user-facing answer. Keep it for the trace only — never as the answer text.
     let repairNarrative;
-    if (input.executeGeneratedSql) {
+    if (deepCandidateResult) {
+        result = deepCandidateResult;
+    }
+    if (deepCandidateExecutionError) {
+        executionError = deepCandidateExecutionError;
+    }
+    if (input.executeGeneratedSql && !result) {
         try {
-            result = await input.executeGeneratedSql(parsed.sql);
+            if (!executionError)
+                result = await input.executeGeneratedSql(parsed.sql);
         }
         catch (err) {
             executionError = err instanceof Error ? err.message : String(err);
+        }
+        if (executionError) {
             if (isRetryableGeneratedSqlError(executionError)) {
                 const localRepairSql = repairGeneratedSqlLocally(parsed.sql, executionError, schemaContext);
-                if (localRepairSql) {
-                    repairAttempts = 1;
-                    parsed.sql = localRepairSql;
-                    try {
-                        result = await input.executeGeneratedSql(parsed.sql);
-                        executionError = undefined;
+                if (localRepairSql && canUseLaneRepair(repairBudgetState, 'execution')) {
+                    recordLaneRepair(repairBudgetState, 'execution');
+                    const qualifiedLocalRepairSql = contextLedger.qualifySql(localRepairSql).sql;
+                    const localRepairValidation = contextLedger.validateSql(qualifiedLocalRepairSql, {
+                        question,
+                        intent,
+                        filterValues: input.followUp?.filters,
+                        trustedFilterValues: trustedFollowUpFilterValues(input.followUp),
+                    });
+                    if (localRepairValidation.ok) {
+                        repairAttempts = 1;
+                        parsed.sql = qualifiedLocalRepairSql;
+                        contextValidation = {
+                            ok: true,
+                            warnings: [
+                                ...localRepairValidation.warnings,
+                                'Execution-repaired SQL passed context validation.',
+                            ],
+                        };
+                        try {
+                            result = await input.executeGeneratedSql(parsed.sql);
+                            executionError = undefined;
+                        }
+                        catch (retryErr) {
+                            executionError = retryErr instanceof Error ? retryErr.message : String(retryErr);
+                        }
                     }
-                    catch (retryErr) {
-                        executionError = retryErr instanceof Error ? retryErr.message : String(retryErr);
+                    else {
+                        executionError = localRepairValidation.error;
                     }
                 }
-                if (executionError) {
+                if (executionError && canUseLaneRepair(repairBudgetState, 'execution')) {
+                    recordLaneRepair(repairBudgetState, 'execution');
                     const repairedRaw = await requestSqlRepair({
                         provider,
                         baseMessages: messages,
@@ -617,17 +1102,37 @@ async function runAnswerLoop(input) {
                     });
                     const repaired = parseProposal(repairedRaw);
                     if (repaired.sql) {
-                        repairAttempts += 1;
-                        // Adopt the corrected SQL, but do NOT let the repair prose become the answer.
-                        repairNarrative = repaired.text?.trim() || undefined;
-                        parsed.sql = repaired.sql;
-                        parsed.viz = repaired.viz ?? parsed.viz;
-                        try {
-                            result = await input.executeGeneratedSql(parsed.sql);
-                            executionError = undefined;
+                        repaired.sql = contextLedger.qualifySql(repaired.sql).sql;
+                        const repairedValidation = contextLedger.validateSql(repaired.sql, {
+                            question,
+                            intent,
+                            filterValues: input.followUp?.filters,
+                            trustedFilterValues: trustedFollowUpFilterValues(input.followUp),
+                        });
+                        if (repairedValidation.ok) {
+                            repairAttempts += 1;
+                            // Adopt the corrected SQL, but do NOT let the repair prose become the answer.
+                            repairNarrative = repaired.text?.trim() || undefined;
+                            parsed.sql = repaired.sql;
+                            parsed.viz = repaired.viz ?? parsed.viz;
+                            applyParsedProposalMetadata(parsed, repaired);
+                            contextValidation = {
+                                ok: true,
+                                warnings: [
+                                    ...repairedValidation.warnings,
+                                    'Execution-repaired SQL passed context validation.',
+                                ],
+                            };
+                            try {
+                                result = await input.executeGeneratedSql(parsed.sql);
+                                executionError = undefined;
+                            }
+                            catch (retryErr) {
+                                executionError = retryErr instanceof Error ? retryErr.message : String(retryErr);
+                            }
                         }
-                        catch (retryErr) {
-                            executionError = retryErr instanceof Error ? retryErr.message : String(retryErr);
+                        else {
+                            executionError = repairedValidation.error;
                         }
                     }
                 }
@@ -638,26 +1143,73 @@ async function runAnswerLoop(input) {
         question,
         intent,
         routeReason: catalogRoute?.reason ?? (intent === 'drillthrough'
-            ? 'The user asked for a drill-through or follow-up, so DQL generated review-required SQL from the prior context and current metadata.'
+            ? 'The user asked for a drill-through or follow-up, so DQL prepared a review-required artifact with a SQL preview from the prior context and current metadata.'
             : '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,
         suggestedViz: parsed.viz ?? 'table',
         assumptions: [
-            'Generated SQL is an uncertified preview until an analyst reviews and promotes it.',
-            ...(localProposal ? ['A local metadata planner selected a review-required SQL grain before provider generation.'] : []),
+            'The SQL preview is uncertified until an analyst reviews and promotes the DQL artifact.',
             ...(repairNarrative ? [`Auto-corrected the query after an execution error: ${repairNarrative}`] : []),
             ...contextValidation.warnings,
             ...(executionError ? ['The preview execution error must be reviewed before reuse.'] : []),
         ],
         repairAttempts,
     });
+    // Global top-N asks must return exactly N rows even when the generated SQL
+    // returned more (missing/oversized LIMIT) — mirrors the certified path so a
+    // "top 10" question never shows 200 rows. per_group scope is left intact by
+    // trimResultToRequestedTopN. Domain-agnostic.
+    let topNTrimNote;
+    if (result) {
+        const beforeRows = Array.isArray(result.rows) ? result.rows.length : result.rowCount;
+        result = trimResultToRequestedTopN(result, questionPlan);
+        const afterRows = Array.isArray(result.rows) ? result.rows.length : result.rowCount;
+        if (afterRows < beforeRows) {
+            topNTrimNote = `Showed the top ${questionPlan.requestedShape.topN?.n ?? afterRows} of ${beforeRows} rows the query returned.`;
+        }
+    }
+    const resultShape = result ? validateAnswerResultShape(questionPlan, result) : undefined;
+    // 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
+    // names the missing columns — a partial table the user can see and refine beats a
+    // blank clarify. Domain-agnostic: works for every project, not just jaffle. The
+    // shape gate downgrades trust rather than blocking the answer.
+    const partialShapeMismatch = Boolean(resultShape && result && result.rowCount > 0
+        && generatedResultShapeIsPartial(resultShape));
+    const partialShapeWarning = partialShapeMismatch && resultShape
+        ? `Partial answer: the result is missing ${resultShape.missingOutputs.join(', ')}`
+            + `. Showing the closest table that executed — review before reuse, or narrow the question to the columns shown.`
+        : undefined;
     const validationWarnings = [
         ...(input.contextPack?.warnings ?? []),
         ...contextValidation.warnings,
+        ...deepCandidateNotes,
+        ...(resultShape?.warnings ?? []),
+        ...(partialShapeWarning ? [partialShapeWarning] : []),
+        ...(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 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,
+    });
     let draftBlock;
     let draftCaptureError;
     if (input.captureGeneratedDraft && parsed.sql) {
@@ -669,7 +1221,13 @@ async function runAnswerLoop(input) {
                 followUp: input.followUp,
                 contextPack: input.contextPack,
                 sourceBlock: followUpSourceBlock ?? undefined,
+                sourceDqlArtifact: input.followUp?.priorDqlArtifact,
+                dqlArtifact,
+                proposedEntity: parsed.proposedEntity,
+                requestedFilters: generatedRequestedFilters,
+                requestedDimensions: generatedRequestedDimensions,
                 validationWarnings,
+                outputs: generatedOutputs,
             });
         }
         catch (err) {
@@ -677,6 +1235,9 @@ async function runAnswerLoop(input) {
             validationWarnings.push(`Draft capture failed: ${draftCaptureError}`);
         }
     }
+    const answerDqlArtifact = dqlArtifact && draftBlock?.path
+        ? { ...dqlArtifact, sourcePath: dqlArtifact.sourcePath ?? draftBlock.path }
+        : dqlArtifact;
     const sourceCertifiedBlock = followUpSourceBlock?.name ?? input.followUp?.sourceBlockName;
     const trustExplanation = generatedTrustExplanation({
         followUp: input.followUp,
@@ -684,15 +1245,20 @@ async function runAnswerLoop(input) {
         draftBlock,
     });
     const cleanedSummary = cleanGeneratedSummary(parsed.text);
-    const generatedText = trustExplanation
-        ? [trustExplanation, cleanedSummary].filter(Boolean).join('\n\n')
-        : cleanedSummary;
+    const generatedText = [partialShapeWarning, trustExplanation, cleanedSummary]
+        .filter(Boolean)
+        .join('\n\n');
+    const semanticMetricCertification = governedMetricAnswer && activeTier === 'semantic_layer'
+        ? semanticMetricMatch?.metric.certification
+        : undefined;
+    const certifiedMetricAnswer = semanticMetricCertification === 'certified' || semanticMetricCertification === 'reviewed';
     return {
         kind: 'uncertified',
         sourceTier: activeTier,
         certification: 'ai_generated',
         reviewStatus: 'draft_ready',
-        confidence: activeTier === 'semantic_layer' ? 0.72 : 0.55,
+        semanticMetricCertification,
+        confidence: certifiedMetricAnswer ? 0.8 : governedMetricAnswer && activeTier === 'semantic_layer' ? 0.72 : 0.55,
         text: generatedText,
         answer: generatedText,
         proposedSql: parsed.sql,
@@ -700,6 +1266,7 @@ async function runAnswerLoop(input) {
         result,
         executionError,
         suggestedViz: parsed.viz ?? 'table',
+        dqlArtifact: answerDqlArtifact,
         draftBlock,
         draftBlockId: draftBlock?.path,
         promoteCommand: draftBlock ? `dql certify --from-draft ${draftBlock.path}` : undefined,
@@ -714,10 +1281,15 @@ async function runAnswerLoop(input) {
         evidence: buildGeneratedEvidence({
             question,
             activeTier,
+            terminalLane: governedMetricAnswer ? 'semantic' : 'generated',
+            terminalDetail: governedMetricAnswer
+                ? semanticBridgeAnswer?.metrics.join(', ') ?? semanticMetricMatch?.metric.name
+                : answerDqlArtifact?.name ?? draftBlock?.path,
             intent,
             contextNodes,
             schemaContext,
             followUp: input.followUp,
+            contextPack: input.contextPack,
             businessHits,
             semanticHits,
             manifestHits,
@@ -728,15 +1300,42 @@ async function runAnswerLoop(input) {
             executionError,
             executorWasAvailable: Boolean(input.executeGeneratedSql),
             analysisPlan,
+            toolCalls: proposalToolCalls,
+            budgetTrace: cascadeBudgetTrace(repairBudgetState),
         }),
         contextPack: input.contextPack,
         considered,
-        providerUsed: localProposal ? 'schema_planner' : provider.name,
+        providerUsed: provider.name,
         // Carry the governed metric match so the exit point can name a
         // `semantic_metric` route (spec 17, part C).
-        _semanticMetricMatch: activeTier === 'semantic_layer' ? semanticMetricMatch ?? undefined : undefined,
+        _semanticMetricMatch: governedMetricAnswer && activeTier === 'semantic_layer' ? semanticMetricMatch ?? undefined : undefined,
+    };
+}
+function trimResultToRequestedTopN(result, plan) {
+    const topN = plan.requestedShape.topN;
+    if (!topN || topN.scope === 'per_group' || !Array.isArray(result.rows) || result.rows.length <= topN.n)
+        return result;
+    return {
+        ...result,
+        rows: result.rows.slice(0, topN.n),
+        rowCount: Math.min(result.rowCount, topN.n),
     };
 }
+function resultColumnNames(result) {
+    if (!result?.columns)
+        return undefined;
+    const columns = result.columns
+        .map((column) => {
+        if (typeof column === 'string')
+            return column.trim();
+        if (column && typeof column === 'object' && typeof column.name === 'string') {
+            return column.name.trim();
+        }
+        return '';
+    })
+        .filter(Boolean);
+    return columns?.length ? columns : undefined;
+}
 const SYSTEM_PROMPT = `You are the DQL Analytics Agent.
 
 Rules:
@@ -746,16 +1345,21 @@ Rules:
 2. Use certified DQL blocks only when the user's question exactly asks for that
    saved block, direct KPI, or definition. For single-user/customer/account,
    custom filters, rankings, breakdowns, comparisons, drill-throughs, or custom
-   grains, generate review-required SQL from supplied metadata and cite
-   certified context as evidence.
-3. If you must generate SQL, return it inside a single \`\`\`sql code block.
-4. Provide a one-paragraph natural-language summary BEFORE the SQL block. In it,
-   state your QUERY PLAN first: the grain (one row per WHAT), the measures and how
-   they aggregate, the dimensions/filters, and the exact join path + join keys
-   between the grounded tables. Then write SQL that matches that plan — an explicit
-   grain and join path prevents wrong-grain answers and fan-out (row-multiplying) joins.
-5. Suggest a visualization type from this list, on a line starting with "Viz:":
-   line, bar, area, pie, single_value, table, pivot, kpi.
+   grains, prepare a review-required DQL artifact with a SQL preview from
+   supplied metadata and cite certified context as evidence.
+3. If you must create a SQL preview, return a single \`\`\`json fenced object with:
+   {"summary": "...", "sql": "SELECT ...", "viz": "table", "outputs": ["column_a"], "dql": {"entity": "orders", "dimensions": ["region"], "filters": ["last 30 days"]}}.
+   The SQL string must be one read-only SELECT/WITH statement. Do not include a
+   separate SQL code fence when using JSON. The optional "dql" object is
+   metadata for the deterministic draft-DQL renderer; do not hand-write a full
+   DQL block.
+4. In summary, state your QUERY PLAN first: the grain (one row per WHAT), the
+   measures and how they aggregate, the dimensions/filters, and the exact join
+   path + join keys between the grounded tables. Then make the SQL match that
+   plan — an explicit grain and join path prevents wrong-grain answers and
+   fan-out (row-multiplying) joins.
+5. Use a visualization type from this list in the "viz" JSON field: line, bar,
+   area, pie, single_value, table, pivot, kpi.
 6. NEVER fabricate column names that are not present in the supplied schema,
    dbt metadata, or certified source SQL shape context. If a requested filter
    value is supplied as a matched value, prefer the table and column that
@@ -765,18 +1369,32 @@ Rules:
    proposed SQL. Do not emit INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, COPY,
    PRAGMA, SET, or multiple statements.
 8. If the schema is insufficient to answer, say so explicitly and ask a
-   clarifying question instead of guessing.
+   clarifying question instead of guessing. But a MULTI-ENTITY question ("top
+   customers who bought the top products", "accounts with the most overdue
+   invoices") is NOT insufficient context when the grounded tables and a join
+   route between them are supplied (see any "Knowledge graph join routes"
+   section). In that case you MUST compose the joined SELECT that answers it
+   directly — never refuse it or offer to show the parts as separate datasets.
+   Reserve the clarifying question for a genuinely absent table, column, or join
+   key.
 9. Write directly to the analyst. Do not say "the user is asking", "the user
    requested", "I will generate", or describe internal routing. State the
-   answer, the certified context used, and the review requirement.
+   answer, the certified context used, the DQL artifact expectation, and the
+   review requirement.
 10. For notebook research, SQL build or repair, DQL import/build, or DQL reuse
    checks, start with one line in this form: "Outcome: <decision>". Use one of
-   these decisions: Reuse certified block, Use existing draft, Generate SQL
-   cell, Fix SQL, Create DQL draft, Needs review, Cannot answer yet.`;
-function renderContextPrompt(blocks, businessContext, others, activeTier, memoryContext, extraContext, followUp, schemaContext = [], intent = 'ad_hoc_analysis', contextPack) {
+   these decisions: Reuse certified block, Use existing draft, Review SQL preview,
+   Fix SQL, Create DQL draft, Needs review, Cannot answer yet.`;
+// Appended on a single retry when the model declined SQL for a question that the
+// grounded schema + KG join routes can actually answer. Turns a false "no
+// 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.`;
+function renderContextPrompt(blocks, businessContext, others, activeTier, memoryContext, extraContext, followUp, schemaContext = [], intent = 'ad_hoc_analysis', contextPack, conversationSnapshot, kgJoinPathHints = [], budget = QUICK_PROMPT_CONTEXT_BUDGET) {
     const intentSection = `## Routing intent\n\nintent: ${intent}\n${intent === 'exact_certified_lookup'
         ? 'Use a certified artifact only if it exactly answers the question.'
-        : 'Generate review-required SQL for this question. Certified blocks are trusted context, not a reason to answer the wrong grain.'}`;
+        : 'Prepare a review-required DQL artifact with a SQL preview for this question. Certified blocks are trusted context, not a reason to answer the wrong grain.'}`;
+    const budgetSection = `\n\n## Context budget\n\nContext budget: ${budget.label} (relations=${budget.relationCardLimit}, relation_columns=${budget.relationColumnLimit}, objects=${budget.contextObjectLimit}, edges=${budget.edgeLimit}).`;
     const blockSection = blocks.length > 0
         ? `## Relevant DQL blocks\n\n${blocks
             .map((b) => `- \`${b.nodeId}\` (${b.domain ?? 'unscoped'}, ${b.status ?? b.certification ?? 'review_required'}): ${b.description ?? b.llmContext ?? '(no description)'}`)
@@ -792,12 +1410,15 @@ function renderContextPrompt(blocks, businessContext, others, activeTier, memory
             .map((n) => `- ${n.kind} \`${n.name}\`${n.domain ? ` (domain: ${n.domain})` : ''}${n.description ? ` — ${n.description}` : ''}${n.llmContext ? `\n  ${n.llmContext.replace(/\n/g, '\n  ')}` : ''}`)
             .join('\n')}`
         : '';
+    const kgJoinSection = kgJoinPathHints.length > 0
+        ? `\n\n## Knowledge graph join routes\n\nUse these as relationship/navigation evidence for multi-entity analysis. SQL must still use inspected relation columns from the schema or metadata context.\n${kgJoinPathHints.map((hint) => `- ${hint}`).join('\n')}`
+        : '';
     const schemaSection = schemaContext.length > 0
         ? `\n\n## Runtime schema context\n\nUse only these runtime relations and columns when generating SQL unless the dbt manifest context gives an equivalent relation.\n${schemaContext
-            .slice(0, 12)
+            .slice(0, budget.schemaTableLimit)
             .map((table) => {
             const cols = table.columns
-                .slice(0, 50)
+                .slice(0, budget.schemaColumnLimit)
                 .map((col) => {
                 const sampleValues = col.sampleValues?.length
                     ? `; matched values: ${col.sampleValues.slice(0, 4).map(formatPromptValue).join(', ')}`
@@ -817,27 +1438,118 @@ function renderContextPrompt(blocks, businessContext, others, activeTier, memory
         : '';
     // Approved, scope-matched correction hints from the Hint Graph. These are
     // human-reviewed lessons (often from a prior wrong→right SQL correction), so
-    // they carry more weight than advisory memory when generating SQL — but they
+    // they carry more weight than advisory memory when preparing a SQL preview — but they
     // still must NOT override a certified artifact that already answers exactly.
     const appliedHints = contextPack?.appliedHints ?? [];
     const hintsSection = appliedHints.length > 0
-        ? `\n\n## Applied governed hints (human-approved corrections)\n\nReviewed, scope-matched corrections from your team. Apply them when generating SQL to avoid known mistakes; they refine generated SQL but MUST NOT override a certified artifact that already answers the question.\n${appliedHints
+        ? `\n\n## Applied governed hints (human-approved corrections)\n\nReviewed, scope-matched corrections from your team. Apply them when preparing a SQL preview to avoid known mistakes; they refine the DQL artifact's SQL preview but MUST NOT override a certified artifact that already answers the question.\n${appliedHints
             .slice(0, 6)
             .map((h) => `- \`${h.title}\`: ${h.guidance}${h.correctedSql ? `\n  corrected SQL pattern: ${h.correctedSql.replace(/\s+/g, ' ').trim().slice(0, 240)}` : ''}`)
             .join('\n')}`
         : '';
     const extraSection = extraContext?.trim()
-        ? `\n\n## Current notebook/app context\n\nThis context may help interpret the user's request, but it MUST NOT override certified artifacts, semantic metrics, dbt metadata, or generated SQL validation.\n\n${extraContext.trim()}`
+        ? `\n\n## Current notebook/app context\n\nThis context may help interpret the user's request, but it MUST NOT override certified artifacts, semantic metrics, dbt metadata, or SQL preview validation.\n\n${extraContext.trim()}`
         : '';
     const followUpSection = followUp
         ? `\n\n## Follow-up routing context\n\n${renderFollowUpContext(followUp)}`
         : '';
+    const conversationSection = conversationSnapshot
+        ? `\n\n## Conversation state (session)\n\n${renderConversationSnapshot(conversationSnapshot)}`
+        : '';
     const contextPackSection = contextPack
-        ? `\n\n## Local metadata context pack\n\n${renderContextPackForPrompt(contextPack)}`
+        ? `\n\n## Local metadata context pack\n\n${renderContextPackForPrompt(contextPack, budget)}`
         : '';
-    return `${intentSection}\n\n${blockSection}${businessSection}${otherSection}${schemaSection}${contextPackSection}${memorySection}${hintsSection}${extraSection}${followUpSection}`;
+    return `${intentSection}${budgetSection}\n\n${blockSection}${businessSection}${otherSection}${kgJoinSection}${schemaSection}${contextPackSection}${memorySection}${hintsSection}${conversationSection}${extraSection}${followUpSection}`;
 }
-function renderContextPackForPrompt(contextPack) {
+function buildKgJoinPathHints(kg, nodes, questionPlan) {
+    const candidates = nodes
+        .filter((node) => ['block', 'business_view', 'metric', 'entity', 'semantic_model', 'dbt_model', 'dbt_source'].includes(node.kind))
+        .slice(0, 8);
+    if (candidates.length < 2)
+        return [];
+    const domains = new Set(candidates.map((node) => node.domain).filter((domain) => Boolean(domain)));
+    const shouldSearch = domains.size > 1 || questionPlan.entities.length > 1 || questionPlan.dimensionTerms.length > 1;
+    if (!shouldSearch)
+        return [];
+    const hints = [];
+    const seen = new Set();
+    for (let leftIndex = 0; leftIndex < candidates.length; leftIndex += 1) {
+        for (let rightIndex = leftIndex + 1; rightIndex < candidates.length; rightIndex += 1) {
+            if (hints.length >= 6)
+                return hints;
+            const left = candidates[leftIndex];
+            const right = candidates[rightIndex];
+            const path = kg.findJoinPath(left.nodeId, right.nodeId, 4);
+            if (!path || path.length < 2)
+                continue;
+            const key = path.join('>');
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            hints.push(path.map((nodeId) => formatKgPathNode(kg, nodeId)).join(' -> '));
+        }
+    }
+    return hints;
+}
+function formatKgPathNode(kg, nodeId) {
+    const node = kg.getNode(nodeId);
+    if (!node)
+        return nodeId;
+    return `${node.kind}:${node.name}`;
+}
+/**
+ * Bounded rendering of the persisted conversation snapshot: working state one-liner
+ * (≤300 chars), compacted rolling summary (≤600), and up to 4 recent turns (≤280 each).
+ */
+function renderConversationSnapshot(snapshot) {
+    const parts = [];
+    const state = snapshot.workingState;
+    if (state) {
+        const stateLine = [
+            state.entities.length ? `entities=${state.entities.join(',')}` : '',
+            state.measures.length ? `measures=${state.measures.join(',')}` : '',
+            state.dimensions.length ? `dimensions=${state.dimensions.join(',')}` : '',
+            state.filters.length ? `filters=${state.filters.map((f) => f.value).join(',')}` : '',
+            state.limit ? `limit=${state.limit}` : '',
+            state.timeframe ? `timeframe=${state.timeframe}` : '',
+            snapshot.topicRelation ? `topic=${snapshot.topicRelation}` : '',
+        ].filter(Boolean).join('; ');
+        if (stateLine)
+            parts.push(`Working state: ${stateLine.slice(0, 300)}`);
+    }
+    else if (snapshot.topicRelation) {
+        parts.push(`Working state: topic=${snapshot.topicRelation}`);
+    }
+    if (snapshot.rollingSummary) {
+        parts.push(`Earlier in this conversation (compacted):\n${snapshot.rollingSummary.slice(0, 600)}`);
+    }
+    if (snapshot.recentTurns.length > 0) {
+        const turns = snapshot.recentTurns.slice(-4).map((turn, index) => {
+            return `${index + 1}. ${renderConversationSnapshotTurnLine(turn, 520)}`;
+        });
+        parts.push(`Recent turns:\n${turns.join('\n')}`);
+    }
+    if (snapshot.recalledTurns?.length) {
+        parts.push(`Recalled earlier turns (semantic match):\n${snapshot.recalledTurns.slice(0, 3)
+            .map((turn) => `- ${renderConversationSnapshotTurnLine(turn, 520)}`)
+            .join('\n')}`);
+    }
+    parts.push('Use this only where the question refers to it. On a new topic, answer fresh.');
+    return parts.join('\n\n');
+}
+function renderConversationSnapshotTurnLine(turn, max) {
+    const line = [
+        `Q: ${turn.question}`,
+        turn.answerSummary ? `A: ${turn.answerSummary}` : '',
+        turn.resultColumns?.length ? `cols: ${turn.resultColumns.slice(0, 6).join(', ')}` : '',
+        typeof turn.resultRowCount === 'number' ? `rows: ${turn.resultRowCount}` : '',
+        turn.sourceSql ? `sql: ${compactSqlSnippet(turn.sourceSql, 180)}` : '',
+        turn.dqlArtifact?.name ? `dql: ${turn.dqlArtifact.name}` : '',
+        turn.sourceCertifiedBlock ? `block: ${turn.sourceCertifiedBlock}` : '',
+    ].filter(Boolean).join(' | ');
+    return line.slice(0, max);
+}
+function renderContextPackForPrompt(contextPack, budget) {
     const questionPlan = contextPack.questionPlan
         ? [
             `Question plan: ${contextPack.questionPlan.mode} -> ${contextPack.questionPlan.routeIntent}`,
@@ -852,10 +1564,13 @@ function renderContextPackForPrompt(contextPack) {
     const certifiedApplicability = contextPack.routeDecision?.certifiedApplicability
         ? `\nCertified applicability: ${contextPack.routeDecision.certifiedApplicability.name} is ${contextPack.routeDecision.certifiedApplicability.kind} (${contextPack.routeDecision.certifiedApplicability.reasons.join('; ')})`
         : '';
+    const blockFit = contextPack.routeDecision?.blockFit
+        ? `\nCertified block fit: ${contextPack.routeDecision.blockFit.kind} / ${contextPack.routeDecision.blockFit.confidence} (${contextPack.routeDecision.blockFit.reasons.join('; ')})`
+        : '';
     const warnings = contextPack.warnings.length
-        ? `Warnings:\n${contextPack.warnings.slice(0, 8).map((warning) => `- ${warning}`).join('\n')}\n`
+        ? `Warnings:\n${contextPack.warnings.slice(0, budget.warningLimit).map((warning) => `- ${warning}`).join('\n')}\n`
         : '';
-    const objects = contextPack.objects.slice(0, 18).map((object) => {
+    const objects = contextPack.objects.slice(0, budget.contextObjectLimit).map((object) => {
         const detail = [
             object.objectType,
             object.domain ? `domain: ${object.domain}` : '',
@@ -868,38 +1583,43 @@ function renderContextPackForPrompt(contextPack) {
         ? `\nCandidate conflicts:\n${contextPack.retrievalDiagnostics.candidateConflicts.slice(0, 4).map((conflict) => `- ${conflict.reason} ${conflict.prompt}`).join('\n')}`
         : '';
     const route = contextPack.routeDecision
-        ? `\nRoute decision: ${contextPack.routeDecision.route} / ${contextPack.routeDecision.intent}\nReason: ${contextPack.routeDecision.reason}${certifiedApplicability}\nMissing context: ${contextPack.routeDecision.missingContext.map((item) => item.message).join(' ') || 'none'}`
+        ? `\nRoute decision: ${contextPack.routeDecision.route} / ${contextPack.routeDecision.intent}\nReason: ${contextPack.routeDecision.reason}${certifiedApplicability}${blockFit}\nMissing context: ${contextPack.routeDecision.missingContext.map((item) => item.message).join(' ') || 'none'}`
         : '';
-    const allowed = renderAllowedSqlRelationsForPrompt(contextPack);
-    const joins = renderCandidateJoinsForPrompt(contextPack);
+    const allowed = renderAllowedSqlRelationsForPrompt(contextPack, budget);
+    const joins = renderCandidateJoinsForPrompt(contextPack, budget);
+    const lineage = renderColumnLineageForPrompt(contextPack, budget);
+    const edges = renderContextEdgesForPrompt(contextPack, budget);
     const relationDiagnostics = contextPack.retrievalDiagnostics?.selectedRelations?.length
-        ? `\nSelected relation reasoning:\n${contextPack.retrievalDiagnostics.selectedRelations.slice(0, 8).map((relation) => `- ${relation.relation} (score ${relation.score.toFixed(1)}): ${relation.reason}`).join('\n')}`
+        ? `\nSelected relation reasoning:\n${contextPack.retrievalDiagnostics.selectedRelations.slice(0, budget.selectedRelationReasonLimit).map((relation) => `- ${relation.relation} (score ${relation.score.toFixed(1)}): ${relation.reason}`).join('\n')}`
         : '';
-    const sourceSql = renderSourceBlockSqlContext(contextPack);
+    const sourceSql = renderSourceBlockSqlContext(contextPack, budget);
     return [
         `context_pack_id: ${contextPack.id}`,
         `trust_label: ${contextPack.trustLabel}`,
+        contextPack.trustLabelInfo ? `trust_label_canonical: ${contextPack.trustLabelInfo.display}` : '',
         questionPlan.trim(),
         route.trim(),
         warnings.trim(),
         `Selected evidence:\n${objects || '- none'}`,
         allowed.trim(),
         joins.trim(),
+        edges.trim(),
+        lineage.trim(),
         relationDiagnostics.trim(),
         sourceSql.trim(),
         conflicts.trim(),
     ].filter(Boolean).join('\n');
 }
-function renderCandidateJoinsForPrompt(contextPack) {
+function renderCandidateJoinsForPrompt(contextPack, budget) {
     const joins = contextPack.retrievalDiagnostics.selectedJoinPaths?.length
-        ? contextPack.retrievalDiagnostics.selectedJoinPaths.slice(0, 8).map((join) => ({
+        ? contextPack.retrievalDiagnostics.selectedJoinPaths.slice(0, budget.joinPathLimit).map((join) => ({
             leftRelation: join.leftRelation,
             leftColumn: join.leftColumn,
             rightRelation: join.rightRelation,
             rightColumn: join.rightColumn,
             reason: join.reason,
         }))
-        : buildCandidateJoinPaths(schemaContextWithAllowedSqlContext([], contextPack)).slice(0, 8);
+        : buildCandidateJoinPaths(schemaContextWithAllowedSqlContext([], contextPack)).slice(0, budget.joinPathLimit);
     if (joins.length === 0)
         return '';
     return [
@@ -907,18 +1627,59 @@ function renderCandidateJoinsForPrompt(contextPack) {
         ...joins.map((join) => `- ${join.leftRelation}.${join.leftColumn} -> ${join.rightRelation}.${join.rightColumn}${join.reason ? ` (${join.reason})` : ''}`),
     ].join('\n');
 }
-function renderAllowedSqlRelationsForPrompt(contextPack) {
+function renderContextEdgesForPrompt(contextPack, budget) {
+    if (budget.edgeLimit <= 0)
+        return '';
+    const edges = contextPack.edges.slice(0, budget.edgeLimit);
+    if (edges.length === 0)
+        return '';
+    return [
+        'Context graph edges:',
+        'Use these object relationships as metadata evidence; SQL still must use inspected relation columns and join keys.',
+        ...edges.map((edge) => {
+            const confidence = typeof edge.confidence === 'number' ? ` (confidence ${edge.confidence.toFixed(2)})` : '';
+            return `- ${edge.edgeType}: ${edge.fromKey} -> ${edge.toKey}${confidence}`;
+        }),
+    ].join('\n');
+}
+function renderColumnLineageForPrompt(contextPack, budget) {
+    const lineageEdges = contextPack.edges
+        .filter((edge) => edge.edgeType === 'derives_from')
+        .slice(0, budget.lineageEdgeLimit);
+    if (lineageEdges.length === 0)
+        return '';
+    const objectsByKey = new Map(contextPack.objects.map((object) => [object.objectKey, object]));
+    return [
+        'Column lineage from governed metadata:',
+        'Use this when adapting certified blocks or dbt models into a DQL artifact SQL preview so derived output columns map back to their physical source columns.',
+        ...lineageEdges.map((edge) => {
+            const from = objectsByKey.get(edge.fromKey);
+            const to = objectsByKey.get(edge.toKey);
+            const aggregateFn = typeof edge.payload?.aggregateFn === 'string' && edge.payload.aggregateFn.trim()
+                ? ` via ${edge.payload.aggregateFn.trim().toUpperCase()}`
+                : '';
+            const confidence = typeof edge.confidence === 'number' ? `, confidence ${edge.confidence.toFixed(2)}` : '';
+            return `- ${formatLineageObjectForPrompt(from, edge.fromKey)} derives from ${formatLineageObjectForPrompt(to, edge.toKey)}${aggregateFn}${confidence}`;
+        }),
+    ].join('\n');
+}
+function formatLineageObjectForPrompt(object, fallbackKey) {
+    if (!object)
+        return fallbackKey;
+    return object.fullName ?? object.name ?? object.objectKey;
+}
+function renderAllowedSqlRelationsForPrompt(contextPack, budget) {
     const relations = contextPack.allowedSqlContext?.relations ?? [];
     if (relations.length === 0)
         return '';
     const selectedLookup = selectedRelationLookup(contextPack);
-    const cards = relations.slice(0, 12).map((relation, index) => {
+    const cards = relations.slice(0, budget.relationCardLimit).map((relation, index) => {
         const selection = relationSelectionFor(relation.relation, selectedLookup);
         const rank = selection?.rank ?? index + 1;
         const score = typeof selection?.score === 'number' ? `, score ${selection.score.toFixed(1)}` : '';
         const reason = selection?.reason ? `\n  why selected: ${selection.reason}` : '';
         const columns = relation.columns.length
-            ? relation.columns.slice(0, 32).map(formatRelationColumnForPrompt).join(', ')
+            ? relation.columns.slice(0, budget.relationColumnLimit).map(formatRelationColumnForPrompt).join(', ')
             : '(columns unavailable; use certified source SQL shape or inspect metadata before inventing columns)';
         return [
             `- [rank ${rank}${score}] ${relation.relation} (${relation.source})`,
@@ -926,11 +1687,37 @@ function renderAllowedSqlRelationsForPrompt(contextPack) {
             `\n  columns: ${columns}`,
         ].join('');
     });
+    const otherRelations = renderOtherAvailableRelationsForPrompt(contextPack, budget);
     return [
         'Selected SQL relation context:',
         'Use these ranked relations and columns as the primary SQL-generation boundary. Prefer lower rank when multiple relations look plausible.',
         ...cards,
-    ].join('\n');
+        otherRelations,
+    ].filter(Boolean).join('\n');
+}
+function renderOtherAvailableRelationsForPrompt(contextPack, budget) {
+    const names = new Map();
+    for (const relation of (contextPack.allowedSqlContext?.relations ?? []).slice(budget.otherRelationStart, budget.otherRelationEnd)) {
+        names.set(normalizePromptRelationName(relation.relation), relation.relation);
+    }
+    for (const item of contextPack.retrievalDiagnostics.topRejected ?? []) {
+        if (!isRelationLikeRejectedObject(item.objectType))
+            continue;
+        names.set(normalizePromptRelationName(item.name), item.name);
+    }
+    const values = [...names.values()].slice(0, budget.otherRelationLimit);
+    if (values.length === 0)
+        return '';
+    return `Other available relations (names only - expand context before using columns): ${values.join(', ')}`;
+}
+function isRelationLikeRejectedObject(objectType) {
+    return objectType === 'dbt_model'
+        || objectType === 'dbt_source'
+        || objectType === 'warehouse_table'
+        || objectType === 'runtime_table';
+}
+function normalizePromptRelationName(name) {
+    return name.toLowerCase().replace(/["`]/g, '').trim();
 }
 function formatRelationColumnForPrompt(column) {
     const type = column.type ? ` ${column.type}` : '';
@@ -940,17 +1727,17 @@ function formatRelationColumnForPrompt(column) {
         : '';
     return `${column.name}${type}${description}${samples}`;
 }
-function renderSourceBlockSqlContext(contextPack) {
+function renderSourceBlockSqlContext(contextPack, budget) {
     const sources = contextPack.allowedSqlContext?.sourceBlockSql ?? [];
     if (sources.length === 0)
         return '';
-    const lines = sources.slice(0, 5).map((source) => {
+    const lines = sources.slice(0, budget.sourceSqlLimit).map((source) => {
         const shape = extractSimpleSelectShape(source.sql);
         const projectedColumns = shape
             ? shape.selectExpressions
                 .map(selectExpressionOutputName)
                 .filter((value) => Boolean(value))
-                .slice(0, 24)
+                .slice(0, budget.sourceSqlColumnLimit)
                 .join(', ')
             : '';
         const snippet = compactSqlSnippet(source.sql, 280);
@@ -966,7 +1753,7 @@ function renderSourceBlockSqlContext(contextPack) {
             snippet ? `  sql: ${snippet}` : '',
         ].filter(Boolean).join('\n');
     });
-    return `## Worked examples from certified blocks (few-shot patterns)\n\nThese certified blocks already answer similar questions. Learn their join paths, grain, and filters and ADAPT them to the question — do not copy blindly, and do not relabel generated SQL as certified.\n${lines.join('\n')}`;
+    return `## Worked examples from certified blocks (few-shot patterns)\n\nThese certified blocks already answer similar questions. Learn their join paths, grain, and filters and ADAPT them to the question — do not copy blindly, and do not relabel a review-required DQL artifact or SQL preview as certified.\n${lines.join('\n')}`;
 }
 function contextPackCitations(contextPack, limit) {
     if (!contextPack)
@@ -992,6 +1779,8 @@ function shouldUseCertifiedRoute(route, intent) {
     return intent === 'exact_certified_lookup' || intent === 'definition_lookup';
 }
 function certifiedHitFromContextPack(contextPack, kg) {
+    if (contextPack?.routeDecision.blockFit && !certifiedFitAllowsTier1(contextPack.routeDecision.blockFit))
+        return null;
     const key = contextPack?.routeDecision.exactObjectKey;
     if (!key)
         return null;
@@ -1040,16 +1829,6 @@ function sourceTierFromContextPack(contextPack) {
         return 'certified_artifact';
     return undefined;
 }
-function isGeneratedAgentIntent(intent) {
-    return intent === 'ad_hoc_analysis'
-        || intent === 'drillthrough'
-        || intent === 'ad_hoc_ranking'
-        || intent === 'driver_breakdown'
-        || intent === 'diagnose_change'
-        || intent === 'segment_compare'
-        || intent === 'entity_drilldown'
-        || intent === 'anomaly_investigation';
-}
 function metadataObjectKindForCitation(objectType) {
     if (objectType === 'dql_block')
         return 'block';
@@ -1092,12 +1871,51 @@ function renderFollowUpContext(followUp) {
         followUp.sourceAnswer ? `source answer: ${followUp.sourceAnswer.slice(0, 700)}` : '',
         followUp.filters?.length ? `requested filters: ${followUp.filters.join(', ')}` : '',
         followUp.dimensions?.length ? `requested dimensions: ${followUp.dimensions.join(', ')}` : '',
+        followUp.priorResultColumns?.length ? `prior result columns: ${followUp.priorResultColumns.join(', ')}` : '',
+        followUp.priorResultValues ? `prior result values: ${formatPriorResultValues(followUp.priorResultValues)}` : '',
+        followUp.priorResultRef ? renderPriorResultReference(followUp.priorResultRef) : '',
+        followUp.priorDqlArtifact ? renderPriorDqlArtifactReference(followUp.priorDqlArtifact) : '',
+        followUp.priorLimit ? `prior result limit: ${followUp.priorLimit}` : '',
     ].filter(Boolean);
     const rule = followUp.kind === 'drilldown'
-        ? 'routing rule: find a distinct certified drilldown block first; if none exists, generate review-required SQL as a draft drilldown. Do not silently re-run the source block unless it explicitly supports the requested filter or dimension.'
-        : 'routing rule: reuse the prior certified block when the user asks a generic follow-up.';
+        ? 'routing rule: find a distinct certified drilldown block first; if none exists, prepare a review-required DQL artifact with a SQL preview as a draft drilldown. Do not silently re-run the source block unless it explicitly supports the requested filter or dimension.'
+        : followUp.kind === 'contextual'
+            ? 'routing rule: this is prior-turn context (advisory). The user may be continuing from it — resolve references like "these"/"those"/"same" against it when the question refers to it. If this question starts a genuinely new topic, ignore the prior-turn context entirely and answer fresh.'
+            : 'routing rule: reuse the prior certified block when the user asks a generic follow-up.';
     return [...parts, rule].join('\n');
 }
+function renderPriorResultReference(ref) {
+    const lines = [
+        `prior result ref: result:${ref.id}`,
+        ref.question ? `prior result question: ${ref.question.slice(0, 220)}` : '',
+        ref.columns.length ? `prior result schema: ${ref.columns.slice(0, 24).join(', ')}` : '',
+        typeof ref.rowCount === 'number' ? `prior result row count: ${ref.rowCount}` : '',
+        ref.sourceSql ? `prior result source SQL: ${compactSqlSnippet(ref.sourceSql, 500)}` : '',
+    ].filter(Boolean);
+    return lines.join('\n');
+}
+function renderPriorDqlArtifactReference(artifact) {
+    const lines = [
+        `prior DQL artifact kind: ${artifact.kind}`,
+        artifact.name ? `prior DQL artifact name: ${artifact.name}` : '',
+        artifact.sourcePath ? `prior DQL artifact path: ${artifact.sourcePath}` : '',
+        artifact.metrics?.length ? `prior DQL metrics: ${artifact.metrics.slice(0, 12).join(', ')}` : '',
+        artifact.dimensions?.length ? `prior DQL dimensions: ${artifact.dimensions.slice(0, 12).join(', ')}` : '',
+        artifact.filters?.length ? `prior DQL filters: ${artifact.filters.slice(0, 8).map(formatDqlArtifactFilter).join('; ')}` : '',
+        artifact.timeDimension ? `prior DQL time: ${artifact.timeDimension.name} / ${artifact.timeDimension.granularity}` : '',
+        artifact.source.trim() ? `prior DQL artifact source:\n${compactSqlSnippet(artifact.source, 1400)}` : '',
+    ].filter(Boolean);
+    return lines.join('\n');
+}
+function formatDqlArtifactFilter(filter) {
+    return `${filter.dimension} ${filter.operator} ${filter.values.slice(0, 8).join(', ')}`;
+}
+function formatPriorResultValues(values) {
+    return Object.entries(values)
+        .slice(0, 8)
+        .map(([key, vals]) => `${key}=[${vals.slice(0, 12).join(', ')}]`)
+        .join('; ');
+}
 function generatedTrustExplanation(input) {
     if (input.followUp?.kind !== 'drilldown')
         return undefined;
@@ -1110,295 +1928,232 @@ function generatedTrustExplanation(input) {
     ];
     const grain = filters.length ? ` at the requested ${filters.join('/')} grain` : ' at the requested drilldown grain';
     const draft = input.draftBlock
-        ? ` The draft was saved at \`${input.draftBlock.path}\` for review.`
-        : ' The generated SQL still needs analyst review before certification.';
-    return `This is an uncertified drilldown.${source} then generated new SQL${grain}.${draft}`;
+        ? ` The DQL draft was saved at \`${input.draftBlock.path}\` for review.`
+        : ' The review-required DQL artifact and SQL preview still need analyst review before certification.';
+    return `This is an uncertified drilldown.${source} then prepared a SQL preview${grain}.${draft}`;
 }
 function cleanGeneratedSummary(text) {
     return text
         .trim()
         .replace(/^(?:the user (?:is asking|asked|wants|requested)[^.]*\.\s*)+/i, '')
         .replace(/\s*(?:therefore,\s*)?i will generate review-required sql[^.]*\.\s*/gi, ' ')
+        .replace(/\s*(?:therefore,\s*)?i will prepare (?:a )?review-required dql artifact[^.]*\.\s*/gi, ' ')
         .replace(/\s*(?:therefore,\s*)?i will generate[^.]*\.\s*/gi, ' ')
         .trim();
 }
 /**
- * Public for tests. Pulls the first ```sql block and an optional Viz: line
- * out of an LLM response.
+ * Public for tests. Prefer the structured W2.7 JSON proposal contract, then
+ * fall back to the legacy prose + ```sql block + Viz line format.
  */
 export function parseProposal(raw) {
+    const structured = parseStructuredProposal(raw);
+    if (structured)
+        return structured;
     const sqlMatch = raw.match(/```sql\s*([\s\S]*?)```/i);
     const sql = sqlMatch ? sqlMatch[1].trim() : undefined;
     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
+        .replace(/```json[\s\S]*?```/gi, '')
         .replace(/```sql[\s\S]*?```/gi, '')
         .replace(/^Viz:.*$/gim, '')
         .trim();
     return { text, sql, viz };
 }
-function buildSchemaAwareProposal(input) {
-    if (!isGeneratedAgentIntent(input.intent))
-        return undefined;
-    const schemaContext = schemaContextWithAllowedSqlContext(input.schemaContext, input.contextPack);
-    const drilldownProposal = buildMatchedEntityDrilldownProposal({ ...input, schemaContext });
-    if (drilldownProposal)
-        return drilldownProposal;
-    const profileProposal = buildEntityProfileProposal({ ...input, schemaContext });
-    if (profileProposal)
-        return profileProposal;
-    if (isFilteredEntityQuestion(input.question))
-        return undefined;
-    const lower = input.question.toLowerCase();
-    const asksForCustomerPerformance = /\bcustomers?\b/.test(lower)
-        && /\border|orders|spend|revenue|perform|performed|better|top|best|rank|ranking|bottom|least|fewest|lowest|less|worst|underperform/.test(lower)
-        && !/\b(order details|specific orders|each order|all orders|order line|line item)\b/.test(lower);
-    if (asksForCustomerPerformance) {
-        const direction = customerRankingDirectionFromText(input.question);
-        const orderDirection = direction === 'bottom' ? 'ASC' : 'DESC';
-        const orderFocused = /\border|orders|order count|ordered\b/.test(lower)
-            && !/\b(spend|revenue|sales|amount|lifetime spend|value)\b/.test(lower);
-        const customers = findSchemaTable(schemaContext, ['customers', 'customer']);
-        if (customers) {
-            const customerName = findSchemaColumn(customers, ['customer_name', 'name', 'full_name']);
-            const orderCount = findSchemaColumn(customers, ['count_lifetime_orders', 'lifetime_orders', 'order_count', 'orders_count', 'orders']);
-            const spend = findSchemaColumn(customers, ['lifetime_spend', 'total_lifetime_spend', 'customer_lifetime_value', 'total_revenue', 'revenue']);
-            if (customerName && orderCount && spend) {
-                const primarySort = orderFocused ? orderCount : spend;
-                const secondarySort = orderFocused ? spend : orderCount;
-                const rankingLabel = direction === 'bottom'
-                    ? orderFocused ? 'Customers with the fewest orders' : 'Lowest performing customers'
-                    : orderFocused ? 'Top customers by order count' : 'Top performing customers';
-                return {
-                    text: `${rankingLabel}, with ${businessMeasurePhrase(orderCount)} and ${businessMeasurePhrase(spend)} for context. This is AI-generated and needs analyst review before certification.`,
-                    sql: [
-                        'SELECT',
-                        `  ${sqlIdentifier(customerName)} AS customer_name,`,
-                        `  ${sqlIdentifier(orderCount)} AS orders,`,
-                        `  ROUND(${sqlIdentifier(spend)}, 2) AS lifetime_spend`,
-                        `FROM ${sqlRelation(customers.relation)}`,
-                        `ORDER BY ${sqlIdentifier(primarySort)} ${orderDirection}, ${sqlIdentifier(secondarySort)} ${orderDirection}`,
-                        'LIMIT 10',
-                    ].join('\n'),
-                    viz: 'table',
-                };
-            }
-            const customerId = findSchemaColumn(customers, ['customer_id', 'id']);
-            const orders = findSchemaTable(schemaContext, ['orders', 'order']);
-            const orderCustomerId = orders ? findSchemaColumn(orders, ['customer_id', 'customer']) : undefined;
-            const orderTotal = orders ? findSchemaColumn(orders, ['order_total', 'total_order_amount', 'total_amount', 'amount', 'subtotal']) : undefined;
-            const orderId = orders ? findSchemaColumn(orders, ['order_id', 'id']) : undefined;
-            if (orders && customerName && customerId && orderCustomerId && orderTotal) {
-                const countExpression = orderId ? `COUNT(DISTINCT o.${sqlIdentifier(orderId)})` : 'COUNT(*)';
-                const primarySort = orderFocused ? 'orders' : 'lifetime_spend';
-                const secondarySort = orderFocused ? 'lifetime_spend' : 'orders';
-                const rankingLabel = direction === 'bottom'
-                    ? orderFocused ? 'Customers with the fewest orders' : 'Lowest performing customers'
-                    : orderFocused ? 'Top customers by order count' : 'Top performing customers';
-                return {
-                    text: `${rankingLabel} from order totals, with order count for context. This is AI-generated and needs analyst review before certification.`,
-                    sql: [
-                        'SELECT',
-                        `  c.${sqlIdentifier(customerName)} AS customer_name,`,
-                        `  ${countExpression} AS orders,`,
-                        `  ROUND(SUM(o.${sqlIdentifier(orderTotal)}), 2) AS lifetime_spend`,
-                        `FROM ${sqlRelation(orders.relation)} AS o`,
-                        `JOIN ${sqlRelation(customers.relation)} AS c ON o.${sqlIdentifier(orderCustomerId)} = c.${sqlIdentifier(customerId)}`,
-                        `GROUP BY c.${sqlIdentifier(customerName)}`,
-                        `ORDER BY ${sqlIdentifier(primarySort)} ${orderDirection}, ${sqlIdentifier(secondarySort)} ${orderDirection}`,
-                        'LIMIT 10',
-                    ].join('\n'),
-                    viz: 'table',
-                };
-            }
+function parseStructuredProposal(raw) {
+    const trimmed = raw.trim();
+    const fenced = raw.match(/```json\s*([\s\S]*?)```/i)?.[1]?.trim();
+    const candidates = [
+        fenced,
+        trimmed.startsWith('{') && trimmed.endsWith('}') ? trimmed : undefined,
+    ].filter((candidate) => Boolean(candidate));
+    for (const candidate of candidates) {
+        try {
+            const parsed = JSON.parse(candidate);
+            const proposal = parsedProposalFromJson(parsed);
+            if (proposal)
+                return proposal;
+        }
+        catch {
+            // Invalid structured output falls through to the legacy SQL-fence parser.
         }
     }
-    const genericJoinProposal = buildGenericJoinProposal({ ...input, schemaContext });
-    if (genericJoinProposal)
-        return genericJoinProposal;
-    const genericProposal = buildGenericSingleTableProposal({ ...input, schemaContext });
-    if (genericProposal)
-        return genericProposal;
     return undefined;
 }
-function customerRankingDirectionFromText(text) {
-    const lower = text.toLowerCase();
-    if (/\b(less|lesser)\s+(?:order|orders|ordering)\b/.test(lower) || /\borders?\s+(?:less|least|fewest|lowest)\b/.test(lower)) {
-        return 'bottom';
-    }
-    return rankingDirectionFromText(text) ?? 'top';
-}
-function buildGenericJoinProposal(input) {
-    const planMode = input.contextPack?.questionPlan?.mode;
-    if (planMode === 'entity_profile' || planMode === 'diagnose_change' || planMode === 'anomaly' || planMode === 'trust_review') {
+function parsedProposalFromJson(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
         return undefined;
-    }
-    const lower = input.question.toLowerCase();
-    if (/\b(why|root cause|diagnos|changed?|drop|decline|increase|decrease|repair|fix|bad|details?|detail rows?|line items?|raw rows?)\b/i.test(lower)) {
-        return undefined;
-    }
-    if (!/\b(by\s+[a-z]|per\s+[a-z]|for each|group(?:ed)? by|split|segment|break\s*down|breakdown|compare)\b/i.test(lower)) {
+    const record = value;
+    const sql = firstJsonString(record.sql, record.query)?.trim();
+    const text = firstJsonString(record.summary, record.text, record.answer, record.description)?.trim() ?? '';
+    const viz = firstJsonString(record.viz, record.visualization, record.chartType)
+        ?.trim()
+        .toLowerCase()
+        .replace(/[^a-z_]/g, '');
+    const dql = jsonRecord(record.dql);
+    const outputs = firstJsonStringList(record.outputs, dql?.outputs);
+    const proposedEntity = firstJsonString(dql?.entity, dql?.proposedEntity, dql?.proposed_entity, record.proposedEntity, record.proposed_entity, record.entity)?.replace(/\s+/g, ' ').trim().slice(0, 160);
+    const requestedFilters = firstJsonStringList(dql?.filters, dql?.requestedFilters, dql?.requested_filters, record.requestedFilters, record.requested_filters, record.filters);
+    const requestedDimensions = firstJsonStringList(dql?.dimensions, dql?.requestedDimensions, dql?.requested_dimensions, record.requestedDimensions, record.requested_dimensions, record.dimensions);
+    if (!sql && !text)
         return undefined;
-    }
-    const candidate = pickGenericJoinCandidate(input.schemaContext, input.question);
-    if (!candidate)
-        return undefined;
-    const direction = rankingDirectionFromText(input.question);
-    const orderDirection = direction === 'bottom' ? 'ASC' : 'DESC';
-    const limit = /\b(all|complete|full)\b/i.test(input.question) ? 50 : 10;
-    const chart = isTimeLikeGenericColumn(candidate.dimensionColumn) ? 'line' : 'bar';
-    const metricExpression = qualifiedMetricExpression(candidate.metric, 'f');
-    const metricAlias = candidate.metric.alias;
-    const dimensionAlias = candidate.dimensionColumn;
     return {
-        text: `Prepared a review-required ${businessMeasurePhrase(candidate.metric.column)} breakdown by ${humanizeIdentifier(candidate.dimensionColumn)} by joining ${candidate.metricTable.relation} to ${candidate.dimensionTable.relation}. This result is uncertified until reviewed and promoted.`,
-        sql: [
-            'SELECT',
-            `  d.${sqlIdentifier(candidate.dimensionColumn)} AS ${sqlIdentifier(dimensionAlias)},`,
-            `  ${metricExpression} AS ${sqlIdentifier(metricAlias)}`,
-            `FROM ${sqlRelation(candidate.metricTable.relation)} AS f`,
-            `JOIN ${sqlRelation(candidate.dimensionTable.relation)} AS d ON f.${sqlIdentifier(candidate.metricJoinColumn)} = d.${sqlIdentifier(candidate.dimensionJoinColumn)}`,
-            `GROUP BY d.${sqlIdentifier(candidate.dimensionColumn)}`,
-            `ORDER BY ${sqlIdentifier(metricAlias)} ${orderDirection}`,
-            `LIMIT ${limit}`,
-        ].join('\n'),
-        viz: chart,
+        text,
+        ...(sql ? { sql } : {}),
+        ...(viz ? { viz } : {}),
+        ...(outputs?.length ? { outputs } : {}),
+        ...(proposedEntity ? { proposedEntity } : {}),
+        ...(requestedFilters?.length ? { requestedFilters } : {}),
+        ...(requestedDimensions?.length ? { requestedDimensions } : {}),
     };
 }
-function buildGenericSingleTableProposal(input) {
-    const planMode = input.contextPack?.questionPlan?.mode;
-    if (planMode === 'entity_profile' || planMode === 'diagnose_change' || planMode === 'anomaly' || planMode === 'trust_review') {
-        return undefined;
-    }
-    const lower = input.question.toLowerCase();
-    if (/\b(why|root cause|diagnos|changed?|drop|decline|increase|decrease|repair|fix|bad|details?|detail rows?|line items?|raw rows?)\b/i.test(lower)) {
-        return undefined;
+function firstJsonString(...values) {
+    return values.find((value) => typeof value === 'string' && value.trim().length > 0);
+}
+function jsonRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function firstJsonStringList(...values) {
+    for (const value of values) {
+        const list = normalizeProposalStringList(value);
+        if (list.length > 0)
+            return list;
     }
-    if (!/\b(show|list|top|bottom|best|worst|highest|lowest|least|fewest|rank|ranking|compare|trend|by\s+[a-z]|how many|number of|revenue|sales|orders?|points?|score|count|total|average|avg|sum)\b/i.test(lower)) {
-        return undefined;
+    return undefined;
+}
+function normalizeProposalStringList(value) {
+    const rawValues = Array.isArray(value)
+        ? value
+        : typeof value === 'string'
+            ? [value]
+            : [];
+    const seen = new Set();
+    const out = [];
+    for (const raw of rawValues) {
+        if (typeof raw !== 'string')
+            continue;
+        const cleaned = raw.replace(/\s+/g, ' ').trim().slice(0, 160);
+        if (!cleaned)
+            continue;
+        const key = cleaned.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(cleaned);
+        if (out.length >= 20)
+            break;
     }
-    const table = pickGenericAnalysisTable(input.schemaContext, input.question);
-    if (!table)
-        return undefined;
-    const metric = inferGenericMetric(table, input.question);
-    if (!metric)
+    return out;
+}
+function mergeProposalStringLists(...lists) {
+    const merged = normalizeProposalStringList(lists.flatMap((list) => list ?? []));
+    return merged.length > 0 ? merged : undefined;
+}
+function applyParsedProposalMetadata(target, source) {
+    target.outputs = source.outputs ?? target.outputs;
+    target.proposedEntity = source.proposedEntity ?? target.proposedEntity;
+    target.requestedFilters = source.requestedFilters ?? target.requestedFilters;
+    target.requestedDimensions = source.requestedDimensions ?? target.requestedDimensions;
+}
+function buildCertifiedBlockDqlArtifact(block, result) {
+    if (block.kind !== 'block')
         return undefined;
-    const dimensions = augmentGenericRankingDimensions(table, inferGenericDimensions(table, input.question, metric.column), metric, input.question).slice(0, 2);
-    const direction = rankingDirectionFromText(input.question);
-    const limit = /\b(all|complete|full)\b/i.test(input.question) ? 50 : 10;
-    const metricAlias = metric.alias;
-    if (dimensions.length === 0) {
-        return {
-            text: `Prepared a review-required ${businessMeasurePhrase(metric.column)} summary from ${table.relation}. This result is uncertified until reviewed and promoted.`,
-            sql: [
-                'SELECT',
-                `  ${metric.expression} AS ${sqlIdentifier(metricAlias)}`,
-                `FROM ${sqlRelation(table.relation)}`,
-            ].join('\n'),
-            viz: 'single_value',
-        };
-    }
-    if (direction && metric.preAggregated) {
+    const sql = block.sql?.trim() ?? result?.sql?.trim() ?? block.examples?.find((example) => example.sql?.trim())?.sql?.trim();
+    if (!sql) {
+        // The block answered but its SQL was not inlined in the index (navigation /
+        // reference artifacts). Still hand back a reference artifact pointing at the
+        // governed source file so every certified-block answer carries a DQL artifact
+        // the UI can open or save, rather than dropping it silently.
+        if (!block.name)
+            return undefined;
         return {
-            text: `Prepared a review-required ${businessMeasurePhrase(metric.column)} ranking by ${dimensions.map(humanizeIdentifier).join(' and ')} from ${table.relation}. This result is uncertified until reviewed and promoted.`,
-            sql: [
-                'SELECT',
-                ...dimensions.map((dimension) => `  ${sqlIdentifier(dimension)} AS ${sqlIdentifier(dimension)},`),
-                `  ${sqlIdentifier(metric.column)} AS ${sqlIdentifier(metric.column)}`,
-                `FROM ${sqlRelation(table.relation)}`,
-                `ORDER BY ${sqlIdentifier(metric.column)} ${direction === 'bottom' ? 'ASC' : 'DESC'}`,
-                `LIMIT ${limit}`,
-            ].join('\n'),
-            viz: 'table',
+            kind: 'certified_block',
+            name: block.name,
+            sourcePath: block.sourcePath,
+            source: `// Certified DQL block "${escapeDqlArtifactString(block.name)}"`
+                + `${block.sourcePath ? `\n// source: ${block.sourcePath}` : ''}`
+                + `\n// SQL is not inlined in the index — open the source file to view or edit the query.`,
         };
     }
-    const selectDimensions = dimensions.map((dimension) => `  ${sqlIdentifier(dimension)} AS ${sqlIdentifier(dimension)},`);
-    const groupBy = dimensions.map(sqlIdentifier).join(', ');
-    const orderDirection = direction === 'bottom' ? 'ASC' : 'DESC';
-    const chart = dimensions.some(isTimeLikeGenericColumn) ? 'line' : 'bar';
+    const domain = block.domain ?? 'misc';
+    const description = block.description ?? `Certified DQL block ${block.name}`;
+    const sourcePathComment = block.sourcePath ? `\n    // source: ${block.sourcePath}` : '';
+    const source = `block "${escapeDqlArtifactString(block.name)}" {
+    domain = "${escapeDqlArtifactString(domain)}"
+    type = "custom"
+    status = "certified"${block.owner ? `\n    owner = "${escapeDqlArtifactString(block.owner)}"` : ''}
+    description = """${escapeDqlArtifactTripleString(description)}"""${sourcePathComment}
+
+    query = """
+        ${sql.replace(/"""/g, '\\"\\"\\"').split('\n').join('\n        ')}
+    """
+}
+`;
     return {
-        text: `Prepared a review-required ${businessMeasurePhrase(metric.column)} breakdown by ${dimensions.map(humanizeIdentifier).join(' and ')} from ${table.relation}. This result is uncertified until reviewed and promoted.`,
-        sql: [
-            'SELECT',
-            ...selectDimensions,
-            `  ${metric.expression} AS ${sqlIdentifier(metricAlias)}`,
-            `FROM ${sqlRelation(table.relation)}`,
-            `GROUP BY ${groupBy}`,
-            `ORDER BY ${sqlIdentifier(metricAlias)} ${orderDirection}`,
-            `LIMIT ${limit}`,
-        ].join('\n'),
-        viz: chart,
+        kind: 'certified_block',
+        name: block.name,
+        sourcePath: block.sourcePath,
+        source,
     };
 }
-function pickGenericAnalysisTable(schemaContext, question) {
-    return schemaContext
-        .filter((table) => table.columns.length > 0)
-        .map((table, index) => ({
-        table,
-        metric: inferGenericMetric(table, question),
-        dimensions: inferGenericDimensions(table, question),
-        index,
-    }))
-        .filter((candidate) => candidate.metric)
-        .sort((a, b) => genericTableScore(b.table, question, b.metric, b.dimensions) -
-        genericTableScore(a.table, question, a.metric, a.dimensions) ||
-        a.index - b.index)[0]?.table;
-}
-function genericTableScore(table, question, metric, dimensions) {
-    const questionTokens = meaningfulTokens(question);
-    const tableTokens = meaningfulTokens([table.relation, table.name, table.description ?? ''].join(' '));
-    const columnTokens = meaningfulTokens(table.columns.map((column) => column.name).join(' '));
-    const overlap = [...questionTokens].filter((token) => tableTokens.has(token) || columnTokens.has(token)).length;
-    const selectedRelationBoost = table.selectionRank
-        ? Math.max(0, 56 - table.selectionRank * 3) + Math.min(table.selectionScore ?? 0, 24)
-        : 0;
-    return selectedRelationBoost + overlap * 8 + (metric?.score ?? 0) + dimensions.length * 8 + Math.min(table.columns.length, 20) * 0.3;
-}
-function pickGenericJoinCandidate(schemaContext, question) {
-    const requestedDimensions = requestedDimensionPhrases(question);
-    if (requestedDimensions.length === 0)
+function buildGeneratedSqlDqlArtifact(input) {
+    const sql = input.sql?.trim();
+    if (!sql)
         return undefined;
-    const metricCandidates = schemaContext
-        .filter((table) => table.columns.length > 0)
-        .map((table, index) => ({
-        table,
-        metric: inferGenericMetric(table, question),
-        localDimensions: inferGenericDimensions(table, question),
-        index,
-    }))
-        .filter((candidate) => Boolean(candidate.metric))
-        .filter((candidate) => !candidate.localDimensions.some((dimension) => !isJoinKeyColumn(dimension) && requestedDimensionMatchesColumn(requestedDimensions, dimension)));
-    const candidates = [];
-    for (const metricCandidate of metricCandidates) {
-        for (const dimensionTable of schemaContext) {
-            if (normalizeRelationKey(dimensionTable.relation) === normalizeRelationKey(metricCandidate.table.relation))
-                continue;
-            const dimensionColumn = pickRequestedDimensionColumn(dimensionTable, question, requestedDimensions);
-            if (!dimensionColumn || namesEqualLoose(dimensionColumn, metricCandidate.metric.column))
-                continue;
-            const join = pickJoinColumns(metricCandidate.table, dimensionTable);
-            if (!join)
-                continue;
-            const dimensionScore = genericDimensionScore({ name: dimensionColumn, type: findColumnType(dimensionTable, dimensionColumn) }, question, Math.max(0, dimensionTable.columns.findIndex((column) => namesEqualLoose(column.name, dimensionColumn))), metricCandidate.metric.column);
-            candidates.push({
-                metricTable: metricCandidate.table,
-                dimensionTable,
-                metric: metricCandidate.metric,
-                dimensionColumn,
-                metricJoinColumn: join.leftColumn,
-                dimensionJoinColumn: join.rightColumn,
-                score: genericTableScore(metricCandidate.table, question, metricCandidate.metric, metricCandidate.localDimensions) +
-                    dimensionScore +
-                    join.score +
-                    selectedRelationWeight(dimensionTable),
-            });
-        }
-    }
-    return candidates
-        .sort((a, b) => b.score - a.score ||
-        (a.metricTable.selectionRank ?? Number.MAX_SAFE_INTEGER) - (b.metricTable.selectionRank ?? Number.MAX_SAFE_INTEGER) ||
-        a.metricTable.relation.localeCompare(b.metricTable.relation))[0];
+    const slug = deriveGeneratedDraftSlug(input.question);
+    const proposedDomain = input.sourceBlock?.domain
+        ?? input.contextPack?.objects.find((object) => object.domain)?.domain
+        ?? input.domain
+        ?? 'misc';
+    return {
+        kind: 'sql_block',
+        name: slug,
+        source: renderGeneratedSqlDqlArtifact({
+            slug,
+            question: input.question,
+            proposedSql: sql,
+            proposedContractId: `${proposedDomain}.Unknown.${slug}`,
+            proposedDomain,
+            sourceQuestion: input.followUp?.sourceQuestion,
+            sourceBlock: input.followUp?.sourceBlockName ?? input.sourceBlock?.name,
+            sourceDqlArtifact: input.sourceDqlArtifact,
+            followupKind: input.followUp?.kind,
+            proposedEntity: input.proposedEntity,
+            requestedFilters: input.requestedFilters,
+            requestedDimensions: input.requestedDimensions,
+            outputs: input.outputs,
+            contextPackId: input.contextPack?.id,
+            routeIntent: String(input.intent),
+            validationWarnings: input.validationWarnings,
+        }),
+    };
+}
+function escapeDqlArtifactString(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+function escapeDqlArtifactTripleString(value) {
+    return value.replace(/"""/g, '\\"\\"\\"');
+}
+/**
+ * Generic partial-shape signal: the SQL executed but dropped MULTIPLE explicitly
+ * requested output columns. Domain-agnostic — this downgrades trust and attaches a
+ * "partial answer, missing <cols>" warning (and biases deep-candidate selection
+ * toward the complete-shape candidate) for ANY project, not just product/customer/
+ * revenue. It never refuses; the executed rows are always returned.
+ */
+function generatedResultShapeIsPartial(resultShape) {
+    return resultShape.missingOutputs.length >= 2;
+}
+function trustedFollowUpFilterValues(followUp) {
+    const filters = new Set((followUp?.filters ?? []).map((value) => value.trim()).filter(Boolean));
+    if (!filters.size || !followUp?.priorResultValues)
+        return undefined;
+    const priorValues = Object.values(followUp.priorResultValues).flat().map((value) => value.trim()).filter(Boolean);
+    const trusted = priorValues.filter((value) => filters.has(value));
+    return trusted.length > 0 ? uniqueDrilldownStrings(trusted) : undefined;
 }
 function buildCandidateJoinPaths(schemaContext) {
     const tables = [...schemaContext]
@@ -1446,542 +2201,63 @@ function joinReason(leftColumn, rightColumn, score) {
         return 'foreign-key style id match';
     return 'join-key style column match';
 }
-function requestedDimensionPhrases(question) {
-    const lower = question.toLowerCase();
-    const phrases = [
-        ...Array.from(lower.matchAll(/\bby\s+([a-z][a-z0-9_ -]{1,50})/g)).map((match) => match[1] ?? ''),
-        ...Array.from(lower.matchAll(/\bper\s+([a-z][a-z0-9_ -]{1,50})/g)).map((match) => match[1] ?? ''),
-        ...Array.from(lower.matchAll(/\bfor each\s+([a-z][a-z0-9_ -]{1,50})/g)).map((match) => match[1] ?? ''),
-    ];
-    return uniqueDrilldownStrings(phrases
-        .flatMap((phrase) => phrase.split(/\band\b|,|\//i))
-        .map((phrase) => phrase
-        .replace(/\b(desc|asc|top|bottom|highest|lowest|least|most|over time|where|for|with|from|in|during|last|this|next)\b.*$/gi, '')
-        .replace(/[^a-z0-9_ -]+/gi, ' ')
-        .replace(/\s+/g, ' ')
-        .trim())
-        .filter((phrase) => phrase.length > 0));
-}
-function pickRequestedDimensionColumn(table, question, requestedDimensions) {
-    for (const phrase of requestedDimensions) {
-        const direct = findSchemaColumn(table, dimensionColumnCandidatesForPhrase(phrase));
-        if (direct && !isJoinKeyColumn(direct) && !isNumericLikeColumn({ name: direct, type: findColumnType(table, direct) })) {
-            return direct;
-        }
-    }
-    const inferred = inferGenericDimensions(table, question)
-        .find((dimension) => !isJoinKeyColumn(dimension) && requestedDimensionMatchesColumn(requestedDimensions, dimension));
-    return inferred;
-}
-function dimensionColumnCandidatesForPhrase(phrase) {
-    const tokens = (phrase.toLowerCase().match(/[a-z0-9_]+/g) ?? [])
-        .flatMap((token) => token.split('_'))
-        .map(normalizeToken)
-        .filter((token) => token.length > 0);
-    if (tokens.length === 0)
-        return [];
-    const joined = tokens.join('_');
-    const tail = tokens.slice(1).join('_');
-    return uniqueDrilldownStrings([
-        joined,
-        phrase.replace(/\s+/g, '_').toLowerCase(),
-        tail,
-        tokens.at(-1) ?? '',
-        ...tokens,
-    ].filter(Boolean));
-}
-function requestedDimensionMatchesColumn(requestedDimensions, column) {
-    const columnTokens = exactMatchTokens(column);
-    return requestedDimensions.some((phrase) => {
-        const phraseTokens = (phrase.toLowerCase().match(/[a-z0-9_]+/g) ?? [])
-            .flatMap((token) => token.split('_'))
-            .map(normalizeToken)
-            .filter((token) => token.length > 0);
-        return phraseTokens.some((token) => columnTokens.has(token));
-    });
-}
-function selectedRelationWeight(table) {
-    return table.selectionRank
-        ? Math.max(0, 30 - table.selectionRank * 2) + Math.min(table.selectionScore ?? 0, 16)
-        : 0;
-}
 function pickJoinColumns(left, right) {
     const candidates = [];
     const leftColumns = left.columns.filter((column) => isJoinKeyColumn(column.name)).slice(0, 32);
     const rightColumns = right.columns.filter((column) => isJoinKeyColumn(column.name)).slice(0, 32);
     for (const leftColumn of leftColumns) {
         for (const rightColumn of rightColumns) {
-            const score = joinColumnScore(leftColumn.name, rightColumn.name, left, right);
-            if (score <= 0)
-                continue;
-            candidates.push({ leftColumn: leftColumn.name, rightColumn: rightColumn.name, score });
-        }
-    }
-    return candidates.sort((a, b) => b.score - a.score || a.leftColumn.localeCompare(b.leftColumn))[0];
-}
-function joinColumnScore(leftColumn, rightColumn, leftTable, rightTable) {
-    const leftKey = normalizeRelationKey(leftColumn).replace(/\./g, '_');
-    const rightKey = normalizeRelationKey(rightColumn).replace(/\./g, '_');
-    const leftJoinLike = isJoinKeyColumn(leftColumn);
-    const rightJoinLike = isJoinKeyColumn(rightColumn);
-    if (!leftJoinLike || !rightJoinLike)
-        return 0;
-    if (leftKey === rightKey)
-        return 70;
-    const leftSubject = joinSubjectForColumn(leftColumn);
-    const rightSubject = joinSubjectForColumn(rightColumn);
-    if (leftSubject && rightSubject && leftSubject === rightSubject)
-        return 62;
-    const leftTableTokens = tableEntityTokens(leftTable);
-    const rightTableTokens = tableEntityTokens(rightTable);
-    if (leftSubject && rightKey === 'id' && rightTableTokens.has(leftSubject))
-        return 58;
-    if (rightSubject && leftKey === 'id' && leftTableTokens.has(rightSubject))
-        return 58;
-    if (leftSubject && rightTableTokens.has(leftSubject) && rightKey.endsWith('_key'))
-        return 42;
-    if (rightSubject && leftTableTokens.has(rightSubject) && leftKey.endsWith('_key'))
-        return 42;
-    return 0;
-}
-function isJoinKeyColumn(column) {
-    const normalized = column.toLowerCase();
-    return normalized === 'id' ||
-        /(^|_)(id|key|uuid|sk)$/.test(normalized) ||
-        /_(id|key|uuid|sk)$/.test(normalized);
-}
-function joinSubjectForColumn(column) {
-    const normalized = column.toLowerCase();
-    const subject = normalized.replace(/_(id|key|uuid|sk)$/i, '');
-    if (!subject || subject === normalized || subject === 'id' || subject === 'key')
-        return undefined;
-    return normalizeToken(subject.split('_').at(-1) ?? subject);
-}
-function tableEntityTokens(table) {
-    const tokens = exactMatchTokens([table.name, table.relation.split('.').at(-1) ?? table.relation].join(' '));
-    for (const generic of ['dim', 'fct', 'fact', 'stg', 'stage', 'model', 'table'])
-        tokens.delete(generic);
-    return tokens;
-}
-function findColumnType(table, columnName) {
-    return table.columns.find((column) => namesEqualLoose(column.name, columnName))?.type;
-}
-function qualifiedMetricExpression(metric, tableAlias) {
-    const column = `${tableAlias}.${sqlIdentifier(metric.column)}`;
-    if (metric.column === 'rows')
-        return 'COUNT(*)';
-    if (/^COUNT\s*\(\s*DISTINCT\b/i.test(metric.expression))
-        return `COUNT(DISTINCT ${column})`;
-    if (metric.preAggregated)
-        return column;
-    const aggregate = metric.expression.match(/^(SUM|AVG|MIN|MAX|MEDIAN)\s*\(/i)?.[1]?.toUpperCase()
-        ?? (/avg|average|mean/i.test(metric.alias) ? 'AVG' : 'SUM');
-    return `${aggregate}(${column})`;
-}
-function inferGenericMetric(table, question) {
-    const lower = question.toLowerCase();
-    const wantsCount = /\b(count|how many|number of|volume)\b/i.test(lower);
-    const candidates = table.columns
-        .map((column) => {
-        const name = column.name.toLowerCase();
-        const tokens = meaningfulTokens(column.name);
-        let score = isNumericLikeColumn(column) ? 20 : 0;
-        for (const token of meaningfulTokens(question)) {
-            if (tokens.has(token))
-                score += 18;
-        }
-        if (/\b(revenue|sales|amount|total|spend|cost|margin|profit|value|points?|score|orders?|count|quantity|duration|minutes?|rate|average|avg)\b/i.test(name.replace(/_/g, ' '))) {
-            score += 18;
-        }
-        if (/\b(id|key|code|zip|postal|phone|season|year|month|week|day|date|time)\b/i.test(name.replace(/_/g, ' '))) {
-            score -= 14;
-        }
-        return { column: column.name, score };
-    })
-        .filter((candidate) => candidate.score > 0)
-        .sort((a, b) => b.score - a.score);
-    const countSubject = wantsCount ? inferCountSubject(question) : undefined;
-    if (wantsCount) {
-        const precomputed = candidates.find((candidate) => isPrecomputedCountMetric(candidate.column, countSubject));
-        if (precomputed) {
-            return {
-                column: precomputed.column,
-                expression: isPreAggregatedMetricColumn(precomputed.column) ? sqlIdentifier(precomputed.column) : `SUM(${sqlIdentifier(precomputed.column)})`,
-                alias: isPreAggregatedMetricColumn(precomputed.column) ? precomputed.column : `${precomputed.column}_sum`,
-                score: precomputed.score + 8,
-                preAggregated: isPreAggregatedMetricColumn(precomputed.column),
-            };
-        }
-        const distinctColumn = countSubject ? findDistinctCountColumn(table, countSubject) : undefined;
-        if (distinctColumn) {
-            return {
-                column: distinctColumn,
-                expression: `COUNT(DISTINCT ${sqlIdentifier(distinctColumn)})`,
-                alias: `${countSubject}_count`,
-                score: 34,
-                preAggregated: false,
-            };
-        }
-    }
-    const selected = candidates[0];
-    if (!selected && !wantsCount)
-        return undefined;
-    if (!selected || wantsCount && selected.score < 26) {
-        return {
-            column: 'rows',
-            expression: 'COUNT(*)',
-            alias: 'row_count',
-            score: 18,
-            preAggregated: true,
-        };
-    }
-    const aggregate = /\b(avg|average|mean)\b/i.test(lower) ? 'AVG' : 'SUM';
-    const aliasBase = `${selected.column}_${aggregate.toLowerCase()}`;
-    const preAggregated = isPreAggregatedMetricColumn(selected.column);
-    return {
-        column: selected.column,
-        expression: preAggregated ? sqlIdentifier(selected.column) : `${aggregate}(${sqlIdentifier(selected.column)})`,
-        alias: preAggregated ? selected.column : aliasBase,
-        score: selected.score,
-        preAggregated,
-    };
-}
-function inferCountSubject(question) {
-    const lower = question.toLowerCase();
-    const match = lower.match(/\b(?:how many|number of|count of|count|total)\s+(?:distinct\s+|unique\s+)?([a-z][a-z0-9_-]*)/);
-    const raw = match?.[1] ?? lower.match(/\b(customers?|accounts?|users?|members?|orders?|products?|players?|teams?|transactions?|sessions?|events?|records?|rows?)\b/)?.[1];
-    if (!raw)
-        return undefined;
-    const normalized = normalizeToken(raw.replace(/[^a-z0-9_]/g, ''));
-    if (!normalized || normalized === 'row' || normalized === 'record')
-        return undefined;
-    return normalized;
-}
-function findDistinctCountColumn(table, subject) {
-    const preferred = [
-        `${subject}_id`,
-        `${subject}_key`,
-        `${subject}_uuid`,
-        `${subject}_sk`,
-        `${subject}_name`,
-        subject,
-    ];
-    const direct = findSchemaColumn(table, preferred);
-    if (direct)
-        return direct;
-    const tableTokens = meaningfulTokens([table.name, table.relation].join(' '));
-    if (!tableTokens.has(subject))
-        return undefined;
-    return findSchemaColumn(table, ['id', 'key', 'uuid']);
-}
-function isPrecomputedCountMetric(column, subject) {
-    const normalized = column.toLowerCase();
-    const text = normalized.replace(/_/g, ' ');
-    if (/\b(id|key|uuid|code)\b/i.test(text))
-        return false;
-    if (/\b(count|cnt|number|num)\b/i.test(text)) {
-        return !subject || text.includes(subject) || text.includes(pluralizeSimple(subject));
-    }
-    return Boolean(subject && (normalized === `total_${subject}` ||
-        normalized === `total_${pluralizeSimple(subject)}`));
-}
-function pluralizeSimple(value) {
-    if (value.endsWith('y'))
-        return `${value.slice(0, -1)}ies`;
-    if (value.endsWith('s'))
-        return value;
-    return `${value}s`;
-}
-function augmentGenericRankingDimensions(table, dimensions, metric, question) {
-    const direction = rankingDirectionFromText(question);
-    if (!direction || !metric.preAggregated || /\bby\s+/i.test(question))
-        return dimensions;
-    const timeColumn = table.columns
-        .map((column) => column.name)
-        .find((name) => isTimeLikeGenericColumn(name) && !dimensions.some((dimension) => namesEqualLoose(dimension, name)));
-    return timeColumn ? [...dimensions, timeColumn] : dimensions;
-}
-function inferGenericDimensions(table, question, metricColumn) {
-    const lower = question.toLowerCase();
-    const requested = Array.from(lower.matchAll(/\bby\s+([a-z][a-z0-9_ -]{1,40})/g))
-        .map((match) => match[1] ?? '')
-        .flatMap((value) => value.split(/\band\b|,|\//i))
-        .map((value) => value.replace(/\b(desc|asc|top|bottom|highest|lowest|least|most|over time)\b/gi, '').trim())
-        .filter(Boolean);
-    const direct = requested
-        .map((value) => findSchemaColumn(table, [value, value.replace(/\s+/g, '_')]))
-        .filter((value) => Boolean(value));
-    if (direct.length > 0)
-        return uniqueDrilldownStrings(direct);
-    const domainHints = [
-        /\bcustomers?\b/.test(lower) ? ['customer_name', 'customer', 'customer_id'] : [],
-        /\bproducts?\b/.test(lower) ? ['product_name', 'product', 'sku', 'product_id'] : [],
-        /\bplayers?\b/.test(lower) ? ['player_name', 'player', 'player_id'] : [],
-        /\bteams?\b/.test(lower) ? ['team_name', 'team', 'team_id'] : [],
-        /\bregions?\b|\bmarkets?\b/.test(lower) ? ['region', 'market', 'geo'] : [],
-        /\bsegments?\b/.test(lower) ? ['segment', 'customer_segment', 'type'] : [],
-        /\bchannels?\b/.test(lower) ? ['channel', 'source_channel'] : [],
-        /\b(month|monthly)\b/.test(lower) ? ['month', 'order_month', 'created_month'] : [],
-        /\b(week|weekly)\b/.test(lower) ? ['week', 'order_week', 'created_week'] : [],
-        /\b(year|season|yearly)\b/.test(lower) ? ['season', 'year', 'order_year'] : [],
-    ].flat();
-    const hinted = findSchemaColumn(table, domainHints);
-    if (hinted)
-        return [hinted];
-    const fallback = table.columns
-        .map((column, index) => ({
-        column: column.name,
-        score: genericDimensionScore(column, question, index, metricColumn),
-    }))
-        .filter((candidate) => candidate.score > 0)
-        .sort((a, b) => b.score - a.score)
-        .map((candidate) => candidate.column);
-    return uniqueDrilldownStrings(fallback).slice(0, 1);
-}
-function genericDimensionScore(column, question, index, metricColumn) {
-    if (metricColumn && namesEqualLoose(column.name, metricColumn))
-        return -100;
-    const name = column.name.toLowerCase();
-    const text = name.replace(/_/g, ' ');
-    let score = Math.max(0, 10 - index * 0.05);
-    if (/\b(name|category|type|segment|region|market|channel|status|team|player|customer|product|vendor|account|month|week|year|season|date)\b/i.test(text)) {
-        score += 24;
-    }
-    if (isNumericLikeColumn(column) && !isTimeLikeGenericColumn(column.name))
-        score -= 18;
-    for (const token of meaningfulTokens(question)) {
-        if (meaningfulTokens(column.name).has(token))
-            score += 10;
-    }
-    return score;
-}
-function isNumericLikeColumn(column) {
-    const type = column.type ?? '';
-    const name = column.name.toLowerCase();
-    return /\b(INT|INTEGER|BIGINT|DECIMAL|DOUBLE|FLOAT|NUMBER|NUMERIC|REAL)\b/i.test(type)
-        || /\b(total|count|amount|revenue|sales|spend|cost|margin|profit|value|points?|score|quantity|duration|minutes?|rate|avg|average)\b/i.test(name.replace(/_/g, ' '));
-}
-function isPreAggregatedMetricColumn(name) {
-    return /^(total|count|avg|average|median|min|max)_/i.test(name)
-        || /_(total|count|avg|average|median|min|max)$/i.test(name);
-}
-function isTimeLikeGenericColumn(name) {
-    return /\b(date|time|day|week|month|quarter|year|season|period)\b/i.test(name);
-}
-function buildEntityProfileProposal(input) {
-    const entityTexts = entityMentionsForProfile(input.question, input.contextPack);
-    if (entityTexts.length === 0 || !isEntityProfileQuestion(input.question, input.contextPack))
-        return undefined;
-    const candidates = input.schemaContext
-        .map((table) => profileTableCandidate(table, input.question, input.followUp, entityTexts))
-        .filter((candidate) => Boolean(candidate))
-        .sort((a, b) => b.score - a.score);
-    const selected = candidates[0];
-    if (!selected)
-        return undefined;
-    const where = selected.filterValue
-        ? [`WHERE ${sqlIdentifier(selected.entityColumn)} = ${sqlStringLiteral(selected.filterValue)}`]
-        : [];
-    const columns = selected.selectColumns.map((column) => `  ${sqlIdentifier(column)}`).join(',\n');
-    const text = [
-        `Prepared a review-required profile query for ${selected.filterValue ?? entityTexts[0]} from ${selected.table.relation}.`,
-        selected.usedSampleValue
-            ? `The entity filter uses an inspected value match on ${selected.entityColumn}.`
-            : `The entity filter uses the likely entity column ${selected.entityColumn} from inspected schema metadata.`,
-        'This result is uncertified until reviewed and promoted.',
-    ].join(' ');
-    return {
-        text,
-        sql: [
-            'SELECT',
-            columns,
-            `FROM ${sqlRelation(selected.table.relation)}`,
-            ...where,
-            'LIMIT 50',
-        ].join('\n'),
-        viz: 'table',
-    };
-}
-function profileTableCandidate(table, question, followUp, entityTexts) {
-    if (table.columns.length === 0)
-        return undefined;
-    const matchedFilters = matchedEntityFiltersForQuestion(table, question, followUp);
-    const sampled = matchedFilters.find((filter) => entityTexts.some((entity) => normalizeForEntityMatch(entity) === normalizeForEntityMatch(filter.value))) ?? matchedFilters[0];
-    const entityColumn = sampled?.column ?? pickEntityProfileColumn(table, question);
-    if (!entityColumn)
-        return undefined;
-    const filterValue = sampled?.value ?? entityTexts[0];
-    if (!filterValue)
-        return undefined;
-    const selectColumns = orderedProfileColumns(table, entityColumn, question);
-    if (selectColumns.length === 0)
-        return undefined;
-    const questionTokens = meaningfulTokens(question);
-    const tableTokens = meaningfulTokens([table.relation, table.name, table.description ?? ''].join(' '));
-    const columnTokens = meaningfulTokens(table.columns.map((column) => column.name).join(' '));
-    const overlap = [...questionTokens].filter((token) => tableTokens.has(token) || columnTokens.has(token)).length;
-    const profileSignal = selectColumns.filter((column) => isProfileMeasureColumn(column, table)).length;
-    const score = (sampled ? 80 : 42) +
-        overlap * 6 +
-        profileSignal * 3 +
-        (/\b(player|customer|account|user|member|person|entity)\b/i.test(table.name) ? 8 : 0);
-    return {
-        table,
-        entityColumn,
-        filterValue,
-        selectColumns,
-        usedSampleValue: Boolean(sampled),
-        score,
-    };
-}
-function isEntityProfileQuestion(question, contextPack) {
-    const mode = contextPack?.questionPlan?.mode;
-    if (mode === 'entity_profile')
-        return true;
-    return /\b(profile|overview|360|complete\s+(?:stats|statistics|view)|full\s+(?:stats|statistics|view)|all\s+(?:stats|statistics|metrics)|research|reserach)\b/i.test(question);
-}
-function entityMentionsForProfile(question, contextPack) {
-    const values = [
-        ...(contextPack?.questionPlan?.entities ?? []).map((entity) => entity.text),
-        ...Array.from(question.matchAll(/\b(?:for|on|profile\s+for|research\s+on|reserach\s+on)\s+([A-Z][A-Za-z0-9&.'-]+(?:\s+[A-Z][A-Za-z0-9&.'-]+){0,5})/g))
-            .map((match) => match[1] ?? ''),
-    ];
-    if (isEntityProfileQuestion(question, contextPack)) {
-        values.push(...Array.from(question.matchAll(/\b([A-Z][a-z]+(?:\s+[A-Z][a-z]+){1,5})\b/g)).map((match) => match[1] ?? ''));
+            const score = joinColumnScore(leftColumn.name, rightColumn.name, left, right);
+            if (score <= 0)
+                continue;
+            candidates.push({ leftColumn: leftColumn.name, rightColumn: rightColumn.name, score });
+        }
     }
-    return uniqueDrilldownStrings(values
-        .map((value) => value.replace(/\b(profile|stats|statistics|details|summary)\b.*$/i, '').trim())
-        .filter((value) => value.length > 1 && !/^(Can You|Could You|Tell Me|Show Me)$/i.test(value)))
-        .slice(0, 6);
+    return candidates.sort((a, b) => b.score - a.score || a.leftColumn.localeCompare(b.leftColumn))[0];
 }
-function pickEntityProfileColumn(table, question) {
-    const lower = question.toLowerCase();
-    const domainHints = [
-        /\bplayers?\b/.test(lower) ? 'player' : '',
-        /\bcustomers?\b/.test(lower) ? 'customer' : '',
-        /\baccounts?\b/.test(lower) ? 'account' : '',
-        /\busers?\b/.test(lower) ? 'user' : '',
-        /\bmembers?\b/.test(lower) ? 'member' : '',
-        /\bteams?\b/.test(lower) ? 'team' : '',
-        /\bproducts?\b/.test(lower) ? 'product' : '',
-    ].filter(Boolean);
-    const preferred = [
-        ...domainHints.flatMap((hint) => [`${hint}_name`, `${hint}_full_name`, hint]),
-        'name',
-        'full_name',
-        'display_name',
-        'title',
-    ];
-    const direct = findSchemaColumn(table, preferred);
-    if (direct)
-        return direct;
-    const scored = table.columns
-        .map((column) => {
-        const name = column.name.toLowerCase();
-        let score = 0;
-        if (name.endsWith('_name') || name === 'name')
-            score += 30;
-        if (/\b(name|title|email)\b/i.test(name.replace(/_/g, ' ')))
-            score += 20;
-        if (domainHints.some((hint) => name.includes(hint)))
-            score += 16;
-        if (/\b(id|key|code|date|time|amount|total|count|score|points|revenue)\b/i.test(name.replace(/_/g, ' ')))
-            score -= 12;
-        return { column: column.name, score };
-    })
-        .filter((item) => item.score > 0)
-        .sort((a, b) => b.score - a.score);
-    return scored[0]?.column;
-}
-function orderedProfileColumns(table, entityColumn, question) {
-    const scored = table.columns
-        .map((column, index) => ({
-        column: column.name,
-        score: profileColumnScore(column, question, index),
-        index,
-    }))
-        .sort((a, b) => b.score - a.score || a.index - b.index);
-    const selected = uniqueDrilldownStrings([
-        entityColumn,
-        ...scored.map((item) => item.column),
-    ]).slice(0, 24);
-    return selected.length > 0 ? selected : [entityColumn];
-}
-function profileColumnScore(column, question, index) {
-    const name = column.name.toLowerCase();
-    const text = name.replace(/_/g, ' ');
-    const lowerQuestion = question.toLowerCase();
-    let score = Math.max(0, 12 - index * 0.1);
-    if (isProfileMeasureColumn(column.name, { relation: '', name: '', columns: [column] }))
-        score += 35;
-    if (/\b(name|title|team|season|year|date|type|category|segment|status)\b/i.test(text))
-        score += 18;
-    if (/\b(id|key|code)\b/i.test(text))
-        score += 2;
-    for (const token of meaningfulTokens(lowerQuestion)) {
-        if (meaningfulTokens(column.name).has(token))
-            score += 12;
-    }
-    if (column.description && meaningfulTokens(column.description).size > 0)
-        score += 4;
-    return score;
+function joinColumnScore(leftColumn, rightColumn, leftTable, rightTable) {
+    const leftKey = normalizeRelationKey(leftColumn).replace(/\./g, '_');
+    const rightKey = normalizeRelationKey(rightColumn).replace(/\./g, '_');
+    const leftJoinLike = isJoinKeyColumn(leftColumn);
+    const rightJoinLike = isJoinKeyColumn(rightColumn);
+    if (!leftJoinLike || !rightJoinLike)
+        return 0;
+    if (leftKey === rightKey)
+        return 70;
+    const leftSubject = joinSubjectForColumn(leftColumn);
+    const rightSubject = joinSubjectForColumn(rightColumn);
+    if (leftSubject && rightSubject && leftSubject === rightSubject)
+        return 62;
+    const leftTableTokens = tableEntityTokens(leftTable);
+    const rightTableTokens = tableEntityTokens(rightTable);
+    if (leftSubject && rightKey === 'id' && rightTableTokens.has(leftSubject))
+        return 58;
+    if (rightSubject && leftKey === 'id' && leftTableTokens.has(rightSubject))
+        return 58;
+    if (leftSubject && rightTableTokens.has(leftSubject) && rightKey.endsWith('_key'))
+        return 42;
+    if (rightSubject && leftTableTokens.has(rightSubject) && leftKey.endsWith('_key'))
+        return 42;
+    return 0;
 }
-function isProfileMeasureColumn(columnName, table) {
-    const column = table.columns.find((item) => namesEqualLoose(item.name, columnName));
-    const name = columnName.toLowerCase();
-    const text = name.replace(/_/g, ' ');
-    return /\b(total|count|avg|average|sum|rate|score|points|pts|rebounds?|assists?|steals?|blocks?|turnovers?|minutes?|games?|wins?|losses?|revenue|amount|spend|orders?|quantity|margin|cost|value|stat)\b/i.test(text)
-        || /\b(INT|INTEGER|BIGINT|DECIMAL|DOUBLE|FLOAT|NUMBER|NUMERIC|REAL)\b/i.test(column?.type ?? '');
+function isJoinKeyColumn(column) {
+    const normalized = column.toLowerCase();
+    return normalized === 'id' ||
+        /(^|_)(id|key|uuid|sk)$/.test(normalized) ||
+        /_(id|key|uuid|sk)$/.test(normalized);
 }
-function buildMatchedEntityDrilldownProposal(input) {
-    if (input.intent !== 'entity_drilldown' && input.followUp?.kind !== 'drilldown')
-        return undefined;
-    const table = pickDrilldownTable(input.schemaContext, input.question, input.followUp);
-    if (!table)
-        return undefined;
-    const dimension = inferDrilldownDimension(table, input.question, input.followUp);
-    if (!dimension)
-        return undefined;
-    const entityFilters = matchedEntityFiltersForQuestion(table, input.question, input.followUp);
-    if (entityFilters.length === 0)
-        return undefined;
-    if (entityFilters.some((filter) => namesEqualLoose(filter.column, dimension)))
-        return undefined;
-    const sourceSql = selectSourceBlockSql(input.contextPack, input.followUp?.sourceBlockName);
-    const metric = inferDrilldownMetric(table, input.question, sourceSql);
-    if (!metric)
-        return undefined;
-    const timePredicates = drilldownTimePredicates({
-        question: input.question,
-        followUp: input.followUp,
-        table,
-        sourceSql,
-    });
-    if (mentionsRelativeTime(input.question, input.followUp) && timePredicates.length === 0)
+function joinSubjectForColumn(column) {
+    const normalized = column.toLowerCase();
+    const subject = normalized.replace(/_(id|key|uuid|sk)$/i, '');
+    if (!subject || subject === normalized || subject === 'id' || subject === 'key')
         return undefined;
-    const predicates = [
-        ...entityFilters.map((filter) => `${sqlIdentifier(filter.column)} = ${sqlStringLiteral(filter.value)}`),
-        ...timePredicates,
-    ];
-    const where = predicates.length ? [`WHERE ${predicates.join(' AND ')}`] : [];
-    return {
-        text: [
-            `Prepared a review-required ${humanizeIdentifier(dimension)} drilldown from inspected metadata.`,
-            `The entity filter uses ${entityFilters.map((filter) => `${filter.column} = ${filter.value}`).join(', ')} from matched sample values.`,
-            'This result is uncertified until reviewed and promoted.',
-        ].join(' '),
-        sql: [
-            'SELECT',
-            `  ${sqlIdentifier(dimension)} AS ${sqlIdentifier(dimension)},`,
-            `  ${metric.expression} AS ${sqlIdentifier(metric.alias)}`,
-            `FROM ${sqlRelation(table.relation)}`,
-            ...where,
-            `GROUP BY ${sqlIdentifier(dimension)}`,
-            `ORDER BY ${sqlIdentifier(metric.alias)} DESC`,
-            'LIMIT 50',
-        ].join('\n'),
-        viz: 'bar',
-    };
+    return normalizeToken(subject.split('_').at(-1) ?? subject);
+}
+function tableEntityTokens(table) {
+    const tokens = exactMatchTokens([table.name, table.relation.split('.').at(-1) ?? table.relation].join(' '));
+    for (const generic of ['dim', 'fct', 'fact', 'stg', 'stage', 'model', 'table'])
+        tokens.delete(generic);
+    return tokens;
 }
 function schemaContextWithAllowedSqlContext(schemaContext, contextPack) {
     const byRelation = new Map();
@@ -2059,169 +2335,6 @@ function relationSelectionFor(relation, lookup) {
     }
     return undefined;
 }
-function pickDrilldownTable(schemaContext, question, followUp) {
-    const scored = schemaContext
-        .map((table) => ({
-        table,
-        filters: matchedEntityFiltersForQuestion(table, question, followUp).length,
-        dimension: inferDrilldownDimension(table, question, followUp) ? 1 : 0,
-        measure: inferDrilldownMetric(table, question, undefined) ? 1 : 0,
-    }))
-        .filter((candidate) => candidate.filters > 0 && candidate.dimension > 0 && candidate.measure > 0)
-        .sort((a, b) => (b.filters + b.dimension + b.measure) - (a.filters + a.dimension + a.measure));
-    return scored[0]?.table;
-}
-function inferDrilldownDimension(table, question, followUp) {
-    const lower = question.toLowerCase();
-    const requested = [
-        ...(followUp?.dimensions ?? []),
-        ...Array.from(lower.matchAll(/\bby\s+([a-z][a-z0-9_ -]{1,40})/g)).map((match) => match[1] ?? ''),
-    ]
-        .flatMap((value) => value.split(/\band\b|,|\//i))
-        .map((value) => value.replace(/\b(last|this|next|previous|prior|current)\s+(day|week|month|quarter|year)\b/gi, '').trim())
-        .filter(Boolean);
-    const direct = findSchemaColumn(table, requested);
-    if (direct)
-        return direct;
-    if (/\bcustomers?\b/.test(lower)) {
-        const customer = findSchemaColumn(table, ['customer', 'customer_name', 'account', 'account_name']);
-        if (customer)
-            return customer;
-    }
-    if (/\bsegments?\b/.test(lower)) {
-        const segment = findSchemaColumn(table, ['segment', 'customer_segment', 'market_segment']);
-        if (segment)
-            return segment;
-    }
-    if (/\bproducts?\b/.test(lower)) {
-        const product = findSchemaColumn(table, ['product', 'product_name', 'sku']);
-        if (product)
-            return product;
-    }
-    if (/\bregions?\b/.test(lower)) {
-        const region = findSchemaColumn(table, ['region', 'market', 'geo']);
-        if (region)
-            return region;
-    }
-    return undefined;
-}
-function matchedEntityFiltersForQuestion(table, question, followUp) {
-    const text = normalizeForEntityMatch([
-        question,
-        ...(followUp?.filters ?? []),
-    ].join(' '));
-    const filters = [];
-    for (const column of table.columns) {
-        for (const sampleValue of column.sampleValues ?? []) {
-            if (isTemporalDrilldownValue(sampleValue))
-                continue;
-            const needle = normalizeForEntityMatch(sampleValue);
-            if (!needle || !text.includes(needle))
-                continue;
-            filters.push({ column: column.name, value: sampleValue });
-        }
-    }
-    return uniqueMatchedEntityFilters(filters);
-}
-function inferDrilldownMetric(table, question, sourceSql) {
-    const sourceMetric = sourceSql ? aggregateMetricFromSourceSql(table, sourceSql) : undefined;
-    if (sourceMetric)
-        return sourceMetric;
-    const lower = question.toLowerCase();
-    const candidates = /\brevenue|arr|mrr|sales\b/.test(lower)
-        ? ['revenue', 'net_revenue', 'gross_revenue', 'amount', 'order_total', 'total_amount', 'sales', 'arr', 'mrr']
-        : ['amount', 'revenue', 'order_total', 'total_amount', 'value', 'spend'];
-    const column = findSchemaColumn(table, candidates);
-    if (!column)
-        return undefined;
-    const alias = /\brevenue|arr|mrr|sales\b/.test(lower) ? 'revenue_total' : `${column}_total`;
-    return {
-        expression: `SUM(${sqlIdentifier(column)})`,
-        alias,
-    };
-}
-function aggregateMetricFromSourceSql(table, sourceSql) {
-    for (const column of table.columns) {
-        const columnPattern = sqlIdentifierPattern(column.name);
-        const aggregatePattern = new RegExp(`\\b(SUM|COUNT|AVG|MIN|MAX)\\s*\\(\\s*(?:["\`]?\\w+["\`]?\\s*\\.\\s*)?(${columnPattern}|\\*)\\s*\\)\\s*(?:AS\\s+(["\`]?\\w+["\`]?))?`, 'i');
-        const match = sourceSql.match(aggregatePattern);
-        if (!match)
-            continue;
-        const fn = (match[1] ?? 'SUM').toUpperCase();
-        const target = match[2] === '*' ? '*' : sqlIdentifier(column.name);
-        const alias = cleanSqlIdentifier(match[3] ?? defaultMetricAlias(fn, column.name));
-        return {
-            expression: `${fn}(${target})`,
-            alias,
-        };
-    }
-    return undefined;
-}
-function drilldownTimePredicates(input) {
-    if (!mentionsRelativeTime(input.question, input.followUp))
-        return [];
-    if (!input.sourceSql)
-        return [];
-    const timeColumns = input.table.columns.map((column) => column.name).filter(isTimeLikeDrilldownColumn);
-    if (timeColumns.length === 0)
-        return [];
-    return extractWherePredicates(input.sourceSql)
-        .map(stripSqlAliasQualifiers)
-        .filter((predicate) => isReusableSqlPredicate(predicate))
-        .filter((predicate) => timeColumns.some((column) => predicateReferencesColumn(predicate, column)))
-        .slice(0, 3);
-}
-function selectSourceBlockSql(contextPack, sourceBlockName) {
-    const sourceSql = contextPack?.allowedSqlContext?.sourceBlockSql ?? [];
-    if (sourceSql.length === 0)
-        return undefined;
-    const preferred = sourceBlockName
-        ? sourceSql.find((source) => namesEqualLoose(source.name, sourceBlockName))
-        : undefined;
-    return (preferred ?? sourceSql.find((source) => source.status === 'certified') ?? sourceSql[0])?.sql;
-}
-function extractWherePredicates(sql) {
-    const match = sql.match(/\bWHERE\b([\s\S]*?)(\bGROUP\s+BY\b|\bHAVING\b|\bORDER\s+BY\b|\bLIMIT\b|$)/i);
-    if (!match)
-        return [];
-    return (match[1] ?? '')
-        .split(/\s+AND\s+/i)
-        .map((part) => part.trim().replace(/^\(+|\)+$/g, '').replace(/\s+/g, ' '))
-        .filter(Boolean);
-}
-function mentionsRelativeTime(question, followUp) {
-    const text = [question, ...(followUp?.filters ?? [])].join(' ');
-    return /\b(last|this|next|previous|prior|current)\s+(day|week|month|quarter|year)\b/i.test(text)
-        || /\b(today|yesterday|tomorrow|ytd|mtd|qtd|wtd)\b/i.test(text);
-}
-function isTimeLikeDrilldownColumn(name) {
-    return /\b(date|time|day|week|month|quarter|year|period|created_at|updated_at)\b/i.test(name);
-}
-function stripSqlAliasQualifiers(predicate) {
-    return predicate.replace(/\b["`]?\w+["`]?\s*\.\s*(["`]?\w+["`]?)/g, '$1');
-}
-function isReusableSqlPredicate(predicate) {
-    if (!predicate || predicate.length > 240)
-        return false;
-    if (/[;]/.test(predicate) || /--|\/\*/.test(predicate))
-        return false;
-    return !/\b(SELECT|INSERT|UPDATE|DELETE|CREATE|DROP|ALTER|COPY|PRAGMA|SET)\b/i.test(predicate);
-}
-function predicateReferencesColumn(predicate, column) {
-    return new RegExp(`(^|[^\\w])${sqlIdentifierPattern(column)}([^\\w]|$)`, 'i').test(predicate);
-}
-function sqlIdentifierPattern(identifier) {
-    const escaped = escapeRegExp(identifier);
-    return `(?:"${escaped}"|\`${escaped}\`|${escaped})`;
-}
-function sqlStringLiteral(value) {
-    return `'${value.replace(/'/g, "''")}'`;
-}
-function defaultMetricAlias(fn, column) {
-    if (fn === 'SUM' && /revenue|amount|sales|arr|mrr/i.test(column))
-        return 'revenue_total';
-    return `${column}_${fn.toLowerCase()}`;
-}
 function cleanSqlIdentifier(identifier) {
     return identifier.replace(/^["`]|["`]$/g, '').trim();
 }
@@ -2243,200 +2356,22 @@ function relationLookupKeys(relation) {
         keys.add(parts[parts.length - 1]);
     return Array.from(keys);
 }
-function normalizeForEntityMatch(value) {
-    return value.toLowerCase().replace(/[^a-z0-9.%+-]+/g, ' ').replace(/\s+/g, ' ').trim();
-}
-function uniqueMatchedEntityFilters(filters) {
-    const seen = new Set();
-    const unique = [];
-    for (const filter of filters) {
-        const key = `${filter.column.toLowerCase()}\0${filter.value.toLowerCase()}`;
-        if (seen.has(key))
-            continue;
-        seen.add(key);
-        unique.push(filter);
-    }
-    return unique;
-}
 function uniqueDrilldownStrings(values) {
     return Array.from(new Set(values));
 }
-function isTemporalDrilldownValue(value) {
-    return mentionsRelativeTime(value, undefined) || /^\d{4}-\d{2}-\d{2}/.test(value);
-}
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-function buildContextPackAwareProposal(input) {
-    if (!isGeneratedAgentIntent(input.intent))
-        return undefined;
-    if (!input.contextPack)
-        return undefined;
-    const profileProposal = buildContextPackProfileProposal(input.question, input.contextPack);
-    if (profileProposal)
-        return profileProposal;
-    const lower = input.question.toLowerCase();
-    if (!/\b(least|lowest|fewest|bottom|min(?:imum)?)\b/.test(lower))
-        return undefined;
-    for (const object of input.contextPack.objects) {
-        if (object.objectType !== 'dql_block' || object.status !== 'certified')
-            continue;
-        const sql = typeof object.payload?.sql === 'string' ? object.payload.sql.trim() : '';
-        if (!sql || !/\border\s+by\b/i.test(sql) || !/\bdesc\b/i.test(sql))
-            continue;
-        const inverted = invertRankingSql(sql);
-        if (!inverted || inverted === sql)
-            continue;
-        return {
-            text: `Generated a review-required least-ranking query by using certified block "${object.name}" as context and reversing its ranking direction. This result is uncertified until reviewed and promoted.`,
-            sql: ensurePreviewLimit(inverted, 10),
-            viz: 'table',
-        };
-    }
-    return undefined;
-}
-function buildContextPackProfileProposal(question, contextPack) {
-    const entityTexts = entityMentionsForProfile(question, contextPack);
-    if (entityTexts.length === 0 || !isEntityProfileQuestion(question, contextPack))
-        return undefined;
-    const sources = [...(contextPack.allowedSqlContext?.sourceBlockSql ?? [])]
-        .sort((a, b) => {
-        const preferred = contextPack.routeDecision.certifiedApplicability?.objectKey;
-        if (preferred && a.objectKey === preferred)
-            return -1;
-        if (preferred && b.objectKey === preferred)
-            return 1;
-        return 0;
-    });
-    for (const source of sources) {
-        const shape = extractSimpleSelectShape(source.sql);
-        if (!shape)
-            continue;
-        const entityColumn = pickEntityColumnFromSelectExpressions(shape.selectExpressions, question);
-        if (!entityColumn)
-            continue;
-        const selectExpressions = uniqueSqlSelectExpressions(shape.selectExpressions).slice(0, 24);
-        if (selectExpressions.length === 0)
-            continue;
-        const orderColumn = selectExpressions
-            .map(selectExpressionOutputName)
-            .find((column) => column && /\b(season|year|date|month|week|game_date|created_at)\b/i.test(column));
-        const sql = [
-            'SELECT',
-            selectExpressions.map((expression) => `  ${expression}`).join(',\n'),
-            `FROM ${shape.relation}`,
-            `WHERE ${sqlIdentifier(entityColumn)} = ${sqlStringLiteral(entityTexts[0])}`,
-            orderColumn ? `ORDER BY ${sqlIdentifier(orderColumn)} DESC` : '',
-            'LIMIT 50',
-        ].filter(Boolean).join('\n');
-        return {
-            text: `Prepared a review-required profile query for ${entityTexts[0]} by using certified block "${source.name}" as SQL-shape context. This result is uncertified until reviewed and promoted.`,
-            sql,
-            viz: 'table',
-        };
-    }
-    return undefined;
-}
-function pickEntityColumnFromSelectExpressions(expressions, question) {
-    const outputNames = expressions
-        .map(selectExpressionOutputName)
-        .filter((value) => Boolean(value));
-    const lower = question.toLowerCase();
-    const hints = [
-        /\bplayers?\b/.test(lower) ? 'player' : '',
-        /\bcustomers?\b/.test(lower) ? 'customer' : '',
-        /\baccounts?\b/.test(lower) ? 'account' : '',
-        /\busers?\b/.test(lower) ? 'user' : '',
-        /\bteams?\b/.test(lower) ? 'team' : '',
-        /\bproducts?\b/.test(lower) ? 'product' : '',
-    ].filter(Boolean);
-    const preferred = [
-        ...hints.flatMap((hint) => [`${hint}_name`, `${hint}_full_name`, hint]),
-        'name',
-        'full_name',
-        'display_name',
-    ];
-    for (const wanted of preferred) {
-        const match = outputNames.find((name) => namesEqualLoose(name, wanted));
-        if (match)
-            return match;
-    }
-    return outputNames.find((name) => /(^|_)(name|title|email)$/.test(name.toLowerCase()));
-}
-function uniqueSqlSelectExpressions(expressions) {
-    const seen = new Set();
-    const unique = [];
-    for (const expression of expressions) {
-        const normalized = expression.replace(/\s+/g, ' ').trim().toLowerCase();
-        if (!normalized || seen.has(normalized))
-            continue;
-        seen.add(normalized);
-        unique.push(expression.replace(/\s+/g, ' ').trim());
-    }
-    return unique;
-}
-function invertRankingSql(sql) {
-    const withoutTrailingSemicolon = sql.replace(/;\s*$/, '').trim();
-    const inverted = withoutTrailingSemicolon.replace(/\border\s+by\s+([\s\S]*?)(\blimit\b|$)/i, (match, orderExpr, limitKeyword) => {
-        if (!/\bdesc\b/i.test(orderExpr))
-            return match;
-        const nextExpr = orderExpr
-            .replace(/\bDESC\b/gi, 'ASC')
-            .replace(/\bNULLS\s+FIRST\b/gi, 'NULLS LAST');
-        return `ORDER BY ${nextExpr}${limitKeyword}`;
-    });
-    return inverted !== withoutTrailingSemicolon ? inverted : undefined;
-}
-function ensurePreviewLimit(sql, limit) {
-    if (/\blimit\s+\d+\b/i.test(sql))
-        return sql;
-    return `${sql.replace(/;\s*$/, '').trim()}\nLIMIT ${limit}`;
-}
-function findSchemaTable(schemaContext, names) {
-    return schemaContext.find((table) => {
-        const tableNames = new Set([table.name, table.relation.split('.').at(-1) ?? table.relation].map((name) => name.toLowerCase()));
-        return names.some((name) => tableNames.has(name.toLowerCase()));
-    });
-}
-function findSchemaColumn(table, names) {
-    const byLower = new Map(table.columns.map((column) => [column.name.toLowerCase(), column.name]));
-    for (const name of names) {
-        const exact = byLower.get(name.toLowerCase());
-        if (exact)
-            return exact;
-    }
-    return undefined;
-}
-function sqlRelation(relation) {
-    return relation.split('.').map(sqlIdentifier).join('.');
-}
-function sqlIdentifier(identifier) {
-    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(identifier)
-        ? identifier
-        : `"${identifier.replace(/"/g, '""')}"`;
-}
 function humanizeIdentifier(identifier) {
     return identifier.replace(/[_-]+/g, ' ');
 }
-function businessMeasurePhrase(identifier) {
-    const lower = identifier.toLowerCase();
-    if (lower.includes('lifetime_spend'))
-        return 'lifetime spend';
-    if (lower.includes('count_lifetime_orders') || lower.includes('lifetime_orders') || lower.includes('order_count')) {
-        return 'lifetime order count';
-    }
-    return humanizeIdentifier(identifier);
-}
 function pickCertifiedArtifact(input) {
     // Hint match wins immediately: the active Skill's vocabulary points the
     // user at a specific block. We still validate it's certified.
     for (const hint of input.blockHints) {
         const node = input.kg.getNode(`block:${hint}`);
-        if (node && node.status === 'certified' && hasCompatibleCertifiedBlockMatch(input.question, node)) {
+        if (node && node.status === 'certified' && hasCertifiedNodeFit(input.question, input.questionPlan, node)) {
             return { node, score: 1, snippet: undefined };
         }
     }
-    const executableHit = pickFirstCertifiedHit(input.executableArtifactHits, input.kg, input.excludedArtifactIds, input.question);
+    const executableHit = pickFirstCertifiedHit(input.executableArtifactHits, input.kg, input.excludedArtifactIds, input.question, input.questionPlan);
     if (isBusinessDefinitionQuestion(input.question)) {
         if (executableHit && hasExactExecutableArtifactSignal(input.question, executableHit.node)) {
             return executableHit;
@@ -2464,7 +2399,7 @@ function pickCertifiedArtifact(input) {
     }
     return null;
 }
-function pickFirstCertifiedHit(hits, kg, excludedNodeIds, question) {
+function pickFirstCertifiedHit(hits, kg, excludedNodeIds, question, questionPlan) {
     for (const hit of hits) {
         if (hit.score < CERTIFIED_HIT_THRESHOLD)
             break;
@@ -2472,7 +2407,9 @@ function pickFirstCertifiedHit(hits, kg, excludedNodeIds, question) {
             continue;
         if (!isCertifiedHit(hit, kg))
             continue;
-        if (question && hit.node.kind === 'block' && !hasCompatibleCertifiedBlockMatch(question, hit.node))
+        if (question && questionPlan && hit.node.kind === 'block' && !hasCertifiedNodeFit(question, questionPlan, hit.node))
+            continue;
+        if (question && !questionPlan && hit.node.kind === 'block' && !hasCompatibleCertifiedBlockMatch(question, hit.node))
             continue;
         return hit;
     }
@@ -2493,7 +2430,7 @@ function pickCertifiedDrilldownArtifact(input) {
             continue;
         if (!isCertifiedHit(hit, input.kg))
             continue;
-        if (!hasCompatibleCertifiedBlockMatch(input.question, hit.node))
+        if (!hasCertifiedNodeFit(input.question, input.questionPlan, hit.node, { allowInferredContract: true }))
             continue;
         if (!hasRequestedDrilldownOverlap(hit.node, requestedTerms))
             continue;
@@ -2593,6 +2530,40 @@ function hasCompatibleCertifiedBlockMatch(question, node) {
     return hasMeaningfulCertifiedBlockSignal(question, node)
         && hasCompatibleRankingDirection(question, node);
 }
+function hasCertifiedNodeFit(question, plan, node, options = {}) {
+    if (!hasCompatibleRankingDirection(question, node))
+        return false;
+    const definitionLookup = isBusinessDefinitionQuestion(question) && objectNameInQuestion(question, node);
+    const exactExampleMatch = (node.examples ?? []).some((example) => normalizeQuestion(example.question) === normalizeQuestion(question));
+    const exactObjectRequest = objectNameInQuestion(question, node)
+        && /\b(run|use|open|show|execute|certified|saved|block)\b/i.test(question);
+    if (!definitionLookup && !exactExampleMatch && !exactObjectRequest && !hasMeaningfulCertifiedBlockSignal(question, node))
+        return false;
+    const fit = evaluateCertifiedBlockFit({
+        question,
+        plan,
+        block: node,
+        exactExampleMatch: exactExampleMatch || exactObjectRequest,
+        definitionLookup,
+    });
+    if (certifiedFitAllowsTier1(fit))
+        return true;
+    return Boolean(options.allowInferredContract
+        && fit.kind === 'exact'
+        && fit.confidence === 'medium'
+        && fit.missingDimensions.length === 0
+        && fit.missingOutputs.length === 0
+        && fit.unsupportedFilters.length === 0
+        && !fit.grainMismatch);
+}
+function objectNameInQuestion(question, node) {
+    const questionText = normalizeQuestion(question);
+    const name = normalizeQuestion(node.name);
+    return Boolean(name && questionText.includes(name));
+}
+function normalizeQuestion(value) {
+    return value.toLowerCase().replace(/[_-]+/g, ' ').replace(/[^a-z0-9 ]+/g, ' ').replace(/\s+/g, ' ').trim();
+}
 function hasCompatibleRankingDirection(question, node) {
     const questionDirection = rankingDirectionFromText(question);
     if (!questionDirection)
@@ -2805,8 +2776,9 @@ function isFilteredEntityQuestion(question) {
     if (/\b(for|where|only|specific|single|individual|named|called)\b.+\b(account|accounts|customer|customers|product|products|sku|user|users)\b/i.test(lower)) {
         return true;
     }
-    if (/\b(account|customer|product|sku|user)\s+(?:id|name|email)\b/i.test(lower))
-        return true;
+    if (/\b(account|customer|product|sku|user)\s+(?:id|name|email)\b/i.test(lower)) {
+        return !mentionsEntityIdentifierAsRequestedOutput(lower);
+    }
     if (/[A-Z][a-z]+(?:\s+[A-Z][a-z]+){1,3}/.test(question) && /\b(revenue|sales|order|orders|spend|value|churn|usage|activity|performance|performed|metric|kpi)\b/i.test(lower)) {
         return true;
     }
@@ -2814,6 +2786,9 @@ function isFilteredEntityQuestion(question) {
         return true;
     return false;
 }
+function mentionsEntityIdentifierAsRequestedOutput(lowerQuestion) {
+    return /\b(?:with|including|include|return|show|list|give|provide|columns?|fields?|results?)\b[^.?!]{0,100}\b(?:account|customer|product|sku|user)\s+(?:id|name|email)\b/i.test(lowerQuestion);
+}
 function looksLikeDataQuestion(question) {
     return /\b(show|list|find|what|which|how many|how much|compare|trend|revenue|account|accounts|customer|customers|order|orders|product|products|sales|metric|kpi|dashboard|performance|performed|user|users)\b/i.test(question);
 }
@@ -2971,10 +2946,10 @@ async function requestSqlRepair(input) {
         {
             role: 'user',
             content: [
-                'The generated SQL failed during bounded preview execution.',
+                'The SQL preview for the review-required DQL artifact failed during bounded preview execution.',
                 `Question: ${input.question}`,
                 `Execution error: ${input.executionError}`,
-                'Return one corrected read-only SQL query using only the runtime schema below.',
+                'Return one corrected read-only SQL query using only the runtime schema below, as a single ```json fenced object with summary, sql, viz, outputs, and optional dql metadata fields.',
                 schema,
             ].join('\n\n'),
         },
@@ -2987,6 +2962,253 @@ async function requestSqlRepair(input) {
         reasoningEffort: input.reasoningEffort,
     });
 }
+async function generateProposalWithOptionalTools(input) {
+    const tools = input.tools?.filter((tool) => tool.name && tool.description) ?? [];
+    const options = {
+        signal: input.signal,
+        reasoningEffort: input.reasoningEffort,
+    };
+    if (!input.provider.generateWithTools || tools.length === 0) {
+        return input.provider.generate(input.messages, options);
+    }
+    const toolBudget = proposalToolBudgetForQuestion(input.questionPlan, input.intent, {
+        analysisDepth: input.analysisDepth,
+        reasoningEffort: input.reasoningEffort,
+    });
+    const toolPolicy = {
+        role: 'system',
+        content: [
+            'You may use the supplied DQL tools to inspect semantic members, certified context, metadata context, and bounded repair options.',
+            `Tool budget for this question: ${toolBudget.maxToolCalls} call(s) (${toolBudget.effortClass}: ${toolBudget.reason}). Stop as soon as a lane can answer.`,
+            'Prefer semantic compile before deep warehouse search when the semantic layer contains the requested metric/dimensions/time grain.',
+            'Use context expansion only to repair a named, known relation/column gap; do not loop on the same failed context.',
+            'Final response must be a single ```json fenced object with summary, sql, viz, outputs, and optional dql metadata fields.',
+        ].join('\n'),
+    };
+    return input.provider.generateWithTools([...input.messages, toolPolicy], tools, {
+        ...options,
+        maxToolCalls: toolBudget.maxToolCalls,
+        onToolCall: (event) => {
+            const sink = input.toolCalls;
+            if (sink)
+                sink.push(evidenceToolCallFromEvent(event, sink.length + 1));
+        },
+    });
+}
+async function selectDeepGeneratedProposalCandidate(input) {
+    const initial = await scoreDeepGeneratedProposalCandidate(input, {
+        raw: input.initial.raw,
+        parsed: input.initial.parsed,
+        index: 1,
+    });
+    // Deep mode diversifies whenever we can COMPARE candidate results (an executor
+    // is available) — so a valid-but-subtly-wrong first candidate can be out-voted
+    // by execution-result agreement — or when the first candidate failed and needs a
+    // repair alternative. Without an executor, a validated first candidate is the
+    // most we can assess, so return it and skip the extra generations.
+    const shouldDiversify = Boolean(input.executeGeneratedSql) || !initial.validationOk;
+    if (!shouldDiversify) {
+        return { selected: initial, notes: [] };
+    }
+    const candidates = [initial];
+    const alternatives = await generateDeepAlternativeProposals(input);
+    for (const [offset, raw] of alternatives.entries()) {
+        if (!raw.trim())
+            continue;
+        candidates.push(await scoreDeepGeneratedProposalCandidate(input, {
+            raw,
+            parsed: parseProposal(raw),
+            index: offset + 2,
+        }));
+        if (candidates.length >= 5)
+            break;
+    }
+    const signatureCounts = new Map();
+    for (const candidate of candidates) {
+        if (!candidate.resultSignature)
+            continue;
+        signatureCounts.set(candidate.resultSignature, (signatureCounts.get(candidate.resultSignature) ?? 0) + 1);
+    }
+    for (const candidate of candidates) {
+        const equivalenceCount = candidate.resultSignature ? signatureCounts.get(candidate.resultSignature) ?? 0 : 0;
+        if (equivalenceCount > 1)
+            candidate.score += equivalenceCount * 10;
+    }
+    const selected = candidates
+        .slice()
+        .sort((a, b) => b.score - a.score ||
+        Number(b.validationOk) - Number(a.validationOk) ||
+        Number(Boolean(b.result && !b.executionError)) - Number(Boolean(a.result && !a.executionError)) ||
+        a.index - b.index)[0];
+    if (!selected)
+        return { notes: [] };
+    const status = selected.validationOk
+        ? selected.executionError
+            ? `validated but preview failed: ${selected.executionError}`
+            : selected.result
+                ? `validated and previewed ${selected.result.rowCount.toLocaleString()} row(s)`
+                : 'validated'
+        : `failed validation: ${selected.validationError ?? 'unknown validation issue'}`;
+    // Surface how much the candidates disagreed: distinct execution-result
+    // signatures among the candidates that executed cleanly.
+    const executedCandidates = candidates.filter((candidate) => candidate.resultSignature);
+    const distinctResults = new Set(executedCandidates.map((candidate) => candidate.resultSignature)).size;
+    const agreementNote = executedCandidates.length > 1
+        ? distinctResults === 1
+            ? ` All ${executedCandidates.length} executed candidates agreed on the result.`
+            : ` Candidates disagreed: ${distinctResults} distinct results across ${executedCandidates.length} executed candidates — selected the highest-scoring.`
+        : '';
+    return {
+        selected,
+        notes: [
+            `Deep candidate selection reviewed ${candidates.length} candidate${candidates.length === 1 ? '' : 's'} and selected candidate ${selected.index} (${status}).${agreementNote}`,
+        ],
+    };
+}
+async function scoreDeepGeneratedProposalCandidate(input, candidate) {
+    const parsed = cloneParsedProposal(candidate.parsed);
+    if (parsed.sql)
+        parsed.sql = input.contextLedger.qualifySql(parsed.sql).sql;
+    let validationOk = false;
+    let validationError;
+    let result;
+    let executionError;
+    let score = parsed.sql ? 10 : -200;
+    if (parsed.sql) {
+        const validation = input.contextLedger.validateSql(parsed.sql, {
+            question: input.question,
+            intent: input.intent,
+        });
+        validationOk = validation.ok;
+        if (validation.ok) {
+            score += 100;
+            if (input.executeGeneratedSql) {
+                try {
+                    result = await input.executeGeneratedSql(parsed.sql);
+                    score += 40;
+                    if (result.rowCount > 0)
+                        score += 8;
+                    const resultShape = validateAnswerResultShape(input.questionPlan, result);
+                    score -= resultShape.warnings.length * 6;
+                    if (generatedResultShapeIsPartial(resultShape))
+                        score -= 120;
+                }
+                catch (error) {
+                    executionError = error instanceof Error ? error.message : String(error);
+                    score -= 20;
+                }
+            }
+        }
+        else {
+            validationError = validation.error;
+            score -= 100;
+        }
+        if (parsed.outputs?.length)
+            score += Math.min(6, parsed.outputs.length);
+    }
+    return {
+        raw: candidate.raw,
+        parsed,
+        index: candidate.index,
+        validationOk,
+        validationError,
+        result,
+        executionError,
+        resultSignature: result && !executionError ? resultEquivalenceSignature(result) : undefined,
+        score,
+    };
+}
+async function generateDeepAlternativeProposals(input) {
+    const previousSql = input.initial.parsed.sql
+        ? `\nInitial SQL candidate:\n\`\`\`sql\n${input.initial.parsed.sql}\n\`\`\``
+        : '';
+    // Diverse candidate styles (CHASE-SQL-style): each explores the solution space
+    // differently so execution-result agreement between styles is a strong signal.
+    const variants = [
+        'Create a second candidate that favors the most direct inspected relations and explicit joins.',
+        'Create a third candidate using QUERY-PLAN reasoning: first outline the grain, measures, dimensions, and join path as steps, then write SQL that follows that plan exactly.',
+        'Create a fourth candidate by DECOMPOSITION: break the question into sub-questions, solve each as a CTE, then compose the final SELECT — avoiding assumptions hidden in the first candidate.',
+    ];
+    const temperatures = [0.2, 0.35, 0.5];
+    const out = [];
+    for (const [index, instruction] of variants.entries()) {
+        try {
+            const raw = await input.provider.generate([
+                ...input.messages,
+                { role: 'assistant', content: input.initial.raw },
+                {
+                    role: 'user',
+                    content: [
+                        'Deep mode is allowed to compare multiple review-required SQL candidates before choosing one.',
+                        `Question: ${input.question}`,
+                        instruction,
+                        previousSql,
+                        'Return only one ```json fenced object with summary, sql, viz, outputs, and optional dql metadata fields.',
+                    ].filter(Boolean).join('\n\n'),
+                },
+            ], {
+                signal: input.signal,
+                reasoningEffort: input.reasoningEffort,
+                temperature: temperatures[index] ?? 0.4,
+            });
+            if (raw.trim())
+                out.push(raw);
+        }
+        catch {
+            // Alternative candidates are opportunistic; the initial candidate remains.
+        }
+    }
+    return out;
+}
+function cloneParsedProposal(proposal) {
+    return {
+        text: proposal.text,
+        ...(proposal.sql ? { sql: proposal.sql } : {}),
+        ...(proposal.viz ? { viz: proposal.viz } : {}),
+        ...(proposal.outputs?.length ? { outputs: proposal.outputs.slice() } : {}),
+        ...(proposal.proposedEntity ? { proposedEntity: proposal.proposedEntity } : {}),
+        ...(proposal.requestedFilters?.length ? { requestedFilters: proposal.requestedFilters.slice() } : {}),
+        ...(proposal.requestedDimensions?.length ? { requestedDimensions: proposal.requestedDimensions.slice() } : {}),
+    };
+}
+function resultEquivalenceSignature(result) {
+    const columns = result.columns.map((column) => String(column)).join('|');
+    const rows = result.rows.slice(0, 25).map((row) => stableResultRow(row)).join('\n');
+    return `${columns}\n${rows}`;
+}
+function stableResultRow(row) {
+    if (!row || typeof row !== 'object' || Array.isArray(row)) {
+        return JSON.stringify(row);
+    }
+    const record = row;
+    return JSON.stringify(Object.keys(record).sort().map((key) => [key, record[key]]));
+}
+function evidenceToolCallFromEvent(event, order) {
+    return {
+        name: event.name,
+        status: event.isError ? 'failed' : 'checked',
+        inputSummary: summarizeEvidencePayload(event.input),
+        outputSummary: summarizeEvidencePayload(event.output),
+        order,
+    };
+}
+function summarizeEvidencePayload(value, maxLength = 700) {
+    if (value === undefined)
+        return undefined;
+    let raw;
+    try {
+        raw = typeof value === 'string' ? value : JSON.stringify(value);
+    }
+    catch {
+        raw = String(value);
+    }
+    if (!raw)
+        return undefined;
+    const compact = raw.replace(/\s+/g, ' ').trim();
+    if (!compact)
+        return undefined;
+    return compact.length <= maxLength ? compact : `${compact.slice(0, maxLength - 3)}...`;
+}
 function isRetryableGeneratedSqlError(error) {
     return !/\b(read-only|readonly|select or with|unsafe|delete|insert|update|drop|alter|create|attach|copy|pragma)\b/i.test(error);
 }
@@ -3130,6 +3352,21 @@ function buildCertifiedEvidence(input) {
         .slice(0, 4);
     return {
         route: [
+            ...cascadeTraceToEvidenceRouteSteps(createCascadeTrace({
+                terminalLane: 'certified',
+                lanes: {
+                    certified: {
+                        label: `Lane 1 answered from certified ${input.artifact.kind.replace('_', ' ')}`,
+                        detail: input.artifact.name,
+                    },
+                    semantic: {
+                        label: 'Lane 2 semantic compile skipped because certified context already answered',
+                    },
+                    generated: {
+                        label: 'Lane 3 generated DQL artifact skipped because certified context already answered',
+                    },
+                },
+            })),
             {
                 tool: 'search_certified_artifacts',
                 status: 'selected',
@@ -3193,10 +3430,12 @@ function buildCertifiedEvidence(input) {
         sourceTables,
         semanticObjects,
         validation: {
-            status: input.executionError ? 'failed' : 'passed',
+            status: input.executionError ? 'failed' : input.resultShapeWarnings?.length ? 'warning' : 'passed',
             message: input.executionError
                 ? 'The certified artifact matched, but execution returned an error.'
-                : 'Certified artifact routing passed; no generated SQL was promoted.',
+                : input.resultShapeWarnings?.length
+                    ? `Certified artifact executed, but the result shape needs review: ${input.resultShapeWarnings.join(' ')}`
+                    : 'Certified artifact routing passed; no review-required DQL artifact was promoted.',
         },
         execution: executionEvidence(input.artifact, input.result, input.executionError, input.executorWasAvailable),
         citations: input.citations,
@@ -3219,8 +3458,35 @@ function buildGeneratedEvidence(input) {
     ]).slice(0, 6);
     const selectedAssets = uniqueAssets(selectedNodes.map(assetFromNode)).slice(0, 4);
     const selectedSemantic = input.activeTier === 'semantic_layer' && semanticObjects.length > 0;
+    const certifiedFitStep = certifiedFitEvidenceStep(input.contextPack);
+    const certifiedCandidateFitSteps = certifiedCandidateFitEvidenceSteps(input.contextPack);
     return {
         route: [
+            ...cascadeTraceToEvidenceRouteSteps(createCascadeTrace({
+                terminalLane: input.terminalLane,
+                lanes: {
+                    certified: {
+                        label: input.followUp?.kind === 'drilldown'
+                            ? 'Lane 1 checked for a distinct certified drilldown block'
+                            : 'Lane 1 checked certified blocks for exact answer fit',
+                    },
+                    semantic: {
+                        label: input.terminalLane === 'semantic'
+                            ? 'Lane 2 answered through semantic metric compile'
+                            : input.semanticHits.length > 0
+                                ? 'Lane 2 semantic context was checked but did not fully answer'
+                                : 'Lane 2 semantic context had no strong match',
+                        ...(input.terminalLane === 'semantic' && input.terminalDetail ? { detail: input.terminalDetail } : {}),
+                    },
+                    generated: {
+                        label: input.terminalLane === 'generated'
+                            ? 'Lane 3 prepared review-required DQL artifact with SQL preview'
+                            : 'Lane 3 generated SQL skipped because semantic compile answered',
+                        ...(input.terminalLane === 'generated' && input.terminalDetail ? { detail: input.terminalDetail } : {}),
+                    },
+                },
+            })),
+            ...cascadeBudgetEvidenceRouteSteps(input.budgetTrace),
             {
                 tool: 'search_certified_artifacts',
                 status: 'checked',
@@ -3231,6 +3497,8 @@ function buildGeneratedEvidence(input) {
                         : 'No certified artifact was strong enough for this question',
                 detail: input.followUp?.sourceBlockName,
             },
+            ...(certifiedFitStep ? [certifiedFitStep] : []),
+            ...certifiedCandidateFitSteps,
             {
                 tool: 'propose_drilldown',
                 status: input.followUp?.kind === 'drilldown' ? 'checked' : 'skipped',
@@ -3241,6 +3509,7 @@ function buildGeneratedEvidence(input) {
                     ? [...(input.followUp.filters ?? []), ...(input.followUp.dimensions ?? [])].join(', ')
                     : undefined,
             },
+            ...providerToolEvidenceRouteSteps(input.toolCalls),
             {
                 tool: 'search_business_context',
                 status: businessAssets.length > 0 ? 'checked' : 'skipped',
@@ -3269,7 +3538,7 @@ function buildGeneratedEvidence(input) {
             {
                 tool: 'validate_sql',
                 status: 'checked',
-                label: 'SQL is generated and requires host validation before certification',
+                label: 'SQL preview for DQL artifact requires host validation before certification',
             },
             {
                 tool: 'execute_generated_sql',
@@ -3281,10 +3550,10 @@ function buildGeneratedEvidence(input) {
                             ? 'skipped'
                             : 'skipped',
                 label: input.executionError
-                    ? 'Generated SQL preview failed'
+                    ? 'SQL preview failed'
                     : input.result
-                        ? 'Executed generated SQL as bounded preview'
-                        : 'Generated SQL preview not requested',
+                        ? 'Executed SQL preview for DQL artifact'
+                        : 'SQL preview not requested',
                 detail: input.executionError ?? (input.result ? `${input.result.rowCount} rows` : undefined),
             },
             {
@@ -3318,19 +3587,20 @@ function buildGeneratedEvidence(input) {
         selectedAssets,
         sourceTables,
         semanticObjects,
+        ...(input.toolCalls?.length ? { toolCalls: input.toolCalls } : {}),
         validation: {
             status: 'warning',
             message: input.followUp?.kind === 'drilldown'
-                ? 'Generated drilldown SQL is not certified. It should be validated, reviewed, and promoted only after analyst approval.'
-                : 'Generated SQL is not certified. It should be validated, reviewed, and promoted only after analyst approval.',
+                ? 'Review-required drilldown DQL artifact is not certified. Its SQL preview should be validated, reviewed, and promoted only after analyst approval.'
+                : 'Review-required DQL artifact is not certified. Its SQL preview should be validated, reviewed, and promoted only after analyst approval.',
         },
         execution: {
             status: input.executionError ? 'failed' : input.result ? 'executed' : 'not_requested',
             message: input.executionError
                 ? input.executionError
                 : input.result
-                    ? 'Executed generated SQL as an uncertified bounded preview.'
-                    : 'Generated SQL was returned for review; execution is handled by the host after validation.',
+                    ? 'Executed SQL preview as an uncertified bounded preview for the DQL artifact.'
+                    : 'Review-required DQL artifact was returned for review; SQL preview execution is handled by the host after validation.',
             rowCount: input.result?.rowCount,
             executionTime: input.result?.executionTime,
         },
@@ -3338,9 +3608,110 @@ function buildGeneratedEvidence(input) {
         analysisPlan: input.analysisPlan,
     };
 }
+function certifiedFitEvidenceStep(contextPack) {
+    const fit = contextPack?.routeDecision?.blockFit;
+    if (!fit)
+        return undefined;
+    const applicability = contextPack?.routeDecision?.certifiedApplicability;
+    const allowed = certifiedFitAllowsTier1(fit);
+    return {
+        tool: 'check_certified_fit',
+        status: allowed ? 'selected' : 'checked',
+        label: allowed
+            ? `Certified block fit passed${applicability?.name ? ` for ${applicability.name}` : ''}`
+            : `Certified block kept as context${applicability?.name ? `: ${applicability.name}` : ''}`,
+        detail: fit.reasons.length > 0
+            ? fit.reasons.join('; ')
+            : allowed
+                ? 'Certified block covers the requested answer contract.'
+                : 'Certified block did not prove an exact answer contract match.',
+    };
+}
+function certifiedCandidateFitEvidenceSteps(contextPack) {
+    const candidates = contextPack?.retrievalDiagnostics.certifiedCandidateFits ?? [];
+    return candidates
+        .slice(0, 4)
+        .map((candidate) => ({
+        tool: 'check_certified_candidate_fit',
+        status: candidate.action === 'certified_answer'
+            ? 'selected'
+            : 'checked',
+        label: certifiedCandidateFitLabel(candidate.name, candidate.action),
+        detail: [
+            `applicability=${candidate.applicabilityKind}`,
+            `fit=${candidate.fit.kind}/${candidate.fit.confidence}`,
+            candidate.fit.reasons.join('; '),
+        ].filter(Boolean).join(' | '),
+    }));
+}
+function certifiedCandidateFitLabel(name, action) {
+    switch (action) {
+        case 'certified_answer':
+            return `Certified candidate selected: ${name}`;
+        case 'context_only':
+            return `Certified candidate used as context only: ${name}`;
+        case 'eligible_not_selected':
+            return `Certified candidate fit passed but was not selected: ${name}`;
+        case 'rejected_for_fit':
+            return `Certified candidate rejected for answer fit: ${name}`;
+    }
+}
+function providerToolEvidenceRouteSteps(toolCalls) {
+    return (toolCalls ?? []).slice(0, 8).map((call) => ({
+        tool: call.name,
+        status: call.status,
+        label: call.status === 'failed'
+            ? `Provider tool failed: ${call.name}`
+            : `Provider tool observed: ${call.name}`,
+        detail: [
+            call.inputSummary ? `input=${truncateEvidenceDetail(call.inputSummary)}` : '',
+            call.outputSummary ? `output=${truncateEvidenceDetail(call.outputSummary)}` : '',
+        ].filter(Boolean).join(' | ') || undefined,
+    }));
+}
+function cascadeBudgetEvidenceRouteSteps(trace) {
+    if (!trace)
+        return [];
+    const { usage, limits } = trace;
+    const used = usage.laneRegroundAttemptsUsed + usage.laneExecutionAttemptsUsed + usage.engineEscalationsUsed;
+    if (used === 0)
+        return [];
+    return [{
+            tool: 'cascade_budget',
+            status: 'checked',
+            label: `Repair budget used: re-ground ${usage.laneRegroundAttemptsUsed}/${limits.lane.reground}, execution ${usage.laneExecutionAttemptsUsed}/${limits.lane.execution}`,
+            detail: `engine escalations ${usage.engineEscalationsUsed}/${limits.engineEscalations}`,
+        }];
+}
+function truncateEvidenceDetail(value, maxLength = 240) {
+    return value.length <= maxLength ? value : `${value.slice(0, maxLength - 3)}...`;
+}
 function buildNoAnswerEvidence(input) {
     return {
         route: [
+            ...cascadeTraceToEvidenceRouteSteps(createCascadeTrace({
+                terminalLane: 'refusal',
+                lanes: {
+                    certified: {
+                        label: input.artifactHits.length > 0
+                            ? 'Lane 1 certified blocks were checked but not selected'
+                            : 'Lane 1 found no certified block match',
+                    },
+                    semantic: {
+                        label: input.semanticHits.length > 0
+                            ? 'Lane 2 semantic context was checked but did not answer'
+                            : 'Lane 2 found no semantic match',
+                    },
+                    generated: {
+                        label: 'Lane 3 could not produce a validated review-required DQL artifact',
+                    },
+                    refusal: {
+                        label: 'Lane 4 returned an honest refusal or clarification',
+                        detail: input.reason,
+                    },
+                },
+            })),
+            ...cascadeBudgetEvidenceRouteSteps(input.budgetTrace),
             {
                 tool: 'search_certified_artifacts',
                 status: input.artifactHits.length > 0 ? 'checked' : 'skipped',
@@ -3361,6 +3732,7 @@ function buildNoAnswerEvidence(input) {
                 status: input.manifestHits.length > 0 ? 'checked' : 'skipped',
                 label: input.manifestHits.length > 0 ? 'dbt context considered' : 'No dbt match',
             },
+            ...providerToolEvidenceRouteSteps(input.toolCalls),
             {
                 tool: 'validate_sql',
                 status: 'failed',
@@ -3382,6 +3754,7 @@ function buildNoAnswerEvidence(input) {
         selectedAssets: [],
         sourceTables: uniqueAssets(input.manifestHits.map((hit) => assetFromNode(hit.node))).slice(0, 6),
         semanticObjects: uniqueAssets(input.semanticHits.map((hit) => assetFromNode(hit.node))).slice(0, 6),
+        ...(input.toolCalls?.length ? { toolCalls: input.toolCalls } : {}),
         validation: {
             status: 'failed',
             message: input.reason,
@@ -3431,7 +3804,7 @@ function schemaContextAssets(schemaContext) {
         nodeId: `runtime_schema:${table.relation}`,
         kind: 'runtime_schema',
         name: table.relation,
-        description: table.description ?? `${table.columns.length} runtime column${table.columns.length === 1 ? '' : 's'} available for generated SQL.`,
+        description: table.description ?? `${table.columns.length} runtime column${table.columns.length === 1 ? '' : 's'} available for DQL artifact SQL previews.`,
         sourceTier: 'project',
         certification: 'ai_generated',
         provenance: table.source ?? 'runtime information_schema',
@@ -3450,11 +3823,18 @@ function schemaCitations(schemaContext, limit) {
     }));
 }
 function certificationForNode(node) {
-    if (node.status === 'certified' || node.certification === 'certified')
+    const certification = node.certification;
+    if (node.status === 'certified' || certification === 'certified')
         return 'certified';
-    if (node.certification === 'analyst_review_required')
+    if (certification === 'reviewed' || node.status === 'review' || node.status === 'reviewed')
+        return 'reviewed';
+    if (certification === 'conflict')
+        return 'conflict';
+    if (certification === 'insufficient_context')
+        return 'insufficient_context';
+    if (certification === 'analyst_review_required')
         return 'analyst_review_required';
-    if (node.certification === 'ai_generated' || node.certification === 'uncertified')
+    if (certification === 'ai_generated' || certification === 'uncertified')
         return 'ai_generated';
     return undefined;
 }