@duckcodeailabs/dql-agent 1.14.0 → 1.14.2

package/dist/agent-run-engine.js

@@ -2,11 +2,13 @@ import { createHash, randomUUID } from "node:crypto";
 import { normalizeProviderEgressReceiptV1, } from '@duckcodeailabs/dql-core';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { classifyConversationalTurn, decideAgentAction, looksLikeComposeApp, } from "./intent-controller.js";
+import { classifyConversationalTurn, looksLikeDefinitionalAboutNamedObject, looksLikeNamedCertifiedArtifactMetadataRequest, decideAgentAction, looksLikeComposeApp, } from "./intent-controller.js";
 import { selectCascadeRunRoute } from "./cascade/route-policy.js";
 import { canUseEngineEscalation, canUseLaneRepair, cascadeBudgetTrace, createCascadeBudgetState, recordEngineEscalation, recordLaneRepair, } from "./cascade/budgets.js";
 import { buildAnalysisQuestionPlan } from "./metadata/analysis-planner.js";
 import { conversationHistoryFromContext, isLikelyClarificationReply, } from "./conversation/snapshot.js";
+import { buildCoverageGap, classifyProviderFailure, } from './analytical-orchestration.js';
+import { evaluateAnalyticalRequestPolicy } from './analytical-request-policy.js';
 /** Routes a stakeholder may never land on (analyst authoring lives in the Notebook). */
 const ANALYST_ONLY_ROUTES = new Set(["sql_cell", "dql_block_draft", "modeling_draft", "skill_draft"]);
 /**
@@ -64,30 +66,60 @@ export function agentRouteDeadlineMs(route) {
         return 120_000;
     return undefined;
 }
+/** Default request-ingress deadlines. */
+const DEFAULT_ASK_DEADLINE_MS = 45_000;
+const DEFAULT_RESEARCH_DEADLINE_MS = 120_000;
+/** Ceiling on any override, so a typo cannot hang a run indefinitely. */
+const MAX_DEADLINE_MS = 600_000;
+/**
+ * A deadline multiplier for slow providers.
+ *
+ * The 45s Ask budget assumes a hosted model. A local Ollama model needs ~7s for
+ * a one-word reply, so the meaning call alone can exhaust the whole window and
+ * every question comes back "The discovery window ended before an exact plan was
+ * frozen" — which makes a local model unusable at the default, and DQL is
+ * local-first by design.
+ *
+ * Deliberately a MULTIPLIER rather than an absolute: the relationship between
+ * the Ask and Research budgets, and between each and its soft targets, is
+ * load-bearing, so scaling keeps them proportional instead of letting one
+ * setting invert them.
+ */
+export function deadlineScale(env = process.env) {
+    const raw = Number(env.DQL_AGENT_DEADLINE_SCALE);
+    if (!Number.isFinite(raw) || raw <= 0)
+        return 1;
+    // Bounded: below 1 would tighten a safety deadline someone is relying on.
+    return Math.min(Math.max(raw, 1), 20);
+}
 /** The request envelope starts before retrieval/routing, so a stuck router can
  * never evade the route-specific deadline that is selected later. */
 export function agentRequestDeadlineMs(requestedMode) {
-    return requestedMode === 'research' ? 120_000 : 45_000;
+    const base = requestedMode === 'research' ? DEFAULT_RESEARCH_DEADLINE_MS : DEFAULT_ASK_DEADLINE_MS;
+    return Math.min(base * deadlineScale(), MAX_DEADLINE_MS);
 }
 /** Create the one request-ingress deadline authority used by every stage. */
 export function createAgentRunBudget(input) {
     const nowMs = input.nowMs ?? Date.now;
     const startedAtMs = input.startedAtMs ?? nowMs();
     const mode = input.requestedMode === 'research' ? 'research' : 'ask';
-    const hardDeadlineMs = mode === 'research' ? 120_000 : 45_000;
+    const scale = deadlineScale();
+    const hardDeadlineMs = Math.min((mode === 'research' ? DEFAULT_RESEARCH_DEADLINE_MS : DEFAULT_ASK_DEADLINE_MS) * scale, MAX_DEADLINE_MS);
     const timeout = (input.timeoutSignal ?? AbortSignal.timeout)(hardDeadlineMs);
     const hardSignal = input.inheritedSignal
         ? AbortSignal.any([input.inheritedSignal, timeout])
         : timeout;
     const elapsedMs = () => Math.max(0, nowMs() - startedAtMs);
     const softTargetMs = (route) => {
-        if (mode === 'research')
-            return 90_000;
-        return agentRouteDeadlineMs(route) ?? 15_000;
+        const base = mode === 'research' ? 90_000 : (agentRouteDeadlineMs(route) ?? 15_000);
+        // Scaled with the hard deadline: a soft target that stayed fixed while the
+        // ceiling moved would stop new work long before the run was actually out of
+        // time, which is the same dead end by a different route.
+        return Math.min(base * scale, hardDeadlineMs);
     };
     // Narration must still be reachable after a full generation window, and must
     // leave the hard deadline (45s ask / 120s research) room to land.
-    const narrationSoftTargetMs = () => (mode === 'research' ? 100_000 : 38_000);
+    const narrationSoftTargetMs = () => Math.min((mode === 'research' ? 100_000 : 38_000) * scale, hardDeadlineMs);
     return Object.freeze({
         startedAtMs,
         hardDeadlineMs,
@@ -613,6 +645,120 @@ export class AgentRunEngine {
                 ...(clarificationContinuation ? { clarificationResolved: true } : {}),
             },
         });
+        // This check is intentionally before route selection.  A restricted direct
+        // disclosure must not be embedded, retrieved, sent to a provider, value
+        // probed, or compiled merely to explain why it cannot be answered.
+        const ingressPolicy = evaluateAnalyticalRequestPolicy(submittedQuestion);
+        if (!ingressPolicy.allowed) {
+            const routeDecision = {
+                action: 'answer',
+                confidence: 1,
+                reason: 'The request is unavailable under the Ask data-safety policy.',
+                followsUp: false,
+                source: 'heuristic',
+                terminalOutcome: {
+                    kind: 'policy_blocked',
+                    code: 'ANALYTICAL_POLICY_BLOCKED',
+                    message: ingressPolicy.message,
+                    candidateIds: [],
+                },
+            };
+            const coverageGap = buildCoverageGap({
+                code: 'POLICY_BLOCKED',
+                phase: 'retrieval',
+                message: ingressPolicy.message,
+                searchedSources: [],
+                attemptedRoutes: [],
+                missing: [],
+                recoverable: false,
+                planFrozen: false,
+                nextActions: ingressPolicy.nextActions,
+            });
+            const evaluation = {
+                id: 'request-policy',
+                label: 'Ask request policy',
+                passed: false,
+                severity: 'blocking',
+                message: ingressPolicy.message,
+            };
+            const artifact = {
+                id: `${runId}:policy`,
+                kind: 'answer',
+                title: 'Ask request unavailable',
+                trustState: 'blocked',
+                payload: {
+                    analyticalCoverageGap: coverageGap,
+                    analyticalFailure: {
+                        code: 'POLICY_BLOCKED',
+                        phase: 'request_policy',
+                        message: ingressPolicy.message,
+                        recoverable: false,
+                        safeActions: ingressPolicy.nextActions,
+                    },
+                },
+            };
+            emit({
+                type: 'route.decided',
+                message: routeDecision.reason,
+                route: 'blocked',
+                payload: routeDecision,
+            });
+            emit({
+                type: 'evaluation.recorded',
+                message: evaluation.message,
+                route: 'blocked',
+                payload: evaluation,
+            });
+            emit({
+                type: 'artifact.created',
+                message: 'Created answer artifact.',
+                route: 'blocked',
+                trustState: 'blocked',
+                payload: artifact,
+            });
+            emit({
+                type: 'run.failed',
+                message: ingressPolicy.message,
+                route: 'blocked',
+                status: 'blocked',
+                trustState: 'blocked',
+            });
+            const completedAt = this.timestamp();
+            const run = {
+                id: runId,
+                question: submittedQuestion,
+                requestedMode,
+                route: 'blocked',
+                status: 'blocked',
+                trustState: 'blocked',
+                stopReason: 'blocked',
+                startedAt,
+                completedAt,
+                selectedObject: request.selectedObject,
+                executionTarget: request.executionTarget,
+                routeDecision,
+                steps: [],
+                summary: ingressPolicy.message,
+                answer: ingressPolicy.message,
+                answerKind: 'governed',
+                artifacts: [artifact],
+                evaluations: [evaluation],
+                events,
+                nextActions: ingressPolicy.nextActions.map((id) => ({ id, label: id === 'ask_for_an_approved_aggregate' ? 'Ask for an approved aggregate' : 'Inspect data policy' })),
+                repairAttempts: 0,
+                escalationAttempts: 0,
+                budgetUsage: cascadeBudgetTrace(createCascadeBudgetState(this.budgetModel)),
+                telemetry: emptyRunTelemetry(durationBetweenMs(startedAt, completedAt), 'policy_blocked'),
+                lifecycle: terminalLifecycle(progress.lifecycle, 'run.failed', completedAt, events.length),
+            };
+            run.diagnosticReceipt = diagnosticReceiptForRun(run);
+            run.diagnosticReceiptV2 = diagnosticReceiptV2ForRun(run);
+            run.diagnosticReceiptV3 = diagnosticReceiptV3ForRun(run);
+            run.artifacts = attachDiagnosticReceipt(run.artifacts, run.diagnosticReceipt, run.diagnosticReceiptV2, run.diagnosticReceiptV3);
+            await checkpointQueue;
+            await this.store?.save(run);
+            return run;
+        }
         const audience = resolveAudience(request);
         // Initialize a deterministic decision so router/provider timeouts can still
         // be persisted as a complete blocked run with an inspectable trace. The old
@@ -722,10 +868,18 @@ export class AgentRunEngine {
                         attempt,
                         stepGoal: planned.goal,
                         priorEvaluations,
+                        priorArtifacts: progress.artifacts,
                         repairHint,
                         emit,
                         emitAnswerDelta: onAnswerDelta,
                     });
