@duckcodeailabs/dql-agent 1.14.2 → 1.14.4

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

@@ -1,6 +1,6 @@
 import { type AnalysisQuestionPlan } from "./analysis-planner.js";
 import { type AnalyticalPolicyContract, type MetricCapabilityContract } from "@duckcodeailabs/dql-core";
-import type { LocalContextPack, MetadataObject } from "./catalog.js";
+import type { LocalContextPack, MetadataObject, MetadataRetrievalLaneResult } from "./catalog.js";
 import { type AgentRetrievalEvidence, type AgentRelationshipSafetyEvidence } from '../meaning-resolution.js';
 import type { KnowledgeLens } from '../domain-context.js';
 export type MetadataEvidenceClass = 'certified' | 'semantic' | 'sql';
@@ -20,6 +20,10 @@ export interface MetadataMeaningCandidate {
     definition?: string;
     formula?: string;
     semanticModel?: string;
+    /** Immutable semantic compiler field identity, not a provider-facing alias. */
+    semanticRuntimeName?: string;
+    /** Source-authored semantic/member or physical column type. */
+    dataType?: string;
     relevanceReasons: string[];
     compatibilityFacts: string[];
     businessShape: {
@@ -38,6 +42,11 @@ export interface MetadataMeaningCandidate {
     /** Structured relationship facts when this card itself is a relationship. */
     relationshipSafety?: AgentRelationshipSafetyEvidence[];
     provenance?: string;
+    /** Actual snapshot retrieval memberships; never inferred from a display name. */
+    retrievalLanes?: Array<{
+        lane: 'exact' | 'lexical' | 'vector' | 'graph' | 'conversation';
+        rank?: number;
+    }>;
     ambiguityPeerIds: string[];
 }
 export interface MetadataMeaningEvidencePackage {
@@ -49,6 +58,15 @@ export interface MetadataMeaningEvidencePackage {
      * role-balanced.
      */
     qualifiedCandidates?: MetadataMeaningCandidate[];
+    /**
+     * The one broad, immutable retrieval snapshot retained by an Ask host before
+     * it makes its own 32-item workspace and 16-card planner package.  This is
+     * deliberately larger than `qualifiedCandidates`: a relevance-only first
+     * cut must not erase a physical product/order relation before role-balanced
+     * admission has a chance to reserve it.  It is not a provider package and
+     * callers must still make a bounded, auditable admission decision.
+     */
+    snapshotCandidates?: MetadataMeaningCandidate[];
     byEvidenceClass: Record<MetadataEvidenceClass, MetadataMeaningCandidate[]>;
     ambiguousGroups: Array<{
         candidateIds: string[];
@@ -65,6 +83,14 @@ export interface AgentRetrievalEvidenceAdapterOptions {
     analyticalPolicies?: AnalyticalPolicyContract[];
     /** Same immutable context-pack objects used to prove member/value bindings. */
     contextObjects?: MetadataObject[];
+    /** Snapshot retrieval results used to preserve multi-lane provenance. */
+    retrievalLanes?: MetadataRetrievalLaneResult[];
+    /**
+     * Ask Analyst Runtime consumes the broad immutable snapshot and performs
+     * its own role-balanced 32/16 admission.  Legacy callers retain the compact
+     * qualified package by default.
+     */
+    preferSnapshotCandidates?: boolean;
 }
 export interface MeaningEvidenceInputCandidate {
     row: MetadataObject;
@@ -78,7 +104,7 @@ export interface MeaningEvidenceInputCandidate {
  * intentionally remain separate: certification labels an execution lane but
  * never makes an unrelated candidate more relevant to the question.
  */
-export declare function buildMeaningEvidencePackage(question: string, questionPlan: AnalysisQuestionPlan, ranked: MeaningEvidenceInputCandidate[]): MetadataMeaningEvidencePackage;
+export declare function buildMeaningEvidencePackage(question: string, questionPlan: AnalysisQuestionPlan, ranked: MeaningEvidenceInputCandidate[], retrievalLanes?: MetadataRetrievalLaneResult[]): MetadataMeaningEvidencePackage;
 export declare function toAgentRetrievalEvidence(evidence: MetadataMeaningEvidencePackage, questionPlan: AnalysisQuestionPlan, options?: AgentRetrievalEvidenceAdapterOptions): AgentRetrievalEvidence;
 /**
  * One host-neutral compatibility projection shared by CLI, Browser Ask, MCP,

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

@@ -1,6 +1,6 @@
 import { scoreMetadataObjectWithAnalysisPlan, } from "./analysis-planner.js";
 import { normalizeMetricCapabilityContract, } from "@duckcodeailabs/dql-core";
-import { candidateMatchesCategoricalDimensionRequirement } from '../analytical-orchestration.js';
+import { candidateMatchesCategoricalDimensionRequirement, categoricalDimensionTermsMatch, } from '../analytical-orchestration.js';
 import { certifiedCandidateExplicitlyCoversMeasures, } from '../meaning-resolution.js';
 const GENERIC_MEANING_TOKENS = new Set([
     'amount', 'value', 'metric', 'measure', 'total', 'overall', 'monthly', 'daily',
@@ -8,13 +8,15 @@ const GENERIC_MEANING_TOKENS = new Set([
 ]);
 const MAX_CANDIDATES_PER_CLASS = 4;
 const MAX_QUALIFIED_CANDIDATES = 32;
+const MAX_SNAPSHOT_CANDIDATES = 80;
 const ANALYTICAL_TIME_GRAINS = new Set(['day', 'week', 'month', 'quarter', 'year', 'season', 'period']);
 /**
  * Produce compact meaning-rich cards for an AI resolver. Relevance and trust
  * intentionally remain separate: certification labels an execution lane but
  * never makes an unrelated candidate more relevant to the question.
  */
-export function buildMeaningEvidencePackage(question, questionPlan, ranked) {
+export function buildMeaningEvidencePackage(question, questionPlan, ranked, retrievalLanes = []) {
+    const laneMembership = laneMembershipByObjectKey(retrievalLanes);
     const questionText = normalizeText(question);
     const questionTokens = tokenSet(questionText);
     const eligible = ranked.flatMap((item) => {
@@ -43,14 +45,20 @@ 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 qualifiedPeerMap = buildAmbiguityPeers(eligible.slice(0, MAX_QUALIFIED_CANDIDATES).map((candidate) => ({
+    const snapshotEligible = eligible.slice(0, MAX_SNAPSHOT_CANDIDATES);
+    const qualifiedPeerMap = buildAmbiguityPeers(snapshotEligible.map((candidate) => ({
         objectKey: candidate.item.row.objectKey,
         aliases: candidate.aliases,
     })));
+    const snapshotCounts = { certified: 0, semantic: 0, sql: 0 };
+    const snapshotCandidates = snapshotEligible.map((candidate) => {
+        snapshotCounts[candidate.evidenceClass] += 1;
+        return candidateCard(candidate.item.row, candidate.evidenceClass, snapshotCounts[candidate.evidenceClass], candidate.relevanceScore, candidate.aliases, candidate.relevanceReasons, qualifiedPeerMap.get(candidate.item.row.objectKey) ?? [], laneMembership.get(candidate.item.row.objectKey));
+    });
     const qualifiedCounts = { certified: 0, semantic: 0, sql: 0 };
-    const qualifiedCandidates = eligible.slice(0, MAX_QUALIFIED_CANDIDATES).map((candidate) => {
+    const qualifiedCandidates = snapshotEligible.slice(0, MAX_QUALIFIED_CANDIDATES).map((candidate) => {
         qualifiedCounts[candidate.evidenceClass] += 1;
-        return candidateCard(candidate.item.row, candidate.evidenceClass, qualifiedCounts[candidate.evidenceClass], candidate.relevanceScore, candidate.aliases, candidate.relevanceReasons, qualifiedPeerMap.get(candidate.item.row.objectKey) ?? []);
+        return candidateCard(candidate.item.row, candidate.evidenceClass, qualifiedCounts[candidate.evidenceClass], candidate.relevanceScore, candidate.aliases, candidate.relevanceReasons, qualifiedPeerMap.get(candidate.item.row.objectKey) ?? [], laneMembership.get(candidate.item.row.objectKey));
     });
     const requiredSemanticMetricKey = questionPlan.requestedShape.measures.length > 0
         ? eligible.find((candidate) => candidate.evidenceClass === 'semantic'
@@ -103,12 +111,13 @@ export function buildMeaningEvidencePackage(question, questionPlan, ranked) {
     };
     for (const candidate of selected) {
         const lane = byEvidenceClass[candidate.evidenceClass];
-        lane.push(candidateCard(candidate.item.row, candidate.evidenceClass, lane.length + 1, candidate.relevanceScore, candidate.aliases, candidate.relevanceReasons, peerMap.get(candidate.item.row.objectKey) ?? []));
+        lane.push(candidateCard(candidate.item.row, candidate.evidenceClass, lane.length + 1, candidate.relevanceScore, candidate.aliases, candidate.relevanceReasons, peerMap.get(candidate.item.row.objectKey) ?? [], laneMembership.get(candidate.item.row.objectKey)));
     }
     return {
         candidates: ['certified', 'semantic', 'sql']
             .flatMap((evidenceClass) => byEvidenceClass[evidenceClass]),
         qualifiedCandidates,
+        snapshotCandidates,
         byEvidenceClass,
         ambiguousGroups: ambiguityGroups(peerMap),
     };
@@ -371,11 +380,18 @@ function attachRelationshipEvidence(candidates, contextObjects) {
     }
 }
 export function toAgentRetrievalEvidence(evidence, questionPlan, options = {}) {
-    const sourceCandidates = evidence.qualifiedCandidates?.length
-        ? evidence.qualifiedCandidates
-        : evidence.candidates;
+    const sourceCandidates = options.preferSnapshotCandidates && evidence.snapshotCandidates?.length
+        ? evidence.snapshotCandidates
+        : evidence.qualifiedCandidates?.length
+            ? evidence.qualifiedCandidates
+            : evidence.candidates;
     const maxRelevance = Math.max(1, ...sourceCandidates.map((candidate) => candidate.relevanceScore));
-    const candidates = sourceCandidates.map((candidate) => agentCandidateFromMeaning(candidate, maxRelevance));
+    const optionLaneMembership = laneMembershipByObjectKey(options.retrievalLanes ?? []);
+    const candidates = sourceCandidates.map((candidate) => agentCandidateFromMeaning(candidate, maxRelevance, candidate.retrievalLanes ?? optionLaneMembership.get(candidate.objectKey)));
+    // Keep runtime-value proof attached to the exact qualified physical column
+    // that owns it. The provider never receives these values; the Ask compiler
+    // can use them only after a planner has selected that categorical field.
+    attachSafeValueEvidence(candidates, options.contextObjects ?? []);
     const trustedBindings = trustedMemberBindingEvidence(questionPlan, candidates, options.contextObjects ?? []);
     for (const member of trustedBindings.candidates) {
         if (!candidates.some((candidate) => candidate.id === member.id))
@@ -435,7 +451,7 @@ export function toAgentRetrievalEvidence(evidence, questionPlan, options = {}) {
         },
     };
 }
-function agentCandidateFromMeaning(candidate, maxRelevance = 1) {
+function agentCandidateFromMeaning(candidate, maxRelevance = 1, retrievalLanes) {
     return {
         id: candidate.objectKey,
         qualifiedId: candidate.qualifiedId,
@@ -452,6 +468,8 @@ function agentCandidateFromMeaning(candidate, maxRelevance = 1) {
         provenance: candidate.provenance,
         domain: candidate.domain,
         semanticModel: candidate.semanticModel,
+        ...(candidate.semanticRuntimeName ? { semanticRuntimeName: candidate.semanticRuntimeName } : {}),
+        dataType: candidate.dataType,
         primaryEntity: candidate.businessShape.entities[0],
         dimensions: dimensionLookupAliases(candidate.businessShape.dimensions),
         timeGrains: candidate.businessShape.timeGrains,
@@ -467,8 +485,73 @@ function agentCandidateFromMeaning(candidate, maxRelevance = 1) {
         analyticalCapability: candidate.analyticalCapability,
         eligible: true,
         exactMatch: candidate.relevanceReasons.includes("exact name or alias"),
+        ...(retrievalLanes?.length ? { retrievalLanes } : {}),
     };
 }
+/**
+ * Attach a bounded, snapshot-local runtime-value observation to its qualified
+ * physical column.  This is stricter than lexical matching: both the physical
+ * relation and the terminal column must agree.  It lets a later deterministic
+ * compiler bind `in Philadelphia` to one selected SQL column without making
+ * the literal or a source-table guess visible to the planner.
+ */
+function attachSafeValueEvidence(candidates, objects) {
+    const values = objects.flatMap((object) => {
+        if (object.objectType !== 'runtime_value')
+            return [];
+        const relation = firstString(object.payload?.relation);
+        const column = firstString(object.payload?.column);
+        const value = firstString(object.payload?.value);
+        const normalizedValue = firstString(object.payload?.normalizedValue)
+            ?? (value ? normalizeText(value) : undefined);
+        if (!relation || !column || !value || !normalizedValue)
+            return [];
+        return [{ version: 1, relation, column, value, normalizedValue }];
+    });
+    if (values.length === 0)
+        return;
+    for (const candidate of candidates) {
+        if (candidate.kind !== 'sql_column')
+            continue;
+        const matching = values.filter((value) => physicalCandidateColumnMatches(candidate, value.column)
+            && physicalCandidateRelationMatches(candidate, value.relation));
+        if (matching.length === 0)
+            continue;
+        const deduped = new Map();
+        for (const value of matching) {
+            const key = [
+                canonicalPhysicalRelation(value.relation),
+                normalizeIdentifier(value.column),
+                normalizeText(value.normalizedValue),
+            ].join('|');
+            if (!deduped.has(key))
+                deduped.set(key, value);
+        }
+        candidate.safeValueEvidence = [...deduped.values()]
+            .sort((left, right) => left.relation.localeCompare(right.relation)
+            || left.column.localeCompare(right.column)
+            || left.normalizedValue.localeCompare(right.normalizedValue));
+    }
+}
+function physicalCandidateColumnMatches(candidate, column) {
+    const expected = normalizeIdentifier(column);
+    return [candidate.name, ...(candidate.aliases ?? [])]
+        .some((value) => normalizeIdentifier(value) === expected);
+}
+function physicalCandidateRelationMatches(candidate, relation) {
+    const expected = canonicalPhysicalRelation(relation);
+    // A qualified physical source relation is mandatory. Do not infer one from
+    // a display name or a loose candidate ID, because that would allow a value
+    // observation from another table to authorize a filter.
+    return (candidate.sourceObjects ?? []).some((source) => {
+        const actual = canonicalPhysicalRelation(source);
+        return actual === expected || actual.endsWith(`.${expected}`) || expected.endsWith(`.${actual}`);
+    });
+}
+function canonicalPhysicalRelation(value) {
+    return normalizeRelation(value)
+        .replace(/^(?:runtime:relation:|dbt:model:|dbt:source:|sql:table:)/, '');
+}
 function trustedMemberBindingEvidence(plan, candidates, objects) {
     const dimensions = new Map();
     for (const object of objects) {
@@ -581,6 +664,87 @@ function supplementalClarificationEvidence(plan, objects, existing) {
                 exactMatch: false,
             }];
     }));
+    // A compact retrieval package can contain the selected semantic metric but
+    // not a separately indexed card for one of that metric's declared grouping
+    // dimensions. Retain one exact, same-snapshot extension for that field when
+    // the request names its categorical role. This does not infer a join or a
+    // business alias: the metric capability owns both the qualified dimension
+    // id and the MetricFlow-native grouping path, and the router later admits it
+    // only beside this exact metric. It is intentionally separate from the
+    // geography-only recovery below, which may bind a location-like field for
+    // the distinct business term `region` under a stricter sole-field rule.
+    const exactCapabilityDimensionCards = existing.flatMap((metric) => {
+        if (metric.kind !== 'semantic_metric')
+            return [];
+        const capability = normalizeMetricCapabilityContract(metric.analyticalCapability);
+        if (!capability || !capability.executionCapabilities.some((execution) => execution.route === 'semantic'))
+            return [];
+        const metricId = metric.qualifiedId ?? metric.id;
+        return requestedDimensions.flatMap((requestedTerm) => capability.dimensions.flatMap((dimension) => {
+            if (!dimension.supportedRoles.includes('group_by'))
+                return [];
+            // `existing` is the unbounded retrieval snapshot, not the compact
+            // meaning package. A separately indexed semantic dimension can be
+            // present here yet later lose its role-balanced admission to a raw/dbt
+            // column with the same business words. Preserve the capability-backed
+            // extension in that case so the router can admit it beside its exact
+            // metric. The final de-duplication deliberately retains this extension
+            // (with its metric/role proof) over a plain dimension card.
+            const identities = [
+                dimension.dimensionId,
+                dimension.label ?? '',
+                ...(dimension.aliases ?? []),
+            ];
+            if (!identities.some((identity) => categoricalDimensionTermsMatch(requestedTerm, identity)))
+                return [];
+            return [{
+                    id: dimension.dimensionId,
+                    qualifiedId: dimension.dimensionId,
+                    kind: 'semantic_member',
+                    semanticObjectType: 'dimension',
+                    trustTier: 'semantic',
+                    name: dimension.label ?? dimension.dimensionId.split(/[.:/]/).at(-1) ?? dimension.dimensionId,
+                    aliases: uniqueStrings([
+                        dimension.label ?? '',
+                        ...(dimension.aliases ?? []),
+                        requestedTerm,
+                    ]),
+                    definition: `Same-snapshot MetricFlow grouping field for ${requestedTerm}.`,
+                    primaryEntity: dimension.entityId,
+                    dimensions: [dimension.dimensionId],
+                    sourceObjects: metric.sourceObjects,
+                    relationshipEvidence: metric.relationshipEvidence,
+                    relationshipSafety: metric.relationshipSafety,
+                    relevanceScore: metric.relevanceScore,
+                    matchReasons: ['same snapshot exact MetricFlow grouping extension'],
+                    compatibility: 'compatible',
+                    eligible: true,
+                    exactMatch: false,
+                    sameSnapshotRoleExtension: {
+                        version: 1,
+                        role: 'categorical_dimension',
+                        requestedTerm,
+                        metricId,
+                        dimensionId: dimension.dimensionId,
+                        basis: 'exact_metricflow_grouping_dimension',
+                    },
+                }];
+        }));
+    });
+    // A location-like semantic dimension is not generally a synonym for
+    // "region".  There is one deliberately narrow exception: when every
+    // current-turn requested metric proves the same one MetricFlow grouping
+    // dimension in this immutable snapshot.  Surface that card as a typed,
+    // host-authored extension so the bounded meaning call can bind it; the
+    // selected metric capability still verifies the native grouping path and
+    // remains the only execution authority.  This recovers the real Jaffle
+    // `revenue by ... region` path without guessing a raw join or widening
+    // lexical geography matching.
+    const sameSnapshotRoleExtensions = sameSnapshotGeographyRoleExtensions({
+        requestedMeasures,
+        requestedDimensions,
+        existing,
+    });
     // 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
@@ -624,8 +788,32 @@ function supplementalClarificationEvidence(plan, objects, existing) {
             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);
+    // The index may yield a generic semantic-dimension card and then this
+    // function may enrich that exact qualified ID with a metric-declared,
+    // same-snapshot role proof. Retain the enriched card: it is not a second
+    // candidate or a guessed relationship, but the only metadata authority that
+    // says this field is queryable with the selected MetricFlow metric for the
+    // current requested role. First-seen de-duplication discarded that proof in
+    // real local indexes and manufactured a false coverage gap for
+    // `product category` / `product_type`.
+    const uniqueByQualifiedId = new Map();
+    for (const candidate of [
+        ...objectCards,
+        ...exactCapabilityDimensionCards,
+        ...declaredDimensionCards,
+        ...sameSnapshotRoleExtensions,
+        ...rankingMeasureCards,
+    ]) {
+        const key = candidate.qualifiedId ?? candidate.id;
+        const existingCandidate = uniqueByQualifiedId.get(key);
+        if (!existingCandidate
+            || (!existingCandidate.sameSnapshotRoleExtension && candidate.sameSnapshotRoleExtension)) {
+            // Map replacement preserves stable first-seen ordering while retaining
+            // the stricter extension provenance for this one qualified object.
+            uniqueByQualifiedId.set(key, candidate);
+        }
+    }
+    const unique = [...uniqueByQualifiedId.values()];
     const roleLanes = [
         ...requestedDimensions.map((term) => ({ kind: 'dimension', term })),
         ...requestedMeasures.map((term) => ({ kind: 'metric', term })),
@@ -658,6 +846,95 @@ function supplementalClarificationEvidence(plan, objects, existing) {
     }
     return selected.slice(0, MAX_SUPPLEMENTAL_CANDIDATES);
 }
+function sameSnapshotGeographyRoleExtensions(input) {
+    const geographyTerms = [...new Set(input.requestedDimensions
+            .map(normalizeText)
+            .filter((term) => term === 'region' || term === 'geography' || term === 'geographic'))];
+    if (geographyTerms.length === 0 || input.requestedMeasures.length === 0)
+        return [];
+    const existingGeography = input.existing.some((candidate) => geographyTerms.some((term) => candidateMatchesCategoricalDimensionRequirement(candidate, [term])));
+    if (existingGeography)
+        return [];
+    const canonicalMetricTerm = (value) => {
+        const normalized = normalizeText(value);
+        return normalized === 'sale' || normalized === 'sales' ? 'revenue' : normalized;
+    };
+    const metricMatches = (candidate, requested) => {
+        if (candidate.kind !== 'semantic_metric' || !candidate.analyticalCapability)
+            return false;
+        const expected = canonicalMetricTerm(requested);
+        return [candidate.name, ...(candidate.aliases ?? []), candidate.analyticalCapability.metricId]
+            .map(canonicalMetricTerm)
+            .some((identity) => phraseTermsMatch(expected, identity));
+    };
+    const geographicDimension = (dimension) => {
+        const identity = [dimension.dimensionId, dimension.entityId, dimension.label ?? '', ...(dimension.aliases ?? [])]
+            .map(normalizeText)
+            .join(' ');
+        return /\b(?:region|geograph(?:y|ic)|location|country|state|province|city|territory)\b/.test(identity);
+    };
+    const candidatesForMeasure = (requested) => input.existing.flatMap((candidate) => {
+        if (!metricMatches(candidate, requested))
+            return [];
+        const capability = candidate.analyticalCapability;
+        if (!capability.executionCapabilities.some((execution) => execution.route === 'semantic'))
+            return [];
+        return capability.dimensions
+            .filter((dimension) => dimension.supportedRoles.includes('group_by') && geographicDimension(dimension))
+            .map((dimension) => ({ candidate, dimension }));
+    });
+    const matchesByMeasure = input.requestedMeasures.map((requested) => ({
+        requested,
+        matches: candidatesForMeasure(requested),
+    }));
+    if (matchesByMeasure.some(({ matches }) => matches.length === 0))
+        return [];
+    const sharedDimensionIds = matchesByMeasure
+        .map(({ matches }) => new Set(matches.map(({ dimension }) => dimension.dimensionId)))
+        .reduce((shared, ids) => shared === undefined
+        ? ids
+        : new Set([...shared].filter((id) => ids.has(id))), undefined);
+    if (!sharedDimensionIds || sharedDimensionIds.size !== 1)
+        return [];
+    const dimensionId = [...sharedDimensionIds][0];
+    const witness = matchesByMeasure[0].matches.find((match) => match.dimension.dimensionId === dimensionId);
+    if (!witness)
+        return [];
+    const { candidate: metricCandidate, dimension } = witness;
+    const requestedTerm = geographyTerms[0];
+    return [{
+            id: dimensionId,
+            qualifiedId: dimensionId,
+            kind: 'semantic_member',
+            semanticObjectType: 'dimension',
+            trustTier: 'semantic',
+            name: dimension.label ?? dimension.dimensionId.split(/[.:/]/).at(-1) ?? dimension.dimensionId,
+            aliases: uniqueStrings([
+                dimension.label ?? '',
+                ...(dimension.aliases ?? []),
+                requestedTerm,
+            ]),
+            definition: `Same-snapshot MetricFlow grouping field for ${requestedTerm}.`,
+            primaryEntity: dimension.entityId,
+            dimensions: [dimensionId],
+            sourceObjects: metricCandidate.sourceObjects,
+            relationshipEvidence: metricCandidate.relationshipEvidence,
+            relationshipSafety: metricCandidate.relationshipSafety,
+            relevanceScore: metricCandidate.relevanceScore,
+            matchReasons: ['same snapshot role-targeted MetricFlow grouping extension'],
+            compatibility: 'compatible',
+            eligible: true,
+            exactMatch: false,
+            sameSnapshotRoleExtension: {
+                version: 1,
+                role: 'categorical_dimension',
+                requestedTerm,
+                metricId: metricCandidate.qualifiedId ?? metricCandidate.id,
+                dimensionId,
+                basis: 'sole_metricflow_grouping_dimension',
+            },
+        }];
+}
 function expandedRequestedTerms(terms, objects) {
     const vocabulary = new Map();
     for (const object of objects) {
@@ -832,13 +1109,45 @@ export function applyContextPackCompatibility(evidence, pack, selectedEvidenceId
                 // paraphrase "What is monthly revenue?".  Do not promote lexical
                 // relevance alone; require the catalog's executable fit verdict.
                 const requestedMeasures = pack.questionPlan.requestedShape.measures;
-                const blockDeclaresRequestedMeasures = certifiedCandidateExplicitlyCoversMeasures(candidate, requestedMeasures);
+                // `declaredOutputs` is preferable because it remains independently
+                // visible in the block source. Some older-but-valid certified blocks
+                // only expose their projection through the catalog's immutable SQL
+                // contract, however. Preserve that proof *only* when the reader typed
+                // the exact block title and the same snapshot's catalog has already
+                // selected this precise block as a high-confidence certified answer.
+                // A fuzzy alias, paraphrase, or ordinary semantic question cannot use
+                // this bridge, so non-exact role and output constraints remain intact.
+                const exactCertifiedTitle = typeof pack.questionPlan.question === 'string'
+                    && normalizeText(pack.questionPlan.question) === normalizeText(candidate.name)
+                    && pack.routeDecision.route === 'certified'
+                    && pack.routeDecision.exactObjectKey === candidate.id
+                    && fit?.action === 'certified_answer'
+                    && (fit.fit.kind === 'exact' || fit.fit.kind === 'trim_safe')
+                    && fit.fit.confidence === 'high';
+                const compatibilityFacts = exactCertifiedTitle
+                    ? uniqueStrings([
+                        ...(candidate.compatibilityFacts ?? []),
+                        ...requestedMeasures.map((measure) => `catalog-proven-output: ${measure}`),
+                        // The catalog fit also proves this block's declared result
+                        // grain. Preserve it as an output only on the exact-title
+                        // bridge, so the immutable plan can bind `customer` to its
+                        // actual `customer_name` result without making a fuzzy block
+                        // title a display-key authority.
+                        ...(candidate.compatibilityFacts ?? []).flatMap((fact) => /^grain:\s*(.+)$/i.exec(fact)?.[1]
+                            ?.split(',')
+                            .map((value) => value.trim())
+                            .filter(Boolean)
+                            .map((value) => `catalog-proven-output: ${value}`) ?? []),
+                    ])
+                    : candidate.compatibilityFacts;
+                const blockDeclaresRequestedMeasures = certifiedCandidateExplicitlyCoversMeasures({ ...candidate, compatibilityFacts }, requestedMeasures);
                 const completeCertifiedFit = fit?.action === 'certified_answer'
                     && (fit.fit.kind === 'exact' || fit.fit.kind === 'trim_safe')
                     && fit.fit.confidence === 'high'
                     && blockDeclaresRequestedMeasures;
                 return {
                     ...candidate,
+                    ...(compatibilityFacts ? { compatibilityFacts } : {}),
                     // Lexical equality to a block name/alias is useful retrieval signal,
                     // but it is not exact analytical authority. The catalog's complete
                     // certified fit is the one host-owned exception and is still checked
@@ -915,11 +1224,31 @@ function trustTierFor(object, evidenceClass) {
         return 'governed_sql';
     return 'exploratory';
 }
-function candidateCard(object, evidenceClass, classRank, relevanceScore, aliases, relevanceReasons, ambiguityPeerIds) {
+function candidateCard(object, evidenceClass, classRank, relevanceScore, aliases, relevanceReasons, ambiguityPeerIds, retrievalLanes) {
     const payload = object.payload ?? {};
+    const typeParams = recordValue(payload.typeParams) ?? recordValue(payload.type_params) ?? {};
+    const dataType = firstString(payload.dataType, payload.data_type, payload.columnType, payload.column_type, payload.dimensionType, payload.dimension_type, payload.type, typeParams.dataType, typeParams.data_type);
+    const declaredTimeGrain = firstString(payload.timeGranularity, payload.time_granularity, typeParams.timeGranularity, typeParams.time_granularity);
+    const semanticRuntimeName = evidenceClass === 'semantic'
+        ? firstString(payload.localId, payload.local_id)
+        : undefined;
     const analyticalCapability = normalizeMetricCapabilityContract(payload.analyticalCapability);
     const relationshipSafety = relationshipSafetyFromObject(object);
-    const qualifiedId = firstString(payload.qualifiedId, payload.uniqueId, object.fullName, object.objectKey) ?? object.objectKey;
+    // A dbt/runtime column inherits its parent node's `uniqueId`.  That value
+    // is useful lineage metadata, but it is not a column identity: using it as
+    // the candidate's qualified ID collapsed every selected column on a model
+    // into the model itself.  The physical cascade then appeared safe but could
+    // not freeze an exact output contract.  Keep the parent relation in
+    // `sourceRelations`; give a column its source-qualified field identity.
+    const columnObject = object.objectType.endsWith('_column');
+    // Semantic registry IDs are model-qualified execution identities.  The
+    // historic `qualifiedId` field on a MetricFlow time dimension was only
+    // domain + local name (`semantic:uncategorized:dimension:metric_time`), so
+    // every model's synthesized global axis collapsed into one V2 capability.
+    // Prefer the registry-qualified identity captured by the KG for semantic
+    // cards; retain the older value in aliases for bounded backward reads.
+    // Physical columns intentionally preserve their own source-qualified rule.
+    const qualifiedId = firstString(...(evidenceClass === 'semantic' ? [payload.registryQualifiedId] : []), payload.qualifiedId, ...(columnObject ? [object.fullName] : []), payload.uniqueId, object.fullName, object.objectKey) ?? object.objectKey;
     const parameters = arrayNames(payload.parameters ?? payload.parameterPolicy);
     const outputs = uniqueStrings([
         ...stringArray(payload.declaredOutputs),
@@ -963,6 +1292,12 @@ function candidateCard(object, evidenceClass, classRank, relevanceScore, aliases
             ? truncate(firstString(payload.formula, payload.expr, payload.sql), 320)
             : undefined,
         semanticModel: firstString(payload.semanticModel, payload.cube),
+        // dbt/MetricFlow semantic objects often use a model-qualified display
+        // name (`order_item.metric_time`) while the compiler accepts their local
+        // declaration (`metric_time`). Preserve the latter only as host-side
+        // capability data. It must never become a fuzzy retrieval alias.
+        ...(semanticRuntimeName ? { semanticRuntimeName } : {}),
+        ...(dataType ? { dataType } : {}),
         relevanceReasons,
         compatibilityFacts,
         businessShape: {
@@ -973,6 +1308,14 @@ function candidateCard(object, evidenceClass, classRank, relevanceScore, aliases
             timeGrains: uniqueStrings([
                 ...stringArray(payload.timeGrains),
                 ...stringArray(payload.supportedTimeGrains),
+                // MetricFlow/dbt semantic dimensions are indexed with their authored
+                // `granularities` array.  Keep that declaration in the bounded
+                // retrieval card: Ask V2 validates a selected time grain against this
+                // exact snapshot-local capability and must not infer one from a name.
+                ...stringArray(payload.granularities),
+                ...stringArray(payload.queryableGranularities),
+                ...stringArray(payload.queryable_granularities),
+                declaredTimeGrain ?? '',
             ]).slice(0, 8),
             parameters: parameters.slice(0, 12),
             filters: stringArray(payload.allowedFilters).slice(0, 12),
@@ -986,9 +1329,23 @@ function candidateCard(object, evidenceClass, classRank, relevanceScore, aliases
         ...(analyticalCapability ? { analyticalCapability } : {}),
         ...(relationshipSafety ? { relationshipSafety: [relationshipSafety] } : {}),
         provenance: firstString(payload.provenance, object.sourceSystem),
+        ...(retrievalLanes?.length ? { retrievalLanes } : {}),
         ambiguityPeerIds,
     };
 }
+function laneMembershipByObjectKey(lanes) {
+    const memberships = new Map();
+    for (const lane of lanes) {
+        for (const candidate of lane.candidates) {
+            const next = memberships.get(candidate.objectKey) ?? [];
+            if (!next.some((entry) => entry.lane === lane.lane && entry.rank === candidate.rank)) {
+                next.push({ lane: lane.lane, rank: candidate.rank });
+            }
+            memberships.set(candidate.objectKey, next);
+        }
+    }
+    return memberships;
+}
 function agentEvidenceKind(candidate) {
     if (candidate.evidenceClass === 'certified')
         return 'certified_block';