@duckcodeailabs/dql-cli 1.12.11 → 1.13.1

package/dist/local-runtime.js

@@ -1,18 +1,21 @@
 import { execFileSync, execSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { gzipSync } from "node:zlib";
+import { gzip } from "node:zlib";
 import { createServer } from "node:http";
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, watch, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, watch, writeFileSync, } from "node:fs";
+import { mkdir as mkdirAsync, rename as renameAsync, rm as rmAsync, writeFile as writeFileAsync, } from 'node:fs/promises';
 import { createRequire } from "node:module";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { dirname, extname, join, normalize, relative, resolve, sep, } from "node:path";
 import { Readable } from "node:stream";
+import { LocalOperationCoordinator, } from './local-operation-coordinator.js';
+import { ProjectRefreshCoordinator } from './project-refresh-coordinator.js';
 import { buildMixedSourceWarehouseFallbackSql, findMentionedNotebookDataset, planMixedSourceNotebookSql, planMixedSourceSql, } from "./mixed-source-sql.js";
 import { resolveNpmInvocation } from './npm-runtime.js';
 import { ensureDqlGitignore, isGovernedSourceFile, isLegacyBroadDqlIgnore, } from './git-contract.js';
 import { buildExecutionPlan, createWelcomeNotebook, deserializeNotebook, getConnectorFormSchemas, hasSemanticRefs, hasStandaloneSemanticRef, resolveSemanticRefs, } from '@duckcodeailabs/dql-notebook';
-import { loadSemanticLayerFromDir, normalizeDqlArtifactReference, serializeMetricDefinitionToYaml, resolveSemanticLayerAsync, resolveRepoSource, getDialect, Parser, NodeKind, blockParameterDefinitions, buildLineageGraph, buildManifest, collectInputFiles, findAppDocuments, findDashboardsForApp, isBlockIdRef, loadAppDocument, loadDashboardDocument, analyzeImpact, buildTrustChain, detectDomainFlows, getDomainTrustOverview, queryLineage, queryBusiness360, queryCompleteLineagePaths, LineageGraph, canonicalize, canonicalizeNotebook, diffDQL, diffNotebook, domainFolderSlug, previewModelingChange, applyModelingChange, previewDbtSourcePatch, applyDbtSourcePatch, loadDomainPackageRegistry, loadDbtNodeAuthoringDetail, normalizeAnalyticalFailureV1, relationshipValidationProofFingerprint, renderSemanticBlockSource, discoverDbtDomains, renderDomainDeclaration, ProjectSnapshotService, analyzeSqlReferences, semanticDimensionReference, } from '@duckcodeailabs/dql-core';
+import { loadSemanticLayerFromDir, normalizeDqlArtifactReference, serializeMetricDefinitionToYaml, resolveSemanticLayerAsync, resolveRepoSource, getDialect, Parser, NodeKind, blockParameterDefinitions, buildLineageGraph, buildManifest, collectInputFiles, findAppDocuments, findDashboardsForApp, isBlockIdRef, loadAppDocument, loadDashboardDocument, analyzeImpact, buildTrustChain, detectDomainFlows, getDomainTrustOverview, queryLineage, queryBusiness360, queryCompleteLineagePaths, LineageGraph, canonicalize, canonicalizeNotebook, diffDQL, diffNotebook, domainFolderSlug, previewModelingChange, previewModelingChanges, applyModelingChange, previewDbtSourcePatch, applyDbtSourcePatch, loadDomainPackageRegistry, loadDbtNodeAuthoringDetail, normalizeAnalyticalFailureV1, relationshipValidationProofFingerprint, renderSemanticBlockSource, discoverDbtDomains, renderDomainDeclaration, ProjectSnapshotService, analyzeSqlReferences, semanticDimensionReference, } 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';
@@ -21,10 +24,10 @@ import { fetchLatestPublishedDqlVersion, resolveDqlRuntimeVersionStatus } from '
 import { resolveRetrievalHealthStatus } from './retrieval-health.js';
 import { createDqlAgentProviderRunner, resolveAgentFollowUpContext } from './llm/providers/dql-agent-provider.js';
 import { listRemoteMcpSettings, saveRemoteMcpSettings } from './llm/mcp-config.js';
-import { ClaudeProvider, ConversationStore, advanceThreadState, buildConversationSnapshot, conversationHistoryFromContext, recallRelevantTurns, renderConversationEnvelopeForPrompt, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildAnalysisQuestionPlan, composeSemanticQueryForQuestion, aggregationIntegrityIssuesForSql, buildLocalContextPack, applyContextPackCompatibility, toAgentRetrievalEvidence, prepareConversationPath, defaultMemoryPath, ensureDefaultMemoryFiles, ensureAgentProjectReady, isAgentProjectIndexReady, currentMetadataFingerprint, ensureMetadataCatalogFresh, readIndexedDomainKnowledge, readIndexedKnowledge360, compactSemanticRuntimeFailure, classifyAnalyticalFailure, normalizeWarehouseSqlFailure, parseProposal, propose, proposePlan, recordGovernedCorrection, HintStore, defaultHintIndexPath, ensureHintIndexFresh, listHintsFromGit, getHintEvaluationFromGit, getCorrectionTraceFromGit, inspectGovernedHint, editGovernedHintCandidate, reopenGovernedHint, retireHint, supersedeHint, hintsConflict, mineJoinPatterns, reviewGovernedHint, AgentRunEngine, SqliteAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, createHybridRouter, computeResultStats, buildDeterministicDashboardStory, synthesizeAnswer, streamOrGenerate, narrateResult, buildProposePreview, buildFromPrompt, internalRelationIdsInSql, defaultAgentRunStorePath, defaultAgentRunSqlitePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, latestRuntimeSchemaSnapshotForProject, loadSkills, migrateLegacySkills, configuredSkillsPath, skillsDir, draftDomainSkillBootstrap, buildDomainSkillBootstrapPrompt, mergeDomainSkillBootstrapEnrichment, writeSkill, deleteSkill, deriveGeneratedDraftSlug, deriveAnalyticalRepair, reindexProject, invalidateAgentProjectState, recordAgentRuntimeVersion, resolveDomainContextEnvelope, projectEmbeddingProvider, isHashedEmbeddingProvider, clearProjectEmbeddingCache, upgradeVectorIndexForProject, openMetadataCatalog, defaultKgPath, planAppFromPrompt, KGStore, planResearch, loadSemanticMetrics, cascadeTraceToEvidenceRouteSteps, createCascadeAnswerResult, createCascadeTrace, routeReasoningEffort, routeForCascadeAnswerTier, clampReasoningEffort, bumpReasoningEffort, resolveThinkingMode, coerceThinkingMode, upsertGeneratedDqlArtifactDraft, loadAgentSemanticLayer, isTrustedConversationTurn, resolveInternalRelationIds, analyticalError, tagAnalyticalError, withAnalyticalErrorOrigin, withAnalyticalErrorOriginSync, } from '@duckcodeailabs/dql-agent';
+import { ClaudeProvider, ConversationStore, advanceThreadState, buildConversationSnapshot, conversationHistoryFromContext, recallRelevantTurns, renderConversationEnvelopeForPrompt, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildAnalysisQuestionPlan, composeSemanticQueryForQuestion, aggregationIntegrityIssuesForSql, buildLocalContextPack, applyContextPackCompatibility, toAgentRetrievalEvidence, prepareConversationPath, defaultMemoryPath, ensureDefaultMemoryFiles, ensureAgentProjectReady, isAgentProjectIndexReady, currentMetadataFingerprint, ensureMetadataCatalogFresh, readIndexedDomainKnowledge, readIndexedKnowledge360, compactSemanticRuntimeFailure, classifyAnalyticalFailure, normalizeWarehouseSqlFailure, parseProposal, propose, proposePlan, recordGovernedCorrection, HintStore, defaultHintIndexPath, ensureHintIndexFresh, listHintsFromGit, getHintEvaluationFromGit, getCorrectionTraceFromGit, inspectGovernedHint, editGovernedHintCandidate, reopenGovernedHint, retireHint, supersedeHint, hintsConflict, mineJoinPatterns, reviewGovernedHint, AgentRunEngine, SqliteAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, createHybridRouter, computeResultStats, buildDeterministicDashboardStory, synthesizeAnswer, streamOrGenerate, narrateResult, buildProposePreview, buildFromPrompt, internalRelationIdsInSql, defaultAgentRunStorePath, defaultAgentRunSqlitePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, latestRuntimeSchemaSnapshotForProject, loadSkills, migrateLegacySkills, configuredSkillsPath, skillsDir, draftDomainSkillBootstrap, buildDomainSkillBootstrapPrompt, mergeDomainSkillBootstrapEnrichment, writeSkill, previewSkillChange, buildContextAuthoringProposal, contextAuthoringDependencyClosure, FileContextAuthoringProposalStore, deleteSkill, deriveGeneratedDraftSlug, deriveAnalyticalRepair, reindexProject, invalidateAgentProjectState, recordAgentRuntimeVersion, resolveDomainContextEnvelope, projectEmbeddingProvider, isHashedEmbeddingProvider, clearProjectEmbeddingCache, upgradeVectorIndexForProject, openMetadataCatalog, defaultKgPath, planAppFromPrompt, KGStore, planResearch, loadSemanticMetrics, cascadeTraceToEvidenceRouteSteps, createCascadeAnswerResult, createCascadeTrace, routeReasoningEffort, routeForCascadeAnswerTier, clampReasoningEffort, bumpReasoningEffort, resolveThinkingMode, coerceThinkingMode, upsertGeneratedDqlArtifactDraft, loadAgentSemanticLayer, isTrustedConversationTurn, resolveInternalRelationIds, analyticalError, tagAnalyticalError, withAnalyticalErrorOrigin, withAnalyticalErrorOriginSync, } from '@duckcodeailabs/dql-agent';
 import { addSqlResultFilter, filterableResultColumns, replaceBlockStudioSql } from './sql-result-filter.js';
 import { gatherProposeEnrichment } from './propose-enrich.js';
-import { handleAppsApi, proposeAppAiBuild, recommendVisualization } from './apps-api.js';
+import { handleAppsApi, proposeAppAiBuild, recommendVisualization, } from './apps-api.js';
 import { getActiveProvider, getEffectiveProviderConfig, isProviderSettingsId, listProviderSettings, saveProviderSettings, } from './settings/provider-settings.js';
 import { ClaudeCodeCliProvider, CodexCliProvider } from './providers/subscription-cli.js';
 import { ClaudeOAuthManager, ClaudeOAuthProvider, claudeOAuthConnected, CLAUDE_OAUTH_MODELS, CLAUDE_OAUTH_DEFAULT_MODEL, } from './providers/oauth/claude-oauth.js';
@@ -85,6 +88,63 @@ function hasDbtSemanticArtifacts(projectRoot, dbtProjectDir, configuredManifestP
     return false;
 }
 const AGENT_RUN_REQUESTED_MODES = new Set(['auto', 'ask', 'research', 'sql', 'block', 'app']);
