@duckcodeailabs/dql-agent 1.13.5 → 1.14.1

package/dist/router.js

@@ -1,3 +1,4 @@
+import { assumeDominantCandidate } from './agentic/assumptions.js';
 /**
  * Hybrid router — deterministic-first, LLM-assisted for the ambiguous middle.
  *
@@ -578,16 +579,26 @@ function routedClarificationQuestion(resolution, bindings, options) {
         ?? `Which governed binding should I use before running this query?`;
 }
 function continueCascadeAfterIncompleteSelection(base, evidence, candidates, selected) {
+    const selectedId = selected.qualifiedId ?? selected.id;
+    const message = `The selected governed meaning ${selectedId} does not prove the complete requested metric, dimension, filter, and grain tuple. DQL did not substitute a correlated metric or execute a different artifact.`;
     return {
         ...base,
-        action: 'answer',
-        confidence: 0.78,
-        reason: `The user selected ${selected.name}, but that evidence does not prove the complete requested metric, dimension, filter, and grain tuple. The selection is consumed once; continue through the governed semantic/SQL cascade without dropping any requested part.`,
+        action: 'block',
+        confidence: 1,
+        reason: message,
         source: 'heuristic',
         category: 'data_lookup',
         depth: 'quick',
         retrievalEvidence: retrievalTrace(evidence, candidates),
         requiresClarification: false,
+        terminalOutcome: {
+            kind: 'modeling_gap',
+            code: 'ANALYTICAL_MODELING_GAP',
+            message,
+            candidateIds: [selectedId],
+        },
+        resolvedAnalyticalPlan: undefined,
+        meaningResolution: undefined,
     };
 }
 function enforceAnalyticalCompatibility(resolution, evidence, candidates) {
@@ -793,6 +804,114 @@ 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);
+    if (options.length === 0) {
+        return unanswerableClarificationFallback(base, retrievalTrace(evidence, candidates), `${selected.name} counts customers and cannot rank them, and no alternative governed measure was retrieved, so DQL continued into the review-required generated lane instead of asking a question with no selectable answer.`);
+    }
+    const labels = options.map((candidate) => renderCandidateChoice(candidate)).join(' or ');
+    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: buildClarificationOptions(options),
+        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 +1049,34 @@ 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)) {
+        // Assume the measure where one is clearly indicated, and BIND it through the
+        // same resolution path an explicit selection takes — an assumption that
+        // cannot freeze a plan is refused downstream and surfaces as `blocked` with
+        // no options, which is worse than the question it replaced.
+        const assumed = mayAssumeInterpretation
+            ? assumableRankingMeasure(request.question, rankingCandidates)
+            : undefined;
+        if (assumed) {
+            return {
+                ...routeDecisionForResolution(base, evidence, candidates, directResolution(request, evidence, assumed.candidate, candidates), 'heuristic', request.question, planMode),
+                assumptions: [assumed.assumption],
+            };
+        }
+        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 +1085,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 +1122,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 +1197,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.
@@ -1112,9 +1346,60 @@ function deterministicPrePlanClarification(request, base, evidence, candidates)
             .sort((left, right) => right.relevanceScore - left.relevanceScore || left.id.localeCompare(right.id))
             .slice(0, 3);
         if (alternatives.length === 0) {
-            if (!asksForRanking || hasExplicitRankingMetric)
+            // Bare rankings need a measure choice, not a dimension gap. Retain the
+            // no-options escape hatch for BCM-like retrieval failures.
+            if (asksForRanking && !hasExplicitRankingMetric) {
+                return bareRankingClarification(base, retrievalEvidence, request.question, evidence, candidates);
+            }
+            // Parsed-intent hints can include inherited/default dimensions that the
+            // user never asked for. Only turn a missing field into a product-facing
+            // modeling gap when its wording is present in this turn; otherwise let
+            // bounded meaning resolution preserve its own ambiguity contract.
+            const normalizedQuestion = normalizeMetricPhrase(request.question);
+            if (!missingDimensions.every((dimension) => normalizedQuestion.includes(dimension)))
                 return undefined;
-            return bareRankingClarification(base, retrievalEvidence);
+            const requestedLabel = missingDimensions.map((term) => `“${term}”`).join(' and ');
+            const message = `The requested dimension ${requestedLabel} is not modeled in the certified blocks, semantic model, dbt manifest, or runtime schema searched for this question. Add or map ${requestedLabel} before retrying.`;
+            return {
+                ...base,
+                action: 'block',
+                confidence: 1,
+                reason: message,
+                source: 'heuristic',
+                category: 'data_lookup',
+                depth: 'quick',
+                requiresClarification: false,
+                retrievalEvidence,
+                terminalOutcome: {
+                    kind: 'modeling_gap',
+                    code: 'ANALYTICAL_MODELING_GAP',
+                    message,
+                    candidateIds: [],
+                },
+                meaningResolution: {
+                    interpretedQuestion: request.question,
+                    questionType: questionTypeFromText(request.question),
+                    selectedConceptIds: [],
+                    queryIntent: {
+                        ...defaultQueryIntent(evidence),
+                        measures: evidence.parsedIntent?.measures ?? [],
+                        dimensions: evidence.parsedIntent?.dimensions ?? [],
+                        filters: evidence.parsedIntent?.filters ?? [],
+                    },
+                    rejectedCandidates: [],
+                    confidence: 'low',
+                    missingInformation: [message],
+                    recommendedRoute: 'clarify',
+                    compatibilityOutcome: 'modeling_gap',
+                    compatibilityFailures: missingDimensions.map((dimension) => ({
+                        code: 'MISSING_DIMENSION',
+                        field: dimension,
+                        message: `${dimension} is not modeled.`,
+                        candidateIds: [],
+                    })),
+                },
+                resolvedAnalyticalPlan: undefined,
+            };
         }
         const requestedLabel = missingDimensions.map((term) => `“${term}”`).join(' and ');
         const alternativeLabels = alternatives.map(renderCandidateChoice);
@@ -1137,11 +1422,187 @@ 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) {
+/**
+ * A clarification with NO selectable options is unanswerable, and asking it is a
+ * dead end rather than a safety measure.
+ *
+ * Reported from production: "who are the top customers for BCM" returned
+ * "Top by which governed metric?" with zero choices. Answering it in prose
+ * ("...who have top revenue") produced the IDENTICAL question again, because the
+ * reply carries no `selectedEvidenceId` and re-enters the same path with the
+ * same evidence. A question that can only be answered by clicking a button that
+ * was never rendered loops forever.
+ *
+ * When the option list is empty the failure is in RETRIEVAL, not in the user's
+ * phrasing, so continue into the review-required generated lane and let the
+ * answer carry the caveat. `requiresClarification` is cleared deliberately:
+ * leaving it set would make `answerAnywayRoute` treat this as material ambiguity
+ * and re-block the turn.
+ */
+function unanswerableClarificationFallback(base, retrievalEvidence, reason) {
+    return {
+        ...base,
+        action: 'answer',
+        confidence: Math.min(base.confidence, 0.5),
+        source: 'heuristic',
+        category: 'data_lookup',
+        requiresClarification: false,
+        clarifyingQuestion: undefined,
+        clarificationOptions: undefined,
+        reason,
+        ...(retrievalEvidence ? { retrievalEvidence } : {}),
+        resolvedAnalyticalPlan: undefined,
+        meaningResolution: undefined,
+    };
+}
+/**
+ * "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.
+ */
+/**
+ * Generic measure vocabulary: words that say HOW MUCH, never WHICH SUBSET.
+ * A candidate built only from these adds no scope the asker did not state.
+ */
+const GENERIC_MEASURE_TOKENS = new Set([
+    'revenue', 'spend', 'spending', 'sale', 'amount', 'value', 'total', 'sum',
+    'count', 'number', 'order', 'quantity', 'qty', 'price', 'cost', 'profit',
+    'margin', 'gross', 'net', 'lifetime', 'avg', 'average', 'mean', 'median', 'score',
+    'rate', 'ratio', 'percent', 'share', 'volume', 'unit', 'balance', 'pretax', 'ltv',
+    'top', 'rank', 'ranking', 'by', 'per', 'the', 'of', 'and',
+]);
+/**
+ * Crude, symmetric singularization. Applied to BOTH sides, so the only thing
+ * that matters is that it agrees with itself — `address` becoming `addres` is
+ * harmless when the question's `address` becomes `addres` too. Without it a
+ * candidate named `customers.customer_value` is rejected against the question
+ * "who are the top customers", because the singular `customer` is neither a
+ * question word nor generic measure vocabulary. That is a morphology accident,
+ * not an unrequested scope, and it silently refused good assumptions.
+ */
+function singularize(token) {
+    if (token.length > 3 && token.endsWith('ies'))
+        return `${token.slice(0, -3)}y`;
+    if (token.length > 3 && (token.endsWith('ses') || token.endsWith('xes') || token.endsWith('zes'))) {
+        return token.slice(0, -2);
+    }
+    if (token.length > 2 && token.endsWith('s') && !token.endsWith('ss'))
+        return token.slice(0, -1);
+    return token;
+}
+/**
+ * Pick the measure a bare ranking should assume, or nothing.
+ *
+ * Returns the CANDIDATE, not a decision, because the assumption is only useful
+ * where it can be bound: an `action: 'answer'` with no frozen analytical plan is
+ * refused by the plan boundary and reaches the user as `blocked` with no
+ * options, which is strictly worse than the clarification it replaced. Measured
+ * exactly that way before this was moved to a caller that can bind it.
+ */
+export function assumableRankingMeasure(question, candidates) {
+    // Only a MEASURE can be assumed. A certified block is a whole authored query,
+    // not a ranking measure, so treating one as the answer to "by which metric?"
+    // silently selects someone else's entire analysis.
+    const assumable = candidates.filter((candidate) => (candidate.kind === 'semantic_metric' || candidate.kind === 'semantic_member')
+        && candidate.compatibility !== 'incompatible'
+        && rankingCandidateFitsBareQuestion(question, candidate));
+    if (assumable.length === 0)
+        return undefined;
+    const assumption = assumeDominantCandidate({
+        about: 'metric',
+        candidates: assumable.map((candidate) => ({
+            id: candidate.qualifiedId ?? candidate.id,
+            label: candidate.name,
+            score: candidate.relevanceScore,
+        })),
+        because: (chosen) => `"${chosen.label ?? chosen.id}" was the highest-ranked governed measure that can rank this entity, and it adds no filter the question did not ask for.`,
+    });
+    if (!assumption)
+        return undefined;
+    const chosen = assumable.find((candidate) => (candidate.qualifiedId ?? candidate.id) === assumption.chose);
+    return chosen ? { candidate: chosen, assumption } : undefined;
+}
+/**
+ * Does this ranking measure fit a question that named no measure?
+ *
+ * "Top customers" must not be silently answered by `top_beverage_customers`:
+ * that candidate carries a scope — beverages — the asker never asked for, and
+ * answering with it returns a confidently wrong list under a different question
+ * than the one posed. `assumeDominantCandidate` deliberately leaves this check
+ * to the caller, because dominance is about ranking and this is about meaning.
+ *
+ * The rule: every substantive token in the candidate's name must be either
+ * something the question already said, or generic measure vocabulary. Any
+ * leftover token is an unrequested qualifier, and the turn keeps asking.
+ */
+export function rankingCandidateFitsBareQuestion(question, candidate) {
+    const questionTokens = new Set(substantiveLexicalTokens(question).map(singularize));
+    // Identities arrive source-qualified (`semantic:metric:orders.revenue`). The
+    // `semantic`/`metric` prefix is plumbing, not vocabulary — tokenizing it would
+    // make every candidate look scoped and refuse every assumption.
+    const identity = (candidate.qualifiedId ?? candidate.id ?? '').split(':').at(-1) ?? '';
+    const nameTokens = substantiveLexicalTokens([candidate.name, identity].join(' '));
+    if (nameTokens.length === 0)
+        return false;
+    return nameTokens.map(singularize).every((token) => questionTokens.has(token) || GENERIC_MEASURE_TOKENS.has(token));
+}
+function bareRankingClarification(base, retrievalEvidence, question, evidence, candidates, 
+/**
+ * May this turn settle the measure by assumption rather than by asking?
+ * False wherever the step whose job is to judge ambiguity has positively
+ * reported some — assuming past a finding overrides it rather than filling a
+ * gap, and AGT-017 already establishes that lexical rank alone must not
+ * settle meaning when semantic judgment is unavailable.
+ */
+mayAssume = true) {
+    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;
+    });
+    if (rankingChoices.length === 0) {
+        return unanswerableClarificationFallback(base, retrievalEvidence, 'No retrieved governed measure can rank this entity, so DQL continued into the review-required generated lane instead of asking a question with no selectable answer.');
+    }
     return {
         ...base,
         action: 'clarify',
@@ -1153,6 +1614,7 @@ function bareRankingClarification(base, retrievalEvidence) {
         requiresClarification: true,
         clarifyingQuestion: 'Top by which governed metric?',
         retrievalEvidence,
+        clarificationOptions: buildClarificationOptions(rankingChoices),
         resolvedAnalyticalPlan: undefined,
         meaningResolution: undefined,
     };
@@ -1432,6 +1894,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 +1955,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 +1976,69 @@ 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');
                     }
