@duckcodeailabs/dql-agent 1.14.2 → 1.14.4

package/dist/analytical-orchestration.js

@@ -12,7 +12,265 @@
  * Acceptance: AGT-027..033, CTX-007, PERF-003, E2E-022.
  */
 import { createHash } from 'node:crypto';
+import { parseAnalyticalTimeWindow } from './requirement-clauses.js';
 export const ANALYTICAL_ORCHESTRATION_CONTRACT_VERSION = 1;
+/**
+ * Preserve a validated prior-result predicate as typed analytical context.
+ * The selected display key supplies the entity/display requirements needed to
+ * retrieve relationship closure; the literal values remain an immutable host
+ * filter and are never treated as a provider-selected member meaning.
+ */
+export function withAnalyticalPriorResultMemberBinding(requirements, binding) {
+    const displayDimension = binding?.displayDimension?.trim();
+    const seenValues = new Set();
+    const values = (binding?.values ?? []).flatMap((value) => {
+        const trimmed = value.trim();
+        const normalized = normalizeRequirementTerm(trimmed);
+        if (!trimmed || !normalized || seenValues.has(normalized))
+            return [];
+        seenValues.add(normalized);
+        return [trimmed];
+    });
+    if (!displayDimension || values.length === 0)
+        return requirements;
+    const normalizedDisplay = normalizeRequirementTerm(displayDimension);
+    const entityTerm = normalizedDisplay
+        .replace(/\b(?:name|id|key|label|email)\b/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return {
+        ...requirements,
+        entityTerms: uniqueRequirementTerms([
+            ...requirements.entityTerms,
+            ...(entityTerm ? [entityTerm] : []),
+        ]),
+        entityDisplayTerms: uniqueRequirementTerms([
+            ...requirements.entityDisplayTerms,
+            normalizedDisplay,
+        ]),
+        // These values are retained for local compiler/filter construction. The
+        // planner request redacts this host-only binding and does not require a
+        // member card when it is present.
+        memberTerms: uniqueRequirementTerms([...requirements.memberTerms, ...values]),
+        priorResultMemberBinding: {
+            version: 1,
+            // Preserve the canonical host field spelling for the immutable filter;
+            // normalized text above is only for role matching/admission.
+            displayDimension,
+            values,
+            ...(binding?.sourceTurnId ? { sourceTurnId: binding.sourceTurnId } : {}),
+            ...(binding?.resultFingerprint ? { resultFingerprint: binding.resultFingerprint } : {}),
+        },
+    };
+}
+/** Build the immutable host request tuple before a meaning model can respond. */
+export function buildAnalyticalRequirementSeedV1(input) {
+    // Retrieval/parser output is intentionally broad: it may contain useful
+    // context from a prior turn, vector hit, or search expansion.  It is not an
+    // authority for a new free-text request.  Keep only refinements that the
+    // source question itself demonstrates before they can contribute to the
+    // frozen host tuple. Structured clarification selections are merged by the
+    // router into `requirements` before this function is called.
+    const parsed = currentQuestionGroundedParsedIntent(input.question, input.parsedIntent);
+    const baseRequirements = input.requirements ?? buildAnalyticalRequirementSet({
+        question: input.question,
+        parsedIntent: parsed,
+    });
+    const requirements = withAnalyticalPriorResultMemberBinding(baseRequirements, input.priorResultMemberBinding ?? baseRequirements.priorResultMemberBinding);
+    // Order and limit are lexical requirements, not parser defaults. In
+    // particular, a prior ranking must not turn a complete new question into a
+    // top-N query just because retrieval retained an old `limit` or `order`.
+    const order = requirements.ranking
+        ? requirements.ranking.direction === 'bottom' ? 'asc' : 'desc'
+        : undefined;
+    const limit = requirements.ranking?.limit;
+    const filters = [...(parsed?.filters ?? [])].map((filter) => ({ field: filter.field, value: filter.value }));
+    for (const value of requirements.priorResultMemberBinding?.values ?? []) {
+        const field = requirements.priorResultMemberBinding?.displayDimension;
+        if (!field || filters.some((filter) => normalizeRequirementTerm(filter.field) === normalizeRequirementTerm(field)
+            && normalizeRequirementTerm(filter.value) === normalizeRequirementTerm(value)))
+            continue;
+        filters.push({ field, value });
+    }
+    if (requirements.time?.fiscalPeriod && input.fiscalCalendar?.fiscalPeriodFieldId
+        && !filters.some((filter) => filter.field === input.fiscalCalendar.fiscalPeriodFieldId)) {
+        filters.push({ field: input.fiscalCalendar.fiscalPeriodFieldId, value: requirements.time.fiscalPeriod });
+    }
+    return {
+        version: 1,
+        sourceQuestion: input.question,
+        requirements,
+        queryIntent: {
+            measures: [...requirements.measures],
+            // A ranking's entity display key is an execution requirement, not a
+            // prompt nicety. Keep it in the host-owned query tuple, but do not put
+            // the broad entity noun (for example `customer`) in the categorical
+            // dimension lane. A metric can legitimately expose customer type and
+            // customer order number as groupings; neither is interchangeable with
+            // the requested customer display/rank key. The frame resolves the
+            // display term against the selected metric's native display/rank role.
+            dimensions: [...new Set([
+                    ...categoricalDimensionRequirementTerms(requirements),
+                    ...requirements.entityDisplayTerms,
+                ])],
+            filters,
+            // The typed window is the host's own reading of the question and wins
+            // over a retrieval refinement. Its canonical expression is exactly the
+            // input `resolvePlanTimeRange` accepts, so populating it is what makes
+            // that (previously never-called) resolver finally produce timeBounds.
+            ...(requirements.time?.window
+                ? { timeRange: requirements.time.window.expression }
+                : parsed?.timeRange ? { timeRange: parsed.timeRange } : {}),
+            ...(requirements.time?.grain
+                ? { timeGrain: requirements.time.grain }
+                : parsed?.timeGrain ? { timeGrain: parsed.timeGrain } : {}),
+            ...(order ? { order } : {}),
+            ...(limit !== undefined ? { limit } : {}),
+            // A calendar/date role is declared snapshot metadata, never an ID
+            // copied from retrieval/parser evidence.
+            ...(input.fiscalCalendar?.id ? { fiscalCalendarId: input.fiscalCalendar.id } : {}),
+            ...(input.fiscalCalendar?.dateRoleId ? { fiscalDateRoleId: input.fiscalCalendar.dateRoleId } : {}),
+        },
+    };
+}
+/**
+ * Return only parser refinements whose business words occur in the current
+ * source question. This deliberately does not try to recover previous turn
+ * context: continuation is represented by a server-issued structured choice
+ * and merged separately by the host. The helper is exported for regression
+ * tests and for router paths that construct a requirement set before a seed.
+ */
+export function currentQuestionGroundedParsedIntent(question, parsedIntent) {
+    if (!parsedIntent)
+        return undefined;
+    // These are intentionally tiny, product-wide vocabulary aliases rather
+    // than semantic guessing. They let a retrieval parser retain the same
+    // current-turn business phrase (`drink revenue` for `beverage revenue`, or
+    // `sales` for `revenue`) while still rejecting an unrelated prior-turn
+    // phrase such as `rollover balance`. Do not add customer/model-specific
+    // synonyms here: those require a qualified selected candidate and an
+    // override receipt at the meaning boundary.
+    const canonicalGroundingToken = (term) => {
+        if (term === 'sale' || term === 'sales')
+            return 'revenue';
+        if (term === 'drink' || term === 'drinks')
+            return 'beverage';
+        return term;
+    };
+    const questionTerms = new Set(normalizeRequirementTerm(question)
+        .split(' ')
+        .filter((term) => term.length > 1)
+        .map(canonicalGroundingToken));
+    const groundedTerm = (value) => {
+        const terms = normalizeRequirementTerm(value ?? '')
+            .split(' ')
+            .filter((term) => term.length > 1 && !/^(?:the|a|an|by|for|with|and|or|of|to|in|on|at)$/.test(term))
+            .map(canonicalGroundingToken);
+        return terms.length > 0 && terms.every((term) => {
+            if (questionTerms.has(term))
+                return true;
+            // Preserve only a trivial singular/plural normalization. Anything more
+            // permissive would let a stale retrieved phrase become a new request.
+            return term.endsWith('s')
+                ? questionTerms.has(term.slice(0, -1))
+                : questionTerms.has(`${term}s`);
+        });
+    };
+    const timeRangeGrounded = (value) => {
+        const normalized = normalizeRequirementTerm(value ?? '');
+        if (!normalized)
+            return false;
+        if (groundedTerm(normalized))
+            return true;
+        if (!/^(?:last|previous|past) (?:\d+|one|two|three|four|five|six|seven|eight|nine|ten|twelve) (?:day|days|week|weeks|month|months|quarter|quarters|year|years)$/.test(normalized))
+            return false;
+        // The question may spell the count ("last two months") while the parsed
+        // range uses digits ("last 2 months"). Both spell the same window; ground
+        // on the digit-normalized forms so the wording difference cannot unground
+        // a range the question itself established.
+        const digits = (value2) => value2
+            .replace(/\bone\b/g, '1').replace(/\btwo\b/g, '2').replace(/\bthree\b/g, '3')
+            .replace(/\bfour\b/g, '4').replace(/\bfive\b/g, '5').replace(/\bsix\b/g, '6')
+            .replace(/\bseven\b/g, '7').replace(/\beight\b/g, '8').replace(/\bnine\b/g, '9')
+            .replace(/\btwelve\b/g, '12').replace(/\bten\b/g, '10');
+        return digits(normalizeRequirementTerm(question)).includes(digits(normalized));
+    };
+    const measures = (parsedIntent.measures ?? []).filter(groundedTerm);
+    const dimensions = (parsedIntent.dimensions ?? []).filter(groundedTerm);
+    // A parser may contribute the column that a reader's explicitly named value
+    // belongs to, but the value itself must appear in this request. This drops
+    // stale rollover-balance/member filters while retaining a current named
+    // member that the host can bind to a qualified field.
+    const filters = (parsedIntent.filters ?? []).filter((filter) => groundedTerm(filter.value));
+    const timeRange = timeRangeGrounded(parsedIntent.timeRange)
+        ? parsedIntent.timeRange
+        : undefined;
+    return {
+        ...(measures.length > 0 ? { measures } : {}),
+        ...(dimensions.length > 0 ? { dimensions } : {}),
+        ...(filters.length > 0 ? { filters } : {}),
+        ...(timeRange ? { timeRange } : {}),
+        // Grain/ranking/limit are derived deterministically from the source
+        // question below. Never promote parser values by themselves.
+    };
+}
+/**
+ * Preserve a small set of explicit current-question literals even when a
+ * retriever did not emit a parser filter. This is deliberately not a value
+ * search or synonym engine: it records only quoted values, capitalized proper
+ * names, and values introduced by an explicit predicate phrase. The planner
+ * must still bind each term to an admitted, qualified member/dimension card
+ * before it can become an executable filter.
+ *
+ * Without this host-owned atom, "customers in Philadelphia" could reach a
+ * broad certified fit after retrieval silently omitted the parser filter.
+ */
+export function currentQuestionLiteralMemberTerms(question) {
+    const literals = [];
+    const append = (value, source = 'predicate') => {
+        const trimmed = (value ?? '').trim()
+            .replace(/^(?:the\s+)/i, '')
+            .replace(/[?.!,;:]+$/g, '')
+            .trim();
+        const normalized = normalizeRequirementTerm(trimmed);
+        if (!normalized || isTemporalTerm(normalized))
+            return;
+        // Do not mistake grammatical/analytical words for a member literal.
+        if (/^(?:by|with|and|or|for|where|that|which|who|having|have)\b/i.test(normalized))
+            return;
+        if (/^(?:show|who|what|which|where|when|why|how|top|bottom|highest|lowest|revenue|sales|customers?|accounts?|products?|orders?|regions?|categories?|category|region|customer|account|product|order)$/i.test(normalized))
+            return;
+        // A two-word title-cased fragment is not automatically a proper name.
+        // Sentence-leading analytical phrases such as `Show Revenue` and `Top
+        // Customers` otherwise become fake member atoms, then falsely demand a
+        // member field before the compiler can reach a safe physical fallback.
+        // Quoted text remains an explicit reader literal; only heuristic proper
+        // name extraction applies this conservative vocabulary guard.
+        if (source === 'proper_name') {
+            const words = normalized.split(/\s+/);
+            if (words.some((word) => /^(?:show|list|give|find|get|top|bottom|highest|lowest|revenue|sales|customer|customers|account|accounts|product|products|order|orders|region|regions|category|categories|metric|metrics|amount|count|total|average|avg|monthly|daily|yearly)$/i.test(word)))
+                return;
+        }
+        literals.push(trimmed);
+    };
+    // A reader can make a value unambiguous with quotes regardless of casing.
+    for (const match of question.matchAll(/["“]([^"”]{2,96})["”]/g))
+        append(match[1], 'quoted');
+    // Keep a literal only when the question itself supplies a predicate-like
+    // construction. The bounded lookahead avoids swallowing "by revenue" or a
+    // second clause into the value.
+    const predicate = /\b(?:in|from|at|named|called)\s+(?:the\s+)?([A-Za-z][A-Za-z0-9'/-]*(?:\s+[A-Za-z][A-Za-z0-9'/-]*){0,3})(?=\s*(?:\b(?:by|with|and|or|for|where|that|which|who|having|have)\b|[?.!,;]|$))/gi;
+    for (const match of question.matchAll(predicate))
+        append(match[1], 'predicate');
+    // Proper names such as "Brittany Barrera" are a member requirement even
+    // when the reader phrases an attribute lookup rather than a SQL-style
+    // predicate. Single capitalized words are intentionally handled only by the
+    // predicate branch above so sentence-leading generic words do not become
+    // fake filters.
+    for (const match of question.matchAll(/\b([A-Z][a-z]+(?:\s+[A-Z][a-z]+){1,3})\b/g))
+        append(match[1], 'proper_name');
+    return uniqueRequirementTerms(literals);
+}
 /**
  * Small, explainable intent vocabulary used before the physical plan exists.
  * It is deliberately not a second semantic matcher: candidate identity still
@@ -54,6 +312,42 @@ function uniqueRequirementTerms(values) {
             .map(normalizeRequirementTerm)
             .filter(Boolean))];
 }
+/**
+ * Entity/display terms are represented in the historical `dimensions` seed
+ * so ranking plans can retain their requested grain. They must not consume
+ * the separate categorical-dimension admission lane. For example, in "top
+ * customers by product category", `customer` is the entity/rank role while
+ * `product category` is the required categorical grouping role.
+ */
+export function categoricalDimensionRequirementTerms(requirements) {
+    const entityTerms = new Set(uniqueRequirementTerms([
+        ...requirements.entityTerms,
+        ...requirements.entityDisplayTerms,
+    ]));
+    return uniqueRequirementTerms(requirements.dimensions)
+        .filter((term) => !entityTerms.has(term));
+}
+/**
+ * A small, typed vocabulary bridge for categorical field identities. It is
+ * intentionally not a general synonym engine: only the field-kind suffix is
+ * canonicalized, while the scoped business noun must still match. Thus
+ * `product category` can bind the snapshot-declared `product_type`, whereas
+ * `customer_type` cannot satisfy it. A bare `category` remains potentially
+ * ambiguous when more than one qualified `*_type` field exists.
+ */
+export function categoricalDimensionTermsMatch(left, right) {
+    const normalizedLeft = normalizeRequirementTerm(left);
+    const normalizedRight = normalizeRequirementTerm(right);
+    if (!normalizedLeft || !normalizedRight)
+        return false;
+    const phraseMatch = (a, b) => a === b || a.endsWith(` ${b}`) || b.endsWith(` ${a}`);
+    if (phraseMatch(normalizedLeft, normalizedRight))
+        return true;
+    const canonicalizeKind = (value) => value
+        .replace(/\bcategories\b/g, 'type')
+        .replace(/\bcategory\b/g, 'type');
+    return phraseMatch(canonicalizeKind(normalizedLeft), canonicalizeKind(normalizedRight));
+}
 function isTemporalTerm(term) {
     return /^(?:date|day|week|month|quarter|year|fy\d{2,4}|fiscal year|fiscal quarter)$/.test(term);
 }
@@ -112,6 +406,43 @@ function normalizedTypedAggregationRequirements(input) {
     ]);
     return { measures, dimensions };
 }