+/** AGT-007 / AGT-022: App-specific context adapter into the uniform AgentRun. */
+export function buildAppCopilotResearchAgentRequest(input) {
+    const memoOnly = input.mode === 'memo_only';
+    const appResearch = {
+        mode: 'app_research',
+        generationMode: input.mode ?? 'sql_and_memo',
+        intent: input.intent,
+        appId: input.appId,
+        dashboardId: input.dashboardId,
+        sourceTileId: input.sourceTileId,
+        sourceBlockId: input.sourceBlockId,
+        title: input.title,
+        instruction: [
+            'Answer as an app-scoped analyst. Start from certified block/result context, active filters, dbt/semantic metadata, and schema evidence.',
+            memoOnly
+                ? 'Write the stakeholder memo from the supplied selected result, preview rows, generated SQL, metrics, drivers, filters, and caveats. Do not generate replacement SQL unless the user explicitly asks to fix SQL.'
+                : 'Generate review-required read-only SQL only when the certified result does not exactly answer the requested analysis grain. Execute only through the bounded generated SQL preview path.',
+            'In the natural-language answer, write a stakeholder analysis memo, not a generic chat answer. Use Markdown headings chosen for the question, usually Executive answer, Key numbers, Drivers or Business readout, Caveats, and Next action.',
+            'Use concrete numbers from the selected result or preview when available. If baseline, segment, grain, lineage, or source proof is missing, say that explicitly instead of inventing a driver story.',
+            'Keep raw SQL in proposedSql/sql. Do not put SQL code fences or implementation trace in the memo body.',
+        ].join(' '),
+        generatedSql: input.generatedSql,
+        metrics: input.metrics,
+        drivers: input.drivers,
+        resultPreviews: input.resultPreviews,
+        summaryHint: input.summaryHint,
+        recommendationHint: input.recommendationHint,
+        sqlError: input.sqlError,
+        sqlErrorKind: input.sqlErrorKind,
+        hasReportEvidence: input.hasReportEvidence,
+        context: input.context,
+    };
+    return {
+        question: memoOnly
+            ? [
+                `Research question: ${input.question}`,
+                'Write the business memo now using only the evidence envelope supplied as upstream context.',
+                'Return Markdown sections. Keep SQL, query text, implementation trace, and raw routing details out of the memo body.',
+                'If the evidence is insufficient, state the gap and the next reviewer action instead of filling the story with generic text.',
+            ].join('\n')
+            : input.question,
+        requestedMode: 'research',
+        audience: 'stakeholder',
+        selectedObject: {
+            kind: 'app',
+            id: input.appId,
+            title: input.title,
+        },
+        analysisDepth: 'deep',
+        workspaceContext: {
+            surface: 'app_copilot',
+            appId: input.appId,
+            dashboardId: input.dashboardId,
+            appResearch,
+        },
+    };
+}
 const AGENT_RUN_SELECTED_OBJECT_KINDS = new Set([
     'notebook',
     'cell',
@@ -228,6 +288,7 @@ export function parseAgentRunRequestBody(body) {
         request: {
             question,
             selectedEvidenceId: agentRunString(record.selectedEvidenceId),
+            clarificationSourceQuestion: agentRunString(record.clarificationSourceQuestion),
             requestedMode,
             audience,
             intent: agentRunString(record.intent),
@@ -324,7 +385,16 @@ export function agentRunDeadlineMs(request, env = process.env, activeProviderId)
     if (request.requestedMode === 'research' || effectiveDepth === 'deep') {
         return scale(researchDeadline);
     }
-    const plan = buildAnalysisQuestionPlan(request.question);
+    // A structured clarification chip displays a compact metric/path label, but
+    // the engine restores and executes the original analytical question. Budget
+    // from that same original question as well. Otherwise a complex ranking or
+    // cross-model request can incorrectly inherit the 45s scalar-lookup budget
+    // merely because the selected label is short, then time out after the user
+    // already supplied the exact governed meaning.
+    const deadlineQuestion = request.selectedEvidenceId
+        ? request.clarificationSourceQuestion?.trim() || request.question
+        : request.question;
+    const plan = buildAnalysisQuestionPlan(deadlineQuestion);
     if (plan.needsResearchWorkspace || isAnalyticalBuildQuestion(plan)) {
         return scale(researchDeadline);
     }
@@ -418,6 +488,41 @@ export function repairableSqlFromAgentRun(run) {
     }
     return undefined;
 }
+/** Editable DQL retained on an immutable failed run, including its bound values. */
+export function repairableDqlArtifactFromAgentRun(run) {
+    for (const artifact of run.artifacts) {
+        const payload = agentRunRecord(artifact.payload);
+        if (!payload)
+            continue;
+        const dqlArtifact = normalizeDqlArtifactReference(payload.dqlArtifact);
+        // Only an ownerless/custom SQL block is editable in place. Certified and
+        // semantic artifacts remain immutable; their retained compiled SQL may
+        // still produce a separate review-required repair result below.
+        if (dqlArtifact?.kind === 'sql_block'
+            && dqlArtifact.source?.trim()
+            && notebookDqlSourceAllowsBackgroundRepair(dqlArtifact.source)) {
+            return dqlArtifact;
+        }
+    }
+    return undefined;
+}
+/**
+ * Keep the parameter surface immutable while repairing malformed DQL. A parser
+ * cannot reliably read a broken wrapper, so collect both declared parameter
+ * names and SQL interpolation names with a deliberately small lexical pass.
+ */
+export function dqlRepairParameterContract(source) {
+    const names = new Set();
+    for (const match of source.matchAll(/\$\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}/g)) {
+        names.add(match[1]);
+    }
+    for (const match of source.matchAll(/\bparams\s*\{([\s\S]*?)\}/gi)) {
+        for (const declaration of match[1].matchAll(/(?:^|\n)\s*([A-Za-z_][A-Za-z0-9_]*)\s*:/g)) {
+            names.add(declaration[1]);
+        }
+    }
+    return [...names].sort((left, right) => left.localeCompare(right));
+}
 /** Structured producer failure retained on the source run. */
 export function warehouseFailureFromAgentRun(run) {
     for (const artifact of run.artifacts) {
@@ -429,10 +534,49 @@ export function warehouseFailureFromAgentRun(run) {
     }
     return undefined;
 }
+/**
+ * Retain planning and retrieval evidence for a successful derived repair while
+ * deliberately dropping the source failure and any result-bound facts. This
+ * is the presentation contract used by "How it was answered" and by grounded
+ * follow-ups after repair.
+ */
+export function repairPresentationContextFromAgentRun(run) {
+    const retainedKeys = [
+        'resolvedAnalyticalPlan',
+        'analyticalExecutionGraph',
+        'analyticalFreshnessObservation',
+        'governedCompilationReceipt',
+        'governedAnalyticalGraphCompilationReceipt',
+        'contextPack',
+        'contextPackId',
+        'cascade',
+        'citations',
+        'lineage',
+    ];
+    const context = {};
+    for (const artifact of run.artifacts) {
+        const payload = agentRunRecord(artifact.payload);
+        if (!payload)
+            continue;
+        for (const key of retainedKeys) {
+            if (context[key] === undefined && payload[key] !== undefined)
+                context[key] = payload[key];
+        }
+        const semanticTrace = agentRunRecord(payload.semanticExecutionTrace);
+        if (context.semanticExecutionTrace === undefined && semanticTrace && !semanticTrace.failure) {
+            context.semanticExecutionTrace = semanticTrace;
+        }
+    }
+    return context;
+}
 /** Permission, authentication, policy and unsafe-query failures are never AI-repaired. */
 export function analyticalFailureAllowsDeterministicRetry(failure) {
     return !failure || !['permission', 'authentication', 'unsafe', 'cancelled'].includes(failure.category);
 }
+/** Structured policy/access refusals stay terminal even when retained SQL exists. */
+export function analyticalFailureAllowsAppRepair(failure) {
+    return !failure || !['PERMISSION_DENIED', 'POLICY_DENIED'].includes(failure.code);
+}
 function businessNarrativeGaps(warnings) {
     const businessRelevant = (warnings ?? []).filter((warning) => !(/missing requested output column/i.test(warning)
         || /\bquery plan\b/i.test(warning)
@@ -1011,11 +1155,11 @@ export async function startLocalServer(opts) {
     const resolveNamedConnection = (name) => {
         if (!name)
             return null;
-        const stored = getStoredConnections(projectConfig);
-        const normalized = normalizeStoredConnection(stored[name]);
-        return normalized
-            ? normalizeProjectConnection(normalized, projectRoot)
-            : null;
+        // `GET /api/connections` exposes the active legacy/default connection as
+        // `default` so every execution surface can present one uniform selector.
+        // Resolve that selector through the same project contract used by metadata
+        // APIs instead of looking only in the newer named `connections` map.
+        return projectConnectionById(projectRoot, projectConfig, name);
     };
     const resolveExecutionConnection = async (body) => {
         const target = body.executionTarget && typeof body.executionTarget === "object"
@@ -1104,6 +1248,35 @@ export async function startLocalServer(opts) {
     // unchanged. Explicit refresh, save, and certification paths still request
     // the default forced rebuild below.
     await refreshLocalMetadataCatalog(projectRoot, undefined, undefined, false);
+    // PERF-001 / API-001: project mutations acknowledge after their source file
+    // is durable. Rebuildable manifest, lineage, metadata, and KG projections run
+    // in one coalesced worker lane and remain observable across page navigation.
+    const operationCoordinator = new LocalOperationCoordinator(join(projectRoot, '.dql', 'cache', 'operations.sqlite'));
+    const operationSseClients = new Set();
+    const operationIdempotency = new Map();
+    const projectRefreshCoordinator = new ProjectRefreshCoordinator(operationCoordinator, () => {
+        projectSnapshots.invalidate();
+        dbtNodeDetailCache.clear();
+        invalidateAgentProjectState(projectRoot);
+        _lineageCache.delete(projectRoot);
+    });
+    const scheduleProjectRefresh = (reason, writeManifest = true) => (projectRefreshCoordinator.schedule({
+        projectRoot,
+        dbtManifestPath: resolveDbtManifestPath(projectRoot, projectConfig) ?? undefined,
+        writeManifest,
+        reason,
+    }));
+    const unsubscribeOperationEvents = operationCoordinator.subscribe((operation) => {
+        const payload = serializeJSON(operation);
+        for (const client of operationSseClients) {
+            try {
+                client.write(`event: operation\ndata: ${payload}\n\n`);
+            }
+            catch {
+                operationSseClients.delete(client);
+            }
+        }
+    });
     const startupDbtManifestPath = resolveDbtManifestPath(projectRoot, projectConfig);
     if (startupDbtManifestPath && !isAgentProjectIndexReady(projectRoot)) {
         try {
@@ -1185,8 +1358,8 @@ export async function startLocalServer(opts) {
             catch { /* non-fatal */ }
         }
     }
-    const executeLocalSqlForStoredResult = async (sql) => {
-        const activeConnection = requireActiveConnection();
+    const executeLocalSqlForStoredResult = async (sql, executionConnection) => {
+        const activeConnection = requireActiveConnection(executionConnection);
         const semantic = prepareSemanticSql(sql, semanticLayer);
         if (semantic.unresolvedRefs.length > 0) {
             throw new Error(`Unknown semantic reference${semantic.unresolvedRefs.length > 1 ? 's' : ''}: ${semantic.unresolvedRefs.join(', ')}`);
@@ -2239,7 +2412,12 @@ export async function startLocalServer(opts) {
             : isTerminalFailure
                 ? terminalFailureActions
                 : isGroundingGap
-                    ? [{ id: 'research-gap', label: 'Research missing metadata coverage', route: 'research', artifactKind: 'research_run' }]
+                    ? governedAnswer.refusalCode === 'modeling_gap'
+                        ? [
+                            { id: 'fix-modeling-gap', label: 'Fix with Modeling AI', route: 'modeling_draft', artifactKind: 'modeling_change_proposal' },
+                            { id: 'research-gap', label: 'Research missing metadata coverage', route: 'research', artifactKind: 'research_run' },
+                        ]
+                        : [{ id: 'research-gap', label: 'Research missing metadata coverage', route: 'research', artifactKind: 'research_run' }]
                     : [
                         { id: 'create-block', label: governedAnswer.dqlArtifact ? 'Review DQL draft' : 'Create DQL draft', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
                         { id: 'research-gap', label: 'Research deeper', route: 'research' },
@@ -2412,11 +2590,175 @@ export async function startLocalServer(opts) {
             nextActions,
         };
     };
+    const contextProposalStore = new FileContextAuthoringProposalStore(projectRoot);
+    const previewContextAuthoring = (input) => {
+        const snapshot = projectSnapshot();
+        if (input.expectedSnapshotId && input.expectedSnapshotId !== snapshot.snapshotId) {
+            throw Object.assign(new Error('Project sources changed before the authoring proposal was previewed.'), { code: 'PROPOSAL_STALE' });
+        }
+        if (input.operations.length === 0)
+            throw Object.assign(new Error('At least one authoring operation is required.'), { code: 'INVALID_REQUEST' });
+        const diagnostics = [...(input.diagnostics ?? [])];
+        const operations = input.operations.map((operation) => {
+            if (operation.kind === 'skill_change') {
+                const value = { ...operation.value };
+                value.status = 'draft';
+                if (value.sourceRefs?.some((reference) => !contextSourceReferenceExists(snapshot.manifest, reference))) {
+                    diagnostics.push({ code: 'UNKNOWN_GOVERNED_REFERENCE', severity: 'blocking', operationId: operation.id, message: 'The Skill proposal references a model or relationship that is not present in the current snapshot.' });
+                }
+                return { ...operation, value };
+            }
+            if (operation.kind !== 'modeling_change')
+                return operation;
+            if ((input.origin === 'ai' || input.origin === 'correction') && operation.change.operation.startsWith('remove_')) {
+                diagnostics.push({ code: 'AI_DELETE_FORBIDDEN', severity: 'blocking', operationId: operation.id, message: 'Modeling AI can create or update context, but it cannot delete governed source.' });
+            }
+            if (operation.change.operation === 'upsert_relationship') {
+                const current = operation.change.value;
+                if (current.crossDomain && (input.origin === 'ai' || input.origin === 'yaml_import')) {
+                    diagnostics.push({ code: 'CROSS_DOMAIN_IMPORT_FORBIDDEN', severity: 'blocking', operationId: operation.id, message: 'Cross-domain relationships require the explicit export, contract, and import workflow.' });
+                }
+                if (input.origin === 'ai' || input.origin === 'correction' || input.origin === 'yaml_import') {
+                    return {
+                        ...operation,
+                        change: {
+                            ...operation.change,
+                            value: {
+                                ...current,
+                                status: 'draft',
+                                fanout: current.fanout === 'unsafe' ? 'forbidden' : current.fanout,
+                                certifiedAgainst: undefined,
+                                validation: undefined,
+                            },
+                        },
+                    };
+                }
+            }
+            if (operation.change.operation === 'upsert_entity'
+                && (input.origin === 'ai' || input.origin === 'yaml_import' || input.origin === 'dbt_discovery')
+                && !operation.change.value.areaId) {
+                diagnostics.push({ code: 'MODEL_AREA_REQUIRED', severity: 'blocking', operationId: operation.id, message: 'Imported and AI-authored models must target one Model Area.' });
+            }
+            return operation;
+        });
+        const operationIds = new Set(operations.map((operation) => operation.id));
+        for (const operation of operations) {
+            for (const dependency of operation.dependsOn ?? []) {
+                if (!operationIds.has(dependency))
+                    diagnostics.push({ code: 'DEPENDENCY_CONFLICT', severity: 'blocking', operationId: operation.id, message: `Required proposal operation is missing: ${dependency}` });
+            }
+        }
+        const patches = [];
+        const modelingOperations = operations.filter((operation) => operation.kind === 'modeling_change');
+        if (modelingOperations.length > 0) {
+            const batch = previewModelingChanges(projectRoot, modelingOperations.map((operation) => operation.change));
+            for (const patch of batch.patches) {
+                const owner = modelingOperations.find((operation) => {
+                    const single = previewModelingChange(projectRoot, operation.change);
+                    return single.patches.some((candidate) => candidate.path === patch.path);
+                })?.id ?? modelingOperations[0].id;
+                patches.push({ ...patch, owner: 'dql', operationId: owner });
+            }
+        }
+        for (const operation of operations) {
+            if (operation.kind === 'skill_change') {
+                const preview = previewSkillChange(projectRoot, operation.value, operation.targetQualifiedId, operation.expectedSourceHash);
+                for (const patch of preview.patches) {
+                    patches.push({
+                        path: relative(projectRoot, patch.path).replace(/\\/g, '/'),
+                        before: patch.before,
+                        after: patch.after,
+                        changed: patch.changed,
+                        owner: 'dql',
+                        operationId: operation.id,
+                    });
+                }
+            }
+            else if (operation.kind === 'dbt_source_change') {
+                const { dbtProjectDir, manifestPath } = onboardingDbtPaths({});
+                const preview = previewDbtSourcePatch(dbtProjectDir, manifestPath, operation.change);
+                patches.push({
+                    path: relative(projectRoot, resolve(dbtProjectDir, preview.patch.path)).replace(/\\/g, '/'),
+                    before: preview.patch.before,
+                    after: preview.patch.after,
+                    changed: preview.patch.changed,
+                    owner: 'dbt',
+                    operationId: operation.id,
+                });
+            }
+        }
+        const duplicatePaths = patches.map((patch) => patch.path).filter((path, index, values) => values.indexOf(path) !== index);
+        for (const path of [...new Set(duplicatePaths)])
+            diagnostics.push({ code: 'OWNERSHIP_CONFLICT', severity: 'blocking', message: `More than one proposal operation owns ${path}. Repreview after resolving the conflict.` });
+        const dependencyFingerprints = Object.fromEntries(patches.map((patch) => [
+            patch.path,
+            createHash('sha256').update(patch.before).digest('hex'),
+        ]));
+        const proposal = buildContextAuthoringProposal({
+            origin: input.origin,
+            baseSnapshotId: snapshot.snapshotId,
+            dependencyFingerprints,
+            operations,
+            patches,
+            diagnostics,
+            sourceRunId: input.sourceRunId,
+            sourceArtifactId: input.sourceArtifactId,
+            revision: input.revision,
+        });
+        contextProposalStore.save(proposal);
+        return proposal;
+    };
+    const modelingAuthoringRunExecutor = async ({ runId, request }) => {
+        const snapshot = projectSnapshot();
+        const operations = buildMetadataBoundModelingOperations(projectRoot, snapshot.manifest, request);
+        const proposal = previewContextAuthoring({
+            origin: request.workspaceContext?.correction === true ? 'correction' : 'ai',
+            operations,
+            expectedSnapshotId: typeof request.workspaceContext?.snapshotId === 'string' ? request.workspaceContext.snapshotId : snapshot.snapshotId,
+            sourceRunId: runId,
+            revision: Number(request.workspaceContext?.revision ?? 1),
+        });
+        return {
+            summary: `Prepared ${proposal.impact.modelingChanges} metadata-bound modeling change${proposal.impact.modelingChanges === 1 ? '' : 's'} for review.`,
+            answer: proposal.diagnostics.some((item) => item.severity === 'blocking')
+                ? 'I prepared a modeling proposal, but the blocking items must be resolved before it can be saved.'
+                : 'I prepared an evidence-bound modeling proposal. Review the exact source diff before saving it as a draft.',
+            status: 'needs_review',
+            trustState: 'review_required',
+            stopReason: 'human_review_required',
+            artifacts: [{ id: `${runId}:modeling-proposal`, kind: 'modeling_change_proposal', title: 'Modeling change proposal', trustState: 'review_required', ref: proposal.id, payload: proposal }],
+            evaluations: proposal.diagnostics.map((diagnostic) => ({ id: `${proposal.id}:${diagnostic.code}`, label: diagnostic.code, passed: diagnostic.severity !== 'blocking', severity: diagnostic.severity, message: diagnostic.message })),
+            nextActions: [{ id: 'review-modeling-proposal', label: 'Review in Modeling', artifactKind: 'modeling_change_proposal' }],
+        };
+    };
+    const skillAuthoringRunExecutor = async ({ runId, request }) => {
+        const snapshot = projectSnapshot();
+        const operations = buildMetadataBoundSkillOperations(projectRoot, snapshot.manifest, request);
+        const proposal = previewContextAuthoring({
+            origin: request.workspaceContext?.correction === true ? 'correction' : 'ai',
+            operations,
+            expectedSnapshotId: typeof request.workspaceContext?.snapshotId === 'string' ? request.workspaceContext.snapshotId : snapshot.snapshotId,
+            sourceRunId: runId,
+            revision: Number(request.workspaceContext?.revision ?? 1),
+        });
+        return {
+            summary: `Prepared ${proposal.impact.skillChanges} metadata-bound Skill change${proposal.impact.skillChanges === 1 ? '' : 's'} for review.`,
+            answer: 'I prepared a scope-qualified Skill draft. It will not guide an agent unless you save it and later activate it explicitly.',
+            status: 'needs_review',
+            trustState: 'review_required',
+            stopReason: 'human_review_required',
+            artifacts: [{ id: `${runId}:skill-proposal`, kind: 'skill_change_proposal', title: 'Skill change proposal', trustState: 'review_required', ref: proposal.id, payload: proposal }],
+            evaluations: proposal.diagnostics.map((diagnostic) => ({ id: `${proposal.id}:${diagnostic.code}`, label: diagnostic.code, passed: diagnostic.severity !== 'blocking', severity: diagnostic.severity, message: diagnostic.message })),
+            nextActions: [{ id: 'review-skill-proposal', label: 'Review Skill draft', artifactKind: 'skill_change_proposal' }],
+        };
+    };
     const agentRunExecutors = {
         conversation: conversationRunExecutor,
         certified_answer: answerRunExecutor,
         semantic_answer: answerRunExecutor,
         generated_answer: answerRunExecutor,
+        modeling_draft: modelingAuthoringRunExecutor,
+        skill_draft: skillAuthoringRunExecutor,
         research: async (researchContext) => {
             const { runId, request, routeDecision, emit } = researchContext;
             const metrics = loadSemanticMetrics(projectRoot);
@@ -2453,6 +2795,23 @@ export async function startLocalServer(opts) {
             const needsClarification = Boolean(plan.followUp);
             const notebookPath = agentRunNotebookPath(request, runId);
             const researchIntent = agentRunResearchIntent(request);
+            const researchSource = agentRunRecord(request.workspaceContext?.researchSource);
+            const researchExecutionConnection = !needsClarification && request.executionTarget
+                ? await resolveAgentRunExecutionConnection(request)
+                : undefined;
+            const researchExecutionConnectionName = request.executionTarget?.target === 'connection'
+                ? request.executionTarget.connectionName
+                : undefined;
+            const researchContextEnvelope = {
+                surface: 'unified_agent_run',
+                agentRunId: runId,
+                routeDecision,
+                selectedObject: request.selectedObject,
+                executionTarget: request.executionTarget,
+                workspaceContext: request.workspaceContext,
+                researchSource,
+                plan,
+            };
             let researchRun;
             let researchWorkspaceError;
             if (!needsClarification) {
@@ -2474,14 +2833,7 @@ export async function startLocalServer(opts) {
                             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,
-                            },
+                            context: researchContextEnvelope,
                         });
                         emit({
                             type: 'artifact.created',
@@ -2496,14 +2848,13 @@ export async function startLocalServer(opts) {
                             sourceCellFingerprint,
                             question: request.question,
                             intent: researchIntent,
-                            context: {
-                                surface: 'unified_agent_run',
-                                agentRunId: runId,
-                                routeDecision,
-                                selectedObject: request.selectedObject,
-                                workspaceContext: request.workspaceContext,
-                                plan,
-                            },
+                            context: researchContextEnvelope,
+                            executionConnection: researchExecutionConnection,
+                            executionConnectionName: researchExecutionConnectionName,
+                            signal: request.signal,
+                            baselineSql: agentRunString(researchSource?.sql),
+                            baselineDqlArtifact: researchSource?.dqlArtifact,
+                            baselineRunId: agentRunString(researchSource?.runId),
                         });
                         researchRun = withNotebookResearchChecklist(executed);
                     }
@@ -2816,7 +3167,7 @@ export async function startLocalServer(opts) {
                             message: `Generating review-required SQL for an uncovered question: ${question}`,
                             route: 'app_build',
                         });
-                        return runGovernedAgentAnswerForRun({ question });
+                        return generateAppBuildAnswerWithRepair(question);
                     },
                 });
             }
@@ -3716,13 +4067,15 @@ export async function startLocalServer(opts) {
      * evidence. The refusal can say the relation is not visible to this
      * connection, rather than only that DQL had not looked at it.
      */
-    const probeNamedRelationsForAgent = async (relations, probeConnection) => {
+    const probeNamedRelationsForAgent = async (relations, probeConnection, verifyExecutionSchema = false) => {
         const probeTarget = probeConnection ?? connection;
         if (!probeTarget)
             return undefined;
-        // Same operator switch that governs live value grounding: a deployment that
-        // wants zero live metadata traffic keeps it.
-        if (resolveAgentRuntimeValueGrounding(projectConfig).mode !== 'safe_automatic')
+        // Named relation discovery remains behind the operator's live-grounding
+        // switch. Executable schema verification is different: it is a bounded,
+        // read-only metadata point lookup for relations already selected from dbt,
+        // and never reads row values or mutates the active target.
+        if (!verifyExecutionSchema && resolveAgentRuntimeValueGrounding(projectConfig).mode !== 'safe_automatic')
             return undefined;
         const sql = buildNamedRelationProbeSql(relations);
         if (!sql)
@@ -3775,12 +4128,29 @@ export async function startLocalServer(opts) {
             && activeRuntimeSnapshot.status !== 'stale');
         const valueGrounding = resolveAgentRuntimeValueGrounding(projectConfig);
         if (catalogContext.length > 0) {
-            if (!schemaConnection || valueGrounding.mode !== 'safe_automatic')
+            if (!schemaConnection)
                 return catalogContext;
-            // The immutable dbt/DQL snapshot already owns schema discovery. A named
-            // row value must not turn a warm Ask into an information_schema scan over
-            // thousands of enterprise tables; only field-scoped value probes are live.
-            const enriched = await enrichAgentSchemaContextWithValueMatches(question, catalogContext, executor, schemaConnection, valueGrounding.searchSafeColumns);
+            // dbt metadata is the semantic authority, but generated SQL must use the
+            // physical columns visible on THIS execution target. Verify only the few
+            // question-ranked relations with a bounded information_schema point lookup;
+            // this is read-only and never mutates DuckDB, Snowflake, or any other target.
+            let executionSchema = catalogContext;
+            try {
+                const live = await probeNamedRelationsForAgent(catalogContext.slice(0, 4).map((table) => table.relation), schemaConnection, true);
+                if (live?.schemaContext?.length) {
+                    executionSchema = reconcileAgentSchemaContextWithLive(catalogContext, live.schemaContext);
+                }
+            }
+            catch {
+                // Live verification is additive. Existing metadata remains available if
+                // the connection cannot expose information_schema to this user.
+            }
+            // The immutable dbt/DQL snapshot owns schema discovery. Live verification
+            // only confirms those named relations; row values remain governed by the
+            // separate allowlisted grounding policy below.
+            if (valueGrounding.mode !== 'safe_automatic')
+                return executionSchema;
+            const enriched = await enrichAgentSchemaContextWithValueMatches(question, executionSchema, executor, schemaConnection, valueGrounding.searchSafeColumns);
             return enriched;
         }
         // An activated, scope-qualified warehouse generation is the complete warm
@@ -3912,83 +4282,365 @@ export async function startLocalServer(opts) {
         }
         return { result, repairedSql, repairMode, firstFailure, rewrites };
     };
-    const generateInvestigationSqlForApp = async (input) => {
-        const governed = resolveGovernedAnswerRunner(projectRoot);
-        const resolvedProvider = governed?.provider ?? null;
-        const runner = governed?.runner ?? null;
-        if (!resolvedProvider || !runner) {
-            throw new Error('No AI provider is configured. Configure a subscription (Claude Code / Codex), OpenAI, Gemini, Ollama, or a custom OpenAI-compatible endpoint in Settings.');
+    /**
+     * Repair a DQL wrapper that cannot compile far enough to expose executable
+     * SQL. This is the DQL-side half of the same bounded repair contract used by
+     * Ask and Notebook: one provider call, one block, identical parameters, one
+     * read-only execution, and the exact target selected by the failed run.
+     */
+    const executeBoundedDqlRepair = async (input) => {
+        const provider = await createBlockStudioAssistProvider(projectRoot);
+        if (!provider) {
+            throw boundedRepairError('Configure an available AI provider in Settings to repair this DQL draft.', 409);
         }
-        let governedAnswer;
-        let providerError;
-        const memoOnly = input.mode === 'memo_only';
-        const reasoningEffort = resolveRunReasoningEffort(projectRoot, resolvedProvider, 'research', false);
-        const contextEnvelope = {
-            mode: 'app_research',
-            generationMode: input.mode ?? 'sql_and_memo',
-            intent: input.intent,
-            appId: input.appId,
-            dashboardId: input.dashboardId,
-            sourceTileId: input.sourceTileId,
-            sourceBlockId: input.sourceBlockId,
-            title: input.title,
-            instruction: [
-                'Answer as an app-scoped analyst. Start from certified block/result context, active filters, dbt/semantic metadata, and schema evidence.',
-                memoOnly
-                    ? 'Write the stakeholder memo from the supplied selected result, preview rows, generated SQL, metrics, drivers, filters, and caveats. Do not generate replacement SQL unless the user explicitly asks to fix SQL.'
-                    : 'Generate review-required read-only SQL only when the certified result does not exactly answer the requested analysis grain. Execute only through the bounded generated SQL preview path.',
-                'In the natural-language answer, write a stakeholder analysis memo, not a generic chat answer. Use Markdown headings chosen for the question, usually Executive answer, Key numbers, Drivers or Business readout, Caveats, and Next action.',
-                'Use concrete numbers from the selected result or preview when available. If baseline, segment, grain, lineage, or source proof is missing, say that explicitly instead of inventing a driver story.',
-                'Keep raw SQL in proposedSql/sql. Do not put SQL code fences or implementation trace in the memo body.',
-            ].join(' '),
-            generatedSql: input.generatedSql,
-            metrics: input.metrics,
-            drivers: input.drivers,
-            resultPreviews: input.resultPreviews,
-            summaryHint: input.summaryHint,
-            recommendationHint: input.recommendationHint,
-            sqlError: input.sqlError,
-            sqlErrorKind: input.sqlErrorKind,
-            hasReportEvidence: input.hasReportEvidence,
-            context: input.context,
-        };
-        const controller = new AbortController();
-        await runner.run({
-            provider: resolvedProvider,
-            messages: [{
+        let schemaContext;
+        try {
+            // Include source identifiers in retrieval so a terse cell title still
+            // resolves the physical dbt relations and live target columns it uses.
+            schemaContext = await getSchemaContextForAgent(`${input.question}\n${input.source.slice(0, 6_000)}`, undefined, input.targetConnection, input.targetConnectionName);
+        }
+        catch (error) {
+            const failure = normalizeWarehouseSqlFailure(error, input.targetConnection.driver);
+            throw boundedRepairError(failure.redactedMessage, 422, failure);
+        }
+        const boundedSchema = schemaContext.slice(0, 16).map((table) => ({
+            relation: table.relation,
+            columns: table.columns.slice(0, 40).map((column) => ({ name: column.name, type: column.type })),
+        }));
+        let raw;
+        try {
+            raw = await provider.generate([
+                {
+                    role: 'system',
+                    content: [
+                        'Repair one malformed executable DQL custom block and its embedded read-only SQL.',
+                        'Return only one JSON object with exactly one key named dql. Do not use markdown.',
+                        'The DQL shape is: block "Name" { type = "custom" params { name: type = default } query = """SELECT ...""" visualization { ... } tests { ... } }.',
+                        'Preserve the block name, business fields, visualization, tests, requested grain, filters, output columns, and aggregation semantics.',
+                        'Preserve every declared parameter and every ${parameter} interpolation exactly. Do not add or remove parameters.',
+                        'Use only relations and columns present in the supplied schema context.',
+                        'Never emit internal relation identities such as source::, model::, seed::, or snapshot::.',
+                        'Return exactly one custom block. Never certify it, bind a saved block, add writes, DDL, or multiple SQL statements.',
+                    ].join(' '),
+                },
+                {
                     role: 'user',
-                    content: memoOnly
-                        ? [
-                            `Research question: ${input.question}`,
-                            'Write the business memo now using only the evidence envelope supplied as upstream context.',
-                            'Return Markdown sections. Keep SQL, query text, implementation trace, and raw routing details out of the memo body.',
-                            'If the evidence is insufficient, state the gap and the next reviewer action instead of filling the story with generic text.',
-                        ].join('\n')
-                        : input.question,
-                }],
-            upstream: {
-                cellId: `app-research:${input.appId}:${input.dashboardId ?? 'app'}`,
-                sql: JSON.stringify(contextEnvelope, null, 2),
+                    content: JSON.stringify({
+                        question: input.question,
+                        driver: input.targetConnection.driver,
+                        failure: input.failure.slice(0, 2_000),
+                        dql: input.source.slice(0, 40_000),
+                        parameters: input.parameters ?? {},
+                        schema: boundedSchema,
+                    }),
+                },
+            ], { maxTokens: 2400, temperature: 0 });
+        }
+        catch {
+            throw boundedRepairError('The AI provider could not complete this DQL repair. Check Provider Settings and retry.', 502);
+        }
+        let repairedSource;
+        try {
+            const parsed = parseFirstJsonObject(raw);
+            repairedSource = parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+                && typeof parsed.dql === 'string'
+                ? String(parsed.dql).trim()
+                : undefined;
+        }
+        catch {
+            repairedSource = undefined;
+        }
+        if (!repairedSource) {
+            throw boundedRepairError('The AI repair did not return a complete DQL block.', 422);
+        }
+        if (repairedSource.length > 50_000) {
+            throw boundedRepairError('The repaired DQL exceeded the safe editable-draft size limit.', 422);
+        }
+        if (/^\s*@block\(/i.test(repairedSource) || /\btype\s*=\s*"semantic"/i.test(repairedSource)) {
+            throw boundedRepairError('The repair changed this editable custom block into a governed reference or semantic block.', 422);
+        }
+        if (!/\bstatus\s*=\s*"certified"/i.test(input.source)
+            && /\bstatus\s*=\s*"certified"/i.test(repairedSource)) {
+            throw boundedRepairError('The repair attempted to certify an AI-edited block, so DQL stopped it.', 422);
+        }
+        const beforeParameters = dqlRepairParameterContract(input.source);
+        const afterParameters = dqlRepairParameterContract(repairedSource);
+        if (beforeParameters.join('|') !== afterParameters.join('|')) {
+            throw boundedRepairError('The repair changed this block\'s parameter contract, so DQL stopped it before execution.', 422);
+        }
+        let invocation;
+        let plan;
+        try {
+            const program = new Parser(repairedSource, '<bounded-dql-repair>').parse();
+            const blocks = program.statements.filter((statement) => statement.kind === NodeKind.BlockDecl);
+            if (blocks.length !== 1 || program.statements.length !== 1) {
+                throw new Error('The repaired source must contain exactly one DQL block.');
+            }
+            const block = blocks[0];
+            if (block.kind !== NodeKind.BlockDecl || block.blockType !== 'custom') {
+                throw new Error('The repaired source must remain a custom DQL block.');
+            }
+            invocation = prepareBlockInvocation({
+                source: repairedSource,
+                parameters: input.parameters,
+                question: input.question,
+                surface: 'notebook',
+            });
+            if (invocation.errors.length)
+                throw new Error(invocation.errors.join(' '));
+            if (invocation.unresolvedParameters.length) {
+                throw new Error(`Provide required parameters before retrying: ${invocation.unresolvedParameters.join(', ')}.`);
+            }
+            plan = buildExecutionPlan({
+                id: 'bounded-dql-repair',
+                type: 'dql',
+                source: repairedSource,
+                title: input.artifactName,
+            }, {
+                semanticLayer,
+                driver: input.targetConnection.driver,
+                parameters: invocation.values,
+            });
+            if (!plan?.sql?.trim())
+                throw new Error('The repaired DQL did not compile to SQL.');
+        }
+        catch (error) {
+            throw boundedRepairError(`The repaired DQL did not compile safely: ${error instanceof Error ? error.message : String(error)}`, 422);
+        }
+        const seed = {
+            kind: 'sql_block',
+            source: repairedSource,
+            name: input.artifactName ?? plan.title,
+            persistence: 'transient',
+            trustState: 'review_required',
+            compiledSql: plan.sql,
+            ...(invocation.parameters.length ? { parameters: invocation.parameters } : {}),
+            ...(Object.keys(invocation.values).length ? { parameterValues: invocation.values } : {}),
+        };
+        let result;
+        try {
+            result = await executeGeneratedSqlDirect(input.question, plan.sql, seed, input.targetConnection, { sqlParams: plan.sqlParams, variables: { ...plan.variables, ...invocation.values } });
+        }
+        catch (error) {
+            const failure = normalizeWarehouseSqlFailure(error, input.targetConnection.driver);
+            throw boundedRepairError(failure.redactedMessage, 422, failure);
+        }
+        result = {
+            ...result,
+            dqlArtifact: {
+                ...(result.dqlArtifact ?? seed),
+                source: repairedSource,
+                compiledSql: result.sql ?? plan.sql,
+                trustState: 'review_required',
+                persistence: 'transient',
+                ...(result.executionReceipt ? { executionReceipt: result.executionReceipt } : {}),
             },
-            reasoningEffort,
-            analysisDepth: 'deep',
-            projectRoot,
-            executeCertifiedBlock: executeCertifiedBlockForAgent,
-            executeGeneratedSql: executeGeneratedSqlForAgent,
-            getSchemaContext: getSchemaContextForAgent,
-        }, (turn) => {
-            if (turn.kind === 'tool_result' && turn.id === 'governed_answer') {
-                governedAnswer = turn.output;
+        };
+        return {
+            result,
+            repairedSql: plan.sql,
+            repairedSource,
+            repairMode: 'ai',
+            rewrites: [],
+            sqlParams: plan.sqlParams,
+            variables: { ...plan.variables, ...invocation.values },
+        };
+    };
+    /**
+     * App proposal parity with Ask/Notebook repair. The first governed attempt is
+     * retained unchanged. Only an execution failure with retained read-only SQL
+     * may spend the shared one-attempt repair budget, on the same connection.
+     * The repaired candidate is still exploratory and review-required.
+     */
+    const generateAppBuildAnswerWithRepair = async (question, appContext) => {
+        const request = {
+            question,
+            audience: 'stakeholder',
+            workspaceContext: appContext
+                ? { surface: 'app_builder', appContext }
+                : { surface: 'app_builder' },
+        };
+        const answer = await runGovernedAgentAnswerForRun(request);
+        const sourceSql = answer.proposedSql?.trim() || answer.sql?.trim();
+        const hasExecutionFailure = agentAnswerHasExecutionFailure(answer)
+            || Boolean(answer.warehouseFailure)
+            || Boolean(answer.analyticalFailure);
+        if (answer.result || !sourceSql || !hasExecutionFailure)
+            return answer;
+        const attemptedAt = new Date().toISOString();
+        const originalFailure = answer.warehouseFailure?.redactedMessage
+            ?? answer.executionError
+            ?? 'The generated query did not execute.';
+        const originalSqlFingerprint = `sha256:${createHash('sha256').update(sourceSql).digest('hex')}`;
+        const failedTrace = (message) => ({
+            version: 1,
+            status: 'failed',
+            source: 'query_generator',
+            attemptedAt,
+            originalFailure,
+            originalSqlFingerprint,
+            approvalEligible: false,
+            message,
+        });
+        if (!analyticalFailureAllowsDeterministicRetry(answer.warehouseFailure)
+            || !analyticalFailureAllowsAppRepair(answer.analyticalFailure)) {
+            return {
+                ...answer,
+                appBuilderRepair: failedTrace('This failure needs an access, policy, or connection decision and was not sent to AI repair.'),
+            };
+        }
+        try {
+            const targetConnection = await resolveAgentRunExecutionConnection(request);
+            const targetConnectionName = request.executionTarget?.target === 'connection'
+                ? request.executionTarget.connectionName
+                : request.executionTarget?.target === 'local'
+                    ? 'local'
+                    : projectConfig.defaultConnectionName;
+            const repaired = await executeBoundedSqlRepair({
+                question,
+                sourceSql,
+                targetConnection,
+                targetConnectionName,
+            });
+            const repair = {
+                version: 1,
+                status: 'repaired',
+                source: 'query_generator',
+                mode: repaired.repairMode,
+                attemptedAt,
+                originalFailure,
+                originalSqlFingerprint,
+                repairedSqlFingerprint: `sha256:${createHash('sha256').update(repaired.repairedSql).digest('hex')}`,
+                approvalEligible: false,
+                message: `${repaired.repairMode === 'ai' ? 'AI' : 'Deterministic'} repair executed successfully on the same data target. Review the repaired query before adding it to the private App draft.`,
+            };
+            return {
+                ...answer,
+                result: repaired.result,
+                proposedSql: repaired.repairedSql,
+                sql: repaired.repairedSql,
+                executionError: undefined,
+                warehouseFailure: undefined,
+                analyticalFailure: undefined,
+                validationWarnings: [
+                    ...(answer.validationWarnings ?? []),
+                    repair.message,
+                ],
+                appBuilderRepair: repair,
+            };
+        }
+        catch (error) {
+            return {
+                ...answer,
+                appBuilderRepair: failedTrace(error instanceof Error
+                    ? `The bounded repair could not complete: ${error.message}`
+                    : 'The bounded repair could not complete.'),
+            };
+        }
+    };
+    const repairFailedAppTileExecution = async (input) => {
+        const attemptedAt = new Date().toISOString();
+        const driver = input.targetConnection?.driver ?? connection?.driver ?? 'duckdb';
+        const failure = normalizeWarehouseSqlFailure(input.error, driver);
+        const originalFailure = failure.redactedMessage;
+        const originalSqlFingerprint = input.sourceSql
+            ? `sha256:${createHash('sha256').update(input.sourceSql).digest('hex')}`
+            : undefined;
+        const failed = (message) => ({
+            ok: false,
+            repair: {
+                version: 1,
+                status: 'failed',
+                source: input.source,
+                attemptedAt,
+                originalFailure,
+                ...(originalSqlFingerprint ? { originalSqlFingerprint } : {}),
+                approvalEligible: false,
+                message,
+            },
+        });
+        if (!input.targetConnection) {
+            return failed('Configure the original data target before retrying this App tile.');
+        }
+        if (!input.sourceSql?.trim() && input.sourceDql?.trim()) {
+            try {
+                const repaired = await executeBoundedDqlRepair({
+                    question: input.question,
+                    source: input.sourceDql,
+                    failure: originalFailure,
+                    targetConnection: input.targetConnection,
+                    targetConnectionName: input.targetConnectionName,
+                    parameters: input.variables,
+                    artifactName: input.artifactName,
+                });
+                const repair = {
+                    version: 1,
+                    status: 'repaired',
+                    source: input.source,
+                    mode: repaired.repairMode,
+                    attemptedAt,
+                    originalFailure,
+                    repairedSqlFingerprint: `sha256:${createHash('sha256').update(repaired.repairedSql).digest('hex')}`,
+                    approvalEligible: false,
+                    message: `${repaired.repairMode === 'ai' ? 'AI' : 'Deterministic'} DQL repair executed successfully on the same data target. The App result remains review-required and the source file was not changed.`,
+                };
+                return {
+                    ok: true,
+                    result: repaired.result,
+                    repairedSql: repaired.repairedSql,
+                    repairedDql: repaired.repairedSource,
+                    repair,
+                };
             }
-            if (turn.kind === 'error') {
-                providerError = turn.message;
+            catch (error) {
+                return failed(error instanceof Error
+                    ? `The bounded DQL repair could not complete: ${error.message}`
+                    : 'The bounded DQL repair could not complete.');
             }
-        }, controller.signal);
-        if (!governedAnswer) {
-            throw new Error(providerError ?? 'The AI provider did not return a governed answer.');
         }
+        if (!input.sourceSql?.trim()) {
+            return failed('DQL retained the failure, but no read-only SQL or editable DQL was available for bounded repair.');
+        }
+        if (!analyticalFailureAllowsDeterministicRetry(failure)) {
+            return failed('This failure needs an access, policy, or connection decision and was not sent to AI repair.');
+        }
+        try {
+            const repaired = await executeBoundedSqlRepair({
+                question: input.question,
+                sourceSql: input.sourceSql,
+                targetConnection: input.targetConnection,
+                targetConnectionName: input.targetConnectionName,
+                sqlParams: input.sqlParams,
+                variables: input.variables,
+            });
+            const repair = {
+                version: 1,
+                status: 'repaired',
+                source: input.source,
+                mode: repaired.repairMode,
+                attemptedAt,
+                originalFailure,
+                ...(originalSqlFingerprint ? { originalSqlFingerprint } : {}),
+                repairedSqlFingerprint: `sha256:${createHash('sha256').update(repaired.repairedSql).digest('hex')}`,
+                approvalEligible: false,
+                message: `${repaired.repairMode === 'ai' ? 'AI' : 'Deterministic'} repair executed successfully on the same data target. The result remains review-required.`,
+            };
+            return { ok: true, result: repaired.result, repairedSql: repaired.repairedSql, repair };
+        }
+        catch (error) {
+            return failed(error instanceof Error
+                ? `The bounded repair could not complete: ${error.message}`
+                : 'The bounded repair could not complete.');
+        }
+    };
+    const generateInvestigationSqlForApp = async (input) => {
+        const request = buildAppCopilotResearchAgentRequest(input);
+        // AGT-007 / AGT-022: App Copilot keeps its server-owned App evidence
+        // adapter, while routing the actual investigation through the uniform
+        // snapshot, retrieval, trust, execution, and bounded-repair orchestration.
+        const governedAnswer = await runGovernedAgentAnswerForRun(request, undefined, 'research');
         return {
-            sql: memoOnly ? undefined : governedAnswer.proposedSql ?? governedAnswer.sql,
+            sql: input.mode === 'memo_only' ? undefined : governedAnswer.proposedSql ?? governedAnswer.sql,
             answer: governedAnswer.answer ?? governedAnswer.text,
             result: governedAnswer.result,
             analysisPlan: governedAnswer.analysisPlan,
@@ -4106,6 +4758,9 @@ export async function startLocalServer(opts) {
         let generatedSql = notebookResearchString(input.generatedSql) ?? run.generatedSql;
         let reviewedSql = notebookResearchString(input.reviewedSql) ?? run.reviewedSql;
         let dqlArtifact = normalizeDqlArtifactReference(input.dqlArtifact) ?? run.dqlArtifact;
+        const baselineSql = notebookResearchString(input.baselineSql);
+        const baselineDqlArtifact = normalizeDqlArtifactReference(input.baselineDqlArtifact);
+        let usedBaselineFallback = false;
         const startedAt = new Date().toISOString();
         storage.updateRun(run.id, {
             domain,
@@ -4156,7 +4811,7 @@ export async function startLocalServer(opts) {
                     generationWarnings.push('No AI provider is configured. Metadata context was saved as a research plan; paste SQL or configure an AI provider to generate candidate SQL.');
                 }
                 else {
-                    const controller = new AbortController();
+                    const researchSignal = input.signal ?? new AbortController().signal;
                     try {
                         await runner.run({
                             provider: resolvedProvider,
@@ -4178,18 +4833,19 @@ export async function startLocalServer(opts) {
                             reasoningEffort: resolveRunReasoningEffort(projectRoot, resolvedProvider, 'research', false),
                             analysisDepth: 'deep',
                             projectRoot,
-                            executeCertifiedBlock: executeCertifiedBlockForAgent,
-                            executeGeneratedSql: executeGeneratedSqlForAgent,
-                            getSchemaContext: getSchemaContextForAgent,
+                            executeCertifiedBlock: (node, invocation) => executeCertifiedBlockForAgent(node, invocation, input.executionConnection, input.executionConnectionName),
+                            executeGeneratedSql: (sql, artifact) => executeGeneratedArtifactForAgent(question, sql, artifact, input.executionConnection, input.executionConnectionName),
+                            getSchemaContext: (schemaQuestion, preparedContextPack) => getSchemaContextForAgent(schemaQuestion, preparedContextPack, input.executionConnection, input.executionConnectionName),
                         }, (turn) => {
                             if (turn.kind === 'tool_result' && turn.id === 'governed_answer') {
                                 governedAnswer = turn.output;
                             }
                             if (turn.kind === 'error')
                                 providerError = turn.message;
-                        }, controller.signal);
+                        }, researchSignal);
                     }
                     catch (error) {
+                        rethrowIfCancelled(error, input.signal);
                         providerError = error instanceof Error ? error.message : String(error);
                     }
                     if (!governedAnswer) {
@@ -4204,6 +4860,25 @@ export async function startLocalServer(opts) {
                     }
                 }
             }
+            const deeperCompositionFailed = !governedAnswer
+                || governedAnswer.kind === 'no_answer'
+                || agentAnswerHasExecutionFailure(governedAnswer)
+                || Boolean(governedAnswer.analyticalFailure)
+                || (!governedAnswer.result && !generatedSql && !dqlArtifact);
+            if (!reviewedSql && baselineSql && deeperCompositionFailed) {
+                const failure = governedAnswer?.executionError
+                    ?? governedAnswer?.analyticalFailure?.message
+                    ?? governedAnswer?.answer
+                    ?? governedAnswer?.text
+                    ?? providerError;
+                generatedSql = baselineSql;
+                dqlArtifact = baselineDqlArtifact ?? dqlArtifact;
+                usedBaselineFallback = true;
+                generationWarnings.push([
+                    'The deeper composition did not produce a safer executable query, so DQL kept and revalidated the successful Ask baseline on the same data target.',
+                    failure ? `Research detail: ${failure}` : '',
+                ].filter(Boolean).join(' '));
+            }
             const sqlForPreview = reviewedSql || generatedSql;
             const warnings = [
                 ...(contextPack.warnings ?? []),
@@ -4212,14 +4887,14 @@ export async function startLocalServer(opts) {
             ].filter(Boolean);
             let resultPreview;
             let previewError;
-            if (governedAnswer?.result?.rows && !reviewedSql) {
+            if (!usedBaselineFallback && governedAnswer?.result?.rows && !reviewedSql) {
                 resultPreview = normalizeNotebookAgentResult(governedAnswer.result);
             }
             else if (sqlForPreview) {
                 try {
                     const previewSql = buildAgentPreviewSql(sqlForPreview);
                     const previewStart = Date.now();
-                    resultPreview = await executeLocalSqlForStoredResult(previewSql);
+                    resultPreview = await executeLocalSqlForStoredResult(previewSql, input.executionConnection);
                     recordNotebookQueryRun(projectRoot, {
                         notebookPath: run.notebookPath,
                         cellId: run.sourceCellId,
@@ -4259,8 +4934,10 @@ export async function startLocalServer(opts) {
                 : undefined;
             const evidence = {
                 trustStatus: {
-                    label: governedAnswer?.trustLabel
-                        ?? (reviewedSql ? 'Reviewed notebook SQL' : generatedSql ? 'AI-generated research SQL' : dqlArtifact ? 'AI-generated DQL artifact' : 'Metadata-grounded research plan'),
+                    label: usedBaselineFallback
+                        ? 'Successful Ask baseline · revalidated on the same target'
+                        : governedAnswer?.trustLabel
+                            ?? (reviewedSql ? 'Reviewed notebook SQL' : generatedSql ? 'AI-generated research SQL' : dqlArtifact ? 'AI-generated DQL artifact' : 'Metadata-grounded research plan'),
                     reviewRequired: true,
                 },
                 contextPackId: contextPack.id,
@@ -4294,9 +4971,11 @@ export async function startLocalServer(opts) {
                     ...(governedAnswer?.citations ?? []),
                 ].slice(0, 40),
             };
-            const summary = notebookResearchString(governedAnswer?.answer)
-                ?? notebookResearchString(governedAnswer?.text)
-                ?? notebookResearchSummary(question, resultPreview, previewError);
+            const summary = usedBaselineFallback && resultPreview && !previewError
+                ? 'Research retained the successful Ask baseline and revalidated it on the same data target. No unverified replacement query was accepted; use the dossier to add the next breakdown or comparison.'
+                : notebookResearchString(governedAnswer?.answer)
+                    ?? notebookResearchString(governedAnswer?.text)
+                    ?? notebookResearchSummary(question, resultPreview, previewError);
             const recommendation = previewError
                 ? 'Review the SQL, selected metadata, and connection context before rerunning.'
                 : dqlArtifact && !reviewedSql
@@ -4334,6 +5013,9 @@ export async function startLocalServer(opts) {
                 contextPackId: contextPack.id,
                 routeDecision,
                 warnings: [
+                    ...(usedBaselineFallback && input.baselineRunId
+                        ? [`Baseline Ask run: ${input.baselineRunId}`]
+                        : []),
                     ...warnings,
                     ...(display && !display.ok ? [display.error] : []),
                     ...(display && display.ok ? display.warnings : []),
@@ -4344,6 +5026,7 @@ export async function startLocalServer(opts) {
             }) ?? run;
         }
         catch (error) {
+            rethrowIfCancelled(error, input.signal);
             return storage.updateRun(run.id, {
                 domain,
                 owner,
@@ -4570,16 +5253,19 @@ export async function startLocalServer(opts) {
     });
     // SSE clients for /api/watch hot-reload
     const sseClients = new Set();
+    const projectWatchers = [];
+    let runtimeClosing = false;
     // Watch all Git-owned authoring roots. Domain Packages are recursive and are
     // the canonical home for modeling, skills, blocks, notebooks, Apps, and evals.
     if (projectRoot) {
-        let sourceRefreshTimer;
         for (const dir of ['domains', 'skills', 'tests', 'notebooks', 'workbooks', 'blocks', 'apps', 'dashboards', 'semantic-layer', 'data']) {
             const watchDir = join(projectRoot, dir);
             if (!existsSync(watchDir))
                 continue;
             try {
-                watch(watchDir, { persistent: false, recursive: true }, (eventType, filename) => {
+                const watcher = watch(watchDir, { persistent: false, recursive: true }, (eventType, filename) => {
+                    if (runtimeClosing)
+                        return;
                     if (!filename)
                         return;
                     const path = `${dir}/${filename}`;
@@ -4594,11 +5280,7 @@ export async function startLocalServer(opts) {
                     }
                     if (['domains', 'skills', 'tests', 'blocks', 'apps', 'notebooks'].includes(dir)) {
                         invalidateAgentProjectState(projectRoot);
-                        if (sourceRefreshTimer)
-                            clearTimeout(sourceRefreshTimer);
-                        sourceRefreshTimer = setTimeout(() => {
-                            void refreshUnifiedProjectIndexes(projectRoot).catch(() => undefined);
-                        }, 250);
+                        scheduleProjectRefresh(`file:${path}`);
                     }
                     // Hot-reload semantic layer on change and notify frontend
                     if (dir === 'semantic-layer') {
@@ -4616,21 +5298,47 @@ export async function startLocalServer(opts) {
                         }).catch(() => { });
                     }
                 });
+                projectWatchers.push(watcher);
             }
             catch { /* dir not watchable */ }
         }
+        // A dbt repository commonly keeps its shared Skills folder beside the DQL
+        // project (`../skills`). It is Git-owned context too, so watch the resolved
+        // configured root even when it is not the default projectRoot/skills path.
+        const configuredSkillsRoot = skillsDir(projectRoot);
+        const defaultSkillsRoot = join(projectRoot, 'skills');
+        if (existsSync(configuredSkillsRoot) && resolve(configuredSkillsRoot) !== resolve(defaultSkillsRoot)) {
+            try {
+                const watcher = watch(configuredSkillsRoot, { persistent: false, recursive: true }, (eventType, filename) => {
+                    if (runtimeClosing || !filename)
+                        return;
+                    const path = relative(projectRoot, join(configuredSkillsRoot, String(filename))).replace(/\\/g, '/');
+                    invalidateAgentProjectState(projectRoot);
+                    scheduleProjectRefresh(`skills:${path}`);
+                    const payload = JSON.stringify({ type: eventType === 'rename' ? 'file-added' : 'file-changed', path });
+                    for (const client of sseClients) {
+                        try {
+                            client.write(`event: change\ndata: ${payload}\n\n`);
+                        }
+                        catch {
+                            sseClients.delete(client);
+                        }
+                    }
+                });
+                projectWatchers.push(watcher);
+            }
+            catch { /* configured Skills folder is not watchable */ }
+        }
         const configuredDbtManifest = resolveDbtManifestPath(projectRoot, projectConfig);
         if (configuredDbtManifest && existsSync(dirname(configuredDbtManifest))) {
             try {
-                watch(dirname(configuredDbtManifest), { persistent: false }, (_eventType, filename) => {
+                const watcher = watch(dirname(configuredDbtManifest), { persistent: false }, (_eventType, filename) => {
+                    if (runtimeClosing)
+                        return;
                     if (!filename || !['manifest.json', 'catalog.json', 'semantic_manifest.json', 'run_results.json'].includes(String(filename)))
                         return;
                     invalidateAgentProjectState(projectRoot);
-                    if (sourceRefreshTimer)
-                        clearTimeout(sourceRefreshTimer);
-                    sourceRefreshTimer = setTimeout(() => {
-                        void refreshUnifiedProjectIndexes(projectRoot).catch(() => undefined);
-                    }, 250);
+                    scheduleProjectRefresh(`dbt:${String(filename)}`);
                     const payload = JSON.stringify({ type: 'dbt-artifacts-changed', path: String(filename) });
                     for (const client of sseClients) {
                         try {
@@ -4652,6 +5360,7 @@ export async function startLocalServer(opts) {
                         }
                     }).catch(() => { });
                 });
+                projectWatchers.push(watcher);
             }
             catch { /* dbt artifact directory not watchable */ }
         }
@@ -4734,11 +5443,15 @@ export async function startLocalServer(opts) {
             result: normalizeQueryResult(result),
             chartConfig: plan?.chartConfig ?? validation.chartConfig ?? null,
             invocation,
+            tests: plan?.tests ?? [],
         };
     };
-    const runBlockStudioTestSummary = async (source, targetConnection) => {
-        const activeConnection = requireActiveConnection(targetConnection);
+    const runBlockStudioTestSummary = async (source, targetConnection, executedPreview) => {
         const start = Date.now();
+        if (executedPreview) {
+            return evaluateBlockStudioTests(executedPreview.tests, executedPreview.result.rows, executedPreview.result.columns, start);
+        }
+        const activeConnection = requireActiveConnection(targetConnection);
         const tableMapping = await resolveSemanticTableMapping(executor, activeConnection, semanticLayer, projectRoot);
         // 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
@@ -4783,40 +5496,7 @@ export async function startLocalServer(opts) {
         const columns = Array.isArray(rawResult?.columns)
             ? rawResult.columns.map((column) => typeof column === 'string' ? column : column?.name ?? String(column))
             : [];
-        const assertions = [];
-        let passed = 0;
-        let failed = 0;
-        for (const test of tests) {
-            const name = `assert ${test.field} ${test.operator} ${formatBlockStudioExpected(test.expected)}`;
-            let actual;
-            if (test.field === 'row_count') {
-                actual = rows.length;
-            }
-            else if (!columns.includes(test.field)) {
-                assertions.push({ name, passed: false, expected: test.expected, error: `Column '${test.field}' not found in results` });
-                failed += 1;
-                continue;
-            }
-            else {
-                actual = rows[0]?.[test.field];
-            }
-            const ok = compareBlockStudioValues(actual, test.operator, test.expected);
-            if (ok) {
-                assertions.push({ name, passed: true, actual, expected: test.expected });
-                passed += 1;
-            }
-            else {
-                assertions.push({
-                    name,
-                    passed: false,
-                    actual,
-                    expected: test.expected,
-                    error: `${String(actual)} ${test.operator} ${formatBlockStudioExpected(test.expected)} is false`,
-                });
-                failed += 1;
-            }
-        }
-        return { passed, failed, skipped: 0, duration: Date.now() - start, assertions, runAt: new Date() };
+        return evaluateBlockStudioTests(tests, rows, columns, start);
     };
     const saveDqlGenerationDraft = (importId, candidate) => saveDqlGenerationDraftForProject(projectRoot, importId, candidate);
     const createDqlGenerationSessionFromBody = async (body) => {
@@ -4875,7 +5555,9 @@ export async function startLocalServer(opts) {
             blockers.push(error instanceof Error ? error.message : String(error));
         }
         try {
-            testResults = await runBlockStudioTestSummary(source);
+            testResults = preview
+                ? await runBlockStudioTestSummary(source, undefined, preview)
+                : await runBlockStudioTestSummary(source);
         }
         catch (error) {
             testResults = {
@@ -5032,15 +5714,24 @@ export async function startLocalServer(opts) {
                 writeHead(status, { ...headers, ...validatorHeaders });
                 return end(raw);
             }
-            const gz = gzipSync(raw);
-            writeHead(status, {
-                ...headers,
-                ...validatorHeaders,
-                'Content-Encoding': 'gzip',
-                'Content-Length': gz.byteLength,
-                Vary: 'Accept-Encoding, Origin',
+            gzip(raw, (error, gz) => {
+                if (response.destroyed || response.writableEnded)
+                    return;
+                if (error) {
+                    writeHead(status, { ...headers, ...validatorHeaders });
+                    end(raw);
+                    return;
+                }
+                writeHead(status, {
+                    ...headers,
+                    ...validatorHeaders,
+                    'Content-Encoding': 'gzip',
+                    'Content-Length': gz.byteLength,
+                    Vary: 'Accept-Encoding, Origin',
+                });
+                end(gz);
             });
-            return end(gz);
+            return response;
         });
         return rawResponse;
     };
@@ -5059,7 +5750,7 @@ export async function startLocalServer(opts) {
                 res.setHeader('Access-Control-Allow-Origin', requestOrigin);
             res.setHeader('Vary', 'Origin');
             res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
-            res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+            res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, Idempotency-Key');
             if (!originAllowed && path.startsWith('/api/')) {
                 res.writeHead(403, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({ error: 'Origin is not allowed.' }));
@@ -5094,6 +5785,40 @@ export async function startLocalServer(opts) {
                 res.end(serializeJSON({ status: 'ok', version: runtimeVersion, versionStatus, retrievalHealth }));
                 return;
             }
+            if (req.method === 'GET' && path === '/api/operations/events') {
+                res.writeHead(200, {
+                    'Content-Type': 'text/event-stream',
+                    'Cache-Control': 'no-cache',
+                    'Connection': 'keep-alive',
+                    'X-Accel-Buffering': 'no',
+                });
+                res.write(': connected\n\n');
+                operationSseClients.add(res);
+                for (const operation of operationCoordinator.list(20).reverse()) {
+                    res.write(`event: operation\ndata: ${serializeJSON(operation)}\n\n`);
+                }
+                req.on('close', () => operationSseClients.delete(res));
+                return;
+            }
+            if (req.method === 'GET' && path === '/api/operations') {
+                const limit = Number(url.searchParams.get('limit') ?? 50);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ operations: operationCoordinator.list(limit) }));
+                return;
+            }
+            const operationMatch = path.match(/^\/api\/operations\/([^/]+)$/);
+            if (operationMatch && req.method === 'GET') {
+                const operation = operationCoordinator.get(decodeURIComponent(operationMatch[1]));
+                res.writeHead(operation ? 200 : 404, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(operation ?? { error: 'Operation not found.' }));
+                return;
+            }
+            if (operationMatch && req.method === 'DELETE') {
+                const operation = operationCoordinator.cancel(decodeURIComponent(operationMatch[1]));
+                res.writeHead(operation ? 200 : 404, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(operation ?? { error: 'Operation not found.' }));
+                return;
+            }
             if (req.method === 'GET' && path === '/api/onboarding/launch') {
                 const requestId = apiRequestId('onboarding-launch');
                 const prefs = readUserPrefs(userPrefsPath);
@@ -5856,6 +6581,224 @@ export async function startLocalServer(opts) {
                 }));
                 return;
             }
+            if (req.method === 'POST' && path === '/api/modeling/dbt-first/imports') {
+                const requestId = apiRequestId('modeling-import');
+                try {
+                    const body = await readJSON(req);
+                    const source = body.source && typeof body.source === 'object' ? body.source : body;
+                    const session = createModelingImportSession(projectRoot, gitRoot, loopback, source);
+                    res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ requestId, session: publicModelingImportSession(session) }));
+                }
+                catch (error) {
+                    const code = apiErrorCode(error, 'MODELING_IMPORT_INVALID');
+                    res.writeHead(code === 'PATH_ACCESS_FORBIDDEN' ? 403 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(apiErrorEnvelope({ requestId, code, message: apiErrorMessage(error), nextActions: ['Choose DQL or dbt YAML from the current Git workspace, or paste/upload the YAML.'] })));
+                }
+                return;
+            }
+            const modelingImportMatch = path.match(/^\/api\/modeling\/dbt-first\/imports\/([^/]+)$/);
+            if (req.method === 'GET' && modelingImportMatch) {
+                const session = readModelingImportSession(projectRoot, decodeURIComponent(modelingImportMatch[1]));
+                if (!session) {
+                    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Modeling import session not found.', code: 'MODELING_IMPORT_NOT_FOUND' }));
+                    return;
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ session: publicModelingImportSession(session) }));
+                return;
+            }
+            const modelingImportPreviewMatch = path.match(/^\/api\/modeling\/dbt-first\/imports\/([^/]+)\/preview$/);
+            if (req.method === 'POST' && modelingImportPreviewMatch) {
+                const requestId = apiRequestId('modeling-import-preview');
+                try {
+                    const session = readModelingImportSession(projectRoot, decodeURIComponent(modelingImportPreviewMatch[1]));
+                    if (!session)
+                        throw Object.assign(new Error('Modeling import session not found.'), { code: 'MODELING_IMPORT_NOT_FOUND' });
+                    const body = await readJSON(req);
+                    const snapshot = projectSnapshot();
+                    const selectedCandidateIds = Array.isArray(body.selectedCandidateIds)
+                        ? body.selectedCandidateIds.filter((value) => typeof value === 'string')
+                        : session.candidates.filter((candidate) => candidate.dialect !== 'unsupported' && candidate.action !== 'open_existing').map((candidate) => candidate.id);
+                    const domain = typeof body.domain === 'string' ? body.domain.trim() : '';
+                    const areaId = typeof body.areaId === 'string' ? body.areaId.trim() : '';
+                    if (!domain || !areaId)
+                        throw Object.assign(new Error('Choose exactly one Domain and Model Area for imported models.'), { code: 'MODEL_SCOPE_REQUIRED' });
+                    const planned = modelingImportOperations(session, selectedCandidateIds, domain, areaId, snapshot.manifest);
+                    const proposal = previewContextAuthoring({
+                        origin: 'yaml_import',
+                        operations: planned.operations,
+                        expectedSnapshotId: typeof body.expectedSnapshotId === 'string' ? body.expectedSnapshotId : snapshot.snapshotId,
+                        diagnostics: planned.diagnostics,
+                    });
+                    const updated = { ...session, proposalId: proposal.id, updatedAt: new Date().toISOString() };
+                    writeModelingImportSession(projectRoot, updated);
+                    res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ requestId, session: publicModelingImportSession(updated), proposal }));
+                }
+                catch (error) {
+                    const code = apiErrorCode(error, 'MODELING_IMPORT_PREVIEW_FAILED');
+                    res.writeHead(code === 'MODELING_IMPORT_NOT_FOUND' ? 404 : code === 'PROPOSAL_STALE' ? 409 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(apiErrorEnvelope({ requestId, code, message: apiErrorMessage(error), nextActions: ['Resolve unmatched models or choose another Domain and Area, then preview again.'] })));
+                }
+                return;
+            }
+            if (req.method === 'POST' && path === '/api/context-proposals') {
+                const requestId = apiRequestId('context-proposal');
+                try {
+                    const body = await readJSON(req);
+                    const origin = parseContextAuthoringOrigin(body.origin);
+                    const operations = parseContextAuthoringOperations(body.operations);
+                    const proposal = previewContextAuthoring({
+                        origin,
+                        operations,
+                        expectedSnapshotId: typeof body.expectedSnapshotId === 'string' ? body.expectedSnapshotId : undefined,
+                        sourceRunId: typeof body.sourceRunId === 'string' ? body.sourceRunId : undefined,
+                        sourceArtifactId: typeof body.sourceArtifactId === 'string' ? body.sourceArtifactId : undefined,
+                        revision: typeof body.revision === 'number' ? body.revision : undefined,
+                    });
+                    res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ requestId, proposal }));
+                }
+                catch (error) {
+                    const code = apiErrorCode(error, 'PROPOSAL_INVALID');
+                    res.writeHead(code === 'PROPOSAL_STALE' ? 409 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(apiErrorEnvelope({ requestId, code, message: apiErrorMessage(error), nextActions: ['Refresh Modeling and preview the proposal again.'] })));
+                }
+                return;
+            }
+            const contextProposalMatch = path.match(/^\/api\/context-proposals\/([^/]+)$/);
+            if (req.method === 'GET' && contextProposalMatch) {
+                const id = decodeURIComponent(contextProposalMatch[1]);
+                const proposal = contextProposalStore.get(id);
+                if (!proposal) {
+                    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Context proposal not found.', code: 'PROPOSAL_NOT_FOUND' }));
+                    return;
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ proposal }));
+                return;
+            }
+            const contextRepreviewMatch = path.match(/^\/api\/context-proposals\/([^/]+)\/repreview$/);
+            if (req.method === 'POST' && contextRepreviewMatch) {
+                const requestId = apiRequestId('context-repreview');
+                try {
+                    const current = contextProposalStore.get(decodeURIComponent(contextRepreviewMatch[1]));
+                    if (!current)
+                        throw Object.assign(new Error('Context proposal not found.'), { code: 'PROPOSAL_NOT_FOUND' });
+                    const body = await readJSON(req);
+                    const selected = Array.isArray(body.selectedOperationIds)
+                        ? body.selectedOperationIds.filter((value) => typeof value === 'string')
+                        : current.operations.map((operation) => operation.id);
+                    const operations = contextAuthoringDependencyClosure(current.operations, selected);
+                    const proposal = previewContextAuthoring({
+                        origin: current.origin,
+                        operations,
+                        expectedSnapshotId: body.rebase === true ? projectSnapshot().snapshotId : current.baseSnapshotId,
+                        sourceRunId: current.sourceRunId,
+                        sourceArtifactId: current.sourceArtifactId,
+                        revision: (current.revision ?? 1) + 1,
+                    });
+                    res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ requestId, proposal }));
+                }
+                catch (error) {
+                    const code = apiErrorCode(error, 'PROPOSAL_INVALID');
+                    res.writeHead(code === 'PROPOSAL_STALE' ? 409 : code === 'PROPOSAL_NOT_FOUND' ? 404 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(apiErrorEnvelope({ requestId, code, message: apiErrorMessage(error), nextActions: ['Refresh the proposal against the latest project snapshot.'] })));
+                }
+                return;
+            }
+            const contextCommitMatch = path.match(/^\/api\/context-proposals\/([^/]+)\/commit$/);
+            if (req.method === 'POST' && contextCommitMatch) {
+                const requestId = apiRequestId('context-commit');
+                const proposalId = decodeURIComponent(contextCommitMatch[1]);
+                try {
+                    const proposal = contextProposalStore.get(proposalId);
+                    if (!proposal)
+                        throw Object.assign(new Error('Context proposal not found.'), { code: 'PROPOSAL_NOT_FOUND' });
+                    const body = await readJSON(req);
+                    const unexpected = Object.keys(body).filter((key) => key !== 'expectedProposalHash' && key !== 'idempotencyKey');
+                    if (unexpected.length)
+                        throw Object.assign(new Error('Commit accepts only expectedProposalHash and idempotencyKey.'), { code: 'INVALID_REQUEST' });
+                    const expectedProposalHash = typeof body.expectedProposalHash === 'string' ? body.expectedProposalHash : '';
+                    const idempotencyKey = typeof body.idempotencyKey === 'string' ? body.idempotencyKey.trim() : '';
+                    if (!expectedProposalHash || !idempotencyKey)
+                        throw Object.assign(new Error('The reviewed proposal hash and idempotency key are required.'), { code: 'INVALID_REQUEST' });
+                    const receipt = contextProposalStore.getCommitReceipt(idempotencyKey);
+                    if (receipt) {
+                        if (receipt.proposalId !== proposal.id || receipt.proposalHash !== expectedProposalHash)
+                            throw Object.assign(new Error('The idempotency key belongs to another reviewed proposal request.'), { code: 'IDEMPOTENCY_CONFLICT' });
+                        res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ requestId, proposal: contextProposalStore.get(proposal.id), snapshotId: receipt.snapshotId, idempotent: true }));
+                        return;
+                    }
+                    if (proposal.status !== 'proposed')
+                        throw Object.assign(new Error('Only a proposed change can be committed.'), { code: 'PROPOSAL_STALE' });
+                    if (proposal.proposalHash !== expectedProposalHash)
+                        throw Object.assign(new Error('The proposal changed after review.'), { code: 'PROPOSAL_STALE' });
+                    if (proposal.diagnostics.some((diagnostic) => diagnostic.severity === 'blocking'))
+                        throw Object.assign(new Error('Resolve all blocking proposal diagnostics before saving.'), { code: 'PROPOSAL_BLOCKED' });
+                    const beforeSnapshot = projectSnapshot();
+                    if (beforeSnapshot.snapshotId !== proposal.baseSnapshotId)
+                        throw Object.assign(new Error('Project sources changed after this proposal was reviewed.'), { code: 'PROPOSAL_STALE' });
+                    const resolvedPatches = proposal.patches.map((patch) => ({ patch, absolute: resolveContextPatchPath(projectRoot, gitRoot, patch.path) }));
+                    for (const { patch, absolute } of resolvedPatches) {
+                        const current = existsSync(absolute) ? readFileSync(absolute, 'utf8') : '';
+                        if (current !== patch.before)
+                            throw Object.assign(new Error(`Source changed after preview: ${patch.path}`), { code: 'SOURCE_CHANGED' });
+                    }
+                    const written = [];
+                    try {
+                        for (const item of resolvedPatches) {
+                            if (!item.patch.changed)
+                                continue;
+                            if (!item.patch.after)
+                                rmSync(item.absolute, { force: true });
+                            else {
+                                mkdirSync(dirname(item.absolute), { recursive: true });
+                                writeFileSync(item.absolute, item.patch.after, 'utf8');
+                            }
+                            written.push(item);
+                        }
+                        projectSnapshots.invalidate();
+                        invalidateAgentProjectState(projectRoot);
+                        const nextSnapshot = projectSnapshot();
+                        if (nextSnapshot.error)
+                            throw Object.assign(new Error(nextSnapshot.error), { code: 'COMPILE_FAILED' });
+                        await refreshUnifiedProjectIndexes(projectRoot);
+                        const committed = { ...proposal, status: 'committed', committedAt: new Date().toISOString(), committedSnapshotId: nextSnapshot.snapshotId };
+                        contextProposalStore.save(committed);
+                        contextProposalStore.saveCommitReceipt(idempotencyKey, { proposalId: proposal.id, proposalHash: proposal.proposalHash, snapshotId: nextSnapshot.snapshotId });
+                        res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ requestId, proposal: committed, snapshotId: nextSnapshot.snapshotId, modeling: nextSnapshot.manifest.modeling }));
+                    }
+                    catch (error) {
+                        for (const { patch, absolute } of written.reverse()) {
+                            if (!patch.before)
+                                rmSync(absolute, { force: true });
+                            else {
+                                mkdirSync(dirname(absolute), { recursive: true });
+                                writeFileSync(absolute, patch.before, 'utf8');
+                            }
+                        }
+                        projectSnapshots.invalidate();
+                        invalidateAgentProjectState(projectRoot);
+                        contextProposalStore.save(proposal);
+                        contextProposalStore.deleteCommitReceipt(idempotencyKey);
+                        throw error;
+                    }
+                }
+                catch (error) {
+                    const code = apiErrorCode(error, /changed after/i.test(apiErrorMessage(error)) ? 'SOURCE_CHANGED' : 'PROPOSAL_COMMIT_FAILED');
+                    const status = code === 'PROPOSAL_NOT_FOUND' ? 404 : ['PROPOSAL_STALE', 'SOURCE_CHANGED', 'IDEMPOTENCY_CONFLICT', 'OWNERSHIP_CONFLICT', 'DEPENDENCY_CONFLICT'].includes(code) ? 409 : code === 'PROPOSAL_BLOCKED' ? 422 : 400;
+                    res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(apiErrorEnvelope({ requestId, code, message: apiErrorMessage(error), nextActions: ['Rebase or repreview the proposal before saving.'] })));
+                }
+                return;
+            }
             if (req.method === 'POST' && path === '/api/modeling/dbt-first/dbt-source/preview') {
                 const requestId = apiRequestId('modeling-dbt-source-preview');
                 const snapshot = projectSnapshot();
@@ -6018,13 +6961,14 @@ export async function startLocalServer(opts) {
                     return;
                 }
                 const sourceSql = repairableSqlFromAgentRun(sourceRun);
+                const sourceDqlArtifact = repairableDqlArtifactFromAgentRun(sourceRun);
                 const retainedFailure = warehouseFailureFromAgentRun(sourceRun);
-                if (!sourceSql || !analyticalFailureAllowsDeterministicRetry(retainedFailure)) {
+                if ((!sourceSql && !sourceDqlArtifact) || !analyticalFailureAllowsDeterministicRetry(retainedFailure)) {
                     res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({
-                        error: sourceSql
+                        error: sourceSql || sourceDqlArtifact
                             ? 'This failure requires authorized access or a policy change and cannot be repaired by AI.'
-                            : 'This run has no retained SQL statement to repair.',
+                            : 'This run has no retained SQL statement or editable DQL artifact to repair.',
                         ...(retainedFailure ? { warehouseFailure: retainedFailure } : {}),
                     }));
                     return;
@@ -6050,12 +6994,27 @@ export async function startLocalServer(opts) {
                         : projectConfig.defaultConnectionName;
                 let repaired;
                 try {
-                    repaired = await executeBoundedSqlRepair({
-                        question: sourceRun.question,
-                        sourceSql,
-                        targetConnection,
-                        targetConnectionName,
-                    });
+                    // Prefer the editable DQL contract even when the failed run also
+                    // retained compiled SQL. This keeps parameters, visualization, tests,
+                    // and the corrected wrapper attached to the repaired Ask result.
+                    repaired = sourceDqlArtifact
+                        ? await executeBoundedDqlRepair({
+                            question: sourceRun.question,
+                            source: sourceDqlArtifact.source,
+                            failure: retainedFailure?.redactedMessage
+                                ?? sourceRun.diagnosticReceipt?.failure?.message
+                                ?? sourceRun.summary,
+                            targetConnection,
+                            targetConnectionName,
+                            parameters: sourceDqlArtifact.parameterValues,
+                            artifactName: sourceDqlArtifact.name,
+                        })
+                        : await executeBoundedSqlRepair({
+                            question: sourceRun.question,
+                            sourceSql: sourceSql,
+                            targetConnection,
+                            targetConnectionName,
+                        });
                 }
                 catch (error) {
                     const repairError = error;
@@ -6078,6 +7037,8 @@ export async function startLocalServer(opts) {
                     ...(preview ? { columnFormats: agentColumnDisplayFormats(projectRoot, preview.columns) } : {}),
                 });
                 const sourceFailure = analyticalFailedRunFromAgentRun(sourceRun)?.failure;
+                const presentationContext = repairPresentationContextFromAgentRun(sourceRun);
+                const executionResultFingerprint = result.executionReceipt?.resultFingerprint;
                 const artifact = agentRunArtifact('answer', 'Repaired analytical answer', {
                     kind: 'uncertified',
                     certification: 'analyst_review_required',
@@ -6085,13 +7046,31 @@ export async function startLocalServer(opts) {
                     trustLabel: 'AI-generated · review required',
                     answer: synthesis.text,
                     text: synthesis.text,
+                    ...presentationContext,
                     result,
                     proposedSql: repairedSql,
                     sql: result.sql ?? repairedSql,
                     dqlArtifact: result.dqlArtifact,
+                    diagnosticReceipt: {
+                        version: 1,
+                        phase: 'run.completed',
+                        route: 'generated_answer',
+                        repair: {
+                            attempt: 1,
+                            mode: repairMode,
+                            sourceRunId: sourceRun.id,
+                            targetPreserved: true,
+                            readOnly: true,
+                        },
+                        execution: {
+                            rowCount: result.rowCount,
+                            ...(executionResultFingerprint ? { resultFingerprint: executionResultFingerprint } : {}),
+                        },
+                    },
                     previousAttempt: {
                         sourceRunId: sourceRun.id,
-                        sql: sourceSql,
+                        ...(sourceSql ? { sql: sourceSql } : {}),
+                        ...(sourceDqlArtifact?.source ? { dql: sourceDqlArtifact.source } : {}),
                         failure: retainedFailure ?? firstFailure,
                     },
                     repair: { attempt: 1, mode: repairMode },
@@ -6274,39 +7253,83 @@ export async function startLocalServer(opts) {
                     const wantsStream = url.searchParams.get('stream') === '1' || url.searchParams.get('stream') === 'true';
                     const runId = parsed.request.runId;
                     const runController = new AbortController();
-                    parsed.request.signal = AbortSignal.any([
-                        runController.signal,
-                        AbortSignal.timeout(agentRunDeadlineMs(parsed.request, process.env, getActiveProvider(projectRoot))),
-                    ]);
                     if (runId)
                         activeAgentRunControllers.set(runId, runController);
+                    let streamConnected = true;
+                    res.on('close', () => { streamConnected = false; });
+                    const writeStream = (event, data) => {
+                        if (!streamConnected || res.destroyed || res.writableEnded)
+                            return;
+                        try {
+                            writeAgentRunSse(res, event, data);
+                        }
+                        catch {
+                            streamConnected = false;
+                        }
+                    };
+                    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 operation = runId ? operationCoordinator.create({
+                        type: 'agent_run',
+                        scope: `agent-run:${runId}`,
+                        resourceRevision: parsed.request.threadId,
+                        message: 'AI request accepted. You can change pages while it runs.',
+                        cancellable: true,
+                    }) : null;
+                    if (wantsStream)
+                        writeStream('agent-run-accepted', { runId, operationId: operation?.id });
+                    let completedRun;
+                    let runError;
                     try {
+                        const executeRun = async (operationSignal, report) => {
+                            parsed.request.signal = AbortSignal.any([
+                                runController.signal,
+                                ...(operationSignal ? [operationSignal] : []),
+                                AbortSignal.timeout(agentRunDeadlineMs(parsed.request, process.env, getActiveProvider(projectRoot))),
+                            ]);
+                            report?.({ phase: 'reasoning', progress: 8, message: 'Grounding the request and selecting the governed route.' });
+                            try {
+                                const run = await agentRunEngine.run(parsed.request, (event) => {
+                                    if (wantsStream)
+                                        writeStream('agent-run-event', event);
+                                    report?.({ phase: event.type, progress: 45, message: event.message });
+                                }, (delta) => {
+                                    if (wantsStream)
+                                        writeStream('agent-run-answer-delta', { runId: parsed.request.runId, delta });
+                                });
+                                completedRun = run;
+                                recordConversationTurn(conversationStore, parsed.request.threadId, run);
+                                return { runId: run.id, threadId: parsed.request.threadId, status: run.status };
+                            }
+                            catch (error) {
+                                runError = error;
+                                throw error;
+                            }
+                        };
+                        if (operation)
+                            await operationCoordinator.run(operation.id, (signal, report) => executeRun(signal, report));
+                        else
+                            await executeRun();
+                        if (runError)
+                            throw runError;
+                        if (!completedRun)
+                            throw new Error('The AI request ended before producing a stored run.');
                         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);
-                            }, (delta) => {
-                                writeAgentRunSse(res, 'agent-run-answer-delta', { runId: parsed.request.runId, delta });
-                            });
-                            recordConversationTurn(conversationStore, parsed.request.threadId, run);
-                            // The terminal frame carried the whole stored run — 2.4 MB on a real
-                            // question, of which the renderable part was ~3 KB. The rest was the
-                            // same artifacts repeated four times over. The client renders from
-                            // the projection and fetches the full record from the run-state
-                            // route only if something needs it.
-                            writeAgentRunSse(res, 'agent-run-complete', slimAgentRunForTransport(run));
-                            res.end();
+                            // The complete stored run stays in the run-state route; the live
+                            // stream ships only the renderable transport projection.
+                            writeStream('agent-run-complete', slimAgentRunForTransport(completedRun));
+                            if (streamConnected && !res.writableEnded)
+                                res.end();
                             return;
                         }
-                        const run = await agentRunEngine.run(parsed.request);
-                        recordConversationTurn(conversationStore, parsed.request.threadId, run);
                         res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
-                        res.end(serializeJSON({ run }));
+                        res.end(serializeJSON({ run: completedRun }));
                     }
                     finally {
                         if (runId)
@@ -6316,8 +7339,10 @@ export async function startLocalServer(opts) {
                 catch (error) {
                     const message = error instanceof Error ? error.message : String(error);
                     if (res.headersSent) {
-                        writeAgentRunSse(res, 'agent-run-error', { error: message });
-                        res.end();
+                        if (!res.destroyed && !res.writableEnded) {
+                            writeAgentRunSse(res, 'agent-run-error', { error: message });
+                            res.end();
+                        }
                     }
                     else {
                         res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -6808,14 +7833,22 @@ export async function startLocalServer(opts) {
                     const metrics = semanticLayer
                         ? semanticLayer.listMetrics(undefined, { includeMeasures: false }).map((m) => m.name).filter(matches).sort().slice(0, limit)
                         : [];
-                    const manifest = buildManifest({ projectRoot, dqlVersion: 'notebook' });
+                    const manifest = buildManifest({
+                        projectRoot,
+                        dqlVersion: 'notebook',
+                        dbtManifestPath: resolveDbtManifestPath(projectRoot) ?? undefined,
+                    });
                     const blocks = Object.values(manifest.blocks)
                         .filter((b) => b.status === 'certified')
                         .map((b) => b.name)
                         .filter(matches)
                         .sort();
+                    const modelingRefs = [
+                        ...Object.values(manifest.modeling?.entities ?? {}).map((entity) => entity.qualifiedId),
+                        ...Object.values(manifest.modeling?.relationships ?? {}).map((relationship) => relationship.qualifiedId),
+                    ].filter(matches).sort();
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
-                    res.end(serializeJSON({ metrics, blocks: blocks.slice(0, limit) }));
+                    res.end(serializeJSON({ metrics, blocks: blocks.slice(0, limit), modelingRefs: modelingRefs.slice(0, limit) }));
                 }
                 catch (error) {
                     res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -6833,6 +7866,9 @@ export async function startLocalServer(opts) {
                         return;
                     }
                     const skill = writeSkill(projectRoot, input);
+                    projectSnapshots.invalidate();
+                    invalidateAgentProjectState(projectRoot);
+                    await refreshUnifiedProjectIndexes(projectRoot);
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ skill: serializeSkill(skill) }));
                 }
@@ -6852,7 +7888,10 @@ export async function startLocalServer(opts) {
                         res.end(serializeJSON({ error: 'Provide { skill } with scope and body.' }));
                         return;
                     }
-                    const skill = writeSkill(projectRoot, input);
+                    const skill = writeSkill(projectRoot, { ...input, qualifiedId: id });
+                    projectSnapshots.invalidate();
+                    invalidateAgentProjectState(projectRoot);
+                    await refreshUnifiedProjectIndexes(projectRoot);
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ skill: serializeSkill(skill) }));
                 }
@@ -6866,6 +7905,9 @@ export async function startLocalServer(opts) {
                 try {
                     const id = decodeURIComponent(path.slice('/api/skills/'.length));
                     deleteSkill(projectRoot, id);
+                    projectSnapshots.invalidate();
+                    invalidateAgentProjectState(projectRoot);
+                    await refreshUnifiedProjectIndexes(projectRoot);
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ ok: true }));
                 }
@@ -7989,9 +9031,14 @@ export async function startLocalServer(opts) {
                         ? body.variables
                         : {};
                     const dashboardVariables = dashboardRuntimeVariables(loaded.dashboard, variables);
+                    const requestedTileId = typeof body.tileId === 'string' && body.tileId.trim()
+                        ? body.tileId.trim()
+                        : undefined;
                     const tiles = [];
                     let localApps = null;
                     for (const item of loaded.dashboard.layout.items) {
+                        if (requestedTileId && item.i !== requestedTileId)
+                            continue;
                         if (item.text) {
                             tiles.push({
                                 tileId: item.i,
@@ -8079,9 +9126,194 @@ export async function startLocalServer(opts) {
                                     kind: 'ai_pin',
                                     name: pin.title,
                                 },
+                                artifact: {
+                                    version: 1,
+                                    sourceKind: 'ai_pin',
+                                    name: pinArtifact?.name ?? pin.title,
+                                    ...(pinArtifact?.sourcePath ? { sourcePath: pinArtifact.sourcePath } : {}),
+                                    ...(pinArtifact?.source ? { dql: pinArtifact.source.slice(0, 40_000) } : {}),
+                                    ...(pinArtifact?.compiledSql || pin.sql ? { sql: (pinArtifact?.compiledSql ?? pin.sql).slice(0, 40_000) } : {}),
+                                    trustState: pinArtifact?.trustState === 'certified' || pin.certification === 'certified'
+                                        ? 'certified'
+                                        : 'review_required',
+                                    explanation: [
+                                        'This result comes from a saved App insight.',
+                                        pinArtifact ? 'The DQL artifact was executed again with the current App parameters.' : 'The saved bounded result is displayed with its original trust state.',
+                                    ],
+                                    executionTarget: executionTargetDescriptor(body),
+                                },
                             });
                             continue;
                         }
+                        if (item.draftAnalysis) {
+                            let draftSource;
+                            let draftAppRelativePath;
+                            let draftParameters = {};
+                            let draftTargetConnection;
+                            let draftRepairPlan;
+                            try {
+                                const draftPath = join(loaded.appDir, item.draftAnalysis.ref);
+                                draftAppRelativePath = relative(loaded.appDir, draftPath);
+                                if (draftAppRelativePath.startsWith('..') || draftAppRelativePath.startsWith('/')) {
+                                    throw new Error('App-scoped analysis reference escapes the App directory.');
+                                }
+                                draftSource = readFileSync(draftPath, 'utf-8');
+                                const fingerprint = `sha256:${createHash('sha256').update(draftSource).digest('hex')}`;
+                                if (fingerprint !== item.draftAnalysis.artifactFingerprint) {
+                                    throw new Error('App-scoped analysis changed after approval. Review the draft again.');
+                                }
+                                draftParameters = dashboardTileParameterValues({
+                                    item,
+                                    dashboardValues: dashboardVariables,
+                                    requestValues: variables,
+                                });
+                                draftTargetConnection = isConnectionConfig(body.connection)
+                                    ? body.connection
+                                    : connection ?? undefined;
+                                draftRepairPlan = buildExecutionPlan({ id: item.i, type: 'dql', source: draftSource, title: item.title ?? item.i }, {
+                                    semanticLayer,
+                                    driver: draftTargetConnection?.driver ?? 'duckdb',
+                                    parameters: draftParameters,
+                                });
+                                let result;
+                                let repair;
+                                let repairedSql;
+                                let repairedDql;
+                                try {
+                                    result = await executeDqlArtifactSourceForAgent(draftSource, { name: item.title ?? item.i, path: draftAppRelativePath }, { question: item.title, parameters: draftParameters });
+                                }
+                                catch (executionError) {
+                                    const repaired = await repairFailedAppTileExecution({
+                                        source: 'draft_analysis',
+                                        question: item.title ?? item.i,
+                                        sourceSql: draftRepairPlan?.sql,
+                                        sourceDql: draftSource,
+                                        artifactName: item.title ?? item.i,
+                                        error: executionError,
+                                        targetConnection: draftTargetConnection,
+                                        targetConnectionName: projectConfig.defaultConnectionName,
+                                        sqlParams: draftRepairPlan?.sqlParams,
+                                        variables: { ...(draftRepairPlan?.variables ?? {}), ...draftParameters },
+                                    });
+                                    if (!repaired.ok) {
+                                        tiles.push({
+                                            tileId: item.i,
+                                            status: 'error',
+                                            tileType: 'draftAnalysis',
+                                            title: item.title ?? item.i,
+                                            error: executionError instanceof Error ? executionError.message : String(executionError),
+                                            trustState: 'review_required',
+                                            repair: repaired.repair,
+                                            artifact: {
+                                                version: 1,
+                                                sourceKind: 'draft_analysis',
+                                                name: item.title ?? item.i,
+                                                sourcePath: draftAppRelativePath,
+                                                dql: draftSource.slice(0, 40_000),
+                                                ...(draftRepairPlan?.sql ? { sql: draftRepairPlan.sql.slice(0, 40_000) } : {}),
+                                                trustState: 'review_required',
+                                                explanation: ['This App-scoped analysis remains review-required.', 'Automatic repair could not produce a safe executable result.'],
+                                                executionTarget: executionTargetDescriptor(body),
+                                            },
+                                        });
+                                        continue;
+                                    }
+                                    result = repaired.result;
+                                    repair = repaired.repair;
+                                    repairedSql = repaired.repairedSql;
+                                    repairedDql = repaired.repairedDql;
+                                }
+                                tiles.push({
+                                    tileId: item.i,
+                                    status: 'ok',
+                                    tileType: 'draftAnalysis',
+                                    title: item.title ?? item.i,
+                                    viz: item.viz,
+                                    chartConfig: mergeDashboardChartConfig(result.chartConfig, item),
+                                    result,
+                                    trustState: 'review_required',
+                                    citation: { kind: repair ? 'app_draft_analysis_repaired' : 'app_draft_analysis', name: item.title ?? item.i, path: draftAppRelativePath },
+                                    ...(repair ? { repair } : {}),
+                                    artifact: {
+                                        version: 1,
+                                        sourceKind: 'draft_analysis',
+                                        name: item.title ?? item.i,
+                                        sourcePath: draftAppRelativePath,
+                                        dql: (repairedDql ?? draftSource).slice(0, 40_000),
+                                        ...(repairedSql ?? draftRepairPlan?.sql ? { sql: (repairedSql ?? draftRepairPlan.sql).slice(0, 40_000) } : {}),
+                                        trustState: 'review_required',
+                                        explanation: [
+                                            'This is private App analysis and remains review-required.',
+                                            repair ? 'A bounded repair ran on the original data target without changing the saved source file.' : 'The saved App-scoped DQL was executed with the current filters.',
+                                        ],
+                                        executionTarget: executionTargetDescriptor(body),
+                                    },
+                                });
+                            }
+                            catch (err) {
+                                const repaired = await repairFailedAppTileExecution({
+                                    source: 'draft_analysis',
+                                    question: item.title ?? item.i,
+                                    sourceSql: draftRepairPlan?.sql,
+                                    sourceDql: draftSource,
+                                    artifactName: item.title ?? item.i,
+                                    error: err,
+                                    targetConnection: draftTargetConnection,
+                                    targetConnectionName: projectConfig.defaultConnectionName,
+                                    sqlParams: draftRepairPlan?.sqlParams,
+                                    variables: { ...(draftRepairPlan?.variables ?? {}), ...draftParameters },
+                                });
+                                if (repaired.ok && draftSource) {
+                                    tiles.push({
+                                        tileId: item.i,
+                                        status: 'ok',
+                                        tileType: 'draftAnalysis',
+                                        title: item.title ?? item.i,
+                                        viz: item.viz,
+                                        chartConfig: mergeDashboardChartConfig(repaired.result.chartConfig, item),
+                                        result: repaired.result,
+                                        trustState: 'review_required',
+                                        citation: { kind: 'app_draft_analysis_repaired', name: item.title ?? item.i, path: draftAppRelativePath },
+                                        repair: repaired.repair,
+                                        artifact: {
+                                            version: 1,
+                                            sourceKind: 'draft_analysis',
+                                            name: item.title ?? item.i,
+                                            ...(draftAppRelativePath ? { sourcePath: draftAppRelativePath } : {}),
+                                            dql: (repaired.repairedDql ?? draftSource).slice(0, 40_000),
+                                            sql: repaired.repairedSql.slice(0, 40_000),
+                                            trustState: 'review_required',
+                                            explanation: ['A bounded DQL repair executed on the original data target. The saved App analysis was not changed.'],
+                                            executionTarget: executionTargetDescriptor(body),
+                                        },
+                                    });
+                                    continue;
+                                }
+                                tiles.push({
+                                    tileId: item.i,
+                                    status: 'error',
+                                    tileType: 'draftAnalysis',
+                                    title: item.title ?? item.i,
+                                    error: err instanceof Error ? err.message : String(err),
+                                    trustState: 'review_required',
+                                    repair: repaired.repair,
+                                    ...(draftSource ? {
+                                        artifact: {
+                                            version: 1,
+                                            sourceKind: 'draft_analysis',
+                                            name: item.title ?? item.i,
+                                            ...(draftAppRelativePath ? { sourcePath: draftAppRelativePath } : {}),
+                                            dql: draftSource.slice(0, 40_000),
+                                            ...(draftRepairPlan?.sql ? { sql: draftRepairPlan.sql.slice(0, 40_000) } : {}),
+                                            trustState: 'review_required',
+                                            explanation: ['Automatic repair could not produce a safe executable result. The saved App analysis was not changed.'],
+                                            executionTarget: executionTargetDescriptor(body),
+                                        },
+                                    } : {}),
+                                });
+                            }
+                            continue;
+                        }
                         if (item.semantic) {
                             try {
                                 if (!semanticLayer)
@@ -8122,16 +9354,69 @@ export async function startLocalServer(opts) {
                                 if (!composed)
                                     throw new Error('The governed semantic query could not be composed.');
                                 const prepared = prepareLocalExecution(composed.sql, targetConnection, projectRoot, projectConfig);
-                                const result = await executor.executeQuery(prepared.sql, [], {}, prepared.connection);
+                                let normalizedResult;
+                                let repair;
+                                let executedSql = composed.sql;
+                                try {
+                                    const result = await executor.executeQuery(prepared.sql, [], {}, prepared.connection);
+                                    normalizedResult = normalizeQueryResult(result);
+                                }
+                                catch (executionError) {
+                                    const repaired = await repairFailedAppTileExecution({
+                                        source: 'semantic_query',
+                                        question: item.title ?? item.semantic.id,
+                                        sourceSql: composed.sql,
+                                        error: executionError,
+                                        targetConnection,
+                                    });
+                                    if (!repaired.ok) {
+                                        tiles.push({
+                                            tileId: item.i,
+                                            status: 'error',
+                                            tileType: 'semantic',
+                                            title: item.title ?? item.semantic.id,
+                                            error: executionError instanceof Error ? executionError.message : String(executionError),
+                                            trustState: 'review_required',
+                                            repair: repaired.repair,
+                                            artifact: {
+                                                version: 1,
+                                                sourceKind: 'semantic_query',
+                                                name: item.title ?? item.semantic.id,
+                                                sql: composed.sql.slice(0, 40_000),
+                                                trustState: 'review_required',
+                                                explanation: ['Automatic repair could not execute the governed semantic query safely.'],
+                                                executionTarget: executionTargetDescriptor(body),
+                                            },
+                                        });
+                                        continue;
+                                    }
+                                    normalizedResult = normalizeQueryResult(repaired.result);
+                                    repair = repaired.repair;
+                                    executedSql = repaired.repairedSql;
+                                }
                                 tiles.push({
                                     tileId: item.i,
                                     status: 'ok',
                                     tileType: 'semantic',
                                     title: item.title ?? item.semantic.id,
                                     viz: item.viz,
-                                    result: normalizeQueryResult(result),
+                                    result: normalizedResult,
                                     trustState: 'review_required',
-                                    citation: { kind: 'semantic_query', name: item.semantic.id },
+                                    citation: { kind: repair ? 'semantic_query_repaired' : 'semantic_query', name: item.semantic.id },
+                                    ...(repair ? { repair } : {}),
+                                    artifact: {
+                                        version: 1,
+                                        sourceKind: 'semantic_query',
+                                        name: item.title ?? item.semantic.id,
+                                        sql: executedSql.slice(0, 40_000),
+                                        trustState: 'review_required',
+                                        explanation: [
+                                            `Metrics: ${item.semantic.metrics.join(', ') || 'none'}.`,
+                                            `Dimensions: ${item.semantic.dimensions?.join(', ') || 'none'}.`,
+                                            repair ? 'The composed SQL needed bounded repair and therefore remains review-required.' : 'The governed semantic intent was composed for the active warehouse and remains review-required until approval.',
+                                        ],
+                                        executionTarget: executionTargetDescriptor(body),
+                                    },
                                 });
                             }
                             catch (err) {
@@ -8156,6 +9441,11 @@ export async function startLocalServer(opts) {
                             });
                             continue;
                         }
+                        let blockSource;
+                        let blockTargetConnection;
+                        let blockPlan;
+                        let blockFilterApplication;
+                        let blockInvocation;
                         try {
                             assertAppAccess({
                                 app: loaded.app,
@@ -8163,55 +9453,55 @@ export async function startLocalServer(opts) {
                                 level: 'execute',
                             });
                             const absBlockPath = join(projectRoot, block.filePath);
-                            const source = readFileSync(absBlockPath, 'utf-8');
-                            const targetConnection = isConnectionConfig(body.connection) ? body.connection : connection;
-                            const tableMapping = await resolveSemanticTableMapping(executor, targetConnection, semanticLayer, projectRoot);
+                            blockSource = readFileSync(absBlockPath, 'utf-8');
+                            blockTargetConnection = requireActiveConnection(isConnectionConfig(body.connection) ? body.connection : connection);
+                            const tableMapping = await resolveSemanticTableMapping(executor, blockTargetConnection, semanticLayer, projectRoot);
                             const boundParameters = dashboardTileParameterValues({
                                 item,
                                 dashboardValues: dashboardVariables,
                                 requestValues: variables,
                             });
-                            const invocation = prepareBlockInvocation({
+                            blockInvocation = prepareBlockInvocation({
                                 block: block.name,
-                                source,
+                                source: blockSource,
                                 parameters: { ...dashboardVariables, ...boundParameters },
                                 parameterSources: Object.fromEntries(Object.keys(boundParameters).map((name) => [name, 'surface'])),
                                 surface: 'app',
                             });
-                            if (invocation.errors.length || invocation.unresolvedParameters.length) {
+                            if (blockInvocation.errors.length || blockInvocation.unresolvedParameters.length) {
                                 tiles.push({
                                     tileId: item.i,
                                     status: 'unresolved',
                                     tileType: 'block',
                                     blockId: block.name,
                                     title: item.title ?? block.name,
-                                    error: invocation.errors[0] ?? `Needs values for: ${invocation.unresolvedParameters.join(', ')}`,
+                                    error: blockInvocation.errors[0] ?? `Needs values for: ${blockInvocation.unresolvedParameters.join(', ')}`,
                                     invocation: {
-                                        resolvedParameters: invocation.resolvedParameters,
-                                        unresolvedParameters: invocation.unresolvedParameters,
-                                        auditId: invocation.auditId,
+                                        resolvedParameters: blockInvocation.resolvedParameters,
+                                        unresolvedParameters: blockInvocation.unresolvedParameters,
+                                        auditId: blockInvocation.auditId,
                                     },
                                 });
                                 continue;
                             }
                             const semanticCompose = semanticLayer
-                                ? await composeSemanticBlockSqlForRuntime(source, semanticLayer, {
-                                    driver: targetConnection.driver,
+                                ? await composeSemanticBlockSqlForRuntime(blockSource, semanticLayer, {
+                                    driver: blockTargetConnection.driver,
                                     tableMapping,
                                     projectRoot,
                                     projectConfig,
                                     detectedProvider: semanticDetectedProvider,
-                                    parameters: invocation.values,
+                                    parameters: blockInvocation.values,
                                 })
                                 : null;
-                            const plan = buildExecutionPlan({ id: item.i, type: 'dql', source, title: item.title ?? block.name }, {
+                            blockPlan = buildExecutionPlan({ id: item.i, type: 'dql', source: blockSource, title: item.title ?? block.name }, {
                                 semanticLayer,
-                                driver: targetConnection.driver,
+                                driver: blockTargetConnection.driver,
                                 tableMapping,
-                                parameters: invocation.values,
+                                parameters: blockInvocation.values,
                                 semanticSql: semanticCompose?.sql ?? undefined,
                             });
-                            if (!plan && !semanticCompose?.sql) {
+                            if (!blockPlan && !semanticCompose?.sql) {
                                 tiles.push({
                                     tileId: item.i,
                                     status: 'error',
@@ -8220,15 +9510,15 @@ export async function startLocalServer(opts) {
                                 });
                                 continue;
                             }
-                            const filterApplication = applyDashboardFiltersToBlockExecution({
-                                sql: semanticCompose?.sql ?? plan.sql,
-                                sqlParams: plan?.sqlParams ?? [],
-                                variables: { ...(plan?.variables ?? {}), ...dashboardVariables },
+                            blockFilterApplication = applyDashboardFiltersToBlockExecution({
+                                sql: semanticCompose?.sql ?? blockPlan.sql,
+                                sqlParams: blockPlan?.sqlParams ?? [],
+                                variables: { ...(blockPlan?.variables ?? {}), ...dashboardVariables },
                                 block,
                                 dashboard: loaded.dashboard,
                             });
-                            const prepared = prepareLocalExecution(filterApplication.sql, targetConnection, projectRoot, projectConfig);
-                            const result = await executor.executeQuery(prepared.sql, filterApplication.sqlParams, runtimeVariables({ ...filterApplication.variables, ...invocation.values }), prepared.connection);
+                            const prepared = prepareLocalExecution(blockFilterApplication.sql, blockTargetConnection, projectRoot, projectConfig);
+                            const result = await executor.executeQuery(prepared.sql, blockFilterApplication.sqlParams, runtimeVariables({ ...blockFilterApplication.variables, ...blockInvocation.values }), prepared.connection);
                             tiles.push({
                                 tileId: item.i,
                                 status: 'ok',
@@ -8237,22 +9527,37 @@ export async function startLocalServer(opts) {
                                 certificationStatus: block.status ?? null,
                                 title: item.title ?? block.name,
                                 viz: item.viz,
-                                chartConfig: mergeDashboardChartConfig(plan?.chartConfig, item),
+                                chartConfig: mergeDashboardChartConfig(blockPlan?.chartConfig, item),
                                 result: normalizeQueryResult(result),
                                 filters: {
-                                    applied: filterApplication.appliedFilters,
-                                    skipped: filterApplication.skippedFilters,
+                                    applied: blockFilterApplication.appliedFilters,
+                                    skipped: blockFilterApplication.skippedFilters,
                                 },
                                 invocation: {
-                                    resolvedParameters: invocation.resolvedParameters,
-                                    unresolvedParameters: invocation.unresolvedParameters,
-                                    auditId: invocation.auditId,
+                                    resolvedParameters: blockInvocation.resolvedParameters,
+                                    unresolvedParameters: blockInvocation.unresolvedParameters,
+                                    auditId: blockInvocation.auditId,
                                 },
+                                trustState: block.status === 'certified' ? 'certified' : 'review_required',
                                 citation: {
                                     kind: 'block',
                                     name: block.name,
                                     path: block.filePath,
                                 },
+                                artifact: {
+                                    version: 1,
+                                    sourceKind: 'certified_block',
+                                    name: block.name,
+                                    sourcePath: block.filePath,
+                                    dql: blockSource.slice(0, 40_000),
+                                    sql: blockFilterApplication.sql.slice(0, 40_000),
+                                    trustState: block.status === 'certified' ? 'certified' : 'review_required',
+                                    explanation: [
+                                        block.status === 'certified' ? 'This tile executed a certified project block.' : 'This project block is not certified and remains review-required.',
+                                        'Dashboard filters and typed parameters were bound before read-only execution.',
+                                    ],
+                                    executionTarget: executionTargetDescriptor(body),
+                                },
                             });
                         }
                         catch (err) {
@@ -8265,11 +9570,87 @@ export async function startLocalServer(opts) {
                                 });
                             }
                             else {
+                                const repaired = await repairFailedAppTileExecution({
+                                    source: 'certified_block',
+                                    question: item.title ?? block.name,
+                                    sourceSql: blockFilterApplication?.sql ?? blockPlan?.sql,
+                                    sourceDql: blockSource,
+                                    artifactName: block.name,
+                                    error: err,
+                                    targetConnection: blockTargetConnection,
+                                    targetConnectionName: projectConfig.defaultConnectionName,
+                                    sqlParams: blockFilterApplication?.sqlParams ?? blockPlan?.sqlParams,
+                                    variables: {
+                                        ...(blockPlan?.variables ?? {}),
+                                        ...(blockFilterApplication?.variables ?? {}),
+                                        ...(blockInvocation?.values ?? {}),
+                                    },
+                                });
+                                if (repaired.ok) {
+                                    tiles.push({
+                                        tileId: item.i,
+                                        status: 'ok',
+                                        tileType: 'block',
+                                        blockId: block.name,
+                                        blockPath: block.filePath,
+                                        certificationStatus: block.status ?? null,
+                                        title: item.title ?? block.name,
+                                        viz: item.viz,
+                                        chartConfig: mergeDashboardChartConfig(blockPlan?.chartConfig, item),
+                                        result: normalizeQueryResult(repaired.result),
+                                        ...(blockFilterApplication ? {
+                                            filters: {
+                                                applied: blockFilterApplication.appliedFilters,
+                                                skipped: blockFilterApplication.skippedFilters,
+                                            },
+                                        } : {}),
+                                        ...(blockInvocation ? {
+                                            invocation: {
+                                                resolvedParameters: blockInvocation.resolvedParameters,
+                                                unresolvedParameters: blockInvocation.unresolvedParameters,
+                                                auditId: blockInvocation.auditId,
+                                            },
+                                        } : {}),
+                                        trustState: 'review_required',
+                                        repair: repaired.repair,
+                                        citation: { kind: 'block_repaired', name: block.name, path: block.filePath },
+                                        artifact: {
+                                            version: 1,
+                                            sourceKind: 'certified_block',
+                                            name: block.name,
+                                            sourcePath: block.filePath,
+                                            ...(repaired.repairedDql ?? blockSource ? { dql: (repaired.repairedDql ?? blockSource).slice(0, 40_000) } : {}),
+                                            sql: repaired.repairedSql.slice(0, 40_000),
+                                            trustState: 'review_required',
+                                            explanation: [
+                                                'The saved certified block was not changed.',
+                                                'A bounded repair executed on the original data target; this repaired result requires human review.',
+                                            ],
+                                            executionTarget: executionTargetDescriptor(body),
+                                        },
+                                    });
+                                    continue;
+                                }
                                 tiles.push({
                                     tileId: item.i,
                                     status: 'error',
+                                    tileType: 'block',
                                     blockId: block.name,
                                     error: err instanceof Error ? err.message : String(err),
+                                    repair: repaired.repair,
+                                    ...(blockSource ? {
+                                        artifact: {
+                                            version: 1,
+                                            sourceKind: 'certified_block',
+                                            name: block.name,
+                                            sourcePath: block.filePath,
+                                            dql: blockSource.slice(0, 40_000),
+                                            ...(blockFilterApplication?.sql ?? blockPlan?.sql ? { sql: (blockFilterApplication?.sql ?? blockPlan.sql).slice(0, 40_000) } : {}),
+                                            trustState: 'review_required',
+                                            explanation: ['Automatic repair could not produce a safe executable result. The saved block was not changed.'],
+                                            executionTarget: executionTargetDescriptor(body),
+                                        },
+                                    } : {}),
                                 });
                             }
                         }
@@ -8304,6 +9685,10 @@ export async function startLocalServer(opts) {
                         filterFingerprint,
                         resultFingerprint,
                         personaFingerprint,
+                        successfulTileIds: tiles.filter((tile) => tile.status === 'ok').map((tile) => tile.tileId),
+                        semanticApprovalEligibleTileIds: tiles.filter((tile) => (tile.status === 'ok'
+                            && tile.tileType === 'semantic'
+                            && (!('repair' in tile) || tile.repair?.approvalEligible !== false))).map((tile) => tile.tileId),
                         facts: storyResult.facts,
                         story: storyResult.story,
                         expiresAt: Date.now() + 15 * 60_000,
@@ -8355,7 +9740,30 @@ export async function startLocalServer(opts) {
                         // Two-phase app build gap-fill: bounded governed answers for uncovered
                         // questions. Throws when no provider is configured — propose degrades
                         // gracefully by listing the gap instead.
-                        generateGovernedAnswer: (question) => runGovernedAgentAnswerForRun({ question }),
+                        generateGovernedAnswer: (question, appContext) => generateAppBuildAnswerWithRepair(question, appContext),
+                        queueOperation: (input, task) => {
+                            const operation = operationCoordinator.create(input);
+                            void operationCoordinator.run(operation.id, task);
+                            return operation;
+                        },
+                        scheduleProjectRefresh: (reason) => { scheduleProjectRefresh(reason); },
+                        verifyDashboardRun: ({ runId, appId, dashboardId, tileIds }) => {
+                            const evidence = dashboardRunEvidence.get(runId);
+                            if (!evidence || evidence.expiresAt < Date.now())
+                                return { ok: false, error: 'The dashboard run receipt expired. Run the dashboard again.' };
+                            if (evidence.appId !== appId || evidence.dashboardId !== dashboardId)
+                                return { ok: false, error: 'The dashboard run receipt does not match this App page.' };
+                            const successful = new Set(evidence.successfulTileIds);
+                            const failed = tileIds.filter((tileId) => !successful.has(tileId));
+                            if (failed.length > 0)
+                                return { ok: false, error: `These semantic tiles did not complete successfully: ${failed.join(', ')}` };
+                            const approvalEligible = new Set(evidence.semanticApprovalEligibleTileIds);
+                            const repaired = tileIds.filter((tileId) => !approvalEligible.has(tileId));
+                            if (repaired.length > 0) {
+                                return { ok: false, error: `These semantic previews required SQL repair and cannot be approved as governed semantic results: ${repaired.join(', ')}. Review them as exploratory App analysis instead.` };
+                            }
+                            return { ok: true, snapshotId: evidence.snapshotId, resultFingerprint: evidence.resultFingerprint };
+                        },
                         // Story narration for commit — LLM-backed with deterministic fallback.
                         narrate: narrateForAgentRun,
                     });
@@ -8531,13 +9939,21 @@ export async function startLocalServer(opts) {
                         res.end(serializeJSON({ error: 'Invalid path' }));
                         return;
                     }
-                    mkdirSync(dirname(absPath), { recursive: true });
+                    await mkdirAsync(dirname(absPath), { recursive: true });
                     const toWrite = absPath.endsWith('.dql')
                         ? canonicalizeSafe(content)
                         : absPath.endsWith('.dqlnb')
                             ? canonicalizeNotebookSafe(content)
                             : content;
-                    writeFileSync(absPath, toWrite, 'utf-8');
+                    const tempPath = `${absPath}.tmp-${process.pid}-${Date.now()}`;
+                    try {
+                        await writeFileAsync(tempPath, toWrite, 'utf-8');
+                        await renameAsync(tempPath, absPath);
+                    }
+                    catch (error) {
+                        await rmAsync(tempPath, { force: true }).catch(() => undefined);
+                        throw error;
+                    }
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ ok: true }));
                 }
@@ -9835,12 +11251,185 @@ export async function startLocalServer(opts) {
                         passed: assertion.passed,
                         actual: assertion.error ?? (assertion.actual !== undefined ? String(assertion.actual) : undefined),
                     }));
-                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
-                    res.end(serializeJSON({ assertions: results, passed: summary.passed, failed: summary.failed, duration: summary.duration }));
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ assertions: results, passed: summary.passed, failed: summary.failed, duration: summary.duration }));
+                }
+                catch (error) {
+                    res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+                }
+                return;
+            }
+            if (req.method === 'POST' && path === '/api/block-studio/certifications') {
+                try {
+                    const body = await readJSON(req);
+                    const source = typeof body.source === 'string' ? body.source : '';
+                    const suppliedMetadata = body.metadata && typeof body.metadata === 'object'
+                        ? body.metadata
+                        : {};
+                    const currentPath = typeof body.path === 'string'
+                        ? normalize(body.path).replace(/^\/+/, '').replaceAll('\\', '/')
+                        : undefined;
+                    const expectedSourceFingerprint = typeof body.expectedSourceFingerprint === 'string'
+                        ? body.expectedSourceFingerprint
+                        : undefined;
+                    const idempotencyKey = typeof req.headers['idempotency-key'] === 'string'
+                        ? req.headers['idempotency-key'].trim()
+                        : '';
+                    if (!source.trim()) {
+                        res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ error: 'source is required' }));
+                        return;
+                    }
+                    if (idempotencyKey) {
+                        const existingId = operationIdempotency.get(idempotencyKey);
+                        const existing = existingId ? operationCoordinator.get(existingId) : null;
+                        if (existing) {
+                            res.writeHead(202, { 'Content-Type': 'application/json; charset=utf-8' });
+                            res.end(serializeJSON({ operation: existing, deduplicated: true }));
+                            return;
+                        }
+                    }
+                    if (currentPath && expectedSourceFingerprint) {
+                        const absoluteCurrentPath = safeJoin(projectRoot, currentPath);
+                        if (!absoluteCurrentPath || !existsSync(absoluteCurrentPath)) {
+                            res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                            res.end(serializeJSON({ error: 'The block changed or moved. Reopen it before certifying.', code: 'SOURCE_CHANGED' }));
+                            return;
+                        }
+                        const actualFingerprint = createHash('sha256')
+                            .update(readFileSync(absoluteCurrentPath, 'utf-8'))
+                            .digest('hex');
+                        if (actualFingerprint !== expectedSourceFingerprint) {
+                            res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                            res.end(serializeJSON({ error: 'The block changed after it was opened. Reopen it before certifying.', code: 'SOURCE_CHANGED' }));
+                            return;
+                        }
+                    }
+                    const draftSource = setBlockStudioStatusInSource(source, 'draft');
+                    const parsed = parseBlockSourceMetadata(draftSource);
+                    const name = typeof suppliedMetadata.name === 'string' && suppliedMetadata.name.trim()
+                        ? suppliedMetadata.name.trim()
+                        : parsed.name;
+                    if (!name) {
+                        res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ error: 'Block name is required.' }));
+                        return;
+                    }
+                    const canonicalPath = currentPath && !isDraftBlockPath(currentPath) ? currentPath : undefined;
+                    const stableSuffix = createHash('sha256')
+                        .update(currentPath ?? `${name}:${draftSource}`)
+                        .digest('hex')
+                        .slice(0, 16);
+                    const draftPath = saveBlockStudioDraftArtifacts(projectRoot, {
+                        currentPath: currentPath && isDraftBlockPath(currentPath) ? currentPath : undefined,
+                        source: draftSource,
+                        name,
+                        domain: typeof suppliedMetadata.domain === 'string' ? suppliedMetadata.domain : parsed.domain,
+                        description: typeof suppliedMetadata.description === 'string' ? suppliedMetadata.description : parsed.description,
+                        owner: typeof suppliedMetadata.owner === 'string' ? suppliedMetadata.owner : parsed.owner,
+                        tags: Array.isArray(suppliedMetadata.tags) ? suppliedMetadata.tags.map(String) : parsed.tags,
+                        lineage: Array.isArray(suppliedMetadata.lineage) ? suppliedMetadata.lineage.map(String) : undefined,
+                        stableSuffix,
+                    });
+                    const operation = operationCoordinator.create({
+                        type: 'block_certification',
+                        scope: `block:${draftPath}`,
+                        resourceRevision: typeof body.clientRevision === 'string'
+                            ? body.clientRevision
+                            : createHash('sha256').update(draftSource).digest('hex'),
+                        message: `Certification queued for ${name}.`,
+                        cancellable: true,
+                    });
+                    if (idempotencyKey) {
+                        operationIdempotency.set(idempotencyKey, operation.id);
+                        while (operationIdempotency.size > 100) {
+                            const oldest = operationIdempotency.keys().next().value;
+                            if (typeof oldest !== 'string')
+                                break;
+                            operationIdempotency.delete(oldest);
+                        }
+                    }
+                    operationCoordinator.run(operation.id, async (signal, report) => {
+                        report({ phase: 'validating', progress: 15, message: 'Validating and running the saved draft once.' });
+                        const result = await certifyBlockStudioSource(draftSource, draftPath, { enterprise: body.enterprise === true });
+                        const blockers = Array.from(new Set(result.checklist.blockers));
+                        if (signal.aborted)
+                            throw Object.assign(new Error('Certification cancelled.'), { code: 'OPERATION_CANCELLED' });
+                        if (!result.certification.certified || blockers.length > 0) {
+                            return {
+                                outcome: 'draft_saved_with_blockers',
+                                oldPath: currentPath ?? draftPath,
+                                draftPath,
+                                blockers,
+                                checklist: result.checklist,
+                                block: openBlockStudioDocument(projectRoot, draftPath, semanticLayer),
+                            };
+                        }
+                        report({ phase: 'publishing', progress: 80, message: 'Publishing the certified block.' });
+                        const certifiedSource = setBlockStudioStatusInSource(draftSource, 'certified');
+                        const certifiedMetadata = parseBlockSourceMetadata(certifiedSource);
+                        const savedPath = saveBlockStudioArtifacts(projectRoot, {
+                            currentPath: canonicalPath ?? draftPath,
+                            source: certifiedSource,
+                            name: certifiedMetadata.name || name,
+                            domain: certifiedMetadata.domain,
+                            description: certifiedMetadata.description,
+                            owner: certifiedMetadata.owner,
+                            tags: certifiedMetadata.tags,
+                        });
+                        if (canonicalPath && draftPath !== savedPath) {
+                            try {
+                                deleteBlockStudioArtifacts(projectRoot, draftPath);
+                            }
+                            catch { /* certified source is already durable */ }
+                        }
+                        // Shared learning remains the same deterministic, advisory write used
+                        // by the synchronous compatibility route. It never gates publication.
+                        try {
+                            const learnedOutputs = Array.isArray(certifiedMetadata.outputs)
+                                ? certifiedMetadata.outputs.filter((output) => typeof output === 'string')
+                                : [];
+                            if (certifiedMetadata.name) {
+                                const memory = new MemoryStore(defaultMemoryPath(projectRoot));
+                                memory.upsert({
+                                    id: `mem_certify_${certifiedMetadata.name}`,
+                                    scope: 'project',
+                                    title: `Certified block: ${certifiedMetadata.name}`,
+                                    content: `Prefer the certified block "${certifiedMetadata.name}" for ${certifiedMetadata.description?.trim() || `questions in the ${certifiedMetadata.domain ?? 'analytics'} domain`}.${certifiedMetadata.grain ? ` Grain: ${certifiedMetadata.grain}.` : ''}${learnedOutputs.length ? ` Outputs: ${learnedOutputs.slice(0, 8).join(', ')}.` : ''} It is the trusted source — reuse it instead of generating new SQL.`,
+                                    tags: [certifiedMetadata.domain, certifiedMetadata.name, ...learnedOutputs.slice(0, 4)].filter((value) => Boolean(value)),
+                                    source: 'certify',
+                                    confidence: 0.95,
+                                    importance: 0.85,
+                                    enabled: true,
+                                });
+                            }
+                        }
+                        catch {
+                            /* best-effort: learning capture must never block certification */
+                        }
+                        const refreshOperation = scheduleProjectRefresh('block-studio-certification');
+                        return {
+                            outcome: 'certified',
+                            oldPath: currentPath ?? draftPath,
+                            draftPath,
+                            newPath: savedPath,
+                            block: openBlockStudioDocument(projectRoot, savedPath, semanticLayer),
+                            checklist: result.checklist,
+                            indexRefresh: { status: 'queued', operationId: refreshOperation.id },
+                        };
+                    });
+                    res.writeHead(202, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        operation: operationCoordinator.get(operation.id) ?? operation,
+                        draft: openBlockStudioDocument(projectRoot, draftPath, semanticLayer),
+                    }));
                 }
                 catch (error) {
-                    res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
-                    res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+                    const code = apiErrorCode(error, 'CERTIFICATION_REQUEST_FAILED');
+                    const status = code === 'SOURCE_CHANGED' || apiErrorMessage(error) === 'BLOCK_EXISTS' ? 409 : 500;
+                    res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: apiErrorMessage(error), code }));
                 }
                 return;
             }
@@ -9913,7 +11502,7 @@ export async function startLocalServer(opts) {
                     catch {
                         /* best-effort: learning capture must never block certification */
                     }
-                    await refreshLocalMetadataCatalog(projectRoot);
+                    const refreshOperation = scheduleProjectRefresh('block-studio-certify');
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({
                         ok: true,
@@ -9924,6 +11513,7 @@ export async function startLocalServer(opts) {
                         metadata: certifiedPayload?.metadata,
                         companionPath: certifiedPayload?.companionPath ?? null,
                         validation: certifiedPayload?.validation ?? result.validation,
+                        lineageRefresh: { status: 'queued', operationId: refreshOperation.id },
                     }));
                 }
                 catch (error) {
@@ -10747,6 +12337,20 @@ export async function startLocalServer(opts) {
                         res.end(serializeJSON({ error: 'Block name is required.' }));
                         return;
                     }
+                    const validation = validateBlockStudioSource(source, semanticLayer);
+                    if (!blockStudioValidationAllowsDraftSave(validation)) {
+                        const errors = validation.diagnostics.filter((diagnostic) => diagnostic.severity === 'error'
+                            && !BLOCK_STUDIO_DRAFT_RUNTIME_DIAGNOSTICS.has(diagnostic.code ?? ''));
+                        res.writeHead(422, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({
+                            error: errors[0]?.message ?? 'Fix the block errors before saving.',
+                            code: 'BLOCK_VALIDATION_FAILED',
+                            recoverable: true,
+                            details: { validation: { ...validation, saveable: false } },
+                            nextActions: ['Edit the DQL source', 'Fix with AI and run'],
+                        }));
+                        return;
+                    }
                     const currentPath = typeof body.path === 'string' ? body.path : undefined;
                     const saveOptions = {
                         currentPath,
@@ -10773,25 +12377,13 @@ export async function startLocalServer(opts) {
                             stableSuffix: metadata.candidateId,
                         })
                         : saveBlockStudioArtifacts(projectRoot, saveOptions);
-                    let compiledManifest;
-                    let lineageRefresh;
-                    try {
-                        compiledManifest = compileBlockStudioManifest(projectRoot, projectConfig);
-                        lineageRefresh = { status: 'ready', compiledAt: new Date().toISOString() };
-                    }
-                    catch (error) {
-                        // The block is already safely stored. Preserve it and report the
-                        // rebuild failure separately instead of turning a successful save
-                        // into a misleading 500 response.
-                        lineageRefresh = {
-                            status: 'failed',
-                            message: error instanceof Error ? error.message : String(error),
-                        };
-                    }
-                    await refreshLocalMetadataCatalog(projectRoot, compiledManifest, semanticLayer);
+                    const refreshOperation = scheduleProjectRefresh('block-studio-save');
                     const payload = {
                         ...openBlockStudioDocument(projectRoot, savedPath, semanticLayer),
-                        lineageRefresh,
+                        lineageRefresh: {
+                            status: 'queued',
+                            operationId: refreshOperation.id,
+                        },
                     };
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON(payload));
@@ -10811,21 +12403,13 @@ export async function startLocalServer(opts) {
                 try {
                     const blockPath = url.searchParams.get('path');
                     const deleted = deleteBlockStudioArtifacts(projectRoot, blockPath ?? '');
-                    let compiledManifest;
-                    let lineageRefresh;
-                    try {
-                        compiledManifest = compileBlockStudioManifest(projectRoot, projectConfig);
-                        lineageRefresh = { status: 'ready', compiledAt: new Date().toISOString() };
-                    }
-                    catch (error) {
-                        lineageRefresh = {
-                            status: 'failed',
-                            message: error instanceof Error ? error.message : String(error),
-                        };
-                    }
-                    await refreshLocalMetadataCatalog(projectRoot, compiledManifest, semanticLayer);
+                    const refreshOperation = scheduleProjectRefresh('block-studio-delete');
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
-                    res.end(serializeJSON({ ok: true, ...deleted, lineageRefresh }));
+                    res.end(serializeJSON({
+                        ok: true,
+                        ...deleted,
+                        lineageRefresh: { status: 'queued', operationId: refreshOperation.id },
+                    }));
                 }
                 catch (error) {
                     const message = error instanceof Error ? error.message : String(error);
@@ -12422,11 +14006,12 @@ export async function startLocalServer(opts) {
                 return;
             }
             /**
-             * Repair an editable notebook cell without starting Notebook AI research.
-             * The returned source is applied only to the in-memory notebook cell by the
-             * client; this endpoint never writes a block/domain/dbt source file.
+             * Repair an editable notebook cell or Block Studio draft without starting
+             * an AI conversation. The returned source is applied only to the in-memory
+             * editor by the client; this endpoint never writes governed source files.
              */
-            if (req.method === 'POST' && path === '/api/notebook/repair-execution') {
+            if (req.method === 'POST' && (path === '/api/notebook/repair-execution'
+                || path === '/api/block-studio/repair-and-run')) {
                 let body = {};
                 let execContext = null;
                 const start = Date.now();
@@ -12445,9 +14030,9 @@ export async function startLocalServer(opts) {
                         return;
                     }
                     const embeddedSourceSql = notebookCellRepairSql(cell);
-                    if (!embeddedSourceSql) {
+                    if (!embeddedSourceSql && (cell.type !== 'dql' || !notebookDqlSourceAllowsBackgroundRepair(cell.source))) {
                         res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
-                        res.end(serializeJSON({ error: 'Background repair supports SQL cells and DQL cells with an embedded query. Edit this semantic DQL definition directly.' }));
+                        res.end(serializeJSON({ error: 'Background repair supports SQL cells and editable custom DQL blocks. Open governed references or semantic definitions in their owning editor.' }));
                         return;
                     }
                     if (cell.type === 'sql' && /\{\{[^}]+\}\}/.test(cell.source)) {
@@ -12480,31 +14065,33 @@ export async function startLocalServer(opts) {
                     const parameters = body.parameters && typeof body.parameters === 'object' && !Array.isArray(body.parameters)
                         ? body.parameters
                         : {};
-                    const invocation = cell.type === 'dql'
-                        ? prepareBlockInvocation({ source: cell.source, parameters, surface: 'notebook' })
-                        : null;
-                    if (invocation?.errors.length) {
-                        throw boundedRepairError(invocation.errors.join(' '), 409);
-                    }
-                    if (invocation?.unresolvedParameters.length) {
-                        throw boundedRepairError(`Provide required parameter${invocation.unresolvedParameters.length === 1 ? '' : 's'} before retrying: ${invocation.unresolvedParameters.join(', ')}.`, 409);
+                    let invocation = null;
+                    let plan = null;
+                    let dqlCompilationError;
+                    if (cell.type === 'dql') {
+                        try {
+                            invocation = prepareBlockInvocation({ source: cell.source, parameters, surface: 'notebook' });
+                            if (invocation.errors.length)
+                                throw boundedRepairError(invocation.errors.join(' '), 409);
+                            if (invocation.unresolvedParameters.length) {
+                                throw boundedRepairError(`Provide required parameter${invocation.unresolvedParameters.length === 1 ? '' : 's'} before retrying: ${invocation.unresolvedParameters.join(', ')}.`, 409);
+                            }
+                            plan = buildExecutionPlan(cell, {
+                                semanticLayer,
+                                driver: targetConnection.driver,
+                                parameters: invocation.values,
+                            });
+                        }
+                        catch (error) {
+                            const repairError = error;
+                            if (repairError.status === 409)
+                                throw error;
+                            dqlCompilationError = repairError.message || String(error);
+                        }
                     }
-                    const plan = cell.type === 'dql'
-                        ? buildExecutionPlan(cell, {
-                            semanticLayer,
-                            driver: targetConnection.driver,
-                            parameters: invocation?.values,
-                        })
-                        : null;
                     const attemptedSql = typeof body.attemptedSql === 'string' && body.attemptedSql.trim()
                         ? body.attemptedSql.trim()
                         : embeddedSourceSql;
-                    const sourceSql = plan?.sql ?? attemptedSql;
-                    const sqlParams = plan?.sqlParams ?? [];
-                    const variables = {
-                        ...(plan?.variables ?? {}),
-                        ...(invocation?.values ?? {}),
-                    };
                     const executionTarget = executionTargetDescriptor(body);
                     const targetConnectionName = executionTarget.target === 'connection'
                         ? executionTarget.connectionName
@@ -12515,24 +14102,48 @@ export async function startLocalServer(opts) {
                         `Repair notebook cell ${cell.title?.trim() || cell.id}.`,
                         submittedError ? `Failure: ${submittedError.slice(0, 1_000)}` : '',
                     ].filter(Boolean).join(' ');
-                    const repaired = await executeBoundedSqlRepair({
-                        question,
-                        sourceSql,
-                        targetConnection,
-                        targetConnectionName,
-                        sqlParams,
-                        variables,
-                    });
+                    let repaired;
                     let repairedSource;
-                    if (cell.type === 'dql') {
-                        const originalQuery = notebookCellRepairSql(cell);
-                        const repairedQuery = repaired.repairMode === 'deterministic'
-                            ? applyNotebookRepairRewrites(originalQuery, repaired.rewrites)
-                            : restoreNotebookDqlParameterInterpolations(repaired.repairedSql, sqlParams);
-                        repairedSource = replaceNotebookDqlQueryForRepair(cell.source, repairedQuery);
+                    if (cell.type === 'dql' && dqlCompilationError) {
+                        const repairedDql = await executeBoundedDqlRepair({
+                            question,
+                            source: cell.source,
+                            failure: [submittedError, dqlCompilationError].filter(Boolean).join('\n'),
+                            targetConnection,
+                            targetConnectionName,
+                            parameters,
+                            artifactName: cell.title,
+                        });
+                        repaired = repairedDql;
+                        repairedSource = repairedDql.repairedSource;
                     }
                     else {
-                        repairedSource = repaired.repairedSql;
+                        const sourceSql = plan?.sql ?? attemptedSql;
+                        if (!sourceSql?.trim()) {
+                            throw boundedRepairError('DQL could not identify an embedded query to repair.', 422);
+                        }
+                        const sqlParams = plan?.sqlParams ?? [];
+                        repaired = await executeBoundedSqlRepair({
+                            question,
+                            sourceSql,
+                            targetConnection,
+                            targetConnectionName,
+                            sqlParams,
+                            variables: {
+                                ...(plan?.variables ?? {}),
+                                ...(invocation?.values ?? {}),
+                            },
+                        });
+                        if (cell.type === 'dql') {
+                            const originalQuery = notebookCellRepairSql(cell);
+                            const repairedQuery = repaired.repairMode === 'deterministic'
+                                ? applyNotebookRepairRewrites(originalQuery, repaired.rewrites)
+                                : restoreNotebookDqlParameterInterpolations(repaired.repairedSql, sqlParams);
+                            repairedSource = replaceNotebookDqlQueryForRepair(cell.source, repairedQuery);
+                        }
+                        else {
+                            repairedSource = repaired.repairedSql;
+                        }
                     }
                     if (!repairedSource) {
                         throw boundedRepairError('DQL could not safely replace the embedded query in this cell.', 422);
@@ -12543,12 +14154,13 @@ export async function startLocalServer(opts) {
                         const validationPlan = buildExecutionPlan({ ...cell, source: repairedSource }, {
                             semanticLayer,
                             driver: targetConnection.driver,
-                            parameters: invocation?.values,
+                            parameters: invocation?.values ?? parameters,
                         });
                         if (!validationPlan?.sql) {
                             throw boundedRepairError('The repaired SQL ran, but the DQL wrapper no longer compiles.', 422);
                         }
-                        const beforeParameters = sqlParams.map((parameter) => `${parameter.position}:${parameter.name}`);
+                        const beforeParameters = (plan?.sqlParams ?? ('sqlParams' in repaired ? repaired.sqlParams : []))
+                            .map((parameter) => `${parameter.position}:${parameter.name}`);
                         const afterParameters = validationPlan.sqlParams.map((parameter) => `${parameter.position}:${parameter.name}`);
                         if (beforeParameters.join('|') !== afterParameters.join('|')) {
                             throw boundedRepairError('The repaired DQL changed the cell parameter contract, so the update was stopped.', 422);
@@ -13814,6 +15426,22 @@ table: ${table}${tagList}
             })));
         });
     });
+    server.once('close', () => {
+        runtimeClosing = true;
+        for (const watcher of projectWatchers)
+            watcher.close();
+        projectWatchers.length = 0;
+        unsubscribeOperationEvents();
+        projectRefreshCoordinator.close();
+        for (const client of operationSseClients) {
+            try {
+                client.end();
+            }
+            catch { /* connection already closed */ }
+        }
+        operationSseClients.clear();
+        operationCoordinator.close();
+    });
     opts.captureServer?.(server);
     return new Promise((resolvePromise, reject) => {
         let retriedWithRandomPort = false;
@@ -14255,7 +15883,7 @@ function loadAppDashboard(projectRoot, appId, dashboardId) {
         for (const d of findDashboardsForApp(appDir)) {
             const { document: dashboard } = loadDashboardDocument(d);
             if (dashboard?.id === dashboardId)
-                return { app, dashboard };
+                return { app, dashboard, appDir };
         }
     }
     return null;
@@ -14360,6 +15988,7 @@ function serializeSkill(skill) {
         clarifyWhen: skill.clarifyWhen,
         examples: skill.examples,
         sourceRefs: skill.sourceRefs,
+        analyticalPolicy: skill.analyticalPolicy,
         vocabulary: skill.vocabulary,
         sourcePath: skill.sourcePath,
         isStarter: skill.isStarter,
@@ -14415,9 +16044,27 @@ function parseSkillInput(raw, fallbackId) {
         examples: asStrings(skill.examples),
         sourceRefs: asStrings(skill.sourceRefs),
         vocabulary: asMap(skill.vocabulary),
+        analyticalPolicy: parseSkillAnalyticalPolicyInput(skill.analyticalPolicy),
         isStarter: skill.isStarter === true ? true : undefined,
     };
 }
+function parseSkillAnalyticalPolicyInput(value) {
+    const policy = contextRecord(value);
+    if (!Object.keys(policy).length)
+        return undefined;
+    const strings = (input) => Array.isArray(input) ? input.filter((item) => typeof item === 'string') : [];
+    const pick = (input) => typeof input === 'string' && input.trim() ? input.trim() : undefined;
+    return {
+        metricIds: strings(policy.metricIds ?? policy.metric_ids),
+        timeRole: pick(policy.timeRole ?? policy.time_role),
+        calendarId: pick(policy.calendarId ?? policy.calendar_id),
+        timezone: pick(policy.timezone),
+        completenessPolicy: ['partial_current', 'latest_complete', 'closed_period'].includes(String(policy.completenessPolicy ?? policy.completeness_policy)) ? String(policy.completenessPolicy ?? policy.completeness_policy) : undefined,
+        comparisonAlignment: ['elapsed_period', 'calendar_period', 'fiscal_period'].includes(String(policy.comparisonAlignment ?? policy.comparison_alignment)) ? String(policy.comparisonAlignment ?? policy.comparison_alignment) : undefined,
+        defaultRankingPeriod: ['current', 'comparison'].includes(String(policy.defaultRankingPeriod ?? policy.default_ranking_period)) ? String(policy.defaultRankingPeriod ?? policy.default_ranking_period) : undefined,
+        narrativeGuidance: strings(policy.narrativeGuidance ?? policy.narrative_guidance),
+    };
+}
 /** Loose, case/slug-insensitive domain key for counting membership. */
 function domainKey(value) {
     if (!value)
@@ -14577,6 +16224,553 @@ export function parseDomainInput(raw, fallbackId) {
         sourcePath: typeof domain.sourcePath === 'string' ? domain.sourcePath : undefined,
     };
 }
+function modelingImportDirectory(projectRoot) {
+    return join(projectRoot, '.dql', 'local', 'modeling-imports');
+}
+function modelingImportSessionPath(projectRoot, id) {
+    const safe = id.replace(/[^a-zA-Z0-9_-]/g, '');
+    if (!safe || safe !== id)
+        throw new Error('Invalid modeling import id.');
+    return join(modelingImportDirectory(projectRoot), `${safe}.json`);
+}
+function writeModelingImportSession(projectRoot, session) {
+    mkdirSync(modelingImportDirectory(projectRoot), { recursive: true });
+    writeFileSync(modelingImportSessionPath(projectRoot, session.id), `${JSON.stringify(session, null, 2)}\n`, 'utf8');
+}
+function readModelingImportSession(projectRoot, id) {
+    const path = modelingImportSessionPath(projectRoot, id);
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return parsed.version === 1 && parsed.id === id ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function publicModelingImportSession(session) {
+    return {
+        ...session,
+        candidates: session.candidates.map(({ document: _document, ...candidate }) => candidate),
+    };
+}
+function createModelingImportSession(projectRoot, gitRoot, loopback, source) {
+    const mode = source.mode;
+    if (mode !== 'current_project' && mode !== 'path' && mode !== 'upload' && mode !== 'paste')
+        throw Object.assign(new Error('Choose current_project, path, upload, or paste.'), { code: 'INVALID_REQUEST' });
+    const files = [];
+    if (mode === 'paste' || mode === 'upload') {
+        const content = typeof source.content === 'string' ? source.content : '';
+        if (!content.trim() || Buffer.byteLength(content) > 1_000_000)
+            throw Object.assign(new Error('YAML content is required and must be 1 MB or smaller.'), { code: 'MODELING_IMPORT_LIMIT' });
+        files.push({ name: typeof source.filename === 'string' ? source.filename : mode === 'paste' ? 'pasted-modeling.yaml' : 'uploaded-modeling.yaml', content, inProject: false });
+    }
+    else {
+        if (mode === 'path' && !loopback)
+            throw Object.assign(new Error('Local path import is available only on the loopback Notebook runtime.'), { code: 'PATH_ACCESS_FORBIDDEN' });
+        const allowedRoot = realpathSync(resolve(gitRoot ?? projectRoot));
+        const requestedInput = mode === 'current_project'
+            ? resolve(projectRoot)
+            : resolve(projectRoot, typeof source.path === 'string' ? source.path : '');
+        if (!existsSync(requestedInput))
+            throw Object.assign(new Error('The selected YAML path does not exist.'), { code: 'MODELING_IMPORT_NOT_FOUND' });
+        const requested = realpathSync(requestedInput);
+        if (requested !== allowedRoot && !requested.startsWith(`${allowedRoot}${sep}`))
+            throw Object.assign(new Error('Import path must stay inside the current Git workspace.'), { code: 'PATH_ACCESS_FORBIDDEN' });
+        const paths = collectModelingYamlPaths(requested, 100);
+        for (const path of paths) {
+            const size = statSync(path).size;
+            if (size > 1_000_000)
+                continue;
+            const resolvedPath = realpathSync(path);
+            if (resolvedPath !== allowedRoot && !resolvedPath.startsWith(`${allowedRoot}${sep}`))
+                continue;
+            const resolvedProject = realpathSync(projectRoot);
+            files.push({ name: relative(requested, resolvedPath).replace(/\\/g, '/') || resolvedPath.split(sep).at(-1), path: relative(resolvedProject, resolvedPath).replace(/\\/g, '/'), content: readFileSync(resolvedPath, 'utf8'), inProject: resolvedPath === resolvedProject || resolvedPath.startsWith(`${resolvedProject}${sep}`) });
+        }
+    }
+    if (files.length === 0)
+        throw Object.assign(new Error('No YAML files were found in the selected source.'), { code: 'MODELING_IMPORT_EMPTY' });
+    const candidates = files.map((file, index) => classifyModelingYamlCandidate(file, index));
+    const now = new Date().toISOString();
+    const session = {
+        version: 1,
+        id: apiRequestId('import'),
+        createdAt: now,
+        updatedAt: now,
+        source: { mode, label: mode === 'path' ? String(source.path ?? '') : mode === 'current_project' ? 'Current project' : files[0].name },
+        candidates,
+    };
+    writeModelingImportSession(projectRoot, session);
+    return session;
+}
+function collectModelingYamlPaths(start, limit) {
+    if (!existsSync(start))
+        throw Object.assign(new Error('The selected YAML path does not exist.'), { code: 'MODELING_IMPORT_NOT_FOUND' });
+    if (statSync(start).isFile())
+        return /\.ya?ml$/i.test(start) ? [start] : [];
+    const output = [];
+    const visit = (directory) => {
+        if (output.length >= limit)
+            return;
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            if (output.length >= limit)
+                return;
+            if (entry.name.startsWith('.') || ['node_modules', 'target', 'dist', 'build'].includes(entry.name))
+                continue;
+            const path = join(directory, entry.name);
+            if (entry.isDirectory())
+                visit(path);
+            else if (entry.isFile() && /\.ya?ml$/i.test(entry.name))
+                output.push(path);
+        }
+    };
+    visit(start);
+    return output.sort();
+}
+function classifyModelingYamlCandidate(file, index) {
+    let document = {};
+    try {
+        const parsed = loadYaml(file.content);
+        document = contextRecord(parsed);
+    }
+    catch (error) {
+        return { id: `file-${index + 1}`, name: file.name, path: file.path, dialect: 'unsupported', action: 'unsupported', summary: 'Malformed YAML', warnings: [error instanceof Error ? error.message : String(error)] };
+    }
+    const keys = new Set(Object.keys(document));
+    const dialect = keys.has('entities') || keys.has('relationships') || keys.has('area') || keys.has('domain')
+        ? 'dql_modeling'
+        : keys.has('semantic_models') || keys.has('metrics')
+            ? 'dbt_semantic'
+            : keys.has('models') || keys.has('sources')
+                ? 'dbt_resource'
+                : 'unsupported';
+    const objectCount = ['entities', 'relationships', 'models', 'sources', 'semantic_models', 'metrics']
+        .reduce((total, key) => total + (Array.isArray(document[key]) ? document[key].length : 0), 0);
+    const openExisting = file.inProject && dialect === 'dql_modeling' && Boolean(file.path?.startsWith('domains/'));
+    return {
+        id: `file-${index + 1}`,
+        name: file.name,
+        path: file.path,
+        dialect,
+        action: dialect === 'unsupported' ? 'unsupported' : openExisting ? 'open_existing' : 'import',
+        summary: dialect === 'unsupported' ? 'Unsupported generic YAML' : `${objectCount || 1} ${dialect.replace('_', ' ')} candidate${objectCount === 1 ? '' : 's'}`,
+        warnings: dialect === 'unsupported' ? ['v1 supports DQL modeling, dbt resource, and dbt semantic YAML only.'] : openExisting ? ['This is already governed by the current project and should be opened in place.'] : [],
+        document,
+    };
+}
+function modelingImportOperations(session, selectedIds, domain, areaId, manifest) {
+    const diagnostics = [];
+    const operations = [];
+    const selected = session.candidates.filter((candidate) => selectedIds.includes(candidate.id));
+    if (!selected.length)
+        throw Object.assign(new Error('Select at least one supported YAML candidate.'), { code: 'MODELING_IMPORT_EMPTY' });
+    const packageExists = Boolean(manifest.modeling?.packages?.[domain]);
+    const area = Object.values(manifest.modeling?.areas ?? {}).find((item) => item.domain === domain && (item.localId === areaId || item.qualifiedId === areaId));
+    if (!packageExists)
+        diagnostics.push({ code: 'DOMAIN_NOT_FOUND', severity: 'blocking', message: `Domain not found: ${domain}` });
+    if (!area)
+        diagnostics.push({ code: 'MODEL_AREA_NOT_FOUND', severity: 'blocking', message: `Model Area not found in ${domain}: ${areaId}` });
+    const nodes = Object.values(manifest.dbtProvenance?.nodes ?? {});
+    const resolveDbt = (reference, operationId) => {
+        const cleaned = reference.replace(/^ref\(['"]|['"]\)$/g, '').replace(/^model\./, '');
+        const matches = nodes.filter((node) => node.uniqueId === reference || node.name === reference || node.name === cleaned || node.uniqueId.endsWith(`.${cleaned}`));
+        if (matches.length !== 1)
+            diagnostics.push({ code: matches.length ? 'AMBIGUOUS_DBT_MODEL' : 'DBT_MODEL_NOT_FOUND', severity: 'blocking', operationId, message: `${reference} ${matches.length ? 'matches multiple dbt models' : 'was not found in the active dbt manifest'}.` });
+        return matches.length === 1 ? matches[0].uniqueId : undefined;
+    };
+    const used = new Set(Object.values(manifest.modeling?.entities ?? {}).filter((entity) => entity.domain === domain).map((entity) => entity.localId));
+    const allocate = (value) => {
+        const base = authoringSlug(value).replace(/-/g, '_') || 'model';
+        let id = base;
+        let suffix = 2;
+        while (used.has(id))
+            id = `${base}_${suffix++}`;
+        used.add(id);
+        return id;
+    };
+    for (const candidate of selected) {
+        if (candidate.action === 'open_existing') {
+            diagnostics.push({ code: 'OPEN_EXISTING_SOURCE', severity: 'info', message: `${candidate.path ?? candidate.name} is already in the current Domain Package and was not copied.` });
+            continue;
+        }
+        if (candidate.dialect === 'unsupported' || !candidate.document) {
+            diagnostics.push({ code: 'UNSUPPORTED_YAML', severity: 'blocking', message: `${candidate.name} is not DQL or dbt modeling YAML.` });
+            continue;
+        }
+        const document = candidate.document;
+        if (candidate.dialect === 'dql_modeling') {
+            const importedEntities = new Map();
+            for (const [index, raw] of contextArray(document.entities).entries()) {
+                const entity = contextRecord(raw);
+                const operationId = `${candidate.id}:entity:${index + 1}`;
+                const dbtModel = resolveDbt(String(entity.dbt_model ?? entity.dbtModel ?? ''), operationId);
+                if (!dbtModel)
+                    continue;
+                const sourceId = String(entity.id ?? nodes.find((node) => node.uniqueId === dbtModel)?.name ?? `model_${index + 1}`);
+                const id = allocate(sourceId);
+                importedEntities.set(sourceId, { id, operationId });
+                importedEntities.set(String(entity.qualified_id ?? entity.qualifiedId ?? ''), { id, operationId });
+                importedEntities.set(dbtModel, { id, operationId });
+                operations.push({ id: operationId, kind: 'modeling_change', evidence: [candidate.path ?? candidate.name, dbtModel], change: { operation: 'upsert_entity', value: { id, domain, areaId: area?.localId ?? areaId, dbtModel, businessName: typeof entity.business_name === 'string' ? entity.business_name : undefined, businessContext: typeof entity.business_context === 'string' ? entity.business_context : undefined, conceptRefs: contextStrings(entity.concept_refs), analyticalRole: parseImportedAnalyticalRole(entity.analytical_role), status: 'draft', owner: typeof entity.owner === 'string' ? entity.owner : undefined, grain: typeof entity.grain === 'string' ? entity.grain : undefined, keys: contextStrings(entity.keys) } } });
+            }
+            for (const [index, raw] of contextArray(document.relationships).entries()) {
+                const relationship = contextRecord(raw);
+                const operationId = `${candidate.id}:relationship:${index + 1}`;
+                const keys = contextArray(relationship.keys).flatMap((value) => {
+                    const key = contextRecord(value);
+                    return typeof key.from === 'string' && typeof key.to === 'string' ? [{ from: key.from, to: key.to }] : [];
+                });
+                if (!relationship.from || !relationship.to || !keys.length) {
+                    diagnostics.push({ code: 'RELATIONSHIP_INCOMPLETE', severity: 'blocking', operationId, message: 'Imported relationship requires from, to, and at least one key pair.' });
+                    continue;
+                }
+                const resolveEndpoint = (rawRef) => {
+                    const ref = String(rawRef);
+                    const imported = importedEntities.get(ref);
+                    if (imported)
+                        return { id: imported.id, dependency: imported.operationId };
+                    const matches = Object.values(manifest.modeling?.entities ?? {}).filter((entity) => entity.domain === domain && (entity.localId === ref || entity.id === ref || entity.qualifiedId === ref));
+                    return matches.length === 1 ? { id: matches[0].localId } : {};
+                };
+                const from = resolveEndpoint(relationship.from);
+                const to = resolveEndpoint(relationship.to);
+                if (!from.id || !to.id) {
+                    diagnostics.push({ code: 'RELATIONSHIP_REFERENCE_UNRESOLVED', severity: 'blocking', operationId, message: `Relationship endpoints must resolve inside ${domain}; simple import cannot create cross-domain relationships.` });
+                    continue;
+                }
+                operations.push({ id: operationId, kind: 'modeling_change', dependsOn: [...new Set([from.dependency, to.dependency].filter((value) => Boolean(value)))], evidence: [candidate.path ?? candidate.name], change: { operation: 'upsert_relationship', value: { id: String(relationship.id ?? `${relationship.from}_to_${relationship.to}`), domain, areaId: area?.localId ?? areaId, from: from.id, to: to.id, keys, cardinality: parseImportedCardinality(relationship.cardinality), fanout: parseImportedFanout(relationship.fanout), status: 'draft', description: typeof relationship.description === 'string' ? relationship.description : undefined, rationale: 'Imported as a draft; certification and warehouse proof were intentionally removed.' } } });
+            }
+        }
+        else {
+            const modelRecords = candidate.dialect === 'dbt_resource'
+                ? contextArray(document.models)
+                : contextArray(document.semantic_models);
+            for (const [index, raw] of modelRecords.entries()) {
+                const model = contextRecord(raw);
+                const operationId = `${candidate.id}:model:${index + 1}`;
+                const reference = String(model.model ?? model.name ?? '');
+                const dbtModel = resolveDbt(reference, operationId);
+                if (!dbtModel)
+                    continue;
+                const existing = Object.values(manifest.modeling?.entities ?? {}).find((entity) => entity.dbtUniqueId === dbtModel);
+                if (existing && existing.domain !== domain) {
+                    diagnostics.push({ code: 'OWNERSHIP_CONFLICT', severity: 'blocking', operationId, message: `${dbtModel} is already owned by ${existing.domain}; import cannot move it implicitly.` });
+                    continue;
+                }
+                const id = existing?.localId ?? allocate(String(model.name ?? nodes.find((node) => node.uniqueId === dbtModel)?.name ?? `model_${index + 1}`));
+                operations.push({ id: operationId, kind: 'modeling_change', evidence: [candidate.path ?? candidate.name, dbtModel], change: { operation: 'upsert_entity', value: { id, domain, areaId: area?.localId ?? areaId, dbtModel, businessName: typeof model.name === 'string' ? titleCaseAuthoring(model.name) : undefined, businessContext: typeof model.description === 'string' ? model.description : undefined, status: 'draft', analyticalRole: 'unknown' } } });
+            }
+        }
+    }
+    if (!operations.length)
+        throw Object.assign(new Error('The selected YAML did not produce any resolvable modeling changes.'), { code: 'MODELING_IMPORT_EMPTY', diagnostics });
+    return { operations, diagnostics };
+}
+function contextRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function contextArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function contextStrings(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+function parseImportedAnalyticalRole(value) {
+    return value === 'event' || value === 'dimension' || value === 'snapshot' || value === 'bridge' ? value : 'unknown';
+}
+function parseImportedCardinality(value) {
+    return value === 'one_to_one' || value === 'one_to_many' || value === 'many_to_one' || value === 'many_to_many' ? value : 'unknown';
+}
+function parseImportedFanout(value) {
+    if (value === 'unsafe' || value === 'forbidden')
+        return 'forbidden';
+    return value === 'safe' || value === 'dedupe_required' || value === 'attribution_required' ? value : 'unknown';
+}
+function contextSourceReferenceExists(manifest, reference) {
+    if (!reference.includes('::entity::') && !reference.includes('::relationship::'))
+        return true;
+    return Object.values(manifest.modeling?.entities ?? {}).some((entity) => entity.qualifiedId === reference)
+        || Object.values(manifest.modeling?.relationships ?? {}).some((relationship) => relationship.qualifiedId === reference);
+}
+function parseContextAuthoringOrigin(value) {
+    if (value === 'manual' || value === 'yaml_import' || value === 'dbt_discovery' || value === 'ai' || value === 'correction')
+        return value;
+    throw Object.assign(new Error('A valid context proposal origin is required.'), { code: 'INVALID_REQUEST' });
+}
+function parseContextAuthoringOperations(value) {
+    if (!Array.isArray(value) || value.length === 0 || value.length > 100)
+        throw Object.assign(new Error('Provide 1-100 authoring operations.'), { code: 'INVALID_REQUEST' });
+    const ids = new Set();
+    return value.map((raw, index) => {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            throw Object.assign(new Error(`Operation ${index + 1} is invalid.`), { code: 'INVALID_REQUEST' });
+        const operation = raw;
+        const id = typeof operation.id === 'string' ? operation.id.trim() : '';
+        if (!id || ids.has(id))
+            throw Object.assign(new Error(`Operation ${index + 1} requires a unique id.`), { code: 'INVALID_REQUEST' });
+        ids.add(id);
+        const dependsOn = Array.isArray(operation.dependsOn) ? operation.dependsOn.filter((item) => typeof item === 'string') : undefined;
+        const evidence = Array.isArray(operation.evidence) ? operation.evidence.filter((item) => typeof item === 'string').slice(0, 32) : undefined;
+        if (operation.kind === 'modeling_change') {
+            const change = operation.change;
+            const allowed = new Set(['upsert_domain', 'upsert_area', 'upsert_entity', 'upsert_relationship', 'upsert_contract', 'upsert_export', 'upsert_import', 'remove_entity', 'remove_relationship', 'remove_area']);
+            if (!change || typeof change !== 'object' || !allowed.has(change.operation) || !('value' in change) || !change.value || typeof change.value !== 'object')
+                throw Object.assign(new Error(`Modeling operation ${id} is invalid.`), { code: 'INVALID_REQUEST' });
+            return { id, kind: 'modeling_change', change, dependsOn, evidence };
+        }
+        if (operation.kind === 'skill_change') {
+            const skillOperation = operation.operation;
+            const skill = operation.value;
+            if ((skillOperation !== 'create' && skillOperation !== 'update' && skillOperation !== 'move') || !skill || typeof skill.id !== 'string' || !skill.id.trim() || typeof skill.body !== 'string')
+                throw Object.assign(new Error(`Skill operation ${id} is invalid.`), { code: 'INVALID_REQUEST' });
+            return {
+                id,
+                kind: 'skill_change',
+                operation: skillOperation,
+                value: { ...skill, scope: 'project', status: 'draft' },
+                targetQualifiedId: typeof operation.targetQualifiedId === 'string' ? operation.targetQualifiedId : undefined,
+                expectedSourceHash: typeof operation.expectedSourceHash === 'string' ? operation.expectedSourceHash : undefined,
+                dependsOn,
+                evidence,
+            };
+        }
+        if (operation.kind === 'dbt_source_change') {
+            const change = operation.change;
+            if (!change || typeof change.uniqueId !== 'string' || !change.uniqueId.trim())
+                throw Object.assign(new Error(`dbt source operation ${id} is invalid.`), { code: 'INVALID_REQUEST' });
+            return { id, kind: 'dbt_source_change', change, dependsOn, evidence };
+        }
+        throw Object.assign(new Error(`Unsupported context operation kind for ${id}.`), { code: 'INVALID_REQUEST' });
+    });
+}
+function resolveContextPatchPath(projectRoot, gitRoot, relativePath) {
+    const allowedRoot = resolve(gitRoot ?? projectRoot);
+    const absolute = resolve(projectRoot, relativePath);
+    if (absolute !== allowedRoot && !absolute.startsWith(`${allowedRoot}${sep}`)) {
+        throw Object.assign(new Error(`Proposal path escapes the Git workspace: ${relativePath}`), { code: 'OWNERSHIP_CONFLICT' });
+    }
+    return absolute;
+}
+function buildMetadataBoundModelingOperations(projectRoot, manifest, request) {
+    const modeling = manifest.modeling;
+    if (!modeling || !manifest.dbtProvenance)
+        throw new Error('Modeling AI requires a compiled dbt-first project snapshot.');
+    const context = request.workspaceContext ?? {};
+    const requestedDomain = typeof context.domain === 'string'
+        ? context.domain
+        : request.selectedObject?.kind === 'domain'
+            ? request.selectedObject.id
+            : undefined;
+    const domain = requestedDomain ?? Object.keys(modeling.packages)[0];
+    if (!domain || !modeling.packages[domain])
+        throw new Error('Select or create a Domain before building models with AI.');
+    const selectedIdentity = request.selectedObject?.id;
+    const selectedRelationship = request.selectedObject?.kind === 'relationship'
+        ? Object.values(modeling.relationships).find((item) => item.qualifiedId === selectedIdentity || item.id === selectedIdentity || item.localId === selectedIdentity)
+        : undefined;
+    if (selectedRelationship) {
+        const cardinality = /one[-_ ]to[-_ ]one|1\s*:\s*1/i.test(request.question)
+            ? 'one_to_one'
+            : /one[-_ ]to[-_ ]many|1\s*:\s*n/i.test(request.question)
+                ? 'one_to_many'
+                : /many[-_ ]to[-_ ]one|n\s*:\s*1/i.test(request.question)
+                    ? 'many_to_one'
+                    : /many[-_ ]to[-_ ]many|n\s*:\s*n/i.test(request.question)
+                        ? 'many_to_many'
+                        : selectedRelationship.cardinality;
+        return [{
+                id: `relationship:${selectedRelationship.qualifiedId}`,
+                kind: 'modeling_change',
+                evidence: [selectedRelationship.sourcePath, ...(selectedRelationship.validation?.queryFingerprint ? [`validation:${selectedRelationship.validation.queryFingerprint}`] : [])],
+                change: {
+                    operation: 'upsert_relationship',
+                    value: {
+                        id: selectedRelationship.localId,
+                        domain: selectedRelationship.ownerDomain ?? domain,
+                        areaId: selectedRelationship.areaId?.split('::area::').at(-1),
+                        from: modeling.entities[selectedRelationship.from]?.localId ?? selectedRelationship.from,
+                        to: modeling.entities[selectedRelationship.to]?.localId ?? selectedRelationship.to,
+                        keys: selectedRelationship.keys,
+                        cardinality,
+                        fanout: selectedRelationship.fanout === 'unsafe' ? 'forbidden' : selectedRelationship.fanout,
+                        status: 'draft',
+                        owner: selectedRelationship.owner,
+                        ownerDomain: selectedRelationship.ownerDomain,
+                        verb: selectedRelationship.verb,
+                        description: selectedRelationship.description,
+                        rationale: request.question.trim(),
+                        roles: selectedRelationship.roles,
+                        optionality: selectedRelationship.optionality,
+                        joinTypes: selectedRelationship.joinTypes,
+                        aggregation: selectedRelationship.aggregation,
+                        temporal: selectedRelationship.temporal,
+                        attributionBlock: selectedRelationship.attributionBlock,
+                        importRefs: selectedRelationship.importRefs,
+                        evidenceExpiresAt: undefined,
+                    },
+                },
+            }];
+    }
+    const selectedEntity = request.selectedObject?.kind === 'model'
+        ? Object.values(modeling.entities).find((item) => item.qualifiedId === selectedIdentity || item.id === selectedIdentity || item.localId === selectedIdentity)
+        : undefined;
+    if (selectedEntity) {
+        return [{
+                id: `entity:${selectedEntity.qualifiedId}`,
+                kind: 'modeling_change',
+                evidence: [selectedEntity.sourcePath, selectedEntity.dbtUniqueId],
+                change: {
+                    operation: 'upsert_entity',
+                    value: {
+                        id: selectedEntity.localId,
+                        domain: selectedEntity.domain,
+                        areaId: selectedEntity.areaId?.split('::area::').at(-1),
+                        dbtModel: selectedEntity.dbtUniqueId,
+                        businessName: selectedEntity.businessName,
+                        businessContext: request.question.trim(),
+                        conceptRefs: selectedEntity.conceptRefs,
+                        analyticalRole: selectedEntity.analyticalRole,
+                        status: 'draft',
+                        owner: selectedEntity.owner,
+                        grain: selectedEntity.grain,
+                        keys: selectedEntity.keys,
+                    },
+                },
+            }];
+    }
+    const requestedArea = typeof context.modelAreaId === 'string' ? context.modelAreaId : typeof context.areaId === 'string' ? context.areaId : undefined;
+    const existingArea = Object.values(modeling.areas).find((area) => area.domain === domain
+        && (!requestedArea || area.qualifiedId === requestedArea || area.localId === requestedArea));
+    const areaId = existingArea?.localId ?? requestedArea?.split('::area::').at(-1) ?? `${authoringSlug(request.question).slice(0, 36) || 'metadata'}_models`;
+    const operations = [];
+    if (!existingArea) {
+        operations.push({
+            id: `area:${domain}:${areaId}`,
+            kind: 'modeling_change',
+            evidence: [`domain:${domain}`],
+            change: { operation: 'upsert_area', value: { id: areaId, domain, name: titleCaseAuthoring(areaId), description: `Metadata-backed modeling area requested by the author: ${request.question.trim()}`, intentExamples: [request.question.trim()] } },
+        });
+    }
+    const bound = new Set(Object.values(modeling.entities).map((entity) => entity.dbtUniqueId));
+    const tokens = authoringTokens(request.question);
+    let candidates = Object.values(manifest.dbtProvenance.nodes).filter((node) => !bound.has(node.uniqueId));
+    const matched = candidates.filter((node) => tokens.some((token) => `${node.name} ${node.uniqueId} ${node.sourcePath ?? ''}`.toLowerCase().includes(token)));
+    if (matched.length)
+        candidates = matched;
+    candidates = candidates.slice(0, 12);
+    if (candidates.length === 0)
+        throw new Error('No unbound dbt models match this request. Focus an existing model to update its business context.');
+    const usedIds = new Set(Object.values(modeling.entities).filter((entity) => entity.domain === domain).map((entity) => entity.localId));
+    for (const node of candidates) {
+        const base = authoringSlug(node.name).replace(/-/g, '_') || 'model';
+        let id = base;
+        let suffix = 2;
+        while (usedIds.has(id))
+            id = `${base}_${suffix++}`;
+        usedIds.add(id);
+        operations.push({
+            id: `entity:${domain}:${id}`,
+            kind: 'modeling_change',
+            dependsOn: existingArea ? [] : [`area:${domain}:${areaId}`],
+            evidence: [node.uniqueId, ...(node.sourcePath ? [node.sourcePath] : [])],
+            change: { operation: 'upsert_entity', value: { id, domain, areaId, dbtModel: node.uniqueId, businessName: titleCaseAuthoring(node.name), status: 'draft', analyticalRole: 'unknown' } },
+        });
+    }
+    if (/\b(connect|relationship|join|related)\b/i.test(request.question) && candidates.length >= 2) {
+        const manifestPath = resolveDbtManifestPath(projectRoot);
+        const left = manifestPath ? loadDbtNodeAuthoringDetail(manifestPath, candidates[0].uniqueId) : undefined;
+        const right = manifestPath ? loadDbtNodeAuthoringDetail(manifestPath, candidates[1].uniqueId) : undefined;
+        const rightColumns = new Set((right?.columns ?? []).map((column) => column.name.toLowerCase()));
+        const sharedKey = (left?.columns ?? []).map((column) => column.name).find((name) => /(^id$|_id$)/i.test(name) && rightColumns.has(name.toLowerCase()));
+        if (sharedKey) {
+            const fromOperation = operations.find((operation) => operation.id.startsWith('entity:') && operation.kind === 'modeling_change' && operation.change.operation === 'upsert_entity' && operation.change.value.dbtModel === candidates[0].uniqueId);
+            const toOperation = operations.find((operation) => operation.id.startsWith('entity:') && operation.kind === 'modeling_change' && operation.change.operation === 'upsert_entity' && operation.change.value.dbtModel === candidates[1].uniqueId);
+            if (fromOperation?.kind === 'modeling_change' && fromOperation.change.operation === 'upsert_entity' && toOperation?.kind === 'modeling_change' && toOperation.change.operation === 'upsert_entity') {
+                const relationshipId = `${fromOperation.change.value.id}_to_${toOperation.change.value.id}`;
+                operations.push({
+                    id: `relationship:${domain}:${relationshipId}`,
+                    kind: 'modeling_change',
+                    dependsOn: [fromOperation.id, toOperation.id],
+                    evidence: [`shared column suggestion:${sharedKey}`, left?.uniqueId ?? '', right?.uniqueId ?? ''].filter(Boolean),
+                    change: { operation: 'upsert_relationship', value: { id: relationshipId, domain, areaId, from: fromOperation.change.value.id, to: toOperation.change.value.id, keys: [{ from: sharedKey, to: sharedKey }], cardinality: 'unknown', fanout: 'unknown', status: 'draft', rationale: 'Candidate only: shared dbt column name requires warehouse validation.' } },
+                });
+            }
+        }
+    }
+    return operations;
+}
+function buildMetadataBoundSkillOperations(projectRoot, manifest, request) {
+    const context = request.workspaceContext ?? {};
+    const selectedIdentity = request.selectedObject?.kind === 'skill' ? request.selectedObject.id : undefined;
+    const existing = selectedIdentity
+        ? loadSkills(projectRoot).skills.find((skill) => skill.qualifiedId === selectedIdentity || skill.id === selectedIdentity)
+        : undefined;
+    const domain = typeof context.domain === 'string'
+        ? context.domain
+        : existing?.domain
+            ?? (request.selectedObject?.kind === 'domain' ? request.selectedObject.id : undefined)
+            ?? Object.keys(manifest.modeling?.packages ?? {})[0];
+    if (!domain)
+        throw new Error('Select a Domain before building a Skill with AI.');
+    const area = typeof context.modelAreaId === 'string' ? context.modelAreaId : existing?.modelAreaRefs?.[0];
+    const focusReference = request.selectedObject?.kind === 'model' || request.selectedObject?.kind === 'relationship'
+        ? request.selectedObject.id
+        : undefined;
+    if (focusReference && !contextSourceReferenceExists(manifest, focusReference))
+        throw new Error('The focused modeling object is not present in the current snapshot.');
+    const id = existing?.localId ?? existing?.id ?? `${authoringSlug(request.question).slice(0, 48) || domain.replace(/[^a-z0-9]+/gi, '-')}-guidance`;
+    const body = existing
+        ? `${existing.body.trim()}\n\n## Proposed correction\n${request.question.trim()}\n`
+        : `## Purpose\nGuide analysis for ${domain} using reviewed repository metadata.\n\n## Guardrails\n${request.question.trim()}\n\n## Clarify\nAsk when the requested metric, model, or relationship is not governed.`;
+    const value = {
+        id,
+        qualifiedId: existing?.qualifiedId,
+        sourcePath: existing?.sourcePath,
+        scope: 'project',
+        domain,
+        domains: [domain],
+        modelAreaRefs: area ? [area] : [],
+        kind: existing?.kind ?? 'domain_reference',
+        status: 'draft',
+        owner: existing?.owner,
+        triggers: existing?.triggers ?? authoringTokens(request.question).slice(0, 8),
+        exclusions: existing?.exclusions ?? [],
+        description: existing?.description ?? `Metadata-backed guidance for ${titleCaseAuthoring(domain)}.`,
+        preferredMetrics: existing?.preferredMetrics ?? Object.values(manifest.metrics ?? {}).filter((metric) => metric.domain === domain).slice(0, 12).map((metric) => metric.name),
+        preferredBlocks: existing?.preferredBlocks ?? Object.values(manifest.blocks ?? {}).filter((block) => block.domain === domain && block.status === 'certified').slice(0, 12).map((block) => block.name),
+        preferredDimensions: existing?.preferredDimensions ?? [],
+        requiredFilters: existing?.requiredFilters ?? [],
+        clarifyWhen: existing?.clarifyWhen ?? ['The request needs a model, metric, or relationship not present in the current governed context.'],
+        examples: existing?.examples ?? [request.question.trim()],
+        sourceRefs: [...new Set([...(existing?.sourceRefs ?? []), ...(focusReference ? [focusReference] : [])])],
+        vocabulary: existing?.vocabulary ?? {},
+        analyticalPolicy: existing?.analyticalPolicy,
+        body,
+        isStarter: existing?.isStarter,
+    };
+    const before = existing?.sourcePath && existsSync(existing.sourcePath) ? readFileSync(existing.sourcePath, 'utf8') : '';
+    return [{
+            id: `skill:${existing?.qualifiedId ?? `${domain}::skill::${id}`}`,
+            kind: 'skill_change',
+            operation: existing ? 'update' : 'create',
+            targetQualifiedId: existing?.qualifiedId,
+            expectedSourceHash: existing ? createHash('sha256').update(before).digest('hex') : undefined,
+            evidence: [existing?.sourcePath ?? `domain:${domain}`, ...(focusReference ? [focusReference] : [])],
+            value,
+        }];
+}
+function authoringTokens(value) {
+    const stop = new Set(['the', 'and', 'for', 'with', 'from', 'this', 'that', 'build', 'create', 'model', 'models', 'skill', 'please', 'into', 'about']);
+    return [...new Set(value.toLowerCase().split(/[^a-z0-9_]+/).filter((token) => token.length > 2 && !stop.has(token)))];
+}
+function authoringSlug(value) {
+    return value.toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+function titleCaseAuthoring(value) {
+    return value.replace(/[._-]+/g, ' ').replace(/\b\w/g, (letter) => letter.toUpperCase());
+}
 function contextBootstrapDir(projectRoot) {
     return join(projectRoot, '.dql', 'local', 'context-bootstrap');
 }
@@ -17157,6 +19351,11 @@ export function notebookCellRepairSql(cell) {
     const match = /\bquery\s*=\s*"""([\s\S]*?)"""/i.exec(cell.source);
     return match?.[1]?.trim() || undefined;
 }
+export function notebookDqlSourceAllowsBackgroundRepair(source) {
+    if (/^\s*@block\(/i.test(source) || /\btype\s*=\s*"semantic"/i.test(source))
+        return false;
+    return /\bblock\b/i.test(source) && /\bquery\b/i.test(source);
+}
 export function replaceNotebookDqlQueryForRepair(source, sql) {
     const queryField = /\b(query\s*=\s*""")([\s\S]*?)(""")/i;
     if (!queryField.test(source) || !sql.trim())
@@ -17618,6 +19817,7 @@ export function openBlockStudioDocument(projectRoot, relativePath, semanticLayer
         owner: parsedMetadata.owner || companion?.owner || '',
         tags: parsedMetadata.tags.length > 0 ? parsedMetadata.tags : companion?.tags ?? [],
         reviewStatus: parsedMetadata.status || companion?.reviewStatus || 'draft',
+        sourceFingerprint: createHash('sha256').update(source).digest('hex'),
     };
     return {
         path: normalizedPath,
@@ -17627,6 +19827,22 @@ export function openBlockStudioDocument(projectRoot, relativePath, semanticLayer
         validation: validateBlockStudioSource(source, semanticLayer),
     };
 }
+const BLOCK_STUDIO_DRAFT_RUNTIME_DIAGNOSTICS = new Set([
+    'metricflow_unavailable',
+    'semantic_compose_failed',
+    'semantic_layer_missing',
+    'semantic_runtime_required',
+]);
+/**
+ * Draft persistence is stricter than loose text storage but does not require a
+ * configured execution runtime. Syntax, unsafe SQL, invalid semantic identity,
+ * and parameter-contract errors must be corrected before a block file is
+ * written; runtime availability remains a Run/Certify concern.
+ */
+export function blockStudioValidationAllowsDraftSave(validation) {
+    return !validation.diagnostics.some((diagnostic) => diagnostic.severity === 'error'
+        && !BLOCK_STUDIO_DRAFT_RUNTIME_DIAGNOSTICS.has(diagnostic.code ?? ''));
+}
 /**
  * Replace the CONTENTS of every string literal with same-length filler, keeping
  * the quotes and every offset intact.
@@ -18234,17 +20450,33 @@ export function validateBlockStudioSource(source, semanticLayer) {
             });
         }
     }
-    const parameterInvocation = prepareBlockInvocation({ source, surface: 'block_studio' });
-    if (parameterInvocation.errors.length > 0) {
-        diagnostics.push(...parameterInvocation.errors.map((message) => ({ severity: 'error', code: 'parameter_parse', message })));
+    let parameters = [];
+    try {
+        const parameterInvocation = prepareBlockInvocation({ source, surface: 'block_studio' });
+        parameters = parameterInvocation.parameters;
+        if (parameterInvocation.errors.length > 0) {
+            diagnostics.push(...parameterInvocation.errors.map((message) => ({ severity: 'error', code: 'parameter_parse', message })));
+        }
+    }
+    catch (error) {
+        // The main parser diagnostic above owns malformed source. Parameter
+        // extraction must never turn a recoverable validation response into a 500.
+        if (!diagnostics.some((diagnostic) => diagnostic.code === 'syntax')) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'parameter_parse',
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
     }
     return {
         valid: diagnostics.every((diagnostic) => diagnostic.severity !== 'error'),
+        saveable: blockStudioValidationAllowsDraftSave({ diagnostics }),
         diagnostics,
         semanticRefs,
         chartConfig: chartConfig ?? undefined,
         executableSql,
-        parameters: parameterInvocation.parameters,
+        parameters,
     };
 }
 export async function createDqlArtifactGenerationSessionForProject(projectRoot, options, semanticLayer) {
@@ -19182,6 +21414,45 @@ function formatBlockStudioExpected(expected) {
         return String(normalized);
     return JSON.stringify(normalized);
 }
+function evaluateBlockStudioTests(tests, rows, columns, startedAt) {
+    if (tests.length === 0) {
+        return { passed: 0, failed: 0, skipped: 0, duration: Date.now() - startedAt, assertions: [], runAt: new Date() };
+    }
+    const assertions = [];
+    let passed = 0;
+    let failed = 0;
+    for (const test of tests) {
+        const name = `assert ${test.field} ${test.operator} ${formatBlockStudioExpected(test.expected)}`;
+        let actual;
+        if (test.field === 'row_count') {
+            actual = rows.length;
+        }
+        else if (!columns.includes(test.field)) {
+            assertions.push({ name, passed: false, expected: test.expected, error: `Column '${test.field}' not found in results` });
+            failed += 1;
+            continue;
+        }
+        else {
+            actual = rows[0]?.[test.field];
+        }
+        const ok = compareBlockStudioValues(actual, test.operator, test.expected);
+        if (ok) {
+            assertions.push({ name, passed: true, actual, expected: test.expected });
+            passed += 1;
+        }
+        else {
+            assertions.push({
+                name,
+                passed: false,
+                actual,
+                expected: test.expected,
+                error: `${String(actual)} ${test.operator} ${formatBlockStudioExpected(test.expected)} is false`,
+            });
+            failed += 1;
+        }
+    }
+    return { passed, failed, skipped: 0, duration: Date.now() - startedAt, assertions, runAt: new Date() };
+}
 function buildBlockStudioCertificationChecklist(input) {
     const parsed = parseBlockSourceMetadata(input.source);
     const sql = extractBlockStudioSql(input.source) ?? '';
@@ -24272,6 +26543,46 @@ function mergeAgentSchemaContexts(...contexts) {
     }
     return Array.from(byRelation.values()).slice(0, 16);
 }
+function agentRelationMatchKey(relation) {
+    return relation
+        .replace(/["`\[\]]/g, '')
+        .split('.')
+        .filter(Boolean)
+        .slice(-2)
+        .join('.')
+        .toLowerCase();
+}
+/**
+ * Keep dbt descriptions and semantic meaning, but make a complete live point
+ * lookup authoritative for executable column names on the selected connection.
+ * No fuzzy aliases are invented: a stale `customer_name` declaration disappears
+ * when the live relation exposes only `name`.
+ */
+export function reconcileAgentSchemaContextWithLive(catalog, live) {
+    const liveByRelation = new Map(live
+        .filter((table) => table.columns.length > 0)
+        .map((table) => [agentRelationMatchKey(table.relation), table]));
+    return catalog.map((table) => {
+        const verified = liveByRelation.get(agentRelationMatchKey(table.relation));
+        if (!verified)
+            return table;
+        const metadataColumns = new Map(table.columns.map((column) => [column.name.toLowerCase(), column]));
+        return {
+            ...table,
+            source: 'dbt metadata verified against live runtime schema',
+            columnCompleteness: 'complete',
+            columns: verified.columns.map((column) => {
+                const metadata = metadataColumns.get(column.name.toLowerCase());
+                return {
+                    ...column,
+                    type: column.type ?? metadata?.type,
+                    description: metadata?.description,
+                    sampleValues: metadata?.sampleValues,
+                };
+            }),
+        };
+    });
+}
 function mergeAgentSchemaSampleValues(snapshot, enriched) {
     const samples = new Map();
     for (const table of enriched) {