@duckcodeailabs/dql-cli 1.12.3 → 1.12.5

package/dist/local-runtime.js

@@ -20,7 +20,8 @@ import { fetchLatestPublishedDqlVersion, resolveDqlRuntimeVersionStatus } from '
 import { resolveRetrievalHealthStatus } from './retrieval-health.js';
 import { createDqlAgentProviderRunner, resolveAgentFollowUpContext } from './llm/providers/dql-agent-provider.js';
 import { listRemoteMcpSettings, saveRemoteMcpSettings } from './llm/mcp-config.js';
-import { ClaudeProvider, ConversationStore, advanceThreadState, buildConversationSnapshot, conversationHistoryFromContext, recallRelevantTurns, renderConversationEnvelopeForPrompt, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildAnalysisQuestionPlan, composeSemanticQueryForQuestion, aggregationIntegrityIssuesForSql, buildLocalContextPack, applyContextPackCompatibility, toAgentRetrievalEvidence, prepareConversationPath, defaultMemoryPath, ensureDefaultMemoryFiles, ensureAgentProjectReady, isAgentProjectIndexReady, currentMetadataFingerprint, ensureMetadataCatalogFresh, readIndexedDomainKnowledge, readIndexedKnowledge360, compactSemanticRuntimeFailure, classifyAnalyticalFailure, propose, proposePlan, recordGovernedCorrection, HintStore, defaultHintIndexPath, ensureHintIndexFresh, listHintsFromGit, getHintEvaluationFromGit, getCorrectionTraceFromGit, inspectGovernedHint, editGovernedHintCandidate, reopenGovernedHint, retireHint, supersedeHint, hintsConflict, mineJoinPatterns, reviewGovernedHint, AgentRunEngine, SqliteAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, createHybridRouter, computeResultStats, buildDeterministicDashboardStory, synthesizeAnswer, streamOrGenerate, narrateResult, buildProposePreview, buildFromPrompt, internalRelationIdsInSql, defaultAgentRunStorePath, defaultAgentRunSqlitePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, latestRuntimeSchemaSnapshotForProject, loadSkills, migrateLegacySkills, configuredSkillsPath, skillsDir, draftDomainSkillBootstrap, buildDomainSkillBootstrapPrompt, mergeDomainSkillBootstrapEnrichment, writeSkill, deleteSkill, deriveGeneratedDraftSlug, deriveAnalyticalRepair, reindexProject, invalidateAgentProjectState, recordAgentRuntimeVersion, resolveDomainContextEnvelope, projectEmbeddingProvider, isHashedEmbeddingProvider, clearProjectEmbeddingCache, upgradeVectorIndexForProject, openMetadataCatalog, defaultKgPath, planAppFromPrompt, KGStore, planResearch, loadSemanticMetrics, cascadeTraceToEvidenceRouteSteps, createCascadeAnswerResult, createCascadeTrace, routeReasoningEffort, routeForCascadeAnswerTier, clampReasoningEffort, bumpReasoningEffort, resolveThinkingMode, coerceThinkingMode, upsertGeneratedDqlArtifactDraft, loadAgentSemanticLayer, } from '@duckcodeailabs/dql-agent';
+import { ClaudeProvider, ConversationStore, advanceThreadState, buildConversationSnapshot, conversationHistoryFromContext, recallRelevantTurns, renderConversationEnvelopeForPrompt, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildAnalysisQuestionPlan, composeSemanticQueryForQuestion, aggregationIntegrityIssuesForSql, buildLocalContextPack, applyContextPackCompatibility, toAgentRetrievalEvidence, prepareConversationPath, defaultMemoryPath, ensureDefaultMemoryFiles, ensureAgentProjectReady, isAgentProjectIndexReady, currentMetadataFingerprint, ensureMetadataCatalogFresh, readIndexedDomainKnowledge, readIndexedKnowledge360, compactSemanticRuntimeFailure, classifyAnalyticalFailure, propose, proposePlan, recordGovernedCorrection, HintStore, defaultHintIndexPath, ensureHintIndexFresh, listHintsFromGit, getHintEvaluationFromGit, getCorrectionTraceFromGit, inspectGovernedHint, editGovernedHintCandidate, reopenGovernedHint, retireHint, supersedeHint, hintsConflict, mineJoinPatterns, reviewGovernedHint, AgentRunEngine, SqliteAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, createHybridRouter, computeResultStats, buildDeterministicDashboardStory, synthesizeAnswer, streamOrGenerate, narrateResult, buildProposePreview, buildFromPrompt, internalRelationIdsInSql, defaultAgentRunStorePath, defaultAgentRunSqlitePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, latestRuntimeSchemaSnapshotForProject, loadSkills, migrateLegacySkills, configuredSkillsPath, skillsDir, draftDomainSkillBootstrap, buildDomainSkillBootstrapPrompt, mergeDomainSkillBootstrapEnrichment, writeSkill, deleteSkill, deriveGeneratedDraftSlug, deriveAnalyticalRepair, reindexProject, invalidateAgentProjectState, recordAgentRuntimeVersion, resolveDomainContextEnvelope, projectEmbeddingProvider, isHashedEmbeddingProvider, clearProjectEmbeddingCache, upgradeVectorIndexForProject, openMetadataCatalog, defaultKgPath, planAppFromPrompt, KGStore, planResearch, loadSemanticMetrics, cascadeTraceToEvidenceRouteSteps, createCascadeAnswerResult, createCascadeTrace, routeReasoningEffort, routeForCascadeAnswerTier, clampReasoningEffort, bumpReasoningEffort, resolveThinkingMode, coerceThinkingMode, upsertGeneratedDqlArtifactDraft, loadAgentSemanticLayer, isTrustedConversationTurn, analyticalError, withAnalyticalErrorOrigin, withAnalyticalErrorOriginSync, } from '@duckcodeailabs/dql-agent';
+import { addSqlResultFilter, filterableResultColumns, replaceBlockStudioSql } from './sql-result-filter.js';
 import { gatherProposeEnrichment } from './propose-enrich.js';
 import { handleAppsApi, proposeAppAiBuild, recommendVisualization } from './apps-api.js';
 import { getActiveProvider, getEffectiveProviderConfig, isProviderSettingsId, listProviderSettings, saveProviderSettings, } from './settings/provider-settings.js';
