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

package/dist/router.js

@@ -22,7 +22,7 @@ import { buildResolvedAnalyticalPlan, } from "./resolved-analytical-plan.js";
 import { buildAnalyticalCascadeDecision, buildAnalyticalRequirementSeedV1, buildAnalyticalRequirementSet, categoricalDimensionRequirementTerms, candidateConflictsWithExplicitRankingMeasure, candidateMatchesCategoricalDimensionRequirement, evidenceCandidateRoles, isEntityAttributeCandidate, } from './analytical-orchestration.js';
 import { askTraceObserverForV1 } from './ask-observability/index.js';
 import { normalizeEvidenceAnalyticalCapability, solveAnalyticalCompatibility, } from "./analytical-compatibility.js";
-import { buildDeterministicAnalyticalFrame, projectResolvedAnalyticalFrame, resolveMetricCapabilityDimension, } from "./analytical-frame.js";
+import { buildDeterministicAnalyticalFrame, projectResolvedAnalyticalFrame, proveSameSnapshotMetricflowRoleExtensionV1, resolveMetricCapabilityDimension, } from "./analytical-frame.js";
 import { conversationHistoryFromContext, renderConversationEnvelopeForPrompt, } from "./conversation/snapshot.js";
 const DEFAULT_THRESHOLD = 0.7;
 const DEFAULT_CACHE_SIZE = 200;
@@ -195,7 +195,7 @@ function parseClassification(raw) {
         rationale,
     };
 }
