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

package/dist/answer-loop.js

@@ -41,7 +41,7 @@ import { planAnalyticalPath, humanizeAnalyticalEntityId, analyticalPolicyUserFac
 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,
@@ -2101,14 +2704,8 @@ async function runAnswerLoop(input) {
         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);
@@ -2977,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: [],
@@ -3707,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,
@@ -3729,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,
@@ -4178,11 +4789,11 @@ 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.`;
@@ -4413,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;
@@ -8301,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,
@@ -8312,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,