@duckcodeailabs/dql-agent 1.7.1 → 1.8.0

package/dist/metadata/analysis-planner.js

@@ -15,7 +15,7 @@ const METRIC_WORDS = [
 const DIMENSION_WORDS = [
     'account', 'category', 'channel', 'cohort', 'customer', 'department', 'entity', 'geo',
     'location', 'market', 'merchant', 'month', 'person', 'player', 'product', 'profile',
-    'region', 'segment', 'sku', 'team', 'type', 'user', 'vendor', 'week', 'year',
+    'region', 'segment', 'sku', 'supply', 'team', 'type', 'user', 'vendor', 'week', 'year',
 ];
 /**
  * Small, domain-neutral vocabulary clusters used only to broaden metadata
@@ -44,21 +44,25 @@ const PROFILE_WORDS = [
 export function buildAnalysisQuestionPlan(question, followUp) {
     const cleanQuestion = question.replace(/\s+/g, ' ').trim();
     const normalizedQuestion = normalizeSearchText(cleanQuestion);
-    const lower = cleanQuestion.toLowerCase();
+    // Stakeholders occasionally paste semantic/dbt identifiers directly. Treat
+    // underscores as word boundaries for intent extraction while retaining the
+    // original question for exact output identifiers and auditability.
+    const languageQuestion = cleanQuestion.replace(/_/g, ' ');
+    const lower = languageQuestion.toLowerCase();
     const entities = extractEntities(cleanQuestion);
-    const metricTerms = uniqueStrings([
-        ...extractMetricTerms(cleanQuestion),
-        ...extractFollowUpMetricTerms(followUp, lower),
-    ]);
-    const extractedDimensionTerms = extractDimensionTerms(cleanQuestion);
-    const filterTerms = extractFilterTerms(cleanQuestion, entities);
-    const dimensionTerms = removeFilterOnlyDimensionTerms(cleanQuestion, extractedDimensionTerms);
-    const timeTerms = extractTimeTerms(cleanQuestion);
+    const valueMentions = extractValueMentions(entities);
+    const metricTerms = resolveQuestionMetricTerms(lower, extractMetricTerms(languageQuestion), extractFollowUpMetricTerms(followUp, lower));
+    const extractedDimensionTerms = extractDimensionTerms(languageQuestion);
+    const filterTerms = extractFilterTerms(languageQuestion, entities);
+    const dimensionTerms = removeFilterOnlyDimensionTerms(languageQuestion, extractedDimensionTerms);
+    const timeTerms = extractTimeTerms(languageQuestion);
     const mode = inferQuestionMode({ question: cleanQuestion, lower, entities, metricTerms, dimensionTerms, followUp });
     const routeIntent = routeIntentForMode(mode);
     const outputShape = outputShapeForMode(mode, lower, dimensionTerms);
-    const shouldConsiderCertifiedExact = certifiedExactIsPlausible(mode, entities)
-        && !(mode === 'general_analysis' && definitionPhraseCarriesAnalyticalShape({ lower, metricTerms, dimensionTerms }));
+    // Certified capability matching is contract-first. An explicit analytical
+    // shape ("lifetime spend by customer") is a reason to reject a definition
+    // term, not a reason to skip a fully compatible certified block.
+    const shouldConsiderCertifiedExact = certifiedExactIsPlausible(mode, entities);
     const needsGeneratedSql = generatedSqlIsLikely(mode, shouldConsiderCertifiedExact);
     const needsResearchWorkspace = researchWorkspaceIsLikely(mode, lower);
     const requestedShape = buildRequestedAnswerShape(cleanQuestion, {
@@ -96,6 +100,7 @@ export function buildAnalysisQuestionPlan(question, followUp) {
         mode,
         routeIntent,
         entities,
+        valueMentions,
         metricTerms,
         dimensionTerms,
         filterTerms,
@@ -125,7 +130,7 @@ export function certifiedApplicabilityForObject(object, plan) {
     const dimensionMatch = scoreTerms(text, plan.dimensionTerms);
     const searchMatch = scoreTerms(text, plan.searchTerms);
     const directionCompatible = rankingDirectionCompatible(plan.question, directionalTextForObject(object));
-    const asksDifferentGrain = plan.needsGeneratedSql || plan.entities.length > 0 || plan.mode === 'entity_profile';
+    const asksDifferentGrain = plan.entities.length > 0 || plan.mode === 'entity_profile';
     const score = Number(((explicitName ? 45 : 0) +
         (exactExample ? 55 : 0) +
         metricMatch.score * 12 +
@@ -463,20 +468,19 @@ function isMetricLikeColumn(column) {
 }
 function inferQuestionMode(input) {
     const { lower } = input;
+    // A relative measure predicate is not an ordinary entity drilldown. It asks for
+    // a peer set whose aggregate is compared with a named entity's aggregate (for
+    // example, "customers who paid less tax than Melissa"). Classify it before the
+    // conversation drilldown carry so a prior certified block cannot turn the ask
+    // into a simple equality filter or a single global KPI.
+    if (isEntityRelativeMeasureComparison(lower))
+        return 'comparison';
     if (followUpKind(input.followUp) === 'drilldown')
         return 'entity_drilldown';
     if (/^\s*(run|execute|open)\b/i.test(lower))
         return 'exact_lookup';
     if (/\b(trust|rely|certif|certified|lineage|owner|caveat|gap|governance|can .* trust)\b/i.test(lower))
         return 'trust_review';
-    // "What is" is not, by itself, a definition request. Questions such as
-    // "what is revenue by customer and product?" carry an explicit analytical
-    // shape and must reach the data cascade. Keep genuine single-concept meaning
-    // questions on the fast definition path while treating multi-dimensional or
-    // explicitly grouped measure requests as analysis (AGT-001).
-    if (/\b(define|definition|meaning of|what is|what are|what does .+ mean)\b/i.test(lower)
-        && !definitionPhraseCarriesAnalyticalShape(input))
-        return 'definition';
     if (/\b(anomal|exception|outlier|spike|dip)\b/i.test(lower))
         return 'anomaly';
     if (/\b(compare|versus|vs\.?|cohort)\b/i.test(lower))
@@ -485,19 +489,33 @@ function inferQuestionMode(input) {
         return 'diagnose_change';
     if (/\b(driver|drivers|drove|break\s*down|breakdown|contribute|contribution|top movers?)\b/i.test(lower))
         return 'driver_breakdown';
+    if (/\b(top|bottom|best|worst|highest|lowest|least|fewest|minimum|min|maximum|max|rank|ranking|most|leading|leader|leaders)\b/i.test(lower)
+        || hasComparativeMetricRanking(lower))
+        return 'ranking';
     if (/\b(profile|overview|360|complete\s+(?:stats|statistics|view)|full\s+(?:stats|statistics|view)|all\s+(?:stats|statistics|metrics)|research|reserach)\b/i.test(lower))
         return 'entity_profile';
-    if (input.entities.length > 0 && (input.metricTerms.length > 0 || /\b(show|list|find|give|provide|performance|activity|history|details)\b/i.test(lower)))
-        return 'entity_drilldown';
     if (/\b(trend|over time|by\s+(?:day|week|month|quarter|year|season)|daily|weekly|monthly|quarterly|yearly)\b/i.test(lower))
         return 'trend';
-    if (/\b(top|bottom|best|worst|highest|lowest|least|fewest|minimum|min|maximum|max|rank|ranking|most|leading|leader|leaders)\b/i.test(lower)
-        || hasComparativeMetricRanking(lower))
-        return 'ranking';
-    if (/\b(block|certified|saved|existing|approved|governed)\b/i.test(lower))
-        return 'exact_lookup';
+    // "Across all customers" states the population for one aggregate; it does
+    // not request a customer breakdown. Resolve direct KPI shape before the
+    // generic each/every/all list heuristic.
     if (isDirectKpiValueQuestion(lower))
         return 'exact_lookup';
+    if (input.metricTerms.length > 0 && input.dimensionTerms.length > 0
+        && /\b(each|every|all|list|show|give|provide)\b/i.test(lower))
+        return 'list_by_dimension';
+    // "What is" is not, by itself, a definition request. Questions such as
+    // "what is revenue by customer and product?" carry an explicit analytical
+    // shape and must reach the data cascade. Keep genuine single-concept meaning
+    // questions on the fast definition path while treating multi-dimensional or
+    // explicitly grouped measure requests as analysis (AGT-001).
+    if (/\b(define|definition|meaning of|what is|what are|what does .+ mean)\b/i.test(lower)
+        && !definitionPhraseCarriesAnalyticalShape(input))
+        return 'definition';
+    if (input.entities.length > 0 && (input.metricTerms.length > 0 || /\b(show|list|find|give|provide|performance|activity|history|details)\b/i.test(lower)))
+        return 'entity_drilldown';
+    if (/\b(block|certified|saved|existing|approved|governed)\b/i.test(lower))
+        return 'exact_lookup';
     if (/\b(show|list|find|which|who|how many|how much|metric|kpi|dashboard|performance|revenue|sales|orders|customers|users)\b/i.test(lower))
         return 'general_analysis';
     // A question that carries real analytical structure — named grouping dimensions
@@ -515,12 +533,13 @@ function definitionPhraseCarriesAnalyticalShape(input) {
     if (input.dimensionTerms.length >= 2)
         return true;
     return input.dimensionTerms.length > 0
-        && /\b(by|per|for each|group(?:ed)? by|split by|break(?:down| down)|info for|details for)\b/i.test(input.lower);
+        && /\b(top|bottom|highest|lowest|most|least|by|per|each|every|group(?:ed)? by|split by|break(?:down| down)|info for|details for|got|bought|purchased)\b/i.test(input.lower);
 }
 function routeIntentForMode(mode) {
     switch (mode) {
         case 'exact_lookup': return 'exact_certified_lookup';
         case 'definition': return 'definition_lookup';
+        case 'list_by_dimension': return 'ad_hoc_ranking';
         case 'ranking': return 'ad_hoc_ranking';
         case 'entity_profile':
         case 'entity_drilldown': return 'entity_drilldown';
@@ -535,16 +554,16 @@ function routeIntentForMode(mode) {
     }
 }
 function certifiedExactIsPlausible(mode, entities) {
-    if (mode === 'exact_lookup' || mode === 'definition')
-        return true;
-    if (mode === 'ranking' || mode === 'general_analysis')
-        return entities.length === 0;
-    return false;
+    void entities;
+    return mode !== 'clarify' && mode !== 'trust_review';
 }
 function generatedSqlIsLikely(mode, certifiedExact) {
+    void certifiedExact;
     if (mode === 'clarify' || mode === 'definition' || mode === 'trust_review')
         return false;
-    return !certifiedExact || ['entity_profile', 'entity_drilldown', 'comparison', 'driver_breakdown', 'diagnose_change', 'anomaly', 'trend'].includes(mode);
+    // This flag controls whether dbt/schema evidence is hydrated as the final
+    // fallback. It must not suppress contract-first certified/semantic matching.
+    return mode !== 'exact_lookup';
 }
 function researchWorkspaceIsLikely(mode, lower) {
     return ['entity_profile', 'driver_breakdown', 'diagnose_change', 'anomaly', 'trust_review'].includes(mode)
@@ -555,13 +574,13 @@ function outputShapeForMode(mode, lower, dimensionTerms) {
         return 'profile';
     if (mode === 'definition' || mode === 'trust_review')
         return 'narrative';
-    if (/\b(chart|graph|visual|plot)\b/i.test(lower) || mode === 'trend')
+    if (/\b(chart|graph|visual|plot|sankey|flow\s+diagram|source.?to.?target\s+flow)\b/i.test(lower) || mode === 'trend')
         return 'chart';
-    if (dimensionTerms.length >= 2 || /\b(info for|details for|for each|group(?:ed)? by|split by|break(?:down| down))\b/i.test(lower))
+    if (mode === 'list_by_dimension' || dimensionTerms.length >= 2 || /\b(info for|details for|for each|group(?:ed)? by|split by|break(?:down| down))\b/i.test(lower))
         return 'table';
     if (/\b(table|list|show all|complete|full)\b/i.test(lower) || mode === 'ranking' || mode === 'entity_drilldown')
         return 'table';
-    if (/\bwhat is|how many|how much|total|count|kpi|metric\b/i.test(lower))
+    if (/\bwhat (?:is|was|were|are)|how many|how much|total|count|kpi|metric\b/i.test(lower))
         return 'value';
     return 'narrative';
 }
@@ -579,6 +598,15 @@ function extractEntities(question) {
     for (const match of question.matchAll(/\b(?:for|where|only|specific|named|called|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)) {
         entities.push({ text: cleanEntityText(match[1]), source: 'explicit_filter' });
     }
+    // A one-token person/account reference after a comparator ("less than
+    // Melissa") is still a data value. The generic named-entity regex below only
+    // accepts two title-cased words, so without this rule the baseline entity is
+    // lost and retrieval repeatedly selects a broad metric or the previous block.
+    for (const match of question.matchAll(/\b(?:than|versus|vs\.?)\s+([A-Z][A-Za-z0-9&.'-]+(?:\s+[A-Z][A-Za-z0-9&.'-]+){0,4})/g)) {
+        const text = cleanEntityText(match[1]);
+        if (text)
+            entities.push({ text, source: 'explicit_filter' });
+    }
     for (const match of question.matchAll(/\b([A-Z][a-z]+(?:\s+[A-Z][a-z]+){1,4})\b/g)) {
         const text = cleanEntityText(match[1]);
         if (text && !/^(SQL|DQL|KPI|ARR|MRR|NBA|AI|LLM)$/.test(text)) {
@@ -587,6 +615,19 @@ function extractEntities(question) {
     }
     return uniqueEntities(entities).slice(0, 8);
 }
+function extractValueMentions(entities) {
+    return entities.map((entity) => ({
+        text: entity.text,
+        normalizedText: normalizeSearchText(entity.text),
+        source: entity.source,
+        syntacticRole: entity.source === 'id' || entity.source === 'email'
+            ? 'entity_identifier'
+            : entity.source === 'quoted' || entity.source === 'explicit_filter' || entity.source === 'named_entity'
+                ? 'filter_value'
+                : 'unknown',
+        ...(entity.typeHint ? { typeHint: entity.typeHint } : {}),
+    }));
+}
 function extractMetricTerms(question) {
     const lower = question.toLowerCase();
     const terms = new Set();
@@ -658,6 +699,26 @@ function removeFilterOnlyDimensionTerms(question, dimensions) {
                 filterOnly.add(dimension);
         }
     }
+    // Natural-language purchase restrictions often put the filtered object after
+    // its qualifier instead of before it: "customers who spent on beverage
+    // category products". In that sentence the answer grain is customer; products
+    // describe what was purchased and must not become an output dimension. Limit
+    // this broader rule to transactional grammar so named subjects such as "What
+    // changed in Player Stats Data Availability?" retain their analytical grain.
+    const hasTransactionalRestriction = /\b(?:spend|spends|spent|spending|buy|buys|bought|buying|purchase|purchases|purchased|purchasing|order|orders|ordered|ordering|sell|sells|sold|selling)\b[^?.!,;]{0,80}\b(?:on|in|within|from|among)\b/i.test(lower);
+    if (hasTransactionalRestriction) {
+        for (const dimension of dimensions) {
+            const word = escapeRegExp(dimension);
+            const restriction = new RegExp(`\\b(?:on|in|within|from|among)\\s+(?:the\\s+)?[^?.!,;]{0,60}\\b${word}s?\\b`, 'ig');
+            for (const match of lower.matchAll(restriction)) {
+                const outsideRestriction = `${lower.slice(0, match.index)} ${lower.slice((match.index ?? 0) + match[0].length)}`;
+                const explicitlyGrouped = new RegExp(`\\b(?:by|per|for each|group(?:ed)? by|split by)\\b[^?.!,;]{0,40}\\b${word}s?\\b`, 'i').test(lower);
+                const mentionedOutsideRestriction = new RegExp(`\\b${word}s?\\b`, 'i').test(outsideRestriction);
+                if (!explicitlyGrouped && !mentionedOutsideRestriction)
+                    filterOnly.add(dimension);
+            }
+        }
+    }
     return dimensions.filter((dimension) => !filterOnly.has(dimension));
 }
 function pluralizeDimensionWord(word) {
@@ -684,13 +745,15 @@ function extractFilterTerms(question, entities) {
         }
     }
     return uniqueStrings([
-        ...entities.flatMap((entity) => tokenize(entity.text)),
+        // Stored member values are phrases, not metadata tokens. Search can still
+        // tokenize them separately, but the executable filter contract must not.
+        ...entities.map((entity) => entity.text),
         ...analyticalValues,
         ...Array.from(question.matchAll(/\b(?:last|this|next|previous|prior|current)\s+(day|week|month|quarter|year|season)\b/gi)).map((match) => match[0].toLowerCase()),
     ]).slice(0, 16);
 }
 function cleanAnalyticalFilterValue(value) {
-    return (value ?? '')
+    const cleaned = (value ?? '')
         .toLowerCase()
         .replace(/\b(?:highest|lowest|most|least|top|bottom|best|worst|the)\b/g, ' ')
         .replace(/^.*\b(?:on|in|within)\s+/, '')
@@ -698,6 +761,12 @@ function cleanAnalyticalFilterValue(value) {
         .trim()
         .replace(/ies$/, 'y')
         .replace(/s$/, '');
+    // Deictic phrases are resolved from the typed prior-result context; they are
+    // not warehouse member values. Treating "for this amount" as a literal
+    // filter polluted value search and produced invalid SQL predicates.
+    if (/^(?:for\s+)?(?:this|that|same|previous|prior)\s+(?:amount|value|result|row)$/.test(cleaned))
+        return '';
+    return cleaned;
 }
 function expandSearchTerm(raw) {
     const term = normalizeTerm(raw);
@@ -713,7 +782,10 @@ function expandSearchTerm(raw) {
 }
 function extractTimeTerms(question) {
     const terms = [];
-    for (const match of question.matchAll(/\b(?:today|yesterday|ytd|mtd|qtd|wtd|last\s+\w+|this\s+\w+|next\s+\w+|previous\s+\w+|prior\s+\w+|\d{4})\b/gi)) {
+    // Relative determiners are temporal only when followed by a temporal noun.
+    // A broad `this \w+` match classified deictic result references such as
+    // "this amount" as a time grain and polluted both retrieval and SQL planning.
+    for (const match of question.matchAll(/\b(?:today|yesterday|ytd|mtd|qtd|wtd|(?:last|this|next|previous|prior)\s+(?:(?:fiscal|calendar)\s+)?(?:hours?|days?|weeks?|months?|quarters?|years?|seasons?|periods?)|\d{4})\b/gi)) {
         terms.push(match[0].toLowerCase());
     }
     for (const word of ['date', 'day', 'week', 'month', 'quarter', 'year', 'season', 'period']) {
@@ -738,6 +810,17 @@ function extractFollowUpMetricTerms(followUp, lowerQuestion) {
         ...cleanStringArray(record.priorResultColumns).filter((column) => METRIC_WORDS.some((word) => new RegExp(`\\b${word}\\b`, 'i').test(column.replace(/_/g, ' ')))),
     ]).slice(0, 8);
 }
+function resolveQuestionMetricTerms(lowerQuestion, directTerms, followUpTerms) {
+    if (!/\b(?:this|that|same|previous|prior)\s+(?:amount|value)\b/.test(lowerQuestion) || followUpTerms.length === 0) {
+        return uniqueStrings([...directTerms, ...followUpTerms]);
+    }
+    const monetary = followUpTerms.filter((term) => /(?:amount|revenue|sales?|spend|value|price|cost|profit|margin|bookings?|arr|mrr)/i.test(term));
+    const resolved = monetary.length > 0 ? monetary : [followUpTerms[0]];
+    return uniqueStrings([
+        ...directTerms.filter((term) => term !== 'amount' && term !== 'value'),
+        ...resolved,
+    ]);
+}
 function cleanStringArray(value) {
     if (!Array.isArray(value))
         return [];
@@ -811,6 +894,10 @@ function hasImplicitRankingRequest(lower) {
 function hasComparativeMetricRanking(lower) {
     return /\bmore\s+(?:amount|bookings|cost|count|margin|orders?|points?|profit|quantity|revenue|sales|score|spend|spending|tax|usage|value|volume)\b/.test(lower);
 }
+function isEntityRelativeMeasureComparison(value) {
+    return /\b(?:less|lower|fewer|more|higher|greater)\b[^?.!]{0,80}\bthan\b\s+[a-z0-9@._'-]+/i.test(value)
+        || /\b(?:below|under|above|over)\b\s+that\s+of\s+[a-z0-9@._'-]+/i.test(value);
+}
 function wordNumberFromTopN(lower) {
     const words = {
         one: 1,
@@ -837,6 +924,11 @@ function isPlausibleRequiredColumn(term) {
 function extractRequiredOutputs(question, dimensions, measures) {
     const lower = question.toLowerCase();
     const outputs = new Set();
+    for (const match of lower.matchAll(/\b([a-z][a-z0-9]*(?:_[a-z0-9]+){1,3})\b/g)) {
+        const identifier = canonicalShapeTerm(match[1]);
+        if (isPlausibleRequiredColumn(identifier))
+            outputs.add(identifier);
+    }
     for (const dim of dimensions) {
         if (isPlausibleRequiredColumn(dim))
             outputs.add(dim);
@@ -847,7 +939,8 @@ function extractRequiredOutputs(question, dimensions, measures) {
         // ("average tax info", "tax info by location") is a fuzzy search hint, not a
         // literal column the generated SQL must return — promoting it falsely flags a
         // valid answer as "partial". Single tokens (incl. "count" for KPI blocks) stay.
-        if (measure.split(/[_\s]+/).filter(Boolean).length === 1)
+        const aggregationOperators = new Set(['total', 'sum', 'average', 'avg', 'minimum', 'min', 'maximum', 'max']);
+        if (measure.split(/[_\s]+/).filter(Boolean).length === 1 && !aggregationOperators.has(measure))
             outputs.add(measure);
     }
     if (/\bproduct\s+name\b/i.test(lower))
@@ -871,13 +964,13 @@ function extractFollowUpReferences(question, followUp) {
     const lower = question.toLowerCase();
     const record = followUpRecord(followUp);
     const hasFollowUp = Boolean(record);
-    for (const match of lower.matchAll(/\b(these|those|that|same|prior|previous)\s+([a-z][a-z0-9_ -]{1,30})\b/g)) {
+    for (const match of lower.matchAll(/\b(this|these|those|that|same|prior|previous)\s+([a-z][a-z0-9_ -]{1,30})\b/g)) {
         const phrase = match[0];
         const noun = canonicalShapeTerm(match[2]);
         let kind = 'ambiguous';
         if (/period|date|day|week|month|quarter|year|time/.test(noun))
             kind = 'prior_timeframe';
-        else if (hasFollowUp && /\b(category|product|customer|account|user|region|segment|channel)\b/.test(noun))
+        else if (hasFollowUp && /\b(category|product|customer|account|user|region|segment|channel|row|result)\b/.test(noun))
             kind = 'prior_dimension_values';
         else if (hasFollowUp)
             kind = 'prior_entities';
@@ -887,8 +980,16 @@ function extractFollowUpReferences(question, followUp) {
             ...resolvedFollowUpValues(record, noun, kind),
         });
     }
+    if (record && /\b(they|their|them)\b/.test(lower)) {
+        const dimension = pronounFollowUpDimension(lower, record);
+        refs.push({
+            phrase: lower.match(/\b(they|their|them)\b/)?.[0] ?? 'they',
+            kind: dimension ? 'prior_dimension_values' : 'prior_entities',
+            ...resolvedFollowUpValues(record, dimension, dimension ? 'prior_dimension_values' : 'prior_entities'),
+        });
+    }
     if (refs.length === 0 && record) {
-        const bare = lower.match(/\b(these|those|that|them|same)\b/);
+        const bare = lower.match(/\b(this|these|those|that|it|them|same)\b/);
         const dimension = bare ? singleFollowUpDimension(record) : undefined;
         if (bare && dimension) {
             refs.push({
@@ -900,6 +1001,17 @@ function extractFollowUpReferences(question, followUp) {
     }
     return refs.slice(0, 8);
 }
+function pronounFollowUpDimension(question, record) {
+    const values = cleanStringRecord(record.priorResultValues);
+    const available = new Set(Object.keys(values).map(contextDimensionTerm));
+    if (available.has('customer') && /\b(they|their|them)\b[^.?!]{0,40}\b(buy|bought|purchase|purchased|order|ordered|spend|spent|use|used)\b/.test(question)) {
+        return 'customer';
+    }
+    if (available.has('product') && /\b(they|their|them)\b[^.?!]{0,40}\b(sell|sold|cost|priced)\b/.test(question)) {
+        return 'product';
+    }
+    return singleFollowUpDimension(record);
+}
 function followUpDimensionsForRequestedShape(followUp, refs) {
     const record = followUpRecord(followUp);
     if (!record || refs.every((ref) => ref.kind !== 'prior_dimension_values'))
@@ -1019,6 +1131,7 @@ function modeSearchTerms(mode) {
     switch (mode) {
         case 'entity_profile': return ['profile', 'summary', 'details', 'stats', 'statistics', 'history'];
         case 'entity_drilldown': return ['detail', 'filter', 'name', 'id'];
+        case 'list_by_dimension': return ['list', 'detail', 'group'];
         case 'ranking': return ['rank', 'top', 'bottom', 'total'];
         case 'trend': return ['date', 'time', 'month', 'week', 'year', 'trend'];
         case 'comparison': return ['compare', 'segment', 'cohort'];
@@ -1053,7 +1166,7 @@ function relationSearchText(relation) {
     ].join(' ');
 }
 function isDirectCertifiedQuestion(plan) {
-    return plan.mode === 'exact_lookup' || plan.mode === 'definition' || (plan.shouldConsiderCertifiedExact && !plan.needsGeneratedSql);
+    return plan.mode === 'exact_lookup' || plan.mode === 'definition' || plan.shouldConsiderCertifiedExact;
 }
 function hasExactExampleQuestion(object, normalizedQuestion) {
     const examples = Array.isArray(object.payload?.examples) ? object.payload.examples : [];
@@ -1073,9 +1186,13 @@ function rankingDirectionCompatible(question, targetText) {
 }
 function rankingDirection(value) {
     const lower = value.toLowerCase();
-    const bottom = /\b(bottom|worst|lowest|least|fewest|minimum|min|smallest)\b/.test(lower);
+    const bottom = /\b(bottom|worst|lowest|least|fewest|minimum|min|smallest)\b/.test(lower)
+        || /\b(?:less|lower|fewer)\b[^?.!]{0,80}\bthan\b/.test(lower)
+        || /\b(?:below|under)\b\s+that\s+of\s+[a-z0-9@._'-]+/.test(lower);
     const top = /\b(top|best|highest|most|maximum|max|largest|leading|leaders?)\b/.test(lower)
-        || hasComparativeMetricRanking(lower);
+        || hasComparativeMetricRanking(lower)
+        || /\b(?:more|higher|greater)\b[^?.!]{0,80}\bthan\b/.test(lower)
+        || /\b(?:above|over)\b\s+that\s+of\s+[a-z0-9@._'-]+/.test(lower);
     if (bottom && !top)
         return 'bottom';
     if (top && !bottom)
@@ -1159,9 +1276,11 @@ function cleanEntityText(value) {
 }
 function isDirectKpiValueQuestion(lower) {
     const asksForValue = /\b(what\s+(?:is|was|were|are)|how\s+(?:much|many)|show|report|calculate|give\s+me|tell\s+me)\b/.test(lower);
-    const metricLanguage = /\b(revenue|sales|arr|mrr|bookings|orders|customers|users|churn|retention|conversion|rate|count|total|points|goals|kpi|metric)\b/.test(lower);
+    const aggregateCue = /\b(how\s+(?:much|many)|show|report|calculate|give\s+me|tell\s+me|total|sum|count|number of|average|avg|minimum|min|maximum|max|across\s+all|overall)\b/.test(lower);
+    const temporalScope = /\b(?:last|this|previous|prior|current)\s+(?:day|week|month|quarter|year)\b/.test(lower);
+    const metricLanguage = /\b(revenue|sales|spend|spending|cost|profit|margin|value|amount|usage|arr|mrr|bookings|orders|customers|users|churn|retention|conversion|rate|count|total|points|goals|kpi|metric)\b/.test(lower);
     const customGrain = /\b(by|break\s*down|breakdown|drill|compare|versus|vs\.?|segment|cohort|top|bottom|best|worst|highest|lowest|least|fewest|rank|ranking|most|why|changed?|driver|anomal|exception)\b/.test(lower);
-    return asksForValue && metricLanguage && !customGrain;
+    return asksForValue && (aggregateCue || temporalScope) && metricLanguage && !customGrain;
 }
 function tokenize(value) {
     const tokens = new Set();