@duckcodeailabs/dql-agent 1.14.2 → 1.14.4

package/dist/answer-loop.js

@@ -35,13 +35,13 @@ import { analyticalErrorDetail, } from './analytical-error.js';
 import { fanoutWarningsForSql } from './metadata/grain-ledger.js';
 import { buildAggregationSafetyProof, buildSemanticCompilationAggregationSafetyProof, } from './aggregation-safety-proof.js';
 import { buildSemanticProofAuthorityV1 } from './semantic-proof-authority.js';
-import { GENERATED_ANALYTICAL_TUPLE_DRIFT_MESSAGE, validateGeneratedAnalyticalProposal, } from './generated-analytical-proposal.js';
+import { GENERATED_ANALYTICAL_TUPLE_DRIFT_MESSAGE, frozenRequiredOutputBindingProofsForPlan, validateFrozenRequiredOutputProjection, validateGeneratedAnalyticalProposal, } from './generated-analytical-proposal.js';
 import { evaluateDbtFirstGeneratedSql } from './metadata/dbt-first-safety.js';
 import { planAnalyticalPath, humanizeAnalyticalEntityId, analyticalPolicyUserFacingReason, } from './metadata/analytical-policy.js';
 import { planCertifiedAdaptation } from './metadata/block-adapt.js';
 import { compactSqlSnippet, extractSimpleSelectShape, selectExpressionOutputName, } from './metadata/sql-shape.js';
 import { composeSemanticQueryForQuestion, composeSemanticQueryFromCompiledMembers, composeSemanticQueryFromMembers, renderSemanticDqlArtifact, semanticDqlArtifactName, } from './semantic-bridge/compose.js';
-import { runAgenticToolLoop } from './agentic/tool-loop.js';
+import { runAgenticToolLoopDetailed } from './agentic/tool-loop.js';
 import { buildSemanticStageTools } from './agentic/toolset.js';
 import { deriveAgenticTrust } from './agentic/answer-contract.js';
 import { selectSemanticMembersViaLlm } from './semantic-bridge/member-select.js';
@@ -384,6 +384,572 @@ function certifiedInvocationInputs(block, plan) {
     }
     return Object.keys(parameters).length > 0 ? { parameters, parameterSources } : {};
 }
