@duckcodeailabs/dql-cli 1.6.21 → 1.6.22

package/dist/local-runtime.js

@@ -7,17 +7,18 @@ 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, queryBusiness360, 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, writeDomainDeclaration, deleteDomainDeclaration, domainFolderSlug, } 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, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildLocalContextPack, defaultMemoryPath, ensureDefaultMemoryFiles, ensureMetadataCatalogFresh, recordQueryRun, recordRuntimeSchemaSnapshot, } from '@duckcodeailabs/dql-agent';
-import { handleAppsApi, recommendVisualization } from './apps-api.js';
+import { ClaudeProvider, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildLocalContextPack, defaultMemoryPath, ensureDefaultMemoryFiles, ensureMetadataCatalogFresh, propose, proposePlan, recordCorrectionTrace, reviewHint, AgentRunEngine, FileAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, narrateResult, normalizeAnthropicBaseUrl, buildProposePreview, buildFromPrompt, defaultAgentRunStorePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, loadSkills, writeSkill, deleteSkill, reindexProject, defaultKgPath, planApp, planResearch, loadSemanticMetrics, } from '@duckcodeailabs/dql-agent';
+import { gatherProposeEnrichment } from './propose-enrich.js';
+import { createAppAiBuildSession, 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, LocalNotebookResearchStorage, defaultLocalAppsDbPath, defaultNotebookResearchDbPath } from '@duckcodeailabs/dql-project';
-import { Certifier, ENTERPRISE_RULES } from '@duckcodeailabs/dql-governance';
+import { Certifier, ENTERPRISE_RULES, evaluateInvariants, hasInvariantViolation, } from '@duckcodeailabs/dql-governance';
 import { buildSemanticObjectDetail, buildSemanticTree, computeSyncDiff, loadSemanticImportManifest, performSemanticImport, previewSemanticImport, syncSemanticImport, } from './semantic-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';
@@ -52,6 +53,82 @@ function hasDbtSemanticArtifacts(projectRoot, dbtProjectDir) {
     }
     return false;
 }
+const AGENT_RUN_REQUESTED_MODES = new Set(['auto', 'ask', 'research', 'sql', 'block', 'app']);
+const AGENT_RUN_SELECTED_OBJECT_KINDS = new Set([
+    'notebook',
+    'cell',
+    'block',
+    'app',
+    'dashboard',
+    'research',
+    'workspace',
+]);
+function agentRunRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function agentRunString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+function parseAgentRunRequestedMode(value) {
+    return typeof value === 'string' && AGENT_RUN_REQUESTED_MODES.has(value)
+        ? value
+        : undefined;
+}
+function parseAgentRunSelectedObject(value) {
+    const record = agentRunRecord(value);
+    if (!record)
+        return undefined;
+    const kind = agentRunString(record.kind);
+    if (!kind || !AGENT_RUN_SELECTED_OBJECT_KINDS.has(kind))
+        return undefined;
+    return {
+        kind: kind,
+        id: agentRunString(record.id),
+        title: agentRunString(record.title),
+        path: agentRunString(record.path),
+    };
+}
+function parseAgentRunHistory(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const history = value.flatMap((item) => {
+        const record = agentRunRecord(item);
+        if (!record)
+            return [];
+        const role = record.role === 'user' || record.role === 'assistant' ? record.role : undefined;
+        const text = agentRunString(record.text) ?? agentRunString(record.content);
+        return role && text ? [{ role, text }] : [];
+    });
+    return history.length > 0 ? history.slice(-20) : undefined;
+}
+function parseAgentRunRequestBody(body) {
+    const record = agentRunRecord(body);
+    if (!record)
+        return { error: 'Invalid JSON body.' };
+    const question = agentRunString(record.question) ?? agentRunString(record.prompt) ?? agentRunString(record.message);
+    if (!question)
+        return { error: 'question is required.' };
+    const selectedObject = parseAgentRunSelectedObject(record.selectedObject);
+    const workspaceContext = agentRunRecord(record.workspaceContext) ?? agentRunRecord(record.context);
+    const signals = agentRunRecord(record.signals);
+    const requestedMode = parseAgentRunRequestedMode(record.requestedMode) ?? parseAgentRunRequestedMode(record.mode);
+    const audience = record.audience === 'stakeholder' || record.audience === 'analyst'
+        ? record.audience
+        : undefined;
+    return {
+        request: {
+            question,
+            requestedMode,
+            audience,
+            intent: agentRunString(record.intent),
+            signals: signals,
+            selectedObject,
+            workspaceContext,
+            history: parseAgentRunHistory(record.history),
+            runId: agentRunString(record.runId),
+        },
+    };
+}
 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';
@@ -127,6 +204,582 @@ export async function startLocalServer(opts) {
         const result = await executor.executeQuery(prepared.sql, [], runtimeVariables({}), prepared.connection);
         return normalizeQueryResult(result, semantic.semanticRefs);
     };
