@duckcodeailabs/dql-agent 1.14.0 → 1.14.2

package/dist/analytical-orchestration.js

@@ -41,6 +41,459 @@ 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))];
+}
+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 };
+}
+/**
+ * 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);
+    const terms = values
+        .filter((value) => !isStructuralMeasurePhrase(value))
+        .filter((value) => !(groupedOrderCount && /^(?:order|orders)$/i.test(normalizeRequirementTerm(value))));
+    if (groupedOrderCount && !terms.some((value) => normalizeRequirementTerm(value) === 'count')) {
+        terms.push('count');
+    }
+    // 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')));
+    });
+}
+/**
+ * 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();
+    const parsed = 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)\s*(\d+)?\b/i);
+    const requestedDimensions = uniqueRequirementTerms(parsed?.dimensions ?? []);
+    const entityTerms = uniqueRequirementTerms([
+        ...((lower.match(/\b(?:account|accounts|customer|customers|client|clients|company|companies)\b/g) ?? [])),
+    ]).map((term) => term.replace(/s$/, ''));
+    const entityDisplayTerms = /\b(?:who|which)\b/i.test(question)
+        ? 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);
+    const parsedMeasures = normalizeAnalyticalMeasureTerms(question, parsed?.measures ?? []);
+    const parsedMeasuresWithLexicalTerms = uniqueRequirementTerms([
+        ...parsedMeasures,
+        ...nonRedundantLexicalMeasureTerms(parsedMeasures, question),
+        ...(!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 measures = typedRequirements.measures;
+    const dimensions = typedRequirements.dimensions;
+    const rankingMetricTerms = ranking ? measures : [];
+    const parsedLimit = typeof parsed?.limit === 'number' && Number.isFinite(parsed.limit) && parsed.limit > 0
+        ? Math.floor(parsed.limit)
+        : undefined;
+    const explicitLimit = ranking?.[2] ? Number(ranking[2]) : parsedLimit;
+    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)),
+        ...(ranking
+            ? {
+                ranking: {
+                    metricTerms: rankingMetricTerms,
+                    entityTerms,
+                    direction: /bottom|lowest/i.test(ranking[1] ?? '') ? 'bottom' : 'top',
+                    limit: explicitLimit ?? 10,
+                    defaultedLimit: explicitLimit === undefined,
+                },
+            }
+            : {}),
+        ...(time ? { time } : {}),
+    };
+}
+/** Classify the role an already-qualified candidate may fill. */
+export function evidenceCandidateRoles(candidate) {
+    const identity = uniqueRequirementTerms([
+        candidate.id,
+        candidate.qualifiedId,
+        candidate.name,
+        ...(candidate.aliases ?? []),
+        ...(candidate.dimensions ?? []),
+        ...(candidate.analyticalCapability?.dimensions ?? []).map((dimension) => dimension.dimensionId),
+        ...(candidate.analyticalCapability?.timeDimensions ?? []).map((dimension) => dimension.dimensionId),
+    ]).join(' ');
+    const roles = new Set();
+    if (candidate.kind === 'semantic_metric' || candidate.semanticObjectType === 'metric' || /\bmetric\b/.test(identity))
+        roles.add('metric');
+    if (candidate.semanticObjectType === 'entity' || /(?:^| )(?:account|customer|client|company) id\b/.test(identity) || /\bentity\b/.test(identity))
+        roles.add('entity_key');
+    if (/\b(?:account|customer|client|company)(?: name)?\b/.test(identity)
+        && /\b(?:name|label|display|account|customer|client|company)\b/.test(identity)
+        && !/\b(?:owner|sentiment|email)\b/.test(identity))
+        roles.add('entity_label');
+    if (/(?:\bdate\b|\btime\b|\bmonth\b|\bquarter\b|\byear\b)/.test(identity)
+        || (candidate.timeGrains?.length ?? 0) > 0
+        || (candidate.analyticalCapability?.timeDimensions?.length ?? 0) > 0)
+        roles.add('time_dimension');
+    if ((candidate.relationshipEvidence?.length ?? 0) > 0 || /\b(?:relationship|join|bridge)\b/.test(identity))
+        roles.add('relationship');
+    if (candidate.kind === 'semantic_member' || candidate.semanticObjectType === 'dimension')
+        roles.add('categorical_dimension');
+    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;
+    return options.categoricalDimension === true
+        && candidateMatchesCategoricalDimensionRequirement(candidate, terms);
+}
+/**
+ * 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 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 && 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;
+        if (roles.includes('categorical_dimension')
+            && input.requirements.dimensions.length > 0
+            && candidateMatchesTerms(candidate, input.requirements.dimensions, { 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', input.requirements.dimensions],
+        ['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 = /\b(?:owner|sentiment|email)\b/i.test([
+                ...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
+                && /\b(?:owner|sentiment|email)\b/i.test(candidate.name ?? candidate.id))
+                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/.test(text) ? 'admission_denied'
+                : /run.?deadline|time limit/.test(text) ? 'run_deadline'
+                    : /timeout|timed out/.test(text) ? 'provider_timeout'
+                        : /401|403|api key|unauthori[sz]ed|auth(?:entication)?/.test(text) ? 'authentication'
+                            : /model(?:[ _-]+|\s+).*not[ _-]?found|unknown model|model_not_found|404/.test(text) ? 'model_not_found'
+                                : /429|rate[ _-]?limit|too many requests/.test(text) ? 'rate_limited'
+                                    : /502|503|504|gateway/.test(text) ? 'gateway'
+                                        : /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'
+        : /\b(?:502|503|504)\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) {
+    return {
+        version: 1,
+        ...input,
+        sourceCoverage: input.sourceCoverage.map((coverage) => ({
+            ...coverage,
+            version: 1,
+            candidateIds: [...new Set(coverage.candidateIds)].slice(0, 32),
+        })),
+        attempts: input.attempts.map((attempt) => ({ ...attempt, version: 1, candidateIds: [...new Set(attempt.candidateIds)].slice(0, 32) })),
+    };
+}
+/**
+ * `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
+ * be the WHOLE clause and the value must be quoted, so an ordinary question
+ * that happens to contain a colon is untouched.
+ */
+const ANNOTATION_CLAUSE = /^\s*[A-Za-z][A-Za-z ]{0,24}:\s*["“'‘][^"”'’]*["”'’]\s*$/;
 export function splitAnalyticalTasks(question) {
     // The separator belongs to the SPLIT, not to the clause. Carrying it through
     // produced a child task whose question was literally
@@ -49,22 +502,36 @@ export function splitAnalyticalTasks(question) {
     // the task title.
     const leadingJunk = /^(?:[\s"'“”‘’,:;.\-]+|\b(?:then|and|also)\b)+/i;
     const trailingJunk = /[\s"'“”‘’,:;.\-]+$/;
-    const parts = question
+    const raw = question
         .split(/\s*(?:\?|;|\band then\b|\balso\b)\s*/i)
-        .flatMap((part) => part.split(/\s+\band\s+(?=(?:what|who|which|show|list|tell|give|how|why)\b)/i))
+        .flatMap((part) => part.split(/\s+\band\s+(?=(?:what|who|which|show|list|tell|give|how|why)\b)/i));
+    // A `Label: "value"` clause is an ANNOTATION, not a question. The composer
+    // appends `Regarding: "<selected row>"` when the reader follows up on
+    // something they clicked, and splitting on the `?` before it turned that
+    // referent into a task of its own — titled `Regarding: "Mr. Matthew Meyer`,
+    // which then "answered" by computing an unrelated maximum over the rows still
+    // on screen. Context says WHO the real task is about; it is never a task.
+    // Filtered before the junk strip, which would unbalance the quotes.
+    const asked = raw.filter((part) => !ANNOTATION_CLAUSE.test(part));
+    const parts = (asked.length > 0 ? asked : raw)
         .map((part) => part.replace(leadingJunk, '').replace(trailingJunk, '').trim())
         .filter(Boolean);
     return parts.length > 0 ? parts : [question.trim()];
 }
 export function buildAnalyticalTaskGraph(input) {
-    const clauses = splitAnalyticalTasks(input.question).slice(0, Math.max(1, Math.min(6, input.maxTasks ?? 6)));
+    const rootKind = input.mode === 'research' ? 'research' : inferAnalyticalTurnKind(input.question);
+    // 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 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 tasks = clauses.map((clause, index) => {
-        const kind = inferAnalyticalTurnKind(clause);
+    const unboundTasks = clauses.map((clause, index) => {
+        const kind = rootKind === 'research' ? 'research' : inferAnalyticalTurnKind(clause);
         const research = kind === 'research' || kind === 'diagnosis';
         const taskKind = research
             ? 'research_branch'
@@ -96,12 +563,36 @@ export function buildAnalyticalTaskGraph(input) {
             inheritedBindings,
         };
     });
+    const tasks = bindTopRankedRegionDependencies(unboundTasks);
     return {
-        kind: tasks.length > 1 ? 'compound' : inferAnalyticalTurnKind(input.question),
+        kind: rootKind === 'research' ? 'research' : tasks.length > 1 ? 'compound' : rootKind,
         tasks,
         partial: false,
     };
 }
+const TOP_RANKED_REGION_RE = /(?:\b(?:top|highest|most)\b[^?.!]{0,72}\bregions?\b|\bregions?\b[^?.!]{0,72}\b(?:top|highest|most)\b)/i;
+const DEPENDENT_REGION_CUSTOMERS_RE = /\b(?:that|this|same)\s+region\b/i;
+/**
+ * Recognise only the demonstrated two-step dependency. Broader pronoun
+ * resolution belongs to the normal conversation layer; turning every compound
+ * question into a dependency would serialise unrelated work and invent filters.
+ */
+function bindTopRankedRegionDependencies(tasks) {
+    return tasks.map((task, index) => {
+        if (!DEPENDENT_REGION_CUSTOMERS_RE.test(task.question) || !/\bcustomers?\b/i.test(task.question))
+            return task;
+        const parent = tasks.slice(0, index).reverse().find((candidate) => TOP_RANKED_REGION_RE.test(candidate.question));
+        if (!parent)
+            return task;
+        const dependency = {
+            version: 1,
+            kind: 'top_ranked_region',
+            sourceTaskId: parent.id,
+            targetDimension: 'region',
+        };
+        return { ...task, dependencies: [parent.id], dependency };
+    });
+}
 export function buildAnalyticalTurnPlan(input) {
     const graph = buildAnalyticalTaskGraph(input);
     const zeroCall = input.zeroCallReason === 'explicit_binding'
@@ -134,6 +625,173 @@ export function summarizeTaskOutcomes(tasks) {
                 : 'gap';
     return { status, completed, gaps };
 }
+/** Stable scalar transport for a selected canonical result cell. */
+export function canonicalResultBindingValue(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    if (typeof value === 'boolean')
+        return String(value);
+    return undefined;
+}
+/** A row proof includes all canonical columns, not just the selected cell. */
+export function canonicalResultRowFingerprint(result, row) {
+    return stableFingerprint({
+        columns: result.columns,
+        row: Object.fromEntries(result.columns.map((column) => [column, row[column]])),
+    });
+}
+/**
+ * Validate an untrusted selected-result reference against a persisted
+ * canonical result. The source run/artifact identities are checked by the
+ * host before calling this pure result-level validator.
+ */
+export function validateSelectedResultBinding(binding, result) {
+    if (!binding
+        || binding.version !== 1
+        || !binding.sourceRunId.trim()
+        || !binding.sourceArtifactId.trim()
+        || !binding.canonicalColumn.trim()
+        || !binding.value.trim()
+        || !normalizeAnalyticalExecutionFingerprint(binding.rowFingerprint)
+        || !normalizeAnalyticalExecutionFingerprint(binding.resultFingerprint)) {
+        return {
+            ok: false,
+            code: 'RESULT_BINDING_INVALID',
+            message: 'The selected result reference is incomplete or malformed.',
+        };
+    }
+    if (!result || binding.resultFingerprint !== result.resultFingerprint) {
+        return {
+            ok: false,
+            code: 'RESULT_BINDING_RESULT_MISMATCH',
+            message: 'The selected result is no longer the persisted result for this run.',
+        };
+    }
+    if (!result.columns.includes(binding.canonicalColumn)) {
+        return {
+            ok: false,
+            code: 'RESULT_BINDING_ROW_MISMATCH',
+            message: `The selected column ${binding.canonicalColumn} is not present in the persisted result.`,
+        };
+    }
+    const matched = result.rows.some((row) => canonicalResultRowFingerprint(result, row) === binding.rowFingerprint
+        && canonicalResultBindingValue(row[binding.canonicalColumn]) === binding.value);
+    if (!matched) {
+        return {
+            ok: false,
+            code: 'RESULT_BINDING_ROW_MISMATCH',
+            message: 'The selected row/value does not match the persisted result.',
+        };
+    }
+    return { ok: true, binding: { ...binding, resultFingerprint: result.resultFingerprint } };
+}
+/**
+ * Derive the one value a `top region -> customers in that region` child may
+ * consume. A first row alone is never proof. The parent must either return an
+ * explicit rank, or be the server-computed descending ranking task and return
+ * at least two rows with one strictly-leading numeric measure. `rowCount` is
+ * the returned-row contract, not proof that a singleton is the complete group
+ * set. Ties and ambiguous result shapes remain a typed child gap.
+ */
+export function resolveTopRankedRegionDependency(sourceTaskId, result, parentTask) {
+    if (!result || result.rows.length === 0) {
+        return {
+            ok: false,
+            code: 'RESULT_CONTRACT_MISMATCH',
+            message: 'The top-region task did not produce a canonical result that can bind the dependent customer task.',
+        };
+    }
+    const canonicalResultFingerprint = normalizeAnalyticalExecutionFingerprint(result.resultFingerprint);
+    const executionReceipt = normalizeAnalyticalExecutionReceipt(result.executionReceipt);
+    if (!executionReceipt) {
+        return {
+            ok: false,
+            code: 'RESULT_CONTRACT_MISMATCH',
+            message: 'The top-region result did not retain a complete normalized execution receipt, so the dependent customer task was not run.',
+        };
+    }
+    if (!canonicalResultFingerprint
+        || result.resultFingerprint !== canonicalResultFingerprint
+        || executionReceipt.resultFingerprint !== canonicalResultFingerprint) {
+        return {
+            ok: false,
+            code: 'RESULT_CONTRACT_MISMATCH',
+            message: 'The top-region execution receipt does not match the canonical result, so the dependent customer task was not run.',
+        };
+    }
+    const regionColumns = result.columns.filter((column) => /(?:^|_)region(?:_name)?$/i.test(column));
+    if (regionColumns.length !== 1) {
+        return {
+            ok: false,
+            code: 'RESULT_CONTRACT_MISMATCH',
+            message: 'The top-region result did not contain exactly one canonical region column.',
+        };
+    }
+    const canonicalColumn = regionColumns[0];
+    const first = result.rows[0];
+    const value = canonicalResultBindingValue(first[canonicalColumn]);
+    if (!value) {
+        return {
+            ok: false,
+            code: 'RESULT_CONTRACT_MISMATCH',
+            message: 'The leading top-region row did not contain a usable region value.',
+        };
+    }
+    if (!hasUnambiguousTopRow(result, parentTask)) {
+        return {
+            ok: false,
+            code: 'RESULT_CONTRACT_MISMATCH',
+            message: 'The top-region result did not prove a single leading region, so the dependent customer task was not run.',
+        };
+    }
+    return {
+        ok: true,
+        binding: {
+            version: 1,
+            sourceTaskId,
+            sourceResultFingerprint: canonicalResultFingerprint,
+            canonicalColumn,
+            value,
+            rowFingerprint: canonicalResultRowFingerprint(result, first),
+        },
+    };
+}
+function hasUnambiguousTopRow(result, parentTask) {
+    const rankColumn = result.columns.find((column) => /(?:^|_)(?:rank|row_number)$/i.test(column));
+    if (rankColumn) {
+        const ranks = result.rows.map((row) => numericCell(row[rankColumn]));
+        if (ranks[0] === 1 && ranks.slice(1).every((rank) => rank === undefined || rank > 1))
+            return true;
+    }
+    // A plain numerical result column does not say that its first row was ranked.
+    // It becomes a ranking proof only when the server's own parent task explicitly
+    // asked for a descending ranking AND the returned rows demonstrate a strictly
+    // leading value. A singleton needs an explicit rank = 1: it cannot establish
+    // that unreturned groups are lower.
+    if (parentTask?.kind !== 'ranking' || parentTask.output.order !== 'desc')
+        return false;
+    if (result.rows.length < 2)
+        return false;
+    const measures = result.columns.filter((column) => {
+        if (column === rankColumn)
+            return false;
+        const values = result.rows.map((row) => numericCell(row[column]));
+        return values.every((value) => value !== undefined);
+    });
+    if (measures.length !== 1)
+        return false;
+    const values = result.rows.map((row) => numericCell(row[measures[0]]));
+    return values.slice(1).every((value) => values[0] > value);
+}
+function numericCell(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim() && Number.isFinite(Number(value)))
+        return Number(value);
+    return undefined;
+}
 /**
  * Normalize connector, MetricFlow, and provider result shapes at one boundary.
  * Connectors may return `ColumnMeta[]` and rows as arrays; UI surfaces should
@@ -348,6 +1006,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())