@@ -435,6 +436,9 @@ async function conversationContextFromThread(store, threadId, clientContext, que
             trustLabel: turn.trustLabel,
             runStatus: turn.runStatus,
             stopReason: turn.stopReason,
+            // Carried so every consumer can compute trust from the same fields.
+            refusalCode: turn.refusalCode,
+            executionError: turn.executionError,
             certification: turn.certification,
             contextPackId: turn.contextPackId,
             dqlArtifact: turn.dqlArtifact,
@@ -473,9 +477,30 @@ async function conversationContextFromThread(store, threadId, clientContext, que
         ...(serverSnapshot ? { conversationEnvelope: serverSnapshot } : {}),
         ...(serverSnapshot ? { serverSnapshot } : {}),
         ...(thread?.rollingSummary ? { conversationSummary: thread.rollingSummary } : {}),
-        ...(turns.length > 0 ? { turns, activeTurnId: turns[turns.length - 1].id } : {}),
+        // `activeTurnId` is the FOLLOW-UP ANCHOR: the turn whose filters, prior DQL
+        // artifact, and source SQL the next question builds on. Anchoring it to the
+        // last turn unconditionally meant a failed turn became the anchor, and its
+        // broken artifact and failing SQL were handed to the next question as
+        // authoritative context — the sticky-error loop. `latestTurnId` keeps the
+        // real tail for presentation.
+        ...(turns.length > 0
+            ? {
+                turns,
+                activeTurnId: lastTrustedTurnId(turns) ?? undefined,
+                latestTurnId: turns[turns.length - 1].id,
+            }
+            : {}),
     };
 }
