@duckcodeailabs/dql-agent 1.13.4 → 1.14.0

package/dist/router.js

@@ -15,11 +15,11 @@
  * question never pays twice.
  */
 import { classifyConversationalTurn, decideAgentAction, } from "./intent-controller.js";
-import { buildMeaningEvidencePackage, defaultQueryIntent, findExplicitEvidenceReference, questionTypeFromText, routeForEvidenceCandidate, validateMeaningResolution, } from "./meaning-resolution.js";
+import { buildMeaningEvidencePackage, canonicalizeMetricMeasureCandidates, defaultQueryIntent, findExplicitEvidenceReference, questionTypeFromText, routeForEvidenceCandidate, validateMeaningResolution, } from "./meaning-resolution.js";
 import { normalizeAnalyticalQuestionFrameV2 } from "@duckcodeailabs/dql-core";
 import { buildResolvedAnalyticalPlan, } from "./resolved-analytical-plan.js";
 import { normalizeEvidenceAnalyticalCapability, solveAnalyticalCompatibility, } from "./analytical-compatibility.js";
-import { buildDeterministicAnalyticalFrame } from "./analytical-frame.js";
+import { buildDeterministicAnalyticalFrame, projectResolvedAnalyticalFrame } from "./analytical-frame.js";
 import { conversationHistoryFromContext, renderConversationEnvelopeForPrompt, } from "./conversation/snapshot.js";
 const DEFAULT_THRESHOLD = 0.7;
 const DEFAULT_CACHE_SIZE = 200;
