@duckcodeailabs/dql-cli 1.8.2 → 1.8.4

package/dist/local-runtime.js

@@ -14,9 +14,12 @@ import { loadSemanticLayerFromDir, normalizeDqlArtifactReference, serializeMetri
 import { load as loadYaml } from 'js-yaml';
 import { listBlockTemplates } from './block-templates.js';
 import { getRunner as getLLMRunner } from './llm/index.js';
+import { rethrowIfCancelled } from './llm/cancellation.js';
+import { fetchLatestPublishedDqlVersion, resolveDqlRuntimeVersionStatus } from './version-status.js';
+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, recallRelevantTurns, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildAnalysisQuestionPlan, buildLocalContextPack, toAgentRetrievalEvidence, defaultConversationPath, defaultMemoryPath, ensureDefaultMemoryFiles, ensureAgentProjectReady, isAgentProjectIndexReady, currentMetadataFingerprint, ensureMetadataCatalogFresh, readIndexedDomainKnowledge, readIndexedKnowledge360, propose, proposePlan, recordCorrectionTrace, emitCorrectionEvalCase, mineJoinPatterns, reviewHint, AgentRunEngine, FileAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, createHybridRouter, computeResultStats, buildDeterministicDashboardStory, synthesizeAnswer, streamOrGenerate, narrateResult, buildProposePreview, buildFromPrompt, defaultAgentRunStorePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, latestRuntimeSchemaSnapshotForProject, loadSkills, migrateLegacySkills, configuredSkillsPath, skillsDir, draftDomainSkillBootstrap, buildDomainSkillBootstrapPrompt, mergeDomainSkillBootstrapEnrichment, writeSkill, deleteSkill, deriveGeneratedDraftSlug, reindexProject, invalidateAgentProjectState, recordAgentRuntimeVersion, resolveDomainContextEnvelope, defaultKgPath, planAppFromPrompt, KGStore, planResearch, loadSemanticMetrics, cascadeTraceToEvidenceRouteSteps, createCascadeAnswerResult, createCascadeTrace, routeReasoningEffort, routeForCascadeAnswerTier, clampReasoningEffort, bumpReasoningEffort, resolveThinkingMode, coerceThinkingMode, upsertGeneratedDqlArtifactDraft, } from '@duckcodeailabs/dql-agent';
+import { ClaudeProvider, ConversationStore, advanceThreadState, buildConversationSnapshot, recallRelevantTurns, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildAnalysisQuestionPlan, buildLocalContextPack, toAgentRetrievalEvidence, defaultConversationPath, defaultMemoryPath, ensureDefaultMemoryFiles, ensureAgentProjectReady, isAgentProjectIndexReady, currentMetadataFingerprint, ensureMetadataCatalogFresh, readIndexedDomainKnowledge, readIndexedKnowledge360, propose, proposePlan, recordCorrectionTrace, emitCorrectionEvalCase, mineJoinPatterns, reviewHint, AgentRunEngine, SqliteAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, createHybridRouter, computeResultStats, buildDeterministicDashboardStory, synthesizeAnswer, streamOrGenerate, narrateResult, buildProposePreview, buildFromPrompt, defaultAgentRunStorePath, defaultAgentRunSqlitePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, latestRuntimeSchemaSnapshotForProject, loadSkills, migrateLegacySkills, configuredSkillsPath, skillsDir, draftDomainSkillBootstrap, buildDomainSkillBootstrapPrompt, mergeDomainSkillBootstrapEnrichment, writeSkill, deleteSkill, deriveGeneratedDraftSlug, reindexProject, invalidateAgentProjectState, recordAgentRuntimeVersion, resolveDomainContextEnvelope, defaultKgPath, planAppFromPrompt, KGStore, planResearch, loadSemanticMetrics, cascadeTraceToEvidenceRouteSteps, createCascadeAnswerResult, createCascadeTrace, routeReasoningEffort, routeForCascadeAnswerTier, clampReasoningEffort, bumpReasoningEffort, resolveThinkingMode, coerceThinkingMode, upsertGeneratedDqlArtifactDraft, } from '@duckcodeailabs/dql-agent';
 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';
