@duckcodeailabs/dql-agent 1.13.4 → 1.14.0

package/dist/metadata/meaning-evidence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"meaning-evidence.d.ts","sourceRoot":"","sources":["../../src/metadata/meaning-evidence.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"meaning-evidence.d.ts","sourceRoot":"","sources":["../../src/metadata/meaning-evidence.ts"],"names":[],"mappings":"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"}

package/dist/metadata/meaning-evidence.js

@@ -40,6 +40,10 @@ export function buildMeaningEvidencePackage(question, questionPlan, ranked) {
     eligible.sort((left, right) => right.relevanceScore - left.relevanceScore
         || left.item.rank - right.item.rank
         || left.item.row.objectKey.localeCompare(right.item.row.objectKey));
+    const requiredSemanticMetricKey = questionPlan.requestedShape.measures.length > 0
+        ? eligible.find((candidate) => candidate.evidenceClass === 'semantic'
+            && candidate.item.row.objectType === 'semantic_metric')?.item.row.objectKey
+        : undefined;
     const selectedByClass = {
         certified: [], semantic: [], sql: [],
     };
@@ -47,6 +51,15 @@ export function buildMeaningEvidencePackage(question, questionPlan, ranked) {
     for (const candidate of eligible) {
         const lane = selectedByClass[candidate.evidenceClass];
         if (candidate.evidenceClass === 'semantic') {
+            // Dimensions and metrics share the semantic trust class. Preserve one
+            // retrieved metric for a measure-bearing question before member matches
+            // consume the bounded lane; deterministic compatibility still decides
+            // whether that metric is executable.
+            if (requiredSemanticMetricKey
+                && candidate.item.row.objectKey !== requiredSemanticMetricKey
+                && lane.length >= MAX_CANDIDATES_PER_CLASS - 1
+                && !lane.some((selectedCandidate) => selectedCandidate.item.row.objectKey === requiredSemanticMetricKey))
+                continue;
             const definitionKey = normalizeText(candidate.item.row.description ?? '');
             const meaningKey = definitionKey ? `${candidate.item.row.domain ?? ''}|${definitionKey}` : '';
             const existingIndex = meaningKey ? semanticMeaningIndexes.get(meaningKey) : undefined;
@@ -130,8 +143,28 @@ function attachRelationshipEvidence(candidates, contextObjects) {
     if (identitiesByEntity.size === 0)
         return;
     for (const candidate of candidates) {
+        for (const dimension of candidate.analyticalCapability?.dimensions ?? []) {
+            const pathRelationships = new Set(dimension.relationshipPathIds ?? []);
+            for (const reference of [dimension.entityId, ...(dimension.nativeGroupingPath ?? [])]) {
+                for (const alias of entityAliasesForRelationshipMatch(reference)) {
+                    for (const identity of identitiesByEntity.get(alias) ?? [])
+                        pathRelationships.add(identity);
+                }
+            }
+            if (pathRelationships.size > 0)
+                dimension.relationshipPathIds = [...pathRelationships].sort();
+        }
         const touched = new Set();
-        for (const reference of [candidate.primaryEntity, ...(candidate.sourceObjects ?? [])]) {
+        const capabilityPathEntities = candidate.analyticalCapability?.dimensions.flatMap((dimension) => [
+            dimension.entityId,
+            ...(dimension.nativeGroupingPath ?? []),
+        ]) ?? [];
+        for (const reference of [
+            candidate.primaryEntity,
+            candidate.analyticalCapability?.primaryEntityId,
+            ...capabilityPathEntities,
+            ...(candidate.sourceObjects ?? []),
+        ]) {
             if (!reference)
                 continue;
             for (const alias of entityAliasesForRelationshipMatch(reference)) {
@@ -150,10 +183,74 @@ function entityAliasesForRelationshipMatch(reference) {
 }
 export function toAgentRetrievalEvidence(evidence, questionPlan, options = {}) {
     const maxRelevance = Math.max(1, ...evidence.candidates.map((candidate) => candidate.relevanceScore));
-    const candidates = evidence.candidates.map((candidate) => ({
+    const candidates = evidence.candidates.map((candidate) => agentCandidateFromMeaning(candidate, maxRelevance));
+    const trustedBindings = trustedMemberBindingEvidence(questionPlan, candidates, options.contextObjects ?? []);
+    for (const member of trustedBindings.candidates) {
+        if (!candidates.some((candidate) => candidate.id === member.id))
+            candidates.push(member);
+    }
+    const clarificationCandidates = supplementalClarificationEvidence(questionPlan, options.contextObjects ?? [], candidates);
+    attachRelationshipEvidence(candidates, options.contextObjects ?? []);
+    attachRelationshipEvidence(clarificationCandidates, options.contextObjects ?? []);
+    // A member the reader named that survived NO grounding lane. Live value
+    // lookup is opt-in per project (`agent.runtimeValueGrounding`), so with it
+    // disabled "What customer type is Wesley Jenkins?" produced zero grounded
+    // filters and the run quietly returned every customer instead of saying it
+    // could not bind him.
+    const groundedFilters = [
+        ...trustedBindings.filters,
+        ...groundedMemberFilters(questionPlan, candidates, options.contextObjects ?? []),
+    ].filter((filter, index, all) => all.findIndex((other) => other.field === filter.field && other.value === filter.value) === index);
+    const groundedValues = new Set(groundedFilters.map((filter) => normalizeText(String(filter.value))));
+    const unboundCandidates = uniqueStrings((questionPlan.requestedShape.filters ?? [])
+        .filter((term) => term.trim().length > 0 && !groundedValues.has(normalizeText(term))));
+    // The planner emits stemmed variants beside the literal ("Wesley Jenkins" and
+    // "wesley jenkin"). Naming both back to the reader reads like two different
+    // missing values, so keep only the longest form of each.
+    const unboundMemberTerms = unboundCandidates.filter((term) => {
+        const normalized = normalizeText(term);
+        return !unboundCandidates.some((other) => {
+            const otherNormalized = normalizeText(other);
+            return otherNormalized !== normalized
+                && otherNormalized.length > normalized.length
+                && otherNormalized.startsWith(normalized);
+        });
+    });
+    return {
+        snapshotId: options.snapshotId,
+        sourceFingerprint: options.sourceFingerprint,
+        knowledgeLens: options.knowledgeLens,
+        analyticalPolicies: options.analyticalPolicies,
+        candidates,
+        ...(clarificationCandidates.length > 0 ? { clarificationCandidates } : {}),
+        ...(unboundMemberTerms.length > 0 ? { unboundMemberTerms } : {}),
+        parsedIntent: {
+            measures: questionPlan.requestedShape.measures,
+            dimensions: questionPlan.requestedShape.dimensions,
+            filters: groundedFilters,
+            ...(analysisTimeGrain(questionPlan)
+                ? { timeGrain: analysisTimeGrain(questionPlan) }
+                : {}),
+            ...(questionPlan.requestedShape.rankingDirection
+                ? { order: questionPlan.requestedShape.rankingDirection === 'top' ? 'desc' : 'asc' }
+                : {}),
+            ...(questionPlan.requestedShape.topN ? { limit: questionPlan.requestedShape.topN.n } : {}),
+        },
+        diagnostics: {
+            searchedKinds: [...new Set([...candidates, ...clarificationCandidates].map((candidate) => candidate.kind))],
+            durationMs: options.durationMs,
+            truncated: options.truncated ?? false,
+        },
+    };
+}
+function agentCandidateFromMeaning(candidate, maxRelevance = 1) {
+    return {
         id: candidate.objectKey,
         qualifiedId: candidate.qualifiedId,
         kind: agentEvidenceKind(candidate),
+        ...(semanticObjectType(candidate.objectType)
+            ? { semanticObjectType: semanticObjectType(candidate.objectType) }
+            : {}),
         trustTier: candidate.trustTier,
         name: candidate.name,
         aliases: candidate.aliases,
@@ -164,7 +261,7 @@ export function toAgentRetrievalEvidence(evidence, questionPlan, options = {}) {
         domain: candidate.domain,
         semanticModel: candidate.semanticModel,
         primaryEntity: candidate.businessShape.entities[0],
-        dimensions: candidate.businessShape.dimensions,
+        dimensions: dimensionLookupAliases(candidate.businessShape.dimensions),
         timeGrains: candidate.businessShape.timeGrains,
         requiredParameters: candidate.businessShape.parameters,
         sourceObjects: candidate.businessShape.sourceRelations,
@@ -177,34 +274,261 @@ export function toAgentRetrievalEvidence(evidence, questionPlan, options = {}) {
         analyticalCapability: candidate.analyticalCapability,
         eligible: true,
         exactMatch: candidate.relevanceReasons.includes("exact name or alias"),
-    }));
-    attachRelationshipEvidence(candidates, options.contextObjects ?? []);
-    const groundedFilters = groundedMemberFilters(questionPlan, candidates, options.contextObjects ?? []);
-    return {
-        snapshotId: options.snapshotId,
-        sourceFingerprint: options.sourceFingerprint,
-        knowledgeLens: options.knowledgeLens,
-        analyticalPolicies: options.analyticalPolicies,
-        candidates,
-        parsedIntent: {
-            measures: questionPlan.requestedShape.measures,
-            dimensions: questionPlan.requestedShape.dimensions,
-            filters: groundedFilters,
-            ...(analysisTimeGrain(questionPlan)
-                ? { timeGrain: analysisTimeGrain(questionPlan) }
-                : {}),
-            ...(questionPlan.requestedShape.rankingDirection
-                ? { order: questionPlan.requestedShape.rankingDirection === 'top' ? 'desc' : 'asc' }
-                : {}),
-            ...(questionPlan.requestedShape.topN ? { limit: questionPlan.requestedShape.topN.n } : {}),
-        },
-        diagnostics: {
-            searchedKinds: [...new Set(candidates.map((candidate) => candidate.kind))],
-            durationMs: options.durationMs,
-            truncated: options.truncated ?? false,
-        },
     };
 }
+function trustedMemberBindingEvidence(plan, candidates, objects) {
+    const dimensions = new Map();
+    for (const object of objects) {
+        if (object.objectType !== 'semantic_dimension')
+            continue;
+        const id = firstString(object.payload?.qualifiedId, object.fullName);
+        if (!id)
+            continue;
+        dimensions.set(normalizeText(object.name), { id, definition: object.description });
+        dimensions.set(normalizeDimensionRole(object.name), { id, definition: object.description });
+    }
+    for (const candidate of candidates) {
+        const capability = normalizeMetricCapabilityContract(candidate.analyticalCapability);
+        for (const dimension of capability?.dimensions ?? []) {
+            const value = { id: dimension.dimensionId, entityId: dimension.entityId };
+            dimensions.set(normalizeText(dimension.dimensionId), value);
+            dimensions.set(normalizeDimensionRole(dimension.dimensionId), value);
+        }
+        for (const dimensionId of candidate.dimensions ?? []) {
+            if (!/[:./]/.test(dimensionId))
+                continue;
+            const value = { id: dimensionId, entityId: normalizeDimensionRole(dimensionId) };
+            dimensions.set(normalizeText(dimensionId), value);
+            dimensions.set(normalizeDimensionRole(dimensionId), value);
+        }
+    }
+    const cards = [];
+    const filters = [];
+    for (const binding of plan.requestedShape.memberBindings ?? []) {
+        if (binding.source !== 'prior_result' && binding.source !== 'clarification')
+            continue;
+        // A deictic binding used to be discarded outright, which threw away the
+        // referent of every "this customer" follow-up and left the turn ungrounded.
+        // Cardinality is what matters: exactly one candidate is unambiguous and
+        // safe to bind; several must not be fanned into an OR'd filter, and are
+        // surfaced as a clarification instead.
+        if (binding.confidence === 'deictic' && binding.values.length !== 1)
+            continue;
+        const dimension = dimensions.get(normalizeText(binding.dimension))
+            ?? dimensions.get(normalizeDimensionRole(binding.dimension));
+        if (!dimension)
+            continue;
+        for (const value of binding.values) {
+            filters.push({ field: dimension.id, value });
+            const id = `semantic:member:${encodeURIComponent(dimension.id)}:${encodeURIComponent(normalizeText(value))}`;
+            cards.push({
+                id,
+                qualifiedId: id,
+                kind: 'semantic_member',
+                trustTier: 'semantic',
+                name: value,
+                aliases: [value],
+                definition: `Trusted ${binding.source.replace('_', ' ')} member for ${dimension.id}.`,
+                primaryEntity: dimension.entityId,
+                dimensions: [dimension.id],
+                relevanceScore: 1,
+                matchReasons: [`typed ${binding.source} member binding`],
+                compatibility: 'compatible',
+                eligible: true,
+                exactMatch: true,
+            });
+        }
+    }
+    return { candidates: cards, filters };
+}
+function supplementalClarificationEvidence(plan, objects, existing) {
+    const MAX_SUPPLEMENTAL_CANDIDATES = 12;
+    const MAX_PER_REQUESTED_ROLE = 3;
+    const existingIds = new Set(existing.map((candidate) => candidate.id));
+    const requestedMeasures = expandedRequestedTerms(plan.requestedShape.measures, objects);
+    const requestedDimensions = expandedRequestedTerms(plan.requestedShape.dimensions, objects);
+    const objectCards = objects.flatMap((object) => {
+        if (existingIds.has(object.objectKey))
+            return [];
+        if (!['semantic_metric', 'semantic_measure', 'semantic_dimension'].includes(object.objectType))
+            return [];
+        const names = aliasesFor(object).map(normalizeText);
+        const role = normalizeDimensionRole(object.name);
+        const relevant = object.objectType === 'semantic_metric' || object.objectType === 'semantic_measure'
+            ? requestedMeasures.some((term) => names.some((name) => phraseTermsMatch(term, name)))
+            : requestedDimensions.some((term) => names.some((name) => phraseTermsMatch(term, name))
+                || (isGeographicRole(term) && isGeographicRole(role)));
+        if (!relevant)
+            return [];
+        const card = candidateCard(object, 'semantic', 1, 1, aliasesFor(object), ['requested clarification capability'], []);
+        return [agentCandidateFromMeaning(card)];
+    });
+    const declaredDimensionCards = existing.flatMap((candidate) => (candidate.dimensions ?? []).flatMap((dimensionId) => {
+        if (!/[:./]/.test(dimensionId) || existingIds.has(dimensionId))
+            return [];
+        const role = normalizeDimensionRole(dimensionId);
+        const relevant = requestedDimensions.some((term) => phraseTermsMatch(term, role) || (isGeographicRole(term) && isGeographicRole(role)));
+        if (!relevant)
+            return [];
+        return [{
+                id: dimensionId,
+                qualifiedId: dimensionId,
+                kind: 'semantic_member',
+                trustTier: 'semantic',
+                name: dimensionId.split(/[.:/]/).at(-1) ?? dimensionId,
+                aliases: [role],
+                definition: `Modeled ${role} dimension available through ${candidate.name}.`,
+                primaryEntity: candidate.primaryEntity,
+                dimensions: [dimensionId],
+                relevanceScore: candidate.relevanceScore,
+                matchReasons: ['requested clarification capability role'],
+                compatibility: 'partial',
+                eligible: true,
+                exactMatch: false,
+            }];
+    }));
+    // A bare ranking ("who are the top customers") names an ENTITY and no
+    // measure, so every lane above — each keyed on a REQUESTED measure or
+    // dimension term — returns nothing, and the clarification has no choices to
+    // offer. Surface the governed measures that can actually order that entity.
+    const rankingMeasureCards = (() => {
+        if (!plan.requestedShape.rankingDirection)
+            return [];
+        if (requestedMeasures.length > 0)
+            return [];
+        const entityTerms = requestedDimensions;
+        if (entityTerms.length === 0)
+            return [];
+        return objects.flatMap((object) => {
+            if (existingIds.has(object.objectKey))
+                return [];
+            if (!['semantic_metric', 'semantic_measure'].includes(object.objectType))
+                return [];
+            const card = agentCandidateFromMeaning(candidateCard(object, 'semantic', 1, 1, aliasesFor(object), ['ranking measure for the requested entity'], []));
+            // It must be reportable at the ranked entity's grain. `semanticModel`
+            // covers a measure that declares its model but no dimension list.
+            const grainTerms = [
+                card.primaryEntity ?? '',
+                card.semanticModel ?? '',
+                ...(card.dimensions ?? []),
+            ].map(normalizeText).filter(Boolean);
+            if (!entityTerms.some((term) => grainTerms.some((grain) => grainTermsMatch(term, grain))))
+                return [];
+            // A count of the ranked entity gives every row the same score.
+            const aggregation = normalizeText(card.aggregation ?? '');
+            const candidateNames = [card.name, ...(card.aliases ?? [])].map(normalizeText);
+            if (/count/.test(aggregation)
+                && entityTerms.some((term) => candidateNames.some((name) => grainTermsMatch(term, name))))
+                return [];
+            // The registry emits a bare alias node beside the entity-qualified metric
+            // (`semantic:metric:revenue` next to `semantic:metric:order_item.revenue`).
+            // The alias carries no aggregation, grain, or prose — only a raw dbt
+            // unique_id as its description — so it can never be proven compatible and
+            // must not take a choice slot from the node that can.
+            if (!card.aggregation)
+                return [];
+            return [card];
+        }).sort((left, right) => right.relevanceScore - left.relevanceScore || left.id.localeCompare(right.id));
+    })();
+    const unique = [...objectCards, ...declaredDimensionCards, ...rankingMeasureCards]
+        .filter((candidate, index, all) => all.findIndex((other) => (other.qualifiedId ?? other.id) === (candidate.qualifiedId ?? candidate.id)) === index);
+    const roleLanes = [
+        ...requestedDimensions.map((term) => ({ kind: 'dimension', term })),
+        ...requestedMeasures.map((term) => ({ kind: 'metric', term })),
+    ];
+    const selected = [];
+    // The ranking lane has no requested term to match on — that absence is the
+    // whole reason it exists — so it seeds the selection directly.
+    for (const candidate of rankingMeasureCards.slice(0, MAX_PER_REQUESTED_ROLE)) {
+        if (!selected.some((item) => (item.qualifiedId ?? item.id) === (candidate.qualifiedId ?? candidate.id))) {
+            selected.push(candidate);
+        }
+    }
+    for (const lane of roleLanes) {
+        const matches = unique.filter((candidate) => {
+            const candidateTerms = [candidate.name, ...(candidate.aliases ?? [])].map(normalizeText);
+            if (lane.kind === 'metric') {
+                return candidate.kind === 'semantic_metric'
+                    && candidateTerms.some((term) => phraseTermsMatch(lane.term, term));
+            }
+            if (candidate.kind !== 'semantic_member')
+                return false;
+            return candidateTerms.some((term) => phraseTermsMatch(lane.term, term))
+                || (isGeographicRole(lane.term) && candidateTerms.some(isGeographicRole));
+        }).sort((left, right) => right.relevanceScore - left.relevanceScore || left.id.localeCompare(right.id));
+        for (const candidate of matches.slice(0, MAX_PER_REQUESTED_ROLE)) {
+            if (!selected.some((item) => (item.qualifiedId ?? item.id) === (candidate.qualifiedId ?? candidate.id))) {
+                selected.push(candidate);
+            }
+        }
+    }
+    return selected.slice(0, MAX_SUPPLEMENTAL_CANDIDATES);
+}
+function expandedRequestedTerms(terms, objects) {
+    const vocabulary = new Map();
+    for (const object of objects) {
+        if (object.objectType !== 'dql_term')
+            continue;
+        const words = [object.name, ...stringArray(object.payload?.synonyms)].map(normalizeText).filter(Boolean);
+        for (const word of words) {
+            const peers = vocabulary.get(word) ?? new Set();
+            for (const peer of words)
+                peers.add(peer);
+            vocabulary.set(word, peers);
+        }
+    }
+    const expanded = new Set();
+    for (const term of terms.map(normalizeText)) {
+        expanded.add(term);
+        const tokens = term.split(' ');
+        tokens.forEach((token, index) => {
+            for (const peer of vocabulary.get(token) ?? []) {
+                expanded.add(tokens.map((value, tokenIndex) => tokenIndex === index ? peer : value).join(' '));
+            }
+        });
+    }
+    return [...expanded];
+}
+function phraseTermsMatch(left, right) {
+    return left === right || left.endsWith(` ${right}`) || right.endsWith(` ${left}`);
+}
+/**
+ * Grain comparison for the ranking-measure lane only.
+ *
+ * A measure frequently declares the MODEL it lives on ("customers") where the
+ * question names the ENTITY ("customer"), and a plain term match misses that by
+ * one character. This stays local to grain matching rather than loosening
+ * `phraseTermsMatch`, which decides identity elsewhere.
+ */
+function grainTermsMatch(entityTerm, grainTerm) {
+    if (phraseTermsMatch(entityTerm, grainTerm))
+        return true;
+    const singular = (value) => value.replace(/ies$/, 'y').replace(/s$/, '');
+    return phraseTermsMatch(singular(entityTerm), singular(grainTerm));
+}
+function normalizeDimensionRole(value) {
+    const leaf = value.split(/[.:/]/).at(-1) ?? value;
+    const normalized = normalizeText(leaf);
+    if (/^customer(?: name| id| key| label)?$/.test(normalized))
+        return 'customer';
+    if (/^location(?: name| id| key| label)?$/.test(normalized))
+        return 'location';
+    if (/^region(?: name| id| key| label)?$/.test(normalized))
+        return 'region';
+    if (/^product(?: name| id| key| label)?$/.test(normalized))
+        return 'product';
+    return normalized;
+}
+function dimensionLookupAliases(dimensions) {
+    return uniqueStrings(dimensions.flatMap((dimension) => {
+        const leaf = dimension.split(/[.:/]/).at(-1) ?? dimension;
+        const role = leaf.replace(/(?:_name|_id|_key|_label)$/i, '');
+        return role && role !== leaf ? [dimension, role] : [dimension];
+    }));
+}
+function isGeographicRole(value) {
+    return /^(?:region|location|geography|territory|market|site|store)$/.test(normalizeDimensionRole(value));
+}
 /**
  * Bind current-turn values only when an authorized runtime-value observation
  * and a semantic dimension's exact physical table/column identity agree. Text
@@ -303,16 +627,28 @@ function normalizeIdentifier(value) {
  */
 export function applyContextPackCompatibility(evidence, pack, selectedEvidenceId) {
     const certifiedFits = new Map(pack.retrievalDiagnostics.certifiedCandidateFits.map((fit) => [fit.objectKey, fit]));
-    const semanticEvidence = new Set(pack.routeDecision.selectedEvidence
-        .filter((item) => item.role === 'semantic_metric')
-        .map((item) => item.objectKey));
     return {
         ...evidence,
         candidates: evidence.candidates.map((candidate) => {
             if (candidate.kind === 'certified_block') {
                 const fit = certifiedFits.get(candidate.id);
+                const unrequestedStaticScope = fit?.fit.reasons.some((reason) => reason.startsWith('certified static scope is not requested:')) ?? false;
+                const exactAuthoredExample = fit?.action === 'certified_answer'
+                    && pack.routeDecision.exactObjectKey === candidate.id
+                    && fit.fit.reasons.includes('question matches a certified example');
                 return {
                     ...candidate,
+                    // Lexical equality to a block name/alias is useful retrieval signal,
+                    // but it is not exact analytical authority. Only the selected block's
+                    // authored exact-example fit may grant the router shortcut.
+                    exactMatch: exactAuthoredExample,
+                    ...(exactAuthoredExample
+                        ? { analyticalFitClass: 'exact' }
+                        : { analyticalFitClass: undefined }),
+                    // A statically scoped certified artifact is not an alternative for a
+                    // broader question. Exclude it before both meaning resolution and
+                    // identifier-bound clarification; later fit rejection is too late.
+                    eligible: unrequestedStaticScope ? false : candidate.eligible,
                     compatibility: fit?.action === 'certified_answer'
                         ? 'compatible'
                         : fit?.action === 'rejected_for_fit'
@@ -321,7 +657,7 @@ export function applyContextPackCompatibility(evidence, pack, selectedEvidenceId
                 };
             }
             if ((candidate.kind === 'semantic_metric' || candidate.kind === 'semantic_member')
-                && (semanticEvidence.has(candidate.id) || selectedEvidenceId === candidate.id)
+                && (Boolean(candidate.analyticalCapability) || selectedEvidenceId === candidate.id)
                 && (selectedEvidenceId === candidate.id
                     || (pack.routeDecision.route !== 'clarify' && pack.routeDecision.route !== 'conflict'))) {
                 const requestedDimensions = pack.questionPlan.requestedShape.dimensions.map((dimension) => normalizeText(dimension));
@@ -330,7 +666,10 @@ export function applyContextPackCompatibility(evidence, pack, selectedEvidenceId
                 const requestedTimeGrain = analysisTimeGrain(pack.questionPlan);
                 const availableTimeGrains = (candidate.timeGrains ?? []).map((grain) => grain.toLowerCase());
                 const timeGrainFits = !requestedTimeGrain || availableTimeGrains.includes(requestedTimeGrain);
-                return { ...candidate, compatibility: dimensionsFit && timeGrainFits ? 'compatible' : 'partial' };
+                const requestedMeasures = pack.questionPlan.requestedShape.measures.map((measure) => normalizeText(measure));
+                const metricPhrases = [candidate.name, ...(candidate.aliases ?? [])].map((value) => normalizeText(value));
+                const measuresFit = requestedMeasures.length === 0 || requestedMeasures.every((measure) => metricPhrases.some((phrase) => phrase === measure || phrase.includes(measure)));
+                return { ...candidate, compatibility: dimensionsFit && timeGrainFits && measuresFit ? 'compatible' : 'partial' };
             }
             if (candidate.trustTier === 'governed_sql')
                 return { ...candidate, compatibility: 'partial' };
@@ -450,6 +789,21 @@ function agentEvidenceKind(candidate) {
         return 'sql_column';
     return 'sql_table';
 }
+function semanticObjectType(objectType) {
+    if (objectType === 'semantic_metric')
+        return 'metric';
+    if (objectType === 'semantic_measure')
+        return 'measure';
+    if (objectType === 'semantic_dimension')
+        return 'dimension';
+    if (objectType === 'semantic_entity')
+        return 'entity';
+    if (objectType === 'semantic_model')
+        return 'model';
+    if (objectType === 'semantic_saved_query')
+        return 'saved_query';
+    return undefined;
+}
 function aliasesFor(object) {
     const payload = object.payload ?? {};
     return uniqueStrings([
@@ -467,7 +821,7 @@ function lexicalRelevance(normalizedQuestion, questionTokens, object, aliases) {
     const normalizedAliases = aliases.map(normalizeText).filter(Boolean);
     const reasons = [];
     let score = 0;
-    if (normalizedAliases.some((alias) => alias === normalizedQuestion)) {
+    if (normalizedAliases.some((alias) => isExactAnalyticalPhrase(normalizedQuestion, alias))) {
         score += 80;
         reasons.push('exact name or alias');
     }
@@ -525,7 +879,25 @@ function addPeer(peers, key, peer) {
     peers.set(key, values);
 }
 function normalizeText(value) {
-    return value.toLowerCase().replace(/[_./:-]+/g, ' ').replace(/[^a-z0-9 ]+/g, ' ').replace(/\s+/g, ' ').trim();
+    return value.toLowerCase()
+        .replace(/%/g, ' percentage ')
+        .replace(/[_./:-]+/g, ' ')
+        .replace(/[^a-z0-9 ]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function isExactAnalyticalPhrase(question, alias) {
+    if (!alias)
+        return false;
+    if (alias === question)
+        return true;
+    const index = question.indexOf(alias);
+    if (index < 0)
+        return false;
+    const remaining = `${question.slice(0, index)} ${question.slice(index + alias.length)}`
+        .replace(/\s+/g, ' ')
+        .trim();
+    return remaining.length === 0 || remaining.split(' ').every((token) => ['a', 'an', 'are', 'can', 'could', 'do', 'does', 'for', 'give', 'is', 'me', 'of', 'please', 'show', 'tell', 'the', 'what', 'which'].includes(token));
 }
 function tokenSet(value) {
     return new Set(value.split(/\s+/).filter((token) => token.length >= 2));