@duckcodeailabs/dql-agent 1.14.2 → 1.14.3-rc.1

package/dist/analytical-orchestration.js

@@ -13,6 +13,133 @@
  */
 import { createHash } from 'node:crypto';
 export const ANALYTICAL_ORCHESTRATION_CONTRACT_VERSION = 1;
+/** 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 requirements = input.requirements ?? buildAnalyticalRequirementSet({
+        question: input.question,
+        parsedIntent: parsed,
+    });
+    // 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 }));
+    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,
+            ...(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;
+        return /^(?:last|previous|past) \d+ (?:day|days|week|weeks|month|months|quarter|quarters|year|years)$/.test(normalized)
+            && normalizeRequirementTerm(question).includes(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.
+    };
+}
 /**
  * Small, explainable intent vocabulary used before the physical plan exists.
  * It is deliberately not a second semantic matcher: candidate identity still
@@ -54,6 +181,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 +275,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
@@ -127,7 +327,16 @@ function normalizedTypedAggregationRequirements(input) {
 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
+        .map(canonicalMeasureAlias)
         .filter((value) => !isStructuralMeasurePhrase(value))
         .filter((value) => !(groupedOrderCount && /^(?:order|orders)$/i.test(normalizeRequirementTerm(value))));
     if (groupedOrderCount && !terms.some((value) => normalizeRequirementTerm(value) === 'count')) {
@@ -172,6 +381,43 @@ function nonRedundantLexicalMeasureTerms(parsedMeasures, question) {
             .some((word) => word === token || (token === 'refund' && word === 'refunds')));
     });
 }
+/**
+ * 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 +426,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 +440,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,10 +460,19 @@ 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 ?? []);
+    // `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 = 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'))
@@ -221,13 +484,31 @@ export function buildAnalyticalRequirementSet(input) {
         measures: parsedMeasuresWithLexicalTerms,
         dimensions: requestedDimensions.filter((term) => !isTemporalTerm(term)),
     });
-    const measures = typedRequirements.measures;
+    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;
     const dimensions = typedRequirements.dimensions;
     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;
+    // 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;
     const time = grain || fiscalPeriod
         ? {
             role: grain ? 'time_axis' : 'time_filter',
@@ -243,12 +524,14 @@ export function buildAnalyticalRequirementSet(input) {
         entityTerms,
         entityDisplayTerms,
         memberTerms: uniqueRequirementTerms((parsed?.filters ?? []).map((filter) => filter.value)),
+        ...(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 +540,98 @@ 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));
+}
+/** 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';
+    const metricCandidate = candidate.kind === 'semantic_metric'
+        || candidate.semanticObjectType === 'metric'
+        || candidate.semanticObjectType === 'measure'
+        || /\bmetric\b/.test(identity)
+        || (physicalColumn && /\b(?:revenue|amount|count|rate|bcm|spend|cost|margin|total)\b/.test(identity));
+    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 (/(?:\bdate\b|\btime\b|\bmonth\b|\bquarter\b|\byear\b|\bfiscal\b|\bperiod\b)/.test(identity)
+            || (candidate.timeGrains?.length ?? 0) > 0)
+            roles.add('time_dimension');
+        if ((candidate.kind === 'dql_modeling' && (candidate.relationshipEvidence?.length ?? 0) > 0)
+            || /\b(?:relationship|join|bridge)\b/.test(identity))
+            roles.add('relationship');
+        if (candidate.kind === 'semantic_member' || candidate.semanticObjectType === 'dimension'
+            || (physicalColumn && /\b(?:competitor|region|category|segment|status|type|owner|sentiment|active)\b/.test(identity)))
+            roles.add('categorical_dimension');
+    }
+    for (const role of explicitlyDeclaredCandidateRoles(candidate))
+        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 +650,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 +716,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));
@@ -348,7 +757,9 @@ 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 servesRequestedRole = (candidate) => {
@@ -368,9 +779,10 @@ export function selectRoleBalancedMeaningCandidates(input) {
             return true;
         if (roles.includes('time_dimension') && Boolean(input.requirements.time))
             return true;
+        const categoricalTerms = categoricalDimensionRequirementTerms(input.requirements);
         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('relationship')
             && (input.requirements.dimensions.length > 1 || input.requirements.entityTerms.length > 0))
@@ -389,7 +801,7 @@ export function selectRoleBalancedMeaningCandidates(input) {
         ['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],
+        ['categorical_dimension', categoricalDimensionRequirementTerms(input.requirements)],
         ['relationship', input.requirements.dimensions.length > 1 || input.requirements.entityTerms.length > 0 ? ['relationship'] : []],
     ];
     for (const [role, terms] of required) {
@@ -411,7 +823,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,7 +836,7 @@ 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
@@ -446,13 +858,13 @@ 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 +873,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 +888,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 +919,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),
+            },
+        } : {}),
     };
 }
 /**