@duckcodeailabs/dql-cli 1.6.3 → 1.6.5

package/dist/local-runtime.js

@@ -4,7 +4,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, wat
 import { homedir } from 'node:os';
 import { dirname, extname, join, normalize, relative, resolve } from 'node:path';
 import { buildExecutionPlan, createWelcomeNotebook, deserializeNotebook, getConnectorFormSchemas, hasSemanticRefs, resolveSemanticRefs, } from '@duckcodeailabs/dql-notebook';
-import { loadSemanticLayerFromDir, resolveSemanticLayerAsync, Parser, buildLineageGraph, buildManifest, findAppDocuments, findDashboardsForApp, isBlockIdRef, loadAppDocument, loadDashboardDocument, analyzeImpact, buildTrustChain, detectDomainFlows, getDomainTrustOverview, queryLineage, queryCompleteLineagePaths, LineageGraph, canonicalize, canonicalizeNotebook, diffDQL, diffNotebook, } from '@duckcodeailabs/dql-core';
+import { loadSemanticLayerFromDir, resolveSemanticLayerAsync, getDialect, Parser, buildLineageGraph, buildManifest, findAppDocuments, findDashboardsForApp, isBlockIdRef, loadAppDocument, loadDashboardDocument, analyzeImpact, buildTrustChain, detectDomainFlows, getDomainTrustOverview, queryLineage, queryCompleteLineagePaths, LineageGraph, canonicalize, canonicalizeNotebook, diffDQL, diffNotebook, } from '@duckcodeailabs/dql-core';
 import { load as loadYaml } from 'js-yaml';
 import { listBlockTemplates } from './block-templates.js';
 import { getRunner as getLLMRunner } from './llm/index.js';
