@duckcodeailabs/dql-cli 1.8.3 → 1.8.5

package/dist/local-runtime.js

@@ -31,7 +31,10 @@ 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 { ManagedMetricFlowInstaller, isMetricFlowWarehouseAdapter, metricFlowAdapterForDriver, } from './metricflow-installer.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;
@@ -467,6 +470,7 @@ export async function startLocalServer(opts) {
     const dashboardRunEvidence = new Map();
     const dbtNodeDetailCache = new Map();
     const onboardingJobs = new Map();
+    const metricFlowInstaller = new ManagedMetricFlowInstaller(projectRoot);
     const projectSnapshot = () => {
         const dbtManifestPath = resolveDbtManifestPath(projectRoot, projectConfig) ?? undefined;
         const inputs = collectInputFiles({ projectRoot, dbtManifestPath });
@@ -1087,12 +1091,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');
@@ -1139,6 +1148,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 }
                 : {}),
@@ -2458,13 +2487,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,
@@ -2511,6 +2555,7 @@ export async function startLocalServer(opts) {
         const invocation = prepareBlockInvocation({
             source,
             parameters: invocationInput?.parameters,
+            parameterSources: invocationInput?.parameterSources,
             question: invocationInput?.question,
             surface: 'ask_ai',
         });
@@ -2523,7 +2568,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,
@@ -2607,7 +2652,8 @@ 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]
@@ -2620,7 +2666,7 @@ 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.' };
         }
@@ -2676,7 +2722,6 @@ export async function startLocalServer(opts) {
         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 activeConnection = requireActiveConnection();
         const proofs = [];
         try {
             for (const [index, join] of probeableJoins.entries()) {
@@ -3545,7 +3590,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,
@@ -3599,7 +3644,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,
@@ -6017,7 +6062,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],
@@ -6108,7 +6153,7 @@ export async function startLocalServer(opts) {
                             continue;
                         }
                         const semanticCompose = semanticLayer
-                            ? composeSemanticBlockSql(source, semanticLayer, {
+                            ? await composeSemanticBlockSqlForRuntime(source, semanticLayer, {
                                 driver: targetConnection.driver,
                                 tableMapping,
                                 projectRoot,
@@ -7487,7 +7532,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,
@@ -7993,8 +8038,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;
@@ -8107,10 +8167,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' });
@@ -8254,9 +8327,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,
@@ -8417,8 +8495,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));
             }
@@ -8817,6 +8913,87 @@ 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 === 'GET' && path === '/api/semantic-runtime/metricflow/installer') {
+            try {
+                const profileAdapter = discoverDbtProfileConnections(projectRoot, projectConfig)[0]?.adapter;
+                const recommendedAdapter = metricFlowAdapterForDriver(connection?.driver ?? profileAdapter);
+                const dbtProjectDir = findDbtProjectPath(projectRoot, projectConfig);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    job: metricFlowInstaller.latest(),
+                    recommendedAdapter,
+                    supportedAdapters: ['duckdb', 'snowflake', 'bigquery', 'databricks', 'redshift', 'postgres', 'trino'],
+                    projectConfigured: existsSync(join(dbtProjectDir, 'dbt_project.yml')),
+                    semanticManifestFound: existsSync(join(dbtProjectDir, 'target', 'semantic_manifest.json')),
+                }));
+            }
+            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/metricflow/install') {
+            try {
+                const body = await readJSON(req);
+                const profileAdapter = discoverDbtProfileConnections(projectRoot, projectConfig)[0]?.adapter;
+                const inferred = metricFlowAdapterForDriver(connection?.driver ?? profileAdapter);
+                const adapter = body.adapter === undefined ? inferred : body.adapter;
+                if (!isMetricFlowWarehouseAdapter(adapter)) {
+                    throw new Error('Choose a supported warehouse adapter before installing MetricFlow.');
+                }
+                const { dbtProjectDir, profilesDir } = onboardingDbtPaths({});
+                const job = metricFlowInstaller.start({ adapter, dbtProjectDir, profilesDir });
+                res.writeHead(202, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: true, job }));
+            }
+            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/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);
@@ -8846,8 +9023,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,
@@ -8862,7 +9038,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,
@@ -8960,24 +9136,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,
@@ -9314,7 +9487,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,
@@ -9827,37 +10000,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,
@@ -9875,10 +10019,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({
@@ -9908,13 +10052,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,
                 }));
             }
@@ -9931,31 +10076,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,
@@ -9973,10 +10095,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({
@@ -10000,13 +10122,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,
                 }));
             }
@@ -10031,7 +10154,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,
@@ -10042,6 +10166,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' });
@@ -10072,13 +10197,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,
                 }));
             }
@@ -10400,7 +10526,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' });
@@ -10496,6 +10627,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;
@@ -10514,15 +10646,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
@@ -10536,29 +10684,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: {
@@ -11491,9 +11639,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 {
-        await ensureMetadataCatalogFresh(projectRoot, { force: true });
+        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,
+            ...(manifest ? { manifest } : {}),
+            ...(semanticLayer ? { semanticLayer } : {}),
+        });
     }
     catch {
         // The catalog is a rebuildable local cache. Save/certify flows should not
@@ -12946,13 +13119,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,
@@ -13003,8 +13176,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;
@@ -13032,8 +13205,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]) => ({
@@ -13056,10 +13229,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] ?? '';
@@ -13085,8 +13258,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'
@@ -13906,28 +14079,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)
@@ -13980,8 +14131,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 {
@@ -14023,41 +14173,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,
@@ -14126,7 +14252,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),
@@ -14135,9 +14261,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,
             })
@@ -14163,10 +14286,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',
@@ -14183,6 +14310,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);
@@ -18208,6 +18390,7 @@ const LOCAL_RUNTIME_GITIGNORE_RULES = [
     '**/.dql/cache/',
     '**/.dql/imports/',
     '**/.dql/local/',
+    '**/.dql/runtimes/',
     '**/.dql/connectors/',
     '**/.dql/memory/',
     '**/.dql/migration-staging/',