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

package/dist/analytical-orchestration.js

@@ -12,7 +12,57 @@
  * 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
@@ -22,10 +72,11 @@ export function buildAnalyticalRequirementSeedV1(input) {
     // 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({
+    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`.
@@ -34,6 +85,13 @@ export function buildAnalyticalRequirementSeedV1(input) {
         : 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 });
@@ -56,7 +114,13 @@ export function buildAnalyticalRequirementSeedV1(input) {
                     ...requirements.entityDisplayTerms,
                 ])],
             filters,
-            ...(parsed?.timeRange ? { timeRange: parsed.timeRange } : {}),
+            // 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 } : {}),
@@ -118,8 +182,18 @@ export function currentQuestionGroundedParsedIntent(question, parsedIntent) {
             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);
+        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);
@@ -140,6 +214,63 @@ export function currentQuestionGroundedParsedIntent(question, parsedIntent) {
         // 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
@@ -319,14 +450,15 @@ function explicitOutputTerms(question) {
  * 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
@@ -337,11 +469,7 @@ export function normalizeAnalyticalMeasureTerms(question, values, options = {})
     };
     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')) {
-        terms.push('count');
-    }
+        .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
@@ -365,20 +493,72 @@ 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)));
     });
 }
 /**
@@ -466,7 +646,7 @@ export function buildAnalyticalRequirementSet(input) {
     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([
+    const parsedMeasuresWithLexicalTerms = preferExplicitQuestionCompoundMeasures(uniqueRequirementTerms([
         ...parsedMeasures,
         ...nonRedundantLexicalMeasureTerms(parsedMeasures, question),
         ...(salesIsRevenueAlias ? ['revenue'] : []),
@@ -478,7 +658,7 @@ export function buildAnalyticalRequirementSet(input) {
             && !parsedMeasures.some((measure) => normalizeRequirementTerm(measure).split(' ').includes('amount'))
             ? ['amount']
             : []),
-    ]);
+    ]), question);
     const typedRequirements = normalizedTypedAggregationRequirements({
         question,
         measures: parsedMeasuresWithLexicalTerms,
@@ -493,7 +673,13 @@ export function buildAnalyticalRequirementSet(input) {
     const measures = explicitRankingMeasures.length > 0
         ? explicitRankingMeasures
         : typedRequirements.measures;
-    const dimensions = typedRequirements.dimensions;
+    // 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 : [];
     // 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
@@ -509,10 +695,15 @@ export function buildAnalyticalRequirementSet(input) {
         ? Number(ranking[2])
         : leadingOrdinalRanking?.[1] ? Number(leadingOrdinalRanking[1])
             : wordRankingLimit ? explicitWordLimit[wordRankingLimit] : undefined;
-    const time = grain || fiscalPeriod
+    // 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),
         }
@@ -523,7 +714,14 @@ 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
@@ -590,16 +788,61 @@ export function hasEntityAttributeTerm(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();
     const physicalColumn = candidate.kind === 'sql_column';
-    const metricCandidate = candidate.kind === 'semantic_metric'
+    // 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'
-        || /\bmetric\b/.test(identity)
-        || (physicalColumn && /\b(?:revenue|amount|count|rate|bcm|spend|cost|margin|total)\b/.test(identity));
+        || 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');
     // Capability metadata belongs to the metric's execution contract.  It must
@@ -620,18 +863,38 @@ export function evidenceCandidateRoles(candidate) {
             && /\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)
+        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');
-        if (candidate.kind === 'semantic_member' || candidate.semanticObjectType === 'dimension'
-            || (physicalColumn && /\b(?:competitor|region|category|segment|status|type|owner|sentiment|active)\b/.test(identity)))
+        // `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))
+    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)
@@ -748,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()]
@@ -762,6 +1030,7 @@ export function selectRoleBalancedMeaningCandidates(input) {
         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
@@ -772,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,
@@ -779,11 +1050,16 @@ 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')
             && 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))
             return true;
@@ -798,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', categoricalDimensionRequirementTerms(input.requirements)],
-        ['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.
@@ -812,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
@@ -841,7 +1126,8 @@ export function selectRoleBalancedMeaningCandidates(input) {
             // 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);
@@ -854,6 +1140,27 @@ 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'
@@ -959,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'
@@ -1010,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;
@@ -1400,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))));
 }