@duckcodeailabs/dql-agent 1.14.1 → 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
@@ -41,6 +168,768 @@ export function inferAnalyticalTurnKind(question) {
         return 'lookup';
     return 'aggregation';
 }
+function normalizeRequirementTerm(value) {
+    return value.toLowerCase()
+        .replace(/[_./:-]+/g, ' ')
+        .replace(/[^a-z0-9 ]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function uniqueRequirementTerms(values) {
+    return [...new Set(values
+            .filter((value) => typeof value === 'string')
+            .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);
+}
+/**
+ * Parser output occasionally retains the grammatical wrapper around an
+ * aggregation (for example "count for each customer") as though it were a
+ * second metric.  The stable requirement is `count`; the rest describes the
+ * requested grain and is already represented by the entity/dimension roles.
+ * Keeping the wrapper makes a physically complete customer table look
+ * incomplete and prematurely terminates the pre-freeze cascade.
+ */
+function isStructuralMeasurePhrase(value) {
+    const term = normalizeRequirementTerm(value);
+    return /^(?:count|sum|total|average|avg)?\s*for\s+(?:each|every)\s+(?:account|customer|client|company|product|order|item|row)s?$/.test(term)
+        || /^for\s+(?:each|every)\s+(?:account|customer|client|company|product|order|item|row)s?$/.test(term);
+}
+const AGGREGATION_REQUIREMENT_OPERATORS = new Set([
+    'total', 'sum', 'average', 'avg', 'minimum', 'min', 'maximum', 'max',
+]);
+/**
+ * A parsed intent may preserve every grammatical fragment of an aggregate
+ * request ("total", "total supply cost", "supply", and "product").  Those
+ * fragments are useful while retrieving, but they are not independent
+ * physical requirements. Normalize only the explicit aggregation + grouping
+ * construction so ordinary named metrics such as `total_revenue` keep their
+ * authored identity.
+ */
+function typedAggregationRequirementRoles(question) {
+    const match = /\b(?:total|sum|average|avg|minimum|min|maximum|max)\s+([a-z][a-z0-9_ -]{1,60}?)\s+(?:per|by|for\s+each)\s+([a-z][a-z0-9_-]*)\b/i.exec(question);
+    const measure = match?.[1] ? normalizeRequirementTerm(match[1]) : '';
+    const dimension = match?.[2] ? normalizeRequirementTerm(match[2]) : '';
+    return measure && dimension ? { measure, dimension } : undefined;
+}
+function normalizedTypedAggregationRequirements(input) {
+    const typed = typedAggregationRequirementRoles(input.question);
+    if (!typed)
+        return input;
+    const measureParts = new Set(typed.measure.split(' ').filter(Boolean));
+    const measures = uniqueRequirementTerms([
+        typed.measure,
+        ...input.measures.filter((value) => {
+            const normalized = normalizeRequirementTerm(value);
+            return normalized !== typed.measure
+                && !AGGREGATION_REQUIREMENT_OPERATORS.has(normalized)
+                && normalized !== `total ${typed.measure}`
+                && !(normalized.split(' ').length === 1 && measureParts.has(normalized));
+        }),
+    ]);
+    const dimensions = uniqueRequirementTerms([
+        typed.dimension,
+        ...input.dimensions.filter((value) => {
+            const normalized = normalizeRequirementTerm(value);
+            return normalized !== typed.dimension
+                && !(normalized.split(' ').length === 1 && measureParts.has(normalized));
+        }),
+    ]);
+    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
+ * phrases, but an immutable plan must never treat "count for each customer"
+ * 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.
+ */
+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')) {
+        terms.push('count');
+    }
+    // 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
+    // here lost the only sticky reference a measure-less refinement carried.
+    if (options.preserveIdentity) {
+        const seen = new Set();
+        return terms.flatMap((value) => {
+            const exact = value.replace(/\s+/g, ' ').trim();
+            const normalized = normalizeRequirementTerm(exact);
+            if (!exact || !normalized || seen.has(normalized))
+                return [];
+            seen.add(normalized);
+            return [exact];
+        });
+    }
+    return uniqueRequirementTerms(terms);
+}
+/**
+ * Parsed measure phrases are the most specific typed evidence available before
+ * meaning resolution. A lexical root is useful only when the parser found no
+ * 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.
+ */
+function nonRedundantLexicalMeasureTerms(parsedMeasures, question) {
+    const lexical = ['revenue', 'refund', 'refunds', 'bcm', 'run rate', 'count']
+        .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)
+            .split(' ')
+            .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
+ * bounded meaning resolver instead of being guessed here.
+ */
+export function buildAnalyticalRequirementSet(input) {
+    const question = input.question;
+    const lower = question.toLowerCase();
+    // 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'
+        : grainWord === 'weekly' ? 'week'
+            : grainWord === 'monthly' ? 'month'
+                : grainWord === 'quarterly' ? 'quarter'
+                    : grainWord === 'yearly' ? 'year'
+                        : /^(day|week|month|quarter|year)$/.test(grainWord) ? grainWord
+                            : 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|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$/, ''));
+    // 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
+    // choose an `amount` metric. Treating it as a new explicit measure made a
+    // compositional follow-up reject every otherwise-valid display/predicate
+    // 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);
+    // `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'))
+            ? ['amount']
+            : []),
+    ]);
+    const typedRequirements = normalizedTypedAggregationRequirements({
+        question,
+        measures: parsedMeasuresWithLexicalTerms,
+        dimensions: requestedDimensions.filter((term) => !isTemporalTerm(term)),
+    });
+    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 : [];
+    // 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',
+            ...(grain ? { grain: grain } : {}),
+            ...(fiscalPeriod ? { fiscalPeriod } : {}),
+            requiresDeclaredFiscalCalendar: Boolean(fiscalPeriod),
+        }
+        : undefined;
+    return {
+        version: 1,
+        measures,
+        dimensions,
+        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|least|cheapest/i.test(ranking[1] ?? '') ? 'bottom' : 'top',
+                    limit: explicitLimit ?? 10,
+                    defaultedLimit: explicitLimit === undefined,
+                },
+            }
+            : {}),
+        ...(time ? { time } : {}),
+    };
+}
+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,
+    ]).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();
+    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');
+    // 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)
+        roles.add('context');
+    return [...roles];
+}
+function candidateMatchesTerms(candidate, terms, options = {}) {
+    if (terms.length === 0)
+        return false;
+    const identity = uniqueRequirementTerms([
+        candidate.id,
+        candidate.qualifiedId,
+        candidate.name,
+        ...(candidate.aliases ?? []),
+        ...(candidate.dimensions ?? []),
+    ]).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
+ * not a synonym for `region`: it can fill a region lane only when metadata
+ * explicitly says `alternative-for:region`, or when the dimension itself is
+ * declared with the semantic geography role. This protects admission from
+ * 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));
+    if (facts.size === 0)
+        return false;
+    const requestedRoles = [...new Set(terms.flatMap((term) => {
+            const normalized = normalizeRequirementTerm(term);
+            const terminal = normalized.split(' ').at(-1) ?? '';
+            return [normalized, terminal].filter(Boolean);
+        }))];
+    const hasDeclaredAlternative = requestedRoles.some((role) => facts.has(`alternative for ${role}`)
+        || facts.has(`dimension alternative for ${role}`));
+    if (hasDeclaredAlternative)
+        return true;
+    const declaredGeography = facts.has('semantic role geography')
+        || facts.has('semantic geography role');
+    return declaredGeography && requestedRoles.some((role) => role === 'region' || role === 'geography' || role === 'geographic');
+}
+/**
+ * Keep an internal retrieval result broad while making the provider package
+ * role-balanced. Exact/alias matches stay pinned; each requested role gets up
+ * 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)));
+    const ranked = [...new Map(input.candidates
+            .filter((candidate) => candidate.id.trim() && candidate.compatibility !== 'incompatible')
+            .map((candidate) => [candidate.id, candidate])).values()]
+        .sort((left, right) => Number(Boolean(right.exactMatch)) - Number(Boolean(left.exactMatch))
+        || (right.relevanceScore ?? 0) - (left.relevanceScore ?? 0)
+        || left.id.localeCompare(right.id));
+    const selected = [];
+    const add = (candidate) => {
+        if (!candidate || candidateConflictsWithExplicitRankingMeasure(candidate, input.requirements))
+            return;
+        if (selected.length < max && !selected.some((item) => item.id === candidate.id))
+            selected.push(candidate);
+    };
+    const servesRequestedRole = (candidate) => {
+        const roles = evidenceCandidateRoles(candidate);
+        const metricTerms = input.requirements.ranking?.metricTerms.length
+            ? input.requirements.ranking.metricTerms
+            : input.requirements.measures;
+        if (roles.includes('metric') && candidateMatchesTerms(candidate, metricTerms))
+            return true;
+        // 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_label') && candidateMatchesTerms(candidate, [
+            ...input.requirements.entityTerms,
+            ...input.requirements.entityDisplayTerms,
+        ]))
+            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('relationship')
+            && (input.requirements.dimensions.length > 1 || input.requirements.entityTerms.length > 0))
+            return true;
+        return false;
+    };
+    for (const candidate of ranked.filter((candidate) => candidate.exactMatch)) {
+        // In a pin-only prepass, an exact match is only a pin when it serves a
+        // requested analytical role. Otherwise a pile of exact members consumes
+        // the whole package before the requested metric/entity can be reserved.
+        if (input.pinOnly && !servesRequestedRole(candidate))
+            continue;
+        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'] : []],
+    ];
+    for (const [role, terms] 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.
+        if (terms.length === 0)
+            continue;
+        let admitted = 0;
+        for (const candidate of ranked) {
+            if (admitted >= 2 || selected.length >= max)
+                break;
+            const roles = evidenceCandidateRoles(candidate);
+            if (!roles.includes(role))
+                continue;
+            // "top accounts" needs the account display key, not any field whose
+            // label happens to contain account. Once a display candidate is
+            // available, owner/e-mail/sentiment attributes are neither the entity
+            // 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 = hasEntityAttributeTerm([
+                ...input.requirements.dimensions,
+                ...input.requirements.entityTerms,
+                ...input.requirements.entityDisplayTerms,
+            ].join(' '));
+            const hasRequestedEntityLabel = ranked.some((item) => evidenceCandidateRoles(item).includes('entity_label')
+                && candidateMatchesTerms(item, [
+                    ...input.requirements.entityTerms,
+                    ...input.requirements.entityDisplayTerms,
+                ]));
+            if (role === 'categorical_dimension'
+                && hasRequestedEntityLabel
+                && !explicitlyRequestsAttribute
+                && 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' })
+                && role !== 'time_dimension' && role !== 'relationship' && role !== 'entity_label')
+                continue;
+            add(candidate);
+            admitted += 1;
+        }
+    }
+    if (!input.pinOnly) {
+        for (const candidate of ranked)
+            add(candidate);
+    }
+    return selected;
+}
+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|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'
+                                    : /\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';
+    const safeAction = retryable ? (cause === 'rate_limited' ? 'wait_and_retry' : 'retry_same_provider')
+        : cause === 'authentication' || cause === 'model_not_found' ? 'fix_provider_configuration'
+            : cause === 'cancelled' ? 'none'
+                : 'inspect_run';
+    const httpStatusClass = /\b(?:401|403|404|429)\b/.test(text) ? '4xx'
+        : /\b5\d{2}\b/.test(text) ? '5xx'
+            : undefined;
+    return {
+        version: 1,
+        cause,
+        phase: input.phase ?? 'unknown',
+        retryable,
+        safeAction,
+        ...(httpStatusClass ? { httpStatusClass } : {}),
+        ...(input.providerFingerprint ? { providerFingerprint: input.providerFingerprint } : {}),
+        ...(input.modelFingerprint ? { modelFingerprint: input.modelFingerprint } : {}),
+        ...(input.baseOriginFingerprint ? { baseOriginFingerprint: input.baseOriginFingerprint } : {}),
+    };
+}
+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,
+        sourceCoverage: input.sourceCoverage.map((coverage) => ({
+            ...coverage,
+            version: 1,
+            candidateIds: [...new Set(coverage.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),
+            },
+        } : {}),
+    };
+}
 /**
  * `Regarding: "Mr. Matthew Meyer"` and friends — a short label, a colon, and a
  * quoted value, with nothing else in the clause. Deliberately narrow: it must
@@ -560,6 +1449,124 @@ export function buildResearchEvidenceLedger(input) {
         stoppingReason: input.stoppingReason ?? (entries.length > 0 ? 'completed' : 'not_started'),
     };
 }
+export function buildResearchEvidenceLedgerV2(input) {
+    const v1 = buildResearchEvidenceLedger(input);
+    const entries = v1.entries.map((entry, index) => {
+        const source = input.entries[index];
+        const validator = normalizeResearchEvidenceValidator(source?.validator, entry);
+        const requestedVerdict = /\b(?:because|caused?|driven by|due to)\b/i.test(source?.hypothesis ?? '')
+            ? undefined
+            : source?.verdict;
+        const verdict = researchVerdictFromValidatedObservation({
+            status: entry.status,
+            requestedVerdict,
+            validator,
+        });
+        const validFactIds = new Set(entry.facts);
+        const counterEvidenceFactIds = [...new Set(source?.counterEvidenceFactIds ?? [])]
+            .filter((factId) => validFactIds.has(factId));
+        return {
+            ...entry,
+            verdict,
+            ...(source?.hypothesis?.trim() ? { hypothesis: source.hypothesis.trim() } : {}),
+            ...(validator ? { validator } : {}),
+            counterEvidenceFactIds,
+        };
+    });
+    const observedGroundableBranchCount = entries.filter((entry) => entry.status === 'observed' && entry.verdict !== 'failed' && 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: 2,
+        rootQuestion: v1.rootQuestion,
+        ...(v1.planId ? { planId: v1.planId } : {}),
+        ...(v1.snapshotId ? { snapshotId: v1.snapshotId } : {}),
+        entries,
+        factIds: [...new Set(entries.flatMap((entry) => [...entry.facts, ...entry.counterEvidenceFactIds]))],
+        groundableBranchCount,
+        limitedScope: groundableBranchCount < 3,
+        stoppingReason: v1.stoppingReason,
+    };
+}
+/**
+ * Normalise a hypothesis plan into the bounded research contract. The caller
+ * may supply fewer than three grounded hypotheses; that is retained honestly as
+ * limited scope rather than padded with invented joins or explanations.
+ */
+export function buildResearchHypothesisPlanV2(input) {
+    const seen = new Set();
+    const hypotheses = [];
+    for (const candidate of input.hypotheses) {
+        const statement = candidate.statement.trim();
+        const expectation = candidate.expectation.trim();
+        const targetId = candidate.targetId.trim();
+        if (!statement || !expectation || !targetId)
+            continue;
+        const key = `${statement.toLowerCase()}\u0000${targetId.toLowerCase()}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        hypotheses.push({
+            id: candidate.id?.trim() || `hypothesis:${hypotheses.length + 1}`,
+            statement,
+            expectation,
+            targetId,
+            validatorKind: candidate.validatorKind ?? inferResearchValidatorKind(statement, expectation),
+        });
+        if (hypotheses.length >= 6)
+            break;
+    }
+    return { version: 2, hypotheses, limitedScope: hypotheses.length < 3 };
+}
+/** Map an action/expectation to a deterministic observation class only. */
+export function inferResearchValidatorKind(statement, expectation = '') {
+    const text = `${statement} ${expectation}`.toLowerCase();
+    if (/fresh|updated|stale|as of|recency/.test(text))
+        return 'freshness';
+    if (/contribut|driver|segment|breakdown|dominant/.test(text))
+        return 'contributor';
+    if (/trend|time|month|week|quarter|year|shift|change/.test(text))
+        return 'trend';
+    if (/compare|versus|vs\.?|difference/.test(text))
+        return 'comparison';
+    if (/anomal|outlier|spike|drop/.test(text))
+        return 'anomaly';
+    return 'counter_evidence';
+}
+/**
+ * A verdict is promoted only from a validator that evaluated a deterministic
+ * observation against a branch receipt. Rows by themselves stay inconclusive;
+ * causal statements are never supported by this helper.
+ */
+export function researchVerdictFromValidatedObservation(input) {
+    if (input.status === 'failed')
+        return 'failed';
+    if (input.status === 'skipped')
+        return 'skipped';
+    if (!input.validator?.evaluated || input.validator.receiptFingerprints.length === 0)
+        return 'inconclusive';
+    if (input.requestedVerdict === 'supported' && input.validator.outcome === 'supports_observation')
+        return 'supported';
+    if (input.requestedVerdict === 'contradicted' && input.validator.outcome === 'contradicts_observation')
+        return 'contradicted';
+    return 'inconclusive';
+}
+function normalizeResearchEvidenceValidator(validator, entry) {
+    if (!validator || validator.version !== 1)
+        return undefined;
+    const knownReceipt = entry.resultFingerprint;
+    const receiptFingerprints = [...new Set(validator.receiptFingerprints)]
+        .map(normalizeAnalyticalExecutionFingerprint)
+        .filter((fingerprint) => Boolean(fingerprint))
+        .filter((fingerprint) => !knownReceipt || fingerprint === knownReceipt);
+    return {
+        version: 1,
+        kind: validator.kind,
+        evaluated: validator.evaluated === true && receiptFingerprints.length > 0,
+        ...(validator.outcome ? { outcome: validator.outcome } : {}),
+        receiptFingerprints,
+    };
+}
 /** The only accepted host-side execution identity is a SHA-256 fingerprint. */
 export function normalizeAnalyticalExecutionFingerprint(value) {
     return typeof value === 'string' && /^[a-f0-9]{64}$/i.test(value.trim())