@duckcodeailabs/dql-cli 1.10.2 → 1.10.4

package/dist/local-runtime.js

@@ -33,8 +33,12 @@ import { buildSemanticObjectDetail, buildSemanticTree, computeSyncDiff, loadSema
 import { clearBlockStudioImportSessions, candidateToDqlSource, createBlockStudioImportSession, deleteBlockStudioImportSession, listBlockStudioImportSessions, loadBlockStudioImportSession, readBlockStudioImportCandidate, parameterizeSqlForDqlImport, updateBlockStudioImportCandidate, writeBlockStudioImportSession, writeBlockStudioImportCandidate, } from './block-studio-import.js';
 import { MetricFlowUnavailableError, hasDbtSemanticManifest, } from "./metricflow.js";
 import { ManagedMetricFlowInstaller, isMetricFlowWarehouseAdapter, metricFlowAdapterForDriver, } from './metricflow-installer.js';
-import { compileSemanticRuntimeQuery, describeRuntimeCompatibility, explainMissingSemanticRuntime, getSemanticRuntimeStatus, semanticRuntimeErrorCode, semanticMetricExecutionCapability as runtimeMetricExecutionCapability, SemanticRuntimeRequiredError, testSemanticRuntimeDraft, } from './semantic-runtime.js';
+import { applySemanticPathSelection, compileSemanticRuntimeQuery, decodeSemanticPathEvidenceId, describeRuntimeCompatibility, explainMissingSemanticRuntime, getSemanticRuntimeStatus, semanticRuntimeErrorDetails, semanticRuntimeErrorCode, semanticMetricExecutionCapability as runtimeMetricExecutionCapability, SemanticRuntimeRequiredError, testSemanticRuntimeDraft, parseSemanticDimensionSelection, } from './semantic-runtime.js';
 import { getSemanticRuntimeSettings, saveTestedSemanticRuntimeSettings, saveSemanticRuntimePreference, } from './semantic-runtime-settings.js';
+import { observeWarehouseTargetIdentity } from './semantic-execution/connection-identity.js';
+import { configuredWarehouseTargetIdentity } from './semantic-execution/connection-identity.js';
+import { executeTargetBoundSemanticQuery, semanticExecutionFailureCode, semanticExecutionFailureDetails, } from './semantic-execution/execution-gateway.js';
+import { buildSemanticTargetBinding } from './semantic-execution/target-binding.js';
 import { NotebookDatasetWorkspace, } from "./notebook-datasets.js";
 import { prepareBlockInvocation } from './block-invocation.js';
 const NOTEBOOK_EXECUTE_PREVIEW_ROW_LIMIT = 500;
@@ -585,6 +589,10 @@ export async function startLocalServer(opts) {
             : null;
     let connection = configuredConnection ?? resolveDbtProfileRuntimeConnection(projectRoot, projectConfig);
     const projectSnapshots = new ProjectSnapshotService();
+    // Server-lifetime registry for exact compiler-owned SQL. The downstream DQL
+    // artifact executor uses this to preserve the selected adapter and target
+    // rather than treating compiled semantic SQL as unrelated generic SQL.
+    const compiledSemanticQueries = new Map();
     const dashboardRunEvidence = new Map();
     const dbtNodeDetailCache = new Map();
     const onboardingJobs = new Map();
@@ -1282,30 +1290,42 @@ export async function startLocalServer(opts) {
                     }
                     projectSnapshot();
                     projectSnapshots.assertCurrent(runProjectSnapshot.snapshotId);
-                    const compiled = await compileSemanticRuntimeQuery({
-                        metrics: [binding.metric],
-                        dimensions: [],
-                        timeDimension: {
-                            name: binding.timeDimension,
-                            granularity: binding.granularity,
-                        },
-                        orderBy: [{ name: binding.outputField, direction: 'desc' }],
-                        limit: 1,
-                    }, {
+                    const plannedAdapter = await resolvePlannedSemanticAdapter(projectRoot, undefined);
+                    const execution = await executeTargetBoundSemanticQuery({
+                        executor,
+                        connection: semanticConnection,
                         projectRoot,
-                        projectConfig,
-                        detectedProvider: semanticDetectedProvider,
-                        semanticLayer: semanticLayer,
-                        driver: semanticDriver,
-                        tableMapping: semanticTableMapping,
+                        plannedAdapter,
+                        metricFlow: plannedAdapter === 'metricflow-cli'
+                            ? resolveMetricFlowTargetMetadata(projectRoot, projectConfig)
+                            : undefined,
+                        compile: () => compileSemanticRuntimeQuery({
+                            metrics: [binding.metric],
+                            dimensions: [],
+                            timeDimension: {
+                                name: binding.timeDimension,
+                                granularity: binding.granularity,
+                            },
+                            orderBy: [{ name: binding.outputField, direction: 'desc' }],
+                            limit: 1,
+                            engine: plannedAdapter,
+                        }, {
+                            projectRoot,
+                            projectConfig,
+                            detectedProvider: semanticDetectedProvider,
+                            semanticLayer: semanticLayer,
+                            driver: semanticDriver,
+                            tableMapping: semanticTableMapping,
+                        }),
+                        prepareSql: (sql) => prepareLocalExecution(sql, semanticConnection, projectRoot, projectConfig),
+                        rowBound: 1,
                     });
-                    if (!compiled) {
+                    if (!execution) {
                         throw Object.assign(new Error('The authorized semantic freshness query could not be compiled.'), {
                             code: 'COMPILATION_FAILED',
                         });
                     }
-                    const prepared = prepareLocalExecution(compiled.sql, semanticConnection, projectRoot, projectConfig);
-                    const result = await executor.executeQuery(prepared.sql, [], runtimeVariables({}), prepared.connection);
+                    const result = execution.result;
                     projectSnapshot();
                     projectSnapshots.assertCurrent(runProjectSnapshot.snapshotId);
                     return {
@@ -1320,9 +1340,31 @@ export async function startLocalServer(opts) {
             } : {}),
             ...(semanticLayer ? {
                 semanticQueryCompiler: async (selection) => {
-                    const compiled = await compileSemanticRuntimeQuery({
+                    const requestedPath = decodeSemanticPathEvidenceId(request.selectedEvidenceId);
+                    const semanticRequest = {
                         ...selection,
                         dimensions: selection.dimensions ?? [],
+                    };
+                    const requestedSemanticQuery = requestedPath
+                        ? applySemanticPathSelection(semanticRequest, requestedPath.authoringReference, requestedPath.entityPath)
+                        : semanticRequest;
+                    const plannedAdapter = await resolvePlannedSemanticAdapter(projectRoot, requestedSemanticQuery.engine);
+                    const executionTarget = semanticConnection
+                        ? await observeWarehouseTargetIdentity(executor, semanticConnection)
+                        : undefined;
+                    const targetBinding = executionTarget
+                        ? buildSemanticTargetBinding({
+                            projectRoot,
+                            adapterId: plannedAdapter,
+                            executionTarget,
+                            metricFlow: plannedAdapter === 'metricflow-cli'
+                                ? resolveMetricFlowTargetMetadata(projectRoot, projectConfig)
+                                : undefined,
+                        })
+                        : undefined;
+                    const compiled = await compileSemanticRuntimeQuery({
+                        ...requestedSemanticQuery,
+                        engine: plannedAdapter,
                     }, {
                         projectRoot,
                         projectConfig,
@@ -1337,6 +1379,7 @@ export async function startLocalServer(opts) {
                             : projectConfig.dbt?.projectDir;
                         throw new SemanticRuntimeRequiredError(await explainMissingSemanticRuntime(projectRoot, dbtProjectPath));
                     }
+                    compiledSemanticQueries.set(executionFingerprint(compiled.sql), compiled);
                     return {
                         sql: compiled.sql,
                         engine: compiled.engine,
@@ -1348,6 +1391,10 @@ export async function startLocalServer(opts) {
                                 ? { timeDimension: compiled.effectiveRequest.timeDimension }
                                 : {}),
                         },
+                        trace: {
+                            ...compiled.semanticTrace,
+                            ...(targetBinding ? { targetBinding } : {}),
+                        },
                     };
                 },
             } : {}),
@@ -1844,6 +1891,9 @@ export async function startLocalServer(opts) {
                 ? 'The governed query could not be executed.'
                 : governedAnswer.route?.label ?? (isCertified ? 'Answered from certified DQL context.' : isExploratory ? 'Exploratory DBT-grounded analysis requires review.' : 'Answered with review-required generated analysis.'),
             answer: synthesizedAnswer ?? governedAnswer.answer ?? governedAnswer.text,
+            ...(governedAnswer.clarificationOptions?.length
+                ? { clarificationOptions: governedAnswer.clarificationOptions }
+                : {}),
             status,
             trustState,
             stopReason,
@@ -1853,9 +1903,13 @@ export async function startLocalServer(opts) {
                     // A refusal still keeps the DQL draft the answer loop produced (when any),
                     // so the "Review DQL draft" next-action isn't a dead link and the user can
                     // see the SQL that was about to run. Provider outages carry no draft.
-                    ? (governedAnswer.dqlArtifact && !isProviderError && !isGroundingGap && !isModelDeclined && !isPolicyBlocked
-                        ? [agentRunArtifact('dql_block_draft', 'DQL draft (review required)', governedAnswer.dqlArtifact, undefined, 'review_required')]
-                        : [])
+                    ? (governedAnswer.semanticExecutionTrace
+                        ? [agentRunArtifact('answer', governedAnswer.refusalCode === 'ambiguous'
+                                ? 'Semantic path selection required'
+                                : 'Semantic compilation details', governedAnswer, undefined, needsClarification ? 'not_applicable' : 'review_required')]
+                        : governedAnswer.dqlArtifact && !isProviderError && !isGroundingGap && !isModelDeclined && !isPolicyBlocked
+                            ? [agentRunArtifact('dql_block_draft', 'DQL draft (review required)', governedAnswer.dqlArtifact, undefined, 'review_required')]
+                            : [])
                     : [agentRunArtifact('answer', isCertified ? 'Certified answer' : isSemantic ? 'Governed semantic answer' : isExploratory ? 'Exploratory DBT-grounded answer' : 'Review-required answer', governedAnswer, governedAnswer.sourceCertifiedBlock ?? governedAnswer.block?.name, isCertified ? 'certified' : isSemantic ? 'governed' : 'review_required')],
             evaluations: [
                 agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to governed answer.', {
@@ -2766,7 +2820,10 @@ export async function startLocalServer(opts) {
             throw new Error(`I need values for: ${invocation.unresolvedParameters.join(', ')}.`);
         }
         const activeConnection = requireActiveConnection();
-        const tableMapping = await resolveSemanticTableMapping(executor, activeConnection, semanticLayer);
+        const precompiledSemanticQuery = Boolean(extractBlockStudioSql(source));
+        const tableMapping = !precompiledSemanticQuery
+            ? await resolveSemanticTableMapping(executor, activeConnection, semanticLayer)
+            : undefined;
         const semanticCompose = semanticLayer
             ? await composeSemanticBlockSqlForRuntime(source, semanticLayer, {
                 driver: activeConnection.driver,
@@ -2795,7 +2852,24 @@ export async function startLocalServer(opts) {
         const app = loadRuntimeApp(projectRoot, activePersonaAppId());
         const sourceDomain = metadata.domain ?? source.match(/\bdomain\s*=\s*"([^"]+)"/i)?.[1];
         assertAppAccess({ app, domain: sourceDomain ?? app?.domain, level: 'execute' });
-        const rawResult = await executor.executeQuery(executionSql, plan?.sqlParams ?? [], runtimeVariables({ ...(plan?.variables ?? {}), ...invocation.values }), prepared.connection);
+        const pinnedSemanticCompile = semanticCompose?.sql
+            ? compiledSemanticQueries.get(executionFingerprint(semanticCompose.sql))
+            : undefined;
+        const semanticExecution = pinnedSemanticCompile
+            ? await executeTargetBoundSemanticQuery({
+                executor,
+                connection: activeConnection,
+                projectRoot,
+                plannedAdapter: pinnedSemanticCompile.engine,
+                metricFlow: pinnedSemanticCompile.engine === 'metricflow-cli'
+                    ? resolveMetricFlowTargetMetadata(projectRoot, projectConfig)
+                    : undefined,
+                compile: async () => pinnedSemanticCompile,
+                prepareSql: () => ({ sql: executionSql, connection: prepared.connection }),
+                rowBound: invocationInput?.rowLimit ?? pinnedSemanticCompile.effectiveRequest.limit,
+            })
+            : null;
+        const rawResult = semanticExecution?.result ?? await executor.executeQuery(executionSql, plan?.sqlParams ?? [], runtimeVariables({ ...(plan?.variables ?? {}), ...invocation.values }), prepared.connection);
         const normalized = normalizeQueryResult(rawResult);
         const executionReceipt = createDqlArtifactExecutionReceipt(source, executionSql, invocation.values, normalized);
         return {
@@ -2810,6 +2884,11 @@ export async function startLocalServer(opts) {
             parameters: invocation.resolvedParameters,
             auditId: invocation.auditId,
             executionReceipt,
+            ...(semanticExecution ? {
+                semanticExecutionReceipt: semanticExecution.executionReceipt,
+                semanticTargetBinding: semanticExecution.targetBinding,
+                semanticTrace: semanticExecution.semanticTrace,
+            } : {}),
         };
     };
     const executeCertifiedBlockByNameForAgent = async (blockName, invocationInput, requireCertified = false) => {
@@ -2998,14 +3077,10 @@ export async function startLocalServer(opts) {
         const scanRuntimeSchema = async () => {
             if (!connection)
                 return { ranked: [], snapshot: [] };
-            const result = await executor.executeQuery(`SELECT table_schema, table_name, column_name, data_type
-         FROM information_schema.columns
-         WHERE UPPER(table_schema) NOT IN ('INFORMATION_SCHEMA', 'PG_CATALOG')
-         ORDER BY table_schema, table_name, ordinal_position
-         LIMIT 2000`, [], runtimeVariables({}), connection);
+            const result = await executor.executePositional(buildRuntimeSchemaSearchSql(question), [], connection, { maxRows: 600, maxBytes: 2 * 1024 * 1024, batchSize: 200, deadlineMs: 30_000 });
             return {
                 ranked: buildAgentSchemaContext(question, result.rows),
-                snapshot: buildAgentSchemaContext(question, result.rows, { includeUnscored: true, limit: 500 }),
+                snapshot: buildAgentSchemaContext(question, result.rows, { includeUnscored: true, limit: 100 }),
             };
         };
         const catalogContext = await buildAgentSchemaContextFromCatalog(projectRoot, question, preparedContextPack).catch(() => []);
@@ -3027,7 +3102,7 @@ export async function startLocalServer(opts) {
             const enriched = valueGrounding.mode === 'safe_automatic'
                 ? await enrichAgentSchemaContextWithValueMatches(question, schemaContext.ranked, executor, connection, valueGrounding.searchSafeColumns)
                 : schemaContext.ranked;
-            recordAgentRuntimeSchemaSnapshot(projectRoot, schemaContext.snapshot, 'full information_schema runtime scan');
+            recordAgentRuntimeSchemaSnapshot(projectRoot, schemaContext.snapshot, 'question-scoped information_schema search');
             return enriched;
         }
         catch {
@@ -7431,8 +7506,15 @@ export async function startLocalServer(opts) {
                     refreshedAt: dataset.refreshedAt,
                     trustState: dataset.trustState,
                 }));
+                const schemaLimit = Math.min(500, Math.max(1, Number(url.searchParams.get('limit')) || 200));
+                const schemaOffset = Math.max(0, Number(url.searchParams.get('offset')) || 0);
+                const schemaSearch = (url.searchParams.get('q') ?? '').trim();
                 const { tables, columnsByPath } = connection
-                    ? await introspectSchema(executor, connection)
+                    ? await introspectSchema(executor, connection, {
+                        limit: schemaLimit,
+                        offset: schemaOffset,
+                        search: schemaSearch,
+                    })
                     : { tables: [], columnsByPath: new Map() };
                 const dbTables = tables.map((t) => ({
                     name: t.path,
@@ -9330,7 +9412,9 @@ export async function startLocalServer(opts) {
             try {
                 const body = await readJSON(req);
                 const result = await testSemanticRuntimeDraft(projectRoot, body);
-                const settings = saveTestedSemanticRuntimeSettings(projectRoot, body, result);
+                const targetConnection = requireActiveConnection(connection);
+                const executionTarget = await observeWarehouseTargetIdentity(executor, targetConnection);
+                const settings = saveTestedSemanticRuntimeSettings(projectRoot, body, result, executionTarget);
                 const runtime = await getSemanticRuntimeStatus(projectRoot);
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({ ok: true, ...settings, runtime }));
@@ -10399,25 +10483,41 @@ export async function startLocalServer(opts) {
                 const { metrics = [], dimensions = [], filters = [], limit, timeDimension, orderBy, savedQuery, engine } = body;
                 // Resolve which connection to use — request can override default
                 const targetConnection = requireActiveConnection(isConnectionConfig(body.connection) ? body.connection : connection);
-                const driver = targetConnection.driver;
-                const tableMapping = await resolveSemanticTableMapping(executor, targetConnection, semanticLayer);
-                const composed = await composeRuntimeSemanticQuery({
-                    metrics,
-                    dimensions,
-                    filters,
-                    limit,
-                    timeDimension,
-                    orderBy,
-                    savedQuery,
-                    engine,
-                }, semanticLayer, {
+                const plannedAdapter = await resolvePlannedSemanticAdapter(projectRoot, engine);
+                const metricFlow = plannedAdapter === 'metricflow-cli'
+                    ? resolveMetricFlowTargetMetadata(projectRoot, projectConfig)
+                    : undefined;
+                const execution = await executeTargetBoundSemanticQuery({
+                    executor,
+                    connection: targetConnection,
                     projectRoot,
-                    projectConfig,
-                    detectedProvider: semanticDetectedProvider,
-                    driver,
-                    tableMapping,
+                    plannedAdapter,
+                    metricFlow,
+                    compile: async () => {
+                        const tableMapping = plannedAdapter === 'native'
+                            ? await resolveSemanticTableMapping(executor, targetConnection, semanticLayer)
+                            : undefined;
+                        return composeRuntimeSemanticQuery({
+                            metrics,
+                            dimensions,
+                            filters,
+                            limit,
+                            timeDimension,
+                            orderBy,
+                            savedQuery,
+                            engine: plannedAdapter,
+                        }, semanticLayer, {
+                            projectRoot,
+                            projectConfig,
+                            detectedProvider: semanticDetectedProvider,
+                            driver: targetConnection.driver,
+                            tableMapping,
+                        });
+                    },
+                    prepareSql: (sql) => prepareLocalExecution(sql, targetConnection, projectRoot, projectConfig),
+                    rowBound: limit,
                 });
-                if (!composed) {
+                if (!execution) {
                     const provider = semanticConfig?.provider ?? semanticDetectedProvider ?? 'dql';
                     const semanticRuntime = await getSemanticRuntimeStatus(projectRoot, { probeConfiguredCloud: true });
                     const blocked = metrics.map((metricName) => ({
@@ -10434,17 +10534,20 @@ export async function startLocalServer(opts) {
                     }));
                     return;
                 }
-                // Execute the composed SQL against the resolved connection
-                const prepared = prepareLocalExecution(composed.sql, targetConnection, projectRoot, projectConfig);
-                const result = await executor.executeQuery(prepared.sql, [], {}, prepared.connection);
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
-                    sql: composed.sql,
-                    tables: composed.tables,
-                    joins: composed.joins,
-                    engine: composed.engine,
-                    effectiveRequest: composed.effectiveRequest,
-                    result: normalizeQueryResult(result),
+                    sql: execution.compiled.sql,
+                    executedSql: execution.preparedSql,
+                    tables: execution.compiled.tables,
+                    joins: execution.compiled.joins,
+                    engine: execution.compiled.engine,
+                    effectiveRequest: execution.compiled.effectiveRequest,
+                    runtimeRequest: execution.compiled.runtimeRequest,
+                    semanticTrace: execution.semanticTrace,
+                    warnings: execution.compiled.warnings,
+                    targetBinding: execution.targetBinding,
+                    executionReceipt: execution.executionReceipt,
+                    result: normalizeQueryResult(execution.result),
                 }));
             }
             catch (error) {
@@ -10453,12 +10556,13 @@ export async function startLocalServer(opts) {
                     res.end(serializeJSON({ error: error.message, code: 'unauthorized' }));
                     return;
                 }
-                const runtimeCode = semanticRuntimeErrorCode(error);
-                const status = runtimeCode ? 400 : 500;
+                const runtimeCode = semanticExecutionFailureCode(error) ?? semanticRuntimeErrorCode(error);
+                const status = runtimeCode === 'EXECUTION_TARGET_MISMATCH' ? 409 : runtimeCode ? 400 : 500;
                 res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
                     error: error instanceof Error ? error.message : String(error),
                     code: runtimeCode,
+                    details: semanticExecutionFailureDetails(error) ?? semanticRuntimeErrorDetails(error),
                     hint: runtimeCode === 'SEMANTIC_RUNTIME_REQUIRED'
                         ? 'Configure dbt Cloud Semantic Layer in Project & dbt settings, or install a compatible local MetricFlow runtime.'
                         : undefined,
@@ -10476,25 +10580,41 @@ export async function startLocalServer(opts) {
                 const body = await readJSON(req);
                 const { metrics = [], dimensions = [], filters = [], limit, timeDimension, orderBy, savedQuery, engine } = body;
                 const targetConnection = requireActiveConnection(isConnectionConfig(body.connection) ? body.connection : connection);
-                const driver = targetConnection.driver;
-                const tableMapping = await resolveSemanticTableMapping(executor, targetConnection, semanticLayer);
-                const composed = await composeRuntimeSemanticQuery({
-                    metrics,
-                    dimensions,
-                    filters,
-                    limit,
-                    timeDimension,
-                    orderBy,
-                    savedQuery,
-                    engine,
-                }, semanticLayer, {
+                const plannedAdapter = await resolvePlannedSemanticAdapter(projectRoot, engine);
+                const metricFlow = plannedAdapter === 'metricflow-cli'
+                    ? resolveMetricFlowTargetMetadata(projectRoot, projectConfig)
+                    : undefined;
+                const execution = await executeTargetBoundSemanticQuery({
+                    executor,
+                    connection: targetConnection,
                     projectRoot,
-                    projectConfig,
-                    detectedProvider: semanticDetectedProvider,
-                    driver,
-                    tableMapping,
+                    plannedAdapter,
+                    metricFlow,
+                    compile: async () => {
+                        const tableMapping = plannedAdapter === 'native'
+                            ? await resolveSemanticTableMapping(executor, targetConnection, semanticLayer)
+                            : undefined;
+                        return composeRuntimeSemanticQuery({
+                            metrics,
+                            dimensions,
+                            filters,
+                            limit,
+                            timeDimension,
+                            orderBy,
+                            savedQuery,
+                            engine: plannedAdapter,
+                        }, semanticLayer, {
+                            projectRoot,
+                            projectConfig,
+                            detectedProvider: semanticDetectedProvider,
+                            driver: targetConnection.driver,
+                            tableMapping,
+                        });
+                    },
+                    prepareSql: (sql) => prepareLocalExecution(sql, targetConnection, projectRoot, projectConfig),
+                    rowBound: limit,
                 });
-                if (!composed) {
+                if (!execution) {
                     const provider = semanticConfig?.provider ?? semanticDetectedProvider ?? 'dql';
                     const semanticRuntime = await getSemanticRuntimeStatus(projectRoot, { probeConfiguredCloud: true });
                     const blocked = metrics.map((metricName) => ({
@@ -10511,25 +10631,30 @@ export async function startLocalServer(opts) {
                     }));
                     return;
                 }
-                const prepared = prepareLocalExecution(composed.sql, targetConnection, projectRoot, projectConfig);
-                const result = await executor.executeQuery(prepared.sql, [], {}, prepared.connection);
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
-                    sql: composed.sql,
-                    joins: composed.joins,
-                    tables: composed.tables,
-                    engine: composed.engine,
-                    effectiveRequest: composed.effectiveRequest,
-                    result: normalizeQueryResult(result),
+                    sql: execution.compiled.sql,
+                    executedSql: execution.preparedSql,
+                    joins: execution.compiled.joins,
+                    tables: execution.compiled.tables,
+                    engine: execution.compiled.engine,
+                    effectiveRequest: execution.compiled.effectiveRequest,
+                    runtimeRequest: execution.compiled.runtimeRequest,
+                    semanticTrace: execution.semanticTrace,
+                    warnings: execution.compiled.warnings,
+                    targetBinding: execution.targetBinding,
+                    executionReceipt: execution.executionReceipt,
+                    result: normalizeQueryResult(execution.result),
                 }));
             }
             catch (error) {
-                const runtimeCode = semanticRuntimeErrorCode(error);
-                const status = runtimeCode ? 400 : 500;
+                const runtimeCode = semanticExecutionFailureCode(error) ?? semanticRuntimeErrorCode(error);
+                const status = runtimeCode === 'EXECUTION_TARGET_MISMATCH' ? 409 : runtimeCode ? 400 : 500;
                 res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
                     error: error instanceof Error ? error.message : String(error),
                     code: runtimeCode,
+                    details: semanticExecutionFailureDetails(error) ?? semanticRuntimeErrorDetails(error),
                     hint: runtimeCode === 'SEMANTIC_RUNTIME_REQUIRED'
                         ? 'Configure dbt Cloud Semantic Layer in Project & dbt settings, or install a compatible local MetricFlow runtime.'
                         : undefined,
@@ -10605,6 +10730,7 @@ export async function startLocalServer(opts) {
                 res.end(serializeJSON({
                     error: error instanceof Error ? error.message : String(error),
                     code: runtimeCode,
+                    details: semanticRuntimeErrorDetails(error),
                     hint: runtimeCode === 'SEMANTIC_RUNTIME_REQUIRED'
                         ? 'Configure dbt Cloud Semantic Layer in Project & dbt settings, or install a compatible local MetricFlow runtime.'
                         : undefined,
@@ -11087,7 +11213,24 @@ export async function startLocalServer(opts) {
                 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 semanticExecution = semanticCompose?.compiled
+                    ? await executeTargetBoundSemanticQuery({
+                        executor,
+                        connection: cellConnection,
+                        projectRoot,
+                        plannedAdapter: semanticCompose.compiled.engine,
+                        metricFlow: semanticCompose.compiled.engine === 'metricflow-cli'
+                            ? resolveMetricFlowTargetMetadata(projectRoot, projectConfig)
+                            : undefined,
+                        // Compilation already produced the exact pinned adapter result
+                        // used by the plan. The gateway validates target identity before
+                        // accepting that result for preflight and execution.
+                        compile: async () => semanticCompose.compiled,
+                        prepareSql: () => ({ sql: prepared.sql, connection: prepared.connection }),
+                        rowBound: semanticCompose.compiled.effectiveRequest.limit,
+                    })
+                    : null;
+                const rawResult = semanticExecution?.result ?? 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
@@ -11125,6 +11268,12 @@ export async function startLocalServer(opts) {
                     chartConfig: plan?.chartConfig,
                     tests: plan?.tests,
                     result: normalized,
+                    ...(semanticExecution ? {
+                        semanticTrace: semanticExecution.semanticTrace,
+                        targetBinding: semanticExecution.targetBinding,
+                        executionReceipt: semanticExecution.executionReceipt,
+                        executedSql: semanticExecution.preparedSql,
+                    } : {}),
                     ...(invocation ? {
                         invocation: {
                             resolvedParameters: invocation.resolvedParameters,
@@ -11157,8 +11306,13 @@ export async function startLocalServer(opts) {
                         error: error instanceof Error ? error.message : String(error),
                     });
                 }
-                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
-                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+                const code = semanticExecutionFailureCode(error) ?? semanticRuntimeErrorCode(error);
+                res.writeHead(code === 'EXECUTION_TARGET_MISMATCH' ? 409 : 500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    error: error instanceof Error ? error.message : String(error),
+                    code,
+                    details: semanticExecutionFailureDetails(error) ?? semanticRuntimeErrorDetails(error),
+                }));
             }
             return;
         }
@@ -14410,15 +14564,25 @@ function readUserPrefs(userPrefsPath) {
 function writeUserPrefs(userPrefsPath, prefs) {
     writeFileSync(userPrefsPath, JSON.stringify(prefs, null, 2) + '\n', 'utf-8');
 }
-async function introspectSchema(executor, connection) {
+async function introspectSchema(executor, connection, options = {}) {
     let tables = [];
-    let columnsByPath = new Map();
-    // Tier 1: information_schema (PG, MySQL, Snowflake, MSSQL, DuckDB, Redshift, Fabric, Databricks)
+    const columnsByPath = new Map();
+    const limit = Math.min(1_000, Math.max(1, Math.floor(options.limit ?? 200)));
+    const offset = Math.max(0, Math.floor(options.offset ?? 0));
+    const escapedSearch = options.search?.trim().replace(/'/g, "''");
+    const searchPredicate = escapedSearch
+        ? ` AND (LOWER(table_schema) LIKE LOWER('%${escapedSearch}%') OR LOWER(table_name) LIKE LOWER('%${escapedSearch}%'))`
+        : '';
+    // Runtime inventory is table-first and bounded. Columns are loaded only for
+    // a selected table through /api/describe-table; constructing one account-wide
+    // table+column tree is an enterprise-scale OOM risk (PERF-001 / CTX-005).
     try {
         const catalogRows = await executor.executeQuery(`SELECT table_schema, table_name, table_type
        FROM information_schema.tables
        WHERE UPPER(table_schema) NOT IN ('INFORMATION_SCHEMA', 'PG_CATALOG')
-       ORDER BY table_schema, table_name`, [], {}, connection);
+       ${searchPredicate}
+       ORDER BY table_schema, table_name
+       LIMIT ${limit} OFFSET ${offset}`, [], {}, connection);
         tables = catalogRows.rows.map((row) => {
             const schema = String(row['table_schema'] ?? row['TABLE_SCHEMA'] ?? 'default');
             const name = String(row['table_name'] ?? row['TABLE_NAME'] ?? '');
@@ -14426,22 +14590,6 @@ async function introspectSchema(executor, connection) {
             const path = schema ? `${schema}.${name}` : name;
             return { schema, name, path, type };
         });
-        const columnRows = await executor.executeQuery(`SELECT table_schema, table_name, column_name, data_type
-       FROM information_schema.columns
-       WHERE UPPER(table_schema) NOT IN ('INFORMATION_SCHEMA', 'PG_CATALOG')
-       ORDER BY table_schema, table_name, ordinal_position`, [], {}, connection);
-        columnsByPath = columnRows.rows.reduce((map, row) => {
-            const schema = String(row['table_schema'] ?? row['TABLE_SCHEMA'] ?? 'default');
-            const tableName = String(row['table_name'] ?? row['TABLE_NAME'] ?? '');
-            const path = schema ? `${schema}.${tableName}` : tableName;
-            const next = map.get(path) ?? [];
-            next.push({
-                name: String(row['column_name'] ?? row['COLUMN_NAME'] ?? ''),
-                type: String(row['data_type'] ?? row['DATA_TYPE'] ?? ''),
-            });
-            map.set(path, next);
-            return map;
-        }, new Map());
         return { tables, columnsByPath };
     }
     catch {
@@ -14452,23 +14600,18 @@ async function introspectSchema(executor, connection) {
         const connector = await executor.getConnector(connection);
         if (typeof connector.listTables === 'function') {
             const rawTables = await connector.listTables();
-            tables = rawTables.map((t) => {
+            const normalizedSearch = options.search?.trim().toLowerCase();
+            tables = rawTables
+                .filter((table) => !normalizedSearch
+                || table.schema.toLowerCase().includes(normalizedSearch)
+                || table.name.toLowerCase().includes(normalizedSearch))
+                .slice(offset, offset + limit)
+                .map((t) => {
                 const schema = t.schema || 'default';
                 const path = t.schema ? `${t.schema}.${t.name}` : t.name;
                 return { schema, name: t.name, path, type: t.type };
             });
         }
-        if (typeof connector.listColumns === 'function') {
-            const rawColumns = await connector.listColumns();
-            columnsByPath = rawColumns.reduce((map, col) => {
-                const schema = col.schema || 'default';
-                const path = schema ? `${schema}.${col.table}` : col.table;
-                const next = map.get(path) ?? [];
-                next.push({ name: col.name, type: col.dataType });
-                map.set(path, next);
-                return map;
-            }, new Map());
-        }
     }
     catch {
         // Tier 3: tables only, no columns — already have what we have
@@ -14478,9 +14621,9 @@ async function introspectSchema(executor, connection) {
 function buildDatabaseSchemaTree(projectRoot, executor, connection) {
     return (async () => {
         const dataFiles = scanDataFiles(projectRoot);
-        const { tables: dbTables, columnsByPath: dbColumnsByPath } = connection
-            ? await introspectSchema(executor, connection)
-            : { tables: [], columnsByPath: new Map() };
+        const dbTables = connection
+            ? (await introspectSchema(executor, connection, { limit: 1_000 })).tables
+            : [];
         const schemaMap = new Map();
         for (const table of dbTables) {
             const schemaName = table.schema || 'default';
@@ -14502,13 +14645,8 @@ function buildDatabaseSchemaTree(projectRoot, executor, connection) {
                 kind: 'table',
                 path: table.path,
                 type: table.type,
-                children: (dbColumnsByPath.get(table.path) ?? []).map((column) => ({
-                    id: `db-column:${table.path}:${column.name}`,
-                    label: column.name,
-                    kind: 'column',
-                    path: table.path,
-                    type: column.type,
-                })),
+                // Warehouse columns are loaded lazily for the selected table.
+                children: [],
             })),
         }));
         // Eagerly resolve file columns via DuckDB DESCRIBE
@@ -14677,6 +14815,28 @@ function isDbtSemanticRuntime(projectConfig, detectedProvider, semanticLayer) {
         return true;
     return Boolean(semanticLayer?.listMetrics().some((metric) => metric.source?.provider === 'dbt'));
 }
+async function resolvePlannedSemanticAdapter(projectRoot, requested) {
+    if (requested === 'dbt-cloud')
+        return 'dbt-cloud';
+    if (requested === 'metricflow' || requested === 'metricflow-cli')
+        return 'metricflow-cli';
+    if (requested === 'native')
+        return 'native';
+    return (await getSemanticRuntimeStatus(projectRoot, { probeConfiguredCloud: true })).active;
+}
+function resolveMetricFlowTargetMetadata(projectRoot, projectConfig) {
+    const candidates = discoverDbtProfileConnections(projectRoot, projectConfig)
+        .filter((candidate) => candidate.missingFields.length === 0);
+    const candidate = candidates.find((item) => !item.warnings.some((warning) => warning.startsWith('Not the default dbt target'))) ?? (candidates.length === 1 ? candidates[0] : undefined);
+    if (!candidate)
+        return undefined;
+    return {
+        expectedTarget: configuredWarehouseTargetIdentity(candidate.connection),
+        profileName: candidate.profileName,
+        targetName: candidate.targetName,
+        profilesPath: candidate.path,
+    };
+}
 async function composeRuntimeSemanticQuery(request, semanticLayer, context) {
     return compileSemanticRuntimeQuery(request, {
         projectRoot: context.projectRoot,
@@ -14688,13 +14848,18 @@ async function composeRuntimeSemanticQuery(request, semanticLayer, context) {
     });
 }
 function composeRuntimeSemanticQueryNative(request, semanticLayer, context) {
+    const stripPath = (value) => parseSemanticDimensionSelection(value).reference;
     const composed = semanticLayer.composeQuery({
         metrics: request.metrics,
-        dimensions: request.dimensions,
-        filters: request.filters,
+        dimensions: request.dimensions.map(stripPath),
+        filters: request.filters?.map((filter) => filter.dimension
+            ? { ...filter, dimension: stripPath(filter.dimension) }
+            : filter),
         limit: request.limit,
-        timeDimension: request.timeDimension,
-        orderBy: request.orderBy,
+        timeDimension: request.timeDimension
+            ? { ...request.timeDimension, name: stripPath(request.timeDimension.name) }
+            : undefined,
+        orderBy: request.orderBy?.map((order) => ({ ...order, name: stripPath(order.name) })),
         driver: context.driver,
         tableMapping: context.tableMapping,
     });
@@ -14737,8 +14902,8 @@ function composeSemanticBlockSql(source, semanticLayer, options) {
     }
     const refValidation = semanticLayer.validateReferences([
         ...metrics,
-        ...config.dimensions,
-        ...(config.timeDimension ? [config.timeDimension] : []),
+        ...config.dimensions.map((dimension) => parseSemanticDimensionSelection(dimension).reference),
+        ...(config.timeDimension ? [parseSemanticDimensionSelection(config.timeDimension).reference] : []),
     ]);
     for (const unknown of refValidation.unknown) {
         diagnostics.push({
@@ -14872,6 +15037,7 @@ async function composeSemanticBlockSqlForRuntime(source, semanticLayer, options)
             // no longer true for this run.
             diagnostics: native.diagnostics.filter((diagnostic) => diagnostic.code !== 'semantic_compose_failed'),
             semanticRefs: native.semanticRefs,
+            compiled,
         };
     }
     catch (error) {
@@ -20547,6 +20713,33 @@ export function buildAgentSchemaContext(question, rows, options = {}) {
         .slice(0, limit)
         .map((entry) => entry.table);
 }
+const RUNTIME_SCHEMA_SEARCH_STOPWORDS = new Set([
+    'what', 'which', 'where', 'when', 'who', 'why', 'how', 'show', 'give', 'find',
+    'from', 'with', 'without', 'this', 'that', 'these', 'those', 'current', 'today',
+    'yesterday', 'last', 'year', 'month', 'week', 'day', 'top', 'bottom', 'their',
+    'have', 'does', 'into', 'than', 'then', 'also', 'all', 'the', 'and', 'for',
+]);
+/**
+ * Physical catalog evidence fallback. This is deliberately question-scoped and
+ * result-bounded: dbt/DQL metadata remains the planning authority, while
+ * information_schema confirms discoverable relations/columns in the selected
+ * execution target. Tokens are reduced to safe identifier characters before
+ * interpolation, so user text cannot become SQL syntax.
+ */
+export function buildRuntimeSchemaSearchSql(question) {
+    const terms = Array.from(agentSchemaTokens(question))
+        .map((term) => term.toLowerCase().replace(/[^a-z0-9_]/g, ''))
+        .filter((term) => term.length >= 3 && !RUNTIME_SCHEMA_SEARCH_STOPWORDS.has(term))
+        .slice(0, 8);
+    const predicate = terms.length > 0
+        ? `\n  AND (\n${terms.map((term) => `    LOWER(table_name) LIKE '%${term}%' OR LOWER(column_name) LIKE '%${term}%'`).join(' OR\n')}\n  )`
+        : '';
+    return `SELECT table_schema, table_name, column_name, data_type
+FROM information_schema.columns
+WHERE UPPER(table_schema) NOT IN ('INFORMATION_SCHEMA', 'PG_CATALOG')${predicate}
+ORDER BY table_schema, table_name, ordinal_position
+LIMIT 600`;
+}
 function mergeAgentSchemaContexts(...contexts) {
     const byRelation = new Map();
     for (const table of contexts.flat()) {