@duckcodeailabs/dql-agent 1.14.1 → 1.14.3-rc.1

package/dist/metadata/meaning-evidence.js

@@ -1,17 +1,21 @@
 import { scoreMetadataObjectWithAnalysisPlan, } from "./analysis-planner.js";
 import { normalizeMetricCapabilityContract, } from "@duckcodeailabs/dql-core";
+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',
     'weekly', 'quarterly', 'yearly', 'annual', 'count', 'number', 'rate', 'ratio',
 ]);
 const MAX_CANDIDATES_PER_CLASS = 4;
+const MAX_QUALIFIED_CANDIDATES = 32;
 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) => {
@@ -40,6 +44,15 @@ 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) => ({
+        objectKey: candidate.item.row.objectKey,
+        aliases: candidate.aliases,
+    })));
+    const qualifiedCounts = { certified: 0, semantic: 0, sql: 0 };
+    const qualifiedCandidates = eligible.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) ?? [], laneMembership.get(candidate.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
@@ -91,11 +104,12 @@ 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,
         byEvidenceClass,
         ambiguousGroups: ambiguityGroups(peerMap),
     };
@@ -114,17 +128,141 @@ export function buildMeaningEvidencePackage(question, questionPlan, ranked) {
  * gates joins on that list, so every multi-relation governed compile returned
  * `RELATIONSHIP_PROOF_REQUIRED` and the path was unreachable in production.
  *
- * This only *offers* the identities. `compileGovernedRelationalPlan` still
- * enforces certified, fresh, automatic-join-safe (`REL-002`) before it emits a
- * join, so surfacing a draft relationship here cannot authorize one.
+ * This only *offers* identities and compact source facts.
+ * `compileGovernedRelationalPlan` still enforces certified, fresh,
+ * automatic-join-safe (`REL-002`) before it emits a join. The router also
+ * requires the structured safety record for exploratory composition, so a
+ * draft relationship with a neutral-looking identity cannot suppress a
+ * clarification.
+ */
+function relationshipSafetyFromObject(object) {
+    if (object.objectType !== 'relationship')
+        return undefined;
+    const payload = object.payload ?? {};
+    const id = firstString(payload.qualifiedId, payload.id, object.fullName, object.objectKey);
+    if (!id)
+        return undefined;
+    const validationPayload = recordValue(payload.validation);
+    const keys = Array.isArray(payload.keys)
+        ? payload.keys.flatMap((value) => {
+            const key = recordValue(value);
+            const from = firstString(key?.from);
+            const to = firstString(key?.to);
+            return from && to ? [{ from, to }] : [];
+        })
+        : [];
+    const validation = validationPayload
+        ? {
+            status: firstString(validationPayload.status),
+            checkedAt: firstString(validationPayload.checkedAt, validationPayload.checked_at),
+            queryFingerprint: firstString(validationPayload.queryFingerprint, validationPayload.query_fingerprint),
+            proofFingerprint: firstString(validationPayload.proofFingerprint, validationPayload.proof_fingerprint),
+        }
+        : undefined;
+    return {
+        id,
+        aliases: uniqueStrings([
+            firstString(payload.qualifiedId) ?? '',
+            firstString(payload.id) ?? '',
+            firstString(payload.localId) ?? '',
+            object.objectKey,
+            object.fullName ?? '',
+            object.name,
+        ]).filter((identity) => identity !== id),
+        from: firstString(payload.from),
+        to: firstString(payload.to),
+        keys,
+        status: firstString(payload.status, object.status),
+        cardinality: firstString(payload.cardinality),
+        fanout: firstString(payload.fanout),
+        ...(typeof payload.staleCertification === 'boolean'
+            ? { staleCertification: payload.staleCertification }
+            : {}),
+        ...(typeof payload.automaticJoinAllowed === 'boolean'
+            ? { automaticJoinAllowed: payload.automaticJoinAllowed }
+            : {}),
+        certificationFingerprint: firstString(payload.certificationFingerprint),
+        evidenceExpiresAt: firstString(payload.evidenceExpiresAt, payload.evidence_expires_at),
+        ...(validation ? { validation } : {}),
+    };
+}
+function normalizedRelationshipReference(value) {
+    return value.trim().toLowerCase();
+}
+function relationshipReferenceLeaf(value) {
+    const normalized = normalizedRelationshipReference(value).replace(/["`\[\]]/g, '');
+    return normalized.split(/::|:|\./).filter(Boolean).at(-1) ?? normalized;
+}
+function candidateRelationshipReferences(candidate) {
+    return uniqueStrings([
+        candidate.qualifiedId ?? '',
+        candidate.id,
+        candidate.primaryEntity ?? '',
+        candidate.analyticalCapability?.primaryEntityId ?? '',
+        ...(candidate.sourceObjects ?? []),
+    ]);
+}
+function isRawRelationCandidate(candidate) {
+    return candidate.kind === 'dbt_model'
+        || candidate.kind === 'dbt_source'
+        || candidate.kind === 'sql_table';
+}
+/**
+ * Bind relationship proof only through a canonical entity/relation identity.
+ * A leaf fallback is deliberately allowed only when both the endpoint and the
+ * raw relation leaf occur exactly once in the retrieval snapshot. This keeps
+ * two domains with an `orders` model from inheriting each other's proof.
  */
 function attachRelationshipEvidence(candidates, contextObjects) {
     const relationships = contextObjects.filter((object) => object.objectType === 'relationship');
     if (relationships.length === 0)
         return;
-    const identitiesByEntity = new Map();
+    const endpointIdsByReference = new Map();
+    const endpointIdsByLeaf = new Map();
+    const identitiesByEndpoint = new Map();
+    const safetyByEndpoint = new Map();
+    const registerEndpointReference = (endpoint, reference) => {
+        if (!reference?.trim())
+            return;
+        const normalizedReference = normalizedRelationshipReference(reference);
+        const existing = endpointIdsByReference.get(normalizedReference) ?? new Set();
+        existing.add(endpoint);
+        endpointIdsByReference.set(normalizedReference, existing);
+    };
+    const registerEndpoint = (endpoint) => {
+        const normalizedEndpoint = normalizedRelationshipReference(endpoint);
+        const existing = endpointIdsByLeaf.get(relationshipReferenceLeaf(endpoint)) ?? new Set();
+        existing.add(endpoint);
+        endpointIdsByLeaf.set(relationshipReferenceLeaf(endpoint), existing);
+        registerEndpointReference(endpoint, endpoint);
+        // Keep the canonical normalized key explicit even when endpoint casing
+        // differs from the relationship payload or a physical dbt reference.
+        registerEndpointReference(endpoint, normalizedEndpoint);
+    };
+    // DQL entity metadata is the authoritative bridge from a canonical modeling
+    // endpoint to its dbt/runtime relation. Preserve that bridge rather than
+    // reducing it to a leaf name.
+    for (const object of contextObjects.filter((item) => item.objectType === 'dql_entity')) {
+        const payload = object.payload ?? {};
+        const endpoint = firstString(payload.qualifiedId, payload.id, object.fullName, object.objectKey);
+        if (!endpoint)
+            continue;
+        registerEndpoint(endpoint);
+        for (const reference of [
+            payload.qualifiedId,
+            payload.id,
+            payload.localId,
+            payload.dbtUniqueId,
+            payload.relation,
+            payload.table,
+            object.objectKey,
+            object.fullName,
+        ])
+            registerEndpointReference(endpoint, firstString(reference));
+    }
     for (const object of relationships) {
         const payload = (object.payload ?? {});
+        const safety = relationshipSafetyFromObject(object);
         const identities = [payload.qualifiedId, payload.id, payload.localId, object.objectKey, object.fullName, object.name]
             .filter((value) => Boolean(value));
         if (identities.length === 0)
@@ -132,58 +270,114 @@ function attachRelationshipEvidence(candidates, contextObjects) {
         for (const endpoint of [payload.from, payload.to]) {
             if (!endpoint)
                 continue;
-            for (const alias of entityAliasesForRelationshipMatch(endpoint)) {
-                const existing = identitiesByEntity.get(alias) ?? new Set();
-                for (const identity of identities)
-                    existing.add(identity);
-                identitiesByEntity.set(alias, existing);
+            registerEndpoint(endpoint);
+            const normalizedEndpoint = normalizedRelationshipReference(endpoint);
+            const endpointIdentities = identitiesByEndpoint.get(normalizedEndpoint) ?? new Set();
+            for (const identity of identities)
+                endpointIdentities.add(identity);
+            identitiesByEndpoint.set(normalizedEndpoint, endpointIdentities);
+            if (safety) {
+                const safetyForEndpoint = safetyByEndpoint.get(normalizedEndpoint) ?? new Map();
+                safetyForEndpoint.set(safety.id, safety);
+                safetyByEndpoint.set(normalizedEndpoint, safetyForEndpoint);
             }
         }
     }
-    if (identitiesByEntity.size === 0)
+    if (identitiesByEndpoint.size === 0)
         return;
+    const rawRelationIdsByLeaf = new Map();
+    const registerRawRelation = (relationId, references) => {
+        for (const leaf of new Set(references.map(relationshipReferenceLeaf))) {
+            const ids = rawRelationIdsByLeaf.get(leaf) ?? new Set();
+            ids.add(relationId);
+            rawRelationIdsByLeaf.set(leaf, ids);
+        }
+    };
+    for (const candidate of candidates.filter(isRawRelationCandidate)) {
+        registerRawRelation(normalizedRelationshipReference(candidate.qualifiedId ?? candidate.id), candidateRelationshipReferences(candidate));
+    }
+    // Candidate cards are bounded, but the immutable context snapshot can retain
+    // another raw relation with the same leaf outside that compact package. Count
+    // it too before permitting a leaf fallback.
+    for (const object of contextObjects.filter((item) => item.objectType === 'dbt_model'
+        || item.objectType === 'dbt_source'
+        || item.objectType === 'warehouse_table'
+        || item.objectType === 'runtime_table')) {
+        const payload = object.payload ?? {};
+        const relationId = firstString(payload.qualifiedId, payload.uniqueId, object.fullName, object.objectKey) ?? object.objectKey;
+        registerRawRelation(normalizedRelationshipReference(relationId), uniqueStrings([
+            relationId,
+            firstString(payload.qualifiedId) ?? '',
+            firstString(payload.uniqueId) ?? '',
+            firstString(payload.relation) ?? '',
+            firstString(payload.table) ?? '',
+            object.name,
+            object.fullName ?? '',
+        ]));
+    }
+    const endpointsForReferences = (references) => {
+        const direct = new Set();
+        for (const reference of references) {
+            for (const endpoint of endpointIdsByReference.get(normalizedRelationshipReference(reference)) ?? []) {
+                direct.add(endpoint);
+            }
+        }
+        if (direct.size > 0)
+            return direct;
+        const fallback = new Set();
+        for (const leaf of new Set(references.map(relationshipReferenceLeaf))) {
+            const endpoints = endpointIdsByLeaf.get(leaf);
+            if (endpoints?.size !== 1 || rawRelationIdsByLeaf.get(leaf)?.size !== 1)
+                continue;
+            for (const endpoint of endpoints)
+                fallback.add(endpoint);
+        }
+        return fallback;
+    };
     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);
+            const endpoints = endpointsForReferences([dimension.entityId, ...(dimension.nativeGroupingPath ?? [])]);
+            for (const endpoint of endpoints) {
+                for (const identity of identitiesByEndpoint.get(normalizedRelationshipReference(endpoint)) ?? []) {
+                    pathRelationships.add(identity);
                 }
             }
             if (pathRelationships.size > 0)
                 dimension.relationshipPathIds = [...pathRelationships].sort();
         }
+        const endpoints = endpointsForReferences(candidateRelationshipReferences(candidate));
         const touched = new Set();
-        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)) {
-                for (const identity of identitiesByEntity.get(alias) ?? [])
-                    touched.add(identity);
+        const touchedSafety = new Map((candidate.relationshipSafety ?? []).map((safety) => [safety.id, safety]));
+        for (const endpoint of endpoints) {
+            const normalizedEndpoint = normalizedRelationshipReference(endpoint);
+            for (const identity of identitiesByEndpoint.get(normalizedEndpoint) ?? [])
+                touched.add(identity);
+            for (const safety of safetyByEndpoint.get(normalizedEndpoint)?.values() ?? []) {
+                touchedSafety.set(safety.id, safety);
             }
         }
+        if (endpoints.size > 0) {
+            candidate.relationshipEndpointIds = [...new Set([
+                    ...(candidate.relationshipEndpointIds ?? []),
+                    ...endpoints,
+                ])].sort();
+        }
         if (touched.size > 0)
             candidate.relationshipEvidence = [...touched].sort();
+        if (touchedSafety.size > 0) {
+            candidate.relationshipSafety = [...touchedSafety.values()]
+                .sort((left, right) => left.id.localeCompare(right.id));
+        }
     }
 }
-/** Match `commerce::entity::order`, `order`, and `entity:order` as one entity. */
-function entityAliasesForRelationshipMatch(reference) {
-    const normalized = reference.toLowerCase().replace(/^entity:/, '');
-    return [...new Set([normalized, normalized.split('::').at(-1) ?? normalized])];
-}
 export function toAgentRetrievalEvidence(evidence, questionPlan, options = {}) {
-    const maxRelevance = Math.max(1, ...evidence.candidates.map((candidate) => candidate.relevanceScore));
-    const candidates = evidence.candidates.map((candidate) => agentCandidateFromMeaning(candidate, maxRelevance));
+    const sourceCandidates = evidence.qualifiedCandidates?.length
+        ? evidence.qualifiedCandidates
+        : evidence.candidates;
+    const maxRelevance = Math.max(1, ...sourceCandidates.map((candidate) => candidate.relevanceScore));
+    const optionLaneMembership = laneMembershipByObjectKey(options.retrievalLanes ?? []);
+    const candidates = sourceCandidates.map((candidate) => agentCandidateFromMeaning(candidate, maxRelevance, candidate.retrievalLanes ?? optionLaneMembership.get(candidate.objectKey)));
     const trustedBindings = trustedMemberBindingEvidence(questionPlan, candidates, options.contextObjects ?? []);
     for (const member of trustedBindings.candidates) {
         if (!candidates.some((candidate) => candidate.id === member.id))
@@ -243,7 +437,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,
@@ -265,6 +459,7 @@ function agentCandidateFromMeaning(candidate, maxRelevance = 1) {
         timeGrains: candidate.businessShape.timeGrains,
         requiredParameters: candidate.businessShape.parameters,
         sourceObjects: candidate.businessShape.sourceRelations,
+        relationshipSafety: candidate.relationshipSafety,
         relevanceScore: Number((candidate.relevanceScore / maxRelevance).toFixed(6)),
         matchReasons: candidate.relevanceReasons,
         // Fit validation remains host-owned. Metadata only reports facts here and
@@ -274,6 +469,7 @@ function agentCandidateFromMeaning(candidate, maxRelevance = 1) {
         analyticalCapability: candidate.analyticalCapability,
         eligible: true,
         exactMatch: candidate.relevanceReasons.includes("exact name or alias"),
+        ...(retrievalLanes?.length ? { retrievalLanes } : {}),
     };
 }
 function trustedMemberBindingEvidence(plan, candidates, objects) {
@@ -353,21 +549,21 @@ function supplementalClarificationEvidence(plan, objects, existing) {
         if (!['semantic_metric', 'semantic_measure', 'semantic_dimension'].includes(object.objectType))
             return [];
         const names = aliasesFor(object).map(normalizeText);
-        const role = normalizeDimensionRole(object.name);
+        const candidate = agentCandidateFromMeaning(candidateCard(object, 'semantic', 1, 1, aliasesFor(object), ['requested clarification capability'], []));
         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)));
+                || candidateMatchesCategoricalDimensionRequirement(candidate, [term]));
         if (!relevant)
             return [];
-        const card = candidateCard(object, 'semantic', 1, 1, aliasesFor(object), ['requested clarification capability'], []);
-        return [agentCandidateFromMeaning(card)];
+        return [candidate];
     });
     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)));