+                    // The router owns a frozen analytical tier. An executor may report a
+                    // same-tier execution failure, but it cannot turn a certified or
+                    // semantic plan into generated work (or vice versa) after execution
+                    // has started. Keep this guard in the engine as well as host adapters
+                    // so an injected/legacy executor cannot redefine durable provenance.
+                    routeDecision = applyExploratoryExecutionFreeze(routeDecision, result.analyticalExecutionFreeze);
+                    result = preserveFrozenAnalyticalRoute(route, routeDecision, result);
                     result = consumeRepeatedClarificationSelection(request, routeDecision, result);
                     if (result.analyticalTurnPlan)
                         progress.analyticalTurnPlan = result.analyticalTurnPlan;
@@ -754,7 +908,7 @@ export class AgentRunEngine {
                     // A frozen analytical plan has one route and no downstream planner,
                     // rematch, route escalation, or whole-answer regeneration authority.
                     // Typed server-issued repair is a separate derived run.
-                    if (authoritativeAsk) {
+                    if (authoritativeAsk || routeDecision.analyticalCascadeDecision?.planFrozen === true) {
                         stepStatus = 'needs_review';
                         break;
                     }
@@ -959,7 +1113,8 @@ export class AgentRunEngine {
             run.lifecycle = terminalLifecycle(progress.lifecycle, run.status === "blocked" ? "run.failed" : "run.completed", run.completedAt, events.length);
             run.diagnosticReceipt = diagnosticReceiptForRun(run);
             run.diagnosticReceiptV2 = diagnosticReceiptV2ForRun(run);
-            run.artifacts = attachDiagnosticReceipt(run.artifacts, run.diagnosticReceipt, run.diagnosticReceiptV2);
+            run.diagnosticReceiptV3 = diagnosticReceiptV3ForRun(run);
+            run.artifacts = attachDiagnosticReceipt(run.artifacts, run.diagnosticReceipt, run.diagnosticReceiptV2, run.diagnosticReceiptV3);
             await checkpointQueue;
             await this.store?.save(run);
             return run;
@@ -1045,6 +1200,7 @@ export class AgentRunEngine {
                     lifecycle: terminalLifecycle(progress.lifecycle, "run.cancelled", completedAt, events.length),
                 };
                 run.diagnosticReceiptV2 = diagnosticReceiptV2ForRun(run);
+                run.diagnosticReceiptV3 = diagnosticReceiptV3ForRun(run);
                 await checkpointQueue;
                 await this.store?.save(run);
                 return run;
@@ -1128,7 +1284,8 @@ export class AgentRunEngine {
                 lifecycle: terminalLifecycle(progress.lifecycle, "run.failed", completedAt, events.length),
             };
             run.diagnosticReceiptV2 = diagnosticReceiptV2ForRun(run);
-            run.artifacts = attachDiagnosticReceipt(retainedArtifacts, receipt, run.diagnosticReceiptV2);
+            run.diagnosticReceiptV3 = diagnosticReceiptV3ForRun(run);
+            run.artifacts = attachDiagnosticReceipt(retainedArtifacts, receipt, run.diagnosticReceiptV2, run.diagnosticReceiptV3);
             await checkpointQueue;
             await this.store?.save(run);
             return run;
@@ -1220,6 +1377,9 @@ export class AgentRunEngine {
             ...(finalResult.telemetry ? {
                 telemetry: withTotalDuration(finalResult.telemetry, durationBetweenMs(input.startedAt, completedAt)),
             } : {}),
+            ...(finalResult.narrationIntegrityReceipt ? {
+                narrationIntegrityReceipt: finalResult.narrationIntegrityReceipt,
+            } : {}),
             escalationAttempts,
             budgetUsage: input.budgetUsage,
             ...(finalResult.analyticalTurnPlan ? { analyticalTurnPlan: finalResult.analyticalTurnPlan } : {}),
@@ -1246,7 +1406,7 @@ export class AgentRunEngine {
                 && !frozenPlan
                 && context.request.runBudget
                 && !context.request.runBudget.mayStartDiscovery(context.route)) {
-                return softBoundaryResult(context.route, context.request.runBudget);
+                return softBoundaryResult(context.route, context.request.runBudget, context.priorArtifacts);
             }
             const signal = context.request.runBudget?.hardSignal ?? context.request.signal;
             if (signal?.aborted)
@@ -1278,6 +1438,235 @@ export class AgentRunEngine {
  * inject or deserialize an older router decision as well as the canonical
  * router producer.
  */
+/** An ordinary Ask turn (not Research, App Build, or another explicit mode). */
+function isOrdinaryAskRequest(request) {
+    return request.requestedMode === undefined
+        || request.requestedMode === 'auto'
+        || request.requestedMode === 'ask';
+}
+/**
+ * A modeling/coverage gap is a pre-freeze DISCOVERY result, not permission to
+ * terminate an ordinary Ask. Keep the diagnostic as a typed reason, clear the
+ * blocked RAP, and let the answer executor continue through the governed
+ * relational and review-required generated lanes (AGT-028, EXP-001).
+ *
+ * `requireGovernedEvidence` separates the two callers, and it is what keeps the
+ * analytical-RAP safety boundary intact:
+ *
+ *   - A gap the ROUTER reported is already proof that discovery ran and found a
+ *     modelling limit, so it is rescued unconditionally (the original AGT-028
+ *     behaviour).
+ *   - A block this module SYNTHESIZES only means "nothing froze here". That is
+ *     also what an absent, LLM-authored, or forged router decision looks like,
+ *     so it is rescued only when retrieval actually surfaced governed
+ *     candidates. With no evidence at all it must still fail closed — a forged
+ *     `converse`/`answer` must never bypass the boundary on an analytical
+ *     question.
+ *
+ * Returns `undefined` when the decision is not a rescuable modeling gap, so
+ * callers can fall through to their own handling.
+ */
+function rescueModelingGapForOrdinaryAsk(request, decision, options = {}) {
+    if (!isOrdinaryAskRequest(request))
+        return undefined;
+    if (decision.terminalOutcome?.kind !== 'modeling_gap')
+        return undefined;
+    // A frozen plan is authoritative. Only a PRE-FREEZE coverage observation may
+    // advance through the later governed-relational/exploratory tiers. This keeps
+    // compiler, policy, validation, and warehouse failures terminal after a plan
+    // has been accepted while restoring the required certified → semantic →
+    // relational → review-required exploration cascade for missing dimensions.
+    if (decision.resolvedAnalyticalPlan?.mode === 'authoritative')
+        return undefined;
+    // Genuine user-facing ambiguity and an explicit evidence pick stay terminal.
+    if (decision.requiresClarification === true)
+        return undefined;
+    if (request.selectedEvidenceId)
+        return undefined;
+    // The router, not this host boundary, owns cascade eligibility. A typed
+    // pre-freeze coverage gap advances only when the same snapshot recorded an
+    // executable exploratory tier. This prevents a semantic-only candidate or a
+    // forged/old terminal decision from quietly becoming generated SQL.
+    const exploratoryAttempt = decision.analyticalCascadeDecision?.attempts.find((attempt) => attempt.tier === 'exploratory_sql');
+    if (decision.analyticalCascadeDecision?.selectedTier !== 'exploratory_sql'
+        || decision.analyticalCascadeDecision.planFrozen
+        || exploratoryAttempt?.outcome !== 'executable'
+        || exploratoryAttempt.candidateIds.length === 0)
+        return undefined;
+    if (options.requireGovernedEvidence) {
+        const governedEvidence = (decision.retrievalEvidence?.candidateCount ?? 0) > 0
+            || (decision.meaningResolution?.selectedConceptIds.length ?? 0) > 0;
+        if (!governedEvidence)
+            return undefined;
+    }
+    return {
+        ...decision,
+        action: 'answer',
+        confidence: Math.min(decision.confidence, 0.55),
+        reason: `${decision.terminalOutcome.message} Continuing through DBT-grounded relational and review-required generated analysis before asking for a modeling change.`,
+        terminalOutcome: undefined,
+        resolvedAnalyticalPlan: undefined,
+        requiresClarification: false,
+        // The premise of this rescue is that NO governed plan froze, so the turn
+        // must not take `selectRoute`'s certified/semantic shortcut — that path
+        // stamps `certified`/`governed` trust off a bare RECOMMENDATION, which is a
+        // suggestion, not a bound execution contract. Keep the meaning evidence for
+        // citations and downgrade the route to governed SQL, which is review-required.
+        ...(decision.meaningResolution
+            ? {
+                meaningResolution: {
+                    ...decision.meaningResolution,
+                    recommendedRoute: 'governed_sql',
+                },
+            }
+            : {}),
+    };
+}
+/**
+ * Consume the router's immutable cascade decision without reparsing the
+ * question or reconstructing a tier from route/identifier text. The selected
+ * tier is intentionally sufficient for dispatch; compilation and execution
+ * still validate the frozen plan or review-required exploratory SQL.
+ */
+function routeFromAnalyticalCascade(decision) {
+    const cascade = decision.analyticalCascadeDecision;
+    if (!cascade)
+        return undefined;
+    if (cascade.stopReason === 'denied' || cascade.stopReason === 'coverage_gap' || cascade.stopReason === 'post_freeze_failure') {
+        return 'blocked';
+    }
+    if (cascade.stopReason === 'ambiguous')
+        return 'clarify';
+    switch (cascade.selectedTier) {
+        case 'certified':
+            return cascade.planFrozen ? 'certified_answer' : undefined;
+        case 'semantic':
+            return cascade.planFrozen ? 'semantic_answer' : undefined;
+        case 'governed_relational':
+        case 'exploratory_sql':
+            return 'generated_answer';
+        default:
+            return undefined;
+    }
+}
+/**
+ * A frozen router decision is an immutable execution contract, not a hint that
+ * a downstream answer loop may replace with another meaning/tier. The executor
+ * is still free to return a terminal compilation, provider, adapter, or result
+ * failure, but it must retain the selected route while doing so.
+ */
+function preserveFrozenAnalyticalRoute(route, decision, result) {
+    const frozen = decision.analyticalCascadeDecision?.planFrozen === true
+        || decision.resolvedAnalyticalPlan?.mode === 'authoritative';
+    if (!frozen || !result.resolvedRoute || result.resolvedRoute === route)
+        return result;
+    return {
+        resolvedRoute: route,
+        status: 'blocked',
+        trustState: 'blocked',
+        stopReason: 'blocked',
+        summary: `The frozen ${route.replaceAll('_', ' ')} plan could not execute as selected. DQL did not substitute another analytical tier.`,
+        answer: 'The selected analytical plan could not be executed as selected. No fallback answer was returned.',
+        artifacts: [],
+        evaluations: [{
+                id: 'frozen-plan-route-mismatch',
+                label: 'Frozen analytical route',
+                passed: false,
+                severity: 'blocking',
+                message: `The executor reported ${result.resolvedRoute.replaceAll('_', ' ')} after the router froze ${route.replaceAll('_', ' ')}.`,
+                evidence: {
+                    selectedRoute: route,
+                    reportedRoute: result.resolvedRoute,
+                    selectedTier: decision.analyticalCascadeDecision?.selectedTier,
+                    planId: decision.resolvedAnalyticalPlan?.planId,
+                },
+            }],
+    };
+}
+/**
+ * Promote only an explicit host-issued exploratory freeze into the router
+ * decision that will be persisted. This deliberately does not inspect route
+ * names, SQL strings, or identifier patterns: a selected tier is immutable
+ * only when its own candidate set, snapshot, target, and capability receipt
+ * all agree.
+ */
+function applyExploratoryExecutionFreeze(decision, freeze) {
+    if (!freeze)
+        return decision;
+    const cascade = decision.analyticalCascadeDecision;
+    const attempt = cascade?.attempts.find((candidate) => candidate.tier === 'exploratory_sql');
+    const sameCandidates = Boolean(attempt
+        && attempt.candidateIds.length === freeze.candidateIds.length
+        && attempt.candidateIds.every((candidate, index) => candidate === freeze.candidateIds[index]));
+    const retrievalSnapshotId = decision.retrievalEvidence?.snapshotId;
+    const valid = Boolean(cascade
+        && cascade.selectedTier === 'exploratory_sql'
+        && cascade.planFrozen === false
+        && attempt?.outcome === 'executable'
+        && sameCandidates
+        && freeze.version === 1
+        && freeze.selectedTier === 'exploratory_sql'
+        && freeze.authorization === 'capability_minted'
+        && freeze.planId.trim()
+        && freeze.planFingerprint.trim()
+        && freeze.snapshotId.trim()
+        && freeze.targetFingerprint.trim()
+        && freeze.sqlFingerprint.trim()
+        && (!retrievalSnapshotId || retrievalSnapshotId === freeze.snapshotId));
+    if (!valid) {
+        throw Object.assign(new Error('The exploratory execution receipt did not match the router-selected candidate set and was not accepted.'), {
+            code: 'EXPLORATORY_FREEZE_RECEIPT_MISMATCH',
+        });
+    }
+    return {
+        ...decision,
+        analyticalCascadeDecision: {
+            ...cascade,
+            planFrozen: true,
+            exploratoryExecutionFreeze: freeze,
+            attempts: cascade.attempts.map((candidate) => candidate.tier === 'exploratory_sql'
+                ? {
+                    ...candidate,
+                    planFrozen: true,
+                    reason: `${candidate.reason} Host-authorized immutable exploratory execution plan ${freeze.planId}.`,
+                }
+                : candidate),
+        },
+    };
+}
+/**
+ * Has this exact clarification already been asked in this thread?
+ *
+ * The reported loop: "who are the top customers for BCM" returned "Top by which
+ * governed metric?", the user answered in prose, and the IDENTICAL question came
+ * back. Their reply reads as a complete new question — which is a defensible
+ * classification — so it re-entered the cascade fresh, retrieved the same
+ * evidence, and produced the same clarification. Nothing in the loop noticed it
+ * had already been there.
+ *
+ * Asking twice is proof the question does not work: the user has already seen it
+ * and responded, and a third identical prompt cannot produce a different reply.
+ * Whatever the best available interpretation is, committing to it and saying so
+ * beats asking again.
+ */
+function clarificationAlreadyAsked(clarifyingQuestion, history) {
+    const asking = clarifyingQuestion?.replace(/\s+/g, ' ').trim().toLowerCase();
+    if (!asking || !history?.length)
+        return false;
+    let sawAssistantAsk = false;
+    for (const turn of history) {
+        if (turn.role !== 'assistant')
+            continue;
+        if (turn.text.replace(/\s+/g, ' ').trim().toLowerCase().includes(asking))
+            sawAssistantAsk = true;
+    }
+    if (!sawAssistantAsk)
+        return false;
+    // Only a loop once the user has actually replied to it. A clarification still
+    // waiting for its first answer is not a repeat.
+    const lastAsk = [...history].reverse().findIndex((turn) => turn.role === 'assistant' && turn.text.replace(/\s+/g, ' ').trim().toLowerCase().includes(asking));
+    return lastAsk > 0;
+}
 function enforceOrdinaryAnalyticalPlanBoundary(request, decision) {
     const ordinaryAsk = request.requestedMode === undefined
         || request.requestedMode === 'auto'
@@ -1286,24 +1675,58 @@ function enforceOrdinaryAnalyticalPlanBoundary(request, decision) {
         || decision.action === 'block'
         || decision.requiresClarification === true
         || Boolean(decision.terminalOutcome);
-    // A modeling/coverage gap is a pre-freeze discovery result, not permission to
-    // terminate an ordinary Ask. Keep the diagnostic as a typed reason in the
-    // route decision, clear the blocked RAP, and let the answer executor continue
-    // through the governed relational and review-required generated lanes. Policy
-    // blocks and genuine user ambiguity remain terminal. This is the key
-    // governed-first-but-not-governed-only boundary (AGT-028, EXP-001).
+    const inboundRescue = rescueModelingGapForOrdinaryAsk(request, decision);
+    if (inboundRescue)
+        return inboundRescue;
+    // A clarification the user has already seen and answered cannot be asked
+    // again. Checked before the `terminal` guard for the same reason as the
+    // definitional case: the gate has already set `action: 'clarify'` by here.
     if (ordinaryAsk
-        && decision.terminalOutcome?.kind === 'modeling_gap'
-        && decision.requiresClarification !== true
-        && !request.selectedEvidenceId) {
+        && decision.action === 'clarify'
+        && clarificationAlreadyAsked(decision.clarifyingQuestion, request.history?.length ? request.history : conversationHistoryFromContext(request.conversationContext))) {
         return {
             ...decision,
             action: 'answer',
-            confidence: Math.min(decision.confidence, 0.55),
-            reason: `${decision.terminalOutcome.message} Continuing through DBT-grounded relational and review-required generated analysis before asking for a modeling change.`,
+            confidence: Math.min(decision.confidence, 0.6),
+            reason: `This clarification was already asked and answered in this thread, so DQL proceeded with the best supported interpretation instead of repeating it: ${decision.clarifyingQuestion ?? ''}`.trim(),
+            requiresClarification: false,
+            clarifyingQuestion: undefined,
             terminalOutcome: undefined,
             resolvedAnalyticalPlan: undefined,
+        };
+    }
+    // A DEFINITIONAL question about an artifact it names is not an analytical
+    // request, and must be caught before the `terminal` guard below — the
+    // ambiguity gate has already set `action: 'clarify'` by this point, so any
+    // check placed after it is unreachable.
+    //
+    // Without this, "what is food_vs_drink_revenue?" is answered with "Which
+    // governed meaning should DQL bind: food_vs_drink_revenue or …?" — asking the
+    // user to disambiguate the one artifact they just named. The plan cannot see
+    // it because it reads the artifact's OWN NAME as analytical intent: that name
+    // contains "vs", so the mode comes back `comparison`.
+    const namedCertifiedArtifactMetadata = looksLikeNamedCertifiedArtifactMetadataRequest(request.question, decision.retrievalEvidence?.candidateIds ?? []);
+    if (ordinaryAsk
+        && !request.selectedEvidenceId
+        && (namedCertifiedArtifactMetadata
+            || looksLikeDefinitionalAboutNamedObject(request.question, decision.retrievalEvidence?.candidateIds ?? []))) {
+        return {
+            ...decision,
+            // Only this explicit selected-block grammar has an artifact-local,
+            // deterministic metadata result. Broader definition wording remains
+            // conversational so a metric phrase cannot acquire certified trust just
+            // because a similarly named block was retrieved.
+            action: namedCertifiedArtifactMetadata ? 'answer' : 'converse',
+            category: namedCertifiedArtifactMetadata ? 'data_lookup' : 'conversational',
+            confidence: 1,
+            reason: namedCertifiedArtifactMetadata
+                ? 'This asks what one selected certified artifact means, so its artifact metadata is returned without running a query.'
+                : 'This asks what a governed artifact means, so it is answered from its definition rather than by running a query.',
             requiresClarification: false,
+            clarifyingQuestion: undefined,
+            clarificationOptions: undefined,
+            terminalOutcome: undefined,
+            resolvedAnalyticalPlan: undefined,
         };
     }
     const exactSemanticContinuation = Boolean(request.selectedEvidenceId
@@ -1368,7 +1791,7 @@ function enforceOrdinaryAnalyticalPlanBoundary(request, decision) {
     if (!analytical)
         return decision;
     const message = 'DQL could not freeze an exact analytical plan for the requested metric, grain, filters, ordering, and outputs. Choose a governed identifier or model the missing capability before retrying.';
-    return {
+    const blocked = {
         ...decision,
         action: 'block',
         confidence: 1,
@@ -1381,9 +1804,40 @@ function enforceOrdinaryAnalyticalPlanBoundary(request, decision) {
             candidateIds: decision.retrievalEvidence?.candidateIds ?? [],
         },
     };
+    // The block synthesized HERE is a modeling gap too, so it must face the same
+    // rescue as one arriving from the router. Without this, the rescue above
+    // silently did not apply to the most common way an ordinary Ask gets blocked:
+    // retrieval found governed candidates, no exact tuple froze, and the run
+    // dead-ended instead of continuing to the generated lane.
+    return rescueModelingGapForOrdinaryAsk(request, blocked, { requireGovernedEvidence: true }) ?? blocked;
 }
-function softBoundaryResult(route, budget) {
+function softBoundaryResult(route, budget, priorArtifacts = []) {
     const seconds = Math.round(budget.softTargetMs(route) / 1_000);
+    // Admission control must never turn work that already validated into a
+    // refusal. A run that established findings and then ran out of clock has
+    // something true to say; answering `blocked` discards it and asks the user
+    // to start the same investigation over. Partial and labelled beats nothing.
+    const established = priorArtifacts.filter((artifact) => artifact.trustState !== "blocked" && artifact.trustState !== "not_applicable");
+    if (established.length > 0) {
+        const titles = established.map((artifact) => artifact.title).filter((title) => Boolean(title));
+        const named = titles.length === 1
+            ? titles[0]
+            : `${titles.slice(0, -1).join(", ")} and ${titles[titles.length - 1]}`;
+        const plural = established.length === 1;
+        return {
+            resolvedRoute: route,
+            status: "needs_review",
+            trustState: "review_required",
+            stopReason: "human_review_required",
+            summary: `The ${seconds}-second discovery target elapsed. Returning what was established rather than discarding it.`,
+            answer: titles.length > 0
+                ? `The discovery window ended before the whole question was covered, so this is partial: ${named}. ${plural ? "It was" : "They were"} validated before the clock ran out; nothing beyond ${plural ? "it" : "them"} was investigated. Continue to pick up from here.`
+                : `The discovery window ended before the whole question was covered. ${established.length} validated finding${plural ? "" : "s"} from this run ${plural ? "is" : "are"} attached; nothing beyond ${plural ? "it" : "them"} was investigated.`,
+            artifacts: [...established],
+            evaluations: [],
+            nextActions: [{ id: "continue-after-soft-target", label: "Continue the investigation" }],
+        };
+    }
     return {
         resolvedRoute: 'clarify',
         status: 'needs_clarification',
@@ -1594,6 +2048,42 @@ function diagnosticReceiptV2ForRun(run) {
         ...(run.repairCapability ? { repairCapabilityFingerprint: receiptFingerprint(run.repairCapability) } : {}),
     };
 }
+/**
+ * Build a compact V3 receipt from existing durable run state. It intentionally
+ * records identifiers and outcomes, never raw metadata, result rows, provider
+ * payloads, or secret-bearing URLs.
+ */
+function diagnosticReceiptV3ForRun(run) {
+    // The router is the sole cascade authority. Do not reconstruct a tier from
+    // route names or identifier text here: that erased stale/error lane states
+    // and falsely reported governed-relational success for pure exploration.
+    const cascade = run.routeDecision?.analyticalCascadeDecision;
+    const sourceCoverage = cascade?.sourceCoverage ?? [];
+    const planFrozen = cascade?.planFrozen ?? false;
+    const artifactProviderDiagnostic = run.artifacts
+        .map((artifact) => artifact.payload)
+        .filter((payload) => Boolean(payload) && typeof payload === 'object' && !Array.isArray(payload))
+        .map((payload) => payload.providerFailure)
+        .find((failure) => Boolean(failure) && typeof failure === 'object' && !Array.isArray(failure));
+    const persistedProviderDiagnostic = artifactProviderDiagnostic?.diagnostic;
+    const provider = persistedProviderDiagnostic && typeof persistedProviderDiagnostic === 'object'
+        ? persistedProviderDiagnostic
+        : (() => {
+            const failure = run.diagnosticReceipt?.failure;
+            return failure && (failure.code === 'AI_PROVIDER_FAILURE' || /provider/i.test(failure.code))
+                ? classifyProviderFailure({ message: failure.message, code: failure.code, phase: 'generation' })
+                : undefined;
+        })();
+    return {
+        version: 3,
+        runId: run.id,
+        sourceCoverage,
+        ...(cascade ? { cascade } : {}),
+        planFrozen,
+        ...(provider ? { provider } : {}),
+        finalStopReason: run.stopReason,
+    };
+}
 function emptyRunTelemetry(total, fallbackReason) {
     return {
         version: 1,
@@ -1619,7 +2109,7 @@ function durationBetweenMs(startedAt, completedAt) {
 function receiptFingerprint(value) {
     return createHash('sha256').update(JSON.stringify(value)).digest('hex');
 }
-function attachDiagnosticReceipt(artifacts, receipt, receiptV2) {
+function attachDiagnosticReceipt(artifacts, receipt, receiptV2, receiptV3) {
     if (artifacts.length === 0) {
         if (!receipt.failure)
             return artifacts;
@@ -1628,7 +2118,7 @@ function attachDiagnosticReceipt(artifacts, receipt, receiptV2) {
                 kind: "answer",
                 title: "Agent run diagnostics",
                 trustState: "blocked",
-                payload: { diagnosticReceipt: receipt, ...(receiptV2 ? { diagnosticReceiptV2: receiptV2 } : {}) },
+                payload: { diagnosticReceipt: receipt, ...(receiptV2 ? { diagnosticReceiptV2: receiptV2 } : {}), ...(receiptV3 ? { diagnosticReceiptV3: receiptV3 } : {}) },
             }];
     }
     const preferredIndex = Math.max(0, artifacts.findIndex((artifact) => artifact.kind === "answer"));
@@ -1644,6 +2134,7 @@ function attachDiagnosticReceipt(artifacts, receipt, receiptV2) {
                 ...payload,
                 diagnosticReceipt: receipt,
                 ...(receiptV2 ? { diagnosticReceiptV2: receiptV2 } : {}),
+                ...(receiptV3 ? { diagnosticReceiptV3: receiptV3 } : {}),
             },
         };
     });
@@ -1880,6 +2371,9 @@ export function selectRoute(request, decision) {
             return 'clarify';
         return 'blocked';
     }
+    const cascadeRoute = routeFromAnalyticalCascade(decision);
+    if (cascadeRoute)
+        return cascadeRoute;
     const explicitMode = request.requestedMode;
     if (explicitMode === 'modeling')
         return 'modeling_draft';