+/** The most recent turn a follow-up may safely build on. */
+function lastTrustedTurnId(turns) {
+    for (let index = turns.length - 1; index >= 0; index -= 1) {
+        const turn = turns[index];
+        if (isTrustedConversationTurn(turn))
+            return turn.id;
+    }
+    return undefined;
+}
 /** Best-effort: persist a completed run as a conversation turn (never throws). */
 function recordConversationTurn(store, threadId, run) {
     if (!store || !threadId)
@@ -489,8 +514,12 @@ function recordConversationTurn(store, threadId, run) {
         // turn folding its (possibly misparsed) filters and measures into working
         // state poisoned every subsequent ask: the SAME question that worked once
         // then failed forever because the bad turn's phantom state carried forward.
-        const producedAnswer = run.status === 'completed' || run.status === 'needs_review';
-        if (producedAnswer)
+        //
+        // The previous guard tested `run.status`, which cannot express this: a
+        // grounding-gap refusal and a perfectly good uncertified answer are BOTH
+        // `needs_review`, so the guard admitted exactly the failures its comment
+        // was written to exclude. Trust is now derived from answer state.
+        if (isTrustedConversationTurn(turn))
             advanceThreadState(store, threadId, turn);
     }
     catch {
@@ -529,6 +558,11 @@ export function conversationTurnInputFromRun(run) {
         trustLabel: agentRunString(payload?.trustLabel) ?? run.trustState,
         runStatus: run.status,
         stopReason: run.stopReason,
+        // Persisted so a later turn can tell a refusal from an answer. `runStatus`
+        // alone cannot: a grounding gap and a good uncertified answer are both
+        // `needs_review`.
+        refusalCode: agentRunString(payload?.refusalCode),
+        executionError: agentRunString(payload?.executionError),
         certification: agentRunString(payload?.certification),
         sourceCertifiedBlock: agentRunString(payload?.sourceCertifiedBlock)
             ?? (artifact?.kind === 'answer' ? agentRunString(artifact.ref) : undefined),
@@ -1542,6 +1576,7 @@ export async function startLocalServer(opts) {
             getSchemaContext: (question, preparedContextPack) => getSchemaContextForAgent(question, preparedContextPack, semanticConnection, request.executionTarget?.target === 'connection'
                 ? request.executionTarget.connectionName
                 : undefined),
+            probeNamedRelations: (relations) => probeNamedRelationsForAgent(relations, semanticConnection),
         }, (turn) => {
             if (turn.kind === 'thinking')
                 onProgress?.(turn.text);
@@ -1927,7 +1962,7 @@ export async function startLocalServer(opts) {
                 ],
             };
         }
-        const resolvedRoute = resolvedRunRouteFromAnswer(governedAnswer) ?? route;
+        const answeredRoute = resolvedRunRouteFromAnswer(governedAnswer) ?? route;
         const isCertified = governedAnswer.certification === 'certified' || governedAnswer.kind === 'certified';
         const isSemantic = governedAnswer.route?.tier === 'semantic_metric';
         const requestedNotebookDataset = findMentionedNotebookDataset(request.question, datasetWorkspace.list());
@@ -1958,6 +1993,12 @@ export async function startLocalServer(opts) {
         // provider outages are blocked so the UI can offer an explicit retry.
         const needsClarification = governedAnswer.kind === 'no_answer'
             && !isGroundingGap && !isProviderError && !isModelDeclined && !isPolicyBlocked;
+        // A run that ASKED THE USER A QUESTION is a clarify turn, whatever route it
+        // would have taken had it answered. Persisting the resolved analytical route
+        // instead (`generated_answer`) meant the engine's clarification-continuation
+        // lookup — which matches on `route === 'clarify'` — never found it, so the
+        // reply ran context-free and was clarified again: the reported clarify loop.
+        const resolvedRoute = needsClarification ? 'clarify' : answeredRoute;
         const sql = governedAnswer.proposedSql ?? governedAnswer.sql;
         const runnableSql = governedAnswer.kind === 'no_answer' || isExecutionFailure || (isExploratory && !governedAnswer.result)
             ? undefined
@@ -2002,31 +2043,45 @@ export async function startLocalServer(opts) {
                 synthesizedAnswer = undefined;
             }
         }
+        // A grounding/modeling gap is a REFUSAL. It was computed above but never
+        // reached this ternary, so it fell through to `needs_review` — the same
+        // status as a perfectly good uncertified answer. Every downstream trust
+        // check then treated the refusal as a usable turn, which is how one failed
+        // answer poisoned every later question in the thread.
         const status = isTerminalFailure
             ? 'blocked'
             : needsClarification
                 ? 'needs_clarification'
-                : isCertified || isSemantic
-                    ? 'completed'
-                    : 'needs_review';
+                : isGroundingGap || isModelDeclined
+                    ? 'blocked'
+                    : isCertified || isSemantic
+                        ? 'completed'
+                        : 'needs_review';
         const trustState = isTerminalFailure
             ? 'blocked'
             : needsClarification
                 ? 'not_applicable'
-                : isCertified
-                    ? 'certified'
-                    : isSemantic
-                        ? 'governed'
-                        : 'review_required';
+                : isGroundingGap || isModelDeclined
+                    ? 'blocked'
+                    : isCertified
+                        ? 'certified'
+                        : isSemantic
+                            ? 'governed'
+                            : 'review_required';
         const stopReason = isTerminalFailure
             ? 'blocked'
             : needsClarification
                 ? 'needs_clarification'
-                : isCertified
-                    ? 'certified_answer_found'
-                    : isSemantic
-                        ? 'governed_semantic_answer'
-                        : 'human_review_required';
+                // A gap is terminal, but it is NOT a provider outage: it still owes the
+                // user its evidence trace, and its next-actions below stay the
+                // grounding-gap set rather than "retry the provider".
+                : isGroundingGap || isModelDeclined
+                    ? 'human_review_required'
+                    : isCertified
+                        ? 'certified_answer_found'
+                        : isSemantic
+                            ? 'governed_semantic_answer'
+                            : 'human_review_required';
         const terminalFailureActions = governedAnswer.analyticalFailure
             ? governedAnswer.analyticalFailure.code === 'PERMISSION_DENIED'
                 ? [{ id: 'repair-access', label: 'Change connection or request access', route: 'blocked' }]
@@ -2172,33 +2227,43 @@ export async function startLocalServer(opts) {
         const kind = routeDecision?.conversationalKind ?? 'smalltalk';
         const isGeneralKnowledge = routeDecision?.category === 'general_knowledge';
         const answerKind = isGeneralKnowledge ? 'general_knowledge' : 'conversational';
-        const catalogContext = buildAgentRunCatalogContext();
+        const catalogContext = kind === 'answer_explanation' ? '' : buildAgentRunCatalogContext();
         const suggestions = buildConversationSuggestions(projectRoot, kind);
         const nextActions = suggestions.map((prompt, index) => ({
             id: `suggest-question-${index + 1}`,
             label: prompt,
         }));
-        let text;
-        try {
-            const provider = await createBlockStudioAssistProvider(projectRoot);
-            if (provider) {
-                const system = buildConversationSystemPrompt(kind, isGeneralKnowledge, catalogContext, request.audience ?? 'analyst');
-                const conversationMemory = renderConversationMemoryForPrompt(request.conversationContext);
-                const messages = [
-                    { role: 'system', content: system },
-                    ...(conversationMemory ? [{ role: 'system', content: conversationMemory }] : []),
-                    ...(request.history ?? []).slice(-6).map((message) => ({ role: message.role, content: message.text })),
-                    { role: 'user', content: request.question },
-                ];
-                text = (await provider.generate(messages, { maxTokens: 320, temperature: 0.6 })).trim();
-                // Perceived-latency: surface the reply as one delta for surfaces wired to stream.
-                if (text)
-                    emitAnswerDelta?.(text);
-            }
+        // A question about the latest answer is an evidence lookup, not another
+        // warehouse run. Resolve it from the persisted artifact contract before
+        // considering a provider-generated conversational reply.
+        let text = kind === 'answer_explanation'
+            ? buildPriorAnswerExplanation(request.question, request.conversationContext)
+            : undefined;
+        if (text) {
+            emitAnswerDelta?.(text);
         }
-        catch {
-            // Provider unavailable / errored — fall through to the deterministic reply.
-            text = undefined;
+        else {
+            try {
+                const provider = await createBlockStudioAssistProvider(projectRoot);
+                if (provider) {
+                    const system = buildConversationSystemPrompt(kind, isGeneralKnowledge, catalogContext, request.audience ?? 'analyst');
+                    const conversationMemory = renderConversationMemoryForPrompt(request.conversationContext);
+                    const messages = [
+                        { role: 'system', content: system },
+                        ...(conversationMemory ? [{ role: 'system', content: conversationMemory }] : []),
+                        ...(request.history ?? []).slice(-6).map((message) => ({ role: message.role, content: message.text })),
+                        { role: 'user', content: request.question },
+                    ];
+                    text = (await provider.generate(messages, { maxTokens: 320, temperature: 0.6 })).trim();
+                    // Perceived-latency: surface the reply as one delta for surfaces wired to stream.
+                    if (text)
+                        emitAnswerDelta?.(text);
+                }
+            }
+            catch {
+                // Provider unavailable / errored — fall through to the deterministic reply.
+                text = undefined;
+            }
         }
         if (!text) {
             text = buildConversationContextRecap(request.conversationContext)
@@ -2206,7 +2271,7 @@ export async function startLocalServer(opts) {
             emitAnswerDelta?.(text);
         }
         return {
-            summary: 'Replied conversationally.',
+            summary: kind === 'answer_explanation' ? 'Explained the previous answer.' : 'Replied conversationally.',
             answer: text,
             answerKind,
             status: 'completed',
@@ -2715,6 +2780,9 @@ export async function startLocalServer(opts) {
         const serverSnapshot = agentRunRecord(request.conversationContext?.conversationEnvelope
             ?? request.conversationContext?.serverSnapshot);
         const topicRelation = agentRunString(serverSnapshot?.topicRelation);
+        const workspaceSurface = agentRunWorkspaceValue(request, 'surface');
+        const blockAuthoringContext = request.requestedMode === 'block'
+            || workspaceSurface === 'block-studio';
         // The readiness marker is source-versioned. When it matches, pass the
         // already-built metadata identity into retrieval so buildLocalContextPack
         // opens the immutable snapshot directly instead of rebuilding all metadata
@@ -2737,6 +2805,8 @@ export async function startLocalServer(opts) {
         const task = buildLocalContextPack(projectRoot, {
             question: request.question,
             focusObjectKey: request.selectedEvidenceId,
+            mode: blockAuthoringContext ? 'build' : 'question',
+            includeDraftBlocks: blockAuthoringContext,
             followUp,
             priorContextPackId: agentRunString(request.conversationContext?.contextPackId),
             conversationTopicRelation: topicRelation === 'continuation'
@@ -2750,7 +2820,9 @@ export async function startLocalServer(opts) {
             reusePolicy: 'seed',
             preparedMetadataFingerprint,
             ...(runtimeSchemaSnapshot ? { runtimeSchemaSnapshot } : {}),
-            surface: 'notebook',
+            surface: blockAuthoringContext
+                ? 'block'
+                : workspaceSurface ?? 'notebook',
             selectedContext: {
                 selectedObject: request.selectedObject,
                 workspaceContext: request.workspaceContext,
@@ -3021,43 +3093,55 @@ export async function startLocalServer(opts) {
         });
     };
     const executeDqlArtifactSourceForAgent = async (source, metadata = {}, invocationInput, executionConnection, executionConnectionName) => {
-        const invocation = prepareBlockInvocation({
+        // Everything from here to the executor call is DQL's OWN block compiler:
+        // parse, parameter resolution, plan build, semantic compose. A failure in
+        // any of it means DQL could not rebuild its artifact — the warehouse was
+        // never contacted. Tagging the origin here stops the answer loop from
+        // reporting these as "the generated SQL failed to execute".
+        const invocation = withAnalyticalCompilationOrigin('bind', () => prepareBlockInvocation({
             source,
             parameters: invocationInput?.parameters,
             parameterSources: invocationInput?.parameterSources,
             question: invocationInput?.question,
             surface: 'ask_ai',
-        });
-        if (invocation.errors.length > 0)
-            throw new Error(invocation.errors.join(' '));
+        }));
+        if (invocation.errors.length > 0) {
+            throw analyticalError(invocation.errors.join(' '), { origin: 'dql_compilation', stage: 'compile' });
+        }
         if (invocation.unresolvedParameters.length > 0) {
-            throw new Error(`I need values for: ${invocation.unresolvedParameters.join(', ')}.`);
+            throw analyticalError(`I need values for: ${invocation.unresolvedParameters.join(', ')}.`, {
+                origin: 'dql_compilation',
+                stage: 'bind',
+                code: 'unresolved_parameter',
+                offending: { parameter: invocation.unresolvedParameters[0] },
+            });
         }
         const activeConnection = requireActiveConnection(executionConnection);
         const precompiledSemanticQuery = Boolean(extractBlockStudioSql(source));
         const tableMapping = !precompiledSemanticQuery
             ? await resolveSemanticTableMapping(executor, activeConnection, semanticLayer, projectRoot, executionConnectionName)
             : undefined;
-        const semanticCompose = semanticLayer
-            ? await composeSemanticBlockSqlForRuntime(source, semanticLayer, {
+        const composeLayer = semanticLayer;
+        const semanticCompose = composeLayer
+            ? await withAnalyticalErrorOrigin({ origin: 'dql_compilation', stage: 'compile' }, () => composeSemanticBlockSqlForRuntime(source, composeLayer, {
                 driver: activeConnection.driver,
                 tableMapping,
                 projectRoot,
                 projectConfig,
                 detectedProvider: semanticDetectedProvider,
                 parameters: invocation.values,
-            })
+            }))
             : null;
-        const plan = buildExecutionPlan({ id: `agent-${metadata.name ?? 'dql-artifact'}`, type: 'dql', source, title: metadata.name ?? 'DQL artifact' }, {
+        const plan = withAnalyticalCompilationOrigin('compile', () => buildExecutionPlan({ id: `agent-${metadata.name ?? 'dql-artifact'}`, type: 'dql', source, title: metadata.name ?? 'DQL artifact' }, {
             semanticLayer,
             driver: activeConnection.driver,
             tableMapping,
             parameters: invocation.values,
             semanticSql: semanticCompose?.sql ?? undefined,
-        });
+        }));
         if (!plan && !semanticCompose?.sql) {
             const semanticError = semanticCompose?.diagnostics.find((diagnostic) => diagnostic.severity === 'error')?.message;
-            throw new Error(semanticError ?? `DQL artifact "${metadata.name ?? 'draft'}" produced no executable SQL.`);
+            throw analyticalError(semanticError ?? `DQL artifact "${metadata.name ?? 'draft'}" produced no executable SQL.`, { origin: 'dql_compilation', stage: 'compile' });
         }
         const prepared = prepareLocalExecution(semanticCompose?.sql ?? plan.sql, activeConnection, projectRoot, projectConfig);
         const executionSql = invocationInput?.rowLimit
@@ -3176,9 +3260,164 @@ export async function startLocalServer(opts) {
             },
         };
     };
+    /**
+     * Build the reusable DQL artifact for an answer that HAS ALREADY EXECUTED,
+     * and check that it recompiles.
+     *
+     * AGT-010 requires the attached artifact to be the one used for execution, so
+     * that "Apply" cannot diverge from what Ask displayed. The old code satisfied
+     * that invariant backwards: it made EXECUTION follow the artifact, routing the
+     * model's SQL through `parameterizeSqlForDqlImport` → `candidateToDqlSource` →
+     * the DQL parser → `processSQL` before running anything. Every one of those
+     * stages could fail on SQL the warehouse would have accepted, and each failure
+     * destroyed the whole answer.
+     *
+     * Now the executed string is the source of truth and the artifact is derived
+     * from it. Building the artifact is a SAVE concern, so a failure here degrades
+     * the artifact to review-required and never throws: the user still gets their
+     * answer, and only "Save as block" is affected.
+     */
+    const buildVerifiedGeneratedArtifact = (question, sql, executedSql, seed, warnings, resultColumns = [], dialect = 'duckdb') => {
+        // Which result columns the user may promote to a filter input. Decided here
+        // because it needs a real dialect parse of the SQL that actually ran.
+        const filterableColumns = resultColumns.length > 0
+            ? filterableResultColumns(executedSql, resultColumns, dialect)
+            : [];
+        const withCandidates = (artifact) => (filterableColumns.length > 0 ? { ...artifact, filterableColumns } : artifact);
+        let artifact;
+        try {
+            artifact = generatedSqlArtifactContract(question, sql, seed);
+        }
+        catch (error) {
+            warnings.push(`This answer could not be captured as a reusable DQL block: ${apiErrorMessage(error)}`);
+            return undefined;
+        }
+        try {
+            const invocation = prepareBlockInvocation({ source: artifact.source, question, surface: 'ask_ai' });
+            const divergence = invocation.errors.length > 0
+                ? invocation.errors.join(' ')
+                : invocation.unresolvedParameters.length > 0
+                    ? `it still needs values for ${invocation.unresolvedParameters.join(', ')}`
+                    : undefined;
+            if (divergence) {
+                warnings.push(`The reusable DQL block for this answer needs review before reuse: ${divergence}`);
+                // Keep the declared parameter contract even when the block cannot run
+                // as-is. This branch is precisely "it still needs values for X", so the
+                // parameter-input surface needs the list in order to ASK for them —
+                // dropping it would leave the user a review-required block with no way
+                // to see, or supply, what it wants.
+                return withCandidates({
+                    ...artifact,
+                    trustState: 'review_required',
+                    compiledSql: executedSql,
+                    ...(invocation.parameters.length > 0 ? { parameters: invocation.parameters } : {}),
+                    ...(Object.keys(invocation.values).length > 0 ? { parameterValues: invocation.values } : {}),
+                });
+            }
+            return withCandidates({
+                ...artifact,
+                compiledSql: executedSql,
+                ...(invocation.parameters.length > 0 ? { parameters: invocation.parameters } : {}),
+                ...(Object.keys(invocation.values).length > 0 ? { parameterValues: invocation.values } : {}),
+            });
+        }
+        catch (error) {
+            warnings.push(`The reusable DQL block for this answer needs review before reuse: ${apiErrorMessage(error)}`);
+            return withCandidates({ ...artifact, trustState: 'review_required', compiledSql: executedSql });
+        }
+    };
+    /**
+     * Execute the model's SQL EXACTLY as validated — the same way a notebook cell
+     * runs it. This is the fix for "the query Ask generated fails in Ask but runs
+     * in the notebook": both paths now reach `executor.executeQuery` with the same
+     * string, so the only remaining reasons to differ are the connection and the
+     * governance gates, both of which report themselves honestly.
+     */
+    const executeGeneratedSqlDirect = async (question, sql, seed, executionConnection) => {
+        const activeConnection = requireActiveConnection(executionConnection);
+        const rowBound = clampAnalyticalRowBound(seed?.limit ?? 200);
+        const trimmed = sql.trim().replace(/;\s*$/, '').trim();
+        if (!trimmed)
+            throw analyticalError('The generated SQL was empty.', { origin: 'host', stage: 'execute' });
+        // RESOLVE FIRST, VALIDATE SECOND. Executing verbatim means executing the
+        // statement the notebook would execute — and the notebook resolves
+        // `@metric()` / `@dim()` refs and dbt macros before it runs anything.
+        // Skipping that here made Ask fail on semantic refs and MetricFlow
+        // (`metric_time`) queries the notebook runs fine, and validating the raw
+        // model SQL first meant `source::` identities and macro-shaped text were
+        // rejected before the step that would have resolved them ever ran.
+        const semanticMapping = semanticLayer && hasStandaloneSemanticRef(trimmed)
+            ? await resolveSemanticTableMapping(executor, activeConnection, semanticLayer, projectRoot)
+            : undefined;
+        const semantic = semanticLayer
+            ? prepareSemanticSql(trimmed, semanticLayer, { tableMapping: semanticMapping })
+            : { sql: trimmed, unresolvedRefs: [], semanticRefs: undefined };
+        if (semantic.unresolvedRefs.length > 0) {
+            throw analyticalError(`Unknown semantic reference${semantic.unresolvedRefs.length > 1 ? 's' : ''}: ${semantic.unresolvedRefs.join(', ')}`, { origin: 'dql_compilation', stage: 'compile', code: 'semantic_ref' });
+        }
+        const prepared = prepareLocalExecution(semantic.sql, activeConnection, projectRoot, projectConfig);
+        // Read-only enforcement runs on the statement that will ACTUALLY execute.
+        const readOnlyError = readOnlySqlValidationError(prepared.sql, 'Generated SQL', activeConnection.driver);
+        if (readOnlyError) {
+            throw analyticalError(readOnlyError, { origin: 'governance_gate', stage: 'validation', code: 'unsafe_sql' });
+        }
+        const bounded = buildRowBoundedSql(prepared.sql, rowBound, activeConnection.driver);
+        const app = loadRuntimeApp(projectRoot, activePersonaAppId());
+        // Generated SQL is governed as 'uncategorized' unless its seed declares a
+        // domain — the same value `generatedSqlArtifactContract` stamps into the
+        // block source. Falling through to `app.domain` instead would evaluate the
+        // policy against the app's OWN domain and could allow a query the previous
+        // release denied; a governance boundary must not move as a side effect.
+        const sourceDomain = seed?.source?.match(/\bdomain\s*=\s*"([^"]+)"/i)?.[1] ?? 'uncategorized';
+        assertAppAccess({ app, domain: sourceDomain, level: 'execute' });
+        // A semantic query the loop already compiled (MetricFlow / dbt Cloud) must
+        // execute through its pinned target binding, not as loose SQL.
+        const pinnedSemanticCompile = compiledSemanticQueries.get(executionFingerprint(prepared.sql))
+            ?? compiledSemanticQueries.get(executionFingerprint(trimmed));
+        const semanticExecution = pinnedSemanticCompile
+            ? await executeTargetBoundSemanticQuery({
+                executor,
+                connection: activeConnection,
+                projectRoot,
+                plannedAdapter: pinnedSemanticCompile.engine,
+                metricFlow: pinnedSemanticCompile.engine === 'metricflow-cli'
+                    ? resolveMetricFlowTargetMetadata(projectRoot, projectConfig)
+                    : undefined,
+                compile: async () => pinnedSemanticCompile,
+                prepareSql: () => ({ sql: bounded.sql, connection: prepared.connection }),
+                rowBound,
+            })
+            : null;
+        const rawResult = semanticExecution?.result
+            ?? await executor.executeQuery(bounded.sql, [], runtimeVariables({}), prepared.connection);
+        const normalized = normalizeQueryResult(rawResult, semantic.semanticRefs);
+        // The authoritative bound. `buildRowBoundedSql` may legitimately decline to
+        // touch the statement, and only one of 15 drivers honours a maxRows hint, so
+        // the host is the only layer correctness may depend on.
+        const truncated = normalized.rows.length > rowBound;
+        const rows = truncated ? normalized.rows.slice(0, rowBound) : normalized.rows;
+        const warnings = [];
+        const artifact = buildVerifiedGeneratedArtifact(question, trimmed, bounded.sql, seed, warnings, normalized.columns, activeConnection.driver);
+        return {
+            columns: normalized.columns,
+            rows,
+            rowCount: rows.length,
+            executionTime: normalized.executionTime,
+            sql: bounded.sql,
+            ...(truncated ? { truncated: true } : {}),
+            ...(artifact ? { dqlArtifact: { ...artifact, limit: rowBound } } : {}),
+            ...(warnings.length > 0 ? { validationWarnings: warnings } : {}),
+            executionReceipt: createDqlArtifactExecutionReceipt(artifact?.source ?? trimmed, bounded.sql, {}, { columns: normalized.columns, rows, rowCount: rows.length }),
+        };
+    };
     const executeGeneratedArtifactForAgent = async (question, sql, seed, executionConnection, executionConnectionName) => {
-        const artifact = generatedSqlArtifactContract(question, sql, seed);
-        return executeArtifactReferenceForAgent({ ...artifact, limit: seed?.limit ?? artifact.limit ?? 200 }, question, executionConnection, executionConnectionName);
+        // A seed that is already a certified/saved artifact keeps the DQL-first
+        // path: there the `.dql` source IS the contract, and its parameters and
+        // semantic refs must be compiled, not bypassed.
+        if (seed && seed.kind !== 'sql_block') {
+            return executeArtifactReferenceForAgent({ ...seed, limit: seed.limit ?? 200 }, question, executionConnection, executionConnectionName);
+        }
+        return executeGeneratedSqlDirect(question, sql, seed, executionConnection);
     };
     /**
      * EXP-001: execution host for the deliberately narrow non-governed lane.
@@ -3287,6 +3526,60 @@ export async function startLocalServer(opts) {
             return { proofs, sql: boundedSql, repairs, error: error instanceof Error ? error.message : String(error) };
         }
     };
+    /**
+     * Ask the warehouse whether specific named relations exist, AFTER the cached
+     * catalog has already missed them.
+     *
+     * `getSchemaContextForAgent` deliberately returns nothing on a lexical miss —
+     * "a lexical miss is not permission to rescan every visible schema". That is
+     * right for BULK retrieval, but it also meant a relation the model named
+     * explicitly, and that the notebook queries without complaint, was refused as
+     * "outside the inspected metadata context" without the warehouse ever being
+     * asked. A point lookup of up to four named `(schema, table)` pairs is not a
+     * rescan.
+     *
+     * The payoff is honesty as much as recall: after this probe, a miss is
+     * evidence. The refusal can say the relation is not visible to this
+     * connection, rather than only that DQL had not looked at it.
+     */
+    const probeNamedRelationsForAgent = async (relations, probeConnection) => {
+        const probeTarget = probeConnection ?? connection;
+        if (!probeTarget)
+            return undefined;
+        // Same operator switch that governs live value grounding: a deployment that
+        // wants zero live metadata traffic keeps it.
+        if (resolveAgentRuntimeValueGrounding(projectConfig).mode !== 'safe_automatic')
+            return undefined;
+        const sql = buildNamedRelationProbeSql(relations);
+        if (!sql)
+            return undefined;
+        const prepared = prepareLocalExecution(sql, probeTarget, projectRoot, projectConfig);
+        const result = await executor.executeQuery(prepared.sql, [], runtimeVariables({}), prepared.connection);
+        const rows = normalizeQueryResult(result).rows;
+        if (rows.length === 0)
+            return undefined;
+        const tables = buildAgentSchemaContext('', rows, { includeUnscored: true, limit: 8 });
+        if (tables.length === 0)
+            return undefined;
+        return {
+            relations: tables.map((table) => ({
+                relation: table.relation,
+                name: table.name,
+                // Provenance is explicit: these columns came from a live lookup, not
+                // from the immutable snapshot.
+                source: 'scoped live probe',
+                columns: table.columns.map((column) => ({ name: column.name, type: column.type })),
+                columnCompleteness: 'complete',
+            })),
+            schemaContext: tables.map((table) => ({
+                relation: table.relation,
+                schema: table.schema,
+                name: table.name,
+                columns: table.columns,
+            })),
+            notes: tables.map((table) => `${table.relation} resolved by a scoped live probe`),
+        };
+    };
     const getSchemaContextForAgent = async (question, preparedContextPack, executionConnection, executionConnectionName) => {
         const schemaConnection = executionConnection ?? connection;
         const scanRuntimeSchema = async () => {
@@ -12135,6 +12428,60 @@ export async function startLocalServer(opts) {
                 res.end(readFileSync(filePath));
                 return;
             }
+            /**
+             * Promote a RESULT COLUMN into a runtime filter input on a generated answer.
+             *
+             * The SQL edit happens here, not in the browser: deciding where a predicate
+             * may go needs a real dialect parse, and shipping a SQL parser to the client
+             * to guess at it is exactly how a filter ends up silently attached to the
+             * wrong query. The client sends a column; it gets back an artifact.
+             */
+            if (req.method === 'POST' && path === '/api/dql/artifacts/add-filter') {
+                try {
+                    const body = await readJSON(req);
+                    const artifact = normalizeDqlArtifactReference(body.artifact);
+                    const column = typeof body.column === 'string' ? body.column.trim() : '';
+                    const value = body.value;
+                    const resultColumns = Array.isArray(body.resultColumns)
+                        ? body.resultColumns.filter((entry) => typeof entry === 'string')
+                        : [];
+                    if (!artifact)
+                        throw new Error('A DQL artifact is required to add a filter input.');
+                    if (!column)
+                        throw new Error('Choose a result column to filter on.');
+                    if (value === undefined || value === null || String(value).trim() === '') {
+                        throw new Error('Choose a default filter value before adding the input.');
+                    }
+                    const sql = extractBlockStudioSql(artifact.source);
+                    if (!sql)
+                        throw new Error('This answer has no editable SQL to filter.');
+                    const activeConnection = requireActiveConnection();
+                    const existingNames = (artifact.parameters ?? []).map((parameter) => parameter.name);
+                    const added = addSqlResultFilter(sql, resultColumns, column, existingNames, activeConnection.driver);
+                    const source = replaceBlockStudioSql(artifact.source, added.sql, added.parameterName, value);
+                    // Re-parse so the returned contract is what the block ACTUALLY declares,
+                    // rather than what this endpoint believes it wrote.
+                    const invocation = prepareBlockInvocation({ source, surface: 'ask_ai' });
+                    if (invocation.errors.length > 0)
+                        throw new Error(invocation.errors.join(' '));
+                    const { executionReceipt: _receipt, compiledSql: _compiled, ...unexecuted } = artifact;
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        artifact: {
+                            ...unexecuted,
+                            source,
+                            parameters: invocation.parameters,
+                            parameterValues: { ...(artifact.parameterValues ?? {}), [added.parameterName]: value },
+                        },
+                        parameterName: added.parameterName,
+                    }));
+                }
+                catch (error) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: apiErrorMessage(error) }));
+                }
+                return;
+            }
             if (req.method === 'POST' && path === '/api/dql/artifacts/execute') {
                 try {
                     const body = await readJSON(req);
@@ -15093,18 +15440,80 @@ const AGENT_PREVIEW_FORBIDDEN_SQL = [
     'update',
     'vacuum',
 ];
+/**
+ * Run DQL's own block-compiler machinery with an honest origin. Anything these
+ * stages throw is a DQL-artifact failure, never a warehouse failure.
+ */
+function withAnalyticalCompilationOrigin(stage, fn) {
+    return withAnalyticalErrorOriginSync({ origin: 'dql_compilation', stage }, fn);
+}
+export function clampAnalyticalRowBound(rowLimit) {
+    return Number.isFinite(rowLimit) ? Math.max(1, Math.min(10_000, Math.floor(rowLimit))) : 200;
+}
+/**
+ * Dialects where a bare trailing `LIMIT n` is valid on a top-level SELECT.
+ * MSSQL/Fabric need `TOP`/`OFFSET…FETCH` in positions that depend on the rest
+ * of the statement, so we never rewrite there — the host-side truncation below
+ * is the guarantee, and appending is only an optimization.
+ */
+const TRAILING_LIMIT_DIALECTS = new Set([
+    'duckdb', 'postgres', 'postgresql', 'redshift', 'snowflake', 'bigquery',
+    'databricks', 'trino', 'presto', 'clickhouse', 'mysql', 'mariadb', 'sqlite', 'athena',
+]);
+/**
+ * Bound a result set WITHOUT rewriting the statement's shape.
+ *
+ * The previous approach wrapped every Ask query as
+ * `SELECT * FROM (<sql>) AS dql_agent_preview LIMIT n`. That is not a no-op:
+ *   - `SELECT * FROM (WITH x AS (…) SELECT …) AS t` is a syntax error on
+ *     MSSQL/Fabric, and the model emits CTEs constantly;
+ *   - duplicate output column names are legal at top level but not as a
+ *     derived table on several engines;
+ *   - the inner `ORDER BY` stops being guaranteed, silently breaking top-N.
+ * All three produced "fails in Ask, runs in the notebook" for identical SQL.
+ *
+ * Appending is skipped whenever it cannot be proven safe. Callers must still
+ * truncate rows host-side — that, not this, is what actually enforces the bound.
+ */
+export function buildRowBoundedSql(sql, rowLimit, dialect = 'duckdb') {
+    const trimmed = sql.trim().replace(/;\s*$/, '').trim();
+    if (!rowLimit)
+        return { sql: trimmed, outcome: 'skipped', reason: 'no row bound requested' };
+    if (!TRAILING_LIMIT_DIALECTS.has(dialect.toLowerCase())) {
+        return { sql: trimmed, outcome: 'skipped', reason: `trailing LIMIT is not portable on ${dialect}` };
+    }
+    const analysis = analyzeSqlReferences(trimmed, dialect);
+    if (!analysis.parsed) {
+        return { sql: trimmed, outcome: 'skipped', reason: 'statement did not parse; not rewriting it' };
+    }
+    const statements = analysis.statementTypes ?? [];
+    if (statements.length !== 1 || statements[0]?.toLowerCase() !== 'select') {
+        return { sql: trimmed, outcome: 'skipped', reason: 'not a single SELECT statement' };
+    }
+    // Any existing bound — LIMIT, FETCH FIRST/NEXT, TOP — wins. Detection is
+    // deliberately greedy: a false positive costs nothing (host truncation still
+    // applies), a false negative would override the author's own bound.
+    const scan = stripSqlStringsAndComments(trimmed);
+    if (/\blimit\b/i.test(scan) || /\bfetch\s+(first|next)\b/i.test(scan) || /\btop\s*\(?\s*\d/i.test(scan)) {
+        return { sql: trimmed, outcome: 'existing', reason: 'statement already carries its own bound' };
+    }
+    return { sql: `${trimmed}\nLIMIT ${clampAnalyticalRowBound(rowLimit)}`, outcome: 'appended' };
+}
+/**
+ * @deprecated Kept for one release so any out-of-tree caller keeps working.
+ * Use {@link executeAnalyticalSql}, which bounds rows without wrapping.
+ */
 export function buildAgentPreviewSql(sql, rowLimit = 200) {
     const trimmed = sql.trim();
     if (!trimmed)
-        throw new Error('Generated SQL preview is empty.');
-    const boundedRowLimit = Number.isFinite(rowLimit)
-        ? Math.max(1, Math.min(10_000, Math.floor(rowLimit)))
-        : 200;
+        throw analyticalError('Generated SQL preview is empty.', { origin: 'host', stage: 'execute' });
     const withoutTrailingSemicolon = trimmed.replace(/;\s*$/, '').trim();
     const readOnlyError = readOnlySqlValidationError(withoutTrailingSemicolon, 'Generated SQL preview');
-    if (readOnlyError)
-        throw new Error(readOnlyError);
-    return `SELECT * FROM (\n${withoutTrailingSemicolon}\n) AS dql_agent_preview LIMIT ${boundedRowLimit}`;
+    // A deliberate read-only refusal, not a warehouse rejection.
+    if (readOnlyError) {
+        throw analyticalError(readOnlyError, { origin: 'governance_gate', stage: 'validation', code: 'unsafe_sql' });
+    }
+    return buildRowBoundedSql(withoutTrailingSemicolon, rowLimit).sql;
 }
 /**
  * EXP-001 preflight for model-authored exploratory SQL.
@@ -15492,7 +15901,7 @@ function summarizeExploratoryJoinProbe(rows, leftRelation, leftColumn, rightRela
     };
     return `${leftRelation}.${leftColumn} ↔ ${rightRelation}.${rightColumn}: sample left=${number('left_sample_rows')}, right=${number('right_sample_rows')}, joined=${number('joined_rows')}, unmatched left/right=${number('unmatched_left_sample_rows')}/${number('unmatched_right_sample_rows')}, max matches left/right=${number('max_matches_per_left_key')}/${number('max_matches_per_right_key')}`;
 }
-function readOnlySqlValidationError(sql, subject) {
+function readOnlySqlValidationError(sql, subject, dialect = 'duckdb') {
     const internalRelationError = internalDqlRelationIdValidationError(sql, subject);
     if (internalRelationError)
         return internalRelationError;
@@ -15503,6 +15912,22 @@ function readOnlySqlValidationError(sql, subject) {
     if (scanSql.includes(';')) {
         return `${subject} only supports one statement.`;
     }
+    // Prefer the parser. The keyword blacklist matches IDENTIFIERS, so a CTE or
+    // column alias legitimately named `set`, `load`, `merge`, or `copy` was
+    // rejected as if it were DDL — a false failure on SQL the notebook runs fine.
+    // The blacklist stays as the conservative fallback for statements the dialect
+    // parser cannot read.
+    const analysis = analyzeSqlReferences(scanSql, dialect);
+    if (analysis.parsed) {
+        const statements = analysis.statementTypes ?? [];
+        const offending = statements.find((statement) => statement.toLowerCase() !== 'select');
+        if (offending) {
+            return `${subject} rejected unsupported statement keyword: ${offending.toUpperCase()}.`;
+        }
+        if (statements.length > 1)
+            return `${subject} only supports one statement.`;
+        return null;
+    }
     const forbiddenPattern = new RegExp(`\\b(${AGENT_PREVIEW_FORBIDDEN_SQL.join('|')})\\b`, 'i');
     const forbidden = scanSql.match(forbiddenPattern)?.[1];
     if (forbidden) {
@@ -18804,7 +19229,7 @@ function agentResultToSynthesisPreview(result) {
 }
 /** Up to three example questions built from real catalog blocks (falls back to generic asks). */
 function buildConversationSuggestions(projectRoot, kind) {
-    if (kind === 'gratitude')
+    if (kind === 'gratitude' || kind === 'answer_explanation')
         return [];
     let names = [];
     try {
@@ -18900,9 +19325,9 @@ export function buildConversationContextRecap(context) {
         return undefined;
     return `We were talking about ${contextBits.join('. ')}.`;
 }
-function buildConversationTurnsRecap(context) {
+function latestSubstantiveConversationTurn(context) {
     const turns = Array.isArray(context.turns)
-        ? context.turns.map(agentRunRecord).filter((turn) => Boolean(turn)).slice(-3)
+        ? context.turns.map(agentRunRecord).filter((turn) => Boolean(turn)).slice(-6)
         : [];
     if (turns.length === 0)
         return undefined;
@@ -18914,9 +19339,120 @@ function buildConversationTurnsRecap(context) {
     // subject of the next recap. Prefer the newest analytical/authoring turn and
     // fall back to the active turn only when the thread contains conversation alone.
     const substantiveTurns = turns.filter((turn) => agentRunString(turn.route) !== 'conversation');
-    const selected = active && agentRunString(active.route) !== 'conversation'
+    return active && agentRunString(active.route) !== 'conversation'
         ? active
         : substantiveTurns[substantiveTurns.length - 1] ?? active ?? turns[turns.length - 1];
+}
+/**
+ * Explain the latest successful answer from its persisted artifact contract.
+ * This is intentionally deterministic and never executes SQL: missing evidence
+ * is reported as missing instead of being guessed or converted into a new metric.
+ */
+export function buildPriorAnswerExplanation(question, context) {
+    if (!context)
+        return undefined;
+    const selected = latestSubstantiveConversationTurn(context);
+    const artifact = agentRunRecord(selected?.dqlArtifact) ?? agentRunRecord(context.dqlArtifact);
+    const result = agentRunRecord(selected?.result);
+    const metrics = agentRunStringArray(artifact?.metrics
+        ?? selected?.requestedMeasures
+        ?? context.priorMeasures);
+    const dimensions = agentRunStringArray(artifact?.dimensions
+        ?? selected?.requestedDimensions
+        ?? context.requestedDimensions);
+    const timeDimension = agentRunRecord(artifact?.timeDimension);
+    const timeName = agentRunString(timeDimension?.name);
+    const granularity = agentRunString(timeDimension?.granularity);
+    const filters = formatPriorAnswerFilters(artifact?.filters, selected?.requestedFilters ?? context.requestedFilters);
+    const topN = typeof selected?.topN === 'number'
+        ? selected.topN
+        : typeof context.priorLimit === 'number'
+            ? context.priorLimit
+            : undefined;
+    const source = agentRunString(artifact?.name)
+        ?? agentRunString(selected?.sourceCertifiedBlock)
+        ?? agentRunString(context.sourceCertifiedBlock);
+    const columns = agentRunStringArray(result?.columns ?? context.resultColumns).slice(0, 8);
+    const metricText = metrics.length > 0 ? metrics.map(humanizeArtifactField).join(', ') : undefined;
+    const dimensionText = dimensions.length > 0 ? dimensions.map(humanizeArtifactField).join(', ') : undefined;
+    const normalizedQuestion = question.toLowerCase();
+    if (/\b(?:daily|monthly|weekly|quarterly|yearly|annual|grain|period|timeframe|date range)\b/.test(normalizedQuestion)) {
+        if (granularity) {
+            return [
+                `The previous result uses${metricText ? ` ${metricText}` : ' the recorded metric'} and is grouped`
+                    + `${timeName ? ` by ${humanizeArtifactField(timeName)}` : ''} at a ${formatTimeGranularity(granularity)} grain.`,
+                filters.length > 0 ? `Applied filters: ${filters.join('; ')}.` : '',
+            ].filter(Boolean).join(' ');
+        }
+        return [
+            `The previous result does not declare a daily or monthly time grain${metricText ? ` for ${metricText}` : ''}.`,
+            dimensionText ? `Its recorded grouping is ${dimensionText}.` : 'It is an aggregate across the applied result scope.',
+            filters.length > 0 ? `Applied filters: ${filters.join('; ')}.` : '',
+            'If you want a new monthly or daily breakdown, ask me to show or group it that way.',
+        ].filter(Boolean).join(' ');
+    }
+    if (/\b(?:which|what)\s+(?:metric|measure)\b|\bmetric\s+(?:did|does|was|is)\b/.test(normalizedQuestion)) {
+        return metricText
+            ? `The previous answer used ${metricText}${source ? ` from ${humanizeArtifactField(source)}` : ''}.`
+            : 'The previous answer did not retain a qualified metric identifier, so I cannot name one without rerunning or reviewing its DQL.';
+    }
+    if (/\bfilter|include|exclude\b/.test(normalizedQuestion)) {
+        return filters.length > 0
+            ? `The previous answer applied these filters: ${filters.join('; ')}.`
+            : 'The previous artifact does not record any explicit filters.';
+    }
+    const facts = [
+        metricText ? `Metric: ${metricText}.` : '',
+        dimensionText ? `Grouped by: ${dimensionText}.` : '',
+        granularity ? `Time grain: ${formatTimeGranularity(granularity)}${timeName ? ` on ${humanizeArtifactField(timeName)}` : ''}.` : '',
+        filters.length > 0 ? `Filters: ${filters.join('; ')}.` : '',
+        topN ? `Limit: top ${topN}.` : '',
+        source ? `Source: ${humanizeArtifactField(source)}.` : '',
+        columns.length > 0 ? `Returned fields: ${columns.map(humanizeArtifactField).join(', ')}.` : '',
+    ].filter(Boolean);
+    return facts.length > 0
+        ? facts.join(' ')
+        : 'The previous answer did not retain enough artifact metadata to explain its metric, filters, or grain safely.';
+}
+function formatPriorAnswerFilters(primary, fallback) {
+    const fromArtifact = Array.isArray(primary)
+        ? primary.map(agentRunRecord).filter((filter) => Boolean(filter)).flatMap((filter) => {
+            const dimension = agentRunString(filter.dimension);
+            const operator = agentRunString(filter.operator) ?? 'equals';
+            const values = agentRunStringArray(filter.values);
+            return dimension && values.length > 0
+                ? [`${humanizeArtifactField(dimension)} ${operator.replace(/_/g, ' ')} ${values.join(', ')}`]
+                : [];
+        })
+        : [];
+    return fromArtifact.length > 0
+        ? fromArtifact
+        : agentRunStringArray(fallback).map((value) => value.replace(/_/g, ' '));
+}
+function humanizeArtifactField(value) {
+    return value
+        .split('.')
+        .at(-1)
+        .replace(/::/g, ' ')
+        .replace(/[_-]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function formatTimeGranularity(value) {
+    const normalized = value.trim().toLowerCase();
+    return {
+        day: 'daily',
+        week: 'weekly',
+        month: 'monthly',
+        quarter: 'quarterly',
+        year: 'yearly',
+    }[normalized] ?? humanizeArtifactField(value);
+}
+function buildConversationTurnsRecap(context) {
+    const turns = Array.isArray(context.turns)
+        ? context.turns.map(agentRunRecord).filter((turn) => Boolean(turn)).slice(-3)
+        : [];
+    const selected = latestSubstantiveConversationTurn(context);
     if (!selected)
         return undefined;
     const result = agentRunRecord(selected.result);
@@ -22423,6 +22959,51 @@ const RUNTIME_SCHEMA_SEARCH_STOPWORDS = new Set([
  * execution target. Tokens are reduced to safe identifier characters before
  * interpolation, so user text cannot become SQL syntax.
  */
+/**
+ * Point-lookup of NAMED relations in `information_schema.columns`.
+ *
+ * This is deliberately not `buildRuntimeSchemaSearchSql`. That one matches
+ * `LOWER(table_name) LIKE '%term%'` across every visible schema, which is the
+ * unbounded rescan the "a lexical miss is not permission to rescan" policy
+ * exists to prevent. This one asks about specific `(schema, table)` pairs the
+ * model actually referenced, with equality predicates — a metadata point
+ * lookup, not a scan.
+ *
+ * Returns null when nothing safe to ask about survives normalization.
+ */
+export function buildNamedRelationProbeSql(relations, maxRelations = 4) {
+    const predicates = [];
+    const seen = new Set();
+    for (const raw of relations) {
+        const parts = raw.replace(/["`\[\]]/g, '').trim().split('.').filter(Boolean);
+        const table = parts.at(-1);
+        // Identifiers only — never interpolate anything that could carry SQL.
+        if (!table || !/^[A-Za-z_][A-Za-z0-9_$]*$/.test(table))
+            continue;
+        const schema = parts.length >= 2 ? parts.at(-2) : undefined;
+        if (schema && !/^[A-Za-z_][A-Za-z0-9_$]*$/.test(schema))
+            continue;
+        const key = `${schema ?? ''}.${table}`.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        predicates.push(schema
+            ? `(LOWER(table_schema) = '${schema.toLowerCase()}' AND LOWER(table_name) = '${table.toLowerCase()}')`
+            : `(LOWER(table_name) = '${table.toLowerCase()}')`);
+        if (predicates.length >= maxRelations)
+            break;
+    }
+    if (predicates.length === 0)
+        return null;
+    return `SELECT table_schema, table_name, column_name, data_type
+FROM information_schema.columns
+WHERE UPPER(table_schema) NOT IN ('INFORMATION_SCHEMA', 'PG_CATALOG')
+  AND (
+${predicates.map((predicate) => `    ${predicate}`).join(' OR\n')}
+  )
+ORDER BY table_schema, table_name, ordinal_position
+LIMIT 400`;
+}
 export function buildRuntimeSchemaSearchSql(question) {
     const terms = Array.from(agentSchemaTokens(question))
         .map((term) => term.toLowerCase().replace(/[^a-z0-9_]/g, ''))