+                    // THE FAST LANE. Evaluated regardless of `shouldUseMeaningCall`, so an
+                    // exact certified hit short-circuits BEFORE the ~10s meaning call
+                    // rather than paying for it. Previously this shortcut only applied
+                    // when the call was already being skipped, which meant a perfect
+                    // certified match — the cheapest, most certain answer DQL can give —
+                    // was also one of the slowest.
+                    //
+                    // The precondition is deliberately the strictest one available:
+                    // exactly one certified block, compatible, whose AUTHORED EXAMPLE the
+                    // question matches. `meaning-evidence.ts` sets that flag only for an
+                    // authored-example fit and explicitly notes it is the one signal that
+                    // may grant this shortcut — lexical equality to a block name does not
+                    // qualify.
                     const authoredExample = authoritativeExactCertifiedExample(candidates);
                     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 +2082,73 @@ 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) {
+                                    // Meaning resolution ran here. If it named the ranking
+                                    // measure as the missing piece, that is its judgment and the
+                                    // turn asks rather than guessing past it. Otherwise a clearly
+                                    // indicated measure is assumed and BOUND through the same
+                                    // resolution path an explicit selection takes — an assumption
+                                    // that cannot freeze a plan is refused downstream and reaches
+                                    // the reader as `blocked` with no options.
+                                    const resolverFlagged = (safeResolution.missingInformation ?? [])
+                                        .some((item) => /measure|metric/i.test(item));
+                                    const assumedRanking = resolverFlagged
+                                        ? undefined
+                                        : assumableRankingMeasure(request.question, clarificationCandidates);
+                                    if (assumedRanking) {
+                                        return {
+                                            ...routeDecisionForResolution(base, evidence, candidates, directResolution(request, evidence, assumedRanking.candidate, candidates), 'heuristic', request.question),
+                                            assumptions: [assumedRanking.assumption],
+                                        };
+                                    }
+                                    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, !resolverFlagged);
+                                }
+                                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 +2181,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;