@duckcodeailabs/dql-agent 1.14.0 → 1.14.2

package/dist/router.js

@@ -1,3 +1,4 @@
+import { assumeDominantCandidate } from './agentic/assumptions.js';
 /**
  * Hybrid router — deterministic-first, LLM-assisted for the ambiguous middle.
  *
@@ -15,9 +16,10 @@
  * question never pays twice.
  */
 import { classifyConversationalTurn, decideAgentAction, } from "./intent-controller.js";
-import { buildMeaningEvidencePackage, canonicalizeMetricMeasureCandidates, defaultQueryIntent, findExplicitEvidenceReference, questionTypeFromText, routeForEvidenceCandidate, validateMeaningResolution, } from "./meaning-resolution.js";
+import { buildMeaningEvidencePackage, canonicalizeMetricMeasureCandidates, certifiedCandidateExplicitlyCoversMeasures, defaultQueryIntent, findExplicitEvidenceReference, 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 { normalizeEvidenceAnalyticalCapability, solveAnalyticalCompatibility, } from "./analytical-compatibility.js";
 import { buildDeterministicAnalyticalFrame, projectResolvedAnalyticalFrame } from "./analytical-frame.js";
 import { conversationHistoryFromContext, renderConversationEnvelopeForPrompt, } from "./conversation/snapshot.js";
@@ -413,13 +415,871 @@ function retrievalTrace(evidence, candidates) {
         candidateIds: candidates.map((candidate) => candidate.id),
     };
 }