+/**
+ * Keep grammatical wrappers out of the physical tuple. In particular, a
+ * parser can return `sales based on the region` as a dimension for a simple
+ * revenue-by-region request. That is neither a business dimension nor an
+ * object DQL may report as absent.
+ */
+function normalizeAnalyticalDimensionTerms(question, values) {
+    const hasRegion = /\b(?:by|based\s+on(?:\s+the)?|across|per)\s+(?:the\s+)?region\b/i.test(question);
+    const hasProductCategory = /\bproduct\s+categor(?:y|ies)\b/i.test(question);
+    // A planner can surface the noun from a projected field as a grouping
+    // dimension (for example `product` from “with product ID and product
+    // price”).  An output is not a `by product` group. Keep the noun only when
+    // the reader actually supplied a grouping construction; otherwise the
+    // host-owned row-level/output tuple would acquire a fake dimension and
+    // make an otherwise single-table exploratory plan ambiguous.
+    const outputRoots = new Set(explicitOutputTerms(question)
+        .map((term) => term.replace(/\s+(?:id|name|price)$/i, '').trim())
+        .filter(Boolean));
+    const isExplicitGroupingRoot = (term) => {
+        const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        return new RegExp(`\\b(?:by|per|across|for\\s+each)\\s+(?:the\\s+)?${escaped}(?:s)?\\b`, 'i').test(question);
+    };
+    const normalized = uniqueRequirementTerms([...values])
+        .filter((value) => !/\b(?:revenue|sales)\b.*\b(?:based\s+on|by)\b.*\bregion\b/.test(value))
+        .filter((value) => !(hasProductCategory && /^(?:product|category)$/.test(value)))
+        .filter((value) => !outputRoots.has(value) || isExplicitGroupingRoot(value));
+    return uniqueRequirementTerms([
+        ...normalized,
+        ...(hasRegion ? ['region'] : []),
+        ...(hasProductCategory ? ['product category'] : []),
+    ]);
+}
+function explicitOutputTerms(question) {
+    const terms = [...question.matchAll(/\b(?:order|product|customer|account)\s+(?:id|name|price)\b/gi)]
+        .map((match) => match[0] ?? '');
+    return uniqueRequirementTerms(terms);
+}
 /**
  * Normalize grammatical aggregation wrappers before they become a plan
  * requirement.  Retrieval/parser output is allowed to retain useful search
@@ -119,20 +450,26 @@ function normalizedTypedAggregationRequirements(input) {
  * or "for each customer" as separate physical measures.  The grouping entity
  * is represented by the dimension/entity roles instead.
  *
- * `order count for each customer` is the common prose form for a count
- * aggregation at customer grain.  Keep the aggregation (`count`) and remove
- * the object noun (`order`) only for that exact grouped construction; a named
- * metric such as `order_value` remains untouched.
+ * `order count for each customer` is the common prose form for the authored
+ * `order_count` semantic measure at customer grain.  Keep that compound
+ * identity intact: reducing it to the generic aggregation `count` makes the
+ * unfiltered `Orders` MetricFlow metric indistinguishable from scoped metrics
+ * such as `Drink Orders` and `Food Orders`.  The grouping entity is still
+ * represented by the dimension/entity roles rather than becoming another
+ * measure.
  */
 export function normalizeAnalyticalMeasureTerms(question, values, options = {}) {
-    const normalizedQuestion = normalizeRequirementTerm(question);
-    const groupedOrderCount = /\borders?\s+count\s+(?:for|per)\s+(?:each|every)\s+(?:the\s+)?(?:account|customer|client|company|product|order|item|row)s?\b/.test(normalizedQuestion);
+    // A parser often singularizes the business alias `sales` into `sale`.  That
+    // is not a second measure beside revenue: it is the same current-question
+    // request.  Canonicalize only that standalone vocabulary alias here; named
+    // measures such as `sales_tax` or `sales_pipeline` keep their identity.
+    const canonicalMeasureAlias = (value) => {
+        const normalized = normalizeRequirementTerm(value);
+        return normalized === 'sale' || normalized === 'sales' ? 'revenue' : value;
+    };
     const terms = values
-        .filter((value) => !isStructuralMeasurePhrase(value))
-        .filter((value) => !(groupedOrderCount && /^(?:order|orders)$/i.test(normalizeRequirementTerm(value))));
-    if (groupedOrderCount && !terms.some((value) => normalizeRequirementTerm(value) === 'count')) {
-        terms.push('count');
-    }
+        .map(canonicalMeasureAlias)
+        .filter((value) => !isStructuralMeasurePhrase(value));
     // An inherited measure can already be a stable semantic/dbt identity. Keep
     // that identity intact for the planner/meaning handoff; matching and display
     // have their own normalizers. Rewriting `total_consumption_units` to prose
@@ -156,22 +493,111 @@ export function normalizeAnalyticalMeasureTerms(question, values, options = {})
  * phrase that already owns it: adding both `beverage revenue` and `revenue`
  * turns one requested metric into two and incorrectly rejects a block whose
  * own declared output is `beverage_revenue`. The same holds for `order count`
- * and its generic `count` root; grouped prose is normalized to `count` before
- * this helper runs, so retaining both is neither necessary nor correct.
+ * and its generic `count` root; the authored compound is retained and owns
+ * that generic aggregation vocabulary for this question.
  */
 function nonRedundantLexicalMeasureTerms(parsedMeasures, question) {
-    const lexical = ['revenue', 'refund', 'refunds', 'bcm', 'run rate', 'count']
+    const compoundTerms = explicitQuestionCompoundMeasureTerms(question);
+    const lexical = [
+        ...compoundTerms,
+        ...['revenue', 'refund', 'refunds', 'bcm', 'run rate', 'count'],
+    ]
+        // `BCM run rate` is one named business measure, not the independent
+        // lexical roots `bcm` and `run rate`.
+        .filter((term) => !compoundTerms.some((compound) => compound !== term && compound.includes(term)))
         .filter((term) => new RegExp(`\\b${term.replace(' ', '\\s+')}\\b`, 'i').test(question));
     return lexical.filter((term) => {
-        if (term === 'count') {
-            return !parsedMeasures.some((measure) => normalizeRequirementTerm(measure).split(' ').includes('count'));
-        }
-        const token = term === 'refunds' ? 'refund' : term;
-        return !parsedMeasures.some((measure) => normalizeRequirementTerm(measure)
+        // A multi-word lexical root such as `run rate` must be considered owned
+        // by `BCM run rate`. The old word-by-word comparison only worked for a
+        // one-word root and added both phrases as independent measures, which
+        // prevented an otherwise exact semantic metric from binding without a
+        // provider. Treat the lexical phrase as redundant when all of its tokens
+        // are already present in one parsed measure. Keep the narrow refund
+        // singular/plural equivalence so existing vocabulary remains stable.
+        const lexicalTokens = normalizeRequirementTerm(term)
             .split(' ')
-            .some((word) => word === token || (token === 'refund' && word === 'refunds')));
+            .filter(Boolean)
+            .map((token) => token === 'refunds' ? 'refund' : token);
+        return !parsedMeasures.some((measure) => {
+            const measureTokens = new Set(normalizeRequirementTerm(measure)
+                .split(' ')
+                .filter(Boolean)
+                .map((token) => token === 'refunds' ? 'refund' : token));
+            return lexicalTokens.every((token) => measureTokens.has(token));
+        });
     });
 }
+/**
+ * Preserve explicit multi-word business measures when a retrieval parser
+ * emits only a suffix such as `rate`. This is intentionally a compact,
+ * vocabulary-backed list rather than a speculative phrase synthesizer: it
+ * upgrades only a phrase the user actually wrote and whose complete meaning
+ * is common in the governed analytics catalog.
+ */
+function explicitQuestionCompoundMeasureTerms(question) {
+    return [
+        ...(/\borders?\s+count\b/i.test(question) ? ['order count'] : []),
+        ...(/\bbcm\s+run\s+rate\b/i.test(question) ? ['bcm run rate'] : []),
+    ];
+}
+/**
+ * A parser fragment must not become a second measure when the source question
+ * contains an explicit compound business measure that subsumes it. For
+ * example, `rate` plus `BCM run rate` is one requested metric. We only remove
+ * strict token subsets of a phrase explicitly present in the user question;
+ * independent named measures remain separate requirements.
+ */
+function preferExplicitQuestionCompoundMeasures(terms, question) {
+    const compounds = explicitQuestionCompoundMeasureTerms(question)
+        .map((term) => ({ term, tokens: normalizeRequirementTerm(term).split(' ').filter(Boolean) }));
+    if (compounds.length === 0)
+        return uniqueRequirementTerms([...terms]);
+    return uniqueRequirementTerms([...terms]).filter((term) => {
+        const normalized = normalizeRequirementTerm(term);
+        const tokens = normalized.split(' ').filter(Boolean);
+        return !compounds.some((compound) => normalized !== compound.term
+            && tokens.length > 0
+            && tokens.length < compound.tokens.length
+            && tokens.every((token) => compound.tokens.includes(token)));
+    });
+}
+/**
+ * A ranking question can contain a business qualifier immediately before the
+ * ranked entity (for example, "BCM customers") as well as the measure that
+ * actually orders the result ("highest revenue").  The retrieval parser keeps
+ * both phrases because both are useful for recall, but they are not equivalent
+ * plan requirements.  Prefer a direct ranking clause over the broad parser
+ * hint before any candidate is admitted as a metric.
+ *
+ * This deliberately remains narrow.  It only disambiguates when the parser
+ * supplied competing measures and the user also wrote an explicit comparator;
+ * parser-absent and already-unambiguous ranking requests retain their existing
+ * normal meaning-resolution path.
+ */
+function explicitRankingMeasureTerms(question, parsedMeasures) {
+    const parsed = uniqueRequirementTerms([...parsedMeasures]);
+    if (parsed.length < 2)
+        return [];
+    const phrases = [];
+    const endOfMeasure = String.raw `(?=\s+(?:across|among|for|per|in|where|during|over|with|that|which|who|and|or)\b|[?.!,;]|$)`;
+    for (const pattern of [
+        new RegExp(String.raw `\b(?:highest|lowest|most|least)\s+(?:the\s+)?([a-z][a-z0-9_. -]{0,80}?)${endOfMeasure}`, 'gi'),
+    ]) {
+        for (const match of question.matchAll(pattern)) {
+            const phrase = normalizeRequirementTerm(match[1] ?? '');
+            if (phrase && !isTemporalTerm(phrase))
+                phrases.push(phrase);
+        }
+    }
+    const direct = uniqueRequirementTerms(phrases);
+    if (direct.length === 0)
+        return [];
+    // Preserve the parser's more stable authored phrase when it is the same
+    // measure.  This avoids replacing `net revenue` with a looser lexical root,
+    // while still removing an entity modifier such as `BCM` in `BCM customers`.
+    const matchedParsed = parsed.filter((measure) => direct.some((phrase) => measure === phrase || measure.includes(phrase) || phrase.includes(measure)));
+    return matchedParsed.length > 0 ? matchedParsed : direct;
+}
 /**
  * Parse only stable analytical roles. This is purposefully narrower than an
  * LLM interpretation: unknown business phrases remain available to the normal
@@ -180,7 +606,9 @@ function nonRedundantLexicalMeasureTerms(parsedMeasures, question) {
 export function buildAnalyticalRequirementSet(input) {
     const question = input.question;
     const lower = question.toLowerCase();
-    const parsed = input.parsedIntent;
+    // Parser/retrieval evidence may be broad or stale. A requirement set is
+    // host authority, so only source-question-grounded refinements may enter it.
+    const parsed = currentQuestionGroundedParsedIntent(question, input.parsedIntent);
     const grainMatch = lower.match(/\b(?:by|per|each)\s+(day|week|month|quarter|year)\b|\b(monthly|weekly|quarterly|yearly|daily)\b/i);
     const grainWord = (grainMatch?.[1] ?? grainMatch?.[0]?.replace(/ly\b/i, '') ?? '').toLowerCase();
     const grain = grainWord === 'daily' ? 'day'
@@ -192,12 +620,18 @@ export function buildAnalyticalRequirementSet(input) {
                             : undefined;
     const fiscal = lower.match(/\bfy\s?(\d{2,4})\b|\bfiscal\s+year\s+(\d{2,4})\b/i);
     const fiscalPeriod = fiscal ? `FY${fiscal[1] ?? fiscal[2]}`.toUpperCase() : undefined;
-    const ranking = lower.match(/\b(top|bottom|highest|lowest)\s*(\d+)?\b/i);
-    const requestedDimensions = uniqueRequirementTerms(parsed?.dimensions ?? []);
+    const ranking = lower.match(/\b(top|bottom|highest|lowest|most|least|expensive|cheapest)\s*(\d+)?\b/i);
+    const leadingOrdinalRanking = lower.match(/\b(\d+)\s+(?:most|least|expensive|cheapest)\b/i);
+    const requestedDimensions = normalizeAnalyticalDimensionTerms(question, parsed?.dimensions ?? []);
     const entityTerms = uniqueRequirementTerms([
         ...((lower.match(/\b(?:account|accounts|customer|customers|client|clients|company|companies)\b/g) ?? [])),
     ]).map((term) => term.replace(/s$/, ''));
-    const entityDisplayTerms = /\b(?:who|which)\b/i.test(question)
+    // A ranking result needs a human-readable entity output even when the
+    // wording starts with "what" rather than "who" or "which".  Treat the
+    // entity's display key as a required role for `top accounts` / `top
+    // customers`; an entity key, owner field, or sentiment attribute is not a
+    // substitute for the result label.
+    const entityDisplayTerms = (/\b(?:who|which)\b/i.test(question) || Boolean(ranking && entityTerms.length > 0))
         ? uniqueRequirementTerms(entityTerms.map((term) => `${term} name`))
         : [];
     // "this amount" is a deictic reference to a prior result, not a request to
@@ -206,32 +640,70 @@ export function buildAnalyticalRequirementSet(input) {
     // option. Concrete metric words remain typed requirements, including the
     // common revenue/refunds pair used by multi-metric requests.
     const deicticAmount = /\b(?:this|that|the|such)\s+amount\b/i.test(question);
-    const parsedMeasures = normalizeAnalyticalMeasureTerms(question, parsed?.measures ?? []);
-    const parsedMeasuresWithLexicalTerms = uniqueRequirementTerms([
+    // `sales` is a common business synonym for revenue. Do not add the broad
+    // revenue root merely because a named metric contains it (`beverage revenue`)
+    // or an exact certified block would suddenly look multi-metric.
+    const salesIsRevenueAlias = /\bsales\b/i.test(question);
+    const parsedMeasures = normalizeAnalyticalMeasureTerms(question, parsed?.measures ?? [])
+        .filter((measure) => !/\bsales\s+based\s+on\b/.test(normalizeRequirementTerm(measure)));
+    const parsedMeasuresWithLexicalTerms = preferExplicitQuestionCompoundMeasures(uniqueRequirementTerms([
         ...parsedMeasures,
         ...nonRedundantLexicalMeasureTerms(parsedMeasures, question),
+        ...(salesIsRevenueAlias ? ['revenue'] : []),
+        ...(/\b(?:most|highest|expensive)\b.*\bproduct\s+price\b|\bproduct\s+price\b.*\b(?:most|highest|expensive)\b/i.test(question)
+            ? ['product price']
+            : []),
         ...(!deicticAmount
             && /\bamount\b/i.test(question)
             && !parsedMeasures.some((measure) => normalizeRequirementTerm(measure).split(' ').includes('amount'))
             ? ['amount']
             : []),
-    ]);
+    ]), question);
     const typedRequirements = normalizedTypedAggregationRequirements({
         question,
         measures: parsedMeasuresWithLexicalTerms,
         dimensions: requestedDimensions.filter((term) => !isTemporalTerm(term)),
     });
-    const measures = typedRequirements.measures;
-    const dimensions = typedRequirements.dimensions;
+    const explicitRankingMeasures = ranking
+        ? explicitRankingMeasureTerms(question, typedRequirements.measures)
+        : [];
+    // A direct ranking clause is the explicit analytical measure.  Keep broad
+    // parser/retrieval phrases out of the execution tuple so a contextual term
+    // cannot become a second ranking metric or force a false clarification.
+    const measures = explicitRankingMeasures.length > 0
+        ? explicitRankingMeasures
+        : typedRequirements.measures;
+    // Retrieval/parser hints sometimes repeat an explicit measure as a
+    // dimension (for example `revenue` in "show revenue by region").  Keep
+    // the user-authored measure authoritative and remove only an exact
+    // normalized duplicate.  A broader substring rule would incorrectly drop
+    // legitimate dimensions such as `product revenue category`.
+    const measureTerms = new Set(measures.map((measure) => normalizeRequirementTerm(measure)));
+    const dimensions = typedRequirements.dimensions.filter((dimension) => !measureTerms.has(normalizeRequirementTerm(dimension)));
     const rankingMetricTerms = ranking ? measures : [];
-    const parsedLimit = typeof parsed?.limit === 'number' && Number.isFinite(parsed.limit) && parsed.limit > 0
-        ? Math.floor(parsed.limit)
-        : undefined;
-    const explicitLimit = ranking?.[2] ? Number(ranking[2]) : parsedLimit;
-    const time = grain || fiscalPeriod
+    // A context planner supplies its own safety default (`topN: 10`) for bare
+    // rankings. It is a useful execution bound, but it is not user intent. Read
+    // an explicit count only from the actual question so the cascade/answer
+    // receipt can disclose that a bare “top” used DQL's default rather than
+    // misleadingly presenting it as a requested limit.
+    const wordRankingLimit = lower.match(/\b(?:top|bottom|highest|lowest|most|least|expensive|cheapest)\s+(one|two|three|four|five|six|seven|eight|nine|ten)\b|\b(one|two|three|four|five|six|seven|eight|nine|ten)\s+(?:most|least|expensive|cheapest)\b/i)?.slice(1).find(Boolean)?.toLowerCase();
+    const explicitWordLimit = {
+        one: 1, two: 2, three: 3, four: 4, five: 5,
+        six: 6, seven: 7, eight: 8, nine: 9, ten: 10,
+    };
+    const explicitLimit = ranking?.[2]
+        ? Number(ranking[2])
+        : leadingOrdinalRanking?.[1] ? Number(leadingOrdinalRanking[1])
+            : wordRankingLimit ? explicitWordLimit[wordRankingLimit] : undefined;
+    // A bounded window is a restriction on WHEN, distinct from grouping grain.
+    // It gets its own typed clause; without one, "last two months" had nowhere
+    // to live and silently vanished between the question and the query.
+    const window = parseAnalyticalTimeWindow(question);
+    const time = grain || fiscalPeriod || window
         ? {
             role: grain ? 'time_axis' : 'time_filter',
             ...(grain ? { grain: grain } : {}),
+            ...(window ? { window } : {}),
             ...(fiscalPeriod ? { fiscalPeriod } : {}),
             requiresDeclaredFiscalCalendar: Boolean(fiscalPeriod),
         }
@@ -242,13 +714,22 @@ export function buildAnalyticalRequirementSet(input) {
         dimensions,
         entityTerms,
         entityDisplayTerms,
-        memberTerms: uniqueRequirementTerms((parsed?.filters ?? []).map((filter) => filter.value)),
+        // A parser filter is useful but not the sole authority for an explicit
+        // current-turn member. Preserve bounded literal atoms too; downstream
+        // planning must still bind them to qualified snapshot evidence before a
+        // field/value predicate can be frozen.
+        memberTerms: uniqueRequirementTerms([
+            ...(parsed?.filters ?? []).map((filter) => filter.value),
+            ...currentQuestionLiteralMemberTerms(question),
+        ]),
+        ...(explicitOutputTerms(question).length > 0 ? { outputTerms: explicitOutputTerms(question) } : {}),
+        ...(/\bindividual\b/i.test(question) ? { grain: 'individual' } : {}),
         ...(ranking
             ? {
                 ranking: {
                     metricTerms: rankingMetricTerms,
                     entityTerms,
-                    direction: /bottom|lowest/i.test(ranking[1] ?? '') ? 'bottom' : 'top',
+                    direction: /bottom|lowest|least|cheapest/i.test(ranking[1] ?? '') ? 'bottom' : 'top',
                     limit: explicitLimit ?? 10,
                     defaultedLimit: explicitLimit === undefined,
                 },
@@ -257,34 +738,163 @@ export function buildAnalyticalRequirementSet(input) {
         ...(time ? { time } : {}),
     };
 }
-/** Classify the role an already-qualified candidate may fill. */
-export function evidenceCandidateRoles(candidate) {
-    const identity = uniqueRequirementTerms([
+const DECLARED_CANDIDATE_ROLE_ALIASES = [
+    ['metric', ['metric']],
+    ['entity_key', ['entity key', 'entity id']],
+    ['entity_label', ['entity label', 'display key', 'display label']],
+    ['categorical_dimension', ['categorical dimension', 'category dimension']],
+    ['time_dimension', ['time dimension', 'date dimension']],
+    ['member', ['member']],
+    ['relationship', ['relationship']],
+    ['context', ['context']],
+];
+/**
+ * Only an authored declaration may let an object fill an additional role.  A
+ * metric's capability lists dimensions, time grains, and relationship paths it
+ * *uses*; that does not make the metric itself a display key, time column, or
+ * relationship candidate.  Compatibility facts are snapshot-authored metadata
+ * and therefore the only additive role declaration accepted here.
+ */
+function explicitlyDeclaredCandidateRoles(candidate) {
+    const declared = new Set();
+    for (const fact of candidate.compatibilityFacts ?? []) {
+        const normalized = normalizeRequirementTerm(fact);
+        if (!/^(?:(?:candidate|evidence|intrinsic|supported) )?roles?\b/.test(normalized))
+            continue;
+        const suffix = normalized.replace(/^(?:(?:candidate|evidence|intrinsic|supported) )?roles?\s*/, '');
+        for (const [role, aliases] of DECLARED_CANDIDATE_ROLE_ALIASES) {
+            if (aliases.some((alias) => new RegExp(`(?:^| )${alias}(?:$| )`).test(suffix)))
+                declared.add(role);
+        }
+    }
+    return declared;
+}
+function intrinsicCandidateIdentity(candidate) {
+    return uniqueRequirementTerms([
         candidate.id,
         candidate.qualifiedId,
         candidate.name,
-        ...(candidate.aliases ?? []),
-        ...(candidate.dimensions ?? []),
-        ...(candidate.analyticalCapability?.dimensions ?? []).map((dimension) => dimension.dimensionId),
-        ...(candidate.analyticalCapability?.timeDimensions ?? []).map((dimension) => dimension.dimensionId),
     ]).join(' ');
+}
+/**
+ * Keep account display-key selection separate from common account attributes.
+ * Candidate names originate in dbt/semantic identifiers, so underscores and
+ * dots must be normalized before testing (`account_sentiment_rating` is just
+ * as much an attribute as "Account Sentiment Rating").
+ */
+export function hasEntityAttributeTerm(value) {
+    return /\b(?:owner|sentiment|email)\b/i.test(normalizeRequirementTerm(value));
+}
+export function isEntityAttributeCandidate(candidate) {
+    return hasEntityAttributeTerm(intrinsicCandidateIdentity(candidate));
+}
+/**
+ * Time is a type-level role, not a lexical synonym. Semantic indexes from
+ * dbt/MetricFlow commonly retain all members as `dimension`, so a typed
+ * `opened_date` must not also enter the ordinary categorical/geographic
+ * fallback lane. A card-level semantic-time class or physical/semantic type
+ * is authoritative. `timeGrains` alone is deliberately not: older retrieval
+ * adapters can inherit a model/metric's supported grains onto unrelated
+ * entity and display cards. Names are used only for legacy cards with no
+ * source type.
+ */
+function candidateHasDeclaredTimeRole(candidate) {
+    if (candidate.semanticObjectType === 'time_dimension')
+        return true;
+    const dataType = normalizeRequirementTerm(candidate.dataType ?? '');
+    return /(?:^| )(?:date|datetime|timestamp|timestamptz|timestampntz|time)(?:$| )/.test(dataType);
+}
+function candidateUsesLegacyTimeNameFallback(candidate) {
+    // A supplied type is authoritative even when a legacy name happens to
+    // contain `date` (for example a text display label). A missing/empty
+    // time-grain list is not a positive type declaration, so old untyped cards
+    // retain this safe fallback.
+    if (normalizeRequirementTerm(candidate.dataType ?? ''))
+        return false;
+    return /(?:\bdate\b|\btime\b|\bmonth\b|\bquarter\b|\byear\b|\bfiscal\b|\bperiod\b)/
+        .test(intrinsicCandidateIdentity(candidate));
+}
+/** Classify the role an already-qualified candidate may fill. */
+export function evidenceCandidateRoles(candidate) {
+    const identity = intrinsicCandidateIdentity(candidate);
     const roles = new Set();
-    if (candidate.kind === 'semantic_metric' || candidate.semanticObjectType === 'metric' || /\bmetric\b/.test(identity))
+    const physicalColumn = candidate.kind === 'sql_column';
+    // An explicit semantic metric remains a metric even if an old index also
+    // carries an imprecise type. Conversely, a typed semantic time dimension
+    // such as `metric_time` must not become a metric merely because its local
+    // compiler name contains the word "metric". The latter was causing V2 to
+    // admit the time card as a metric and discard its declared grains before
+    // semantic validation.
+    const explicitMetricCandidate = candidate.kind === 'semantic_metric'
+        || candidate.semanticObjectType === 'metric'
+        || candidate.semanticObjectType === 'measure';
+    const sourceDeclaredTimeRole = !explicitMetricCandidate && candidateHasDeclaredTimeRole(candidate);
+    const metricCandidate = explicitMetricCandidate
+        || (!sourceDeclaredTimeRole && (/\bmetric\b/.test(identity)
+            || (physicalColumn && /\b(?:revenue|amount|count|rate|bcm|spend|cost|margin|total)\b/.test(identity))));
+    // A temporal type/grain is stronger than an authored compatibility-role
+    // label. Index migrations can leave an old `roles categorical dimension`
+    // fact on a date field, but allowing that contradictory fact back into the
+    // ordinary inference lane turns time fields into false geography choices.
+    // Metrics retain their explicit compatibility roles because capability
+    // metadata is not the metric object's own temporal identity.
+    const declaredTimeRole = !metricCandidate && sourceDeclaredTimeRole;
+    const legacyTimeName = !metricCandidate
+        && !declaredTimeRole
+        && candidateUsesLegacyTimeNameFallback(candidate);
+    const temporalCandidate = declaredTimeRole || legacyTimeName;
+    if (metricCandidate)
         roles.add('metric');
-    if (candidate.semanticObjectType === 'entity' || /(?:^| )(?:account|customer|client|company) id\b/.test(identity) || /\bentity\b/.test(identity))
-        roles.add('entity_key');
-    if (/\b(?:account|customer|client|company)(?: name)?\b/.test(identity)
-        && /\b(?:name|label|display|account|customer|client|company)\b/.test(identity)
-        && !/\b(?:owner|sentiment|email)\b/.test(identity))
-        roles.add('entity_label');
-    if (/(?:\bdate\b|\btime\b|\bmonth\b|\bquarter\b|\byear\b)/.test(identity)
-        || (candidate.timeGrains?.length ?? 0) > 0
-        || (candidate.analyticalCapability?.timeDimensions?.length ?? 0) > 0)
-        roles.add('time_dimension');
-    if ((candidate.relationshipEvidence?.length ?? 0) > 0 || /\b(?:relationship|join|bridge)\b/.test(identity))
-        roles.add('relationship');
-    if (candidate.kind === 'semantic_member' || candidate.semanticObjectType === 'dimension')
-        roles.add('categorical_dimension');
+    // Capability metadata belongs to the metric's execution contract.  It must
+    // not be treated as the metric object's own entity, display, time, or join
+    // identity.  Explicit snapshot metadata is the only exception.
+    if (!metricCandidate) {
+        if (candidate.semanticObjectType === 'entity'
+            || /(?:^| )(?:account|customer|client|company) (?:id|key)\b/.test(identity)
+            || /\bentity\b/.test(identity))
+            roles.add('entity_key');
+        // Entity identity (for example `semantic:entity:account`) proves an
+        // entity key/grain but not the field a person can read in a ranking
+        // result.  Require an intrinsic display-name declaration instead of
+        // allowing every identifier that merely contains "account" or
+        // "customer" to fill the entity-label role.  Explicit authored role
+        // facts below remain the only additive exception.
+        if (/\b(?:account|customer|client|company)\b/.test(identity)
+            && /\b(?:name|label|display)\b/.test(identity)
+            && !hasEntityAttributeTerm(identity))
+            roles.add('entity_label');
+        if (temporalCandidate)
+            roles.add('time_dimension');
+        if ((candidate.kind === 'dql_modeling' && (candidate.relationshipEvidence?.length ?? 0) > 0)
+            || /\b(?:relationship|join|bridge)\b/.test(identity))
+            roles.add('relationship');
+        // `semantic_member` intentionally collapses dimensions, entities, models,
+        // and saved queries in older local indexes. Only a real (or legacy
+        // unclassified) dimension can be a categorical field. A semantic model or
+        // entity is execution context, never a user-visible grouping dimension.
+        const semanticDimension = candidate.semanticObjectType === 'dimension'
+            || (candidate.kind === 'semantic_member' && candidate.semanticObjectType === undefined);
+        // A time dimension can be grouped at a time grain, but it is not an
+        // ordinary categorical/geographic alternative for a business term such
+        // as `region`. Keep the role sets mutually exclusive here; the semantic
+        // compiler still receives the same qualified identity when time is asked.
+        if (!temporalCandidate
+            && (semanticDimension
+                || (physicalColumn && /\b(?:competitor|region|category|segment|status|type|owner|sentiment|active|product|description)\b/.test(identity)))) {
+            roles.add('categorical_dimension');
+        }
+        if (candidate.kind === 'semantic_member' && candidate.semanticObjectType === 'member')
+            roles.add('member');
+    }
+    for (const role of explicitlyDeclaredCandidateRoles(candidate)) {
+        // Do not let a stale/contradictory authored compatibility declaration
+        // reverse a source-authored temporal type or legacy temporal identity.
+        // The temporal role remains visible; only the conflicting ordinary
+        // categorical role is rejected.
+        if (temporalCandidate && role === 'categorical_dimension')
+            continue;
+        roles.add(role);
+    }
     if (candidate.kind === 'sql_column' || candidate.kind === 'dbt_model' || candidate.kind === 'sql_table')
         roles.add('context');
     if (roles.size === 0)
@@ -303,9 +913,63 @@ function candidateMatchesTerms(candidate, terms, options = {}) {
     ]).join(' ');
     if (terms.some((term) => identity.includes(term) || term.includes(identity)))
         return true;
+    if (options.categoricalDimension === true
+        && terms.some((term) => categoricalDimensionTermsMatch(term, identity)))
+        return true;
     return options.categoricalDimension === true
         && candidateMatchesCategoricalDimensionRequirement(candidate, terms);
 }
+/**
+ * A metric's attached dimensions, source model, and relationship path are
+ * execution context.  They are deliberately useful for binding a complete
+ * plan, but must never make one metric match the name of another.  In
+ * particular, `bcm_run_rate` from an `account_revenue` model is not the
+ * `revenue` ranking measure merely because its source-model identity contains
+ * that word.
+ */
+function metricCandidateIdentityTerms(candidate) {
+    const terminalMetricIdentity = (value) => {
+        if (!value)
+            return undefined;
+        const namespaceLeaf = value.split(':').filter(Boolean).at(-1) ?? value;
+        const metricLeaf = namespaceLeaf.split(/[./]/).filter(Boolean).at(-1) ?? namespaceLeaf;
+        return normalizeRequirementTerm(metricLeaf);
+    };
+    return uniqueRequirementTerms([
+        // Metadata cards sometimes use their source-qualified identifier as the
+        // display label (for example `account_revenue.bcm_run_rate`). Treat that
+        // exactly like an ID: its terminal metric leaf is intrinsic identity and
+        // its model prefix is execution context. A human label such as `Total
+        // Revenue` has no namespace separator and is retained intact.
+        terminalMetricIdentity(candidate.name),
+        ...(candidate.aliases ?? []).map(terminalMetricIdentity),
+        terminalMetricIdentity(candidate.id),
+        terminalMetricIdentity(candidate.qualifiedId),
+    ]);
+}
+function metricCandidateMatchesTerms(candidate, terms) {
+    const identities = metricCandidateIdentityTerms(candidate);
+    return terms.some((term) => {
+        const normalizedTerm = normalizeRequirementTerm(term);
+        if (!normalizedTerm)
+            return false;
+        return identities.some((identity) => identity === normalizedTerm
+            || identity.endsWith(` ${normalizedTerm}`)
+            || normalizedTerm.endsWith(` ${identity}`));
+    });
+}
+/**
+ * A direct ranking measure is authoritative for metric admission.  Other
+ * retrieved metrics remain visible in the lifecycle receipt, but they cannot
+ * become a second metric choice merely because they are correlated with the
+ * entity phrase in the question.
+ */
+export function candidateConflictsWithExplicitRankingMeasure(candidate, requirements) {
+    const metricTerms = requirements.ranking?.metricTerms ?? [];
+    return metricTerms.length > 0
+        && evidenceCandidateRoles(candidate).includes('metric')
+        && !metricCandidateMatchesTerms(candidate, metricTerms);
+}
 /**
  * A categorical dimension may satisfy a requested business role only through
  * its own snapshot-authored declaration. In particular, `location_name` is
@@ -315,6 +979,14 @@ function candidateMatchesTerms(candidate, terms, options = {}) {
  * broad lexical geography expansion while retaining role-balanced recall.
  */
 export function candidateMatchesCategoricalDimensionRequirement(candidate, terms) {
+    const extension = candidate.sameSnapshotRoleExtension;
+    if (extension?.role === 'categorical_dimension'
+        && (extension.basis === 'sole_metricflow_grouping_dimension'
+            || extension.basis === 'exact_metricflow_grouping_dimension')) {
+        const requested = new Set(terms.map(normalizeRequirementTerm).filter(Boolean));
+        if (requested.has(normalizeRequirementTerm(extension.requestedTerm)))
+            return true;
+    }
     const facts = new Set((candidate.compatibilityFacts ?? [])
         .map(normalizeRequirementTerm)
         .filter(Boolean));
@@ -339,7 +1011,12 @@ export function candidateMatchesCategoricalDimensionRequirement(candidate, terms
  * to two candidates before relevance fills remaining cards.
  */
 export function selectRoleBalancedMeaningCandidates(input) {
-    const max = Math.max(1, Math.min(16, Math.floor(input.maxCandidates ?? 16)));
+    // This selector is used twice by Ask Analyst Runtime: once to make the
+    // immutable 32-item execution workspace and again to make the compact
+    // 16-card planner package.  Keep the ceiling here rather than allowing a
+    // caller to accidentally turn a retrieval result into an unbounded prompt
+    // or compiler closure.
+    const max = Math.max(1, Math.min(32, Math.floor(input.maxCandidates ?? 16)));
     const ranked = [...new Map(input.candidates
             .filter((candidate) => candidate.id.trim() && candidate.compatibility !== 'incompatible')
             .map((candidate) => [candidate.id, candidate])).values()]
@@ -348,9 +1025,12 @@ export function selectRoleBalancedMeaningCandidates(input) {
         || left.id.localeCompare(right.id));
     const selected = [];
     const add = (candidate) => {
-        if (candidate && selected.length < max && !selected.some((item) => item.id === candidate.id))
+        if (!candidate || candidateConflictsWithExplicitRankingMeasure(candidate, input.requirements))
+            return;
+        if (selected.length < max && !selected.some((item) => item.id === candidate.id))
             selected.push(candidate);
     };
+    const categoricalTerms = categoricalDimensionRequirementTerms(input.requirements);
     const servesRequestedRole = (candidate) => {
         const roles = evidenceCandidateRoles(candidate);
         const metricTerms = input.requirements.ranking?.metricTerms.length
@@ -361,6 +1041,8 @@ export function selectRoleBalancedMeaningCandidates(input) {
         // An entity term such as "account" is deliberately insufficient for an
         // attribute (Account Owner Email) to displace the requested display key.
         // Only an actual entity-label candidate may satisfy this binding.
+        if (roles.includes('entity_key') && candidateMatchesTerms(candidate, input.requirements.entityTerms))
+            return true;
         if (roles.includes('entity_label') && candidateMatchesTerms(candidate, [
             ...input.requirements.entityTerms,
             ...input.requirements.entityDisplayTerms,
@@ -369,8 +1051,14 @@ export function selectRoleBalancedMeaningCandidates(input) {
         if (roles.includes('time_dimension') && Boolean(input.requirements.time))
             return true;
         if (roles.includes('categorical_dimension')
-            && input.requirements.dimensions.length > 0
-            && candidateMatchesTerms(candidate, input.requirements.dimensions, { categoricalDimension: true }))
+            && categoricalTerms.length > 0
+            && candidateMatchesTerms(candidate, categoricalTerms, { categoricalDimension: true }))
+            return true;
+        if (roles.includes('member') && input.requirements.memberTerms.length > 0
+            && candidateMatchesTerms(candidate, input.requirements.memberTerms))
+            return true;
+        if (roles.includes('categorical_dimension') && input.requirements.memberTerms.length > 0
+            && candidateHasSafeValueForMemberTerms(candidate, input.requirements.memberTerms))
             return true;
         if (roles.includes('relationship')
             && (input.requirements.dimensions.length > 1 || input.requirements.entityTerms.length > 0))
@@ -386,13 +1074,19 @@ export function selectRoleBalancedMeaningCandidates(input) {
         add(candidate);
     }
     const required = [
-        ['metric', input.requirements.ranking?.metricTerms.length ? input.requirements.ranking.metricTerms : input.requirements.measures],
-        ['entity_label', [...input.requirements.entityTerms, ...input.requirements.entityDisplayTerms]],
-        ['time_dimension', input.requirements.time ? [input.requirements.time.grain ?? 'time'] : []],
-        ['categorical_dimension', input.requirements.dimensions],
-        ['relationship', input.requirements.dimensions.length > 1 || input.requirements.entityTerms.length > 0 ? ['relationship'] : []],
+        // An explicit ranking measure is never displaced by correlated metric
+        // variants. Two cards leave room for a compatible canonical/alias pair.
+        { role: 'metric', terms: input.requirements.ranking?.metricTerms.length ? input.requirements.ranking.metricTerms : input.requirements.measures, limit: 2 },
+        { role: 'entity_key', terms: input.requirements.entityTerms, limit: 1 },
+        { role: 'entity_label', terms: [...input.requirements.entityTerms, ...input.requirements.entityDisplayTerms], limit: 2 },
+        // Each requested breakdown gets two candidates, bounded to four total so
+        // a product/category request cannot be crowded out by customer variants.
+        ...categoricalTerms.slice(0, 2).map((term) => ({ role: 'categorical_dimension', terms: [term], limit: 2, categorical: true })),
+        { role: 'time_dimension', terms: input.requirements.time ? [input.requirements.time.grain ?? 'time'] : [], limit: 2 },
+        { role: 'member', terms: input.requirements.memberTerms, limit: 2 },
+        { role: 'relationship', terms: input.requirements.dimensions.length > 1 || input.requirements.entityTerms.length > 0 ? ['relationship'] : [], limit: 2 },
     ];
-    for (const [role, terms] of required) {
+    for (const { role, terms, limit, categorical } of required) {
         // No requested categorical dimension means that high-scoring arbitrary
         // members are noise, not a role reservation. This is the subtle path that
         // used to admit Account Owner and Sentiment immediately after Account Name.
@@ -400,10 +1094,13 @@ export function selectRoleBalancedMeaningCandidates(input) {
             continue;
         let admitted = 0;
         for (const candidate of ranked) {
-            if (admitted >= 2 || selected.length >= max)
+            if (admitted >= limit || selected.length >= max)
                 break;
             const roles = evidenceCandidateRoles(candidate);
-            if (!roles.includes(role))
+            const safePhysicalMember = role === 'member'
+                && roles.includes('categorical_dimension')
+                && candidateHasSafeValueForMemberTerms(candidate, terms);
+            if (!roles.includes(role) && !safePhysicalMember)
                 continue;
             // "top accounts" needs the account display key, not any field whose
             // label happens to contain account. Once a display candidate is
@@ -411,7 +1108,7 @@ export function selectRoleBalancedMeaningCandidates(input) {
             // role nor a useful categorical reservation unless the user explicitly
             // named that attribute. This runs during the pre-cap pin pass so noisy
             // same-kind cards cannot enter through the categorical role.
-            const explicitlyRequestsAttribute = /\b(?:owner|sentiment|email)\b/i.test([
+            const explicitlyRequestsAttribute = hasEntityAttributeTerm([
                 ...input.requirements.dimensions,
                 ...input.requirements.entityTerms,
                 ...input.requirements.entityDisplayTerms,
@@ -424,12 +1121,13 @@ export function selectRoleBalancedMeaningCandidates(input) {
             if (role === 'categorical_dimension'
                 && hasRequestedEntityLabel
                 && !explicitlyRequestsAttribute
-                && /\b(?:owner|sentiment|email)\b/i.test(candidate.name ?? candidate.id))
+                && isEntityAttributeCandidate(candidate))
                 continue;
             // For entity labels, role is more important than a lexical owner/email
             // hit. For all other roles, prefer an identity matching the requested
             // business term but retain a role candidate when the request is terse.
-            if (terms.length > 0 && !candidateMatchesTerms(candidate, terms, { categoricalDimension: role === 'categorical_dimension' })
+            if (terms.length > 0 && !safePhysicalMember
+                && !candidateMatchesTerms(candidate, terms, { categoricalDimension: categorical === true })
                 && role !== 'time_dimension' && role !== 'relationship' && role !== 'entity_label')
                 continue;
             add(candidate);
@@ -442,17 +1140,38 @@ export function selectRoleBalancedMeaningCandidates(input) {
     }
     return selected;
 }
+/** Exact snapshot-value equality only; no lexical/synonym member matching. */
+function candidateHasSafeValueForMemberTerms(candidate, terms) {
+    const values = candidate.safeValueEvidence ?? [];
+    return terms.some((term) => {
+        const normalized = normalizeRequirementTerm(term);
+        return Boolean(normalized) && values.some((value) => normalizeRequirementTerm(value.normalizedValue ?? value.value ?? '') === normalized);
+    });
+}
+/**
+ * Build the Ask execution workspace before planner admission.  It is the
+ * only helper that may create the 32-card closure; all later compiler paths
+ * must intersect with this immutable result rather than reaching back into a
+ * broad snapshot.
+ */
+export function selectRoleBalancedWorkspaceCandidates(input) {
+    return selectRoleBalancedMeaningCandidates({
+        candidates: input.candidates,
+        requirements: input.requirements,
+        maxCandidates: 32,
+    });
+}
 export function classifyProviderFailure(input) {
     const text = `${input.code ?? ''} ${input.message ?? ''}`.toLowerCase();
     const cause = /cancel/.test(text) ? 'cancelled'
         : /dispatch.?budget|provider_dispatch_budget/.test(text) ? 'dispatch_budget'
-            : /deadline.?insufficient|admission|soft.?target/.test(text) ? 'admission_denied'
+            : /deadline.?insufficient|admission|soft.?target|provider_result_rows_(?:blocked|limit_exceeded)/.test(text) ? 'admission_denied'
                 : /run.?deadline|time limit/.test(text) ? 'run_deadline'
                     : /timeout|timed out/.test(text) ? 'provider_timeout'
                         : /401|403|api key|unauthori[sz]ed|auth(?:entication)?/.test(text) ? 'authentication'
                             : /model(?:[ _-]+|\s+).*not[ _-]?found|unknown model|model_not_found|404/.test(text) ? 'model_not_found'
                                 : /429|rate[ _-]?limit|too many requests/.test(text) ? 'rate_limited'
-                                    : /502|503|504|gateway/.test(text) ? 'gateway'
+                                    : /\b5\d{2}\b|gateway/.test(text) ? 'gateway'
                                         : /econn|network|fetch failed|not reachable|connection refused/.test(text) ? 'network'
                                             : 'unknown';
     const retryable = cause === 'rate_limited' || cause === 'gateway' || cause === 'network' || cause === 'provider_timeout';
@@ -461,7 +1180,7 @@ export function classifyProviderFailure(input) {
             : cause === 'cancelled' ? 'none'
                 : 'inspect_run';
     const httpStatusClass = /\b(?:401|403|404|429)\b/.test(text) ? '4xx'
-        : /\b(?:502|503|504)\b/.test(text) ? '5xx'
+        : /\b5\d{2}\b/.test(text) ? '5xx'
             : undefined;
     return {
         version: 1,
@@ -476,6 +1195,29 @@ export function classifyProviderFailure(input) {
     };
 }
 export function buildAnalyticalCascadeDecision(input) {
+    // A frozen tier is the end of the authoritative cascade.  Later tiers are
+    // neither evaluated nor eligible as a fallback, even when the selected
+    // compiler, adapter, or execution target subsequently fails.  Retaining
+    // pre-built later attempts in the receipt makes a truthful post-freeze
+    // failure look like a silent downgrade and invalidates portable replay.
+    // Normalize at the shared construction boundary so every router path and
+    // every emitted trace receives the same immutable attempt prefix.
+    const attempts = [];
+    for (const inputAttempt of input.attempts) {
+        const attempt = {
+            ...inputAttempt,
+            version: 1,
+            candidateIds: [...new Set(inputAttempt.candidateIds)].slice(0, 32),
+            // Decision-level `planFrozen` is the server-owned source of truth. A
+            // legacy caller may have stamped it only on the decision; keep the
+            // selected attempt coherent before enforcing the immutable prefix.
+            planFrozen: inputAttempt.planFrozen
+                || (input.planFrozen === true && input.selectedTier === inputAttempt.tier),
+        };
+        attempts.push(attempt);
+        if (attempt.planFrozen)
+            break;
+    }
     return {
         version: 1,
         ...input,
@@ -484,7 +1226,15 @@ export function buildAnalyticalCascadeDecision(input) {
             version: 1,
             candidateIds: [...new Set(coverage.candidateIds)].slice(0, 32),
         })),
-        attempts: input.attempts.map((attempt) => ({ ...attempt, version: 1, candidateIds: [...new Set(attempt.candidateIds)].slice(0, 32) })),
+        attempts,
+        ...(input.terminalGap ? {
+            terminalGap: {
+                version: 1,
+                code: 'MISSING_RELATIONSHIP',
+                requirement: 'certified_relationship_or_allocation_proof',
+                witnessCandidateIds: [...new Set(input.terminalGap.witnessCandidateIds)].sort().slice(0, 32),
+            },
+        } : {}),
     };
 }
 /**
@@ -516,23 +1266,76 @@ export function splitAnalyticalTasks(question) {
     const parts = (asked.length > 0 ? asked : raw)
         .map((part) => part.replace(leadingJunk, '').replace(trailingJunk, '').trim())
         .filter(Boolean);
-    return parts.length > 0 ? parts : [question.trim()];
+    // "… and give me top 5 rows" is a RANKING CLAUSE of the request before it,
+    // not an independent question — it names no measure, no entity, nothing to
+    // ask about on its own. Splitting it minted a task titled "give me top 5
+    // rows" that could never resolve, and the phantom task then spent the
+    // dispatch budget the real question needed. A fragment that is nothing but
+    // shape vocabulary folds back into its predecessor.
+    const merged = [];
+    for (const part of parts) {
+        if (merged.length > 0 && isPureShapeClause(part)) {
+            merged[merged.length - 1] = `${merged[merged.length - 1]} and ${part}`;
+            continue;
+        }
+        merged.push(part);
+    }
+    return merged.length > 0 ? merged : [question.trim()];
+}
+/**
+ * Does this fragment carry ONLY result-shape vocabulary (ranking, limit,
+ * projection), with no subject of its own? Checked by removal: strip the
+ * shape words, counts and connectives; a real question leaves a residue.
+ */
+function isPureShapeClause(fragment) {
+    const lower = fragment.toLowerCase();
+    if (!/\b(?:top|bottom|first|last|highest|lowest|limit|rows?|results?)\b/.test(lower))
+        return false;
+    const residue = lower
+        .replace(/\b(?:and|then|please|give|me|show|list|just|only|the|a|an|top|bottom|first|last|highest|lowest|best|worst|limit|it|to|of|them|rows?|results?|records?|entries|items?|values?)\b/g, ' ')
+        .replace(/\b(?:one|two|three|four|five|six|seven|eight|nine|ten|twelve)\b/g, ' ')
+        .replace(/\d+/g, ' ')
+        .replace(/[^a-z]+/g, ' ')
+        .trim();
+    return residue.length === 0;
 }
 export function buildAnalyticalTaskGraph(input) {
-    const rootKind = input.mode === 'research' ? 'research' : inferAnalyticalTurnKind(input.question);
+    // Research is an explicit mode boundary. Investigative wording in an
+    // ordinary Ask can influence its operations but must not silently switch it
+    // to the multi-branch Research budget/execution contract.
+    const inferredKind = inferAnalyticalTurnKind(input.question);
+    const rootKind = input.mode === 'research'
+        ? 'research'
+        : inferredKind === 'research'
+            ? 'diagnosis'
+            : inferredKind;
     // A research turn may later create bounded evidence branches, but that is a
     // research planner's job. Splitting at ingress loses the surrounding story
     // before it has an opportunity to reason about it.
-    const clauses = (rootKind === 'research' ? [input.question.trim()] : splitAnalyticalTasks(input.question))
-        .slice(0, Math.max(1, Math.min(6, input.maxTasks ?? 6)));
+    const sourceClauses = rootKind === 'research'
+        ? [input.question.trim()]
+        : splitAnalyticalTasks(input.question);
+    const taskCap = Math.max(1, Math.min(6, input.maxTasks ?? 6));
+    // Keep the overflow visible to the runtime.  The prior `slice()` silently
+    // accepted the first three ordinary-Ask clauses and returned `partial:
+    // false`, which could make a four-question request look successfully
+    // answered after only three frozen programs.  Ordinary Ask must stop before
+    // planning/execution in that case; explicit Research owns broader branching.
+    const partial = sourceClauses.length > taskCap;
+    const clauses = sourceClauses.slice(0, taskCap);
     const candidateIds = [...new Set((input.candidateIds ?? []).filter((id) => id.trim()))];
     const metrics = [...new Set((input.metrics ?? []).filter((metric) => metric.trim()))];
     const dimensions = [...new Set((input.dimensions ?? []).filter((dimension) => dimension.trim()))];
     const filters = input.filters ?? [];
     const inheritedBindings = input.inheritedBindings ?? [];
     const unboundTasks = clauses.map((clause, index) => {
-        const kind = rootKind === 'research' ? 'research' : inferAnalyticalTurnKind(clause);
-        const research = kind === 'research' || kind === 'diagnosis';
+        const inferredClauseKind = rootKind === 'research' ? 'research' : inferAnalyticalTurnKind(clause);
+        const kind = rootKind === 'research'
+            ? 'research'
+            : inferredClauseKind === 'research'
+                ? 'diagnosis'
+                : inferredClauseKind;
+        const research = rootKind === 'research';
         const taskKind = research
             ? 'research_branch'
             : kind === 'lookup'
@@ -567,7 +1370,7 @@ export function buildAnalyticalTaskGraph(input) {
     return {
         kind: rootKind === 'research' ? 'research' : tasks.length > 1 ? 'compound' : rootKind,
         tasks,
-        partial: false,
+        partial,
     };
 }
 const TOP_RANKED_REGION_RE = /(?:\b(?:top|highest|most)\b[^?.!]{0,72}\bregions?\b|\bregions?\b[^?.!]{0,72}\b(?:top|highest|most)\b)/i;
@@ -957,6 +1760,89 @@ export async function retrieveContextLanes(lanes, limit = 32, maxConcurrent = 4)
     }
     return fused;
 }
+function ledgerFactIdsV3(branchId, facts) {
+    const byFact = new Map();
+    const ids = [];
+    for (const fact of facts) {
+        const normalized = fact.trim();
+        if (!normalized || byFact.has(normalized))
+            continue;
+        const id = `fact:${branchId}:${ids.length + 1}`;
+        ids.push(id);
+        byFact.set(normalized, id);
+    }
+    return { ids, byFact };
+}
+/**
+ * Build a mixed V3 ledger without reinterpreting V1/V2.  The legacy ledgers
+ * continue to contain analytical branches only, because their `observed`
+ * state requires an execution/result receipt and would otherwise falsely
+ * represent a graph walk as query execution.
+ */
+export function buildResearchEvidenceLedgerV3(input) {
+    const entries = input.entries
+        .slice(0, 6)
+        .sort((left, right) => left.index - right.index || left.kind.localeCompare(right.kind))
+        .map((source) => {
+        if (source.kind === 'analytical_result') {
+            const entry = source.entry;
+            const facts = ledgerFactIdsV3(entry.branchId, entry.facts);
+            const counterEvidenceFactIds = [...new Set(entry.counterEvidenceFactIds)]
+                .flatMap((fact) => facts.byFact.get(fact) ? [facts.byFact.get(fact)] : []);
+            const resultFingerprint = normalizeAnalyticalExecutionFingerprint(entry.resultFingerprint);
+            return {
+                version: 3,
+                id: entry.id,
+                branchId: entry.branchId,
+                evidenceKind: 'analytical_result',
+                status: entry.status,
+                verdict: entry.verdict,
+                ...(source.hypothesisFingerprint ? { hypothesisFingerprint: source.hypothesisFingerprint } : {}),
+                factIds: facts.ids,
+                counterEvidenceFactIds,
+                receiptFingerprints: resultFingerprint ? [resultFingerprint] : [],
+                ...(resultFingerprint ? { resultFingerprint } : {}),
+            };
+        }
+        const facts = ledgerFactIdsV3(source.branchId, [
+            `lineage:${source.receipt.status}`,
+            `lineage:resolution:${source.receipt.resolution}`,
+        ]);
+        const status = source.status
+            ?? (source.receipt.status === 'completed' || source.receipt.status === 'truncated'
+                ? 'observed'
+                : 'failed');
+        return {
+            version: 3,
+            id: source.id,
+            branchId: source.branchId,
+            evidenceKind: 'lineage_graph',
+            status,
+            // The local graph can establish a structural dependency. It cannot
+            // establish causation, even when a complete path exists.
+            verdict: status === 'skipped' ? 'skipped' : 'inconclusive',
+            ...(source.hypothesisFingerprint ? { hypothesisFingerprint: source.hypothesisFingerprint } : {}),
+            factIds: facts.ids,
+            counterEvidenceFactIds: [],
+            receiptFingerprints: source.receipt.structuralFingerprint ? [source.receipt.structuralFingerprint] : [],
+            lineageReceipt: source.receipt,
+        };
+    });
+    const observedGroundableBranchCount = entries.filter((entry) => entry.status === 'observed' && entry.verdict !== 'skipped').length;
+    const plannedGroundableBranchCount = Math.max(0, Math.min(6, Math.trunc(input.groundableBranchCount ?? 0)));
+    const groundableBranchCount = Math.max(observedGroundableBranchCount, plannedGroundableBranchCount);
+    return {
+        version: 3,
+        rootQuestionFingerprint: input.rootQuestionFingerprint,
+        ...(input.planId ? { planId: input.planId } : {}),
+        ...(input.snapshotId ? { snapshotId: input.snapshotId } : {}),
+        entries,
+        factIds: [...new Set(entries.flatMap((entry) => [...entry.factIds, ...entry.counterEvidenceFactIds]))],
+        groundableBranchCount,
+        limitedScope: groundableBranchCount < 3,
+        stoppingReason: input.stoppingReason ?? (entries.length > 0 ? 'completed' : 'not_started'),
+    };
+}
 export function capResearchBranches(branches, max = 6) {
     return branches.slice(0, Math.max(1, Math.min(6, Math.trunc(max))));
 }