-function buildMeaningSystemPrompt() {
+export function buildMeaningSystemPrompt() {
     return [
         "You resolve business meaning for DQL, a governed analytics system.",
         "The host already performed broad retrieval and supplied a host-owned requirement seed. Compare ONLY the supplied candidate cards against that seed.",
@@ -210,7 +210,7 @@ function buildMeaningSystemPrompt() {
         "`selectedConceptIds` is accepted only for legacy compatibility. All omitted optional fields receive host-owned safe defaults.",
     ].join("\n");
 }
-function buildMeaningUserPrompt(request, evidence, candidates, requirementSeed) {
+export function buildMeaningUserPrompt(request, evidence, candidates, requirementSeed) {
     const cards = candidates.map((candidate) => ({
         id: candidate.id,
         kind: candidate.kind,
@@ -222,6 +222,7 @@ function buildMeaningUserPrompt(request, evidence, candidates, requirementSeed)
         aggregation: compactText(candidate.aggregation, 120),
         domain: compactText(candidate.domain, 120),
         semanticModel: compactText(candidate.semanticModel, 160),
+        dataType: compactText(candidate.dataType, 80),
         primaryEntity: compactText(candidate.primaryEntity, 160),
         dimensions: compactArray(candidate.dimensions, 16, 120),
         timeGrains: compactArray(candidate.timeGrains, 8, 80),
@@ -469,6 +470,7 @@ function retrievalTrace(evidence, candidates) {
     return {
         ...(evidence.snapshotId ? { snapshotId: evidence.snapshotId } : {}),
         ...(evidence.sourceFingerprint ? { sourceFingerprint: evidence.sourceFingerprint } : {}),
+        ...(evidence.continuityFingerprint ? { continuityFingerprint: evidence.continuityFingerprint } : {}),
         candidateCount: candidates.length,
         candidateIds: candidates.map((candidate) => candidate.id),
         ...(candidateTraceMetadata.length ? { candidateTraceMetadata } : {}),
@@ -504,7 +506,12 @@ function traceSourceForCandidate(candidate) {
         return 'runtime_schema';
     return 'exploratory';
 }
-function traceCandidateLifecycleBeforePruning(request, evidence, candidates, packageCandidates) {
+/**
+ * Persist the immutable snapshot's candidate lifecycle for either the legacy
+ * router or AskAnalystRuntimeV1. This is an observability projection only: it
+ * cannot retrieve, rank, admit, or alter a program.
+ */
+export function recordAskCandidateLifecycleV1(request, evidence, candidates, packageCandidates) {
     const observer = askTraceObserverForV1(request);
     if (!observer.enabled)
         return;
@@ -522,9 +529,15 @@ function traceCandidateLifecycleBeforePruning(request, evidence, candidates, pac
         ...(requirements.dimensions.length ? ['categorical_dimension'] : []),
         ...(requirements.dimensions.length > 1 || requirements.entityTerms.length ? ['relationship'] : []),
     ]);
-    const candidateLimit = 32;
+    // Candidate lifecycle is an Advanced trace projection over the immutable
+    // prequalification/search backing pool. It intentionally has a larger cap
+    // than EvidenceWorkspaceV2 (32) so users can see a relevant candidate was
+    // pruned as `not_admitted` rather than falsely told it was absent. This
+    // projection is not an admission path: planner cards stay <=16 and the
+    // frozen execution closure stays <=32 plus an explicit bounded extension.
+    const rawCandidateTraceLimit = 80;
     const hasRequestedEntityLabel = requirements.entityTerms.length > 0 || requirements.entityDisplayTerms.length > 0;
-    for (const [index, candidate] of candidates.slice(0, candidateLimit).entries()) {
+    for (const [index, candidate] of candidates.slice(0, rawCandidateTraceLimit).entries()) {
         const roles = evidenceCandidateRoles(candidate);
         const source = traceSourceForCandidate(candidate);
         // This receipt must retain the actual retrieval memberships captured by
@@ -536,9 +549,13 @@ function traceCandidateLifecycleBeforePruning(request, evidence, candidates, pac
             || left.lane.localeCompare(right.lane));
         const lane = lanes?.[0]?.lane;
         const laneRank = lanes?.[0]?.rank;
-        const initialReason = candidate.exactMatch
-            ? 'exact_name_match'
-            : 'unknown';
+        const configuredRuntimeValueGroundingPin = candidate.matchReasons
+            .includes('host configured runtime value grounding pin');
+        const initialReason = configuredRuntimeValueGroundingPin
+            ? 'configured_runtime_value_grounding_pin'
+            : candidate.exactMatch
+                ? 'exact_name_match'
+                : 'unknown';
         const compatibilityCode = candidate.compatibility === 'compatible' ? 'compatible'
             : candidate.compatibility === 'incompatible' ? 'operation_unsupported'
                 : 'unknown';
@@ -582,15 +599,22 @@ function traceCandidateLifecycleBeforePruning(request, evidence, candidates, pac
             }
             if (packageIds.has(candidate.id)) {
                 const reservedForRole = requestedRoles.has(role);
+                const unresolvedRoleAdmission = candidate.matchReasons.some((reason) => reason.startsWith(`candidate_for_unresolved_role:${role}:`));
                 observer.recordCandidateDecision({
                     ...common,
                     decision: 'reserved',
-                    reasonCode: candidate.exactMatch ? 'exact_name_match' : reservedForRole ? 'role_reserved' : 'fused_relevance_fill',
+                    reasonCode: configuredRuntimeValueGroundingPin ? 'configured_runtime_value_grounding_pin'
+                        : candidate.exactMatch ? 'exact_name_match'
+                            : unresolvedRoleAdmission ? 'candidate_for_unresolved_role'
+                                : reservedForRole ? 'role_reserved' : 'fused_relevance_fill',
                 });
                 observer.recordCandidateDecision({
                     ...common,
                     decision: 'admitted',
-                    reasonCode: candidate.exactMatch ? 'exact_name_match' : reservedForRole ? 'role_reserved' : 'fused_relevance_fill',
+                    reasonCode: configuredRuntimeValueGroundingPin ? 'configured_runtime_value_grounding_pin'
+                        : candidate.exactMatch ? 'exact_name_match'
+                            : unresolvedRoleAdmission ? 'candidate_for_unresolved_role'
+                                : reservedForRole ? 'role_reserved' : 'fused_relevance_fill',
                 });
             }
             else {
@@ -845,6 +869,34 @@ function relationshipSafetyAllowsExploratoryJoin(safety, requiredJoinKey) {
     const lifecycleAllowsExploration = safety.status === 'certified'
         || safety.status === 'validated'
         || safety.status === 'draft';
+    // A local runtime may mint this *after* it has evaluated the immutable DQL
+    // relationship graph. It is not a weaker spelling of automaticJoinAllowed:
+    // it can only admit a declared same-domain draft/review edge to the
+    // review-required exploratory compiler. Keep generic retrieved evidence on
+    // the stricter validated/automatic route below.
+    const hostAttestedExploratory = safety.exploratoryJoinAllowed === true
+        && Boolean(safety.exploratoryPathFingerprint?.trim());
+    const lifecycleAllowsHostAttestedExploration = safety.status === 'draft'
+        || safety.status === 'evaluated'
+        || safety.status === 'review'
+        || safety.status === 'reviewed';
+    const keysAreUsable = safety.keys.length > 0
+        && safety.keys.every((key) => Boolean(key.from.trim() && key.to.trim()));
+    if (hostAttestedExploratory) {
+        if (!lifecycleAllowsHostAttestedExploration
+            || safety.staleCertification === true
+            || safety.fanout !== 'safe'
+            || !['one_to_one', 'one_to_many', 'many_to_one'].includes(safety.cardinality ?? '')
+            || !safety.from?.trim()
+            || !safety.to?.trim()
+            || !keysAreUsable)
+            return false;
+        if (!requiredJoinKey)
+            return true;
+        const normalizedKey = normalizeMetricPhrase(requiredJoinKey);
+        return safety.keys.some((key) => metricTermsMatch(normalizeMetricPhrase(key.from), normalizedKey)
+            || metricTermsMatch(normalizeMetricPhrase(key.to), normalizedKey));
+    }
     if (!lifecycleAllowsExploration
         || safety.staleCertification === true
         || safety.automaticJoinAllowed !== true
@@ -858,8 +910,7 @@ function relationshipSafetyAllowsExploratoryJoin(safety, requiredJoinKey) {
         || !validation.proofFingerprint?.trim()
         || !Number.isFinite(checkedAt)
         || expirationInvalid
-        || safety.keys.length === 0
-        || safety.keys.some((key) => !key.from.trim() || !key.to.trim()))
+        || !keysAreUsable)
         return false;
     if (!requiredJoinKey)
         return true;
@@ -867,6 +918,77 @@ function relationshipSafetyAllowsExploratoryJoin(safety, requiredJoinKey) {
     return safety.keys.some((key) => metricTermsMatch(normalizeMetricPhrase(key.from), normalizedKey)
         || metricTermsMatch(normalizeMetricPhrase(key.to), normalizedKey));
 }
+/**
+ * Resolve a card's complete same-snapshot relationship proof set.
+ *
+ * Every evidence edge must map to exactly one structured proof (an alias may
+ * perform that mapping); every supplied proof must be used by an evidence
+ * edge.  This rejects partial cards, unrelated safety records, and aliases
+ * that ambiguously name two proofs before a host-authored path card can carry
+ * them into planner context.  The router/compiler still revalidates the
+ * selected raw edges at freeze time.
+ */
+export function relationshipSafetyProofSelectionForCandidateV1(candidate) {
+    const evidenceByIdentity = new Map();
+    for (const rawEvidenceId of candidate.relationshipEvidence ?? []) {
+        const canonicalInput = rawEvidenceId.trim();
+        const identity = normalizedRelationshipIdentity(canonicalInput);
+        if (!identity)
+            return undefined;
+        // Duplicate spellings of the same input identity do not create another
+        // edge.  They are canonicalized below to the matched safety ID.
+        if (!evidenceByIdentity.has(identity))
+            evidenceByIdentity.set(identity, canonicalInput);
+    }
+    if (evidenceByIdentity.size === 0)
+        return undefined;
+    const proofs = candidate.relationshipSafety ?? [];
+    if (proofs.length === 0)
+        return undefined;
+    const matchedProofIndexes = new Set();
+    const matchedProofs = [];
+    for (const evidenceIdentity of evidenceByIdentity.keys()) {
+        const matches = proofs
+            .map((safety, index) => ({ safety, index }))
+            .filter(({ safety }) => {
+            // A canonical record without an ID cannot be safely serialized even
+            // if a loose alias happens to match the retrieval edge.
+            if (!safety.id?.trim())
+                return false;
+            return relationshipSafetyIdentities(safety).includes(evidenceIdentity);
+        });
+        // One evidence edge must identify one and only one canonical proof.  A
+        // duplicate ID, duplicate alias, or conflicting alias is unsafe rather
+        // than a tie the path-card builder may resolve heuristically.
+        if (matches.length !== 1)
+            return undefined;
+        const match = matches[0];
+        matchedProofIndexes.add(match.index);
+        if (!matchedProofs.some((proof) => proof === match.safety))
+            matchedProofs.push(match.safety);
+    }
+    // A card that carries an unrelated proof is not a compact proof set.  Do
+    // not silently discard it: the raw card may represent a stale/mixed
+    // snapshot and cannot become a trusted atomic planner path.
+    if (matchedProofIndexes.size !== proofs.length)
+        return undefined;
+    const proofClass = matchedProofs.every((safety) => relationshipSafetyAllowsAutomaticJoin(safety))
+        ? 'governed'
+        : matchedProofs.every((safety) => relationshipSafetyAllowsExploratoryJoin(safety))
+            ? 'exploratory'
+            : undefined;
+    if (!proofClass)
+        return undefined;
+    return {
+        proofClass,
+        relationshipEvidence: [...new Set(matchedProofs.map((safety) => safety.id.trim()))].sort(),
+        relationshipSafety: [...matchedProofs]
+            .sort((left, right) => left.id.localeCompare(right.id)),
+    };
+}
+export function relationshipSafetyProofClassForCandidateV1(candidate) {
+    return relationshipSafetyProofSelectionForCandidateV1(candidate)?.proofClass;
+}
 function relationshipSafetyAllowsJoin(safety, authority, requiredJoinKey) {
     return authority === 'governed'
         ? relationshipSafetyAllowsAutomaticJoin(safety, requiredJoinKey)
@@ -913,13 +1035,30 @@ function relationshipEndpointMatchesEntityTerms(endpoint, entityTerms) {
     const normalizedEndpoint = normalizeMetricPhrase(endpoint);
     return entityTerms.some((term) => metricTermsMatch(normalizedEndpoint, normalizeMetricPhrase(term)));
 }
+/**
+ * Modeling files commonly use local entity IDs for relationship endpoints while
+ * candidate cards retain the domain-qualified entity identity.  Relationship
+ * safety is only meaningful inside the declared relationship's domain, so
+ * bridge that representation here rather than falling back to an unscoped
+ * leaf-name match.  This helper is used exclusively by the attribution-policy
+ * graph below; it never authorizes a join.
+ */
+function scopedRelationshipEndpointIdentity(endpoint, relationship) {
+    const normalizedEndpoint = normalizedRelationshipIdentity(endpoint ?? '');
+    if (!normalizedEndpoint || normalizedEndpoint.includes('::entity::'))
+        return normalizedEndpoint;
+    const relationshipIdentity = relationshipSafetyIdentities(relationship)
+        .find((identity) => identity.includes('::relationship::'));
+    const domainPrefix = relationshipIdentity?.split('::relationship::')[0];
+    return domainPrefix ? `${domainPrefix}::entity::${normalizedEndpoint}` : normalizedEndpoint;
+}
 function relationshipGraphReaches(starts, targets, relationships) {
     if (starts.size === 0 || targets.size === 0)
         return false;
     const graph = new Map();
     for (const relationship of relationships) {
-        const from = normalizedRelationshipIdentity(relationship.from ?? '');
-        const to = normalizedRelationshipIdentity(relationship.to ?? '');
+        const from = scopedRelationshipEndpointIdentity(relationship.from, relationship);
+        const to = scopedRelationshipEndpointIdentity(relationship.to, relationship);
         if (!from || !to)
             continue;
         const fromNeighbors = graph.get(from) ?? new Set();
@@ -944,7 +1083,14 @@ function relationshipGraphReaches(starts, targets, relationships) {
     }
     return false;
 }
-function attributionRequiredRelationshipGapDecision(input) {
+/**
+ * Evaluate an attribution/allocation policy boundary from one immutable
+ * snapshot. AskAnalystRuntimeV1 invokes this before an optional provider
+ * meaning call: a declared denial is neither an ambiguity nor a provider
+ * failure. This helper only evaluates supplied evidence; it never retrieves
+ * additional context or executes a query.
+ */
+export function attributionRequiredRelationshipGapDecision(input) {
     if (!EXPLICIT_ATTRIBUTION_REQUEST_RE.test(input.request.question)
         || input.requirements.entityTerms.length === 0)
         return undefined;
@@ -969,8 +1115,8 @@ function attributionRequiredRelationshipGapDecision(input) {
         return undefined;
     const attributed = attributionRequired.find((relationship) => {
         const endpoints = [
-            normalizedRelationshipIdentity(relationship.from ?? ''),
-            normalizedRelationshipIdentity(relationship.to ?? ''),
+            scopedRelationshipEndpointIdentity(relationship.from, relationship),
+            scopedRelationshipEndpointIdentity(relationship.to, relationship),
         ].filter(Boolean);
         const requestedSignalEndpoints = new Set(endpoints.filter((endpoint) => relationshipEndpointMatchesQuestionConcept(endpoint, input.request.question)));
         if (requestedSignalEndpoints.size === 0)
@@ -982,7 +1128,17 @@ function attributionRequiredRelationshipGapDecision(input) {
         const allReachable = relationshipGraphReaches(requestedSignalEndpoints, targetEndpoints, relationships);
         const safeRelationships = relationships.filter((candidate) => relationshipSafetyAllowsAutomaticJoin(candidate));
         const safelyReachable = relationshipGraphReaches(requestedSignalEndpoints, targetEndpoints, safeRelationships);
-        return allReachable && !safelyReachable;
+        if (safelyReachable)
+            return false;
+        if (allReachable)
+            return true;
+        // The compact route workspace may omit an otherwise-safe continuation
+        // edge, but it must not erase a declared attribution boundary for the
+        // exact signal the user named.  We have already established a direct,
+        // snapshot-bound match for that signal and a requested entity.  Returning
+        // a typed modeling gap is safer than presenting unrelated metric choices
+        // or attempting an unapproved attribution join.
+        return true;
     });
     if (!attributed)
         return undefined;
@@ -1362,7 +1518,7 @@ function hasSafeExploratoryPhysicalPath(requirements, candidates, missingDimensi
 function preFreezePhysicalCascadeDecision(input) {
     // `candidates` can be the capped meaning package. Physical eligibility is
     // allowed one same-snapshot extension, never a new retrieval/domain scope.
-    const snapshotCandidates = immutableSnapshotCandidates(input.evidence, input.candidates);
+    const snapshotCandidates = targetScopedSameSnapshotCandidates(input.evidence, input.candidates, input.targetScope, input.executionCandidateIds);
     const physicalPath = hasSafeExploratoryPhysicalPath(input.requirements, snapshotCandidates, input.missingTerms, input.requiredPhysicalFieldTerms ?? []);
     const missingRankingMetric = Boolean(physicalPath.ok
         && input.requireRankingMetric
@@ -1429,14 +1585,17 @@ function preFreezePhysicalCascadeDecision(input) {
     const coverageFor = (source) => coverage.find((item) => item.source === source);
     const skippedAttempt = (tier, source) => {
         const item = coverageFor(source);
+        const semanticCompilerUnavailable = tier === 'semantic' && input.semanticTierUnavailable;
         return {
             version: 1,
             tier,
-            outcome: item?.status === 'available' ? 'ineligible' : 'unavailable',
+            outcome: semanticCompilerUnavailable || item?.status !== 'available' ? 'unavailable' : 'ineligible',
             candidateIds: item?.candidateIds ?? [],
-            reason: item?.status === 'available'
-                ? `The ${tier} tier did not prove the complete requested tuple before plan freeze.`
-                : `The ${tier} source was ${item?.status ?? 'unavailable'} in this snapshot.`,
+            reason: semanticCompilerUnavailable
+                ? 'The selected semantic compiler was unavailable before plan freeze.'
+                : item?.status === 'available'
+                    ? `The ${tier} tier did not prove the complete requested tuple before plan freeze.`
+                    : `The ${tier} source was ${item?.status ?? 'unavailable'} in this snapshot.`,
             planFrozen: false,
         };
     };
@@ -1535,7 +1694,7 @@ function preFreezePhysicalCascadeDecision(input) {
  * structured-continuation checks, while retaining a caller's server-issued
  * selection when it was supplied as a same-snapshot clarification card.
  */
-function immutableSnapshotCandidates(evidence, candidates) {
+function immutableSnapshotCandidates(evidence, candidates, executionCandidateIds) {
     const byId = new Map();
     for (const candidate of [
         ...evidence.candidates,
@@ -1545,7 +1704,41 @@ function immutableSnapshotCandidates(evidence, candidates) {
         if (!byId.has(candidate.id))
             byId.set(candidate.id, candidate);
     }
-    return [...byId.values()];
+    const snapshot = [...byId.values()];
+    if (!executionCandidateIds)
+        return snapshot;
+    const allowed = new Set(executionCandidateIds);
+    return snapshot.filter((candidate) => allowed.has(candidate.id) || allowed.has(candidate.qualifiedId ?? candidate.id));
+}
+/**
+ * The one permitted physical extension stays inside the already acquired
+ * snapshot and, when the active target is represented in source provenance,
+ * restricts physical cards to that target. This prevents a semantic target
+ * mismatch from being misreported as global schema absence while retaining
+ * relationship cards needed to prove a safe closure.
+ */
+function targetScopedSameSnapshotCandidates(evidence, candidates, targetScope, executionCandidateIds) {
+    const snapshot = immutableSnapshotCandidates(evidence, candidates, executionCandidateIds);
+    if (!targetScope)
+        return snapshot;
+    const normalized = targetScope.toLowerCase();
+    const physical = snapshot.filter((candidate) => candidate.kind === 'sql_table'
+        || candidate.kind === 'sql_column' || candidate.kind === 'dbt_model' || candidate.kind === 'dbt_source');
+    const scopedPhysical = physical.filter((candidate) => [
+        ...(candidate.sourceObjects ?? []),
+        candidate.provenance ?? '',
+        candidate.semanticModel ?? '',
+        candidate.domain ?? '',
+    ].some((value) => value.toLowerCase().includes(normalized)));
+    // Provenance often does not carry a connection name in older indexes. In
+    // that case retain the immutable snapshot rather than inventing absence.
+    if (scopedPhysical.length === 0)
+        return snapshot;
+    const scopedIds = new Set(scopedPhysical.map((candidate) => candidate.id));
+    return snapshot.filter((candidate) => !physical.includes(candidate)
+        || scopedIds.has(candidate.id)
+        || candidate.kind === 'dql_modeling'
+        || (candidate.relationshipEvidence?.length ?? 0) > 0);
 }
 /**
  * A normal meaning call may nominate either a semantic metric or a governed
@@ -1590,7 +1783,7 @@ function continuePreFreezeModelingGapThroughPhysicalSnapshot(input) {
     const physicalContinuation = preFreezePhysicalCascadeDecision({
         base: input.base,
         evidence,
-        candidates: immutableSnapshotCandidates(evidence, input.candidates),
+        candidates: immutableSnapshotCandidates(evidence, input.candidates, input.executionCandidateIds),
         question: input.question,
         requirements,
         missingTerms,
@@ -1599,6 +1792,7 @@ function continuePreFreezeModelingGapThroughPhysicalSnapshot(input) {
             ? 'The selected governed relational interpretation did not prove a compiler-owned DQL projection before plan freeze.'
             : 'The selected semantic interpretation was pre-freeze-ineligible for the complete requested tuple.',
         terminalCandidateIds: plan.selectedConceptIds,
+        ...(input.executionCandidateIds ? { executionCandidateIds: input.executionCandidateIds } : {}),
     });
     if (physicalContinuation.action === 'answer'
         && physicalContinuation.analyticalCascadeDecision?.selectedTier === 'exploratory_sql') {
@@ -1989,6 +2183,264 @@ function routeDecisionForResolution(base, evidence, candidates, resolution, sour
             : {}),
     };
 }
+/**
+ * Compiler-only bridge for AskAnalystRuntimeV1.  The runtime owns question
+ * framing, candidate admission, meaning selection, and the immutable program;
+ * this adapter only validates that selected program against existing safe
+ * certified/MetricFlow/relational/exploratory compilers.  It must never call a
+ * provider, retrieve a new snapshot, or nominate a different business meaning.
+ */
+export function compileAskAnalyticalProgramV1(input) {
+    const readiness = input.request.askAnalystTierReadiness;
+    // A compiler must never widen the program that the runtime froze.  A stale
+    // adapter-selected identity is a compilation failure, not an invitation to
+    // rank/retrieve/interpret the question again.
+    const executionCandidates = input.executionCandidates ?? input.candidates;
+    const executionIds = new Set(input.program.executionCandidateIds ?? input.program.candidateIds);
+    const executionCandidateIds = [...executionIds];
+    const isProgramExecutionCandidate = (candidate) => executionIds.has(candidate.id) || executionIds.has(candidate.qualifiedId ?? candidate.id);
+    if (executionCandidates.some((candidate) => !isProgramExecutionCandidate(candidate))) {
+        return immutableProgramBlocked(input.base, 'A compiler received a candidate outside the frozen Ask execution closure.');
+    }
+    const seedFilters = input.request.hostRequirementSeed?.queryIntent.filters ?? [];
+    if (!validProgramFilterBindings(input.program, seedFilters)) {
+        return immutableProgramBlocked(input.base, 'The immutable Ask program did not retain valid field, operator, and value bindings for every requested filter.');
+    }
+    const unboundCurrentQuestionLiterals = unboundProgramV3CurrentQuestionLiterals(input.program);
+    if (unboundCurrentQuestionLiterals.length > 0) {
+        // This is a normal pre-freeze analytical coverage gap, not an immutable
+        // program corruption or policy breach. The current question named a
+        // value, but no single selected qualified field/value binding survived
+        // verification. Reporting it as a typed gap prevents an unknown or
+        // ambiguous literal from broadening the SQL while preserving the ordinary
+        // cascade vocabulary for repair and trace rendering.
+        return currentQuestionLiteralCoverageGapDecision({
+            base: input.base,
+            evidence: input.evidence,
+            executionCandidates,
+            requirements: input.requirements,
+            program: input.program,
+            literals: unboundCurrentQuestionLiterals,
+        });
+    }
+    const programIds = new Set(input.program.candidateIds);
+    // The compiler receives the full frozen 32-card execution closure for
+    // relationship/physical compilation, but only the program's verified
+    // selected cards may authorize meaning. Do not treat closure membership as
+    // selection authority: that would let a tail candidate change the question
+    // after planner verification.
+    const programIdentityIds = new Set(input.candidates
+        .filter((candidate) => programIds.has(candidate.id) || programIds.has(candidate.qualifiedId ?? candidate.id))
+        .flatMap((candidate) => [candidate.id, candidate.qualifiedId].filter((id) => Boolean(id))));
+    const selectedIds = [
+        ...input.resolution.selectedConceptIds,
+        ...(input.resolution.recommendedExecutionId ? [input.resolution.recommendedExecutionId] : []),
+    ];
+    if (selectedIds.some((id) => !programIds.has(id) && !programIdentityIds.has(id))) {
+        return {
+            ...input.base,
+            action: 'block',
+            confidence: 1,
+            source: 'heuristic',
+            followsUp: false,
+            reason: 'The immutable Ask program did not authorize every selected compiler identity.',
+            terminalOutcome: {
+                kind: 'policy_blocked',
+                code: 'ANALYTICAL_POLICY_BLOCKED',
+                message: 'A compiler attempted to consume a candidate outside the frozen Ask program.',
+                candidateIds: selectedIds,
+            },
+        };
+    }
+    // `candidates` is the runtime-verified business tuple. The larger frozen
+    // execution closure is deliberately supplied only to the physical
+    // continuation below. Passing it into the semantic router lets a related
+    // metric or numeric attribute re-open meaning selection after program
+    // verification (for example Orders + Drink Orders + customer order number
+    // for the singular request "order count for each customer").
+    const selectedMeaningCandidates = input.candidates.filter((candidate) => programIds.has(candidate.id) || programIds.has(candidate.qualifiedId ?? candidate.id));
+    const decision = routeDecisionForResolution(input.base, input.evidence, selectedMeaningCandidates, input.resolution, 'heuristic', input.request.question, input.mode ?? 'authoritative');
+    // A material business choice is resolved before target readiness.  A target
+    // being unavailable does not make two independently valid semantic display
+    // meanings become one physical meaning; collapsing it first caused offline
+    // structured clarification/restart flows to report a false coverage gap.
+    // Once an immutable meaning is selected, readiness still advances an
+    // unavailable semantic target through the same-snapshot physical cascade.
+    if (decision.requiresClarification === true || decision.action === 'clarify') {
+        return decision;
+    }
+    // Connector/active-target readiness is recorded separately because it is an
+    // execution boundary, not necessarily a semantic *compiler* boundary. A
+    // native semantic plan can be proven and frozen from an authored local
+    // snapshot without a configured connection; execution then reports the
+    // normal post-freeze setup failure. Adapter/target binding for MetricFlow or
+    // another external semantic compiler is folded into semanticCompiler by the
+    // host readiness probe, so only that state authorizes pre-freeze fallback.
+    const semanticUnavailable = readiness?.semanticCompiler === 'unavailable';
+    // A semantic adapter/target mismatch is a pre-freeze availability result,
+    // not a modeling absence. A safe physical closure from this exact snapshot
+    // may still answer as review-required exploratory SQL.
+    if (semanticUnavailable && input.resolution.recommendedRoute === 'semantic') {
+        return preFreezePhysicalCascadeDecision({
+            base: input.base,
+            evidence: input.evidence,
+            candidates: executionCandidates,
+            question: input.request.question,
+            requirements: input.requirements,
+            missingTerms: [
+                ...input.requirements.measures,
+                ...input.requirements.dimensions,
+                ...input.requirements.entityTerms,
+                ...input.requirements.entityDisplayTerms,
+            ],
+            requiredPhysicalFieldTerms: [
+                ...input.requirements.measures,
+                ...input.requirements.dimensions,
+                ...input.requirements.entityTerms,
+                ...input.requirements.entityDisplayTerms,
+            ],
+            messagePrefix: 'The semantic compiler or active target was unavailable before plan freeze; DQL evaluated the same-snapshot safe physical path independently.',
+            terminalCandidateIds: input.resolution.selectedConceptIds,
+            ...(input.request.executionTarget?.target === 'connection' && input.request.executionTarget.connectionName
+                ? { targetScope: input.request.executionTarget.connectionName }
+                : {}),
+            executionCandidateIds,
+            semanticTierUnavailable: true,
+            requireRankingMetric: Boolean(input.requirements.ranking && input.requirements.ranking.metricTerms.length === 0),
+        });
+    }
+    // A selected semantic/governed plan may be invalid before it freezes. That
+    // is explicitly allowed to advance, but a frozen, denied, or unsafe plan is
+    // never silently downgraded.
+    return continuePreFreezeModelingGapThroughPhysicalSnapshot({
+        decision,
+        base: input.base,
+        evidence: input.evidence,
+        candidates: executionCandidates,
+        question: input.request.question,
+        executionCandidateIds,
+    });
+}
+function immutableProgramBlocked(base, message) {
+    return {
+        ...base,
+        action: 'block',
+        confidence: 1,
+        source: 'heuristic',
+        followsUp: false,
+        reason: message,
+        terminalOutcome: {
+            kind: 'policy_blocked',
+            code: 'ANALYTICAL_POLICY_BLOCKED',
+            message,
+            candidateIds: [],
+        },
+    };
+}
+function validProgramFilterBindings(program, seedFilters) {
+    if (program.filters.some((filter) => filter.fieldTerms.length === 0 || !filter.fieldTerms.every(Boolean) || !filter.value.trim() || filter.operator === 'unknown'))
+        return false;
+    // Direct compiler consumers from before AskAnalystRuntimeV1 do not carry a
+    // host requirement seed. They still must provide internally valid filters,
+    // but cannot be compared to a seed that was never supplied. Authoritative
+    // Ask always supplies one and therefore takes the exact-binding branch.
+    if (seedFilters.length === 0)
+        return true;
+    // A program with no predicate is valid only when the host seed also has no
+    // predicate. When a seed exists, exact normalized bindings make it
+    // impossible for a compiler to drop, broaden, or replace a user filter.
+    const normalize = (field, operator, value) => `${field.trim().toLowerCase()}|${operator.trim().toLowerCase()}|${value.trim().toLowerCase()}`;
+    const expected = seedFilters.map((filter) => normalize(filter.field, 'equals', filter.value)).sort();
+    const actual = program.filters
+        .map((filter) => filter.fieldTerms.map((field) => normalize(field, filter.operator, filter.value)))
+        .flat()
+        .sort();
+    return expected.length === actual.length && expected.every((value, index) => value === actual[index]);
+}
+/**
+ * V3 carries raw current-turn atoms specifically so an incomplete parser or
+ * compatibility adapter cannot erase a literal and allow a broad certified
+ * block to look complete. A literal must be represented by a frozen predicate
+ * before any compiler can select a tier. Prior-result anchors are distinct
+ * host-bound continuity evidence and therefore have their own source.
+ */
+function unboundProgramV3CurrentQuestionLiterals(program) {
+    if (program.version !== 3)
+        return [];
+    const normalize = (value) => value.trim().toLowerCase();
+    const frozenValues = new Set(program.filters.map((filter) => normalize(filter.value)));
+    const trustedValues = new Set(program.trustedTaskAnchors
+        .filter((anchor) => anchor.kind === 'member_binding' || anchor.kind === undefined)
+        .flatMap((anchor) => anchor.values)
+        .map(normalize));
+    return program.inputAtoms
+        .filter((atom) => atom.source === 'current_question' && atom.role === 'member')
+        .map((atom) => atom.term)
+        .filter((term) => !frozenValues.has(normalize(term)) && !trustedValues.has(normalize(term)));
+}
+/**
+ * A missing/ambiguous literal binding is an answerability gap, not evidence
+ * that the already-built program was tampered with. Keep it pre-freeze and
+ * show the actual terminal cause, so Ask can safely explain why it did not
+ * generate a broad exploratory query.
+ */
+function currentQuestionLiteralCoverageGapDecision(input) {
+    const normalize = (value) => value.trim().toLowerCase();
+    const literalSet = new Set(input.literals.map(normalize));
+    const matchingColumns = input.executionCandidates.filter((candidate) => candidate.kind === 'sql_column'
+        && evidenceCandidateRoles(candidate).includes('categorical_dimension')
+        && (candidate.safeValueEvidence ?? []).some((evidence) => literalSet.has(normalize(evidence.normalizedValue)) || literalSet.has(normalize(evidence.value))));
+    const qualifiedColumnIds = [...new Set(matchingColumns.map((candidate) => candidate.qualifiedId ?? candidate.id))].sort();
+    const ambiguity = qualifiedColumnIds.length > 1;
+    const literalLabel = input.literals.map((literal) => `“${literal}”`).join(', ');
+    const message = ambiguity
+        ? `The current-question value ${literalLabel} matched multiple qualified categorical fields in this metadata snapshot, so DQL did not choose or broaden a generated SQL filter.`
+        : `The current-question value ${literalLabel} was not verified on one selected qualified categorical field in this metadata snapshot, so DQL did not broaden a generated SQL filter.`;
+    const candidateIds = qualifiedColumnIds.length > 0
+        ? qualifiedColumnIds
+        : [...new Set(input.program.candidateIds)].sort();
+    const coverage = sourceCoverageFromEvidence(input.evidence, input.executionCandidates);
+    const attempts = [
+        { version: 1, tier: 'certified', outcome: 'ineligible', candidateIds: coverage.find((item) => item.source === 'certified')?.candidateIds ?? [], reason: 'A current-question literal is not bound in the frozen program.', planFrozen: false },
+        { version: 1, tier: 'semantic', outcome: 'ineligible', candidateIds: coverage.find((item) => item.source === 'semantic')?.candidateIds ?? [], reason: 'No selected semantic member binding proved the current literal.', planFrozen: false },
+        { version: 1, tier: 'governed_relational', outcome: 'unavailable', candidateIds: coverage.find((item) => item.source === 'governed_relational')?.candidateIds ?? [], reason: 'A relationship cannot bind an unverified literal value by itself.', planFrozen: false },
+        { version: 1, tier: 'exploratory_sql', outcome: 'unavailable', candidateIds: qualifiedColumnIds, reason: ambiguity ? 'More than one qualified physical field matched the literal.' : 'No selected qualified physical field had exact safe-value evidence for the literal.', planFrozen: false },
+        { version: 1, tier: 'clarify_or_gap', outcome: 'unavailable', candidateIds, reason: message, planFrozen: false },
+    ];
+    return {
+        ...input.base,
+        action: 'block',
+        confidence: 1,
+        followsUp: false,
+        source: 'heuristic',
+        category: 'data_lookup',
+        depth: 'quick',
+        reason: message,
+        requiresClarification: false,
+        retrievalEvidence: retrievalTrace(input.evidence, input.executionCandidates),
+        resolvedAnalyticalPlan: undefined,
+        analyticalCascadeDecision: buildAnalyticalCascadeDecision({
+            requirements: input.requirements,
+            sourceCoverage: coverage,
+            attempts,
+            planFrozen: false,
+            stopReason: 'coverage_gap',
+        }),
+        terminalOutcome: {
+            kind: 'modeling_gap',
+            code: 'ANALYTICAL_MODELING_GAP',
+            message,
+            candidateIds,
+            gap: {
+                code: 'MISSING_ATTRIBUTE',
+                missing: ambiguity
+                    ? ['one unambiguous qualified categorical field for the current-question value']
+                    : ['one qualified categorical field with exact safe-value evidence for the current-question value'],
+                witnessCandidateIds: candidateIds,
+            },
+        },
+    };
+}
 /**
  * A block may be relevant to a metric without returning that metric. When a
  * stale catalog result or provider selection nominates such a block, continue
@@ -2291,7 +2743,7 @@ function clarificationOptionsForQualifiedIds(ids, candidates, requirements) {
         .map(({ id, candidate }) => {
         return {
             id: candidate?.id ?? id,
-            label: candidate?.name || qualifiedIdLabel(candidate?.qualifiedId ?? id),
+            label: clarificationOptionLabel(candidate?.name, candidate?.qualifiedId ?? id),
             ...(candidate?.definition?.trim() ? { description: candidate.definition.trim() } : {}),
             kind: candidate?.kind ?? 'semantic_member',
         };
@@ -2301,6 +2753,19 @@ function qualifiedIdLabel(id) {
     const local = id.split(/[:./]/).filter(Boolean).at(-1) ?? id;
     return local.replace(/[_-]+/g, ' ').replace(/\b\w/g, (character) => character.toUpperCase());
 }
+/**
+ * Candidate names are canonical metadata values, not necessarily presentation
+ * labels. Keep a curated label intact, but humanize local snake/kebab names so
+ * a stable clarification never asks a business user to choose `account_name`.
+ */
+function clarificationOptionLabel(name, fallbackId) {
+    const trimmed = name?.trim();
+    if (!trimmed)
+        return qualifiedIdLabel(fallbackId);
+    return /[_-]/.test(trimmed)
+        ? trimmed.replace(/[_-]+/g, ' ').replace(/\b\w/g, (character) => character.toUpperCase())
+        : trimmed;
+}
 function routedClarificationQuestion(resolution, bindings, options) {
     if (resolution.clarifyingQuestion && !/^The analytical frame has unresolved ambiguity:/i.test(resolution.clarifyingQuestion)) {
         return resolution.clarifyingQuestion;
@@ -2636,8 +3101,8 @@ function buildClarificationOptions(candidates, requirements) {
         return {
             id: candidate.id,
             label: ambiguousName
-                ? `${candidate.name} (${candidateKindLabel(candidate.kind)})`
-                : candidate.name,
+                ? `${clarificationOptionLabel(candidate.name, candidate.qualifiedId ?? candidate.id)} (${candidateKindLabel(candidate.kind)})`
+                : clarificationOptionLabel(candidate.name, candidate.qualifiedId ?? candidate.id),
             ...(description ? { description } : {}),
             kind: candidate.kind,
         };
@@ -3251,6 +3716,7 @@ function preventDegenerateRankingResolution(resolution, evidence, candidates, qu
     if (hasExplicitRankingMeasure(question, evidence))
         return resolution;
     const selected = candidates.find((candidate) => candidate.id === resolution.recommendedExecutionId
+        || candidate.qualifiedId === resolution.recommendedExecutionId
         || resolution.selectedConceptIds.includes(candidate.id));
     if (!selected || !isDegenerateRankingMetric(question, evidence, selected))
         return resolution;
@@ -3280,25 +3746,64 @@ function preventDegenerateRankingResolution(resolution, evidence, candidates, qu
     };
 }
 function isSameSnapshotCategoricalExtensionForMetric(candidate, metricCandidate) {
-    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')
-        || candidate.kind !== 'semantic_member'
-        || (candidate.qualifiedId ?? candidate.id) !== extension.dimensionId)
-        return false;
-    const metricIds = new Set([
-        metricCandidate.id,
-        metricCandidate.qualifiedId,
-        normalizeEvidenceAnalyticalCapability(metricCandidate).capability?.metricId,
-    ].filter((id) => Boolean(id)));
-    if (!metricIds.has(extension.metricId))
-        return false;
+    return Boolean(proveSameSnapshotMetricflowRoleExtensionV1({ candidate, metricCandidate }));
+}
+/**
+ * A planner/runtime selection can name a semantic display card through its
+ * registry identity while the metric capability names the same field through
+ * its MetricFlow identity.  That is common for dbt MetricFlow exports:
+ * `semantic:dimension:customers.customer_name` is the selected registry card,
+ * while the metric declares
+ * `semantic:uncategorized:dimension:customers.customer_name` as its native
+ * grouping field.
+ *
+ * Do not reopen retrieval to bridge those forms.  When (and only when) the
+ * already-selected semantic member maps uniquely to an exact group-by
+ * dimension on the already-selected metric capability, record the
+ * same-snapshot proof on that selected card.  The existing semantic compiler
+ * still checks the normalized capability, additivity, and native grouping
+ * path before freezing.  This lets a complete singular tuple execute without
+ * permitting a correlated metric, a numeric order attribute, or any
+ * unselected workspace card to become meaning authority.
+ */
+function bindSelectedMetricFlowGroupingExtensions(metricCandidate, candidates) {
     const capability = normalizeEvidenceAnalyticalCapability(metricCandidate).capability;
-    return Boolean(capability?.dimensions.some((dimension) => dimension.dimensionId === extension.dimensionId
-        && dimension.supportedRoles.includes('group_by')));
+    if (!capability)
+        return candidates;
+    const normalizedIdentitySet = (candidate) => new Set([
+        candidate.id,
+        candidate.qualifiedId,
+        candidate.name,
+        ...(candidate.aliases ?? []),
+    ].filter((identity) => Boolean(identity)).map(normalizeMetricPhrase).filter(Boolean));
+    const dimensionIdentities = (dimension) => new Set([
+        dimension.dimensionId,
+        dimension.label,
+        ...(dimension.aliases ?? []),
+    ].filter((identity) => Boolean(identity)).map(normalizeMetricPhrase).filter(Boolean));
+    return candidates.map((candidate) => {
+        if (candidate.kind !== 'semantic_member'
+            || candidate.compatibility === 'incompatible'
+            || candidate.sameSnapshotRoleExtension)
+            return candidate;
+        const identities = normalizedIdentitySet(candidate);
+        const matchedDimensions = capability.dimensions.filter((dimension) => dimension.supportedRoles.includes('group_by')
+            && [...dimensionIdentities(dimension)].some((identity) => identities.has(identity)));
+        if (matchedDimensions.length !== 1)
+            return candidate;
+        const dimension = matchedDimensions[0];
+        return {
+            ...candidate,
+            sameSnapshotRoleExtension: {
+                version: 1,
+                role: 'categorical_dimension',
+                requestedTerm: candidate.name,
+                metricId: capability.metricId,
+                dimensionId: dimension.dimensionId,
+                basis: 'exact_metricflow_grouping_dimension',
+            },
+        };
+    });
 }
 /**
  * A model chooses from the bounded package, but it cannot remove a unique
@@ -3323,11 +3828,14 @@ function directResolution(request, evidence, candidate, candidates, selectedDime
     // model path. Raw parser terms are retrieval hints only: they may not turn a
     // normalized business alias back into a phantom metric or dimension after
     // the meaning boundary has been intentionally skipped.
-    const requirementSeed = buildAnalyticalRequirementSeedV1({
-        question: request.question,
-        parsedIntent: evidence.parsedIntent,
-        fiscalCalendar: declaredFiscalCalendar(evidence, candidates),
-    });
+    const requirementSeed = request.hostRequirementSeed?.version === 1
+        && request.hostRequirementSeed.sourceQuestion === request.question
+        ? request.hostRequirementSeed
+        : buildAnalyticalRequirementSeedV1({
+            question: request.question,
+            parsedIntent: evidence.parsedIntent,
+            fiscalCalendar: declaredFiscalCalendar(evidence, candidates),
+        });
     const hostOwnedEvidence = {
         ...evidence,
         parsedIntent: {
@@ -3448,7 +3956,14 @@ function directResolution(request, evidence, candidate, candidates, selectedDime
             .map((item) => item.id)
             .concat(selectedDimensionConceptIds, hostBoundDimensionConceptIds)
             .filter((id, index, all) => all.indexOf(id) === index),
-        recommendedExecutionId: candidate.id,
+        // Meaning receipts retain the source-qualified identity selected from the
+        // immutable workspace.  The frozen semantic compiler plan may normalize
+        // that handle to its canonical execution ID later, but rewriting it here
+        // breaks the provenance link between the model/meaning choice and the
+        // selected semantic evidence card.
+        recommendedExecutionId: candidate.kind === 'semantic_metric'
+            ? candidate.qualifiedId ?? candidate.id
+            : candidate.id,
         queryIntent: { ...queryIntentWithSelectedDimensions, filters: canonicalFilters },
         rejectedCandidates: [],
         confidence: "high",
@@ -3571,6 +4086,86 @@ function attachHostOwnedAnalyticalFrame(input) {
         ...(overrideReceipts?.length ? { overrideReceipts } : {}),
     };
 }
+/**
+ * Bind an already validated runtime meaning selection to the immutable
+ * host-owned analytical frame.  This is intentionally a narrow compiler
+ * adapter: it does not retrieve, rank candidates, call a provider, or change
+ * the runtime program.  Keeping the V2 frame construction here lets the
+ * existing MetricFlow compiler retain its capability/additivity validation
+ * without returning ownership of interpretation to the legacy router.
+ */
+export function bindAskAnalystProgramMeaningV1(input) {
+    // The runtime has already verified which cards express the business tuple.
+    // `input.candidates` can still contain the 16-card planner package so the
+    // compiler has definition/relationship context, but it is not permission
+    // to rebuild the frame with every correlated metric in that package. In the
+    // retained Jaffle snapshot, that turned the singular Orders metric into
+    // Orders + Large Orders + Food Orders + Drink Orders after verification.
+    // Preserve only server-validated selection identities here; execution
+    // closure remains a separate compiler input later in the cascade.
+    const selectedIdentityIds = new Set([
+        ...input.resolution.selectedConceptIds,
+        ...(input.resolution.recommendedExecutionId ? [input.resolution.recommendedExecutionId] : []),
+    ]);
+    const selectedCandidates = input.candidates.filter((candidate) => [candidate.id, candidate.qualifiedId]
+        .filter((identity) => Boolean(identity))
+        .some((identity) => selectedIdentityIds.has(identity)));
+    // Legacy/direct callers can lack a selected card only when they supplied an
+    // incomplete resolution. Keep their prior behavior rather than fabricating
+    // an empty frame; authoritative Ask always takes the narrow branch above.
+    const framingCandidates = selectedCandidates.length > 0 ? selectedCandidates : input.candidates;
+    const metricCandidate = framingCandidates.find((candidate) => candidate.kind === 'semantic_metric'
+        && (candidate.id === input.resolution.recommendedExecutionId
+            || candidate.qualifiedId === input.resolution.recommendedExecutionId
+            || input.resolution.selectedConceptIds.some((identity) => candidate.id === identity || candidate.qualifiedId === identity)));
+    const compilerFramingCandidates = metricCandidate
+        ? bindSelectedMetricFlowGroupingExtensions(metricCandidate, framingCandidates)
+        : framingCandidates;
+    // The Ask runtime may rebuild the compiler-facing seed after verifying
+    // canonical planner bindings. `attachHostOwnedAnalyticalFrame` deliberately
+    // preserves most of the incoming resolution, so explicitly carry that
+    // verified seed forward here. Otherwise a valid same-snapshot extension
+    // can produce a frame with `locations.location_name`, only for RAP binding
+    // to reopen the stale pre-planner phrase `region` and mark it unresolved.
+    const frameBound = {
+        ...attachHostOwnedAnalyticalFrame({ ...input, candidates: compilerFramingCandidates }),
+        hostRequirementSeed: input.requirementSeed,
+    };
+    const protectedResolution = preventDegenerateRankingResolution(frameBound, input.evidence, compilerFramingCandidates, input.requirementSeed.sourceQuestion);
+    // This adapter may enrich a selected MetricFlow tuple with host-owned
+    // dimensions, but it may not silently subtract a verified runtime
+    // selection. `attachHostOwnedAnalyticalFrame` rebuilds legacy resolution
+    // fields for compiler compatibility; some native Measure -> MetricFlow
+    // Metric pairs intentionally have different text identities (for example
+    // `order_count` -> `Orders`). Keep every already-validated candidate ID
+    // from the authoritative program, limited to this same candidate package.
+    // The verifier/compiler still prove the metric's capability, grain, and
+    // relationship closure before freeze.
+    // The MetricFlow framing subset is allowed to shape legacy metric/grouping
+    // metadata, but it is not the authority boundary for a V3 selection. A
+    // verified planner can legitimately retain a qualified physical output or
+    // context field beside its semantic metric. Keep those already-admitted
+    // identities through the compatibility carrier; they remain subject to the
+    // immutable compiler program's physical/semantic safety proof below.
+    const allowed = new Set(input.candidates.flatMap((candidate) => [
+        candidate.id,
+        candidate.qualifiedId ?? candidate.id,
+    ]));
+    const preservedSelectedConceptIds = input.resolution.selectedConceptIds
+        .filter((identity) => allowed.has(identity));
+    const selectedConceptIds = [...new Set([
+            ...protectedResolution.selectedConceptIds,
+            ...preservedSelectedConceptIds,
+        ])];
+    const originalRecommendedExecutionId = input.resolution.recommendedExecutionId;
+    return {
+        ...protectedResolution,
+        selectedConceptIds,
+        ...(originalRecommendedExecutionId && allowed.has(originalRecommendedExecutionId)
+            ? { recommendedExecutionId: originalRecommendedExecutionId }
+            : {}),
+    };
+}
 function explicitlyRequestedMetricCandidates(question, evidence, primary, candidates) {
     const requirements = buildAnalyticalRequirementSet({ question, parsedIntent: evidence.parsedIntent });
     const requested = requirements.ranking?.metricTerms.length
@@ -4775,13 +5370,7 @@ function sameSnapshotRoleTargetedMeaningExtensions(input) {
     const requestedCategoricalTerms = categoricalDimensionRequirementTerms(input.requirements);
     for (const candidate of input.clarificationCandidates) {
         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')
-            || candidate.kind !== 'semantic_member'
-            || (candidate.qualifiedId ?? candidate.id) !== extension.dimensionId)
+        if (!extension)
             continue;
         if (!requestedCategoricalTerms.some((requested) => normalizeMetricPhrase(requested) === normalizeMetricPhrase(extension.requestedTerm)))
             continue;
@@ -4795,9 +5384,18 @@ function sameSnapshotRoleTargetedMeaningExtensions(input) {
         if (input.candidates.some((admitted) => admitted.kind === 'semantic_member'
             && candidateMatchesCategoricalDimensionRequirement(admitted, [extension.requestedTerm])))
             continue;
-        const sourceMetricAdmitted = input.candidates.some((admitted) => admitted.kind === 'semantic_metric'
-            && (admitted.id === extension.metricId || admitted.qualifiedId === extension.metricId));
-        if (!sourceMetricAdmitted)
+        // The compact package may retain a metric card across reloads, but only
+        // its *current* normalized capability can authorize the companion
+        // grouping card. Reuse the router/compiler/workspace proof rather than
+        // accepting matching strings for metric/dimension identities.
+        const sourceMetricProof = input.candidates.flatMap((admitted) => {
+            const proof = proveSameSnapshotMetricflowRoleExtensionV1({
+                candidate,
+                metricCandidate: admitted,
+            });
+            return proof ? [proof] : [];
+        });
+        if (sourceMetricProof.length === 0)
             continue;
         const role = normalizeMetricPhrase(extension.requestedTerm);
         const values = extensionsByRole.get(role) ?? [];
@@ -4879,8 +5477,12 @@ export function createHybridRouter(options = {}) {
             if (request.runBudget && !request.runBudget.mayStartDiscovery(initialDiscoveryRoute)) {
                 return softBoundaryDecision(request, base, initialDiscoveryRoute);
             }
-            let evidence;
-            if (options.getEvidence) {
+            // AskAnalystRuntimeV1 acquires one immutable snapshot before invoking
+            // this compiler broker. Reusing that host-only handoff prevents a second
+            // retrieval/ranking decision from silently becoming another source of
+            // truth. Legacy callers retain the original retrieval behavior.
+            let evidence = request.askAnalystEvidence;
+            if (!evidence && options.getEvidence) {
                 try {
                     evidence = await options.getEvidence(request);
                 }
@@ -4911,6 +5513,47 @@ export function createHybridRouter(options = {}) {
                             ]).filter((candidate) => evidence.clarificationCandidates.some((item) => item.id === candidate.id)) }
                         : {}),
                 };
+                // Authoritative AskAnalystRuntimeV1 already completed the bounded
+                // interpretation/tool phase.  Do not re-run legacy candidate ranking,
+                // clarification heuristics, or a provider call here: this layer is a
+                // compiler broker only and can validate exactly the immutable program
+                // selection against safe compiler primitives.
+                if (request.askAnalystProgram && request.askAnalystMeaningResolution) {
+                    const programIds = new Set(request.askAnalystProgram.candidateIds);
+                    const executionIds = new Set(request.askAnalystProgram.executionCandidateIds
+                        ?? request.askAnalystProgram.candidateIds);
+                    const programCandidates = evidence.candidates.filter((candidate) => programIds.has(candidate.id) || programIds.has(candidate.qualifiedId ?? candidate.id));
+                    const executionCandidates = evidence.candidates.filter((candidate) => executionIds.has(candidate.id) || executionIds.has(candidate.qualifiedId ?? candidate.id));
+                    const requirements = request.askAnalystState?.frame.requirements
+                        ?? request.hostRequirementSeed?.requirements;
+                    if (!requirements || programCandidates.length === 0) {
+                        return {
+                            ...base,
+                            action: 'block',
+                            confidence: 1,
+                            reason: 'The Ask runtime program could not be compiled because its snapshot-bound candidate selection was unavailable.',
+                            source: 'heuristic',
+                            followsUp: false,
+                            terminalOutcome: {
+                                kind: 'modeling_gap',
+                                code: 'ANALYTICAL_MODELING_GAP',
+                                message: 'The immutable Ask runtime program did not retain a compiler-eligible candidate selection.',
+                                candidateIds: request.askAnalystProgram.candidateIds,
+                            },
+                        };
+                    }
+                    return compileAskAnalyticalProgramV1({
+                        base,
+                        request,
+                        evidence,
+                        program: request.askAnalystProgram,
+                        candidates: programCandidates,
+                        executionCandidates,
+                        resolution: request.askAnalystMeaningResolution,
+                        requirements,
+                        mode: options.resolvedPlanMode ?? 'authoritative',
+                    });
+                }
                 // Ranking measure identity is resolved from the same immutable
                 // request/evidence frame that drives package reservation.  A metric
                 // may remain in broad retrieval context, but it cannot become a
@@ -4976,7 +5619,7 @@ export function createHybridRouter(options = {}) {
                 // supplied so explicit revenue, entity labels, and time roles cannot be
                 // pruned by unrelated lexical matches.
                 let candidates = buildMeaningEvidencePackage(evidence, options.maxMeaningCandidates ?? 16, continuationQuestion);
-                traceCandidateLifecycleBeforePruning(request, evidence, retrievedCandidates, candidates);
+                recordAskCandidateLifecycleV1(request, evidence, retrievedCandidates, candidates);
                 // The complete already-retrieved set is retained only to validate a
                 // server-issued stable selection before any route can fall through to
                 // a generic/generated answer. New free-text choices are constrained to
@@ -5118,11 +5761,14 @@ export function createHybridRouter(options = {}) {
                     // matched semantic metric remains the only execution/measure
                     // authority. A selected dimension must therefore never flow through
                     // the metric-only direct-resolution path as the primary candidate.
+                    const canonicalLiteral = canonicalLiteralEvidenceReference(request.question, candidates);
                     const explicit = selectedDimensionBinding?.metricCandidate
                         ?? selectedEvidence
-                        ?? findExplicitEvidenceReference(request.question, candidates);
+                        ?? findExplicitEvidenceReference(request.question, candidates)
+                        ?? canonicalLiteral;
                     const explicitMeaningBinding = Boolean(explicit && (request.selectedEvidenceId
-                        || /@(metric|block|model|table|column)\(/i.test(request.question)));
+                        || /@(metric|block|model|table|column)\(/i.test(request.question)
+                        || canonicalLiteral?.id === explicit.id));
                     const shouldUseMeaningCall = requireMeaningCall
                         && !explicitMeaningBinding
                         && Boolean(options.resolveMeaning || options.complete);
@@ -5199,8 +5845,12 @@ export function createHybridRouter(options = {}) {
                     // did run, committing to the best governed reading is the whole point.
                     let meaningResolverReachable = true;
                     try {
-                        if (request.runBudget && !request.runBudget.mayStartDiscovery('clarify')) {
-                            return softBoundaryDecision(request, base, 'clarify');
+                        // Meaning is the one bounded planning continuation of an ordinary
+                        // generated Ask, not a user clarification. Charging it to the
+                        // short clarify target was the direct cause of the 1.14.x
+                        // "discovery window ended" loop before semantic/raw fallback.
+                        if (request.runBudget && !request.runBudget.mayStartDiscovery('generated_answer')) {
+                            return softBoundaryDecision(request, base, 'generated_answer');
                         }
                         let resolution;
                         try {
@@ -5490,15 +6140,42 @@ function softBoundaryDecision(request, base, route) {
     const seconds = Math.round((request.runBudget?.softTargetMs(route) ?? 15_000) / 1_000);
     return {
         ...base,
-        action: 'clarify',
+        // A budget/admission boundary is an operational condition, never a
+        // business ambiguity.  Returning `clarify` here made the UI ask users to
+        // choose a metric or grain even though no competing executable meanings
+        // had been validated.  Keep this a typed terminal block so diagnostics can
+        // offer a retry/recovery action without teaching users to compensate for a
+        // runtime deadline.
+        action: 'block',
         confidence: 1,
         source: 'heuristic',
-        requiresClarification: true,
+        requiresClarification: false,
+        clarifyingQuestion: undefined,
         reason: `The ${seconds}-second discovery target elapsed before a plan was frozen, so DQL did not start another retrieval or provider branch.`,
-        clarifyingQuestion: request.runBudget?.mode === 'research'
-            ? 'Research has stopped starting new branches. Would you like to narrow the question and retry?'
-            : 'The discovery window ended before an exact plan was frozen. Which metric or grain should DQL use on retry?',
     };
 }
+/**
+ * A literal stable metric/block identifier is already a user-selected meaning.
+ * It is intentionally narrower than a human label such as "revenue": only
+ * an identifier-shaped value (`foo_bar`, `namespace.metric`, `metric:foo`) or
+ * a supplied exact qualified ID can bypass the one meaning call. This restores
+ * the useful 1.13 zero-call semantic path without turning lexical retrieval
+ * into permission to guess between similarly named business metrics.
+ */
+function canonicalLiteralEvidenceReference(question, candidates) {
+    const normalizedQuestion = question.toLowerCase();
+    const matches = candidates.filter((candidate) => {
+        if (candidate.compatibility === 'incompatible' || candidate.eligible === false)
+            return false;
+        const identities = [candidate.qualifiedId, candidate.id, candidate.name, ...(candidate.aliases ?? [])]
+            .filter((value) => Boolean(value))
+            .filter((value) => /[_:.]/.test(value));
+        return identities.some((identity) => {
+            const escaped = identity.toLowerCase().replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            return new RegExp(`(^|[^a-z0-9_.:-])${escaped}($|[^a-z0-9_.:-])`, 'i').test(normalizedQuestion);
+        });
+    });
+    return matches.length === 1 ? matches[0] : undefined;
+}
 export { intentForCategory, parseMeaningResolution };
 //# sourceMappingURL=router.js.map