+/** 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]));
+    const sourceKinds = [
+        ['certified', (candidate) => candidate.kind === 'certified_block'],
+        ['semantic', (candidate) => candidate.trustTier === 'semantic' || candidate.kind === 'semantic_metric' || candidate.kind === 'semantic_member'],
+        ['governed_relational', (candidate) => candidate.kind === 'dql_modeling' || (candidate.relationshipEvidence?.length ?? 0) > 0],
+        ['exploratory', (candidate) => candidate.kind === 'dbt_model' || candidate.kind === 'dbt_source' || candidate.kind === 'sql_table' || candidate.kind === 'sql_column'],
+        ['dbt_manifest', (candidate) => candidate.kind === 'dbt_model' || candidate.kind === 'dbt_source'],
+        ['runtime_schema', (candidate) => candidate.kind === 'sql_table' || candidate.kind === 'sql_column'],
+    ];
+    const coverage = [];
+    for (const [source, matches] of sourceKinds) {
+        const explicit = supplied.get(source);
+        if (explicit) {
+            coverage.push({ ...explicit, version: 1, candidateIds: [...new Set(explicit.candidateIds)].slice(0, 32) });
+            continue;
+        }
+        const ids = candidates.filter(matches).map((candidate) => candidate.qualifiedId ?? candidate.id).slice(0, 32);
+        const searched = evidence.diagnostics?.searchedKinds ?? [];
+        const relevantSearched = source === 'certified'
+            ? searched.includes('certified_block')
+            : source === 'semantic'
+                ? searched.includes('semantic_metric') || searched.includes('semantic_member')
+                : source === 'dbt_manifest'
+                    ? searched.includes('dbt_model') || searched.includes('dbt_source')
+                    : source === 'runtime_schema'
+                        ? searched.includes('sql_table') || searched.includes('sql_column')
+                        : source === 'exploratory'
+                            ? searched.some((kind) => kind === 'dbt_model' || kind === 'dbt_source' || kind === 'sql_table' || kind === 'sql_column')
+                            : searched.includes('dql_modeling');
+        coverage.push({ version: 1, source, status: ids.length > 0 ? 'available' : relevantSearched ? 'empty' : 'unavailable', candidateIds: ids });
+    }
+    // Vector/conversation status is only included when its retrieval lane told us
+    // its real status. It is not a synthetic “skipped” placeholder.
+    for (const source of ['vector', 'conversation']) {
+        const explicit = supplied.get(source);
+        if (explicit)
+            coverage.push({ ...explicit, version: 1, candidateIds: [...new Set(explicit.candidateIds)].slice(0, 32) });
+    }
+    return coverage;
+}
+function declaredFiscalCalendar(evidence, candidates) {
+    const calendar = evidence.fiscalCalendar;
+    // A fiscal period value is meaningless without the date role it applies to.
+    // Older snapshots may not contain this field, but they must clarify instead
+    // of silently applying FY26 to an arbitrary date column.
+    if (!calendar?.dateRoleId)
+        return undefined;
+    const identifiers = new Set(candidates.flatMap((candidate) => [candidate.id, candidate.qualifiedId].filter((id) => Boolean(id))));
+    return identifiers.has(calendar.id)
+        && identifiers.has(calendar.fiscalPeriodFieldId)
+        && identifiers.has(calendar.dateRoleId)
+        ? calendar
+        : undefined;
+}
+function withDeclaredFiscalBinding(resolution, evidence, candidates, question) {
+    const requirements = buildAnalyticalRequirementSet({ question, parsedIntent: evidence.parsedIntent });
+    const fiscalPeriod = requirements.time?.fiscalPeriod;
+    const calendar = fiscalPeriod ? declaredFiscalCalendar(evidence, candidates) : undefined;
+    if (!fiscalPeriod || !calendar)
+        return resolution;
+    const filters = resolution.queryIntent.filters.filter((filter) => filter.field !== calendar.fiscalPeriodFieldId);
+    return {
+        ...resolution,
+        queryIntent: {
+            ...resolution.queryIntent,
+            filters: [...filters, { field: calendar.fiscalPeriodFieldId, value: fiscalPeriod }],
+            ...(requirements.time?.grain && !resolution.queryIntent.timeGrain ? { timeGrain: requirements.time.grain } : {}),
+            fiscalCalendarId: calendar.id,
+            fiscalDateRoleId: calendar.dateRoleId,
+        },
+    };
+}
+function fiscalCalendarClarification(request, base, evidence, candidates) {
+    const requirements = buildAnalyticalRequirementSet({ question: request.question, parsedIntent: evidence.parsedIntent });
+    if (!requirements.time?.requiresDeclaredFiscalCalendar || declaredFiscalCalendar(evidence, candidates))
+        return undefined;
+    const fiscalPeriod = requirements.time.fiscalPeriod ?? 'the requested fiscal period';
+    const coverage = sourceCoverageFromEvidence(evidence, candidates);
+    return {
+        ...base,
+        action: 'clarify',
+        confidence: 1,
+        source: 'heuristic',
+        category: 'unclear',
+        depth: 'quick',
+        reason: `${fiscalPeriod} requires one declared fiscal calendar and date-role mapping before a plan can freeze.`,
+        clarifyingQuestion: `Which declared fiscal calendar and date role should DQL use for ${fiscalPeriod}?`,
+        requiresClarification: true,
+        retrievalEvidence: retrievalTrace(evidence, candidates),
+        analyticalCascadeDecision: buildAnalyticalCascadeDecision({
+            requirements,
+            sourceCoverage: coverage,
+            attempts: [{ version: 1, tier: 'clarify_or_gap', outcome: 'ambiguous', candidateIds: [], reason: 'No declared fiscal calendar/date-role binding was present in the snapshot.', planFrozen: false }],
+            planFrozen: false,
+            stopReason: 'ambiguous',
+        }),
+    };
+}
+function normalizedRelationshipIdentity(value) {
+    return value.trim().toLowerCase();
+}
+/**
+ * The retrieval parser is intentionally generous because its terms also seed
+ * search.  Before the router turns those terms into a resolved plan, replace
+ * grammatical aggregation wrappers with the shared typed requirement set.
+ * This keeps all router paths (fast certified, no-meaning, structured
+ * continuation, and one-call meaning) on the same count/customer contract.
+ */
+function withNormalizedAnalyticalRequirements(evidence, question) {
+    if (!evidence.parsedIntent)
+        return evidence;
+    const requirements = buildAnalyticalRequirementSet({ question, parsedIntent: evidence.parsedIntent });
+    return {
+        ...evidence,
+        parsedIntent: {
+            ...evidence.parsedIntent,
+            measures: requirements.measures,
+            dimensions: requirements.dimensions,
+        },
+    };
+}
+function relationshipSafetyIdentities(safety) {
+    return [...new Set([safety.id, ...(safety.aliases ?? [])]
+            .map(normalizedRelationshipIdentity)
+            .filter(Boolean))];
+}
+/**
+ * This mirrors the local manifest relationship admission gate with the compact
+ * facts preserved in retrieval evidence. IDs and names deliberately play no
+ * part in the decision: a neutral draft/many-to-many identity is still unsafe.
+ */
+function relationshipSafetyAllowsAutomaticJoin(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());
+    if (safety.status !== 'certified'
+        || safety.staleCertification !== false
+        || safety.automaticJoinAllowed !== true
+        || safety.fanout !== 'safe'
+        || !['one_to_one', 'one_to_many', 'many_to_one'].includes(safety.cardinality ?? '')
+        || !safety.from?.trim()
+        || !safety.to?.trim()
+        || !safety.certificationFingerprint?.trim()
+        || !validation
+        || validation.status !== 'passed'
+        || !validation.queryFingerprint?.trim()
+        || !validation.proofFingerprint?.trim()
+        || !Number.isFinite(checkedAt)
+        || expirationInvalid
+        || safety.keys.length === 0
+        || safety.keys.some((key) => !key.from.trim() || !key.to.trim()))
+        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));
+}
+function safeRelationshipProofsForCandidate(candidate, requiredJoinKey) {
+    const referenced = new Set((candidate.relationshipEvidence ?? []).map(normalizedRelationshipIdentity));
+    const proofs = new Map();
+    for (const safety of candidate.relationshipSafety ?? []) {
+        if (!relationshipSafetyAllowsAutomaticJoin(safety, requiredJoinKey))
+            continue;
+        if (!relationshipSafetyIdentities(safety).some((identity) => referenced.has(identity)))
+            continue;
+        proofs.set(safety.id, safety);
+    }
+    return proofs;
+}
+function candidateRelationshipEndpoints(candidate) {
+    return new Set([
+        ...(candidate.relationshipEndpointIds ?? []),
+        candidate.primaryEntity ?? '',
+        candidate.analyticalCapability?.primaryEntityId ?? '',
+    ].map(normalizedRelationshipIdentity).filter(Boolean));
+}
+/**
+ * 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
+ * endpoints in either direction before it can close an exploratory join.
+ */
+function relationshipProofMatchesSelectedPair(safety, left, right) {
+    const leftEndpoints = candidateRelationshipEndpoints(left);
+    const rightEndpoints = candidateRelationshipEndpoints(right);
+    const from = normalizedRelationshipIdentity(safety.from ?? '');
+    const to = normalizedRelationshipIdentity(safety.to ?? '');
+    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);
+    const shared = new Map();
+    for (const [id, proof] of leftProofs) {
+        const pairedProof = rightProofs.get(id);
+        if (!pairedProof
+            || !relationshipProofMatchesSelectedPair(proof, left, right)
+            || !relationshipProofMatchesSelectedPair(pairedProof, left, right))
+            continue;
+        shared.set(id, proof);
+    }
+    return shared;
+}
+function hasSafeExploratoryPhysicalPath(requirements, candidates, missingDimensions, requiredPhysicalFieldTerms = []) {
+    const physical = candidates.filter((candidate) => candidate.eligible !== false
+        && candidate.compatibility !== 'incompatible'
+        && (candidate.kind === 'dbt_model' || candidate.kind === 'dbt_source' || candidate.kind === 'sql_table' || candidate.kind === 'sql_column'));
+    const relations = physical.filter((candidate) => candidate.kind !== 'sql_column');
+    const columns = physical.filter((candidate) => candidate.kind === 'sql_column');
+    if (relations.length === 0 || columns.length === 0) {
+        return { ok: false, candidateIds: [], reason: 'No qualified raw relation plus column coverage was retrieved from this snapshot.' };
+    }
+    // This list is intentionally field/role-only.  Filter values such as
+    // `Datadog`, `FY26`, or `true` are member constraints, not column names;
+    // 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]
+            .map(normalizeMetricPhrase)
+            .filter(Boolean))];
+    if (terms.length === 0) {
+        return { ok: false, candidateIds: [], reason: 'No typed physical fields were available to prove an exploratory plan.' };
+    }
+    const relationSources = (relation) => relation.sourceObjects?.length ? relation.sourceObjects : [relation.qualifiedId ?? relation.id];
+    const columnTouchesRelation = (column, relation) => column.sourceObjects?.length
+        ? column.sourceObjects.some((source) => relationSources(relation).includes(source))
+        // A source that omitted its column edge cannot substantiate a multi-table
+        // plan. It remains usable only when a single relation is selected.
+        : relations.length === 1;
+    const columnFieldIdentityTerms = (column) => uniqueNormalizedTerms([
+        column.name,
+        ...(column.aliases ?? []),
+        ...(column.dimensions ?? []),
+    ]);
+    // These are intentionally a tiny, role-only bridge for raw physical
+    // evidence. They are evaluated against a column's own name/aliases in this
+    // immutable snapshot; they neither infer a relation nor turn a member value
+    // into a column. The aliases cover common authored field terminology in the
+    // supplied dbt/runtime schema (`product category` -> `product_type`, and a
+    // product-level revenue ask -> `product_price`).
+    const hasProductCategoryRequirement = [
+        ...requirements.dimensions,
+        ...missingDimensions,
+        ...requiredPhysicalFieldTerms,
+    ].some((term) => ['product category', 'category'].includes(normalizeMetricPhrase(term)));
+    const physicalRoleAliases = {
+        'product category': ['product type'],
+        category: ['product type'],
+        // `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
+        // price column.
+        ...(hasProductCategoryRequirement ? { revenue: ['product price'] } : {}),
+    };
+    const physicalRoleTerms = (term) => uniqueNormalizedTerms([
+        term,
+        ...(physicalRoleAliases[normalizeMetricPhrase(term)] ?? []),
+    ]);
+    const columnMatchesTerm = (column, term) => 
+    // A relation-qualified ID can contain a metric word even when the column
+    // itself does not.  Raw `fact_revenue.competitor` is not revenue evidence.
+    // Physical role proof therefore starts with field-local name/alias facts,
+    // never a parent relation token.
+    columnFieldIdentityTerms(column).some((identity) => physicalRoleTerms(term).some((role) => metricTermsMatch(identity, role)));
+    const matchingColumns = new Map(terms.map((term) => [
+        term,
+        columns.filter((column) => columnMatchesTerm(column, term)),
+    ]));
+    const uncovered = terms.filter((term) => (matchingColumns.get(term) ?? []).length === 0);
+    if (uncovered.length > 0) {
+        return { ok: false, candidateIds: [], reason: `Qualified physical columns did not cover ${uncovered.join(', ')}.` };
+    }
+    const stableCandidateId = (candidate) => candidate.qualifiedId ?? candidate.id;
+    const stableCandidates = (values) => [...values].sort((left, right) => Number(right.exactMatch === true) - Number(left.exactMatch === true)
+        || right.relevanceScore - left.relevanceScore
+        || stableCandidateId(left).localeCompare(stableCandidateId(right)));
+    const stableColumnsForTerm = (values, term) => [...values].sort((left, right) => {
+        const rank = (column) => {
+            const identities = columnFieldIdentityTerms(column);
+            if (identities.some((identity) => identity === term))
+                return 0;
+            if (identities.some((identity) => metricTermsMatch(identity, term)))
+                return 1;
+            return 2;
+        };
+        return rank(left) - rank(right)
+            || Number(right.exactMatch === true) - Number(left.exactMatch === true)
+            || right.relevanceScore - left.relevanceScore
+            || stableCandidateId(left).localeCompare(stableCandidateId(right));
+    });
+    const relationCoverage = relations.map((relation) => new Set(terms.filter((term) => (matchingColumns.get(term) ?? []).some((column) => columnTouchesRelation(column, relation)))));
+    const selectRequiredColumns = (selectedRelations) => {
+        const selected = new Map();
+        for (const term of [...terms].sort()) {
+            const alreadySelected = [...selected.values()].some((column) => columnMatchesTerm(column, term));
+            if (alreadySelected)
+                continue;
+            const matches = stableColumnsForTerm((matchingColumns.get(term) ?? []).filter((column) => selectedRelations.some((relation) => columnTouchesRelation(column, relation))), term);
+            const selectedColumn = matches[0];
+            if (!selectedColumn)
+                return undefined;
+            selected.set(stableCandidateId(selectedColumn), selectedColumn);
+        }
+        return [...selected.values()];
+    };
+    const physicalEvidence = (selectedRelations, requiredColumns, joinColumns, relationshipProofIds, reason) => {
+        // Keep one deterministic witness for every requested role, then the
+        // necessary join-key witnesses and proof identities.  Do not add an
+        // entire table schema: that used to hide required columns behind a broad
+        // 32-card truncation.  If the minimal evidence itself exceeds the cap,
+        // decline the path rather than silently dropping a required witness.
+        const ids = [...new Set([
+                ...stableCandidates(selectedRelations).map(stableCandidateId),
+                ...stableCandidates(requiredColumns).map(stableCandidateId),
+                ...stableCandidates(joinColumns).map(stableCandidateId),
+                ...[...relationshipProofIds].sort(),
+            ])];
+        if (ids.length > 32) {
+            return {
+                ok: false,
+                candidateIds: [],
+                reason: `The minimal qualified exploratory closure needs ${ids.length} required relation, field, join-key, or proof witnesses, exceeding the 32-card safety cap; no required evidence was dropped.`,
+            };
+        }
+        return { ok: true, candidateIds: ids, reason };
+    };
+    const completeRelation = relationCoverage
+        .map((coverage, index) => ({ coverage, index }))
+        .filter(({ coverage }) => coverage.size === terms.length)
+        .sort((left, right) => stableCandidateId(relations[left.index]).localeCompare(stableCandidateId(relations[right.index])))[0];
+    if (completeRelation) {
+        const relation = relations[completeRelation.index];
+        const requiredColumns = selectRequiredColumns([relation]);
+        if (!requiredColumns) {
+            return { ok: false, candidateIds: [], reason: 'Qualified physical columns did not cover the requested fields on the selected relation.' };
+        }
+        return physicalEvidence([relation], requiredColumns, [], [], 'One qualified physical relation covers the requested fields without a join.');
+    }
+    // Build only from structured relationship proofs. A large retrieval snapshot
+    // 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.
+    const adjacent = relations.map(() => new Set());
+    const joinColumnsForProof = (proof, left, right) => {
+        const leftEndpoints = candidateRelationshipEndpoints(left);
+        const rightEndpoints = candidateRelationshipEndpoints(right);
+        const from = normalizedRelationshipIdentity(proof.from ?? '');
+        const to = normalizedRelationshipIdentity(proof.to ?? '');
+        const direct = leftEndpoints.has(from) && rightEndpoints.has(to);
+        const reverse = leftEndpoints.has(to) && rightEndpoints.has(from);
+        if (!direct && !reverse)
+            return undefined;
+        const witnesses = new Map();
+        for (const key of proof.keys) {
+            const leftKey = normalizeMetricPhrase(direct ? key.from : key.to);
+            const rightKey = normalizeMetricPhrase(direct ? key.to : key.from);
+            const leftColumn = stableColumnsForTerm(columns.filter((column) => columnTouchesRelation(column, left)
+                && columnMatchesTerm(column, leftKey)), leftKey)[0];
+            const rightColumn = stableColumnsForTerm(columns.filter((column) => columnTouchesRelation(column, right)
+                && columnMatchesTerm(column, rightKey)), rightKey)[0];
+            // A relationship record alone cannot prove a compilable raw join.  Both
+            // canonical endpoint columns must be present in this same snapshot.
+            if (!leftColumn || !rightColumn)
+                return undefined;
+            witnesses.set(stableCandidateId(leftColumn), leftColumn);
+            witnesses.set(stableCandidateId(rightColumn), rightColumn);
+        }
+        return [...witnesses.values()];
+    };
+    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()]
+                .sort((first, second) => first.id.localeCompare(second.id))
+                .flatMap((proof) => {
+                const joinColumns = joinColumnsForProof(proof, relations[left], relations[right]);
+                return joinColumns ? [{ proof, columns: joinColumns }] : [];
+            });
+            if (shared.length === 0)
+                continue;
+            adjacent[left].add(right);
+            adjacent[right].add(left);
+            witnessesForEdge.set(`${Math.min(left, right)}:${Math.max(left, right)}`, shared);
+        }
+    }
+    const closures = [];
+    for (let root = 0; root < relations.length; root += 1) {
+        const nodes = new Set([root]);
+        const edges = [];
+        const covered = new Set(relationCoverage[root]);
+        while (covered.size < terms.length) {
+            let best;
+            const pending = [{ node: root, path: [root] }];
+            const seen = new Set([root]);
+            while (pending.length > 0) {
+                const current = pending.shift();
+                const gain = [...relationCoverage[current.node]].filter((term) => !covered.has(term)).length;
+                if (gain > 0 && (!best || gain > best.gain || (gain === best.gain && current.path.length < best.distance))) {
+                    best = { path: current.path, gain, distance: current.path.length };
+                }
+                for (const neighbor of adjacent[current.node] ?? []) {
+                    if (seen.has(neighbor))
+                        continue;
+                    seen.add(neighbor);
+                    pending.push({ node: neighbor, path: [...current.path, neighbor] });
+                }
+            }
+            if (!best)
+                break;
+            for (const node of best.path) {
+                nodes.add(node);
+                for (const term of relationCoverage[node])
+                    covered.add(term);
+            }
+            for (let index = 1; index < best.path.length; index += 1) {
+                const left = best.path[index - 1];
+                const right = best.path[index];
+                if (!edges.some(([edgeLeft, edgeRight]) => edgeLeft === left && edgeRight === right || edgeLeft === right && edgeRight === left)) {
+                    edges.push([left, right]);
+                }
+            }
+        }
+        if (covered.size === terms.length)
+            closures.push({ nodes, edges, covered });
+    }
+    const selected = closures.sort((left, right) => left.nodes.size - right.nodes.size
+        || left.edges.length - right.edges.length
+        || [...left.nodes].join(',').localeCompare([...right.nodes].join(',')))[0];
+    if (!selected) {
+        return {
+            ok: false,
+            candidateIds: [],
+            reason: 'Multiple physical relations lacked one connected, certified, validated, fanout-safe automatic-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
+            // relations. Preserve that proof-specific category for downstream
+            // receipts and repair guidance.
+            gap: {
+                code: 'MISSING_RELATIONSHIP',
+                missing: ['a connected certified, validated, fanout-safe relationship proof'],
+                witnessCandidateIds: stableCandidates(relations).map(stableCandidateId),
+            },
+        };
+    }
+    const selectedRelations = [...selected.nodes].map((index) => relations[index]);
+    const requiredColumns = selectRequiredColumns(selectedRelations);
+    if (!requiredColumns) {
+        return { ok: false, candidateIds: [], reason: 'Qualified physical columns did not cover the requested fields on the selected relationship closure.' };
+    }
+    const selectedWitnesses = selected.edges.map(([left, right]) => witnessesForEdge.get(`${Math.min(left, right)}:${Math.max(left, right)}`)?.[0]).filter((witness) => Boolean(witness));
+    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.');
+}
+/**
+ * The pre-freeze cascade is router authority, including when the bounded
+ * meaning call could not run.  A missing role in a compact meaning package is
+ * not terminal proof of absence: eligible certified/semantic tiers are marked
+ * ineligible, then the same immutable snapshot may prove a review-required
+ * physical path.  Policy, fiscal, and relationship safety gates run before
+ * this helper and remain terminal where appropriate.
+ */
+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 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 coverage = sourceCoverageFromEvidence(input.evidence, snapshotCandidates);
+    const coverageFor = (source) => coverage.find((item) => item.source === source);
+    const skippedAttempt = (tier, source) => {
+        const item = coverageFor(source);
+        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 requested tuple before plan freeze.`
+                : `The ${tier} source was ${item?.status ?? 'unavailable'} in this snapshot.`,
+            planFrozen: false,
+        };
+    };
+    const governedCoverage = coverageFor('governed_relational');
+    const attempts = [
+        skippedAttempt('certified', 'certified'),
+        skippedAttempt('semantic', 'semantic'),
+        {
+            version: 1,
+            tier: 'governed_relational',
+            outcome: governedCoverage?.status === 'available' ? 'ineligible' : 'unavailable',
+            candidateIds: governedCoverage?.candidateIds ?? [],
+            reason: governedCoverage?.status === 'available'
+                ? 'Retrieved governed relationship evidence did not prove a complete relational execution tuple.'
+                : `The governed relational source was ${governedCoverage?.status ?? 'unavailable'}; exploratory eligibility is evaluated independently.`,
+            planFrozen: false,
+        },
+        {
+            version: 1,
+            tier: 'exploratory_sql',
+            outcome: exploratoryExecutable ? 'executable' : missingRankingMetric ? 'ambiguous' : 'unavailable',
+            candidateIds: physicalPath.candidateIds,
+            reason: missingRankingMetric
+                ? `${physicalPath.reason} A ranking measure remains unbound, so exploration cannot be selected.`
+                : physicalPath.reason,
+            planFrozen: false,
+        },
+    ];
+    const message = exploratoryExecutable
+        ? `${input.messagePrefix} A same-snapshot qualified physical path is available for review-required exploratory SQL.`
+        : missingRankingMetric
+            ? `${input.messagePrefix} ${physicalPath.reason} A ranking measure must be selected before DQL can freeze or explore this plan.`
+            : `${input.messagePrefix} ${physicalPath.reason}`;
+    const analyticalCascadeDecision = buildAnalyticalCascadeDecision({
+        requirements: input.requirements,
+        sourceCoverage: coverage,
+        attempts: exploratoryExecutable
+            ? attempts
+            : [...attempts, {
+                    version: 1,
+                    tier: 'clarify_or_gap',
+                    outcome: 'unavailable',
+                    candidateIds: [],
+                    reason: message,
+                    planFrozen: false,
+                }],
+        ...(exploratoryExecutable ? { selectedTier: 'exploratory_sql' } : {}),
+        planFrozen: false,
+        stopReason: exploratoryExecutable ? 'selected' : missingRankingMetric ? 'ambiguous' : 'coverage_gap',
+    });
+    if (!exploratoryExecutable) {
+        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: input.terminalCandidateIds ?? [],
+                ...(physicalPath.gap ? { gap: physicalPath.gap } : {}),
+            },
+            analyticalCascadeDecision,
+            resolvedAnalyticalPlan: undefined,
+            meaningResolution: undefined,
+        };
+    }
+    return {
+        ...input.base,
+        action: 'answer',
+        confidence: 0.55,
+        reason: message,
+        source: 'heuristic',
+        category: 'data_lookup',
+        depth: 'quick',
+        requiresClarification: false,
+        clarifyingQuestion: undefined,
+        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,
+    };
+}
+/**
+ * A pair of raw relations is not normally a reason to bypass a clarification:
+ * `orders`, `customers`, and `products` can still be three competing meanings.
+ * It is different when the reader asked for a display value from one relation
+ * and a predicate that physically exists only on another relation.  In that
+ * narrow case the evidence is complementary rather than competing.
+ *
+ * This helper is intentionally conservative.  It requires all of the
+ * following from ONE retrieval snapshot before it can select review-required
+ * exploration:
+ *   - a display-shaped column (for example `product_name`),
+ *   - a boolean/predicate-shaped column on a different relation (for example
+ *     `is_perishable_supply`),
+ *   - the same qualified join key on both relations, and
+ *   - a shared, non-fanout relationship proof that touches those relations.
+ *
+ * That means a lexical collection of tables can never suppress a genuine
+ * ambiguity.  The generated executor still validates read-only SQL and its
+ * join/aggregation safety before anything runs.
+ */
+function findSafeComplementaryPhysicalComposition(question, candidates) {
+    const physical = candidates.filter((candidate) => candidate.eligible !== false
+        && candidate.compatibility !== 'incompatible'
+        && (candidate.kind === 'dbt_model' || candidate.kind === 'dbt_source' || candidate.kind === 'sql_table' || candidate.kind === 'sql_column'));
+    const relations = physical.filter((candidate) => candidate.kind !== 'sql_column');
+    const columns = physical.filter((candidate) => candidate.kind === 'sql_column');
+    if (relations.length < 2 || columns.length < 4)
+        return undefined;
+    const relationSources = (candidate) => candidate.sourceObjects?.length
+        ? candidate.sourceObjects
+        : [candidate.qualifiedId ?? candidate.id];
+    const relationForColumn = (column) => {
+        if (!column.sourceObjects?.length)
+            return [];
+        return relations.filter((relation) => relationSources(relation).some((source) => column.sourceObjects.includes(source)));
+    };
+    const questionTokens = new Set(substantiveLexicalTokens(question).map(singularize));
+    const candidateTokens = (candidate) => new Set(candidateIdentityTerms(candidate)
+        .flatMap((identity) => identity.split(' '))
+        .map(singularize)
+        .filter(Boolean));
+    const matchesQuestion = (candidate) => [...candidateTokens(candidate)].filter((token) => questionTokens.has(token));
+    const displayColumns = columns.filter((column) => {
+        const name = normalizeMetricPhrase(column.name);
+        return /(?:^| )(?:name|label|title)(?:$| )/.test(name)
+            && matchesQuestion(column).length > 0
+            && relationForColumn(column).length > 0;
+    });
+    if (displayColumns.length === 0)
+        return undefined;
+    const displayTokens = new Set(displayColumns.flatMap(matchesQuestion));
+    const predicateColumns = columns.filter((column) => {
+        const name = normalizeMetricPhrase(column.name);
+        // Predicate shape is required. A text field such as `supply_name` may be
+        // lexically close to "supplies", but it is not proof of the requested
+        // condition and must keep the ordinary clarification behavior.
+        const predicateShape = /(?:^| )(?:is|has|flag|status|active|enabled)(?: |$)/.test(name);
+        return predicateShape
+            && matchesQuestion(column).some((token) => !displayTokens.has(token))
+            && relationForColumn(column).length > 0;
+    });
+    if (predicateColumns.length === 0)
+        return undefined;
+    const columnJoinKeys = (column) => uniqueNormalizedTerms([
+        column.name,
+        ...(column.aliases ?? []),
+    ]).filter((term) => /(?:^| )id$/.test(term));
+    for (const displayColumn of displayColumns) {
+        for (const displayRelation of relationForColumn(displayColumn)) {
+            for (const predicateColumn of predicateColumns) {
+                for (const predicateRelation of relationForColumn(predicateColumn)) {
+                    const displaySources = new Set(relationSources(displayRelation));
+                    if (relationSources(predicateRelation).some((source) => displaySources.has(source)))
+                        continue;
+                    const displayColumnsOnRelation = columns.filter((column) => relationForColumn(column).some((relation) => relation.id === displayRelation.id));
+                    const predicateColumnsOnRelation = columns.filter((column) => relationForColumn(column).some((relation) => relation.id === predicateRelation.id));
+                    const predicateJoinKeys = new Set(predicateColumnsOnRelation.flatMap(columnJoinKeys));
+                    const joinKey = displayColumnsOnRelation.flatMap(columnJoinKeys).find((key) => predicateJoinKeys.has(key));
+                    if (!joinKey)
+                        continue;
+                    const sharedRelationshipProofIds = [...safeRelationshipProofsForPair(displayRelation, predicateRelation, joinKey).keys()];
+                    if (sharedRelationshipProofIds.length === 0)
+                        continue;
+                    const selectedPhysical = [
+                        displayRelation,
+                        predicateRelation,
+                        ...displayColumnsOnRelation,
+                        ...predicateColumnsOnRelation,
+                    ].filter((candidate, index, all) => all.findIndex((other) => other.id === candidate.id) === index);
+                    const baseRequirements = buildAnalyticalRequirementSet({ question });
+                    const requirements = {
+                        ...baseRequirements,
+                        dimensions: uniqueNormalizedTerms([...baseRequirements.dimensions, displayColumn.name]),
+                        entityTerms: uniqueNormalizedTerms([...baseRequirements.entityTerms, ...matchesQuestion(displayColumn)]),
+                        entityDisplayTerms: uniqueNormalizedTerms([...baseRequirements.entityDisplayTerms, ...matchesQuestion(displayColumn)]),
+                        memberTerms: uniqueNormalizedTerms([...baseRequirements.memberTerms, predicateColumn.name]),
+                    };
+                    const physicalPath = hasSafeExploratoryPhysicalPath(requirements, selectedPhysical, [], [displayColumn.name, predicateColumn.name, joinKey]);
+                    if (!physicalPath.ok)
+                        continue;
+                    const relationshipCandidates = candidates.filter((candidate) => sharedRelationshipProofIds.includes(candidate.id)
+                        || Boolean(candidate.qualifiedId && sharedRelationshipProofIds.includes(candidate.qualifiedId)));
+                    return {
+                        requirements,
+                        candidateIds: [...new Set([
+                                ...physicalPath.candidateIds,
+                                ...sharedRelationshipProofIds,
+                                ...relationshipCandidates.map((candidate) => candidate.qualifiedId ?? candidate.id),
+                            ])].slice(0, 32),
+                        displayColumn,
+                        predicateColumn,
+                        joinKey,
+                        relationshipProofIds: sharedRelationshipProofIds,
+                        reason: `Qualified ${displayRelation.name}.${displayColumn.name} and ${predicateRelation.name}.${predicateColumn.name} are complementary requirements joined by ${joinKey}; the shared relationship proof permits review-required exploration.`,
+                    };
+                }
+            }
+        }
+    }
+    return undefined;
+}
+/** Build the router-owned cascade for a safe raw relational composition. */
+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);
+    if (!composition)
+        return undefined;
+    const coverage = sourceCoverageFromEvidence(evidence, evidence.candidates);
+    const coverageFor = (source) => coverage.find((item) => item.source === source);
+    const skippedAttempt = (tier, source, reason) => {
+        const item = coverageFor(source);
+        return {
+            version: 1,
+            tier,
+            outcome: item?.status === 'available' ? 'ineligible' : 'unavailable',
+            candidateIds: item?.candidateIds ?? [],
+            reason,
+            planFrozen: false,
+        };
+    };
+    const attempts = [
+        skippedAttempt('certified', 'certified', 'No certified candidate proved the composed display and predicate tuple.'),
+        skippedAttempt('semantic', 'semantic', 'No semantic candidate proved the composed display and predicate tuple.'),
+        {
+            version: 1,
+            tier: 'governed_relational',
+            outcome: 'ineligible',
+            candidateIds: [...new Set([
+                    ...(coverageFor('governed_relational')?.candidateIds ?? []),
+                    ...composition.relationshipProofIds,
+                ])].slice(0, 32),
+            reason: 'The same-snapshot relationship proof closes the physical path, but no complete governed relational execution tuple was retrieved.',
+            planFrozen: false,
+        },
+        {
+            version: 1,
+            tier: 'exploratory_sql',
+            outcome: 'executable',
+            candidateIds: composition.candidateIds,
+            reason: composition.reason,
+            planFrozen: false,
+        },
+    ];
+    const analyticalCascadeDecision = buildAnalyticalCascadeDecision({
+        requirements: composition.requirements,
+        sourceCoverage: coverage,
+        attempts,
+        selectedTier: 'exploratory_sql',
+        planFrozen: false,
+        stopReason: 'selected',
+    });
+    return {
+        ...base,
+        action: 'answer',
+        confidence: 0.55,
+        source: 'heuristic',
+        category: 'data_lookup',
+        depth: 'quick',
+        reason: `${composition.reason} Certified and semantic execution did not freeze; generated SQL remains review_required.`,
+        requiresClarification: false,
+        retrievalEvidence: retrievalTrace(evidence, candidates),
+        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',
+        },
+    };
+}
+function cascadeForResolution(input) {
+    const coverage = sourceCoverageFromEvidence(input.evidence, input.candidates);
+    const coverageFor = (source) => coverage.find((item) => item.source === source);
+    const selectedTier = input.plan.capability === 'certified_execution' ? 'certified'
+        : input.plan.capability === 'semantic_execution' ? 'semantic'
+            : input.plan.capability === 'governed_relational' ? 'governed_relational'
+                : input.plan.capability === 'bounded_exploration' ? 'exploratory_sql'
+                    : undefined;
+    const frozen = input.reconciliation.outcome === 'ready' && input.plan.mode === 'authoritative';
+    const tier = (name, source, selected) => {
+        const item = coverageFor(source);
+        return {
+            version: 1,
+            tier: name,
+            outcome: selected ? 'executable' : item?.status === 'available' ? 'ineligible' : 'unavailable',
+            candidateIds: item?.candidateIds ?? [],
+            reason: selected ? `The ${name} tier proved the complete requested tuple and froze the plan.` : item?.status === 'available' ? `The ${name} tier was retrieved but did not prove the complete tuple.` : `The ${name} source was ${item?.status ?? 'unavailable'} in this snapshot.`,
+            planFrozen: frozen && selected,
+        };
+    };
+    const attempts = [
+        tier('certified', 'certified', selectedTier === 'certified'),
+        tier('semantic', 'semantic', selectedTier === 'semantic'),
+        tier('governed_relational', 'governed_relational', selectedTier === 'governed_relational'),
+        tier('exploratory_sql', 'exploratory', selectedTier === 'exploratory_sql'),
+    ];
+    if (!selectedTier) {
+        attempts.push({ version: 1, tier: 'clarify_or_gap', outcome: input.reconciliation.outcome === 'clarify' ? 'ambiguous' : input.reconciliation.outcome === 'policy_blocked' ? 'denied' : 'unavailable', candidateIds: [], reason: input.reconciliation.reason, planFrozen: false });
+    }
+    return buildAnalyticalCascadeDecision({
+        requirements: buildAnalyticalRequirementSet({ question: input.question, parsedIntent: input.evidence.parsedIntent }),
+        sourceCoverage: coverage,
+        attempts,
+        ...(selectedTier ? { selectedTier } : {}),
+        planFrozen: frozen,
+        stopReason: input.reconciliation.outcome === 'ready' ? 'selected' : input.reconciliation.outcome === 'clarify' ? 'ambiguous' : input.reconciliation.outcome === 'policy_blocked' ? 'denied' : 'coverage_gap',
+    });
+}
 function routeDecisionForResolution(base, evidence, candidates, resolution, source, question = resolution.interpretedQuestion, mode = 'authoritative') {
-    let planBoundResolution = resolution;
+    // Treat an LLM/direct selection as a nomination, never as permission to
+    // let a certified block borrow a metric from neighboring semantic cards.
+    // This check runs immediately before plan construction so every fast lane,
+    // cached selection, explicit choice, and provider response shares it.
+    let planBoundResolution = withDeclaredFiscalBinding(repairIncompleteCertifiedMeasureSelection(resolution, evidence, candidates), evidence, candidates, question);
     if (resolution.analyticalFrame && resolution.recommendedRoute === 'semantic') {
-        const { analyticalFrame: sourceFrame, ...resolutionWithoutFrame } = resolution;
+        const sourceFrame = resolution.analyticalFrame;
         const bindingPlan = buildResolvedAnalyticalPlan({
             question,
-            resolution: resolutionWithoutFrame,
+            // Keep the frame available while binding its time-axis roles.  A
+            // time dimension lives in `capability.timeDimensions`, not the ordinary
+            // group-by list; stripping the frame first made a valid report_date
+            // binding look unresolved after a certified→semantic recovery.
+            resolution,
             evidence,
             candidates,
             mode,
@@ -444,6 +1304,17 @@ function routeDecisionForResolution(base, evidence, candidates, resolution, sour
     const analytical = routedResolution.questionType === "diagnosis" ||
         routedResolution.questionType === "research";
     const reason = reconciliation.reason;
+    const analyticalCascadeDecision = cascadeForResolution({
+        evidence,
+        candidates,
+        resolution: routedResolution,
+        plan: resolvedAnalyticalPlan,
+        reconciliation,
+        question,
+    });
+    const terminalGap = reconciliation.outcome === 'modeling_gap'
+        ? terminalGapWitnessForResolutionFailure(resolvedAnalyticalPlan)
+        : undefined;
     return {
         ...base,
         action: needsClarification
@@ -464,6 +1335,7 @@ function routeDecisionForResolution(base, evidence, candidates, resolution, sour
         depth: analytical ? "deep" : "quick",
         meaningResolution: routedResolution,
         resolvedAnalyticalPlan,
+        analyticalCascadeDecision,
         retrievalEvidence: retrievalTrace(evidence, candidates),
         requiresClarification: needsClarification,
         ...(terminallyBlocked
@@ -477,6 +1349,7 @@ function routeDecisionForResolution(base, evidence, candidates, resolution, sour
                         : 'ANALYTICAL_MODELING_GAP',
                     message: reconciliation.reason,
                     candidateIds: resolvedAnalyticalPlan.resolutionFailure?.candidateIds ?? [],
+                    ...(terminalGap ? { gap: terminalGap } : {}),
                 },
             }
             : {}),
@@ -490,6 +1363,151 @@ function routeDecisionForResolution(base, evidence, candidates, resolution, sour
             : {}),
     };
 }
+/**
+ * A block may be relevant to a metric without returning that metric. When a
+ * stale catalog result or provider selection nominates such a block, continue
+ * with one exact semantic definition when it exists; otherwise preserve the
+ * genuine metric ambiguity as stable semantic choices. Never construct a
+ * certified plan whose output contract merely borrows a neighbor's identity.
+ */
+function repairIncompleteCertifiedMeasureSelection(resolution, evidence, candidates) {
+    if (resolution.recommendedRoute !== 'certified')
+        return resolution;
+    const selected = resolution.recommendedExecutionId
+        ? candidates.find((candidate) => candidate.id === resolution.recommendedExecutionId)
+        : candidates.find((candidate) => resolution.selectedConceptIds.includes(candidate.id));
+    const requestedMeasures = evidence.parsedIntent?.measures?.length
+        ? evidence.parsedIntent.measures
+        : resolution.queryIntent.measures;
+    if (!selected || selected.kind !== 'certified_block'
+        || certifiedCandidateExplicitlyCoversMeasures(selected, requestedMeasures))
+        return resolution;
+    const compatibleMetrics = candidates.filter((candidate) => candidate.kind === 'semantic_metric'
+        && candidate.compatibility === 'compatible'
+        && requestedMeasures.length > 0
+        && requestedMeasures.every((requested) => candidateProvesMetricTerm(candidate, requested))
+        && Boolean(normalizeEvidenceAnalyticalCapability(candidate).capability));
+    const exactMetrics = compatibleMetrics.filter((candidate) => requestedMeasures.every((requested) => semanticMetricIdentityExactlyMatches(candidate, requested)));
+    if (exactMetrics.length === 1) {
+        const metric = exactMetrics[0];
+        return {
+            ...resolution,
+            selectedConceptIds: [metric.id],
+            recommendedExecutionId: metric.id,
+            recommendedRoute: 'semantic',
+            confidence: resolution.confidence === 'low' ? 'medium' : resolution.confidence,
+            // The frame is a typed interpretation of the requested tuple, not a
+            // claim that the rejected certified block can execute it.  Preserve it
+            // when the exact semantic metric owns the same request so the frozen
+            // plan retains its V2 time/comparison/ranking contract.  Clearing it
+            // here downgraded a safe semantic recovery into a legacy V1 blocked
+            // plan solely because the original certified nomination was incomplete.
+            analyticalFrame: resolution.analyticalFrame,
+            missingInformation: [...new Set([
+                    ...resolution.missingInformation,
+                    `${selected.name} does not declare ${requestedMeasures.join(', ')} as an output; continued with the exact semantic metric ${metric.name}.`,
+                ])],
+        };
+    }
+    const choices = compatibleMetrics.map((candidate) => candidate.id);
+    return {
+        ...resolution,
+        selectedConceptIds: [],
+        recommendedExecutionId: undefined,
+        recommendedRoute: 'clarify',
+        confidence: 'low',
+        analyticalFrame: undefined,
+        compatibilityOutcome: 'clarify',
+        compatibilityFailures: [{
+                code: 'CERTIFIED_MEASURE_OUTPUT_MISSING',
+                field: 'measure',
+                message: `${selected.name} does not declare ${requestedMeasures.join(', ')} as an output.`,
+                candidateIds: choices,
+            }],
+        missingInformation: [...new Set([
+                ...resolution.missingInformation,
+                choices.length > 1
+                    ? `The selected certified block does not declare ${requestedMeasures.join(', ')}. Choose among the compatible semantic metric definitions.`
+                    : `The selected certified block does not declare ${requestedMeasures.join(', ')} as an output.`,
+            ])],
+        clarifyingQuestion: choices.length > 1
+            ? 'Which compatible semantic metric should DQL use?'
+            : resolution.clarifyingQuestion,
+    };
+}
+function semanticMetricIdentityExactlyMatches(candidate, requested) {
+    const requestedIdentity = normalizeMetricPhrase(requested);
+    if (!requestedIdentity)
+        return false;
+    return [candidate.name, ...(candidate.aliases ?? []), candidate.qualifiedId ?? candidate.id]
+        .map((identity) => normalizeMetricPhrase(identity.split(/[.:/]/).at(-1) ?? identity))
+        .some((identity) => identity === requestedIdentity);
+}
+/**
+ * Clarification is an execution-affecting choice, not a generic search result
+ * picker.  In particular, a block tagged with revenue may be useful context
+ * but cannot be offered for an explicit revenue request unless that block's
+ * own output contract declares revenue.  Applying this at the option boundary
+ * keeps a stale pooled candidate from becoming a later structured bypass.
+ */
+function clarificationRequirementsForResolution(resolution) {
+    const question = resolution.interpretedQuestion;
+    const questionTerms = normalizeMetricPhrase(question);
+    // A parser/result frame can carry inherited technical hints that do not
+    // belong to the user's current wording.  They are useful to planning, but
+    // must not turn an unrelated structured option into an invalid selection.
+    // Keep only parser measures the question actually says, then add the
+    // resolver's own typed metric frame when it exists.
+    const mentionedMeasures = resolution.queryIntent.measures.filter((measure) => {
+        const normalized = normalizeMetricPhrase(measure);
+        const tokens = normalized.split(' ').filter((token) => token.length >= 3);
+        return tokens.length > 0 && tokens.every((token) => questionTerms.includes(token));
+    });
+    const frameMeasures = resolution.analyticalFrame?.metricConceptIds.map((id) => id.split(/[.:/]/).filter(Boolean).at(-1) ?? id) ?? [];
+    return buildAnalyticalRequirementSet({
+        question,
+        parsedIntent: {
+            ...resolution.queryIntent,
+            measures: [...new Set([...mentionedMeasures, ...frameMeasures])],
+        },
+    });
+}
+function explicitMeasureTermsForClarification(requirements) {
+    return [...new Set([
+            ...(requirements?.measures ?? []),
+            ...(requirements?.ranking?.metricTerms ?? []),
+        ].map((term) => normalizeMetricPhrase(term.split(/[.:/]/).at(-1) ?? term)).filter(Boolean))];
+}
+function candidateOwnsExplicitClarificationRoles(candidate, requirements) {
+    if (candidate.eligible === false || candidate.compatibility === 'incompatible')
+        return false;
+    const measures = explicitMeasureTermsForClarification(requirements);
+    if (measures.length === 0)
+        return true;
+    if (candidate.kind === 'certified_block') {
+        return certifiedCandidateExplicitlyCoversMeasures(candidate, measures);
+    }
+    // A structured choice for a measure must be the metric itself.  An entity,
+    // member, model, or physical relation can help compile the chosen metric but
+    // cannot become its meaning merely because it happened to rank highly.
+    // A semantic metric is a valid *meaning* choice when it owns at least one
+    // explicitly requested metric. Multi-metric plans still cannot freeze until
+    // every requested measure is bound by the immutable plan; this narrower
+    // option check lets a user choose between the revenue/refunds definitions
+    // without pretending the single metric already answers the whole tuple.
+    return candidate.kind === 'semantic_metric'
+        && measures.some((measure) => candidateProvesMetricTerm(candidate, measure));
+}
+function compatibleClarificationCandidates(candidates, requirements) {
+    return candidates.filter((candidate) => candidateOwnsExplicitClarificationRoles(candidate, requirements));
+}
+function withoutMeasureClarificationRequirements(requirements) {
+    const { ranking: _ranking, ...withoutRanking } = requirements;
+    return {
+        ...withoutRanking,
+        measures: [],
+    };
+}
 /**
  * The immutable RAP is the final routing authority. Meaning may nominate an
  * execution route, but cannot leave the router claiming an answer after the
@@ -509,6 +1527,7 @@ function reconcileResolvedPlanOutcome(resolution, plan, candidates) {
     ].filter(({ binding }) => binding.status !== 'resolved');
     const qualifiedChoiceIds = [...new Set(bindings.flatMap(({ binding }) => binding.candidateIds))].sort();
     const userResolvableBinding = bindings.some(({ binding }) => binding.candidateIds.length > 0);
+    const clarificationRequirements = clarificationRequirementsForResolution(resolution);
     if (plan.resolutionFailure?.outcome === 'policy_blocked') {
         return {
             outcome: 'policy_blocked',
@@ -525,9 +1544,19 @@ function reconcileResolvedPlanOutcome(resolution, plan, candidates) {
         const optionIds = qualifiedChoiceIds.length > 0
             ? qualifiedChoiceIds
             : [...new Set((resolution.compatibilityFailures ?? []).flatMap((failure) => failure.candidateIds))].sort();
+        const unresolvedMeasure = bindings.some(({ kind }) => kind === 'measure');
+        const optionRequirements = unresolvedMeasure
+            ? clarificationRequirements
+            : withoutMeasureClarificationRequirements(clarificationRequirements);
         const options = optionIds.length > 0
-            ? clarificationOptionsForQualifiedIds(optionIds, candidates)
-            : buildClarificationOptions(candidates);
+            ? clarificationOptionsForQualifiedIds(optionIds, candidates, optionRequirements)
+            : buildClarificationOptions(candidates, optionRequirements);
+        if (options.length === 0) {
+            return {
+                outcome: 'modeling_gap',
+                reason: 'No retrieved artifact owns every explicitly requested analytical role, so DQL did not offer an incompatible structured selection.',
+            };
+        }
         const bindingSummary = bindings.map(({ kind, binding }) => `${kind} “${binding.requested}” is ${binding.status}`).join('; ');
         const question = routedClarificationQuestion(resolution, bindings, options);
         return {
@@ -538,11 +1567,18 @@ function reconcileResolvedPlanOutcome(resolution, plan, candidates) {
         };
     }
     if (resolution.confidence === 'low' || resolution.recommendedRoute === 'clarify') {
+        const options = buildClarificationOptions(candidates, clarificationRequirements);
+        if (options.length === 0) {
+            return {
+                outcome: 'modeling_gap',
+                reason: 'No retrieved artifact owns every explicitly requested analytical role, so DQL did not offer an incompatible structured selection.',
+            };
+        }
         return {
             outcome: 'clarify',
             reason: `The retrieved evidence needs one governed meaning choice: ${plan.missingInformation.join(' ') || resolution.interpretedQuestion}`,
             question: resolution.clarifyingQuestion ?? buildEvidenceClarification(candidates, plan.missingInformation),
-            options: buildClarificationOptions(candidates),
+            options,
         };
     }
     return {
@@ -550,12 +1586,85 @@ function reconcileResolvedPlanOutcome(resolution, plan, candidates) {
         reason: `The selected analytical plan is not executable from the governed model: ${plan.missingInformation.join(' ') || 'review its capability and relationship proof.'}`,
     };
 }
-function clarificationOptionsForQualifiedIds(ids, candidates) {
-    return ids.slice(0, 3).map((id) => {
-        const candidate = candidates.find((item) => item.id === id || item.qualifiedId === id);
+/**
+ * Keep a specific terminal gap only when its producer supplied a typed reason.
+ * A generic modeling gap must never become a relationship-gap claim because a
+ * later renderer happened to mention joins in its repair copy.
+ */
+function terminalGapWitnessForResolutionFailure(plan) {
+    const failure = plan.resolutionFailure;
+    if (!failure || failure.outcome !== 'modeling_gap')
+        return undefined;
+    const codes = new Set(failure.codes);
+    const unresolved = [...new Set(failure.bindings
+            .filter((binding) => binding.status !== 'resolved')
+            .map((binding) => binding.requested)
+            .filter(Boolean))];
+    const witnessCandidateIds = [...new Set([
+            ...failure.candidateIds,
+            ...(failure.selectedCapabilityId ? [failure.selectedCapabilityId] : []),
+            ...(failure.selectedExecutionId ? [failure.selectedExecutionId] : []),
+        ])].sort();
+    if (codes.has('RELATIONSHIP_PROOF_MISSING')) {
+        return {
+            code: 'MISSING_RELATIONSHIP',
+            missing: ['a certified, validated, fanout-safe relationship proof'],
+            witnessCandidateIds,
+        };
+    }
+    if (codes.has('METRIC_CAPABILITY_MISSING') || codes.has('MISSING_MEASURE')) {
+        return {
+            code: 'MISSING_MEASURE',
+            missing: unresolved.length > 0 ? unresolved : ['the requested governed measure'],
+            witnessCandidateIds,
+        };
+    }
+    if (codes.has('MEMBER_FILTER_UNSUPPORTED') || codes.has('MISSING_ATTRIBUTE')) {
+        return {
+            code: 'MISSING_ATTRIBUTE',
+            missing: unresolved.length > 0 ? unresolved : ['the requested governed attribute or member filter'],
+            witnessCandidateIds,
+        };
+    }
+    if ([
+        'DIMENSION_ROLE_UNSUPPORTED',
+        'TIME_DIMENSION_REQUIRED',
+        'TIME_DIMENSION_AMBIGUOUS',
+        'TIME_ROLE_UNSUPPORTED',
+        'TIME_GRAIN_UNSUPPORTED',
+        'MISSING_DIMENSION',
+    ].some((code) => codes.has(code))) {
+        return {
+            code: 'MISSING_DIMENSION',
+            missing: unresolved.length > 0 ? unresolved : ['the requested governed dimension or time role'],
+            witnessCandidateIds,
+        };
+    }
+    return {
+        code: 'MISSING_RUNTIME_CAPABILITY',
+        missing: unresolved.length > 0 ? unresolved : ['the complete requested analytical tuple'],
+        witnessCandidateIds,
+    };
+}
+function clarificationOptionsForQualifiedIds(ids, candidates, requirements) {
+    const requireArtifactLocalMeasureProof = explicitMeasureTermsForClarification(requirements).length > 0;
+    return ids
+        .map((id) => ({
+        id,
+        candidate: candidates.find((item) => item.id === id || item.qualifiedId === id),
+    }))
+        .filter(({ candidate }) => candidate
+        ? candidateOwnsExplicitClarificationRoles(candidate, requirements)
+        // Qualified capability dimensions are synthesized by the resolved
+        // plan, not necessarily returned as standalone retrieval cards. They
+        // remain valid choices for a dimension/filter clarification, but never
+        // for an explicit metric role whose local artifact proof is missing.
+        : !requireArtifactLocalMeasureProof)
+        .slice(0, 3)
+        .map(({ id, candidate }) => {
         return {
-            id,
-            label: candidate?.name ?? qualifiedIdLabel(id),
+            id: candidate?.id ?? id,
+            label: candidate?.name || qualifiedIdLabel(candidate?.qualifiedId ?? id),
             ...(candidate?.definition?.trim() ? { description: candidate.definition.trim() } : {}),
             kind: candidate?.kind ?? 'semantic_member',
         };
@@ -577,17 +1686,122 @@ function routedClarificationQuestion(resolution, bindings, options) {
     return resolution.clarifyingQuestion
         ?? `Which governed binding should I use before running this query?`;
 }
-function continueCascadeAfterIncompleteSelection(base, evidence, candidates, selected) {
+function continueCascadeAfterIncompleteSelection(base, evidence, candidates, selected, question) {
+    // 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;
+    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 governedCoverage = coverage.find((item) => item.source === 'governed_relational');
+    const attempts = [
+        {
+            version: 1,
+            tier: 'certified',
+            outcome: 'ineligible',
+            candidateIds: coverage.find((item) => item.source === 'certified')?.candidateIds ?? [],
+            reason: `The explicit selection ${selectedId} did not prove a complete certified tuple.`,
+            planFrozen: false,
+        },
+        {
+            version: 1,
+            tier: 'semantic',
+            outcome: 'ineligible',
+            candidateIds: [...new Set([selectedId, ...(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,
+        },
+        {
+            version: 1,
+            tier: 'governed_relational',
+            outcome: governedCoverage?.status === 'available' ? 'ineligible' : 'unavailable',
+            candidateIds: governedCoverage?.candidateIds ?? [],
+            reason: governedCoverage?.status === 'available'
+                ? 'Retrieved governed relationship evidence did not prove a complete relational plan.'
+                : `The governed relational source was ${governedCoverage?.status ?? 'unavailable'}; exploratory eligibility is evaluated independently.`,
+            planFrozen: false,
+        },
+        {
+            version: 1,
+            tier: 'exploratory_sql',
+            outcome: physicalPath.ok ? 'executable' : 'unavailable',
+            candidateIds: physicalPath.candidateIds,
+            reason: physicalPath.reason,
+            planFrozen: false,
+        },
+    ];
+    const message = physicalPath.ok
+        ? `The selected governed meaning ${selectedId} does not prove the complete requested metric, dimension, filter, and grain tuple. DQL consumed that selection once and did not substitute a correlated metric or execute a different artifact; a same-snapshot qualified physical path is available for review-required exploratory SQL.`
+        : `The selected governed meaning ${selectedId} does not prove the complete requested metric, dimension, filter, and grain tuple. DQL consumed that selection once and will not substitute a correlated metric or execute generated SQL because ${physicalPath.reason}`;
+    const analyticalCascadeDecision = buildAnalyticalCascadeDecision({
+        requirements,
+        sourceCoverage: coverage,
+        attempts: physicalPath.ok
+            ? attempts
+            : [...attempts, { version: 1, tier: 'clarify_or_gap', outcome: 'unavailable', candidateIds: [selectedId], reason: message, planFrozen: false }],
+        ...(physicalPath.ok ? { selectedTier: 'exploratory_sql' } : {}),
+        planFrozen: false,
+        stopReason: physicalPath.ok ? 'selected' : 'coverage_gap',
+    });
+    const meaningResolution = {
+        interpretedQuestion: question,
+        questionType: 'value',
+        selectedConceptIds: [selectedId],
+        queryIntent: defaultQueryIntent(evidence),
+        rejectedCandidates: [],
+        confidence: 'low',
+        missingInformation: [message],
+        recommendedRoute: physicalPath.ok ? 'exploratory' : 'clarify',
+        compatibilityOutcome: 'modeling_gap',
+        compatibilityFailures: [{
+                code: 'INCOMPLETE_SELECTED_CAPABILITY',
+                field: 'selected capability',
+                message,
+                candidateIds: [selectedId],
+            }],
+    };
+    if (!physicalPath.ok) {
+        return {
+            ...base,
+            action: 'block',
+            confidence: 1,
+            reason: message,
+            source: 'heuristic',
+            category: 'data_lookup',
+            depth: 'quick',
+            retrievalEvidence: retrievalTrace(evidence, candidates),
+            requiresClarification: false,
+            resolvedAnalyticalPlan: undefined,
+            meaningResolution,
+            analyticalCascadeDecision,
+            terminalOutcome: {
+                kind: 'modeling_gap',
+                code: 'ANALYTICAL_MODELING_GAP',
+                message,
+                candidateIds: [selectedId],
+                ...(physicalPath.gap ? { gap: physicalPath.gap } : {}),
+            },
+        };
+    }
     return {
         ...base,
         action: 'answer',
-        confidence: 0.78,
-        reason: `The user selected ${selected.name}, but that evidence does not prove the complete requested metric, dimension, filter, and grain tuple. The selection is consumed once; continue through the governed semantic/SQL cascade without dropping any requested part.`,
+        confidence: 0.55,
+        reason: message,
         source: 'heuristic',
         category: 'data_lookup',
         depth: 'quick',
         retrievalEvidence: retrievalTrace(evidence, candidates),
         requiresClarification: false,
+        resolvedAnalyticalPlan: undefined,
+        meaningResolution,
+        analyticalCascadeDecision,
     };
 }
 function enforceAnalyticalCompatibility(resolution, evidence, candidates) {
@@ -702,14 +1916,15 @@ function enforceAnalyticalCompatibility(resolution, evidence, candidates) {
                 "The requested analytical tuple is not executable from the current governed model."),
     };
 }
-function buildClarificationOptions(candidates) {
-    const governed = candidates.filter((candidate) => candidate.compatibility !== "incompatible" &&
+function buildClarificationOptions(candidates, requirements) {
+    const roleCompatible = compatibleClarificationCandidates(candidates, requirements);
+    const governed = roleCompatible.filter((candidate) => candidate.compatibility !== "incompatible" &&
         (candidate.kind === "certified_block" ||
             candidate.kind === "semantic_metric" ||
             candidate.kind === "semantic_member"));
     const pool = governed.length > 1
         ? governed
-        : candidates.filter((candidate) => candidate.compatibility !== "incompatible");
+        : roleCompatible;
     const chosen = pool.slice(0, 3);
     // Two candidates can legitimately share a display name (a dbt model and its
     // MetricFlow measure are both "customers"). Rendering both as "customers"
@@ -732,6 +1947,301 @@ function buildClarificationOptions(candidates) {
         };
     });
 }
+/**
+ * The server envelope persists the option/requirement contract that rendered a
+ * clarification.  Browser context is never authority: the local runtime adds
+ * a host-only binding only after reading the persisted thread. Current snapshot
+ * compatibility remains mandatory, so a client cannot forge an old option list
+ * to admit an unrelated artifact.
+ */
+function persistedClarificationSelectionContext(request) {
+    const context = request.conversationContext;
+    const envelope = context?.conversationEnvelope && typeof context.conversationEnvelope === 'object'
+        ? context.conversationEnvelope
+        : context?.serverSnapshot && typeof context.serverSnapshot === 'object'
+            ? context.serverSnapshot
+            : undefined;
+    const pending = envelope?.pendingClarification;
+    if (!pending || typeof pending !== 'object')
+        return undefined;
+    const pendingRecord = pending;
+    const selection = pendingRecord.selection;
+    if (!selection || typeof selection !== 'object')
+        return undefined;
+    const record = selection;
+    const ids = (value) => Array.isArray(value)
+        ? [...new Set(value.filter((item) => typeof item === 'string' && Boolean(item.trim())).map((item) => item.trim()))]
+        : [];
+    const requirements = normalizePersistedClarificationRequirements(record.requirements);
+    const optionIds = ids(record.optionIds);
+    const ambiguityCandidateIds = ids(record.ambiguityCandidateIds);
+    const snapshotId = typeof record.snapshotId === 'string' && record.snapshotId.trim()
+        ? record.snapshotId.trim()
+        : undefined;
+    const sourceTurnId = typeof pendingRecord.sourceTurnId === 'string' && pendingRecord.sourceTurnId.trim()
+        ? pendingRecord.sourceTurnId.trim()
+        : undefined;
+    const threadId = typeof envelope?.threadId === 'string' && envelope.threadId.trim()
+        ? envelope.threadId.trim()
+        : undefined;
+    const authority = context?.serverIssuedClarificationSelection;
+    const authorityRecord = authority && typeof authority === 'object' && !Array.isArray(authority)
+        ? authority
+        : undefined;
+    const authorityMatches = Boolean(authorityRecord?.version === 1
+        && typeof authorityRecord.threadId === 'string'
+        && authorityRecord.threadId === threadId
+        && typeof authorityRecord.sourceTurnId === 'string'
+        && authorityRecord.sourceTurnId === sourceTurnId
+        && typeof authorityRecord.snapshotId === 'string'
+        && authorityRecord.snapshotId === snapshotId);
+    const invalidReason = record.version !== 1
+        ? 'The structured selection envelope has an unsupported version.'
+        : !request.threadId || !threadId || threadId !== request.threadId
+            ? 'The structured selection is not bound to the active server conversation thread.'
+            : !sourceTurnId
+                ? 'The structured selection is missing its server turn binding.'
+                : optionIds.length === 0
+                    ? 'The structured selection is missing the options rendered by the server.'
+                    : !requirements
+                        ? 'The structured selection is missing its typed analytical requirements.'
+                        : !snapshotId
+                            ? 'The structured selection is missing its retrieval snapshot binding.'
+                            : !authorityMatches
+                                ? 'The structured selection was not issued by the active server conversation.'
+                                : undefined;
+    return {
+        optionIds,
+        ambiguityCandidateIds,
+        ...(requirements ? { requirements } : {}),
+        ...(snapshotId ? { snapshotId } : {}),
+        ...(sourceTurnId ? { sourceTurnId } : {}),
+        ...(threadId ? { threadId } : {}),
+        serverIssued: !invalidReason,
+        ...(invalidReason ? { invalidReason } : {}),
+    };
+}
+/**
+ * The persisted envelope crosses a client/server boundary.  It is only a
+ * reject-only continuity hint, but it must still be parsed as data rather than
+ * cast as an executable typed requirement set.  In particular, a malformed
+ * string must never be spread into one-character "measures" and weaken the
+ * selected-ID validation path.
+ */
+function normalizePersistedClarificationRequirements(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const record = value;
+    if (record.version !== 1)
+        return undefined;
+    const terms = (input) => Array.isArray(input)
+        ? [...new Set(input.filter((item) => typeof item === 'string' && Boolean(item.trim())).map((item) => item.trim()))]
+        : [];
+    const rankingRecord = record.ranking && typeof record.ranking === 'object' && !Array.isArray(record.ranking)
+        ? record.ranking
+        : undefined;
+    const timeRecord = record.time && typeof record.time === 'object' && !Array.isArray(record.time)
+        ? record.time
+        : undefined;
+    const direction = rankingRecord?.direction === 'bottom' ? 'bottom' : rankingRecord?.direction === 'top' ? 'top' : undefined;
+    const limit = typeof rankingRecord?.limit === 'number' && Number.isFinite(rankingRecord.limit) && rankingRecord.limit > 0
+        ? Math.floor(rankingRecord.limit)
+        : undefined;
+    const grain = timeRecord?.grain;
+    const safeGrain = grain === 'day' || grain === 'week' || grain === 'month' || grain === 'quarter' || grain === 'year'
+        ? grain
+        : undefined;
+    const timeRole = timeRecord?.role === 'time_axis' || timeRecord?.role === 'time_filter'
+        ? timeRecord.role
+        : undefined;
+    const fiscalPeriod = typeof timeRecord?.fiscalPeriod === 'string' && timeRecord.fiscalPeriod.trim()
+        ? timeRecord.fiscalPeriod.trim()
+        : undefined;
+    return {
+        version: 1,
+        measures: terms(record.measures),
+        dimensions: terms(record.dimensions),
+        entityTerms: terms(record.entityTerms),
+        entityDisplayTerms: terms(record.entityDisplayTerms),
+        memberTerms: terms(record.memberTerms),
+        ...(direction && limit !== undefined
+            ? {
+                ranking: {
+                    metricTerms: terms(rankingRecord?.metricTerms),
+                    entityTerms: terms(rankingRecord?.entityTerms),
+                    direction,
+                    limit,
+                    defaultedLimit: rankingRecord?.defaultedLimit === true,
+                },
+            }
+            : {}),
+        ...(timeRole
+            ? {
+                time: {
+                    role: timeRole,
+                    ...(safeGrain ? { grain: safeGrain } : {}),
+                    ...(fiscalPeriod ? { fiscalPeriod } : {}),
+                    requiresDeclaredFiscalCalendar: timeRecord?.requiresDeclaredFiscalCalendar === true,
+                },
+            }
+            : {}),
+    };
+}
+function mergeClarificationRequirements(current, persisted) {
+    if (!persisted)
+        return current;
+    // Persisted requirements are only a reject-only continuity check.  Unioning
+    // explicitly requested roles means an old selection cannot weaken the new
+    // typed interpretation even if a caller fabricated its envelope.
+    return {
+        ...current,
+        measures: [...new Set([...current.measures, ...(persisted.measures ?? [])])],
+        dimensions: [...new Set([...current.dimensions, ...(persisted.dimensions ?? [])])],
+        entityTerms: [...new Set([...current.entityTerms, ...(persisted.entityTerms ?? [])])],
+        entityDisplayTerms: [...new Set([...current.entityDisplayTerms, ...(persisted.entityDisplayTerms ?? [])])],
+        memberTerms: [...new Set([...current.memberTerms, ...(persisted.memberTerms ?? [])])],
+    };
+}
+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);
+    const choiceIds = compatible.map((candidate) => candidate.id);
+    if (!persisted?.serverIssued) {
+        return {
+            ok: false,
+            requirements,
+            choiceIds,
+            reason: persisted?.invalidReason
+                ?? 'A structured selection requires a server-issued clarification envelope.',
+        };
+    }
+    if (persisted.snapshotId !== input.evidence.snapshotId) {
+        return {
+            ok: false,
+            requirements,
+            choiceIds,
+            reason: 'The structured selection belongs to a stale retrieval snapshot and must be chosen again.',
+        };
+    }
+    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)) {
+        return {
+            ok: false,
+            requirements,
+            choiceIds,
+            reason: `The selected artifact ${input.selected.id} does not own every explicitly requested analytical role.`,
+        };
+    }
+    const persistedChoices = new Set([
+        ...(persisted?.optionIds ?? []),
+        ...(persisted?.ambiguityCandidateIds ?? []),
+    ]);
+    if (!persistedChoices.has(input.selected.id)
+        && !persistedChoices.has(input.selected.qualifiedId ?? '')) {
+        return {
+            ok: false,
+            requirements,
+            choiceIds,
+            reason: 'The selected governed identifier was not one of the persisted ambiguity choices for this question.',
+        };
+    }
+    if (choiceIds.length > 0 && !choiceIds.includes(input.selected.id)) {
+        return {
+            ok: false,
+            requirements,
+            choiceIds,
+            reason: 'The selected governed identifier is incompatible with the current typed requirement set.',
+        };
+    }
+    return { ok: true, requirements, choiceIds };
+}
+function invalidStructuredSelectionDecision(input) {
+    const coverage = sourceCoverageFromEvidence(input.evidence, input.candidates);
+    const persisted = persistedClarificationSelectionContext(input.request);
+    const persistedOptionIds = [...new Set([
+            ...(persisted?.serverIssued ? persisted.optionIds : []),
+            ...(persisted?.serverIssued ? persisted.ambiguityCandidateIds : []),
+        ])];
+    // Re-render only the original server-persisted ambiguity set when it exists.
+    // A rejected click cannot silently widen into a fresh block/metric choice
+    // that was never offered for this question; each remaining item is still
+    // filtered against current snapshot eligibility and artifact-local roles.
+    const options = persistedOptionIds.length > 0
+        ? clarificationOptionsForQualifiedIds(persistedOptionIds, input.candidates, input.validation.requirements)
+        : buildClarificationOptions(input.candidates, input.validation.requirements);
+    const candidateIds = input.validation.choiceIds;
+    const message = `${input.validation.reason} DQL did not freeze or execute a plan for that selection.`;
+    const decision = buildAnalyticalCascadeDecision({
+        requirements: input.validation.requirements,
+        sourceCoverage: coverage,
+        attempts: [
+            { version: 1, tier: 'certified', outcome: 'ineligible', candidateIds: coverage.find((item) => item.source === 'certified')?.candidateIds ?? [], reason: 'No selected certified artifact proved the requested tuple.', planFrozen: false },
+            { version: 1, tier: 'semantic', outcome: 'ambiguous', candidateIds, reason: 'The selected identifier was rejected before semantic ambiguity could be resolved.', planFrozen: false },
+            { version: 1, tier: 'governed_relational', outcome: 'unavailable', candidateIds: coverage.find((item) => item.source === 'governed_relational')?.candidateIds ?? [], reason: 'A structured selection cannot authorize relational execution while its meaning is invalid.', planFrozen: false },
+            { version: 1, tier: 'exploratory_sql', outcome: 'unavailable', candidateIds: coverage.find((item) => item.source === 'exploratory')?.candidateIds ?? [], reason: 'A structured selection cannot authorize exploratory execution while its meaning is invalid.', planFrozen: false },
+            { version: 1, tier: 'clarify_or_gap', outcome: options.length > 0 ? 'ambiguous' : 'unavailable', candidateIds, reason: message, planFrozen: false },
+        ],
+        planFrozen: false,
+        stopReason: options.length > 0 ? 'ambiguous' : 'coverage_gap',
+    });
+    if (options.length === 0) {
+        return {
+            ...input.base,
+            action: 'block',
+            confidence: 1,
+            source: 'heuristic',
+            category: 'data_lookup',
+            depth: 'quick',
+            reason: message,
+            requiresClarification: false,
+            retrievalEvidence: retrievalTrace(input.evidence, input.candidates),
+            terminalOutcome: { kind: 'modeling_gap', code: 'ANALYTICAL_MODELING_GAP', message, candidateIds },
+            analyticalCascadeDecision: decision,
+            resolvedAnalyticalPlan: undefined,
+            meaningResolution: undefined,
+        };
+    }
+    return {
+        ...input.base,
+        action: 'clarify',
+        confidence: 1,
+        source: 'heuristic',
+        category: 'unclear',
+        depth: 'quick',
+        reason: message,
+        requiresClarification: true,
+        clarifyingQuestion: 'That selection does not match the requested analytical meaning. Which compatible governed metric should DQL use?',
+        clarificationOptions: options,
+        retrievalEvidence: retrievalTrace(input.evidence, input.candidates),
+        analyticalCascadeDecision: decision,
+        resolvedAnalyticalPlan: undefined,
+        meaningResolution: {
+            interpretedQuestion: input.request.question,
+            questionType: questionTypeFromText(input.request.question),
+            selectedConceptIds: [],
+            queryIntent: defaultQueryIntent(input.evidence),
+            rejectedCandidates: [{ id: input.selectedId, reason: input.validation.reason }],
+            confidence: 'low',
+            missingInformation: [message],
+            recommendedRoute: 'clarify',
+            compatibilityOutcome: 'clarify',
+            compatibilityFailures: [{
+                    code: 'INVALID_STRUCTURED_SELECTION',
+                    field: 'selection',
+                    message: input.validation.reason,
+                    candidateIds,
+                }],
+        },
+    };
+}
 function candidateKindLabel(kind) {
     if (kind === 'certified_block')
         return 'certified block';
@@ -848,9 +2358,10 @@ function rankingMetricChoiceDecision(base, evidence, candidates, selected, quest
         && candidate.kind === 'semantic_metric'
         && !isDegenerateRankingMetric(question, evidence, candidate))
         .slice(0, 3);
-    const labels = options.length > 0
-        ? options.map((candidate) => renderCandidateChoice(candidate)).join(' or ')
-        : 'revenue, order count, or another measure available in the model';
+    if (options.length === 0) {
+        return unanswerableClarificationFallback(base, retrievalTrace(evidence, candidates), `${selected.name} counts customers and cannot rank them, and no alternative governed measure was retrieved, so DQL continued into the review-required generated lane instead of asking a question with no selectable answer.`);
+    }
+    const labels = options.map((candidate) => renderCandidateChoice(candidate)).join(' or ');
     return {
         ...base,
         action: 'clarify',
@@ -862,7 +2373,7 @@ function rankingMetricChoiceDecision(base, evidence, candidates, selected, quest
         requiresClarification: true,
         reason: `${selected.name} counts customers; it cannot distinguish individual customers for a top-customer ranking.`,
         clarifyingQuestion: `That metric counts unique customers and cannot rank individual customers. Which measure should rank them: ${labels}?`,
-        clarificationOptions: options.length > 0 ? buildClarificationOptions(options) : undefined,
+        clarificationOptions: buildClarificationOptions(options),
         retrievalEvidence: retrievalTrace(evidence, candidates),
         resolvedAnalyticalPlan: undefined,
         meaningResolution: undefined,
@@ -919,7 +2430,22 @@ function directResolution(request, evidence, candidate, candidates) {
         metricCandidates,
         candidates,
     });
-    const queryIntent = defaultQueryIntent(evidence);
+    const defaultIntent = defaultQueryIntent(evidence);
+    // 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
+    // two literal dimensions and overrule that local contract. Only replace
+    // dimensions when the selected block explicitly declares them, while the
+    // strict requested-measure check remains unchanged.
+    const exactCertifiedExample = candidate.kind === 'certified_block'
+        && candidate.exactMatch
+        && candidate.compatibility === 'compatible'
+        && candidate.analyticalFitClass === 'exact'
+        && certifiedCandidateExplicitlyCoversMeasures(candidate, defaultIntent.measures)
+        && (candidate.dimensions?.length ?? 0) > 0;
+    const queryIntent = exactCertifiedExample
+        ? { ...defaultIntent, dimensions: candidate.dimensions ?? [] }
+        : defaultIntent;
     const memberCandidates = candidates.filter((item) => {
         if (item.kind !== 'semantic_member' || item.compatibility === 'incompatible')
             return false;
@@ -1042,11 +2568,25 @@ mayAssumeInterpretation = true) {
         : candidates.filter((candidate) => !isDegenerateRankingMetric(request.question, evidence, candidate));
     if (questionTypeFromText(request.question) === 'ranking'
         && !hasExplicitRankingMeasure(request.question, evidence)) {
+        // Assume the measure where one is clearly indicated, and BIND it through the
+        // same resolution path an explicit selection takes — an assumption that
+        // cannot freeze a plan is refused downstream and surfaces as `blocked` with
+        // no options, which is worse than the question it replaced.
+        const assumed = mayAssumeInterpretation
+            ? assumableRankingMeasure(request.question, rankingCandidates)
+            : undefined;
+        if (assumed) {
+            return {
+                ...routeDecisionForResolution(base, evidence, candidates, directResolution(request, evidence, assumed.candidate, candidates), 'heuristic', request.question, planMode),
+                assumptions: [assumed.assumption],
+            };
+        }
         return bareRankingClarification(base, retrievalTrace(evidence, candidates), request.question, evidence, rankingCandidates);
     }
     const exactCompatible = candidates.filter((candidate) => candidate.exactMatch
         && candidate.compatibility !== "incompatible"
-        && rankingCandidates.includes(candidate));
+        && rankingCandidates.includes(candidate)
+        && candidateMayTerminateCertifiedForMeasures(candidate, evidence.parsedIntent?.measures ?? []));
     if (exactCompatible.length === 1 &&
         !hasMateriallyRelatedCompetitor(exactCompatible[0], candidates)) {
         return routeDecisionForResolution(base, evidence, candidates, directResolution(request, evidence, exactCompatible[0], candidates), "heuristic", request.question, planMode);
@@ -1060,7 +2600,7 @@ mayAssumeInterpretation = true) {
     // `type: simple` metric, the measure it wraps, and the model that holds them
     // were offered as three competing "meanings" of the same number.
     const best = mayAssumeInterpretation
-        ? bestGovernedInterpretation(request.question, rankingCandidates)
+        ? bestGovernedInterpretation(request.question, rankingCandidates, evidence.parsedIntent?.measures ?? [])
         : undefined;
     if (best) {
         return routeDecisionForResolution(base, evidence, candidates, directResolution(request, evidence, best, candidates), "heuristic", request.question, planMode);
@@ -1219,7 +2759,7 @@ export function collapseRedundantGovernedCandidates(question, candidates) {
  * question made ordinary lookups feel like an interrogation, and most of those
  * questions had no real ambiguity behind them.
  */
-export function bestGovernedInterpretation(question, candidates) {
+export function bestGovernedInterpretation(question, candidates, requestedMeasures = []) {
     // Take the best candidate that is actually executable, rather than refusing
     // because the top-ranked hit happens to be a descriptive modeling entity.
     // `compatibility: 'unknown'` is common for governed objects that execute
@@ -1229,7 +2769,9 @@ export function bestGovernedInterpretation(question, candidates) {
     return collapseRedundantGovernedCandidates(question, candidates).find((candidate) => candidate.compatibility !== 'partial'
         && (candidate.kind === 'certified_block'
             || candidate.kind === 'semantic_metric'
-            || candidate.kind === 'semantic_member'));
+            || candidate.kind === 'semantic_member')
+        && (candidate.kind !== 'certified_block'
+            || certifiedCandidateExplicitlyCoversMeasures(candidate, requestedMeasures)));
 }
 /**
  * Retrieval may nominate qualified candidates, but only the resolved plan may
@@ -1247,8 +2789,69 @@ function unresolvedAnalyticalPlanDecision(base, evidence, candidates = [], quest
         candidateCount: 0,
         candidateIds: [],
     };
+    // This generic fallback has no provider/plan-issued role target yet. Build
+    // its strict option roles from the user's words only; inherited parsed-intent
+    // hints can still guide later plan construction but must not hide every
+    // valid compositional or dimension choice.
+    const clarificationRequirements = buildAnalyticalRequirementSet({ question });
+    const physicalRequirements = buildAnalyticalRequirementSet({
+        question,
+        parsedIntent: evidence?.parsedIntent,
+    });
+    const fallbackToPhysicalCascade = () => {
+        if (!evidence)
+            return undefined;
+        const requiredPhysicalFieldTerms = [
+            ...physicalRequirements.dimensions,
+            ...physicalRequirements.entityTerms,
+            ...physicalRequirements.entityDisplayTerms,
+            ...(evidence.parsedIntent?.filters ?? []).map((filter) => filter.field),
+        ];
+        return preFreezePhysicalCascadeDecision({
+            base,
+            evidence,
+            candidates,
+            question,
+            requirements: physicalRequirements,
+            missingTerms: physicalRequirements.dimensions,
+            requiredPhysicalFieldTerms,
+            messagePrefix: 'No certified, semantic, or governed relational candidate proved the complete requested tuple before plan freeze.',
+            terminalCandidateIds: eligible.map((candidate) => candidate.qualifiedId ?? candidate.id),
+        });
+    };
     if (eligible.length > 1) {
-        const choices = eligible.slice(0, 3);
+        // Raw candidates can be complementary rather than competing. Do not ask a
+        // person to pick between the table that supplies the display value and the
+        // table that supplies the requested predicate when their qualified,
+        // same-snapshot relationship proof already closes a safe exploration path.
+        // The helper is deliberately stricter than generic retrieval: missing a
+        // display/predicate role, a shared key, or relationship/fanout proof keeps
+        // this exact clarification path intact.
+        const composition = evidence
+            ? complementaryExploratoryDecision(base, evidence, candidates, question)
+            : undefined;
+        if (composition)
+            return composition;
+        const choices = compatibleClarificationCandidates(eligible, clarificationRequirements).slice(0, 3);
+        if (choices.length === 0) {
+            return fallbackToPhysicalCascade() ?? (() => {
+                const message = 'No retrieved artifact owns every explicitly requested analytical role, so DQL did not offer an incompatible structured selection.';
+                return {
+                    ...base,
+                    action: 'block',
+                    confidence: 1,
+                    source: 'heuristic',
+                    category: 'data_lookup',
+                    depth: 'quick',
+                    reason: message,
+                    requiresClarification: false,
+                    retrievalEvidence: trace,
+                    terminalOutcome: { kind: 'modeling_gap', code: 'ANALYTICAL_MODELING_GAP', message, candidateIds: eligible.map((candidate) => candidate.qualifiedId ?? candidate.id) },
+                    resolvedAnalyticalPlan: undefined,
+                    meaningResolution: undefined,
+                };
+            })();
+        }
         return {
             ...base,
             action: 'clarify',
@@ -1259,7 +2862,7 @@ function unresolvedAnalyticalPlanDecision(base, evidence, candidates = [], quest
             reason: 'Bounded retrieval found multiple governed meanings, so no analytical plan was frozen.',
             requiresClarification: true,
             clarifyingQuestion: `Which governed meaning should DQL bind: ${choices.map(renderCandidateChoice).join(' or ')}?`,
-            clarificationOptions: buildClarificationOptions(choices),
+            clarificationOptions: buildClarificationOptions(choices, clarificationRequirements),
             retrievalEvidence: trace,
             resolvedAnalyticalPlan: undefined,
             meaningResolution: undefined,
@@ -1269,6 +2872,9 @@ function unresolvedAnalyticalPlanDecision(base, evidence, candidates = [], quest
     const message = candidateIds.length === 1
         ? `The retrieved governed candidate ${candidateIds[0]} did not prove the complete requested metric, grain, filters, ordering, and outputs. Model the missing capability before retrying.`
         : 'No governed candidate proved the complete requested metric, grain, filters, ordering, and outputs. Model the missing capability or choose a governed identifier before retrying.';
+    const physicalFallback = fallbackToPhysicalCascade();
+    if (physicalFallback)
+        return physicalFallback;
     return {
         ...base,
         action: 'block',
@@ -1296,6 +2902,10 @@ function unresolvedAnalyticalPlanDecision(base, evidence, candidates = [], quest
  */
 function deterministicPrePlanClarification(request, base, evidence, candidates) {
     const asksForRanking = questionTypeFromText(request.question) === 'ranking';
+    const requirements = buildAnalyticalRequirementSet({
+        question: request.question,
+        parsedIntent: evidence.parsedIntent,
+    });
     const requestedMeasures = (evidence.parsedIntent?.measures ?? [])
         .map(normalizeMetricPhrase)
         .filter(Boolean);
@@ -1304,7 +2914,13 @@ function deterministicPrePlanClarification(request, base, evidence, candidates)
         || hasStrongQualifiedMetricEvidence(candidates)
         || hasQuestionQualifiedMetricEvidence(request.question, evidence, candidates);
     const retrievalEvidence = retrievalTrace(evidence, candidates);
-    const requestedDimensions = uniqueNormalizedTerms(evidence.parsedIntent?.dimensions ?? []);
+    // “by month” is a time role/grain, and FY26 is a fiscal-period filter. They
+    // are not requests for literal `month`/`year` columns. A fiscal token still
+    // 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 ?? [])
+        .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))))
         ? [normalizeMetricPhrase(filter.field)]
@@ -1321,9 +2937,52 @@ function deterministicPrePlanClarification(request, base, evidence, candidates)
             .sort((left, right) => right.relevanceScore - left.relevanceScore || left.id.localeCompare(right.id))
             .slice(0, 3);
         if (alternatives.length === 0) {
-            if (!asksForRanking || hasExplicitRankingMetric)
+            // Bare rankings need a measure choice, not a dimension gap. Retain the
+            // no-options escape hatch only when the snapshot does not also expose a
+            // typed structural request. For "top customers for perishable products",
+            // a no-option ranking response previously hid the missing safe
+            // customer→order→item→supply closure behind an answer-shaped dead end.
+            // Record that pre-freeze gap instead; this still never invents a ranking
+            // measure or a relationship.
+            if (asksForRanking && !hasExplicitRankingMetric) {
+                const rankingClarification = bareRankingClarification(base, retrievalEvidence, request.question, evidence, candidates);
+                if (rankingClarification.action === 'clarify'
+                    && (rankingClarification.clarificationOptions?.length ?? 0) > 0) {
+                    return rankingClarification;
+                }
+                return preFreezePhysicalCascadeDecision({
+                    base,
+                    evidence,
+                    candidates,
+                    question: request.question,
+                    requirements,
+                    missingTerms: missingDimensions,
+                    requiredPhysicalFieldTerms: (evidence.parsedIntent?.filters ?? []).map((filter) => filter.field),
+                    messagePrefix: `No governed ranking measure and no complete governed tuple proved ${missingDimensions.map((term) => `“${term}”`).join(' and ')} before plan freeze.`,
+                    requireRankingMetric: true,
+                });
+            }
+            // Parsed-intent hints can include inherited/default dimensions that the
+            // user never asked for. Only turn a missing field into a product-facing
+            // modeling gap when its wording is present in this turn; otherwise let
+            // bounded meaning resolution preserve its own ambiguity contract.
+            const normalizedQuestion = normalizeMetricPhrase(request.question);
+            if (!missingDimensions.every((dimension) => normalizedQuestion.includes(dimension)))
                 return undefined;
-            return bareRankingClarification(base, retrievalEvidence, request.question, evidence, candidates);
+            const requestedLabel = missingDimensions.map((term) => `“${term}”`).join(' and ');
+            const temporalNote = requirements.time?.fiscalPeriod
+                ? ` ${requirements.time.fiscalPeriod} remains an unbound fiscal-period token until a declared calendar is available; DQL will not guess one.`
+                : '';
+            return preFreezePhysicalCascadeDecision({
+                base,
+                evidence,
+                candidates,
+                question: request.question,
+                requirements,
+                missingTerms: missingDimensions,
+                requiredPhysicalFieldTerms: (evidence.parsedIntent?.filters ?? []).map((filter) => filter.field),
+                messagePrefix: `The certified and semantic candidates did not prove ${requestedLabel}.${temporalNote}`,
+            });
         }
         const requestedLabel = missingDimensions.map((term) => `“${term}”`).join(' and ');
         const alternativeLabels = alternatives.map(renderCandidateChoice);
@@ -1350,6 +3009,39 @@ function deterministicPrePlanClarification(request, base, evidence, candidates)
     }
     return undefined;
 }
+/**
+ * A clarification with NO selectable options is unanswerable, and asking it is a
+ * dead end rather than a safety measure.
+ *
+ * Reported from production: "who are the top customers for BCM" returned
+ * "Top by which governed metric?" with zero choices. Answering it in prose
+ * ("...who have top revenue") produced the IDENTICAL question again, because the
+ * reply carries no `selectedEvidenceId` and re-enters the same path with the
+ * same evidence. A question that can only be answered by clicking a button that
+ * was never rendered loops forever.
+ *
+ * When the option list is empty the failure is in RETRIEVAL, not in the user's
+ * phrasing, so continue into the review-required generated lane and let the
+ * answer carry the caveat. `requiresClarification` is cleared deliberately:
+ * leaving it set would make `answerAnywayRoute` treat this as material ambiguity
+ * and re-block the turn.
+ */
+function unanswerableClarificationFallback(base, retrievalEvidence, reason) {
+    return {
+        ...base,
+        action: 'answer',
+        confidence: Math.min(base.confidence, 0.5),
+        source: 'heuristic',
+        category: 'data_lookup',
+        requiresClarification: false,
+        clarifyingQuestion: undefined,
+        clarificationOptions: undefined,
+        reason,
+        ...(retrievalEvidence ? { retrievalEvidence } : {}),
+        resolvedAnalyticalPlan: undefined,
+        meaningResolution: undefined,
+    };
+}
 /**
  * "Top by which governed metric?" with NO choices is a dead end: the asker
  * cannot know which measures are both governed and valid at the ranked grain,
@@ -1365,7 +3057,101 @@ function deterministicPrePlanClarification(request, base, evidence, candidates)
  *
  * Acceptance: AGT-030.
  */
-function bareRankingClarification(base, retrievalEvidence, question, evidence, candidates) {
+/**
+ * Generic measure vocabulary: words that say HOW MUCH, never WHICH SUBSET.
+ * A candidate built only from these adds no scope the asker did not state.
+ */
+const GENERIC_MEASURE_TOKENS = new Set([
+    'revenue', 'spend', 'spending', 'sale', 'amount', 'value', 'total', 'sum',
+    'count', 'number', 'order', 'quantity', 'qty', 'price', 'cost', 'profit',
+    'margin', 'gross', 'net', 'lifetime', 'avg', 'average', 'mean', 'median', 'score',
+    'rate', 'ratio', 'percent', 'share', 'volume', 'unit', 'balance', 'pretax', 'ltv',
+    'top', 'rank', 'ranking', 'by', 'per', 'the', 'of', 'and',
+]);
+/**
+ * Crude, symmetric singularization. Applied to BOTH sides, so the only thing
+ * that matters is that it agrees with itself — `address` becoming `addres` is
+ * harmless when the question's `address` becomes `addres` too. Without it a
+ * candidate named `customers.customer_value` is rejected against the question
+ * "who are the top customers", because the singular `customer` is neither a
+ * question word nor generic measure vocabulary. That is a morphology accident,
+ * not an unrequested scope, and it silently refused good assumptions.
+ */
+function singularize(token) {
+    if (token.length > 3 && token.endsWith('ies'))
+        return `${token.slice(0, -3)}y`;
+    if (token.length > 3 && (token.endsWith('ses') || token.endsWith('xes') || token.endsWith('zes'))) {
+        return token.slice(0, -2);
+    }
+    if (token.length > 2 && token.endsWith('s') && !token.endsWith('ss'))
+        return token.slice(0, -1);
+    return token;
+}
+/**
+ * Pick the measure a bare ranking should assume, or nothing.
+ *
+ * Returns the CANDIDATE, not a decision, because the assumption is only useful
+ * where it can be bound: an `action: 'answer'` with no frozen analytical plan is
+ * refused by the plan boundary and reaches the user as `blocked` with no
+ * options, which is strictly worse than the clarification it replaced. Measured
+ * exactly that way before this was moved to a caller that can bind it.
+ */
+export function assumableRankingMeasure(question, candidates) {
+    // Only a MEASURE can be assumed. A certified block is a whole authored query,
+    // not a ranking measure, so treating one as the answer to "by which metric?"
+    // silently selects someone else's entire analysis.
+    const assumable = candidates.filter((candidate) => (candidate.kind === 'semantic_metric' || candidate.kind === 'semantic_member')
+        && candidate.compatibility !== 'incompatible'
+        && rankingCandidateFitsBareQuestion(question, candidate));
+    if (assumable.length === 0)
+        return undefined;
+    const assumption = assumeDominantCandidate({
+        about: 'metric',
+        candidates: assumable.map((candidate) => ({
+            id: candidate.qualifiedId ?? candidate.id,
+            label: candidate.name,
+            score: candidate.relevanceScore,
+        })),
+        because: (chosen) => `"${chosen.label ?? chosen.id}" was the highest-ranked governed measure that can rank this entity, and it adds no filter the question did not ask for.`,
+    });
+    if (!assumption)
+        return undefined;
+    const chosen = assumable.find((candidate) => (candidate.qualifiedId ?? candidate.id) === assumption.chose);
+    return chosen ? { candidate: chosen, assumption } : undefined;
+}
+/**
+ * Does this ranking measure fit a question that named no measure?
+ *
+ * "Top customers" must not be silently answered by `top_beverage_customers`:
+ * that candidate carries a scope — beverages — the asker never asked for, and
+ * answering with it returns a confidently wrong list under a different question
+ * than the one posed. `assumeDominantCandidate` deliberately leaves this check
+ * to the caller, because dominance is about ranking and this is about meaning.
+ *
+ * The rule: every substantive token in the candidate's name must be either
+ * something the question already said, or generic measure vocabulary. Any
+ * leftover token is an unrequested qualifier, and the turn keeps asking.
+ */
+export function rankingCandidateFitsBareQuestion(question, candidate) {
+    const questionTokens = new Set(substantiveLexicalTokens(question).map(singularize));
+    // Identities arrive source-qualified (`semantic:metric:orders.revenue`). The
+    // `semantic`/`metric` prefix is plumbing, not vocabulary — tokenizing it would
+    // make every candidate look scoped and refuse every assumption.
+    const identity = (candidate.qualifiedId ?? candidate.id ?? '').split(':').at(-1) ?? '';
+    const nameTokens = substantiveLexicalTokens([candidate.name, identity].join(' '));
+    if (nameTokens.length === 0)
+        return false;
+    return nameTokens.map(singularize).every((token) => questionTokens.has(token) || GENERIC_MEASURE_TOKENS.has(token));
+}
+function bareRankingClarification(base, retrievalEvidence, question, evidence, candidates, 
+/**
+ * May this turn settle the measure by assumption rather than by asking?
+ * False wherever the step whose job is to judge ambiguity has positively
+ * reported some — assuming past a finding overrides it rather than filling a
+ * gap, and AGT-017 already establishes that lexical rank alone must not
+ * settle meaning when semantic judgment is unavailable.
+ */
+mayAssume = true) {
     const rankingChoices = (candidates ?? []).filter((candidate) => {
         if (candidate.compatibility === 'incompatible')
             return false;
@@ -1397,6 +3183,9 @@ function bareRankingClarification(base, retrievalEvidence, question, evidence, c
             return false;
         return true;
     });
+    if (rankingChoices.length === 0) {
+        return unanswerableClarificationFallback(base, retrievalEvidence, 'No retrieved governed measure can rank this entity, so DQL continued into the review-required generated lane instead of asking a question with no selectable answer.');
+    }
     return {
         ...base,
         action: 'clarify',
@@ -1408,9 +3197,7 @@ function bareRankingClarification(base, retrievalEvidence, question, evidence, c
         requiresClarification: true,
         clarifyingQuestion: 'Top by which governed metric?',
         retrievalEvidence,
-        ...(rankingChoices.length > 0
-            ? { clarificationOptions: buildClarificationOptions(rankingChoices) }
-            : {}),
+        clarificationOptions: buildClarificationOptions(rankingChoices),
         resolvedAnalyticalPlan: undefined,
         meaningResolution: undefined,
     };
@@ -1446,7 +3233,11 @@ function candidateProvesMetricTerm(candidate, requested) {
     if (candidate.compatibility === 'incompatible')
         return false;
     if (candidate.kind === 'certified_block') {
-        return candidate.compatibility === 'compatible';
+        // A block's relevance/tag/example must never impersonate one of its
+        // outputs.  Only a declared block output may prove an explicit requested
+        // metric (AGT-009/AGT-010).
+        return candidate.compatibility === 'compatible'
+            && certifiedCandidateExplicitlyCoversMeasures(candidate, [requested]);
     }
     if (candidate.kind !== 'semantic_metric')
         return false;
@@ -1617,9 +3408,10 @@ function hasMateriallyRelatedCompetitor(exact, candidates) {
  * against a uniquely compatible certified block; a second compatible block or
  * metric still goes to the bounded AI resolver.
  */
-function dominantCompatibleGovernedCandidate(candidates) {
+function dominantCompatibleGovernedCandidate(candidates, requestedMeasures = []) {
     const compatible = candidates.filter((candidate) => candidate.compatibility === "compatible"
-        && (candidate.kind === "certified_block" || candidate.kind === "semantic_metric" || candidate.kind === "semantic_member"));
+        && (candidate.kind === "certified_block" || candidate.kind === "semantic_metric" || candidate.kind === "semantic_member")
+        && candidateMayTerminateCertifiedForMeasures(candidate, requestedMeasures));
     if (compatible.length === 0)
         return undefined;
     const best = compatible[0];
@@ -1641,13 +3433,19 @@ function dominantCompatibleGovernedCandidate(candidates) {
     const hasExecutableCompetitor = compatible.some((candidate) => candidate.id !== best.id && candidate.relevanceScore >= competitorFloor);
     return hasExecutableCompetitor ? undefined : best;
 }
-function authoritativeExactCertifiedExample(candidates) {
+function authoritativeExactCertifiedExample(candidates, requestedMeasures = []) {
     const exact = candidates.filter((candidate) => candidate.kind === 'certified_block'
         && candidate.exactMatch
         && candidate.compatibility === 'compatible'
-        && candidate.analyticalFitClass === 'exact');
+        && candidate.analyticalFitClass === 'exact'
+        && certifiedCandidateExplicitlyCoversMeasures(candidate, requestedMeasures));
     return exact.length === 1 ? exact[0] : undefined;
 }
+/** Certified output coverage is a Tier-1 invariant; other routes pass through. */
+function candidateMayTerminateCertifiedForMeasures(candidate, requestedMeasures) {
+    return candidate.kind !== 'certified_block'
+        || certifiedCandidateExplicitlyCoversMeasures(candidate, requestedMeasures);
+}
 function shouldDeferCompositionalFollowUpToExecutor(base, candidates) {
     if (!base.followsUp)
         return false;
@@ -1718,7 +3516,7 @@ export function createHybridRouter(options = {}) {
             const base = deterministic(request);
             // The only pre-retrieval exits are deliberately narrow and unambiguously
             // non-analytical. App composition has its own catalog-grounded workflow.
-            if (base.action === "converse" || base.action === "compose_app") {
+            if (!request.selectedEvidenceId && (base.action === "converse" || base.action === "compose_app")) {
                 return { ...base, source: base.source ?? "heuristic" };
             }
             const initialDiscoveryRoute = discoveryRouteBeforeRetrieval(request, base);
@@ -1737,6 +3535,12 @@ export function createHybridRouter(options = {}) {
                 }
             }
             if (evidence) {
+                // The retrieval parser may carry broad search phrases such as
+                // `count_for_each_customer`. They are useful before retrieval, but
+                // they are not executable measures. Normalize once at the router
+                // boundary so every downstream plan/meaning path consumes the same
+                // typed measure + entity/dimension requirements.
+                evidence = withNormalizedAnalyticalRequirements(evidence, request.question);
                 evidence = {
                     ...evidence,
                     candidates: canonicalizeMetricMeasureCandidates(evidence.candidates),
@@ -1747,31 +3551,69 @@ export function createHybridRouter(options = {}) {
                             ]).filter((candidate) => evidence.clarificationCandidates.some((item) => item.id === candidate.id)) }
                         : {}),
                 };
-                let candidates = buildMeaningEvidencePackage(evidence, options.maxMeaningCandidates ?? 12);
-                // A structured clarification selection is authoritative identity input,
-                // not a new fuzzy-search phrase. Keep it in the bounded package even if
-                // per-tier limits would otherwise trim it from a large catalog.
-                // Look in BOTH lists. The ranking-measure choices are supplemental
-                // clarification candidates, not execution candidates, so resolving the
-                // selection against `candidates` alone silently found nothing — the
-                // click looked identical to no click, the ranking gate fired again, and
-                // the same three options came back forever.
+                // 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);
+                // 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
-                    ? [...evidence.candidates, ...(evidence.clarificationCandidates ?? [])]
-                        .find((candidate) => candidate.id === request.selectedEvidenceId && candidate.eligible !== false)
+                    ? clarificationCandidates.find((candidate) => candidate.id === request.selectedEvidenceId)
+                    : undefined;
+                const structuredSelection = request.selectedEvidenceId
+                    ? validateStructuredClarificationSelection({
+                        request,
+                        evidence,
+                        candidates: clarificationCandidates,
+                        selected: selectedEvidence,
+                    })
                     : undefined;
+                if (structuredSelection && !structuredSelection.ok) {
+                    return invalidStructuredSelectionDecision({
+                        base,
+                        request,
+                        evidence,
+                        candidates: clarificationCandidates,
+                        selectedId: request.selectedEvidenceId,
+                        validation: structuredSelection,
+                    });
+                }
                 if (selectedEvidence && !candidates.some((candidate) => candidate.id === selectedEvidence.id)) {
                     candidates = [selectedEvidence, ...candidates.filter((candidate) => candidate.id !== selectedEvidence.id)]
-                        .slice(0, options.maxMeaningCandidates ?? 12);
+                        .slice(0, options.maxMeaningCandidates ?? 16);
+                }
+                // 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
+                // must be considered before the package-length guard and before any
+                // deterministic missing-dimension cascade.
+                if (!request.selectedEvidenceId) {
+                    const authoredExample = authoritativeExactCertifiedExample(clarificationCandidates, evidence?.parsedIntent?.measures ?? []);
+                    if (authoredExample) {
+                        const candidatesForResolution = candidates.some((candidate) => candidate.id === authoredExample.id)
+                            ? candidates
+                            : [authoredExample, ...candidates];
+                        return routeDecisionForResolution(base, evidence, candidatesForResolution, directResolution(request, evidence, authoredExample, candidatesForResolution), 'heuristic', request.question, options.resolvedPlanMode ?? 'authoritative');
+                    }
                 }
                 if (candidates.length > 0) {
-                    // Clarification is local and never provider-bound, so it can inspect the
-                    // complete already-retrieved set. Keep the smaller package below for
-                    // any later meaning call.
-                    const clarificationCandidates = [
-                        ...evidence.candidates,
-                        ...(evidence.clarificationCandidates ?? []),
-                    ].filter((candidate, index, all) => candidate.eligible !== false && all.findIndex((other) => other.id === candidate.id) === index);
+                    // Fiscal tokens are execution requirements, not a semantic guess.
+                    // Ask exactly once before a meaning call or plan freeze when the
+                    // snapshot has no declared fiscal calendar/date-role binding.
+                    const fiscalClarification = fiscalCalendarClarification(request, base, evidence, candidates);
+                    if (fiscalClarification)
+                        return fiscalClarification;
                     const explicit = selectedEvidence ?? findExplicitEvidenceReference(request.question, candidates);
                     const explicitMeaningBinding = Boolean(explicit && (request.selectedEvidenceId
                         || /@(metric|block|model|table|column)\(/i.test(request.question)));
@@ -1797,8 +3639,19 @@ export function createHybridRouter(options = {}) {
                             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');
-                        return selectedEvidence && decision.requiresClarification
-                            ? continueCascadeAfterIncompleteSelection(base, evidence, candidates, selectedEvidence)
+                        // 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:
+                        // keep the chosen meaning, then consider the same-snapshot safe
+                        // exploratory path. An invalid/stale choice never reaches here, and
+                        // a frozen plan/policy denial is deliberately not downgraded.
+                        const selectedPreFreezeModelingGap = decision.terminalOutcome?.kind === 'modeling_gap'
+                            && decision.resolvedAnalyticalPlan?.capability === 'blocked'
+                            && decision.analyticalCascadeDecision?.planFrozen === false;
+                        return selectedEvidence
+                            && structuredSelection?.ok
+                            && (decision.requiresClarification || selectedPreFreezeModelingGap)
+                            ? continueCascadeAfterIncompleteSelection(base, evidence, candidates, selectedEvidence, request.question)
                             : decision;
                     }
                     const multiMetricPrimary = !shouldUseMeaningCall
@@ -1807,18 +3660,14 @@ export function createHybridRouter(options = {}) {
                     if (multiMetricPrimary) {
                         return routeDecisionForResolution(base, evidence, candidates, directResolution(request, evidence, multiMetricPrimary, candidates), "heuristic", request.question, options.resolvedPlanMode ?? 'authoritative');
                     }
-                    const authoredExample = !shouldUseMeaningCall
-                        ? authoritativeExactCertifiedExample(candidates)
-                        : undefined;
-                    if (authoredExample) {
-                        return routeDecisionForResolution(base, evidence, candidates, directResolution(request, evidence, authoredExample, candidates), 'heuristic', request.question, options.resolvedPlanMode ?? 'authoritative');
-                    }
-                    const exactCompatible = !shouldUseMeaningCall ? candidates.filter((candidate) => candidate.exactMatch && candidate.compatibility !== "incompatible") : [];
+                    const exactCompatible = !shouldUseMeaningCall ? candidates.filter((candidate) => candidate.exactMatch
+                        && candidate.compatibility !== "incompatible"
+                        && candidateMayTerminateCertifiedForMeasures(candidate, evidence?.parsedIntent?.measures ?? [])) : [];
                     if (exactCompatible.length === 1 && !hasMateriallyRelatedCompetitor(exactCompatible[0], candidates)) {
                         return routeDecisionForResolution(base, evidence, candidates, directResolution(request, evidence, exactCompatible[0], candidates), "heuristic", request.question, options.resolvedPlanMode ?? 'authoritative');
                     }
                     const dominant = !shouldUseMeaningCall
-                        ? dominantCompatibleGovernedCandidate(candidates)
+                        ? dominantCompatibleGovernedCandidate(candidates, evidence.parsedIntent?.measures ?? [])
                         : undefined;
                     if (dominant) {
                         return routeDecisionForResolution(base, evidence, candidates, directResolution(request, evidence, dominant, candidates), "heuristic", request.question, options.resolvedPlanMode ?? 'authoritative');
@@ -1865,7 +3714,12 @@ export function createHybridRouter(options = {}) {
                                 }))
                                 : undefined;
                         if (resolution) {
-                            const validated = validateMeaningResolution(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);
                             if (validated.ok) {
                                 const safeResolution = preventDegenerateRankingResolution(validated.resolution, evidence, candidates, request.question);
                                 // Meaning interpretation is still required for a fresh turn,
@@ -1905,11 +3759,29 @@ export function createHybridRouter(options = {}) {
                                     && !hasExplicitRankingMeasure(request.question, evidence)
                                     && !resolutionResolvedRanking
                                     && !explicitRankingSelection) {
+                                    // Meaning resolution ran here. If it named the ranking
+                                    // measure as the missing piece, that is its judgment and the
+                                    // turn asks rather than guessing past it. Otherwise a clearly
+                                    // indicated measure is assumed and BOUND through the same
+                                    // resolution path an explicit selection takes — an assumption
+                                    // that cannot freeze a plan is refused downstream and reaches
+                                    // the reader as `blocked` with no options.
+                                    const resolverFlagged = (safeResolution.missingInformation ?? [])
+                                        .some((item) => /measure|metric/i.test(item));
+                                    const assumedRanking = resolverFlagged
+                                        ? undefined
+                                        : assumableRankingMeasure(request.question, clarificationCandidates);
+                                    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);
+                                    clarificationCandidates, !resolverFlagged);
                                 }
                                 const deterministicGap = deterministicPrePlanClarification(request, base, evidence, clarificationCandidates);
                                 if (deterministicGap && safeResolution.recommendedRoute === 'clarify') {
@@ -1959,6 +3831,38 @@ export function createHybridRouter(options = {}) {
                         ?? fallbackDecision;
                 }
             }
+            // A structured selection cannot enter the legacy/no-evidence classifier.
+            // Without a fresh retrieval snapshot it has no proof that the server
+            // option still exists, so fail closed before any provider dispatch or
+            // generated-SQL fallback.
+            if (request.selectedEvidenceId) {
+                const unavailableEvidence = {
+                    snapshotId: 'unavailable:structured-selection',
+                    sourceFingerprint: 'unavailable:structured-selection',
+                    candidates: [],
+                };
+                const validation = validateStructuredClarificationSelection({
+                    request,
+                    evidence: unavailableEvidence,
+                    candidates: [],
+                    selected: undefined,
+                });
+                return invalidStructuredSelectionDecision({
+                    base,
+                    request,
+                    evidence: unavailableEvidence,
+                    candidates: [],
+                    selectedId: request.selectedEvidenceId,
+                    validation: validation.ok
+                        ? {
+                            ok: false,
+                            requirements: validation.requirements,
+                            choiceIds: validation.choiceIds,
+                            reason: 'The selected governed identifier could not be revalidated because retrieval is unavailable.',
+                        }
+                        : validation,
+                });
+            }
             // Legacy/no-evidence path. A confident analytical heuristic stays offline;
             // only the ambiguous middle pays the old classification call. Importantly,
             // load the catalog context before the model may choose general knowledge.