@duckcodeailabs/dql-cli 1.6.17 → 1.6.19

package/dist/local-runtime.js

@@ -7,21 +7,50 @@ import { dirname, extname, join, normalize, relative, resolve } from 'node:path'
 import Anthropic from '@anthropic-ai/sdk';
 import OpenAI from 'openai';
 import { buildExecutionPlan, createWelcomeNotebook, deserializeNotebook, getConnectorFormSchemas, hasSemanticRefs, resolveSemanticRefs, } from '@duckcodeailabs/dql-notebook';
-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 { loadSemanticLayerFromDir, resolveSemanticLayerAsync, getDialect, Parser, buildLineageGraph, buildManifest, findAppDocuments, findDashboardsForApp, isBlockIdRef, loadAppDocument, loadDashboardDocument, analyzeImpact, buildTrustChain, detectDomainFlows, getDomainTrustOverview, queryLineage, queryBusiness360, 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';
 import { listRemoteMcpSettings, saveRemoteMcpSettings } from './llm/mcp-config.js';
-import { ClaudeProvider, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildLocalContextPack, defaultMemoryPath, ensureDefaultMemoryFiles, ensureMetadataCatalogFresh, recordRuntimeSchemaSnapshot, } from '@duckcodeailabs/dql-agent';
-import { handleAppsApi } from './apps-api.js';
+import { ClaudeProvider, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildLocalContextPack, defaultMemoryPath, ensureDefaultMemoryFiles, ensureMetadataCatalogFresh, recordQueryRun, recordRuntimeSchemaSnapshot, } from '@duckcodeailabs/dql-agent';
+import { handleAppsApi, recommendVisualization } from './apps-api.js';
 import { getActiveProvider, getEffectiveProviderConfig, listProviderSettings, saveProviderSettings, } from './settings/provider-settings.js';
 import { DQLAccessDeniedError, activePersonaAppId, assertAppAccess, loadRuntimeApp, runtimeVariables, } from './governance-runtime.js';
-import { LocalAppStorage, defaultLocalAppsDbPath } from '@duckcodeailabs/dql-project';
-import { Certifier } from '@duckcodeailabs/dql-governance';
+import { LocalAppStorage, LocalNotebookResearchStorage, defaultLocalAppsDbPath, defaultNotebookResearchDbPath } from '@duckcodeailabs/dql-project';
+import { Certifier, ENTERPRISE_RULES } from '@duckcodeailabs/dql-governance';
 import { buildSemanticObjectDetail, buildSemanticTree, computeSyncDiff, loadSemanticImportManifest, performSemanticImport, previewSemanticImport, syncSemanticImport, } from './semantic-import.js';
-import { clearBlockStudioImportSessions, createBlockStudioImportSession, deleteBlockStudioImportSession, listBlockStudioImportSessions, loadBlockStudioImportSession, readBlockStudioImportCandidate, updateBlockStudioImportCandidate, writeBlockStudioImportSession, writeBlockStudioImportCandidate, } from './block-studio-import.js';
+import { clearBlockStudioImportSessions, createBlockStudioImportSession, deleteBlockStudioImportSession, listBlockStudioImportSessions, loadBlockStudioImportSession, readBlockStudioImportCandidate, parameterizeSqlForDqlImport, updateBlockStudioImportCandidate, writeBlockStudioImportSession, writeBlockStudioImportCandidate, } from './block-studio-import.js';
 import { MetricFlowUnavailableError, compileMetricFlowQuery, hasDbtSemanticManifest, } from './metricflow.js';
 const NOTEBOOK_EXECUTE_PREVIEW_ROW_LIMIT = 500;
+export function resolveProjectSemanticConfig(projectConfig, projectRoot) {
+    const configured = projectConfig.semanticLayer;
+    const dbtProjectDir = projectConfig.dbt?.projectDir;
+    if (dbtProjectDir
+        && (!configured || configured.provider === 'dql')
+        && hasDbtSemanticArtifacts(projectRoot, dbtProjectDir)) {
+        return { provider: 'dbt', projectPath: dbtProjectDir };
+    }
+    return configured;
+}
+function hasDbtSemanticArtifacts(projectRoot, dbtProjectDir) {
+    const dbtRoot = resolve(projectRoot, dbtProjectDir);
+    if (existsSync(join(dbtRoot, 'target', 'semantic_manifest.json')))
+        return true;
+    const manifestPath = join(dbtRoot, 'target', 'manifest.json');
+    if (!existsSync(manifestPath))
+        return false;
+    try {
+        const parsed = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+        if (parsed.semantic_models && typeof parsed.semantic_models === 'object')
+            return true;
+        if (parsed.metrics && typeof parsed.metrics === 'object')
+            return true;
+    }
+    catch {
+        return false;
+    }
+    return false;
+}
 export async function startLocalServer(opts) {
     const { rootDir, executor, connection: rawConnection, preferredPort, projectRoot = process.cwd() } = opts;
     const bindHost = opts.host ?? process.env.DQL_HOST ?? '127.0.0.1';
@@ -40,7 +69,7 @@ export async function startLocalServer(opts) {
     const semanticLayerDir = join(projectRoot, 'semantic-layer');
     let semanticImportManifest = loadSemanticImportManifest(projectRoot);
     const userPrefsPath = join(projectRoot, '.dql-user-prefs.json');
-    const semanticConfig = projectConfig.semanticLayer;
+    const semanticConfig = resolveProjectSemanticConfig(projectConfig, projectRoot);
     let semanticLastSyncTime = null;
     {
         const semanticConnection = connection;
@@ -330,6 +359,430 @@ export async function startLocalServer(opts) {
             providerUsed: governedAnswer.providerUsed,
         };
     };
+    const openNotebookResearchStorage = () => new LocalNotebookResearchStorage(defaultNotebookResearchDbPath(projectRoot));
+    const runNotebookResearch = async (storage, run, input = {}) => {
+        const question = notebookResearchString(input.question) || run.question;
+        const domain = notebookResearchString(input.domain) ?? run.domain;
+        const owner = notebookResearchString(input.owner) ?? run.owner;
+        const sourceCellFingerprint = notebookResearchString(input.sourceCellFingerprint) ?? run.sourceCellFingerprint;
+        const intent = input.intent ?? run.intent;
+        const context = input.context === undefined ? run.context : input.context;
+        let generatedSql = notebookResearchString(input.generatedSql) ?? run.generatedSql;
+        let reviewedSql = notebookResearchString(input.reviewedSql) ?? run.reviewedSql;
+        const startedAt = new Date().toISOString();
+        storage.updateRun(run.id, {
+            domain,
+            owner,
+            sourceCellFingerprint,
+            question,
+            intent,
+            context,
+            generatedSql,
+            reviewedSql,
+            status: 'running',
+            reviewStatus: 'needs_review',
+            error: '',
+        });
+        try {
+            const contextPack = await buildLocalContextPack(projectRoot, {
+                question,
+                mode: 'question',
+                surface: 'notebook',
+                selectedContext: {
+                    ...notebookResearchSelectedContext(run, context),
+                    domain,
+                    owner,
+                    intent,
+                    researchPattern: notebookResearchIntentPattern(intent),
+                },
+                strictness: 'balanced',
+                limit: 100,
+            }).catch((error) => {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    id: '',
+                    routeDecision: undefined,
+                    evidenceRoles: [],
+                    warnings: [`Context pack failed: ${message}`],
+                    retrievalDiagnostics: { selectedEvidence: [] },
+                };
+            });
+            let governedAnswer;
+            let providerError;
+            const generationWarnings = [];
+            if (!generatedSql && !reviewedSql) {
+                const resolvedProvider = resolveDefaultLLMProvider(projectRoot);
+                const runner = resolvedProvider ? getLLMRunner(resolvedProvider) : null;
+                if (!resolvedProvider || !runner) {
+                    generationWarnings.push('No AI provider is configured. Metadata context was saved as a research plan; paste SQL or configure an AI provider to generate candidate SQL.');
+                }
+                else {
+                    const controller = new AbortController();
+                    try {
+                        await runner.run({
+                            provider: resolvedProvider,
+                            messages: [{ role: 'user', content: notebookResearchAgentPrompt(question, intent) }],
+                            upstream: {
+                                cellId: `notebook-research:${run.notebookPath}:${run.id}`,
+                                sql: JSON.stringify({
+                                    mode: 'notebook_research',
+                                    notebookPath: run.notebookPath,
+                                    sourceCellId: run.sourceCellId,
+                                    sourceCellName: run.sourceCellName,
+                                    owner,
+                                    intent,
+                                    researchPattern: notebookResearchIntentPattern(intent),
+                                    instruction: 'Generate review-required read-only SQL from the inspected metadata context. Execute only through bounded preview and keep the result uncertified until promoted to a DQL draft.',
+                                    context,
+                                }, 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);
+                    }
+                    catch (error) {
+                        providerError = error instanceof Error ? error.message : String(error);
+                    }
+                    if (!governedAnswer) {
+                        generationWarnings.push(`AI SQL generation did not return a governed answer. Metadata context was saved for review.${providerError ? ` ${providerError}` : ''}`);
+                    }
+                    else {
+                        generatedSql = notebookResearchString(governedAnswer.proposedSql) ?? notebookResearchString(governedAnswer.sql);
+                        if (!generatedSql) {
+                            generationWarnings.push('AI returned a governed answer without SQL. Metadata context was saved; add reviewed SQL before DQL promotion.');
+                        }
+                    }
+                }
+            }
+            const sqlForPreview = reviewedSql || generatedSql;
+            const warnings = [
+                ...(contextPack.warnings ?? []),
+                ...(governedAnswer?.validationWarnings ?? []),
+                ...generationWarnings,
+            ].filter(Boolean);
+            let resultPreview;
+            let previewError;
+            if (governedAnswer?.result?.rows && !reviewedSql) {
+                resultPreview = normalizeNotebookAgentResult(governedAnswer.result);
+            }
+            else if (sqlForPreview) {
+                try {
+                    const previewSql = buildAgentPreviewSql(sqlForPreview);
+                    const previewStart = Date.now();
+                    resultPreview = await executeLocalSqlForStoredResult(previewSql);
+                    recordNotebookQueryRun(projectRoot, {
+                        notebookPath: run.notebookPath,
+                        cellId: run.sourceCellId,
+                        cellName: run.sourceCellName,
+                        researchRunId: run.id,
+                        source: reviewedSql ? 'notebook_research_reviewed_sql' : 'notebook_research_ai_sql',
+                        status: 'success',
+                        rowCount: resultPreview.rowCount ?? resultPreview.rows.length,
+                        durationMs: Date.now() - previewStart,
+                        sql: sqlForPreview,
+                        contextPackId: contextPack.id,
+                    });
+                }
+                catch (error) {
+                    previewError = error instanceof Error ? error.message : String(error);
+                    recordNotebookQueryRun(projectRoot, {
+                        notebookPath: run.notebookPath,
+                        cellId: run.sourceCellId,
+                        cellName: run.sourceCellName,
+                        researchRunId: run.id,
+                        source: reviewedSql ? 'notebook_research_reviewed_sql' : 'notebook_research_ai_sql',
+                        status: 'error',
+                        errorCode: previewError,
+                        sql: sqlForPreview,
+                        contextPackId: contextPack.id,
+                    });
+                }
+            }
+            const routeDecision = notebookResearchRouteDecisionForRun(run, contextPack.routeDecision, sqlForPreview);
+            const display = resultPreview
+                ? recommendVisualization(projectRoot, {
+                    prompt: question,
+                    resultSchema: resultPreview.columns,
+                    rowSample: resultPreview.rows.slice(0, 25),
+                    defaultVisualization: governedAnswer?.suggestedViz,
+                })
+                : undefined;
+            const evidence = {
+                trustStatus: {
+                    label: governedAnswer?.trustLabel
+                        ?? (reviewedSql ? 'Reviewed notebook SQL' : generatedSql ? 'AI-generated research SQL' : 'Metadata-grounded research plan'),
+                    reviewRequired: true,
+                },
+                contextPackId: contextPack.id,
+                routeDecision,
+                selectedEvidence: contextPack.evidenceRoles?.slice(0, 24) ?? [],
+                evidenceRoles: contextPack.evidenceRoles?.slice(0, 24) ?? [],
+                evidenceSummaries: contextPack.evidenceSummaries?.slice(0, 16) ?? [],
+                allowedSqlContext: {
+                    relations: (contextPack.allowedSqlContext?.relations ?? []).slice(0, 24).map((relation) => ({
+                        relation: relation.relation,
+                        name: relation.name,
+                        source: relation.source,
+                        columns: relation.columns.slice(0, 32).map((column) => {
+                            if (typeof column === 'string')
+                                return column;
+                            if (column && typeof column === 'object' && typeof column.name === 'string') {
+                                return String(column.name);
+                            }
+                            return String(column);
+                        }),
+                    })),
+                    sourceBlockSql: contextPack.allowedSqlContext?.sourceBlockSql?.slice(0, 12) ?? [],
+                },
+                missingContext: contextPack.missingContext?.slice(0, 16) ?? [],
+                warnings: contextPack.warnings?.slice(0, 16) ?? [],
+                retrievalDiagnostics: contextPack.retrievalDiagnostics,
+                agentEvidence: governedAnswer?.evidence,
+                analysisPlan: governedAnswer?.analysisPlan,
+                citations: [
+                    ...(contextPack.citations ?? []),
+                    ...(governedAnswer?.citations ?? []),
+                ].slice(0, 40),
+            };
+            const summary = notebookResearchString(governedAnswer?.answer)
+                ?? notebookResearchString(governedAnswer?.text)
+                ?? notebookResearchSummary(question, resultPreview, previewError);
+            const recommendation = previewError
+                ? 'Review the SQL, selected metadata, and connection context before rerunning.'
+                : sqlForPreview
+                    ? 'Review the SQL, parameter choices, grain, and evidence before promoting this research into a DQL draft block.'
+                    : 'Review the selected metadata context, then paste reviewed SQL or configure an AI provider before DQL draft promotion.';
+            const researchPlan = buildNotebookResearchPlan({
+                run,
+                evidence,
+                resultPreview,
+                previewError,
+                generatedSql,
+                reviewedSql,
+                routeDecision,
+            });
+            return storage.updateRun(run.id, {
+                domain,
+                owner,
+                sourceCellFingerprint,
+                question,
+                intent,
+                context,
+                status: previewError ? 'error' : 'ready',
+                summary,
+                recommendation,
+                resultPreview,
+                evidence,
+                researchPlan,
+                generatedSql,
+                reviewedSql,
+                display: display && display.ok ? display.display : undefined,
+                contextPackId: contextPack.id,
+                routeDecision,
+                warnings: [
+                    ...warnings,
+                    ...(display && !display.ok ? [display.error] : []),
+                    ...(display && display.ok ? display.warnings : []),
+                ],
+                reviewStatus: 'needs_review',
+                error: previewError,
+                lastRunAt: startedAt,
+            }) ?? run;
+        }
+        catch (error) {
+            return storage.updateRun(run.id, {
+                domain,
+                owner,
+                sourceCellFingerprint,
+                status: 'error',
+                error: error instanceof Error ? error.message : String(error),
+                reviewStatus: 'needs_review',
+                lastRunAt: startedAt,
+            }) ?? run;
+        }
+    };
+    const promoteNotebookResearchToDql = async (storage, run, input = {}) => {
+        const sql = notebookResearchString(run.reviewedSql) ?? notebookResearchString(run.generatedSql);
+        if (!sql)
+            throw new Error('Notebook research needs generated or reviewed SQL before DQL draft promotion.');
+        const sourcePath = `${run.notebookPath}${run.sourceCellId ? `#${run.sourceCellId}` : ''}`;
+        const session = await createDqlGenerationSessionForProject(projectRoot, {
+            inputMode: 'upload',
+            sources: [{ path: sourcePath.endsWith('.sql') ? sourcePath : `${sourcePath}.sql`, content: sql }],
+            sourceKind: 'raw-sql-file',
+            domain: notebookResearchString(input.domain) ?? run.domain,
+            owner: notebookResearchString(input.owner),
+            tags: ['notebook-research', 'review-required', ...(Array.isArray(input.tags) ? input.tags : [])],
+            provider: input.provider,
+        }, semanticLayer);
+        const draftPath = session.candidates.find((candidate) => candidate.draftSave?.path)?.draftSave?.path
+            ?? session.candidates.find((candidate) => candidate.savedPath)?.savedPath;
+        const promotion = buildNotebookDqlPromotionSummary(session, draftPath);
+        const updated = storage.markPromoted(run.id, {
+            draftBlockPath: draftPath,
+            dqlImportId: session.id,
+            dqlCandidateIds: session.candidates.map((candidate) => candidate.id),
+            dqlPromotion: promotion,
+        }) ?? run;
+        const planned = storage.updateRun(updated.id, {
+            researchPlan: buildNotebookResearchPlan({
+                run: updated,
+                evidence: updated.evidence,
+                resultPreview: updated.resultPreview,
+                generatedSql: updated.generatedSql,
+                reviewedSql: updated.reviewedSql,
+                routeDecision: updated.routeDecision,
+            }),
+        }) ?? updated;
+        return { run: planned, session };
+    };
+    const checkNotebookResearchReuse = async (storage, run, input = {}) => {
+        const sql = notebookResearchString(run.reviewedSql) ?? notebookResearchString(run.generatedSql);
+        if (!sql)
+            throw new Error('Notebook research needs generated or reviewed SQL before reuse checking.');
+        const sourcePath = `${run.notebookPath}${run.sourceCellId ? `#${run.sourceCellId}` : ''}.sql`;
+        const match = await matchSqlForDqlReuse({
+            sql,
+            sourcePath,
+            name: run.title || 'Notebook research SQL',
+            domain: notebookResearchString(input.domain) ?? run.domain ?? 'uncategorized',
+            owner: notebookResearchString(input.owner) ?? 'analytics',
+        });
+        const promotion = {
+            importId: `reuse-check:${run.id}:${Date.now()}`,
+            candidateIds: ['reuse_check'],
+            recommendedAction: match.recommendedAction,
+            similarityMatches: match.similarityMatches.slice(0, 8).map(toNotebookPromotionMatch),
+            candidates: [{
+                    id: 'reuse_check',
+                    name: run.title || 'Notebook research SQL',
+                    domain: notebookResearchString(input.domain) ?? run.domain,
+                    reviewStatus: 'reuse_checked',
+                    recommendedAction: match.recommendedAction,
+                    similarityMatches: match.similarityMatches.slice(0, 5).map(toNotebookPromotionMatch),
+                    parameterPolicy: match.parameterPolicy.slice(0, 16).map((entry) => ({
+                        name: entry.name,
+                        policy: entry.policy,
+                    })),
+                    allowedFilters: match.allowedFilters.slice(0, 16),
+                    warnings: match.parameterDecisions
+                        .filter((decision) => decision.reason)
+                        .map((decision) => `${decision.name}: ${decision.reason}`)
+                        .slice(0, 12),
+                }],
+            createdAt: new Date().toISOString(),
+        };
+        const checked = storage.updateRun(run.id, {
+            dqlPromotionAction: match.recommendedAction,
+            dqlPromotion: promotion,
+            researchPlan: buildNotebookResearchPlan({
+                run: {
+                    ...run,
+                    dqlPromotionAction: match.recommendedAction,
+                    dqlPromotion: promotion,
+                },
+                evidence: run.evidence,
+                resultPreview: run.resultPreview,
+                generatedSql: run.generatedSql,
+                reviewedSql: run.reviewedSql,
+                routeDecision: run.routeDecision,
+            }),
+        }) ?? run;
+        return { run: checked, promotion, match };
+    };
+    const matchSqlForDqlReuse = async (input) => {
+        const sql = input.sql.trim();
+        if (!sql)
+            throw new Error('Missing SQL for reuse check.');
+        const sourceTables = extractSqlTablesLight(sql);
+        const candidate = {
+            id: 'match_sql',
+            sourceKind: 'raw-sql-file',
+            sourcePath: input.sourcePath ?? 'pasted.sql',
+            name: input.name ?? 'SQL match preview',
+            domain: input.domain ?? 'imported',
+            description: 'SQL match preview candidate.',
+            owner: input.owner ?? 'analytics',
+            tags: [],
+            sql,
+            dqlSource: '',
+            validation: null,
+            preview: null,
+            lineage: {
+                sourceTables,
+                parameters: [],
+                warnings: [],
+                statementIndex: 1,
+                totalStatements: 1,
+            },
+            confidence: 0.8,
+            splitStrategy: 'manual',
+            warnings: [],
+            conversionNotes: [],
+            aiAssistance: [],
+            reviewStatus: 'draft',
+        };
+        const evidence = deterministicDqlGenerationEvidence(candidate);
+        const patch = deterministicDqlGenerationPatch(candidate, evidence);
+        const contextPack = await buildDqlGenerationContextPack(projectRoot, { ...candidate, sql: patch.sql ?? sql }).catch(() => null);
+        const similarity = buildDqlGenerationSimilarityMatches(candidate, patch, contextPack);
+        return {
+            parameterDecisions: patch.parameterDecisions ?? [],
+            parameterPolicy: patch.parameterPolicy ?? [],
+            filterBindings: patch.filterBindings ?? [],
+            allowedFilters: patch.allowedFilters ?? [],
+            parameterizedSql: patch.sql ?? sql,
+            similarityMatches: similarity.matches,
+            recommendedAction: similarity.recommendedAction,
+        };
+    };
+    const buildNotebookDqlPromotionSummary = (session, draftBlockPath) => {
+        const primary = draftBlockPath
+            ? session.candidates.find((candidate) => candidate.draftSave?.path === draftBlockPath || candidate.savedPath === draftBlockPath) ?? session.candidates[0]
+            : session.candidates[0];
+        return {
+            importId: session.id,
+            candidateIds: session.candidates.map((candidate) => candidate.id),
+            draftBlockPath,
+            recommendedAction: primary?.recommendedAction,
+            similarityMatches: (primary?.similarityMatches ?? []).slice(0, 8).map(toNotebookPromotionMatch),
+            candidates: session.candidates.map((candidate) => ({
+                id: candidate.id,
+                name: candidate.name,
+                domain: candidate.domain,
+                draftPath: candidate.draftSave?.path,
+                savedPath: candidate.savedPath,
+                reviewStatus: candidate.reviewStatus,
+                recommendedAction: candidate.recommendedAction,
+                similarityMatches: (candidate.similarityMatches ?? []).slice(0, 5).map(toNotebookPromotionMatch),
+                parameterPolicy: (candidate.parameterPolicy ?? []).slice(0, 16).map((entry) => ({
+                    name: entry.name,
+                    policy: entry.policy,
+                })),
+                allowedFilters: (candidate.allowedFilters ?? []).slice(0, 16),
+                warnings: [...(candidate.warnings ?? []), ...(candidate.lineage.warnings ?? [])].slice(0, 12),
+            })),
+            createdAt: new Date().toISOString(),
+        };
+    };
+    const toNotebookPromotionMatch = (match) => ({
+        kind: match.kind,
+        objectKey: match.objectKey,
+        name: match.name,
+        status: match.status,
+        source: match.source,
+        score: match.score,
+        reason: match.reason,
+        recommendedAction: match.recommendedAction,
+    });
     // SSE clients for /api/watch hot-reload
     const sseClients = new Set();
     // Watch notebooks/, workbooks/, semantic-layer/, and data/ dirs for changes
@@ -398,8 +851,28 @@ export async function startLocalServer(opts) {
         if (validated.reviewStatus === 'rejected') {
             errors.unshift('Candidate was rejected.');
         }
+        const duplicateBlocker = duplicateCertificationBlocker(validated);
+        if (duplicateBlocker)
+            errors.unshift(duplicateBlocker);
         return { candidate: validated, errors };
     };
+    const duplicateCertificationBlocker = (candidate) => {
+        const match = candidate.similarityMatches?.[0];
+        if (!match)
+            return null;
+        const duplicateKind = match.kind === 'exact_sql_match'
+            || match.kind === 'parameterized_duplicate'
+            || (match.kind === 'business_duplicate' && match.status === 'certified' && match.score >= 0.76);
+        if (!duplicateKind)
+            return null;
+        const replacementFor = new Set((candidate.replacementFor ?? []).map((value) => value.toLowerCase()));
+        const documentedReplacement = candidate.recommendedAction === 'create_replacement'
+            || replacementFor.has(match.name.toLowerCase())
+            || (match.objectKey && replacementFor.has(match.objectKey.toLowerCase()));
+        if (documentedReplacement)
+            return null;
+        return `Likely duplicate of ${match.name} (${match.kind}, ${Math.round(match.score * 100)}% match). Reuse the existing block, extend it, or document this draft as a replacement before certification.`;
+    };
     const runBlockStudioPreviewSource = async (source, targetConnection) => {
         const activeConnection = requireActiveConnection(targetConnection);
         let tableMapping;
@@ -504,7 +977,50 @@ export async function startLocalServer(opts) {
         }
         return { passed, failed, skipped: 0, duration: Date.now() - start, assertions, runAt: new Date() };
     };
-    const certifyBlockStudioSource = async (source, blockPath) => {
+    const saveDqlGenerationDraft = (importId, candidate) => saveDqlGenerationDraftForProject(projectRoot, importId, candidate);
+    const createDqlGenerationSessionFromBody = async (body) => {
+        return createDqlGenerationSessionForProject(projectRoot, {
+            inputPath: typeof body.path === 'string' ? body.path : '',
+            inputMode: body.inputMode === 'paste' || body.inputMode === 'upload' || body.inputMode === 'path' ? body.inputMode : undefined,
+            sources: Array.isArray(body.sources)
+                ? body.sources.map((source, index) => ({
+                    path: typeof source?.path === 'string' ? source.path : `source-${index + 1}.sql`,
+                    content: typeof source?.content === 'string' ? source.content : '',
+                }))
+                : undefined,
+            sourceKind: typeof body.sourceKind === 'string' ? body.sourceKind : 'raw-sql',
+            domain: typeof body.domain === 'string' ? body.domain : undefined,
+            owner: typeof body.owner === 'string' ? body.owner : undefined,
+            tags: Array.isArray(body.tags) ? body.tags.map(String) : undefined,
+            provider: typeof body.provider === 'string' ? body.provider : undefined,
+        }, semanticLayer);
+    };
+    const loadDqlGenerationSession = (importId) => {
+        const session = loadBlockStudioImportSession(projectRoot, importId);
+        const candidates = session.candidates.map((candidate) => ({
+            ...candidate,
+            generationMode: candidate.generationMode ?? 'deterministic',
+            generationProvider: candidate.generationProvider ?? 'local-deterministic',
+            llmContext: candidate.llmContext ?? deterministicDqlGenerationContext(candidate, candidate.evidence ?? []),
+            evidence: candidate.evidence ?? deterministicDqlGenerationEvidence(candidate),
+            draftSave: candidate.draftSave ?? (isDraftBlockPath(candidate.savedPath)
+                ? { status: 'saved', path: candidate.savedPath }
+                : { status: 'pending' }),
+        }));
+        return {
+            ...session,
+            mode: 'ai-import',
+            candidates,
+            generation: {
+                provider: candidates.find((candidate) => candidate.generationProvider)?.generationProvider ?? 'local-deterministic',
+                aiEnabled: candidates.some((candidate) => candidate.generationMode === 'ai'),
+                contextObjectCount: candidates.reduce((sum, candidate) => sum + (candidate.evidence?.length ?? 0), 0),
+                createdDrafts: candidates.filter((candidate) => candidate.draftSave.status === 'saved').length,
+                warnings: candidates.flatMap((candidate) => candidate.draftSave.status === 'error' && candidate.draftSave.error ? [candidate.draftSave.error] : []),
+            },
+        };
+    };
+    const certifyBlockStudioSource = async (source, blockPath, options = {}) => {
         const validation = validateBlockStudioSource(source, semanticLayer);
         let preview = null;
         let testResults = null;
@@ -542,12 +1058,24 @@ export async function startLocalServer(opts) {
             description: parsed.description,
             owner: parsed.owner,
             tags: parsed.tags,
+            llmContext: parsed.llmContext,
+            pattern: parsed.pattern,
+            grain: parsed.grain,
+            entities: parsed.entities,
+            declaredOutputs: parsed.outputs,
+            dimensions: parsed.dimensions,
+            allowedFilters: parsed.allowedFilters,
+            parameterPolicy: parsed.parameterPolicy,
+            filterBindings: parsed.filterBindings,
+            sourceSystems: parsed.sourceSystems,
+            replacementFor: parsed.replacementFor,
+            reviewCadence: parsed.reviewCadence,
             dependencies: [],
             usedInCount: 0,
             createdAt: new Date(),
             updatedAt: new Date(),
         };
-        const certification = new Certifier().evaluate(record, testResults ?? undefined);
+        const certification = new Certifier(options.enterprise ? ENTERPRISE_RULES : undefined).evaluate(record, testResults ?? undefined);
         const checklist = buildBlockStudioCertificationChecklist({
             source,
             validation,
@@ -730,6 +1258,7 @@ export async function startLocalServer(opts) {
                 const variables = body.variables && typeof body.variables === 'object'
                     ? body.variables
                     : {};
+                const dashboardVariables = dashboardRuntimeVariables(loaded.dashboard, variables);
                 const tiles = [];
                 let localApps = null;
                 for (const item of loaded.dashboard.layout.items) {
@@ -831,8 +1360,15 @@ export async function startLocalServer(opts) {
                             });
                             continue;
                         }
-                        const prepared = prepareLocalExecution(semanticCompose?.sql ?? plan.sql, targetConnection, projectRoot, projectConfig);
-                        const result = await executor.executeQuery(prepared.sql, plan?.sqlParams ?? [], runtimeVariables({ ...(plan?.variables ?? {}), ...variables }), prepared.connection);
+                        const filterApplication = applyDashboardFiltersToBlockExecution({
+                            sql: semanticCompose?.sql ?? plan.sql,
+                            sqlParams: plan?.sqlParams ?? [],
+                            variables: { ...(plan?.variables ?? {}), ...dashboardVariables },
+                            block,
+                            dashboard: loaded.dashboard,
+                        });
+                        const prepared = prepareLocalExecution(filterApplication.sql, targetConnection, projectRoot, projectConfig);
+                        const result = await executor.executeQuery(prepared.sql, filterApplication.sqlParams, runtimeVariables(filterApplication.variables), prepared.connection);
                         tiles.push({
                             tileId: item.i,
                             status: 'ok',
@@ -843,6 +1379,10 @@ export async function startLocalServer(opts) {
                             viz: item.viz,
                             chartConfig: mergeDashboardChartConfig(plan?.chartConfig, item),
                             result: normalizeQueryResult(result),
+                            filters: {
+                                applied: filterApplication.appliedFilters,
+                                skipped: filterApplication.skippedFilters,
+                            },
                             citation: {
                                 kind: 'block',
                                 name: block.name,
@@ -885,11 +1425,11 @@ export async function startLocalServer(opts) {
             return;
         }
         // Apps, dashboards, persona — see apps-api.ts. Returns true if handled.
-        if (path.startsWith('/api/apps') || path === '/api/persona') {
+        if (path.startsWith('/api/apps') || path.startsWith('/api/visualizations') || path === '/api/persona') {
             try {
                 const handled = await handleAppsApi({
                     req,
-                    res,
+                    res: res,
                     url,
                     path,
                     projectRoot,
@@ -1019,6 +1559,393 @@ export async function startLocalServer(opts) {
             }
             return;
         }
+        if (req.method === 'GET' && path === '/api/notebook/research') {
+            const storage = openNotebookResearchStorage();
+            try {
+                const notebookPath = notebookResearchString(url.searchParams.get('path'));
+                const sourceCellId = notebookResearchString(url.searchParams.get('sourceCellId') ?? url.searchParams.get('cellId'));
+                const domain = notebookResearchString(url.searchParams.get('domain'));
+                const owner = notebookResearchString(url.searchParams.get('owner'));
+                const intent = notebookResearchIntent(url.searchParams.get('intent'));
+                const search = notebookResearchString(url.searchParams.get('q')) ?? notebookResearchString(url.searchParams.get('search'));
+                const status = notebookResearchStatus(url.searchParams.get('status'));
+                const reviewStatus = notebookResearchReviewStatus(url.searchParams.get('reviewStatus'));
+                const promotionAction = notebookResearchPromotionAction(url.searchParams.get('promotionAction') ?? url.searchParams.get('action'));
+                const readiness = notebookResearchReadiness(url.searchParams.get('readiness') ?? url.searchParams.get('ready'));
+                const age = notebookResearchAge(url.searchParams.get('age'));
+                const nextAction = notebookResearchNextAction(url.searchParams.get('nextAction') ?? url.searchParams.get('next'));
+                const activeOnlyParam = url.searchParams.get('activeOnly') ?? url.searchParams.get('active');
+                const activeOnly = activeOnlyParam === 'true' || activeOnlyParam === '1';
+                const sort = notebookResearchSort(url.searchParams.get('sort'));
+                const limit = notebookResearchInteger(url.searchParams.get('limit'), 50, 1, 500);
+                const offset = notebookResearchInteger(url.searchParams.get('offset'), 0, 0, Number.MAX_SAFE_INTEGER);
+                const page = storage.listRunsPage({ notebookPath, sourceCellId, domain, owner, intent, search, status, reviewStatus, promotionAction, readiness, age, nextAction, activeOnly, sort, limit, offset });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(withNotebookResearchChecklistPage(page)));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            finally {
+                storage.close();
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/notebook/research') {
+            const storage = openNotebookResearchStorage();
+            try {
+                const body = await readJSON(req);
+                const notebookPath = notebookResearchString(body.notebookPath) ?? notebookResearchString(body.path);
+                const question = notebookResearchString(body.question);
+                const sourceCell = notebookResearchSourceCellPayload(body);
+                const sourceCellId = notebookResearchString(body.sourceCellId) ?? notebookResearchSourceCellId(sourceCell);
+                const sourceCellName = notebookResearchString(body.sourceCellName) ?? notebookResearchSourceCellName(sourceCell);
+                const sourceCellFingerprint = notebookResearchString(body.sourceCellFingerprint) ?? notebookResearchSourceCellFingerprint(sourceCell);
+                if (!notebookPath || !question) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'notebookPath and question are required.' }));
+                    return;
+                }
+                const created = storage.createRun({
+                    notebookPath,
+                    domain: notebookResearchString(body.domain),
+                    owner: notebookResearchString(body.owner),
+                    sourceCell,
+                    sourceCellId,
+                    sourceCellName,
+                    sourceCellFingerprint,
+                    title: notebookResearchString(body.title),
+                    question,
+                    intent: notebookResearchIntent(body.intent),
+                    context: body.context,
+                    generatedSql: notebookResearchString(body.generatedSql),
+                    reviewedSql: notebookResearchString(body.reviewedSql),
+                });
+                const run = body.run === true
+                    ? await runNotebookResearch(storage, created, {
+                        domain: notebookResearchString(body.domain),
+                        sourceCellFingerprint,
+                        question,
+                        intent: notebookResearchIntent(body.intent),
+                        context: body.context,
+                        generatedSql: notebookResearchString(body.generatedSql),
+                        reviewedSql: notebookResearchString(body.reviewedSql),
+                    })
+                    : created;
+                res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ run: withNotebookResearchChecklist(run) }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            finally {
+                storage.close();
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/notebook/research/context-preview') {
+            try {
+                const body = await readJSON(req);
+                const notebookPath = notebookResearchString(body.notebookPath) ?? notebookResearchString(body.path);
+                const question = notebookResearchString(body.question);
+                if (!notebookPath || !question) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'notebookPath and question are required.' }));
+                    return;
+                }
+                const intent = notebookResearchIntent(body.intent) ?? 'ad_hoc_analysis';
+                const domain = notebookResearchString(body.domain);
+                const context = body.context;
+                const sourceCell = notebookResearchSourceCellPayload(body);
+                const contextPack = await buildLocalContextPack(projectRoot, {
+                    question,
+                    mode: 'question',
+                    surface: 'notebook',
+                    selectedContext: {
+                        activeSurface: 'notebook',
+                        notebookPath,
+                        domain,
+                        sourceCellId: notebookResearchString(body.sourceCellId) ?? notebookResearchSourceCellId(sourceCell),
+                        sourceCellName: notebookResearchString(body.sourceCellName) ?? notebookResearchSourceCellName(sourceCell),
+                        context,
+                        intent,
+                        researchPattern: notebookResearchIntentPattern(intent),
+                    },
+                    strictness: 'balanced',
+                    limit: 100,
+                });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(notebookResearchContextPreview(contextPack)));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/notebook/research/seed-cells') {
+            const storage = openNotebookResearchStorage();
+            try {
+                const body = await readJSON(req);
+                const notebookPath = notebookResearchString(body.notebookPath) ?? notebookResearchString(body.path);
+                if (!notebookPath) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'notebookPath is required.' }));
+                    return;
+                }
+                const cells = Array.isArray(body.cells) ? body.cells : [];
+                if (cells.length === 0) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'At least one source cell is required.' }));
+                    return;
+                }
+                const validCells = cells.filter((cell) => Boolean(cell && typeof cell === 'object' && !Array.isArray(cell)));
+                const invalidCellCount = cells.length - validCells.length;
+                const seeded = storage.seedRunsFromCells({
+                    notebookPath,
+                    domain: notebookResearchString(body.domain),
+                    owner: notebookResearchString(body.owner),
+                    notebookTitle: notebookResearchString(body.notebookTitle),
+                    cells: validCells.map((cell) => ({
+                        sourceCell: notebookResearchSourceCellPayload(cell),
+                        id: notebookResearchString(cell.id),
+                        sourceCellId: notebookResearchString(cell.sourceCellId),
+                        name: notebookResearchString(cell.name),
+                        sourceCellName: notebookResearchString(cell.sourceCellName),
+                        sourceCellFingerprint: notebookResearchString(cell.sourceCellFingerprint),
+                        title: notebookResearchString(cell.title),
+                        type: notebookResearchString(cell.type),
+                        sql: notebookResearchString(cell.sql),
+                        content: notebookResearchString(cell.content),
+                        source: notebookResearchString(cell.source),
+                        question: notebookResearchString(cell.question),
+                        intent: notebookResearchIntent(cell.intent),
+                    })),
+                    limit: 1000,
+                });
+                res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    created: seeded.created.map(withNotebookResearchChecklist),
+                    createdCount: seeded.createdCount,
+                    skippedCount: seeded.skippedCount + invalidCellCount,
+                    limitApplied: seeded.limitApplied,
+                }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            finally {
+                storage.close();
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/notebook/research/source-coverage') {
+            const storage = openNotebookResearchStorage();
+            try {
+                const body = await readJSON(req);
+                const notebookPath = notebookResearchString(body.notebookPath) ?? notebookResearchString(body.path);
+                if (!notebookPath) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'notebookPath is required.' }));
+                    return;
+                }
+                const rawSourceCells = Array.isArray(body.sourceCells)
+                    ? body.sourceCells
+                    : Array.isArray(body.cells)
+                        ? body.cells
+                        : [];
+                const sourceCells = rawSourceCells.flatMap((cell) => {
+                    if (!cell || typeof cell !== 'object' || Array.isArray(cell))
+                        return [];
+                    const record = cell;
+                    const nested = notebookResearchSourceCellPayload(record) ?? {};
+                    return [{
+                            ...nested,
+                            id: notebookResearchString(record.id) ?? nested.id,
+                            sourceCellId: notebookResearchString(record.sourceCellId) ?? nested.sourceCellId,
+                            cellId: notebookResearchString(record.cellId) ?? nested.cellId,
+                            name: notebookResearchString(record.name) ?? nested.name,
+                            sourceCellName: notebookResearchString(record.sourceCellName) ?? nested.sourceCellName,
+                            title: notebookResearchString(record.title) ?? nested.title,
+                            fingerprint: notebookResearchString(record.fingerprint) ?? nested.fingerprint,
+                            sourceCellFingerprint: notebookResearchString(record.sourceCellFingerprint) ?? nested.sourceCellFingerprint,
+                            sqlFingerprint: notebookResearchString(record.sqlFingerprint) ?? nested.sqlFingerprint,
+                            type: notebookResearchString(record.type) ?? nested.type,
+                        }];
+                });
+                const requestedIds = Array.isArray(body.sourceCellIds)
+                    ? body.sourceCellIds
+                    : rawSourceCells.length > 0
+                        ? sourceCells.map((cell) => notebookResearchSourceCellId(cell))
+                        : [];
+                const sourceCellIds = Array.from(new Set(requestedIds
+                    .map((id) => notebookResearchString(id))
+                    .filter((id) => Boolean(id))));
+                const requestedSourceCellCount = new Set([
+                    ...sourceCellIds,
+                    ...sourceCells
+                        .map((cell) => notebookResearchSourceCellId(cell))
+                        .filter((id) => Boolean(id)),
+                ]).size;
+                const limit = typeof body.limit === 'number' && Number.isFinite(body.limit)
+                    ? Math.max(1, Math.min(10_000, Math.floor(body.limit)))
+                    : 10_000;
+                const linkedRuns = storage.listLatestRunsBySourceCell({
+                    notebookPath,
+                    sourceCellIds,
+                    sourceCells,
+                    limit,
+                });
+                const missingRuns = storage.listLatestRunsForMissingSourceCells({
+                    notebookPath,
+                    sourceCellIds,
+                    sourceCells,
+                    limit,
+                });
+                const runs = [...linkedRuns, ...missingRuns];
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    runs: runs.map(withNotebookResearchChecklist),
+                    requestedCount: requestedSourceCellCount,
+                    matchedCount: runs.length,
+                    limitApplied: requestedSourceCellCount > limit,
+                }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            finally {
+                storage.close();
+            }
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/notebook/research/diagnostics') {
+            const storage = openNotebookResearchStorage();
+            try {
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(storage.getDiagnostics()));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            finally {
+                storage.close();
+            }
+            return;
+        }
+        const notebookResearchMatch = /^\/api\/notebook\/research\/([^/]+)(?:\/([^/]+))?$/.exec(path);
+        if (notebookResearchMatch) {
+            const id = decodeURIComponent(notebookResearchMatch[1]);
+            const action = notebookResearchMatch[2];
+            const storage = openNotebookResearchStorage();
+            try {
+                const run = storage.getRun(id);
+                if (!run) {
+                    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Notebook research run not found.' }));
+                    return;
+                }
+                if (req.method === 'GET' && !action) {
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ run: withNotebookResearchChecklist(run) }));
+                    return;
+                }
+                if (req.method === 'PATCH' && !action) {
+                    const body = await readJSON(req);
+                    const sourceCell = notebookResearchSourceCellPayload(body);
+                    const sourceCellIdPatch = notebookResearchPatchString(body, 'sourceCellId');
+                    const sourceCellNamePatch = notebookResearchPatchString(body, 'sourceCellName');
+                    const sourceCellFingerprintPatch = notebookResearchPatchString(body, 'sourceCellFingerprint');
+                    const updated = storage.updateRun(id, {
+                        domain: notebookResearchString(body.domain),
+                        owner: notebookResearchString(body.owner),
+                        sourceCellId: sourceCellIdPatch !== undefined ? sourceCellIdPatch : notebookResearchSourceCellId(sourceCell),
+                        sourceCellName: sourceCellNamePatch !== undefined ? sourceCellNamePatch : notebookResearchSourceCellName(sourceCell),
+                        sourceCellFingerprint: sourceCellFingerprintPatch !== undefined ? sourceCellFingerprintPatch : notebookResearchSourceCellFingerprint(sourceCell),
+                        title: notebookResearchString(body.title),
+                        question: notebookResearchString(body.question),
+                        intent: notebookResearchIntent(body.intent),
+                        context: body.context,
+                        recommendation: notebookResearchString(body.recommendation),
+                        evidence: body.evidence,
+                        contextPackId: notebookResearchString(body.contextPackId),
+                        routeDecision: body.routeDecision,
+                        generatedSql: notebookResearchString(body.generatedSql),
+                        reviewedSql: notebookResearchString(body.reviewedSql),
+                        warnings: Array.isArray(body.warnings) ? body.warnings.filter((item) => typeof item === 'string') : undefined,
+                        reviewStatus: notebookResearchReviewStatus(body.reviewStatus),
+                    }) ?? run;
+                    const planned = storage.updateRun(updated.id, {
+                        researchPlan: buildNotebookResearchPlan({
+                            run: updated,
+                            evidence: updated.evidence,
+                            resultPreview: updated.resultPreview,
+                            previewError: updated.error,
+                            generatedSql: updated.generatedSql,
+                            reviewedSql: updated.reviewedSql,
+                            routeDecision: updated.routeDecision,
+                        }),
+                    }) ?? updated;
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ run: withNotebookResearchChecklist(planned) }));
+                    return;
+                }
+                if (req.method === 'POST' && action === 'run') {
+                    const body = await readJSON(req).catch(() => ({}));
+                    const sourceCell = notebookResearchSourceCellPayload(body);
+                    const updated = await runNotebookResearch(storage, run, {
+                        domain: notebookResearchString(body.domain),
+                        owner: notebookResearchString(body.owner),
+                        sourceCellFingerprint: notebookResearchString(body.sourceCellFingerprint) ?? notebookResearchSourceCellFingerprint(sourceCell),
+                        question: notebookResearchString(body.question),
+                        intent: notebookResearchIntent(body.intent),
+                        context: body.context,
+                        generatedSql: notebookResearchString(body.generatedSql),
+                        reviewedSql: notebookResearchString(body.reviewedSql),
+                    });
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ run: withNotebookResearchChecklist(updated) }));
+                    return;
+                }
+                if (req.method === 'POST' && action === 'reuse-check') {
+                    const body = await readJSON(req).catch(() => ({}));
+                    const payload = await checkNotebookResearchReuse(storage, run, {
+                        domain: notebookResearchString(body.domain),
+                        owner: notebookResearchString(body.owner),
+                    });
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ ...payload, run: withNotebookResearchChecklist(payload.run) }));
+                    return;
+                }
+                if (req.method === 'POST' && action === 'promote-dql') {
+                    const body = await readJSON(req).catch(() => ({}));
+                    const payload = await promoteNotebookResearchToDql(storage, run, {
+                        domain: notebookResearchString(body.domain),
+                        owner: notebookResearchString(body.owner),
+                        provider: notebookResearchString(body.provider),
+                        tags: Array.isArray(body.tags) ? body.tags.filter((item) => typeof item === 'string') : undefined,
+                    });
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ ...payload, run: withNotebookResearchChecklist(payload.run) }));
+                    return;
+                }
+                res.writeHead(405, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: 'Unsupported notebook research operation.' }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            finally {
+                storage.close();
+            }
+            return;
+        }
         // ── run snapshots (v0.11) ───────────────────────────────────────────────
         // Captures executed notebook state (query results + timings) in a
         // sibling `.run.json` so notebooks can show last-run output without
