@duckcodeailabs/dql-agent 1.14.0 → 1.14.2

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

@@ -1,7 +1,7 @@
 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 { AgentRetrievalEvidence } from '../meaning-resolution.js';
+import { type AgentRetrievalEvidence, type AgentRelationshipSafetyEvidence } from '../meaning-resolution.js';
 import type { KnowledgeLens } from '../domain-context.js';
 export type MetadataEvidenceClass = 'certified' | 'semantic' | 'sql';
 export type MetadataEvidenceTrust = 'certified' | 'semantic' | 'governed_sql' | 'exploratory';
@@ -35,11 +35,20 @@ export interface MetadataMeaningCandidate {
     };
     /** Snapshot-normalized execution truth; absent means capability is incomplete. */
     analyticalCapability?: MetricCapabilityContract;
+    /** Structured relationship facts when this card itself is a relationship. */
+    relationshipSafety?: AgentRelationshipSafetyEvidence[];
     provenance?: string;
     ambiguityPeerIds: string[];
 }
 export interface MetadataMeaningEvidencePackage {
     candidates: MetadataMeaningCandidate[];
+    /**
+     * Snapshot-qualified retrieval retained for host-side role admission. The
+     * historic per-class cards remain for compact UI diagnostics, but must not
+     * erase an explicit metric/entity before the one bounded meaning package is
+     * role-balanced.
+     */
+    qualifiedCandidates?: MetadataMeaningCandidate[];
     byEvidenceClass: Record<MetadataEvidenceClass, MetadataMeaningCandidate[]>;
     ambiguousGroups: Array<{
         candidateIds: string[];

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,10 +1,13 @@
 import { scoreMetadataObjectWithAnalysisPlan, } from "./analysis-planner.js";
 import { normalizeMetricCapabilityContract, } from "@duckcodeailabs/dql-core";
+import { candidateMatchesCategoricalDimensionRequirement } 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
@@ -40,6 +43,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) ?? []);
+    });
     const requiredSemanticMetricKey = questionPlan.requestedShape.measures.length > 0
         ? eligible.find((candidate) => candidate.evidenceClass === 'semantic'
             && candidate.item.row.objectType === 'semantic_metric')?.item.row.objectKey
@@ -96,6 +108,7 @@ export function buildMeaningEvidencePackage(question, questionPlan, ranked) {
     return {
         candidates: ['certified', 'semantic', 'sql']
             .flatMap((evidenceClass) => byEvidenceClass[evidenceClass]),
+        qualifiedCandidates,
         byEvidenceClass,
         ambiguousGroups: ambiguityGroups(peerMap),
     };
@@ -114,17 +127,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 +269,113 @@ 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 candidates = sourceCandidates.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))
@@ -265,6 +457,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
@@ -353,21 +546,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 +573,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',
@@ -454,7 +648,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))) {
@@ -526,9 +720,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
@@ -633,23 +824,34 @@ export function applyContextPackCompatibility(evidence, pack, selectedEvidenceId
             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');
+                // `certified_answer` is already the catalog's termination verdict: it
+                // binds the exact artifact to a high-confidence complete shape fit.
+                // An authored example remains one way to reach it, but it is not the
+                // only safe way.  Requiring literal example wording made a compatible
+                // `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 requestedMeasures = pack.questionPlan.requestedShape.measures;
+                const blockDeclaresRequestedMeasures = certifiedCandidateExplicitlyCoversMeasures(candidate, requestedMeasures);
+                const completeCertifiedFit = fit?.action === 'certified_answer'
+                    && (fit.fit.kind === 'exact' || fit.fit.kind === 'trim_safe')
+                    && fit.fit.confidence === 'high'
+                    && blockDeclaresRequestedMeasures;
                 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
+                    // but it is not exact analytical authority. The catalog's complete
+                    // certified fit is the one host-owned exception and is still checked
+                    // again when the immutable plan freezes.
+                    exactMatch: completeCertifiedFit,
+                    ...(completeCertifiedFit
                         ? { 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'
+                    compatibility: completeCertifiedFit
                         ? 'compatible'
                         : fit?.action === 'rejected_for_fit'
                             ? 'incompatible'
@@ -716,6 +918,7 @@ function trustTierFor(object, evidenceClass) {
 function candidateCard(object, evidenceClass, classRank, relevanceScore, aliases, relevanceReasons, ambiguityPeerIds) {
     const payload = object.payload ?? {};
     const analyticalCapability = normalizeMetricCapabilityContract(payload.analyticalCapability);
+    const relationshipSafety = relationshipSafetyFromObject(object);
     const qualifiedId = firstString(payload.qualifiedId, payload.uniqueId, object.fullName, object.objectKey) ?? object.objectKey;
     const parameters = arrayNames(payload.parameters ?? payload.parameterPolicy);
     const outputs = uniqueStrings([
@@ -723,7 +926,20 @@ function candidateCard(object, evidenceClass, classRank, relevanceScore, aliases
         ...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}`),
@@ -768,6 +984,7 @@ function candidateCard(object, evidenceClass, classRank, relevanceScore, aliases
             ]).slice(0, 12),
         },
         ...(analyticalCapability ? { analyticalCapability } : {}),
+        ...(relationshipSafety ? { relationshipSafety: [relationshipSafety] } : {}),
         provenance: firstString(payload.provenance, object.sourceSystem),
         ambiguityPeerIds,
     };
@@ -907,6 +1124,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 [];