@duckcodeailabs/dql-agent 1.13.5 → 1.14.0

package/dist/router.js

@@ -793,6 +793,113 @@ function buildEvidenceClarification(candidates, missing = []) {
         return `I found relevant governed context, but need ${missing.join(" and ")}. What should I use?`;
     return "Which governed business meaning should I use for this question?";
 }
+/**
+ * A distinct-entity count is not a useful ranking measure at the same entity
+ * grain: every customer normally has a count of one. Keep the candidate in the
+ * evidence trace, but do not let lexical relevance freeze it as the answer to
+ * "top customers". This is deliberately a semantic suitability check, not a
+ * name-based ban; an explicit "top customers by customer count" request remains
+ * the user's choice and can proceed through normal compatibility checks.
+ */
+function isDegenerateRankingMetric(question, evidence, candidate) {
+    if (questionTypeFromText(question) !== 'ranking')
+        return false;
+    if (candidate.kind !== 'semantic_metric' && candidate.kind !== 'semantic_member')
+        return false;
+    const capability = normalizeEvidenceAnalyticalCapability(candidate).capability;
+    const aggregation = normalizeMetricPhrase(candidate.aggregation ?? capability?.aggregation ?? '');
+    if (!aggregation || !/^(count|count distinct|count unique|count distinct values)$/.test(aggregation))
+        return false;
+    const questionTerms = new Set(substantiveLexicalTokens(question));
+    const entityTerms = [
+        candidate.primaryEntity ?? '',
+        ...(candidate.analyticalCapability?.resultGrainIds ?? []),
+        ...(candidate.dimensions ?? []),
+        ...(evidence.parsedIntent?.dimensions ?? []),
+    ].flatMap((value) => substantiveLexicalTokens(value));
+    const metricTerms = [candidate.name, candidate.qualifiedId ?? '', ...(candidate.aliases ?? [])]
+        .flatMap((value) => substantiveLexicalTokens(value));
+    return entityTerms.some((term) => questionTerms.has(term))
+        && metricTerms.some((term) => entityTerms.includes(term));
+}
+function hasExplicitRankingMeasure(question, evidence) {
+    const parsed = [
+        ...(evidence.parsedIntent?.measures ?? []),
+        ...extractRankingMeasurePhrases(question),
+    ].map(normalizeMetricPhrase).filter(Boolean);
+    return parsed.length > 0;
+}
+function extractRankingMeasurePhrases(question) {
+    const matches = [];
+    for (const pattern of [
+        /\b(?:by|based on|using|with|for)\s+(?:the\s+)?([a-z][a-z0-9_. -]{1,80}?)(?=\s+(?:among|for each|per|in|where|during|over)|[?.!,]|$)/gi,
+        /\b(?:highest|lowest|most|least)\s+([a-z][a-z0-9_. -]{1,80}?)(?=\s+(?:among|for each|per|in|where|during|over)|[?.!,]|$)/gi,
+    ]) {
+        for (const match of question.matchAll(pattern))
+            if (match[1])
+                matches.push(match[1]);
+    }
+    return matches;
+}
+function rankingMetricChoiceDecision(base, evidence, candidates, selected, question) {
+    const options = candidates
+        .filter((candidate) => candidate.id !== selected.id
+        && candidate.compatibility !== 'incompatible'
+        && candidate.kind === 'semantic_metric'
+        && !isDegenerateRankingMetric(question, evidence, candidate))
+        .slice(0, 3);
+    const labels = options.length > 0
+        ? options.map((candidate) => renderCandidateChoice(candidate)).join(' or ')
+        : 'revenue, order count, or another measure available in the model';
+    return {
+        ...base,
+        action: 'clarify',
+        confidence: 1,
+        source: 'heuristic',
+        category: 'unclear',
+        depth: 'quick',
+        followsUp: true,
+        requiresClarification: true,
+        reason: `${selected.name} counts customers; it cannot distinguish individual customers for a top-customer ranking.`,
+        clarifyingQuestion: `That metric counts unique customers and cannot rank individual customers. Which measure should rank them: ${labels}?`,
+        clarificationOptions: options.length > 0 ? buildClarificationOptions(options) : undefined,
+        retrievalEvidence: retrievalTrace(evidence, candidates),
+        resolvedAnalyticalPlan: undefined,
+        meaningResolution: undefined,
+    };
+}
+function preventDegenerateRankingResolution(resolution, evidence, candidates, question) {
+    if (hasExplicitRankingMeasure(question, evidence))
+        return resolution;
+    const selected = candidates.find((candidate) => candidate.id === resolution.recommendedExecutionId
+        || resolution.selectedConceptIds.includes(candidate.id));
+    if (!selected || !isDegenerateRankingMetric(question, evidence, selected))
+        return resolution;
+    const alternatives = candidates
+        .filter((candidate) => candidate.id !== selected.id
+        && candidate.kind === 'semantic_metric'
+        && candidate.compatibility !== 'incompatible'
+        && !isDegenerateRankingMetric(question, evidence, candidate))
+        .slice(0, 3);
+    const alternativeLabels = alternatives.map(renderCandidateChoice).join(' or ');
+    return {
+        ...resolution,
+        confidence: 'low',
+        recommendedRoute: 'clarify',
+        recommendedExecutionId: undefined,
+        selectedConceptIds: [],
+        analyticalFrame: undefined,
+        missingInformation: [
+            ...new Set([
+                ...resolution.missingInformation,
+                `${selected.name} counts the ranked entity and is not a suitable ranking measure`,
+            ]),
+        ],
+        clarifyingQuestion: alternativeLabels
+            ? `I found ${selected.name}, but it counts the ranked entity and cannot identify the top individual customers. Which measure should I use: ${alternativeLabels}?`
+            : `I found ${selected.name}, but it counts the ranked entity and cannot identify the top individual customers. Which measure should I use for the ranking?`,
+    };
+}
 function directResolution(request, evidence, candidate, candidates) {
     const inferredQuestionType = questionTypeFromText(request.question);
     const questionType = inferredQuestionType === 'definition'
@@ -930,12 +1037,21 @@ mayAssumeInterpretation = true) {
     if (multiMetricPrimary) {
         return routeDecisionForResolution(base, evidence, candidates, directResolution(request, evidence, multiMetricPrimary, candidates), "heuristic", request.question, planMode);
     }
-    const exactCompatible = candidates.filter((candidate) => candidate.exactMatch && candidate.compatibility !== "incompatible");
+    const rankingCandidates = hasExplicitRankingMeasure(request.question, evidence)
+        ? candidates
+        : candidates.filter((candidate) => !isDegenerateRankingMetric(request.question, evidence, candidate));
+    if (questionTypeFromText(request.question) === 'ranking'
+        && !hasExplicitRankingMeasure(request.question, evidence)) {
+        return bareRankingClarification(base, retrievalTrace(evidence, candidates), request.question, evidence, rankingCandidates);
+    }
+    const exactCompatible = candidates.filter((candidate) => candidate.exactMatch
+        && candidate.compatibility !== "incompatible"
+        && rankingCandidates.includes(candidate));
     if (exactCompatible.length === 1 &&
         !hasMateriallyRelatedCompetitor(exactCompatible[0], candidates)) {
         return routeDecisionForResolution(base, evidence, candidates, directResolution(request, evidence, exactCompatible[0], candidates), "heuristic", request.question, planMode);
     }
-    const semanticMetric = uniqueExecutableSemanticMetric(evidence, candidates);
+    const semanticMetric = uniqueExecutableSemanticMetric(evidence, rankingCandidates);
     if (semanticMetric) {
         return routeDecisionForResolution(base, evidence, candidates, directResolution(request, evidence, semanticMetric, candidates), "heuristic", request.question, planMode);
     }
@@ -944,7 +1060,7 @@ mayAssumeInterpretation = true) {
     // `type: simple` metric, the measure it wraps, and the model that holds them
     // were offered as three competing "meanings" of the same number.
     const best = mayAssumeInterpretation
-        ? bestGovernedInterpretation(request.question, candidates)
+        ? bestGovernedInterpretation(request.question, rankingCandidates)
         : undefined;
     if (best) {
         return routeDecisionForResolution(base, evidence, candidates, directResolution(request, evidence, best, candidates), "heuristic", request.question, planMode);
@@ -981,11 +1097,67 @@ export function collapseRedundantGovernedCandidates(question, candidates) {
     const byScore = [...new Map(candidates
             .filter((candidate) => candidate.eligible !== false && candidate.compatibility !== 'incompatible')
             .map((candidate) => [candidate.id, candidate])).values()].sort((left, right) => right.relevanceScore - left.relevanceScore || left.id.localeCompare(right.id));
-    const wantsAttribute = /\b(names?|labels?|titles?|descriptions?)\b/i.test(question);
+    // An entity is a JOIN KEY. It is a reading of "how many customers", but never
+    // of "what customer type is <member>" — there the reader named a field and a
+    // member, and the entity cannot answer either. The trigger used to be a
+    // four-word list (name/label/title/description), so "customer type", "region",
+    // and "when did X first order" all left the entity competing and turned an
+    // ordinary attribute lookup into a bind-interrogation. Recognise the
+    // interrogative FORM as well as the vocabulary; `hasDimension` below still
+    // requires that a real attribute was actually retrieved.
+    const wantsAttribute = /\b(names?|labels?|titles?|descriptions?|types?|status(?:es)?|categor(?:y|ies)|segments?|tiers?|regions?|emails?|addresses?)\b/i.test(question)
+        || /\b(what|which|when|where)\b[^?]*\b(is|are|was|were|does|do|did|belongs?)\b/i.test(question);
     const hasDimension = byScore.some((candidate) => candidate.semanticObjectType === 'dimension');
-    const kindFiltered = wantsAttribute && hasDimension
-        ? byScore.filter((candidate) => candidate.semanticObjectType !== 'entity')
+    // An entity arrives as a semantic-layer entity OR as a DQL modeling entity
+    // (`dql:entity:…`, kind `dql_modeling`). Testing only `semanticObjectType`
+    // left the DQL one competing, so the interrogation survived the fix above.
+    // Check BOTH identities: a DQL entity's `qualifiedId` is the bare
+    // `commerce::entity::customer`, so testing the qualified id alone still let
+    // it through.
+    const isEntityCandidate = (candidate) => candidate.semanticObjectType === 'entity'
+        || [candidate.id, candidate.qualifiedId ?? ''].some((identity) => /(^|:)entity(:|::)/i.test(identity));
+    const entityFiltered = wantsAttribute && hasDimension
+        ? byScore.filter((candidate) => !isEntityCandidate(candidate))
         : byScore;
+    // Within an attribute question, a candidate matching only a SUB-TOKEN of the
+    // requested field is a lexical decoy, not a competing reading. "What customer
+    // type is <member>?" dragged in `raw_products.type` and
+    // `orders.new_customer_orders` purely because they contain "type" and
+    // "customer", and two decoys are enough to trip the ambiguity gate and turn
+    // the lookup into an interrogation. Score how much of the question each
+    // candidate actually accounts for — including the fields a block declares,
+    // which is how the block that OUTPUTS `customer_type` outranks a column
+    // merely named `type` — and keep only the most specific matches.
+    const normalizedQuestion = normalizeMetricPhrase(question);
+    const phraseSpecificity = (candidate) => {
+        const terms = [
+            candidate.name,
+            ...(candidate.aliases ?? []),
+            ...(candidate.dimensions ?? []),
+            ...(candidate.compatibilityFacts ?? [])
+                .filter((fact) => fact.startsWith('output: '))
+                .map((fact) => fact.slice('output: '.length)),
+        ].map((term) => normalizeMetricPhrase(String(term ?? '').split(/[.:/]/).at(-1) ?? ''));
+        let best = 0;
+        for (const term of terms) {
+            if (!term)
+                continue;
+            const matches = normalizedQuestion === term
+                || normalizedQuestion.startsWith(`${term} `)
+                || normalizedQuestion.endsWith(` ${term}`)
+                || normalizedQuestion.includes(` ${term} `);
+            if (matches)
+                best = Math.max(best, term.split(' ').length);
+        }
+        return best;
+    };
+    const specificity = new Map(entityFiltered.map((candidate) => [candidate.id, phraseSpecificity(candidate)]));
+    const bestSpecificity = Math.max(0, ...specificity.values());
+    // Only prune when something matched a MULTI-word field name. A single shared
+    // token is not enough evidence to call the others decoys.
+    const kindFiltered = wantsAttribute && hasDimension && bestSpecificity >= 2
+        ? entityFiltered.filter((candidate) => (specificity.get(candidate.id) ?? 0) === bestSpecificity)
+        : entityFiltered;
     const representatives = new Map();
     const passthrough = [];
     for (const candidate of kindFiltered) {
@@ -1000,7 +1172,44 @@ export function collapseRedundantGovernedCandidates(question, candidates) {
             representatives.set(key, candidate);
         }
     }
-    return [...passthrough, ...representatives.values()].sort((left, right) => right.relevanceScore - left.relevanceScore || left.id.localeCompare(right.id));
+    // A certified block that already OUTPUTS an attribute is not a competing
+    // MEANING of that attribute — it is the same reading at higher authority.
+    // Keeping both turned an ordinary attribute lookup ("what customer type is
+    // <member>?") into a "Which governed meaning should DQL bind: customer_profile
+    // or customers.customer_type?" interrogation, even though the block declares
+    // that exact output, sits at the requested grain, and permits the member
+    // filter. The cascade already says certified outranks semantic for one
+    // reading; this stops the tie from being mistaken for ambiguity.
+    const certifiedCoverage = passthrough
+        .filter((candidate) => candidate.kind === 'certified_block')
+        .map((candidate) => new Set([
+        ...(candidate.dimensions ?? []),
+        ...(candidate.compatibilityFacts ?? [])
+            .filter((fact) => fact.startsWith('output: '))
+            .map((fact) => fact.slice('output: '.length)),
+    ].map((value) => normalizeMetricPhrase(String(value).split(/[.:/]/).at(-1) ?? ''))
+        .filter(Boolean)));
+    const survivingPassthrough = certifiedCoverage.length === 0
+        ? passthrough
+        : passthrough.filter((candidate) => {
+            // The same field can arrive three ways — the block's declared output, the
+            // semantic dimension, and the raw warehouse/dbt column. Only the first is
+            // a governed meaning; the other two are lower-trust representations of it.
+            const supersedable = candidate.semanticObjectType === 'dimension'
+                || candidate.kind === 'sql_column';
+            if (!supersedable)
+                return true;
+            // A column's qualified identity points at its PARENT RELATION, so
+            // `candidateLeafName` yields "customers" for `customers.customer_type`.
+            // Match the candidate's own name as well, or a raw column is never
+            // recognised as the field a block already publishes.
+            const leaves = [
+                normalizeMetricPhrase(String(candidate.name ?? '').split(/[.:/]/).at(-1) ?? ''),
+                normalizeMetricPhrase(candidateLeafName(candidate)),
+            ].filter(Boolean);
+            return !leaves.some((leaf) => certifiedCoverage.some((outputs) => outputs.has(leaf)));
+        });
+    return [...survivingPassthrough, ...representatives.values()].sort((left, right) => right.relevanceScore - left.relevanceScore || left.id.localeCompare(right.id));
 }
 /**
  * The governed meaning to run when nothing proved a single exact reading.
@@ -1114,7 +1323,7 @@ function deterministicPrePlanClarification(request, base, evidence, candidates)
         if (alternatives.length === 0) {
             if (!asksForRanking || hasExplicitRankingMetric)
                 return undefined;
-            return bareRankingClarification(base, retrievalEvidence);
+            return bareRankingClarification(base, retrievalEvidence, request.question, evidence, candidates);
         }
         const requestedLabel = missingDimensions.map((term) => `“${term}”`).join(' and ');
         const alternativeLabels = alternatives.map(renderCandidateChoice);
@@ -1137,11 +1346,57 @@ function deterministicPrePlanClarification(request, base, evidence, candidates)
         };
     }
     if (asksForRanking && !hasExplicitRankingMetric) {
-        return bareRankingClarification(base, retrievalEvidence);
+        return bareRankingClarification(base, retrievalEvidence, request.question, evidence, candidates);
     }
     return undefined;
 }
-function bareRankingClarification(base, retrievalEvidence) {
+/**
+ * "Top by which governed metric?" with NO choices is a dead end: the asker
+ * cannot know which measures are both governed and valid at the ranked grain,
+ * so the only move left is to guess. A built-CLI run on the commerce fixture
+ * ended here with zero options while `revenue`, `lifetime_spend_pretax`, and
+ * `orders` were all modeled.
+ *
+ * The question stays exactly as it was — this only attaches the compatible
+ * ranking measures as selectable choices, minus any same-grain entity count,
+ * which is degenerate for ranking individuals. Selecting one returns an
+ * explicit qualified id, which takes the resolved-selection path instead of
+ * asking again.
+ *
+ * Acceptance: AGT-030.
+ */
+function bareRankingClarification(base, retrievalEvidence, question, evidence, candidates) {
+    const rankingChoices = (candidates ?? []).filter((candidate) => {
+        if (candidate.compatibility === 'incompatible')
+            return false;
+        if (candidate.kind !== 'certified_block'
+            && candidate.kind !== 'semantic_metric'
+            && candidate.kind !== 'semantic_member')
+            return false;
+        // Check BOTH identities: `qualifiedId` is often the bare semantic-layer
+        // name, so testing it alone let `semantic:model:customers` through.
+        const identities = [candidate.id, candidate.qualifiedId ?? ''].filter(Boolean);
+        // A model, entity, dimension, dbt node, or warehouse table cannot BE the
+        // measure a ranking is ordered by; offering one as a "governed metric" is
+        // how `semantic:model:customers` reached the choice list.
+        if (identities.some((identity) => /^(semantic:(model|entity|dimension|time_dimension):|dbt:|warehouse:)/i.test(identity)))
+            return false;
+        // `semantic:measure:X.X` is a count of X reported at X's own grain — every
+        // row scores 1, so it can never order X. The metadata-driven guard below
+        // needs a declared aggregation, which retrieval does not always carry, so
+        // this identity check catches the case that metadata misses.
+        const degenerateIdentity = identities.some((identity) => {
+            const measurePath = /^semantic:(?:measure|metric):(.+)$/i.exec(identity)?.[1] ?? '';
+            const [owner, measureName] = measurePath.split('.');
+            return Boolean(owner && measureName
+                && normalizeMetricPhrase(owner) === normalizeMetricPhrase(measureName));
+        });
+        if (degenerateIdentity)
+            return false;
+        if (question && evidence && isDegenerateRankingMetric(question, evidence, candidate))
+            return false;
+        return true;
+    });
     return {
         ...base,
         action: 'clarify',
@@ -1153,6 +1408,9 @@ function bareRankingClarification(base, retrievalEvidence) {
         requiresClarification: true,
         clarifyingQuestion: 'Top by which governed metric?',
         retrievalEvidence,
+        ...(rankingChoices.length > 0
+            ? { clarificationOptions: buildClarificationOptions(rankingChoices) }
+            : {}),
         resolvedAnalyticalPlan: undefined,
         meaningResolution: undefined,
     };
@@ -1432,6 +1690,7 @@ export function createHybridRouter(options = {}) {
     const threshold = options.llmThreshold ?? DEFAULT_THRESHOLD;
     const cacheSize = options.cacheSize ?? DEFAULT_CACHE_SIZE;
     const cacheTtlMs = options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+    const requireMeaningCall = options.requireMeaningCallForNaturalLanguage ?? true;
     const cache = new Map();
     let tick = 0;
     const now = options.now ?? (() => { tick += 1; return tick; });
@@ -1492,8 +1751,14 @@ export function createHybridRouter(options = {}) {
                 // A structured clarification selection is authoritative identity input,
                 // not a new fuzzy-search phrase. Keep it in the bounded package even if
                 // per-tier limits would otherwise trim it from a large catalog.
+                // Look in BOTH lists. The ranking-measure choices are supplemental
+                // clarification candidates, not execution candidates, so resolving the
+                // selection against `candidates` alone silently found nothing — the
+                // click looked identical to no click, the ranking gate fired again, and
+                // the same three options came back forever.
                 const selectedEvidence = request.selectedEvidenceId
-                    ? evidence.candidates.find((candidate) => candidate.id === request.selectedEvidenceId && candidate.eligible !== false)
+                    ? [...evidence.candidates, ...(evidence.clarificationCandidates ?? [])]
+                        .find((candidate) => candidate.id === request.selectedEvidenceId && candidate.eligible !== false)
                     : undefined;
                 if (selectedEvidence && !candidates.some((candidate) => candidate.id === selectedEvidence.id)) {
                     candidates = [selectedEvidence, ...candidates.filter((candidate) => candidate.id !== selectedEvidence.id)]
@@ -1507,33 +1772,58 @@ export function createHybridRouter(options = {}) {
                         ...evidence.candidates,
                         ...(evidence.clarificationCandidates ?? []),
                     ].filter((candidate, index, all) => candidate.eligible !== false && all.findIndex((other) => other.id === candidate.id) === index);
-                    const deterministicClarification = deterministicPrePlanClarification(request, base, evidence, clarificationCandidates);
-                    if (deterministicClarification)
-                        return deterministicClarification;
                     const explicit = selectedEvidence ?? findExplicitEvidenceReference(request.question, candidates);
-                    if (explicit && explicit.compatibility !== "incompatible") {
+                    const explicitMeaningBinding = Boolean(explicit && (request.selectedEvidenceId
+                        || /@(metric|block|model|table|column)\(/i.test(request.question)));
+                    const shouldUseMeaningCall = requireMeaningCall
+                        && !explicitMeaningBinding
+                        && Boolean(options.resolveMeaning || options.complete);
+                    // A normal natural-language turn must be interpreted against the
+                    // candidate cards before a deterministic clarification is allowed.
+                    // Running this gate first was the source of the "Top by which
+                    // governed metric?" repeat loop: it treated a customer-count
+                    // execution shim as the answer and never let the meaning model see
+                    // the ranking entity/measure distinction.
+                    if (!shouldUseMeaningCall && !explicitMeaningBinding) {
+                        const deterministicClarification = deterministicPrePlanClarification(request, base, evidence, clarificationCandidates);
+                        if (deterministicClarification)
+                            return deterministicClarification;
+                    }
+                    if (explicit
+                        && explicit.compatibility !== "incompatible"
+                        && (!shouldUseMeaningCall || explicitMeaningBinding)) {
+                        if (isDegenerateRankingMetric(request.question, evidence, explicit)
+                            && !hasExplicitRankingMeasure(request.question, evidence)) {
+                            return rankingMetricChoiceDecision(base, evidence, candidates, explicit, request.question);
+                        }
                         const decision = routeDecisionForResolution(base, evidence, candidates, directResolution(request, evidence, explicit, candidates), "heuristic", request.question, options.resolvedPlanMode ?? 'authoritative');
                         return selectedEvidence && decision.requiresClarification
                             ? continueCascadeAfterIncompleteSelection(base, evidence, candidates, selectedEvidence)
                             : decision;
                     }
-                    const multiMetricPrimary = exactMultiMetricPrimary(request.question, evidence, candidates);
+                    const multiMetricPrimary = !shouldUseMeaningCall
+                        ? exactMultiMetricPrimary(request.question, evidence, candidates)
+                        : undefined;
                     if (multiMetricPrimary) {
                         return routeDecisionForResolution(base, evidence, candidates, directResolution(request, evidence, multiMetricPrimary, candidates), "heuristic", request.question, options.resolvedPlanMode ?? 'authoritative');
                     }
-                    const authoredExample = authoritativeExactCertifiedExample(candidates);
+                    const authoredExample = !shouldUseMeaningCall
+                        ? authoritativeExactCertifiedExample(candidates)
+                        : undefined;
                     if (authoredExample) {
                         return routeDecisionForResolution(base, evidence, candidates, directResolution(request, evidence, authoredExample, candidates), 'heuristic', request.question, options.resolvedPlanMode ?? 'authoritative');
                     }
-                    const exactCompatible = candidates.filter((candidate) => candidate.exactMatch && candidate.compatibility !== "incompatible");
+                    const exactCompatible = !shouldUseMeaningCall ? candidates.filter((candidate) => candidate.exactMatch && candidate.compatibility !== "incompatible") : [];
                     if (exactCompatible.length === 1 && !hasMateriallyRelatedCompetitor(exactCompatible[0], candidates)) {
                         return routeDecisionForResolution(base, evidence, candidates, directResolution(request, evidence, exactCompatible[0], candidates), "heuristic", request.question, options.resolvedPlanMode ?? 'authoritative');
                     }
-                    const dominant = dominantCompatibleGovernedCandidate(candidates);
+                    const dominant = !shouldUseMeaningCall
+                        ? dominantCompatibleGovernedCandidate(candidates)
+                        : undefined;
                     if (dominant) {
                         return routeDecisionForResolution(base, evidence, candidates, directResolution(request, evidence, dominant, candidates), "heuristic", request.question, options.resolvedPlanMode ?? 'authoritative');
                     }
-                    if (shouldDeferCompositionalFollowUpToExecutor(base, candidates)) {
+                    if (!shouldUseMeaningCall && shouldDeferCompositionalFollowUpToExecutor(base, candidates)) {
                         return routeWithoutMeaningModel(request, base, evidence, candidates, options.resolvedPlanMode ?? 'authoritative');
                     }
                     const key = cacheKey(request, evidence);
@@ -1577,7 +1867,55 @@ export function createHybridRouter(options = {}) {
                         if (resolution) {
                             const validated = validateMeaningResolution(resolution, candidates);
                             if (validated.ok) {
-                                return remember(key, routeDecisionForResolution(base, evidence, candidates, validated.resolution, "llm", request.question, options.resolvedPlanMode ?? 'authoritative'));
+                                const safeResolution = preventDegenerateRankingResolution(validated.resolution, evidence, candidates, request.question);
+                                // Meaning interpretation is still required for a fresh turn,
+                                // but it cannot invent a ranking measure when the user only
+                                // supplied an entity. Preserve the precise follow-up after the
+                                // bounded call so this does not regress into a generic block
+                                // or a repeated customer-count answer.
+                                //
+                                // Gate on the MEANING MODEL's classification, not on
+                                // `questionTypeFromText`. The text heuristic only looks for
+                                // words like "top", so it also claimed "what region does the
+                                // top customer belong to" (an attribute lookup) and "top
+                                // products in Philadelphia and the customers who bought them"
+                                // (a compound turn) — both were preempted here and never
+                                // routed, even though the bounded call had just resolved them.
+                                //
+                                // A resolution that named an execution target is honored:
+                                // `preventDegenerateRankingResolution` above has already
+                                // downgraded a same-grain entity count to `clarify`, so
+                                // anything still standing is a governed measure the model
+                                // selected from qualified candidate ids.
+                                const resolutionResolvedRanking = safeResolution.recommendedRoute !== 'clarify'
+                                    && Boolean(safeResolution.recommendedExecutionId
+                                        || safeResolution.selectedConceptIds.length > 0);
+                                // An explicit SELECTION answers this gate as well as words in
+                                // the question do. `hasExplicitRankingMeasure` reads the
+                                // question TEXT, and clicking a choice never changes the text —
+                                // so picking `customers.average_order_value` re-asked "Top by
+                                // which governed metric?" with the same three options, forever.
+                                // A degenerate pick is still refused above, so anything
+                                // arriving here is a measure the reader chose from governed
+                                // evidence.
+                                const explicitRankingSelection = Boolean(request.selectedEvidenceId)
+                                    && Boolean(selectedEvidence)
+                                    && !isDegenerateRankingMetric(request.question, evidence, selectedEvidence);
+                                if (safeResolution.questionType === 'ranking'
+                                    && !hasExplicitRankingMeasure(request.question, evidence)
+                                    && !resolutionResolvedRanking
+                                    && !explicitRankingSelection) {
+                                    return bareRankingClarification(base, retrievalTrace(evidence, candidates), request.question, evidence, 
+                                    // Supplemental clarification cards carry the ranking
+                                    // measures for the requested entity, which the execution
+                                    // candidate set deliberately does not.
+                                    clarificationCandidates);
+                                }
+                                const deterministicGap = deterministicPrePlanClarification(request, base, evidence, clarificationCandidates);
+                                if (deterministicGap && safeResolution.recommendedRoute === 'clarify') {
+                                    return deterministicGap;
+                                }
+                                return remember(key, routeDecisionForResolution(base, evidence, candidates, safeResolution, "llm", request.question, options.resolvedPlanMode ?? 'authoritative'));
                             }
                             const invalidResolution = {
                                 interpretedQuestion: request.question,
@@ -1610,7 +1948,15 @@ export function createHybridRouter(options = {}) {
                         // retrieval signal or permitting a general-knowledge misroute.
                         meaningResolverReachable = false;
                     }
-                    return routeWithoutMeaningModel(request, base, evidence, candidates, options.resolvedPlanMode ?? 'authoritative', meaningResolverReachable);
+                    const fallbackDecision = routeWithoutMeaningModel(request, base, evidence, candidates, options.resolvedPlanMode ?? 'authoritative', meaningResolverReachable);
+                    if (!shouldUseMeaningCall)
+                        return fallbackDecision;
+                    // The provider was unavailable or returned malformed JSON. Apply the
+                    // deterministic clarification only after the bounded meaning attempt
+                    // has been exhausted; this preserves a precise recovery path without
+                    // allowing the generic governed error to terminate the question.
+                    return deterministicPrePlanClarification(request, base, evidence, clarificationCandidates)
+                        ?? fallbackDecision;
                 }
             }
             // Legacy/no-evidence path. A confident analytical heuristic stays offline;