@@ -414,14 +414,22 @@ function retrievalTrace(evidence, candidates) {
     };
 }
 function routeDecisionForResolution(base, evidence, candidates, resolution, source, question = resolution.interpretedQuestion, mode = 'authoritative') {
-    const routedResolution = enforceAnalyticalCompatibility(resolution, evidence, candidates);
-    const needsClarification = routedResolution.confidence === "low" ||
-        routedResolution.recommendedRoute === "clarify";
-    const analytical = routedResolution.questionType === "diagnosis" ||
-        routedResolution.questionType === "research";
-    const reason = needsClarification
-        ? `The retrieved evidence does not prove one complete analytical tuple: ${routedResolution.missingInformation.join(" ") || routedResolution.interpretedQuestion}`
-        : `Resolved the question against ${routedResolution.selectedConceptIds.join(", ")}: ${routedResolution.interpretedQuestion}`;
+    let planBoundResolution = resolution;
+    if (resolution.analyticalFrame && resolution.recommendedRoute === 'semantic') {
+        const { analyticalFrame: sourceFrame, ...resolutionWithoutFrame } = resolution;
+        const bindingPlan = buildResolvedAnalyticalPlan({
+            question,
+            resolution: resolutionWithoutFrame,
+            evidence,
+            candidates,
+            mode,
+        });
+        planBoundResolution = {
+            ...resolution,
+            analyticalFrame: projectResolvedAnalyticalFrame({ plan: bindingPlan, sourceFrame }),
+        };
+    }
+    const routedResolution = enforceAnalyticalCompatibility(planBoundResolution, evidence, candidates);
     const resolvedAnalyticalPlan = buildResolvedAnalyticalPlan({
         question,
         resolution: routedResolution,
@@ -429,13 +437,22 @@ function routeDecisionForResolution(base, evidence, candidates, resolution, sour
         candidates,
         mode,
     });
+    const reconciliation = reconcileResolvedPlanOutcome(routedResolution, resolvedAnalyticalPlan, candidates);
+    const needsClarification = reconciliation.outcome === 'clarify';
+    const terminallyBlocked = reconciliation.outcome === 'modeling_gap'
+        || reconciliation.outcome === 'policy_blocked';
+    const analytical = routedResolution.questionType === "diagnosis" ||
+        routedResolution.questionType === "research";
+    const reason = reconciliation.reason;
     return {
         ...base,
         action: needsClarification
             ? "clarify"
-            : analytical
-                ? "investigate"
-                : "answer",
+            : terminallyBlocked
+                ? "block"
+                : analytical
+                    ? "investigate"
+                    : "answer",
         confidence: routedResolution.confidence === "high"
             ? 0.9
             : routedResolution.confidence === "medium"
@@ -449,17 +466,117 @@ function routeDecisionForResolution(base, evidence, candidates, resolution, sour
         resolvedAnalyticalPlan,
         retrievalEvidence: retrievalTrace(evidence, candidates),
         requiresClarification: needsClarification,
+        ...(terminallyBlocked
+            ? {
+                terminalOutcome: {
+                    kind: reconciliation.outcome === 'policy_blocked'
+                        ? 'policy_blocked'
+                        : 'modeling_gap',
+                    code: reconciliation.outcome === 'policy_blocked'
+                        ? 'ANALYTICAL_POLICY_BLOCKED'
+                        : 'ANALYTICAL_MODELING_GAP',
+                    message: reconciliation.reason,
+                    candidateIds: resolvedAnalyticalPlan.resolutionFailure?.candidateIds ?? [],
+                },
+            }
+            : {}),
         ...(needsClarification
-            ? { clarificationOptions: buildClarificationOptions(candidates) }
+            ? { clarificationOptions: reconciliation.options }
             : {}),
         ...(needsClarification
             ? {
-                clarifyingQuestion: routedResolution.clarifyingQuestion ??
-                    buildEvidenceClarification(candidates, routedResolution.missingInformation),
+                clarifyingQuestion: reconciliation.question,
             }
             : {}),
     };
 }
+/**
+ * The immutable RAP is the final routing authority. Meaning may nominate an
+ * execution route, but cannot leave the router claiming an answer after the
+ * host has retained an ambiguous or blocked qualified binding.
+ */
+function reconcileResolvedPlanOutcome(resolution, plan, candidates) {
+    if (plan.capability !== 'blocked') {
+        return {
+            outcome: 'ready',
+            reason: `Resolved the question against ${plan.selectedConceptIds.join(', ')}: ${resolution.interpretedQuestion}`,
+        };
+    }
+    const bindings = [
+        ...plan.query.measures.map((binding) => ({ kind: 'measure', binding })),
+        ...plan.query.dimensions.map((binding) => ({ kind: 'dimension', binding })),
+        ...plan.query.filters.map((filter) => ({ kind: 'filter', binding: filter.binding })),
+    ].filter(({ binding }) => binding.status !== 'resolved');
+    const qualifiedChoiceIds = [...new Set(bindings.flatMap(({ binding }) => binding.candidateIds))].sort();
+    const userResolvableBinding = bindings.some(({ binding }) => binding.candidateIds.length > 0);
+    if (plan.resolutionFailure?.outcome === 'policy_blocked') {
+        return {
+            outcome: 'policy_blocked',
+            reason: `Policy blocked the selected analytical plan: ${plan.missingInformation.join(' ') || 'review the retained policy diagnostic.'}`,
+        };
+    }
+    if (plan.resolutionFailure?.outcome === 'modeling_gap') {
+        return {
+            outcome: 'modeling_gap',
+            reason: `The selected analytical plan has a governed modeling gap: ${plan.missingInformation.join(' ') || 'review the retained capability diagnostic.'}`,
+        };
+    }
+    if (userResolvableBinding || plan.resolutionFailure?.outcome === 'clarify') {
+        const optionIds = qualifiedChoiceIds.length > 0
+            ? qualifiedChoiceIds
+            : [...new Set((resolution.compatibilityFailures ?? []).flatMap((failure) => failure.candidateIds))].sort();
+        const options = optionIds.length > 0
+            ? clarificationOptionsForQualifiedIds(optionIds, candidates)
+            : buildClarificationOptions(candidates);
+        const bindingSummary = bindings.map(({ kind, binding }) => `${kind} “${binding.requested}” is ${binding.status}`).join('; ');
+        const question = routedClarificationQuestion(resolution, bindings, options);
+        return {
+            outcome: 'clarify',
+            reason: `The immutable analytical plan needs one identifier-bound choice: ${bindingSummary || plan.missingInformation.join(' ')}`,
+            question,
+            options,
+        };
+    }
+    if (resolution.confidence === 'low' || resolution.recommendedRoute === 'clarify') {
+        return {
+            outcome: 'clarify',
+            reason: `The retrieved evidence needs one governed meaning choice: ${plan.missingInformation.join(' ') || resolution.interpretedQuestion}`,
+            question: resolution.clarifyingQuestion ?? buildEvidenceClarification(candidates, plan.missingInformation),
+            options: buildClarificationOptions(candidates),
+        };
+    }
+    return {
+        outcome: 'modeling_gap',
+        reason: `The selected analytical plan is not executable from the governed model: ${plan.missingInformation.join(' ') || 'review its capability and relationship proof.'}`,
+    };
+}
+function clarificationOptionsForQualifiedIds(ids, candidates) {
+    return ids.slice(0, 3).map((id) => {
+        const candidate = candidates.find((item) => item.id === id || item.qualifiedId === id);
+        return {
+            id,
+            label: candidate?.name ?? qualifiedIdLabel(id),
+            ...(candidate?.definition?.trim() ? { description: candidate.definition.trim() } : {}),
+            kind: candidate?.kind ?? 'semantic_member',
+        };
+    });
+}
+function qualifiedIdLabel(id) {
+    const local = id.split(/[:./]/).filter(Boolean).at(-1) ?? id;
+    return local.replace(/[_-]+/g, ' ').replace(/\b\w/g, (character) => character.toUpperCase());
+}
+function routedClarificationQuestion(resolution, bindings, options) {
+    if (resolution.clarifyingQuestion && !/^The analytical frame has unresolved ambiguity:/i.test(resolution.clarifyingQuestion)) {
+        return resolution.clarifyingQuestion;
+    }
+    const first = bindings[0];
+    const labels = options.map((option) => option.label);
+    if (first && labels.length > 1) {
+        return `Which governed ${first.kind} should I use for “${first.binding.requested}”: ${labels.join(' or ')}?`;
+    }
+    return resolution.clarifyingQuestion
+        ?? `Which governed binding should I use before running this query?`;
+}
 function continueCascadeAfterIncompleteSelection(base, evidence, candidates, selected) {
     return {
         ...base,
@@ -478,7 +595,14 @@ function enforceAnalyticalCompatibility(resolution, evidence, candidates) {
     const requestedMetricCount = new Set((evidence.parsedIntent?.measures ?? resolution.queryIntent.measures)
         .map(normalizeMetricPhrase)
         .filter(Boolean)).size;
+    // Parser hints may split one business metric name into overlapping measure
+    // tokens (for example "rollover balance amount" -> "balance", "amount").
+    // Treat several hints as a multi-metric contract only when the question
+    // actually coordinates separate measures; otherwise one exact qualified
+    // capability is allowed to bind all synonymous hints.
+    const explicitlyCoordinatesMetrics = /(?:,|\b(?:and|plus|versus|vs\.?|along with)\b)/i.test(resolution.interpretedQuestion);
     if (requestedMetricCount > 1
+        && explicitlyCoordinatesMetrics
         && (missingMetricTerms.length > 0
             || (resolution.analyticalFrame?.metricConceptIds.length ?? 0) < requestedMetricCount)) {
         const missing = missingMetricTerms.length > 0
@@ -529,6 +653,8 @@ function enforceAnalyticalCompatibility(resolution, evidence, candidates) {
             recommendedExecutionId: result.candidateId,
             recommendedRoute: result.route,
             missingInformation: [],
+            compatibilityOutcome: undefined,
+            compatibilityFailures: undefined,
         };
     }
     // A question asking for SEVERAL metrics ("revenue and refunds by month") is a
@@ -547,12 +673,26 @@ function enforceAnalyticalCompatibility(resolution, evidence, candidates) {
         };
     }
     const failures = result.failures.map((failure) => failure.message);
+    const compatibilityFailures = result.failures.map((failure) => ({
+        code: failure.code,
+        field: failure.field,
+        message: failure.message,
+        candidateIds: [...(failure.candidateIds ?? [])],
+    }));
+    const policyFailure = result.failures.some((failure) => failure.code.startsWith('POLICY_'));
+    const compatibilityOutcome = policyFailure
+        ? 'policy_blocked'
+        : result.status === 'clarify'
+            ? 'clarify'
+            : 'modeling_gap';
     return {
         ...resolution,
         analyticalFrame: result.frame,
         analyticalPolicyIds: result.policyIds,
         confidence: result.status === "clarify" ? "low" : resolution.confidence,
         recommendedRoute: "clarify",
+        compatibilityOutcome,
+        compatibilityFailures,
         missingInformation: [
             ...new Set([...resolution.missingInformation, ...failures]),
         ],
@@ -570,12 +710,72 @@ function buildClarificationOptions(candidates) {
     const pool = governed.length > 1
         ? governed
         : candidates.filter((candidate) => candidate.compatibility !== "incompatible");
-    return pool.slice(0, 3).map((candidate) => ({
-        id: candidate.id,
-        label: candidate.name,
-        ...(candidate.definition?.trim() ? { description: candidate.definition.trim() } : {}),
-        kind: candidate.kind,
-    }));
+    const chosen = pool.slice(0, 3);
+    // Two candidates can legitimately share a display name (a dbt model and its
+    // MetricFlow measure are both "customers"). Rendering both as "customers"
+    // asks the user to choose between two identical-looking buttons, so the
+    // duplicates carry their distinguishing identity.
+    const nameCounts = new Map();
+    for (const candidate of chosen) {
+        nameCounts.set(candidate.name, (nameCounts.get(candidate.name) ?? 0) + 1);
+    }
+    return chosen.map((candidate) => {
+        const ambiguousName = (nameCounts.get(candidate.name) ?? 0) > 1;
+        const description = humanizeCandidateDefinition(candidate.definition);
+        return {
+            id: candidate.id,
+            label: ambiguousName
+                ? `${candidate.name} (${candidateKindLabel(candidate.kind)})`
+                : candidate.name,
+            ...(description ? { description } : {}),
+            kind: candidate.kind,
+        };
+    });
+}
+function candidateKindLabel(kind) {
+    if (kind === 'certified_block')
+        return 'certified block';
+    if (kind === 'semantic_metric')
+        return 'metric';
+    if (kind === 'semantic_member')
+        return 'model field';
+    return kind.replace(/[_-]+/g, ' ');
+}
+/**
+ * A candidate's `definition` is sometimes the raw semantic-layer record —
+ * `label: customers\naggregation: count_distinct\ntable: "..."\nexpr: customer_id`.
+ * Dumping that into a question asks a business user to disambiguate by reading
+ * YAML. Turn a recognisable key/value record into one plain sentence; leave
+ * genuine authored prose alone.
+ */
+export function humanizeCandidateDefinition(definition) {
+    const text = definition?.trim();
+    if (!text)
+        return undefined;
+    const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    const fields = new Map();
+    for (const line of lines) {
+        const match = /^([a-z_][a-z0-9_]*)\s*:\s*(.+)$/i.exec(line);
+        if (match)
+            fields.set(match[1].toLowerCase(), match[2].trim().replace(/^["']|["']$/g, ''));
+    }
+    // Only treat it as a record when MOST of it is key/value pairs; a one-line
+    // sentence containing a colon is prose, not a dump.
+    if (fields.size < 2 || fields.size < lines.length - 1) {
+        return text.replace(/\s+/g, ' ').slice(0, 200);
+    }
+    const aggregation = fields.get('aggregation');
+    const expr = fields.get('expr');
+    const table = fields.get('table');
+    const parts = [];
+    if (aggregation)
+        parts.push(`${aggregation.replace(/_/g, ' ')}${expr ? ` of ${expr}` : ''}`);
+    else if (expr)
+        parts.push(expr);
+    if (table)
+        parts.push(`from ${table.split('.').pop()?.replace(/"/g, '') ?? table}`);
+    const summary = parts.join(' ');
+    return summary ? `${summary}.` : undefined;
 }
 function buildEvidenceClarification(candidates, missing = []) {
     const governedChoices = candidates.filter((candidate) => candidate.compatibility !== "incompatible"
@@ -593,21 +793,151 @@ 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'
+        && candidate.kind === 'semantic_metric'
+        && candidate.exactMatch
+        && Boolean(normalizeEvidenceAnalyticalCapability(candidate).capability)
+        && /^\s*what (?:is|was|were|are)\b/i.test(request.question)
+        && !/\b(?:define|definition|meaning|mean)\b/i.test(request.question)
+        ? 'value'
+        : inferredQuestionType;
     const metricCandidates = explicitlyRequestedMetricCandidates(request.question, evidence, candidate, candidates);
     const analyticalFrame = buildDeterministicAnalyticalFrame({
         question: request.question,
+        questionType,
         evidence,
         metricCandidate: candidate,
         metricCandidates,
         candidates,
     });
+    const queryIntent = defaultQueryIntent(evidence);
+    const memberCandidates = candidates.filter((item) => {
+        if (item.kind !== 'semantic_member' || item.compatibility === 'incompatible')
+            return false;
+        const identities = [item.name, ...(item.aliases ?? [])].map(normalizeMetricPhrase).filter(Boolean);
+        return queryIntent.filters.some((filter) => identities.includes(normalizeMetricPhrase(filter.value)));
+    });
+    const canonicalFilters = queryIntent.filters.map((filter) => {
+        const member = memberCandidates.find((item) => [item.name, ...(item.aliases ?? [])]
+            .map(normalizeMetricPhrase)
+            .includes(normalizeMetricPhrase(filter.value)));
+        return member ? { ...filter, value: member.name } : filter;
+    });
     return {
         interpretedQuestion: request.question,
-        questionType: questionTypeFromText(request.question),
-        selectedConceptIds: metricCandidates.map((metric) => metric.id),
+        questionType,
+        selectedConceptIds: [...metricCandidates, ...memberCandidates].map((item) => item.id),
         recommendedExecutionId: candidate.id,
-        queryIntent: defaultQueryIntent(evidence),
+        queryIntent: { ...queryIntent, filters: canonicalFilters },
         rejectedCandidates: [],
         confidence: "high",
         missingInformation: [],
@@ -623,6 +953,12 @@ function explicitlyRequestedMetricCandidates(question, evidence, primary, candid
     // representations of the same request, not additional requested metrics.
     if (requestedTerms.length <= 1)
         return [primary];
+    const primaryNames = [primary.name, ...(primary.aliases ?? [])]
+        .map(normalizeMetricPhrase)
+        .filter(Boolean);
+    if (requestedTerms.every((term) => primaryNames.some((name) => metricTermsMatch(name, term)))) {
+        return [primary];
+    }
     const questionText = normalizeMetricPhrase(question);
     const metrics = candidates.filter((candidate) => {
         if (candidate.kind !== 'semantic_metric' || candidate.compatibility === 'incompatible')
@@ -646,6 +982,7 @@ function explicitlyRequestedMetricCandidates(question, evidence, primary, candid
 function normalizeMetricPhrase(value) {
     return value
         .toLowerCase()
+        .replace(/%/g, ' percentage ')
         .replace(/[_./:-]+/g, ' ')
         .replace(/[^a-z0-9 ]+/g, ' ')
         .replace(/\s+/g, ' ')
@@ -686,36 +1023,528 @@ function exactMultiMetricPrimary(question, evidence, candidates) {
         ? primary
         : undefined;
 }
-function routeWithoutMeaningModel(request, base, evidence, candidates, planMode = 'authoritative') {
+function routeWithoutMeaningModel(request, base, evidence, candidates, planMode = 'authoritative', 
+/**
+ * Whether DQL may commit to the best-ranked reading on the user's behalf.
+ *
+ * False when the meaning resolver never got to run (provider outage). Two
+ * genuinely different metrics that merely share an alias — `booked_revenue`
+ * and `billed_revenue` both aliased "revenue" — must not be settled by
+ * lexical rank alone with the semantic judgment switched off. AGT-017.
+ */
+mayAssumeInterpretation = true) {
     const multiMetricPrimary = exactMultiMetricPrimary(request.question, evidence, candidates);
     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);
     }
-    if (base.action === "investigate") {
+    // Last resort before asking the user: commit to the best governed reading.
+    // Clarifying whenever retrieval returned more than one candidate meant a
+    // `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, rankingCandidates)
+        : undefined;
+    if (best) {
+        return routeDecisionForResolution(base, evidence, candidates, directResolution(request, evidence, best, candidates), "heuristic", request.question, planMode);
+    }
+    return unresolvedAnalyticalPlanDecision(base, evidence, candidates, request.question);
+}
+/** Leaf identity of a governed candidate, ignoring its source qualification. */
+function candidateLeafName(candidate) {
+    const identity = candidate.qualifiedId ?? candidate.id;
+    return (identity.split(/[.:]/).at(-1) ?? candidate.name).trim().toLowerCase();
+}
+/** Prefer the most authoritative representative of one underlying meaning. */
+function governedObjectAuthority(candidate) {
+    if (candidate.semanticObjectType === 'metric')
+        return 3;
+    if (candidate.semanticObjectType === 'measure')
+        return 2;
+    if (candidate.semanticObjectType === 'model')
+        return 1;
+    return 0;
+}
+/**
+ * Reduce retrieval output to genuinely DIFFERENT governed meanings.
+ *
+ * Two collapses, both provable from the semantic registry rather than guessed:
+ *  - A simple metric, the measure it wraps, and the model that holds them are
+ *    one meaning. Offering all three asks a person to choose between a thing
+ *    and its own wrapper.
+ *  - An entity is a join key, not an answer. When the question asks for an
+ *    attribute ("customer names") and a dimension matched, entities are not
+ *    candidate readings of it at all.
+ */
+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));
+    // 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');
+    // 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) {
+        const type = candidate.semanticObjectType;
+        if (type !== 'metric' && type !== 'measure' && type !== 'model') {
+            passthrough.push(candidate);
+            continue;
+        }
+        const key = `${(candidate.semanticModel ?? '').toLowerCase()}::${candidateLeafName(candidate)}`;
+        const current = representatives.get(key);
+        if (!current || governedObjectAuthority(candidate) > governedObjectAuthority(current)) {
+            representatives.set(key, candidate);
+        }
+    }
+    // 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.
+ *
+ * DQL commits to the best-ranked interpretation and discloses it through the
+ * route label, instead of stopping to ask. Asking on every multi-candidate
+ * question made ordinary lookups feel like an interrogation, and most of those
+ * questions had no real ambiguity behind them.
+ */
+export function bestGovernedInterpretation(question, candidates) {
+    // Take the best candidate that is actually executable, rather than refusing
+    // because the top-ranked hit happens to be a descriptive modeling entity.
+    // `compatibility: 'unknown'` is common for governed objects that execute
+    // perfectly well, so it does not disqualify — but 'partial' does. A partial
+    // match has already been proven NOT to cover the request, and running one
+    // silently answers a different question than the one that was asked.
+    return collapseRedundantGovernedCandidates(question, candidates).find((candidate) => candidate.compatibility !== 'partial'
+        && (candidate.kind === 'certified_block'
+            || candidate.kind === 'semantic_metric'
+            || candidate.kind === 'semantic_member'));
+}
+/**
+ * Retrieval may nominate qualified candidates, but only the resolved plan may
+ * authorize analytical execution. If bounded meaning cannot freeze one exact
+ * tuple, retain stable candidate identities for a focused continuation or emit
+ * a typed modeling gap. Never hand those candidates to the legacy answer loop
+ * as another meaning/planning authority.
+ */
+function unresolvedAnalyticalPlanDecision(base, evidence, candidates = [], question = '') {
+    // Ask only about meanings that genuinely differ. A metric, the measure it
+    // wraps, and their model are one reading, and a join key is not a reading of
+    // an attribute question at all.
+    const eligible = collapseRedundantGovernedCandidates(question, candidates);
+    const trace = evidence ? retrievalTrace(evidence, candidates) : {
+        candidateCount: 0,
+        candidateIds: [],
+    };
+    if (eligible.length > 1) {
+        const choices = eligible.slice(0, 3);
         return {
             ...base,
-            category: "data_analysis",
-            retrievalEvidence: retrievalTrace(evidence, candidates),
+            action: 'clarify',
+            confidence: 1,
+            source: 'heuristic',
+            category: 'unclear',
+            depth: 'quick',
+            reason: 'Bounded retrieval found multiple governed meanings, so no analytical plan was frozen.',
+            requiresClarification: true,
+            clarifyingQuestion: `Which governed meaning should DQL bind: ${choices.map(renderCandidateChoice).join(' or ')}?`,
+            clarificationOptions: buildClarificationOptions(choices),
+            retrievalEvidence: trace,
+            resolvedAnalyticalPlan: undefined,
+            meaningResolution: undefined,
         };
     }
+    const candidateIds = eligible.map((candidate) => candidate.qualifiedId ?? candidate.id);
+    const message = candidateIds.length === 1
+        ? `The retrieved governed candidate ${candidateIds[0]} did not prove the complete requested metric, grain, filters, ordering, and outputs. Model the missing capability before retrying.`
+        : 'No governed candidate proved the complete requested metric, grain, filters, ordering, and outputs. Model the missing capability or choose a governed identifier before retrying.';
     return {
         ...base,
-        action: "answer",
-        confidence: Math.max(base.confidence, 0.7),
-        reason: `Retrieved ${candidates.length} governed candidate${candidates.length === 1 ? "" : "s"}; the answer executor will resolve them without a router general-knowledge fallback.`,
-        category: "data_lookup",
-        retrievalEvidence: retrievalTrace(evidence, candidates),
+        action: 'block',
+        confidence: 1,
+        source: 'heuristic',
+        category: base.action === 'investigate' ? 'data_analysis' : 'data_lookup',
+        depth: 'quick',
+        reason: message,
+        requiresClarification: false,
+        retrievalEvidence: trace,
+        terminalOutcome: {
+            kind: 'modeling_gap',
+            code: 'ANALYTICAL_MODELING_GAP',
+            message,
+            candidateIds,
+        },
+        resolvedAnalyticalPlan: undefined,
+        meaningResolution: undefined,
+    };
+}
+/**
+ * Deterministic business questions that must be settled before meaning/model
+ * orchestration.  These are not proof failures: no immutable analytical plan
+ * exists yet, so the only valid outcome is one concise clarification.
+ */
+function deterministicPrePlanClarification(request, base, evidence, candidates) {
+    const asksForRanking = questionTypeFromText(request.question) === 'ranking';
+    const requestedMeasures = (evidence.parsedIntent?.measures ?? [])
+        .map(normalizeMetricPhrase)
+        .filter(Boolean);
+    const hasExplicitRankingMetric = requestedMeasures.length > 0
+        && requestedMeasures.every((requested) => candidates.some((candidate) => candidateProvesMetricTerm(candidate, requested)))
+        || hasStrongQualifiedMetricEvidence(candidates)
+        || hasQuestionQualifiedMetricEvidence(request.question, evidence, candidates);
+    const retrievalEvidence = retrievalTrace(evidence, candidates);
+    const requestedDimensions = uniqueNormalizedTerms(evidence.parsedIntent?.dimensions ?? []);
+    const modeledFilterFields = new Set((evidence.parsedIntent?.filters ?? []).flatMap((filter) => candidates.some((candidate) => isCompatibleQualifiedMember(candidate)
+        && candidateIdentityTerms(candidate).some((term) => metricTermsMatch(term, normalizeMetricPhrase(filter.value))))
+        ? [normalizeMetricPhrase(filter.field)]
+        : []));
+    const missingDimensions = requestedDimensions.filter((requested) => !modeledFilterFields.has(requested)
+        && !candidates.some((candidate) => candidateProvesDimensionTerm(candidate, requested)));
+    if (missingDimensions.length > 0) {
+        const filterValues = (evidence.parsedIntent?.filters ?? []).map((filter) => normalizeMetricPhrase(filter.value));
+        const alternatives = candidates
+            .filter(isCompatibleQualifiedMember)
+            .filter((candidate) => candidateIsDeclaredDimensionAlternative(candidate, missingDimensions))
+            .filter((candidate) => !candidateIdentityTerms(candidate).some((term) => requestedDimensions.some((requested) => metricTermsMatch(term, requested))
+            || filterValues.some((value) => metricTermsMatch(term, value))))
+            .sort((left, right) => right.relevanceScore - left.relevanceScore || left.id.localeCompare(right.id))
+            .slice(0, 3);
+        if (alternatives.length === 0) {
+            if (!asksForRanking || hasExplicitRankingMetric)
+                return undefined;
+            return bareRankingClarification(base, retrievalEvidence, request.question, evidence, candidates);
+        }
+        const requestedLabel = missingDimensions.map((term) => `“${term}”`).join(' and ');
+        const alternativeLabels = alternatives.map(renderCandidateChoice);
+        return {
+            ...base,
+            action: 'clarify',
+            confidence: 1,
+            reason: `The requested dimension ${requestedLabel} is absent from the retrieved qualified evidence, so no analytical plan was frozen.`,
+            source: 'heuristic',
+            category: 'unclear',
+            depth: 'quick',
+            requiresClarification: true,
+            clarifyingQuestion: alternativeLabels.length > 0
+                ? `${requestedLabel} is not modeled. Should I use ${alternativeLabels.join(' or ')} instead?`
+                : `${requestedLabel} is not modeled. Which governed dimension should I use instead?`,
+            retrievalEvidence,
+            ...(alternatives.length > 0 ? { clarificationOptions: buildClarificationOptions(alternatives) } : {}),
+            resolvedAnalyticalPlan: undefined,
+            meaningResolution: undefined,
+        };
+    }
+    if (asksForRanking && !hasExplicitRankingMetric) {
+        return bareRankingClarification(base, retrievalEvidence, request.question, evidence, candidates);
+    }
+    return 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.
+ */
+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',
+        confidence: 1,
+        reason: 'A ranking needs a positively identified governed metric before an execution capability can be selected.',
+        source: 'heuristic',
+        category: 'unclear',
+        depth: 'quick',
+        requiresClarification: true,
+        clarifyingQuestion: 'Top by which governed metric?',
+        retrievalEvidence,
+        ...(rankingChoices.length > 0
+            ? { clarificationOptions: buildClarificationOptions(rankingChoices) }
+            : {}),
+        resolvedAnalyticalPlan: undefined,
+        meaningResolution: undefined,
     };
 }
+function uniqueNormalizedTerms(values) {
+    return [...new Set(values.map(normalizeMetricPhrase).filter(Boolean))];
+}
+function isCompatibleQualifiedMember(candidate) {
+    return candidate.kind === 'semantic_member'
+        && candidate.compatibility !== 'incompatible'
+        && Boolean(candidate.qualifiedId ?? candidate.id);
+}
+function candidateIdentityTerms(candidate) {
+    return uniqueNormalizedTerms([
+        candidate.id,
+        candidate.qualifiedId ?? '',
+        candidate.name,
+        ...(candidate.aliases ?? []),
+        ...(candidate.dimensions ?? []),
+    ]);
+}
+function candidateProvesDimensionTerm(candidate, requested) {
+    if (candidate.compatibility === 'incompatible')
+        return false;
+    if (candidate.kind === 'semantic_member'
+        && candidateIdentityTerms(candidate).some((term) => metricTermsMatch(term, requested)))
+        return true;
+    const normalized = normalizeEvidenceAnalyticalCapability(candidate);
+    return normalized.status === 'complete'
+        && Boolean(normalized.capability?.dimensions.some((dimension) => metricTermsMatch(normalizeMetricPhrase(dimension.dimensionId), requested)));
+}
+function candidateProvesMetricTerm(candidate, requested) {
+    if (candidate.compatibility === 'incompatible')
+        return false;
+    if (candidate.kind === 'certified_block') {
+        return candidate.compatibility === 'compatible';
+    }
+    if (candidate.kind !== 'semantic_metric')
+        return false;
+    const stableIdentity = candidate.qualifiedId ?? candidate.id;
+    if (!stableIdentity)
+        return false;
+    return [candidate.name, ...(candidate.aliases ?? [])]
+        .map(normalizeMetricPhrase)
+        .some((term) => metricTermsMatch(term, requested));
+}
+function candidateIsDeclaredDimensionAlternative(candidate, missingDimensions) {
+    const facts = candidate.compatibilityFacts?.map(normalizeMetricPhrase) ?? [];
+    return missingDimensions.some((requested) => facts.includes(`alternative for ${requested}`)
+        || facts.includes(`dimension alternative for ${requested}`));
+}
+/**
+ * A missing optional parsed-intent projection must not erase positive metric
+ * evidence already retrieved for the question. Only complete, compatible,
+ * qualified semantic metrics with an exact/explicit match reason can bypass
+ * the bare-ranking clarification; mere catalog presence is insufficient.
+ */
+function hasStrongQualifiedMetricEvidence(candidates) {
+    return candidates.some((candidate) => {
+        if (candidate.kind !== 'semantic_metric' || candidate.compatibility === 'incompatible')
+            return false;
+        if (!candidate.qualifiedId || !normalizeEvidenceAnalyticalCapability(candidate).capability)
+            return false;
+        if (candidate.exactMatch)
+            return true;
+        return candidate.matchReasons.some((reason) => {
+            const normalized = normalizeMetricPhrase(reason);
+            return /\b(?:exact|explicit)\b/.test(normalized)
+                && /\b(?:metric|measure|meaning|name|alias)\b/.test(normalized);
+        });
+    });
+}
+function hasQuestionQualifiedMetricEvidence(question, evidence, candidates) {
+    const questionTokens = new Set(substantiveLexicalTokens(question));
+    const dimensionTokens = new Set(substantiveLexicalTokens((evidence.parsedIntent?.dimensions ?? []).join(' ')));
+    return candidates.some((candidate) => {
+        if (candidate.kind !== 'semantic_metric' || candidate.compatibility === 'incompatible')
+            return false;
+        const normalized = normalizeEvidenceAnalyticalCapability(candidate);
+        if (normalized.status !== 'complete' || !candidate.qualifiedId)
+            return false;
+        return metricLexicalVariants(candidate).some((variant) => {
+            const metricTokens = [...new Set(substantiveLexicalTokens(variant)
+                    .filter((token) => !dimensionTokens.has(token)))];
+            if (metricTokens.length === 0)
+                return false;
+            const matched = metricTokens.filter((token) => questionTokens.has(token)).length;
+            return metricTokens.length === 1
+                ? matched === 1
+                : matched >= 2 && matched / metricTokens.length >= 0.5;
+        });
+    });
+}
+/**
+ * Compare both authored identities and their canonical local names. Generated
+ * semantic-model namespaces remain available as authored evidence, but cannot
+ * dilute the leaf metric phrase that users naturally ask for.
+ */
+function metricLexicalVariants(candidate) {
+    const authored = [
+        candidate.name,
+        ...(candidate.aliases ?? []),
+        ...(candidate.qualifiedId ? [candidate.qualifiedId] : []),
+    ].filter(Boolean);
+    return [...new Set(authored.flatMap((value) => {
+            const local = value.split(/[.:/]/).filter(Boolean).at(-1);
+            return local && local !== value ? [value, local] : [value];
+        }))];
+}
+const NON_SUBSTANTIVE_RANKING_TOKENS = new Set([
+    'a', 'an', 'and', 'are', 'at', 'best', 'bottom', 'by', 'count', 'for',
+    'from', 'give', 'has', 'have', 'highest', 'in', 'is', 'least', 'list',
+    'lowest', 'me', 'measure', 'metric', 'most', 'number', 'of', 'on', 'or',
+    'per', 'rank', 'ranked', 'ranking', 'show', 'that', 'the', 'this', 'to',
+    'top', 'total', 'value', 'what', 'which', 'who', 'with', 'without', 'worst',
+    'amount',
+]);
+function substantiveLexicalTokens(value) {
+    return normalizeMetricPhrase(value)
+        .split(' ')
+        .filter((token) => token.length >= 2 && !NON_SUBSTANTIVE_RANKING_TOKENS.has(token));
+}
+function renderCandidateChoice(candidate) {
+    const identity = candidate.qualifiedId ?? candidate.id;
+    const stableName = identity.split(/[.:]/).at(-1) ?? candidate.name;
+    // Never paste a raw semantic-layer record into the question a person reads.
+    const description = humanizeCandidateDefinition(candidate.definition);
+    const grain = candidate.primaryEntity?.trim();
+    const kind = candidateKindLabel(candidate.kind);
+    const detail = [description, grain ? `grain: ${grain}` : ''].filter(Boolean).join('; ');
+    return detail
+        ? `${candidate.name} — ${kind}, ${detail}`
+        : `${candidate.name} — ${kind} (${stableName})`;
+}
 /**
  * AGT-017 / AGT-018 / PERF-002 — provider failure must not send an otherwise
  * unambiguous semantic question back through the legacy answer cascade. A dbt
@@ -773,7 +1602,13 @@ function hasMateriallyRelatedCompetitor(exact, candidates) {
     const floor = Math.max(0.55, exact.relevanceScore - 0.2);
     return candidates.some((candidate) => candidate.id !== exact.id
         && candidate.compatibility !== "incompatible"
-        && candidate.relevanceScore >= floor);
+        && candidate.relevanceScore >= floor
+        // A dimension/member card can help bind the selected metric's tuple, but
+        // it is not a competing business metric meaning. Treating it as one sends
+        // an exact metric plus its own dimension candidates back to the resolver.
+        && (exact.kind !== 'semantic_metric'
+            || candidate.kind === 'semantic_metric'
+            || candidate.kind === 'certified_block'));
 }
 /**
  * Skip the meaning-model call only when host-owned fit checks have already
@@ -806,6 +1641,13 @@ function dominantCompatibleGovernedCandidate(candidates) {
     const hasExecutableCompetitor = compatible.some((candidate) => candidate.id !== best.id && candidate.relevanceScore >= competitorFloor);
     return hasExecutableCompetitor ? undefined : best;
 }
+function authoritativeExactCertifiedExample(candidates) {
+    const exact = candidates.filter((candidate) => candidate.kind === 'certified_block'
+        && candidate.exactMatch
+        && candidate.compatibility === 'compatible'
+        && candidate.analyticalFitClass === 'exact');
+    return exact.length === 1 ? exact[0] : undefined;
+}
 function shouldDeferCompositionalFollowUpToExecutor(base, candidates) {
     if (!base.followsUp)
         return false;
@@ -848,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; });
@@ -878,6 +1721,10 @@ export function createHybridRouter(options = {}) {
             if (base.action === "converse" || base.action === "compose_app") {
                 return { ...base, source: base.source ?? "heuristic" };
             }
+            const initialDiscoveryRoute = discoveryRouteBeforeRetrieval(request, base);
+            if (request.runBudget && !request.runBudget.mayStartDiscovery(initialDiscoveryRoute)) {
+                return softBoundaryDecision(request, base, initialDiscoveryRoute);
+            }
             let evidence;
             if (options.getEvidence) {
                 try {
@@ -890,38 +1737,93 @@ export function createHybridRouter(options = {}) {
                 }
             }
             if (evidence) {
+                evidence = {
+                    ...evidence,
+                    candidates: canonicalizeMetricMeasureCandidates(evidence.candidates),
+                    ...(evidence.clarificationCandidates
+                        ? { clarificationCandidates: canonicalizeMetricMeasureCandidates([
+                                ...evidence.candidates,
+                                ...evidence.clarificationCandidates,
+                            ]).filter((candidate) => evidence.clarificationCandidates.some((item) => item.id === candidate.id)) }
+                        : {}),
+                };
                 let candidates = buildMeaningEvidencePackage(evidence, options.maxMeaningCandidates ?? 12);
                 // 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)]
                         .slice(0, options.maxMeaningCandidates ?? 12);
                 }
                 if (candidates.length > 0) {
+                    // Clarification is local and never provider-bound, so it can inspect the
+                    // complete already-retrieved set. Keep the smaller package below for
+                    // any later meaning call.
+                    const clarificationCandidates = [
+                        ...evidence.candidates,
+                        ...(evidence.clarificationCandidates ?? []),
+                    ].filter((candidate, index, all) => candidate.eligible !== false && all.findIndex((other) => other.id === candidate.id) === index);
                     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 exactCompatible = candidates.filter((candidate) => candidate.exactMatch && candidate.compatibility !== "incompatible");
+                    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 = !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);
@@ -929,12 +1831,29 @@ export function createHybridRouter(options = {}) {
                     if (cached && (options.cacheTtlMs === undefined || now() - cached.at < cacheTtlMs)) {
                         return { ...cached.decision, source: "cache" };
                     }
+                    // Distinguish "the resolver could not run" from "the resolver ran and
+                    // froze nothing". Only the first is a reason to refuse to interpret:
+                    // with the semantic judgment unavailable, lexical rank alone must not
+                    // settle two genuinely different metrics (AGT-017). When the resolver
+                    // did run, committing to the best governed reading is the whole point.
+                    let meaningResolverReachable = true;
                     try {
+                        if (request.runBudget && !request.runBudget.mayStartDiscovery('clarify')) {
+                            return softBoundaryDecision(request, base, 'clarify');
+                        }
                         const resolution = options.resolveMeaning
                             ? await options.resolveMeaning({
                                 question: request.question,
                                 history: effectiveConversationHistory(request),
-                                evidence,
+                                // The resolver/provider receives the same bounded evidence
+                                // package as its candidate argument. Supplemental qualified
+                                // cards are a host-only clarification aid and must not leak
+                                // through this richer carrier.
+                                evidence: {
+                                    ...evidence,
+                                    candidates,
+                                    clarificationCandidates: undefined,
+                                },
                                 candidates,
                                 signal: request.signal ?? options.signal,
                             })
@@ -948,26 +1867,77 @@ 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,
                                 questionType: questionTypeFromText(request.question),
-                                selectedConceptIds: [],
-                                queryIntent: defaultQueryIntent(evidence),
+                                selectedConceptIds: resolution.selectedConceptIds,
+                                recommendedExecutionId: resolution.recommendedExecutionId,
+                                queryIntent: resolution.queryIntent,
                                 rejectedCandidates: [],
                                 confidence: "low",
                                 missingInformation: [validated.reason],
                                 recommendedRoute: "clarify",
-                                clarifyingQuestion: buildEvidenceClarification(candidates, [validated.reason]),
+                                compatibilityOutcome: 'modeling_gap',
+                                compatibilityFailures: [{
+                                        code: 'INVALID_EVIDENCE_REFERENCE',
+                                        field: 'meaningResolution',
+                                        message: validated.reason,
+                                        candidateIds: [],
+                                    }],
                             };
                             const invalidDecision = routeDecisionForResolution(base, evidence, candidates, invalidResolution, "llm", request.question, options.resolvedPlanMode ?? 'authoritative');
                             return remember(key, {
                                 ...invalidDecision,
-                                action: 'answer',
-                                requiresClarification: false,
-                                clarificationOptions: undefined,
-                                clarifyingQuestion: undefined,
                                 meaningResolutionErrorCode: 'invalid_evidence_reference',
                             });
                         }
@@ -976,8 +1946,17 @@ export function createHybridRouter(options = {}) {
                         rethrowCancellation(error, request.signal, options.signal);
                         // A resolver transport/parse failure falls back without losing the
                         // retrieval signal or permitting a general-knowledge misroute.
+                        meaningResolverReachable = false;
                     }
-                    return routeWithoutMeaningModel(request, base, evidence, candidates, options.resolvedPlanMode ?? 'authoritative');
+                    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;
@@ -987,6 +1966,9 @@ export function createHybridRouter(options = {}) {
                 return { ...base, source: base.source ?? "heuristic" };
             }
             let catalogContext;
+            if (request.runBudget && !request.runBudget.mayStartDiscovery('clarify')) {
+                return softBoundaryDecision(request, base, 'clarify');
+            }
             try {
                 catalogContext = options.getCatalogContext ? await options.getCatalogContext(request) : undefined;
             }
@@ -1017,5 +1999,30 @@ export function createHybridRouter(options = {}) {
         },
     };
 }
+function discoveryRouteBeforeRetrieval(request, base) {
+    if (request.runBudget?.mode === 'research' || request.requestedMode === 'research')
+        return 'research';
+    if (base.action === 'clarify' || base.requiresClarification || request.signals?.missingContext?.length)
+        return 'clarify';
+    if (request.intent === 'exact_certified_lookup'
+        || (request.signals?.certifiedScore ?? 0) >= 0.5
+        || (request.signals?.metricScore ?? 0) >= 0.5)
+        return 'semantic_answer';
+    return 'generated_answer';
+}
+function softBoundaryDecision(request, base, route) {
+    const seconds = Math.round((request.runBudget?.softTargetMs(route) ?? 15_000) / 1_000);
+    return {
+        ...base,
+        action: 'clarify',
+        confidence: 1,
+        source: 'heuristic',
+        requiresClarification: true,
+        reason: `The ${seconds}-second discovery target elapsed before a plan was frozen, so DQL did not start another retrieval or provider branch.`,
+        clarifyingQuestion: request.runBudget?.mode === 'research'
+            ? 'Research has stopped starting new branches. Would you like to narrow the question and retry?'
+            : 'The discovery window ended before an exact plan was frozen. Which metric or grain should DQL use on retry?',
+    };
+}
 export { intentForCategory, parseMeaningResolution };
 //# sourceMappingURL=router.js.map