@duckcodeailabs/dql-agent 1.6.5 → 1.6.7

package/dist/answer-loop.js

@@ -15,6 +15,7 @@
  * full pipeline.
  */
 import { buildSkillBlockHints, buildSkillsPrompt } from './skills/loader.js';
+import { validateSqlAgainstLocalContext } from './metadata/sql-context-validation.js';
 const CERTIFIED_HIT_THRESHOLD = 0.18;
 const HARD_NEGATIVE_RATIO = 0.5;
 const EXECUTABLE_ARTIFACT_KINDS = ['block', 'dashboard', 'app', 'notebook'];
@@ -40,7 +41,8 @@ export async function answer(input) {
     const semanticHits = kg.search({ query: question, domain, kinds: SEMANTIC_KINDS, limit: 12 });
     const manifestHits = kg.search({ query: question, domain, kinds: MANIFEST_KINDS, limit: 12 });
     const considered = mergeHits(artifactHits, semanticHits, manifestHits, kg.search({ query: question, domain, limit: 10 })).slice(0, 30);
-    const intent = classifyAgentIntent({
+    const catalogRoute = input.contextPack?.routeDecision;
+    const fallbackIntent = classifyAgentIntent({
         question,
         followUp: input.followUp,
         artifactHits,
@@ -48,19 +50,30 @@ export async function answer(input) {
         manifestHits,
         schemaContext: input.schemaContext ?? [],
     });
+    const 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 artifactHit = intent === 'exact_certified_lookup'
-        ? pickCertifiedArtifact({
-            artifactHits,
+    const drilldownCertifiedHit = input.followUp?.kind === 'drilldown'
+        ? pickCertifiedDrilldownArtifact({
             executableArtifactHits,
-            businessHits,
             question,
-            blockHints: input.followUp?.kind === 'drilldown' ? [] : effectiveBlockHints,
+            followUp: input.followUp,
             excludedArtifactIds,
             kg,
         })
         : null;
+    const artifactHit = drilldownCertifiedHit ?? (shouldUseCertifiedRoute(catalogRoute, intent)
+        ? certifiedHitFromContextPack(input.contextPack, kg)
+            ?? pickCertifiedArtifact({
+                artifactHits,
+                executableArtifactHits,
+                businessHits,
+                question,
+                blockHints: input.followUp?.kind === 'drilldown' ? [] : effectiveBlockHints,
+                excludedArtifactIds,
+                kg,
+            })
+        : null);
     if (artifactHit) {
         let result;
         let executionError;
@@ -89,7 +102,7 @@ export async function answer(input) {
         const analysisPlan = buildAnalysisPlan({
             question,
             intent,
-            routeReason: 'The question matched a certified DQL artifact closely enough to answer without generating new SQL.',
+            routeReason: catalogRoute?.reason ?? 'The question matched a certified DQL artifact closely enough to answer without generating new SQL.',
             selectedNodes: [artifactHit.node],
             schemaContext: input.schemaContext ?? [],
             sql: result?.sql,
@@ -107,6 +120,10 @@ export async function answer(input) {
             result,
             executionError,
             sql: result?.sql,
+            trustLabel: input.contextPack?.trustLabel ?? 'certified',
+            sourceCertifiedBlock: artifactHit.node.kind === 'block' ? artifactHit.node.name : undefined,
+            contextPackId: input.contextPack?.id,
+            selectedEvidence: input.contextPack?.evidenceRoles?.slice(0, 12),
             citations,
             memoryContext: input.memoryContext,
             analysisPlan,
@@ -124,19 +141,22 @@ export async function answer(input) {
                 memoryContext: input.memoryContext ?? [],
                 analysisPlan,
             }),
+            contextPack: input.contextPack,
             considered,
             providerUsed: provider.name,
         };
     }
-    if (intent === 'clarify') {
-        const text = composeClarificationText(question, considered, input.schemaContext ?? []);
+    if (intent === 'clarify' || catalogRoute?.route === 'clarify') {
+        const text = composeCatalogClarificationText(question, catalogRoute) ?? composeClarificationText(question, considered, input.schemaContext ?? []);
         const analysisPlan = buildAnalysisPlan({
             question,
             intent,
-            routeReason: 'No certified artifact, semantic object, dbt/source table, or runtime schema match was strong enough to safely generate SQL.',
+            routeReason: catalogRoute?.reason ?? 'No certified artifact, semantic object, dbt/source table, or runtime schema match was strong enough to safely generate SQL.',
             selectedNodes: considered.slice(0, 4).map((hit) => hit.node),
             schemaContext: input.schemaContext ?? [],
-            assumptions: ['Need a clearer business object, measure, or grain before querying.'],
+            assumptions: catalogRoute?.missingContext.length
+                ? catalogRoute.missingContext.map((item) => item.message)
+                : ['Need a clearer business object, measure, or grain before querying.'],
         });
         return {
             kind: 'no_answer',
@@ -160,17 +180,18 @@ export async function answer(input) {
                 memoryContext: input.memoryContext ?? [],
                 analysisPlan,
             }),
+            contextPack: input.contextPack,
             considered,
             providerUsed: provider.name,
         };
     }
     // Stage 2/3: generate only after certified artifacts miss. Semantic context
     // wins over raw dbt manifest context; memory is appended last as advisory.
-    const activeTier = semanticHits.length > 0
+    const activeTier = sourceTierFromContextPack(input.contextPack) ?? (semanticHits.length > 0
         ? 'semantic_layer'
         : manifestHits.length > 0
             ? 'dbt_manifest'
-            : 'dbt_manifest';
+            : 'dbt_manifest');
     const reviewRequiredArtifactHits = artifactHits
         .filter((hit) => hit.score >= CERTIFIED_HIT_THRESHOLD && !isCertifiedHit(hit, kg))
         .slice(0, 4);
@@ -192,13 +213,19 @@ export async function answer(input) {
         messages.push({ role: 'system', content: skillsPrompt });
     messages.push({
         role: 'system',
-        content: renderContextPrompt(contextBlocks, contextBusiness, contextOther, activeTier, input.memoryContext ?? [], input.extraContext, input.followUp, input.schemaContext ?? [], intent),
+        content: renderContextPrompt(contextBlocks, contextBusiness, contextOther, activeTier, input.memoryContext ?? [], input.extraContext, input.followUp, input.schemaContext ?? [], intent, input.contextPack),
     });
     messages.push({ role: 'user', content: question });
     const localProposal = buildSchemaAwareProposal({
         question,
         intent,
         schemaContext: input.schemaContext ?? [],
+        followUp: input.followUp,
+        contextPack: input.contextPack,
+    }) ?? buildContextPackAwareProposal({
+        question,
+        intent,
+        contextPack: input.contextPack,
     });
     let proposed = '';
     let parsed;
@@ -231,6 +258,7 @@ export async function answer(input) {
                     considered,
                     memoryContext: input.memoryContext ?? [],
                 }),
+                contextPack: input.contextPack,
                 considered,
                 providerUsed: provider.name,
             };
@@ -259,11 +287,67 @@ export async function answer(input) {
                 considered,
                 memoryContext: input.memoryContext ?? [],
             }),
+            contextPack: input.contextPack,
             considered,
             providerUsed: provider.name,
         };
     }
+    const contextValidation = validateSqlAgainstLocalContext(parsed.sql, input.contextPack, {
+        question,
+        intent,
+        filterValues: input.followUp?.filters,
+    });
+    if (!contextValidation.ok) {
+        const text = `I could not safely prepare this generated SQL from the inspected context. ${contextValidation.error}`;
+        const analysisPlan = buildAnalysisPlan({
+            question,
+            intent,
+            routeReason: catalogRoute?.reason ?? 'Generated SQL failed metadata context validation before preview execution or draft capture.',
+            selectedNodes: contextNodes,
+            schemaContext: input.schemaContext ?? [],
+            sql: parsed.sql,
+            suggestedViz: parsed.viz ?? 'table',
+            assumptions: [
+                'Generated SQL was rejected before execution because it did not match inspected metadata context.',
+                ...contextValidation.warnings,
+            ],
+        });
+        return {
+            kind: 'no_answer',
+            sourceTier: 'no_answer',
+            certification: 'analyst_review_required',
+            reviewStatus: 'none',
+            confidence: 0.15,
+            text,
+            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,
+            selectedEvidence: input.contextPack?.evidenceRoles?.slice(0, 12),
+            citations: [],
+            memoryContext: input.memoryContext,
+            analysisPlan,
+            evidence: buildNoAnswerEvidence({
+                question,
+                reason: contextValidation.error,
+                artifactHits,
+                businessHits,
+                semanticHits,
+                manifestHits,
+                considered,
+                memoryContext: input.memoryContext ?? [],
+                analysisPlan,
+            }),
+            contextPack: input.contextPack,
+            considered,
+            providerUsed: localProposal ? 'schema_planner' : provider.name,
+        };
+    }
     const generatedCitations = [
+        ...contextPackCitations(input.contextPack, 4),
         ...contextNodes.slice(0, 4).map((n) => ({
             nodeId: n.nodeId,
             kind: n.kind,
@@ -334,33 +418,74 @@ export async function answer(input) {
     const analysisPlan = buildAnalysisPlan({
         question,
         intent,
-        routeReason: intent === 'drillthrough'
+        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 question asks for a custom analysis, ranking, breakdown, comparison, or grain that should not be answered by a loose certified block match.',
+            : '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: input.schemaContext ?? [],
         sql: parsed.sql,
         suggestedViz: parsed.viz ?? 'table',
         assumptions: [
             'Generated SQL is an uncertified preview until an analyst reviews and promotes it.',
-            ...(localProposal ? ['A schema-aware local planner selected the customer ranking grain before provider generation.'] : []),
+            ...(localProposal ? ['A local metadata planner selected a review-required SQL grain before provider generation.'] : []),
             ...(executionError ? ['The preview execution error must be reviewed before reuse.'] : []),
         ],
         repairAttempts,
     });
+    const validationWarnings = [
+        ...(input.contextPack?.warnings ?? []),
+        ...(executionError ? ['The preview execution error must be reviewed before reuse.'] : []),
+    ];
+    let draftBlock;
+    let draftCaptureError;
+    if (input.captureGeneratedDraft && parsed.sql) {
+        try {
+            draftBlock = await input.captureGeneratedDraft({
+                question,
+                sql: parsed.sql,
+                intent,
+                followUp: input.followUp,
+                contextPack: input.contextPack,
+                sourceBlock: followUpSourceBlock ?? undefined,
+                validationWarnings,
+            });
+        }
+        catch (err) {
+            draftCaptureError = err instanceof Error ? err.message : String(err);
+            validationWarnings.push(`Draft capture failed: ${draftCaptureError}`);
+        }
+    }
+    const sourceCertifiedBlock = followUpSourceBlock?.name ?? input.followUp?.sourceBlockName;
+    const trustExplanation = generatedTrustExplanation({
+        followUp: input.followUp,
+        sourceCertifiedBlock,
+        draftBlock,
+    });
+    const cleanedSummary = cleanGeneratedSummary(parsed.text);
+    const generatedText = trustExplanation
+        ? [trustExplanation, cleanedSummary].filter(Boolean).join('\n\n')
+        : cleanedSummary;
     return {
         kind: 'uncertified',
         sourceTier: activeTier,
         certification: 'ai_generated',
         reviewStatus: 'draft_ready',
         confidence: activeTier === 'semantic_layer' ? 0.72 : 0.55,
-        text: parsed.text,
-        answer: parsed.text,
+        text: generatedText,
+        answer: generatedText,
         proposedSql: parsed.sql,
         sql: parsed.sql,
         result,
         executionError,
         suggestedViz: parsed.viz ?? 'table',
+        draftBlock,
+        draftBlockId: draftBlock?.path,
+        promoteCommand: draftBlock ? `dql certify --from-draft ${draftBlock.path}` : undefined,
+        trustLabel: input.contextPack?.trustLabel,
+        sourceCertifiedBlock,
+        contextPackId: input.contextPack?.id,
+        validationWarnings,
+        selectedEvidence: input.contextPack?.evidenceRoles?.slice(0, 12),
         citations: generatedCitations,
         memoryContext: input.memoryContext,
         analysisPlan,
@@ -382,6 +507,7 @@ export async function answer(input) {
             executorWasAvailable: Boolean(input.executeGeneratedSql),
             analysisPlan,
         }),
+        contextPack: input.contextPack,
         considered,
         providerUsed: localProposal ? 'schema_planner' : provider.name,
     };
@@ -409,8 +535,11 @@ 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.`;
-function renderContextPrompt(blocks, businessContext, others, activeTier, memoryContext, extraContext, followUp, schemaContext = [], intent = 'ad_hoc_analysis') {
+   clarifying question instead of guessing.
+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.`;
+function renderContextPrompt(blocks, businessContext, others, activeTier, memoryContext, extraContext, followUp, schemaContext = [], intent = 'ad_hoc_analysis', contextPack) {
     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.'}`;
@@ -458,7 +587,146 @@ function renderContextPrompt(blocks, businessContext, others, activeTier, memory
     const followUpSection = followUp
         ? `\n\n## Follow-up routing context\n\n${renderFollowUpContext(followUp)}`
         : '';
-    return `${intentSection}\n\n${blockSection}${businessSection}${otherSection}${schemaSection}${memorySection}${extraSection}${followUpSection}`;
+    const contextPackSection = contextPack
+        ? `\n\n## Local metadata context pack\n\n${renderContextPackForPrompt(contextPack)}`
+        : '';
+    return `${intentSection}\n\n${blockSection}${businessSection}${otherSection}${schemaSection}${contextPackSection}${memorySection}${extraSection}${followUpSection}`;
+}
+function renderContextPackForPrompt(contextPack) {
+    const warnings = contextPack.warnings.length
+        ? `Warnings:\n${contextPack.warnings.slice(0, 8).map((warning) => `- ${warning}`).join('\n')}\n`
+        : '';
+    const objects = contextPack.objects.slice(0, 18).map((object) => {
+        const detail = [
+            object.objectType,
+            object.domain ? `domain: ${object.domain}` : '',
+            object.status ? `status: ${object.status}` : '',
+            object.description ? `description: ${object.description}` : '',
+        ].filter(Boolean).join('; ');
+        return `- ${object.objectKey} (${detail})`;
+    }).join('\n');
+    const conflicts = contextPack.retrievalDiagnostics.candidateConflicts.length
+        ? `\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}\nMissing context: ${contextPack.routeDecision.missingContext.map((item) => item.message).join(' ') || 'none'}`
+        : '';
+    const allowed = contextPack.allowedSqlContext?.relations.length
+        ? `\nAllowed SQL relations:\n${contextPack.allowedSqlContext.relations.slice(0, 12).map((relation) => `- ${relation.relation}: ${relation.columns.slice(0, 24).map((column) => column.name).join(', ') || '(columns unavailable)'}`).join('\n')}`
+        : '';
+    return [
+        `context_pack_id: ${contextPack.id}`,
+        `trust_label: ${contextPack.trustLabel}`,
+        route.trim(),
+        warnings.trim(),
+        `Selected evidence:\n${objects || '- none'}`,
+        allowed.trim(),
+        conflicts.trim(),
+    ].filter(Boolean).join('\n');
+}
+function contextPackCitations(contextPack, limit) {
+    if (!contextPack)
+        return [];
+    return contextPack.objects.slice(0, limit).map((object) => ({
+        nodeId: object.objectKey,
+        kind: metadataObjectKindForCitation(object.objectType),
+        name: object.name,
+        sourceTier: metadataObjectSourceTier(object.objectType),
+        provenance: object.sourceSystem,
+    }));
+}
+function agentIntentFromCatalogRoute(route) {
+    if (route.route === 'clarify')
+        return 'clarify';
+    if (route.route === 'certified')
+        return route.intent === 'definition_lookup' ? 'definition_lookup' : 'exact_certified_lookup';
+    return route.intent;
+}
+function shouldUseCertifiedRoute(route, intent) {
+    if (route)
+        return route.route === 'certified';
+    return intent === 'exact_certified_lookup' || intent === 'definition_lookup';
+}
+function certifiedHitFromContextPack(contextPack, kg) {
+    const key = contextPack?.routeDecision.exactObjectKey;
+    if (!key)
+        return null;
+    const object = contextPack.objects.find((item) => item.objectKey === key);
+    if (!object)
+        return null;
+    const nodeId = object.objectType === 'dql_block'
+        ? `block:${object.name}`
+        : object.objectType === 'dql_term'
+            ? `term:${object.name}`
+            : object.objectType === 'business_view'
+                ? `business_view:${object.name}`
+                : undefined;
+    const node = nodeId ? kg.getNode(nodeId) : null;
+    return node ? { node, score: 1, snippet: object.snippet } : null;
+}
+function composeCatalogClarificationText(question, route) {
+    if (!route?.missingContext.length)
+        return undefined;
+    const missing = route.missingContext.map((item) => item.message).join(' ');
+    const followUp = route.followUps[0] ? ` ${route.followUps[0]}?` : '';
+    return `I need one more detail before querying "${question}". ${missing}${followUp}`;
+}
+function sourceTierFromContextPack(contextPack) {
+    if (!contextPack)
+        return undefined;
+    if (contextPack.objects.some((object) => object.objectType === 'semantic_metric'))
+        return 'semantic_layer';
+    if (contextPack.objects.some((object) => object.objectType.startsWith('dbt_') || object.objectType === 'warehouse_table' || object.objectType === 'runtime_table'))
+        return 'dbt_manifest';
+    if (contextPack.objects.some((object) => object.objectType === 'dql_term' || object.objectType === 'business_view'))
+        return 'business_context';
+    if (contextPack.objects.some((object) => object.objectType === 'dql_block'))
+        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';
+    if (objectType === 'dql_term')
+        return 'term';
+    if (objectType === 'business_view')
+        return 'business_view';
+    if (objectType === 'semantic_metric')
+        return 'metric';
+    if (objectType === 'semantic_dimension')
+        return 'dimension';
+    if (objectType === 'dbt_model')
+        return 'dbt_model';
+    if (objectType === 'dbt_source' || objectType === 'warehouse_table')
+        return 'dbt_source';
+    if (objectType === 'notebook')
+        return 'notebook';
+    if (objectType === 'dashboard')
+        return 'dashboard';
+    if (objectType === 'app')
+        return 'app';
+    return 'runtime_schema';
+}
+function metadataObjectSourceTier(objectType) {
+    if (objectType === 'dql_block')
+        return 'certified_artifact';
+    if (objectType === 'dql_term' || objectType === 'business_view')
+        return 'business_context';
+    if (objectType.startsWith('semantic_'))
+        return 'semantic_layer';
+    if (objectType.startsWith('dbt_') || objectType === 'warehouse_table')
+        return 'dbt_manifest';
+    return 'business_context';
 }
 function renderFollowUpContext(followUp) {
     const parts = [
@@ -474,6 +742,30 @@ function renderFollowUpContext(followUp) {
         : 'routing rule: reuse the prior certified block when the user asks a generic follow-up.';
     return [...parts, rule].join('\n');
 }
+function generatedTrustExplanation(input) {
+    if (input.followUp?.kind !== 'drilldown')
+        return undefined;
+    const source = input.sourceCertifiedBlock
+        ? ` I used the certified \`${input.sourceCertifiedBlock}\` block for the business definition,`
+        : ' I used certified context where available,';
+    const filters = [
+        ...(input.followUp.filters ?? []),
+        ...(input.followUp.dimensions ?? []),
+    ];
+    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}`;
+}
+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 generate[^.]*\.\s*/gi, ' ')
+        .trim();
+}
 /**
  * Public for tests. Pulls the first ```sql block and an optional Viz: line
  * out of an LLM response.
@@ -491,8 +783,12 @@ export function parseProposal(raw) {
     return { text, sql, viz };
 }
 function buildSchemaAwareProposal(input) {
-    if (input.intent !== 'ad_hoc_analysis' && input.intent !== 'drillthrough')
+    if (!isGeneratedAgentIntent(input.intent))
         return undefined;
+    const schemaContext = schemaContextWithAllowedSqlContext(input.schemaContext, input.contextPack);
+    const drilldownProposal = buildMatchedEntityDrilldownProposal({ ...input, schemaContext });
+    if (drilldownProposal)
+        return drilldownProposal;
     if (isFilteredEntityQuestion(input.question))
         return undefined;
     const lower = input.question.toLowerCase();
@@ -501,7 +797,7 @@ function buildSchemaAwareProposal(input) {
         && !/\b(order details|specific orders|each order|all orders|order line|line item)\b/.test(lower);
     if (!asksForCustomerPerformance)
         return undefined;
-    const customers = findSchemaTable(input.schemaContext, ['customers', 'customer']);
+    const customers = findSchemaTable(schemaContext, ['customers', 'customer']);
     if (!customers)
         return undefined;
     const customerName = findSchemaColumn(customers, ['customer_name', 'name', 'full_name']);
@@ -523,7 +819,7 @@ function buildSchemaAwareProposal(input) {
         };
     }
     const customerId = findSchemaColumn(customers, ['customer_id', 'id']);
-    const orders = findSchemaTable(input.schemaContext, ['orders', 'order']);
+    const orders = findSchemaTable(schemaContext, ['orders', 'order']);
     if (!orders || !customerName || !customerId)
         return undefined;
     const orderCustomerId = findSchemaColumn(orders, ['customer_id', 'customer']);
@@ -548,6 +844,341 @@ function buildSchemaAwareProposal(input) {
         viz: 'table',
     };
 }
+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)
+        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',
+    };
+}
+function schemaContextWithAllowedSqlContext(schemaContext, contextPack) {
+    const byRelation = new Map();
+    for (const table of schemaContext) {
+        byRelation.set(normalizeRelationKey(table.relation), {
+            ...table,
+            columns: table.columns.map((column) => ({ ...column, sampleValues: column.sampleValues?.slice() })),
+        });
+    }
+    for (const relation of contextPack?.allowedSqlContext?.relations ?? []) {
+        const key = normalizeRelationKey(relation.relation);
+        const existing = byRelation.get(key);
+        if (!existing) {
+            byRelation.set(key, {
+                relation: relation.relation,
+                name: relation.name,
+                columns: relation.columns.map((column) => ({
+                    name: column.name,
+                    type: column.type,
+                    description: column.description,
+                    sampleValues: column.sampleValues?.slice(),
+                })),
+                source: relation.source,
+            });
+            continue;
+        }
+        const columns = new Map(existing.columns.map((column) => [column.name.toLowerCase(), column]));
+        for (const column of relation.columns) {
+            const existingColumn = columns.get(column.name.toLowerCase());
+            if (!existingColumn) {
+                existing.columns.push({
+                    name: column.name,
+                    type: column.type,
+                    description: column.description,
+                    sampleValues: column.sampleValues?.slice(),
+                });
+                continue;
+            }
+            existingColumn.sampleValues = uniqueDrilldownStrings([
+                ...(existingColumn.sampleValues ?? []),
+                ...(column.sampleValues ?? []),
+            ]).slice(0, 8);
+            existingColumn.type ??= column.type;
+            existingColumn.description ??= column.description;
+        }
+    }
+    return Array.from(byRelation.values());
+}
+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();
+}
+function namesEqualLoose(a, b) {
+    return cleanSqlIdentifier(a).replace(/[_-]+/g, ' ').toLowerCase() === cleanSqlIdentifier(b).replace(/[_-]+/g, ' ').toLowerCase();
+}
+function normalizeRelationKey(relation) {
+    return relation.replace(/["`]/g, '').replace(/\s*\.\s*/g, '.').toLowerCase().trim();
+}
+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 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 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()));
@@ -588,7 +1219,7 @@ function pickCertifiedArtifact(input) {
     // 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') {
+        if (node && node.status === 'certified' && hasCompatibleCertifiedBlockMatch(input.question, node)) {
             return { node, score: 1, snippet: undefined };
         }
     }
@@ -628,12 +1259,46 @@ function pickFirstCertifiedHit(hits, kg, excludedNodeIds, question) {
             continue;
         if (!isCertifiedHit(hit, kg))
             continue;
-        if (question && hit.node.kind === 'block' && !hasMeaningfulCertifiedBlockSignal(question, hit.node))
+        if (question && hit.node.kind === 'block' && !hasCompatibleCertifiedBlockMatch(question, hit.node))
             continue;
         return hit;
     }
     return null;
 }
+function pickCertifiedDrilldownArtifact(input) {
+    const requestedTerms = meaningfulTokens([
+        input.question,
+        ...(input.followUp.filters ?? []),
+        ...(input.followUp.dimensions ?? []),
+    ].join(' '));
+    for (const hit of input.executableArtifactHits) {
+        if (hit.score < CERTIFIED_HIT_THRESHOLD)
+            break;
+        if (input.excludedArtifactIds?.has(hit.node.nodeId))
+            continue;
+        if (hit.node.kind !== 'block')
+            continue;
+        if (!isCertifiedHit(hit, input.kg))
+            continue;
+        if (!hasCompatibleCertifiedBlockMatch(input.question, hit.node))
+            continue;
+        if (!hasRequestedDrilldownOverlap(hit.node, requestedTerms))
+            continue;
+        return hit;
+    }
+    return null;
+}
+function hasRequestedDrilldownOverlap(node, requestedTerms) {
+    if (requestedTerms.size === 0)
+        return false;
+    const nodeTerms = meaningfulTokens(certifiedBlockSignalText(node));
+    let overlaps = 0;
+    for (const term of requestedTerms) {
+        if (nodeTerms.has(term))
+            overlaps += 1;
+    }
+    return overlaps >= 2 || (requestedTerms.size === 1 && overlaps === 1);
+}
 function shouldDeferCertifiedArtifactForReviewPath(input) {
     if (!isBreakdownOrDrilldownQuestion(input.question))
         return false;
@@ -711,6 +1376,44 @@ function hasMeaningfulCertifiedBlockSignal(question, node) {
     }
     return false;
 }
+function hasCompatibleCertifiedBlockMatch(question, node) {
+    return hasMeaningfulCertifiedBlockSignal(question, node)
+        && hasCompatibleRankingDirection(question, node);
+}
+function hasCompatibleRankingDirection(question, node) {
+    const questionDirection = rankingDirectionFromText(question);
+    if (!questionDirection)
+        return true;
+    const blockDirection = rankingDirectionFromText(certifiedBlockSignalText(node));
+    if (!blockDirection)
+        return true;
+    return questionDirection === blockDirection;
+}
+function rankingDirectionFromText(text) {
+    const lower = text.toLowerCase();
+    const hasBottomSignal = /\b(bottom|least|fewest|lowest|minimum|min|smallest|worst|underperform(?:ing|ed|er|ers)?)\b/.test(lower);
+    const hasTopSignal = /\b(top|most|highest|maximum|max|greatest|best|leader|leaders|leading)\b/.test(lower);
+    if (hasBottomSignal && !hasTopSignal)
+        return 'bottom';
+    if (hasTopSignal && !hasBottomSignal)
+        return 'top';
+    return undefined;
+}
+function certifiedBlockSignalText(node) {
+    const examples = (node.examples ?? [])
+        .flatMap((example) => [example.question, example.sql ?? '']);
+    return [
+        node.name,
+        node.domain ?? '',
+        node.description ?? '',
+        node.llmContext ?? '',
+        node.provenance ?? '',
+        ...(node.tags ?? []),
+        ...(node.businessRules ?? []),
+        ...(node.caveats ?? []),
+        ...examples,
+    ].join(' ');
+}
 function hasExactExecutableArtifactSignal(question, node) {
     if (!EXECUTABLE_ARTIFACT_KINDS.includes(node.kind))
         return false;
@@ -876,7 +1579,7 @@ function isAdHocAnalysisQuestion(question) {
     const lower = question.toLowerCase();
     if (isBusinessDefinitionQuestion(question))
         return false;
-    return /\b(break\s*down|breakdown|drill\s*(?:down|into)|slice|segment|split|compare|versus|vs\.?|trend|over time|top|bottom|best|worst|highest|lowest|rank|ranking|performed better|better performing|why|what drove|driver|drivers|top movers?|changed?|change|dropped?|drop|decreased?|decrease|declined?|decline|increased?|increase|anomal(?:y|ies)|exceptions?|root cause|contribut(?:e|ed|ion)|variance|delta|by\s+[a-z][\w\s-]{1,40})\b/i.test(lower)
+    return /\b(break\s*down|breakdown|drill\s*(?:down|into)|slice|segment|split|compare|versus|vs\.?|trend|over time|top|bottom|best|worst|highest|lowest|least|fewest|minimum|min|smallest|rank|ranking|performed better|better performing|why|what drove|driver|drivers|top movers?|changed?|change|dropped?|drop|decreased?|decrease|declined?|decline|increased?|increase|anomal(?:y|ies)|exceptions?|root cause|contribut(?:e|ed|ion)|variance|delta|by\s+[a-z][\w\s-]{1,40})\b/i.test(lower)
         || /\b(show|list|find|give)\b.+\b(account|accounts|customer|customers|product|products|order|orders|region|location|month|week|day|user|users)\b/i.test(lower);
 }
 function isFilteredEntityQuestion(question) {