@duckcodeailabs/dql-cli 1.12.2 → 1.12.4

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),
@@ -968,7 +1002,10 @@ export async function startLocalServer(opts) {
         return result;
     };
     await reloadSemanticLayer();
-    await refreshLocalMetadataCatalog(projectRoot);
+    // Normal startup reuses the fingerprinted local catalog when its inputs are
+    // unchanged. Explicit refresh, save, and certification paths still request
+    // the default forced rebuild below.
+    await refreshLocalMetadataCatalog(projectRoot, undefined, undefined, false);
     const startupDbtManifestPath = resolveDbtManifestPath(projectRoot, projectConfig);
     if (startupDbtManifestPath && !isAgentProjectIndexReady(projectRoot)) {
         try {
@@ -1338,8 +1375,14 @@ export async function startLocalServer(opts) {
                 throw error;
         }
         const semanticDriver = semanticConnection?.driver;
+        const defaultExecutionTarget = executionTargetDescriptor({});
+        const semanticConnectionName = request.executionTarget?.target === 'connection'
+            ? request.executionTarget.connectionName
+            : defaultExecutionTarget.target === 'connection'
+                ? defaultExecutionTarget.connectionName
+                : undefined;
         const semanticTableMapping = semanticLayer && semanticConnection
-            ? await resolveSemanticTableMapping(executor, semanticConnection, semanticLayer, projectRoot)
+            ? await resolveSemanticTableMapping(executor, semanticConnection, semanticLayer, projectRoot, semanticConnectionName)
             : undefined;
         const requestedDomain = normalizeAgentRunDomain(agentRunWorkspaceValue(request, 'domain'));
         const requestedPurpose = agentRunWorkspaceValue(request, 'purpose');
@@ -1527,12 +1570,13 @@ export async function startLocalServer(opts) {
                 ? { resolvedAnalyticalPlan: routeDecision.resolvedAnalyticalPlan }
                 : {}),
             analyticalReferenceInstant: new Date().toISOString(),
-            executeCertifiedBlock: (node, invocation) => executeCertifiedBlockForAgent(node, invocation, semanticConnection),
-            executeGeneratedSql: (sql, artifact) => executeGeneratedArtifactForAgent(request.question, sql, artifact, semanticConnection),
-            executeDqlArtifact: (artifact) => executeArtifactReferenceForAgent(artifact, request.question, semanticConnection),
+            executeCertifiedBlock: (node, invocation) => executeCertifiedBlockForAgent(node, invocation, semanticConnection, semanticConnectionName),
+            executeGeneratedSql: (sql, artifact) => executeGeneratedArtifactForAgent(request.question, sql, artifact, semanticConnection, semanticConnectionName),
+            executeDqlArtifact: (artifact) => executeArtifactReferenceForAgent(artifact, request.question, semanticConnection, semanticConnectionName),
             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);
@@ -1918,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());
@@ -1949,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
@@ -1993,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' }]
@@ -2163,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)
@@ -2197,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',
@@ -2706,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
@@ -2713,9 +2790,23 @@ export async function startLocalServer(opts) {
         const preparedMetadataFingerprint = isAgentProjectIndexReady(projectRoot)
             ? currentMetadataFingerprint(projectRoot)
             : undefined;
+        const targetDescriptor = executionTargetDescriptor(request);
+        const targetConnectionName = targetDescriptor.target === 'connection'
+            ? targetDescriptor.connectionName
+            : undefined;
+        let runtimeSchemaSnapshot;
+        if (targetConnectionName) {
+            const targetConnection = resolveNamedConnection(targetConnectionName);
+            const activeScope = targetConnection
+                ? optionalActiveConnectionMetadataScope(projectRoot, projectConfig, targetConnection, targetConnectionName)
+                : null;
+            runtimeSchemaSnapshot = runtimeSchemaSnapshotForAgentConnection(projectRoot, targetConnectionName, activeScope?.scopeFingerprint);
+        }
         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'
@@ -2724,8 +2815,14 @@ export async function startLocalServer(opts) {
                 || topicRelation === 'shift'
                 ? topicRelation
                 : undefined,
+            // Reuse remains available for fast follow-ups; the context-pack freshness
+            // contract now binds it to this runtime snapshot's connection/generation.
+            reusePolicy: 'seed',
             preparedMetadataFingerprint,
-            surface: 'notebook',
+            ...(runtimeSchemaSnapshot ? { runtimeSchemaSnapshot } : {}),
+            surface: blockAuthoringContext
+                ? 'block'
+                : workspaceSurface ?? 'notebook',
             selectedContext: {
                 selectedObject: request.selectedObject,
                 workspaceContext: request.workspaceContext,
@@ -2995,44 +3092,56 @@ export async function startLocalServer(opts) {
             cells: snapshotCells,
         });
     };
-    const executeDqlArtifactSourceForAgent = async (source, metadata = {}, invocationInput, executionConnection) => {
-        const invocation = prepareBlockInvocation({
+    const executeDqlArtifactSourceForAgent = async (source, metadata = {}, invocationInput, executionConnection, executionConnectionName) => {
+        // 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)
+            ? 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
@@ -3080,7 +3189,7 @@ export async function startLocalServer(opts) {
             } : {}),
         };
     };
-    const executeCertifiedBlockByNameForAgent = async (blockName, invocationInput, requireCertified = false, executionConnection) => {
+    const executeCertifiedBlockByNameForAgent = async (blockName, invocationInput, requireCertified = false, executionConnection, executionConnectionName) => {
         const manifest = buildManifest({ projectRoot });
         const block = manifest.blocks[blockName];
         if (!block) {
@@ -3095,7 +3204,7 @@ export async function startLocalServer(opts) {
             path: block.filePath,
             domain: block.domain,
             chartType: block.chartType,
-        }, invocationInput, executionConnection);
+        }, invocationInput, executionConnection, executionConnectionName);
         return {
             ...result,
             dqlArtifact: {
@@ -3114,17 +3223,17 @@ export async function startLocalServer(opts) {
             },
         };
     };
-    const executeCertifiedBlockForAgent = async (node, invocationInput, executionConnection) => {
+    const executeCertifiedBlockForAgent = async (node, invocationInput, executionConnection, executionConnectionName) => {
         if (node.kind !== 'block') {
             throw new Error(`Certified ${node.kind} "${node.name}" is a navigation artifact and cannot be executed as a block.`);
         }
-        return executeCertifiedBlockByNameForAgent(node.name || node.nodeId.replace(/^block:/, ''), invocationInput, false, executionConnection);
+        return executeCertifiedBlockByNameForAgent(node.name || node.nodeId.replace(/^block:/, ''), invocationInput, false, executionConnection, executionConnectionName);
     };
     // Secondary agent surfaces use this compatibility callback. Delegate to the
     // same artifact-first path as Ask so research/app/notebook execution cannot
     // silently reintroduce a raw-SQL result followed by a different DQL artifact.
     const executeGeneratedSqlForAgent = async (sql, artifact) => executeGeneratedArtifactForAgent(artifact?.name ?? 'AI-generated query', sql, artifact);
-    const executeArtifactReferenceForAgent = async (artifact, question, executionConnection) => {
+    const executeArtifactReferenceForAgent = async (artifact, question, executionConnection, executionConnectionName) => {
         const invocation = prepareBlockInvocation({
             source: artifact.source,
             parameters: artifact.parameterValues,
@@ -3139,7 +3248,7 @@ export async function startLocalServer(opts) {
             question,
             parameters: invocation.values,
             rowLimit: artifact.limit ?? 200,
-        }, executionConnection);
+        }, executionConnection, executionConnectionName);
         return {
             ...result,
             dqlArtifact: {
@@ -3151,9 +3260,123 @@ export async function startLocalServer(opts) {
             },
         };
     };
-    const executeGeneratedArtifactForAgent = async (question, sql, seed, executionConnection) => {
-        const artifact = generatedSqlArtifactContract(question, sql, seed);
-        return executeArtifactReferenceForAgent({ ...artifact, limit: seed?.limit ?? artifact.limit ?? 200 }, question, executionConnection);
+    /**
+     * 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' });
+        const readOnlyError = readOnlySqlValidationError(trimmed, 'Generated SQL', activeConnection.driver);
+        if (readOnlyError) {
+            throw analyticalError(readOnlyError, { origin: 'governance_gate', stage: 'validation', code: 'unsafe_sql' });
+        }
+        const prepared = prepareLocalExecution(trimmed, activeConnection, projectRoot, projectConfig);
+        const bounded = buildRowBoundedSql(prepared.sql, rowBound, activeConnection.driver);
+        const app = loadRuntimeApp(projectRoot, activePersonaAppId());
+        const sourceDomain = seed?.source?.match(/\bdomain\s*=\s*"([^"]+)"/i)?.[1];
+        assertAppAccess({ app, domain: sourceDomain ?? app?.domain, level: 'execute' });
+        const rawResult = await executor.executeQuery(bounded.sql, [], runtimeVariables({}), prepared.connection);
+        const normalized = normalizeQueryResult(rawResult);
+        // 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) => {
+        // 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.
@@ -3262,6 +3485,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 () => {
@@ -3277,7 +3554,7 @@ export async function startLocalServer(opts) {
         const activeScope = schemaConnection
             ? optionalActiveConnectionMetadataScope(projectRoot, projectConfig, schemaConnection, executionConnectionName ?? projectConfig.defaultConnectionName ?? 'default')
             : null;
-        const activeRuntimeSnapshot = latestRuntimeSchemaSnapshotForProject(projectRoot);
+        const activeRuntimeSnapshot = latestRuntimeSchemaSnapshotForProject(projectRoot, executionConnectionName);
         const hasActivatedMetadataGeneration = Boolean(activeScope
             && activeRuntimeSnapshot?.scopeFingerprint === activeScope.scopeFingerprint
             && activeRuntimeSnapshot.status !== 'stale');
@@ -3289,9 +3566,6 @@ export async function startLocalServer(opts) {
             // row value must not turn a warm Ask into an information_schema scan over
             // thousands of enterprise tables; only field-scoped value probes are live.
             const enriched = await enrichAgentSchemaContextWithValueMatches(question, catalogContext, executor, schemaConnection, valueGrounding.searchSafeColumns);
-            if (!hasActivatedMetadataGeneration) {
-                recordAgentRuntimeSchemaSnapshot(projectRoot, catalogContext, 'catalog runtime schema');
-            }
             return enriched;
         }
         // An activated, scope-qualified warehouse generation is the complete warm
@@ -3307,7 +3581,7 @@ export async function startLocalServer(opts) {
             const enriched = valueGrounding.mode === 'safe_automatic'
                 ? await enrichAgentSchemaContextWithValueMatches(question, schemaContext.ranked, executor, schemaConnection, valueGrounding.searchSafeColumns)
                 : schemaContext.ranked;
-            recordAgentRuntimeSchemaSnapshot(projectRoot, schemaContext.snapshot, 'question-scoped information_schema search');
+            recordAgentRuntimeSchemaSnapshot(projectRoot, schemaContext.snapshot, 'question-scoped information_schema search', executionConnectionName);
             return enriched;
         }
         catch {
@@ -6519,6 +6793,12 @@ export async function startLocalServer(opts) {
                             res.end(serializeJSON({ ok: true }));
                             return;
                         }
+                        if (req.method === 'DELETE' && !action) {
+                            store.deleteThread(threadId);
+                            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                            res.end(serializeJSON({ ok: true }));
+                            return;
+                        }
                         // Explicit promotion — the ONLY path from conversation into durable
                         // memory ("remember this"). Deliberate user act, tagged for audit.
                         if (req.method === 'POST' && action === 'promote') {
@@ -9884,7 +10164,7 @@ export async function startLocalServer(opts) {
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({
                         scope,
-                        status: warehouseMetadataStatus(projectRoot, scope.scopeFingerprint),
+                        status: warehouseMetadataStatus(projectRoot, scope.scopeFingerprint, connectionId),
                     }));
                 }
                 catch (error) {
@@ -9904,7 +10184,7 @@ export async function startLocalServer(opts) {
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({
                         scope,
-                        status: warehouseMetadataStatus(projectRoot, scope.scopeFingerprint),
+                        status: warehouseMetadataStatus(projectRoot, scope.scopeFingerprint, connectionId),
                     }));
                 }
                 catch (error) {
@@ -9933,7 +10213,7 @@ export async function startLocalServer(opts) {
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({
                         scope: synced.scope,
-                        status: warehouseMetadataStatus(projectRoot, synced.scope.scopeFingerprint),
+                        status: warehouseMetadataStatus(projectRoot, synced.scope.scopeFingerprint, connectionId),
                     }));
                 }
                 catch (error) {
@@ -9959,7 +10239,7 @@ export async function startLocalServer(opts) {
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({
                         scope: synced.scope,
-                        status: warehouseMetadataStatus(projectRoot, synced.scope.scopeFingerprint),
+                        status: warehouseMetadataStatus(projectRoot, synced.scope.scopeFingerprint, connectionId),
                     }));
                 }
                 catch (error) {
@@ -9996,7 +10276,7 @@ export async function startLocalServer(opts) {
                     connectorStatus,
                     metadataScope,
                     metadataStatus: metadataScope
-                        ? warehouseMetadataStatus(projectRoot, metadataScope.scopeFingerprint)
+                        ? warehouseMetadataStatus(projectRoot, metadataScope.scopeFingerprint, defaultKey)
                         : warehouseMetadataStatus(projectRoot),
                 }));
                 return;
@@ -12107,6 +12387,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);
@@ -12524,7 +12858,11 @@ table: ${table}${tagList}
                 return;
             }
             const content = readFileSync(filePath);
-            res.writeHead(200, { 'Content-Type': contentTypeFor(filePath) });
+            res.writeHead(200, {
+                'Content-Type': contentTypeFor(filePath),
+                'Cache-Control': staticResponseCacheControl(filePath),
+                'Content-Length': content.byteLength,
+            });
             res.end(content);
         })().catch((error) => {
             // API-007/E2E-014: no rejected request promise may terminate the local
@@ -13480,10 +13818,10 @@ export function compileBlockStudioManifest(projectRoot, projectConfig = loadProj
     _lineageCache.delete(projectRoot);
     return manifest;
 }
-async function refreshLocalMetadataCatalog(projectRoot, manifest, semanticLayer) {
+async function refreshLocalMetadataCatalog(projectRoot, manifest, semanticLayer, force = true) {
     try {
         await ensureMetadataCatalogFresh(projectRoot, {
-            force: true,
+            force,
             ...(manifest ? { manifest } : {}),
             ...(semanticLayer ? { semanticLayer } : {}),
         });
@@ -15061,18 +15399,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.
@@ -15460,7 +15860,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;
@@ -15471,6 +15871,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) {
@@ -15691,6 +16107,16 @@ function contentTypeFor(filePath) {
             return 'text/plain; charset=utf-8';
     }
 }
+export function staticResponseCacheControl(filePath) {
+    // Vite fingerprints every generated asset filename, so a new DQL build gets
+    // a new URL and the previous file is safe to retain indefinitely. Keep the
+    // HTML shell revalidated so it can point at the current asset hashes.
+    if (extname(filePath).toLowerCase() === '.html')
+        return 'no-cache';
+    return filePath.split(sep).includes('assets')
+        ? 'public, max-age=31536000, immutable'
+        : 'no-cache';
+}
 function listProjectFiles(projectRoot) {
     const allowed = new Set(['.dql', '.sql', '.md', '.json', '.csv', '.yaml', '.yml', '.dqlnb']);
     const files = [];
@@ -16132,11 +16558,11 @@ function parseSemanticBlockConfig(source) {
         limit: limitMatch ? Number.parseInt(limitMatch[1], 10) : undefined,
     };
 }
-export async function resolveSemanticTableMapping(executor, connection, semanticLayer, projectRoot) {
+export async function resolveSemanticTableMapping(executor, connection, semanticLayer, projectRoot, connectionId) {
     if (!semanticLayer)
         return undefined;
     if (projectRoot) {
-        const snapshot = latestRuntimeSchemaSnapshotForProject(projectRoot);
+        const snapshot = latestRuntimeSchemaSnapshotForProject(projectRoot, connectionId);
         if (snapshot?.scopeFingerprint && snapshot.tables.length) {
             return buildSemanticTableMapping(semanticLayer, snapshot.tables.map((table) => ({
                 table_catalog: table.catalogOrDatabase,
@@ -16158,16 +16584,30 @@ export async function resolveSemanticTableMapping(executor, connection, semantic
     }
 }
 export function buildSemanticTableMapping(semanticLayer, rows) {
-    const dbTableNames = new Set();
-    const schemaQualified = new Map();
+    const normalizeIdentifierPart = (value) => value
+        .trim()
+        .replace(/^["'`\[]|["'`\]]$/g, '')
+        .toLowerCase();
+    const normalizeRelation = (value) => value
+        .split('.')
+        .map(normalizeIdentifierPart)
+        .filter(Boolean)
+        .join('.');
+    const candidates = [];
     for (const row of rows) {
+        const catalog = String(row['table_catalog'] ?? '');
         const schema = String(row['table_schema'] ?? '');
         const name = String(row['table_name'] ?? '');
-        const relation = typeof row['table_relation'] === 'string' ? row['table_relation'] : undefined;
+        const relation = typeof row['table_relation'] === 'string' && row['table_relation'].trim()
+            ? row['table_relation']
+            : [catalog, schema, name].filter(Boolean).join('.');
         if (!name)
             continue;
-        dbTableNames.add(name);
-        schemaQualified.set(name, relation ?? (schema ? `${schema}.${name}` : name));
+        candidates.push({
+            name: normalizeIdentifierPart(name),
+            relation,
+            normalizedRelation: normalizeRelation(relation),
+        });
     }
     const tableMapping = {};
     const allSemanticTables = new Set();
@@ -16182,9 +16622,19 @@ export function buildSemanticTableMapping(semanticLayer, rows) {
     for (const semTable of allSemanticTables) {
         if (!semTable)
             continue;
-        if (dbTableNames.has(semTable) && schemaQualified.has(semTable)) {
-            tableMapping[semTable] = schemaQualified.get(semTable);
-        }
+        const normalizedSemantic = normalizeRelation(semTable);
+        const semanticLeaf = normalizedSemantic.split('.').at(-1);
+        if (!semanticLeaf)
+            continue;
+        const qualifiedMatches = candidates.filter((candidate) => candidate.normalizedRelation === normalizedSemantic
+            || candidate.normalizedRelation.endsWith(`.${normalizedSemantic}`));
+        const leafMatches = candidates.filter((candidate) => candidate.name === semanticLeaf);
+        const matches = qualifiedMatches.length > 0 ? qualifiedMatches : leafMatches;
+        // Never guess when the same semantic leaf exists in several schemas. A
+        // qualified semantic relation can disambiguate; otherwise the semantic
+        // runtime must surface the modeling gap instead of executing the wrong one.
+        if (matches.length === 1)
+            tableMapping[semTable] = matches[0].relation;
     }
     return Object.keys(tableMapping).length > 0 ? tableMapping : undefined;
 }
@@ -18738,7 +19188,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 {
@@ -18834,9 +19284,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;
@@ -18848,9 +19298,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);
@@ -21433,11 +21994,36 @@ export function runtimeSnapshotStale(projectRoot, maxAgeMs = RUNTIME_SNAPSHOT_MA
         return false;
     }
 }
-function recordAgentRuntimeSchemaSnapshot(projectRoot, schemaContext, source) {
+/**
+ * Resolve only metadata captured for the connection executing this Ask run.
+ * Returning an explicit empty snapshot is a correctness boundary: callers pass
+ * it into the context builder so it cannot silently fall back to another
+ * connection's project-global runtime FTS rows.
+ */
+export function runtimeSchemaSnapshotForAgentConnection(projectRoot, connectionId, expectedScopeFingerprint) {
+    const snapshot = latestRuntimeSchemaSnapshotForProject(projectRoot, connectionId);
+    const current = Boolean(snapshot
+        && snapshot.status !== 'stale'
+        && (!expectedScopeFingerprint
+            || !snapshot.scopeFingerprint
+            || snapshot.scopeFingerprint === expectedScopeFingerprint));
+    return current
+        ? snapshot
+        : {
+            version: 1,
+            connectionId,
+            status: 'partial',
+            source: 'selected connection has no current runtime metadata',
+            tables: [],
+        };
+}
+function recordAgentRuntimeSchemaSnapshot(projectRoot, schemaContext, source, connectionId) {
     if (schemaContext.length === 0)
         return;
     try {
         recordRuntimeSchemaSnapshot(projectRoot, {
+            ...(connectionId ? { connectionId } : {}),
+            status: 'partial',
             source,
             tables: schemaContext.map((table) => ({
                 relation: table.relation,
@@ -22332,6 +22918,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, ''))