@@ -1304,49 +2231,51 @@ export async function startLocalServer(opts) {
         // ── Block library (list all blocks with metadata) ────────────────────
         if (req.method === 'GET' && path === '/api/blocks/library') {
             try {
-                const blocksDir = join(projectRoot, 'blocks');
                 const blocks = [];
-                if (existsSync(blocksDir)) {
-                    const scanDir = (dir) => {
-                        for (const entry of readdirSync(dir, { withFileTypes: true })) {
-                            if (entry.isDirectory()) {
-                                scanDir(join(dir, entry.name));
-                            }
-                            else if (entry.name.endsWith('.dql')) {
-                                const filePath = join(dir, entry.name);
-                                const relPath = relative(projectRoot, filePath);
-                                try {
-                                    const source = readFileSync(filePath, 'utf-8');
-                                    const stat = statSync(filePath);
-                                    // Quick regex parse for key block fields
-                                    const nameMatch = /block\s+"([^"]+)"/.exec(source);
-                                    const domainMatch = /domain\s*=\s*"([^"]+)"/.exec(source);
-                                    const statusMatch = /status\s*=\s*"([^"]+)"/.exec(source);
-                                    const ownerMatch = /owner\s*=\s*"([^"]+)"/.exec(source);
-                                    const descMatch = /description\s*=\s*"([^"]+)"/.exec(source);
-                                    const tagsMatch = /tags\s*=\s*\[([^\]]*)\]/.exec(source);
-                                    const parsedTags = tagsMatch
-                                        ? tagsMatch[1].split(',').map((tag) => tag.trim().replace(/^"|"$/g, '')).filter(Boolean)
-                                        : [];
-                                    const llmMatch = /llmContext\s*=\s*"((?:[^"\\]|\\.)*)"/.exec(source);
-                                    blocks.push({
-                                        name: nameMatch?.[1] ?? entry.name.replace('.dql', ''),
-                                        domain: domainMatch?.[1] ?? 'uncategorized',
-                                        status: statusMatch?.[1] ?? 'draft',
-                                        owner: ownerMatch?.[1] ?? null,
-                                        tags: parsedTags,
-                                        path: relPath,
-                                        lastModified: stat.mtime.toISOString(),
-                                        description: descMatch?.[1] ?? '',
-                                        llmContext: llmMatch?.[1] ?? null,
-                                    });
-                                }
-                                catch { /* skip unreadable files */ }
+                const seen = new Set();
+                const scanDir = (dir) => {
+                    if (!existsSync(dir))
+                        return;
+                    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+                        const filePath = join(dir, entry.name);
+                        if (entry.isDirectory()) {
+                            scanDir(filePath);
+                        }
+                        else if (entry.name.endsWith('.dql') && !seen.has(filePath)) {
+                            seen.add(filePath);
+                            const relPath = relative(projectRoot, filePath).replaceAll('\\', '/');
+                            try {
+                                const source = readFileSync(filePath, 'utf-8');
+                                const stat = statSync(filePath);
+                                // Quick regex parse for key block fields
+                                const nameMatch = /block\s+"([^"]+)"/.exec(source);
+                                const domainMatch = /domain\s*=\s*"([^"]+)"/.exec(source);
+                                const statusMatch = /status\s*=\s*"([^"]+)"/.exec(source);
+                                const ownerMatch = /owner\s*=\s*"([^"]+)"/.exec(source);
+                                const descMatch = /description\s*=\s*"([^"]+)"/.exec(source);
+                                const tagsMatch = /tags\s*=\s*\[([^\]]*)\]/.exec(source);
+                                const parsedTags = tagsMatch
+                                    ? tagsMatch[1].split(',').map((tag) => tag.trim().replace(/^"|"$/g, '')).filter(Boolean)
+                                    : [];
+                                const llmMatch = /llmContext\s*=\s*"((?:[^"\\]|\\.)*)"/.exec(source);
+                                blocks.push({
+                                    name: nameMatch?.[1] ?? entry.name.replace('.dql', ''),
+                                    domain: (domainMatch?.[1] ?? inferBlockStudioPathDomain(relPath)) || 'uncategorized',
+                                    status: statusMatch?.[1] ?? 'draft',
+                                    owner: ownerMatch?.[1] ?? null,
+                                    tags: parsedTags,
+                                    path: relPath,
+                                    lastModified: stat.mtime.toISOString(),
+                                    description: descMatch?.[1] ?? '',
+                                    llmContext: llmMatch?.[1] ?? null,
+                                });
                             }