@@ -28,7 +31,9 @@ import { LocalAppStorage, LocalNotebookResearchStorage, defaultLocalAppsDbPath,
 import { Certifier, ENTERPRISE_RULES, evaluateInvariants, hasInvariantViolation, } from '@duckcodeailabs/dql-governance';
 import { buildSemanticObjectDetail, buildSemanticTree, computeSyncDiff, loadSemanticImportManifest, performSemanticImport, previewSemanticImport, syncSemanticImport, } from './semantic-import.js';
 import { clearBlockStudioImportSessions, candidateToDqlSource, createBlockStudioImportSession, deleteBlockStudioImportSession, listBlockStudioImportSessions, loadBlockStudioImportSession, readBlockStudioImportCandidate, parameterizeSqlForDqlImport, updateBlockStudioImportCandidate, writeBlockStudioImportSession, writeBlockStudioImportCandidate, } from './block-studio-import.js';
-import { MetricFlowUnavailableError, compileMetricFlowQuery, hasDbtSemanticManifest, hasMetricFlowCli, } from "./metricflow.js";
+import { MetricFlowUnavailableError, hasDbtSemanticManifest, } from "./metricflow.js";
+import { compileSemanticRuntimeQuery, getSemanticRuntimeStatus, isSemanticRuntimeError, listRuntimeCompatibleDimensions, semanticMetricExecutionCapability as runtimeMetricExecutionCapability, SemanticRuntimeRequiredError, testSemanticRuntimeDraft, } from './semantic-runtime.js';
+import { getSemanticRuntimeSettings, saveTestedSemanticRuntimeSettings, } from './semantic-runtime-settings.js';
 import { NotebookDatasetWorkspace, } from "./notebook-datasets.js";
 import { prepareBlockInvocation } from './block-invocation.js';
 const NOTEBOOK_EXECUTE_PREVIEW_ROW_LIMIT = 500;
@@ -164,17 +169,26 @@ export function parseAgentRunRequestBody(body) {
 }
 const AGENT_LOOKUP_DEADLINE_MS = 45_000;
 const AGENT_RESEARCH_DEADLINE_MS = 120_000;
+/** Env-tunable run deadline (e.g. slow subscription-CLI providers), clamped to sane bounds. */
+function resolveAgentDeadlineMs(envKey, fallback, env = process.env) {
+    const configured = Number(env[envKey]);
+    if (!Number.isFinite(configured) || configured <= 0)
+        return fallback;
+    return Math.max(15_000, Math.min(600_000, Math.floor(configured)));
+}
 /**
  * PERF-002: one wall-clock budget follows the request through routing, provider
  * calls, repair, and execution. Ordinary Ask never inherits Research's budget
  * merely because it spans two tables; explicit/deep investigation does.
  */
-export function agentRunDeadlineMs(request) {
+export function agentRunDeadlineMs(request, env = process.env) {
+    const lookupDeadline = resolveAgentDeadlineMs('DQL_AGENT_LOOKUP_DEADLINE_MS', AGENT_LOOKUP_DEADLINE_MS, env);
+    const researchDeadline = resolveAgentDeadlineMs('DQL_AGENT_RESEARCH_DEADLINE_MS', AGENT_RESEARCH_DEADLINE_MS, env);
     if (request.requestedMode === 'research' || request.analysisDepth === 'deep') {
-        return AGENT_RESEARCH_DEADLINE_MS;
+        return researchDeadline;
     }
     const plan = buildAnalysisQuestionPlan(request.question);
-    return plan.needsResearchWorkspace ? AGENT_RESEARCH_DEADLINE_MS : AGENT_LOOKUP_DEADLINE_MS;
+    return plan.needsResearchWorkspace ? researchDeadline : lookupDeadline;
 }
 export function shouldSynthesizeAgentRunAnswer(governedAnswer) {
     if (governedAnswer.kind === 'no_answer')
@@ -215,7 +229,11 @@ function businessNarrativeGaps(warnings) {
 // source of prior turns (survives refresh); the client-built context remains
 // the fallback for embedders that never send a threadId.
 async function conversationContextFromThread(store, threadId, clientContext, question) {
-    const turns = store.recentTurns(threadId, 8).map((turn) => {
+    // Token-budget backstop: six verbatim turns with per-field caps. Older turns
+    // remain reachable through the rolling summary + semantic recall below —
+    // carrying more raw prose mostly slows every provider call on follow-ups.
+    const clampTurnText = (value) => value && value.length > 1_200 ? `${value.slice(0, 1_200)}…` : value;
+    const turns = store.recentTurns(threadId, 6).map((turn) => {
         const contract = turn.contract ?? {};
         const topN = contract.topN;
         const topNValue = typeof topN === 'number'
@@ -225,8 +243,8 @@ async function conversationContextFromThread(store, threadId, clientContext, que
                 : undefined;
         return compactConversationRecord({
             id: turn.id,
-            question: turn.question,
-            answerSummary: turn.answerSummary,
+            question: clampTurnText(turn.question),
+            answerSummary: clampTurnText(turn.answerSummary),
             sourceCertifiedBlock: turn.sourceCertifiedBlock,
             route: turn.route,
             trustLabel: turn.trustLabel,
@@ -425,6 +443,8 @@ export async function startLocalServer(opts) {
     const loopback = bindHost === '127.0.0.1' || bindHost === 'localhost' || bindHost === '::1';
     const authToken = opts.authToken ?? process.env.DQL_SERVER_TOKEN;
     const runtimeVersion = readDqlRuntimeVersion();
+    // Warm the latest-version cache in the background (2s cap, 24h cache; offline → unknown).
+    void fetchLatestPublishedDqlVersion();
     const allowedOrigins = new Set((opts.allowedOrigins ?? (process.env.DQL_ALLOWED_ORIGINS ?? '').split(','))
         .map((value) => value.trim().replace(/\/$/, ''))
         .filter(Boolean));
@@ -1069,12 +1089,17 @@ export async function startLocalServer(opts) {
         // dialect-correct SQL (e.g. DATE_TRUNC / identifier quoting). Absent when no
         // connection is configured — the compiler then uses its default dialect.
         let semanticDriver;
+        let semanticConnection;
         try {
-            semanticDriver = requireActiveConnection().driver;
+            semanticConnection = requireActiveConnection();
+            semanticDriver = semanticConnection.driver;
         }
         catch {
             semanticDriver = undefined;
         }
+        const semanticTableMapping = semanticLayer && semanticConnection
+            ? await resolveSemanticTableMapping(executor, semanticConnection, semanticLayer)
+            : undefined;
         const requestedDomain = agentRunWorkspaceValue(request, 'domain');
         const requestedPurpose = agentRunWorkspaceValue(request, 'purpose');
         const requestedModelAreaId = agentRunWorkspaceValue(request, 'modelAreaId');
@@ -1093,7 +1118,12 @@ export async function startLocalServer(opts) {
         await runner.run({
             provider: resolvedProvider,
             messages: [
-                ...(request.history ?? []).map((message) => ({ role: message.role, content: message.text })),
+                // No-thread fallback path: bound the raw client history so follow-ups
+                // cannot inflate every provider call (8 turns × 4k chars).
+                ...(request.history ?? []).slice(-8).map((message) => ({
+                    role: message.role,
+                    content: message.text.length > 4_000 ? `${message.text.slice(0, 4_000)}…` : message.text,
+                })),
                 ...(isRepair
                     ? [{ role: 'assistant', content: `The prior attempt needs repair without changing the original question or requested output grain: ${repair?.repairHint}` }]
                     : []),
@@ -1116,6 +1146,26 @@ export async function startLocalServer(opts) {
                 projectSnapshots.assertCurrent(snapshotId);
             },
             ...(semanticDriver ? { semanticDriver } : {}),
+            ...(semanticTableMapping ? { semanticTableMapping } : {}),
+            ...(semanticLayer ? {
+                semanticQueryCompiler: async (selection) => {
+                    const compiled = await compileSemanticRuntimeQuery({
+                        ...selection,
+                        dimensions: selection.dimensions ?? [],
+                    }, {
+                        projectRoot,
+                        projectConfig,
+                        detectedProvider: semanticDetectedProvider,
+                        semanticLayer: semanticLayer,
+                        driver: semanticDriver,
+                        tableMapping: semanticTableMapping,
+                    });
+                    if (!compiled) {
+                        throw new SemanticRuntimeRequiredError('The selected semantic members could not be composed. Configure dbt Cloud Semantic Layer or a compatible local MetricFlow runtime for derived metrics.');
+                    }
+                    return { sql: compiled.sql, engine: compiled.engine };
+                },
+            } : {}),
             ...(routeDecision?.meaningResolution?.selectedConceptIds.length
                 ? { preferredEvidenceIds: routeDecision.meaningResolution.selectedConceptIds }
                 : {}),
@@ -1429,6 +1479,9 @@ export async function startLocalServer(opts) {
             applySmartVisualization(governedAnswer, request.question);
         }
         catch (error) {
+            // Deadline/cancellation propagates to the engine, which renders the
+            // graceful "bounded execution deadline" outcome — never a provider error.
+            rethrowIfCancelled(error, request.signal);
             const message = formatAgentRunInfrastructureError(error, 'AI answer provider');
             return {
                 summary: message,
@@ -1456,7 +1509,7 @@ export async function startLocalServer(opts) {
         const isExploratory = Boolean(governedAnswer.exploratoryCandidate);
         const isExecutionFailure = agentAnswerHasExecutionFailure(governedAnswer);
         const isGroundingGap = governedAnswer.kind === 'no_answer'
-            && governedAnswer.refusalCode === 'grounding_gap'
+            && (governedAnswer.refusalCode === 'grounding_gap' || governedAnswer.refusalCode === 'modeling_gap')
             && !isExploratory;
         const isProviderError = governedAnswer.kind === 'no_answer' && governedAnswer.refusalCode === 'provider_error';
         // AGT-004: a rejected attribution/export/proof policy is a deliberate
@@ -1786,6 +1839,7 @@ export async function startLocalServer(opts) {
                     }
                 }
                 catch (error) {
+                    rethrowIfCancelled(error, request.signal);
                     researchWorkspaceError = formatNotebookResearchStorageError(error);
                 }
             }
@@ -2355,7 +2409,13 @@ export async function startLocalServer(opts) {
         getEvidence: buildAgentRunEvidence,
         getCatalogContext: buildRankedAgentRunCatalogContext,
     });
-    const agentRunStore = new FileAgentRunStore({ path: defaultAgentRunStorePath(projectRoot) });
+    // P0: one row per run with retention + old-run compaction. The legacy JSON
+    // store rewrote the entire file (123 MB observed) twice per answered question;
+    // existing history is imported once and the JSON renamed to *.migrated.
+    const agentRunStore = new SqliteAgentRunStore({
+        path: defaultAgentRunSqlitePath(projectRoot),
+        legacyJsonPath: defaultAgentRunStorePath(projectRoot),
+    });
     // A run may outlive its streaming browser connection, so cancellation is
     // server-owned and keyed by run id rather than relying on fetch abort alone.
     const activeAgentRunControllers = new Map();
@@ -2425,13 +2485,28 @@ export async function startLocalServer(opts) {
                     const activeConnection = requireActiveConnection();
                     const tableMapping = await resolveSemanticTableMapping(executor, activeConnection, semanticLayer);
                     const plan = buildExecutionPlan(resolved.cell, { semanticLayer, driver: activeConnection.driver, tableMapping });
-                    if (!plan) {
+                    const semanticCompose = resolved.cell.type === 'dql'
+                        && semanticLayer
+                        && /\btype\s*=\s*"semantic"/i.test(resolved.cell.source)
+                        ? await composeSemanticBlockSqlForRuntime(resolved.cell.source, semanticLayer, {
+                            driver: activeConnection.driver,
+                            tableMapping,
+                            detectedProvider: semanticDetectedProvider,
+                            projectRoot,
+                            projectConfig,
+                        })
+                        : null;
+                    if (semanticCompose && !semanticCompose.sql) {
+                        throw new Error(semanticCompose.diagnostics.map((diagnostic) => diagnostic.message).join(' '));
+                    }
+                    const executableSql = semanticCompose?.sql ?? plan?.sql;
+                    if (!executableSql) {
                         snapshotCells.push({ cellId, status: 'idle', executionCount: 0, executedAt });
                         continue;
                     }
-                    const prepared = prepareLocalExecution(plan.sql, activeConnection, projectRoot, projectConfig);
+                    const prepared = prepareLocalExecution(executableSql, activeConnection, projectRoot, projectConfig);
                     assertAppAccess({ app, domain: resolved.domain ?? app.domain, level: 'execute' });
-                    const rawResult = await executor.executeQuery(prepared.sql, plan.sqlParams, runtimeVariables(plan.variables), prepared.connection);
+                    const rawResult = await executor.executeQuery(prepared.sql, plan?.sqlParams ?? [], runtimeVariables(plan?.variables ?? {}), prepared.connection);
                     const result = normalizeQueryResult(rawResult);
                     snapshotCells.push({
                         cellId,
@@ -2478,6 +2553,7 @@ export async function startLocalServer(opts) {
         const invocation = prepareBlockInvocation({
             source,
             parameters: invocationInput?.parameters,
+            parameterSources: invocationInput?.parameterSources,
             question: invocationInput?.question,
             surface: 'ask_ai',
         });
@@ -2490,7 +2566,7 @@ export async function startLocalServer(opts) {
         const tableMapping = await resolveSemanticTableMapping(executor, activeConnection, semanticLayer);
         const plan = buildExecutionPlan({ id: `agent-${metadata.name ?? 'dql-artifact'}`, type: 'dql', source, title: metadata.name ?? 'DQL artifact' }, { semanticLayer, driver: activeConnection.driver, tableMapping, parameters: invocation.values });
         const semanticCompose = semanticLayer
-            ? composeSemanticBlockSql(source, semanticLayer, {
+            ? await composeSemanticBlockSqlForRuntime(source, semanticLayer, {
                 driver: activeConnection.driver,
                 tableMapping,
                 projectRoot,
@@ -2574,10 +2650,11 @@ export async function startLocalServer(opts) {
      * candidate remains review-required and is not executed automatically.
      */
     const executeExploratoryCandidate = async (candidate, schemaContext = [], question = '', requestedTopN) => {
-        const preflight = repairExploratorySqlBeforeExecution(candidate.sql, schemaContext, question);
+        const activeConnection = requireActiveConnection();
+        const preflight = repairExploratorySqlBeforeExecution(candidate.sql, schemaContext, question, activeConnection.driver);
         const boundedSql = applyRequestedTopNToExploratorySql(preflight.sql, requestedTopN);
         const repairs = boundedSql === preflight.sql
-            ? preflight.repairs
+            ? [...preflight.repairs]
             : [...preflight.repairs, `Applied the requested overall top-${requestedTopN} bound before exploratory execution.`];
         if (preflight.blockedReason) {
             return {
@@ -2587,23 +2664,65 @@ export async function startLocalServer(opts) {
                 error: preflight.blockedReason,
             };
         }
-        const analysis = analyzeSqlReferences(boundedSql);
+        const analysis = analyzeSqlReferences(boundedSql, activeConnection.driver);
         if (!analysis.parsed) {
             return { proofs: [], sql: boundedSql, repairs, error: 'DQL could not parse the exploratory SQL to validate its join predicates.' };
         }
+        const probeableJoins = probeableExploratoryJoins(analysis.joins, analysis.ctes);
         // A normal customer → order → order-item → product question needs three
         // joins. Keep the lane bounded, but do not reject this common dbt-star path
-        // solely because the old two-join demo limit was too small.
-        if (analysis.joins.length > 4) {
+        // solely because the old two-join demo limit was too small. CTE-internal
+        // joins are counted physically (they appear in analysis.joins with their
+        // physical endpoints); joins ON a CTE are restructuring, not new paths.
+        if (probeableJoins.length > 4) {
             return { proofs: [], sql: boundedSql, repairs, error: 'This exploratory query has more than four joins and requires an analyst to review the relationship path.' };
         }
-        if (analysis.joins.some((join) => !join.leftRelation || !join.rightRelation)) {
+        if (probeableJoins.some((join) => !join.leftRelation || !join.rightRelation)) {
             return { proofs: [], sql: boundedSql, repairs, error: 'This exploratory query has a join endpoint DQL could not resolve for bounded validation.' };
         }
-        const activeConnection = requireActiveConnection();
+        // Structural binding: when the candidate carries a declared draft join path,
+        // every SQL join must ride one of its edges on the declared key pair. A join
+        // outside the declared path (or on different keys) is not executed — it is a
+        // review-required modeling question, not a runtime guess.
+        const declaredEdges = candidate.exploratoryPath?.edges ?? [];
+        const joinEdges = new Map();
+        if (declaredEdges.length > 0) {
+            for (const [index, join] of probeableJoins.entries()) {
+                const edge = declaredEdges.find((value) => declaredExploratoryRelationMatches(join.leftRelation, value.fromRelation) && declaredExploratoryRelationMatches(join.rightRelation, value.toRelation)
+                    || declaredExploratoryRelationMatches(join.leftRelation, value.toRelation) && declaredExploratoryRelationMatches(join.rightRelation, value.fromRelation));
+                if (!edge) {
+                    return {
+                        proofs: [],
+                        sql: boundedSql,
+                        repairs,
+                        error: `The join between ${join.leftRelation} and ${join.rightRelation} is not part of the declared relationship path, so DQL did not execute it. Declare the relationship in the DQL model to enable it.`,
+                    };
+                }
+                const keyMatches = edge.keys.some((key) => exploratoryColumnsMatch(join.leftColumn, key.from) && exploratoryColumnsMatch(join.rightColumn, key.to)
+                    || exploratoryColumnsMatch(join.leftColumn, key.to) && exploratoryColumnsMatch(join.rightColumn, key.from));
+                if (!keyMatches) {
+                    return {
+                        proofs: [],
+                        sql: boundedSql,
+                        repairs,
+                        error: `The join ${join.leftColumn} = ${join.rightColumn} uses different keys than relationship "${edge.relationshipId}" declares (${edge.keys.map((key) => `${key.from}=${key.to}`).join(', ')}). Review the declared keys before executing.`,
+                    };
+                }
+                joinEdges.set(index, edge);
+            }
+            const exercised = new Set([...joinEdges.values()].map((edge) => edge.relationshipId));
+            for (const edge of declaredEdges) {
+                if (!exercised.has(edge.relationshipId)) {
+                    repairs.push(`Declared relationship "${edge.relationshipId}" was not exercised by this query.`);
+                }
+            }
+        }
+        if (probeableJoins.length < analysis.joins.length) {
+            repairs.push(`Skipped join probes for ${analysis.joins.length - probeableJoins.length} join(s) on derived (CTE) relations; the final query execution validates them.`);
+        }
         const proofs = [];
         try {
-            for (const join of analysis.joins) {
+            for (const [index, join] of probeableJoins.entries()) {
                 const proofSql = buildExploratoryJoinProbeSql({
                     leftRelation: join.leftRelation,
                     leftColumn: join.leftColumn,
@@ -2613,6 +2732,14 @@ export async function startLocalServer(opts) {
                 const prepared = prepareLocalExecution(proofSql, activeConnection, projectRoot, projectConfig);
                 const raw = await executor.executeQuery(prepared.sql, [], runtimeVariables({}), prepared.connection);
                 proofs.push({ summary: summarizeExploratoryJoinProbe(raw.rows, join.leftRelation, join.leftColumn, join.rightRelation, join.rightColumn) });
+                // Gating (not observational): a structural contradiction between the
+                // UNFILTERED key overlap and the declared relationship stops automatic
+                // execution. A legitimately empty *filtered* business result is still an
+                // answer — these gates only inspect the raw key samples.
+                const contradiction = exploratoryProbeContradiction(raw.rows, join, joinEdges.get(index));
+                if (contradiction) {
+                    return { proofs, sql: boundedSql, repairs, error: contradiction };
+                }
             }
             const result = await executeGeneratedSqlForAgent(boundedSql);
             return { result, proofs, sql: boundedSql, repairs };
@@ -3461,7 +3588,7 @@ export async function startLocalServer(opts) {
             throw new Error(`Provide required parameter${invocation.unresolvedParameters.length === 1 ? '' : 's'}: ${invocation.unresolvedParameters.join(', ')}.`);
         }
         const semanticCompose = semanticLayer
-            ? composeSemanticBlockSql(source, semanticLayer, {
+            ? await composeSemanticBlockSqlForRuntime(source, semanticLayer, {
                 driver: activeConnection.driver,
                 tableMapping,
                 projectRoot,
@@ -3515,7 +3642,7 @@ export async function startLocalServer(opts) {
         // pre-compiled query, that's the query (not a recompiled metric), so the test's
         // output columns match the block's declared outputs.
         const semanticCompose = semanticLayer
-            ? composeSemanticBlockSql(source, semanticLayer, {
+            ? await composeSemanticBlockSqlForRuntime(source, semanticLayer, {
                 driver: activeConnection.driver,
                 tableMapping,
                 projectRoot,
@@ -3733,8 +3860,19 @@ export async function startLocalServer(opts) {
             }
         }
         if (req.method === 'GET' && path === '/api/health') {
+            // REL-002: expose runtime/build identity so a server started before a
+            // rebuild or running a different version than the project pin is visibly
+            // stale. Uses only the cached latest-version lookup — never blocks.
+            const versionStatus = resolveDqlRuntimeVersionStatus({ projectRoot, runningVersion: runtimeVersion });
+            void fetchLatestPublishedDqlVersion();
+            const healthValueGrounding = resolveAgentRuntimeValueGrounding(projectConfig);
+            const retrievalHealth = resolveRetrievalHealthStatus({
+                projectRoot,
+                valueGroundingMode: healthValueGrounding.mode,
+                searchSafeColumnCount: healthValueGrounding.searchSafeColumns.size,
+            });
             res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
-            res.end(serializeJSON({ status: 'ok', version: runtimeVersion }));
+            res.end(serializeJSON({ status: 'ok', version: runtimeVersion, versionStatus, retrievalHealth }));
             return;
         }
         if (req.method === 'GET' && path === '/api/onboarding/launch') {
@@ -4543,6 +4681,11 @@ export async function startLocalServer(opts) {
                 const conversationStore = parsed.request.threadId ? getConversationStore() : null;
                 if (conversationStore && parsed.request.threadId && conversationStore.getThread(parsed.request.threadId)) {
                     parsed.request.conversationContext = await conversationContextFromThread(conversationStore, parsed.request.threadId, parsed.request.conversationContext, parsed.request.question);
+                    // The persisted thread is authoritative for prior turns. Raw client
+                    // history would duplicate the same conversation into the prompt a
+                    // second time — dropping it keeps follow-up prompts bounded.
+                    if (parsed.request.history?.length)
+                        parsed.request.history = [];
                 }
                 const wantsStream = url.searchParams.get('stream') === '1' || url.searchParams.get('stream') === 'true';
                 const runId = parsed.request.runId;
@@ -5917,7 +6060,7 @@ export async function startLocalServer(opts) {
                                 operator: filter.operator,
                                 values: Array.isArray(filter.value) ? filter.value.map(String) : [String(filter.value)],
                             }));
-                            const composed = composeRuntimeSemanticQuery({
+                            const composed = await composeRuntimeSemanticQuery({
                                 metrics: item.semantic.metrics,
                                 dimensions: item.semantic.dimensions ?? [],
                                 filters: [...staticFilters, ...activeFilters],
@@ -6008,7 +6151,7 @@ export async function startLocalServer(opts) {
                             continue;
                         }
                         const semanticCompose = semanticLayer
-                            ? composeSemanticBlockSql(source, semanticLayer, {
+                            ? await composeSemanticBlockSqlForRuntime(source, semanticLayer, {
                                 driver: targetConnection.driver,
                                 tableMapping,
                                 projectRoot,
@@ -7387,7 +7530,7 @@ export async function startLocalServer(opts) {
                 const activeConnection = requireActiveConnection();
                 const tableMapping = await resolveSemanticTableMapping(executor, activeConnection, semanticLayer);
                 const semanticCompose = semanticLayer
-                    ? composeSemanticBlockSql(source, semanticLayer, {
+                    ? await composeSemanticBlockSqlForRuntime(source, semanticLayer, {
                         driver: activeConnection.driver,
                         tableMapping,
                         projectRoot,
@@ -7893,8 +8036,23 @@ export async function startLocalServer(opts) {
                         draftSave: readiness.candidate.draftSave ?? { status: 'pending' },
                     };
                     writeBlockStudioImportCandidate(projectRoot, importId, next);
-                    await refreshLocalMetadataCatalog(projectRoot);
-                    const payload = openBlockStudioDocument(projectRoot, savedPath, semanticLayer);
+                    let compiledManifest;
+                    let lineageRefresh;
+                    try {
+                        compiledManifest = compileBlockStudioManifest(projectRoot, projectConfig);
+                        lineageRefresh = { status: 'ready', compiledAt: new Date().toISOString() };
+                    }
+                    catch (error) {
+                        lineageRefresh = {
+                            status: 'failed',
+                            message: error instanceof Error ? error.message : String(error),
+                        };
+                    }
+                    await refreshLocalMetadataCatalog(projectRoot, compiledManifest, semanticLayer);
+                    const payload = {
+                        ...openBlockStudioDocument(projectRoot, savedPath, semanticLayer),
+                        lineageRefresh,
+                    };
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ candidate: next, block: payload, certification }));
                     return;
@@ -8007,10 +8165,23 @@ export async function startLocalServer(opts) {
                 }
                 const nextSession = { ...session, candidates: nextCandidates, updatedAt: new Date().toISOString() };
                 writeBlockStudioImportSession(projectRoot, nextSession);
-                if (saved.length > 0)
-                    await refreshLocalMetadataCatalog(projectRoot);
+                let lineageRefresh;
+                if (saved.length > 0) {
+                    let compiledManifest;
+                    try {
+                        compiledManifest = compileBlockStudioManifest(projectRoot, projectConfig);
+                        lineageRefresh = { status: 'ready', compiledAt: new Date().toISOString() };
+                    }
+                    catch (error) {
+                        lineageRefresh = {
+                            status: 'failed',
+                            message: error instanceof Error ? error.message : String(error),
+                        };
+                    }
+                    await refreshLocalMetadataCatalog(projectRoot, compiledManifest, semanticLayer);
+                }
                 res.writeHead(errors.length > 0 ? 207 : 200, { 'Content-Type': 'application/json; charset=utf-8' });
-                res.end(serializeJSON({ ok: errors.length === 0, session: nextSession, saved, errors }));
+                res.end(serializeJSON({ ok: errors.length === 0, session: nextSession, saved, errors, lineageRefresh }));
             }
             catch (error) {
                 res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -8154,9 +8325,14 @@ export async function startLocalServer(opts) {
                 const connections = getProjectConnectionsForApi(cfg);
                 const defaultKey = resolveDefaultConnectionKey(cfg, connections) ?? Object.keys(connections)[0] ?? 'default';
                 const userPrefs = readUserPrefs(userPrefsPath);
+                // UI-009 / PERF-001: Block Studio already loads the canonical semantic
+                // layer. Let it omit this second, potentially multi-megabyte rendering
+                // of the same 7,500+ object catalog while keeping the route compatible
+                // for older clients.
+                const includeSemantic = url.searchParams.get('includeSemantic') !== 'false';
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
-                    semanticTree: semanticLayer ? buildSemanticTree(semanticLayer, semanticImportManifest) : null,
+                    semanticTree: includeSemantic && semanticLayer ? buildSemanticTree(semanticLayer, semanticImportManifest) : null,
                     databaseTree: await buildDatabaseSchemaTree(projectRoot, executor, connection),
                     connection: {
                         default: defaultKey,
@@ -8317,8 +8493,26 @@ export async function startLocalServer(opts) {
                         stableSuffix: metadata.candidateId,
                     })
                     : saveBlockStudioArtifacts(projectRoot, saveOptions);
-                await refreshLocalMetadataCatalog(projectRoot);
-                const payload = openBlockStudioDocument(projectRoot, savedPath, semanticLayer);
+                let compiledManifest;
+                let lineageRefresh;
+                try {
+                    compiledManifest = compileBlockStudioManifest(projectRoot, projectConfig);
+                    lineageRefresh = { status: 'ready', compiledAt: new Date().toISOString() };
+                }
+                catch (error) {
+                    // The block is already safely stored. Preserve it and report the
+                    // rebuild failure separately instead of turning a successful save
+                    // into a misleading 500 response.
+                    lineageRefresh = {
+                        status: 'failed',
+                        message: error instanceof Error ? error.message : String(error),
+                    };
+                }
+                await refreshLocalMetadataCatalog(projectRoot, compiledManifest, semanticLayer);
+                const payload = {
+                    ...openBlockStudioDocument(projectRoot, savedPath, semanticLayer),
+                    lineageRefresh,
+                };
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON(payload));
             }
@@ -8717,6 +8911,47 @@ export async function startLocalServer(opts) {
             }
             return;
         }
+        // ── Semantic runtime adapters (API-004 / UI-009 / E2E-008) ───────────────
+        if (req.method === 'GET' && path === '/api/semantic-runtime') {
+            try {
+                const runtime = await getSemanticRuntimeStatus(projectRoot, { probeConfiguredCloud: true });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ...getSemanticRuntimeSettings(projectRoot), runtime }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/semantic-runtime/dbt-cloud/test') {
+            try {
+                const body = await readJSON(req);
+                const result = await testSemanticRuntimeDraft(projectRoot, body);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(result));
+            }
+            catch (error) {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: false, error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/semantic-runtime/dbt-cloud/apply') {
+            try {
+                const body = await readJSON(req);
+                const result = await testSemanticRuntimeDraft(projectRoot, body);
+                const settings = saveTestedSemanticRuntimeSettings(projectRoot, body, result);
+                const runtime = await getSemanticRuntimeStatus(projectRoot);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: true, ...settings, runtime }));
+            }
+            catch (error) {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: false, error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
         // ── Semantic layer discovery API ─────────────────────────────────────────
         if (req.method === 'GET' && path === '/api/semantic-layer') {
             const userPrefs = readUserPrefs(userPrefsPath);
@@ -8746,8 +8981,7 @@ export async function startLocalServer(opts) {
             const dbtManifestReady = provider === 'dbt'
                 ? hasDbtSemanticManifest(projectRoot, semanticConfig?.projectPath)
                 : false;
-            const metricFlowReady = provider === 'dbt' ? hasMetricFlowCli() : false;
-            const dbtExecutionReady = dbtManifestReady && metricFlowReady;
+            const semanticRuntime = await getSemanticRuntimeStatus(projectRoot, { probeConfiguredCloud: true });
             const metrics = semanticLayer.listMetrics().map((m) => ({
                 name: m.name,
                 label: m.label,
@@ -8762,7 +8996,7 @@ export async function startLocalServer(opts) {
                 typeParams: m.typeParams ?? null,
                 filter: m.filter ?? null,
                 source: m.source ?? null,
-                execution: semanticMetricExecutionCapability(m.name, semanticLayer, provider, metricFlowReady, connection?.driver),
+                execution: runtimeMetricExecutionCapability(m.name, semanticLayer, provider, semanticRuntime),
             }));
             const measures = semanticLayer.listMeasures().map((m) => ({
                 name: m.name,
@@ -8860,24 +9094,21 @@ export async function startLocalServer(opts) {
                 owner: q.owner ?? null,
                 source: q.source ?? null,
             }));
-            const dbtExecutionSetup = dbtExecutionReady
-                ? null
-                : !dbtManifestReady && !metricFlowReady
-                    ? 'Run `dbt parse` or `dbt build` so target/semantic_manifest.json exists, and install MetricFlow so `mf` is on PATH.'
-                    : !dbtManifestReady
-                        ? 'Run `dbt parse` or `dbt build` so target/semantic_manifest.json exists.'
-                        : 'Install MetricFlow so `mf` is on PATH, or set DQL_METRICFLOW_BIN to the MetricFlow executable.';
+            const dbtExecutionSetup = !dbtManifestReady
+                ? 'Run `dbt parse` or `dbt build` so target/semantic_manifest.json exists.'
+                : semanticRuntime.setup;
             res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
             res.end(serializeJSON({
                 available: true,
                 provider,
                 execution: provider === 'dbt'
                     ? {
-                        engine: 'metricflow',
-                        ready: dbtExecutionReady,
+                        engine: semanticRuntime.active,
+                        ready: semanticRuntime.active !== 'native' || metrics.every((metric) => metric.execution.status === 'ready'),
                         setup: dbtExecutionSetup,
+                        adapters: semanticRuntime.adapters,
                     }
-                    : { engine: 'native', ready: true, setup: null },
+                    : { engine: 'native', ready: true, setup: null, adapters: semanticRuntime.adapters },
                 errors: semanticLayerErrors,
                 metrics,
                 measures,
@@ -9214,7 +9445,7 @@ export async function startLocalServer(opts) {
                 .split(',')
                 .map((value) => value.trim())
                 .filter(Boolean);
-            const dimensions = semanticLayer.listCompatibleDimensions(metrics).map((d) => ({
+            const dimensions = (await listRuntimeCompatibleDimensions(projectRoot, semanticLayer, metrics)).map((d) => ({
                 name: d.name,
                 label: d.label,
                 description: d.description,
@@ -9727,37 +9958,8 @@ export async function startLocalServer(opts) {
                 // Resolve which connection to use — request can override default
                 const targetConnection = requireActiveConnection(isConnectionConfig(body.connection) ? body.connection : connection);
                 const driver = targetConnection.driver;
-                // Build table mapping: resolve semantic model names to actual DB table names
-                let tableMapping;
-                try {
-                    const tablesResult = await executor.executeQuery(`SELECT table_schema, table_name FROM information_schema.tables WHERE UPPER(table_schema) NOT IN ('INFORMATION_SCHEMA', 'PG_CATALOG')`, [], {}, targetConnection);
-                    const dbTableNames = new Set();
-                    const schemaQualified = new Map();
-                    for (const row of tablesResult.rows) {
-                        const schema = String(row['table_schema'] ?? '');
-                        const name = String(row['table_name'] ?? '');
-                        dbTableNames.add(name);
-                        schemaQualified.set(name, schema ? `${schema}.${name}` : name);
-                    }
-                    // For each table in the semantic layer, map to qualified name if it exists
-                    const allSemanticTables = new Set();
-                    for (const m of semanticLayer.listMetrics())
-                        allSemanticTables.add(m.table);
-                    for (const d of semanticLayer.listDimensions())
-                        allSemanticTables.add(d.table);
-                    tableMapping = {};
-                    for (const semTable of allSemanticTables) {
-                        if (dbTableNames.has(semTable) && schemaQualified.has(semTable)) {
-                            tableMapping[semTable] = schemaQualified.get(semTable);
-                        }
-                    }
-                    if (Object.keys(tableMapping).length === 0)
-                        tableMapping = undefined;
-                }
-                catch {
-                    // Non-fatal: proceed without table mapping
-                }
-                const composed = composeRuntimeSemanticQuery({
+                const tableMapping = await resolveSemanticTableMapping(executor, targetConnection, semanticLayer);
+                const composed = await composeRuntimeSemanticQuery({
                     metrics,
                     dimensions,
                     filters,
@@ -9775,10 +9977,10 @@ export async function startLocalServer(opts) {
                 });
                 if (!composed) {
                     const provider = semanticConfig?.provider ?? semanticDetectedProvider ?? 'dql';
-                    const metricFlowReady = provider === 'dbt' && hasMetricFlowCli();
+                    const semanticRuntime = await getSemanticRuntimeStatus(projectRoot, { probeConfiguredCloud: true });
                     const blocked = metrics.map((metricName) => ({
                         metric: metricName,
-                        ...semanticMetricExecutionCapability(metricName, semanticLayer, provider, metricFlowReady, driver),
+                        ...runtimeMetricExecutionCapability(metricName, semanticLayer, provider, semanticRuntime),
                     })).filter((capability) => capability.status !== 'ready');
                     res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({
@@ -9808,13 +10010,14 @@ export async function startLocalServer(opts) {
                     res.end(serializeJSON({ error: error.message, code: 'unauthorized' }));
                     return;
                 }
-                const status = error instanceof MetricFlowUnavailableError ? 400 : 500;
+                const runtimeError = isSemanticRuntimeError(error);
+                const status = runtimeError ? 400 : 500;
                 res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
                     error: error instanceof Error ? error.message : String(error),
-                    code: error instanceof MetricFlowUnavailableError ? 'metricflow_unavailable' : undefined,
-                    hint: error instanceof MetricFlowUnavailableError
-                        ? 'Install dbt Semantic Layer dependencies, run dbt parse/build to create target/semantic_manifest.json, then retry.'
+                    code: runtimeError ? 'SEMANTIC_RUNTIME_REQUIRED' : undefined,
+                    hint: runtimeError
+                        ? 'Configure dbt Cloud Semantic Layer in Project & dbt settings, or install a compatible local MetricFlow runtime.'
                         : undefined,
                 }));
             }
@@ -9831,31 +10034,8 @@ export async function startLocalServer(opts) {
                 const { metrics = [], dimensions = [], filters = [], limit, timeDimension, orderBy, savedQuery, engine } = body;
                 const targetConnection = requireActiveConnection(isConnectionConfig(body.connection) ? body.connection : connection);
                 const driver = targetConnection.driver;
-                let tableMapping;
-                try {
-                    const tablesResult = await executor.executeQuery(`SELECT table_schema, table_name FROM information_schema.tables WHERE UPPER(table_schema) NOT IN ('INFORMATION_SCHEMA', 'PG_CATALOG')`, [], {}, targetConnection);
-                    const schemaQualified = new Map();
-                    for (const row of tablesResult.rows) {
-                        const schema = String(row['table_schema'] ?? '');
-                        const name = String(row['table_name'] ?? '');
-                        schemaQualified.set(name, schema ? `${schema}.${name}` : name);
-                    }
-                    tableMapping = {};
-                    for (const metric of semanticLayer.listMetrics()) {
-                        if (schemaQualified.has(metric.table))
-                            tableMapping[metric.table] = schemaQualified.get(metric.table);
-                    }
-                    for (const dimension of semanticLayer.listDimensions()) {
-                        if (schemaQualified.has(dimension.table))
-                            tableMapping[dimension.table] = schemaQualified.get(dimension.table);
-                    }
-                    if (Object.keys(tableMapping).length === 0)
-                        tableMapping = undefined;
-                }
-                catch {
-                    tableMapping = undefined;
-                }
-                const composed = composeRuntimeSemanticQuery({
+                const tableMapping = await resolveSemanticTableMapping(executor, targetConnection, semanticLayer);
+                const composed = await composeRuntimeSemanticQuery({
                     metrics,
                     dimensions,
                     filters,
@@ -9873,10 +10053,10 @@ export async function startLocalServer(opts) {
                 });
                 if (!composed) {
                     const provider = semanticConfig?.provider ?? semanticDetectedProvider ?? 'dql';
-                    const metricFlowReady = provider === 'dbt' && hasMetricFlowCli();
+                    const semanticRuntime = await getSemanticRuntimeStatus(projectRoot, { probeConfiguredCloud: true });
                     const blocked = metrics.map((metricName) => ({
                         metric: metricName,
-                        ...semanticMetricExecutionCapability(metricName, semanticLayer, provider, metricFlowReady, driver),
+                        ...runtimeMetricExecutionCapability(metricName, semanticLayer, provider, semanticRuntime),
                     })).filter((capability) => capability.status !== 'ready');
                     res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({
@@ -9900,13 +10080,14 @@ export async function startLocalServer(opts) {
                 }));
             }
             catch (error) {
-                const status = error instanceof MetricFlowUnavailableError ? 400 : 500;
+                const runtimeError = isSemanticRuntimeError(error);
+                const status = runtimeError ? 400 : 500;
                 res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
                     error: error instanceof Error ? error.message : String(error),
-                    code: error instanceof MetricFlowUnavailableError ? 'metricflow_unavailable' : undefined,
-                    hint: error instanceof MetricFlowUnavailableError
-                        ? 'Install dbt Semantic Layer dependencies, run dbt parse/build to create target/semantic_manifest.json, then retry.'
+                    code: runtimeError ? 'SEMANTIC_RUNTIME_REQUIRED' : undefined,
+                    hint: runtimeError
+                        ? 'Configure dbt Cloud Semantic Layer in Project & dbt settings, or install a compatible local MetricFlow runtime.'
                         : undefined,
                 }));
             }
@@ -9931,7 +10112,8 @@ export async function startLocalServer(opts) {
                     return;
                 }
                 const targetConnection = requireActiveConnection(isConnectionConfig(body.connection) ? body.connection : connection);
-                const composed = composeRuntimeSemanticQuery({
+                const tableMapping = await resolveSemanticTableMapping(executor, targetConnection, semanticLayer);
+                const composed = await composeRuntimeSemanticQuery({
                     metrics,
                     dimensions,
                     filters,
@@ -9942,6 +10124,7 @@ export async function startLocalServer(opts) {
                     projectConfig,
                     detectedProvider: semanticDetectedProvider,
                     driver: targetConnection.driver,
+                    tableMapping,
                 });
                 if (!composed) {
                     res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -9972,13 +10155,14 @@ export async function startLocalServer(opts) {
                     res.end(serializeJSON({ error: 'Block already exists' }));
                     return;
                 }
-                const status = error instanceof MetricFlowUnavailableError ? 400 : 500;
+                const runtimeError = isSemanticRuntimeError(error);
+                const status = runtimeError ? 400 : 500;
                 res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
                     error: error instanceof Error ? error.message : String(error),
-                    code: error instanceof MetricFlowUnavailableError ? 'metricflow_unavailable' : undefined,
-                    hint: error instanceof MetricFlowUnavailableError
-                        ? 'Install dbt Semantic Layer dependencies, run dbt parse/build to create target/semantic_manifest.json, then retry.'
+                    code: runtimeError ? 'SEMANTIC_RUNTIME_REQUIRED' : undefined,
+                    hint: runtimeError
+                        ? 'Configure dbt Cloud Semantic Layer in Project & dbt settings, or install a compatible local MetricFlow runtime.'
                         : undefined,
                 }));
             }
@@ -10300,7 +10484,12 @@ export async function startLocalServer(opts) {
                     parameters,
                     question: typeof body.question === 'string' ? body.question : undefined,
                 });
-                const contract = prepareBlockInvocation({ source, parameters, surface: 'ask_ai' });
+                const contract = prepareBlockInvocation({
+                    source,
+                    parameters,
+                    question: typeof body.question === 'string' ? body.question : undefined,
+                    surface: 'ask_ai',
+                });
                 const certified = /\bstatus\s*=\s*"certified"/i.test(source);
                 const semantic = /\btype\s*=\s*"semantic"/i.test(source);
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -10396,6 +10585,7 @@ export async function startLocalServer(opts) {
                         parameters: body.parameters && typeof body.parameters === 'object' && !Array.isArray(body.parameters)
                             ? body.parameters
                             : {},
+                        question: typeof body.question === 'string' ? body.question : undefined,
                         surface: 'notebook',
                     })
                     : null;
@@ -10414,15 +10604,31 @@ export async function startLocalServer(opts) {
                     tableMapping,
                     parameters: invocation?.values,
                 });
-                if (!plan) {
+                const semanticCompose = executableCell.type === 'dql'
+                    && semanticLayer
+                    && /\btype\s*=\s*"semantic"/i.test(executableCell.source)
+                    ? await composeSemanticBlockSqlForRuntime(executableCell.source, semanticLayer, {
+                        driver: cellConnection.driver,
+                        tableMapping,
+                        parameters: invocation?.values,
+                        detectedProvider: semanticDetectedProvider,
+                        projectRoot,
+                        projectConfig,
+                    })
+                    : null;
+                if (semanticCompose && !semanticCompose.sql) {
+                    throw new Error(semanticCompose.diagnostics.map((diagnostic) => diagnostic.message).join(' '));
+                }
+                const executableSql = semanticCompose?.sql ?? plan?.sql;
+                if (!executableSql) {
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ cellType: cell.type, result: null }));
                     return;
                 }
-                const prepared = prepareLocalExecution(plan.sql, cellConnection, projectRoot, projectConfig);
+                const prepared = prepareLocalExecution(executableSql, cellConnection, projectRoot, projectConfig);
                 const app = loadRuntimeApp(projectRoot, typeof body.appId === 'string' ? body.appId : activePersonaAppId());
                 assertAppAccess({ app, domain: resolved.domain ?? app?.domain, level: 'execute' });
-                const rawResult = await executor.executeQuery(prepared.sql, plan.sqlParams, runtimeVariables({ ...plan.variables, ...(invocation?.values ?? {}) }), prepared.connection);
+                const rawResult = await executor.executeQuery(prepared.sql, plan?.sqlParams ?? [], runtimeVariables({ ...(plan?.variables ?? {}), ...(invocation?.values ?? {}) }), prepared.connection);
                 const normalized = normalizeQueryResult(rawResult);
                 // Enforce the block's declared invariants against the result set. This
                 // is additive: blocks without invariants produce `null` and the
@@ -10436,29 +10642,29 @@ export async function startLocalServer(opts) {
                     recordNotebookQueryRun(projectRoot, {
                         notebookPath: execContext.notebookPath,
                         cellId: execContext.cellId ?? cell.id,
-                        cellName: execContext.cellName ?? plan.title ?? resolved.blockName,
+                        cellName: execContext.cellName ?? plan?.title ?? resolved.blockName,
                         researchRunId: execContext.researchRunId,
                         source: execContext.source ?? (cell.type === 'dql' ? 'notebook_dql_cell' : 'notebook_cell'),
                         status: 'success',
                         rowCount: normalized.rowCount ?? normalized.rows.length,
                         durationMs: Date.now() - start,
-                        sql: plan.sql,
+                        sql: executableSql,
                         objectKey: resolved.blockPath,
                     });
                     updateNotebookResearchFromCellExecution(projectRoot, execContext, {
                         status: 'success',
                         resultPreview: normalized,
-                        sql: plan.sql,
+                        sql: executableSql,
                     });
                 }
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
                     cellType: cell.type,
-                    title: plan.title,
+                    title: plan?.title,
                     blockName: resolved.blockName,
                     blockPath: resolved.blockPath,
-                    chartConfig: plan.chartConfig,
-                    tests: plan.tests,
+                    chartConfig: plan?.chartConfig,
+                    tests: plan?.tests,
                     result: normalized,
                     ...(invocation ? {
                         invocation: {
@@ -11391,9 +11597,34 @@ function latestOpenContextBootstrapSession(projectRoot) {
     }
     return null;
 }
-async function refreshLocalMetadataCatalog(projectRoot) {
+/**
+ * API-004 / E2E-006: save-time compile for Block Studio. The manifest is
+ * replaced atomically so lineage readers and agent retrieval never observe a
+ * half-written snapshot, and an existing manifest survives compilation errors.
+ */
+export function compileBlockStudioManifest(projectRoot, projectConfig = loadProjectConfig(projectRoot)) {
+    const dbtManifestPath = resolveDbtManifestPath(projectRoot, projectConfig) ?? undefined;
+    const manifest = buildManifest({ projectRoot, dqlVersion: 'notebook', dbtManifestPath });
+    const manifestPath = join(projectRoot, 'dql-manifest.json');
+    const tempPath = `${manifestPath}.tmp-${process.pid}-${Date.now()}`;
+    try {
+        writeFileSync(tempPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf-8');
+        renameSync(tempPath, manifestPath);
+    }
+    catch (error) {
+        rmSync(tempPath, { force: true });
+        throw error;
+    }
+    _lineageCache.delete(projectRoot);
+    return manifest;
+}
+async function refreshLocalMetadataCatalog(projectRoot, manifest, semanticLayer) {
     try {
-        await ensureMetadataCatalogFresh(projectRoot, { force: true });
+        await ensureMetadataCatalogFresh(projectRoot, {
+            force: true,
+            ...(manifest ? { manifest } : {}),
+            ...(semanticLayer ? { semanticLayer } : {}),
+        });
     }
     catch {
         // The catalog is a rebuildable local cache. Save/certify flows should not
@@ -12846,13 +13077,13 @@ export function buildAgentPreviewSql(sql) {
  * only when the owning entity is retained in GROUP BY. It never invents a
  * relation, join key, or allocation rule.
  */
-export function repairExploratorySqlBeforeExecution(sql, schemaContext, question = '') {
+export function repairExploratorySqlBeforeExecution(sql, schemaContext, question = '', dialect = 'duckdb') {
     const repairs = [];
-    let repairedSql = qualifyExploratoryRelationsFromSchema(sql, schemaContext, repairs);
-    repairedSql = repairExploratoryRelationQualifiers(repairedSql, repairs);
-    repairedSql = repairExploratoryLifetimeMeasureSelection(repairedSql, schemaContext, question, repairs);
+    let repairedSql = qualifyExploratoryRelationsFromSchema(sql, schemaContext, repairs, dialect);
+    repairedSql = repairExploratoryRelationQualifiers(repairedSql, repairs, dialect);
+    repairedSql = repairExploratoryLifetimeMeasureSelection(repairedSql, schemaContext, question, repairs, dialect);
     repairedSql = repairExploratoryMisleadingPercentAliases(repairedSql, question, repairs);
-    const grainRepair = repairExploratoryNonAdditiveAggregates(repairedSql, schemaContext, repairs);
+    const grainRepair = repairExploratoryNonAdditiveAggregates(repairedSql, schemaContext, repairs, dialect);
     repairedSql = grainRepair.sql;
     return {
         sql: repairedSql,
@@ -12903,8 +13134,8 @@ export function applyRequestedTopNToExploratorySql(sql, requestedTopN) {
     }
     return `${withoutTerminator}\nLIMIT ${requestedTopN}`;
 }
-function qualifyExploratoryRelationsFromSchema(sql, schemaContext, repairs) {
-    const analysis = analyzeSqlReferences(sql);
+function qualifyExploratoryRelationsFromSchema(sql, schemaContext, repairs, dialect = 'duckdb') {
+    const analysis = analyzeSqlReferences(sql, dialect);
     if (!analysis.parsed)
         return sql;
     let repaired = sql;
@@ -12932,8 +13163,8 @@ function qualifyExploratoryRelationsFromSchema(sql, schemaContext, repairs) {
     }
     return repaired;
 }
-function repairExploratoryRelationQualifiers(sql, repairs) {
-    const analysis = analyzeSqlReferences(sql);
+function repairExploratoryRelationQualifiers(sql, repairs, dialect = 'duckdb') {
+    const analysis = analyzeSqlReferences(sql, dialect);
     if (!analysis.parsed)
         return sql;
     const declared = Object.entries(analysis.aliasToRelation).map(([qualifier, relation]) => ({
@@ -12956,10 +13187,10 @@ function repairExploratoryRelationQualifiers(sql, repairs) {
     }
     return repaired;
 }
-function repairExploratoryLifetimeMeasureSelection(sql, schemaContext, question, repairs) {
+function repairExploratoryLifetimeMeasureSelection(sql, schemaContext, question, repairs, dialect = 'duckdb') {
     if (!/\b(lifetime|life\s*span|lifespan|customer\s+life)\b/i.test(question))
         return sql;
-    const analysis = analyzeSqlReferences(sql);
+    const analysis = analyzeSqlReferences(sql, dialect);
     if (!analysis.parsed || analysis.joins.length === 0)
         return sql;
     const groupClause = sql.match(/\bgroup\s+by\s+([\s\S]*?)(?:\border\s+by\b|\blimit\b|\bqualify\b|\bhaving\b|$)/i)?.[1] ?? '';
@@ -12985,8 +13216,8 @@ function repairExploratoryLifetimeMeasureSelection(sql, schemaContext, question,
     }
     return repaired;
 }
-function repairExploratoryNonAdditiveAggregates(sql, schemaContext, repairs) {
-    const analysis = analyzeSqlReferences(sql);
+function repairExploratoryNonAdditiveAggregates(sql, schemaContext, repairs, dialect = 'duckdb') {
+    const analysis = analyzeSqlReferences(sql, dialect);
     if (!analysis.parsed || analysis.joins.length === 0)
         return { sql };
     const risky = analysis.aggregates.filter((aggregate) => aggregate.func.toLowerCase() === 'sum'
@@ -13108,6 +13339,16 @@ export function buildExploratoryJoinProbeSql(input) {
     SELECT right_key, COUNT(*) AS match_count
     FROM matches
     GROUP BY right_key
+  ),
+  left_key_counts AS (
+    SELECT join_key, COUNT(*) AS key_count
+    FROM left_sample
+    GROUP BY join_key
+  ),
+  right_key_counts AS (
+    SELECT join_key, COUNT(*) AS key_count
+    FROM right_sample
+    GROUP BY join_key
   )
 SELECT
   (SELECT COUNT(*) FROM left_sample) AS left_sample_rows,
@@ -13116,7 +13357,87 @@ SELECT
   (SELECT COUNT(*) FROM left_sample AS l WHERE NOT EXISTS (SELECT 1 FROM right_sample AS r WHERE r.join_key = l.join_key)) AS unmatched_left_sample_rows,
   (SELECT COUNT(*) FROM right_sample AS r WHERE NOT EXISTS (SELECT 1 FROM left_sample AS l WHERE l.join_key = r.join_key)) AS unmatched_right_sample_rows,
   (SELECT COALESCE(MAX(match_count), 0) FROM left_counts) AS max_matches_per_left_key,
-  (SELECT COALESCE(MAX(match_count), 0) FROM right_counts) AS max_matches_per_right_key`;
+  (SELECT COALESCE(MAX(match_count), 0) FROM right_counts) AS max_matches_per_right_key,
+  (SELECT COALESCE(MAX(key_count), 0) FROM left_key_counts) AS max_left_rows_per_key,
+  (SELECT COALESCE(MAX(key_count), 0) FROM right_key_counts) AS max_right_rows_per_key`;
+}
+/**
+ * CTE names are query-internal derived relations, not warehouse tables. A join
+ * whose endpoint is a CTE (e.g. `WITH joy_items AS (…) … JOIN joy_items`) must
+ * be excluded from declared-path enforcement and from join probes — probing
+ * `FROM "joy_items"` throws a DuckDB catalog error for a table that was never
+ * supposed to exist. The physical joins INSIDE the CTE are still present in
+ * the parsed join list and get validated/probed on their own.
+ */
+export function probeableExploratoryJoins(joins, ctes) {
+    const cteNames = new Set(ctes.map((name) => name.split('.').at(-1)?.toLowerCase() ?? name.toLowerCase()));
+    if (cteNames.size === 0)
+        return joins;
+    return joins.filter((join) => ![join.leftRelation, join.rightRelation].some((relation) => {
+        const bare = relation?.replace(/["`\[\]]/g, '').split('.').at(-1)?.toLowerCase();
+        return Boolean(bare && cteNames.has(bare));
+    }));
+}
+function declaredExploratoryRelationMatches(sqlRelation, declaredRelation) {
+    if (!declaredRelation)
+        return false;
+    const normalize = (value) => value.replace(/["`\[\]]/g, '').trim();
+    return exploratoryRelationsMatch(normalize(sqlRelation), normalize(declaredRelation));
+}
+function exploratoryColumnsMatch(sqlColumn, declaredColumn) {
+    const normalize = (value) => value.replace(/["`\[\]]/g, '').split('.').at(-1)?.trim().toLowerCase() ?? value.toLowerCase();
+    return normalize(sqlColumn) === normalize(declaredColumn);
+}
+/**
+ * Gate a join probe against the declared relationship. Returns an error string
+ * when the UNFILTERED key samples structurally contradict the declaration:
+ * - zero key overlap while both sides have rows (wrong/mistyped key), or
+ * - duplicate keys on the declared "one" side of a *_to_one / one_to_* edge.
+ * Sampling caveat: gates only fire on definitive contradictions, never on low
+ * match rates, so a sparse but real relationship still executes.
+ */
+export function exploratoryProbeContradiction(rows, join, edge) {
+    const row = Array.isArray(rows) && rows[0] && typeof rows[0] === 'object'
+        ? rows[0]
+        : {};
+    const number = (key) => {
+        const value = Number(row[key]);
+        return Number.isFinite(value) ? value : 0;
+    };
+    const leftRows = number('left_sample_rows');
+    const rightRows = number('right_sample_rows');
+    const joined = number('joined_rows');
+    if (leftRows > 0 && rightRows > 0 && joined === 0) {
+        return `The join key ${join.leftColumn} = ${join.rightColumn} produced no matching rows between ${join.leftRelation} and ${join.rightRelation} (unfiltered sample). The declared key pair is likely wrong — review the relationship before executing this analysis.`;
+    }
+    if (!edge)
+        return undefined;
+    // Orient the declared cardinality onto the parsed join: which physical side is
+    // the declared "one" side? Duplicated keys there contradict the declaration.
+    const leftIsFrom = Boolean(join.leftRelation && declaredExploratoryRelationMatches(join.leftRelation, edge.fromRelation));
+    const rightIsFrom = Boolean(join.rightRelation && declaredExploratoryRelationMatches(join.rightRelation, edge.fromRelation));
+    if (leftIsFrom === rightIsFrom)
+        return undefined; // orientation unresolved — do not guess
+    const oneSide = edge.cardinality === 'many_to_one' ? 'to' : edge.cardinality === 'one_to_many' ? 'from' : edge.cardinality === 'one_to_one' ? 'both' : undefined;
+    if (!oneSide)
+        return undefined;
+    // Per-side key duplication measured WITHIN each sample (max rows sharing one
+    // key value). Duplicates inside a sample are definitive — a subset of a table
+    // cannot show duplicates the full table does not have. The pairwise
+    // max_matches_* columns are NOT used here: they inflate whenever the
+    // legitimate "many" side repeats a key value.
+    const leftDuplicated = number('max_left_rows_per_key') > 1;
+    const rightDuplicated = number('max_right_rows_per_key') > 1;
+    const fromSideIsLeft = leftIsFrom;
+    const duplicatedSides = [
+        ...(leftDuplicated ? [fromSideIsLeft ? 'from' : 'to'] : []),
+        ...(rightDuplicated ? [fromSideIsLeft ? 'to' : 'from'] : []),
+    ];
+    const violated = oneSide === 'both' ? duplicatedSides.length > 0 : duplicatedSides.includes(oneSide);
+    if (violated) {
+        return `Relationship "${edge.relationshipId}" declares ${edge.cardinality}, but the sampled join keys show duplicates on the declared unique side. Executing would duplicate rows — validate and correct the relationship first.`;
+    }
+    return undefined;
 }
 function summarizeExploratoryJoinProbe(rows, leftRelation, leftColumn, rightRelation, rightColumn) {
     const row = Array.isArray(rows) && rows[0] && typeof rows[0] === 'object'
@@ -13716,28 +14037,6 @@ export function openBlockStudioDocument(projectRoot, relativePath, semanticLayer
         validation: validateBlockStudioSource(source, semanticLayer),
     };
 }
-function semanticMetricExecutionCapability(metricName, semanticLayer, provider, metricFlowReady, driver) {
-    if (provider === 'dbt' && metricFlowReady) {
-        return { status: 'ready', engine: 'metricflow', reason: null };
-    }
-    const native = semanticLayer.composeQuery({ metrics: [metricName], dimensions: [], driver });
-    if (native)
-        return { status: 'ready', engine: 'native', reason: null };
-    const metric = semanticLayer.getMetric(metricName);
-    if (provider === 'dbt') {
-        const kind = metric?.metricType || metric?.aggregation || metric?.type || 'metric';
-        return {
-            status: 'requires_setup',
-            engine: null,
-            reason: `${kind} metric requires MetricFlow execution. Install/configure the MetricFlow CLI, then refresh the semantic layer.`,
-        };
-    }
-    return {
-        status: 'unsupported',
-        engine: null,
-        reason: 'The metric does not have enough composable measure and relation metadata.',
-    };
-}
 function parseBlockStudioArrayField(source, key) {
     const match = source.match(new RegExp(`\\b${key}\\s*=\\s*\\[([\\s\\S]*?)\\]`, 'i'));
     if (!match)
@@ -13790,8 +14089,7 @@ export async function resolveSemanticTableMapping(executor, connection, semantic
         const tablesResult = await executor.executeQuery(`SELECT table_schema, table_name
        FROM information_schema.tables
        WHERE UPPER(table_schema) NOT IN ('INFORMATION_SCHEMA', 'PG_CATALOG')
-       ORDER BY table_schema, table_name
-       LIMIT 2000`, [], {}, connection);
+       ORDER BY table_schema, table_name`, [], {}, connection);
         return buildSemanticTableMapping(semanticLayer, tablesResult.rows);
     }
     catch {
@@ -13833,41 +14131,17 @@ function isDbtSemanticRuntime(projectConfig, detectedProvider, semanticLayer) {
         return true;
     return Boolean(semanticLayer?.listMetrics().some((metric) => metric.source?.provider === 'dbt'));
 }
-function composeRuntimeSemanticQuery(request, semanticLayer, context) {
-    const useMetricFlow = request.engine === 'metricflow' || (request.engine !== 'native' &&
-        isDbtSemanticRuntime(context.projectConfig, context.detectedProvider, semanticLayer));
-    if (useMetricFlow) {
-        const effectiveSemanticConfig = resolveProjectSemanticConfig(context.projectConfig, context.projectRoot);
-        const dbtProjectPath = effectiveSemanticConfig?.provider === 'dbt'
-            ? effectiveSemanticConfig.projectPath
-            : context.projectConfig.dbt?.projectDir;
-        try {
-            const compiled = compileMetricFlowQuery({
-                projectRoot: context.projectRoot,
-                dbtProjectPath,
-                metrics: request.metrics,
-                dimensions: request.dimensions,
-                filters: request.filters,
-                timeDimension: request.timeDimension,
-                orderBy: request.orderBy,
-                limit: request.limit,
-                savedQuery: request.savedQuery,
-            });
-            return {
-                sql: compiled.sql,
-                joins: [],
-                tables: [],
-                engine: 'metricflow',
-            };
-        }
-        catch (error) {
-            // An explicit MetricFlow request must retain its strict engine contract.
-            // For the default dbt path, a missing local CLI may fall back only if the
-            // native composer can safely materialize the requested simple metrics.
-            if (request.engine === 'metricflow' || !(error instanceof MetricFlowUnavailableError))
-                throw error;
-        }
-    }
+async function composeRuntimeSemanticQuery(request, semanticLayer, context) {
+    return compileSemanticRuntimeQuery(request, {
+        projectRoot: context.projectRoot,
+        projectConfig: context.projectConfig,
+        detectedProvider: context.detectedProvider,
+        semanticLayer,
+        driver: context.driver,
+        tableMapping: context.tableMapping,
+    });
+}
+function composeRuntimeSemanticQueryNative(request, semanticLayer, context) {
     const composed = semanticLayer.composeQuery({
         metrics: request.metrics,
         dimensions: request.dimensions,
@@ -13936,7 +14210,7 @@ function composeSemanticBlockSql(source, semanticLayer, options) {
     let composed;
     try {
         composed = options?.projectRoot && options.projectConfig
-            ? composeRuntimeSemanticQuery({
+            ? composeRuntimeSemanticQueryNative({
                 metrics,
                 dimensions: config.dimensions,
                 filters: mergeSemanticRuntimeFilters(config.filters, runtimeBindings.filters),
@@ -13945,9 +14219,6 @@ function composeSemanticBlockSql(source, semanticLayer, options) {
                     : undefined,
                 limit: runtimeBindings.limit ?? config.limit,
             }, semanticLayer, {
-                projectRoot: options.projectRoot,
-                projectConfig: options.projectConfig,
-                detectedProvider: options.detectedProvider ?? null,
                 driver: options.driver,
                 tableMapping: options.tableMapping,
             })
@@ -13973,10 +14244,14 @@ function composeSemanticBlockSql(source, semanticLayer, options) {
     }
     if (!composed) {
         const provider = options?.projectConfig && isDbtSemanticRuntime(options.projectConfig, options.detectedProvider, semanticLayer) ? 'dbt' : (options?.detectedProvider ?? 'dql');
-        const metricFlowReady = provider === 'dbt' && hasMetricFlowCli();
         const reasons = metrics.map((metricName) => {
-            const capability = semanticMetricExecutionCapability(metricName, semanticLayer, provider, metricFlowReady, options?.driver);
-            return capability.status === 'ready' ? null : `${metricName}: ${capability.reason}`;
+            if (semanticLayer.canComposeMetric(metricName))
+                return null;
+            const metric = semanticLayer.getMetric(metricName);
+            const kind = metric?.metricType || metric?.aggregation || metric?.type || 'metric';
+            return provider === 'dbt'
+                ? `${metricName}: ${kind} metric requires a configured dbt Cloud or local MetricFlow runtime.`
+                : `${metricName}: the metric does not have enough composable measure and relation metadata.`;
         }).filter((reason) => Boolean(reason));
         diagnostics.push({
             severity: 'error',
@@ -13993,6 +14268,61 @@ function composeSemanticBlockSql(source, semanticLayer, options) {
         semanticRefs,
     };
 }
+/**
+ * Runtime-aware semantic block compiler. Static validation remains synchronous
+ * and native-only, while execution surfaces can use the bundled dbt Cloud or
+ * local MetricFlow adapters without changing the persisted semantic identities.
+ */
+async function composeSemanticBlockSqlForRuntime(source, semanticLayer, options) {
+    const native = composeSemanticBlockSql(source, semanticLayer, options);
+    if (native.sql)
+        return native;
+    const config = parseSemanticBlockConfig(source);
+    if (config.blockType !== 'semantic')
+        return native;
+    const metrics = config.metrics.length > 0 ? config.metrics : config.metric ? [config.metric] : [];
+    if (metrics.length === 0 || native.diagnostics.some((diagnostic) => diagnostic.code === 'semantic_ref'))
+        return native;
+    const runtimeBindings = semanticRuntimeParameterBindings(source, options.parameters ?? {});
+    try {
+        const compiled = await composeRuntimeSemanticQuery({
+            metrics,
+            dimensions: config.dimensions,
+            filters: mergeSemanticRuntimeFilters(config.filters, runtimeBindings.filters),
+            timeDimension: config.timeDimension && config.granularity
+                ? { name: config.timeDimension, granularity: config.granularity }
+                : undefined,
+            limit: runtimeBindings.limit ?? config.limit,
+        }, semanticLayer, {
+            projectRoot: options.projectRoot,
+            projectConfig: options.projectConfig,
+            detectedProvider: options.detectedProvider ?? null,
+            driver: options.driver,
+            tableMapping: options.tableMapping,
+        });
+        if (!compiled)
+            return native;
+        return {
+            sql: compiled.sql,
+            diagnostics: native.diagnostics.filter((diagnostic) => diagnostic.code !== 'semantic_compose_failed'),
+            semanticRefs: native.semanticRefs,
+        };
+    }
+    catch (error) {
+        return {
+            sql: null,
+            diagnostics: [
+                ...native.diagnostics.filter((diagnostic) => diagnostic.code !== 'semantic_compose_failed'),
+                {
+                    severity: 'error',
+                    code: isSemanticRuntimeError(error) ? 'semantic_runtime_required' : 'semantic_compose_failed',
+                    message: error instanceof Error ? error.message : String(error),
+                },
+            ],
+            semanticRefs: native.semanticRefs,
+        };
+    }
+}
 function semanticRuntimeParameterBindings(source, values) {
     const program = new Parser(source, '<semantic-parameters>').parse();
     const block = program.statements.find((statement) => statement.kind === NodeKind.BlockDecl);