+    const runBlockReflectionProbe = async ({ sql, invariants }) => {
+        const activeConnection = requireActiveConnection();
+        const prepared = prepareLocalExecution(sql, activeConnection, projectRoot, projectConfig);
+        const probeSql = `SELECT * FROM (${stripSqlTerminator(prepared.sql)}) _dql_probe LIMIT 2000`;
+        const probeResult = await executor.executeQuery(probeSql, [], runtimeVariables({}), prepared.connection);
+        const rows = (Array.isArray(probeResult?.rows) ? probeResult.rows : []);
+        const rawColumns = Array.isArray(probeResult?.columns)
+            ? probeResult.columns
+            : [];
+        const actualColumns = rawColumns.length > 0
+            ? rawColumns.map((c) => (typeof c === 'string' ? c : c?.name ?? String(c)))
+            : (rows[0] ? Object.keys(rows[0]) : []);
+        const invariantResults = evaluateInvariants(invariants, { columns: actualColumns, rows });
+        const passed = invariantResults.filter((r) => r.passed && !r.uncheckable).length;
+        const failed = invariantResults.filter((r) => !r.passed && !r.uncheckable).length;
+        return {
+            actualColumns,
+            invariantResults,
+            tests: invariants.length > 0
+                ? { passed, failed, assertionCount: invariantResults.length }
+                : undefined,
+        };
+    };
+    const agentRunWorkspaceValue = (request, key) => {
+        const workspace = request.workspaceContext ?? {};
+        const nested = agentRunRecord(workspace.context);
+        return agentRunString(workspace[key]) ?? (nested ? agentRunString(nested[key]) : undefined);
+    };
+    const agentRunNotebookPath = (request, runId) => (agentRunWorkspaceValue(request, 'notebookPath')
+        ?? (request.selectedObject?.kind === 'notebook' || request.selectedObject?.kind === 'cell' ? request.selectedObject.path : undefined)
+        ?? `notebooks/agent-research/${runId}.dqlnb`);
+    const agentRunResearchIntent = (request) => {
+        switch (request.intent) {
+            case 'diagnose_change':
+                return 'diagnose_change';
+            case 'driver_breakdown':
+                return 'driver_breakdown';
+            case 'segment_compare':
+                return 'segment_compare';
+            case 'entity_drilldown':
+                return 'entity_drilldown';
+            case 'anomaly_investigation':
+                return 'anomaly_investigation';
+            case 'trust_gap_review':
+                return 'trust_gap_review';
+            default:
+                if (/\b(driver|why|cause|contributor|breakdown)\b/i.test(request.question))
+                    return 'driver_breakdown';
+                if (/\b(anomaly|spike|drop|outlier)\b/i.test(request.question))
+                    return 'anomaly_investigation';
+                if (/\b(compare|segment|cohort)\b/i.test(request.question))
+                    return 'segment_compare';
+                return 'ad_hoc_analysis';
+        }
+    };
+    const agentRunSourceCell = (request) => {
+        const sourceCellId = agentRunWorkspaceValue(request, 'sourceCellId') ?? request.selectedObject?.id;
+        if (!sourceCellId)
+            return undefined;
+        return {
+            id: sourceCellId,
+            sourceCellId,
+            name: agentRunWorkspaceValue(request, 'sourceCellName') ?? request.selectedObject?.title,
+            sourceCellName: agentRunWorkspaceValue(request, 'sourceCellName') ?? request.selectedObject?.title,
+            type: agentRunWorkspaceValue(request, 'sourceCellType'),
+            sql: agentRunWorkspaceValue(request, 'cellSql'),
+            fingerprint: agentRunWorkspaceValue(request, 'sourceCellFingerprint'),
+        };
+    };
+    const agentRunTitle = (question, fallback) => {
+        const cleaned = question.replace(/\s+/g, ' ').trim();
+        if (!cleaned)
+            return fallback;
+        return cleaned.length > 90 ? `${cleaned.slice(0, 87)}...` : cleaned;
+    };
+    const parseAgentRunSelectedBlockIds = (request) => {
+        const workspace = request.workspaceContext ?? {};
+        const value = workspace.selectedBlockIds ?? workspace.blockIds;
+        if (!Array.isArray(value))
+            return [];
+        return Array.from(new Set(value.flatMap((item) => {
+            const id = agentRunString(item);
+            return id ? [id] : [];
+        })));
+    };
+    const formatAgentRunInfrastructureError = (error, scope) => {
+        const message = error instanceof Error ? error.message : String(error);
+        if (/Could not locate the bindings file/i.test(message) || /better[-_]sqlite3/i.test(message)) {
+            return `${scope} is unavailable because the local SQLite native bindings are not installed for this Node.js runtime.`;
+        }
+        return message;
+    };
+    const formatNotebookResearchStorageError = (error) => (formatAgentRunInfrastructureError(error, 'Notebook research storage'));
+    const buildAgentPromptArtifact = async (request, target, repair) => {
+        try {
+            await reindexProject(projectRoot, { kgPath: defaultKgPath(projectRoot) });
+        }
+        catch {
+            // Best-effort: buildFromPrompt can still use any existing KG/cache state.
+        }
+        const skills = loadSkills(projectRoot).skills;
+        // On a repair re-run, target the prior failure and (for blocks) revise in place.
+        const isRepair = (repair?.attempt ?? 0) > 0 && Boolean(repair?.repairHint);
+        const mode = target === 'block' && (isRepair || agentRunWorkspaceValue(request, 'mode') === 'edit')
+            ? 'edit'
+            : 'create';
+        const prompt = isRepair
+            ? `${request.question}\n\nFix the previous attempt: ${repair?.repairHint}`
+            : request.question;
+        return buildFromPrompt({
+            projectRoot,
+            prompt,
+            context: {
+                cellSql: agentRunWorkspaceValue(request, 'cellSql'),
+                selection: agentRunWorkspaceValue(request, 'selection'),
+            },
+            target,
+            mode,
+            blockPath: target === 'block'
+                ? agentRunWorkspaceValue(request, 'blockPath') ?? request.selectedObject?.path
+                : undefined,
+            owner: agentRunWorkspaceValue(request, 'owner'),
+            domain: target === 'block' ? agentRunWorkspaceValue(request, 'domain') : undefined,
+            userId: agentRunWorkspaceValue(request, 'userId'),
+            skills,
+            dbtManifestPath: resolveDbtManifestPath(projectRoot, projectConfig),
+            executionProbe: target === 'block' ? runBlockReflectionProbe : undefined,
+        });
+    };
+    const agentRunEvaluation = (id, label, passed, severity, message, evidence) => ({ id, label, passed, severity, message, evidence });
+    const agentRunArtifact = (kind, title, payload, ref, trustState = 'review_required') => ({
+        id: `${kind}:${Date.now()}`,
+        kind,
+        title,
+        trustState,
+        ref,
+        payload,
+    });
+    const coerceNarrateResultData = (value) => {
+        const record = agentRunRecord(value);
+        if (!record)
+            return undefined;
+        const columns = Array.isArray(record.columns)
+            ? record.columns.map((c) => (typeof c === 'string' ? c : agentRunRecord(c)?.name ?? String(c)))
+            : [];
+        const rows = Array.isArray(record.rows) ? record.rows.filter((r) => Boolean(agentRunRecord(r))) : [];
+        if (rows.length === 0)
+            return undefined;
+        return { columns: columns.length > 0 ? columns : Object.keys(rows[0]), rows };
+    };
+    // Provider-backed narration for stakeholder stories. Reuses the same provider
+    // adapter as the planner; narrateResult always returns (deterministic fallback).
+    const narrateForAgentRun = async (input) => narrateResult(input, {
+        complete: async ({ system, user, signal }) => {
+            const provider = await createBlockStudioAssistProvider(projectRoot);
+            if (!provider)
+                throw new Error('No AI provider configured for narration.');
+            return provider.generate([{ role: 'system', content: system }, { role: 'user', content: user }], { maxTokens: 600, temperature: 0.2, signal });
+        },
+    });
+    async function runGovernedAgentAnswerForRun(request, repair) {
+        const resolvedProvider = resolveDefaultLLMProvider(projectRoot);
+        const runner = resolvedProvider ? getLLMRunner(resolvedProvider) : null;
+        if (!resolvedProvider || !runner) {
+            throw new Error('No AI provider is configured. Configure OpenAI, Gemini, Ollama, or a custom OpenAI-compatible endpoint in Settings.');
+        }
+        let governedAnswer;
+        let providerError;
+        const isRepair = (repair?.attempt ?? 0) > 0 && Boolean(repair?.repairHint);
+        const contextEnvelope = {
+            mode: 'agent_run',
+            selectedObject: request.selectedObject,
+            workspaceContext: request.workspaceContext,
+            instruction: [
+                'Route through the governed DQL answer loop.',
+                'Prefer certified DQL blocks when they exactly cover the question.',
+                'Generated SQL remains review-required and must use the bounded preview executor.',
+                'If the question needs investigation, return the clearest answer and next review action without certifying generated work.',
+                ...(isRepair ? [`This is a repair attempt — fix the previous failure: ${repair?.repairHint}`] : []),
+            ].join(' '),
+        };
+        const controller = new AbortController();
+        await runner.run({
+            provider: resolvedProvider,
+            messages: [
+                ...(request.history ?? []).map((message) => ({ role: message.role, content: message.text })),
+                { role: 'user', content: isRepair ? `${request.question}\n\nFix the previous attempt: ${repair?.repairHint}` : request.question },
+            ],
+            upstream: {
+                cellId: `agent-run:${request.selectedObject?.kind ?? 'workspace'}:${request.selectedObject?.id ?? request.runId ?? 'auto'}`,
+                sql: JSON.stringify(contextEnvelope, null, 2),
+            },
+            projectRoot,
+            executeCertifiedBlock: executeCertifiedBlockForAgent,
+            executeGeneratedSql: executeGeneratedSqlForAgent,
+            getSchemaContext: getSchemaContextForAgent,
+        }, (turn) => {
+            if (turn.kind === 'tool_result' && turn.id === 'governed_answer') {
+                governedAnswer = turn.output;
+            }
+            if (turn.kind === 'error') {
+                providerError = turn.message;
+            }
+        }, controller.signal);
+        if (!governedAnswer) {
+            throw new Error(providerError ?? 'The AI provider did not return a governed answer.');
+        }
+        return governedAnswer;
+    }
+    const answerRunExecutor = async ({ request, routeDecision, attempt, repairHint }) => {
+        let governedAnswer;
+        try {
+            governedAnswer = await runGovernedAgentAnswerForRun(request, { attempt, repairHint });
+            // Surface the approved Hint-Graph corrections that shaped this answer so the
+            // UI can show an "applied learnings" chip (memoryContext is already on the answer).
+            if (!governedAnswer.appliedHints) {
+                governedAnswer.appliedHints = governedAnswer.contextPack?.appliedHints;
+            }
+        }
+        catch (error) {
+            const message = formatAgentRunInfrastructureError(error, 'AI answer provider');
+            return {
+                summary: message,
+                status: 'blocked',
+                trustState: 'blocked',
+                stopReason: 'blocked',
+                evaluations: [
+                    agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to governed answer.'),
+                    agentRunEvaluation('ai-provider', 'AI provider', false, 'blocking', message, { originalErrorType: error instanceof Error ? error.name : typeof error }),
+                ],
+                nextActions: [
+                    { id: 'retry-ask-after-provider', label: 'Retry after provider setup', route: 'generated_answer' },
+                    { id: 'research-without-answer', label: 'Research with available metadata', route: 'research', artifactKind: 'research_run' },
+                ],
+            };
+        }
+        const isCertified = governedAnswer.certification === 'certified' || governedAnswer.kind === 'certified';
+        const needsClarification = governedAnswer.kind === 'no_answer';
+        const sql = governedAnswer.proposedSql ?? governedAnswer.sql;
+        const status = needsClarification ? 'needs_clarification' : isCertified ? 'completed' : 'needs_review';
+        const trustState = needsClarification ? 'not_applicable' : isCertified ? 'certified' : 'review_required';
+        const stopReason = needsClarification ? 'needs_clarification' : isCertified ? 'certified_answer_found' : 'human_review_required';
+        const nextActions = needsClarification
+            ? [{ id: 'clarify', label: 'Clarify question', route: 'generated_answer' }]
+            : [
+                ...(sql ? [{ id: 'insert-sql', label: 'Insert SQL cell', route: 'sql_cell', artifactKind: 'sql_cell' }] : []),
+                { id: 'research-gap', label: 'Research deeper', route: 'research' },
+                { id: 'create-block', label: 'Create DQL draft', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
+            ];
+        return {
+            summary: governedAnswer.route?.label ?? (isCertified ? 'Answered from certified DQL context.' : 'Answered with review-required generated analysis.'),
+            answer: governedAnswer.answer ?? governedAnswer.text,
+            status,
+            trustState,
+            stopReason,
+            artifacts: needsClarification
+                ? []
+                : [agentRunArtifact('answer', isCertified ? 'Certified answer' : 'Review-required answer', governedAnswer, governedAnswer.sourceCertifiedBlock ?? governedAnswer.block?.name, isCertified ? 'certified' : 'review_required')],
+            evaluations: [
+                agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to governed answer.'),
+                agentRunEvaluation('trust-boundary', 'Trust boundary', isCertified, isCertified ? 'info' : 'warning', isCertified
+                    ? 'The answer came from certified DQL context.'
+                    : needsClarification
+                        ? 'The answer loop needs more context before producing a governed answer.'
+                        : 'The answer is generated or semantic-layer backed and remains review-required.', governedAnswer.route),
+                ...(governedAnswer.executionError ? [
+                    agentRunEvaluation('execution-error', 'Execution error', false, 'warning', governedAnswer.executionError),
+                ] : []),
+            ],
+            nextActions,
+        };
+    };
+    const agentRunExecutors = {
+        certified_answer: answerRunExecutor,
+        generated_answer: answerRunExecutor,
+        research: async ({ runId, request, routeDecision, emit }) => {
+            const metrics = loadSemanticMetrics(projectRoot);
+            let blocks = collectPlanBlocks(projectRoot, { certifiedOnly: true });
+            const usedCertifiedOnly = blocks.length > 0;
+            if (blocks.length === 0)
+                blocks = collectPlanBlocks(projectRoot, { certifiedOnly: false });
+            emit({
+                type: 'executor.started',
+                message: 'Building catalog-grounded research plan.',
+                route: 'research',
+            });
+            const plan = await planResearch({
+                question: request.question,
+                metrics,
+                blocks,
+                intent: request.intent,
+                isFollowUp: Boolean(request.history?.length),
+                history: request.history,
+            });
+            const needsClarification = Boolean(plan.followUp);
+            const notebookPath = agentRunNotebookPath(request, runId);
+            const researchIntent = agentRunResearchIntent(request);
+            let researchRun;
+            let researchWorkspaceError;
+            if (!needsClarification) {
+                try {
+                    const storage = openNotebookResearchStorage();
+                    try {
+                        const sourceCell = agentRunSourceCell(request);
+                        const sourceCellId = notebookResearchSourceCellId(sourceCell);
+                        const sourceCellName = notebookResearchSourceCellName(sourceCell);
+                        const sourceCellFingerprint = notebookResearchSourceCellFingerprint(sourceCell);
+                        const created = storage.createRun({
+                            notebookPath,
+                            title: agentRunTitle(request.question, 'Agent research'),
+                            question: request.question,
+                            sourceCell,
+                            sourceCellId,
+                            sourceCellName,
+                            sourceCellFingerprint,
+                            intent: researchIntent,
+                            domain: agentRunWorkspaceValue(request, 'domain'),
+                            owner: agentRunWorkspaceValue(request, 'owner'),
+                            context: {
+                                surface: 'unified_agent_run',
+                                agentRunId: runId,
+                                routeDecision,
+                                selectedObject: request.selectedObject,
+                                workspaceContext: request.workspaceContext,
+                                plan,
+                            },
+                        });
+                        emit({
+                            type: 'artifact.created',
+                            message: 'Saved notebook research workspace record.',
+                            route: 'research',
+                            trustState: 'review_required',
+                            payload: { researchRunId: created.id, notebookPath },
+                        });
+                        const executed = await runNotebookResearch(storage, created, {
+                            domain: agentRunWorkspaceValue(request, 'domain'),
+                            owner: agentRunWorkspaceValue(request, 'owner'),
+                            sourceCellFingerprint,
+                            question: request.question,
+                            intent: researchIntent,
+                            context: {
+                                surface: 'unified_agent_run',
+                                agentRunId: runId,
+                                routeDecision,
+                                selectedObject: request.selectedObject,
+                                workspaceContext: request.workspaceContext,
+                                plan,
+                            },
+                        });
+                        researchRun = withNotebookResearchChecklist(executed);
+                    }
+                    finally {
+                        storage.close();
+                    }
+                }
+                catch (error) {
+                    researchWorkspaceError = formatNotebookResearchStorageError(error);
+                }
+            }
+            const researchResultData = coerceNarrateResultData(researchRun?.resultPreview);
+            const narration = !needsClarification && researchResultData
+                ? await narrateForAgentRun({
+                    question: request.question,
+                    intent: request.intent,
+                    result: researchResultData,
+                    evidence: plan.sources,
+                    reviewRequired: true,
+                })
+                : undefined;
+            const summary = needsClarification
+                ? 'Needs clarification before running deeper research.'
+                : narration?.summary
+                    ?? (researchRun?.status === 'ready'
+                        ? 'Saved a grounded research dossier with context evidence and next review actions.'
+                        : researchRun?.status === 'error'
+                            ? 'Saved a research dossier, but the preview needs review before promotion.'
+                            : researchWorkspaceError
+                                ? 'Prepared a grounded research plan; durable research storage is unavailable in this runtime.'
+                                : plan.done
+                                    ? 'Prepared a direct grounded-answer plan.'
+                                    : 'Prepared a grounded research plan over real DQL assets.');
+            return {
+                summary,
+                answer: plan.followUp?.question ?? narration?.summary ?? researchRun?.summary,
+                status: needsClarification ? 'needs_clarification' : 'needs_review',
+                trustState: needsClarification ? 'not_applicable' : 'review_required',
+                stopReason: needsClarification ? 'needs_clarification' : 'human_review_required',
+                artifacts: needsClarification
+                    ? []
+                    : [agentRunArtifact('research_run', 'Research plan', {
+                            plan,
+                            researchRun,
+                            researchRunId: researchRun?.id,
+                            notebookPath,
+                            workspaceError: researchWorkspaceError,
+                            routeDecision,
+                            narration,
+                            resultPreview: researchResultData,
+                            blockCount: blocks.length,
+                            metricCount: metrics.length,
+                            certifiedOnly: usedCertifiedOnly,
+                        }, researchRun?.id)],
+                evaluations: [
+                    agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to research.'),
+                    agentRunEvaluation('catalog-grounding', 'Catalog grounding', plan.sources.length > 0 || Boolean(researchRun?.evidence), plan.sources.length > 0 || Boolean(researchRun?.evidence) ? 'info' : 'warning', plan.sources.length > 0 || Boolean(researchRun?.evidence)
+                        ? 'Research dossier is grounded to catalog or context-pack evidence.'
+                        : 'No certified catalog source was found; output remains exploratory.', { sources: plan.sources, researchRunId: researchRun?.id, evidence: researchRun?.evidence }),
+                    agentRunEvaluation('research-workspace', 'Research workspace', Boolean(researchRun?.id), researchRun?.id ? 'info' : 'warning', researchRun?.id
+                        ? 'A durable notebook research record was saved for review and DQL promotion.'
+                        : researchWorkspaceError
+                            ? 'Research workspace storage is unavailable; the plan remains available in this agent run.'
+                            : 'No durable research record was created because the run needs clarification first.', { notebookPath, researchRunId: researchRun?.id, error: researchWorkspaceError }),
+                ],
+                nextActions: needsClarification
+                    ? [{ id: 'answer-follow-up', label: 'Answer follow-up', route: 'research' }]
+                    : [
+                        ...(researchRun?.id ? [{ id: 'open-research', label: 'Open research dossier', artifactKind: 'research_run' }] : []),
+                        ...(researchRun?.generatedSql || researchRun?.reviewedSql ? [{ id: 'insert-sql', label: 'Insert SQL cell', route: 'sql_cell', artifactKind: 'sql_cell' }] : []),
+                        { id: 'create-block', label: 'Create DQL draft', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
+                    ],
+            };
+        },
+        sql_cell: async ({ request, routeDecision, attempt, repairHint }) => {
+            const result = await buildAgentPromptArtifact(request, 'cell', { attempt, repairHint });
+            return {
+                summary: 'Created a review-required SQL cell draft.',
+                answer: result.target === 'cell' ? result.explanation : undefined,
+                artifacts: [agentRunArtifact('sql_cell', 'Generated SQL cell', result)],
+                evaluations: [
+                    agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to SQL cell generation.'),
+                    agentRunEvaluation('review-boundary', 'Review boundary', true, 'warning', 'Generated SQL must be reviewed before it becomes certified analytics.'),
+                ],
+                nextActions: [
+                    { id: 'insert-sql', label: 'Insert SQL cell', artifactKind: 'sql_cell' },
+                    { id: 'create-block', label: 'Promote to DQL draft', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
+                ],
+            };
+        },
+        dql_block_draft: async ({ request, routeDecision, attempt, repairHint }) => {
+            const result = await buildAgentPromptArtifact(request, 'block', { attempt, repairHint });
+            const ready = result.target === 'block' ? result.certifierVerdict.ready : false;
+            return {
+                summary: ready
+                    ? 'Created a DQL block draft that is ready for human certification review.'
+                    : 'Created a DQL block draft with review blockers or warnings.',
+                artifacts: [agentRunArtifact('dql_block_draft', result.target === 'block' ? result.name : 'DQL block draft', result, result.target === 'block' ? result.path : undefined)],
+                evaluations: [
+                    agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to DQL block draft generation.'),
+                    agentRunEvaluation('certification-boundary', 'Certification boundary', ready, 'warning', ready
+                        ? 'The draft has no automatic certifier blockers, but certification still requires human review.'
+                        : 'The draft has certifier blockers that must be resolved before certification review.', result),
+                ],
+                nextActions: [
+                    { id: 'open-review', label: 'Open review checklist', artifactKind: 'dql_block_draft' },
+                    { id: 'build-app', label: 'Build app from block', route: 'app_build', artifactKind: 'app_draft' },
+                ],
+            };
+        },
+        app_build: async ({ request, routeDecision, emit }) => {
+            emit({
+                type: 'executor.started',
+                message: 'Creating app build session from governed app builder.',
+                route: 'app_build',
+            });
+            let session;
+            try {
+                session = await createAppAiBuildSession(projectRoot, {
+                    prompt: request.question,
+                    domain: agentRunWorkspaceValue(request, 'domain'),
+                    owner: agentRunWorkspaceValue(request, 'owner'),
+                    notebookPath: agentRunWorkspaceValue(request, 'notebookPath') ?? request.selectedObject?.path,
+                    selectedBlockIds: parseAgentRunSelectedBlockIds(request),
+                    plannerMode: 'deterministic',
+                });
+            }
+            catch (error) {
+                const message = formatAgentRunInfrastructureError(error, 'App build storage');
+                return {
+                    summary: message,
+                    status: 'blocked',
+                    trustState: 'blocked',
+                    stopReason: 'blocked',
+                    evaluations: [
+                        agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to app build.'),
+                        agentRunEvaluation('app-build-storage', 'App build storage', false, 'blocking', message, { originalErrorType: error instanceof Error ? error.name : typeof error }),
+                    ],
+                    nextActions: [
+                        { id: 'research-coverage', label: 'Research missing coverage', route: 'research', artifactKind: 'research_run' },
+                        { id: 'create-gap-blocks', label: 'Create DQL drafts for gaps', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
+                    ],
+                };
+            }
+            const ready = session.status === 'ready';
+            const sessionPlan = agentRunRecord(session.plan);
+            const appTitle = agentRunString(sessionPlan?.name) ?? 'App draft';
+            // A coverage gap is NOT terminal — leave status open so the gate can escalate to
+            // drafting the missing blocks. Only genuine infra errors (the catch above) block.
+            return {
+                summary: ready
+                    ? 'Created a review-required app draft session from certified DQL assets.'
+                    : 'App build needs more certified DQL coverage before files can be generated.',
+                status: ready ? 'needs_review' : undefined,
+                trustState: ready ? 'review_required' : undefined,
+                stopReason: ready ? 'human_review_required' : undefined,
+                artifacts: ready ? [agentRunArtifact('app_draft', appTitle, {
+                        session,
+                        sessionId: session.id,
+                        appId: session.appId,
+                        dashboardId: session.dashboardId,
+                        generatedPaths: session.generatedPaths,
+                        plan: session.plan,
+                        validation: session.validation,
+                    }, session.appId)] : [],
+                evaluations: [
+                    agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to app build.'),
+                    agentRunEvaluation('app-coverage', 'Certified coverage', ready, ready ? 'info' : 'blocking', ready
+                        ? 'Generated app files are backed by certified block tiles and saved as a draft app session.'
+                        : session.error ?? 'No certified app tiles matched the request.', session),
+                ],
+                nextActions: ready
+                    ? [
+                        { id: 'open-app', label: 'Open app draft', artifactKind: 'app_draft' },
+                        { id: 'create-gap-blocks', label: 'Create DQL drafts for gaps', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
+                    ]
+                    : [
+                        { id: 'research-coverage', label: 'Research missing coverage', route: 'research', artifactKind: 'research_run' },
+                        { id: 'create-gap-blocks', label: 'Create DQL drafts for gaps', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
+                    ],
+            };
+        },
+    };
+    // Compact, catalog-grounded context the LLM planner decomposes `auto` turns against.
+    const buildAgentRunCatalogContext = () => {
+        try {
+            const blocks = collectPlanBlocks(projectRoot, { certifiedOnly: true });
+            const sourceBlocks = blocks.length > 0 ? blocks : collectPlanBlocks(projectRoot, { certifiedOnly: false });
+            const blockLines = sourceBlocks.slice(0, 24).map((block) => {
+                const domain = block.domain ? ` [${block.domain}]` : '';
+                const detail = block.description ? `: ${block.description}` : '';
+                return `- ${block.name}${domain}${detail}`;
+            });
+            const metrics = loadSemanticMetrics(projectRoot).slice(0, 24);
+            const metricLines = metrics.map((metric) => {
+                const node = metric;
+                return `- ${node.name ?? node.label ?? node.id ?? 'metric'}`;
+            });
+            return [
+                blockLines.length > 0 ? `Available DQL blocks:\n${blockLines.join('\n')}` : 'Available DQL blocks: none',
+                metricLines.length > 0 ? `Governed metrics:\n${metricLines.join('\n')}` : '',
+            ].filter(Boolean).join('\n\n');
+        }
+        catch {
+            return '';
+        }
+    };
+    // Provider-agnostic completion the planner injects. Reuses the configured provider
+    // adapter; throwing here makes the planner fall back to its deterministic path.
+    const agentRunPlanner = createLlmAgentRunPlanner({
+        complete: async ({ system, user, signal }) => {
+            const provider = await createBlockStudioAssistProvider(projectRoot);
+            if (!provider)
+                throw new Error('No AI provider configured for planning.');
+            return provider.generate([
+                { role: 'system', content: system },
+                { role: 'user', content: user },
+            ], { maxTokens: 700, temperature: 0.1, signal });
+        },
+        getCatalogContext: buildAgentRunCatalogContext,
+    });
+    const agentRunStore = new FileAgentRunStore({ path: defaultAgentRunStorePath(projectRoot) });
+    const agentRunEngine = new AgentRunEngine({
+        store: agentRunStore,
+        executors: agentRunExecutors,
+        gates: defaultAgentRunGates,
+        planner: agentRunPlanner,
+    });
     const runNotebookForApp = async (appId, notebookPath) => {
         const absPath = safeJoin(projectRoot, notebookPath);
         if (!absPath || !existsSync(absPath) || statSync(absPath).isDirectory() || !absPath.endsWith('.dqlnb')) {
@@ -390,6 +1043,87 @@ export async function startLocalServer(opts) {
         };
     };
     const openNotebookResearchStorage = () => new LocalNotebookResearchStorage(defaultNotebookResearchDbPath(projectRoot));
+    const notebookResearchStorageUnavailableMessage = 'Notebook research storage is unavailable because the local SQLite native bindings are not installed for this Node.js runtime.';
+    const notebookResearchNextActionFilters = [
+        'fix_blockers',
+        'review_sql',
+        'review_context',
+        'run_preview',
+        'reuse_existing',
+        'create_dql_draft',
+        'open_certification',
+        'complete_review',
+        'continue_review',
+    ];
+    const isNotebookResearchStorageUnavailable = (error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        return /better[-_]sqlite3/i.test(message) || /Could not locate the bindings file/i.test(message);
+    };
+    const emptyNotebookResearchNextActionCounts = () => Object.fromEntries(notebookResearchNextActionFilters.map((action) => [action, 0]));
+    const emptyNotebookResearchListPage = (input = {}) => ({
+        runs: [],
+        total: 0,
+        domains: [],
+        owners: [],
+        intents: [],
+        notebooks: [],
+        counts: {
+            total: 0,
+            ready: 0,
+            needsReview: 0,
+            dqlDrafts: 0,
+            errors: 0,
+            reuseExisting: 0,
+            extendExisting: 0,
+            replacements: 0,
+            createNew: 0,
+            draftReady: 0,
+            certificationReady: 0,
+            blocked: 0,
+            staleOpen: 0,
+            expiredOpen: 0,
+            sourceLinked: 0,
+            nextActions: emptyNotebookResearchNextActionCounts(),
+        },
+        groupCounts: {
+            domains: 0,
+            owners: 0,
+            intents: 0,
+            notebooks: 0,
+        },
+        limit: input.limit,
+        offset: input.offset ?? 0,
+    });
+    const emptyNotebookResearchDiagnostics = () => ({
+        counts: {
+            totalRuns: 0,
+            activeRuns: 0,
+            closedRuns: 0,
+            notebooks: 0,
+            domains: 0,
+            owners: 0,
+            sourceLinkedRuns: 0,
+        },
+        health: {
+            staleOpenRuns: 0,
+            expiredOpenRuns: 0,
+            staleThresholdDays: 7,
+            expiredThresholdDays: 30,
+        },
+        search: {
+            indexed: false,
+            indexRows: 0,
+            stale: false,
+        },
+        updatedAt: {},
+        limits: {
+            pageSize: 50,
+            maxPageSize: 500,
+            sourceCoverageLimit: 10_000,
+            seedCellLimit: 1000,
+        },
+        warnings: [notebookResearchStorageUnavailableMessage],
+    });
     const runNotebookResearch = async (storage, run, input = {}) => {
         const question = notebookResearchString(input.question) || run.question;
         const domain = notebookResearchString(input.domain) ?? run.domain;
@@ -966,7 +1700,19 @@ export async function startLocalServer(opts) {
         if (tests.length === 0) {
             return { passed: 0, failed: 0, skipped: 0, duration: Date.now() - start, assertions: [], runAt: new Date() };
         }
-        const prepared = prepareLocalExecution(plan.sql, activeConnection, projectRoot, projectConfig);
+        // Run tests against the SAME SQL the preview runs: for a semantic block with a
+        // pre-compiled query, that's the query (not a recompiled metric), so the test's
+        // output columns match the block's declared outputs.
+        const semanticCompose = semanticLayer
+            ? composeSemanticBlockSql(source, semanticLayer, {
+                driver: activeConnection.driver,
+                tableMapping,
+                projectRoot,
+                projectConfig,
+                detectedProvider: semanticDetectedProvider,
+            })
+            : null;
+        const prepared = prepareLocalExecution(semanticCompose?.sql ?? plan.sql, activeConnection, projectRoot, projectConfig);
         const rawResult = await executor.executeQuery(prepared.sql, plan.sqlParams ?? [], runtimeVariables(plan.variables ?? {}), prepared.connection);
         const rows = Array.isArray(rawResult?.rows) ? rawResult.rows : [];
         const columns = Array.isArray(rawResult?.columns)
@@ -1100,12 +1846,25 @@ export async function startLocalServer(opts) {
             sourceSystems: parsed.sourceSystems,
             replacementFor: parsed.replacementFor,
             reviewCadence: parsed.reviewCadence,
+            metricRef: parsed.metricRef || undefined,
+            metricsRef: parsed.metricsRef.length > 0 ? parsed.metricsRef : undefined,
             dependencies: [],
             usedInCount: 0,
             createdAt: new Date(),
             updatedAt: new Date(),
         };
-        const certification = new Certifier(options.enterprise ? ENTERPRISE_RULES : undefined).evaluate(record, testResults ?? undefined);
+        // Evaluate declared invariants against the preview result so the
+        // `invariants-hold` certifier rule can enforce them. Best-effort: when the
+        // preview failed there is no result to check, and the rule then blocks
+        // certification (in enterprise mode) because the guarantees are unverified.
+        const invariantEval = preview
+            ? evaluateBlockInvariants(source, {
+                columns: preview.result.columns,
+                rows: preview.result.rows,
+            })
+            : null;
+        record.invariants = extractBlockInvariants(source);
+        const certification = new Certifier(options.enterprise ? ENTERPRISE_RULES : undefined).evaluate(record, testResults ?? undefined, invariantEval ? { invariantResults: invariantEval.invariantResults } : undefined);
         const checklist = buildBlockStudioCertificationChecklist({
             source,
             validation,
@@ -1114,7 +1873,19 @@ export async function startLocalServer(opts) {
             certificationErrors: certification.errors,
             extraBlockers: blockers,
         });
-        return { certification, checklist, validation, preview, testResults };
+        return {
+            certification,
+            checklist,
+            validation,
+            preview,
+            testResults,
+            invariantResults: invariantEval?.invariantResults ?? [],
+            invariantViolation: invariantEval?.invariantViolation ?? false,
+        };
+    };
+    const writeAgentRunSse = (response, event, data) => {
+        response.write(`event: ${event}\n`);
+        response.write(`data: ${serializeJSON(data)}\n\n`);
     };
     const server = createServer(async (req, res) => {
         const requestUrl = req.url || '/';
@@ -1129,9 +1900,532 @@ export async function startLocalServer(opts) {
             res.end();
             return;
         }
-        if (req.method === 'GET' && path === '/api/health') {
-            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
-            res.end(serializeJSON({ status: 'ok' }));
+        if (req.method === 'GET' && path === '/api/health') {
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({ status: 'ok' }));
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/agent-runs') {
+            const rawLimit = Number(url.searchParams.get('limit'));
+            const limit = Number.isFinite(rawLimit) && rawLimit > 0
+                ? Math.min(200, Math.floor(rawLimit))
+                : 50;
+            const runs = agentRunStore
+                .list()
+                .sort((a, b) => b.startedAt.localeCompare(a.startedAt))
+                .slice(0, limit);
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({ runs, total: agentRunStore.list().length, limit }));
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/agent-runs') {
+            try {
+                const body = await readJSON(req).catch(() => null);
+                const parsed = parseAgentRunRequestBody(body);
+                if (!parsed.request) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: parsed.error ?? 'Invalid agent run request.' }));
+                    return;
+                }
+                const wantsStream = url.searchParams.get('stream') === '1' || url.searchParams.get('stream') === 'true';
+                if (wantsStream) {
+                    res.writeHead(200, {
+                        'Content-Type': 'text/event-stream; charset=utf-8',
+                        'Cache-Control': 'no-cache',
+                        'Connection': 'keep-alive',
+                        'X-Accel-Buffering': 'no',
+                    });
+                    const run = await agentRunEngine.run(parsed.request, (event) => {
+                        writeAgentRunSse(res, 'agent-run-event', event);
+                    });
+                    writeAgentRunSse(res, 'agent-run-complete', run);
+                    res.end();
+                    return;
+                }
+                const run = await agentRunEngine.run(parsed.request);
+                res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ run }));
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (res.headersSent) {
+                    writeAgentRunSse(res, 'agent-run-error', { error: message });
+                    res.end();
+                }
+                else {
+                    res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: message }));
+                }
+            }
+            return;
+        }
+        // Stakeholder → analyst handoff: turn a review-required output into a draft
+        // research run in the analyst notebook queue (no authoring by the stakeholder).
+        if (req.method === 'POST' && path === '/api/agent-runs/request-certification') {
+            try {
+                const body = await readJSON(req).catch(() => null);
+                const record = agentRunRecord(body);
+                const question = record ? agentRunString(record.question) : undefined;
+                if (!question) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ ok: false, error: 'question is required.' }));
+                    return;
+                }
+                const notebookPath = (record && agentRunString(record.notebookPath))
+                    ?? `notebooks/certification-requests/${Date.now()}.dqlnb`;
+                const generatedSql = record ? agentRunString(record.generatedSql) : undefined;
+                try {
+                    const storage = openNotebookResearchStorage();
+                    try {
+                        const created = storage.createRun({
+                            notebookPath,
+                            title: agentRunTitle(question, 'Certification request'),
+                            question,
+                            intent: 'ad_hoc_analysis',
+                            domain: record ? agentRunString(record.domain) : undefined,
+                            owner: record ? agentRunString(record.owner) : undefined,
+                            generatedSql,
+                            context: {
+                                surface: 'stakeholder_request_certification',
+                                requestedContext: agentRunRecord(record?.context) ?? null,
+                            },
+                        });
+                        res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ ok: true, researchRunId: created.id, notebookPath }));
+                    }
+                    finally {
+                        storage.close();
+                    }
+                }
+                catch (error) {
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ ok: false, error: formatNotebookResearchStorageError(error) }));
+                }
+            }
+            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;
+        }
+        const agentRunMatch = /^\/api\/agent-runs\/([^/]+)$/.exec(path);
+        if (req.method === 'GET' && agentRunMatch) {
+            const id = decodeURIComponent(agentRunMatch[1]);
+            const run = await agentRunStore.get(id);
+            if (!run) {
+                res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: 'Agent run not found.' }));
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({ run }));
+            return;
+        }
+        // Readiness → propose backbone. Returns a readiness summary plus the ranked
+        // DRAFT proposals (each with its stored Certifier verdict) so the notebook
+        // "Get Started" surface can route them into human review. dryRun preview —
+        // nothing is written or certified by this call.
+        if ((req.method === 'GET' || req.method === 'POST') && path === '/api/propose') {
+            try {
+                let owner;
+                let limit;
+                if (req.method === 'POST') {
+                    const body = await readJSON(req).catch(() => ({}));
+                    if (typeof body?.owner === 'string')
+                        owner = body.owner;
+                    if (typeof body?.limit === 'number' && Number.isFinite(body.limit) && body.limit > 0) {
+                        limit = body.limit;
+                    }
+                }
+                else {
+                    const ownerParam = url.searchParams.get('owner');
+                    if (ownerParam)
+                        owner = ownerParam;
+                    const limitParam = Number(url.searchParams.get('limit'));
+                    if (Number.isFinite(limitParam) && limitParam > 0)
+                        limit = limitParam;
+                }
+                const readiness = buildProposeReadiness(projectRoot, loadProjectConfig(projectRoot), { owner, limit });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(readiness));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // Deterministic PLAN only (classify → plan). Writes NOTHING. Same data the
+        // readiness endpoint embeds, exposed standalone for the approve gate.
+        if (req.method === 'POST' && path === '/api/propose/plan') {
+            try {
+                const readiness = buildProposeReadiness(projectRoot, loadProjectConfig(projectRoot));
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(readiness.ready ? readiness.plan : { ready: false, reason: readiness.reason }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // Materialize drafts for an APPROVED scope { slugs } (or { domains }).
+        // This is the only propose endpoint that writes — and only for the approved,
+        // business-only selection. Nothing is ever certified.
+        if (req.method === 'POST' && path === '/api/propose/generate') {
+            try {
+                const body = (await readJSON(req).catch(() => ({})));
+                const config = loadProjectConfig(projectRoot);
+                let slugs = Array.isArray(body?.slugs)
+                    ? body.slugs.filter((s) => typeof s === 'string')
+                    : [];
+                // { domains } → resolve to the plan's slugs for those domains.
+                if (slugs.length === 0 && Array.isArray(body?.domains)) {
+                    const wanted = new Set(body.domains.filter((d) => typeof d === 'string'));
+                    const readiness = buildProposeReadiness(projectRoot, config);
+                    slugs = readiness.ready
+                        ? readiness.plan.domains
+                            .filter((d) => wanted.has(d.name))
+                            .flatMap((d) => d.candidates.map((c) => c.slug))
+                        : [];
+                }
+                if (slugs.length === 0) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Provide a non-empty { slugs } or { domains } scope to generate.' }));
+                    return;
+                }
+                const owner = typeof body?.owner === 'string' ? body.owner : undefined;
+                const result = await generateProposeDrafts(projectRoot, slugs, config, { owner });
+                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;
+        }
+        // Materialize a single approved draft { slug } and return it. Convenience for
+        // the per-block "Review & Certify" affordance.
+        if (req.method === 'POST' && path === '/api/propose/draft') {
+            try {
+                const body = (await readJSON(req).catch(() => ({})));
+                const slug = typeof body?.slug === 'string' ? body.slug : '';
+                if (!slug) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Provide { slug } to draft.' }));
+                    return;
+                }
+                const owner = typeof body?.owner === 'string' ? body.owner : undefined;
+                const result = await generateProposeDrafts(projectRoot, [slug], loadProjectConfig(projectRoot), { owner });
+                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;
+        }
+        // Transparent PLAN PREVIEW for ONE candidate (spec 14, part A). Lazy +
+        // expensive: builds the real SQL + Certifier verdict + best-effort AI
+        // enrichment for a single slug, so the UI shows the actual logic before a
+        // human commits. Writes NOTHING.
+        if (req.method === 'GET' && path === '/api/propose/preview') {
+            try {
+                const slug = url.searchParams.get('slug')?.trim();
+                if (!slug) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Provide a ?slug= query parameter.' }));
+                    return;
+                }
+                const candidate = await buildProposeCandidatePreview(projectRoot, slug, url.searchParams.get('owner') ?? undefined);
+                if (!candidate) {
+                    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: `No proposed candidate found for slug "${slug}".` }));
+                    return;
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ candidate }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // Unified AI BUILD (spec 14, part B). ONE engine, two targets:
+        //   target:'cell'  → generate SQL from the prompt (+ context). Writes nothing.
+        //   target:'block' → assemble a COMPLETE draft, WRITE it, return preview fields.
+        // Never routes through the governed Q&A answer-loop.
+        if (req.method === 'POST' && path === '/api/ai/build') {
+            try {
+                const body = (await readJSON(req).catch(() => ({})));
+                const prompt = typeof body?.prompt === 'string' ? body.prompt.trim() : '';
+                if (!prompt) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Provide a non-empty { prompt }.' }));
+                    return;
+                }
+                const target = body?.target === 'cell' || body?.target === 'block' ? body.target : undefined;
+                if (!target) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: "Provide { target: 'cell' | 'block' }." }));
+                    return;
+                }
+                const context = {
+                    cellSql: typeof body?.context?.cellSql === 'string' ? body.context.cellSql : undefined,
+                    selection: typeof body?.context?.selection === 'string' ? body.context.selection : undefined,
+                };
+                const owner = typeof body?.owner === 'string' ? body.owner : undefined;
+                const userId = typeof body?.userId === 'string'
+                    ? body.userId
+                    : undefined;
+                // Edit mode (spec 17, part A): modify the block at `blockPath` in place.
+                const mode = body?.mode === 'edit' ? 'edit' : 'create';
+                const blockPath = typeof body?.blockPath === 'string' && body.blockPath.trim()
+                    ? body.blockPath.trim()
+                    : undefined;
+                if (mode === 'edit' && (target !== 'block' || !blockPath)) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: "Edit mode requires target 'block' and a { blockPath }." }));
+                    return;
+                }
+                // Ensure the agent knowledge graph is built before generating, so the Build
+                // path's semantic-metric routing sees the governed metrics on the very first
+                // call (a cold Build-before-Ask otherwise reads an unbuilt KG and misses them).
+                // Mirrors what the Ask path does; reindex is idempotent and closes its write
+                // connection, so the read-only metric load observes committed data.
+                try {
+                    await reindexProject(projectRoot, { kgPath: defaultKgPath(projectRoot) });
+                }
+                catch {
+                    // Best-effort: a failed reindex falls back to whatever KG exists (or none).
+                }
+                // Inject user-authored Skills as business context; the engine selects the
+                // relevant subset and stamps `appliedSkills` on the result.
+                const skills = loadSkills(projectRoot).skills;
+                const result = await buildFromPrompt({
+                    projectRoot,
+                    prompt,
+                    context,
+                    target,
+                    mode,
+                    blockPath,
+                    owner,
+                    userId,
+                    skills,
+                    dbtManifestPath: resolveDbtManifestPath(projectRoot, loadProjectConfig(projectRoot)),
+                    // Reflect-before-certify probe (P2): run the candidate block's SQL to learn
+                    // its REAL output columns and evaluate the declared invariants, so the agent
+                    // can reconcile the output contract + produce a grounded verdict before a
+                    // human reviews. Best-effort — buildFromPrompt falls back to a static reflection.
+                    executionProbe: async ({ sql, invariants }) => {
+                        const activeConnection = requireActiveConnection();
+                        const prepared = prepareLocalExecution(sql, activeConnection, projectRoot, projectConfig);
+                        const probeSql = `SELECT * FROM (${stripSqlTerminator(prepared.sql)}) _dql_probe LIMIT 2000`;
+                        const probeResult = await executor.executeQuery(probeSql, [], runtimeVariables({}), prepared.connection);
+                        const rows = (Array.isArray(probeResult?.rows) ? probeResult.rows : []);
+                        const rawColumns = Array.isArray(probeResult?.columns)
+                            ? probeResult.columns
+                            : [];
+                        const actualColumns = rawColumns.length > 0
+                            ? rawColumns.map((c) => (typeof c === 'string' ? c : c?.name ?? String(c)))
+                            : (rows[0] ? Object.keys(rows[0]) : []);
+                        const invariantResults = evaluateInvariants(invariants, { columns: actualColumns, rows });
+                        const passed = invariantResults.filter((r) => r.passed && !r.uncheckable).length;
+                        const failed = invariantResults.filter((r) => !r.passed && !r.uncheckable).length;
+                        return {
+                            actualColumns,
+                            invariantResults,
+                            tests: invariants.length > 0
+                                ? { passed, failed, assertionCount: invariantResults.length }
+                                : undefined,
+                        };
+                    },
+                });
+                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;
+        }
+        // Resolved local OSS owner (spec 14, part C). Stamps drafts so a new block is
+        // never born with a "Missing owner" Certifier strike.
+        if (req.method === 'GET' && path === '/api/identity') {
+            try {
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ owner: resolveLocalOwner(projectRoot) }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // ── Skills (spec 16) — user-authored business context. AI drafts, humans
+        //    certify; skills never carry certification. PROJECT skills (user empty)
+        //    are shared; PERSONAL skills (user set) are user-bound. ────────────────
+        if (req.method === 'GET' && path === '/api/skills') {
+            try {
+                const skills = loadSkills(projectRoot).skills.map(serializeSkill);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ skills }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // Form pickers: metrics from the semantic layer + certified block ids.
+        if (req.method === 'GET' && path === '/api/skills/options') {
+            try {
+                const metrics = semanticLayer
+                    ? semanticLayer.listMetrics().map((m) => m.name).sort()
+                    : [];
+                const manifest = buildManifest({ projectRoot, dqlVersion: 'notebook' });
+                const blocks = Object.values(manifest.blocks)
+                    .filter((b) => b.status === 'certified')
+                    .map((b) => b.name)
+                    .sort();
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ metrics, blocks }));
+            }
+            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/skills') {
+            try {
+                const body = (await readJSON(req).catch(() => ({})));
+                const input = parseSkillInput(body?.skill);
+                if (!input) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Provide { skill } with id, scope, and body.' }));
+                    return;
+                }
+                const skill = writeSkill(projectRoot, input);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ skill: serializeSkill(skill) }));
+            }
+            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 === 'PUT' && path.startsWith('/api/skills/')) {
+            try {
+                const id = decodeURIComponent(path.slice('/api/skills/'.length));
+                const body = (await readJSON(req).catch(() => ({})));
+                const input = parseSkillInput(body?.skill, id);
+                if (!input) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Provide { skill } with scope and body.' }));
+                    return;
+                }
+                const skill = writeSkill(projectRoot, input);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ skill: serializeSkill(skill) }));
+            }
+            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 === 'DELETE' && path.startsWith('/api/skills/')) {
+            try {
+                const id = decodeURIComponent(path.slice('/api/skills/'.length));
+                deleteSkill(projectRoot, id);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: true }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // ── Domains (spec 17, part B) — first-class business domain declarations.
+        //    Authoring here satisfies `dql doctor`'s "missing domain declaration"
+        //    warning. AI drafts, humans certify; domains carry no certification. ────
+        if (req.method === 'GET' && path === '/api/domains') {
+            try {
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ domains: listDomains(projectRoot) }));
+            }
+            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/domains') {
+            try {
+                const body = (await readJSON(req).catch(() => ({})));
+                const input = parseDomainInput(body?.domain);
+                if (!input) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Provide { domain } with a non-empty name.' }));
+                    return;
+                }
+                writeDomainDeclaration(projectRoot, input);
+                await refreshLocalMetadataCatalog(projectRoot);
+                const domain = findDomain(projectRoot, input.name);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ domain }));
+            }
+            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 === 'PUT' && path.startsWith('/api/domains/')) {
+            try {
+                const id = decodeURIComponent(path.slice('/api/domains/'.length));
+                const body = (await readJSON(req).catch(() => ({})));
+                const input = parseDomainInput(body?.domain, id);
+                if (!input) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Provide { domain } with a name.' }));
+                    return;
+                }
+                // If the name changed, remove the old declaration so we never orphan one.
+                if (domainFolderSlug(id) !== domainFolderSlug(input.name)) {
+                    deleteDomainDeclaration(projectRoot, id);
+                }
+                writeDomainDeclaration(projectRoot, input);
+                await refreshLocalMetadataCatalog(projectRoot);
+                const domain = findDomain(projectRoot, input.name);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ domain }));
+            }
+            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 === 'DELETE' && path.startsWith('/api/domains/')) {
+            try {
+                const id = decodeURIComponent(path.slice('/api/domains/'.length));
+                deleteDomainDeclaration(projectRoot, id);
+                await refreshLocalMetadataCatalog(projectRoot);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: true }));
+            }
+            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 === '/favicon.ico') {
@@ -1280,6 +2574,80 @@ export async function startLocalServer(opts) {
             res.end(serializeJSON({ ok: true, files }));
             return;
         }
+        // Local learning loop (OSS): record an analyst's wrong→right correction as a
+        // scope-matched Hint-Graph hint plus an advisory memory, so future similar
+        // questions avoid the same mistake. Single-user self-serve — the correction IS
+        // the approval, so the derived candidate is approved immediately unless the
+        // caller opts out. Advisory only: never overrides certified routing. The
+        // multi-tenant review workflow + automated distillation stay a cloud feature.
+        if (req.method === 'POST' && path === '/api/agent/learnings/correction') {
+            const body = await readJSON(req).catch(() => null);
+            const question = body && typeof body.question === 'string' ? body.question.trim() : '';
+            const correctedSql = body && typeof body.correctedSql === 'string' ? body.correctedSql.trim() : '';
+            if (!body || !question || !correctedSql) {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: 'question and correctedSql are required.' }));
+                return;
+            }
+            const rawScope = body.scope && typeof body.scope === 'object' ? body.scope : {};
+            const scopeStr = (key) => (typeof rawScope[key] === 'string' && rawScope[key].trim() ? rawScope[key].trim() : undefined);
+            const scope = {
+                metric: scopeStr('metric'),
+                dbtModel: scopeStr('dbtModel'),
+                domain: scopeStr('domain'),
+                dialect: scopeStr('dialect'),
+                term: scopeStr('term'),
+                block: scopeStr('block'),
+            };
+            const wrongSql = typeof body.wrongSql === 'string' ? body.wrongSql.trim() : '';
+            const rationale = typeof body.rationale === 'string' && body.rationale.trim() ? body.rationale.trim() : undefined;
+            const author = typeof body.author === 'string' ? body.author : (resolveLocalOwner(projectRoot) ?? undefined);
+            try {
+                const { trace, hint } = recordCorrectionTrace(projectRoot, {
+                    question,
+                    scope,
+                    wrongAnswer: wrongSql || '(no prior SQL captured)',
+                    correction: correctedSql,
+                    correctedSql,
+                    rationale,
+                    author,
+                    hintTitle: typeof body.title === 'string' && body.title.trim() ? body.title.trim() : undefined,
+                    hintGuidance: typeof body.guidance === 'string' && body.guidance.trim() ? body.guidance.trim() : undefined,
+                    tags: Array.isArray(body.tags) ? body.tags.map(String) : undefined,
+                });
+                let approvedHint = hint;
+                if (body.approve !== false) {
+                    reviewHint(projectRoot, { hintId: hint.id, decision: 'approved', reviewer: author ?? 'local', note: 'Self-approved (OSS single-user).' });
+                    approvedHint = { ...hint, status: 'approved' };
+                }
+                // Plain-language advisory memory mirroring the lesson, for transparency + recall.
+                try {
+                    const memory = new MemoryStore(defaultMemoryPath(projectRoot));
+                    memory.upsert({
+                        id: `mem_${hint.id}`,
+                        scope: 'project',
+                        title: approvedHint.title,
+                        content: `${approvedHint.guidance}${rationale ? ` (${rationale})` : ''}`,
+                        tags: [scope.metric, scope.domain, scope.dbtModel].filter((x) => Boolean(x)),
+                        source: 'correction',
+                        confidence: 0.9,
+                        importance: 0.85,
+                        enabled: true,
+                    });
+                    memory.close();
+                }
+                catch {
+                    /* best-effort */
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: true, trace, hint: approvedHint }));
+            }
+            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 appDashRun = path.match(/^\/api\/apps\/([^/]+)\/dashboards\/([^/]+)\/run$/);
         if (req.method === 'POST' && appDashRun) {
             try {
@@ -1474,6 +2842,14 @@ export async function startLocalServer(opts) {
                     executeSql: executeLocalSqlForStoredResult,
                     generateInvestigationSql: generateInvestigationSqlForApp,
                     runNotebook: (appId, notebookPath) => runNotebookForApp(appId, notebookPath),
+                    // P4: give the App ask lane a grounded research planner over the catalog.
+                    planResearch: async ({ question, isFollowUp }) => {
+                        const metrics = loadSemanticMetrics(projectRoot);
+                        let blocks = collectPlanBlocks(projectRoot, { certifiedOnly: true });
+                        if (blocks.length === 0)
+                            blocks = collectPlanBlocks(projectRoot, { certifiedOnly: false });
+                        return planResearch({ question, metrics, blocks, isFollowUp });
+                    },
                 });
                 if (handled)
                     return;
@@ -1598,8 +2974,11 @@ export async function startLocalServer(opts) {
             return;
         }
         if (req.method === 'GET' && path === '/api/notebook/research') {
-            const storage = openNotebookResearchStorage();
+            let storage;
+            const limit = notebookResearchInteger(url.searchParams.get('limit'), 50, 1, 500);
+            const offset = notebookResearchInteger(url.searchParams.get('offset'), 0, 0, Number.MAX_SAFE_INTEGER);
             try {
+                storage = openNotebookResearchStorage();
                 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'));
@@ -1615,24 +2994,28 @@ export async function startLocalServer(opts) {
                 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) {
+                if (isNotebookResearchStorageUnavailable(error)) {
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(withNotebookResearchChecklistPage(emptyNotebookResearchListPage({ limit, offset }))));
+                    return;
+                }
                 res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
             }
             finally {
-                storage.close();
+                storage?.close();
             }
             return;
         }
         if (req.method === 'POST' && path === '/api/notebook/research') {
-            const storage = openNotebookResearchStorage();
+            let storage;
             try {
+                storage = openNotebookResearchStorage();
                 const body = await readJSON(req);
                 const notebookPath = notebookResearchString(body.notebookPath) ?? notebookResearchString(body.path);
                 const question = notebookResearchString(body.question);
@@ -1679,7 +3062,7 @@ export async function startLocalServer(opts) {
                 res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
             }
             finally {
-                storage.close();
+                storage?.close();
             }
             return;
         }
@@ -1724,8 +3107,9 @@ export async function startLocalServer(opts) {
             return;
         }
         if (req.method === 'POST' && path === '/api/notebook/research/seed-cells') {
-            const storage = openNotebookResearchStorage();
+            let storage;
             try {
+                storage = openNotebookResearchStorage();
                 const body = await readJSON(req);
                 const notebookPath = notebookResearchString(body.notebookPath) ?? notebookResearchString(body.path);
                 if (!notebookPath) {
@@ -1776,12 +3160,14 @@ export async function startLocalServer(opts) {
                 res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
             }
             finally {
-                storage.close();
+                storage?.close();
             }
             return;
         }
         if (req.method === 'POST' && path === '/api/notebook/research/source-coverage') {
-            const storage = openNotebookResearchStorage();
+            let storage;
+            let requestedSourceCellCount = 0;
+            let limit = 10_000;
             try {
                 const body = await readJSON(req);
                 const notebookPath = notebookResearchString(body.notebookPath) ?? notebookResearchString(body.path);
@@ -1822,15 +3208,16 @@ export async function startLocalServer(opts) {
                 const sourceCellIds = Array.from(new Set(requestedIds
                     .map((id) => notebookResearchString(id))
                     .filter((id) => Boolean(id))));
-                const requestedSourceCellCount = new Set([
+                requestedSourceCellCount = new Set([
                     ...sourceCellIds,
                     ...sourceCells
                         .map((cell) => notebookResearchSourceCellId(cell))
                         .filter((id) => Boolean(id)),
                 ]).size;
-                const limit = typeof body.limit === 'number' && Number.isFinite(body.limit)
+                limit = typeof body.limit === 'number' && Number.isFinite(body.limit)
                     ? Math.max(1, Math.min(10_000, Math.floor(body.limit)))
                     : 10_000;
+                storage = openNotebookResearchStorage();
                 const linkedRuns = storage.listLatestRunsBySourceCell({
                     notebookPath,
                     sourceCellIds,
@@ -1853,26 +3240,42 @@ export async function startLocalServer(opts) {
                 }));
             }
             catch (error) {
+                if (isNotebookResearchStorageUnavailable(error)) {
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        runs: [],
+                        requestedCount: requestedSourceCellCount,
+                        matchedCount: 0,
+                        limitApplied: requestedSourceCellCount > limit,
+                    }));
+                    return;
+                }
                 res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
             }
             finally {
-                storage.close();
+                storage?.close();
             }
             return;
         }
         if (req.method === 'GET' && path === '/api/notebook/research/diagnostics') {
-            const storage = openNotebookResearchStorage();
+            let storage;
             try {
+                storage = openNotebookResearchStorage();
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON(storage.getDiagnostics()));
             }
             catch (error) {
+                if (isNotebookResearchStorageUnavailable(error)) {
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(emptyNotebookResearchDiagnostics()));
+                    return;
+                }
                 res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
             }
             finally {
-                storage.close();
+                storage?.close();
             }
             return;
         }
@@ -1880,8 +3283,9 @@ export async function startLocalServer(opts) {
         if (notebookResearchMatch) {
             const id = decodeURIComponent(notebookResearchMatch[1]);
             const action = notebookResearchMatch[2];
-            const storage = openNotebookResearchStorage();
+            let storage;
             try {
+                storage = openNotebookResearchStorage();
                 const run = storage.getRun(id);
                 if (!run) {
                     res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -1981,7 +3385,7 @@ export async function startLocalServer(opts) {
                 res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
             }
             finally {
-                storage.close();
+                storage?.close();
             }
             return;
         }
@@ -2485,6 +3889,144 @@ export async function startLocalServer(opts) {
             }
             return;
         }
+        // ── Distinct values for a block column → app/dashboard filter dropdowns ──
+        if (req.method === 'GET' && path === '/api/dashboard/filter-options') {
+            try {
+                const blockIdParam = url.searchParams.get('block');
+                const blockPath = url.searchParams.get('path')
+                    ?? (blockIdParam ? resolveBlockPathById(projectRoot, blockIdParam) : null);
+                const column = (url.searchParams.get('column') ?? '').trim();
+                const limit = Math.min(Math.max(Number(url.searchParams.get('limit') ?? 50) || 50, 1), 200);
+                if (!blockPath || !column || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(column)) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'path and a valid column are required' }));
+                    return;
+                }
+                const absolutePath = resolve(projectRoot, blockPath);
+                if (!absolutePath.startsWith(projectRoot + '/') && absolutePath !== projectRoot) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'path escapes project root' }));
+                    return;
+                }
+                if (!existsSync(absolutePath)) {
+                    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'block not found' }));
+                    return;
+                }
+                const source = readFileSync(absolutePath, 'utf-8');
+                // Only expose distinct values for a DECLARED output column — keeps the probe
+                // inside the governed block contract (no arbitrary column scanning).
+                const parsedMeta = parseBlockSourceMetadata(source);
+                if (parsedMeta.outputs.length > 0 && !parsedMeta.outputs.includes(column)) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: `"${column}" is not a declared output of this block` }));
+                    return;
+                }
+                const activeConnection = requireActiveConnection();
+                const tableMapping = await resolveSemanticTableMapping(executor, activeConnection, semanticLayer);
+                const semanticCompose = semanticLayer
+                    ? composeSemanticBlockSql(source, semanticLayer, {
+                        driver: activeConnection.driver,
+                        tableMapping,
+                        projectRoot,
+                        projectConfig,
+                        detectedProvider: semanticDetectedProvider,
+                    })
+                    : null;
+                const validation = validateBlockStudioSource(source, semanticLayer);
+                const baseSql = semanticCompose?.sql ?? validation.executableSql;
+                if (!baseSql) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'block has no executable SQL' }));
+                    return;
+                }
+                const prepared = prepareLocalExecution(baseSql, activeConnection, projectRoot, projectConfig);
+                const q = quoteAgentIdentifier(column, prepared.connection);
+                const wrapped = `SELECT DISTINCT ${q} AS value FROM (${stripSqlTerminator(prepared.sql)}) _dql_opt WHERE ${q} IS NOT NULL ORDER BY 1 LIMIT ${limit + 1}`;
+                const result = await executor.executeQuery(wrapped, [], runtimeVariables({}), prepared.connection);
+                const rows = Array.isArray(result?.rows) ? result.rows : [];
+                const truncated = rows.length > limit;
+                const options = rows
+                    .slice(0, limit)
+                    .map((row) => row?.value)
+                    .filter((value) => value !== null && value !== undefined)
+                    .map((value) => String(value));
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ column, options, truncated }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // ── Plan an app from a goal (P1: plan → critique → show gaps) ──────────
+        // The agent decomposes the goal into the questions an app should answer
+        // (KPI + trend + breakdowns), matches each to a CERTIFIED block, derives the
+        // shared filters that refresh every tile, and reports coverage + gaps BEFORE
+        // anything is built — so the human reviews the plan, not a blank canvas.
+        if (req.method === 'POST' && path === '/api/app-plan') {
+            try {
+                const body = await readJSON(req);
+                const goal = typeof body.goal === 'string' ? body.goal.trim() : '';
+                if (!goal) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'goal is required' }));
+                    return;
+                }
+                const certifiedOnly = body.certifiedOnly !== false;
+                const metrics = loadSemanticMetrics(projectRoot);
+                let blocks = collectPlanBlocks(projectRoot, { certifiedOnly });
+                // If nothing is certified yet, fall back to all drafts so the plan still
+                // shows what COULD be assembled (every section then reads as a gap to certify).
+                if (blocks.length === 0 && certifiedOnly)
+                    blocks = collectPlanBlocks(projectRoot, { certifiedOnly: false });
+                const plan = await planApp({ goal, metrics, blocks });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ plan, blockCount: blocks.length, metricCount: metrics.length, certifiedOnly }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // ── Research / follow-up planning (P4: ReAct over the catalog) ─────────
+        // Decide whether to answer, research across grounded steps, or ask a smart
+        // follow-up — so the agent behaves like a real assistant instead of always
+        // generating one query. Every step + option is bound to a real metric/block.
+        if (req.method === 'POST' && path === '/api/research-plan') {
+            try {
+                const body = await readJSON(req);
+                const question = typeof body.question === 'string' ? body.question.trim() : '';
+                if (!question) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'question is required' }));
+                    return;
+                }
+                const metrics = loadSemanticMetrics(projectRoot);
+                let blocks = collectPlanBlocks(projectRoot, { certifiedOnly: true });
+                if (blocks.length === 0)
+                    blocks = collectPlanBlocks(projectRoot, { certifiedOnly: false });
+                const plan = await planResearch({
+                    question,
+                    metrics,
+                    blocks,
+                    intent: typeof body.intent === 'string'
+                        ? body.intent
+                        : undefined,
+                    isFollowUp: body.isFollowUp === true,
+                    history: Array.isArray(body.history) ? body.history : undefined,
+                });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ plan, blockCount: blocks.length, metricCount: metrics.length }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
         // ── Run block tests ────────────────────────────────────────────────
         if (req.method === 'POST' && path === '/api/blocks/run-tests') {
             try {
@@ -2523,7 +4065,11 @@ export async function startLocalServer(opts) {
                     res.end(serializeJSON({ error: 'source is required' }));
                     return;
                 }
-                const result = await certifyBlockStudioSource(source, blockPath, { enterprise: body.enterprise !== false });
+                // OSS local-first certifies in non-enterprise mode: owner + passing tests +
+                // a successful run are the gate; grain/outputs/pattern/lineage/cadence are
+                // AI-filled advisory warnings, not hard blockers. Enterprise-grade certification
+                // (all of those required) is an opt-in for the cloud tier — request it explicitly.
+                const result = await certifyBlockStudioSource(source, blockPath, { enterprise: body.enterprise === true });
                 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' });
@@ -2552,6 +4098,32 @@ export async function startLocalServer(opts) {
                         certifiedPayload = openBlockStudioDocument(projectRoot, normalizedBlockPath, semanticLayer);
                     }
                 }
+                // Auto-capture (OSS local learning loop): certifying a block teaches the
+                // agent to prefer it. Write a scoped, advisory project memory — deterministic,
+                // best-effort, and it never blocks certification.
+                try {
+                    const learned = parseBlockSourceMetadata(certifiedSource);
+                    if (learned.name) {
+                        const learnedOutputs = Array.isArray(learned.outputs)
+                            ? learned.outputs.filter((o) => typeof o === 'string')
+                            : [];
+                        const memory = new MemoryStore(defaultMemoryPath(projectRoot));
+                        memory.upsert({
+                            id: `mem_certify_${learned.name}`,
+                            scope: 'project',
+                            title: `Certified block: ${learned.name}`,
+                            content: `Prefer the certified block "${learned.name}" for ${learned.description?.trim() || `questions in the ${learned.domain ?? 'analytics'} domain`}.${learned.grain ? ` Grain: ${learned.grain}.` : ''}${learnedOutputs.length ? ` Outputs: ${learnedOutputs.slice(0, 8).join(', ')}.` : ''} It is the trusted source — reuse it instead of generating new SQL.`,
+                            tags: [learned.domain, learned.name, ...learnedOutputs.slice(0, 4)].filter((x) => Boolean(x)),
+                            source: 'certify',
+                            confidence: 0.95,
+                            importance: 0.85,
+                            enabled: true,
+                        });
+                    }
+                }
+                catch {
+                    /* best-effort: learning capture must never block certification */
+                }
                 await refreshLocalMetadataCatalog(projectRoot);
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
@@ -2680,7 +4252,8 @@ export async function startLocalServer(opts) {
                         return;
                     }
                     const certifiedSource = setBlockStudioSourceStatus(readiness.candidate.dqlSource, 'certified');
-                    const certification = await certifyBlockStudioSource(certifiedSource, readiness.candidate.savedPath, { enterprise: true });
+                    // OSS certify = non-enterprise (owner-gated); enterprise depth is the cloud tier.
+                    const certification = await certifyBlockStudioSource(certifiedSource, readiness.candidate.savedPath, { enterprise: false });
                     const blockers = Array.from(new Set(certification.checklist.blockers));
                     if (!certification.certification.certified || blockers.length > 0) {
                         const savedDraft = saveDqlGenerationDraft(importId, readiness.candidate);
@@ -4614,6 +6187,14 @@ export async function startLocalServer(opts) {
                 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);
+                // Enforce the block's declared invariants against the result set. This
+                // is additive: blocks without invariants produce `null` and the
+                // response is unchanged. The agent surface (`query_via_block`) reads
+                // these fields to downgrade the trust label on violation.
+                const invariants = evaluateBlockInvariants(executableCell.source || cell.source || '', {
+                    columns: normalized.columns,
+                    rows: normalized.rows,
+                });
                 if (execContext) {
                     recordNotebookQueryRun(projectRoot, {
                         notebookPath: execContext.notebookPath,
@@ -4642,6 +6223,12 @@ export async function startLocalServer(opts) {
                     chartConfig: plan.chartConfig,
                     tests: plan.tests,
                     result: normalized,
+                    ...(invariants
+                        ? {
+                            invariantResults: invariants.invariantResults,
+                            invariantViolation: invariants.invariantViolation,
+                        }
+                        : {}),
                 }));
             }
             catch (error) {
@@ -4717,6 +6304,7 @@ table: ${table}${tagList}
         res.writeHead(200, { 'Content-Type': contentTypeFor(filePath) });
         res.end(content);
     });
+    opts.captureServer?.(server);
     return new Promise((resolvePromise, reject) => {
         let retriedWithRandomPort = false;
         server.on('error', (error) => {
@@ -4951,6 +6539,145 @@ export function serializeJSON(value) {
         return current;
     });
 }
+/** Serialize a Skill to the shared API contract shape (spec 16). */
+function serializeSkill(skill) {
+    return {
+        id: skill.id,
+        scope: skill.scope,
+        user: skill.user,
+        domain: skill.domain,
+        description: skill.description,
+        body: skill.body,
+        preferredMetrics: skill.preferredMetrics,
+        preferredBlocks: skill.preferredBlocks,
+        vocabulary: skill.vocabulary,
+        sourcePath: skill.sourcePath,
+        isStarter: skill.isStarter,
+    };
+}
+/**
+ * Validate + normalize an inbound `{ skill }` body into a WriteSkillInput.
+ * `id` + `scope` + `body` are required; `fallbackId` supplies the id on PUT
+ * (from the URL). Returns null when the payload is invalid.
+ */
+function parseSkillInput(raw, fallbackId) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const skill = raw;
+    const id = typeof skill.id === 'string' && skill.id.trim() ? skill.id.trim() : fallbackId;
+    if (!id)
+        return null;
+    const scope = skill.scope === 'personal' ? 'personal' : skill.scope === 'project' ? 'project' : undefined;
+    if (!scope)
+        return null;
+    if (typeof skill.body !== 'string')
+        return null;
+    const asStrings = (value) => Array.isArray(value) ? value.filter((v) => typeof v === 'string') : [];
+    const asMap = (value) => {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return {};
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (typeof v === 'string')
+                out[k] = v;
+        }
+        return out;
+    };
+    return {
+        id,
+        scope,
+        user: scope === 'personal' && typeof skill.user === 'string' ? skill.user : undefined,
+        domain: typeof skill.domain === 'string' && skill.domain.trim() ? skill.domain.trim() : undefined,
+        description: typeof skill.description === 'string' ? skill.description : undefined,
+        body: skill.body,
+        preferredMetrics: asStrings(skill.preferredMetrics),
+        preferredBlocks: asStrings(skill.preferredBlocks),
+        vocabulary: asMap(skill.vocabulary),
+        isStarter: skill.isStarter === true ? true : undefined,
+    };
+}
+/** Loose, case/slug-insensitive domain key for counting membership. */
+function domainKey(value) {
+    if (!value)
+        return '';
+    return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+function manifestDomainToDto(domain, counts) {
+    return {
+        id: domain.name,
+        name: domain.name,
+        owner: domain.owner,
+        boundedContext: domain.boundedContext,
+        sourceSystems: domain.sourceSystems,
+        description: domain.description,
+        sourcePath: domain.filePath,
+        blockCount: counts.blockCount,
+        skillCount: counts.skillCount,
+        termCount: counts.termCount,
+    };
+}
+/** List authored domains with per-domain block/skill/term counts. */
+export function listDomains(projectRoot) {
+    const manifest = buildManifest({ projectRoot, dqlVersion: 'notebook' });
+    const domains = manifest.domains ?? {};
+    const skills = loadSkills(projectRoot).skills;
+    const blockCounts = new Map();
+    for (const block of Object.values(manifest.blocks)) {
+        const key = domainKey(block.domain);
+        if (key)
+            blockCounts.set(key, (blockCounts.get(key) ?? 0) + 1);
+    }
+    const termCounts = new Map();
+    for (const term of Object.values(manifest.terms ?? {})) {
+        const key = domainKey(term.domain);
+        if (key)
+            termCounts.set(key, (termCounts.get(key) ?? 0) + 1);
+    }
+    const skillCounts = new Map();
+    for (const skill of skills) {
+        const key = domainKey(skill.domain);
+        if (key)
+            skillCounts.set(key, (skillCounts.get(key) ?? 0) + 1);
+    }
+    return Object.values(domains)
+        .map((domain) => {
+        const key = domainKey(domain.name);
+        return manifestDomainToDto(domain, {
+            blockCount: blockCounts.get(key) ?? 0,
+            skillCount: skillCounts.get(key) ?? 0,
+            termCount: termCounts.get(key) ?? 0,
+        });
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Find a single authored domain by name/id (case/slug-insensitive). */
+function findDomain(projectRoot, nameOrId) {
+    const key = domainKey(nameOrId);
+    return listDomains(projectRoot).find((domain) => domainKey(domain.name) === key);
+}
+/** Validate + normalize an inbound `{ domain }` body into a DomainInput. */
+export function parseDomainInput(raw, fallbackId) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const domain = raw;
+    const name = typeof domain.name === 'string' && domain.name.trim()
+        ? domain.name.trim()
+        : typeof domain.id === 'string' && domain.id.trim()
+            ? domain.id.trim()
+            : fallbackId;
+    if (!name)
+        return null;
+    const asStrings = (value) => Array.isArray(value)
+        ? value.filter((v) => typeof v === 'string' && v.trim().length > 0)
+        : undefined;
+    return {
+        name,
+        owner: typeof domain.owner === 'string' ? domain.owner : undefined,
+        boundedContext: typeof domain.boundedContext === 'string' ? domain.boundedContext : undefined,
+        sourceSystems: asStrings(domain.sourceSystems),
+        description: typeof domain.description === 'string' ? domain.description : undefined,
+    };
+}
 async function refreshLocalMetadataCatalog(projectRoot) {
     try {
         await ensureMetadataCatalogFresh(projectRoot, { force: true });
@@ -5023,6 +6750,153 @@ export function loadProjectConfig(projectRoot) {
     }
     return config;
 }
+/**
+ * Core of the `/api/propose` endpoint, factored out as a pure function so it can
+ * be unit-tested without standing up an HTTP server.
+ *
+ * It reuses the existing `propose` engine from `@duckcodeailabs/dql-agent`
+ * verbatim (no inference/ranking logic is duplicated here) in `dryRun` mode so a
+ * readiness preview never mutates the project. Every returned proposal is a
+ * `status: draft` block with the engine's stored Certifier verdict attached.
+ */
+export function buildProposeReadiness(projectRoot, projectConfig = loadProjectConfig(projectRoot), options = {}) {
+    const manifestPath = resolveDbtManifestPath(projectRoot, projectConfig);
+    if (!manifestPath) {
+        return {
+            ready: false,
+            reason: 'No dbt manifest found. Run `dbt parse` (or `dbt compile`) in your dbt project, then reopen Get Started.',
+            summary: {
+                modelsScanned: 0,
+                businessModels: 0,
+                plumbingExcluded: 0,
+                metricsFound: 0,
+                proposalsRanked: 0,
+                draftsExisting: 0,
+                readyForReview: 0,
+                blockingTotal: 0,
+                warningTotal: 0,
+            },
+            plan: {
+                totals: { modelsScanned: 0, businessModels: 0, plumbingExcluded: 0, metricsFound: 0 },
+                willGenerate: 0,
+                willSkip: 0,
+                domains: [],
+                config: {
+                    businessLayers: [],
+                    excludeLayers: [],
+                    maxPerDomain: 0,
+                    minScore: 0,
+                    aiEnrichment: 'auto',
+                },
+            },
+            proposals: [],
+        };
+    }
+    const proposeConfig = projectConfig.propose;
+    // PLAN: deterministic, business-only, bounded. Writes nothing.
+    const plan = proposePlan(projectRoot, manifestPath, { config: proposeConfig });
+    // dryRun: rank + certify the selected scope only. Never writes from a preview.
+    // Stamp the resolved local OSS owner when none was passed so the stored verdict
+    // does not carry a phantom "Missing owner" strike. Read-only resolution — the
+    // preview must not mutate the project.
+    const summary = propose({
+        projectRoot,
+        dbtManifestPath: manifestPath,
+        owner: options.owner || resolveLocalOwner(projectRoot, { persist: false }),
+        limit: options.limit,
+        dryRun: true,
+        config: proposeConfig,
+    });
+    let readyForReview = 0;
+    let blockingTotal = 0;
+    let warningTotal = 0;
+    for (const proposal of summary.proposals) {
+        blockingTotal += proposal.certification.errors.length;
+        warningTotal += proposal.certification.warnings.length;
+        if (proposal.certification.errors.length === 0)
+            readyForReview += 1;
+    }
+    return {
+        ready: true,
+        summary: {
+            projectName: summary.projectName,
+            modelsScanned: summary.modelsScanned,
+            businessModels: summary.businessModels,
+            plumbingExcluded: summary.plumbingExcluded,
+            metricsFound: summary.metricsFound,
+            proposalsRanked: summary.proposalsRanked,
+            // In dryRun the engine marks already-present blocks as skipped.
+            draftsExisting: summary.draftsSkipped,
+            readyForReview,
+            blockingTotal,
+            warningTotal,
+        },
+        plan,
+        proposals: summary.proposals,
+    };
+}
+export async function generateProposeDrafts(projectRoot, slugs, projectConfig = loadProjectConfig(projectRoot), options = {}) {
+    const manifestPath = resolveDbtManifestPath(projectRoot, projectConfig);
+    if (!manifestPath) {
+        return {
+            ready: false,
+            reason: 'No dbt manifest found. Run `dbt parse` (or `dbt compile`) first.',
+            draftsWritten: 0,
+            draftsSkipped: 0,
+            proposals: [],
+        };
+    }
+    // Structure deterministic, content AI-optional: optionally pre-compute AI
+    // enrichment (description / llmContext / examples) for the approved slugs, then
+    // hand it to the deterministic engine as data. Best-effort — any failure or a
+    // missing provider falls back to dbt-derived content.
+    let enrichedBySlug;
+    const proposeConfig = resolveProposeConfig(projectConfig.propose);
+    if (proposeConfig.aiEnrichment !== 'off' && slugs.length > 0) {
+        enrichedBySlug = await gatherProposeEnrichment(projectRoot, manifestPath, projectConfig.propose, slugs).catch(() => undefined);
+    }
+    const summary = propose({
+        projectRoot,
+        dbtManifestPath: manifestPath,
+        // Stamp the resolved local OSS owner when none was passed so drafts are not
+        // born with a "Missing owner" Certifier strike.
+        owner: options.owner || resolveLocalOwner(projectRoot),
+        config: projectConfig.propose,
+        onlySlugs: slugs,
+        enrichedBySlug,
+    });
+    return {
+        ready: true,
+        draftsWritten: summary.draftsWritten,
+        draftsSkipped: summary.draftsSkipped,
+        proposals: summary.proposals,
+    };
+}
+/**
+ * Build the FILLED transparent preview for ONE proposed candidate slug (spec 14,
+ * part A). Reuses the deterministic `buildProposePreview` engine (real SQL +
+ * Certifier verdict) and best-effort AI enrichment (description/llmContext/
+ * examples) when a provider is available. Writes NOTHING. Returns `undefined`
+ * when the slug is not part of the bounded, business-only selection.
+ */
+export async function buildProposeCandidatePreview(projectRoot, slug, owner, projectConfig = loadProjectConfig(projectRoot)) {
+    const manifestPath = resolveDbtManifestPath(projectRoot, projectConfig);
+    if (!manifestPath)
+        return undefined;
+    // Best-effort AI enrichment for this one slug (content only). Any miss falls
+    // back to the deterministic dbt-derived content inside buildProposePreview.
+    let enriched;
+    const proposeConfig = resolveProposeConfig(projectConfig.propose);
+    if (proposeConfig.aiEnrichment !== 'off') {
+        const map = await gatherProposeEnrichment(projectRoot, manifestPath, projectConfig.propose, [slug]).catch(() => undefined);
+        enriched = map?.get(slug);
+    }
+    return buildProposePreview(projectRoot, manifestPath, slug, {
+        config: projectConfig.propose,
+        owner: owner || resolveLocalOwner(projectRoot),
+        enriched,
+    });
+}
 function getProjectConnectionsForApi(config) {
     const connections = getStoredConnections(config);
     if (Object.keys(connections).length === 0 && isConnectionLike(config.defaultConnection)) {
@@ -5035,6 +6909,11 @@ const CONNECTOR_INSTALLS = {
         driver: 'duckdb',
         label: 'DuckDB',
         packageName: 'duckdb',
+        // Latest 1.x. An earlier pin to 1.1.3 worked around a BIGINT serialization crash,
+        // but that only bites a naive `JSON.stringify` — the DQL driver
+        // (`normalizeDuckDBValue`) coerces BIGINT→number before marshaling and
+        // `serializeJSON` has a BigInt replacer, so 1.4.x is verified-good on the local
+        // DuckDB path (COUNT/AVG/SELECT * over UUID/BIGINT/decimal/datetime on real data).
         packageSpec: 'duckdb@^1.1.0',
         builtIn: false,
     },
@@ -5383,6 +7262,10 @@ function buildDashboardFilterPredicate(input) {
         const end = addDashboardFilterParam(input, 'end', range.end);
         return `${input.expression} BETWEEN $${start.position} AND $${end.position}`;
     }
+    // A daterange with only one bound set is incomplete — skip it rather than binding
+    // the partial object as a scalar equality (which would produce invalid SQL).
+    if (input.filterType === 'daterange')
+        return null;
     const values = Array.isArray(input.value) ? input.value.filter((item) => !isEmptyDashboardFilterValue(item)) : [input.value];
     if (values.length === 0)
         return null;
@@ -6229,6 +8112,16 @@ function composeSemanticBlockSql(source, semanticLayer, options) {
     if (diagnostics.some((diagnostic) => diagnostic.severity === 'error')) {
         return { sql: null, diagnostics, semanticRefs };
     }
+    // Import-adapter shape: a semantic block may carry a pre-compiled `query` (the
+    // governed metric already expanded to runnable SQL). When present, RUN THAT —
+    // the `metric` field is provenance/governance, not something to recompile. This
+    // keeps metric-bound blocks runnable offline (the full MetricFlow engine may be
+    // unavailable). We still validated the metric exists above. Returning the query
+    // as the composed SQL lets the normal {{ ref() }} resolution + execution apply.
+    const precompiledQuery = extractBlockStudioSql(source);
+    if (precompiledQuery) {
+        return { sql: precompiledQuery, diagnostics, semanticRefs };
+    }
     let composed;
     try {
         composed = options?.projectRoot && options.projectConfig
@@ -6574,7 +8467,7 @@ function saveDqlGenerationDraftForProject(projectRoot, importId, candidate) {
     }
 }
 export function saveBlockStudioArtifacts(projectRoot, options) {
-    const slug = options.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'block';
+    const slug = options.name.toLowerCase().replace(/[^a-z0-9_]+/g, '-').replace(/^[-_]+|[-_]+$/g, '') || 'block';
     const safeDomain = (options.domain ?? '')
         .trim()
         .toLowerCase()
@@ -6614,7 +8507,7 @@ 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 slug = options.name.toLowerCase().replace(/[^a-z0-9_]+/g, '-').replace(/^[-_]+|[-_]+$/g, '') || 'block';
     const safeDomain = (options.domain ?? '')
         .trim()
         .toLowerCase()
@@ -6757,8 +8650,132 @@ function readBlockCompanionFile(projectRoot, relativePath) {
         return null;
     }
 }
+/**
+ * Extract the declared `invariants` from a block's DQL source using the core
+ * parser (the same path that populates the manifest). Returns an empty array
+ * when the source has no invariants or cannot be parsed — invariant evaluation
+ * is best-effort and must never break a run.
+ */
+export function extractBlockInvariants(source) {
+    // Only DQL block sources declare invariants. Never hand a non-DQL cell source
+    // (e.g. a raw SQL notebook cell like "SELECT 1") to the DQL parser: it can loop
+    // on input it doesn't recognize and OOM-crash the runtime on every execute.
+    // Require a `block "..."` declaration before parsing.
+    if (!/(?:^|\n)\s*block\s+["']/.test(source))
+        return [];
+    try {
+        const ast = new Parser(source).parse();
+        const block = ast.statements.find((statement) => statement.kind === 'BlockDecl');
+        return Array.isArray(block?.invariants) ? block.invariants : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Evaluate a block's declared invariants against a normalized query result.
+ * Returns `null` when the block declares no invariants so callers can omit the
+ * field entirely (blocks without invariants behave exactly as before).
+ */
+export function evaluateBlockInvariants(source, result) {
+    const invariants = extractBlockInvariants(source);
+    if (invariants.length === 0)
+        return null;
+    const invariantResults = evaluateInvariants(invariants, {
+        columns: result.columns,
+        rows: result.rows,
+    });
+    return { invariantResults, invariantViolation: hasInvariantViolation(invariantResults) };
+}
+/** Resolve a block id/slug to its `.dql` path (filename slug first, then `block "<id>"`). */
+function resolveBlockPathById(projectRoot, blockId) {
+    const wanted = blockId.trim().toLowerCase();
+    if (!wanted)
+        return null;
+    const leaf = wanted.split('.').pop() ?? wanted;
+    const escaped = leaf.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const nameRe = new RegExp(`^\\s*block\\s+"${escaped}"`, 'im');
+    const stack = ['blocks', 'domains'].map((dir) => join(projectRoot, dir));
+    let nameMatch = null;
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (!existsSync(dir))
+            continue;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const filePath = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(filePath);
+                continue;
+            }
+            if (!entry.name.endsWith('.dql'))
+                continue;
+            const rel = relative(projectRoot, filePath).replaceAll('\\', '/');
+            if (entry.name.replace(/\.dql$/, '').toLowerCase() === leaf)
+                return rel; // fast path: filename slug
+            if (!nameMatch) {
+                try {
+                    if (nameRe.test(readFileSync(filePath, 'utf-8')))
+                        nameMatch = rel;
+                }
+                catch { /* skip */ }
+            }
+        }
+    }
+    return nameMatch;
+}
+/**
+ * Collect the workspace's blocks as the App planner needs to see them (name +
+ * governed metric + filterable dimensions). Walks blocks/ and domains/, parsing
+ * each `.dql`. Certified-only by default — the planner builds an app from trusted
+ * material and reports the rest as gaps.
+ */
+function collectPlanBlocks(projectRoot, opts = {}) {
+    const out = [];
+    const seen = new Set();
+    const stack = ['blocks', 'domains'].map((dir) => join(projectRoot, dir));
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (!existsSync(dir))
+            continue;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const filePath = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(filePath);
+                continue;
+            }
+            if (!entry.name.endsWith('.dql'))
+                continue;
+            let source;
+            try {
+                source = readFileSync(filePath, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            const meta = parseBlockSourceMetadata(source);
+            if (!meta.name || seen.has(meta.name))
+                continue;
+            if (opts.certifiedOnly && meta.status !== 'certified')
+                continue;
+            seen.add(meta.name);
+            out.push({
+                name: meta.name,
+                domain: meta.domain || undefined,
+                description: meta.description || undefined,
+                metricRef: meta.metricRef || meta.metricsRef[0] || undefined,
+                allowedFilters: meta.allowedFilters,
+                dimensions: meta.dimensions,
+            });
+        }
+    }
+    return out;
+}
 export function parseBlockSourceMetadata(source) {
-    const name = source.match(/^\s*block\s+"([^"]+)"/i)?.[1] ?? '';
+    // Multiline: a `.dql` typically opens with a comment header (e.g. a proposed-draft
+    // banner), so the `block "<name>"` declaration is NOT at the start of the string.
+    // Without `m` the name parsed empty and every certified block was saved as the
+    // generic `block.dql` (slug fallback) — colliding on the 2nd certify (BLOCK_EXISTS).
+    const name = source.match(/^\s*block\s+"([^"]+)"/im)?.[1] ?? '';
     const extractString = (key) => source.match(new RegExp(`\\b${key}\\s*=\\s*"([^"]*)"`, 'i'))?.[1] ?? '';
     const extractStringArray = (key) => {
         const match = source.match(new RegExp(`\\b${key}\\s*=\\s*\\[([^\\]]*)\\]`, 'i'));
@@ -6799,6 +8816,8 @@ export function parseBlockSourceMetadata(source) {
         sourceSystems: extractStringArray('sourceSystems'),
         replacementFor: extractStringArray('replacementFor'),
         reviewCadence: extractString('reviewCadence'),
+        metricRef: extractString('metric'),
+        metricsRef: extractStringArray('metrics'),
     };
 }
 function compareBlockStudioValues(actual, operator, expected) {
@@ -6848,14 +8867,15 @@ function buildBlockStudioCertificationChecklist(input) {
         blockers.add(blocker);
     if (!input.previewSucceeded)
         blockers.add('Block has not run successfully');
-    if (!input.testResults || input.testResults.failed > 0)
+    // Only a REAL test failure blocks. "No tests" and "no chart" are advisory review
+    // items the AI fills at draft time — never hard gates (owner is the gate). This is
+    // what keeps "build a DQL" from demanding ~13 fields per block at 300-query scale.
+    if (input.testResults && input.testResults.failed > 0)
         blockers.add('Tests must pass before certification');
-    if (!input.testResults || input.testResults.assertions.length === 0)
-        blockers.add('At least one test assertion is required before certification');
-    if (!input.validation.chartConfig?.chart)
-        blockers.add('Visualization config is missing');
     return {
-        metadata: Boolean(parsed.domain.trim() && parsed.owner.trim() && parsed.description.trim()),
+        // The metadata tab is green once the one required field (owner) is present.
+        // Description/domain are AI-filled + editable and surface as review items, not gates.
+        metadata: Boolean(parsed.owner.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),
@@ -7866,13 +9886,13 @@ async function createBlockStudioAssistProvider(projectRoot, requestedProvider) {
     let provider;
     switch (selected.id) {
         case 'anthropic':
-            provider = new ClaudeProvider({ apiKey: config.apiKey, model: config.model });
+            provider = new ClaudeProvider({ apiKey: config.apiKey, baseUrl: config.baseUrl, model: config.model });
             break;
         case 'openai':
             provider = new OpenAIProvider({ apiKey: config.apiKey, baseUrl: config.baseUrl, model: config.model });
             break;
         case 'gemini':
-            provider = new GeminiProvider({ apiKey: config.apiKey, model: config.model });
+            provider = new GeminiProvider({ apiKey: config.apiKey, baseUrl: config.baseUrl, model: config.model });
             break;
         case 'ollama':
             provider = new OllamaProvider({ baseUrl: config.baseUrl, model: config.model });
@@ -8013,7 +10033,7 @@ function resolveBlockWriteTarget(projectRoot, safeDomain, slug) {
     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 slug = options.name.toLowerCase().replace(/[^a-z0-9_]+/g, '-').replace(/^[-_]+|[-_]+$/g, '') || 'block';
     const safeDomain = (options.domain ?? '')
         .trim()
         .toLowerCase()
@@ -8068,7 +10088,7 @@ export function createBlockArtifacts(projectRoot, options) {
     };
 }
 export function createSemanticBuilderBlock(projectRoot, options) {
-    const slug = options.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'block';
+    const slug = options.name.toLowerCase().replace(/[^a-z0-9_]+/g, '-').replace(/^[-_]+|[-_]+$/g, '') || 'block';
     const safeDomain = (options.domain ?? '')
         .trim()
         .toLowerCase()
@@ -8531,6 +10551,19 @@ export function discoverDbtProfileConnections(projectRoot, projectConfig) {
                 const mapped = mapDbtProfileOutput(output);
                 if (!mapped)
                     continue;
+                // dbt resolves a relative duckdb `path` against the dbt project dir (where it runs),
+                // NOT the DQL workspace. Resolve to an absolute path here so the imported connection
+                // opens the real warehouse instead of silently creating an empty db next to dql.config.json.
+                if (mapped.adapter === 'duckdb' &&
+                    mapped.connection.filepath &&
+                    mapped.connection.filepath !== ':memory:') {
+                    if (!isAbsoluteLikePath(mapped.connection.filepath)) {
+                        mapped.connection.filepath = resolve(dbtProjectPath, mapped.connection.filepath);
+                    }
+                    if (!existsSync(mapped.connection.filepath)) {
+                        mapped.warnings.push(`DuckDB file not found at ${mapped.connection.filepath} — run \`dbt build\` (or \`dbt seed\`) to create it before querying.`);
+                    }
+                }
                 const warnings = [...mapped.warnings];
                 if (targetName !== defaultTarget) {
                     warnings.push(`Not the default dbt target "${defaultTarget}".`);
@@ -9643,7 +11676,7 @@ async function testProviderConfig(projectRoot, id) {
     let provider;
     switch (id) {
         case 'gemini':
-            provider = new GeminiProvider({ apiKey: config.apiKey, model: config.model });
+            provider = new GeminiProvider({ apiKey: config.apiKey, baseUrl: config.baseUrl, model: config.model });
             break;
         case 'ollama':
             provider = new OllamaProvider({ baseUrl: config.baseUrl, model: config.model });
@@ -9704,7 +11737,10 @@ async function testAnthropicProviderConfig(config, label, details) {
         return { ok: false, message: `${label} is not configured${details}. Add an API key in Settings or ANTHROPIC_API_KEY.` };
     }
     try {
-        const client = new Anthropic({ apiKey: config.apiKey });
+        const client = new Anthropic({
+            apiKey: config.apiKey,
+            ...(config.baseUrl ? { baseURL: normalizeAnthropicBaseUrl(config.baseUrl) } : {}),
+        });
         const response = await client.messages.create({
             model: config.model ?? 'claude-opus-4-8',
             max_tokens: 16,