+                            catch { /* skip unreadable files */ }
                         }
-                    };
-                    scanDir(blocksDir);
-                }
+                    }
+                };
+                scanDir(join(projectRoot, 'blocks'));
+                scanDir(join(projectRoot, 'domains'));
                 blocks.sort((a, b) => new Date(b.lastModified).getTime() - new Date(a.lastModified).getTime());
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({ blocks }));
@@ -1555,20 +2484,216 @@ export async function startLocalServer(opts) {
                     res.end(serializeJSON({ error: 'source is required' }));
                     return;
                 }
-                const result = await certifyBlockStudioSource(source, blockPath);
+                const result = await certifyBlockStudioSource(source, blockPath, { enterprise: body.enterprise !== false });
                 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 }));
                     return;
                 }
-                if (blockPath)
-                    setBlockStudioStatus(projectRoot, blockPath, 'certified');
+                let certifiedPayload = null;
+                const certifiedSource = setBlockStudioStatusInSource(source, 'certified');
+                if (blockPath) {
+                    const normalizedBlockPath = normalize(blockPath).replace(/^\/+/, '');
+                    const parsed = parseBlockSourceMetadata(certifiedSource);
+                    if (isDraftBlockPath(normalizedBlockPath)) {
+                        const savedPath = saveBlockStudioArtifacts(projectRoot, {
+                            currentPath: normalizedBlockPath,
+                            source: certifiedSource,
+                            name: parsed.name,
+                            domain: parsed.domain,
+                            description: parsed.description,
+                            owner: parsed.owner,
+                            tags: parsed.tags,
+                        });
+                        certifiedPayload = openBlockStudioDocument(projectRoot, savedPath, semanticLayer);
+                    }
+                    else {
+                        setBlockStudioStatus(projectRoot, normalizedBlockPath, 'certified');
+                        certifiedPayload = openBlockStudioDocument(projectRoot, normalizedBlockPath, semanticLayer);
+                    }
+                }
                 await refreshLocalMetadataCatalog(projectRoot);
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
-                res.end(serializeJSON({ ok: true, status: 'certified', ...result }));
+                res.end(serializeJSON({
+                    ok: true,
+                    status: 'certified',
+                    ...result,
+                    path: certifiedPayload?.path ?? blockPath ?? null,
+                    source: certifiedPayload?.source ?? certifiedSource,
+                    metadata: certifiedPayload?.metadata,
+                    companionPath: certifiedPayload?.companionPath ?? null,
+                    validation: certifiedPayload?.validation ?? result.validation,
+                }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/block-studio/ai-imports') {
+            try {
+                const body = await readJSON(req);
+                const session = await createDqlGenerationSessionFromBody(body);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(session));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/block-studio/match-sql') {
+            try {
+                const body = await readJSON(req);
+                if (typeof body.sql !== 'string' || body.sql.trim().length === 0) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Missing SQL in request body.' }));
+                    return;
+                }
+                const sql = body.sql.trim();
+                const match = await matchSqlForDqlReuse({
+                    sql,
+                    sourcePath: typeof body.sourcePath === 'string' ? body.sourcePath : 'pasted.sql',
+                    name: typeof body.name === 'string' ? body.name : 'SQL match preview',
+                    domain: typeof body.domain === 'string' ? body.domain : 'imported',
+                    owner: typeof body.owner === 'string' ? body.owner : 'analytics',
+                });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(match));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        const aiImportPathMatch = path.match(/^\/api\/block-studio\/ai-imports\/([^/]+)(?:\/candidates\/([^/]+)(?:\/(preview|certify))?)?$/);
+        if (aiImportPathMatch) {
+            const importId = decodeURIComponent(aiImportPathMatch[1]);
+            const candidateId = aiImportPathMatch[2] ? decodeURIComponent(aiImportPathMatch[2]) : null;
+            const action = aiImportPathMatch[3] ?? null;
+            try {
+                if (req.method === 'GET' && !candidateId) {
+                    const session = loadDqlGenerationSession(importId);
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(session));
+                    return;
+                }
+                if (req.method === 'PATCH' && candidateId && !action) {
+                    const body = await readJSON(req);
+                    const candidate = updateBlockStudioImportCandidate(projectRoot, importId, candidateId, {
+                        name: typeof body.name === 'string' ? body.name : undefined,
+                        domain: typeof body.domain === 'string' ? body.domain : undefined,
+                        description: typeof body.description === 'string' ? body.description : undefined,
+                        owner: typeof body.owner === 'string' ? body.owner : undefined,
+                        tags: Array.isArray(body.tags) ? body.tags.map(String) : undefined,
+                        terms: Array.isArray(body.terms) ? body.terms.map(String) : undefined,
+                        pattern: typeof body.pattern === 'string' ? body.pattern : undefined,
+                        grain: typeof body.grain === 'string' ? body.grain : undefined,
+                        entities: Array.isArray(body.entities) ? body.entities.map(String) : undefined,
+                        outputs: Array.isArray(body.outputs) ? body.outputs.map(String) : undefined,
+                        dimensions: Array.isArray(body.dimensions) ? body.dimensions.map(String) : undefined,
+                        allowedFilters: Array.isArray(body.allowedFilters) ? body.allowedFilters.map(String) : undefined,
+                        parameterPolicy: Array.isArray(body.parameterPolicy) ? body.parameterPolicy : undefined,
+                        filterBindings: Array.isArray(body.filterBindings) ? body.filterBindings : undefined,
+                        sourceSystems: Array.isArray(body.sourceSystems) ? body.sourceSystems.map(String) : undefined,
+                        replacementFor: Array.isArray(body.replacementFor) ? body.replacementFor.map(String) : undefined,
+                        reviewCadence: typeof body.reviewCadence === 'string' ? body.reviewCadence : undefined,
+                        sql: typeof body.sql === 'string' ? body.sql : undefined,
+                        llmContext: typeof body.llmContext === 'string' ? body.llmContext : undefined,
+                    });
+                    const validated = validateImportCandidate(candidate);
+                    const savedDraft = saveDqlGenerationDraft(importId, validated);
+                    writeBlockStudioImportCandidate(projectRoot, importId, savedDraft);
+                    await refreshLocalMetadataCatalog(projectRoot);
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(savedDraft));
+                    return;
+                }
+                if (req.method === 'POST' && candidateId && action === 'preview') {
+                    const candidate = readBlockStudioImportCandidate(projectRoot, importId, candidateId);
+                    const preview = await runBlockStudioPreviewSource(candidate.dqlSource);
+                    const next = saveDqlGenerationDraft(importId, {
+                        ...candidate,
+                        preview,
+                        validation: validateBlockStudioSource(candidate.dqlSource, semanticLayer),
+                    });
+                    writeBlockStudioImportCandidate(projectRoot, importId, next);
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(next));
+                    return;
+                }
+                if (req.method === 'POST' && candidateId && action === 'certify') {
+                    const candidate = readBlockStudioImportCandidate(projectRoot, importId, candidateId);
+                    const readiness = validateImportCandidateForSave(candidate);
+                    if (readiness.errors.length > 0) {
+                        const savedDraft = saveDqlGenerationDraft(importId, readiness.candidate);
+                        writeBlockStudioImportCandidate(projectRoot, importId, savedDraft);
+                        res.writeHead(422, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({
+                            error: readiness.errors.join(' '),
+                            candidate: savedDraft,
+                            diagnostics: savedDraft.validation?.diagnostics ?? [],
+                        }));
+                        return;
+                    }
+                    const certifiedSource = setBlockStudioSourceStatus(readiness.candidate.dqlSource, 'certified');
+                    const certification = await certifyBlockStudioSource(certifiedSource, readiness.candidate.savedPath, { enterprise: true });
+                    const blockers = Array.from(new Set(certification.checklist.blockers));
+                    if (!certification.certification.certified || blockers.length > 0) {
+                        const savedDraft = saveDqlGenerationDraft(importId, readiness.candidate);
+                        writeBlockStudioImportCandidate(projectRoot, importId, savedDraft);
+                        res.writeHead(422, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ ok: false, candidate: savedDraft, blockers, ...certification }));
+                        return;
+                    }
+                    const savedPath = saveBlockStudioArtifacts(projectRoot, {
+                        currentPath: readiness.candidate.savedPath,
+                        source: certifiedSource,
+                        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: readiness.candidate.sourceKind,
+                            sourcePath: readiness.candidate.sourcePath,
+                        },
+                    });
+                    const next = {
+                        ...readiness.candidate,
+                        dqlSource: certifiedSource,
+                        reviewStatus: 'saved',
+                        savedPath,
+                        validation: validateBlockStudioSource(certifiedSource, semanticLayer),
+                        generationMode: readiness.candidate.generationMode ?? 'deterministic',
+                        generationProvider: readiness.candidate.generationProvider ?? 'local-deterministic',
+                        llmContext: readiness.candidate.llmContext ?? deterministicDqlGenerationContext(readiness.candidate, readiness.candidate.evidence ?? []),
+                        evidence: readiness.candidate.evidence ?? [],
+                        draftSave: readiness.candidate.draftSave ?? { status: 'pending' },
+                    };
+                    writeBlockStudioImportCandidate(projectRoot, importId, next);
+                    await refreshLocalMetadataCatalog(projectRoot);
+                    const payload = openBlockStudioDocument(projectRoot, savedPath, semanticLayer);
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ candidate: next, block: payload, certification }));
+                    return;
+                }
+                res.writeHead(405, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: 'Unsupported AI import operation.' }));
             }
             catch (error) {
+                if (error instanceof Error && error.message === 'BLOCK_EXISTS') {
+                    res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Block already exists' }));
+                    return;
+                }
                 res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
             }
@@ -1708,6 +2833,8 @@ export async function startLocalServer(opts) {
                         description: typeof body.description === 'string' ? body.description : undefined,
                         owner: typeof body.owner === 'string' ? body.owner : undefined,
                         tags: Array.isArray(body.tags) ? body.tags.map(String) : undefined,
+                        terms: Array.isArray(body.terms) ? body.terms.map(String) : undefined,
+                        reviewCadence: typeof body.reviewCadence === 'string' ? body.reviewCadence : undefined,
                         sql: typeof body.sql === 'string' ? body.sql : undefined,
                         reviewStatus,
                     });
@@ -1844,6 +2971,55 @@ export async function startLocalServer(opts) {
             }
             return;
         }
+        if (req.method === 'GET' && path === '/api/semantic-layer/diagnostics') {
+            try {
+                const diagnostics = buildSemanticLayerDiagnostics(projectRoot, projectConfig, {
+                    semanticLayer,
+                    semanticErrors: semanticLayerErrors,
+                    semanticConfig,
+                    detectedProvider: semanticDetectedProvider,
+                    lastSyncTime: semanticLastSyncTime,
+                });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(diagnostics));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/semantic-layer/reload') {
+            try {
+                const semanticConnection = connection;
+                const executeQuery = semanticConfig?.provider === 'snowflake' && semanticConnection
+                    ? async (sql) => { const r = await executor.executeQuery(sql, [], {}, semanticConnection); return { rows: r.rows }; }
+                    : undefined;
+                const refreshed = await resolveSemanticLayerAsync(semanticConfig, projectRoot, executeQuery);
+                semanticLayer = refreshed.layer;
+                semanticLayerErrors = refreshed.errors;
+                semanticDetectedProvider = refreshed.detectedProvider;
+                semanticLastSyncTime = refreshed.layer ? new Date().toISOString() : null;
+                semanticImportManifest = loadSemanticImportManifest(projectRoot);
+                const diagnostics = buildSemanticLayerDiagnostics(projectRoot, projectConfig, {
+                    semanticLayer,
+                    semanticErrors: semanticLayerErrors,
+                    semanticConfig,
+                    detectedProvider: semanticDetectedProvider,
+                    lastSyncTime: semanticLastSyncTime,
+                });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    ok: Boolean(refreshed.layer),
+                    ...diagnostics,
+                }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
         if (req.method === 'GET' && path === '/api/block-studio/open') {
             try {
                 const relativePath = url.searchParams.get('path');
@@ -1908,8 +3084,9 @@ export async function startLocalServer(opts) {
                     res.end(serializeJSON({ error: 'Block name is required.' }));
                     return;
                 }
-                const savedPath = saveBlockStudioArtifacts(projectRoot, {
-                    currentPath: typeof body.path === 'string' ? body.path : undefined,
+                const currentPath = typeof body.path === 'string' ? body.path : undefined;
+                const saveOptions = {
+                    currentPath,
                     source,
                     name: metadata.name,
                     domain: metadata.domain,
@@ -1925,7 +3102,13 @@ export async function startLocalServer(opts) {
                             sourcePath: metadata.sourcePath,
                         }
                         : undefined,
-                });
+                };
+                const savedPath = isDraftBlockPath(currentPath)
+                    ? saveBlockStudioDraftArtifacts(projectRoot, {
+                        ...saveOptions,
+                        stableSuffix: metadata.candidateId,
+                    })
+                    : saveBlockStudioArtifacts(projectRoot, saveOptions);
                 await refreshLocalMetadataCatalog(projectRoot);
                 const payload = openBlockStudioDocument(projectRoot, savedPath, semanticLayer);
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -2051,7 +3234,7 @@ export async function startLocalServer(opts) {
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
                     available: false,
-                    provider: projectConfig.semanticLayer?.provider ?? semanticDetectedProvider ?? null,
+                    provider: semanticConfig?.provider ?? semanticDetectedProvider ?? null,
                     errors: semanticLayerErrors,
                     metrics: [],
                     measures: [],
@@ -2180,9 +3363,9 @@ export async function startLocalServer(opts) {
                 owner: q.owner ?? null,
                 source: q.source ?? null,
             }));
-            const provider = projectConfig.semanticLayer?.provider ?? semanticDetectedProvider ?? 'dql';
+            const provider = semanticConfig?.provider ?? semanticDetectedProvider ?? 'dql';
             const dbtExecutionReady = provider === 'dbt'
-                ? hasDbtSemanticManifest(projectRoot, projectConfig.semanticLayer?.projectPath)
+                ? hasDbtSemanticManifest(projectRoot, semanticConfig?.projectPath)
                 : false;
             res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
             res.end(serializeJSON({
@@ -2731,9 +3914,35 @@ export async function startLocalServer(opts) {
             res.end();
             return;
         }
-        if (req.method === 'POST' && path === '/api/query') {
+        if (req.method === 'POST' && path === '/api/ai/sql-draft/preview') {
             try {
                 const body = await readJSON(req);
+                if (typeof body.sql !== 'string' || body.sql.trim().length === 0) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Missing SQL in request body.' }));
+                    return;
+                }
+                const previewSql = buildAgentPreviewSql(body.sql);
+                const result = await executeLocalSqlForStoredResult(previewSql);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: true, result }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    ok: false,
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/query') {
+            let body;
+            let execContext = null;
+            const start = Date.now();
+            try {
+                body = await readJSON(req);
+                execContext = notebookExecutionContext(body.executionContext);
                 if (typeof body.sql !== 'string' || body.sql.trim().length === 0) {
                     res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ columns: [], rows: [], error: 'Missing SQL in request body.' }));
@@ -2756,7 +3965,26 @@ export async function startLocalServer(opts) {
                 const domain = typeof body.domain === 'string' ? body.domain : app?.domain;
                 assertAppAccess({ app, domain, level: 'execute' });
                 const result = await executor.executeQuery(prepared.sql, Array.isArray(body.sqlParams) ? body.sqlParams : [], runtimeVariables(body.variables && typeof body.variables === 'object' ? body.variables : {}), prepared.connection);
-                const payload = serializeJSON(normalizeQueryResult(result, semantic.semanticRefs));
+                const normalized = normalizeQueryResult(result, semantic.semanticRefs);
+                if (execContext) {
+                    recordNotebookQueryRun(projectRoot, {
+                        notebookPath: execContext.notebookPath,
+                        cellId: execContext.cellId,
+                        cellName: execContext.cellName,
+                        researchRunId: execContext.researchRunId,
+                        source: execContext.source ?? 'notebook_sql_cell',
+                        status: 'success',
+                        rowCount: normalized.rowCount ?? normalized.rows.length,
+                        durationMs: Date.now() - start,
+                        sql: body.sql,
+                    });
+                    updateNotebookResearchFromCellExecution(projectRoot, execContext, {
+                        status: 'success',
+                        resultPreview: normalized,
+                        sql: body.sql,
+                    });
+                }
+                const payload = serializeJSON(normalized);
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(payload);
             }
@@ -2775,6 +4003,24 @@ export async function startLocalServer(opts) {
                     }));
                     return;
                 }
+                if (execContext) {
+                    recordNotebookQueryRun(projectRoot, {
+                        notebookPath: execContext.notebookPath,
+                        cellId: execContext.cellId,
+                        cellName: execContext.cellName,
+                        researchRunId: execContext.researchRunId,
+                        source: execContext.source ?? 'notebook_sql_cell',
+                        status: 'error',
+                        durationMs: Date.now() - start,
+                        errorCode: error instanceof Error ? error.message : String(error),
+                        sql: typeof body?.sql === 'string' ? body.sql : undefined,
+                    });
+                    updateNotebookResearchFromCellExecution(projectRoot, execContext, {
+                        status: 'error',
+                        error: error instanceof Error ? error.message : String(error),
+                        sql: typeof body?.sql === 'string' ? body.sql : undefined,
+                    });
+                }
                 res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
                     columns: [],
@@ -3116,6 +4362,25 @@ export async function startLocalServer(opts) {
             }
             return;
         }
+        if (req.method === 'GET' && path.startsWith('/api/lineage/business-360/')) {
+            const rawNodeId = decodeURIComponent(path.slice('/api/lineage/business-360/'.length));
+            try {
+                const graph = buildProjectLineageGraph(projectRoot, semanticLayer);
+                const result = queryBusiness360(graph, rawNodeId);
+                if (!result) {
+                    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: `Lineage node "${rawNodeId}" not found` }));
+                    return;
+                }
+                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.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
         if (req.method === 'GET' && path.startsWith('/api/lineage/node/')) {
             const rawNodeId = decodeURIComponent(path.slice('/api/lineage/node/'.length));
             try {
@@ -3281,8 +4546,12 @@ export async function startLocalServer(opts) {
             return;
         }
         if (req.method === 'POST' && path === '/api/notebook/execute') {
+            let body;
+            let execContext = null;
+            const start = Date.now();
             try {
-                const body = await readJSON(req);
+                body = await readJSON(req);
+                execContext = notebookExecutionContext(body.executionContext);
                 const cell = normalizeNotebookCell(body.cell);
                 if (!cell) {
                     res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -3305,6 +4574,26 @@ export async function startLocalServer(opts) {
                 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), prepared.connection);
+                const normalized = normalizeQueryResult(rawResult);
+                if (execContext) {
+                    recordNotebookQueryRun(projectRoot, {
+                        notebookPath: execContext.notebookPath,
+                        cellId: execContext.cellId ?? cell.id,
+                        cellName: execContext.cellName ?? plan.title ?? resolved.blockName,
+                        researchRunId: execContext.researchRunId,
+                        source: execContext.source ?? (cell.type === 'dql' ? 'notebook_dql_cell' : 'notebook_cell'),
+                        status: 'success',
+                        rowCount: normalized.rowCount ?? normalized.rows.length,
+                        durationMs: Date.now() - start,
+                        sql: plan.sql,
+                        objectKey: resolved.blockPath,
+                    });
+                    updateNotebookResearchFromCellExecution(projectRoot, execContext, {
+                        status: 'success',
+                        resultPreview: normalized,
+                        sql: plan.sql,
+                    });
+                }
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
                     cellType: cell.type,
@@ -3313,10 +4602,26 @@ export async function startLocalServer(opts) {
                     blockPath: resolved.blockPath,
                     chartConfig: plan.chartConfig,
                     tests: plan.tests,
-                    result: normalizeQueryResult(rawResult),
+                    result: normalized,
                 }));
             }
             catch (error) {
+                if (execContext) {
+                    recordNotebookQueryRun(projectRoot, {
+                        notebookPath: execContext.notebookPath,
+                        cellId: execContext.cellId,
+                        cellName: execContext.cellName,
+                        researchRunId: execContext.researchRunId,
+                        source: execContext.source ?? 'notebook_cell',
+                        status: 'error',
+                        durationMs: Date.now() - start,
+                        errorCode: error instanceof Error ? error.message : String(error),
+                    });
+                    updateNotebookResearchFromCellExecution(projectRoot, execContext, {
+                        status: 'error',
+                        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) }));
             }