+/**
+ * Build the one typed certified-block invocation used by both the ordinary
+ * answer loop and the authoritative V2 exact-fit path.  Keeping this at the
+ * DQL boundary is important: a zero-provider Tier 1 shortcut may avoid
+ * conversational planning, but it must not avoid declared parameter binding,
+ * validation, or the normal overall top-N execution bound.
+ */
+export function buildCertifiedBlockInvocationInput(block, plan, question) {
+    return {
+        question,
+        ...certifiedInvocationInputs(block, plan),
+        ...(plan.requestedShape.topN?.scope === 'per_group'
+            ? {}
+            : plan.requestedShape.topN?.n
+                ? { rowLimit: plan.requestedShape.topN.n }
+                : {}),
+    };
+}
+/**
+ * Prove that an immutable certified block may satisfy a question-driven
+ * overall top-N result contract without conversational planning.  A declared
+ * limit parameter alone is not enough: the authored SQL must order rows and
+ * consume that exact parameter in its LIMIT clause.  This prevents a host
+ * from slicing arbitrary connector order and presenting it as certified.
+ */
+export function certifiedBlockProvesRequestedTopN(block, plan, options = {}) {
+    const topN = plan.requestedShape.topN;
+    if (!topN)
+        return true;
+    // The artifact is loaded from the snapshot-bound KG, but that persisted
+    // payload still crosses an older JSON schema boundary. Treat a malformed
+    // parameter contract as *not proved*, never as a reason to crash the Ask
+    // run or to infer an unordered ranking from connector row order.
+    if (topN.scope !== 'overall' || !block || block.kind !== 'block')
+        return false;
+    const limitParameters = (Array.isArray(block.parameters) ? block.parameters : []).flatMap((parameter) => {
+        if (!parameter || typeof parameter.name !== 'string' || parameter.name.trim() === '')
+            return [];
+        return parameter.name === 'top_n' || parameter.binding?.kind === 'limit'
+            ? [parameter]
+            : [];
+    });
+    if (typeof block.sql !== 'string')
+        return false;
+    const outerClauses = scanOutermostTopNClauses(block.sql);
+    if (!outerClauses)
+        return false;
+    const { orderBy, limitValue } = outerClauses;
+    // There are exactly two safe ways to prove the overall row bound:
+    //
+    // 1. The immutable artifact consumes its own declared top-N parameter in
+    //    the outer LIMIT clause (the ordinary certified contract); or
+    // 2. The artifact intentionally has no outer LIMIT and the local host owns
+    //    a frozen, typed execution row limit at the read-only SQL boundary.
+    //
+    // We never treat a fixed, driver-style, compound, or stale outer LIMIT as
+    // equivalent to the requested value. In particular, an existing fixed
+    // LIMIT prevents the host executor from appending the frozen limit, so it
+    // cannot prove a different user-requested top N.
+    const limitUsesDeclaredParameter = limitParameters.length === 1
+        && typeof limitValue === 'string'
+        && outerLimitUsesDeclaredTopNParameter(limitValue, limitParameters[0].name);
+    const hostOwnsFrozenRowLimit = limitValue === undefined
+        && Number.isInteger(options.hostEnforcedRowLimit)
+        && options.hostEnforcedRowLimit === topN.n
+        && options.hostEnforcedRowLimit > 0;
+    if (!limitUsesDeclaredParameter && !hostOwnsFrozenRowLimit)
+        return false;
+    // A question-driven ranking is only exact when the *primary* authored sort
+    // expression proves the requested measure.  Finding `revenue DESC` later in
+    // `ORDER BY customer_name ASC, revenue DESC` is not sufficient: the result
+    // is primarily alphabetical, not a top-revenue result.  Do not infer a
+    // ranking measure from row shape or candidate tags; that would turn an
+    // unproven certified artifact into a false exact answer.
+    const requestedMeasures = plan.requestedShape.measures
+        .map(normalizedTopNMetricId)
+        .filter(Boolean);
+    // An omitted measure is not normally a license to infer a ranking from a
+    // certified block. The narrow exception is server-owned evidence that this
+    // is either a direct certified question/title/alias match *or* the one
+    // complete certified tuple admitted by this immutable retrieval snapshot.
+    // In both cases the artifact's own primary non-dimension output supplies
+    // the authored default ranking contract. A provider cannot manufacture
+    // either flag from text or a card count.
+    const useAuthoredRankingDefault = requestedMeasures.length === 0
+        && (options.exactCertifiedQuestionMatch === true
+            || options.uniqueCompleteCertifiedFit === true);
+    if (requestedMeasures.length === 0 && !useAuthoredRankingDefault)
+        return false;
+    const firstOrderExpression = splitTopLevelSqlList(orderBy)[0];
+    if (!firstOrderExpression)
+        return false;
+    const firstOrder = parseTopNOrderExpression(firstOrderExpression);
+    if (!firstOrder)
+        return false;
+    const requiredDirection = plan.requestedShape.rankingDirection === 'bottom' ? 'asc' : 'desc';
+    if (firstOrder.direction !== requiredDirection)
+        return false;
+    const orderMetricIds = topNOrderMetricIds(firstOrder.expression, block);
+    if (requestedMeasures.length > 0) {
+        return requestedMeasures.some((measure) => orderMetricIds.has(measure));
+    }
+    return [...authoredTopNRankingMetricIds(block)].some((metric) => orderMetricIds.has(metric));
+}
+/**
+ * The implicit-ranking exception still needs an authored metric, not merely a
+ * sortable dimension.  Keep this proof inside the immutable block contract:
+ * declared outputs, compiler output lineage, and typed output roles are all
+ * captured with the artifact.  If an older block cannot distinguish its
+ * measures from dimensions, fail closed into the Ask planner.
+ */
+function authoredTopNRankingMetricIds(block) {
+    const dimensionIds = new Set((block.dimensions ?? []).map(normalizedTopNMetricId).filter(Boolean));
+    const outputRoles = new Map((block.outputContract ?? [])
+        .filter((output) => typeof output?.name === 'string')
+        .map((output) => [normalizedTopNMetricId(output.name), String(output.role ?? '').toLowerCase()]));
+    const outputIds = new Set([
+        ...(block.declaredOutputs ?? []),
+        ...(block.outputs ?? []).map((output) => output.name),
+        ...(block.outputContract ?? []).map((output) => output.name),
+    ].map(normalizedTopNMetricId).filter(Boolean));
+    const metrics = new Set();
+    for (const outputId of outputIds) {
+        const role = outputRoles.get(outputId) ?? '';
+        if (dimensionIds.has(outputId) || /(?:dimension|entity|label|attribute)/.test(role))
+            continue;
+        metrics.add(outputId);
+    }
+    return metrics;
+}
+function outerLimitUsesDeclaredTopNParameter(limitValue, parameterName) {
+    const escapedParameter = parameterName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // This proof is about an authored DQL artifact, not a connector SQL
+    // statement. Accept only the two compiler-recognized interpolation forms
+    // (`${name}` and `{name}`); driver placeholders, bare identifiers, fixed
+    // values, and compound expressions do not prove that the requested typed
+    // top-N binding controls the outer result contract.
+    return new RegExp(`^(?:\\$\\{\\s*${escapedParameter}\\s*\\}|\\{\\s*${escapedParameter}\\s*\\})$`, 'i').test(topNVisibleSql(limitValue).trim());
+}
+/**
+ * Locate the outer SELECT/ORDER BY/LIMIT clauses without treating text in a
+ * CTE, subquery, quoted identifier/string, or comment as part of the answer
+ * contract. A ranking proof must be about the query that actually returns the
+ * block rows, never an unused inner query that happens to mention revenue.
+ */
+function scanOutermostTopNClauses(sql) {
+    const tokens = topLevelSqlTokens(sql);
+    if (!tokens)
+        return undefined;
+    let orderByIndex = -1;
+    for (let index = 0; index + 1 < tokens.length; index += 1) {
+        if (tokens[index].text === 'order' && tokens[index + 1].text === 'by')
+            orderByIndex = index;
+    }
+    if (orderByIndex < 0)
+        return undefined;
+    let selectIndex = -1;
+    for (let index = 0; index < orderByIndex; index += 1) {
+        if (tokens[index].text === 'select')
+            selectIndex = index;
+    }
+    if (selectIndex < 0)
+        return undefined;
+    let fromIndex = -1;
+    for (let index = selectIndex + 1; index < orderByIndex; index += 1) {
+        if (tokens[index].text === 'from') {
+            fromIndex = index;
+            break;
+        }
+    }
+    if (fromIndex < 0)
+        return undefined;
+    let limitIndex = -1;
+    for (let index = orderByIndex + 2; index < tokens.length; index += 1) {
+        if (tokens[index].text === 'limit') {
+            limitIndex = index;
+            break;
+        }
+    }
+    const orderByEnd = limitIndex >= 0 ? tokens[limitIndex].start : sql.length;
+    // The outer ORDER BY must directly govern the outer LIMIT when one exists.
+    // A set operation, second SELECT, or a second ORDER BY in between is too
+    // complex for this exact shortcut and correctly falls back to the bounded
+    // Ask tool runtime. The same guard applies through end-of-query for an
+    // intentionally unbounded artifact whose host owns the frozen row limit.
+    if (tokens.slice(orderByIndex + 2, limitIndex >= 0 ? limitIndex : tokens.length).some((token) => token.text === 'select' || token.text === 'union' || token.text === 'intersect' || token.text === 'except')) {
+        return undefined;
+    }
+    const afterLimit = limitIndex >= 0 ? tokens.find((token, index) => index > limitIndex && (token.text === 'offset' || token.text === 'fetch' || token.text === 'for'))?.start ?? sql.length : sql.length;
+    const selectList = sql.slice(tokens[selectIndex].end, tokens[fromIndex].start).trim();
+    const orderBy = sql.slice(tokens[orderByIndex + 1].end, orderByEnd).trim();
+    const limitValue = limitIndex >= 0
+        ? sql.slice(tokens[limitIndex].end, afterLimit).replace(/;\s*$/, '').trim()
+        : undefined;
+    if (!selectList || !orderBy || (limitIndex >= 0 && !limitValue))
+        return undefined;
+    return {
+        selectList,
+        orderBy,
+        ...(limitValue ? { limitValue } : {}),
+    };
+}
+/**
+ * Tokenize only depth-zero SQL words. The state machine deliberately removes
+ * comments and literals from consideration while retaining positional ranges
+ * against the original SQL for clause slicing.
+ */
+function topLevelSqlTokens(sql) {
+    const tokens = [];
+    let depth = 0;
+    let quote;
+    let lineComment = false;
+    let blockCommentDepth = 0;
+    for (let index = 0; index < sql.length; index += 1) {
+        const character = sql[index];
+        const next = sql[index + 1];
+        if (lineComment) {
+            if (character === '\n' || character === '\r')
+                lineComment = false;
+            continue;
+        }
+        if (blockCommentDepth > 0) {
+            if (character === '/' && next === '*') {
+                blockCommentDepth += 1;
+                index += 1;
+            }
+            else if (character === '*' && next === '/') {
+                blockCommentDepth -= 1;
+                index += 1;
+            }
+            continue;
+        }
+        if (quote) {
+            if (quote === ']' && character === ']') {
+                if (next === ']')
+                    index += 1;
+                else
+                    quote = undefined;
+            }
+            else if (quote !== ']' && character === quote) {
+                if (next === quote)
+                    index += 1;
+                else
+                    quote = undefined;
+            }
+            continue;
+        }
+        if (character === '-' && next === '-') {
+            lineComment = true;
+            index += 1;
+            continue;
+        }
+        if (character === '/' && next === '*') {
+            blockCommentDepth = 1;
+            index += 1;
+            continue;
+        }
+        if (character === "'" || character === '"' || character === '`') {
+            quote = character;
+            continue;
+        }
+        if (character === '[') {
+            quote = ']';
+            continue;
+        }
+        if (character === '(') {
+            depth += 1;
+            continue;
+        }
+        if (character === ')') {
+            if (depth === 0)
+                return undefined;
+            depth -= 1;
+            continue;
+        }
+        if (depth !== 0 || !/[A-Za-z_]/.test(character))
+            continue;
+        const start = index;
+        index += 1;
+        while (index < sql.length && /[A-Za-z0-9_$]/.test(sql[index]))
+            index += 1;
+        tokens.push({ text: sql.slice(start, index).toLowerCase(), start, end: index });
+        index -= 1;
+    }
+    // A line comment is valid through EOF. Unterminated string, bracket, block
+    // comment, or parenthesis state is not a trustworthy exact-proof input.
+    return depth === 0 && !quote && blockCommentDepth === 0 ? tokens : undefined;
+}
+/**
+ * Split an authored comma-separated SQL list without treating a function
+ * argument, quoted string, or quoted identifier as a second ORDER BY key.
+ * This intentionally stays small and fails closed for malformed SQL; DQL's
+ * compiler is still the authority for execution syntax.
+ */
+function splitTopLevelSqlList(value) {
+    const expressions = [];
+    let start = 0;
+    let depth = 0;
+    let quote;
+    let lineComment = false;
+    let blockCommentDepth = 0;
+    for (let index = 0; index < value.length; index += 1) {
+        const character = value[index];
+        const next = value[index + 1];
+        if (lineComment) {
+            if (character === '\n' || character === '\r')
+                lineComment = false;
+            continue;
+        }
+        if (blockCommentDepth > 0) {
+            if (character === '/' && next === '*') {
+                blockCommentDepth += 1;
+                index += 1;
+            }
+            else if (character === '*' && next === '/') {
+                blockCommentDepth -= 1;
+                index += 1;
+            }
+            continue;
+        }
+        if (quote) {
+            if (quote === ']' && character === ']') {
+                if (next === ']')
+                    index += 1;
+                else
+                    quote = undefined;
+            }
+            else if (quote !== ']' && character === quote) {
+                // SQL escapes an in-string quote by doubling it. Keep scanning inside
+                // the quoted value rather than mistaking a later comma for a list
+                // separator.
+                if (value[index + 1] === quote) {
+                    index += 1;
+                }
+                else {
+                    quote = undefined;
+                }
+            }
+            continue;
+        }
+        if (character === '-' && next === '-') {
+            lineComment = true;
+            index += 1;
+            continue;
+        }
+        if (character === '/' && next === '*') {
+            blockCommentDepth = 1;
+            index += 1;
+            continue;
+        }
+        if (character === "'" || character === '"' || character === '`') {
+            quote = character;
+            continue;
+        }
+        if (character === '[') {
+            quote = ']';
+            continue;
+        }
+        if (character === '(') {
+            depth += 1;
+            continue;
+        }
+        if (character === ')' && depth > 0) {
+            depth -= 1;
+            continue;
+        }
+        if (character === ',' && depth === 0) {
+            const expression = value.slice(start, index).trim();
+            if (!expression)
+                return [];
+            expressions.push(expression);
+            start = index + 1;
+        }
+    }
+    if (quote || blockCommentDepth > 0 || depth !== 0)
+        return [];
+    const finalExpression = value.slice(start).trim();
+    return finalExpression ? [...expressions, finalExpression] : [];
+}
+function parseTopNOrderExpression(expression) {
+    const visible = topNVisibleSql(expression);
+    const match = visible.match(/^(.*?)(?:\s+(asc|desc))(?:\s+nulls\s+(?:first|last))?\s*$/i);
+    if (!match?.[1] || !match[2])
+        return undefined;
+    return {
+        expression: expression.slice(0, match[1].length).trim(),
+        direction: match[2].toLowerCase(),
+    };
+}
+/** Preserve SQL positions while blanking literals/comments that cannot prove a ranking contract. */
+function topNVisibleSql(value) {
+    let output = '';
+    let quote;
+    let lineComment = false;
+    let blockCommentDepth = 0;
+    for (let index = 0; index < value.length; index += 1) {
+        const character = value[index];
+        const next = value[index + 1];
+        const blank = () => { output += character === '\n' || character === '\r' ? character : ' '; };
+        if (lineComment) {
+            blank();
+            if (character === '\n' || character === '\r')
+                lineComment = false;
+            continue;
+        }
+        if (blockCommentDepth > 0) {
+            blank();
+            if (character === '/' && next === '*') {
+                blockCommentDepth += 1;
+                index += 1;
+                output += ' ';
+            }
+            else if (character === '*' && next === '/') {
+                blockCommentDepth -= 1;
+                index += 1;
+                output += ' ';
+            }
+            continue;
+        }
+        if (quote === "'") {
+            blank();
+            if (character === "'") {
+                if (next === "'") {
+                    index += 1;
+                    output += ' ';
+                }
+                else {
+                    quote = undefined;
+                }
+            }
+            continue;
+        }
+        if (quote) {
+            // Keep quoted identifiers intact for identifier normalization while the
+            // outer-clause scanner itself ignores their contents.
+            output += character;
+            if (quote === ']' && character === ']') {
+                if (next === ']') {
+                    index += 1;
+                    output += next;
+                }
+                else {
+                    quote = undefined;
+                }
+            }
+            else if (quote !== ']' && character === quote) {
+                if (next === quote) {
+                    index += 1;
+                    output += next;
+                }
+                else {
+                    quote = undefined;
+                }
+            }
+            continue;
+        }
+        if (character === '-' && next === '-') {
+            output += '  ';
+            index += 1;
+            lineComment = true;
+            continue;
+        }
+        if (character === '/' && next === '*') {
+            output += '  ';
+            index += 1;
+            blockCommentDepth = 1;
+            continue;
+        }
+        if (character === "'") {
+            output += ' ';
+            quote = character;
+            continue;
+        }
+        if (character === '"' || character === '`') {
+            output += character;
+            quote = character;
+            continue;
+        }
+        if (character === '[') {
+            output += character;
+            quote = ']';
+            continue;
+        }
+        output += character;
+    }
+    return output;
+}
+/** Normalize an identifier or business measure into its opaque-free SQL key. */
+function normalizedTopNMetricId(value) {
+    return value
+        .trim()
+        .replace(/^['"`\[]|['"`\]]$/g, '')
+        .split('.')
+        .at(-1)
+        .trim()
+        .replace(/^['"`\[]|['"`\]]$/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '');
+}
+/**
+ * Resolve the primary ORDER BY expression through selected-output aliases and
+ * captured output lineage.  Qualified columns (`c.revenue`), SQL aliases
+ * (`SUM(o.revenue) AS revenue` / `ORDER BY revenue`), and compiler-captured
+ * output sources all converge on the same normalized key.  Unknown or
+ * ambiguous expressions deliberately yield no proof.
+ */
+function topNOrderMetricIds(expression, block) {
+    const keys = topNIdentifierIds(expression);
+    const selectedAliases = selectedSqlOutputAliases(block.sql);
+    const outputLineage = block.outputs ?? [];
+    for (const key of [...keys]) {
+        const selectedExpression = selectedAliases.get(key);
+        if (selectedExpression) {
+            for (const selectedKey of topNIdentifierIds(selectedExpression))
+                keys.add(selectedKey);
+        }
+        for (const output of outputLineage) {
+            if (normalizedTopNMetricId(output.name) !== key)
+                continue;
+            for (const source of output.sources ?? []) {
+                const sourceKey = normalizedTopNMetricId(source.column);
+                if (sourceKey)
+                    keys.add(sourceKey);
+            }
+        }
+    }
+    return keys;
+}
+function topNIdentifierIds(expression) {
+    const keys = new Set();
+    // Quoted identifiers remain intact, while literals/comments were blanked.
+    // Therefore a string such as `'revenue'` cannot prove a ranking measure.
+    const identifierPattern = /(?:\[[^\]]+\]|"(?:""|[^"])+"|`(?:``|[^`])+`|[A-Za-z_][A-Za-z0-9_$]*)/g;
+    for (const identifier of topNVisibleSql(expression).match(identifierPattern) ?? []) {
+        const key = normalizedTopNMetricId(identifier);
+        if (key && !TOP_N_SQL_WORDS.has(key))
+            keys.add(key);
+    }
+    return keys;
+}
+function selectedSqlOutputAliases(sql) {
+    if (!sql)
+        return new Map();
+    const select = scanOutermostTopNClauses(sql)?.selectList;
+    if (!select)
+        return new Map();
+    const aliases = new Map();
+    for (const projection of splitTopLevelSqlList(select)) {
+        const visibleProjection = topNVisibleSql(projection);
+        const explicitAlias = visibleProjection.match(/^(.*?)\s+as\s+((?:\[[^\]]+\])|(?:"(?:""|[^"])+")|(?:`(?:``|[^`])+`)|(?:[A-Za-z_][A-Za-z0-9_$]*))\s*$/i);
+        const implicitAlias = explicitAlias
+            ? undefined
+            : visibleProjection.match(/^(.*?)\s+((?:\[[^\]]+\])|(?:"(?:""|[^"])+")|(?:`(?:``|[^`])+`)|(?:[A-Za-z_][A-Za-z0-9_$]*))\s*$/i);
+        const expressionLength = (explicitAlias?.[1] ?? implicitAlias?.[1] ?? visibleProjection).length;
+        const expression = projection.slice(0, expressionLength).trim();
+        const alias = (explicitAlias?.[2] ?? implicitAlias?.[2] ?? projection).trim();
+        const aliasId = normalizedTopNMetricId(alias);
+        if (aliasId)
+            aliases.set(aliasId, expression);
+    }
+    return aliases;
+}
+const TOP_N_SQL_WORDS = new Set([
+    'asc', 'desc', 'nulls', 'first', 'last', 'sum', 'avg', 'average', 'count',
+    'min', 'max', 'cast', 'coalesce', 'case', 'when', 'then', 'else', 'end',
+]);
 /**
  * Return only output aliases that the selected certified artifact itself
  * declares.  This is deliberately built after the router has frozen the plan:
@@ -625,6 +1191,41 @@ export function renderContextValidationRefusalForUser(code, machineError, member
                 : 'I could not prepare a governed query from the retrieved metadata. Name the specific metric or table and how to break it down, and I can generate a review-required draft.';
     }
 }
+/**
+ * Did validation fail because something the USER asked for is not modeled?
+ *
+ * "What region does he belong to" against a warehouse with no customer→region
+ * path fails as `unknown_column: region`. Reported as a grounding gap that
+ * reads "Not enough context to answer safely", which is untrue and unhelpful:
+ * no amount of extra context will produce a column the business has never
+ * modeled, and the user is left to guess whether to rephrase, re-ask, or give
+ * up. The truthful answer names the gap and offers the way forward.
+ *
+ * Deliberately narrow. A column the MODEL invented is a grounding failure and
+ * must keep its existing code — the distinction between "you asked for
+ * something we don't have" and "the draft referenced something that isn't
+ * there" is the whole safety value of this classification.
+ */
+function requestedDimensionModelingGap(code, offending, requestedTerms) {
+    if (code !== 'unknown_column' && code !== 'unknown_relation')
+        return undefined;
+    const identifier = offending?.column ?? offending?.relation;
+    if (!identifier)
+        return undefined;
+    const canonical = (value) => value
+        .split(/[.:]/).pop()
+        .toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+    const target = canonical(identifier);
+    if (!target)
+        return undefined;
+    const requested = requestedTerms
+        .map(canonical)
+        .filter((term) => term.length > 2);
+    const matched = requested.find((term) => term === target
+        || target.split(' ').includes(term)
+        || term.split(' ').includes(target));
+    return matched ? identifier.split(/[.:]/).pop() : undefined;
+}
 function refusalCodeForValidation(code) {
     if (code === 'unknown_relation' || code === 'unknown_column' || code === 'insufficient_context' || code === 'missing_baseline') {
         return 'grounding_gap';
@@ -1024,7 +1625,9 @@ export async function answer(input) {
     // Cross-result computations are intentionally independent of the KG and
     // warehouse. Preserve this earliest exit before building any execution
     // registry so lightweight follow-up callers do not need runtime services.
-    const earlyCrossResult = tryCrossResultAnswer(normalizedInput);
+    const earlyCrossResult = normalizedInput.skipCrossResultComputation
+        ? null
+        : tryCrossResultAnswer(normalizedInput);
     if (earlyCrossResult) {
         return {
             ...earlyCrossResult,
@@ -1161,9 +1764,17 @@ export async function answer(input) {
     const analyticalExecutionGraph = analyticalGraphBuild?.status === 'ready'
         ? analyticalGraphBuild.graph
         : undefined;
+    // A v2 plan can also be synthesized for legacy/direct AnswerLoop callers so
+    // they can opt into the deterministic compiler. That compatibility bridge is
+    // not a router freeze: it must not turn a missing optional graph/adapter into
+    // a terminal answer before the established, safe legacy semantic execution
+    // path is considered. Router-selected semantic plans carry the explicit
+    // `selectedCascadeTier` signal and remain immutable/terminal below.
+    const routerFrozenSemanticPlan = Boolean(frozenSemanticRouteForInput(normalizedInput));
     const analyticalExecutionGraphFailure = normalizedInput.resolvedAnalyticalPlan?.schemaVersion === 2
         && !multiMetricPlan
         && !generatedProposalPlan
+        && routerFrozenSemanticPlan
         ? analyticalGraphBuild?.status === 'blocked'
             ? {
                 code: analyticalGraphBuild.code,
@@ -1248,7 +1859,23 @@ export async function answer(input) {
         }
         : compiledInput;
     const loopResult = await runAnswerLoop(executionInput);
-    const result = applyHollowAnswerGate(validateCertifiedAnalyticalGraphAnswer(loopResult, executionInput.analyticalExecutionGraph, executionInput.resolvedAnalyticalPlan?.analyticalFrame));
+    let result = applyHollowAnswerGate(validateCertifiedAnalyticalGraphAnswer(loopResult, executionInput.analyticalExecutionGraph, executionInput.resolvedAnalyticalPlan?.analyticalFrame));
+    const frozenSemanticRoute = frozenSemanticRouteForInput(executionInput);
+    // A final defensive boundary keeps future return sites from accidentally
+    // restoring the old semantic -> generated fallthrough. Do not relabel an
+    // actual generated result as semantic: replace it with an inspectable,
+    // same-tier terminal failure instead.
+    const returnedNonSemanticRoute = frozenSemanticRoute && ((result.route !== undefined && result.route.tier !== 'semantic_metric')
+        || (result.route === undefined && result.kind !== 'no_answer' && result.sourceTier !== 'semantic_layer'));
+    if (returnedNonSemanticRoute && frozenSemanticRoute) {
+        result = frozenSemanticPlanFailureAnswer({
+            answerInput: executionInput,
+            considered: result.considered ?? [],
+            providerName: executionInput.provider.name,
+            code: 'EXECUTION_GRAPH_MISMATCH',
+            reason: `The pinned semantic plan ${frozenSemanticRoute.ref ?? 'selected by the router'} returned a non-semantic answer route. DQL did not substitute generated SQL.`,
+        });
+    }
     // Attach the canonical trust label once, at the single exit point, so every
     // return site inside runAnswerLoop stays untouched and backward compatible.
     // Freshness-aware trust: for a certified answer, fold the source block's data
@@ -1256,7 +1883,7 @@ export async function answer(input) {
     // stale data" / "Certified · upstream failed". Non-certified or fresh answers
     // are unaffected.
     const { _semanticMetricMatch, ...publicResult } = result;
-    const chosenRoute = result.route ?? deriveAiRoute(result, _semanticMetricMatch);
+    const chosenRoute = frozenSemanticRoute ?? result.route ?? deriveAiRoute(result, _semanticMetricMatch);
     // P0 — record the high-level action this turn warranted, so callers can route
     // (compose_app → app build, investigate → research) and the UI can show the
     // agent's reasoning. Computed once at the single exit from the finished answer.
@@ -1390,6 +2017,69 @@ function deriveAiRoute(result, metricMatch) {
         ? { tier: 'generated_sql', label: 'Prepared review-required DQL artifact with SQL preview.' }
         : { tier: 'generated_sql', label: 'Prepared review-required SQL preview.' };
 }
+/**
+ * The router owns the cascade decision.  Once it freezes a semantic plan, the
+ * answer loop may either execute that exact plan or return a semantic-tier
+ * terminal failure.  It must never let an unavailable semantic adapter fall
+ * through to the legacy generated-SQL lane merely because the latter can still
+ * construct a preview.
+ */
+function frozenSemanticRouteForInput(input) {
+    const plan = input.resolvedAnalyticalPlan;
+    // `freezeLegacySemanticSelection()` upgrades older direct AnswerLoop callers
+    // to a typed plan so they can use the deterministic semantic compiler. That
+    // migration is not the router's immutable cascade freeze. The server-owned
+    // cascade explicitly carries `selectedCascadeTier: 'semantic'`; only that
+    // signal activates the no-downgrade boundary below. Otherwise direct legacy
+    // callers retain their established deterministic semantic behavior.
+    if (input.selectedCascadeTier !== 'semantic'
+        || plan?.mode !== 'authoritative'
+        || plan.capability !== 'semantic_execution')
+        return undefined;
+    const executionId = plan.executionId ?? plan.selectedConceptIds[0];
+    return {
+        tier: 'semantic_metric',
+        label: executionId
+            ? `Frozen semantic plan ${executionId}`
+            : 'Frozen semantic plan',
+        ...(executionId ? { ref: executionId } : {}),
+    };
+}
+function frozenSemanticPlanFailureAnswer(input) {
+    const { answerInput, considered, providerName, code, reason } = input;
+    const route = frozenSemanticRouteForInput(answerInput);
+    // Callers use this only for an authoritative semantic plan. Keep the
+    // fallback defensive so an internal misuse still produces a safe no-answer.
+    const analyticalFailure = analyticalFailureForInput(answerInput, {
+        error: { code, message: reason },
+        phase: 'compilation',
+        failedBindings: answerInput.resolvedAnalyticalPlan?.executionId
+            ? [{
+                    qualifiedId: answerInput.resolvedAnalyticalPlan.executionId,
+                    role: 'metric',
+                    reasonCode: code,
+                }]
+            : undefined,
+    });
+    return {
+        kind: 'no_answer',
+        sourceTier: 'no_answer',
+        certification: 'analyst_review_required',
+        reviewStatus: 'none',
+        confidence: 0,
+        text: analyticalFailure.message,
+        answer: analyticalFailure.message,
+        executionError: analyticalFailure.message,
+        refusalCode: 'grounding_gap',
+        refusalDetails: { code, message: analyticalFailure.message },
+        analyticalFailure,
+        ...(route ? { route } : {}),
+        citations: contextPackCitations(answerInput.contextPack, 8),
+        considered,
+        contextPack: answerInput.contextPack,
+        providerUsed: providerName,
+    };
+}
 /** "customers_customer_name" → "customers" for a question the user has to read. */
 function humanizeDeicticDimension(dimension) {
     const leaf = dimension.split(/[.:]/).pop() ?? dimension;
@@ -1419,6 +2109,7 @@ async function runAnswerLoop(input) {
     // or provider is dispatched.  Full retrieval stays on `input.contextPack`
     // for receipts and diagnostics only.
     const forcedExploratoryTier = input.selectedCascadeTier === 'exploratory_sql';
+    const frozenSemanticRoute = frozenSemanticRouteForInput(input);
     const exploratoryClosureContextPack = forcedExploratoryTier
         ? scopeContextPackToExploratoryCandidateClosure(scopedContextPack, input.exploratoryCandidateIds)
         : undefined;
@@ -1510,6 +2201,31 @@ async function runAnswerLoop(input) {
     const authoritativePlanBinding = !forcedExploratoryTier && input.resolvedAnalyticalPlan?.mode === 'authoritative'
         ? input.resolvedPlanExecutionBinding
         : undefined;
+    // `freezeLegacySemanticSelection()` attaches an authoritative-shaped v2
+    // plan for direct AnswerLoop compatibility. It is not the router-owned
+    // semantic cascade decision. Only an explicit selected semantic tier may
+    // make an adapter/graph miss terminal; direct callers retain the established
+    // deterministic metric path, which still applies the ordinary SQL safety
+    // validation before it can execute.
+    const legacyDirectSemanticPlan = input.selectedCascadeTier === undefined
+        && input.resolvedAnalyticalPlan?.mode === 'authoritative'
+        && input.resolvedAnalyticalPlan.recommendedRoute === 'semantic'
+        && !frozenSemanticRoute;
+    // A semantic freeze is an immutable execution authority, not a hint for the
+    // legacy loop.  In particular, projects that have indexed semantic metadata
+    // but have not configured the corresponding local semantic adapter used to
+    // continue into generated SQL.  Stop here with the selected plan's typed
+    // diagnostic instead; no provider, tool, or SQL work is allowed to replace
+    // it after freeze.
+    if (!forcedExploratoryTier && frozenSemanticRoute && !input.semanticLayer) {
+        return frozenSemanticPlanFailureAnswer({
+            answerInput: input,
+            considered,
+            providerName: provider.name,
+            code: 'SEMANTIC_LAYER_REQUIRED',
+            reason: `The pinned semantic adapter for ${frozenSemanticRoute.ref ?? 'the selected semantic plan'} is unavailable.`,
+        });
+    }
     if (!forcedExploratoryTier && input.analyticalPeriodResolutionFailure) {
         const failure = input.analyticalPeriodResolutionFailure;
         const structuredFailureCode = failure.error && typeof failure.error === 'object'
@@ -1601,7 +2317,11 @@ async function runAnswerLoop(input) {
             input,
             binding: input.semanticGraphExecutionBinding,
             graph: input.analyticalExecutionGraph,
-            capability: normalizeMetricCapabilityContract(input.semanticGraphExecutionBinding.metricNode.payload?.analyticalCapability),
+            // The execution registry identifies the adapter metric, but its compact
+            // node payload may omit the relationship-path metadata that was frozen
+            // on the RAP. Re-deriving aggregation proof from that projection makes
+            // an already accepted native MetricFlow grouping fail post-freeze.
+            capability: input.semanticGraphExecutionBinding.capability,
             considered,
             providerName: provider.name,
         });
@@ -1716,7 +2436,7 @@ async function runAnswerLoop(input) {
             providerUsed: provider.name,
         };
     }
-    if (authoritativePlanBinding?.status === 'blocked') {
+    if (authoritativePlanBinding?.status === 'blocked' && !legacyDirectSemanticPlan) {
         // An ambiguous singular reference is answerable the moment the user says
         // which one they meant, so offer the candidates rather than dead-ending.
         // The old refusal shipped the binder's internal sentence as the answer
@@ -1792,7 +2512,7 @@ async function runAnswerLoop(input) {
         ? authoritativePlanBinding
         : undefined;
     const preferredSemanticMetric = authoritativeSemanticBinding?.metricNode
-        ?? (input.resolvedAnalyticalPlan?.mode === 'authoritative'
+        ?? (input.resolvedAnalyticalPlan?.mode === 'authoritative' && !legacyDirectSemanticPlan
             ? undefined
             : resolvePreferredSemanticMetric([input.preferredExecutionId, ...(input.preferredEvidenceIds ?? [])], semanticMetricNodes, kg));
     const semanticLayerForExec = input.semanticLayer;
@@ -1802,7 +2522,7 @@ async function runAnswerLoop(input) {
         ? null
         : preferredSemanticMetric
             ? { metric: preferredSemanticMetric, score: 1, basis: 'name' }
-            : input.resolvedAnalyticalPlan?.mode === 'authoritative'
+            : input.resolvedAnalyticalPlan?.mode === 'authoritative' && !legacyDirectSemanticPlan
                 ? null
                 : await matchSemanticMetric(semanticQuestion, semanticMetricNodes, {
                     measureTerms: [...questionPlan.requestedShape.measures, ...questionPlan.metricTerms],
@@ -1981,18 +2701,14 @@ async function runAnswerLoop(input) {
     if (artifactHit && businessContextTerminal) {
         let result;
         let executionError;
+        let executionFailureDetail;
         if (artifactHit.node.kind === 'block' && input.executeCertifiedBlock) {
             try {
-                result = await input.executeCertifiedBlock(artifactHit.node, {
-                    question,
-                    ...certifiedInvocationInputs(artifactHit.node, questionPlan),
-                    rowLimit: questionPlan.requestedShape.topN?.scope === 'per_group'
-                        ? undefined
-                        : questionPlan.requestedShape.topN?.n,
-                });
-                result = trimResultToRequestedTopN(result, questionPlan);
+                result = await input.executeCertifiedBlock(artifactHit.node, buildCertifiedBlockInvocationInput(artifactHit.node, questionPlan, question));
+                result = trimCertifiedBlockResultToRequestedTopN(result, questionPlan);
             }
             catch (err) {
+                executionFailureDetail = analyticalErrorDetail(err);
                 executionError = err instanceof Error ? err.message : String(err);
             }
         }
@@ -2098,6 +2814,9 @@ async function runAnswerLoop(input) {
             ? undefined
             : questionPlan.requestedShape.topN?.n);
         const authoritativeCertifiedFailure = Boolean(authoritativeCertifiedBinding && executionError);
+        const observabilityExecutionFailure = authoritativeCertifiedFailure
+            ? observabilityFailureForFrozenExecution(executionFailureDetail)
+            : undefined;
         // A selected certified block which returns an incomplete tuple is a
         // same-tier terminal failure. It is not a reason to reinterpret meaning,
         // label the partial rows generated, or retry another route after freeze.
@@ -2143,6 +2862,7 @@ async function runAnswerLoop(input) {
                 block: artifactHit.node.kind === 'block' ? artifactHit.node : undefined,
                 result,
                 executionError,
+                ...(observabilityExecutionFailure ? { observabilityExecutionFailure } : {}),
                 ...(authoritativeCertifiedFailure || authoritativeCertifiedShapeFailure
                     ? { refusalCode: 'grounding_gap' }
                     : {}),
@@ -2637,8 +3357,21 @@ async function runAnswerLoop(input) {
             contextPack: input.contextPack,
             considered,
             providerUsed: provider.name,
+            ...(frozenSemanticRoute ? { route: frozenSemanticRoute } : {}),
         };
     }
+    // The semantic branch above has exhausted the exact plan's compiler and
+    // adapter choices.  Do not let `metricFirst` or the ordinary generated
+    // proposal branch reinterpret the question after a semantic freeze.
+    if (frozenSemanticRoute && !semanticBridgeAnswer) {
+        return frozenSemanticPlanFailureAnswer({
+            answerInput: input,
+            considered,
+            providerName: provider.name,
+            code: 'COMPILATION_FAILED',
+            reason: `The pinned semantic adapter could not compose ${frozenSemanticRoute.ref ?? 'the selected semantic plan'} without changing the frozen plan.`,
+        });
+    }
     const metricFirst = semanticMetricMatch
         ? buildGovernedMetricFirstSql({
             metric: semanticMetricMatch.metric,
@@ -2841,9 +3574,15 @@ async function runAnswerLoop(input) {
                 confidence: 0,
                 text,
                 answer: text,
-                refusalCode: 'provider_error',
+                // DQL stopping itself is not the provider failing. Reporting both as
+                // `provider_error` put "The AI provider did not respond" above a body
+                // that said the opposite, and sent the reader to check provider health
+                // for a run that ended on an internal ceiling.
+                refusalCode: admissionDeclined || orchestrationBudget ? 'orchestration_budget_exhausted' : 'provider_error',
                 refusalDetails: {
-                    code: orchestrationBudget ? 'orchestration_budget_exhausted' : 'provider_error',
+                    code: admissionDeclined
+                        ? 'RUN_DEADLINE_INSUFFICIENT'
+                        : orchestrationBudget ? 'orchestration_budget_exhausted' : 'provider_error',
                     message: orchestrationBudget ? `${text} (${err.message})` : text,
                 },
                 citations: [],
@@ -2970,14 +3709,36 @@ async function runAnswerLoop(input) {
         || (input.contextPack?.allowedSqlContext?.relations.length ?? 0) > 0
         || (input.contextPack?.allowedSqlContext?.sourceBlockSql.length ?? 0) > 0
         || contextBlocks.length > 0;
+    // A selected bounded-exploration RAP is stronger than the advisory legacy
+    // analytical-path diagnosis.  The latter may still call raw output terms a
+    // semantic "missing dimension" even after the router has proven one safe
+    // physical relation and frozen the exploratory tuple.  Do not let that
+    // advisory pre-freeze diagnosis suppress the one explicitly authorized
+    // same-plan model-decline repair; the host re-validates the exact proposal
+    // against the frozen closure before it can execute.
+    const frozenExploratoryRepair = frozenExploratoryModelRepairAuthority(input);
     if (!parsed.sql && !governedMetricAnswer && wantsGeneratedData && hasGeneratableContext
-        && (analyticalPlan?.safe !== false || analyticalPlanAllowsDbtExploration(analyticalPlan))) {
+        && (frozenExploratoryRepair
+            || analyticalPlan?.safe !== false
+            || analyticalPlanAllowsDbtExploration(analyticalPlan))) {
         try {
             proposed = await generateProposalWithOptionalTools({
                 provider,
-                messages: [...messages, { role: 'system', content: FORCE_JOIN_INSTRUCTION }],
-                // One tool round per ordinary Ask. The second generation is a bounded
-                // composition correction over already-retrieved evidence.
+                messages: [...messages, {
+                        role: 'system',
+                        content: [
+                            FORCE_JOIN_INSTRUCTION,
+                            ...(frozenExploratoryRepair
+                                ? [renderFrozenExploratoryRepairContract(input.resolvedAnalyticalPlan, questionPlan)]
+                                : []),
+                        ].join('\n\n'),
+                    }],
+                // A router-frozen exploratory plan may consume exactly one additional
+                // provider transport to correct a model decline.  The host carries the
+                // immutable plan and output tuple into this retry; it is neither a
+                // replan nor a route change.  Legacy direct callers retain their
+                // historical composition correction, but do not receive the typed
+                // repair authority below.
                 tools: [],
                 questionPlan,
                 intent,
@@ -2986,6 +3747,13 @@ async function runAnswerLoop(input) {
                 analysisDepth: input.analysisDepth,
                 toolCalls: proposalToolCalls,
                 providerPayloadGuard: input.providerPayloadGuard,
+                ...(frozenExploratoryRepair
+                    ? {
+                        dispatchPhase: 'repair',
+                        egressPurpose: 'repair_sql',
+                        maxProviderDispatches: 1,
+                    }
+                    : {}),
             });
             parsed = parseProposal(proposed);
         }
@@ -3060,6 +3828,49 @@ async function runAnswerLoop(input) {
     }
     if (parsed.sql) {
         const frozenPlan = input.resolvedAnalyticalPlan;
+        // The result contract is host-owned even in tests or embedded callers
+        // that provide their own execution adapter.  Stop before capability
+        // preparation when a generated alias is backed by a different physical
+        // column than the frozen plan (for example `product_id AS order_id`).
+        // The local runtime repeats this check while minting the capability and
+        // persists the matching proof on its receipt.
+        if (input.selectedCascadeTier === 'exploratory_sql' && frozenPlan) {
+            const requiredOutputValidation = validateFrozenRequiredOutputProjection({
+                plan: frozenPlan,
+                sql: parsed.sql,
+                ...(input.semanticDriver ? { dialect: input.semanticDriver } : {}),
+            });
+            if (!requiredOutputValidation.ok) {
+                const failedOutputs = [...new Set([
+                        ...requiredOutputValidation.missingOutputs,
+                        ...requiredOutputValidation.bindingMismatches,
+                    ])];
+                const message = `The generated exploratory query did not prove the frozen source binding for required output ${failedOutputs.join(', ')}, so DQL did not execute it.`;
+                return {
+                    kind: 'no_answer',
+                    sourceTier: 'no_answer',
+                    certification: 'analyst_review_required',
+                    reviewStatus: 'none',
+                    confidence: 0,
+                    text: message,
+                    answer: message,
+                    refusalCode: 'policy_blocked',
+                    refusalDetails: {
+                        code: 'OUTPUT_BINDING_TUPLE_DRIFT',
+                        message,
+                    },
+                    validationWarnings: [
+                        'OUTPUT_BINDING_TUPLE_DRIFT',
+                        ...failedOutputs.map((output) => `Frozen output binding not proven: ${output}`),
+                    ],
+                    citations: contextPackCitations(input.contextPack, 8),
+                    memoryContext: input.memoryContext,
+                    contextPack: input.contextPack,
+                    considered,
+                    providerUsed: provider.name,
+                };
+            }
+        }
         if (!governedMetricAnswer && frozenPlan?.mode === 'authoritative' && frozenPlan.schemaVersion === 2) {
             const targetFingerprint = input.generatedProposalTargetFingerprint ?? '';
             const validation = validateGeneratedAnalyticalProposal({
@@ -3499,7 +4310,13 @@ async function runAnswerLoop(input) {
         // Business-language chat text; the validator's machine message (with
         // relation ids and tool guidance for the repair prompt) stays in
         // refusalDetails + validationWarnings for the Inspect surface.
-        const text = renderContextValidationRefusalForUser(contextValidation.code, contextValidation.error, input.followUp?.memberBindings, contextValidation.aggregationSafetyProof?.issueCodes);
+        // A dimension the user explicitly asked for that the business has not
+        // modeled is a modeling gap, not a retrieval gap. Say so, and say what
+        // would let the question be answered.
+        const unmodeledRequestedDimension = requestedDimensionModelingGap(contextValidation.code, contextValidation.offending, [...questionPlan.dimensionTerms, ...(input.followUp?.dimensions ?? [])]);
+        const text = unmodeledRequestedDimension
+            ? `"${unmodeledRequestedDimension}" is not modeled. Which governed dimension should I use instead?`
+            : renderContextValidationRefusalForUser(contextValidation.code, contextValidation.error, input.followUp?.memberBindings, contextValidation.aggregationSafetyProof?.issueCodes);
         const analysisPlan = buildAnalysisPlan({
             question,
             intent,
@@ -3521,7 +4338,9 @@ async function runAnswerLoop(input) {
             reviewStatus: 'none',
             confidence: 0.15,
             text,
-            refusalCode: refusalCodeForValidation(contextValidation.code),
+            refusalCode: unmodeledRequestedDimension
+                ? 'modeling_gap'
+                : refusalCodeForValidation(contextValidation.code),
             refusalDetails: {
                 code: contextValidation.code ?? 'insufficient_context',
                 message: contextValidation.error,
@@ -3664,12 +4483,14 @@ async function runAnswerLoop(input) {
     let executionError;
     let warehouseFailure;
     let exploratoryClosureDenied = false;
+    let semanticFanoutProbeFailure;
     let repairAttempts = 0;
     // A forced proposal may originate from the bounded analyst loop, but it
     // cannot bypass a router-owned exploratory decision.  In that case the host
     // still prepares and freezes the exact validated SQL before execution.
     const exploratoryExecutionSelected = input.selectedCascadeTier === 'exploratory_sql';
-    let preparedExploratoryExecution;
+    let initialExploratoryExecution;
+    let exploratoryRepairExecution;
     // Repair candidates that were generated but rejected before execution. These
     // are diagnostics ABOUT the recovery attempt, not the reason the run failed,
     // so they are reported alongside the original error rather than replacing it.
@@ -3684,7 +4505,7 @@ async function runAnswerLoop(input) {
         executionError = deepCandidateExecutionError;
         warehouseFailure = normalizeWarehouseSqlFailure(deepCandidateExecutionError, input.semanticDriver);
     }
-    const executeCurrentSql = async () => {
+    const executeCurrentSql = async (authorizationAttempt) => {
         const requestedLimit = questionPlan.requestedShape.topN?.scope === 'per_group'
             ? 200
             : questionPlan.requestedShape.topN?.n ?? 200;
@@ -3725,17 +4546,23 @@ async function runAnswerLoop(input) {
                 });
             }
             // This is the only point at which a router-selected exploratory proposal
-            // crosses from validated text into executable authority. The callback
-            // rechecks the snapshot, physical target, and qualified runtime columns,
-            // then returns a one-shot capability bound to these exact SQL bytes.
-            preparedExploratoryExecution ??= await input.prepareExploratorySqlExecution(parsed.sql, boundedArtifact);
-            return input.executeAgenticGeneratedSql(preparedExploratoryExecution.capability, parsed.sql, boundedArtifact);
+            // crosses from validated text into executable authority. The first call
+            // receives the original one-shot capability. A retryable warehouse
+            // failure may mint exactly one *new* repair capability, explicitly bound
+            // to the first SQL fingerprint; it never reopens meaning or routing.
+            const prepared = authorizationAttempt
+                ? await input.prepareExploratorySqlExecution(parsed.sql, boundedArtifact, authorizationAttempt)
+                : (initialExploratoryExecution ??= await input.prepareExploratorySqlExecution(parsed.sql, boundedArtifact));
+            if (authorizationAttempt)
+                exploratoryRepairExecution = prepared;
+            return input.executeAgenticGeneratedSql(prepared.capability, parsed.sql, boundedArtifact);
         }
         if (!input.executeGeneratedSql)
             throw new Error('No generated SQL executor is configured.');
         return input.executeGeneratedSql(parsed.sql, boundedArtifact);
     };
     if ((input.executeGeneratedSql
+        || input.executeDqlArtifact
         || (input.forcedGeneratedProposal && input.executeAgenticGeneratedSql)
         || exploratoryExecutionSelected) && !result) {
         // Fanout gate for native semantic direct-joins: a duplicate join-key row on
@@ -3744,17 +4571,31 @@ async function runAnswerLoop(input) {
         // answers). Probe first; on structural contradiction, refuse with the cause
         // instead of presenting wrong numbers — and never hand the error to SQL
         // repair, which would regenerate the same multiplying join.
-        let fanoutContradiction = false;
+        let semanticFanoutBlocked = false;
         if (!executionError
             && !input.forcedGeneratedProposal
             && !exploratoryExecutionSelected
-            && input.executeGeneratedSql
             && semanticBridgeAnswer?.composeResult?.fanoutProbeSql
             && semanticBridgeAnswer.sql.trim() === parsed.sql?.trim()) {
-            const inflationError = await probeSemanticJoinFanout(semanticBridgeAnswer.composeResult.fanoutProbeSql, semanticBridgeAnswer.composeResult.tables, input.executeGeneratedSql);
-            if (inflationError) {
-                executionError = inflationError;
-                fanoutContradiction = true;
+            // A DQL-artifact executor owns the semantic artifact, not an arbitrary
+            // one-row structural SQL probe. If the host did not also provide the
+            // read-only SQL executor needed for that probe, native direct joins fail
+            // closed rather than treating an artifact handoff as proof of uniqueness.
+            const fanoutProbe = input.executeGeneratedSql
+                ? await probeSemanticJoinFanout(semanticBridgeAnswer.composeResult.fanoutProbeSql, semanticBridgeAnswer.composeResult.tables, input.executeGeneratedSql)
+                : {
+                    status: 'blocked',
+                    code: 'SEMANTIC_FANOUT_PROBE_ERROR',
+                    message: 'DQL did not execute this governed semantic answer because the host could not verify native join fanout before aggregation. Configure the semantic runtime or a read-only SQL probe executor, then retry.',
+                };
+            if (fanoutProbe.status === 'blocked') {
+                // A governed semantic route freezes before execution. If DQL cannot
+                // prove its native join is fanout-safe, it must fail closed rather than
+                // execute, label the result governed, or quietly repair into a
+                // different plan.
+                executionError = fanoutProbe.message;
+                semanticFanoutProbeFailure = fanoutProbe;
+                semanticFanoutBlocked = true;
             }
         }
         try {
@@ -3776,9 +4617,15 @@ async function runAnswerLoop(input) {
             executionError = warehouseFailure.redactedMessage;
         }
         if (executionError
-            && !input.forcedGeneratedProposal
-            && !exploratoryExecutionSelected
-            && !fanoutContradiction
+            // A host-supplied SQL proposal normally bypasses repair. A router-owned
+            // exploratory proposal is the exception: its frozen plan may authorize
+            // one corrected SQL statement after a retryable warehouse failure.
+            && (!input.forcedGeneratedProposal || exploratoryExecutionSelected)
+            // A router-selected exploratory plan may receive one bounded
+            // same-plan repair. The repair still goes through a fresh host
+            // authorization; it does not reuse the consumed initial capability.
+            && (!exploratoryExecutionSelected || Boolean(initialExploratoryExecution))
+            && !semanticFanoutBlocked
             && !authoritativeSemanticBinding) {
             warehouseFailure ??= normalizeWarehouseSqlFailure(executionError, input.semanticDriver);
             if (isRetryableGeneratedSqlError(warehouseFailure)) {
@@ -3804,7 +4651,13 @@ async function runAnswerLoop(input) {
                             ],
                         };
                         try {
-                            result = await executeCurrentSql();
+                            result = await executeCurrentSql(exploratoryExecutionSelected
+                                ? {
+                                    version: 1,
+                                    index: 1,
+                                    parentSqlFingerprint: initialExploratoryExecution.freeze.sqlFingerprint,
+                                }
+                                : undefined);
                             executionError = undefined;
                             warehouseFailure = undefined;
                         }
@@ -3836,6 +4689,18 @@ async function runAnswerLoop(input) {
                         schemaContext,
                         signal: input.signal,
                         reasoningEffort: input.reasoningEffort,
+                        // Only the router-frozen exploratory lane has authority to spend
+                        // the exceptional post-warehouse repair transport. Legacy callers
+                        // keep their prior unlabelled repair behavior.
+                        ...(exploratoryExecutionSelected
+                            && Boolean(initialExploratoryExecution)
+                            && frozenExploratoryModelRepairAuthority(input)
+                            ? {
+                                dispatchPhase: 'repair',
+                                egressPurpose: 'repair_sql',
+                                maxProviderDispatches: 1,
+                            }
+                            : {}),
                     });
                     const repaired = parseProposal(repairedRaw);
                     if (repaired.sql) {
@@ -3854,7 +4719,12 @@ async function runAnswerLoop(input) {
                             repairNarrative = repaired.text?.trim() || undefined;
                             parsed.sql = repaired.sql;
                             parsed.viz = repaired.viz ?? parsed.viz;
-                            applyParsedProposalMetadata(parsed, repaired);
+                            // A repair fixes SQL bytes only. On the router-owned
+                            // exploratory lane, model prose or metadata must never mutate
+                            // the host-selected frame, route, outputs, or trust state after
+                            // the plan froze.
+                            if (!exploratoryExecutionSelected)
+                                applyParsedProposalMetadata(parsed, repaired);
                             contextValidation = {
                                 ok: true,
                                 warnings: [
@@ -3863,7 +4733,13 @@ async function runAnswerLoop(input) {
                                 ],
                             };
                             try {
-                                result = await executeCurrentSql();
+                                result = await executeCurrentSql(exploratoryExecutionSelected
+                                    ? {
+                                        version: 1,
+                                        index: 1,
+                                        parentSqlFingerprint: initialExploratoryExecution.freeze.sqlFingerprint,
+                                    }
+                                    : undefined);
                                 executionError = undefined;
                                 warehouseFailure = undefined;
                             }
@@ -3893,12 +4769,14 @@ async function runAnswerLoop(input) {
         // A router-selected physical-closure denial happens before a capability
         // exists. Its rejected bytes are diagnostics for the host, never a SQL
         // preview that a user can review, copy, or turn into a draft.
-        sql: exploratoryClosureDenied ? undefined : parsed.sql,
+        sql: exploratoryClosureDenied || semanticFanoutProbeFailure ? undefined : parsed.sql,
         suggestedViz: parsed.viz ?? 'table',
         assumptions: [
             ...(exploratoryClosureDenied
                 ? ['The router-selected physical closure rejected the generated SQL before capability minting.']
-                : ['The SQL preview is uncertified until an analyst reviews and promotes the DQL artifact.']),
+                : semanticFanoutProbeFailure
+                    ? ['The native semantic join could not be proven fanout-safe before plan freeze, so DQL did not execute or expose its SQL.']
+                    : ['The SQL preview is uncertified until an analyst reviews and promotes the DQL artifact.']),
             ...(certifiedExecutionFallback
                 ? [`Certified block ${certifiedExecutionFallback.node.name} failed execution and was bypassed: ${certifiedExecutionFallback.error}`]
                 : []),
@@ -3911,17 +4789,34 @@ async function runAnswerLoop(input) {
     // Global top-N asks must return exactly N rows even when the generated SQL
     // returned more (missing/oversized LIMIT) — mirrors the certified path so a
     // "top 10" question never shows 200 rows. per_group scope is left intact by
-    // trimResultToRequestedTopN. Domain-agnostic.
+    // trimCertifiedBlockResultToRequestedTopN. Domain-agnostic.
     let topNTrimNote;
     if (result) {
         const beforeRows = Array.isArray(result.rows) ? result.rows.length : result.rowCount;
-        result = trimResultToRequestedTopN(result, questionPlan);
+        result = trimCertifiedBlockResultToRequestedTopN(result, questionPlan);
         const afterRows = Array.isArray(result.rows) ? result.rows.length : result.rowCount;
         if (afterRows < beforeRows) {
             topNTrimNote = `Showed the top ${questionPlan.requestedShape.topN?.n ?? afterRows} of ${beforeRows} rows the query returned.`;
         }
     }
     const resultShape = result ? validateAnswerResultShape(questionPlan, result) : undefined;
+    // A router-selected exploratory plan carries a host-bound output
+    // projection. The ordinary generated-answer UX may show a partial result
+    // with a warning, but a frozen exploratory plan may not: displaying it
+    // would silently change the tuple DQL authorized. Keep the connector rows
+    // out of the answer/artifact when a broken executor returns them anyway.
+    const missingFrozenExploratoryOutputs = exploratoryExecutionSelected && result
+        ? missingFrozenRequiredOutputProjection(input.resolvedAnalyticalPlan, result)
+        : [];
+    const activeExploratoryOutputFreeze = exploratoryRepairExecution?.freeze ?? initialExploratoryExecution?.freeze;
+    const missingFrozenExploratoryBindingProofs = exploratoryExecutionSelected && result
+        ? missingFrozenRequiredOutputBindingProof(input.resolvedAnalyticalPlan, activeExploratoryOutputFreeze)
+        : [];
+    const frozenExploratoryOutputFailures = [...new Set([
+            ...missingFrozenExploratoryOutputs,
+            ...missingFrozenExploratoryBindingProofs,
+        ])];
+    const frozenExploratoryOutputContractFailure = frozenExploratoryOutputFailures.length > 0;
     // ANY question whose SQL executed but dropped multiple requested columns used to
     // REFUSE outright ("no governed answer"), throwing away a result that actually
     // ran. Instead, SURFACE the partial result (review-required) with a warning that
@@ -3944,13 +4839,16 @@ async function runAnswerLoop(input) {
         ...repairNotes,
         ...(resultShape?.warnings ?? []),
         ...(partialShapeWarning ? [partialShapeWarning] : []),
+        ...(frozenExploratoryOutputContractFailure
+            ? [`The executed exploratory result violated the frozen output contract: ${frozenExploratoryOutputFailures.join(', ')}.`]
+            : []),
         ...(topNTrimNote ? [topNTrimNote] : []),
         ...(executionError ? ['The preview execution error must be reviewed before reuse.'] : []),
     ];
     const generatedOutputs = parsed.outputs?.length ? parsed.outputs : resultColumnNames(result);
     const generatedRequestedFilters = mergeProposalStringLists(input.followUp?.filters, parsed.requestedFilters);
     const generatedRequestedDimensions = mergeProposalStringLists(input.followUp?.dimensions, parsed.requestedDimensions);
-    const baseDqlArtifact = exploratoryClosureDenied
+    const baseDqlArtifact = exploratoryClosureDenied || semanticFanoutProbeFailure || frozenExploratoryOutputContractFailure
         ? undefined
         : result?.dqlArtifact ?? semanticBridgeAnswer?.dqlArtifact ?? buildGeneratedSqlDqlArtifact({
             question,
@@ -3979,7 +4877,7 @@ async function runAnswerLoop(input) {
         : undefined;
     let draftBlock;
     let draftCaptureError;
-    if (!exploratoryClosureDenied && input.captureGeneratedDraft && parsed.sql) {
+    if (!exploratoryClosureDenied && !semanticFanoutProbeFailure && !frozenExploratoryOutputContractFailure && input.captureGeneratedDraft && parsed.sql) {
         try {
             draftBlock = await input.captureGeneratedDraft({
                 question,
@@ -4026,10 +4924,21 @@ async function runAnswerLoop(input) {
         : undefined;
     const certifiedMetricAnswer = semanticMetricCertification === 'certified' || semanticMetricCertification === 'reviewed';
     const governedMetricExecutionFailure = governedMetricAnswer && Boolean(executionError);
-    const terminalExecutionFailure = governedMetricExecutionFailure || exploratoryClosureDenied;
+    const terminalExecutionFailure = governedMetricExecutionFailure || exploratoryClosureDenied || frozenExploratoryOutputContractFailure;
+    const semanticFanoutTraceError = semanticFanoutProbeFailure
+        ? Object.assign(new Error(semanticFanoutProbeFailure.message), {
+            code: semanticFanoutProbeFailure.code,
+            details: { phase: 'validation' },
+        })
+        : executionError;
+    const terminalFailureMessage = frozenExploratoryOutputContractFailure
+        ? `The exploratory execution result did not retain proven frozen output binding ${frozenExploratoryOutputFailures.join(', ')}, so DQL did not display it.`
+        : exploratoryClosureDenied
+            ? 'The generated SQL referenced a relation outside the router-selected physical closure, so DQL did not execute it.'
+            : semanticFanoutProbeFailure?.message;
     const finalSemanticExecutionTrace = semanticTraceAfterExecution(semanticExecutionTrace, {
         executed: Boolean(result),
-        ...(executionError ? { error: executionError } : {}),
+        ...(semanticFanoutTraceError ? { error: semanticFanoutTraceError } : {}),
         ...(result ? { result } : {}),
     });
     return {
@@ -4039,21 +4948,25 @@ async function runAnswerLoop(input) {
         reviewStatus: terminalExecutionFailure ? 'none' : governedMetricAnswer ? 'governed' : 'draft_ready',
         semanticMetricCertification,
         confidence: terminalExecutionFailure ? 0 : certifiedMetricAnswer ? 0.8 : governedMetricAnswer ? 0.72 : 0.55,
-        text: exploratoryClosureDenied
-            ? 'The generated SQL referenced a relation outside the router-selected physical closure, so DQL did not execute it.'
-            : generatedText,
-        answer: exploratoryClosureDenied
-            ? 'The generated SQL referenced a relation outside the router-selected physical closure, so DQL did not execute it.'
-            : generatedText,
-        ...(exploratoryClosureDenied ? {} : { proposedSql: parsed.sql, sql: parsed.sql }),
-        result,
+        text: terminalFailureMessage ?? generatedText,
+        answer: terminalFailureMessage ?? generatedText,
+        ...(exploratoryClosureDenied || semanticFanoutProbeFailure || frozenExploratoryOutputContractFailure ? {} : { proposedSql: parsed.sql, sql: parsed.sql }),
+        result: frozenExploratoryOutputContractFailure ? undefined : result,
         executionError,
         ...(warehouseFailure ? { warehouseFailure } : {}),
         ...(finalSemanticExecutionTrace ? { semanticExecutionTrace: finalSemanticExecutionTrace } : {}),
-        ...(terminalExecutionFailure ? { refusalCode: 'grounding_gap' } : {}),
+        ...(terminalExecutionFailure ? {
+            refusalCode: semanticFanoutProbeFailure ? 'policy_blocked' : 'grounding_gap',
+        } : {}),
+        ...(semanticFanoutProbeFailure ? {
+            refusalDetails: {
+                code: semanticFanoutProbeFailure.code,
+                message: semanticFanoutProbeFailure.message,
+            },
+        } : {}),
         suggestedViz: parsed.viz ?? 'table',
-        ...(exploratoryClosureDenied ? {} : { dqlArtifact: answerDqlArtifact }),
-        ...(exploratoryClosureDenied ? {} : {
+        ...(exploratoryClosureDenied || semanticFanoutProbeFailure || frozenExploratoryOutputContractFailure ? {} : { dqlArtifact: answerDqlArtifact }),
+        ...(exploratoryClosureDenied || semanticFanoutProbeFailure || frozenExploratoryOutputContractFailure ? {} : {
             draftBlock,
             draftBlockId: draftBlock?.path,
             promoteCommand: draftBlock ? `dql certify --from-draft ${draftBlock.path}` : undefined,
@@ -4095,7 +5008,8 @@ async function runAnswerLoop(input) {
         considered,
         providerUsed: provider.name,
         aggregationSafetyProof,
-        ...(preparedExploratoryExecution ? { exploratoryExecutionFreeze: preparedExploratoryExecution.freeze } : {}),
+        ...(initialExploratoryExecution ? { exploratoryExecutionFreeze: initialExploratoryExecution.freeze } : {}),
+        ...(exploratoryRepairExecution ? { exploratoryRepairExecutionFreeze: exploratoryRepairExecution.freeze } : {}),
         // Carry the governed metric match so the exit point can name a
         // `semantic_metric` route (spec 17, part C).
         _semanticMetricMatch: governedMetricAnswer ? semanticMetricMatch ?? undefined : undefined,
@@ -4110,7 +5024,13 @@ function renderExecutionSchemaForRepair(schemaContext) {
         ? `Current execution-target columns (authoritative for this repair):\n${tables.join('\n')}`
         : 'No execution-target columns were available; do not invent a replacement column.';
 }
-function trimResultToRequestedTopN(result, plan) {
+/**
+ * Preserve the declared answer shape even when an authored certified block
+ * returns a broader result set than its typed `top_n` input.  The V2 exact
+ * path uses this same normalization so a provider-free execution cannot
+ * present a different result than the ordinary certified route.
+ */
+export function trimCertifiedBlockResultToRequestedTopN(result, plan) {
     const topN = plan.requestedShape.topN;
     if (!topN || topN.scope === 'per_group' || !Array.isArray(result.rows) || result.rows.length <= topN.n)
         return result;
@@ -4135,6 +5055,70 @@ function resultColumnNames(result) {
         .filter(Boolean);
     return columns?.length ? columns : undefined;
 }
+/**
+ * Check only the host-bound aliases from a frozen plan. This is intentionally
+ * stricter than the conversational shape helper: synonym matching is useful
+ * for ordinary narration, but it cannot substitute a requested order/product
+ * identifier after exploratory SQL has been authorized.
+ */
+function missingFrozenRequiredOutputProjection(plan, result) {
+    const required = plan?.outputContract?.requiredOutputs ?? [];
+    if (required.length === 0)
+        return [];
+    const columns = new Set((resultColumnNames(result) ?? []).map(canonicalFrozenOutputAlias));
+    return required.flatMap((binding) => {
+        const alias = binding.outputName
+            ?? binding.qualifiedId?.split(/[:.]/).at(-1)
+            ?? binding.requested;
+        const normalized = canonicalFrozenOutputAlias(alias);
+        return normalized && columns.has(normalized) ? [] : [alias];
+    });
+}
+/**
+ * A column name in a returned result does not prove where it came from.  The
+ * result is accepted only when the server-owned authorization receipt carries
+ * the exact frozen output-source binding that was parser-validated for the SQL
+ * handed to the connector.  Old persisted receipts remain readable; they
+ * simply cannot authorize a new result for a plan that has explicit outputs.
+ */
+function missingFrozenRequiredOutputBindingProof(plan, freeze) {
+    const required = plan?.outputContract?.requiredOutputs ?? [];
+    if (required.length === 0)
+        return [];
+    const expected = frozenRequiredOutputBindingProofsForPlan(plan);
+    const missingSourceBindingAliases = required
+        .filter((binding) => !expected.some((proof) => canonicalFrozenOutputAlias(proof.outputName)
+        === canonicalFrozenOutputAlias(binding.outputName
+            ?? binding.qualifiedId?.split(/[:.]/).at(-1)
+            ?? binding.requested)))
+        .map((binding) => binding.outputName
+        ?? binding.qualifiedId?.split(/[:.]/).at(-1)
+        ?? binding.requested);
+    const actual = freeze?.requiredOutputBindings ?? [];
+    const missingProofAliases = expected
+        .filter((proof) => !actual.some((candidate) => sameFrozenRequiredOutputBindingProof(candidate, proof)))
+        .map((proof) => proof.outputName);
+    return [...new Set([...missingSourceBindingAliases, ...missingProofAliases])];
+}
+function sameFrozenRequiredOutputBindingProof(actual, expected) {
+    return actual.version === 1
+        && actual.qualifiedId === expected.qualifiedId
+        && canonicalFrozenOutputAlias(actual.outputName) === canonicalFrozenOutputAlias(expected.outputName)
+        && canonicalFrozenSourceIdentifier(actual.relation) === canonicalFrozenSourceIdentifier(expected.relation)
+        && canonicalFrozenSourceIdentifier(actual.column) === canonicalFrozenSourceIdentifier(expected.column);
+}
+function canonicalFrozenOutputAlias(value) {
+    return value.toLowerCase()
+        .replace(/["`]/g, '')
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+}
+function canonicalFrozenSourceIdentifier(value) {
+    return value.toLowerCase()
+        .replace(/["`\[\]]/g, '')
+        .replace(/\s*\.\s*/g, '.')
+        .trim();
+}
 function analyticalCapabilityForPlan(plan, contextPack, registry = []) {
     const selected = normalizeMetricCapabilityContract(plan.selectedCapability);
     if (selected) {
@@ -4501,8 +5485,11 @@ async function executeSemanticAnalyticalGraph(input) {
         });
         aggregationSafetyProof = proof;
         if (proof.status !== 'safe') {
-            return analyticalGraphFailureAnswer(input, 'EXECUTION_GRAPH_MISMATCH', semanticAggregationSafetyFailure(proof), {
-                phase: 'validation',
+            return analyticalGraphFailureAnswer(input, 'COMPILATION_FAILED', semanticAggregationSafetyFailure(proof), {
+                // This is compiler/plan validation before a warehouse statement is
+                // dispatched. It must be represented as semantic.compile, never as
+                // result normalization or a SQL execution failure.
+                phase: 'compilation',
                 dqlArtifact: composed.dqlArtifact,
                 compiledSql: composed.sql,
                 semanticExecutionTrace,
@@ -4528,11 +5515,25 @@ async function executeSemanticAnalyticalGraph(input) {
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
+            // A missing local execution target fails at the host's pre-execution
+            // boundary. It must not be recast as a semantic compiler failure merely
+            // because the semantic graph owns the callback. Preserve the narrow,
+            // producer-tagged fact for the durable Ask receipt; it does not alter
+            // the frozen route, trust, or user-facing analytical failure.
+            const observabilityExecutionFailure = observabilityFailureForFrozenExecution(analyticalErrorDetail(error));
             return analyticalGraphFailureAnswer(input, 'EXECUTION_FAILED', message, {
                 phase: 'execution',
                 dqlArtifact: composed.dqlArtifact,
                 compiledSql: composed.sql,
                 semanticExecutionTrace: semanticTraceAfterExecution(semanticExecutionTrace, { executed: false, error }),
+                // The exact aggregation proof already passed before the connector
+                // call. Preserve it so presentation never recasts a warehouse binder
+                // error as a failed semantic aggregation proof.
+                aggregationSafetyProof,
+                // This producer-tagged fact is diagnostic only: it does not alter
+                // routing, trust, or the immutable frozen plan.
+                warehouseFailure: normalizeWarehouseSqlFailure(error, input.input.semanticDriver),
+                ...(observabilityExecutionFailure ? { observabilityExecutionFailure } : {}),
             });
         }
         const normalized = normalizeAnalyticalSourceResult({
@@ -4962,6 +5963,10 @@ function analyticalGraphFailureAnswer(input, code, reason, artifacts = {}) {
         ...(artifacts.dqlArtifact ? { dqlArtifact: artifacts.dqlArtifact } : {}),
         ...(artifacts.semanticExecutionTrace ? { semanticExecutionTrace: artifacts.semanticExecutionTrace } : {}),
         ...(artifacts.aggregationSafetyProof ? { aggregationSafetyProof: artifacts.aggregationSafetyProof } : {}),
+        ...(artifacts.warehouseFailure ? { warehouseFailure: artifacts.warehouseFailure } : {}),
+        ...(artifacts.observabilityExecutionFailure
+            ? { observabilityExecutionFailure: artifacts.observabilityExecutionFailure }
+            : {}),
         citations: contextPackCitations(input.input.contextPack, 8),
         considered: input.considered,
         contextPack: input.input.contextPack,
@@ -5133,6 +6138,38 @@ Rules:
 // combined dataset — show them separately" refusal into the join the user asked
 // for, while still allowing an honest refusal if context is truly missing.
 const FORCE_JOIN_INSTRUCTION = `Your previous attempt declined to produce SQL. Re-read the supplied schema, metadata, and any "Knowledge graph join routes": this question CAN be answered by joining the grounded tables along their documented keys. Do NOT refuse, and do NOT suggest showing the datasets separately — compose ONE read-only SELECT/WITH that joins the relevant tables to answer it directly, following the JSON contract from rule 3. State the grain and the exact join path in the summary. Only if a required table, column, or join key is truly absent from the supplied context may you still ask a clarifying question.`;
+/**
+ * A model-decline correction is only a repair when the router already froze a
+ * bounded exploratory RAP and the host supplied the matching capability
+ * mint/consume closures.  Anything weaker is a new planning attempt and must
+ * not borrow the repair transport allowance.
+ */
+function frozenExploratoryModelRepairAuthority(input) {
+    const plan = input.resolvedAnalyticalPlan;
+    return input.selectedCascadeTier === 'exploratory_sql'
+        && plan?.mode === 'authoritative'
+        && plan.capability === 'bounded_exploration'
+        && Boolean(plan.planId && plan.fingerprint && plan.snapshotId)
+        && Boolean(input.prepareExploratorySqlExecution && input.executeAgenticGeneratedSql);
+}
+/**
+ * The corrective prompt repeats only host-owned tuple facts.  It never asks
+ * the model to choose a new route, relation closure, output contract, or
+ * trust label; SQL authorization re-proves those facts after the response.
+ */
+function renderFrozenExploratoryRepairContract(plan, questionPlan) {
+    const requiredOutputs = plan.outputContract?.requiredOutputs?.filter((output) => output.status === 'resolved' && output.outputName && output.qualifiedId)
+        .map((output) => `${output.outputName} <- ${output.qualifiedId}`)
+        ?? [];
+    return [
+        'This is the one permitted correction for an already frozen, review-required exploratory plan.',
+        renderRequestedShapeForRepair(questionPlan),
+        requiredOutputs.length > 0
+            ? `Frozen required output bindings (preserve exactly): ${requiredOutputs.join('; ')}`
+            : 'Preserve the frozen requested tuple exactly.',
+        'Use only the relations and columns already supplied in the bounded context. Do not add a relation, change the ranking, remove an output, change the limit, or alter the analytical meaning. The host will validate the same frozen snapshot and closure before execution.',
+    ].join('\n');
+}
 /**
  * Produces the prompt-facing subset of a broad local context pack. Global
  * records remain available, while a record explicitly owned by another domain
@@ -7842,6 +8879,11 @@ async function requestSqlRepair(input) {
         // bumping would let an internal preview-repair exceed that cap. Escalation-level
         // repairs bump-then-clamp in the host (resolveRunReasoningEffort).
         reasoningEffort: input.reasoningEffort,
+        ...(input.dispatchPhase ? { dispatchPhase: input.dispatchPhase } : {}),
+        ...(input.egressPurpose ? { egressPurpose: input.egressPurpose } : {}),
+        ...(input.maxProviderDispatches !== undefined
+            ? { maxProviderDispatches: input.maxProviderDispatches }
+            : {}),
     });
 }
 async function generateProposalWithOptionalTools(input) {
@@ -7849,6 +8891,11 @@ async function generateProposalWithOptionalTools(input) {
     const options = {
         signal: input.signal,
         reasoningEffort: input.reasoningEffort,
+        ...(input.dispatchPhase ? { dispatchPhase: input.dispatchPhase } : {}),
+        ...(input.egressPurpose ? { egressPurpose: input.egressPurpose } : {}),
+        ...(input.maxProviderDispatches !== undefined
+            ? { maxProviderDispatches: input.maxProviderDispatches }
+            : {}),
     };
     // No tools → plain generation (nothing for the loop to drive).
     if (tools.length === 0) {
@@ -7871,7 +8918,7 @@ async function generateProposalWithOptionalTools(input) {
     // provider implements generateWithTools (Claude/OpenAI), and an equivalent text
     // protocol otherwise (subscription-CLI passthrough, Ollama). This is what gives
     // every provider — not just the two API ones — a real tool-driven Stage B.
-    return runAgenticToolLoop(input.provider, [...input.messages], tools, {
+    const result = await runAgenticToolLoopDetailed(input.provider, [...input.messages], tools, {
         ...options,
         toolPolicy,
         maxToolCalls: toolBudget.maxToolCalls,
@@ -7882,7 +8929,26 @@ async function generateProposalWithOptionalTools(input) {
                 sink.push(evidenceToolCallFromEvent(event, sink.length + 1));
         },
     });
+    // The tool loop converts a budget stop into a TERMINAL RESULT rather than
+    // rethrowing, so the reason reached this caller as an empty string and the
+    // run reported "the model declined to propose SQL" — blaming the model for
+    // a ceiling DQL imposed on itself. The plain-generation branch above throws
+    // these, so rethrow here too and let one handler label them honestly.
+    const budgetStop = PROPOSAL_BUDGET_STOP_CODES[result.stop ?? ''];
+    if (budgetStop) {
+        throw Object.assign(new Error(`The Ask runtime stopped before a query was settled (${result.stop}).`), { code: budgetStop });
+    }
+    return result.text;
 }
+/**
+ * Tool-loop terminal reasons that mean DQL stopped itself, mapped back to the
+ * dispatch codes the answer loop's provider-failure handler understands.
+ */
+const PROPOSAL_BUDGET_STOP_CODES = {
+    provider_dispatch_budget_exhausted: 'PROVIDER_DISPATCH_BUDGET_EXHAUSTED',
+    run_soft_target_exceeded: 'RUN_SOFT_TARGET_EXCEEDED',
+    run_deadline_insufficient: 'RUN_DEADLINE_INSUFFICIENT',
+};
 async function selectDeepGeneratedProposalCandidate(input) {
     const initial = await scoreDeepGeneratedProposalCandidate(input, {
         raw: input.initial.raw,
@@ -8245,10 +9311,25 @@ function isRetryableGeneratedSqlError(failure) {
     return failure.retryDisposition === 'model_repair';
 }
 /**
- * Only SQL-shape/binding failures may leave the certified lane. Connectivity,
- * authorization, cancellation, and timeout failures would affect every query
- * route and must remain terminal rather than triggering wasteful provider work.
+ * Only SQL-shape/binding failures may leave a frozen governed lane.
+ * Connectivity, authorization, cancellation, and timeout failures would affect
+ * every query route and must remain terminal rather than triggering wasteful
+ * provider work.
  */
+function observabilityFailureForFrozenExecution(detail) {
+    // Do not infer this from user-facing error text. The local runtime tags the
+    // physical pre-execution boundary; this projection only carries that exact
+    // typed fact into the redacted trace after a governed plan has frozen.
+    if (detail?.origin !== 'host' || detail.stage !== 'execute' || detail.code !== 'connection_not_configured') {
+        return undefined;
+    }
+    return {
+        version: 1,
+        phase: 'execution',
+        cause: 'connection_not_configured',
+        safeAction: 'configure_connection',
+    };
+}
 function isRetryableCertifiedExecutionError(error) {
     return /\b(?:binder|parser|catalog)\s+error\b/i.test(error)
         // DuckDB says "ambiguous reference"; Snowflake says "ambiguous column name".
@@ -9213,29 +10294,45 @@ function uniqueAssets(assets) {
     return Array.from(byId.values());
 }
 /**
- * Execute the semantic layer's fanout probe and translate a structural
- * contradiction into an actionable refusal message. Probe failures (missing
- * permissions, dialect quirks) return undefined — the probe protects against
- * silent inflation but must never become a new way for a healthy query to fail.
+ * Execute the semantic layer's fanout probe before a governed native semantic
+ * join freezes. A native join that cannot be checked is not a governed-safe
+ * join: fail closed with a redacted typed failure instead of executing a query
+ * that could multiply aggregates. MetricFlow/dbt Cloud paths have their own
+ * compiler guarantees and do not use this native direct-join guard.
  */
 export async function probeSemanticJoinFanout(probeSql, joinedTables, executeSql) {
     try {
         const payload = await executeSql(probeSql);
         const counts = parseFanoutProbeCounts(payload);
-        if (!counts || counts.base <= 0 || counts.joined <= counts.base)
-            return undefined;
+        if (!counts || counts.base <= 0) {
+            return {
+                status: 'blocked',
+                code: 'SEMANTIC_FANOUT_PROBE_UNPARSEABLE',
+                message: 'DQL did not execute this governed semantic answer because its join-safety probe did not return verifiable row counts. Check the declared relationship or run the metric through MetricFlow / dbt Cloud, then retry.',
+            };
+        }
+        if (counts.joined <= counts.base)
+            return { status: 'safe' };
         const factor = counts.joined / counts.base;
         const tables = joinedTables.filter(Boolean).join(', ');
-        return [
-            `Blocked a governed semantic answer whose join inflates results: joining ${tables || 'the declared tables'}`,
-            `turned ${counts.base.toLocaleString('en-US')} base rows into ${counts.joined.toLocaleString('en-US')} (×${factor >= 10 ? Math.round(factor) : factor.toFixed(1)}).`,
-            'The declared join key is not unique on the joined side, so every aggregated value would be multiplied.',
-            'Deduplicate the joined model (for example, filter a slowly-changing dimension to current records)',
-            'or execute this metric through MetricFlow / dbt Cloud, then retry. No numbers were shown because they would be wrong.',
-        ].join(' ');
+        return {
+            status: 'blocked',
+            code: 'SEMANTIC_FANOUT_DUPLICATE_KEY',
+            message: [
+                `Blocked a governed semantic answer whose join inflates results: joining ${tables || 'the declared tables'}`,
+                `turned ${counts.base.toLocaleString('en-US')} base rows into ${counts.joined.toLocaleString('en-US')} (×${factor >= 10 ? Math.round(factor) : factor.toFixed(1)}).`,
+                'The declared join key is not unique on the joined side, so every aggregated value would be multiplied.',
+                'Deduplicate the joined model (for example, filter a slowly-changing dimension to current records)',
+                'or execute this metric through MetricFlow / dbt Cloud, then retry. No numbers were shown because they would be wrong.',
+            ].join(' '),
+        };
     }
     catch {
-        return undefined;
+        return {
+            status: 'blocked',
+            code: 'SEMANTIC_FANOUT_PROBE_ERROR',
+            message: 'DQL did not execute this governed semantic answer because it could not verify join fanout before aggregation. Check the declared relationship or run the metric through MetricFlow / dbt Cloud, then retry.',
+        };
     }
 }
 function parseFanoutProbeCounts(payload) {