+        const relevant = requestedDimensions.some((term) => phraseTermsMatch(term, role)
+            || candidateMatchesCategoricalDimensionRequirement(candidate, [term]));
         if (!relevant)
             return [];
         return [{
@@ -380,6 +576,7 @@ function supplementalClarificationEvidence(plan, objects, existing) {
                 definition: `Modeled ${role} dimension available through ${candidate.name}.`,
                 primaryEntity: candidate.primaryEntity,
                 dimensions: [dimensionId],
+                compatibilityFacts: candidate.compatibilityFacts,
                 relevanceScore: candidate.relevanceScore,
                 matchReasons: ['requested clarification capability role'],
                 compatibility: 'partial',
@@ -387,6 +584,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
@@ -430,8 +708,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 })),
@@ -454,7 +756,7 @@ function supplementalClarificationEvidence(plan, objects, existing) {
             if (candidate.kind !== 'semantic_member')
                 return false;
             return candidateTerms.some((term) => phraseTermsMatch(lane.term, term))
-                || (isGeographicRole(lane.term) && candidateTerms.some(isGeographicRole));
+                || candidateMatchesCategoricalDimensionRequirement(candidate, [lane.term]);
         }).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))) {
@@ -464,6 +766,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) {
@@ -526,9 +917,6 @@ function dimensionLookupAliases(dimensions) {
         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
@@ -640,11 +1028,46 @@ export function applyContextPackCompatibility(evidence, pack, selectedEvidenceId
                 // `monthly_revenue` artifact lose to a semantic metric for the ordinary
                 // paraphrase "What is monthly revenue?".  Do not promote lexical
                 // relevance alone; require the catalog's executable fit verdict.
-                const completeCertifiedFit = fit?.action === 'certified_answer'
+                const requestedMeasures = pack.questionPlan.requestedShape.measures;
+                // `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
@@ -657,7 +1080,7 @@ export function applyContextPackCompatibility(evidence, pack, selectedEvidenceId
                     // 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'
+                    compatibility: completeCertifiedFit
                         ? 'compatible'
                         : fit?.action === 'rejected_for_fit'
                             ? 'incompatible'
@@ -721,17 +1144,38 @@ 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 analyticalCapability = normalizeMetricCapabilityContract(payload.analyticalCapability);
-    const qualifiedId = firstString(payload.qualifiedId, payload.uniqueId, object.fullName, object.objectKey) ?? object.objectKey;
+    const relationshipSafety = relationshipSafetyFromObject(object);
+    // 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');
+    const qualifiedId = firstString(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),
         ...arrayNames(payload.outputContract),
         ...arrayNames(payload.outputs),
     ]);
+    const declaredSemanticGeography = [
+        ...stringArray(payload.semanticRoles),
+        ...stringArray(payload.semantic_roles),
+        firstString(payload.semanticRole, payload.semantic_role) ?? '',
+    ].some((role) => {
+        const normalized = normalizeText(role);
+        return normalized === 'geography' || normalized === 'geographic';
+    });
     const compatibilityFacts = uniqueStrings([
+        // Carry only authored, snapshot-local compatibility facts. Consumers use
+        // these as typed declarations, never as fuzzy lexical aliases.
+        ...stringArray(payload.compatibilityFacts),
+        ...stringArray(payload.compatibility_facts),
+        ...(declaredSemanticGeography ? ['semantic-role: geography'] : []),
         firstString(payload.grain) ? `grain: ${firstString(payload.grain)}` : '',
         ...stringArray(payload.dimensions).slice(0, 8).map((value) => `dimension: ${value}`),
         ...parameters.slice(0, 8).map((value) => `parameter: ${value}`),
@@ -776,10 +1220,25 @@ function candidateCard(object, evidenceClass, classRank, relevanceScore, aliases
             ]).slice(0, 12),
         },
         ...(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';
@@ -915,6 +1374,11 @@ function stringArray(value) {
         ? value.filter((item) => typeof item === 'string' && Boolean(item.trim()))
         : [];
 }
+function recordValue(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
 function arrayNames(value) {
     if (!Array.isArray(value))
         return [];