@duckcodeailabs/dql-agent 1.14.2 → 1.14.4

package/dist/router.js

@@ -16,12 +16,13 @@ import { assumeDominantCandidate } from './agentic/assumptions.js';
  * question never pays twice.
  */
 import { classifyConversationalTurn, decideAgentAction, } from "./intent-controller.js";
-import { buildMeaningEvidencePackage, canonicalizeMetricMeasureCandidates, certifiedCandidateExplicitlyCoversMeasures, defaultQueryIntent, findExplicitEvidenceReference, questionTypeFromText, routeForEvidenceCandidate, validateMeaningResolution, } from "./meaning-resolution.js";
+import { buildMeaningEvidencePackage, canonicalizeMetricMeasureCandidates, certifiedCandidateExplicitlyCoversMeasures, defaultQueryIntent, findExplicitEvidenceReference, mergeMeaningResolutionWithRequirementSeed, questionTypeFromText, routeForEvidenceCandidate, validateMeaningResolution, } from "./meaning-resolution.js";
 import { normalizeAnalyticalQuestionFrameV2 } from "@duckcodeailabs/dql-core";
 import { buildResolvedAnalyticalPlan, } from "./resolved-analytical-plan.js";
-import { buildAnalyticalCascadeDecision, buildAnalyticalRequirementSet, } from './analytical-orchestration.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 } 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;
@@ -194,20 +195,22 @@ 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. Compare ONLY the supplied candidate cards.",
-        "Select the concept that best matches the full question, entity, dimensions, filters, time grain, formula, aggregation, domain, and conversation context.",
-        "Trust is an execution preference only after relevance and compatibility. Never select an unrelated certified block over a relevant semantic metric.",
+        "The host already performed broad retrieval and supplied a host-owned requirement seed. Compare ONLY the supplied candidate cards against that seed.",
+        "Select the supplied candidate IDs that best bind the host-owned metric, entity, dimensions, filters, time grain, ranking, and output requirements.",
+        "Trust, route selection, SQL, and the final analytical frame are host-owned. Never select an unrelated certified block over a relevant semantic metric.",
         "You may reference ONLY candidate IDs supplied below. Never invent an ID, table, column, metric, relationship, or filter value.",
+        "Do not rewrite, add, remove, or replace any host-owned requirement. Do not use prior conversation unless the host seed says it is a continuation.",
+        "Do not emit SQL, trust labels, an execution route, query intent, or an analytical frame. Those fields are ignored if present for legacy compatibility.",
         "Use low confidence and recommend clarify when material business meanings remain unresolved.",
-        "Respond with ONLY one JSON object matching this shape:",
-        '{"interpretedQuestion":string,"questionType":"definition"|"value"|"ranking"|"trend"|"comparison"|"diagnosis"|"research","selectedConceptIds":string[],"recommendedExecutionId"?:string,"queryIntent":{"measures":string[],"dimensions":string[],"filters":[{"field":string,"value":string}],"timeRange"?:string,"timeGrain"?:string,"order"?:"asc"|"desc","limit"?:number},"analyticalFrame"?:AnalyticalQuestionFrameV2,"rejectedCandidates":[{"id":string,"reason":string}],"confidence":"high"|"medium"|"low","missingInformation":string[],"recommendedRoute":"certified"|"semantic"|"governed_sql"|"exploratory"|"clarify","clarifyingQuestion"?:string}',
-        "AnalyticalQuestionFrameV2 uses version 2 and exact supplied IDs for metricConceptIds, entityGrainIds, dimensions with roles group_by/filter/display/rank_entity/time_axis, memberBindings, timeContext with bounded periods, comparison, ranking, requestedOutputs, and ambiguity. Include it for value/ranking/trend/comparison requests when the supplied capability facts are sufficient; otherwise report missingInformation.",
+        "Respond with ONLY one JSON object matching this minimal candidate-ID shape:",
+        '{"selectedCandidateIds":string[],"recommendedExecutionId"?:string,"confidence"?:"high"|"medium"|"low","missingInformation"?:string[]}',
+        "`selectedConceptIds` is accepted only for legacy compatibility. All omitted optional fields receive host-owned safe defaults.",
     ].join("\n");
 }
