@duckcodeailabs/dql-agent 1.13.4 → 1.14.0

package/dist/resolved-analytical-plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolved-analytical-plan.d.ts","sourceRoot":"","sources":["../src/resolved-analytical-plan.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resolved-analytical-plan.d.ts","sourceRoot":"","sources":["../src/resolved-analytical-plan.ts"],"names":[],"mappings":"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"}

package/dist/resolved-analytical-plan.js

@@ -1,11 +1,14 @@
 /**
  * Immutable, snapshot-bound analytical plan shared by every downstream route.
- * The router emits it authoritatively by default. Shadow mode remains the
- * bounded route-level rollback switch while integration verification closes.
+ * The router emits it authoritatively by default. The `shadow` discriminator
+ * remains only for explicit dev/test comparison fixtures; production has no
+ * environment flag or request field that can select it.
  *
  * Acceptance: AGT-013, API-006.
  */
 import { createHash } from "node:crypto";
+import { normalizeMetricCapabilityContract, } from "@duckcodeailabs/dql-core";
+import { buildResolvedRelationshipProofsV1 } from './relationship-proof.js';
 export function buildResolvedAnalyticalPlan(input) {
     const byLegacyId = new Map(input.candidates.map((candidate) => [candidate.id, candidate]));
     const selectedCandidates = input.resolution.selectedConceptIds
@@ -13,18 +16,23 @@ export function buildResolvedAnalyticalPlan(input) {
     const executionCandidate = input.resolution.recommendedExecutionId
         ? byLegacyId.get(input.resolution.recommendedExecutionId)
         : selectedCandidates[0];
-    const bindingCandidates = resolutionUsesRelationalEvidence(input.resolution)
-        ? input.candidates
-        : selectedCandidates.length > 0
-            ? selectedCandidates
-            : executionCandidate
-                ? [executionCandidate]
-                : input.candidates;
+    const bindingCandidates = input.resolution.recommendedRoute === 'certified' && executionCandidate
+        // A deterministically compatible certified block has already proved the
+        // 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)
+            ? input.candidates
+            : selectedCandidates.length > 0
+                ? selectedCandidates
+                : executionCandidate
+                    ? [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.resolution.queryIntent.measures.map((requested) => bindRequestedMember(requested, bindingCandidates, 'measure', input.question))
         : selectedCandidates
             .filter((candidate) => candidate.kind === 'semantic_metric')
             .map((candidate) => ({
@@ -40,31 +48,123 @@ export function buildResolvedAnalyticalPlan(input) {
     const dimensionBindingCandidates = input.resolution.analyticalFrame
         ? input.candidates
         : bindingCandidates;
+    const selectedCapability = normalizeMetricCapabilityContract(executionCandidate?.analyticalCapability);
+    const bindDimension = (requested, roles) => {
+        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
+        // normalized capability supplies a relevant binding, its identifiers,
+        // roles, entity/grain and relationship proof are authoritative.
+        // A selected capability owns its grouping dimensions, but when it reports
+        // AMBIGUITY the question text can still settle it — and until it did, an
+        // answerable lookup stopped to ask.
+        if (capabilityBinding && capabilityBinding.status === 'ambiguous') {
+            const settled = memberNamedInQuestion(capabilityBinding.candidateIds, input.candidates, input.question);
+            if (settled)
+                return { ...capabilityBinding, qualifiedId: settled, status: 'resolved', candidateIds: [settled] };
+        }
+        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) {
+            return {
+                requested,
+                qualifiedId: frameIds[0],
+                status: 'resolved',
+                candidateIds: frameIds,
+            };
+        }
+        if (capabilityBinding)
+            return capabilityBinding;
+        return bindRequestedMember(requested, dimensionBindingCandidates, 'dimension', input.question);
+    };
+    const rankingRequested = input.resolution.questionType === 'ranking'
+        || input.resolution.queryIntent.order !== undefined
+        || input.resolution.queryIntent.limit !== undefined;
     const dimensions = input.resolution.queryIntent.dimensions
-        .map((requested) => bindRequestedMember(requested, dimensionBindingCandidates, 'dimension'));
-    const filters = input.resolution.queryIntent.filters.map((filter) => ({
+        .map((requested) => bindDimension(requested, rankingRequested ? ['group_by', 'rank_entity'] : ['group_by']));
+    // 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
+    // truthfully reported that his value was not present.
+    //
+    // DQL had already found him. `evidence.parsedIntent.filters` are GROUNDED
+    // member bindings — matched against the retrieved context, not guessed — so
+    // falling back to them adds no unproven predicate. The provider's own filters
+    // 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);
+    const filters = requestedFilters.map((filter) => ({
         ...filter,
-        binding: bindRequestedMember(filter.field, dimensionBindingCandidates, 'dimension'),
+        binding: bindDimension(filter.field, ['filter']),
     }));
-    const compatibilityProof = selectedCandidates.map((candidate) => ({
+    const capabilityDimensionProof = resolvedCapabilityDimensionProof(selectedCapability, dimensions, filters);
+    const proofCandidates = [
+        ...selectedCandidates,
+        ...(executionCandidate && !selectedCandidates.some((candidate) => candidate.id === executionCandidate.id)
+            ? [executionCandidate]
+            : []),
+    ];
+    const compatibilityProof = proofCandidates.map((candidate) => ({
         candidateId: canonicalId(candidate),
         compatibility: candidate.compatibility,
-        facts: [...(candidate.compatibilityFacts ?? [])].sort(),
+        facts: uniqueSorted([
+            ...(candidate.compatibilityFacts ?? []),
+            ...(candidate.id === executionCandidate?.id && selectedCapability
+                ? selectedCapabilityProofFacts(selectedCapability, capabilityDimensionProof)
+                : []),
+        ]),
     }));
     const capability = resolveCapability(input.resolution, executionCandidate, measures, dimensions, filters);
+    const bindingGaps = bindingMissingInformation(measures, dimensions, filters);
+    // 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
+    // a gap rather than dropping it. Live value lookup is opt-in per project, so
+    // the remedy is named here instead of leaving a bare failure.
+    const unboundMembers = filters.length === 0 ? (input.evidence.unboundMemberTerms ?? []) : [];
+    const unboundMemberGaps = unboundMembers.length > 0
+        ? [`The named value ${unboundMembers.map((term) => `“${term}”`).join(' and ')} could not be bound to a governed member, so it was not applied as a filter. Enable live value grounding (agent.runtimeValueGrounding.mode = "safe_automatic" with a searchSafeColumns allowlist) or filter on a modeled dimension.`]
+        : [];
+    const missingInformation = uniqueSorted([
+        ...input.resolution.missingInformation,
+        ...bindingGaps,
+        ...unboundMemberGaps,
+        ...(capability === 'blocked' && input.resolution.missingInformation.length === 0 && bindingGaps.length === 0
+            ? [`The selected ${input.resolution.recommendedRoute} capability is not executable for this analytical tuple.`]
+            : []),
+    ]);
     const timeBounds = input.resolution.queryIntent.timeRange
         ? resolvePlanTimeRange(input.resolution.queryIntent.timeRange, input.referenceTime ?? new Date())
         : undefined;
+    const snapshotId = input.evidence.knowledgeLens?.snapshotId
+        ?? input.evidence.snapshotId
+        ?? input.evidence.sourceFingerprint
+        ?? 'snapshot-unavailable';
+    const selectedExecutionCapability = selectedCapability?.executionCapabilities.find((candidate) => candidate.route === input.resolution.recommendedRoute);
+    const relationshipProofs = selectedCapability && selectedExecutionCapability && executionId
+        ? buildResolvedRelationshipProofsV1({
+            capability: selectedCapability,
+            dimensionIds: capabilityDimensionProof.map((dimension) => dimension.dimensionId),
+            route: selectedExecutionCapability.route,
+            ...(selectedExecutionCapability.adapterId ? { adapterId: selectedExecutionCapability.adapterId } : {}),
+            executionId,
+            snapshotId,
+        })
+        : [];
     const payload = {
         schemaVersion: input.resolution.analyticalFrame
             ? 2
             : 1,
-        mode: input.mode ?? "shadow",
+        mode: input.mode ?? "authoritative",
         revision: 0,
-        snapshotId: input.evidence.knowledgeLens?.snapshotId
-            ?? input.evidence.snapshotId
-            ?? input.evidence.sourceFingerprint
-            ?? 'snapshot-unavailable',
+        snapshotId,
         sourceFingerprint: input.evidence.sourceFingerprint,
         question: input.question,
         interpretedQuestion: input.resolution.interpretedQuestion,
@@ -72,6 +172,12 @@ export function buildResolvedAnalyticalPlan(input) {
         confidence: input.resolution.confidence,
         selectedConceptIds,
         executionId,
+        ...(selectedCapability
+            ? {
+                selectedCapability,
+                selectedCapabilityFingerprint: selectedCapability.sourceFingerprint,
+            }
+            : {}),
         recommendedRoute: input.resolution.recommendedRoute,
         capability,
         query: {
@@ -84,10 +190,14 @@ export function buildResolvedAnalyticalPlan(input) {
             ...(input.resolution.queryIntent.order ? { order: input.resolution.queryIntent.order } : {}),
             ...(input.resolution.queryIntent.limit !== undefined ? { limit: input.resolution.queryIntent.limit } : {}),
         },
-        entityGrain: input.resolution.analyticalFrame?.entityGrainIds[0] ??
-            executionCandidate?.primaryEntity,
+        entityGrain: selectedCapability
+            ? resolvedCapabilityEntityGrain(selectedCapability, dimensions)
+            : input.resolution.analyticalFrame?.entityGrainIds[0] ?? executionCandidate?.primaryEntity,
         sourceRelationIds: uniqueSorted(selectedCandidates.flatMap((candidate) => candidate.sourceObjects ?? [])),
-        relationshipPathIds: uniqueSorted(selectedCandidates.flatMap((candidate) => candidate.relationshipEvidence ?? [])),
+        relationshipPathIds: selectedCapability
+            ? uniqueSorted(relationshipProofs.flatMap((proof) => proof.kind === 'dql_relationship_path' ? proof.relationshipPathIds : []))
+            : uniqueSorted(selectedCandidates.flatMap((candidate) => candidate.relationshipEvidence ?? [])),
+        relationshipProofs,
         compatibilityProof,
         outputContract: {
             measures: uniqueSorted(measures.flatMap((binding) => binding.qualifiedId ? [binding.qualifiedId] : [binding.requested])),
@@ -107,8 +217,34 @@ export function buildResolvedAnalyticalPlan(input) {
             const retrieved = byLegacyId.get(candidate.id);
             return { id: retrieved ? canonicalId(retrieved) : candidate.id, reason: candidate.reason };
         }),
-        missingInformation: [...input.resolution.missingInformation],
+        missingInformation,
         clarification: input.resolution.clarifyingQuestion,
+        ...(capability === 'blocked'
+            ? {
+                resolutionFailure: {
+                    outcome: input.resolution.compatibilityOutcome
+                        ?? (input.resolution.recommendedRoute === 'clarify' || input.resolution.confidence === 'low'
+                            ? 'clarify'
+                            : bindingCandidateIds(measures, dimensions, filters).length > 0
+                                ? 'clarify'
+                                : 'modeling_gap'),
+                    codes: uniqueSorted([
+                        ...(input.resolution.compatibilityFailures ?? []).map((failure) => failure.code),
+                        ...bindingFailureCodes(measures, dimensions, filters),
+                    ]),
+                    candidateIds: uniqueSorted([
+                        ...(input.resolution.compatibilityFailures ?? []).flatMap((failure) => failure.candidateIds),
+                        ...bindingCandidateIds(measures, dimensions, filters),
+                    ]),
+                    ...(selectedCapability?.metricId
+                        ? { selectedCapabilityId: selectedCapability.metricId }
+                        : {}),
+                    ...(executionId ? { selectedExecutionId: executionId } : {}),
+                    finalCapability: capability,
+                    bindings: unresolvedBindingReceipts(measures, dimensions, filters),
+                },
+            }
+            : {}),
         knowledgeLens: input.evidence.knowledgeLens,
         ...((input.resolution.analyticalPolicyIds?.length ?? 0) > 0
             ? {
@@ -133,6 +269,233 @@ export function buildResolvedAnalyticalPlan(input) {
         fingerprint,
     });
 }
+/**
+ * The selected metric capability is the sole authority for metric-relative
+ * dimensions. Standalone member cards can help the model explain meaning, but
+ * cannot introduce a second execution binding or substitute a same-name ID.
+ */
+function bindSelectedCapabilityDimension(requested, capability, requiredRoles, candidates) {
+    if (!capability)
+        return undefined;
+    const eligible = eligibleCapabilityDimensions(capability, requiredRoles);
+    const exactIds = uniqueSorted(eligible
+        .filter((dimension) => dimension.dimensionId === requested)
+        .map((dimension) => dimension.dimensionId));
+    if (exactIds.length === 1) {
+        return {
+            requested,
+            qualifiedId: exactIds[0],
+            status: 'resolved',
+            candidateIds: exactIds,
+        };
+    }
+    const requestedEntityEvidence = candidates.filter((candidate) => candidate.semanticObjectType === 'entity'
+        && candidateTerms(candidate).some((term) => termMatchSpecificity(term, canonicalTokens(requested)) > 0));
+    const entityScoped = requestedEntityEvidence.length > 0
+        ? eligible.filter((dimension) => capabilityDimensionMatchesEntityEvidence(dimension, requestedEntityEvidence))
+        : [];
+    const bindingPool = entityScoped.length > 0 ? entityScoped : eligible;
+    const scored = bindingPool
+        .map((dimension) => ({
+        dimension,
+        score: capabilityDimensionMatchScore(requested, dimension, capability, candidates),
+    }))
+        .filter((match) => match.score > 0);
+    if (scored.length === 0) {
+        return {
+            requested,
+            status: 'unresolved',
+            // Role-compatible but semantically unrelated members are not choices a
+            // user can use to repair this binding. Keep the list empty so the router
+            // reports a modeling/binding gap instead of offering arbitrary booleans.
+            candidateIds: [],
+        };
+    }
+    const bestScore = Math.max(...scored.map((match) => match.score));
+    const matches = scored
+        .filter((match) => match.score === bestScore)
+        .map((match) => match.dimension);
+    const ids = uniqueSorted(matches.map((dimension) => dimension.dimensionId));
+    return {
+        requested,
+        ...(ids.length === 1 ? { qualifiedId: ids[0] } : {}),
+        status: ids.length === 1 ? 'resolved' : 'ambiguous',
+        candidateIds: ids,
+    };
+}
+function capabilityDimensionMatchScore(requested, dimension, capability, candidates) {
+    const requestedTokens = canonicalTokens(requested);
+    if (requestedTokens.length === 0)
+        return 0;
+    const evidenceTerms = candidates
+        .filter((candidate) => candidate.kind === 'semantic_member'
+        && candidate.semanticObjectType !== 'entity'
+        && (candidate.qualifiedId ?? candidate.id) === dimension.dimensionId)
+        .flatMap((candidate) => [candidate.name, ...(candidate.aliases ?? [])]);
+    const evidenceScore = Math.max(0, ...evidenceTerms.map((term) => termMatchSpecificity(term, requestedTokens)));
+    const authoredDisplayScore = Math.max(0, ...[dimension.label, ...(dimension.aliases ?? [])]
+        .filter((term) => Boolean(term))
+        .map((term) => termMatchSpecificity(term, requestedTokens)));
+    const localScore = termMatchSpecificity(localQualifiedLeaf(dimension.dimensionId), requestedTokens);
+    const conventionalIdentityScore = conventionalIdentitySpecificity(localQualifiedLeaf(dimension.dimensionId), requestedTokens);
+    const entityScore = termMatchSpecificity(localQualifiedLeaf(dimension.entityId), requestedTokens);
+    const identityScore = Math.max(evidenceScore > 0 ? 1_000 + evidenceScore : 0, authoredDisplayScore > 0 ? 900 + authoredDisplayScore : 0, conventionalIdentityScore > 0 ? 1_100 + conventionalIdentityScore : 0, localScore > 0 ? 600 + localScore : 0, entityScore > 0 ? 300 + entityScore : 0);
+    if (identityScore === 0)
+        return 0;
+    const authorityScore = (dimension.supportedRoles.includes('display') ? 8 : 0)
+        + (dimension.entityId === capability.primaryEntityId ? 4 : 0)
+        + (capability.resultGrainIds.includes(dimension.entityId) ? 4 : 0)
+        + ((dimension.relationshipPathIds?.length ?? 0) > 0 ? 4 : 0);
+    return identityScore + authorityScore;
+}
+function conventionalIdentitySpecificity(term, requestedTokens) {
+    const termTokens = canonicalTokens(term);
+    if (!requestedTokens.every((token) => termTokens.includes(token)))
+        return 0;
+    const remaining = termTokens.filter((token) => !requestedTokens.includes(token));
+    const identityDescriptors = new Set(['display', 'identifier', 'id', 'key', 'label', 'name', 'title']);
+    return remaining.length === 1 && identityDescriptors.has(remaining[0]) ? 100 : 0;
+}
+function capabilityDimensionMatchesEntityEvidence(dimension, entityCandidates) {
+    const ownerTokens = canonicalTokens(localQualifiedOwner(dimension.dimensionId));
+    return entityCandidates.some((candidate) => {
+        const candidateId = candidate.qualifiedId ?? candidate.id;
+        if (dimension.entityId === candidateId)
+            return true;
+        if (ownerTokens.length === 0)
+            return false;
+        const entityTerms = [candidate.name, ...(candidate.aliases ?? []), localQualifiedLeaf(candidateId)];
+        return entityTerms.some((term) => {
+            const tokens = canonicalTokens(localQualifiedLeaf(term));
+            return tokens.length > 0 && tokens.every((token) => ownerTokens.includes(token));
+        });
+    });
+}
+function termMatchSpecificity(term, requestedTokens) {
+    const termTokens = canonicalTokens(term);
+    if (termTokens.length === 0 || !requestedTokens.every((token) => termTokens.includes(token)))
+        return 0;
+    if (termTokens.length === requestedTokens.length
+        && termTokens.every((token, index) => token === requestedTokens[index]))
+        return 100;
+    return 50 + requestedTokens.length;
+}
+function canonicalTokens(value) {
+    return normalize(value)
+        .split(' ')
+        .filter(Boolean)
+        .map(singularizeBindingToken);
+}
+function singularizeBindingToken(value) {
+    if (value.length <= 4 || value.endsWith('ss') || value.endsWith('us') || value.endsWith('is'))
+        return value;
+    if (value.endsWith('ies'))
+        return `${value.slice(0, -3)}y`;
+    return value.endsWith('s') ? value.slice(0, -1) : value;
+}
+function localQualifiedLeaf(value) {
+    const leaf = value.split(/[:./]+/).filter(Boolean).at(-1);
+    return leaf ?? value;
+}
+function localQualifiedOwner(value) {
+    const local = value.split(':').at(-1) ?? value;
+    const segments = local.split(/[./]+/).filter(Boolean);
+    return segments.length > 1 ? segments[0] : '';
+}
+function eligibleCapabilityDimensions(capability, requiredRoles) {
+    if (!capability)
+        return [];
+    return capability.dimensions.filter((dimension) => {
+        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;
+    });
+}
+function capabilityEntailsFrameDimension(capability, binding) {
+    if (!capability)
+        return false;
+    if (binding.role === 'time_axis') {
+        return capability.timeDimensions.some((dimension) => dimension.dimensionId === binding.dimensionId);
+    }
+    return eligibleCapabilityDimensions(capability, [binding.role])
+        .some((dimension) => dimension.dimensionId === binding.dimensionId);
+}
+function resolvedCapabilityDimensionProof(capability, dimensions, filters) {
+    if (!capability)
+        return [];
+    const boundIds = new Set([
+        ...dimensions.flatMap((binding) => binding.qualifiedId ? [binding.qualifiedId] : []),
+        ...filters.flatMap((filter) => filter.binding.qualifiedId ? [filter.binding.qualifiedId] : []),
+    ]);
+    return capability.dimensions
+        .filter((dimension) => boundIds.has(dimension.dimensionId))
+        .sort((left, right) => left.dimensionId.localeCompare(right.dimensionId));
+}
+function resolvedCapabilityEntityGrain(capability, dimensions) {
+    const groupedIds = new Set(dimensions.flatMap((binding) => binding.qualifiedId ? [binding.qualifiedId] : []));
+    const groupedEntityIds = uniqueSorted(capability.dimensions
+        .filter((dimension) => groupedIds.has(dimension.dimensionId))
+        .map((dimension) => dimension.entityId));
+    if (groupedEntityIds.length === 1 && capability.resultGrainIds.includes(groupedEntityIds[0])) {
+        return groupedEntityIds[0];
+    }
+    return capability.defaultResultGrainId;
+}
+function selectedCapabilityProofFacts(capability, dimensions) {
+    return [
+        `capability:metric:${capability.metricId}`,
+        `capability:primary_entity:${capability.primaryEntityId}`,
+        `capability:default_result_grain:${capability.defaultResultGrainId}`,
+        ...capability.resultGrainIds.map((grain) => `capability:result_grain:${grain}`),
+        ...dimensions.map((dimension) => `capability:dimension:${dimension.dimensionId}:${dimension.entityId}`),
+        ...dimensions.flatMap((dimension) => dimension.nativeGroupingReference
+            ? [`capability:native_grouping:${dimension.dimensionId}:${dimension.nativeGroupingReference}`]
+            : []),
+        ...dimensions.flatMap((dimension) => (dimension.relationshipPathIds ?? []).map((relationshipId) => `capability:relationship:${relationshipId}`)),
+        ...capability.executionCapabilities.map((execution) => `capability:route:${execution.route}:${execution.adapterId ?? 'native'}`),
+    ];
+}
+function unresolvedBindingReceipts(measures, dimensions, filters) {
+    return [
+        ...measures.map((binding) => ({ kind: 'measure', binding })),
+        ...dimensions.map((binding) => ({ kind: 'dimension', binding })),
+        ...filters.map((filter) => ({ kind: 'filter', binding: filter.binding })),
+    ]
+        .filter(({ binding }) => binding.status !== 'resolved')
+        .map(({ kind, binding }) => ({
+        kind,
+        requested: binding.requested,
+        status: binding.status,
+        candidateIds: [...binding.candidateIds],
+    }));
+}
+function bindingCandidateIds(measures, dimensions, filters) {
+    return unresolvedBindingReceipts(measures, dimensions, filters)
+        .flatMap((binding) => binding.candidateIds);
+}
+function bindingFailureCodes(measures, dimensions, filters) {
+    return unresolvedBindingReceipts(measures, dimensions, filters)
+        .map((binding) => `${binding.kind.toUpperCase()}_${binding.status.toUpperCase()}`);
+}
+function bindingMissingInformation(measures, dimensions, filters) {
+    return [
+        ...measures.map((binding) => ({ kind: 'measure', binding })),
+        ...dimensions.map((binding) => ({ kind: 'dimension', binding })),
+        ...filters.map((filter) => ({ kind: 'filter', binding: filter.binding })),
+    ].flatMap(({ kind, binding }) => {
+        if (binding.status === 'resolved')
+            return [];
+        const choices = binding.candidateIds.length > 0
+            ? ` Qualified choices: ${binding.candidateIds.join(', ')}.`
+            : '';
+        return [`Requested ${kind} “${binding.requested}” is ${binding.status}.${choices}`];
+    });
+}
 /**
  * Apply an explicitly typed follow-up delta. No prose, prior SQL, or answer text
  * is inspected; every carried member remains a qualified binding from the root.
@@ -220,24 +583,74 @@ function cloneBinding(binding) {
 function cloneFilter(filter) {
     return { ...filter, binding: cloneBinding(filter.binding) };
 }
-function bindRequestedMember(requested, candidates, kind) {
+/**
+ * Disambiguate a member binding using the QUESTION TEXT.
+ *
+ * A planner (or a provider) often reduces "customer type" to the bare term
+ * `type`, and worse, may split it into two requested dimensions ("customer",
+ * "type"). A bare `type` then matches `customers.customer_type` AND
+ * `products.product_type` and reads as ambiguous, so an answerable question
+ * stops to ask which dimension was meant. The question already answers it:
+ * "customer type" appears in it and "product type" does not.
+ *
+ * Returns the single id the reader actually named, or undefined when the text
+ * does not settle it. Only multi-word names count — one shared token is not
+ * evidence.
+ */
+function memberNamedInQuestion(ids, candidates, question) {
+    if (ids.length < 2)
+        return undefined;
+    const questionText = normalize(question);
+    if (!questionText)
+        return undefined;
+    const named = ids.filter((id) => {
+        const candidate = candidates.find((item) => (item.qualifiedId ?? item.id) === id || item.id === id);
+        const terms = [candidate?.name ?? '', ...(candidate?.aliases ?? []), id.split(/[.:/]/).at(-1) ?? '']
+            .map((term) => normalize(String(term)))
+            .filter((term) => term.split(' ').length > 1);
+        return terms.some((term) => questionText === term
+            || questionText.startsWith(`${term} `)
+            || questionText.endsWith(` ${term}`)
+            || questionText.includes(` ${term} `));
+    });
+    return named.length === 1 ? named[0] : undefined;
+}
+function bindRequestedMember(requested, candidates, kind, question = '') {
     const normalized = normalize(requested);
-    const directCandidates = candidates.filter((candidate) => {
+    // A lexical decoy that compatibility already rejected must never introduce
+    // 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 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));
     });
-    const ids = uniqueSorted([
+    const collectedIds = uniqueSorted([
         ...directCandidates.map((candidate) => candidate.qualifiedId ?? candidate.id),
-        ...(kind === 'dimension' ? candidates.flatMap((candidate) => (candidate.dimensions ?? []).filter((dimension) => {
+        ...(kind === 'dimension' ? eligibleCandidates.flatMap((candidate) => (candidate.dimensions ?? []).filter((dimension) => {
             const value = normalize(dimension);
             return value === normalized || value.endsWith(` ${normalized}`);
         }).map((dimension) => qualifyDeclaredDimension(candidate, dimension))) : []),
     ]);
-    if (ids.length === 0 && kind === 'measure' && candidates.length === 1) {
-        const certified = candidates[0];
+    // A candidate contributes its qualified identity AND its own declared
+    // dimension list, so a dimension that IS the candidate arrived twice —
+    // `semantic:dimension:customers.customer_type` alongside a bare
+    // `customer_type`. Two ids read as ambiguous, the binding failed, and the
+    // plan blocked, which is why a metric-free attribute lookup could never
+    // freeze. A bare name that is the LEAF of a qualified id in the same set is
+    // the same member named twice, not a second choice.
+    const qualifiedIds = collectedIds.filter((id) => /[:./]/.test(id));
+    const ids = collectedIds.filter((id) => {
+        if (/[:./]/.test(id))
+            return true;
+        const bare = normalize(id);
+        return !qualifiedIds.some((qualified) => normalize(qualified.split(/[.:/]/).at(-1) ?? '') === bare);
+    });
+    if (ids.length === 0 && kind === 'measure' && eligibleCandidates.length === 1) {
+        const certified = eligibleCandidates[0];
         if (certified.kind === 'certified_block' && certified.compatibility === 'compatible') {
             const id = certified.qualifiedId ?? certified.id;
             return {
@@ -248,6 +661,17 @@ function bindRequestedMember(requested, candidates, kind) {
             };
         }
     }
+    const namedWinner = memberNamedInQuestion(ids, eligibleCandidates, question);
+    if (namedWinner) {
+        const winnerCandidate = directCandidates.find((candidate) => (candidate.qualifiedId ?? candidate.id) === namedWinner);
+        return {
+            requested,
+            qualifiedId: namedWinner,
+            ...(winnerCandidate?.aggregation ? { aggregation: winnerCandidate.aggregation } : {}),
+            status: 'resolved',
+            candidateIds: [namedWinner],
+        };
+    }
     const direct = ids.length === 1
         ? directCandidates.find((candidate) => (candidate.qualifiedId ?? candidate.id) === ids[0])
         : undefined;
@@ -316,7 +740,12 @@ function resolveCapability(resolution, execution, measures, dimensions, filters)
     return 'blocked';
 }
 function normalize(value) {
-    return value.toLowerCase().replace(/[_./:-]+/g, ' ').replace(/[^a-z0-9 ]+/g, ' ').replace(/\s+/g, ' ').trim();
+    return value.toLowerCase()
+        .replace(/%/g, ' percentage ')
+        .replace(/[_./:-]+/g, ' ')
+        .replace(/[^a-z0-9 ]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
 }
 /** Resolve common analytical ranges once so no executor reinterprets "last month". */
 export function resolvePlanTimeRange(expression, referenceTime) {