@duckcodeailabs/dql-agent 1.13.3 → 1.13.5

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"
@@ -594,20 +794,43 @@ function buildEvidenceClarification(candidates, missing = []) {
     return "Which governed business meaning should I use for this question?";
 }
 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 +846,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 +875,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,7 +916,16 @@ 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);
@@ -700,22 +939,354 @@ function routeWithoutMeaningModel(request, base, evidence, candidates, planMode
     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, candidates)
+        : 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));
+    const wantsAttribute = /\b(names?|labels?|titles?|descriptions?)\b/i.test(question);
+    const hasDimension = byScore.some((candidate) => candidate.semanticObjectType === 'dimension');
+    const kindFiltered = wantsAttribute && hasDimension
+        ? byScore.filter((candidate) => candidate.semanticObjectType !== 'entity')
+        : byScore;
+    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);
+        }
+    }
+    return [...passthrough, ...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);
+        }
+        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);
+    }
+    return undefined;
+}
+function bareRankingClarification(base, retrievalEvidence) {
+    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,
+        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 +1344,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 +1383,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;
@@ -878,6 +1462,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,6 +1478,16 @@ 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
@@ -902,6 +1500,16 @@ export function createHybridRouter(options = {}) {
                         .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 deterministicClarification = deterministicPrePlanClarification(request, base, evidence, clarificationCandidates);
+                    if (deterministicClarification)
+                        return deterministicClarification;
                     const explicit = selectedEvidence ?? findExplicitEvidenceReference(request.question, candidates);
                     if (explicit && explicit.compatibility !== "incompatible") {
                         const decision = routeDecisionForResolution(base, evidence, candidates, directResolution(request, evidence, explicit, candidates), "heuristic", request.question, options.resolvedPlanMode ?? 'authoritative');
@@ -913,6 +1521,10 @@ export function createHybridRouter(options = {}) {
                     if (multiMetricPrimary) {
                         return routeDecisionForResolution(base, evidence, candidates, directResolution(request, evidence, multiMetricPrimary, candidates), "heuristic", request.question, options.resolvedPlanMode ?? 'authoritative');
                     }
+                    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");
                     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');
@@ -929,12 +1541,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,
                             })
@@ -953,21 +1582,24 @@ export function createHybridRouter(options = {}) {
                             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 +1608,9 @@ 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');
+                    return routeWithoutMeaningModel(request, base, evidence, candidates, options.resolvedPlanMode ?? 'authoritative', meaningResolverReachable);
                 }
             }
             // Legacy/no-evidence path. A confident analytical heuristic stays offline;
@@ -987,6 +1620,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 +1653,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