@@ -3845,6 +5150,245 @@ export function prepareLocalExecution(sql, connection, projectRoot, projectConfi
         connection: normalizedConnection,
     };
 }
+export function dashboardRuntimeVariables(dashboard, overrides = {}) {
+    const variables = {};
+    for (const param of dashboard.params ?? []) {
+        if (param.default !== undefined)
+            variables[param.id] = param.default;
+    }
+    for (const filter of dashboard.filters ?? []) {
+        if (filter.default !== undefined)
+            variables[filter.id] = filter.default;
+    }
+    return { ...variables, ...overrides };
+}
+export function applyDashboardFiltersToBlockExecution(input) {
+    const variables = { ...input.variables };
+    const sqlParams = [...input.sqlParams];
+    const appliedFilters = [];
+    const skippedFilters = [];
+    const clauses = [];
+    let nextPosition = sqlParams.reduce((max, param) => Math.max(max, param.position), 0);
+    for (const filter of input.dashboard.filters ?? []) {
+        const value = dashboardFilterValue(filter, variables);
+        if (isEmptyDashboardFilterValue(value)) {
+            skippedFilters.push({ filter: filter.id, reason: 'no value supplied' });
+            continue;
+        }
+        const paramNames = bindDashboardFilterToExistingParams(filter, value, input.block, sqlParams, variables);
+        if (paramNames.length > 0) {
+            appliedFilters.push({
+                filter: filter.id,
+                mode: 'parameter',
+                paramNames,
+            });
+            continue;
+        }
+        const binding = resolveDashboardFilterBinding(filter, input.block);
+        if (!binding) {
+            skippedFilters.push({ filter: filter.id, reason: `block "${input.block.name}" does not declare a compatible filter binding` });
+            continue;
+        }
+        const expression = dashboardFilterExpression(binding);
+        if (!expression) {
+            skippedFilters.push({ filter: filter.id, reason: `filter binding "${binding}" is not safe for runtime predicate injection` });
+            continue;
+        }
+        const predicate = buildDashboardFilterPredicate({
+            expression,
+            filterId: filter.id,
+            filterType: filter.type,
+            value,
+            params: sqlParams,
+            nextPosition: () => {
+                nextPosition += 1;
+                return nextPosition;
+            },
+            variables,
+        });
+        if (!predicate) {
+            skippedFilters.push({ filter: filter.id, reason: 'filter value could not be converted into a predicate' });
+            continue;
+        }
+        clauses.push(predicate);
+        appliedFilters.push({
+            filter: filter.id,
+            binding,
+            mode: 'predicate',
+            paramNames: sqlParams
+                .filter((param) => param.name.startsWith(`__dashboard_filter_${normalizeDashboardFilterName(filter.id)}_`))
+                .map((param) => param.name),
+        });
+    }
+    if (clauses.length === 0) {
+        return { sql: input.sql, sqlParams, variables, appliedFilters, skippedFilters };
+    }
+    return {
+        sql: `SELECT * FROM (${stripSqlTerminator(input.sql)}) _dql_filter WHERE ${clauses.join(' AND ')}`,
+        sqlParams,
+        variables,
+        appliedFilters,
+        skippedFilters,
+    };
+}
+function dashboardFilterValue(filter, variables) {
+    if (Object.prototype.hasOwnProperty.call(variables, filter.id))
+        return variables[filter.id];
+    if (filter.bindsTo && Object.prototype.hasOwnProperty.call(variables, filter.bindsTo))
+        return variables[filter.bindsTo];
+    return filter.default;
+}
+function isEmptyDashboardFilterValue(value) {
+    if (value === undefined || value === null)
+        return true;
+    if (typeof value === 'string' && value.trim() === '')
+        return true;
+    if (Array.isArray(value) && value.length === 0)
+        return true;
+    return false;
+}
+function bindDashboardFilterToExistingParams(filter, value, block, sqlParams, variables) {
+    const availableParamNames = new Set(sqlParams.map((param) => param.name));
+    const declaredParamNames = new Set((block.parameterPolicy ?? []).map((entry) => entry.name));
+    const applied = [];
+    const directCandidates = uniqueDashboardStrings([
+        filter.id,
+        filter.bindsTo ?? '',
+        normalizeDashboardFilterName(filter.id),
+        filter.bindsTo ? normalizeDashboardFilterName(filter.bindsTo) : '',
+    ]);
+    for (const name of directCandidates) {
+        if (!name || !availableParamNames.has(name))
+            continue;
+        variables[name] = value;
+        applied.push(name);
+    }
+    if (applied.length > 0)
+        return applied;
+    const range = dashboardRangeValue(value);
+    if (range) {
+        const baseNames = uniqueDashboardStrings([
+            filter.id,
+            filter.id.replace(/_?range$/i, ''),
+            filter.bindsTo ?? '',
+            filter.bindsTo ? filter.bindsTo.replace(/_?range$/i, '') : '',
+        ].map(normalizeDashboardFilterName));
+        for (const base of baseNames) {
+            const pairs = [
+                [`${base}_start`, `${base}_end`],
+                [`${base}_from`, `${base}_to`],
+                [`start_${base}`, `end_${base}`],
+            ];
+            for (const [startName, endName] of pairs) {
+                if (availableParamNames.has(startName) && availableParamNames.has(endName)) {
+                    variables[startName] = range.start;
+                    variables[endName] = range.end;
+                    return [startName, endName];
+                }
+            }
+        }
+        for (const [startName, endName] of [['start_date', 'end_date'], ['date_start', 'date_end'], ['season_start', 'season_end'], ['year_start', 'year_end']]) {
+            if (availableParamNames.has(startName) && availableParamNames.has(endName)) {
+                variables[startName] = range.start;
+                variables[endName] = range.end;
+                return [startName, endName];
+            }
+        }
+    }
+    for (const name of declaredParamNames) {
+        if (!availableParamNames.has(name))
+            continue;
+        const normalized = normalizeDashboardFilterName(name);
+        if (normalized === normalizeDashboardFilterName(filter.id) || normalized === normalizeDashboardFilterName(filter.bindsTo ?? '')) {
+            variables[name] = value;
+            return [name];
+        }
+    }
+    return [];
+}
+function resolveDashboardFilterBinding(filter, block) {
+    const candidates = uniqueDashboardStrings([filter.id, filter.bindsTo ?? '']).map(normalizeDashboardFilterName);
+    for (const entry of block.filterBindings ?? []) {
+        if (candidates.includes(normalizeDashboardFilterName(entry.filter)))
+            return entry.binding;
+    }
+    if (filter.bindsTo && (block.allowedFilters ?? []).some((item) => normalizeDashboardFilterName(item) === normalizeDashboardFilterName(filter.bindsTo ?? ''))) {
+        return filter.bindsTo;
+    }
+    if ((block.allowedFilters ?? []).some((item) => normalizeDashboardFilterName(item) === normalizeDashboardFilterName(filter.id))) {
+        return filter.id;
+    }
+    return null;
+}
+function dashboardFilterExpression(binding) {
+    const trimmed = binding.trim();
+    const yearMatch = trimmed.match(/^([A-Za-z_][A-Za-z0-9_.]*)\.year$/i);
+    if (yearMatch) {
+        const base = dashboardOutputColumn(yearMatch[1]);
+        return base ? `EXTRACT(YEAR FROM _dql_filter.${base})` : null;
+    }
+    const column = dashboardOutputColumn(trimmed);
+    return column ? `_dql_filter.${column}` : null;
+}
+function dashboardOutputColumn(binding) {
+    const cleaned = binding.replace(/[`"[\]]/g, '').trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_.]*$/.test(cleaned))
+        return null;
+    const column = cleaned.split('.').filter(Boolean).at(-1);
+    return column && /^[A-Za-z_][A-Za-z0-9_]*$/.test(column) ? column : null;
+}
+function buildDashboardFilterPredicate(input) {
+    const range = input.filterType === 'daterange' ? dashboardRangeValue(input.value) : null;
+    if (range) {
+        const start = addDashboardFilterParam(input, 'start', range.start);
+        const end = addDashboardFilterParam(input, 'end', range.end);
+        return `${input.expression} BETWEEN $${start.position} AND $${end.position}`;
+    }
+    const values = Array.isArray(input.value) ? input.value.filter((item) => !isEmptyDashboardFilterValue(item)) : [input.value];
+    if (values.length === 0)
+        return null;
+    if (values.length === 1) {
+        const param = addDashboardFilterParam(input, 'value', values[0]);
+        return `${input.expression} = $${param.position}`;
+    }
+    const placeholders = values.map((value, index) => {
+        const param = addDashboardFilterParam(input, `value_${index + 1}`, value);
+        return `$${param.position}`;
+    });
+    return `${input.expression} IN (${placeholders.join(', ')})`;
+}
+function addDashboardFilterParam(input, suffix, value) {
+    const name = `__dashboard_filter_${normalizeDashboardFilterName(input.filterId)}_${suffix}`;
+    const uniqueName = input.variables[name] === undefined && !input.params.some((param) => param.name === name)
+        ? name
+        : `${name}_${input.params.length + 1}`;
+    const param = { name: uniqueName, position: input.nextPosition() };
+    input.params.push(param);
+    input.variables[uniqueName] = value;
+    return param;
+}
+function dashboardRangeValue(value) {
+    if (Array.isArray(value) && value.length >= 2 && !isEmptyDashboardFilterValue(value[0]) && !isEmptyDashboardFilterValue(value[1])) {
+        return { start: value[0], end: value[1] };
+    }
+    if (value && typeof value === 'object') {
+        const record = value;
+        const start = record.start ?? record.from ?? record.min;
+        const end = record.end ?? record.to ?? record.max;
+        if (!isEmptyDashboardFilterValue(start) && !isEmptyDashboardFilterValue(end))
+            return { start, end };
+    }
+    return null;
+}
+function normalizeDashboardFilterName(value) {
+    return String(value ?? '').trim().toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+}
+function stripSqlTerminator(sql) {
+    return sql.trim().replace(/;\s*$/, '');
+}
+function uniqueDashboardStrings(values) {
+    return Array.from(new Set(values.map((value) => value.trim()).filter(Boolean)));
+}
 export function resolveDbtMacrosForExecution(sql, projectRoot, projectConfig = {}) {
     if (!/\{\{\s*(?:ref|source)\s*\(/i.test(sql))
         return sql;
@@ -4462,9 +6006,9 @@ function buildDatabaseSchemaTree(projectRoot, executor, connection) {
         return databaseNodes;
     })();
 }
-function openBlockStudioDocument(projectRoot, relativePath, semanticLayer) {
+export function openBlockStudioDocument(projectRoot, relativePath, semanticLayer) {
     const normalizedPath = normalize(relativePath).replace(/^\/+/, '');
-    if (!normalizedPath.startsWith('blocks/')) {
+    if (!isBlockStudioBlockPath(normalizedPath)) {
         throw new Error('Invalid block path');
     }
     const absPath = join(projectRoot, normalizedPath);
@@ -4479,7 +6023,7 @@ function openBlockStudioDocument(projectRoot, relativePath, semanticLayer) {
     const metadata = {
         name: parsedMetadata.name || companion?.name || fileName,
         path: normalizedPath,
-        domain: parsedMetadata.domain || companion?.domain || normalizedPath.split('/').slice(1, -1).join('/') || 'uncategorized',
+        domain: parsedMetadata.domain || companion?.domain || inferBlockStudioPathDomain(normalizedPath) || 'uncategorized',
         description: parsedMetadata.description || companion?.description || '',
         owner: parsedMetadata.owner || companion?.owner || '',
         tags: parsedMetadata.tags.length > 0 ? parsedMetadata.tags : companion?.tags ?? [],
@@ -4562,7 +6106,7 @@ export function buildSemanticTableMapping(semanticLayer, rows) {
     return Object.keys(tableMapping).length > 0 ? tableMapping : undefined;
 }
 function isDbtSemanticRuntime(projectConfig, detectedProvider, semanticLayer) {
-    if (projectConfig.semanticLayer?.provider === 'dbt' || detectedProvider === 'dbt')
+    if (projectConfig.semanticLayer?.provider === 'dbt' || projectConfig.dbt?.projectDir || detectedProvider === 'dbt')
         return true;
     return Boolean(semanticLayer?.listMetrics().some((metric) => metric.source?.provider === 'dbt'));
 }
@@ -4570,7 +6114,10 @@ function composeRuntimeSemanticQuery(request, semanticLayer, context) {
     const useMetricFlow = request.engine === 'metricflow' || (request.engine !== 'native' &&
         isDbtSemanticRuntime(context.projectConfig, context.detectedProvider, semanticLayer));
     if (useMetricFlow) {
-        const dbtProjectPath = context.projectConfig.semanticLayer?.projectPath;
+        const effectiveSemanticConfig = resolveProjectSemanticConfig(context.projectConfig, context.projectRoot);
+        const dbtProjectPath = effectiveSemanticConfig?.provider === 'dbt'
+            ? effectiveSemanticConfig.projectPath
+            : context.projectConfig.dbt?.projectDir;
         const compiled = compileMetricFlowQuery({
             projectRoot: context.projectRoot,
             dbtProjectPath,
@@ -4829,6 +6376,164 @@ export function validateBlockStudioSource(source, semanticLayer) {
         executableSql,
     };
 }
+export async function createDqlGenerationSessionForProject(projectRoot, options, semanticLayer) {
+    const deterministicOnly = isDeterministicDqlGenerationProvider(options.provider);
+    const requestedProvider = !deterministicOnly && isProviderSettingsId(options.provider) ? options.provider : undefined;
+    const provider = deterministicOnly ? null : await createBlockStudioAssistProvider(projectRoot, requestedProvider);
+    const session = createBlockStudioImportSession(projectRoot, {
+        inputPath: options.inputPath ?? '',
+        inputMode: options.inputMode,
+        sources: options.sources,
+        sourceKind: options.sourceKind ?? 'raw-sql',
+        domain: options.domain,
+        owner: options.owner,
+        tags: options.tags,
+    });
+    const warnings = [];
+    const nextCandidates = [];
+    let contextObjectCount = 0;
+    for (const candidate of session.candidates) {
+        const contextPack = await buildDqlGenerationContextPack(projectRoot, candidate).catch((error) => {
+            warnings.push(`Context pack failed for ${candidate.name}: ${error instanceof Error ? error.message : String(error)}`);
+            return null;
+        });
+        contextObjectCount += contextPack?.objects.length ?? 0;
+        const evidence = contextPack ? dqlGenerationEvidenceFromContext(contextPack, candidate) : deterministicDqlGenerationEvidence(candidate);
+        let patch = deterministicDqlGenerationPatch(candidate, evidence);
+        let generatorName = 'local-deterministic';
+        let generationMode = 'deterministic';
+        if (provider) {
+            const aiPatch = await buildAiDqlGenerationPatch(provider, candidate, evidence, contextPack).catch((error) => {
+                warnings.push(`AI generation fell back for ${candidate.name}: ${error instanceof Error ? error.message : String(error)}`);
+                return null;
+            });
+            if (aiPatch) {
+                patch = mergeDqlGenerationPatch(patch, aiPatch, candidate, evidence);
+                generatorName = provider.name;
+                generationMode = 'ai';
+            }
+        }
+        const similarity = buildDqlGenerationSimilarityMatches(candidate, patch, contextPack);
+        patch = {
+            ...patch,
+            similarityMatches: similarity.matches,
+            recommendedAction: similarity.recommendedAction,
+        };
+        for (const warning of patch.warnings ?? [])
+            warnings.push(`${candidate.name}: ${warning}`);
+        const enriched = updateBlockStudioImportCandidate(projectRoot, session.id, candidate.id, {
+            name: patch.name,
+            domain: patch.domain,
+            description: patch.description,
+            owner: patch.owner,
+            tags: patch.tags,
+            terms: patch.terms,
+            pattern: patch.pattern,
+            grain: patch.grain,
+            entities: patch.entities,
+            outputs: patch.outputs,
+            dimensions: patch.dimensions,
+            allowedFilters: patch.allowedFilters,
+            parameterPolicy: patch.parameterPolicy,
+            filterBindings: patch.filterBindings,
+            parameterDecisions: patch.parameterDecisions,
+            similarityMatches: patch.similarityMatches,
+            recommendedAction: patch.recommendedAction,
+            sourceSystems: patch.sourceSystems,
+            replacementFor: patch.replacementFor,
+            reviewCadence: patch.reviewCadence,
+            sql: patch.sql,
+            llmContext: patch.llmContext,
+            evidence,
+            conversionNotes: dqlGenerationConversionNotes(generatorName),
+            generationMode,
+            generationProvider: generatorName,
+        });
+        const validated = {
+            ...enriched,
+            validation: validateBlockStudioSource(enriched.dqlSource, semanticLayer),
+        };
+        const savedDraft = saveDqlGenerationDraftForProject(projectRoot, session.id, validated);
+        writeBlockStudioImportCandidate(projectRoot, session.id, savedDraft);
+        nextCandidates.push(savedDraft);
+    }
+    const generationSession = {
+        ...session,
+        mode: 'ai-import',
+        candidates: nextCandidates,
+        updatedAt: new Date().toISOString(),
+        generation: {
+            provider: nextCandidates.find((candidate) => candidate.generationMode === 'ai')?.generationProvider ?? 'local-deterministic',
+            aiEnabled: nextCandidates.some((candidate) => candidate.generationMode === 'ai'),
+            contextObjectCount,
+            createdDrafts: nextCandidates.filter((candidate) => candidate.draftSave.status === 'saved').length,
+            warnings,
+        },
+    };
+    writeBlockStudioImportSession(projectRoot, generationSession);
+    if (generationSession.generation.createdDrafts > 0)
+        await refreshLocalMetadataCatalog(projectRoot);
+    return generationSession;
+}
+function saveDqlGenerationDraftForProject(projectRoot, importId, candidate) {
+    if (candidate.recommendedAction === 'reuse_existing') {
+        const topMatch = candidate.similarityMatches?.[0];
+        return {
+            ...candidate,
+            reviewStatus: 'review',
+            draftSave: {
+                status: 'skipped',
+                reason: topMatch
+                    ? `Reuse recommended: ${topMatch.name} (${topMatch.kind}, ${(topMatch.score * 100).toFixed(0)}%).`
+                    : 'Reuse recommended; no new draft block was needed.',
+            },
+            generationMode: candidate.generationMode ?? 'deterministic',
+            generationProvider: candidate.generationProvider ?? 'local-deterministic',
+            llmContext: candidate.llmContext ?? deterministicDqlGenerationContext(candidate, candidate.evidence ?? []),
+            evidence: candidate.evidence ?? [],
+        };
+    }
+    try {
+        const savedPath = saveBlockStudioDraftArtifacts(projectRoot, {
+            currentPath: isDraftBlockPath(candidate.savedPath) ? candidate.savedPath : undefined,
+            source: candidate.dqlSource,
+            name: candidate.name,
+            domain: candidate.domain,
+            description: candidate.description,
+            owner: candidate.owner,
+            tags: candidate.tags,
+            lineage: candidate.lineage.sourceTables,
+            stableSuffix: candidate.id.replace(/^cand_/, ''),
+            importMeta: {
+                importId,
+                candidateId: candidate.id,
+                sourceKind: candidate.sourceKind,
+                sourcePath: candidate.sourcePath,
+            },
+        });
+        const draftSave = { status: 'saved', path: savedPath, savedAt: new Date().toISOString() };
+        return {
+            ...candidate,
+            reviewStatus: candidate.reviewStatus === 'rejected' ? 'rejected' : 'draft',
+            savedPath,
+            draftSave,
+            generationMode: candidate.generationMode ?? 'deterministic',
+            generationProvider: candidate.generationProvider ?? 'local-deterministic',
+            llmContext: candidate.llmContext ?? deterministicDqlGenerationContext(candidate, candidate.evidence ?? []),
+            evidence: candidate.evidence ?? [],
+        };
+    }
+    catch (error) {
+        return {
+            ...candidate,
+            draftSave: { status: 'error', error: error instanceof Error ? error.message : String(error) },
+            generationMode: candidate.generationMode ?? 'deterministic',
+            generationProvider: candidate.generationProvider ?? 'local-deterministic',
+            llmContext: candidate.llmContext ?? deterministicDqlGenerationContext(candidate, candidate.evidence ?? []),
+            evidence: candidate.evidence ?? [],
+        };
+    }
+}
 export function saveBlockStudioArtifacts(projectRoot, options) {
     const slug = options.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'block';
     const safeDomain = (options.domain ?? '')
@@ -4836,9 +6541,9 @@ export function saveBlockStudioArtifacts(projectRoot, options) {
         .toLowerCase()
         .replace(/[^a-z0-9/_-]+/g, '-')
         .replace(/^\/+|\/+$/g, '') || 'uncategorized';
-    const targetRelativePath = `blocks/${safeDomain}/${slug}.dql`;
-    const targetPath = join(projectRoot, targetRelativePath);
     const previousPath = options.currentPath ? normalize(options.currentPath).replace(/^\/+/, '') : null;
+    const targetRelativePath = canonicalBlockRelativePath(projectRoot, safeDomain, slug, previousPath);
+    const targetPath = join(projectRoot, targetRelativePath);
     if (existsSync(targetPath) && previousPath !== targetRelativePath) {
         throw new Error('BLOCK_EXISTS');
     }
@@ -4869,12 +6574,103 @@ export function saveBlockStudioArtifacts(projectRoot, options) {
     }
     return targetRelativePath;
 }
+export function saveBlockStudioDraftArtifacts(projectRoot, options) {
+    const slug = options.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'block';
+    const safeDomain = (options.domain ?? '')
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9/_-]+/g, '-')
+        .replace(/^\/+|\/+$/g, '') || 'uncategorized';
+    const previousPath = options.currentPath ? normalize(options.currentPath).replace(/^\/+/, '') : null;
+    const domainFirstRoot = join(projectRoot, 'domains');
+    const useDomainFirstDrafts = existsSync(domainFirstRoot);
+    const draftPrefix = useDomainFirstDrafts
+        ? `domains/${safeDomain}/blocks/_drafts/`
+        : `blocks/_drafts/${safeDomain}/`;
+    const stableSuffix = options.stableSuffix?.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 18);
+    let targetRelativePath = previousPath && isDraftBlockPath(previousPath)
+        ? previousPath
+        : `${draftPrefix}${slug}${stableSuffix ? `-${stableSuffix}` : ''}.dql`;
+    let targetPath = join(projectRoot, targetRelativePath);
+    if (!previousPath && existsSync(targetPath)) {
+        for (let index = 2; index < 1000; index += 1) {
+            const candidatePath = `${draftPrefix}${slug}-${index}.dql`;
+            if (!existsSync(join(projectRoot, candidatePath))) {
+                targetRelativePath = candidatePath;
+                targetPath = join(projectRoot, targetRelativePath);
+                break;
+            }
+        }
+    }
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, options.source.trimEnd() + '\n', 'utf-8');
+    const companionSlug = targetRelativePath.split('/').pop()?.replace(/\.dql$/, '') || slug;
+    writeBlockCompanionFile(projectRoot, {
+        slug: companionSlug,
+        name: options.name,
+        domain: `_drafts/${safeDomain}`,
+        description: options.description,
+        owner: options.owner,
+        tags: options.tags,
+        provider: 'dql',
+        content: options.source,
+        lineage: options.lineage,
+        importMeta: options.importMeta,
+    });
+    return targetRelativePath;
+}
+function canonicalBlockRelativePath(projectRoot, safeDomain, slug, previousPath) {
+    const previousDomainFirst = previousPath?.match(/^domains\/([^/]+)\/blocks\/(?:_drafts\/)?[^/]+\.dql$/);
+    if (previousDomainFirst) {
+        return `domains/${previousDomainFirst[1]}/blocks/${slug}.dql`;
+    }
+    if (existsSync(join(projectRoot, 'domains', safeDomain))) {
+        return `domains/${safeDomain}/blocks/${slug}.dql`;
+    }
+    return `blocks/${safeDomain}/${slug}.dql`;
+}
+function isDraftBlockPath(value) {
+    if (!value)
+        return false;
+    const normalized = normalize(value).replace(/^\/+/, '');
+    return normalized.startsWith('blocks/_drafts/') || /^domains\/[^/]+\/blocks\/_drafts\//.test(normalized);
+}
+function isBlockStudioBlockPath(value) {
+    if (!value)
+        return false;
+    const normalized = normalize(value).replace(/^\/+/, '');
+    return normalized.startsWith('blocks/') || /^domains\/[^/]+\/blocks\//.test(normalized);
+}
+function inferBlockStudioPathDomain(blockPath) {
+    const normalized = normalize(blockPath).replace(/^\/+/, '');
+    if (normalized.startsWith('blocks/')) {
+        return normalized.split('/').slice(1, -1).join('/');
+    }
+    const domainFirst = normalized.match(/^domains\/([^/]+)\/blocks\/(.+)$/);
+    if (!domainFirst)
+        return '';
+    const domain = domainFirst[1];
+    const blockSubpath = domainFirst[2];
+    if (blockSubpath.startsWith('_drafts/'))
+        return `_drafts/${domain}`;
+    return domain;
+}
 function blockCompanionRelativePath(blockPath) {
     const normalized = normalize(blockPath).replace(/^\/+/, '');
-    if (!normalized.startsWith('blocks/'))
-        return null;
-    const withoutRoot = normalized.slice('blocks/'.length).replace(/\.dql$/, '.yaml');
-    return join('semantic-layer', 'blocks', withoutRoot).replaceAll('\\', '/');
+    if (normalized.startsWith('blocks/')) {
+        const withoutRoot = normalized.slice('blocks/'.length).replace(/\.dql$/, '.yaml');
+        return join('semantic-layer', 'blocks', withoutRoot).replaceAll('\\', '/');
+    }
+    const domainFirst = normalized.match(/^domains\/([^/]+)\/blocks\/(.+)\.dql$/);
+    if (domainFirst) {
+        const domain = domainFirst[1];
+        const blockPath = domainFirst[2];
+        const companionBlockPath = blockPath.startsWith('_drafts/')
+            ? join('_drafts', domain, blockPath.slice('_drafts/'.length))
+            : join(domain, blockPath);
+        return join('semantic-layer', 'blocks', `${companionBlockPath}.yaml`).replaceAll('\\', '/');
+    }
+    return null;
 }
 function readBlockCompanionFile(projectRoot, relativePath) {
     const absPath = join(projectRoot, relativePath);
@@ -4922,18 +6718,48 @@ function readBlockCompanionFile(projectRoot, relativePath) {
         return null;
     }
 }
-function parseBlockSourceMetadata(source) {
+export function parseBlockSourceMetadata(source) {
     const name = source.match(/^\s*block\s+"([^"]+)"/i)?.[1] ?? '';
     const extractString = (key) => source.match(new RegExp(`\\b${key}\\s*=\\s*"([^"]*)"`, 'i'))?.[1] ?? '';
-    const tags = source.match(/\btags\s*=\s*\[([^\]]*)\]/i);
+    const extractStringArray = (key) => {
+        const match = source.match(new RegExp(`\\b${key}\\s*=\\s*\\[([^\\]]*)\\]`, 'i'));
+        return match ? (match[1].match(/"([^"]*)"/g) ?? []).map((value) => value.slice(1, -1)) : [];
+    };
+    const extractStringMapSection = (key) => {
+        const match = source.match(new RegExp(`\\b${key}\\s*\\{([\\s\\S]*?)\\n\\s*\\}`, 'i'));
+        if (!match)
+            return [];
+        return match[1]
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .map((line) => line.match(/^([A-Za-z_][\w.]*)\s*=\s*"([^"]*)"\s*$/))
+            .filter((entry) => Boolean(entry))
+            .map((entry) => ({ key: entry[1], value: entry[2] }));
+    };
+    const parameterPolicy = extractStringMapSection('parameterPolicy')
+        .map((entry) => ({ name: entry.key, policy: entry.value }));
+    const filterBindings = extractStringMapSection('filterBindings')
+        .map((entry) => ({ filter: entry.key, binding: entry.value }));
     return {
         name,
         domain: extractString('domain'),
         description: extractString('description'),
         owner: extractString('owner'),
-        tags: tags ? (tags[1].match(/"([^"]*)"/g) ?? []).map((value) => value.slice(1, -1)) : [],
+        tags: extractStringArray('tags'),
         status: extractString('status') || 'draft',
         blockType: extractString('type') || 'custom',
+        llmContext: extractString('llmContext'),
+        pattern: extractString('pattern'),
+        grain: extractString('grain'),
+        entities: extractStringArray('entities'),
+        outputs: extractStringArray('outputs'),
+        dimensions: extractStringArray('dimensions'),
+        allowedFilters: extractStringArray('allowedFilters'),
+        parameterPolicy,
+        filterBindings,
+        sourceSystems: extractStringArray('sourceSystems'),
+        replacementFor: extractStringArray('replacementFor'),
+        reviewCadence: extractString('reviewCadence'),
     };
 }
 function compareBlockStudioValues(actual, operator, expected) {
@@ -4990,58 +6816,948 @@ function buildBlockStudioCertificationChecklist(input) {
     if (!input.validation.chartConfig?.chart)
         blockers.add('Visualization config is missing');
     return {
-        metadata: Boolean(parsed.domain.trim() && parsed.owner.trim() && parsed.description.trim()),
-        validation: input.validation.diagnostics.every((diagnostic) => diagnostic.severity !== 'error'),
-        run: input.previewSucceeded,
-        tests: Boolean(input.testResults && input.testResults.failed === 0 && input.testResults.assertions.length > 0),
-        chart: Boolean(input.validation.chartConfig?.chart),
-        lineage: extractSqlTablesLight(sql).length > 0 || input.validation.semanticRefs.metrics.length > 0,
-        aiReviewed: true,
-        blockers: Array.from(blockers),
-        checkedAt: new Date().toISOString(),
+        metadata: Boolean(parsed.domain.trim() && parsed.owner.trim() && parsed.description.trim()),
+        validation: input.validation.diagnostics.every((diagnostic) => diagnostic.severity !== 'error'),
+        run: input.previewSucceeded,
+        tests: Boolean(input.testResults && input.testResults.failed === 0 && input.testResults.assertions.length > 0),
+        chart: Boolean(input.validation.chartConfig?.chart),
+        lineage: extractSqlTablesLight(sql).length > 0 || input.validation.semanticRefs.metrics.length > 0,
+        aiReviewed: true,
+        blockers: Array.from(blockers),
+        checkedAt: new Date().toISOString(),
+    };
+}
+function extractSqlTablesLight(sql) {
+    const tables = new Set();
+    const cleaned = sql
+        .replace(/\/\*[\s\S]*?\*\//g, ' ')
+        .replace(/--[^\n\r]*/g, ' ')
+        .replace(/extract\s*\(\s*\w+\s+from\s+[^)]+\)/gi, 'EXTRACT_VALUE');
+    const regex = /\b(?:from|join|update|into)\s+([`"[]?[A-Za-z0-9_./:-]+(?:\.[A-Za-z0-9_./:-]+)*[`"\]]?)/gi;
+    let match;
+    while ((match = regex.exec(cleaned))) {
+        const raw = match[1].replace(/^[`"[]|[`"\]]$/g, '');
+        if (raw && !raw.startsWith('(') && !/^(select|values|unnest|lateral)$/i.test(raw))
+            tables.add(raw);
+    }
+    return Array.from(tables);
+}
+function setBlockStudioStatusInSource(source, newStatus) {
+    if (/status\s*=\s*"[^"]*"/.test(source)) {
+        return source.replace(/status\s*=\s*"[^"]*"/, `status = "${newStatus}"`);
+    }
+    return source.replace(/block\s+"[^"]*"\s*\{/, (match) => `${match}\n  status = "${newStatus}"`);
+}
+export function setBlockStudioStatus(projectRoot, blockPath, newStatus) {
+    const normalizedPath = normalize(blockPath).replace(/^\/+/, '');
+    if (!isBlockStudioBlockPath(normalizedPath))
+        throw new Error('Invalid block path');
+    const absPath = join(projectRoot, normalizedPath);
+    if (!existsSync(absPath))
+        throw new Error('Block file not found');
+    const source = setBlockStudioStatusInSource(readFileSync(absPath, 'utf-8'), newStatus);
+    writeFileSync(absPath, source, 'utf-8');
+    const companionPath = blockCompanionRelativePath(normalizedPath);
+    if (!companionPath)
+        return;
+    const absCompanionPath = join(projectRoot, companionPath);
+    if (!existsSync(absCompanionPath))
+        return;
+    let companion = readFileSync(absCompanionPath, 'utf-8');
+    if (/^reviewStatus:\s*.+$/m.test(companion)) {
+        companion = companion.replace(/^reviewStatus:\s*.+$/m, `reviewStatus: ${newStatus}`);
+    }
+    else {
+        companion = `${companion.trimEnd()}\nreviewStatus: ${newStatus}\n`;
+    }
+    writeFileSync(absCompanionPath, companion, 'utf-8');
+}
+async function buildDqlGenerationContextPack(projectRoot, candidate) {
+    const tables = candidate.lineage.sourceTables.join(', ');
+    const question = [
+        `Generate a governed DQL block draft for SQL import candidate "${candidate.name}".`,
+        candidate.description,
+        tables ? `Source tables: ${tables}.` : '',
+        candidate.sql.slice(0, 1200),
+    ].filter(Boolean).join('\n');
+    return buildLocalContextPack(projectRoot, {
+        question,
+        mode: 'build',
+        surface: 'block-studio',
+        limit: 80,
+        objectTypes: [
+            'dql_block',
+            'dql_term',
+            'business_view',
+            'domain',
+            'semantic_metric',
+            'semantic_model',
+            'semantic_dimension',
+            'semantic_measure',
+            'dbt_model',
+            'dbt_source',
+            'dbt_column',
+            'warehouse_table',
+            'datalex_domain',
+            'datalex_entity',
+            'datalex_contract',
+            'datalex_term',
+        ],
+        strictness: 'balanced',
+    });
+}
+function dqlGenerationEvidenceFromContext(contextPack, candidate) {
+    const directEvidence = contextPack.objects
+        .filter((object) => isDqlGenerationEvidenceObject(object))
+        .filter((object) => metadataObjectMatchesImportedSource(object, candidate.lineage.sourceTables))
+        .map((object) => metadataObjectToDqlGenerationEvidence(object, 'Directly matches an imported SQL source table.'));
+    const selected = contextPack.retrievalDiagnostics.selectedEvidence.slice(0, 12);
+    const byKey = new Map(contextPack.objects.map((object) => [object.objectKey, object]));
+    const evidence = selected.flatMap((item) => {
+        const object = byKey.get(item.objectKey);
+        if (!object || !isDqlGenerationEvidenceObject(object))
+            return [];
+        return [metadataObjectToDqlGenerationEvidence(object, item.reason, Math.max(0.35, Math.min(0.98, item.score / Math.max(item.score, 10))))];
+    });
+    const ranked = uniqueDqlGenerationEvidence([...directEvidence, ...evidence]).slice(0, 12);
+    return ranked.length > 0 ? ranked : deterministicDqlGenerationEvidence(candidate);
+}
+function deterministicDqlGenerationEvidence(candidate) {
+    return candidate.lineage.sourceTables.map((table) => ({
+        kind: 'warehouse_table',
+        name: table,
+        source: candidate.sourcePath,
+        reason: 'Detected in the imported SQL source.',
+        confidence: 0.7,
+    }));
+}
+function isDqlGenerationEvidenceObject(object) {
+    if (object.objectType === 'dql_block') {
+        if (object.status !== 'certified')
+            return false;
+        if (object.sourcePath?.includes('/_drafts/') || object.sourcePath?.includes('\\_drafts\\'))
+            return false;
+    }
+    return true;
+}
+function metadataObjectToDqlGenerationEvidence(object, reason, confidence = 0.82) {
+    return {
+        kind: dqlGenerationEvidenceKind(object.objectType),
+        name: object.fullName ?? object.name,
+        description: object.description,
+        objectKey: object.objectKey,
+        source: object.sourcePath ?? object.sourceSystem,
+        reason,
+        confidence,
+    };
+}
+function metadataObjectMatchesImportedSource(object, sourceTables) {
+    if (sourceTables.length === 0)
+        return false;
+    const haystack = [
+        object.fullName,
+        object.name,
+        object.objectKey,
+        object.sourcePath,
+        object.sourceSystem,
+        typeof object.payload?.relation === 'string' ? object.payload.relation : '',
+        typeof object.payload?.relationName === 'string' ? object.payload.relationName : '',
+        typeof object.payload?.relation_name === 'string' ? object.payload.relation_name : '',
+    ].filter(Boolean).join(' ').toLowerCase();
+    return sourceTables.some((table) => relationLookupTokens(table).some((token) => token && haystack.includes(token)));
+}
+function relationLookupTokens(relation) {
+    const normalized = relation.replace(/[`"[\]]/g, '').toLowerCase();
+    const parts = normalized.split('.').filter(Boolean);
+    return Array.from(new Set([
+        normalized,
+        parts.slice(-2).join('.'),
+        parts.at(-1) ?? '',
+    ].filter((item) => item.length >= 3)));
+}
+function uniqueDqlGenerationEvidence(evidence) {
+    const seen = new Set();
+    const result = [];
+    for (const item of evidence) {
+        const key = item.objectKey || `${item.kind}:${item.name}`.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(item);
+    }
+    return result;
+}
+function dqlGenerationEvidenceKind(objectType) {
+    if (objectType === 'dql_block')
+        return 'dql_block';
+    if (objectType === 'dql_term')
+        return 'dql_term';
+    if (objectType === 'business_view')
+        return 'business_view';
+    if (objectType === 'domain')
+        return 'domain';
+    if (objectType === 'semantic_metric')
+        return 'semantic_metric';
+    if (objectType === 'semantic_model')
+        return 'semantic_model';
+    if (objectType === 'dbt_model' || objectType === 'dbt_source' || objectType === 'dbt_column')
+        return 'dbt_model';
+    if (objectType === 'warehouse_table')
+        return 'warehouse_table';
+    if (objectType === 'datalex_contract')
+        return 'datalex_contract';
+    if (objectType === 'datalex_entity')
+        return 'datalex_entity';
+    if (objectType === 'datalex_domain')
+        return 'datalex_domain';
+    if (objectType === 'datalex_term')
+        return 'datalex_term';
+    if (objectType.includes('lineage'))
+        return 'lineage';
+    return 'metadata';
+}
+function deterministicDqlGenerationPatch(candidate, evidence) {
+    const domain = inferDqlGenerationDomain(candidate);
+    const parameterized = parameterizeSqlForDqlImport(candidate.sql);
+    const grain = extractDqlGenerationGroupByFields(parameterized.sql)[0];
+    const outputs = extractDqlGenerationSelectOutputs(parameterized.sql);
+    const sourceSystems = candidate.lineage.sourceTables.map((table) => table.split('.').filter(Boolean).slice(-2, -1)[0] ?? '').filter(Boolean);
+    const description = candidate.description && !candidate.description.startsWith('Imported from ')
+        ? candidate.description
+        : deterministicDqlGenerationDescription(candidate, evidence);
+    const allowedFilters = Array.from(new Set([
+        ...parameterized.allowedFilters,
+        ...extractDqlGenerationFilterFields(parameterized.sql),
+    ])).slice(0, 16);
+    return {
+        name: candidate.name,
+        domain,
+        description,
+        owner: candidate.owner,
+        tags: dqlGenerationBusinessTags(candidate, evidence, domain),
+        terms: inferDqlGenerationTerms(evidence),
+        llmContext: deterministicDqlGenerationContext({ ...candidate, sql: parameterized.sql }, evidence),
+        pattern: inferDqlGenerationPattern(parameterized.sql),
+        grain,
+        entities: inferDqlGenerationEntities({
+            grain,
+            outputs,
+            sourceTables: candidate.lineage.sourceTables,
+            evidence,
+        }),
+        outputs,
+        dimensions: extractDqlGenerationDimensions(parameterized.sql, grain, outputs),
+        allowedFilters,
+        parameterPolicy: parameterized.parameterPolicy,
+        filterBindings: parameterized.filterBindings,
+        parameterDecisions: parameterized.parameterDecisions,
+        sql: parameterized.sql,
+        warnings: parameterized.warnings,
+        sourceSystems,
+        reviewCadence: 'monthly',
+    };
+}
+function inferDqlGenerationTerms(evidence) {
+    return Array.from(new Set(evidence
+        .filter((item) => item.kind === 'dql_term' || item.kind === 'datalex_term')
+        .map((item) => item.name.trim())
+        .filter(Boolean))).slice(0, 16);
+}
+function deterministicDqlGenerationDescription(candidate, evidence) {
+    const tables = candidate.lineage.sourceTables.length > 0
+        ? candidate.lineage.sourceTables.join(', ')
+        : candidate.sourcePath;
+    const sourceContext = evidence.find((item) => (item.kind === 'dbt_model' || item.kind === 'semantic_model' || item.kind === 'warehouse_table') &&
+        item.description &&
+        candidate.lineage.sourceTables.some((table) => relationLookupTokens(table).some((token) => item.name.toLowerCase().includes(token))));
+    const aggregate = /\b(sum|count|avg|min|max)\s*\(/i.test(candidate.sql);
+    const grouped = /\bgroup\s+by\b/i.test(candidate.sql);
+    const sourcePhrase = sourceContext?.description
+        ? ` using ${sourceContext.name} (${sourceContext.description})`
+        : ` using ${tables}`;
+    if (aggregate && grouped)
+        return `Summarizes imported SQL${sourcePhrase}.`;
+    if (aggregate)
+        return `Calculates aggregate values${sourcePhrase}.`;
+    return `Exposes imported SQL${sourcePhrase}.`;
+}
+function dqlGenerationBusinessTags(candidate, evidence, domain) {
+    const generic = new Set(['imported', 'raw-sql', 'ai-generated']);
+    const stopTags = new Set(['int', 'stg', 'src', 'fct', 'dim', 'name', 'id', 'key', 'model', 'source', 'table']);
+    const sourceTokens = candidate.lineage.sourceTables
+        .flatMap((table) => table.split('.').slice(-2))
+        .flatMap((part) => part.split(/[_\s.-]+/));
+    const tags = [
+        ...candidate.tags.filter((tag) => !generic.has(tag)),
+        domain,
+        ...sourceTokens,
+        'review-required',
+    ].map((tag) => tag.trim().toLowerCase())
+        .filter((tag) => tag.length > 1 && !generic.has(tag) && !stopTags.has(tag))
+        .map((tag) => tag.replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, ''))
+        .filter(Boolean);
+    return Array.from(new Set(tags)).slice(0, 12);
+}
+function deterministicDqlGenerationContext(candidate, evidence) {
+    const tables = candidate.lineage.sourceTables.length > 0
+        ? candidate.lineage.sourceTables.join(', ')
+        : 'the imported SQL source';
+    const evidenceNames = evidence
+        .filter((item) => item.kind !== 'dql_block')
+        .slice(0, 3)
+        .map((item) => item.name)
+        .filter(Boolean);
+    const grain = extractDqlGenerationGroupByFields(candidate.sql);
+    const years = extractDqlGenerationYearFilters(candidate.sql);
+    return [
+        `Use after review for questions matching "${candidate.name}".`,
+        grain.length > 0 ? `Grain: ${grain.join(', ')}.` : '',
+        years.length > 0 ? `Filters: year ${years.join(', ')}.` : '',
+        `Source: ${tables}.`,
+        evidenceNames.length > 0 ? `Grounded by: ${evidenceNames.join(', ')}.` : '',
+        'Certification must confirm grain, filters, owner, tags, and tests.',
+    ].filter(Boolean).join(' ');
+}
+function extractDqlGenerationGroupByFields(sql) {
+    const match = sql.match(/\bgroup\s+by\b([\s\S]+?)(?:\border\s+by\b|\blimit\b|\bqualify\b|\bhaving\b|$)/i);
+    if (!match)
+        return [];
+    return splitDqlGenerationSqlList(match[1])
+        .map((item) => item.replace(/[`"[\]]/g, '').trim())
+        .filter((item) => item && !/^\d+$/.test(item))
+        .slice(0, 4);
+}
+function extractDqlGenerationSelectOutputs(sql) {
+    const selectMatch = sql.match(/\bselect\b([\s\S]+?)\bfrom\b/i);
+    if (!selectMatch)
+        return [];
+    return splitDqlGenerationSqlList(selectMatch[1])
+        .map((expr) => {
+        const alias = expr.match(/\bas\s+([A-Za-z_][A-Za-z0-9_]*)\b/i)?.[1]
+            ?? expr.match(/([A-Za-z_][A-Za-z0-9_]*)\s*$/)?.[1]
+            ?? '';
+        return alias.replace(/[`"[\]]/g, '');
+    })
+        .filter(Boolean)
+        .filter((name) => !/^(from|where|group|order|limit)$/i.test(name))
+        .slice(0, 24);
+}
+function extractDqlGenerationDimensions(sql, grain, outputs) {
+    const outputSet = new Set(outputs.map(normalizedTerm));
+    return extractDqlGenerationGroupByFields(sql)
+        .map((field) => field.split('.').pop() ?? field)
+        .filter((field) => normalizedTerm(field) !== normalizedTerm(grain ?? ''))
+        .filter((field) => !outputSet.has(normalizedTerm(field)))
+        .filter((field) => !/\b(total|count|sum|avg|average|min|max|rate|pct|percent|amount|revenue|points?|score)\b/i.test(field))
+        .slice(0, 16);
+}
+function inferDqlGenerationEntities(input) {
+    const entities = new Set();
+    const add = (value) => {
+        const entity = businessEntityFromDqlGenerationIdentifier(value ?? '');
+        if (entity)
+            entities.add(entity);
+    };
+    add(input.grain);
+    for (const output of input.outputs)
+        add(output);
+    for (const table of input.sourceTables)
+        add(table.split('.').pop());
+    for (const item of input.evidence.slice(0, 12)) {
+        if (item.kind === 'datalex_entity' || item.kind === 'semantic_model' || item.kind === 'dbt_model' || item.kind === 'warehouse_table') {
+            add(item.name.split('.').pop());
+        }
+    }
+    return [...entities].slice(0, 8);
+}
+function businessEntityFromDqlGenerationIdentifier(value) {
+    const raw = value
+        .split('.').pop()
+        ?.trim()
+        .replace(/[`"[\]]/g, '')
+        .replace(/^(dim|fact|fct|stg|src|int)_/i, '')
+        .replace(/_(id|key|name|code|uuid|number|num|abbreviation|abbr)$/i, '')
+        .replace(/s$/i, '') ?? '';
+    if (!raw)
+        return '';
+    const tokens = raw
+        .split(/[^A-Za-z0-9]+/)
+        .map((token) => token.trim().toLowerCase())
+        .filter(Boolean)
+        .filter((token) => !isGenericDqlGenerationEntityToken(token));
+    if (tokens.length === 0)
+        return '';
+    return titleizeDqlGenerationName(tokens.join(' '));
+}
+function isGenericDqlGenerationEntityToken(token) {
+    return new Set([
+        'total',
+        'count',
+        'sum',
+        'avg',
+        'average',
+        'min',
+        'max',
+        'metric',
+        'measure',
+        'value',
+        'amount',
+        'revenue',
+        'point',
+        'points',
+        'score',
+        'date',
+        'day',
+        'week',
+        'month',
+        'quarter',
+        'year',
+        'season',
+        'period',
+        'time',
+        'row',
+        'record',
+        'detail',
+        'stat',
+        'stats',
+        'analytic',
+        'analytics',
+        'transformed',
+    ]).has(token);
+}
+function titleizeDqlGenerationName(value) {
+    return value
+        .replace(/[_-]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .replace(/\b\w/g, (char) => char.toUpperCase());
+}
+function inferDqlGenerationPattern(sql) {
+    const groupFields = extractDqlGenerationGroupByFields(sql);
+    if (/@metric\s*\(/i.test(sql))
+        return 'metric_wrapper';
+    if (/\bjoin\b/i.test(sql)) {
+        const systems = new Set(extractDqlGenerationSourceSystems(sql));
+        if (systems.size > 1)
+            return 'bridge';
+    }
+    if (hasDqlGenerationRankingLimit(sql))
+        return 'ranking';
+    if (groupFields.some((field) => /\b(date|day|week|month|quarter|year|period|time)\b/i.test(field)))
+        return 'trend';
+    if (groupFields.length === 1 && /_id$|_key$/i.test(groupFields[0]))
+        return 'entity_rollup';
+    if (!/\b(sum|count|avg|min|max|median|percentile|rank)\s*\(/i.test(sql) && /\b(dim|profile|customer|account|player|product|user|entity)\b/i.test(sql)) {
+        return 'entity_profile';
+    }
+    return 'custom';
+}
+function hasDqlGenerationRankingLimit(sql) {
+    return /\border\s+by\b[\s\S]*\blimit\s+(?:\d+|\$\{\s*[A-Za-z_][A-Za-z0-9_]*\s*\}|[:?][A-Za-z_][A-Za-z0-9_]*)/i.test(sql);
+}
+function extractDqlGenerationSourceSystems(sql) {
+    const tables = new Set();
+    const cleaned = sql.replace(/--[^\n\r]*/g, ' ').replace(/\/\*[\s\S]*?\*\//g, ' ');
+    const regex = /\b(?:from|join|update|into)\s+([`"[]?[A-Za-z0-9_./:-]+(?:\.[A-Za-z0-9_./:-]+)*[`"\]]?)/gi;
+    let match;
+    while ((match = regex.exec(cleaned))) {
+        const raw = match[1].replace(/^[`"[]|[`"\]]$/g, '');
+        const parts = raw.split('.').filter(Boolean);
+        const system = parts.slice(-2, -1)[0] ?? parts[0];
+        if (system)
+            tables.add(system.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, '-'));
+    }
+    return [...tables].filter(Boolean).slice(0, 12);
+}
+function extractDqlGenerationFilterFields(sql) {
+    const filters = new Set();
+    const where = sql.match(/\bwhere\b([\s\S]+?)(?:\bgroup\s+by\b|\border\s+by\b|\blimit\b|$)/i)?.[1] ?? '';
+    const addFilter = (value) => {
+        const name = value?.split('.').pop()?.replace(/[`"[\]]/g, '');
+        if (name && !/^(and|or|not|null|year|month|day)$/i.test(name))
+            filters.add(name);
+    };
+    const extractRegex = /\bextract\s*\([^)]*\bfrom\s+([A-Za-z_][A-Za-z0-9_.]*)\s*\)\s*(?:=|<>|!=|>|<|>=|<=|\bin\b|\blike\b)/gi;
+    const isNullRegex = /\b([A-Za-z_][A-Za-z0-9_.]*)\s+is\s+(?:not\s+)?null\b/gi;
+    const regex = /\b([A-Za-z_][A-Za-z0-9_.]*)\s*(?:=|<>|!=|>|<|>=|<=|\bin\b|\blike\b)/gi;
+    let match;
+    while ((match = extractRegex.exec(where)))
+        addFilter(match[1]);
+    while ((match = isNullRegex.exec(where)))
+        addFilter(match[1]);
+    while ((match = regex.exec(where))) {
+        addFilter(match[1]);
+    }
+    return [...filters].slice(0, 16);
+}
+function extractDqlGenerationYearFilters(sql) {
+    const years = new Set();
+    const cleaned = sql.replace(/--[^\n\r]*/g, ' ').replace(/\/\*[\s\S]*?\*\//g, ' ');
+    let match;
+    const extractYear = /extract\s*\(\s*year\s+from\s+[^)]+\)\s*(?:=\s*([12][0-9]{3})|in\s*\(([^)]*)\))/gi;
+    while ((match = extractYear.exec(cleaned))) {
+        for (const year of (match[1] || match[2] || '').match(/[12][0-9]{3}/g) ?? [])
+            years.add(year);
+    }
+    return Array.from(years).sort();
+}
+function splitDqlGenerationSqlList(value) {
+    const parts = [];
+    let start = 0;
+    let depth = 0;
+    let single = false;
+    let double = false;
+    for (let i = 0; i < value.length; i += 1) {
+        const char = value[i];
+        if (!double && char === "'" && value[i - 1] !== '\\')
+            single = !single;
+        else if (!single && char === '"' && value[i - 1] !== '\\')
+            double = !double;
+        else if (!single && !double && char === '(')
+            depth += 1;
+        else if (!single && !double && char === ')' && depth > 0)
+            depth -= 1;
+        else if (!single && !double && depth === 0 && char === ',') {
+            parts.push(value.slice(start, i));
+            start = i + 1;
+        }
+    }
+    parts.push(value.slice(start));
+    return parts.map((part) => part.trim()).filter(Boolean);
+}
+function inferDqlGenerationDomain(candidate) {
+    const current = candidate.domain?.trim();
+    if (current && current !== 'imported' && current !== 'general')
+        return current;
+    const firstTable = candidate.lineage.sourceTables[0];
+    const schema = firstTable?.split('.').filter(Boolean).slice(-2, -1)[0];
+    return schema?.replace(/[^a-z0-9/_-]+/gi, '-').toLowerCase() || current || 'imported';
+}
+async function buildAiDqlGenerationPatch(provider, candidate, evidence, contextPack) {
+    const payload = {
+        candidate: {
+            name: candidate.name,
+            domain: candidate.domain,
+            description: candidate.description,
+            owner: candidate.owner,
+            tags: candidate.tags,
+            sql: candidate.sql,
+            sourceTables: candidate.lineage.sourceTables,
+            parameters: candidate.lineage.parameters,
+            warnings: candidate.warnings ?? candidate.lineage.warnings,
+            grain: extractDqlGenerationGroupByFields(candidate.sql),
+            yearFilters: extractDqlGenerationYearFilters(candidate.sql),
+            parameterization: parameterizeSqlForDqlImport(candidate.sql),
+        },
+        context: {
+            evidence,
+            selectedObjects: contextPack?.objects.slice(0, 24).map((object) => ({
+                objectKey: object.objectKey,
+                objectType: object.objectType,
+                name: object.fullName ?? object.name,
+                domain: object.domain,
+                status: object.status,
+                description: object.description,
+            })) ?? [],
+            allowedRelations: contextPack?.allowedSqlContext.relations.slice(0, 12).map((relation) => ({
+                relation: relation.relation,
+                source: relation.source,
+                columns: relation.columns.slice(0, 16).map((column) => column.name),
+            })) ?? [],
+        },
+    };
+    const text = await provider.generate([
+        {
+            role: 'system',
+            content: [
+                'You generate DQL Block Studio metadata for a local draft.',
+                'Return only a compact JSON object with optional keys: name, domain, description, owner, tags, terms, llmContext, pattern, grain, entities, outputs, dimensions, allowedFilters, sourceSystems, replacementFor, reviewCadence.',
+                'Do not return markdown. Do not mark the block certified. Do not change SQL.',
+                'Use only directly relevant dbt, semantic, warehouse, certified block, and SQL-shape evidence from the payload.',
+                'terms must reference existing DQL/DataLex glossary terms from the payload. Do not invent term names.',
+                'If metadata descriptions are missing, describe the observable SQL intent instead of inventing business meaning.',
+                'Descriptions and llmContext must be specific, business-readable, concise, and review-required.',
+                'reviewCadence should usually be monthly or quarterly unless evidence strongly suggests a different cadence.',
+                'Tags must be business/search tags. Avoid generic tags such as raw-sql, imported, ai-generated.',
+            ].join('\n'),
+        },
+        { role: 'user', content: JSON.stringify(payload) },
+    ], { maxTokens: 900, temperature: 0.1 });
+    return normalizeDqlGenerationPatch(parseFirstJsonObject(text));
+}
+function parseFirstJsonObject(text) {
+    const trimmed = text.trim();
+    if (trimmed.startsWith('{') && trimmed.endsWith('}'))
+        return JSON.parse(trimmed);
+    const match = trimmed.match(/\{[\s\S]*\}/);
+    if (!match)
+        return null;
+    return JSON.parse(match[0]);
+}
+function normalizeDqlGenerationPatch(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const record = value;
+    const patch = {};
+    if (typeof record.name === 'string' && record.name.trim())
+        patch.name = record.name.trim().slice(0, 120);
+    if (typeof record.domain === 'string' && record.domain.trim())
+        patch.domain = record.domain.trim().slice(0, 80);
+    if (typeof record.description === 'string' && record.description.trim())
+        patch.description = record.description.trim().slice(0, 500);
+    if (typeof record.owner === 'string' && record.owner.trim())
+        patch.owner = record.owner.trim().slice(0, 120);
+    if (Array.isArray(record.tags))
+        patch.tags = normalizeDqlGenerationStringArray(record.tags, 12);
+    if (Array.isArray(record.terms))
+        patch.terms = normalizeDqlGenerationStringArray(record.terms, 16);
+    if (typeof record.llmContext === 'string' && record.llmContext.trim())
+        patch.llmContext = record.llmContext.trim().slice(0, 1000);
+    if (typeof record.pattern === 'string' && record.pattern.trim())
+        patch.pattern = normalizeDqlGenerationPattern(record.pattern);
+    if (typeof record.grain === 'string' && record.grain.trim())
+        patch.grain = record.grain.trim().slice(0, 120);
+    if (Array.isArray(record.entities))
+        patch.entities = normalizeDqlGenerationStringArray(record.entities, 12);
+    if (Array.isArray(record.outputs))
+        patch.outputs = normalizeDqlGenerationStringArray(record.outputs, 24);
+    if (Array.isArray(record.dimensions))
+        patch.dimensions = normalizeDqlGenerationStringArray(record.dimensions, 16);
+    if (Array.isArray(record.allowedFilters))
+        patch.allowedFilters = normalizeDqlGenerationStringArray(record.allowedFilters, 16);
+    if (Array.isArray(record.sourceSystems))
+        patch.sourceSystems = normalizeDqlGenerationStringArray(record.sourceSystems, 12);
+    if (Array.isArray(record.replacementFor))
+        patch.replacementFor = normalizeDqlGenerationStringArray(record.replacementFor, 12);
+    if (typeof record.reviewCadence === 'string' && record.reviewCadence.trim()) {
+        const reviewCadence = normalizeDqlGenerationReviewCadence(record.reviewCadence);
+        if (reviewCadence)
+            patch.reviewCadence = reviewCadence;
+    }
+    return Object.keys(patch).length > 0 ? patch : null;
+}
+function normalizeDqlGenerationStringArray(value, limit) {
+    const result = [];
+    for (const item of value) {
+        const normalized = normalizeDqlGenerationStringItem(item);
+        if (normalized)
+            result.push(normalized);
+    }
+    return Array.from(new Set(result)).slice(0, limit);
+}
+function normalizeDqlGenerationStringItem(value) {
+    if (typeof value === 'string')
+        return value.trim();
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return '';
+    const record = value;
+    for (const key of ['name', 'field', 'column', 'id', 'value', 'label', 'sourceSystem', 'source_system']) {
+        const nested = record[key];
+        if (typeof nested === 'string' && nested.trim())
+            return nested.trim();
+    }
+    return '';
+}
+function normalizeDqlGenerationPattern(value) {
+    const normalized = value.trim().toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+    const allowed = new Set([
+        'metric_wrapper',
+        'entity_profile',
+        'entity_rollup',
+        'ranking',
+        'trend',
+        'bridge',
+        'drilldown',
+        'replacement',
+        'custom',
+    ]);
+    return allowed.has(normalized) ? normalized : undefined;
+}
+function normalizeDqlGenerationReviewCadence(value) {
+    const normalized = value.trim().toLowerCase().replace(/[^a-z0-9_ -]+/g, '').replace(/\s+/g, '_');
+    const allowed = new Set(['daily', 'weekly', 'biweekly', 'monthly', 'quarterly', 'semiannual', 'annual']);
+    return allowed.has(normalized) ? normalized : undefined;
+}
+function mergeGroundedDqlGenerationTerms(baseTerms, overrideTerms, evidence) {
+    const grounded = new Map();
+    for (const item of evidence) {
+        if (item.kind !== 'dql_term' && item.kind !== 'datalex_term')
+            continue;
+        const normalized = normalizedTerm(item.name);
+        if (normalized)
+            grounded.set(normalized, item.name.trim());
+    }
+    const merged = [...(baseTerms ?? []), ...(overrideTerms ?? [])]
+        .map((term) => grounded.get(normalizedTerm(term)))
+        .filter((term) => Boolean(term));
+    const result = Array.from(new Set(merged)).slice(0, 16);
+    return result.length > 0 ? result : undefined;
+}
+function mergeDqlGenerationPatch(base, override, candidate, evidence) {
+    const name = override.name && !isWeakDqlGenerationName(override.name) ? override.name : base.name;
+    const description = override.description
+        && !isWeakDqlGenerationDescription(override.description)
+        && !isUngroundedDqlGenerationDescription(override.description, candidate, evidence)
+        ? override.description
+        : base.description;
+    const llmContext = override.llmContext
+        && !isUngroundedDqlGenerationDescription(override.llmContext, candidate, evidence)
+        ? override.llmContext
+        : base.llmContext;
+    const overrideTags = override.tags
+        ? override.tags.filter((tag) => !/^(raw-sql|imported|ai-generated)$/i.test(tag))
+        : [];
+    return {
+        ...base,
+        ...override,
+        name,
+        description,
+        llmContext,
+        tags: Array.from(new Set([...(base.tags ?? []), ...overrideTags])).slice(0, 12),
+        terms: mergeGroundedDqlGenerationTerms(base.terms, override.terms, evidence),
+        pattern: override.pattern ?? base.pattern,
+        grain: override.grain ?? base.grain,
+        entities: override.entities?.length ? override.entities : base.entities,
+        outputs: override.outputs?.length ? override.outputs : base.outputs,
+        dimensions: override.dimensions?.length ? override.dimensions : base.dimensions,
+        allowedFilters: override.allowedFilters?.length ? override.allowedFilters : base.allowedFilters,
+        parameterPolicy: base.parameterPolicy,
+        filterBindings: base.filterBindings,
+        parameterDecisions: base.parameterDecisions,
+        similarityMatches: base.similarityMatches,
+        recommendedAction: base.recommendedAction,
+        sql: base.sql,
+        warnings: base.warnings,
+        sourceSystems: override.sourceSystems?.length ? override.sourceSystems : base.sourceSystems,
+        replacementFor: override.replacementFor?.length ? override.replacementFor : base.replacementFor,
+        reviewCadence: override.reviewCadence ?? base.reviewCadence,
     };
 }
-function extractSqlTablesLight(sql) {
-    const tables = new Set();
-    const cleaned = sql.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/--[^\n\r]*/g, ' ');
-    const regex = /\b(?:from|join|update|into)\s+([`"[]?[A-Za-z0-9_./:-]+(?:\.[A-Za-z0-9_./:-]+)*[`"\]]?)/gi;
-    let match;
-    while ((match = regex.exec(cleaned))) {
-        const raw = match[1].replace(/^[`"[]|[`"\]]$/g, '');
-        if (raw && !raw.startsWith('(') && !/^(select|values|unnest|lateral)$/i.test(raw))
-            tables.add(raw);
-    }
-    return Array.from(tables);
+function buildDqlGenerationSimilarityMatches(candidate, patch, contextPack) {
+    const candidateSql = patch.sql ?? candidate.sql;
+    const candidateFingerprints = buildBlockSqlFingerprints(candidateSql);
+    const candidateBusinessFingerprint = buildBlockBusinessFingerprint({
+        name: patch.name ?? candidate.name,
+        domain: patch.domain ?? candidate.domain,
+        pattern: patch.pattern,
+        grain: patch.grain,
+        entities: patch.entities,
+        terms: patch.terms,
+        outputs: patch.outputs,
+        dimensions: patch.dimensions,
+        filters: patch.allowedFilters,
+        sources: candidate.lineage.sourceTables,
+        sourceSystems: patch.sourceSystems,
+    });
+    const candidateShape = {
+        name: candidate.name,
+        pattern: patch.pattern,
+        grain: patch.grain,
+        outputs: new Set((patch.outputs ?? []).map(normalizedTerm)),
+        terms: new Set((patch.terms ?? []).map(normalizedTerm)),
+        dimensions: new Set((patch.dimensions ?? []).map(normalizedTerm)),
+        filters: new Set((patch.allowedFilters ?? []).map(normalizedTerm)),
+        entities: new Set((patch.entities ?? []).map(normalizedTerm)),
+        sources: new Set(candidate.lineage.sourceTables.flatMap(relationLookupTokens).map(normalizedTerm)),
+    };
+    const objects = (contextPack?.objects ?? []).filter((object) => object.objectType === 'dql_block');
+    const matches = objects.flatMap((object) => {
+        const payload = object.payload ?? {};
+        const objectSql = typeof payload.sql === 'string' ? payload.sql : '';
+        const objectFingerprints = metadataSqlFingerprints(payload.sqlFingerprints)
+            ?? (objectSql ? buildBlockSqlFingerprints(objectSql) : null);
+        const objectBusinessFingerprint = metadataBusinessFingerprint(payload.businessFingerprint);
+        const objectShape = {
+            pattern: metadataString(payload.pattern),
+            grain: metadataString(payload.grain),
+            outputs: new Set(metadataStringArray(payload.declaredOutputs ?? payload.outputs)),
+            terms: new Set(metadataStringArray(payload.termRefs ?? payload.terms)),
+            dimensions: new Set(metadataStringArray(payload.dimensions)),
+            filters: new Set(metadataStringArray(payload.allowedFilters)),
+            entities: new Set(metadataStringArray(payload.entities)),
+            sources: new Set(metadataStringArray(payload.tableDependencies ?? payload.rawTableRefs).flatMap(relationLookupTokens).map(normalizedTerm)),
+        };
+        if (objectFingerprints?.exact && objectFingerprints.exact === candidateFingerprints.exact) {
+            return [{
+                    kind: 'exact_sql_match',
+                    objectKey: object.objectKey,
+                    name: object.fullName ?? object.name,
+                    status: object.status,
+                    source: object.sourcePath,
+                    score: 0.99,
+                    reason: 'Normalized SQL exactly matches an existing DQL block.',
+                    recommendedAction: 'reuse_existing',
+                }];
+        }
+        if (objectFingerprints?.parameterized && objectFingerprints.parameterized === candidateFingerprints.parameterized) {
+            return [{
+                    kind: 'parameterized_duplicate',
+                    objectKey: object.objectKey,
+                    name: object.fullName ?? object.name,
+                    status: object.status,
+                    source: object.sourcePath,
+                    score: 0.94,
+                    reason: 'SQL shape matches after replacing literal values with parameters.',
+                    recommendedAction: 'reuse_existing',
+                }];
+        }
+        const score = businessShapeSimilarity(candidateShape, objectShape, object);
+        if (objectBusinessFingerprint?.hash
+            && objectBusinessFingerprint.hash === candidateBusinessFingerprint.hash
+            && object.status === 'certified') {
+            return [{
+                    kind: 'business_duplicate',
+                    objectKey: object.objectKey,
+                    name: object.fullName ?? object.name,
+                    status: object.status,
+                    source: object.sourcePath,
+                    score: Math.max(score, 0.86),
+                    reason: 'Certified block has the same persisted business-shape fingerprint.',
+                    recommendedAction: 'reuse_existing',
+                }];
+        }
+        if (score >= 0.76 && object.status === 'certified') {
+            return [{
+                    kind: 'business_duplicate',
+                    objectKey: object.objectKey,
+                    name: object.fullName ?? object.name,
+                    status: object.status,
+                    source: object.sourcePath,
+                    score,
+                    reason: 'Certified block has the same business shape: entity, grain, filters, outputs, or source family overlap.',
+                    recommendedAction: 'reuse_existing',
+                }];
+        }
+        if (score >= 0.58) {
+            return [{
+                    kind: 'near_variant',
+                    objectKey: object.objectKey,
+                    name: object.fullName ?? object.name,
+                    status: object.status,
+                    source: object.sourcePath,
+                    score,
+                    reason: 'Existing block is close but appears to need a reviewed filter, output, grain, or source extension.',
+                    recommendedAction: 'extend_existing',
+                }];
+        }
+        return [];
+    }).sort((a, b) => b.score - a.score).slice(0, 8);
+    const top = matches[0];
+    return {
+        matches,
+        recommendedAction: top?.recommendedAction ?? 'create_new',
+    };
 }
-function setBlockStudioStatus(projectRoot, blockPath, newStatus) {
-    const normalizedPath = normalize(blockPath).replace(/^\/+/, '');
-    if (!normalizedPath.startsWith('blocks/'))
-        throw new Error('Invalid block path');
-    const absPath = join(projectRoot, normalizedPath);
-    if (!existsSync(absPath))
-        throw new Error('Block file not found');
-    let source = readFileSync(absPath, 'utf-8');
-    if (/status\s*=\s*"[^"]*"/.test(source)) {
-        source = source.replace(/status\s*=\s*"[^"]*"/, `status = "${newStatus}"`);
+function metadataSqlFingerprints(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const record = value;
+    const exact = typeof record.exact === 'string' ? record.exact : '';
+    const parameterized = typeof record.parameterized === 'string' ? record.parameterized : '';
+    if (!exact || !parameterized)
+        return null;
+    return { exact, parameterized };
+}
+function metadataBusinessFingerprint(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const record = value;
+    const hash = typeof record.hash === 'string' ? record.hash : '';
+    if (!hash)
+        return null;
+    const tokens = Array.isArray(record.tokens)
+        ? record.tokens.map((item) => String(item)).filter(Boolean)
+        : [];
+    return { hash, tokens };
+}
+function businessShapeSimilarity(candidate, object, metadata) {
+    let score = 0;
+    if (candidate.pattern && object.pattern && normalizedTerm(candidate.pattern) === normalizedTerm(object.pattern))
+        score += 0.12;
+    if (candidate.grain && object.grain && normalizedTerm(candidate.grain) === normalizedTerm(object.grain))
+        score += 0.15;
+    score += overlapScore(candidate.outputs, object.outputs) * 0.18;
+    score += overlapScore(candidate.terms, object.terms) * 0.08;
+    score += overlapScore(candidate.dimensions, object.dimensions) * 0.13;
+    score += overlapScore(candidate.filters, object.filters) * 0.14;
+    score += overlapScore(candidate.entities, object.entities) * 0.12;
+    score += overlapScore(candidate.sources, object.sources) * 0.1;
+    const nameTokens = new Set(candidate.name.toLowerCase().split(/[^a-z0-9]+/).filter((value) => value.length > 2));
+    const targetTokens = new Set([
+        ...metadata.name.toLowerCase().split(/[^a-z0-9]+/),
+        ...(metadata.description ?? '').toLowerCase().split(/[^a-z0-9]+/),
+    ].filter((value) => value.length > 2));
+    score += overlapScore(nameTokens, targetTokens) * 0.04;
+    return Number(Math.min(0.98, score).toFixed(3));
+}
+function overlapScore(left, right) {
+    if (left.size === 0 || right.size === 0)
+        return 0;
+    let overlap = 0;
+    for (const value of left) {
+        if (value && right.has(value))
+            overlap += 1;
+    }
+    return overlap / Math.max(1, Math.min(left.size, right.size));
+}
+function normalizedTerm(value) {
+    return String(value ?? '').trim().toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+}
+function metadataString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function metadataStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map((item) => String(item).trim()).filter(Boolean).map(normalizedTerm);
+}
+function isWeakDqlGenerationName(name) {
+    return /^(pasted|query|source|imported query|sql import)(?:\s+\d+)?$/i.test(name.trim());
+}
+function isWeakDqlGenerationDescription(description) {
+    return /^draft dql block summarizing imported sql/i.test(description.trim())
+        || /^draft dql block generated from imported sql/i.test(description.trim())
+        || /^imported from /i.test(description.trim())
+        || /^this query (shows|returns|provides)/i.test(description.trim());
+}
+function isUngroundedDqlGenerationDescription(description, candidate, evidence) {
+    const text = description.toLowerCase();
+    const tokens = new Set();
+    for (const tag of candidate.tags) {
+        if (!/^(raw-sql|imported|ai-generated|review-required)$/i.test(tag) && tag.length > 2)
+            tokens.add(tag.toLowerCase());
     }
-    else {
-        source = source.replace(/block\s+"[^"]*"\s*\{/, (match) => `${match}\n  status = "${newStatus}"`);
+    for (const table of candidate.lineage.sourceTables) {
+        for (const token of table.split(/[._\s/-]+/)) {
+            if (token.length > 2)
+                tokens.add(token.toLowerCase());
+        }
     }
-    writeFileSync(absPath, source, 'utf-8');
-    const companionPath = blockCompanionRelativePath(normalizedPath);
-    if (!companionPath)
-        return;
-    const absCompanionPath = join(projectRoot, companionPath);
-    if (!existsSync(absCompanionPath))
-        return;
-    let companion = readFileSync(absCompanionPath, 'utf-8');
-    if (/^reviewStatus:\s*.+$/m.test(companion)) {
-        companion = companion.replace(/^reviewStatus:\s*.+$/m, `reviewStatus: ${newStatus}`);
+    for (const item of evidence.slice(0, 6)) {
+        for (const token of item.name.split(/[._\s/-]+/)) {
+            if (token.length > 3 && !/^(model|source|semantic|table)$/i.test(token))
+                tokens.add(token.toLowerCase());
+        }
     }
-    else {
-        companion = `${companion.trimEnd()}\nreviewStatus: ${newStatus}\n`;
+    if (tokens.size === 0)
+        return false;
+    return !Array.from(tokens).some((token) => text.includes(token));
+}
+function dqlGenerationConversionNotes(providerName) {
+    return [
+        `Generated with ${providerName} using local project context when available.`,
+        'Runtime-scope SQL literals are converted into DQL params when safe; business constants stay static for review.',
+        'Certified and draft block similarity is checked before a new draft is saved.',
+        'SQL semantics are preserved while reusable parameter placeholders may replace literal values.',
+        'Drafts are autosaved under blocks/_drafts or domains/<domain>/blocks/_drafts before certification.',
+        'Preview results and tests gate certification before promotion.',
+    ];
+}
+function setBlockStudioSourceStatus(source, status) {
+    if (/status\s*=\s*"[^"]*"/.test(source)) {
+        return source.replace(/status\s*=\s*"[^"]*"/, `status = "${status}"`);
     }
-    writeFileSync(absCompanionPath, companion, 'utf-8');
+    return source.replace(/block\s+"[^"]*"\s*\{/, (match) => `${match}\n  status = "${status}"`);
 }
 async function buildBlockStudioAiAssistSummary(projectRoot, action, candidate, validation, requestedProvider) {
     const fallback = buildDeterministicAiAssistSummary(action, candidate, validation);
@@ -5249,6 +7965,14 @@ export function readGitMetadata(projectRoot) {
         return null;
     }
 }
+function resolveBlockWriteTarget(projectRoot, safeDomain, slug) {
+    if (safeDomain && existsSync(join(projectRoot, 'domains', safeDomain))) {
+        const relativePath = `domains/${safeDomain}/blocks/${slug}.dql`;
+        return { relativePath, absPath: join(projectRoot, relativePath) };
+    }
+    const relativePath = safeDomain ? `blocks/${safeDomain}/${slug}.dql` : `blocks/${slug}.dql`;
+    return { relativePath, absPath: join(projectRoot, relativePath) };
+}
 export function createBlockArtifacts(projectRoot, options) {
     const slug = options.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'block';
     const safeDomain = (options.domain ?? '')
@@ -5256,16 +7980,16 @@ export function createBlockArtifacts(projectRoot, options) {
         .toLowerCase()
         .replace(/[^a-z0-9/_-]+/g, '-')
         .replace(/^\/+|\/+$/g, '');
-    const blocksDir = safeDomain ? join(projectRoot, 'blocks', safeDomain) : join(projectRoot, 'blocks');
-    mkdirSync(blocksDir, { recursive: true });
-    const blockPath = join(blocksDir, `${slug}.dql`);
+    const target = resolveBlockWriteTarget(projectRoot, safeDomain, slug);
+    mkdirSync(dirname(target.absPath), { recursive: true });
+    const blockPath = target.absPath;
     if (existsSync(blockPath)) {
         throw new Error('BLOCK_EXISTS');
     }
     const templateContent = options.template
         ? listBlockTemplates().find((template) => template.id === options.template)?.content
         : undefined;
-    const relativePath = safeDomain ? `blocks/${safeDomain}/${slug}.dql` : `blocks/${slug}.dql`;
+    const relativePath = target.relativePath;
     const fileContent = canonicalizeSafe(options.blockType === 'semantic' && !options.content?.trim() && !templateContent
         ? buildBlankSemanticBlockContent({
             name: options.name,
@@ -5311,9 +8035,9 @@ export function createSemanticBuilderBlock(projectRoot, options) {
         .toLowerCase()
         .replace(/[^a-z0-9/_-]+/g, '-')
         .replace(/^\/+|\/+$/g, '') || 'uncategorized';
-    const blocksDir = join(projectRoot, 'blocks', safeDomain);
-    mkdirSync(blocksDir, { recursive: true });
-    const blockPath = join(blocksDir, `${slug}.dql`);
+    const target = resolveBlockWriteTarget(projectRoot, safeDomain, slug);
+    mkdirSync(dirname(target.absPath), { recursive: true });
+    const blockPath = target.absPath;
     if (existsSync(blockPath)) {
         throw new Error('BLOCK_EXISTS');
     }
@@ -5338,7 +8062,7 @@ export function createSemanticBuilderBlock(projectRoot, options) {
         ],
     });
     return {
-        path: `blocks/${safeDomain}/${slug}.dql`,
+        path: target.relativePath,
         content,
         companionPath,
     };
@@ -6100,18 +8824,16 @@ export function buildDbtStatus(projectRoot, projectConfig, lastSyncTime) {
     const sourceCount = manifest?.sources && typeof manifest.sources === 'object'
         ? Object.keys(manifest.sources).length
         : 0;
-    const manifestMetricCount = manifest?.metrics && typeof manifest.metrics === 'object'
-        ? Object.keys(manifest.metrics).length
-        : 0;
-    const semanticMetricCount = Array.isArray(semanticManifest?.metrics)
-        ? semanticManifest.metrics.length
+    const manifestMetricCount = artifactCollectionCount(manifest?.metrics);
+    const semanticMetricCount = semanticManifest
+        ? artifactCollectionCount(semanticManifest.metrics)
         : manifestMetricCount;
-    const semanticModelCount = Array.isArray(semanticManifest?.semantic_models)
-        ? semanticManifest.semantic_models.length
-        : 0;
-    const savedQueryCount = Array.isArray(semanticManifest?.saved_queries)
-        ? semanticManifest.saved_queries.length
-        : 0;
+    const semanticModelCount = semanticManifest
+        ? artifactCollectionCount(semanticManifest.semantic_models)
+        : artifactCollectionCount(manifest?.semantic_models);
+    const savedQueryCount = semanticManifest
+        ? artifactCollectionCount(semanticManifest.saved_queries ?? semanticManifest.savedQueries)
+        : artifactCollectionCount(manifest?.saved_queries ?? manifest?.savedQueries);
     const configured = existsSync(join(dbtProjectPath, 'dbt_project.yml'))
         || Boolean(projectConfig.dbt?.projectDir)
         || Boolean(projectConfig.semanticLayer?.provider === 'dbt' && projectConfig.semanticLayer.projectPath);
@@ -6123,7 +8845,9 @@ export function buildDbtStatus(projectRoot, projectConfig, lastSyncTime) {
             ? 'Run `dbt parse`, `dbt compile`, or `dbt build`, then run `dql sync dbt`.'
             : !semanticExists
                 ? 'dbt manifest is ready. Run `dbt parse` or `dbt build` if you use dbt Semantic Layer metrics.'
-                : 'dbt artifacts are ready. Build SQL blocks from models or semantic blocks from metrics.';
+                : semanticMetricCount === 0 && semanticModelCount === 0 && savedQueryCount === 0
+                    ? 'dbt manifest is ready, but MetricFlow semantic_manifest.json is empty. Add dbt semantic_models and metrics, then rerun dbt parse/build.'
+                    : 'dbt artifacts are ready. Build SQL blocks from models or semantic blocks from metrics.';
     return {
         configured,
         provider: projectConfig.semanticLayer?.provider ?? null,
@@ -6146,6 +8870,185 @@ export function buildDbtStatus(projectRoot, projectConfig, lastSyncTime) {
         setupHint,
     };
 }
+export function buildSemanticLayerDiagnostics(projectRoot, projectConfig, options) {
+    const provider = options.semanticConfig?.provider ?? options.detectedProvider ?? null;
+    const dbt = buildDbtStatus(projectRoot, projectConfig, options.lastSyncTime);
+    const counts = semanticLayerCounts(options.semanticLayer);
+    const uncategorizedObjects = countUncategorizedSemanticObjects(options.semanticLayer);
+    const totalObjects = counts.metrics
+        + counts.measures
+        + counts.dimensions
+        + counts.timeDimensions
+        + counts.entities
+        + counts.hierarchies
+        + counts.semanticModels
+        + counts.savedQueries;
+    const issues = [];
+    for (const error of options.semanticErrors ?? []) {
+        issues.push({
+            severity: 'error',
+            code: 'semantic_load_error',
+            message: error,
+            action: 'Open the semantic source configuration, fix the provider error, then reload the semantic layer.',
+        });
+    }
+    if (!provider) {
+        issues.push({
+            severity: existsSync(join(projectRoot, 'semantic-layer')) ? 'info' : 'warning',
+            code: 'semantic_provider_not_configured',
+            message: 'No semantic layer provider is configured.',
+            action: 'Configure dbt MetricFlow, local semantic-layer YAML, or Snowflake Semantic Views from the setup flow.',
+        });
+    }
+    if (provider === 'dbt' || dbt.configured) {
+        if (!dbt.configured) {
+            issues.push({
+                severity: 'warning',
+                code: 'dbt_project_not_detected',
+                message: 'dbt is selected as the semantic source, but no dbt project was detected.',
+                action: 'Set dbt.projectDir or run DQL from a repository containing dbt_project.yml.',
+            });
+        }
+        if (!dbt.artifacts.manifest.exists) {
+            issues.push({
+                severity: 'error',
+                code: 'dbt_manifest_missing',
+                message: 'dbt manifest.json is missing, so DQL cannot build dbt model context.',
+                action: 'Run dbt parse, dbt compile, or dbt build, then reload the semantic layer.',
+                path: dbt.artifacts.manifest.path,
+            });
+        }
+        if (!dbt.artifacts.semanticManifest.exists) {
+            issues.push({
+                severity: 'warning',
+                code: 'metricflow_semantic_manifest_missing',
+                message: 'dbt MetricFlow semantic_manifest.json is missing. DQL can still inspect dbt models, but MetricFlow metrics and saved queries may be incomplete.',
+                action: 'Run dbt parse or dbt build with semantic models configured, then reload. For execution, ensure MetricFlow is installed and mf is on PATH.',
+                path: dbt.artifacts.semanticManifest.path,
+            });
+        }
+        else if (dbt.counts.metrics === 0 && dbt.counts.semanticModels === 0 && dbt.counts.savedQueries === 0) {
+            issues.push({
+                severity: 'warning',
+                code: 'metricflow_semantic_manifest_empty',
+                message: 'semantic_manifest.json exists, but it does not contain metrics, semantic models, or saved queries.',
+                action: 'Check dbt semantic model YAML definitions and rerun dbt parse.',
+                path: dbt.artifacts.semanticManifest.path,
+            });
+        }
+        if (options.semanticLayer && totalObjects === 0 && (dbt.counts.models > 0 || dbt.counts.sources > 0)) {
+            issues.push({
+                severity: 'warning',
+                code: 'dbt_model_inventory_only',
+                message: 'DQL loaded dbt model inventory, but no MetricFlow semantic metrics were found.',
+                action: 'Create dbt semantic_models and metrics, or use AI Import to build DQL blocks from dbt model metadata.',
+            });
+        }
+    }
+    if (provider === 'snowflake') {
+        if (!options.semanticLayer && (options.semanticErrors ?? []).length === 0) {
+            issues.push({
+                severity: 'warning',
+                code: 'snowflake_semantic_views_not_loaded',
+                message: 'Snowflake semantic provider did not load semantic views.',
+                action: 'Confirm the active Snowflake connection can query semantic views, then reload. Warehouse tables still feed database context separately.',
+            });
+        }
+        else if (options.semanticLayer && totalObjects === 0) {
+            issues.push({
+                severity: 'info',
+                code: 'snowflake_semantic_views_empty',
+                message: 'Snowflake semantic provider loaded, but no semantic view objects were discovered.',
+                action: 'Check that Snowflake Semantic Views exist and the active role can see them.',
+            });
+        }
+    }
+    if (options.semanticLayer && totalObjects === 0 && issues.every((issue) => issue.code !== 'dbt_model_inventory_only')) {
+        issues.push({
+            severity: 'warning',
+            code: 'semantic_layer_empty',
+            message: 'Semantic layer is available, but no semantic objects are loaded.',
+            action: 'Import semantic definitions or run dbt parse/build, then reload.',
+        });
+    }
+    if (uncategorizedObjects > 0) {
+        issues.push({
+            severity: 'info',
+            code: 'semantic_uncategorized_domain',
+            message: `${uncategorizedObjects} semantic object${uncategorizedObjects === 1 ? '' : 's'} had no domain and are visible under "uncategorized".`,
+            action: 'Add domain metadata in dbt semantic YAML or local semantic-layer files when domain ownership matters.',
+        });
+    }
+    const warnings = Array.from(new Set([
+        ...(options.semanticErrors ?? []),
+        ...issues
+            .filter((issue) => issue.severity !== 'info')
+            .map((issue) => issue.message),
+    ]));
+    return {
+        available: Boolean(options.semanticLayer),
+        provider,
+        sourceOfTruth: provider === 'dbt'
+            ? 'dbt MetricFlow semantic_manifest.json, dbt manifest.json semantic nodes, then dbt semantic YAML fallback'
+            : provider === 'snowflake'
+                ? 'Snowflake Semantic Views only; warehouse tables remain database catalog context'
+                : provider === 'dql'
+                    ? 'local semantic-layer YAML'
+                    : 'not configured',
+        errors: options.semanticErrors ?? [],
+        lastSyncTime: options.lastSyncTime,
+        counts,
+        dbt,
+        issues,
+        warnings,
+    };
+}
+function semanticLayerCounts(layer) {
+    return layer
+        ? {
+            domains: layer.listDomains().length,
+            metrics: layer.listMetrics().length,
+            measures: layer.listMeasures().length,
+            dimensions: layer.listDimensions().length,
+            timeDimensions: layer.listTimeDimensions().length,
+            entities: layer.listEntities().length,
+            hierarchies: layer.listHierarchies().length,
+            semanticModels: layer.listSemanticModels().length,
+            savedQueries: layer.listSavedQueries().length,
+        }
+        : {
+            domains: 0,
+            metrics: 0,
+            measures: 0,
+            dimensions: 0,
+            timeDimensions: 0,
+            entities: 0,
+            hierarchies: 0,
+            semanticModels: 0,
+            savedQueries: 0,
+        };
+}
+function countUncategorizedSemanticObjects(layer) {
+    if (!layer)
+        return 0;
+    return [
+        ...layer.listMetrics(),
+        ...layer.listMeasures(),
+        ...layer.listDimensions(),
+        ...layer.listTimeDimensions(),
+        ...layer.listEntities(),
+        ...layer.listHierarchies(),
+        ...layer.listSemanticModels(),
+        ...layer.listSavedQueries(),
+    ].filter((object) => !object.domain || !object.domain.trim()).length;
+}
+function artifactCollectionCount(value) {
+    if (Array.isArray(value))
+        return value.length;
+    if (value && typeof value === 'object')
+        return Object.keys(value).length;
+    return 0;
+}
 function describeArtifact(path, count, generatedAt) {
     return {
         path,
@@ -6682,6 +9585,11 @@ function isProviderSettingsId(value) {
         || value === 'ollama'
         || value === 'custom-openai';
 }
+function isDeterministicDqlGenerationProvider(value) {
+    if (typeof value !== 'string')
+        return false;
+    return value === 'none' || value === 'deterministic' || value === 'local-deterministic';
+}
 async function testProviderConfig(projectRoot, id) {
     const config = getEffectiveProviderConfig(projectRoot, id);
     const label = providerSettingsLabel(id);
@@ -6831,6 +9739,655 @@ function recordAgentRuntimeSchemaSnapshot(projectRoot, schemaContext, source) {
         // Runtime schema snapshots are advisory local metadata and must not block answers.
     }
 }
+function notebookResearchString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function notebookResearchRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function notebookResearchSourceCellPayload(body) {
+    const sourceCell = notebookResearchRecord(body.sourceCell)
+        ?? notebookResearchRecord(notebookResearchRecord(body.context)?.sourceCell);
+    if (!sourceCell)
+        return undefined;
+    const payload = {
+        id: notebookResearchString(sourceCell.id),
+        sourceCellId: notebookResearchString(sourceCell.sourceCellId),
+        cellId: notebookResearchString(sourceCell.cellId),
+        name: notebookResearchString(sourceCell.name),
+        sourceCellName: notebookResearchString(sourceCell.sourceCellName),
+        title: notebookResearchString(sourceCell.title),
+        fingerprint: notebookResearchString(sourceCell.fingerprint),
+        sourceCellFingerprint: notebookResearchString(sourceCell.sourceCellFingerprint),
+        sqlFingerprint: notebookResearchString(sourceCell.sqlFingerprint),
+        type: notebookResearchString(sourceCell.type),
+        sql: notebookResearchString(sourceCell.sql),
+        content: notebookResearchString(sourceCell.content),
+        source: notebookResearchString(sourceCell.source),
+    };
+    return Object.values(payload).some(Boolean) ? payload : undefined;
+}
+function notebookResearchSourceCellId(sourceCell) {
+    return notebookResearchString(sourceCell?.id)
+        ?? notebookResearchString(sourceCell?.sourceCellId)
+        ?? notebookResearchString(sourceCell?.cellId);
+}
+function notebookResearchSourceCellName(sourceCell) {
+    return notebookResearchString(sourceCell?.name)
+        ?? notebookResearchString(sourceCell?.sourceCellName)
+        ?? notebookResearchString(sourceCell?.title);
+}
+function notebookResearchSourceCellFingerprint(sourceCell) {
+    return notebookResearchString(sourceCell?.sourceCellFingerprint)
+        ?? notebookResearchString(sourceCell?.fingerprint)
+        ?? notebookResearchString(sourceCell?.sqlFingerprint);
+}
+function notebookResearchPatchString(body, key) {
+    if (!Object.prototype.hasOwnProperty.call(body, key))
+        return undefined;
+    return notebookResearchString(body[key]) ?? null;
+}
+function notebookResearchIntent(value) {
+    return value === 'ad_hoc_analysis'
+        || value === 'diagnose_change'
+        || value === 'driver_breakdown'
+        || value === 'segment_compare'
+        || value === 'entity_drilldown'
+        || value === 'anomaly_investigation'
+        || value === 'trust_gap_review'
+        ? value
+        : undefined;
+}
+function notebookResearchReviewStatus(value) {
+    return value === 'needs_review'
+        || value === 'draft_created'
+        || value === 'completed'
+        || value === 'certified'
+        || value === 'rejected'
+        ? value
+        : undefined;
+}
+function notebookResearchStatus(value) {
+    return value === 'draft'
+        || value === 'running'
+        || value === 'ready'
+        || value === 'error'
+        ? value
+        : undefined;
+}
+function notebookResearchPromotionAction(value) {
+    return value === 'reuse_existing'
+        || value === 'extend_existing'
+        || value === 'create_replacement'
+        || value === 'create_new'
+        || value === 'review_required'
+        ? value
+        : undefined;
+}
+function notebookResearchReadiness(value) {
+    return value === 'draft_ready' || value === 'certification_ready' || value === 'blocked' ? value : undefined;
+}
+function notebookResearchAge(value) {
+    return value === 'stale_open' || value === 'expired_open' ? value : undefined;
+}
+function notebookResearchNextAction(value) {
+    return value === 'fix_blockers'
+        || value === 'review_sql'
+        || value === 'review_context'
+        || value === 'run_preview'
+        || value === 'reuse_existing'
+        || value === 'create_dql_draft'
+        || value === 'open_certification'
+        || value === 'complete_review'
+        || value === 'continue_review'
+        ? value
+        : undefined;
+}
+function notebookResearchSort(value) {
+    return value === 'priority' || value === 'updated_desc' ? value : undefined;
+}
+function withNotebookResearchChecklistPage(page) {
+    return {
+        ...page,
+        runs: page.runs.map(withNotebookResearchChecklist),
+    };
+}
+function withNotebookResearchChecklist(run) {
+    const researchPlan = run.researchPlan ?? buildNotebookResearchPlan({
+        run,
+        evidence: run.evidence,
+        resultPreview: run.resultPreview,
+        previewError: run.status === 'error' ? run.error : undefined,
+        generatedSql: run.generatedSql,
+        reviewedSql: run.reviewedSql,
+        routeDecision: run.routeDecision,
+    });
+    return {
+        ...run,
+        researchPlan,
+        reviewChecklist: buildNotebookResearchReviewChecklist(run),
+    };
+}
+function buildNotebookResearchReviewChecklist(run) {
+    const questionReady = Boolean(notebookResearchString(run.question));
+    const hasReviewedSql = Boolean(notebookResearchString(run.reviewedSql));
+    const hasGeneratedSql = Boolean(notebookResearchString(run.generatedSql));
+    const hasSql = hasReviewedSql || hasGeneratedSql;
+    const preview = notebookResearchPreviewInfo(run.resultPreview);
+    const previewReady = run.status === 'ready' && preview.hasPreview;
+    const evidenceReady = notebookResearchEvidenceCount(run.evidence) > 0 || Boolean(run.contextPackId);
+    const promoted = Boolean(run.dqlPromotion || run.dqlImportId || run.draftBlockPath);
+    const duplicateChecked = Boolean(run.dqlPromotionAction || run.dqlPromotion);
+    const promotionAction = run.dqlPromotionAction ?? run.dqlPromotion?.recommendedAction;
+    const reuseRecommended = promotionAction === 'reuse_existing';
+    const promotionReviewRequired = promotionAction === 'review_required';
+    const hasDraft = Boolean(notebookResearchString(run.draftBlockPath));
+    const sqlForParameterReview = notebookResearchString(run.reviewedSql) ?? notebookResearchString(run.generatedSql);
+    const parameterReview = sqlForParameterReview ? parameterizeSqlForDqlImport(sqlForParameterReview) : null;
+    const dynamicParameters = parameterReview?.parameterPolicy.filter((item) => item.policy === 'dynamic') ?? [];
+    const staticParameters = parameterReview?.parameterPolicy.filter((item) => item.policy !== 'dynamic') ?? [];
+    const blockers = [];
+    const warnings = [];
+    if (!questionReady)
+        blockers.push('Add a business question before review.');
+    if (!hasSql)
+        blockers.push('Add reviewed SQL or generate SQL before promotion.');
+    if (run.status === 'error')
+        blockers.push(run.error ? `Fix preview error: ${run.error}` : 'Fix the failed preview before promotion.');
+    if (!previewReady && run.status !== 'error')
+        warnings.push('Run a bounded preview before certification review.');
+    if (!evidenceReady)
+        warnings.push('Inspect metadata evidence before turning this into a reusable block.');
+    if (hasSql && dynamicParameters.length === 0)
+        warnings.push('No dynamic parameters were detected; confirm this should be a static block before certification.');
+    for (const warning of parameterReview?.warnings ?? [])
+        warnings.push(warning);
+    if (promoted && !duplicateChecked)
+        warnings.push('Promotion exists but duplicate/reuse evidence is missing.');
+    if (reuseRecommended)
+        warnings.push('Reuse the matching block or explicitly document a replacement before certification.');
+    if (promotionReviewRequired)
+        warnings.push('Resolve the review-required promotion decision before certification.');
+    const items = [
+        {
+            id: 'question',
+            label: 'Question',
+            status: questionReady ? 'passed' : 'blocked',
+            detail: questionReady ? 'Business question is captured.' : 'A reusable block needs a clear business question.',
+        },
+        {
+            id: 'sql',
+            label: 'Reviewed SQL',
+            status: hasReviewedSql ? 'passed' : hasGeneratedSql ? 'warning' : 'blocked',
+            detail: hasReviewedSql
+                ? 'Reviewer SQL is saved.'
+                : hasGeneratedSql
+                    ? 'Generated SQL exists; review it before promotion.'
+                    : 'No SQL is available for preview or DQL generation.',
+        },
+        {
+            id: 'preview',
+            label: 'Preview',
+            status: previewReady ? 'passed' : run.status === 'error' ? 'blocked' : 'pending',
+            detail: previewReady
+                ? `Preview returned ${preview.rowCount.toLocaleString()} row${preview.rowCount === 1 ? '' : 's'}.`
+                : run.status === 'error'
+                    ? (run.error ?? 'Preview failed.')
+                    : 'Run a bounded preview to validate the query shape.',
+        },
+        {
+            id: 'evidence',
+            label: 'Evidence',
+            status: evidenceReady ? 'passed' : 'warning',
+            detail: evidenceReady ? 'Metadata evidence or context pack is attached.' : 'No context evidence is attached yet.',
+        },
+        {
+            id: 'duplicates',
+            label: 'Reuse check',
+            status: duplicateChecked ? (reuseRecommended || promotionReviewRequired ? 'warning' : 'passed') : promoted ? 'warning' : 'pending',
+            detail: duplicateChecked
+                ? `Promotion decision: ${promotionAction ?? 'review required'}.`
+                : promoted
+                    ? 'Draft was created without stored duplicate evidence.'
+                    : 'Duplicate check runs when creating a DQL draft.',
+        },
+        {
+            id: 'parameters',
+            label: 'Parameter review',
+            status: !hasSql ? 'pending' : dynamicParameters.length > 0 ? 'passed' : 'warning',
+            detail: !hasSql
+                ? 'Add SQL before checking runtime parameters.'
+                : dynamicParameters.length > 0
+                    ? `Detected ${dynamicParameters.length.toLocaleString()} dynamic parameter${dynamicParameters.length === 1 ? '' : 's'}: ${dynamicParameters.slice(0, 6).map((item) => item.name).join(', ')}.`
+                    : staticParameters.length > 0
+                        ? `Only static or review-required literals were detected: ${staticParameters.slice(0, 6).map((item) => `${item.name} (${item.policy})`).join(', ')}.`
+                        : 'No reusable runtime parameters were detected. Certify as static only if the business question is intentionally fixed.',
+        },
+        {
+            id: 'dql_draft',
+            label: 'DQL draft',
+            status: hasDraft ? 'passed' : hasReviewedSql && evidenceReady ? 'pending' : 'blocked',
+            detail: hasDraft
+                ? `Draft saved at ${run.draftBlockPath}.`
+                : !hasReviewedSql
+                    ? 'Save reviewed SQL before DQL draft creation.'
+                    : evidenceReady
+                        ? 'Create a draft after SQL review.'
+                        : 'Save metadata evidence before creating a reusable DQL draft.',
+        },
+    ];
+    const readyForDqlDraft = questionReady && hasReviewedSql && evidenceReady && run.status !== 'error';
+    const readyForCertificationReview = readyForDqlDraft && previewReady && hasDraft && !reuseRecommended && !promotionReviewRequired;
+    return { readyForDqlDraft, readyForCertificationReview, blockers, warnings, items };
+}
+function buildNotebookResearchPlan(input) {
+    const reviewedSql = notebookResearchString(input.reviewedSql);
+    const generatedSql = notebookResearchString(input.generatedSql);
+    const sql = reviewedSql ?? generatedSql;
+    const parameterized = sql ? parameterizeSqlForDqlImport(sql) : null;
+    const evidence = input.evidence && typeof input.evidence === 'object' && !Array.isArray(input.evidence)
+        ? input.evidence
+        : {};
+    const trustStatus = evidence.trustStatus && typeof evidence.trustStatus === 'object' && !Array.isArray(evidence.trustStatus)
+        ? evidence.trustStatus
+        : {};
+    const allowedSqlContext = evidence.allowedSqlContext && typeof evidence.allowedSqlContext === 'object' && !Array.isArray(evidence.allowedSqlContext)
+        ? evidence.allowedSqlContext
+        : {};
+    const previewRows = input.resultPreview?.rowCount ?? input.resultPreview?.rows.length;
+    const hasEvidence = notebookResearchEvidenceCount(input.evidence) > 0 || Boolean(input.run.contextPackId);
+    const hasPreview = previewRows !== undefined && (previewRows > 0 || Boolean(input.resultPreview?.columns.length));
+    const promotionAction = input.run.dqlPromotionAction ?? input.run.dqlPromotion?.recommendedAction;
+    const missingContext = Array.isArray(evidence.missingContext) ? evidence.missingContext : [];
+    const relations = Array.isArray(allowedSqlContext.relations) ? allowedSqlContext.relations : [];
+    return {
+        sqlState: reviewedSql ? 'reviewed' : generatedSql ? 'generated' : 'missing',
+        grain: sql ? extractDqlGenerationGroupByFields(sql)[0] : undefined,
+        parameterPolicy: (parameterized?.parameterPolicy ?? []).slice(0, 16).map((entry) => ({
+            name: entry.name,
+            policy: entry.policy,
+        })),
+        allowedFilters: (parameterized?.allowedFilters ?? []).slice(0, 16),
+        evidence: {
+            trustLabel: notebookResearchString(trustStatus.label),
+            contextPackId: notebookResearchString(evidence.contextPackId) ?? input.run.contextPackId,
+            evidenceCount: notebookResearchEvidenceCount(input.evidence),
+            relationCount: relations.length,
+            missingContextCount: missingContext.length,
+        },
+        preview: {
+            status: input.previewError ? 'error' : hasPreview ? 'ready' : 'not_run',
+            ...(previewRows === undefined ? {} : { rowCount: previewRows }),
+        },
+        promotion: {
+            path: notebookResearchPlanPromotionPath({
+                hasSql: Boolean(sql),
+                hasEvidence,
+                hasPreview,
+                previewError: input.previewError,
+                draftBlockPath: input.run.draftBlockPath,
+                promotionAction,
+            }),
+            duplicateDecision: promotionAction,
+        },
+        reviewFocus: notebookResearchPlanFocus(input.run.intent, {
+            hasSql: Boolean(sql),
+            hasEvidence,
+            hasPreview,
+            dynamicParameterCount: parameterized?.parameterPolicy.filter((entry) => entry.policy === 'dynamic').length ?? 0,
+            missingContextCount: missingContext.length,
+            promotionAction,
+        }),
+        generatedAt: new Date().toISOString(),
+    };
+}
+function notebookResearchPlanPromotionPath(input) {
+    if (!input.hasSql)
+        return 'needs_sql';
+    if (!input.hasEvidence)
+        return 'review_context';
+    if (input.previewError || !input.hasPreview)
+        return 'run_preview';
+    if (input.promotionAction === 'reuse_existing')
+        return 'reuse_existing';
+    if (input.draftBlockPath)
+        return 'open_certification';
+    return 'create_dql_draft';
+}
+function notebookResearchPlanFocus(intent, input) {
+    const focus = new Set();
+    if (!input.hasSql)
+        focus.add('Add reviewed SQL or configure AI SQL generation.');
+    if (!input.hasEvidence)
+        focus.add('Save metadata context evidence before DQL promotion.');
+    if (!input.hasPreview)
+        focus.add('Run a bounded preview and inspect result shape.');
+    if (input.dynamicParameterCount === 0)
+        focus.add('Confirm whether this should be static or parameterized.');
+    if (input.missingContextCount > 0)
+        focus.add('Resolve missing metadata context before certification.');
+    if (input.promotionAction === 'reuse_existing')
+        focus.add('Reuse the existing certified block or document replacement rationale.');
+    const pattern = notebookResearchIntentPattern(intent);
+    const reviewFocus = Array.isArray(pattern.reviewFocus) ? pattern.reviewFocus : [];
+    for (const item of reviewFocus.slice(0, 4))
+        focus.add(String(item));
+    return Array.from(focus).slice(0, 8);
+}
+function notebookResearchPreviewInfo(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return { hasPreview: false, rowCount: 0 };
+    const record = value;
+    const rowCount = typeof record.rowCount === 'number' && Number.isFinite(record.rowCount)
+        ? record.rowCount
+        : Array.isArray(record.rows)
+            ? record.rows.length
+            : 0;
+    const hasColumns = Array.isArray(record.columns) && record.columns.length > 0;
+    return { hasPreview: hasColumns || rowCount > 0, rowCount };
+}
+function notebookResearchEvidenceCount(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return 0;
+    const record = value;
+    const selected = Array.isArray(record.selectedEvidence) ? record.selectedEvidence.length : 0;
+    const citations = Array.isArray(record.citations) ? record.citations.length : 0;
+    const roles = Array.isArray(record.evidenceRoles) ? record.evidenceRoles.length : 0;
+    return selected + citations + roles;
+}
+function notebookResearchInteger(value, fallback, min, max) {
+    if (typeof value !== 'string' || !value.trim())
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed))
+        return fallback;
+    return Math.max(min, Math.min(max, Math.floor(parsed)));
+}
+function notebookExecutionContext(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const raw = value;
+    const notebookPath = notebookResearchString(raw.notebookPath);
+    if (!notebookPath)
+        return null;
+    return {
+        notebookPath,
+        cellId: notebookResearchString(raw.cellId),
+        cellName: notebookResearchString(raw.cellName),
+        researchRunId: notebookResearchString(raw.researchRunId),
+        source: notebookResearchString(raw.source),
+    };
+}
+function notebookResearchSelectedContext(run, context) {
+    return {
+        activeSurface: 'notebook',
+        notebookPath: run.notebookPath,
+        domain: run.domain,
+        sourceCellId: run.sourceCellId,
+        sourceCellName: run.sourceCellName,
+        context,
+    };
+}
+function notebookResearchIntentPattern(intent) {
+    switch (intent) {
+        case 'diagnose_change':
+            return {
+                label: 'Change diagnosis',
+                dqlTarget: 'driver or trend block',
+                sqlFocus: ['baseline period', 'comparison period', 'metric delta', 'driver dimensions'],
+                reviewFocus: ['time grain', 'comparison filters', 'metric definition', 'explainability evidence'],
+            };
+        case 'driver_breakdown':
+            return {
+                label: 'Driver breakdown',
+                dqlTarget: 'ranking or contribution block',
+                sqlFocus: ['contribution metric', 'ranking', 'tie breaker', 'segment dimensions'],
+                reviewFocus: ['metric grain', 'ranking direction', 'parameterized filters', 'duplicate block match'],
+            };
+        case 'segment_compare':
+            return {
+                label: 'Segment compare',
+                dqlTarget: 'comparison block',
+                sqlFocus: ['shared metric', 'segment fields', 'normalized comparisons', 'deltas'],
+                reviewFocus: ['segment definitions', 'filter compatibility', 'comparison grain', 'semantic metric alignment'],
+            };
+        case 'entity_drilldown':
+            return {
+                label: 'Entity drilldown',
+                dqlTarget: 'entity profile or drilldown block',
+                sqlFocus: ['entity grain', 'stable identifier', 'detail fields', 'supporting metrics'],
+                reviewFocus: ['entity contract', 'primary key', 'allowed filters', 'downstream drill path'],
+            };
+        case 'anomaly_investigation':
+            return {
+                label: 'Anomaly investigation',
+                dqlTarget: 'monitoring or exception block',
+                sqlFocus: ['observed value', 'expected range', 'anomaly rule', 'supporting dimensions'],
+                reviewFocus: ['threshold definition', 'time window', 'false-positive risk', 'evidence fields'],
+            };
+        case 'trust_gap_review':
+            return {
+                label: 'Trust review',
+                dqlTarget: 'replacement or validation block',
+                sqlFocus: ['definition comparison', 'lineage trace', 'duplicate candidates', 'conflict evidence'],
+                reviewFocus: ['certified block match', 'semantic metric match', 'replacement reason', 'governance blockers'],
+            };
+        default:
+            return {
+                label: 'Ad hoc analysis',
+                dqlTarget: 'custom block',
+                sqlFocus: ['business question', 'grain', 'metrics', 'dimensions', 'filters'],
+                reviewFocus: ['reusability', 'parameterization', 'lineage evidence', 'DQL promotion path'],
+            };
+    }
+}
+function notebookResearchAgentPrompt(question, intent) {
+    const pattern = notebookResearchIntentPattern(intent);
+    const sqlFocus = Array.isArray(pattern.sqlFocus) ? pattern.sqlFocus.join(', ') : 'business logic';
+    const reviewFocus = Array.isArray(pattern.reviewFocus) ? pattern.reviewFocus.join(', ') : 'review evidence';
+    return [
+        `Research question: ${question}`,
+        `Research pattern: ${pattern.label ?? intent}`,
+        `DQL target: ${pattern.dqlTarget ?? 'custom block'}`,
+        `SQL focus: ${sqlFocus}`,
+        `Review focus: ${reviewFocus}`,
+        'Generate read-only SQL that can become a reusable, parameterized DQL block after human review.',
+    ].join('\n');
+}
+function notebookResearchRouteDecisionForRun(run, routeDecision, sqlForPreview) {
+    if (!routeDecision)
+        return undefined;
+    const hasSelectedNotebookSql = Boolean(run.sourceCellId && notebookResearchString(sqlForPreview));
+    if (!hasSelectedNotebookSql || routeDecision.route !== 'certified')
+        return routeDecision;
+    const certifiedEvidence = routeDecision.selectedEvidence.find((item) => item.role === 'exact_certified_answer')
+        ?? routeDecision.selectedEvidence.find((item) => item.role === 'certified_context');
+    const certifiedName = certifiedEvidence?.name ?? routeDecision.certifiedApplicability?.objectKey ?? 'matching certified artifact';
+    return {
+        ...routeDecision,
+        route: 'research',
+        trustLabel: routeDecision.trustLabel === 'certified' ? 'mixed' : routeDecision.trustLabel,
+        reviewStatus: 'needs_review',
+        exactObjectKey: undefined,
+        reason: `Selected notebook SQL from "${run.sourceCellName ?? run.sourceCellId}" is the source for this research run. Certified artifact "${certifiedName}" is duplicate/reuse evidence until the reviewed SQL, grain, parameters, and preview are accepted.`,
+        selectedEvidence: routeDecision.selectedEvidence.map((item) => item.role === 'exact_certified_answer'
+            ? {
+                ...item,
+                role: 'certified_context',
+                reason: 'Certified block is reuse or duplicate evidence for the selected notebook SQL; it is not an automatic answer for this research run.',
+            }
+            : item),
+        missingContext: routeDecision.missingContext.length > 0
+            ? routeDecision.missingContext
+            : [{
+                    kind: 'metadata',
+                    severity: 'warning',
+                    message: 'Selected notebook SQL requires human review before DQL promotion, even when certified context exists.',
+                }],
+    };
+}
+function notebookResearchContextPreview(contextPack) {
+    return {
+        contextPackId: contextPack.id,
+        trustLabel: contextPack.trustLabel,
+        routeDecision: contextPack.routeDecision
+            ? {
+                route: contextPack.routeDecision.route,
+                intent: contextPack.routeDecision.intent,
+                reason: contextPack.routeDecision.reason,
+            }
+            : undefined,
+        evidence: contextPack.evidenceRoles.slice(0, 16).map((item) => ({
+            objectKey: item.objectKey,
+            objectType: item.objectType,
+            name: item.name,
+            role: item.role,
+            reason: item.reason,
+        })),
+        summaries: contextPack.evidenceSummaries.slice(0, 12).map((item) => ({
+            title: item.title,
+            detail: item.detail,
+            objectType: item.objectType,
+            reason: item.reason,
+        })),
+        relations: contextPack.allowedSqlContext.relations.slice(0, 12).map((relation) => ({
+            relation: relation.relation,
+            name: relation.name,
+            source: relation.source,
+            columns: relation.columns.slice(0, 24).map((column) => {
+                if (typeof column === 'string')
+                    return column;
+                if (column && typeof column === 'object' && typeof column.name === 'string') {
+                    return String(column.name);
+                }
+                return String(column);
+            }),
+        })),
+        missingContext: contextPack.missingContext.slice(0, 12).map((item) => ({
+            kind: item.kind,
+            message: item.message,
+            severity: item.severity,
+        })),
+        warnings: contextPack.warnings.slice(0, 12),
+        topRejected: contextPack.retrievalDiagnostics.topRejected.slice(0, 8).map((item) => ({
+            name: item.name,
+            objectType: item.objectType,
+            reason: item.reason,
+            score: item.score,
+        })),
+        counts: {
+            objects: contextPack.objects.length,
+            evidence: contextPack.evidenceRoles.length,
+            relations: contextPack.allowedSqlContext.relations.length,
+            warnings: contextPack.warnings.length + contextPack.missingContext.length,
+        },
+    };
+}
+function normalizeNotebookAgentResult(result) {
+    const columns = Array.isArray(result.columns)
+        ? result.columns.map((column) => {
+            if (typeof column === 'string')
+                return column;
+            if (column && typeof column === 'object' && typeof column.name === 'string') {
+                return String(column.name);
+            }
+            return String(column);
+        })
+        : [];
+    const rows = Array.isArray(result.rows)
+        ? result.rows
+            .filter((row) => Boolean(row && typeof row === 'object' && !Array.isArray(row)))
+            .map((row) => row)
+        : [];
+    return {
+        columns,
+        rows,
+        rowCount: typeof result.rowCount === 'number' ? result.rowCount : rows.length,
+        executionTime: typeof result.executionTime === 'number' ? result.executionTime : 0,
+    };
+}
+function notebookResearchSummary(question, result, error) {
+    if (error)
+        return `Research could not preview results for "${question}". ${error}`;
+    if (result) {
+        const rowCount = result.rowCount ?? result.rows.length;
+        return `Research preview for "${question}" returned ${rowCount.toLocaleString()} row${rowCount === 1 ? '' : 's'} across ${result.columns.length.toLocaleString()} column${result.columns.length === 1 ? '' : 's'}.`;
+    }
+    return `Research plan created for "${question}". Add or generate SQL, then run a bounded preview.`;
+}
+function recordNotebookQueryRun(projectRoot, input) {
+    try {
+        recordQueryRun(projectRoot, {
+            objectKey: input.objectKey,
+            source: input.source,
+            status: input.status,
+            rowCount: input.rowCount,
+            durationMs: input.durationMs,
+            errorCode: input.errorCode,
+            payload: {
+                notebookPath: input.notebookPath,
+                cellId: input.cellId,
+                cellName: input.cellName,
+                researchRunId: input.researchRunId,
+                contextPackId: input.contextPackId,
+                sql: input.sql ? compactSqlForRunHistory(input.sql) : undefined,
+            },
+        });
+    }
+    catch {
+        // Query history is advisory metadata and must not block notebook execution.
+    }
+}
+function updateNotebookResearchFromCellExecution(projectRoot, execContext, input) {
+    if (!execContext.notebookPath || (!execContext.cellId && !execContext.researchRunId))
+        return;
+    const storage = new LocalNotebookResearchStorage(defaultNotebookResearchDbPath(projectRoot));
+    try {
+        const page = storage.listRunsPage({
+            notebookPath: execContext.notebookPath,
+            sort: 'updated_desc',
+            limit: 500,
+        });
+        const matches = page.runs.filter((run) => {
+            if (execContext.researchRunId && run.id === execContext.researchRunId)
+                return true;
+            return Boolean(execContext.cellId && run.sourceCellId === execContext.cellId);
+        });
+        const now = new Date().toISOString();
+        for (const run of matches.slice(0, 20)) {
+            if (input.status === 'success') {
+                storage.updateRun(run.id, {
+                    status: 'ready',
+                    resultPreview: input.resultPreview,
+                    summary: notebookResearchSummary(run.question, input.resultPreview, undefined),
+                    recommendation: run.recommendation ?? 'Review SQL, metadata evidence, grain, filters, and duplicate matches before DQL draft promotion.',
+                    error: '',
+                    lastRunAt: now,
+                });
+            }
+            else {
+                storage.updateRun(run.id, {
+                    status: 'error',
+                    error: input.error,
+                    summary: notebookResearchSummary(run.question, undefined, input.error),
+                    lastRunAt: now,
+                });
+            }
+        }
+    }
+    catch {
+        // Research run sync is advisory metadata and must not block notebook execution.
+    }
+    finally {
+        storage.close();
+    }
+}
+function compactSqlForRunHistory(sql) {
+    const clean = sql.replace(/\s+/g, ' ').trim();
+    return clean.length > 1200 ? `${clean.slice(0, 1197)}...` : clean;
+}
 function buildAgentSchemaContextFromContextPack(question, contextPack) {
     const byRelation = new Map();
     const objectsByKey = new Map(contextPack.objects.map((object) => [object.objectKey, object]));