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

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';
@@ -38,6 +38,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 {
@@ -65,6 +70,8 @@ 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[];
 }
 export interface MeaningEvidenceInputCandidate {
     row: MetadataObject;
@@ -78,7 +85,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',
@@ -14,7 +14,8 @@ const ANALYTICAL_TIME_GRAINS = new Set(['day', 'week', 'month', 'quarter', 'year
  * 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) => {
@@ -50,7 +51,7 @@ export function buildMeaningEvidencePackage(question, questionPlan, ranked) {
     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) ?? []);
+        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,7 +104,7 @@ 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']
@@ -375,7 +376,8 @@ export function toAgentRetrievalEvidence(evidence, questionPlan, options = {}) {
         ? 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)));
     const trustedBindings = trustedMemberBindingEvidence(questionPlan, candidates, options.contextObjects ?? []);
     for (const member of trustedBindings.candidates) {
         if (!candidates.some((candidate) => candidate.id === member.id))
@@ -435,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,
@@ -467,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) {
@@ -581,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
@@ -624,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 })),
@@ -658,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) {
@@ -832,13 +1029,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 +1144,18 @@ 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 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');
+    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),
@@ -986,9 +1222,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';