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

package/dist/resolved-analytical-plan.js

@@ -8,8 +8,9 @@
  */
 import { createHash } from "node:crypto";
 import { normalizeMetricCapabilityContract, } from "@duckcodeailabs/dql-core";
-import { certifiedCandidateDeclaredMeasureOutput, certifiedCandidateExplicitlyCoversMeasures, } from './meaning-resolution.js';
-import { buildResolvedRelationshipProofsV1 } from './relationship-proof.js';
+import { certifiedCandidateDeclaredDimensionOutput, certifiedCandidateDeclaredMeasureOutput, certifiedCandidateExplicitlyCoversMeasures, } from './meaning-resolution.js';
+import { currentQuestionGroundedParsedIntent } from './analytical-orchestration.js';
+import { buildResolvedRelationshipProofsV1, buildGovernedRelationshipSafetyProofsV1, governedCapabilityDimensionHasFreshAutomaticRelationshipProofV1, semanticDimensionUsesExactAdapterGrouping, } from './relationship-proof.js';
 export function buildResolvedAnalyticalPlan(input) {
     const byLegacyId = new Map(input.candidates.map((candidate) => [candidate.id, candidate]));
     const selectedCandidates = input.resolution.selectedConceptIds
@@ -22,7 +23,12 @@ export function buildResolvedAnalyticalPlan(input) {
         // complete tuple. Bind its declared inputs/outputs as one execution
         // authority instead of mixing in the semantic concept used to select it.
         ? [executionCandidate]
-        : resolutionUsesRelationalEvidence(input.resolution)
+        // A governed-relational route may bind through its certified relationship
+        // closure. Exploratory is different: the router has already selected a
+        // minimal qualified physical closure before plan freeze. Re-opening the
+        // whole snapshot here lets unrelated columns re-enter an exact output
+        // contract and turns `order_id`/`product_id` into false ambiguities.
+        : input.resolution.recommendedRoute === 'governed_sql'
             ? input.candidates
             : selectedCandidates.length > 0
                 ? selectedCandidates
@@ -30,7 +36,6 @@ export function buildResolvedAnalyticalPlan(input) {
                     ? [executionCandidate]
                     : input.candidates;
     const canonicalId = (candidate) => candidate.qualifiedId ?? candidate.id;
-    const selectedConceptIds = selectedCandidates.map(canonicalId);
     const executionId = executionCandidate ? canonicalId(executionCandidate) : undefined;
     const measures = input.resolution.queryIntent.measures.length > 0
         ? input.resolution.queryIntent.measures.map((requested) => bindRequestedMember(requested, bindingCandidates, 'measure', input.question))
@@ -50,7 +55,134 @@ export function buildResolvedAnalyticalPlan(input) {
         ? input.candidates
         : bindingCandidates;
     const selectedCapability = normalizeMetricCapabilityContract(executionCandidate?.analyticalCapability);
+    const selectedCertifiedBlock = input.resolution.recommendedRoute === 'certified'
+        && executionCandidate?.kind === 'certified_block'
+        && executionCandidate.compatibility === 'compatible'
+        ? executionCandidate
+        : undefined;
+    // The direct router may canonicalize a literal request (for example,
+    // “food and drink”) to an exact block's declared output (`category`) after
+    // that exact block independently proved the tuple. Keep that narrow
+    // zero-provider projection distinct from the ordinary host requirement
+    // contract below; a model-selected block can never create it.
+    const exactCertifiedDimensionProjection = certifiedBlockCanUseExactCanonicalDimensionProjection(executionCandidate, input.resolution);
+    const hostEntityDisplayTerms = new Set(input.resolution.hostRequirementSeed?.requirements.entityDisplayTerms
+        .map(normalize)
+        .filter(Boolean) ?? []);
+    // A certified route is not a semantic capability route with a green badge.
+    // Every host-owned grouping/display/output term must be declared by the
+    // selected block itself before that block can freeze. The optional normalized
+    // capability can corroborate the selected block, but it may not substitute a
+    // contextual semantic field for a block output the block never promised.
+    const hostCertifiedProjectionTerms = new Set([
+        ...(input.resolution.hostRequirementSeed?.queryIntent.dimensions ?? []),
+        ...(input.resolution.hostRequirementSeed?.requirements.entityDisplayTerms ?? []),
+        ...(input.resolution.hostRequirementSeed?.requirements.outputTerms ?? []),
+    ].map(normalize).filter(Boolean));
+    const bindCertifiedDeclaredDimension = (requested) => {
+        const outputName = selectedCertifiedBlock
+            ? certifiedCandidateDeclaredDimensionOutput(selectedCertifiedBlock, requested)
+            : undefined;
+        if (!selectedCertifiedBlock || !outputName) {
+            return { requested, status: 'unresolved', candidateIds: [] };
+        }
+        const candidateId = canonicalId(selectedCertifiedBlock);
+        return {
+            requested,
+            qualifiedId: candidateId,
+            outputName,
+            status: 'resolved',
+            candidateIds: [candidateId],
+        };
+    };
+    const bindCertifiedDeclaredOutput = (requested) => {
+        const outputName = selectedCertifiedBlock
+            ? certifiedCandidateDeclaredDimensionOutput(selectedCertifiedBlock, requested)
+                ?? certifiedCandidateDeclaredMeasureOutput(selectedCertifiedBlock, requested)
+            : undefined;
+        if (!selectedCertifiedBlock || !outputName) {
+            return { requested, status: 'unresolved', candidateIds: [] };
+        }
+        const candidateId = canonicalId(selectedCertifiedBlock);
+        return {
+            requested,
+            qualifiedId: candidateId,
+            outputName,
+            status: 'resolved',
+            candidateIds: [candidateId],
+        };
+    };
     const bindDimension = (requested, roles) => {
+        const normalizedRequested = normalize(requested);
+        if (selectedCertifiedBlock && hostCertifiedProjectionTerms.has(normalizedRequested)) {
+            return bindCertifiedDeclaredDimension(requested);
+        }
+        // The candidate-ID meaning protocol cannot author a frame, but the host
+        // has already bound a V2 frame from the immutable requirement seed. A
+        // seeded rank/display requirement may use the human phrase `customer
+        // name` while the selected MetricFlow capability truthfully names the
+        // native field simply `customer`. Re-running that field through generic
+        // lexical scoring loses the authoritative host binding and makes an
+        // executable legacy capability look unmodeled. Reuse only the exact host
+        // frame rank entity, and only after the selected capability proves every
+        // required role. This is not a name-based fallback and cannot select
+        // Customer Type, Customer Owner, or a cross-model same-leaf field.
+        const hostRankEntityDimensionId = hostEntityDisplayTerms.has(normalizedRequested)
+            ? input.resolution.analyticalFrame?.ranking?.entityDimensionId
+            : undefined;
+        const hostRankEntityDimension = hostRankEntityDimensionId
+            ? selectedCapability?.dimensions.find((dimension) => dimension.dimensionId === hostRankEntityDimensionId)
+            : undefined;
+        if (hostRankEntityDimension && roles.every((role) => hostRankEntityDimension.supportedRoles.includes(role))) {
+            return {
+                requested,
+                qualifiedId: hostRankEntityDimension.dimensionId,
+                status: 'resolved',
+                candidateIds: [hostRankEntityDimension.dimensionId],
+            };
+        }
+        // The host-built V2 frame may intentionally retain a genuine native
+        // display-key ambiguity (for example Billing Account versus Service
+        // Account). Keep that exact, metric-owned choice set when RAP binds the
+        // same seeded phrase. Re-running it through lexical candidate matching
+        // would discard the qualified alternatives and turn a useful
+        // clarification into a false “unresolved” gap. The frame is already
+        // snapshot-bound; still require the selected capability to prove every
+        // requested role before carrying a choice forward.
+        const sourceAmbiguity = input.resolution.analyticalFrame?.ambiguity.find((entry) => {
+            const [lane, ...parts] = entry.field.split('.');
+            return lane === 'dimensions' && normalize(parts.join('.')) === normalizedRequested;
+        });
+        const sourceChoices = uniqueSorted((sourceAmbiguity?.candidateIds ?? []).filter((candidateId) => eligibleCapabilityDimensions(selectedCapability, roles)
+            .some((dimension) => dimension.dimensionId === candidateId)));
+        if (sourceChoices.length === 1) {
+            return {
+                requested,
+                qualifiedId: sourceChoices[0],
+                status: 'resolved',
+                candidateIds: sourceChoices,
+            };
+        }
+        if (sourceChoices.length > 1) {
+            return {
+                requested,
+                status: 'ambiguous',
+                candidateIds: sourceChoices,
+            };
+        }
+        // An exact certified block is its own execution authority. Its declared
+        // output contract may use the entity identity (`customer`) where the
+        // host-owned ranking seed deliberately retains the display phrase
+        // (`customer name`). Do not let the optional normalized semantic
+        // capability re-run that proven block output through lexical capability
+        // matching: the capability is context for the block, while the block's
+        // declared output is the certified proof. This remains narrow to the
+        // selected compatible block and cannot bind an unrelated retrieved field.
+        const certifiedOutput = selectedCertifiedBlock
+            ? certifiedCandidateDeclaredDimensionOutput(selectedCertifiedBlock, requested)
+            : undefined;
+        if (certifiedOutput && selectedCertifiedBlock)
+            return bindCertifiedDeclaredDimension(requested);
         const capabilityBinding = bindSelectedCapabilityDimension(requested, selectedCapability, roles, input.candidates);
         // A provider frame may describe a selected capability, but it cannot pick
         // one of that capability's grouping dimensions for the host. Once a
@@ -66,10 +198,8 @@ export function buildResolvedAnalyticalPlan(input) {
         }
         if (capabilityBinding && capabilityBinding.status !== 'unresolved')
             return capabilityBinding;
-        const normalizedRequested = normalize(requested);
         const frameIds = uniqueSorted((input.resolution.analyticalFrame?.dimensions ?? [])
             .filter((binding) => capabilityEntailsFrameDimension(selectedCapability, binding)
-            && (!selectedCapability || binding.role === 'time_axis')
             && memberTermMatches(normalize(binding.dimensionId), normalizedRequested))
             .map((binding) => binding.dimensionId));
         if (frameIds.length === 1) {
@@ -87,8 +217,68 @@ export function buildResolvedAnalyticalPlan(input) {
     const rankingRequested = input.resolution.questionType === 'ranking'
         || input.resolution.queryIntent.order !== undefined
         || input.resolution.queryIntent.limit !== undefined;
-    const dimensions = input.resolution.queryIntent.dimensions
-        .map((requested) => bindDimension(requested, rankingRequested ? ['group_by', 'rank_entity'] : ['group_by']));
+    // A ranked report can group by several dimensions, but exactly one of them
+    // is the entity being ranked. Requiring `rank_entity` on every grouping
+    // field made a complete tuple such as "top customers by product category"
+    // clarify because `product_type` correctly supports grouping but not being
+    // the ranked customer entity.
+    const rankEntityDimensionId = input.resolution.analyticalFrame?.ranking?.entityDimensionId;
+    const requiredDimensionRoles = (requested) => {
+        if (!rankingRequested)
+            return ['group_by'];
+        const rankEntity = selectedCapability?.dimensions.find((dimension) => dimension.dimensionId === rankEntityDimensionId);
+        const matchesHostEntityDisplay = hostEntityDisplayTerms.has(normalize(requested))
+            && Boolean(rankEntity && rankEntity.dimensionId === rankEntityDimensionId);
+        const matchesRankEntity = matchesHostEntityDisplay || Boolean(rankEntity && selectedCapability
+            && capabilityDimensionMatchScore(requested, rankEntity, selectedCapability, input.candidates) > 0);
+        return matchesRankEntity ? ['group_by', 'rank_entity'] : ['group_by'];
+    };
+    // The requirement seed is the immutable, host-owned tuple for a bounded
+    // meaning call.  Route reconciliation may still carry a legacy/broad
+    // `queryIntent` alongside that seed for compatibility, but it must never
+    // reintroduce an entity noun that the seed deliberately separated from its
+    // display/rank requirement.  For example, `top customers by product
+    // category` binds the host terms `customer name` and `product category`;
+    // a legacy `customer` dimension would make Customer Type and Customer Order
+    // Number compete with the metric-native Customer Name key after the frame
+    // had already resolved it.  Structured selections are merged into the
+    // seed before this point, so the seeded dimensions remain complete.
+    //
+    // An exact authored certified asset is a zero-provider host decision. Its
+    // direct router canonicalizes literal value wording (for example, “food and
+    // drink”) to the block's declared output (`category`) only after that exact
+    // block itself proved the requested measures and output contract. A model
+    // cannot reach this branch: candidate-ID meaning merge restores the host
+    // seed before RAP construction. Preserve this narrow canonical projection
+    // instead of turning a certified answer back into two invented dimensions.
+    // Unseeded V1/legacy callers retain their historical query-intent path.
+    const seededDimensionTerms = exactCertifiedDimensionProjection
+        ? input.resolution.queryIntent.dimensions
+        : input.resolution.hostRequirementSeed
+            ? input.resolution.hostRequirementSeed.queryIntent.dimensions
+            : input.resolution.queryIntent.dimensions;
+    // A server-issued clarification choice is a typed continuation binding. It
+    // may complete a display/grouping role that did not occur literally in the
+    // source question (for example “Show the top names by revenue” → Customer
+    // Name), but only after the router revalidated the stable choice against
+    // this snapshot. Candidate-ID model output cannot use this carrier.
+    const authoritativeDimensionTerms = [...new Set([
+            ...seededDimensionTerms,
+            ...(input.resolution.structuredDimensionIds ?? []),
+        ])];
+    const rawDimensions = authoritativeDimensionTerms
+        .map((requested) => bindDimension(requested, requiredDimensionRoles(requested)));
+    // The host-owned seed retains an entity display term (for example, "customer
+    // name") so a model cannot quietly turn "top customers" into an anonymous
+    // entity id.  Some authored semantic/certified capabilities deliberately
+    // expose that display role under the generic entity identity ("customer").
+    // In that case the label is not a second requested grouping dimension.  Keep
+    // it in the immutable seed/receipt, but remove only a redundant execution
+    // binding when the same resolved entity proves it, or an unresolved label
+    // when a resolved generic entity already covers the role.  A real explicit
+    // `by customer name` dimension remains untouched because it appears in the
+    // seed's ordinary dimensions as well as its display terms.
+    const dimensions = collapseHostEntityDisplayBindings(rawDimensions, input.resolution.hostRequirementSeed);
     // A provider may name the field it is grouping by and forget the MEMBER the
     // reader asked about: "What customer type is Wesley Jenkins?" came back with
     // `filters: []`, so the run returned all 200 customers and the narration
@@ -100,18 +290,52 @@ export function buildResolvedAnalyticalPlan(input) {
     // still win whenever it supplies any.
     const requestedFilters = input.resolution.queryIntent.filters.length > 0
         ? input.resolution.queryIntent.filters
-        : (input.evidence.parsedIntent?.filters ?? []).filter((filter) => filter.field && filter.value);
+        : (input.resolution.hostRequirementSeed?.queryIntent.filters
+            ?? currentQuestionGroundedParsedIntent(input.question, input.evidence.parsedIntent)?.filters
+            ?? []).filter((filter) => filter.field && filter.value);
     const filters = requestedFilters.map((filter) => ({
         ...filter,
         binding: bindDimension(filter.field, ['filter']),
     }));
-    const capabilityDimensionProof = resolvedCapabilityDimensionProof(selectedCapability, dimensions, filters);
-    const proofCandidates = [
-        ...selectedCandidates,
-        ...(executionCandidate && !selectedCandidates.some((candidate) => candidate.id === executionCandidate.id)
+    // Output terms are a distinct host-owned projection. A model may choose a
+    // qualified binding for one only from the admitted snapshot, but it cannot
+    // turn explicit `order ID` / `product ID` output terms into dimensions or
+    // omit them from an exploratory result contract.
+    //
+    // Host-owned output bindings have to come from the qualified meaning
+    // closure, not from the provisional route label. A meaning response may
+    // still carry the legacy `governed_sql` recommendation before the cascade
+    // proves whether the tuple is relational or exploratory. Re-opening the
+    // complete snapshot in that state turns unrelated `orders.order_id` /
+    // `raw_items.order_id` cards into false alternatives to the explicitly
+    // selected `order_items.order_id` output.
+    //
+    // If no meaning candidate was selected, preserve the legacy evidence path
+    // so a deterministic/certified binding can still explain a genuine gap.
+    // Once selection exists, however, only that snapshot-bound closure can
+    // satisfy a user-named output. The authorizer still proves target,
+    // read-only, relation, and exact-expression safety before SQL dispatch.
+    const outputBindingCandidates = selectedCandidates.length > 0
+        ? selectedCandidates
+        : executionCandidate
             ? [executionCandidate]
-            : []),
-    ];
+            : bindingCandidates;
+    const requiredOutputs = (input.resolution.hostRequirementSeed?.requirements.outputTerms ?? [])
+        .map((requested) => selectedCertifiedBlock
+        ? bindCertifiedDeclaredOutput(requested)
+        : bindRequestedMember(requested, outputBindingCandidates, 'output', input.question));
+    const outputAuthorityCandidates = requiredOutputs.flatMap((binding) => {
+        const ids = new Set([binding.qualifiedId, ...binding.candidateIds].filter((id) => Boolean(id)));
+        return input.candidates.filter((candidate) => ids.has(canonicalId(candidate)) || ids.has(candidate.id));
+    });
+    const frozenAuthorityCandidates = uniqueCandidatesByCanonicalId([
+        ...selectedCandidates,
+        ...(executionCandidate ? [executionCandidate] : []),
+        ...outputAuthorityCandidates,
+    ], canonicalId);
+    const selectedConceptIds = frozenAuthorityCandidates.map(canonicalId);
+    const capabilityDimensionProof = resolvedCapabilityDimensionProof(selectedCapability, dimensions, filters);
+    const proofCandidates = frozenAuthorityCandidates;
     const compatibilityProof = proofCandidates.map((candidate) => ({
         candidateId: canonicalId(candidate),
         compatibility: candidate.compatibility,
@@ -122,8 +346,8 @@ export function buildResolvedAnalyticalPlan(input) {
                 : []),
         ]),
     }));
-    const capability = resolveCapability(input.resolution, executionCandidate, measures, dimensions, filters);
-    const bindingGaps = bindingMissingInformation(measures, dimensions, filters);
+    const capability = resolveCapability(input.resolution, executionCandidate, measures, dimensions, filters, requiredOutputs, selectedCapability, frozenAuthorityCandidates, input.candidates);
+    const bindingGaps = bindingMissingInformation(measures, dimensions, filters, requiredOutputs);
     // The reader named a member that no grounding lane could bind. Answering the
     // question WITHOUT it silently changes what was asked — "what customer type
     // is Wesley Jenkins" became "list every customer" — so the plan carries it as
@@ -159,6 +383,15 @@ export function buildResolvedAnalyticalPlan(input) {
             snapshotId,
         })
         : [];
+    const governedRelationshipSafetyProofs = selectedCapability
+        && selectedExecutionCapability?.route === 'governed_sql'
+        ? buildGovernedRelationshipSafetyProofsV1({
+            capability: selectedCapability,
+            dimensions: capabilityDimensionProof,
+            candidates: input.candidates,
+            snapshotId,
+        })
+        : [];
     const payload = {
         schemaVersion: input.resolution.analyticalFrame
             ? 2
@@ -194,15 +427,17 @@ export function buildResolvedAnalyticalPlan(input) {
         entityGrain: selectedCapability
             ? resolvedCapabilityEntityGrain(selectedCapability, dimensions)
             : input.resolution.analyticalFrame?.entityGrainIds[0] ?? executionCandidate?.primaryEntity,
-        sourceRelationIds: uniqueSorted(selectedCandidates.flatMap((candidate) => candidate.sourceObjects ?? [])),
+        sourceRelationIds: uniqueSorted(frozenAuthorityCandidates.flatMap((candidate) => candidate.sourceObjects ?? [])),
         relationshipPathIds: selectedCapability
             ? uniqueSorted(relationshipProofs.flatMap((proof) => proof.kind === 'dql_relationship_path' ? proof.relationshipPathIds : []))
-            : uniqueSorted(selectedCandidates.flatMap((candidate) => candidate.relationshipEvidence ?? [])),
+            : uniqueSorted(frozenAuthorityCandidates.flatMap((candidate) => candidate.relationshipEvidence ?? [])),
         relationshipProofs,
+        governedRelationshipSafetyProofs,
         compatibilityProof,
         outputContract: {
             measures: uniqueSorted(measures.flatMap((binding) => binding.outputName ? [binding.outputName] : binding.qualifiedId ? [binding.qualifiedId] : [binding.requested])),
-            dimensions: uniqueSorted(dimensions.flatMap((binding) => binding.qualifiedId ? [binding.qualifiedId] : [binding.requested])),
+            dimensions: uniqueSorted(dimensions.flatMap((binding) => binding.outputName ? [binding.outputName] : binding.qualifiedId ? [binding.qualifiedId] : [binding.requested])),
+            requiredOutputs: requiredOutputs.map(cloneBinding),
             ...(input.resolution.queryIntent.timeGrain
                 ? { timeGrain: input.resolution.queryIntent.timeGrain }
                 : {}),
@@ -226,23 +461,23 @@ export function buildResolvedAnalyticalPlan(input) {
                     outcome: input.resolution.compatibilityOutcome
                         ?? (input.resolution.recommendedRoute === 'clarify' || input.resolution.confidence === 'low'
                             ? 'clarify'
-                            : bindingCandidateIds(measures, dimensions, filters).length > 0
+                            : bindingCandidateIds(measures, dimensions, filters, requiredOutputs).length > 0
                                 ? 'clarify'
                                 : 'modeling_gap'),
                     codes: uniqueSorted([
                         ...(input.resolution.compatibilityFailures ?? []).map((failure) => failure.code),
-                        ...bindingFailureCodes(measures, dimensions, filters),
+                        ...bindingFailureCodes(measures, dimensions, filters, requiredOutputs),
                     ]),
                     candidateIds: uniqueSorted([
                         ...(input.resolution.compatibilityFailures ?? []).flatMap((failure) => failure.candidateIds),
-                        ...bindingCandidateIds(measures, dimensions, filters),
+                        ...bindingCandidateIds(measures, dimensions, filters, requiredOutputs),
                     ]),
                     ...(selectedCapability?.metricId
                         ? { selectedCapabilityId: selectedCapability.metricId }
                         : {}),
                     ...(executionId ? { selectedExecutionId: executionId } : {}),
                     finalCapability: capability,
-                    bindings: unresolvedBindingReceipts(measures, dimensions, filters),
+                    bindings: unresolvedBindingReceipts(measures, dimensions, filters, requiredOutputs),
                 },
             }
             : {}),
@@ -410,13 +645,31 @@ function eligibleCapabilityDimensions(capability, requiredRoles) {
         if (!requiredRoles.every((role) => dimension.supportedRoles.includes(role)))
             return false;
         const sameEntity = dimension.entityId === capability.primaryEntityId;
-        const declaredGrain = capability.resultGrainIds.includes(dimension.entityId);
-        const relationshipProven = (dimension.relationshipPathIds?.length ?? 0) > 0;
-        const nativeGroupingProven = Boolean(dimension.nativeGroupingReference)
-            && capability.executionCapabilities.some((execution) => execution.route === 'semantic');
-        return sameEntity || declaredGrain || relationshipProven || nativeGroupingProven;
+        // A semantic metric may only use a cross-model dimension when the
+        // capability carries the exact adapter-native grouping reference which
+        // the compiler can consume. Result-grain membership and a generic DQL
+        // relationship ID prove neither MetricFlow spelling nor semantic adapter
+        // reachability, so they must not admit a semantic freeze on their own.
+        // Non-semantic routes retain their separately governed relationship
+        // authority below.
+        const semanticNativeGroupingProven = semanticNativeGroupingIsExact(capability, dimension);
+        const nonSemanticRoute = capability.executionCapabilities.some((execution) => execution.route !== 'semantic');
+        const relationalProof = nonSemanticRoute
+            && (capability.resultGrainIds.includes(dimension.entityId)
+                || (dimension.relationshipPathIds?.length ?? 0) > 0);
+        return sameEntity || semanticNativeGroupingProven || relationalProof;
     });
 }
+/**
+ * Verify a cross-model semantic grouping before it is allowed to bind the
+ * frozen plan. The capability is the only authority here: leaf-name equality,
+ * a broad result grain, and a physical/DQL relationship are intentionally not
+ * enough to claim MetricFlow can compose this tuple.
+ */
+function semanticNativeGroupingIsExact(capability, dimension) {
+    return dimension.entityId === capability.primaryEntityId
+        || semanticDimensionUsesExactAdapterGrouping(capability, dimension);
+}
 function capabilityEntailsFrameDimension(capability, binding) {
     if (!capability)
         return false;
@@ -461,11 +714,12 @@ function selectedCapabilityProofFacts(capability, dimensions) {
         ...capability.executionCapabilities.map((execution) => `capability:route:${execution.route}:${execution.adapterId ?? 'native'}`),
     ];
 }
-function unresolvedBindingReceipts(measures, dimensions, filters) {
+function unresolvedBindingReceipts(measures, dimensions, filters, requiredOutputs = []) {
     return [
         ...measures.map((binding) => ({ kind: 'measure', binding })),
         ...dimensions.map((binding) => ({ kind: 'dimension', binding })),
         ...filters.map((filter) => ({ kind: 'filter', binding: filter.binding })),
+        ...requiredOutputs.map((binding) => ({ kind: 'output', binding })),
     ]
         .filter(({ binding }) => binding.status !== 'resolved')
         .map(({ kind, binding }) => ({
@@ -475,19 +729,20 @@ function unresolvedBindingReceipts(measures, dimensions, filters) {
         candidateIds: [...binding.candidateIds],
     }));
 }
-function bindingCandidateIds(measures, dimensions, filters) {
-    return unresolvedBindingReceipts(measures, dimensions, filters)
+function bindingCandidateIds(measures, dimensions, filters, requiredOutputs = []) {
+    return unresolvedBindingReceipts(measures, dimensions, filters, requiredOutputs)
         .flatMap((binding) => binding.candidateIds);
 }
-function bindingFailureCodes(measures, dimensions, filters) {
-    return unresolvedBindingReceipts(measures, dimensions, filters)
+function bindingFailureCodes(measures, dimensions, filters, requiredOutputs = []) {
+    return unresolvedBindingReceipts(measures, dimensions, filters, requiredOutputs)
         .map((binding) => `${binding.kind.toUpperCase()}_${binding.status.toUpperCase()}`);
 }
-function bindingMissingInformation(measures, dimensions, filters) {
+function bindingMissingInformation(measures, dimensions, filters, requiredOutputs = []) {
     return [
         ...measures.map((binding) => ({ kind: 'measure', binding })),
         ...dimensions.map((binding) => ({ kind: 'dimension', binding })),
         ...filters.map((filter) => ({ kind: 'filter', binding: filter.binding })),
+        ...requiredOutputs.map((binding) => ({ kind: 'output', binding })),
     ].flatMap(({ kind, binding }) => {
         if (binding.status === 'resolved')
             return [];
@@ -523,6 +778,7 @@ export function deriveResolvedAnalyticalPlan(parent, delta) {
         ? (timeRange ? resolvePlanTimeRange(timeRange, delta.referenceTime ?? new Date()) : undefined)
         : parent.query.timeBounds;
     const unresolved = [...measures, ...dimensions, ...filters.map((filter) => filter.binding)]
+        .concat((parent.outputContract.requiredOutputs ?? []).map(cloneBinding))
         .filter((binding) => binding.status !== 'resolved');
     const payload = {
         ...parent,
@@ -544,7 +800,8 @@ export function deriveResolvedAnalyticalPlan(parent, delta) {
         },
         outputContract: {
             measures: uniqueSorted(measures.flatMap((binding) => binding.outputName ? [binding.outputName] : binding.qualifiedId ? [binding.qualifiedId] : [binding.requested])),
-            dimensions: uniqueSorted(dimensions.flatMap((binding) => binding.qualifiedId ? [binding.qualifiedId] : [binding.requested])),
+            dimensions: uniqueSorted(dimensions.flatMap((binding) => binding.outputName ? [binding.outputName] : binding.qualifiedId ? [binding.qualifiedId] : [binding.requested])),
+            requiredOutputs: (parent.outputContract.requiredOutputs ?? []).map(cloneBinding),
             ...((delta.timeGrain ?? parent.query.timeGrain)
                 ? { timeGrain: delta.timeGrain ?? parent.query.timeGrain }
                 : {}),
@@ -622,13 +879,32 @@ function bindRequestedMember(requested, candidates, kind, question = '') {
     // a second binding identity into the frozen plan. Only candidates still
     // eligible for the requested tuple can contribute member authority.
     const eligibleCandidates = candidates.filter((candidate) => candidate.compatibility !== 'incompatible');
-    const directCandidates = eligibleCandidates.filter((candidate) => {
+    const kindCandidates = eligibleCandidates.filter((candidate) => {
         const kindMatches = kind === 'measure'
             ? candidate.kind === 'semantic_metric' || candidate.kind === 'sql_column'
-            : candidate.kind === 'semantic_member' || candidate.kind === 'sql_column';
-        return kindMatches
-            && candidateTerms(candidate).some((term) => memberTermMatches(term, normalized));
+            : kind === 'dimension'
+                ? candidate.kind === 'semantic_member' || candidate.kind === 'sql_column'
+                // Explicit projected fields are not grouping dimensions. A metric can
+                // satisfy a requested price/revenue output only when it is selected as
+                // the measure; the projection lane itself accepts qualified members or
+                // physical columns.
+                : candidate.kind === 'semantic_member' || candidate.kind === 'sql_column';
+        return kindMatches;
     });
+    // Explicit outputs are a projection contract, not an approximate semantic
+    // search. Prefer a physical qualified column whose leaf is exactly the
+    // requested field. This keeps `product_id` from becoming an alternative for
+    // `order id` through a noisy alias and collapses duplicate cards for the
+    // same physical relation.column. Different exact physical columns remain
+    // distinct, so genuine ambiguity is still surfaced for clarification.
+    const exactOutputCandidates = kind === 'output'
+        ? exactOutputBindingCandidates(kindCandidates, normalized)
+        : [];
+    const directCandidates = kind === 'output'
+        ? exactOutputCandidates.length > 0 || isExplicitOutputIdentity(normalized)
+            ? exactOutputCandidates
+            : uniqueOutputBindingCandidates(kindCandidates.filter((candidate) => candidateTerms(candidate).some((term) => memberTermMatches(term, normalized))))
+        : kindCandidates.filter((candidate) => candidateTerms(candidate).some((term) => memberTermMatches(term, normalized)));
     const collectedIds = uniqueSorted([
         ...directCandidates.map((candidate) => candidate.qualifiedId ?? candidate.id),
         ...(kind === 'dimension' ? eligibleCandidates.flatMap((candidate) => (candidate.dimensions ?? []).filter((dimension) => {
@@ -667,12 +943,29 @@ function bindRequestedMember(requested, candidates, kind, question = '') {
             };
         }
     }
+    if (ids.length === 0 && (kind === 'dimension' || kind === 'output') && eligibleCandidates.length === 1) {
+        const certified = eligibleCandidates[0];
+        const outputName = certifiedCandidateDeclaredDimensionOutput(certified, requested);
+        if (certified.kind === 'certified_block'
+            && certified.compatibility === 'compatible'
+            && outputName) {
+            const id = certified.qualifiedId ?? certified.id;
+            return {
+                requested,
+                qualifiedId: id,
+                outputName,
+                status: 'resolved',
+                candidateIds: [id],
+            };
+        }
+    }
     const namedWinner = memberNamedInQuestion(ids, eligibleCandidates, question);
     if (namedWinner) {
         const winnerCandidate = directCandidates.find((candidate) => (candidate.qualifiedId ?? candidate.id) === namedWinner);
         return {
             requested,
             qualifiedId: namedWinner,
+            ...(kind === 'output' ? { outputName: outputNameForCandidate(winnerCandidate, namedWinner) } : {}),
             ...(winnerCandidate?.aggregation ? { aggregation: winnerCandidate.aggregation } : {}),
             status: 'resolved',
             candidateIds: [namedWinner],
@@ -684,11 +977,85 @@ function bindRequestedMember(requested, candidates, kind, question = '') {
     return {
         requested,
         ...(ids.length === 1 ? { qualifiedId: ids[0] } : {}),
+        ...(kind === 'output' && ids.length === 1
+            ? { outputName: outputNameForCandidate(direct, ids[0]) }
+            : {}),
         ...(direct?.aggregation ? { aggregation: direct.aggregation } : {}),
         status: ids.length === 1 ? 'resolved' : ids.length > 1 ? 'ambiguous' : 'unresolved',
         candidateIds: ids,
     };
 }
+/**
+ * Return the exact host-authoritative output candidates for a requested
+ * projection. Physical columns win over descriptive semantic aliases: when a
+ * selected closure contains `order_items.order_id`, a semantic entity named
+ * `order_id` is useful retrieval context but is not a competing SQL output.
+ */
+function exactOutputBindingCandidates(candidates, requested) {
+    const exactPhysical = candidates.filter((candidate) => physicalOutputColumnLeaf(candidate) === requested);
+    if (exactPhysical.length > 0)
+        return uniqueOutputBindingCandidates(exactPhysical);
+    // Semantic projections do not always carry a physical column identity. They
+    // may still bind if their declared name itself is exact; aliases alone never
+    // have authority to substitute one requested identifier for another.
+    return uniqueOutputBindingCandidates(candidates.filter((candidate) => normalize(candidate.name) === requested));
+}
+/**
+ * A requested `... id` / `... identifier` must not fall back to lexical alias
+ * matching. In particular, an alias attached to product_id cannot make it a
+ * candidate for order_id when no actual order_id is selected.
+ */
+function isExplicitOutputIdentity(requested) {
+    return /(?:^| )(?:id|identifier)$/.test(requested);
+}
+function physicalOutputColumnLeaf(candidate) {
+    if (candidate.kind !== 'sql_column')
+        return undefined;
+    const raw = candidate.qualifiedId ?? candidate.id;
+    const columnReference = raw.replace(/^(?:dbt|runtime):column:/i, '');
+    const leaf = columnReference.split('.').at(-1);
+    const normalized = normalize(leaf ?? '');
+    return normalized || undefined;
+}
+/**
+ * Candidate IDs can be emitted once by the dbt manifest and again by runtime
+ * schema/index lanes. They describe one output only when their canonical
+ * physical relation.column is identical. Do not dedupe two relations that
+ * merely share the same leaf: that remains a real ambiguity.
+ */
+function uniqueOutputBindingCandidates(candidates) {
+    const seen = new Set();
+    return candidates.filter((candidate) => {
+        const identity = canonicalOutputBindingIdentity(candidate);
+        if (seen.has(identity))
+            return false;
+        seen.add(identity);
+        return true;
+    });
+}
+function canonicalOutputBindingIdentity(candidate) {
+    if (candidate.kind === 'sql_column') {
+        const raw = candidate.qualifiedId ?? candidate.id;
+        const columnReference = raw.replace(/^(?:dbt|runtime):column:/i, '');
+        if (columnReference.includes('.'))
+            return `physical:${normalize(columnReference)}`;
+    }
+    return `candidate:${candidate.qualifiedId ?? candidate.id}`;
+}
+/**
+ * A selected physical/semantic output's alias is part of the frozen result
+ * contract. Prefer the inspected candidate name; a qualified-id leaf is a
+ * safe fallback for machine-authored dbt/sql column identities.
+ */
+function outputNameForCandidate(candidate, qualifiedId) {
+    const candidateName = candidate?.name?.trim();
+    if (candidateName && /^[A-Za-z_][A-Za-z0-9_]*$/.test(candidateName))
+        return candidateName;
+    const leaf = qualifiedId.split(/[:.]/).at(-1)?.replace(/[^A-Za-z0-9_]/g, '_');
+    return leaf && /^[A-Za-z_][A-Za-z0-9_]*$/.test(leaf)
+        ? leaf
+        : normalize(candidateName || qualifiedId).replace(/\s+/g, '_');
+}
 function qualifyDeclaredDimension(candidate, dimension) {
     if (/[:./]/.test(dimension) || !candidate.domain)
         return dimension;
@@ -696,9 +1063,6 @@ function qualifyDeclaredDimension(candidate, dimension) {
     const local = dimension.toLowerCase().replace(/[^a-z0-9_-]+/g, '_');
     return `semantic:${domain}:dimension:${local}`;
 }
-function resolutionUsesRelationalEvidence(resolution) {
-    return resolution.recommendedRoute === 'governed_sql' || resolution.recommendedRoute === 'exploratory';
-}
 function memberTermMatches(candidateTerm, requested) {
     if (candidateTerm === requested || candidateTerm.endsWith(` ${requested}`))
         return true;
@@ -711,7 +1075,7 @@ function candidateTerms(candidate) {
         .map(normalize)
         .filter(Boolean);
 }
-function resolveCapability(resolution, execution, measures, dimensions, filters) {
+function resolveCapability(resolution, execution, measures, dimensions, filters, requiredOutputs = [], selectedCapability, frozenAuthorityCandidates = [], snapshotCandidates = []) {
     if (resolution.confidence === "low" ||
         resolution.recommendedRoute === "clarify" ||
         !execution ||
@@ -728,24 +1092,329 @@ function resolveCapability(resolution, execution, measures, dimensions, filters)
         (resolution.recommendedRoute === "certified" ||
             resolution.recommendedRoute === "semantic"))
         return "blocked";
+    // A frozen plan may not silently drop an explicitly requested projection.
+    // This applies to exploratory SQL too: otherwise a query can execute and
+    // display five rows that omit one of the user-named identifiers.
+    if (requiredOutputs.some((binding) => binding.status !== 'resolved'))
+        return 'blocked';
     if (execution.compatibility === "incompatible")
         return "blocked";
     if (resolution.recommendedRoute === "certified" &&
         execution.kind === "certified_block" &&
         execution.compatibility === "compatible" &&
-        certifiedCandidateExplicitlyCoversMeasures(execution, measures.map((binding) => binding.requested))) {
+        certifiedCandidateExplicitlyCoversMeasures(execution, measures.map((binding) => binding.requested)) &&
+        certifiedBlockProvesHostProjection(execution, resolution)) {
         return "certified_execution";
     }
     if (resolution.recommendedRoute === 'semantic'
         && (execution.kind === 'semantic_metric' || execution.kind === 'semantic_member')
-        && execution.compatibility === 'compatible')
+        && semanticCapabilitiesProveFrozenTuple({
+            capability: selectedCapability,
+            measures,
+            dimensions,
+            filters,
+            requiredOutputs,
+            timeGrain: resolution.queryIntent.timeGrain,
+            hasTimeRange: Boolean(resolution.queryIntent.timeRange),
+            candidates: frozenAuthorityCandidates,
+        })
+        && (execution.compatibility === 'compatible'
+            || sameSnapshotSemanticExtensionProvesFrozenTuple({
+                execution,
+                capability: selectedCapability,
+                measures,
+                dimensions,
+                filters,
+                requiredOutputs,
+                candidates: frozenAuthorityCandidates,
+                timeGrain: resolution.queryIntent.timeGrain,
+                hasTimeRange: Boolean(resolution.queryIntent.timeRange),
+            })))
         return 'semantic_execution';
-    if (resolution.recommendedRoute === 'governed_sql')
+    // A relationship/entity card and a qualified physical closure are useful
+    // evidence for exploratory SQL, but they are not themselves a governed DQL
+    // projection.  In particular, a DQL entity may bridge an order-items model
+    // to related business context while the selected tuple still consists only
+    // of dbt/runtime columns.  Freezing that as governed relational defers the
+    // first real eligibility check until the compiler, where it becomes a
+    // post-freeze COMPILATION_FAILED with no permitted fallback.
+    //
+    // Keep the boundary before freeze: governed relational execution requires a
+    // snapshot-declared capability with a concrete governed adapter and proof
+    // for every bound measure/dimension/filter/output.  A raw physical path is
+    // deliberately returned as blocked here so the router can evaluate its
+    // existing same-snapshot exploratory cascade, which rebuilds an immutable
+    // review-required plan with `recommendedRoute: exploratory`.
+    if (resolution.recommendedRoute === 'governed_sql'
+        // A partial DQL modeling card can contribute relationship context, but it
+        // cannot be the compiler authority for a frozen governed plan. In
+        // particular, an entity card that merely names an order-item grain must
+        // not turn selected dbt/runtime output columns into a governed DQL
+        // projection. It remains eligible evidence for the router's safe
+        // same-snapshot exploratory cascade below this pre-freeze gate.
+        && execution.compatibility === 'compatible'
+        && governedRelationalCapabilityProvesFrozenTuple({
+            capability: selectedCapability,
+            measures,
+            dimensions,
+            filters,
+            requiredOutputs,
+            timeGrain: resolution.queryIntent.timeGrain,
+            hasTimeRange: Boolean(resolution.queryIntent.timeRange),
+            snapshotCandidates,
+        }))
         return 'governed_relational';
     if (resolution.recommendedRoute === 'exploratory')
         return 'bounded_exploration';
     return 'blocked';
 }
+/**
+ * Governed relational compilation has a distinct authority boundary from
+ * physical SQL safety.  The latter can prove a read-only, review-required
+ * closure; it cannot mint a governed compiler projection.  Require the
+ * selected capability to declare the governed adapter and to prove the exact
+ * frozen tuple before the router is allowed to freeze this tier.
+ */
+function governedRelationalCapabilityProvesFrozenTuple(input) {
+    const { capability } = input;
+    if (!capability)
+        return false;
+    if (!capability.executionCapabilities.some((execution) => execution.route === 'governed_sql' && Boolean(execution.adapterId?.trim())))
+        return false;
+    const metricIds = new Set([capability.metricId, ...capability.measureIds]);
+    if (!input.measures.every((binding) => binding.status === 'resolved'
+        && Boolean(binding.qualifiedId)
+        && metricIds.has(binding.qualifiedId)))
+        return false;
+    const provesDimension = (binding, roles) => {
+        if (binding.status !== 'resolved' || !binding.qualifiedId)
+            return false;
+        const dimension = eligibleCapabilityDimensions(capability, roles)
+            .find((candidate) => candidate.dimensionId === binding.qualifiedId);
+        return Boolean(dimension
+            && governedCapabilityDimensionHasFreshAutomaticRelationshipProofV1({
+                capability,
+                dimension,
+                candidates: input.snapshotCandidates,
+            }));
+    };
+    if (!input.dimensions.every((binding) => provesDimension(binding, ['group_by'])))
+        return false;
+    if (!input.filters.every((filter) => provesDimension(filter.binding, ['filter'])))
+        return false;
+    // An explicit output is a host-owned result-contract field, not an
+    // implication of a physical relation. A `declaredOutputIds` entry is not a
+    // compiler projection on its own: the governed compiler consumes metrics
+    // and grouped dimensions. Therefore a non-measure output must be the exact
+    // selected capability display/rank dimension *and* already be represented
+    // in the frozen grouped tuple. This keeps raw `order_id` / `product_id`
+    // columns and detached cross-entity display fields on the exploratory path
+    // unless the authored governed graph can actually compile them.
+    // Metrics follow the same rule: capability membership describes what could
+    // be compiled, while the frozen query measures describe what *will* be
+    // projected. A required `gross_profit` output may not piggyback on a
+    // selected `revenue` measure just because both live in the capability.
+    const groupedDimensionIds = new Set(input.dimensions
+        .flatMap((binding) => binding.qualifiedId ? [binding.qualifiedId] : []));
+    const projectedMeasureIds = new Set(input.measures
+        .filter((binding) => binding.status === 'resolved')
+        .flatMap((binding) => binding.qualifiedId ? [binding.qualifiedId] : []));
+    const provesOutput = (binding) => {
+        if (binding.status !== 'resolved' || !binding.qualifiedId)
+            return false;
+        if (metricIds.has(binding.qualifiedId))
+            return projectedMeasureIds.has(binding.qualifiedId);
+        if (!groupedDimensionIds.has(binding.qualifiedId))
+            return false;
+        return provesDimension(binding, ['display'])
+            || provesDimension(binding, ['rank_entity']);
+    };
+    if (!input.requiredOutputs.every(provesOutput))
+        return false;
+    if (input.timeGrain && !capability.timeDimensions.some((dimension) => dimension.supportedGrains.some((grain) => normalize(grain) === normalize(input.timeGrain))))
+        return false;
+    return !input.hasTimeRange || capability.timeDimensions.length > 0;
+}
+/**
+ * A selected certified block must prove the host-owned projection itself.
+ * Contextual semantic capability metadata is useful corroboration, but it is
+ * never authority to add an entity label, grouping field, or explicit output
+ * that the block does not declare. This defensive freeze gate covers paths
+ * where a binding was collapsed/projected before capability resolution.
+ */
+function certifiedBlockProvesHostProjection(block, resolution) {
+    const seed = resolution.hostRequirementSeed;
+    if (!seed)
+        return true;
+    const projectedDimensions = certifiedBlockCanUseExactCanonicalDimensionProjection(block, resolution)
+        ? resolution.queryIntent.dimensions
+        : seed.queryIntent.dimensions;
+    const terms = uniqueSorted([
+        ...projectedDimensions,
+        ...seed.requirements.entityDisplayTerms,
+        ...(seed.requirements.outputTerms ?? []),
+    ].map(normalize).filter(Boolean));
+    return terms.every((term) => Boolean(certifiedCandidateDeclaredDimensionOutput(block, term)
+        || certifiedCandidateDeclaredMeasureOutput(block, term)));
+}
+function certifiedBlockCanUseExactCanonicalDimensionProjection(block, resolution) {
+    const seed = resolution.hostRequirementSeed;
+    return Boolean(seed
+        && resolution.recommendedRoute === 'certified'
+        && block?.kind === 'certified_block'
+        && block.exactMatch
+        && block.compatibility === 'compatible'
+        && block.analyticalFitClass === 'exact'
+        && certifiedCandidateExplicitlyCoversMeasures(block, resolution.queryIntent.measures)
+        && resolution.queryIntent.dimensions.length > 0
+        && resolution.queryIntent.dimensions.every((dimension) => Boolean(certifiedCandidateDeclaredDimensionOutput(block, dimension)))
+        && !sameNormalizedTerms(resolution.queryIntent.dimensions, seed.queryIntent.dimensions));
+}
+/**
+ * The semantic route may freeze only after the exact frozen tuple can be
+ * expressed by the selected semantic adapter. A metric-relative native
+ * grouping reference is required for every cross-model dimension/filter.
+ * Same-model dimensions are already a declared group-by on the metric model.
+ */
+function semanticCapabilityProvesFrozenTuple(input) {
+    const { capability } = input;
+    // Metric-free semantic member lookups retain their existing exact registry
+    // path. A metric tuple, however, must have a normalized capability.
+    if (!capability)
+        return input.measures.length === 0;
+    if (!capability.executionCapabilities.some((execution) => execution.route === 'semantic' && Boolean(execution.adapterId?.trim())))
+        return false;
+    const metricIds = new Set([capability.metricId, ...capability.measureIds]);
+    if (!input.measures.every((binding) => binding.status === 'resolved' && Boolean(binding.qualifiedId) && metricIds.has(binding.qualifiedId)))
+        return false;
+    const provesDimension = (binding, roles) => {
+        if (binding.status !== 'resolved' || !binding.qualifiedId)
+            return false;
+        const dimension = capability.dimensions.find((candidate) => candidate.dimensionId === binding.qualifiedId
+            && roles.every((role) => candidate.supportedRoles.includes(role)));
+        return Boolean(dimension && (dimension.entityId === capability.primaryEntityId
+            || semanticNativeGroupingIsExact(capability, dimension)));
+    };
+    if (!input.dimensions.every((binding) => provesDimension(binding, ['group_by'])))
+        return false;
+    if (!input.filters.every((filter) => provesDimension(filter.binding, ['filter'])))
+        return false;
+    // Explicit output projections are not grouping dimensions. They have their
+    // own frozen result contract and cannot be smuggled into a semantic tuple by
+    // a same-snapshot extension.
+    if (input.requiredOutputs.length > 0)
+        return false;
+    if (input.timeGrain && !capability.timeDimensions.some((dimension) => dimension.supportedGrains.some((grain) => normalize(grain) === normalize(input.timeGrain))))
+        return false;
+    return !input.hasTimeRange || capability.timeDimensions.length > 0;
+}
+/**
+ * A multi-metric semantic plan remains one immutable request frame, but each
+ * selected metric has to prove that frame independently before the route can
+ * freeze.  The first selected capability remains the stable execution anchor
+ * for backward-compatible receipts; it is never allowed to stand in for a
+ * second requested metric.  This closes the old single-capability shortcut
+ * where a multi-metric frame was marked blocked (or, worse, could later be
+ * compiled against only its first measure).
+ */
+function semanticCapabilitiesProveFrozenTuple(input) {
+    const resolvedMeasures = input.measures.filter((binding) => binding.status === 'resolved' && Boolean(binding.qualifiedId));
+    if (resolvedMeasures.length <= 1) {
+        return semanticCapabilityProvesFrozenTuple(input);
+    }
+    // Every requested metric must have a selected normalized capability.  The
+    // identity match is exact; aliases, matching leaves, or a correlated metric
+    // are not enough to enlarge the frozen tuple.
+    const capabilities = uniqueMetricCapabilities([
+        input.capability,
+        ...input.candidates.map((candidate) => normalizeMetricCapabilityContract(candidate.analyticalCapability)),
+    ]);
+    const selected = resolvedMeasures.map((measure) => {
+        const matches = capabilities.filter((capability) => capability.metricId === measure.qualifiedId
+            || capability.measureIds.includes(measure.qualifiedId));
+        return matches.length === 1 ? { measure, capability: matches[0] } : undefined;
+    });
+    if (selected.some((entry) => !entry))
+        return false;
+    const entries = selected;
+    const semanticRoutes = entries.map((entry) => entry.capability.executionCapabilities
+        .filter((route) => route.route === 'semantic' && Boolean(route.adapterId?.trim())));
+    if (semanticRoutes.some((routes) => routes.length !== 1))
+        return false;
+    const adapterId = semanticRoutes[0][0].adapterId;
+    if (!entries.every((entry, index) => semanticRoutes[index][0].adapterId === adapterId
+        && entry.capability.semanticModelId === entries[0].capability.semanticModelId))
+        return false;
+    return entries.every(({ measure, capability }) => semanticCapabilityProvesFrozenTuple({
+        capability,
+        measures: [measure],
+        dimensions: input.dimensions,
+        filters: input.filters,
+        requiredOutputs: input.requiredOutputs,
+        ...(input.timeGrain ? { timeGrain: input.timeGrain } : {}),
+        hasTimeRange: input.hasTimeRange,
+    }));
+}
+function uniqueMetricCapabilities(capabilities) {
+    const byFingerprint = new Map();
+    for (const capability of capabilities) {
+        if (!capability)
+            continue;
+        // The source fingerprint is the snapshot identity, not a metric identity:
+        // one semantic model can legitimately expose several requested metrics
+        // from the same immutable snapshot. A duplicate of the *same* metric can
+        // appear as selected execution and selected evidence, but must not turn
+        // that metric into an ambiguous capability choice.
+        byFingerprint.set(`${capability.sourceFingerprint}:${capability.metricId}`, capability);
+    }
+    return [...byFingerprint.values()];
+}
+/**
+ * Retrieval cards are scored before the role-balanced same-snapshot extension
+ * is admitted. A semantic metric can therefore retain `partial` even after
+ * the host has selected its one proven MetricFlow grouping field. Do not make
+ * `partial` generally executable: advance it only when the immutable frozen
+ * tuple proves the exact metric, every required role, and the extension's
+ * metric/dimension identity from the same snapshot.
+ *
+ * This is semantic-adapter authority only. It never authorizes a physical join
+ * or exploratory SQL, and an omitted output, unbound role, mismatched metric,
+ * mismatched dimension, unsupported time grain, or absent extension remains
+ * blocked for the cascade to evaluate safely.
+ */
+function sameSnapshotSemanticExtensionProvesFrozenTuple(input) {
+    const { execution, capability } = input;
+    if (execution.kind !== 'semantic_metric' || execution.compatibility !== 'partial' || !capability)
+        return false;
+    if (!semanticCapabilityProvesFrozenTuple(input))
+        return false;
+    // Explicit output terms have their own source-column result proof. A
+    // semantic role extension does not prove such an extra projection.
+    if (input.requiredOutputs.length > 0 || input.measures.length === 0)
+        return false;
+    const metricAuthorityIds = new Set([
+        execution.id,
+        execution.qualifiedId,
+        capability.metricId,
+        ...capability.measureIds,
+    ].filter((id) => Boolean(id)));
+    if (!input.measures.every((binding) => binding.status === 'resolved'
+        && Boolean(binding.qualifiedId)
+        && metricAuthorityIds.has(binding.qualifiedId)))
+        return false;
+    return input.candidates.some((candidate) => {
+        const extension = candidate.sameSnapshotRoleExtension;
+        if (!extension
+            || extension.version !== 1
+            || extension.role !== 'categorical_dimension'
+            || (extension.basis !== 'sole_metricflow_grouping_dimension'
+                && extension.basis !== 'exact_metricflow_grouping_dimension')
+            || !metricAuthorityIds.has(extension.metricId)
+            || (candidate.qualifiedId ?? candidate.id) !== extension.dimensionId)
+            return false;
+        return input.dimensions.some((binding) => binding.qualifiedId === extension.dimensionId);
+    });
+}
 function normalize(value) {
     return value.toLowerCase()
         .replace(/%/g, ' percentage ')
@@ -754,6 +1423,40 @@ function normalize(value) {
         .replace(/\s+/g, ' ')
         .trim();
 }
+/**
+ * Resolve a host-owned display-key requirement against a capability that uses
+ * the generic entity field as its declared display output.  This is a
+ * deterministic capability projection, not an interpretation of the user
+ * question and never mutates the requirement seed.
+ */
+function collapseHostEntityDisplayBindings(bindings, seed) {
+    if (!seed)
+        return bindings;
+    const displayOnlyTerms = new Set(seed.requirements.entityDisplayTerms
+        .map(normalize)
+        .filter((term) => term.length > 0 && !seed.requirements.dimensions.some((dimension) => normalize(dimension) === term)));
+    const entityTerms = seed.requirements.entityTerms.map(normalize).filter(Boolean);
+    if (displayOnlyTerms.size === 0 || entityTerms.length === 0)
+        return bindings;
+    const isEntityCompanion = (binding) => {
+        const requested = normalize(binding.requested);
+        return entityTerms.some((entity) => requested === entity || requested.startsWith(`${entity} `));
+    };
+    return bindings.filter((binding, index, all) => {
+        const requested = normalize(binding.requested);
+        if (!displayOnlyTerms.has(requested))
+            return true;
+        const companion = all.find((other, otherIndex) => otherIndex !== index && isEntityCompanion(other));
+        // An ambiguous generic entity is still the sole decision the reader must
+        // make. Do not add an unrelated "account name" unresolved gap beside the
+        // two qualified account choices.
+        if (!companion || companion.status === 'unresolved')
+            return true;
+        if (binding.status === 'unresolved')
+            return false;
+        return binding.status !== 'resolved' || binding.qualifiedId !== companion.qualifiedId;
+    });
+}
 /** Resolve common analytical ranges once so no executor reinterprets "last month". */
 export function resolvePlanTimeRange(expression, referenceTime) {
     const text = expression.trim().toLowerCase();
@@ -819,6 +1522,20 @@ function addUnits(value, unit, count) {
 function uniqueSorted(values) {
     return [...new Set(values.filter(Boolean))].sort();
 }
+function sameNormalizedTerms(left, right) {
+    const normalizeTerms = (values) => uniqueSorted(values.map(normalize));
+    return normalizeTerms(left).join('\u0000') === normalizeTerms(right).join('\u0000');
+}
+function uniqueCandidatesByCanonicalId(candidates, canonicalId) {
+    const seen = new Set();
+    return candidates.filter((candidate) => {
+        const id = canonicalId(candidate);
+        if (!id || seen.has(id))
+            return false;
+        seen.add(id);
+        return true;
+    });
+}
 function sha256(value) {
     return createHash('sha256').update(value).digest('hex');
 }