@@ -239,12 +239,67 @@ export async function startLocalServer(opts) {
          FROM information_schema.columns
          WHERE table_schema NOT IN ('information_schema', 'pg_catalog')
          ORDER BY table_schema, table_name, ordinal_position`, [], runtimeVariables({}), connection);
-            return buildAgentSchemaContext(question, result.rows);
+            const schemaContext = buildAgentSchemaContext(question, result.rows);
+            return enrichAgentSchemaContextWithValueMatches(question, schemaContext, executor, connection);
         }
         catch {
             return [];
         }
     };
+    const generateInvestigationSqlForApp = async (input) => {
+        const resolvedProvider = resolveDefaultLLMProvider(projectRoot);
+        const runner = resolvedProvider ? getLLMRunner(resolvedProvider) : null;
+        if (!resolvedProvider || !runner) {
+            throw new Error('No AI provider is configured. Configure OpenAI, Gemini, Ollama, or a custom OpenAI-compatible endpoint in Settings.');
+        }
+        let governedAnswer;
+        let providerError;
+        const contextEnvelope = {
+            mode: 'app_research',
+            intent: input.intent,
+            appId: input.appId,
+            dashboardId: input.dashboardId,
+            sourceTileId: input.sourceTileId,
+            sourceBlockId: input.sourceBlockId,
+            title: input.title,
+            instruction: 'Generate review-required read-only SQL when certified blocks do not exactly answer the requested research grain. Execute only through the bounded generated SQL preview path.',
+            context: input.context,
+        };
+        const controller = new AbortController();
+        await runner.run({
+            provider: resolvedProvider,
+            messages: [{ role: 'user', content: input.question }],
+            upstream: {
+                cellId: `app-research:${input.appId}:${input.dashboardId ?? 'app'}`,
+                sql: JSON.stringify(contextEnvelope, null, 2),
+            },
+            projectRoot,
+            executeCertifiedBlock: executeCertifiedBlockForAgent,
+            executeGeneratedSql: executeGeneratedSqlForAgent,
+            getSchemaContext: getSchemaContextForAgent,
+        }, (turn) => {
+            if (turn.kind === 'tool_result' && turn.id === 'governed_answer') {
+                governedAnswer = turn.output;
+            }
+            if (turn.kind === 'error') {
+                providerError = turn.message;
+            }
+        }, controller.signal);
+        if (!governedAnswer) {
+            throw new Error(providerError ?? 'The AI provider did not return a governed answer.');
+        }
+        return {
+            sql: governedAnswer.proposedSql ?? governedAnswer.sql,
+            answer: governedAnswer.answer ?? governedAnswer.text,
+            result: governedAnswer.result,
+            analysisPlan: governedAnswer.analysisPlan,
+            evidence: governedAnswer.evidence,
+            citations: governedAnswer.citations,
+            suggestedViz: governedAnswer.suggestedViz,
+            executionError: governedAnswer.executionError,
+            providerUsed: governedAnswer.providerUsed,
+        };
+    };
     // SSE clients for /api/watch hot-reload
     const sseClients = new Set();
     // Watch notebooks/, workbooks/, semantic-layer/, and data/ dirs for changes
@@ -303,6 +358,17 @@ export async function startLocalServer(opts) {
         ...candidate,
         validation: validateBlockStudioSource(candidate.dqlSource, semanticLayer),
     });
+    const validateImportCandidateForSave = (candidate) => {
+        const validated = validateImportCandidate(candidate);
+        const diagnostics = (validated.validation?.diagnostics ?? []);
+        const errors = diagnostics
+            .filter((diagnostic) => diagnostic.severity === 'error')
+            .map((diagnostic) => diagnostic.message || 'Candidate validation failed.');
+        if (validated.reviewStatus === 'rejected') {
+            errors.unshift('Candidate was rejected.');
+        }
+        return { candidate: validated, errors };
+    };
     const runBlockStudioPreviewSource = async (source, targetConnection = connection) => {
         let tableMapping;
         if (semanticLayer) {
@@ -334,10 +400,10 @@ export async function startLocalServer(opts) {
             throw new Error(message);
         }
         const plan = buildExecutionPlan({ id: 'block-studio', type: 'dql', source, title: 'Block Studio' }, { semanticLayer, driver: targetConnection.driver, tableMapping });
-        const sql = resolveProjectRelativeSqlPaths(semanticCompose?.sql ?? plan?.sql ?? executableSql, projectRoot, projectConfig.dataDir);
-        const result = await executor.executeQuery(sql, plan?.sqlParams ?? [], runtimeVariables(plan?.variables ?? {}), targetConnection);
+        const prepared = prepareLocalExecution(semanticCompose?.sql ?? plan?.sql ?? executableSql, targetConnection, projectRoot, projectConfig);
+        const result = await executor.executeQuery(prepared.sql, plan?.sqlParams ?? [], runtimeVariables(plan?.variables ?? {}), prepared.connection);
         return {
-            sql: plan?.sql ?? executableSql,
+            sql: prepared.sql,
             result: normalizeQueryResult(result),
             chartConfig: plan?.chartConfig ?? validation.chartConfig ?? null,
         };
@@ -777,6 +843,7 @@ export async function startLocalServer(opts) {
                     path,
                     projectRoot,
                     executeSql: executeLocalSqlForStoredResult,
+                    generateInvestigationSql: generateInvestigationSqlForApp,
                     runNotebook: (appId, notebookPath) => runNotebookForApp(appId, notebookPath),
                 });
                 if (handled)
@@ -1435,10 +1502,7 @@ export async function startLocalServer(opts) {
                     return;
                 }
                 const result = await certifyBlockStudioSource(source, blockPath);
-                const blockers = [
-                    ...result.checklist.blockers,
-                    ...result.certification.errors.map((error) => `${error.rule}: ${error.message}`),
-                ];
+                const blockers = Array.from(new Set(result.checklist.blockers));
                 if (!result.certification.certified || blockers.length > 0) {
                     res.writeHead(422, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ ok: false, ...result, blockers }));
@@ -1514,25 +1578,32 @@ export async function startLocalServer(opts) {
                 const nextCandidates = [...session.candidates];
                 for (let i = 0; i < nextCandidates.length; i += 1) {
                     const candidate = nextCandidates[i];
-                    if (candidate.reviewStatus === 'saved' || candidate.reviewStatus === 'rejected' || candidate.validation?.valid === false)
+                    if (candidate.reviewStatus === 'saved' || candidate.reviewStatus === 'rejected')
+                        continue;
+                    const readiness = validateImportCandidateForSave(candidate);
+                    nextCandidates[i] = readiness.candidate;
+                    writeBlockStudioImportCandidate(projectRoot, importId, readiness.candidate);
+                    if (readiness.errors.length > 0) {
+                        errors.push({ candidateId: candidate.id, error: readiness.errors.join(' ') });
                         continue;
+                    }
                     try {
                         const savedPath = saveBlockStudioArtifacts(projectRoot, {
-                            source: candidate.dqlSource,
-                            name: candidate.name,
-                            domain: candidate.domain,
-                            description: candidate.description,
-                            owner: candidate.owner,
-                            tags: candidate.tags,
-                            lineage: candidate.lineage.sourceTables,
+                            source: readiness.candidate.dqlSource,
+                            name: readiness.candidate.name,
+                            domain: readiness.candidate.domain,
+                            description: readiness.candidate.description,
+                            owner: readiness.candidate.owner,
+                            tags: readiness.candidate.tags,
+                            lineage: readiness.candidate.lineage.sourceTables,
                             importMeta: {
                                 importId,
-                                candidateId: candidate.id,
-                                sourceKind: candidate.sourceKind,
-                                sourcePath: candidate.sourcePath,
+                                candidateId: readiness.candidate.id,
+                                sourceKind: readiness.candidate.sourceKind,
+                                sourcePath: readiness.candidate.sourcePath,
                             },
                         });
-                        nextCandidates[i] = { ...candidate, reviewStatus: 'saved', savedPath };
+                        nextCandidates[i] = { ...readiness.candidate, reviewStatus: 'saved', savedPath };
                         writeBlockStudioImportCandidate(projectRoot, importId, nextCandidates[i]);
                         saved.push({ candidateId: candidate.id, path: savedPath });
                     }
@@ -1625,22 +1696,39 @@ export async function startLocalServer(opts) {
                 }
                 if (req.method === 'POST' && candidateId && action === 'save') {
                     const candidate = readBlockStudioImportCandidate(projectRoot, importId, candidateId);
+                    if (candidate.reviewStatus === 'saved' && candidate.savedPath) {
+                        const payload = openBlockStudioDocument(projectRoot, candidate.savedPath, semanticLayer);
+                        res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ candidate, block: payload }));
+                        return;
+                    }
+                    const readiness = validateImportCandidateForSave(candidate);
+                    if (readiness.errors.length > 0) {
+                        writeBlockStudioImportCandidate(projectRoot, importId, readiness.candidate);
+                        res.writeHead(422, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({
+                            error: readiness.errors.join(' '),
+                            candidate: readiness.candidate,
+                            diagnostics: readiness.candidate.validation?.diagnostics ?? [],
+                        }));
+                        return;
+                    }
                     const savedPath = saveBlockStudioArtifacts(projectRoot, {
-                        source: candidate.dqlSource,
-                        name: candidate.name,
-                        domain: candidate.domain,
-                        description: candidate.description,
-                        owner: candidate.owner,
-                        tags: candidate.tags,
-                        lineage: candidate.lineage.sourceTables,
+                        source: readiness.candidate.dqlSource,
+                        name: readiness.candidate.name,
+                        domain: readiness.candidate.domain,
+                        description: readiness.candidate.description,
+                        owner: readiness.candidate.owner,
+                        tags: readiness.candidate.tags,
+                        lineage: readiness.candidate.lineage.sourceTables,
                         importMeta: {
                             importId,
                             candidateId,
-                            sourceKind: candidate.sourceKind,
-                            sourcePath: candidate.sourcePath,
+                            sourceKind: readiness.candidate.sourceKind,
+                            sourcePath: readiness.candidate.sourcePath,
                         },
                     });
-                    const next = { ...candidate, reviewStatus: 'saved', savedPath };
+                    const next = { ...readiness.candidate, reviewStatus: 'saved', savedPath };
                     writeBlockStudioImportCandidate(projectRoot, importId, next);
                     const payload = openBlockStudioDocument(projectRoot, savedPath, semanticLayer);
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -1664,11 +1752,8 @@ export async function startLocalServer(opts) {
         if (req.method === 'GET' && path === '/api/block-studio/catalog') {
             try {
                 const cfg = loadProjectConfig(projectRoot);
-                const connections = cfg.connections ?? {};
-                if (Object.keys(connections).length === 0 && cfg.defaultConnection) {
-                    connections.default = cfg.defaultConnection;
-                }
-                const defaultKey = cfg.defaultConnection ? 'default' : Object.keys(connections)[0] ?? 'default';
+                const connections = getProjectConnectionsForApi(cfg);
+                const defaultKey = resolveDefaultConnectionKey(cfg, connections) ?? Object.keys(connections)[0] ?? 'default';
                 const userPrefs = readUserPrefs(userPrefsPath);
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
@@ -1800,15 +1885,10 @@ export async function startLocalServer(opts) {
         }
         if (req.method === 'GET' && path === '/api/connections') {
             const cfg = loadProjectConfig(projectRoot);
-            const raw = cfg;
-            const connections = raw.connections ?? {};
-            // If no explicit connections map, surface the defaultConnection as "default"
-            if (Object.keys(connections).length === 0 && cfg.defaultConnection) {
-                connections['default'] = cfg.defaultConnection;
-            }
-            const defaultKey = raw.defaultConnection
-                ? 'default'
-                : Object.keys(connections)[0] ?? 'default';
+            const connections = getProjectConnectionsForApi(cfg);
+            const defaultKey = resolveDefaultConnectionKey(cfg, connections)
+                ?? Object.keys(connections)[0]
+                ?? 'default';
             const dbtProfiles = discoverDbtProfileConnections(projectRoot, cfg);
             res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
             res.end(serializeJSON({ default: defaultKey, connections, dbtProfiles }));
@@ -1826,6 +1906,22 @@ export async function startLocalServer(opts) {
                 if (body.connections && typeof body.connections === 'object') {
                     raw.connections = body.connections;
                 }
+                const connections = getStoredConnections(raw);
+                if (body.connections && typeof body.connections === 'object') {
+                    const requestedDefault = typeof body.defaultConnectionName === 'string'
+                        ? body.defaultConnectionName
+                        : typeof body.default === 'string'
+                            ? body.default
+                            : undefined;
+                    const defaultConnectionName = resolveDefaultConnectionKey(requestedDefault ? { ...raw, defaultConnectionName: requestedDefault } : raw, connections);
+                    delete raw.defaultConnection;
+                    if (defaultConnectionName) {
+                        raw.defaultConnectionName = defaultConnectionName;
+                    }
+                    else {
+                        delete raw.defaultConnectionName;
+                    }
+                }
                 writeFileSync(configPath, JSON.stringify(raw, null, 2) + '\n', 'utf-8');
                 // Hot-swap: re-read the config and re-initialize the active connection
                 projectConfig = loadProjectConfig(projectRoot);
@@ -2840,23 +2936,20 @@ export async function startLocalServer(opts) {
             return;
         }
         if (req.method === 'POST' && path === '/api/test-connection') {
+            let target = connection;
             try {
                 const body = await readJSON(req);
-                const target = normalizeProjectConnection(isConnectionConfig(body.connection) ? body.connection : connection, projectRoot);
+                target = normalizeProjectConnection(isConnectionConfig(body.connection) ? body.connection : connection, projectRoot);
                 const connector = await executor.getConnector(target);
-                const ok = await connector.ping();
-                const driver = target.driver ?? 'unknown';
-                res.writeHead(ok ? 200 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
-                res.end(serializeJSON({
-                    ok,
-                    message: ok ? `Connected to ${driver} successfully` : `Connection to ${driver} failed`,
-                }));
+                const result = await validateConnectionForTest(connector, target);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(result));
             }
             catch (error) {
-                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
                     ok: false,
-                    message: error instanceof Error ? error.message : String(error),
+                    message: formatConnectionTestError(target, error),
                 }));
             }
             return;
@@ -3229,6 +3322,102 @@ export function formatLocalQueryRuntimeError(connection, error) {
     }
     return `Local query runtime is unavailable for driver "${driver}": ${detail}`;
 }
+export async function validateConnectionForTest(connector, connection) {
+    if (connection.driver === 'snowflake') {
+        return validateSnowflakeConnectionForTest(connector, connection);
+    }
+    const ok = await connector.ping();
+    const label = connectionDriverLabel(connection);
+    return {
+        ok,
+        message: ok
+            ? `Connected to ${label} successfully.`
+            : `Connection to ${label} failed. Check credentials, network access, and database availability.`,
+    };
+}
+function formatConnectionTestError(connection, error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    const label = connectionDriverLabel(connection);
+    if (connection.driver === 'snowflake') {
+        const cleaned = detail.replace(/^Snowflake (?:connection|query) failed:\s*/i, '').trim();
+        return `Snowflake connection failed: ${cleaned || 'Check account, user, password/auth method, role, and network access.'}`;
+    }
+    return `Connection to ${label} failed: ${detail}`;
+}
+async function validateSnowflakeConnectionForTest(connector, connection) {
+    const warehouse = connection.warehouse?.trim();
+    if (!warehouse) {
+        return {
+            ok: false,
+            message: 'Snowflake connection requires a warehouse before it can be tested.',
+        };
+    }
+    const warehouseRow = await findSnowflakeWarehouse(connector, warehouse);
+    if (!warehouseRow) {
+        return {
+            ok: false,
+            message: `Snowflake warehouse "${warehouse}" was not found or is not visible to this role.`,
+        };
+    }
+    const state = String(readRowField(warehouseRow, 'state') ?? '').trim();
+    const normalizedState = state.toUpperCase();
+    if (normalizedState && normalizedState !== 'STARTED') {
+        return {
+            ok: false,
+            message: `Snowflake warehouse "${warehouse}" is ${state}. Start or resume it, then test again.`,
+            details: {
+                warehouse,
+                state,
+            },
+        };
+    }
+    const context = await connector.execute(`SELECT
+       CURRENT_ACCOUNT() AS account_name,
+       CURRENT_USER() AS user_name,
+       CURRENT_ROLE() AS role_name,
+       CURRENT_DATABASE() AS database_name,
+       CURRENT_SCHEMA() AS schema_name,
+       CURRENT_WAREHOUSE() AS warehouse_name`);
+    const row = context.rows[0] ?? {};
+    const user = String(readRowField(row, 'user_name') ?? connection.username ?? '').trim();
+    const role = String(readRowField(row, 'role_name') ?? connection.role ?? '').trim();
+    const activeWarehouse = String(readRowField(row, 'warehouse_name') ?? warehouse).trim();
+    return {
+        ok: true,
+        message: `Connected to Snowflake${user ? ` as ${user}` : ''} using warehouse ${activeWarehouse || warehouse}.`,
+        details: {
+            warehouse: activeWarehouse || warehouse,
+            warehouseState: state || 'STARTED',
+            role: role || undefined,
+            database: readRowField(row, 'database_name') ?? connection.database,
+            schema: readRowField(row, 'schema_name') ?? connection.schema,
+        },
+    };
+}
+async function findSnowflakeWarehouse(connector, warehouse) {
+    const candidates = Array.from(new Set([warehouse, warehouse.toUpperCase()]));
+    for (const candidate of candidates) {
+        const result = await connector.execute(`SHOW WAREHOUSES LIKE '${escapeSqlString(candidate)}'`);
+        const row = result.rows.find((item) => {
+            const name = String(readRowField(item, 'name') ?? '').trim();
+            return name.localeCompare(warehouse, undefined, { sensitivity: 'accent' }) === 0;
+        });
+        if (row)
+            return row;
+    }
+    return null;
+}
+function readRowField(row, field) {
+    const expected = field.toLowerCase();
+    const entry = Object.entries(row).find(([key]) => key.toLowerCase() === expected);
+    return entry?.[1];
+}
+function escapeSqlString(value) {
+    return value.replace(/'/g, "''");
+}
+function connectionDriverLabel(connection) {
+    return connection.driver === 'snowflake' ? 'Snowflake' : connection.driver ?? 'database';
+}
 /**
  * Normalize connector QueryResult → SPA-friendly shape.
  * Connector returns columns as ColumnMeta[] ({name,type,driverType}).
@@ -3361,31 +3550,203 @@ export function loadProjectConfig(projectRoot) {
     }
     const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
     const config = raw;
-    // Normalize modern `connections.default` format to `defaultConnection`
-    if (!config.defaultConnection && raw.connections) {
-        const connections = raw.connections;
-        const defaultConn = connections.default;
-        if (defaultConn?.driver) {
-            // Support both `filepath` (correct) and `path` (legacy/init compat)
-            const filepath = (defaultConn.filepath ?? defaultConn.path);
-            config.defaultConnection = {
-                ...defaultConn,
-                driver: defaultConn.driver,
-                ...(filepath ? { filepath } : {}),
-            };
+    const connections = getStoredConnections(raw);
+    const defaultConnectionName = resolveDefaultConnectionKey(raw, connections);
+    if (defaultConnectionName) {
+        const selected = normalizeStoredConnection(connections[defaultConnectionName]);
+        if (selected) {
+            config.defaultConnection = selected;
+            config.defaultConnectionName = defaultConnectionName;
+        }
+    }
+    else if (config.defaultConnection) {
+        const normalized = normalizeStoredConnection(config.defaultConnection);
+        if (normalized) {
+            config.defaultConnection = normalized;
         }
     }
     return config;
 }
+function getProjectConnectionsForApi(config) {
+    const connections = getStoredConnections(config);
+    if (Object.keys(connections).length === 0 && isConnectionLike(config.defaultConnection)) {
+        return { default: config.defaultConnection };
+    }
+    return connections;
+}
+function getStoredConnections(raw) {
+    const value = raw.connections;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return {};
+    }
+    return { ...value };
+}
+function resolveDefaultConnectionKey(raw, connections) {
+    const keys = Object.keys(connections).filter((key) => isConnectionLike(connections[key]));
+    if (keys.length === 0)
+        return undefined;
+    const configured = readConfiguredDefaultConnectionName(raw);
+    if (configured && keys.includes(configured)) {
+        return configured;
+    }
+    if (keys.includes('default') && !isPlaceholderLocalConnection(connections.default)) {
+        return 'default';
+    }
+    const realConnections = keys.filter((key) => !isPlaceholderLocalConnection(connections[key]));
+    if (keys.includes('default') && isPlaceholderLocalConnection(connections.default) && realConnections.length === 1) {
+        return realConnections[0];
+    }
+    if (keys.length === 1) {
+        return keys[0];
+    }
+    return keys.includes('default') ? 'default' : keys[0];
+}
+function readConfiguredDefaultConnectionName(raw) {
+    for (const key of ['defaultConnectionName', 'defaultConnectionKey', 'currentConnection']) {
+        const value = raw[key];
+        if (typeof value === 'string' && value.trim())
+            return value.trim();
+    }
+    return typeof raw.default === 'string' && raw.default.trim() ? raw.default.trim() : undefined;
+}
+function normalizeStoredConnection(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const raw = value;
+    const driver = raw.driver ?? raw.type;
+    if (typeof driver !== 'string' || !driver.trim())
+        return null;
+    const { path: legacyPath, type: _type, ...rest } = raw;
+    const filepath = typeof raw.filepath === 'string'
+        ? raw.filepath
+        : typeof legacyPath === 'string'
+            ? legacyPath
+            : undefined;
+    return {
+        ...rest,
+        driver: driver.trim(),
+        ...(filepath ? { filepath } : {}),
+    };
+}
+function isConnectionLike(value) {
+    return normalizeStoredConnection(value) !== null;
+}
+function isPlaceholderLocalConnection(value) {
+    const connection = normalizeStoredConnection(value);
+    if (!connection)
+        return false;
+    if (connection.driver !== 'duckdb' && connection.driver !== 'file')
+        return false;
+    return !connection.filepath || connection.filepath === ':memory:';
+}
 export function prepareLocalExecution(sql, connection, projectRoot, projectConfig) {
     const normalizedConnection = normalizeProjectConnection(connection, projectRoot);
+    const dbtResolvedSql = resolveDbtMacrosForExecution(sql, projectRoot, projectConfig);
     return {
         sql: shouldResolveProjectPaths(normalizedConnection)
-            ? resolveProjectRelativeSqlPaths(sql, projectRoot, projectConfig.dataDir)
-            : sql,
+            ? resolveProjectRelativeSqlPaths(dbtResolvedSql, projectRoot, projectConfig.dataDir)
+            : dbtResolvedSql,
         connection: normalizedConnection,
     };
 }
+export function resolveDbtMacrosForExecution(sql, projectRoot, projectConfig = {}) {
+    if (!/\{\{\s*(?:ref|source)\s*\(/i.test(sql))
+        return sql;
+    const manifestPath = resolveDbtManifestPath(projectRoot, projectConfig);
+    if (!manifestPath) {
+        throw new Error('dbt ref/source macros were found, but target/manifest.json was not available. Run dbt parse or dbt compile, then retry.');
+    }
+    const manifest = readJsonFile(manifestPath);
+    const refs = buildDbtRelationLookup(manifest);
+    const unresolved = new Set();
+    let rendered = sql.replace(/\{\{\s*ref\(\s*(?:(['"])([^'"]+)\1\s*,\s*)?(['"])([^'"]+)\3(?:\s*,[^)]*)?\)\s*\}\}/gi, (match, _pkgQuote, packageName, _modelQuote, modelName) => {
+        const key = normalizeDbtLookupKey(modelName);
+        const scopedKey = packageName ? normalizeDbtLookupKey(`${packageName}.${modelName}`) : key;
+        const relation = refs.models.get(scopedKey) ?? refs.models.get(key);
+        if (!relation) {
+            unresolved.add(packageName ? `ref('${packageName}', '${modelName}')` : `ref('${modelName}')`);
+            return match;
+        }
+        return relation;
+    });
+    rendered = rendered.replace(/\{\{\s*source\(\s*(['"])([^'"]+)\1\s*,\s*(['"])([^'"]+)\3\s*\)\s*\}\}/gi, (match, _sourceQuote, sourceName, _tableQuote, tableName) => {
+        const key = normalizeDbtLookupKey(`${sourceName}.${tableName}`);
+        const relation = refs.sources.get(key) ?? refs.sources.get(normalizeDbtLookupKey(tableName));
+        if (!relation) {
+            unresolved.add(`source('${sourceName}', '${tableName}')`);
+            return match;
+        }
+        return relation;
+    });
+    if (unresolved.size > 0) {
+        throw new Error(`Could not resolve dbt macro${unresolved.size === 1 ? '' : 's'} from manifest.json: ${Array.from(unresolved).join(', ')}.`);
+    }
+    return rendered;
+}
+function buildDbtRelationLookup(manifest) {
+    const models = new Map();
+    const sources = new Map();
+    const root = manifest && typeof manifest === 'object' ? manifest : {};
+    const nodes = root.nodes && typeof root.nodes === 'object' ? root.nodes : {};
+    const manifestSources = root.sources && typeof root.sources === 'object' ? root.sources : {};
+    for (const [uniqueId, rawNode] of Object.entries(nodes)) {
+        const node = rawNode && typeof rawNode === 'object' ? rawNode : null;
+        if (!node || node.resource_type !== 'model')
+            continue;
+        const relation = dbtRelationName(node);
+        if (!relation)
+            continue;
+        const name = stringField(node, 'name');
+        const alias = stringField(node, 'alias');
+        const packageName = uniqueId.split('.')[1];
+        for (const key of [name, alias, packageName && name ? `${packageName}.${name}` : null, uniqueId]) {
+            if (key)
+                models.set(normalizeDbtLookupKey(key), relation);
+        }
+    }
+    for (const [uniqueId, rawSource] of Object.entries(manifestSources)) {
+        const source = rawSource && typeof rawSource === 'object' ? rawSource : null;
+        if (!source)
+            continue;
+        const relation = dbtRelationName(source);
+        if (!relation)
+            continue;
+        const sourceName = stringField(source, 'source_name');
+        const name = stringField(source, 'name');
+        const identifier = stringField(source, 'identifier');
+        for (const key of [
+            sourceName && name ? `${sourceName}.${name}` : null,
+            sourceName && identifier ? `${sourceName}.${identifier}` : null,
+            name,
+            identifier,
+            uniqueId,
+        ]) {
+            if (key)
+                sources.set(normalizeDbtLookupKey(key), relation);
+        }
+    }
+    return { models, sources };
+}
+function dbtRelationName(node) {
+    const relationName = stringField(node, 'relation_name');
+    if (relationName)
+        return relationName;
+    const database = stringField(node, 'database');
+    const schema = stringField(node, 'schema');
+    const alias = stringField(node, 'alias') ?? stringField(node, 'identifier') ?? stringField(node, 'name');
+    if (database && schema && alias)
+        return `${database}.${schema}.${alias}`;
+    if (schema && alias)
+        return `${schema}.${alias}`;
+    return alias ?? null;
+}
+function stringField(source, key) {
+    const value = source[key];
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function normalizeDbtLookupKey(value) {
+    return value.trim().replace(/^['"]|['"]$/g, '').toLowerCase();
+}
 const AGENT_PREVIEW_FORBIDDEN_SQL = [
     'alter',
     'analyze',
@@ -3416,19 +3777,25 @@ export function buildAgentPreviewSql(sql) {
     if (!trimmed)
         throw new Error('Generated SQL preview is empty.');
     const withoutTrailingSemicolon = trimmed.replace(/;\s*$/, '').trim();
-    const scanSql = stripSqlStringsAndComments(withoutTrailingSemicolon).trim();
+    const readOnlyError = readOnlySqlValidationError(withoutTrailingSemicolon, 'Generated SQL preview');
+    if (readOnlyError)
+        throw new Error(readOnlyError);
+    return `SELECT * FROM (\n${withoutTrailingSemicolon}\n) AS dql_agent_preview LIMIT 200`;
+}
+function readOnlySqlValidationError(sql, subject) {
+    const scanSql = stripSqlStringsAndComments(sql).trim();
     if (!/^(select|with)\b/i.test(scanSql)) {
-        throw new Error('Generated SQL preview only supports read-only SELECT or WITH queries.');
+        return `${subject} only supports read-only SELECT or WITH queries.`;
     }
     if (scanSql.includes(';')) {
-        throw new Error('Generated SQL preview only supports one statement.');
+        return `${subject} only supports one statement.`;
     }
     const forbiddenPattern = new RegExp(`\\b(${AGENT_PREVIEW_FORBIDDEN_SQL.join('|')})\\b`, 'i');
     const forbidden = scanSql.match(forbiddenPattern)?.[1];
     if (forbidden) {
-        throw new Error(`Generated SQL preview rejected unsupported statement keyword: ${forbidden.toUpperCase()}.`);
+        return `${subject} rejected unsupported statement keyword: ${forbidden.toUpperCase()}.`;
     }
-    return `SELECT * FROM (\n${withoutTrailingSemicolon}\n) AS dql_agent_preview LIMIT 200`;
+    return null;
 }
 function stripSqlStringsAndComments(sql) {
     let output = '';
@@ -4211,6 +4578,16 @@ export function validateBlockStudioSource(source, semanticLayer) {
         diagnostics.push(...resolvedCustomSql.diagnostics);
         executableSql = resolvedCustomSql.sql;
     }
+    if (executableSql && semanticConfig.blockType !== 'semantic') {
+        const readOnlyError = readOnlySqlValidationError(executableSql.trim().replace(/;\s*$/, '').trim(), 'Block SQL');
+        if (readOnlyError) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'sql_read_only',
+                message: readOnlyError,
+            });
+        }
+    }
     const chartConfig = extractBlockStudioChartConfig(source);
     if (!chartConfig) {
         diagnostics.push({
@@ -4240,7 +4617,7 @@ export function validateBlockStudioSource(source, semanticLayer) {
         executableSql,
     };
 }
-function saveBlockStudioArtifacts(projectRoot, options) {
+export function saveBlockStudioArtifacts(projectRoot, options) {
     const slug = options.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'block';
     const safeDomain = (options.domain ?? '')
         .trim()
@@ -4392,12 +4769,6 @@ function buildBlockStudioCertificationChecklist(input) {
         blockers.add(`${error.rule}: ${error.message}`);
     for (const blocker of input.extraBlockers ?? [])
         blockers.add(blocker);
-    if (!parsed.domain.trim())
-        blockers.add('Missing domain');
-    if (!parsed.owner.trim())
-        blockers.add('Missing owner');
-    if (!parsed.description.trim())
-        blockers.add('Missing description');
     if (!input.previewSucceeded)
         blockers.add('Block has not run successfully');
     if (!input.testResults || input.testResults.failed > 0)
@@ -5092,7 +5463,7 @@ function buildProjectLineageGraphUncached(projectRoot, semanticLayer) {
             // Fall back to a live build.
         }
     }
-    const dbtManifestPath = resolveDbtManifestPath(projectRoot);
+    const dbtManifestPath = resolveDbtManifestPath(projectRoot, {});
     try {
         const manifest = buildManifest({
             projectRoot,
@@ -5149,9 +5520,14 @@ function buildProjectLineageGraphUncached(projectRoot, semanticLayer) {
         return buildLineageGraph(blocks, metrics, dimensions);
     }
 }
-function resolveDbtManifestPath(projectRoot) {
-    const candidate = join(projectRoot, 'target', 'manifest.json');
-    return existsSync(candidate) ? candidate : undefined;
+function resolveDbtManifestPath(projectRoot, projectConfig = {}) {
+    const candidates = [];
+    if (projectConfig.dbt?.projectDir || projectConfig.semanticLayer?.provider === 'dbt') {
+        const dbtProjectPath = findDbtProjectPath(projectRoot, projectConfig);
+        candidates.push(resolve(dbtProjectPath, projectConfig.dbt?.manifestPath ?? 'target/manifest.json'));
+    }
+    candidates.push(join(projectRoot, 'target', 'manifest.json'), join(resolve(projectRoot, '..'), 'target', 'manifest.json'), join(resolve(projectRoot, '../dbt'), 'target', 'manifest.json'), join(resolve(projectRoot, '../../dbt'), 'target', 'manifest.json'));
+    return candidates.find((candidate, index, list) => list.indexOf(candidate) === index && existsSync(candidate));
 }
 export function discoverDbtProfileConnections(projectRoot, projectConfig) {
     const dbtProjectPath = findDbtProjectPath(projectRoot, projectConfig);
@@ -6113,7 +6489,7 @@ function isAiPinRefreshDue(lastRefreshedAt) {
         return true;
     return Date.now() - last >= 24 * 60 * 60 * 1000;
 }
-function buildAgentSchemaContext(question, rows) {
+export function buildAgentSchemaContext(question, rows) {
     const byRelation = new Map();
     for (const row of rows) {
         if (!row || typeof row !== 'object')
@@ -6141,13 +6517,54 @@ function buildAgentSchemaContext(question, rows) {
         byRelation.set(relation, current);
     }
     const tokens = agentSchemaTokens(question);
+    const shouldProbeValues = extractAgentValueSearchTerms(question).length > 0;
     return Array.from(byRelation.values())
-        .map((table) => ({ table, score: scoreAgentSchemaTable(table, tokens) }))
+        .map((table) => ({
+        table,
+        score: scoreAgentSchemaTable(table, tokens) + (shouldProbeValues ? scoreAgentValueProbeTable(table) : 0),
+    }))
         .filter((entry) => entry.score > 0)
         .sort((a, b) => b.score - a.score || a.table.relation.localeCompare(b.table.relation))
         .slice(0, 12)
         .map((entry) => entry.table);
 }
+async function enrichAgentSchemaContextWithValueMatches(question, schemaContext, executor, connection) {
+    const searchTerms = extractAgentValueSearchTerms(question);
+    if (schemaContext.length === 0 || searchTerms.length === 0)
+        return schemaContext;
+    const matches = new Map();
+    for (const candidate of rankAgentValueProbeColumns(schemaContext).slice(0, 12)) {
+        try {
+            const result = await executor.executeQuery(buildAgentValueProbeSql(candidate.table, candidate.column.name, searchTerms, connection), [], runtimeVariables({}), connection);
+            const values = uniqueStrings(result.rows.flatMap(valueProbeRowValues)).slice(0, 5);
+            if (values.length === 0)
+                continue;
+            const tableMatches = matches.get(candidate.table.relation) ?? new Map();
+            tableMatches.set(candidate.column.name, values);
+            matches.set(candidate.table.relation, tableMatches);
+        }
+        catch {
+            // Value probes are advisory. Unsupported casts, privileges, and large-table
+            // failures should not block the metadata-backed answer path.
+        }
+    }
+    if (matches.size === 0)
+        return schemaContext;
+    return schemaContext.map((table) => {
+        const tableMatches = matches.get(table.relation);
+        if (!tableMatches)
+            return table;
+        return {
+            ...table,
+            columns: table.columns.map((column) => {
+                const sampleValues = tableMatches.get(column.name);
+                return sampleValues?.length
+                    ? { ...column, sampleValues: uniqueStrings([...(column.sampleValues ?? []), ...sampleValues]).slice(0, 5) }
+                    : column;
+            }),
+        };
+    });
+}
 function scoreAgentSchemaTable(table, tokens) {
     let score = 0;
     const relationTokens = agentSchemaTokens(`${table.schema ?? ''} ${table.name} ${table.relation}`);
@@ -6166,6 +6583,146 @@ function scoreAgentSchemaTable(table, tokens) {
         score += 1;
     return score;
 }
+function scoreAgentValueProbeTable(table) {
+    let score = 0;
+    if (hasAgentSchemaToken(table.name, ['account', 'customer', 'member', 'order', 'product', 'sku', 'subscriber', 'user']))
+        score += 5;
+    for (const column of table.columns) {
+        if (!isAgentValueProbeColumn(column))
+            continue;
+        score += 2;
+        if (hasAgentSchemaToken(column.name, ['account', 'customer', 'email', 'full', 'member', 'name', 'product', 'sku', 'user']))
+            score += 2;
+    }
+    return Math.min(score, 18);
+}
+function rankAgentValueProbeColumns(schemaContext) {
+    const ranked = [];
+    for (const table of schemaContext) {
+        for (const column of table.columns) {
+            if (!isAgentValueProbeColumn(column))
+                continue;
+            ranked.push({
+                table,
+                column,
+                score: scoreAgentValueProbeColumn(table, column),
+            });
+        }
+    }
+    return ranked.sort((a, b) => b.score - a.score || a.table.relation.localeCompare(b.table.relation) || a.column.name.localeCompare(b.column.name));
+}
+function scoreAgentValueProbeColumn(table, column) {
+    let score = 0;
+    if (hasAgentSchemaToken(table.name, ['account', 'customer', 'member', 'product', 'sku', 'subscriber', 'user']))
+        score += 4;
+    if (hasAgentSchemaToken(column.name, ['full', 'name', 'email', 'account', 'customer', 'member', 'product', 'sku', 'subscriber', 'user']))
+        score += 8;
+    if (hasAgentSchemaToken(column.name, ['id', 'key', 'code', 'number', 'status', 'segment', 'region', 'category', 'type']))
+        score += 3;
+    return score;
+}
+function isAgentValueProbeColumn(column) {
+    const name = column.name.toLowerCase();
+    if (/\b(password|secret|token|credential|hash|salt)\b/.test(name))
+        return false;
+    if (!hasAgentSchemaToken(name, [
+        'account',
+        'category',
+        'channel',
+        'city',
+        'code',
+        'country',
+        'customer',
+        'email',
+        'full',
+        'id',
+        'key',
+        'member',
+        'name',
+        'number',
+        'product',
+        'region',
+        'segment',
+        'sku',
+        'state',
+        'status',
+        'subscriber',
+        'type',
+        'user',
+    ])) {
+        return false;
+    }
+    const type = column.type?.toLowerCase() ?? '';
+    if (!type)
+        return true;
+    return /\b(char|character|clob|email|string|text|uuid|varchar)\b/.test(type);
+}
+function buildAgentValueProbeSql(table, column, searchTerms, connection) {
+    const relation = quoteAgentRelation(table.relation, connection);
+    const identifier = quoteAgentIdentifier(column, connection);
+    const castValue = `LOWER(CAST(${identifier} AS ${agentTextCastType(connection.driver)}))`;
+    const predicates = searchTerms
+        .slice(0, 5)
+        .map((term) => `${castValue} LIKE ${sqlStringLiteral(`%${escapeSqlLike(term.toLowerCase())}%`)} ESCAPE '\\\\'`)
+        .join(' OR ');
+    return [
+        `SELECT DISTINCT CAST(${identifier} AS ${agentTextCastType(connection.driver)}) AS value`,
+        `FROM ${relation}`,
+        `WHERE ${identifier} IS NOT NULL AND (${predicates})`,
+        'LIMIT 5',
+    ].join('\n');
+}
+function agentTextCastType(driver) {
+    switch (driver) {
+        case 'bigquery':
+            return 'STRING';
+        case 'clickhouse':
+            return 'String';
+        case 'fabric':
+        case 'mssql':
+            return 'NVARCHAR(MAX)';
+        case 'mysql':
+            return 'CHAR';
+        case 'sqlite':
+            return 'TEXT';
+        default:
+            return 'VARCHAR';
+    }
+}
+function quoteAgentRelation(relation, connection) {
+    return relation.split('.').map((part) => quoteAgentIdentifier(part, connection)).join('.');
+}
+function quoteAgentIdentifier(identifier, connection) {
+    return getDialect(connection.driver).quoteIdentifier(identifier);
+}
+function sqlStringLiteral(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+function escapeSqlLike(value) {
+    return value.replace(/[\\%_]/g, (match) => `\\${match}`);
+}
+function valueProbeRowValues(row) {
+    if (!row || typeof row !== 'object')
+        return [];
+    const record = row;
+    return Object.values(record)
+        .filter((value) => (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'))
+        .map(String)
+        .map((value) => value.trim())
+        .filter(Boolean);
+}
+function uniqueStrings(values) {
+    const seen = new Set();
+    const output = [];
+    for (const value of values) {
+        const normalized = value.toLowerCase();
+        if (seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        output.push(value);
+    }
+    return output;
+}
 function agentSchemaTokens(value) {
     const tokens = new Set();
     for (const raw of value.toLowerCase().match(/[a-z0-9_]+/g) ?? []) {
@@ -6178,10 +6735,60 @@ function agentSchemaTokens(value) {
     }
     return tokens;
 }
+function hasAgentSchemaToken(value, expected) {
+    const tokens = agentSchemaTokens(value);
+    return expected.some((token) => tokens.has(token));
+}
+export function extractAgentValueSearchTerms(question) {
+    const terms = [];
+    for (const match of question.matchAll(/["']([^"']{3,120})["']/g)) {
+        terms.push(match[1]);
+    }
+    for (const match of question.matchAll(/\b[\w.%+-]+@[\w.-]+\.[A-Za-z]{2,}\b/g)) {
+        terms.push(match[0]);
+    }
+    for (const match of question.matchAll(/\b[A-Z][a-z0-9]+(?:\s+[A-Z][a-z0-9]+){1,3}\b/g)) {
+        terms.push(match[0]);
+    }
+    for (const match of question.matchAll(/\b(?:for|named|called|only|where|customer|user|account|product)\s+([A-Za-z0-9@._-]+(?:\s+[A-Za-z0-9@._-]+){0,3})/gi)) {
+        terms.push(match[1]);
+    }
+    return uniqueStrings(terms
+        .map(cleanAgentValueSearchTerm)
+        .filter((term) => term.length >= 3 && !AGENT_VALUE_SEARCH_STOP_PHRASES.has(term.toLowerCase()))).slice(0, 6);
+}
+function cleanAgentValueSearchTerm(term) {
+    return term
+        .replace(/[?.,;:]+$/g, '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .replace(/^(?:account|customer|member|named|called|product|sku|subscriber|user)\s+/i, '')
+        .replace(/\s+\b(?:last|next|this)\b.*$/i, '')
+        .replace(/\s+\b(?:last|this)\s+(?:day|week|month|quarter|year)\b.*$/i, '')
+        .replace(/\s+\b(?:daily|weekly|monthly|quarterly|yearly)\b.*$/i, '')
+        .trim();
+}
 const AGENT_SCHEMA_STOPWORDS = new Set([
     'all', 'and', 'are', 'can', 'data', 'for', 'from', 'have', 'how', 'many', 'me',
     'show', 'the', 'this', 'who', 'with', 'value',
 ]);
+const AGENT_VALUE_SEARCH_STOP_PHRASES = new Set([
+    'account',
+    'customer',
+    'last week',
+    'this week',
+    'last month',
+    'this month',
+    'last quarter',
+    'this quarter',
+    'last year',
+    'this year',
+    'member',
+    'product',
+    'sku',
+    'subscriber',
+    'user',
+]);
 function normalizeAgentSchemaToken(token) {
     if (token === 'orders')
         return 'order';