-function buildMeaningUserPrompt(request, evidence, candidates) {
+export function buildMeaningUserPrompt(request, evidence, candidates, requirementSeed) {
     const cards = candidates.map((candidate) => ({
         id: candidate.id,
         kind: candidate.kind,
@@ -219,6 +222,7 @@ function buildMeaningUserPrompt(request, evidence, candidates) {
         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),
@@ -232,21 +236,23 @@ function buildMeaningUserPrompt(request, evidence, candidates) {
         analyticalCapability: candidate.analyticalCapability,
     }));
     const lines = [
-        `Question: ${compactText(request.question, 2_000)}`,
-        `Parsed request hints: ${JSON.stringify(compactQueryIntent(defaultQueryIntent(evidence)))}`,
+        `Host-owned requirement seed: ${JSON.stringify(requirementSeed)}`,
         `Candidate cards: ${JSON.stringify(cards)}`,
     ];
     const history = effectiveConversationHistory(request);
-    if (history.length) {
+    const continuation = request.conversationBinding ?? 'none';
+    if (history.length && continuation !== 'none') {
         lines.push(`Recent conversation: ${JSON.stringify(history.slice(-4).map((turn) => ({
             role: turn.role,
             text: compactText(turn.text, 1_200),
         })))}`);
     }
-    const envelope = renderConversationEnvelopeForPrompt(request.conversationContext);
+    const envelope = continuation === 'none'
+        ? undefined
+        : renderConversationEnvelopeForPrompt(request.conversationContext);
     if (envelope)
         lines.push(`Structured conversation state: ${JSON.stringify(envelope)}`);
-    lines.push("Resolve the intended meaning and return JSON only.");
+    lines.push("Bind only supplied candidate IDs to the host-owned seed and return JSON only.");
     return lines.join("\n");
 }
 function compactText(value, maxLength) {
@@ -275,42 +281,62 @@ function compactQueryIntent(intent) {
 const QUESTION_TYPES = new Set(["definition", "value", "ranking", "trend", "comparison", "diagnosis", "research"]);
 const MEANING_CONFIDENCES = new Set(["high", "medium", "low"]);
 const MEANING_ROUTES = new Set(["certified", "semantic", "governed_sql", "exploratory", "clarify"]);
-function parseMeaningResolution(raw) {
+function parseMeaningResolution(raw, requirementSeed) {
     const parsed = extractJsonObject(raw);
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
         return undefined;
     const record = parsed;
-    if (typeof record.interpretedQuestion !== "string" || !record.interpretedQuestion.trim())
+    const interpretedQuestion = typeof record.interpretedQuestion === "string" && record.interpretedQuestion.trim()
+        ? record.interpretedQuestion.trim()
+        : requirementSeed?.sourceQuestion;
+    if (!interpretedQuestion)
         return undefined;
-    if (typeof record.questionType !== "string" || !QUESTION_TYPES.has(record.questionType))
+    const questionType = typeof record.questionType === "string" && QUESTION_TYPES.has(record.questionType)
+        ? record.questionType
+        : requirementSeed ? questionTypeFromText(requirementSeed.sourceQuestion) : undefined;
+    if (!questionType)
         return undefined;
-    if (!Array.isArray(record.selectedConceptIds) || record.selectedConceptIds.some((id) => typeof id !== "string"))
+    const selectedConceptIds = Array.isArray(record.selectedCandidateIds)
+        ? record.selectedCandidateIds
+        : record.selectedConceptIds;
+    if (!Array.isArray(selectedConceptIds) || selectedConceptIds.some((id) => typeof id !== "string"))
         return undefined;
-    if (typeof record.confidence !== "string" || !MEANING_CONFIDENCES.has(record.confidence))
-        return undefined;
-    if (typeof record.recommendedRoute !== "string" || !MEANING_ROUTES.has(record.recommendedRoute))
+    const confidence = typeof record.confidence === "string" && MEANING_CONFIDENCES.has(record.confidence)
+        ? record.confidence
+        : requirementSeed
+            ? selectedConceptIds.length > 0 ? 'medium' : 'low'
+            : undefined;
+    if (!confidence)
         return undefined;
-    if (!record.queryIntent || typeof record.queryIntent !== "object" || Array.isArray(record.queryIntent))
+    const recommendedRoute = typeof record.recommendedRoute === "string" && MEANING_ROUTES.has(record.recommendedRoute)
+        ? record.recommendedRoute
+        : requirementSeed ? "clarify" : undefined;
+    if (!recommendedRoute)
         return undefined;
-    const query = record.queryIntent;
-    const measures = stringArray(query.measures);
-    const dimensions = stringArray(query.dimensions);
-    const missingInformation = stringArray(record.missingInformation);
-    if (!measures || !dimensions || !missingInformation || !Array.isArray(query.filters))
+    const missingInformation = stringArray(record.missingInformation) ?? (requirementSeed ? [] : undefined);
+    if (!missingInformation)
         return undefined;
-    const filters = query.filters.flatMap((filter) => {
-        if (!filter || typeof filter !== "object" || Array.isArray(filter))
-            return [];
-        const item = filter;
-        return typeof item.field === "string" && typeof item.value === "string"
-            ? [{ field: item.field, value: item.value }]
-            : [];
-    });
-    if (filters.length !== query.filters.length)
+    const query = record.queryIntent && typeof record.queryIntent === "object" && !Array.isArray(record.queryIntent)
+        ? record.queryIntent
+        : undefined;
+    const measures = query ? stringArray(query.measures) : undefined;
+    const dimensions = query ? stringArray(query.dimensions) : undefined;
+    const filters = Array.isArray(query?.filters)
+        ? query.filters.flatMap((filter) => {
+            if (!filter || typeof filter !== "object" || Array.isArray(filter))
+                return [];
+            const item = filter;
+            return typeof item.field === "string" && typeof item.value === "string"
+                ? [{ field: item.field, value: item.value }]
+                : [];
+        })
+        : undefined;
+    if (!requirementSeed && (!measures || !dimensions || !filters || !Array.isArray(query?.filters) || filters.length !== query.filters.length))
         return undefined;
-    if (!Array.isArray(record.rejectedCandidates))
+    const rejectedCandidatesRaw = record.rejectedCandidates;
+    if (rejectedCandidatesRaw !== undefined && !Array.isArray(rejectedCandidatesRaw))
         return undefined;
-    const rejectedCandidates = record.rejectedCandidates.flatMap((candidate) => {
+    const rejectedCandidates = (rejectedCandidatesRaw ?? []).flatMap((candidate) => {
         if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
             return [];
         const item = candidate;
@@ -318,42 +344,66 @@ function parseMeaningResolution(raw) {
             ? [{ id: item.id, reason: item.reason }]
             : [];
     });
-    if (rejectedCandidates.length !== record.rejectedCandidates.length)
+    if (rejectedCandidates.length !== (rejectedCandidatesRaw?.length ?? 0))
         return undefined;
     const recommendedExecutionId = typeof record.recommendedExecutionId === "string"
         ? record.recommendedExecutionId
         : undefined;
-    const clarifyingQuestion = typeof record.clarifyingQuestion === "string" &&
-        record.clarifyingQuestion.trim()
+    const clarifyingQuestion = typeof record.clarifyingQuestion === "string" && record.clarifyingQuestion.trim()
         ? record.clarifyingQuestion.trim()
         : undefined;
-    const analyticalFrame = record.analyticalFrame === undefined
+    const providerExplicitlyClarified = (recommendedRoute === 'clarify'
+        && typeof record.recommendedRoute === 'string')
+        || Boolean(clarifyingQuestion)
+        || missingInformation.length > 0
+        || rejectedCandidates.length > 0;
+    // Legacy callers may still send a V2 frame. It remains readable without a
+    // seed, but a seeded meaning call must never grant a model frame authority.
+    const analyticalFrame = requirementSeed || record.analyticalFrame === undefined
         ? undefined
         : normalizeAnalyticalQuestionFrameV2(record.analyticalFrame);
-    if (record.analyticalFrame !== undefined && !analyticalFrame)
+    if (!requirementSeed && record.analyticalFrame !== undefined && !analyticalFrame)
         return undefined;
     return {
-        interpretedQuestion: record.interpretedQuestion.trim(),
-        questionType: record.questionType,
-        selectedConceptIds: record.selectedConceptIds,
+        interpretedQuestion,
+        questionType,
+        selectedConceptIds: selectedConceptIds,
         ...(recommendedExecutionId ? { recommendedExecutionId } : {}),
-        queryIntent: {
-            measures,
-            dimensions,
-            filters,
-            ...(typeof query.timeRange === "string" ? { timeRange: query.timeRange } : {}),
-            ...(typeof query.timeGrain === "string" ? { timeGrain: query.timeGrain } : {}),
-            ...(query.order === "asc" || query.order === "desc" ? { order: query.order } : {}),
-            ...(typeof query.limit === "number" && Number.isFinite(query.limit) && query.limit > 0
-                ? { limit: Math.floor(query.limit) }
-                : {}),
-        },
+        queryIntent: requirementSeed
+            ? queryIntentFromRequirementSeed(requirementSeed)
+            : {
+                measures: measures,
+                dimensions: dimensions,
+                filters: filters,
+                ...(typeof query?.timeRange === "string" ? { timeRange: query.timeRange } : {}),
+                ...(typeof query?.timeGrain === "string" ? { timeGrain: query.timeGrain } : {}),
+                ...(query?.order === "asc" || query?.order === "desc" ? { order: query.order } : {}),
+                ...(typeof query?.limit === "number" && Number.isFinite(query.limit) && query.limit > 0
+                    ? { limit: Math.floor(query.limit) }
+                    : {}),
+            },
         rejectedCandidates,
-        confidence: record.confidence,
+        confidence,
         missingInformation,
-        recommendedRoute: record.recommendedRoute,
+        recommendedRoute,
         ...(clarifyingQuestion ? { clarifyingQuestion } : {}),
         ...(analyticalFrame ? { analyticalFrame } : {}),
+        ...(selectedConceptIds.length === 0 && !recommendedExecutionId && !providerExplicitlyClarified
+            ? { emptyCandidateBinding: true }
+            : {}),
+    };
+}
+function queryIntentFromRequirementSeed(seed) {
+    return {
+        measures: [...seed.queryIntent.measures],
+        dimensions: [...seed.queryIntent.dimensions],
+        filters: seed.queryIntent.filters.map((filter) => ({ field: filter.field, value: filter.value })),
+        ...(seed.queryIntent.timeRange ? { timeRange: seed.queryIntent.timeRange } : {}),
+        ...(seed.queryIntent.timeGrain ? { timeGrain: seed.queryIntent.timeGrain } : {}),
+        ...(seed.queryIntent.order ? { order: seed.queryIntent.order } : {}),
+        ...(seed.queryIntent.limit !== undefined ? { limit: seed.queryIntent.limit } : {}),
+        ...(seed.queryIntent.fiscalCalendarId ? { fiscalCalendarId: seed.queryIntent.fiscalCalendarId } : {}),
+        ...(seed.queryIntent.fiscalDateRoleId ? { fiscalDateRoleId: seed.queryIntent.fiscalDateRoleId } : {}),
     };
 }
 function stringArray(value) {
@@ -408,13 +458,228 @@ function conversationPositionToken(context) {
     return `${latest}:${turns.length}:${recent}:${tailId}`;
 }
 function retrievalTrace(evidence, candidates) {
+    const candidateTraceMetadata = candidates.flatMap((candidate) => evidenceCandidateRoles(candidate).map((role) => ({
+        // `id` is the identity accepted by the meaning resolver. It is already
+        // source-qualified by the retrieval contract; keep it so later selection
+        // IDs can be joined without guessing a legacy-to-canonical mapping.
+        candidateId: candidate.id,
+        role,
+        source: traceSourceForCandidate(candidate),
+        ...(candidate.retrievalLanes?.length ? { lanes: candidate.retrievalLanes } : {}),
+    })));
     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 } : {}),
     };
 }
+/**
+ * Observability is a projection of snapshot-bound evidence, never a second
+ * retriever or a route authority. Keep source classification conservative so
+ * an absent lane is not manufactured from an arbitrary ID prefix.
+ */
+function traceSourceForCandidate(candidate) {
+    // Qualified candidate identities preserve their originating index. Prefer
+    // that declared provenance for collapsed `sql_column`/`sql_table` kinds: a
+    // dbt manifest column must not be relabelled as runtime-schema evidence.
+    const identity = candidate.qualifiedId ?? candidate.id;
+    if (identity.startsWith('dbt:'))
+        return 'dbt_manifest';
+    if (identity.startsWith('runtime:'))
+        return 'runtime_schema';
+    if (identity.startsWith('semantic:'))
+        return 'semantic';
+    if (identity.startsWith('dql:'))
+        return candidate.kind === 'certified_block' ? 'certified' : 'governed_relational';
+    if (candidate.kind === 'certified_block')
+        return 'certified';
+    if (candidate.kind === 'semantic_metric' || candidate.kind === 'semantic_member')
+        return 'semantic';
+    if (candidate.kind === 'dql_modeling')
+        return 'governed_relational';
+    if (candidate.kind === 'dbt_model' || candidate.kind === 'dbt_source')
+        return 'dbt_manifest';
+    if (candidate.kind === 'sql_table' || candidate.kind === 'sql_column')
+        return 'runtime_schema';
+    return 'exploratory';
+}
+/**
+ * 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;
+    const packageIds = new Set(packageCandidates.map((candidate) => candidate.id));
+    const fuse = observer.startSpan({
+        name: 'retrieval.fuse',
+        stage: 'retrieval',
+        payload: { kind: 'retrieval', candidateCount: candidates.length },
+    });
+    const requirements = buildAnalyticalRequirementSet({ question: request.question, parsedIntent: evidence.parsedIntent });
+    const requestedRoles = new Set([
+        ...(requirements.measures.length || requirements.ranking?.metricTerms.length ? ['metric'] : []),
+        ...(requirements.entityTerms.length || requirements.entityDisplayTerms.length ? ['entity_label'] : []),
+        ...(requirements.time ? ['time_dimension'] : []),
+        ...(requirements.dimensions.length ? ['categorical_dimension'] : []),
+        ...(requirements.dimensions.length > 1 || requirements.entityTerms.length ? ['relationship'] : []),
+    ]);
+    // 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, rawCandidateTraceLimit).entries()) {
+        const roles = evidenceCandidateRoles(candidate);
+        const source = traceSourceForCandidate(candidate);
+        // This receipt must retain the actual retrieval memberships captured by
+        // the snapshot. Do not infer a lane from aliases, IDs, or a relationship
+        // attribute after fusion has already lost that physical provenance.
+        const lanes = candidate.retrievalLanes
+            ?.map((entry) => ({ ...entry }))
+            .sort((left, right) => (left.rank ?? Number.MAX_SAFE_INTEGER) - (right.rank ?? Number.MAX_SAFE_INTEGER)
+            || left.lane.localeCompare(right.lane));
+        const lane = lanes?.[0]?.lane;
+        const laneRank = lanes?.[0]?.rank;
+        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';
+        for (const role of roles) {
+            const common = {
+                // The resolver and cascade use `id`; keeping that exact stable identity
+                // makes retrieval, admission, and model-selection receipts joinable.
+                candidateId: candidate.id,
+                role,
+                source,
+                ...(lane ? { lane } : {}),
+                ...(laneRank !== undefined ? { laneRank } : {}),
+                ...(lanes?.length ? { lanes } : {}),
+                fusedRank: index + 1,
+                compatibilityCode,
+            };
+            observer.recordCandidateDecision({
+                ...common,
+                decision: 'retrieved',
+                reasonCode: candidate.eligible === false ? 'role_mismatch' : initialReason,
+            });
+            // An explicit ranking measure is a typed request, not a relevance hint.
+            // Keep correlated metrics in the receipt, but record their exclusion at
+            // the metric admission boundary instead of allowing them to become
+            // clarification options or to fill an unrelated analytical role.
+            if (role === 'metric' && candidateConflictsWithExplicitRankingMeasure(candidate, requirements)) {
+                observer.recordCandidateDecision({
+                    ...common,
+                    decision: 'excluded',
+                    reasonCode: 'explicit_measure_conflict',
+                });
+                continue;
+            }
+            if (candidate.eligible === false || candidate.compatibility === 'incompatible') {
+                observer.recordCandidateDecision({
+                    ...common,
+                    decision: 'excluded',
+                    reasonCode: candidate.compatibility === 'incompatible' ? 'capability_incompatible' : 'role_mismatch',
+                });
+                continue;
+            }
+            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: 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: configuredRuntimeValueGroundingPin ? 'configured_runtime_value_grounding_pin'
+                        : candidate.exactMatch ? 'exact_name_match'
+                            : unresolvedRoleAdmission ? 'candidate_for_unresolved_role'
+                                : reservedForRole ? 'role_reserved' : 'fused_relevance_fill',
+                });
+            }
+            else {
+                const isNoisyEntityAttribute = hasRequestedEntityLabel
+                    && isEntityAttributeCandidate(candidate)
+                    && role === 'categorical_dimension';
+                observer.recordCandidateDecision({
+                    ...common,
+                    decision: 'excluded',
+                    reasonCode: isNoisyEntityAttribute ? 'entity_label_mismatch' : 'below_fused_limit',
+                });
+            }
+        }
+    }
+    observer.finishSpan(fuse, { outcome: 'ok', reasonCode: 'completed' });
+}
+/**
+ * Emit source-bound lane summaries before the meaning-package cap applies.
+ * These spans are evidence about the existing retrieval result only; they do
+ * not invoke, retry, or reinterpret any retrieval source.
+ */
+function traceRetrievalLanesBeforePruning(request, evidence, candidates) {
+    const observer = askTraceObserverForV1(request);
+    if (!observer.enabled)
+        return;
+    const sourceSpan = {
+        certified: 'retrieval.certified',
+        semantic: 'retrieval.semantic',
+        governed_relational: 'retrieval.governed_relational',
+        dbt_manifest: 'retrieval.dbt_manifest',
+        runtime_schema: 'retrieval.runtime_schema',
+        vector: 'retrieval.vector',
+        conversation: 'retrieval.conversation',
+    };
+    const record = (name, source, count, coverage, lane) => {
+        const span = observer.startSpan({
+            name,
+            stage: 'retrieval',
+            reasonCode: coverage === 'unavailable' ? 'source_unavailable' : coverage === 'empty' ? 'source_empty' : coverage === 'stale' ? 'source_stale' : 'completed',
+            payload: { kind: 'retrieval', ...(source ? { source } : {}), ...(lane ? { lane } : {}), candidateCount: count, ...(coverage ? { coverage } : {}) },
+        });
+        observer.finishSpan(span, {
+            outcome: coverage === 'unavailable' ? 'unavailable' : 'ok',
+            reasonCode: coverage === 'unavailable' ? 'source_unavailable' : coverage === 'empty' ? 'source_empty' : coverage === 'stale' ? 'source_stale' : 'completed',
+        });
+    };
+    for (const coverage of sourceCoverageFromEvidence(evidence, candidates)) {
+        const name = sourceSpan[coverage.source];
+        if (!name)
+            continue;
+        record(name, coverage.source, coverage.candidateIds.length, coverage.status, coverage.source === 'vector' ? 'vector' : coverage.source === 'conversation' ? 'conversation' : undefined);
+    }
+    const laneSpan = {
+        exact: 'retrieval.exact',
+        lexical: 'retrieval.lexical',
+        vector: 'retrieval.vector',
+        graph: 'retrieval.graph',
+        conversation: 'retrieval.conversation',
+    };
+    for (const lane of Object.keys(laneSpan)) {
+        const count = candidates.filter((candidate) => candidate.retrievalLanes?.some((membership) => membership.lane === lane)).length;
+        if (count > 0)
+            record(laneSpan[lane], undefined, count, 'available', lane);
+    }
+}
 /** Preserve actual retrieval provenance; never infer lane state from an ID regex. */
 function sourceCoverageFromEvidence(evidence, candidates) {
     const supplied = new Map((evidence.diagnostics?.sourceCoverage ?? []).map((coverage) => [coverage.source, coverage]));
@@ -535,6 +800,9 @@ function withNormalizedAnalyticalRequirements(evidence, question) {
             ...evidence.parsedIntent,
             measures: requirements.measures,
             dimensions: requirements.dimensions,
+            ...(requirements.time?.grain && !evidence.parsedIntent.timeGrain
+                ? { timeGrain: requirements.time.grain }
+                : {}),
         },
     };
 }
@@ -577,11 +845,160 @@ function relationshipSafetyAllowsAutomaticJoin(safety, requiredJoinKey) {
     return safety.keys.some((key) => metricTermsMatch(normalizeMetricPhrase(key.from), normalizedKey)
         || metricTermsMatch(normalizeMetricPhrase(key.to), normalizedKey));
 }
-function safeRelationshipProofsForCandidate(candidate, requiredJoinKey) {
+/**
+ * Relationship evidence has three deliberately different authorities:
+ *
+ * - governed: a certified, fresh proof may compile a governed relational plan;
+ * - exploratory: an explicitly allowed, validated relation may close a raw
+ *   review-required SQL plan after normal runtime validation; and
+ * - hint: anything weaker may improve retrieval, but can never add a join.
+ *
+ * The first authority remains intentionally stricter.  Reusing it for raw
+ * fallback is what made a missing semantic capability look like a terminal
+ * absence even when the dbt/runtime snapshot had the exact relations, keys,
+ * and fields required to inspect it safely.  This helper never upgrades a
+ * draft relationship to governed trust: callers that use it must select the
+ * exploratory tier and retain review_required provenance.
+ */
+function relationshipSafetyAllowsExploratoryJoin(safety, requiredJoinKey) {
+    const validation = safety.validation;
+    const checkedAt = Date.parse(validation?.checkedAt ?? '');
+    const expiresAt = safety.evidenceExpiresAt ? Date.parse(safety.evidenceExpiresAt) : undefined;
+    const expirationInvalid = safety.evidenceExpiresAt !== undefined
+        && (expiresAt === undefined || !Number.isFinite(expiresAt) || expiresAt <= Date.now());
+    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
+        || safety.fanout !== 'safe'
+        || !['one_to_one', 'one_to_many', 'many_to_one'].includes(safety.cardinality ?? '')
+        || !safety.from?.trim()
+        || !safety.to?.trim()
+        || !validation
+        || validation.status !== 'passed'
+        || !validation.queryFingerprint?.trim()
+        || !validation.proofFingerprint?.trim()
+        || !Number.isFinite(checkedAt)
+        || expirationInvalid
+        || !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));
+}
+/**
+ * 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)
+        : relationshipSafetyAllowsExploratoryJoin(safety, requiredJoinKey);
+}
+function safeRelationshipProofsForCandidate(candidate, requiredJoinKey, authority = 'governed') {
     const referenced = new Set((candidate.relationshipEvidence ?? []).map(normalizedRelationshipIdentity));
     const proofs = new Map();
     for (const safety of candidate.relationshipSafety ?? []) {
-        if (!relationshipSafetyAllowsAutomaticJoin(safety, requiredJoinKey))
+        if (!relationshipSafetyAllowsJoin(safety, authority, requiredJoinKey))
             continue;
         if (!relationshipSafetyIdentities(safety).some((identity) => referenced.has(identity)))
             continue;
@@ -596,6 +1013,210 @@ function candidateRelationshipEndpoints(candidate) {
         candidate.analyticalCapability?.primaryEntityId ?? '',
     ].map(normalizedRelationshipIdentity).filter(Boolean));
 }
+/**
+ * An attribution-required relationship is intentionally not a generic join
+ * failure.  It becomes terminal only when the user explicitly asks to rank an
+ * un-attributed/attribution-scoped signal and the same immutable snapshot
+ * proves that getting from that signal to the requested entity would require
+ * the declared attribution edge.  This keeps neutral unsafe relationship
+ * evidence available for the normal clarification path (AGT-029), while
+ * preventing a bare-ranking metric picker from masking a known governance
+ * boundary with unrelated options.
+ */
+const EXPLICIT_ATTRIBUTION_REQUEST_RE = /\b(?:un[-\s]?attributed|attribution|allocation|allocate)\b/i;
+function relationshipEndpointMatchesQuestionConcept(endpoint, question) {
+    const leaf = normalizedRelationshipIdentity(endpoint).split('::').at(-1) ?? endpoint;
+    const concept = normalizeMetricPhrase(leaf);
+    const conceptTokens = substantiveLexicalTokens(concept);
+    const questionTokens = new Set(substantiveLexicalTokens(question));
+    return conceptTokens.length >= 2 && conceptTokens.every((token) => questionTokens.has(token));
+}
+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 = scopedRelationshipEndpointIdentity(relationship.from, relationship);
+        const to = scopedRelationshipEndpointIdentity(relationship.to, relationship);
+        if (!from || !to)
+            continue;
+        const fromNeighbors = graph.get(from) ?? new Set();
+        fromNeighbors.add(to);
+        graph.set(from, fromNeighbors);
+        const toNeighbors = graph.get(to) ?? new Set();
+        toNeighbors.add(from);
+        graph.set(to, toNeighbors);
+    }
+    const pending = [...starts];
+    const visited = new Set(pending);
+    while (pending.length > 0) {
+        const current = pending.shift();
+        if (targets.has(current))
+            return true;
+        for (const next of graph.get(current) ?? []) {
+            if (!visited.has(next)) {
+                visited.add(next);
+                pending.push(next);
+            }
+        }
+    }
+    return false;
+}
+/**
+ * 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;
+    // Use the complete same-snapshot retrieval result. The compact provider
+    // package is intentionally allowed to omit a relationship card; omission
+    // cannot erase an authored governance restriction before it is evaluated.
+    const snapshotCandidates = [
+        ...input.evidence.candidates,
+        ...(input.evidence.clarificationCandidates ?? []),
+    ].filter((candidate, index, all) => all.findIndex((other) => other.id === candidate.id) === index);
+    const relationships = [...new Map(snapshotCandidates
+            .flatMap((candidate) => candidate.relationshipSafety ?? [])
+            .map((relationship) => [relationship.id, relationship])).values()]
+        .filter((relationship) => Boolean(relationship.from?.trim() && relationship.to?.trim()));
+    const attributionRequired = relationships.filter((relationship) => relationship.fanout === 'attribution_required');
+    if (attributionRequired.length === 0)
+        return undefined;
+    const targetEndpoints = new Set(snapshotCandidates
+        .flatMap((candidate) => [...candidateRelationshipEndpoints(candidate)])
+        .filter((endpoint) => relationshipEndpointMatchesEntityTerms(endpoint, input.requirements.entityTerms)));
+    if (targetEndpoints.size === 0)
+        return undefined;
+    const attributed = attributionRequired.find((relationship) => {
+        const endpoints = [
+            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)
+            return false;
+        // The declared graph can demonstrate why the requested entity would need
+        // this relation, but only a fully certified/fanout-safe graph may
+        // authorize automatic composition. A path that requires this edge is a
+        // typed modeling gap, never a reason to invent an attribution join.
+        const allReachable = relationshipGraphReaches(requestedSignalEndpoints, targetEndpoints, relationships);
+        const safeRelationships = relationships.filter((candidate) => relationshipSafetyAllowsAutomaticJoin(candidate));
+        const safelyReachable = relationshipGraphReaches(requestedSignalEndpoints, targetEndpoints, safeRelationships);
+        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;
+    const coverage = sourceCoverageFromEvidence(input.evidence, snapshotCandidates);
+    const coverageFor = (source) => coverage.find((item) => item.source === source);
+    const skipped = (tier) => {
+        const item = coverageFor(tier);
+        return {
+            version: 1,
+            tier,
+            outcome: item?.status === 'available' ? 'ineligible' : 'unavailable',
+            candidateIds: item?.candidateIds ?? [],
+            reason: item?.status === 'available'
+                ? `The ${tier} tier did not prove the complete attribution-safe requested tuple before plan freeze.`
+                : `The ${tier} source was ${item?.status ?? 'unavailable'} in this snapshot.`,
+            planFrozen: false,
+        };
+    };
+    const message = 'The requested un-attributed signal requires a certified attribution relationship or approved allocation policy before it can be ranked by the requested entity. DQL did not infer a relationship or execute a query.';
+    const witnessCandidateIds = [attributed.id];
+    const terminalGap = {
+        code: 'MISSING_RELATIONSHIP',
+        missing: ['a certified attribution relationship or approved allocation policy for the requested un-attributed signal'],
+        witnessCandidateIds,
+    };
+    const observer = askTraceObserverForV1(input.request);
+    for (const candidate of snapshotCandidates.filter((candidate) => (candidate.relationshipSafety ?? []).some((relationship) => relationship.id === attributed.id))) {
+        observer.recordCandidateDecision({
+            candidateId: candidate.id,
+            role: 'relationship',
+            source: traceSourceForCandidate(candidate),
+            decision: 'excluded',
+            reasonCode: 'policy_denied',
+            compatibilityCode: 'unknown',
+        });
+    }
+    return {
+        ...input.base,
+        action: 'block',
+        confidence: 1,
+        reason: message,
+        source: 'heuristic',
+        category: 'data_lookup',
+        depth: 'quick',
+        requiresClarification: false,
+        clarifyingQuestion: undefined,
+        clarificationOptions: undefined,
+        retrievalEvidence: retrievalTrace(input.evidence, snapshotCandidates),
+        terminalOutcome: {
+            kind: 'modeling_gap',
+            code: 'ANALYTICAL_MODELING_GAP',
+            message,
+            candidateIds: witnessCandidateIds,
+            gap: terminalGap,
+        },
+        analyticalCascadeDecision: buildAnalyticalCascadeDecision({
+            requirements: input.requirements,
+            sourceCoverage: coverage,
+            attempts: [
+                skipped('certified'),
+                skipped('semantic'),
+                {
+                    version: 1,
+                    tier: 'governed_relational',
+                    outcome: 'denied',
+                    candidateIds: witnessCandidateIds,
+                    reason: 'The declared relationship requires attribution or allocation approval and cannot authorize the requested ranking.',
+                    planFrozen: false,
+                },
+            ],
+            planFrozen: false,
+            terminalGap: cascadeTerminalRelationshipGap(terminalGap),
+            stopReason: 'denied',
+        }),
+        resolvedAnalyticalPlan: undefined,
+        meaningResolution: undefined,
+    };
+}
 /**
  * A proof may be structurally safe yet belong to a different domain's relation
  * with the same leaf name. The selected pair must match the proof's canonical
@@ -609,9 +1230,9 @@ function relationshipProofMatchesSelectedPair(safety, left, right) {
     return Boolean(from && to && ((leftEndpoints.has(from) && rightEndpoints.has(to))
         || (leftEndpoints.has(to) && rightEndpoints.has(from))));
 }
-function safeRelationshipProofsForPair(left, right, requiredJoinKey) {
-    const leftProofs = safeRelationshipProofsForCandidate(left, requiredJoinKey);
-    const rightProofs = safeRelationshipProofsForCandidate(right, requiredJoinKey);
+function safeRelationshipProofsForPair(left, right, requiredJoinKey, authority = 'governed') {
+    const leftProofs = safeRelationshipProofsForCandidate(left, requiredJoinKey, authority);
+    const rightProofs = safeRelationshipProofsForCandidate(right, requiredJoinKey, authority);
     const shared = new Map();
     for (const [id, proof] of leftProofs) {
         const pairedProof = rightProofs.get(id);
@@ -637,7 +1258,13 @@ function hasSafeExploratoryPhysicalPath(requirements, candidates, missingDimensi
     // their safe-value validation happens independently from proving the raw
     // physical closure.  Treating them as fields made a valid relation appear
     // unmodeled and produced a false absence diagnostic.
-    const terms = [...new Set([...missingDimensions, ...requirements.measures, ...requiredPhysicalFieldTerms]
+    const terms = [...new Set([
+            ...missingDimensions,
+            ...requirements.measures,
+            ...requirements.entityDisplayTerms,
+            ...(requirements.outputTerms ?? []),
+            ...requiredPhysicalFieldTerms,
+        ]
             .map(normalizeMetricPhrase)
             .filter(Boolean))];
     if (terms.length === 0) {
@@ -668,6 +1295,8 @@ function hasSafeExploratoryPhysicalPath(requirements, candidates, missingDimensi
     const physicalRoleAliases = {
         'product category': ['product type'],
         category: ['product type'],
+        customer: ['customer name'],
+        account: ['account name'],
         // `product_price` is a local revenue witness only when the same request
         // also requires product-category grain. It must not let a bare selected
         // revenue metric bypass its semantic contract through an unrelated raw
@@ -762,7 +1391,8 @@ function hasSafeExploratoryPhysicalPath(requirements, candidates, missingDimensi
     // routinely contains unrelated raw tables; requiring every one to join made
     // a complete local path appear unavailable. Conversely, never infer a join
     // from names or shared column strings: the proof must retain the structured
-    // certified, validated, fanout-safe disposition above.
+    // exploratory-safe disposition above. A selected path remains
+    // review-required; it is not a governed relational plan.
     const adjacent = relations.map(() => new Set());
     const joinColumnsForProof = (proof, left, right) => {
         const leftEndpoints = candidateRelationshipEndpoints(left);
@@ -793,7 +1423,7 @@ function hasSafeExploratoryPhysicalPath(requirements, candidates, missingDimensi
     const witnessesForEdge = new Map();
     for (let left = 0; left < relations.length; left += 1) {
         for (let right = left + 1; right < relations.length; right += 1) {
-            const shared = [...safeRelationshipProofsForPair(relations[left], relations[right]).values()]
+            const shared = [...safeRelationshipProofsForPair(relations[left], relations[right], undefined, 'exploratory').values()]
                 .sort((first, second) => first.id.localeCompare(second.id))
                 .flatMap((proof) => {
                 const joinColumns = joinColumnsForProof(proof, relations[left], relations[right]);
@@ -853,7 +1483,7 @@ function hasSafeExploratoryPhysicalPath(requirements, candidates, missingDimensi
         return {
             ok: false,
             candidateIds: [],
-            reason: 'Multiple physical relations lacked one connected, certified, validated, fanout-safe automatic-join path.',
+            reason: 'Multiple physical relations lacked one connected, structured, fanout-safe exploratory join path.',
             // This is not a lexical conclusion. Every requested physical field was
             // found above, no one relation covered the tuple, and the structured
             // relationship/fanout proof graph could not connect the required
@@ -861,7 +1491,7 @@ function hasSafeExploratoryPhysicalPath(requirements, candidates, missingDimensi
             // receipts and repair guidance.
             gap: {
                 code: 'MISSING_RELATIONSHIP',
-                missing: ['a connected certified, validated, fanout-safe relationship proof'],
+                missing: ['a connected, explicitly allowed, validated, fanout-safe relationship proof'],
                 witnessCandidateIds: stableCandidates(relations).map(stableCandidateId),
             },
         };
@@ -875,7 +1505,7 @@ function hasSafeExploratoryPhysicalPath(requirements, candidates, missingDimensi
     if (selectedWitnesses.length !== selected.edges.length) {
         return { ok: false, candidateIds: [], reason: 'The selected relationship closure lacked qualified join-key witnesses for every automatic join.' };
     }
-    return physicalEvidence(selectedRelations, requiredColumns, selectedWitnesses.flatMap((witness) => witness.columns), selectedWitnesses.map((witness) => witness.proof.id), 'Qualified physical relations and structured relationship safety proofs support a bounded exploratory plan.');
+    return physicalEvidence(selectedRelations, requiredColumns, selectedWitnesses.flatMap((witness) => witness.columns), selectedWitnesses.map((witness) => witness.proof.id), 'Qualified physical relations and explicitly allowed relationship proofs support a bounded exploratory plan.');
 }
 /**
  * The pre-freeze cascade is router authority, including when the bounded
@@ -888,27 +1518,84 @@ 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 = input.evidence.candidates.length > 0
-        ? input.evidence.candidates
-        : 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
         && input.requirements.ranking
         && input.requirements.ranking.metricTerms.length === 0);
     const exploratoryExecutable = physicalPath.ok && !missingRankingMetric;
+    const selectedPhysicalLegacyIds = snapshotCandidates
+        .filter((candidate) => physicalPath.candidateIds.includes(candidate.qualifiedId ?? candidate.id))
+        .map((candidate) => candidate.id);
+    const selectedPhysicalIdsForPlan = selectedPhysicalLegacyIds.length > 0
+        ? selectedPhysicalLegacyIds
+        : physicalPath.candidateIds;
+    // The physical cascade is still an authoritative Ask route, not a legacy
+    // escape hatch. Recreate the same host-owned seed used before the meaning
+    // call so a semantic miss cannot erase an explicit entity display key,
+    // member/filter, ranking limit, time role, or output tuple on the way to
+    // review-required exploration.
+    const hostRequirementSeed = buildAnalyticalRequirementSeedV1({
+        question: input.question,
+        parsedIntent: input.evidence.parsedIntent,
+        requirements: input.requirements,
+        fiscalCalendar: declaredFiscalCalendar(input.evidence, snapshotCandidates),
+    });
+    // The router, not the SQL generator, owns analytical meaning and the
+    // physical closure.  Freeze that selected exploratory plan before a model
+    // sees SQL work.  The host later attaches an authorization receipt for the
+    // exact read-only SQL/target; it must never be the event that changes the
+    // selected tier or reinterprets this request.
+    const exploratoryMeaning = exploratoryExecutable
+        ? {
+            interpretedQuestion: input.question,
+            questionType: questionTypeFromText(input.question),
+            selectedConceptIds: selectedPhysicalIdsForPlan,
+            recommendedExecutionId: selectedPhysicalIdsForPlan[0],
+            queryIntent: queryIntentFromRequirementSeed(hostRequirementSeed),
+            rejectedCandidates: [],
+            // Low confidence is intentionally non-executable in a resolved plan.
+            // This is a router-proven physical closure, not a speculative model
+            // answer, so the confidence describes the selected route only.
+            confidence: 'high',
+            missingInformation: [],
+            recommendedRoute: 'exploratory',
+            hostRequirementSeed,
+            compatibilityOutcome: 'modeling_gap',
+            compatibilityFailures: input.missingTerms.map((term) => ({
+                code: 'MISSING_DIMENSION',
+                field: term,
+                message: `${term} was not complete in the earlier governed tiers.`,
+                candidateIds: [],
+            })),
+        }
+        : undefined;
+    const resolvedAnalyticalPlan = exploratoryMeaning
+        ? buildResolvedAnalyticalPlan({
+            question: input.question,
+            resolution: exploratoryMeaning,
+            evidence: input.evidence,
+            candidates: snapshotCandidates,
+            mode: 'authoritative',
+        })
+        : undefined;
+    const exploratoryPlanFrozen = resolvedAnalyticalPlan?.capability === 'bounded_exploration';
     const coverage = sourceCoverageFromEvidence(input.evidence, snapshotCandidates);
     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,
         };
     };
@@ -934,7 +1621,7 @@ function preFreezePhysicalCascadeDecision(input) {
             reason: missingRankingMetric
                 ? `${physicalPath.reason} A ranking measure remains unbound, so exploration cannot be selected.`
                 : physicalPath.reason,
-            planFrozen: false,
+            planFrozen: exploratoryPlanFrozen,
         },
     ];
     const message = exploratoryExecutable
@@ -956,7 +1643,7 @@ function preFreezePhysicalCascadeDecision(input) {
                     planFrozen: false,
                 }],
         ...(exploratoryExecutable ? { selectedTier: 'exploratory_sql' } : {}),
-        planFrozen: false,
+        planFrozen: exploratoryPlanFrozen,
         stopReason: exploratoryExecutable ? 'selected' : missingRankingMetric ? 'ambiguous' : 'coverage_gap',
     });
     if (!exploratoryExecutable) {
@@ -997,29 +1684,131 @@ function preFreezePhysicalCascadeDecision(input) {
         clarificationOptions: undefined,
         retrievalEvidence: retrievalTrace(input.evidence, snapshotCandidates),
         analyticalCascadeDecision,
-        meaningResolution: {
-            interpretedQuestion: input.question,
-            questionType: questionTypeFromText(input.question),
-            selectedConceptIds: physicalPath.candidateIds,
-            queryIntent: {
-                ...defaultQueryIntent(input.evidence),
-                measures: input.requirements.measures,
-                dimensions: input.requirements.dimensions,
-                filters: input.evidence.parsedIntent?.filters ?? [],
-            },
-            rejectedCandidates: [],
-            confidence: 'low',
-            missingInformation: [message],
-            recommendedRoute: 'exploratory',
-            compatibilityOutcome: 'modeling_gap',
-            compatibilityFailures: input.missingTerms.map((term) => ({
-                code: 'MISSING_DIMENSION',
-                field: term,
-                message: `${term} was not complete in the earlier governed tiers.`,
-                candidateIds: [],
-            })),
-        },
-        resolvedAnalyticalPlan: undefined,
+        meaningResolution: exploratoryMeaning,
+        resolvedAnalyticalPlan,
+    };
+}
+/**
+ * The compact meaning package is deliberately not a proof-of-absence set.
+ * Preserve the complete immutable retrieval snapshot for physical closure and
+ * 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, executionCandidateIds) {
+    const byId = new Map();
+    for (const candidate of [
+        ...evidence.candidates,
+        ...(evidence.clarificationCandidates ?? []),
+        ...candidates,
+    ]) {
+        if (!byId.has(candidate.id))
+            byId.set(candidate.id, candidate);
+    }
+    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
+ * modeling card whose declared execution contract cannot satisfy the exact
+ * tuple.  Before presenting that *pre-freeze* modeling gap as terminal,
+ * inspect the complete immutable snapshot for one bounded, relationship-safe
+ * physical closure.  This is not a post-freeze downgrade: policy, fiscal, and
+ * unsafe failures remain blocked and a safe result is explicitly
+ * review-required exploratory work.
+ */
+function continuePreFreezeModelingGapThroughPhysicalSnapshot(input) {
+    const { decision, evidence } = input;
+    const plan = decision.resolvedAnalyticalPlan;
+    if (!plan
+        || decision.terminalOutcome?.kind !== 'modeling_gap'
+        || decision.analyticalCascadeDecision?.planFrozen === true
+        || (plan.recommendedRoute !== 'semantic' && plan.recommendedRoute !== 'governed_sql'))
+        return decision;
+    const selectedPreFreezeTier = plan.recommendedRoute;
+    const requirements = buildAnalyticalRequirementSet({
+        question: input.question,
+        parsedIntent: input.evidence.parsedIntent,
+    });
+    const unresolved = plan.resolutionFailure?.bindings
+        .filter((binding) => binding.status !== 'resolved')
+        .map((binding) => binding.requested) ?? [];
+    const missingTerms = [...new Set([
+            ...unresolved,
+            ...requirements.dimensions,
+            ...requirements.entityTerms,
+            ...requirements.entityDisplayTerms,
+            ...(plan.outputContract.requiredOutputs ?? []).map((binding) => binding.requested),
+        ])];
+    const requiredPhysicalFieldTerms = [...new Set([
+            ...requirements.dimensions,
+            ...requirements.entityTerms,
+            ...requirements.entityDisplayTerms,
+            ...(plan.outputContract.requiredOutputs ?? []).map((binding) => binding.requested),
+            ...(plan.query.filters ?? []).map((filter) => filter.field),
+            ...unresolved,
+        ])];
+    const physicalContinuation = preFreezePhysicalCascadeDecision({
+        base: input.base,
+        evidence,
+        candidates: immutableSnapshotCandidates(evidence, input.candidates, input.executionCandidateIds),
+        question: input.question,
+        requirements,
+        missingTerms,
+        requiredPhysicalFieldTerms,
+        messagePrefix: selectedPreFreezeTier === 'governed_sql'
+            ? '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') {
+        return physicalContinuation;
+    }
+    // The physical extension was considered and was not safe/executable. Keep
+    // the original immutable semantic plan and its typed failure rather than
+    // replacing it with a synthetic exploratory meaning; surface the full
+    // snapshot cascade evidence so the terminal block explains why it could not
+    // continue. This retains policy/unsafe/fiscal terminal semantics.
+    return {
+        ...decision,
+        reason: physicalContinuation.reason,
+        retrievalEvidence: physicalContinuation.retrievalEvidence,
+        analyticalCascadeDecision: physicalContinuation.analyticalCascadeDecision,
+        terminalOutcome: physicalContinuation.terminalOutcome ?? decision.terminalOutcome,
     };
 }
 /**
@@ -1102,7 +1891,7 @@ function findSafeComplementaryPhysicalComposition(question, candidates) {
                     const joinKey = displayColumnsOnRelation.flatMap(columnJoinKeys).find((key) => predicateJoinKeys.has(key));
                     if (!joinKey)
                         continue;
-                    const sharedRelationshipProofIds = [...safeRelationshipProofsForPair(displayRelation, predicateRelation, joinKey).keys()];
+                    const sharedRelationshipProofIds = [...safeRelationshipProofsForPair(displayRelation, predicateRelation, joinKey, 'exploratory').keys()];
                     if (sharedRelationshipProofIds.length === 0)
                         continue;
                     const selectedPhysical = [
@@ -1148,10 +1937,40 @@ function complementaryExploratoryDecision(base, evidence, candidates, question)
     // Use all already-retrieved cards from the same snapshot. The bounded meaning
     // package can omit a supporting raw join column, but no new retrieval/domain
     // scope is opened here.
-    const composition = findSafeComplementaryPhysicalComposition(question, evidence.candidates);
+    const snapshotCandidates = immutableSnapshotCandidates(evidence, candidates);
+    const composition = findSafeComplementaryPhysicalComposition(question, snapshotCandidates);
     if (!composition)
         return undefined;
-    const coverage = sourceCoverageFromEvidence(evidence, evidence.candidates);
+    const coverage = sourceCoverageFromEvidence(evidence, snapshotCandidates);
+    const exploratoryMeaning = {
+        interpretedQuestion: question,
+        questionType: questionTypeFromText(question),
+        selectedConceptIds: composition.candidateIds,
+        recommendedExecutionId: composition.displayColumn.qualifiedId ?? composition.displayColumn.id,
+        queryIntent: {
+            measures: [],
+            dimensions: [composition.displayColumn.qualifiedId ?? composition.displayColumn.id],
+            filters: [{
+                    field: composition.predicateColumn.qualifiedId ?? composition.predicateColumn.id,
+                    value: 'true',
+                }],
+        },
+        rejectedCandidates: [],
+        confidence: 'high',
+        missingInformation: [],
+        recommendedRoute: 'exploratory',
+        compatibilityOutcome: 'modeling_gap',
+    };
+    const resolvedAnalyticalPlan = buildResolvedAnalyticalPlan({
+        question,
+        resolution: exploratoryMeaning,
+        evidence,
+        candidates: snapshotCandidates,
+        mode: 'authoritative',
+    });
+    const exploratoryPlanFrozen = resolvedAnalyticalPlan.capability === 'bounded_exploration';
+    if (!exploratoryPlanFrozen)
+        return undefined;
     const coverageFor = (source) => coverage.find((item) => item.source === source);
     const skippedAttempt = (tier, source, reason) => {
         const item = coverageFor(source);
@@ -1184,7 +2003,7 @@ function complementaryExploratoryDecision(base, evidence, candidates, question)
             outcome: 'executable',
             candidateIds: composition.candidateIds,
             reason: composition.reason,
-            planFrozen: false,
+            planFrozen: exploratoryPlanFrozen,
         },
     ];
     const analyticalCascadeDecision = buildAnalyticalCascadeDecision({
@@ -1192,7 +2011,7 @@ function complementaryExploratoryDecision(base, evidence, candidates, question)
         sourceCoverage: coverage,
         attempts,
         selectedTier: 'exploratory_sql',
-        planFrozen: false,
+        planFrozen: exploratoryPlanFrozen,
         stopReason: 'selected',
     });
     return {
@@ -1204,27 +2023,10 @@ function complementaryExploratoryDecision(base, evidence, candidates, question)
         depth: 'quick',
         reason: `${composition.reason} Certified and semantic execution did not freeze; generated SQL remains review_required.`,
         requiresClarification: false,
-        retrievalEvidence: retrievalTrace(evidence, candidates),
+        retrievalEvidence: retrievalTrace(evidence, snapshotCandidates),
         analyticalCascadeDecision,
-        resolvedAnalyticalPlan: undefined,
-        meaningResolution: {
-            interpretedQuestion: question,
-            questionType: questionTypeFromText(question),
-            selectedConceptIds: composition.candidateIds,
-            recommendedExecutionId: composition.displayColumn.qualifiedId ?? composition.displayColumn.id,
-            queryIntent: {
-                measures: [],
-                dimensions: [composition.displayColumn.qualifiedId ?? composition.displayColumn.id],
-                filters: [{
-                        field: composition.predicateColumn.qualifiedId ?? composition.predicateColumn.id,
-                        value: 'true',
-                    }],
-            },
-            rejectedCandidates: [],
-            confidence: 'low',
-            missingInformation: ['No certified or semantic route proved the complete composed request.'],
-            recommendedRoute: 'exploratory',
-        },
+        resolvedAnalyticalPlan,
+        meaningResolution: exploratoryMeaning,
     };
 }
 function cascadeForResolution(input) {
@@ -1262,6 +2064,7 @@ function cascadeForResolution(input) {
         attempts,
         ...(selectedTier ? { selectedTier } : {}),
         planFrozen: frozen,
+        ...(input.terminalGap ? { terminalGap: input.terminalGap } : {}),
         stopReason: input.reconciliation.outcome === 'ready' ? 'selected' : input.reconciliation.outcome === 'clarify' ? 'ambiguous' : input.reconciliation.outcome === 'policy_blocked' ? 'denied' : 'coverage_gap',
     });
 }
@@ -1304,6 +2107,9 @@ function routeDecisionForResolution(base, evidence, candidates, resolution, sour
     const analytical = routedResolution.questionType === "diagnosis" ||
         routedResolution.questionType === "research";
     const reason = reconciliation.reason;
+    const terminalGap = reconciliation.outcome === 'modeling_gap'
+        ? terminalGapWitnessForResolutionFailure(resolvedAnalyticalPlan)
+        : undefined;
     const analyticalCascadeDecision = cascadeForResolution({
         evidence,
         candidates,
@@ -1311,12 +2117,22 @@ function routeDecisionForResolution(base, evidence, candidates, resolution, sour
         plan: resolvedAnalyticalPlan,
         reconciliation,
         question,
+        ...(terminalGap ? { terminalGap: cascadeTerminalRelationshipGap(terminalGap) } : {}),
     });
-    const terminalGap = reconciliation.outcome === 'modeling_gap'
-        ? terminalGapWitnessForResolutionFailure(resolvedAnalyticalPlan)
-        : undefined;
+    const declaredDimensionAssumptions = assumptionsForDeclaredDimensionAlternatives({
+        question,
+        evidence,
+        candidates,
+        plan: resolvedAnalyticalPlan,
+    });
+    // The deterministic pre-router may attach a generic soft clarification
+    // while retrieval is still incomplete. Once this same turn has bound and
+    // frozen a plan, that stale prompt must not leak into a completed answer or
+    // its trace. Keep a clarification only when reconciliation itself says the
+    // final immutable tuple is genuinely ambiguous.
+    const { clarifyingQuestion: _staleClarifyingQuestion, clarificationOptions: _staleClarificationOptions, clarifySoft: _staleClarifySoft, ...baseWithoutStaleClarification } = base;
     return {
-        ...base,
+        ...baseWithoutStaleClarification,
         action: needsClarification
             ? "clarify"
             : terminallyBlocked
@@ -1359,8 +2175,270 @@ function routeDecisionForResolution(base, evidence, candidates, resolution, sour
         ...(needsClarification
             ? {
                 clarifyingQuestion: reconciliation.question,
+                ...(_staleClarifySoft ? { clarifySoft: true } : {}),
             }
             : {}),
+        ...(declaredDimensionAssumptions.length > 0
+            ? { assumptions: declaredDimensionAssumptions }
+            : {}),
+    };
+}
+/**
+ * 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,
+            },
+        },
     };
 }
 /**
@@ -1524,6 +2602,7 @@ function reconcileResolvedPlanOutcome(resolution, plan, candidates) {
         ...plan.query.measures.map((binding) => ({ kind: 'measure', binding })),
         ...plan.query.dimensions.map((binding) => ({ kind: 'dimension', binding })),
         ...plan.query.filters.map((filter) => ({ kind: 'filter', binding: filter.binding })),
+        ...(plan.outputContract.requiredOutputs ?? []).map((binding) => ({ kind: 'output', binding })),
     ].filter(({ binding }) => binding.status !== 'resolved');
     const qualifiedChoiceIds = [...new Set(bindings.flatMap(({ binding }) => binding.candidateIds))].sort();
     const userResolvableBinding = bindings.some(({ binding }) => binding.candidateIds.length > 0);
@@ -1664,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',
         };
@@ -1674,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;
@@ -1686,19 +2778,57 @@ function routedClarificationQuestion(resolution, bindings, options) {
     return resolution.clarifyingQuestion
         ?? `Which governed binding should I use before running this query?`;
 }
-function continueCascadeAfterIncompleteSelection(base, evidence, candidates, selected, question) {
+function continueCascadeAfterIncompleteSelection(base, evidence, candidates, selected, question, selectedConceptIds = [selected.id]) {
     // Preserve the exact stable ID emitted by the clarification option. A
     // candidate may also carry a source-qualified execution alias, but replacing
     // the clicked ID here makes the persisted ambiguity contract and the later
     // diagnostic receipt disagree even though the user chose a legitimate item.
     const selectedId = selected.id;
+    // A server-issued display-key click has already passed the snapshot and
+    // metric-capability checks. If its tuple is pre-freeze-ineligible, preserve
+    // both the metric authority and the exact clicked ID through the typed gap
+    // or same-snapshot exploratory continuation. Reconstructing only the
+    // metric made restart receipts falsely look as though no choice was made.
+    const preservedSelectionIds = [...new Set([
+            ...selectedConceptIds.filter((id) => Boolean(id?.trim())),
+            selectedId,
+        ])];
+    // A structured choice is validated against its exact stable identity, but an
+    // incomplete selected capability must evaluate physical eligibility against
+    // the entire immutable snapshot—not the compact model package that happened
+    // to carry the clarification. This is one same-snapshot extension only.
+    const snapshotCandidates = immutableSnapshotCandidates(evidence, candidates);
     const requirements = buildAnalyticalRequirementSet({ question, parsedIntent: evidence.parsedIntent });
     const requiredPhysicalFieldTerms = [
         ...(evidence.parsedIntent?.dimensions ?? []),
         ...(evidence.parsedIntent?.filters ?? []).map((filter) => filter.field),
     ];
-    const physicalPath = hasSafeExploratoryPhysicalPath(requirements, candidates, requirements.dimensions, requiredPhysicalFieldTerms);
-    const coverage = sourceCoverageFromEvidence(evidence, candidates);
+    const physicalPath = hasSafeExploratoryPhysicalPath(requirements, snapshotCandidates, requirements.dimensions, requiredPhysicalFieldTerms);
+    // A structured clarification consumes the exact selected ID once, but an
+    // incomplete governed capability is not a post-freeze terminal.  Reuse the
+    // router-owned physical cascade so the same-snapshot exploratory closure is
+    // resolved and frozen *before* SQL is generated.  The host may later attach
+    // only an authorization receipt for that frozen plan; it must not select or
+    // freeze another plan after SQL exists.
+    if (physicalPath.ok) {
+        return preFreezePhysicalCascadeDecision({
+            base,
+            evidence,
+            candidates: snapshotCandidates,
+            question,
+            requirements,
+            missingTerms: [...new Set([
+                    ...requirements.dimensions,
+                    ...requirements.entityTerms,
+                    ...requirements.entityDisplayTerms,
+                ])],
+            requiredPhysicalFieldTerms,
+            messagePrefix: `The selected governed meaning ${selectedId} did not prove the complete requested tuple. DQL consumed that selection once and did not substitute a correlated metric or execute a different artifact;`,
+            terminalCandidateIds: preservedSelectionIds,
+            requireRankingMetric: Boolean(requirements.ranking),
+        });
+    }
+    const coverage = sourceCoverageFromEvidence(evidence, snapshotCandidates);
     const governedCoverage = coverage.find((item) => item.source === 'governed_relational');
     const attempts = [
         {
@@ -1713,7 +2843,7 @@ function continueCascadeAfterIncompleteSelection(base, evidence, candidates, sel
             version: 1,
             tier: 'semantic',
             outcome: 'ineligible',
-            candidateIds: [...new Set([selectedId, ...(coverage.find((item) => item.source === 'semantic')?.candidateIds ?? [])])],
+            candidateIds: [...new Set([...preservedSelectionIds, ...(coverage.find((item) => item.source === 'semantic')?.candidateIds ?? [])])],
             reason: `The explicit selection ${selectedId} was consumed once but did not prove the complete semantic tuple.`,
             planFrozen: false,
         },
@@ -1744,7 +2874,7 @@ function continueCascadeAfterIncompleteSelection(base, evidence, candidates, sel
         sourceCoverage: coverage,
         attempts: physicalPath.ok
             ? attempts
-            : [...attempts, { version: 1, tier: 'clarify_or_gap', outcome: 'unavailable', candidateIds: [selectedId], reason: message, planFrozen: false }],
+            : [...attempts, { version: 1, tier: 'clarify_or_gap', outcome: 'unavailable', candidateIds: preservedSelectionIds, reason: message, planFrozen: false }],
         ...(physicalPath.ok ? { selectedTier: 'exploratory_sql' } : {}),
         planFrozen: false,
         stopReason: physicalPath.ok ? 'selected' : 'coverage_gap',
@@ -1752,7 +2882,7 @@ function continueCascadeAfterIncompleteSelection(base, evidence, candidates, sel
     const meaningResolution = {
         interpretedQuestion: question,
         questionType: 'value',
-        selectedConceptIds: [selectedId],
+        selectedConceptIds: preservedSelectionIds,
         queryIntent: defaultQueryIntent(evidence),
         rejectedCandidates: [],
         confidence: 'low',
@@ -1763,7 +2893,7 @@ function continueCascadeAfterIncompleteSelection(base, evidence, candidates, sel
                 code: 'INCOMPLETE_SELECTED_CAPABILITY',
                 field: 'selected capability',
                 message,
-                candidateIds: [selectedId],
+                candidateIds: preservedSelectionIds,
             }],
     };
     if (!physicalPath.ok) {
@@ -1775,7 +2905,7 @@ function continueCascadeAfterIncompleteSelection(base, evidence, candidates, sel
             source: 'heuristic',
             category: 'data_lookup',
             depth: 'quick',
-            retrievalEvidence: retrievalTrace(evidence, candidates),
+            retrievalEvidence: retrievalTrace(evidence, snapshotCandidates),
             requiresClarification: false,
             resolvedAnalyticalPlan: undefined,
             meaningResolution,
@@ -1784,7 +2914,7 @@ function continueCascadeAfterIncompleteSelection(base, evidence, candidates, sel
                 kind: 'modeling_gap',
                 code: 'ANALYTICAL_MODELING_GAP',
                 message,
-                candidateIds: [selectedId],
+                candidateIds: preservedSelectionIds,
                 ...(physicalPath.gap ? { gap: physicalPath.gap } : {}),
             },
         };
@@ -1797,7 +2927,7 @@ function continueCascadeAfterIncompleteSelection(base, evidence, candidates, sel
         source: 'heuristic',
         category: 'data_lookup',
         depth: 'quick',
-        retrievalEvidence: retrievalTrace(evidence, candidates),
+        retrievalEvidence: retrievalTrace(evidence, snapshotCandidates),
         requiresClarification: false,
         resolvedAnalyticalPlan: undefined,
         meaningResolution,
@@ -1857,12 +2987,38 @@ function enforceAnalyticalCompatibility(resolution, evidence, candidates) {
         const metricEvidence = candidates.filter((candidate) => candidate.kind === "semantic_metric" &&
             candidate.analyticalCapability?.metricId &&
             metricIds.has(candidate.analyticalCapability.metricId));
+        // Preserve an already validated semantic member when the resulting frame
+        // proves that the selected metric owns that exact dimension. This is how a
+        // server-issued “Account Name” clarification continues alongside the
+        // explicit Revenue metric; stripping it here made trace meaning IDs and
+        // durable continuation state look empty even though the frame was valid.
+        const selectedFrameMembers = resolution.selectedConceptIds.flatMap((id) => {
+            const member = candidates.find((candidate) => candidate.id === id);
+            if (member?.kind !== 'semantic_member')
+                return [];
+            const resolvesIntoFrame = metricEvidence.some((metric) => {
+                const identities = [
+                    member.qualifiedId,
+                    member.id,
+                    member.name,
+                    ...(member.aliases ?? []),
+                ].filter((identity) => Boolean(identity));
+                return identities.some((identity) => {
+                    const dimension = resolveMetricCapabilityDimension(metric, identity);
+                    return Boolean(dimension && result.frame.dimensions.some((binding) => binding.dimensionId === dimension.dimensionId));
+                });
+            });
+            return resolvesIntoFrame ? [member.id] : [];
+        });
         return {
             ...resolution,
             analyticalFrame: result.frame,
             analyticalPolicyIds: result.policyIds,
             ...(metricEvidence.length > 0
-                ? { selectedConceptIds: metricEvidence.map((candidate) => candidate.id) }
+                ? { selectedConceptIds: [...new Set([
+                            ...metricEvidence.map((candidate) => candidate.id),
+                            ...selectedFrameMembers,
+                        ])] }
                 : {}),
             recommendedExecutionId: result.candidateId,
             recommendedRoute: result.route,
@@ -1904,7 +3060,12 @@ function enforceAnalyticalCompatibility(resolution, evidence, candidates) {
         analyticalFrame: result.frame,
         analyticalPolicyIds: result.policyIds,
         confidence: result.status === "clarify" ? "low" : resolution.confidence,
-        recommendedRoute: "clarify",
+        // A compatibility block is a pre-freeze failure of the nominated tier,
+        // not a new model decision to route somewhere else. Retain the semantic
+        // nomination so the authoritative cascade can inspect the complete
+        // same-snapshot qualified physical closure. Only genuine multi-option
+        // ambiguity changes the route to clarification.
+        recommendedRoute: result.status === 'clarify' ? 'clarify' : resolution.recommendedRoute,
         compatibilityOutcome,
         compatibilityFailures,
         missingInformation: [
@@ -1940,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,
         };
@@ -1981,6 +3142,9 @@ function persistedClarificationSelectionContext(request) {
     const sourceTurnId = typeof pendingRecord.sourceTurnId === 'string' && pendingRecord.sourceTurnId.trim()
         ? pendingRecord.sourceTurnId.trim()
         : undefined;
+    const sourceQuestion = typeof pendingRecord.sourceQuestion === 'string' && pendingRecord.sourceQuestion.trim()
+        ? pendingRecord.sourceQuestion.trim()
+        : undefined;
     const threadId = typeof envelope?.threadId === 'string' && envelope.threadId.trim()
         ? envelope.threadId.trim()
         : undefined;
@@ -2016,6 +3180,7 @@ function persistedClarificationSelectionContext(request) {
         ...(requirements ? { requirements } : {}),
         ...(snapshotId ? { snapshotId } : {}),
         ...(sourceTurnId ? { sourceTurnId } : {}),
+        ...(sourceQuestion ? { sourceQuestion } : {}),
         ...(threadId ? { threadId } : {}),
         serverIssued: !invalidReason,
         ...(invalidReason ? { invalidReason } : {}),
@@ -2100,17 +3265,182 @@ function mergeClarificationRequirements(current, persisted) {
         entityTerms: [...new Set([...current.entityTerms, ...(persisted.entityTerms ?? [])])],
         entityDisplayTerms: [...new Set([...current.entityDisplayTerms, ...(persisted.entityDisplayTerms ?? [])])],
         memberTerms: [...new Set([...current.memberTerms, ...(persisted.memberTerms ?? [])])],
+        ...(current.ranking || persisted.ranking
+            ? {
+                ranking: current.ranking && persisted.ranking
+                    ? {
+                        ...current.ranking,
+                        metricTerms: [...new Set([...current.ranking.metricTerms, ...persisted.ranking.metricTerms])],
+                        entityTerms: [...new Set([...current.ranking.entityTerms, ...persisted.ranking.entityTerms])],
+                    }
+                    : current.ranking ?? persisted.ranking,
+            }
+            : {}),
+        ...(current.time || persisted.time
+            ? {
+                time: current.time && persisted.time
+                    ? {
+                        ...current.time,
+                        grain: current.time.grain ?? persisted.time.grain,
+                        fiscalPeriod: current.time.fiscalPeriod ?? persisted.time.fiscalPeriod,
+                        requiresDeclaredFiscalCalendar: current.time.requiresDeclaredFiscalCalendar
+                            || persisted.time.requiresDeclaredFiscalCalendar,
+                    }
+                    : current.time ?? persisted.time,
+            }
+            : {}),
+    };
+}
+/**
+ * A structured choice continues the server-rendered analytical frame.  The
+ * browser may echo `clarificationSourceQuestion`, but the persisted server
+ * envelope wins whenever it is available so a choice label cannot be parsed as
+ * a new question on reload or restart.
+ */
+function structuredClarificationRequirements(request, persisted) {
+    const sourceQuestion = persisted?.serverIssued && persisted.sourceQuestion
+        ? persisted.sourceQuestion
+        : request.clarificationSourceQuestion?.trim() || request.question;
+    return mergeClarificationRequirements(buildAnalyticalRequirementSet({ question: sourceQuestion }), persisted?.serverIssued ? persisted.requirements : undefined);
+}
+/**
+ * A dimension clarification is not an alternate definition of the measure.
+ * Find the exact semantic metric that owns the persisted explicit measure
+ * before accepting a server-issued semantic member as a display/grouping
+ * selection.  Multiple metrics remain a real ambiguity; we never use a
+ * dimension click to guess one of them.
+ */
+function uniqueStructuredSelectionMetric(candidates, requirements) {
+    const measures = explicitMeasureTermsForClarification(requirements);
+    if (measures.length !== 1)
+        return undefined;
+    const byMetricId = new Map();
+    for (const candidate of canonicalizeMetricMeasureCandidates(candidates)) {
+        if (candidate.kind !== 'semantic_metric'
+            || candidate.eligible === false
+            // The first clarification deliberately exists because the metric's
+            // display/entity role was not yet fully bound. A partial fit can still
+            // be the unique, complete semantic capability for the explicit measure;
+            // after the server-issued dimension choice binds it, the ordinary
+            // immutable-plan compatibility checks remain authoritative. Only a
+            // proven incompatible metric is disqualified at this identity boundary.
+            || candidate.compatibility === 'incompatible'
+            || candidateConflictsWithExplicitRankingMeasure(candidate, requirements)
+            || !candidateProvesMetricTerm(candidate, measures[0]))
+            continue;
+        const normalized = normalizeEvidenceAnalyticalCapability(candidate);
+        if (normalized.status !== 'complete' || !normalized.capability)
+            continue;
+        const current = byMetricId.get(normalized.capability.metricId);
+        if (!current
+            || candidate.exactMatch && !current.exactMatch
+            || candidate.relevanceScore > current.relevanceScore) {
+            byMetricId.set(normalized.capability.metricId, candidate);
+        }
+    }
+    return byMetricId.size === 1 ? [...byMetricId.values()][0] : undefined;
+}
+/**
+ * A resolver can offer a qualified semantic capability dimension without a
+ * standalone retrieval card.  That is expected: the option is an authored
+ * child of a metric capability, not an independently ranked candidate.  On a
+ * later click, restore that child only when the active server-issued
+ * clarification contract names the exact option and the *same immutable
+ * snapshot* still proves it through one exact metric capability.
+ *
+ * This is deliberately not a fuzzy retrieval fallback.  A malformed,
+ * foreign, stale, or client-invented ID never reaches this helper because the
+ * host-only envelope/snapshot checks occur before the capability projection.
+ */
+function rehydrateServerIssuedCapabilityDimensionSelection(input) {
+    const selectedId = input.request.selectedEvidenceId?.trim();
+    if (!selectedId)
+        return undefined;
+    const persisted = persistedClarificationSelectionContext(input.request);
+    if (!persisted?.serverIssued || persisted.snapshotId !== input.evidence.snapshotId)
+        return undefined;
+    const offeredIds = new Set([...persisted.optionIds, ...persisted.ambiguityCandidateIds]);
+    if (!offeredIds.has(selectedId))
+        return undefined;
+    const requirements = structuredClarificationRequirements(input.request, persisted);
+    const metricCandidate = uniqueStructuredSelectionMetric(input.candidates, requirements);
+    if (!metricCandidate)
+        return undefined;
+    const dimension = resolveMetricCapabilityDimension(metricCandidate, selectedId);
+    if (!dimension)
+        return undefined;
+    if (requirements.ranking && !dimension.supportedRoles.includes('rank_entity'))
+        return undefined;
+    if (!requirements.ranking
+        && !dimension.supportedRoles.includes('group_by')
+        && !dimension.supportedRoles.includes('filter'))
+        return undefined;
+    return {
+        // Keep the exact server-issued ID as the router identity and persistable
+        // choice binding. The metric capability's authored ID stays available as
+        // provenance for semantic-frame construction.
+        id: selectedId,
+        qualifiedId: dimension.dimensionId,
+        kind: 'semantic_member',
+        semanticObjectType: 'dimension',
+        trustTier: 'semantic',
+        name: dimension.label || qualifiedIdLabel(dimension.dimensionId),
+        ...(dimension.aliases?.length ? { aliases: dimension.aliases } : {}),
+        ...(metricCandidate.domain ? { domain: metricCandidate.domain } : {}),
+        ...(metricCandidate.semanticModel ? { semanticModel: metricCandidate.semanticModel } : {}),
+        relevanceScore: metricCandidate.relevanceScore,
+        matchReasons: ['server-issued snapshot capability binding'],
+        compatibility: 'compatible',
+        eligible: true,
+    };
+}
+/**
+ * Validate a selected display/grouping member against the selected metric's
+ * physical semantic capability.  The candidate must already have been offered
+ * by the server; this only determines which typed role it can complete.
+ */
+function structuredDimensionSelection(selected, candidates, requirements) {
+    if (selected.kind !== 'semantic_member'
+        || selected.eligible === false
+        || selected.compatibility === 'incompatible')
+        return undefined;
+    const roles = evidenceCandidateRoles(selected);
+    if (!roles.some((role) => role === 'entity_label'
+        || role === 'categorical_dimension'
+        || role === 'time_dimension'))
+        return undefined;
+    const metricCandidate = uniqueStructuredSelectionMetric(candidates, requirements);
+    if (!metricCandidate)
+        return undefined;
+    const dimension = resolveMetricCapabilityDimension(metricCandidate, selected.qualifiedId ?? selected.id);
+    if (!dimension)
+        return undefined;
+    // A top/bottom clarification must select an authored rankable entity, not a
+    // filter-only field. For ordinary dimensional requests, grouping is enough.
+    if (requirements.ranking && !dimension.supportedRoles.includes('rank_entity'))
+        return undefined;
+    if (!requirements.ranking
+        && !dimension.supportedRoles.includes('group_by')
+        && !dimension.supportedRoles.includes('filter'))
+        return undefined;
+    return {
+        kind: 'dimension',
+        metricCandidate,
+        selectedDimensionId: selected.id,
+        dimensionId: dimension.dimensionId,
     };
 }
+function compatibleStructuredClarificationCandidates(candidates, requirements) {
+    return candidates.filter((candidate) => candidateOwnsExplicitClarificationRoles(candidate, requirements)
+        || Boolean(structuredDimensionSelection(candidate, candidates, requirements)));
+}
 function validateStructuredClarificationSelection(input) {
     const persisted = persistedClarificationSelectionContext(input.request);
-    const sourceQuestion = input.request.clarificationSourceQuestion?.trim() || input.request.question;
-    const requirements = mergeClarificationRequirements(
     // A click/reload continuation is an identity action. Use the original user
-    // question (and, when available, the server-persisted typed contract), not
-    // arbitrary inherited parser hints from an unrelated previous turn.
-    buildAnalyticalRequirementSet({ question: sourceQuestion }), persisted?.requirements);
-    const compatible = compatibleClarificationCandidates(input.candidates, requirements);
+    // question and server-persisted typed contract, not arbitrary inherited
+    // parser hints or the rendered option label.
+    const requirements = structuredClarificationRequirements(input.request, persisted);
+    const compatible = compatibleStructuredClarificationCandidates(input.candidates, requirements);
     const choiceIds = compatible.map((candidate) => candidate.id);
     if (!persisted?.serverIssued) {
         return {
@@ -2132,7 +3462,10 @@ function validateStructuredClarificationSelection(input) {
     if (!input.selected) {
         return { ok: false, requirements, choiceIds, reason: 'The selected governed identifier is no longer present in the retrieved snapshot.' };
     }
-    if (!candidateOwnsExplicitClarificationRoles(input.selected, requirements)) {
+    const selection = candidateOwnsExplicitClarificationRoles(input.selected, requirements)
+        ? { kind: 'metric' }
+        : structuredDimensionSelection(input.selected, input.candidates, requirements);
+    if (!selection) {
         return {
             ok: false,
             requirements,
@@ -2161,7 +3494,7 @@ function validateStructuredClarificationSelection(input) {
             reason: 'The selected governed identifier is incompatible with the current typed requirement set.',
         };
     }
-    return { ok: true, requirements, choiceIds };
+    return { ok: true, requirements, choiceIds, selection };
 }
 function invalidStructuredSelectionDecision(input) {
     const coverage = sourceCoverageFromEvidence(input.evidence, input.candidates);
@@ -2383,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;
@@ -2411,7 +3745,110 @@ function preventDegenerateRankingResolution(resolution, evidence, candidates, qu
             : `I found ${selected.name}, but it counts the ranked entity and cannot identify the top individual customers. Which measure should I use for the ranking?`,
     };
 }
-function directResolution(request, evidence, candidate, candidates) {
+function isSameSnapshotCategoricalExtensionForMetric(candidate, metricCandidate) {
+    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;
+    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
+ * host-required categorical grouping whose exact qualified field is already
+ * declared by the selected metric's immutable capability. This is a binding,
+ * not a semantic guess: zero or multiple capability-backed cards leave the
+ * requirement unresolved for the normal clarify/gap path.
+ */
+function hostBoundCategoricalExtensions(input) {
+    const bound = [];
+    for (const requested of categoricalDimensionRequirementTerms(input.requirements)) {
+        const matches = input.candidates.filter((candidate) => isSameSnapshotCategoricalExtensionForMetric(candidate, input.metricCandidate)
+            && normalizeMetricPhrase(candidate.sameSnapshotRoleExtension.requestedTerm)
+                === normalizeMetricPhrase(requested));
+        if (matches.length === 1)
+            bound.push(matches[0]);
+    }
+    return bound.filter((candidate, index, all) => all.findIndex((item) => item.id === candidate.id) === index);
+}
+function directResolution(request, evidence, candidate, candidates, selectedDimensionIds = [], selectedDimensionConceptIds = selectedDimensionIds) {
+    // Keep deterministic/direct routing on the same host-owned tuple as the
+    // 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 = 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: {
+            ...evidence.parsedIntent,
+            measures: requirementSeed.queryIntent.measures,
+            dimensions: requirementSeed.queryIntent.dimensions,
+            filters: requirementSeed.queryIntent.filters,
+            ...(requirementSeed.queryIntent.timeRange ? { timeRange: requirementSeed.queryIntent.timeRange } : {}),
+            ...(requirementSeed.queryIntent.timeGrain ? { timeGrain: requirementSeed.queryIntent.timeGrain } : {}),
+            ...(requirementSeed.queryIntent.order ? { order: requirementSeed.queryIntent.order } : {}),
+            ...(requirementSeed.queryIntent.limit !== undefined ? { limit: requirementSeed.queryIntent.limit } : {}),
+        },
+    };
     const inferredQuestionType = questionTypeFromText(request.question);
     const questionType = inferredQuestionType === 'definition'
         && candidate.kind === 'semantic_metric'
@@ -2421,16 +3858,40 @@ function directResolution(request, evidence, candidate, candidates) {
         && !/\b(?:define|definition|meaning|mean)\b/i.test(request.question)
         ? 'value'
         : inferredQuestionType;
-    const metricCandidates = explicitlyRequestedMetricCandidates(request.question, evidence, candidate, candidates);
+    const metricCandidates = explicitlyRequestedMetricCandidates(request.question, hostOwnedEvidence, candidate, candidates);
+    const requirements = requirementSeed.requirements;
+    const hostBoundExtensions = hostBoundCategoricalExtensions({
+        metricCandidate: candidate,
+        candidates,
+        requirements,
+    });
+    const resolvedSelectedDimensionIds = [...new Set([
+            ...selectedDimensionIds,
+            ...hostBoundExtensions.map((item) => item.qualifiedId ?? item.id),
+        ])];
     const analyticalFrame = buildDeterministicAnalyticalFrame({
         question: request.question,
         questionType,
-        evidence,
+        evidence: hostOwnedEvidence,
         metricCandidate: candidate,
         metricCandidates,
+        entityTerms: requirements.entityTerms,
+        entityDisplayTerms: requirements.entityDisplayTerms,
+        selectedDimensionIds: resolvedSelectedDimensionIds,
         candidates,
     });
-    const defaultIntent = defaultQueryIntent(evidence);
+    const defaultIntent = defaultQueryIntent(hostOwnedEvidence);
+    // `top` without a count is a deterministic product convention, not a
+    // missing business meaning.  Bind the default into the direct execution
+    // nomination while the typed requirements retain `defaultedLimit: true` for
+    // the answer/receipt to disclose the assumption.
+    const rankedDefaultIntent = requirements.ranking
+        ? {
+            ...defaultIntent,
+            order: defaultIntent.order ?? (requirements.ranking.direction === 'bottom' ? 'asc' : 'desc'),
+            limit: defaultIntent.limit ?? requirements.ranking.limit,
+        }
+        : defaultIntent;
     // An exact authored certified example has already proved this block's own
     // output contract. Parser wording such as "food and drink" describes the
     // values of the block's declared `category` output; it must not manufacture
@@ -2444,15 +3905,45 @@ function directResolution(request, evidence, candidate, candidates) {
         && certifiedCandidateExplicitlyCoversMeasures(candidate, defaultIntent.measures)
         && (candidate.dimensions?.length ?? 0) > 0;
     const queryIntent = exactCertifiedExample
-        ? { ...defaultIntent, dimensions: candidate.dimensions ?? [] }
-        : defaultIntent;
+        ? { ...rankedDefaultIntent, dimensions: candidate.dimensions ?? [] }
+        : rankedDefaultIntent;
+    // Preserve a selected semantic field as a typed dimension binding rather
+    // than folding its label into the question. The ID comes from the selected
+    // metric's capability contract, so the immutable plan will revalidate it
+    // against the same snapshot before it can freeze.
+    const selectedQueryDimensions = analyticalFrame?.dimensions
+        // Server-issued structured selections may add their qualified identity to
+        // the intent carrier. A host-bound same-snapshot extension instead binds
+        // through the V2 frame below; adding its ID as a second text dimension
+        // would create a duplicate request (`region` plus its qualified field).
+        .filter((binding) => selectedDimensionIds.includes(binding.dimensionId))
+        .map((binding) => binding.dimensionId) ?? [];
+    // A direct host resolution can bind a categorical capability dimension from
+    // the current question without a model-selected member card. Carry the
+    // *actual* same-snapshot card into the resolution as well, otherwise the
+    // immutable solver sees a valid V2 frame but cannot prove the selected
+    // MetricFlow grouping evidence and incorrectly marks the tuple partial.
+    // This is not a fuzzy name lookup: the candidate must be the dimension's
+    // own qualified identity or the already-recorded same-snapshot extension.
+    const hostBoundDimensionConceptIds = analyticalFrame?.dimensions.flatMap((binding) => hostBoundExtensions
+        .filter((item) => (item.qualifiedId ?? item.id) === binding.dimensionId)
+        .map((item) => item.id)) ?? [];
+    const queryIntentWithSelectedDimensions = selectedQueryDimensions.length > 0
+        ? {
+            ...queryIntent,
+            dimensions: [...new Set([
+                    ...queryIntent.dimensions,
+                    ...selectedQueryDimensions,
+                ])],
+        }
+        : queryIntent;
     const memberCandidates = candidates.filter((item) => {
         if (item.kind !== 'semantic_member' || item.compatibility === 'incompatible')
             return false;
         const identities = [item.name, ...(item.aliases ?? [])].map(normalizeMetricPhrase).filter(Boolean);
-        return queryIntent.filters.some((filter) => identities.includes(normalizeMetricPhrase(filter.value)));
+        return queryIntentWithSelectedDimensions.filters.some((filter) => identities.includes(normalizeMetricPhrase(filter.value)));
     });
-    const canonicalFilters = queryIntent.filters.map((filter) => {
+    const canonicalFilters = queryIntentWithSelectedDimensions.filters.map((filter) => {
         const member = memberCandidates.find((item) => [item.name, ...(item.aliases ?? [])]
             .map(normalizeMetricPhrase)
             .includes(normalizeMetricPhrase(filter.value)));
@@ -2461,18 +3952,225 @@ function directResolution(request, evidence, candidate, candidates) {
     return {
         interpretedQuestion: request.question,
         questionType,
-        selectedConceptIds: [...metricCandidates, ...memberCandidates].map((item) => item.id),
-        recommendedExecutionId: candidate.id,
-        queryIntent: { ...queryIntent, filters: canonicalFilters },
+        selectedConceptIds: [...metricCandidates, ...memberCandidates]
+            .map((item) => item.id)
+            .concat(selectedDimensionConceptIds, hostBoundDimensionConceptIds)
+            .filter((id, index, all) => all.indexOf(id) === index),
+        // 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",
         missingInformation: [],
         recommendedRoute: routeForEvidenceCandidate(candidate),
+        // Direct/exact routing deliberately bypasses the model, not the host
+        // meaning boundary.  Carry the same immutable seed into plan binding so
+        // display-key projection and downstream receipts cannot fall back to raw
+        // parser wording.
+        hostRequirementSeed: requirementSeed,
+        ...(selectedDimensionIds.length > 0
+            ? { structuredDimensionIds: [...new Set(selectedDimensionIds)] }
+            : {}),
         ...(analyticalFrame ? { analyticalFrame } : {}),
     };
 }
+/**
+ * Build the V2 execution frame after the one candidate-ID meaning call.
+ *
+ * The model's response has already passed package membership validation.  It
+ * may therefore identify a supplied semantic metric and supplied semantic
+ * members, but it is never allowed to author the frame itself.  This helper
+ * rebuilds the frame from the immutable host seed plus those qualified
+ * identities, exactly as {@link directResolution} does for a zero-call path.
+ *
+ * Keeping this boundary here is important: a candidate-only model response
+ * used to bind a perfectly valid semantic tuple into a V1 plan.  V1 plans
+ * bypass the immutable analytical execution graph and fall into the legacy
+ * semantic SQL path, where generic aggregation validation cannot prove a
+ * MetricFlow capability.  A host-built V2 frame keeps the selected semantic
+ * route compiler-owned without letting the model change the requested tuple.
+ */
+function attachHostOwnedAnalyticalFrame(input) {
+    const { request, evidence, candidates, requirementSeed, resolution } = input;
+    if (resolution.recommendedRoute !== 'semantic' || resolution.questionType === 'definition') {
+        return resolution;
+    }
+    const matchesIdentity = (candidate, identity) => Boolean(identity && (candidate.id === identity || candidate.qualifiedId === identity));
+    const metricCandidate = candidates.find((candidate) => candidate.kind === 'semantic_metric'
+        && matchesIdentity(candidate, resolution.recommendedExecutionId))
+        ?? candidates.find((candidate) => candidate.kind === 'semantic_metric'
+            && resolution.selectedConceptIds.some((identity) => matchesIdentity(candidate, identity)));
+    if (!metricCandidate || normalizeEvidenceAnalyticalCapability(metricCandidate).status !== 'complete') {
+        return resolution;
+    }
+    // Parsed intent is retrieval evidence only.  The deterministic frame reads
+    // the same host-owned seed that the plan will later bind, so stale retrieval
+    // terms cannot re-enter as a metric, dimension, filter, output, or time
+    // constraint merely because the model selected an otherwise valid card.
+    const hostOwnedEvidence = {
+        ...evidence,
+        parsedIntent: {
+            ...evidence.parsedIntent,
+            measures: [...requirementSeed.queryIntent.measures],
+            dimensions: [...requirementSeed.queryIntent.dimensions],
+            filters: requirementSeed.queryIntent.filters.map((filter) => ({ ...filter })),
+            ...(requirementSeed.queryIntent.timeRange
+                ? { timeRange: requirementSeed.queryIntent.timeRange }
+                : {}),
+            ...(requirementSeed.queryIntent.timeGrain
+                ? { timeGrain: requirementSeed.queryIntent.timeGrain }
+                : {}),
+            ...(requirementSeed.queryIntent.order
+                ? { order: requirementSeed.queryIntent.order }
+                : {}),
+            ...(requirementSeed.queryIntent.limit !== undefined
+                ? { limit: requirementSeed.queryIntent.limit }
+                : {}),
+        },
+    };
+    const modelSelectedDimensionIds = resolution.selectedConceptIds.flatMap((identity) => {
+        const candidate = candidates.find((item) => matchesIdentity(item, identity));
+        return candidate?.kind === 'semantic_member'
+            ? [candidate.qualifiedId ?? candidate.id]
+            : [];
+    });
+    const hostBoundExtensions = hostBoundCategoricalExtensions({
+        metricCandidate,
+        candidates,
+        requirements: requirementSeed.requirements,
+    });
+    const selectedDimensionIds = [...new Set([
+            ...modelSelectedDimensionIds,
+            ...hostBoundExtensions.map((candidate) => candidate.qualifiedId ?? candidate.id),
+        ])];
+    const analyticalFrame = buildDeterministicAnalyticalFrame({
+        question: requirementSeed.sourceQuestion,
+        questionType: resolution.questionType,
+        evidence: hostOwnedEvidence,
+        metricCandidate,
+        metricCandidates: explicitlyRequestedMetricCandidates(requirementSeed.sourceQuestion, hostOwnedEvidence, metricCandidate, candidates),
+        entityTerms: requirementSeed.requirements.entityTerms,
+        entityDisplayTerms: requirementSeed.requirements.entityDisplayTerms,
+        selectedDimensionIds,
+        candidates,
+    });
+    if (!analyticalFrame)
+        return resolution;
+    const hostBoundConceptIds = hostBoundExtensions.map((candidate) => candidate.id);
+    const selectedConceptIds = [...new Set([
+            ...resolution.selectedConceptIds,
+            ...hostBoundConceptIds,
+        ])];
+    const overrideReceipts = hostBoundConceptIds.length > 0
+        ? [
+            ...(resolution.overrideReceipts ?? []),
+            {
+                version: 1,
+                field: 'candidate_selection',
+                action: 'host_preserved',
+                reason: 'A unique, same-snapshot MetricFlow grouping field is required by the host-owned categorical dimension and cannot be removed by a model omission.',
+                candidateIds: hostBoundConceptIds,
+            },
+        ]
+        : resolution.overrideReceipts;
+    return {
+        ...resolution,
+        selectedConceptIds,
+        analyticalFrame,
+        ...(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 requested = evidence.parsedIntent?.measures ?? [];
+    const requirements = buildAnalyticalRequirementSet({ question, parsedIntent: evidence.parsedIntent });
+    const requested = requirements.ranking?.metricTerms.length
+        ? requirements.ranking.metricTerms
+        : requirements.measures;
     const requestedTerms = [...new Set(requested.map(normalizeMetricPhrase).filter(Boolean))];
     // A single business metric can be retrieved alongside technical dbt measure
     // shims and registry aliases that share its words. Those are execution
@@ -2489,6 +4187,8 @@ function explicitlyRequestedMetricCandidates(question, evidence, primary, candid
     const metrics = candidates.filter((candidate) => {
         if (candidate.kind !== 'semantic_metric' || candidate.compatibility === 'incompatible')
             return false;
+        if (candidateConflictsWithExplicitRankingMeasure(candidate, requirements))
+            return false;
         if (!normalizeEvidenceAnalyticalCapability(candidate).capability)
             return false;
         if (candidate.id === primary.id)
@@ -2607,6 +4307,29 @@ mayAssumeInterpretation = true) {
     }
     return unresolvedAnalyticalPlanDecision(base, evidence, candidates, request.question);
 }
+/**
+ * A bounded meaning call may return malformed JSON or a syntactically valid
+ * low-confidence response with no candidate binding.  It must not override a
+ * plan the host can prove from one exact current-turn semantic identity.  The
+ * predicate deliberately requires a frozen executable plan: ordinary metric
+ * ambiguity, a coverage gap, policy denial, and every unfrozen candidate still
+ * take their existing clarification/block paths.
+ */
+function isFrozenExecutableHostFallback(decision) {
+    return decision.analyticalCascadeDecision?.planFrozen === true
+        && Boolean(decision.resolvedAnalyticalPlan)
+        && !decision.requiresClarification
+        && !decision.terminalOutcome;
+}
+function meaningResolutionHasNoBinding(resolution) {
+    return resolution.selectedConceptIds.length === 0
+        && !resolution.recommendedExecutionId
+        && (resolution.emptyCandidateBinding === true || (!resolution.clarifyingQuestion
+            && resolution.recommendedRoute !== 'clarify'
+            && resolution.compatibilityOutcome !== 'clarify'
+            && resolution.missingInformation.length === 0
+            && resolution.rejectedCandidates.length === 0));
+}
 /** Leaf identity of a governed candidate, ignoring its source qualification. */
 function candidateLeafName(candidate) {
     const identity = candidate.qualifiedId ?? candidate.id;
@@ -2919,7 +4642,11 @@ function deterministicPrePlanClarification(request, base, evidence, candidates)
     // requires a declared calendar at compilation time; this router simply must
     // not manufacture one or report an absence before relational/runtime context
     // has had a chance to bind the declared date role.
-    const requestedDimensions = uniqueNormalizedTerms(evidence.parsedIntent?.dimensions ?? [])
+    // The host-owned requirements are the canonical reader tuple. Parsed intent
+    // is only a retrieval seed: carrying its raw phrase here made "sales based
+    // on the region" look like a literal physical dimension even after the
+    // requirement seed had correctly normalized it to `region`.
+    const requestedDimensions = requirements.dimensions
         .filter((dimension) => !/^(?:date|day|week|month|quarter|year|fiscal year|fy\d{2,4})$/.test(dimension));
     const modeledFilterFields = new Set((evidence.parsedIntent?.filters ?? []).flatMap((filter) => candidates.some((candidate) => isCompatibleQualifiedMember(candidate)
         && candidateIdentityTerms(candidate).some((term) => metricTermsMatch(term, normalizeMetricPhrase(filter.value))))
@@ -2984,6 +4711,16 @@ function deterministicPrePlanClarification(request, base, evidence, candidates)
                 messagePrefix: `The certified and semantic candidates did not prove ${requestedLabel}.${temporalNote}`,
             });
         }
+        // A single declared alternative can only be assumed when an executable
+        // metric capability in this same snapshot explicitly contains it. A bare
+        // standalone semantic member (for example `location_name` marked as an
+        // alternative for `region`) is evidence of a possible wording, not proof
+        // that it can safely answer this tuple. Without that closure, retain the
+        // concise modeled-gap clarification rather than letting a later meaning
+        // path substitute an unrelated field or metric.
+        if (alternatives.length === 1
+            && declaredDimensionAlternativeCompletesExecutableTuple(alternatives[0], candidates, requirements))
+            return undefined;
         const requestedLabel = missingDimensions.map((term) => `“${term}”`).join(' and ');
         const alternativeLabels = alternatives.map(renderCandidateChoice);
         return {
@@ -3009,6 +4746,22 @@ function deterministicPrePlanClarification(request, base, evidence, candidates)
     }
     return undefined;
 }
+/**
+ * The broad router terminal witness can carry reader-safe missing-role prose
+ * for several gap classes.  Observability persists only the relationship
+ * variant, and only as an enumerated proof requirement, so an export cannot
+ * accidentally turn an unresolved question term into trace content.
+ */
+function cascadeTerminalRelationshipGap(gap) {
+    if (!gap || gap.code !== 'MISSING_RELATIONSHIP')
+        return undefined;
+    return {
+        version: 1,
+        code: 'MISSING_RELATIONSHIP',
+        requirement: 'certified_relationship_or_allocation_proof',
+        witnessCandidateIds: [...new Set(gap.witnessCandidateIds)].sort().slice(0, 32),
+    };
+}
 /**
  * A clarification with NO selectable options is unanswerable, and asking it is a
  * dead end rather than a safety measure.
@@ -3249,10 +5002,73 @@ function candidateProvesMetricTerm(candidate, requested) {
         .some((term) => metricTermsMatch(term, requested));
 }
 function candidateIsDeclaredDimensionAlternative(candidate, missingDimensions) {
+    const extension = candidate.sameSnapshotRoleExtension;
+    if (extension?.role === 'categorical_dimension'
+        && (extension.basis === 'sole_metricflow_grouping_dimension'
+            || extension.basis === 'exact_metricflow_grouping_dimension')
+        && missingDimensions.some((requested) => normalizeMetricPhrase(requested) === normalizeMetricPhrase(extension.requestedTerm)))
+        return true;
     const facts = candidate.compatibilityFacts?.map(normalizeMetricPhrase) ?? [];
     return missingDimensions.some((requested) => facts.includes(`alternative for ${requested}`)
         || facts.includes(`dimension alternative for ${requested}`));
 }
+function declaredDimensionAlternativeCompletesExecutableTuple(alternative, candidates, requirements) {
+    // A substitution is executable only when a metric capability in the same
+    // snapshot names this exact qualified dimension.  Do not treat a lone
+    // semantic-member card as an authorization to change the reader's request.
+    if (requirements.measures.length === 0)
+        return false;
+    const alternativeId = alternative.qualifiedId ?? alternative.id;
+    return candidates.some((candidate) => {
+        if (candidate.kind !== 'semantic_metric' || candidate.compatibility === 'incompatible')
+            return false;
+        if (!requirements.measures.every((measure) => candidateProvesMetricTerm(candidate, measure)))
+            return false;
+        const normalized = normalizeEvidenceAnalyticalCapability(candidate);
+        return normalized.status === 'complete'
+            && Boolean(normalized.capability?.dimensions.some((dimension) => dimension.dimensionId === alternativeId));
+    });
+}
+/**
+ * A declared dimension alternative is safe only after the immutable plan has
+ * bound that exact qualified field. This makes the one permitted vocabulary
+ * substitution visible to the reader without letting a raw parser phrase or
+ * model response authorize it.
+ */
+function assumptionsForDeclaredDimensionAlternatives(input) {
+    const requirements = buildAnalyticalRequirementSet({
+        question: input.question,
+        parsedIntent: input.evidence.parsedIntent,
+    });
+    const boundDimensionIds = new Set(input.plan.query.dimensions
+        .filter((binding) => binding.status === 'resolved' && binding.qualifiedId)
+        .map((binding) => binding.qualifiedId));
+    const assumptions = [];
+    for (const requested of requirements.dimensions) {
+        const alternatives = input.candidates
+            .filter(isCompatibleQualifiedMember)
+            .filter((candidate) => candidateIsDeclaredDimensionAlternative(candidate, [requested]))
+            .filter((candidate) => boundDimensionIds.has(candidate.qualifiedId ?? candidate.id));
+        if (alternatives.length !== 1)
+            continue;
+        const alternative = alternatives[0];
+        const extension = alternative.sameSnapshotRoleExtension;
+        const assumption = assumeDominantCandidate({
+            about: 'dimension',
+            candidates: [{
+                    id: alternative.qualifiedId ?? alternative.id,
+                    label: alternative.name,
+                    score: alternative.relevanceScore,
+                }],
+            because: (chosen) => extension
+                ? `“${requested}” is bound to ${chosen.label ?? chosen.id}, the sole same-snapshot MetricFlow grouping field shared by the selected metric.`
+                : `“${requested}” is not modeled directly; ${chosen.label ?? chosen.id} is the sole compatible, declared alternative in this snapshot.`,
+        });
+        if (assumption)
+            assumptions.push(assumption);
+    }
+    return assumptions;
+}
 /**
  * A missing optional parsed-intent projection must not erase positive metric
  * evidence already retrieved for the question. Only complete, compatible,
@@ -3350,12 +5166,50 @@ function renderCandidateChoice(candidate) {
  * metrics therefore remain ambiguous and continue to clarification/resolution.
  */
 function uniqueExecutableSemanticMetric(evidence, candidates) {
-    const requestedTokens = metricTokens(evidence.parsedIntent?.measures ?? []);
+    const requestedMeasures = [...new Set((evidence.parsedIntent?.measures ?? [])
+            .map(normalizeMetricPhrase)
+            .filter(Boolean))];
+    const requestedTokens = metricTokens(requestedMeasures);
     if (requestedTokens.size === 0)
         return undefined;
+    // Do this before capability normalization. Local metadata can retain an
+    // executable semantic metric card while its pre-plan compatibility hint is
+    // still partial/unknown; a selected provider binding correctly reaches the
+    // capability solver in that state. The exact leaf identity is nevertheless
+    // a real, qualified current-snapshot meaning. Dedupe only representations
+    // of the same qualified metric, never two same-named metrics from different
+    // models, and let the immutable cascade prove execution afterwards.
+    if (requestedMeasures.length === 1) {
+        const requested = requestedMeasures[0];
+        const exactByMetricIdentity = new Map();
+        for (const candidate of candidates) {
+            if (candidate.kind !== 'semantic_metric'
+                || candidate.compatibility === 'incompatible'
+                || candidate.eligible === false
+                || !candidateMetricLeafIdentities(candidate).includes(requested))
+                continue;
+            const normalized = normalizeEvidenceAnalyticalCapability(candidate);
+            const metricIdentity = normalized.capability?.metricId
+                ?? candidate.qualifiedId
+                ?? candidate.id;
+            const current = exactByMetricIdentity.get(metricIdentity);
+            if (!current || candidate.relevanceScore > current.relevanceScore) {
+                exactByMetricIdentity.set(metricIdentity, candidate);
+            }
+        }
+        if (exactByMetricIdentity.size === 1) {
+            return [...exactByMetricIdentity.values()][0];
+        }
+    }
     const byMetricId = new Map();
     for (const candidate of candidates) {
-        if (candidate.kind !== "semantic_metric" || candidate.compatibility !== "compatible")
+        // Retrieval compatibility is a pre-plan hint. A current snapshot can mark
+        // a MetricFlow metric `unknown`/`partial` until its selected grouping is
+        // bound, even though the capability itself is complete. The direct route
+        // below still solves the full tuple before freeze, so exclude only an
+        // explicitly incompatible metric here rather than turning exact `revenue`
+        // into an artificial choice against `product_revenue`.
+        if (candidate.kind !== "semantic_metric" || candidate.compatibility === "incompatible")
             continue;
         if (/\bdbt\s+measure\b/i.test(candidate.provenance ?? ""))
             continue;
@@ -3374,8 +5228,33 @@ function uniqueExecutableSemanticMetric(evidence, candidates) {
             byMetricId.set(normalized.capability.metricId, candidate);
         }
     }
+    // A malformed/empty candidate-ID meaning response may also safely fall back
+    // when a complete capability proves one exact semantic metric identity from
+    // the current-turn requirement seed. This is intentionally stricter than
+    // the token fallback below: `order_items.revenue` has the leaf identity
+    // `revenue`, whereas `order_items.product_revenue` is a different meaning
+    // and must not force a clarification when the reader asked only for
+    // revenue. Multi-metric questions retain their dedicated exact tuple path.
+    if (requestedMeasures.length === 1) {
+        const requested = requestedMeasures[0];
+        const exactMatches = [...byMetricId.values()].filter((candidate) => candidateMetricLeafIdentities(candidate).includes(requested));
+        if (exactMatches.length === 1)
+            return exactMatches[0];
+    }
     return byMetricId.size === 1 ? [...byMetricId.values()][0] : undefined;
 }
+function candidateMetricLeafIdentities(candidate) {
+    return [...new Set([
+            candidate.id,
+            candidate.qualifiedId ?? '',
+            candidate.name,
+            ...(candidate.aliases ?? []),
+        ].flatMap((identity) => {
+            const normalized = normalizeMetricPhrase(identity);
+            const leaf = normalizeMetricPhrase(identity.split(/[.:/]/).at(-1) ?? identity);
+            return [normalized, leaf].filter(Boolean);
+        }))];
+}
 function metricTokens(values) {
     const ignored = new Set([
         "a", "an", "and", "as", "at", "by", "current", "for", "from", "is",
@@ -3478,6 +5357,81 @@ function rethrowCancellation(error, ...signals) {
     if (error instanceof Error && error.name === "AbortError")
         throw error;
 }
+/**
+ * Admit the one narrowly typed extension produced by metadata only when it
+ * closes an actually unmet requested categorical role and its source metric is
+ * already in the compact meaning package.  The extension was derived from the
+ * same immutable metric capability snapshot; this function does not search,
+ * infer a join, or create an alias.  Multiple candidates for a role stay an
+ * ambiguity instead of being silently ranked into a new business meaning.
+ */
+function sameSnapshotRoleTargetedMeaningExtensions(input) {
+    const extensionsByRole = new Map();
+    const requestedCategoricalTerms = categoricalDimensionRequirementTerms(input.requirements);
+    for (const candidate of input.clarificationCandidates) {
+        const extension = candidate.sameSnapshotRoleExtension;
+        if (!extension)
+            continue;
+        if (!requestedCategoricalTerms.some((requested) => normalizeMetricPhrase(requested) === normalizeMetricPhrase(extension.requestedTerm)))
+            continue;
+        // A raw/dbt column can lexically satisfy "product category", but it is
+        // not a MetricFlow binding for this semantic metric.  Do not let that
+        // broad retrieval hit suppress the exact same-snapshot semantic member:
+        // otherwise a package contains only the raw column, the model cannot bind
+        // the metric-native grouping, and the cascade falsely reports absence.
+        // An already-admitted semantic member remains sufficient and keeps this
+        // extension bounded to genuinely unmet semantic roles.
+        if (input.candidates.some((admitted) => admitted.kind === 'semantic_member'
+            && candidateMatchesCategoricalDimensionRequirement(admitted, [extension.requestedTerm])))
+            continue;
+        // 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) ?? [];
+        if (!values.some((value) => value.id === candidate.id))
+            values.push(candidate);
+        extensionsByRole.set(role, values);
+    }
+    return [...extensionsByRole.values()]
+        .flatMap((values) => values.length === 1 ? values : [])
+        .sort((left, right) => left.id.localeCompare(right.id));
+}
+/**
+ * Keep the role-targeted form of a qualified candidate when retrieval has
+ * emitted both the ordinary catalog card and a same-snapshot extension with
+ * the identical stable ID.  The extension is not a second object or a new
+ * join: it is the metadata proof explaining why that exact qualified object
+ * closes a currently unmet role for a selected metric.  Dropping it merely
+ * because the less-specific catalog card appeared first makes the compact
+ * meaning package lose a declared MetricFlow grouping and can manufacture a
+ * false coverage gap.
+ */
+function consolidateClarificationCandidates(input) {
+    const byId = new Map();
+    for (const candidate of input.candidates) {
+        if (candidate.eligible === false
+            || candidateConflictsWithExplicitRankingMeasure(candidate, input.requirements))
+            continue;
+        const existing = byId.get(candidate.id);
+        if (!existing || (!existing.sameSnapshotRoleExtension && candidate.sameSnapshotRoleExtension)) {
+            // Map replacement preserves the original stable ordering while retaining
+            // the stricter same-snapshot proof for this exact candidate identity.
+            byId.set(candidate.id, candidate);
+        }
+    }
+    return [...byId.values()];
+}
 /**
  * Build a retrieval-first hybrid router. Narrow conversational/app preflight is
  * deterministic. Every other turn loads structured evidence before any
@@ -3523,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);
                 }
@@ -3541,6 +5499,10 @@ export function createHybridRouter(options = {}) {
                 // boundary so every downstream plan/meaning path consumes the same
                 // typed measure + entity/dimension requirements.
                 evidence = withNormalizedAnalyticalRequirements(evidence, request.question);
+                // Keep the complete snapshot result for trace-only lifecycle evidence
+                // before canonicalization and bounded meaning-package admission prune it.
+                const retrievedCandidates = evidence.candidates;
+                traceRetrievalLanesBeforePruning(request, evidence, retrievedCandidates);
                 evidence = {
                     ...evidence,
                     candidates: canonicalizeMetricMeasureCandidates(evidence.candidates),
@@ -3551,26 +5513,140 @@ 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
+                // clarification or meaning-selection alternative after an explicit
+                // comparator already bound a different ranking measure.
+                const persistedSelection = request.selectedEvidenceId
+                    ? persistedClarificationSelectionContext(request)
+                    : undefined;
+                // A structured click is a continuation of the original server turn,
+                // not a new parse of its display label. Retain the typed partial frame
+                // (ranking/time included) before candidate pruning can affect it.
+                const continuationQuestion = persistedSelection?.serverIssued && persistedSelection.sourceQuestion
+                    ? persistedSelection.sourceQuestion
+                    // A free-text turn is always a new source question. A browser may
+                    // retain clarificationSourceQuestion for display, but it must never
+                    // make stale retrieval intent or a previous result authoritative.
+                    : request.question;
+                // Retrieval parser output is never an independent source of request
+                // authority, but it can refine a host-owned source question when every
+                // business term is demonstrably present in that question.  In
+                // particular, "active seats" is a legitimate current-turn metric
+                // refinement for "Which workspaces have the most active seats?";
+                // omitting it altogether forced the seed to erase an explicit metric
+                // before the model had a chance only to bind it.  The shared
+                // requirement builder rejects stale parser terms (for example a prior
+                // rollover balance, member filter, or top-N), so this remains a
+                // source-question-plus-server-selection tuple rather than retrieval
+                // intent becoming plan authority.
+                // A server-composed child Ask (currently a Research hypothesis) may
+                // carry an exact host-owned seed.  Planner prose is not user wording:
+                // reparsing it can turn an asset namespace or explanatory phrase into
+                // a second requested measure.  Accept the seed only when it belongs
+                // to this exact source question and there is no structured
+                // continuation to merge; public request parsers never hydrate this
+                // host-only field.
+                const hostSeed = !request.selectedEvidenceId
+                    && request.hostRequirementSeed?.version === 1
+                    && request.hostRequirementSeed.sourceQuestion === continuationQuestion
+                    ? request.hostRequirementSeed
+                    : undefined;
+                const sourceQuestionRequirements = hostSeed?.requirements
+                    ?? buildAnalyticalRequirementSet({
+                        question: continuationQuestion,
+                        parsedIntent: evidence.parsedIntent,
+                    });
+                const analyticalRequirements = request.selectedEvidenceId
+                    ? mergeClarificationRequirements(sourceQuestionRequirements, persistedSelection?.serverIssued ? persistedSelection.requirements : undefined)
+                    : sourceQuestionRequirements;
+                // The host freezes the reader's requested tuple before the bounded
+                // meaning call. A model may bind only supplied candidate identities;
+                // it cannot erase explicit outputs, ranking, time, or a new question's
+                // independent scope by rephrasing the request.
+                const requirementSeed = hostSeed
+                    ? hostSeed
+                    : buildAnalyticalRequirementSeedV1({
+                        question: continuationQuestion,
+                        parsedIntent: evidence.parsedIntent,
+                        requirements: analyticalRequirements,
+                        fiscalCalendar: declaredFiscalCalendar(evidence, evidence.candidates),
+                    });
                 // Retrieval can retain more context internally; only this compact,
                 // role-balanced package reaches the one meaning call. The question is
                 // supplied so explicit revenue, entity labels, and time roles cannot be
                 // pruned by unrelated lexical matches.
-                let candidates = buildMeaningEvidencePackage(evidence, options.maxMeaningCandidates ?? 16, request.question);
-                // Clarification is local and never provider-bound, so it can inspect the
-                // complete already-retrieved set. A raw selectedEvidenceId must be
-                // validated against this set before any route can fall through to a
-                // generic/generated answer; this is deliberately outside the bounded
-                // package length guard so an empty retrieval cannot fail open.
-                const clarificationCandidates = [
-                    ...evidence.candidates,
-                    ...(evidence.clarificationCandidates ?? []),
-                ].filter((candidate, index, all) => candidate.eligible !== false && all.findIndex((other) => other.id === candidate.id) === index);
+                let candidates = buildMeaningEvidencePackage(evidence, options.maxMeaningCandidates ?? 16, continuationQuestion);
+                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
+                // the admitted package below, so a pruned candidate cannot reappear as
+                // an unrelated clarification option.
+                const clarificationCandidates = consolidateClarificationCandidates({
+                    candidates: [
+                        ...evidence.candidates,
+                        ...(evidence.clarificationCandidates ?? []),
+                    ],
+                    requirements: analyticalRequirements,
+                });
                 // A structured clarification selection is identity input, not a new
                 // fuzzy-search phrase. Look in BOTH lists: ranking-measure choices are
                 // supplemental clarification candidates, not execution candidates.
-                const selectedEvidence = request.selectedEvidenceId
+                let selectedEvidence = request.selectedEvidenceId
                     ? clarificationCandidates.find((candidate) => candidate.id === request.selectedEvidenceId)
                     : undefined;
+                if (!selectedEvidence && request.selectedEvidenceId) {
+                    selectedEvidence = rehydrateServerIssuedCapabilityDimensionSelection({
+                        request,
+                        evidence,
+                        candidates: clarificationCandidates,
+                    });
+                    if (selectedEvidence)
+                        clarificationCandidates.push(selectedEvidence);
+                }
                 const structuredSelection = request.selectedEvidenceId
                     ? validateStructuredClarificationSelection({
                         request,
@@ -3589,10 +5665,77 @@ export function createHybridRouter(options = {}) {
                         validation: structuredSelection,
                     });
                 }
-                if (selectedEvidence && !candidates.some((candidate) => candidate.id === selectedEvidence.id)) {
-                    candidates = [selectedEvidence, ...candidates.filter((candidate) => candidate.id !== selectedEvidence.id)]
-                        .slice(0, options.maxMeaningCandidates ?? 16);
+                const selectedDimensionBinding = structuredSelection?.ok
+                    && structuredSelection.selection.kind === 'dimension'
+                    ? structuredSelection.selection
+                    : undefined;
+                const stableSelectionCandidates = [
+                    ...(selectedDimensionBinding ? [selectedDimensionBinding.metricCandidate] : []),
+                    ...(selectedEvidence ? [selectedEvidence] : []),
+                ].filter((candidate, index, all) => all.findIndex((item) => item.id === candidate.id) === index);
+                // One host-authored, role-targeted extension may enter the same
+                // snapshot package before absence is declared. It is eligible only
+                // when a selected/retrieved semantic metric itself proves one unique
+                // MetricFlow grouping dimension for the unmet business role. This is
+                // not a lexical location→region rule and never creates a raw join.
+                const roleTargetedExtensions = sameSnapshotRoleTargetedMeaningExtensions({
+                    candidates,
+                    clarificationCandidates,
+                    requirements: analyticalRequirements,
+                });
+                const extensions = [
+                    ...stableSelectionCandidates,
+                    ...roleTargetedExtensions,
+                ].filter((candidate, index, all) => all.findIndex((item) => item.id === candidate.id) === index
+                    // A role-targeted card may intentionally share the stable ID of an
+                    // unscoped catalog card already admitted by generic relevance. In
+                    // that case replace the card in-place below so the provider sees the
+                    // same qualified object plus the immutable role proof; do not drop
+                    // the proof just because its base record was admitted first.
+                    && (() => {
+                        const existing = candidates.find((item) => item.id === candidate.id);
+                        return !existing || (!existing.sameSnapshotRoleExtension && candidate.sameSnapshotRoleExtension);
+                    })());
+                if (extensions.length > 0) {
+                    // Keep the exact metric and the separately selected semantic member
+                    // together. The choice never becomes a synthetic metric merely to
+                    // fit the bounded meaning package.
+                    candidates = [...extensions, ...candidates.filter((candidate) => !extensions.some((extension) => extension.id === candidate.id))]
+                        .slice(0, Math.max(1, Math.min(16, options.maxMeaningCandidates ?? 16)));
+                    const observer = askTraceObserverForV1(request);
+                    for (const extension of extensions) {
+                        const roles = evidenceCandidateRoles(extension);
+                        for (const role of roles) {
+                            observer.recordCandidateDecision({
+                                // This must stay on the router's stable resolver identity. The
+                                // qualifiedId is display/provenance data and can differ from the
+                                // candidate id used by meaning validation and model selection.
+                                candidateId: extension.id,
+                                role,
+                                source: traceSourceForCandidate(extension),
+                                decision: 'extended',
+                                reasonCode: 'same_snapshot_extension',
+                                compatibilityCode: 'unknown',
+                            });
+                        }
+                    }
                 }
+                // Only package-admitted, role-compatible candidates may become a new
+                // free-text clarification option. The complete snapshot is retained
+                // above exclusively to validate a server-issued stable selection or
+                // to prove a terminal safety boundary; it must never let a pruned,
+                // unrelated metric re-enter the answer flow as a choice.
+                const admittedClarificationCandidates = candidates.filter((candidate) => candidate.eligible !== false
+                    && candidate.compatibility !== 'incompatible'
+                    && !candidateConflictsWithExplicitRankingMeasure(candidate, analyticalRequirements));
+                const attributionGap = attributionRequiredRelationshipGapDecision({
+                    request,
+                    base,
+                    evidence,
+                    requirements: analyticalRequirements,
+                });
+                if (attributionGap)
+                    return attributionGap;
                 // The compact meaning package can be empty when every ranked card was
                 // reserved for a role that the parser marked missing. A unique authored
                 // certified example is still an authoritative snapshot fact, so it
@@ -3614,9 +5757,18 @@ export function createHybridRouter(options = {}) {
                     const fiscalClarification = fiscalCalendarClarification(request, base, evidence, candidates);
                     if (fiscalClarification)
                         return fiscalClarification;
-                    const explicit = selectedEvidence ?? findExplicitEvidenceReference(request.question, candidates);
+                    // A selected display/grouping field completes a persisted frame; the
+                    // 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)
+                        ?? 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);
@@ -3627,7 +5779,7 @@ export function createHybridRouter(options = {}) {
                     // execution shim as the answer and never let the meaning model see
                     // the ranking entity/measure distinction.
                     if (!shouldUseMeaningCall && !explicitMeaningBinding) {
-                        const deterministicClarification = deterministicPrePlanClarification(request, base, evidence, clarificationCandidates);
+                        const deterministicClarification = deterministicPrePlanClarification(request, base, evidence, admittedClarificationCandidates);
                         if (deterministicClarification)
                             return deterministicClarification;
                     }
@@ -3638,7 +5790,7 @@ export function createHybridRouter(options = {}) {
                             && !hasExplicitRankingMeasure(request.question, evidence)) {
                             return rankingMetricChoiceDecision(base, evidence, candidates, explicit, request.question);
                         }
-                        const decision = routeDecisionForResolution(base, evidence, candidates, directResolution(request, evidence, explicit, candidates), "heuristic", request.question, options.resolvedPlanMode ?? 'authoritative');
+                        const decision = routeDecisionForResolution(base, evidence, candidates, directResolution(request, evidence, explicit, candidates, selectedDimensionBinding ? [selectedDimensionBinding.dimensionId] : [], selectedDimensionBinding ? [selectedDimensionBinding.selectedDimensionId] : []), "heuristic", request.question, options.resolvedPlanMode ?? 'authoritative');
                         // A valid stable semantic choice may still be pre-freeze-ineligible
                         // in this local snapshot (for example, the semantic adapter cannot
                         // execute the selected tuple). That is a normal cascade condition:
@@ -3648,10 +5800,16 @@ export function createHybridRouter(options = {}) {
                         const selectedPreFreezeModelingGap = decision.terminalOutcome?.kind === 'modeling_gap'
                             && decision.resolvedAnalyticalPlan?.capability === 'blocked'
                             && decision.analyticalCascadeDecision?.planFrozen === false;
-                        return selectedEvidence
+                        return explicit
                             && structuredSelection?.ok
                             && (decision.requiresClarification || selectedPreFreezeModelingGap)
-                            ? continueCascadeAfterIncompleteSelection(base, evidence, candidates, selectedEvidence, request.question)
+                            ? continueCascadeAfterIncompleteSelection(base, evidence, candidates, 
+                            // Preserve the display-key identity the user clicked in
+                            // user-facing gap/continuation evidence; the paired metric
+                            // remains recorded below as execution provenance.
+                            selectedEvidence ?? explicit, request.question, selectedDimensionBinding
+                                ? [selectedDimensionBinding.metricCandidate.id, selectedDimensionBinding.selectedDimensionId]
+                                : [explicit.id])
                             : decision;
                     }
                     const multiMetricPrimary = !shouldUseMeaningCall
@@ -3687,41 +5845,97 @@ 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');
                         }
-                        const resolution = options.resolveMeaning
-                            ? await options.resolveMeaning({
-                                question: request.question,
-                                history: effectiveConversationHistory(request),
-                                // The resolver/provider receives the same bounded evidence
-                                // package as its candidate argument. Supplemental qualified
-                                // cards are a host-only clarification aid and must not leak
-                                // through this richer carrier.
-                                evidence: {
-                                    ...evidence,
+                        let resolution;
+                        try {
+                            resolution = options.resolveMeaning
+                                ? await options.resolveMeaning({
+                                    question: requirementSeed.sourceQuestion,
+                                    history: request.conversationBinding && request.conversationBinding !== 'none'
+                                        ? effectiveConversationHistory(request)
+                                        : undefined,
+                                    // The resolver/provider receives the same bounded evidence
+                                    // package as its candidate argument. Supplemental qualified
+                                    // cards are a host-only clarification aid and must not leak
+                                    // through this richer carrier.
+                                    evidence: {
+                                        ...evidence,
+                                        candidates,
+                                        clarificationCandidates: undefined,
+                                    },
                                     candidates,
-                                    clarificationCandidates: undefined,
-                                },
-                                candidates,
-                                signal: request.signal ?? options.signal,
-                            })
-                            : options.complete
-                                ? parseMeaningResolution(await options.complete({
-                                    system: buildMeaningSystemPrompt(),
-                                    user: buildMeaningUserPrompt(request, evidence, candidates),
+                                    requirementSeed,
                                     signal: request.signal ?? options.signal,
-                                }))
-                                : undefined;
+                                })
+                                : options.complete
+                                    ? parseMeaningResolution(await options.complete({
+                                        system: buildMeaningSystemPrompt(),
+                                        user: buildMeaningUserPrompt(request, evidence, candidates, requirementSeed),
+                                        signal: request.signal ?? options.signal,
+                                        request,
+                                        phase: 'meaning_resolution',
+                                    }), requirementSeed)
+                                    : undefined;
+                        }
+                        catch (error) {
+                            throw error;
+                        }
                         if (resolution) {
+                            // A model is allowed to say that it cannot bind any supplied
+                            // card, but that is not a new business ambiguity by itself. If
+                            // the host can prove one exact current-turn semantic identity,
+                            // take the ordinary direct/cascade path instead of preserving an
+                            // empty selection as a clarification. This is intentionally
+                            // evaluated before merge/validation so the host never treats an
+                            // empty provider response as an authoritative analytical frame.
+                            if (meaningResolutionHasNoBinding(resolution)) {
+                                const hostFallback = routeWithoutMeaningModel(request, base, evidence, candidates, options.resolvedPlanMode ?? 'authoritative', true);
+                                if (isFrozenExecutableHostFallback(hostFallback)) {
+                                    return remember(key, hostFallback);
+                                }
+                            }
+                            // Merge exactly once at the model boundary. Candidate IDs remain
+                            // subject to the bounded-package validator below; model route,
+                            // SQL-adjacent frame, rephrased question, and query intent never
+                            // become downstream authority.
+                            resolution = mergeMeaningResolutionWithRequirementSeed({
+                                seed: requirementSeed,
+                                resolution,
+                                candidates,
+                            });
                             // Repair an incomplete certified nomination before generic
                             // evidence validation. This preserves the real semantic choices
                             // instead of turning a false certified selection into an opaque
                             // invalid-evidence gap.
                             const certifiedSafeResolution = repairIncompleteCertifiedMeasureSelection(resolution, evidence, candidates);
-                            const validated = validateMeaningResolution(certifiedSafeResolution, candidates, evidence.parsedIntent?.measures ?? certifiedSafeResolution.queryIntent.measures);
+                            const validated = validateMeaningResolution(certifiedSafeResolution, candidates, evidence.parsedIntent?.measures ?? certifiedSafeResolution.queryIntent.measures, { requirements: analyticalRequirements });
                             if (validated.ok) {
-                                const safeResolution = preventDegenerateRankingResolution(validated.resolution, evidence, candidates, request.question);
+                                // The meaning model may select only supplied candidate IDs.  It
+                                // intentionally cannot return an analytical frame, because a
+                                // model-owned frame could add a metric, dimension, output, or
+                                // prior-turn scope after the host froze the requirement seed.
+                                //
+                                // Do not leave that candidate-only result on the legacy V1
+                                // path, though: a valid selected semantic metric plus its
+                                // selected supplied members must receive the same *host-built*
+                                // V2 frame as a zero-call/direct resolution.  Otherwise the
+                                // router freezes a V1 semantic plan, the answer loop skips the
+                                // immutable semantic execution graph, and legacy SQL is
+                                // incorrectly checked against generic aggregation metadata.
+                                const frameBoundResolution = attachHostOwnedAnalyticalFrame({
+                                    request,
+                                    evidence,
+                                    candidates,
+                                    requirementSeed,
+                                    resolution: validated.resolution,
+                                });
+                                const safeResolution = preventDegenerateRankingResolution(frameBoundResolution, evidence, candidates, request.question);
                                 // Meaning interpretation is still required for a fresh turn,
                                 // but it cannot invent a ranking measure when the user only
                                 // supplied an entity. Preserve the precise follow-up after the
@@ -3770,24 +5984,27 @@ export function createHybridRouter(options = {}) {
                                         .some((item) => /measure|metric/i.test(item));
                                     const assumedRanking = resolverFlagged
                                         ? undefined
-                                        : assumableRankingMeasure(request.question, clarificationCandidates);
+                                        : assumableRankingMeasure(request.question, admittedClarificationCandidates);
                                     if (assumedRanking) {
                                         return {
                                             ...routeDecisionForResolution(base, evidence, candidates, directResolution(request, evidence, assumedRanking.candidate, candidates), 'heuristic', request.question),
                                             assumptions: [assumedRanking.assumption],
                                         };
                                     }
-                                    return bareRankingClarification(base, retrievalTrace(evidence, candidates), request.question, evidence, 
-                                    // Supplemental clarification cards carry the ranking
-                                    // measures for the requested entity, which the execution
-                                    // candidate set deliberately does not.
-                                    clarificationCandidates, !resolverFlagged);
+                                    return bareRankingClarification(base, retrievalTrace(evidence, candidates), request.question, evidence, admittedClarificationCandidates, !resolverFlagged);
                                 }
-                                const deterministicGap = deterministicPrePlanClarification(request, base, evidence, clarificationCandidates);
+                                const deterministicGap = deterministicPrePlanClarification(request, base, evidence, admittedClarificationCandidates);
                                 if (deterministicGap && safeResolution.recommendedRoute === 'clarify') {
                                     return deterministicGap;
                                 }
-                                return remember(key, routeDecisionForResolution(base, evidence, candidates, safeResolution, "llm", request.question, options.resolvedPlanMode ?? 'authoritative'));
+                                const meaningDecision = routeDecisionForResolution(base, evidence, candidates, safeResolution, "llm", request.question, options.resolvedPlanMode ?? 'authoritative');
+                                return remember(key, continuePreFreezeModelingGapThroughPhysicalSnapshot({
+                                    decision: meaningDecision,
+                                    base,
+                                    evidence,
+                                    candidates,
+                                    question: request.question,
+                                }));
                             }
                             const invalidResolution = {
                                 interpretedQuestion: request.question,
@@ -3823,11 +6040,14 @@ export function createHybridRouter(options = {}) {
                     const fallbackDecision = routeWithoutMeaningModel(request, base, evidence, candidates, options.resolvedPlanMode ?? 'authoritative', meaningResolverReachable);
                     if (!shouldUseMeaningCall)
                         return fallbackDecision;
+                    if (isFrozenExecutableHostFallback(fallbackDecision)) {
+                        return fallbackDecision;
+                    }
                     // The provider was unavailable or returned malformed JSON. Apply the
                     // deterministic clarification only after the bounded meaning attempt
                     // has been exhausted; this preserves a precise recovery path without
                     // allowing the generic governed error to terminate the question.
-                    return deterministicPrePlanClarification(request, base, evidence, clarificationCandidates)
+                    return deterministicPrePlanClarification(request, base, evidence, admittedClarificationCandidates)
                         ?? fallbackDecision;
                 }
             }
@@ -3890,6 +6110,8 @@ export function createHybridRouter(options = {}) {
                     system: buildSystemPrompt(),
                     user: buildUserPrompt(request, catalogContext),
                     signal: request.signal ?? options.signal,
+                    request,
+                    phase: 'classification',
                 });
                 const classification = parseClassification(raw);
                 if (classification)
@@ -3918,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