@duckcodeailabs/dql-cli 1.12.9 → 1.12.11

package/dist/local-runtime.js

@@ -21,7 +21,7 @@ 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, 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, 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, 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';
@@ -403,6 +403,36 @@ export function analyticalFailedRunFromAgentRun(run) {
     }
     return undefined;
 }
+/** Exact failed statement retained on an immutable run, if one exists. */
+export function repairableSqlFromAgentRun(run) {
+    for (const artifact of run.artifacts) {
+        const payload = agentRunRecord(artifact.payload);
+        if (!payload)
+            continue;
+        const dqlArtifact = normalizeDqlArtifactReference(payload.dqlArtifact);
+        const sql = agentRunString(payload.proposedSql)
+            ?? agentRunString(payload.sql)
+            ?? dqlArtifact?.compiledSql;
+        if (sql?.trim())
+            return sql.trim();
+    }
+    return undefined;
+}
+/** Structured producer failure retained on the source run. */
+export function warehouseFailureFromAgentRun(run) {
+    for (const artifact of run.artifacts) {
+        const payload = agentRunRecord(artifact.payload);
+        const failure = agentRunRecord(payload?.warehouseFailure);
+        if (failure?.version !== 1 || typeof failure.redactedMessage !== 'string')
+            continue;
+        return failure;
+    }
+    return undefined;
+}
+/** Permission, authentication, policy and unsafe-query failures are never AI-repaired. */
+export function analyticalFailureAllowsDeterministicRetry(failure) {
+    return !failure || !['permission', 'authentication', 'unsafe', 'cancelled'].includes(failure.category);
+}
 function businessNarrativeGaps(warnings) {
     const businessRelevant = (warnings ?? []).filter((warning) => !(/missing requested output column/i.test(warning)
         || /\bquery plan\b/i.test(warning)
@@ -1996,6 +2026,7 @@ export async function startLocalServer(opts) {
                     sql: exploration.sql,
                     exploratoryCandidate: repairedExploratoryCandidate,
                     executionError: exploration.error,
+                    warehouseFailure: exploration.warehouseFailure,
                     text: explorationAnswer,
                     answer: explorationAnswer,
                     trustLabel: 'Exploratory · DBT-grounded',
@@ -3242,10 +3273,21 @@ export async function startLocalServer(opts) {
             const semanticError = semanticCompose?.diagnostics.find((diagnostic) => diagnostic.severity === 'error')?.message;
             throw analyticalError(semanticError ?? `DQL artifact "${metadata.name ?? 'draft'}" produced no executable SQL.`, { origin: 'dql_compilation', stage: 'compile' });
         }
-        const prepared = prepareLocalExecution(semanticCompose?.sql ?? plan.sql, activeConnection, projectRoot, projectConfig);
-        const executionSql = invocationInput?.rowLimit
-            ? buildAgentPreviewSql(prepared.sql, invocationInput.rowLimit)
-            : prepared.sql;
+        const preparation = await prepareAnalyticalExecutionSql({
+            sql: semanticCompose?.sql ?? plan.sql,
+            subject: 'DQL artifact query',
+            executor,
+            connection: activeConnection,
+            projectRoot,
+            projectConfig,
+            // Preserve the existing contract: previewed Ask artifacts are explicitly
+            // read-only and bounded; saved/manual DQL execution keeps its compiler-
+            // governed behavior when no preview bound was requested.
+            enforceReadOnly: invocationInput?.rowLimit !== undefined,
+            rowLimit: invocationInput?.rowLimit,
+        });
+        const prepared = { sql: preparation.preparedSql, connection: preparation.connection };
+        const executionSql = preparation.executedSql;
         const app = loadRuntimeApp(projectRoot, activePersonaAppId());
         const sourceDomain = metadata.domain ?? source.match(/\bdomain\s*=\s*"([^"]+)"/i)?.[1];
         assertAppAccess({ app, domain: sourceDomain ?? app?.domain, level: 'execute' });
@@ -3432,7 +3474,7 @@ export async function startLocalServer(opts) {
      * string, so the only remaining reasons to differ are the connection and the
      * governance gates, both of which report themselves honestly.
      */
-    const executeGeneratedSqlDirect = async (question, sql, seed, executionConnection) => {
+    const executeGeneratedSqlDirect = async (question, sql, seed, executionConnection, bindings) => {
         const activeConnection = requireActiveConnection(executionConnection);
         const rowBound = clampAnalyticalRowBound(seed?.limit ?? 200);
         const trimmed = sql.trim().replace(/;\s*$/, '').trim();
@@ -3454,13 +3496,18 @@ export async function startLocalServer(opts) {
         if (semantic.unresolvedRefs.length > 0) {
             throw analyticalError(`Unknown semantic reference${semantic.unresolvedRefs.length > 1 ? 's' : ''}: ${semantic.unresolvedRefs.join(', ')}`, { origin: 'dql_compilation', stage: 'compile', code: 'semantic_ref' });
         }
-        const prepared = prepareLocalExecution(semantic.sql, activeConnection, projectRoot, projectConfig);
-        // Read-only enforcement runs on the statement that will ACTUALLY execute.
-        const readOnlyError = readOnlySqlValidationError(prepared.sql, 'Generated SQL', activeConnection.driver);
-        if (readOnlyError) {
-            throw analyticalError(readOnlyError, { origin: 'governance_gate', stage: 'validation', code: 'unsafe_sql' });
-        }
-        const bounded = buildRowBoundedSql(prepared.sql, rowBound, activeConnection.driver);
+        const preparation = await prepareAnalyticalExecutionSql({
+            sql: semantic.sql,
+            subject: 'Generated SQL',
+            executor,
+            connection: activeConnection,
+            projectRoot,
+            projectConfig,
+            enforceReadOnly: true,
+            rowLimit: rowBound,
+        });
+        const prepared = { sql: preparation.preparedSql, connection: preparation.connection };
+        const bounded = preparation.rowBound;
         const app = loadRuntimeApp(projectRoot, activePersonaAppId());
         // Generated SQL is governed as 'uncategorized' unless its seed declares a
         // domain — the same value `generatedSqlArtifactContract` stamps into the
@@ -3488,7 +3535,7 @@ export async function startLocalServer(opts) {
             })
             : null;
         const rawResult = semanticExecution?.result
-            ?? await executor.executeQuery(bounded.sql, [], runtimeVariables({}), prepared.connection);
+            ?? await executor.executeQuery(preparation.executedSql, bindings?.sqlParams ?? [], runtimeVariables(bindings?.variables ?? {}), preparation.connection);
         const normalized = normalizeQueryResult(rawResult, semantic.semanticRefs);
         // The authoritative bound. `buildRowBoundedSql` may legitimately decline to
         // touch the statement, and only one of 15 drivers honours a maxRows hint, so
@@ -3528,34 +3575,65 @@ export async function startLocalServer(opts) {
      */
     const executeExploratoryCandidate = async (candidate, schemaContext = [], question = '', requestedTopN, executionConnection) => {
         const activeConnection = requireActiveConnection(executionConnection);
-        const preflight = repairExploratorySqlBeforeExecution(candidate.sql, schemaContext, question, activeConnection.driver);
+        const failed = (message, sql, repairs, proofs = [], code = 'exploratory_validation_failed') => ({
+            proofs,
+            sql,
+            repairs,
+            error: message,
+            warehouseFailure: normalizeWarehouseSqlFailure(analyticalError(message, {
+                origin: 'governance_gate',
+                stage: 'validation',
+                code,
+            }), activeConnection.driver),
+        });
+        let normalizedCandidateSql;
+        try {
+            normalizedCandidateSql = (await prepareAnalyticalExecutionSql({
+                sql: candidate.sql,
+                subject: question || 'this exploratory query',
+                executor,
+                connection: activeConnection,
+                projectRoot,
+                projectConfig,
+                enforceReadOnly: true,
+            })).preparedSql;
+        }
+        catch (error) {
+            const failure = normalizeWarehouseSqlFailure(error, activeConnection.driver);
+            return {
+                proofs: [],
+                sql: candidate.sql,
+                repairs: [],
+                error: failure.redactedMessage,
+                warehouseFailure: failure,
+            };
+        }
+        const preflight = repairExploratorySqlBeforeExecution(normalizedCandidateSql, schemaContext, question, activeConnection.driver);
         const boundedSql = applyRequestedTopNToExploratorySql(preflight.sql, requestedTopN);
         const repairs = boundedSql === preflight.sql
             ? [...preflight.repairs]
             : [...preflight.repairs, `Applied the requested overall top-${requestedTopN} bound before exploratory execution.`];
         if (preflight.blockedReason) {
-            return {
-                proofs: [],
-                sql: boundedSql,
-                repairs,
-                error: preflight.blockedReason,
-            };
+            return failed(preflight.blockedReason, boundedSql, repairs, [], 'exploratory_preflight_blocked');
         }
         const analysis = analyzeSqlReferences(boundedSql, activeConnection.driver);
+        if (!analysis.parsed && sqlMayContainJoin(boundedSql)) {
+            return failed('DQL could not parse the exploratory SQL to validate its join predicates. Nothing was sent to the warehouse.', boundedSql, repairs, [], 'exploratory_join_parse_failed');
+        }
         if (!analysis.parsed) {
-            return { proofs: [], sql: boundedSql, repairs, error: 'DQL could not parse the exploratory SQL to validate its join predicates.' };
+            repairs.push('The local DQL parser could not inspect this join-free statement; warehouse read-only execution will provide the authoritative syntax check.');
         }
-        const probeableJoins = probeableExploratoryJoins(analysis.joins, analysis.ctes, analysis.derivedRelations);
+        const probeableJoins = probeableExploratoryJoins(analysis.parsed ? analysis.joins : [], analysis.parsed ? analysis.ctes : [], analysis.parsed ? analysis.derivedRelations : []);
         // A normal customer → order → order-item → product question needs three
         // joins. Keep the lane bounded, but do not reject this common dbt-star path
         // solely because the old two-join demo limit was too small. CTE-internal
         // joins are counted physically (they appear in analysis.joins with their
         // physical endpoints); joins ON a CTE are restructuring, not new paths.
         if (probeableJoins.length > 4) {
-            return { proofs: [], sql: boundedSql, repairs, error: 'This exploratory query has more than four joins and requires an analyst to review the relationship path.' };
+            return failed('This exploratory query has more than four joins and requires an analyst to review the relationship path.', boundedSql, repairs, [], 'exploratory_join_limit');
         }
         if (probeableJoins.some((join) => !join.leftRelation || !join.rightRelation)) {
-            return { proofs: [], sql: boundedSql, repairs, error: 'This exploratory query has a join endpoint DQL could not resolve for bounded validation.' };
+            return failed('This exploratory query has a join endpoint DQL could not resolve for bounded validation.', boundedSql, repairs, [], 'exploratory_join_unresolved');
         }
         // Structural binding: when the candidate carries a declared draft join path,
         // every SQL join must ride one of its edges on the declared key pair. A join
@@ -3568,22 +3646,12 @@ export async function startLocalServer(opts) {
                 const edge = declaredEdges.find((value) => declaredExploratoryRelationMatches(join.leftRelation, value.fromRelation) && declaredExploratoryRelationMatches(join.rightRelation, value.toRelation)
                     || declaredExploratoryRelationMatches(join.leftRelation, value.toRelation) && declaredExploratoryRelationMatches(join.rightRelation, value.fromRelation));
                 if (!edge) {
-                    return {
-                        proofs: [],
-                        sql: boundedSql,
-                        repairs,
-                        error: `The join between ${join.leftRelation} and ${join.rightRelation} is not part of the declared relationship path, so DQL did not execute it. Declare the relationship in the DQL model to enable it.`,
-                    };
+                    return failed(`The join between ${join.leftRelation} and ${join.rightRelation} is not part of the declared relationship path, so DQL did not execute it. Declare the relationship in the DQL model to enable it.`, boundedSql, repairs, [], 'undeclared_relationship');
                 }
                 const keyMatches = edge.keys.some((key) => exploratoryColumnsMatch(join.leftColumn, key.from) && exploratoryColumnsMatch(join.rightColumn, key.to)
                     || exploratoryColumnsMatch(join.leftColumn, key.to) && exploratoryColumnsMatch(join.rightColumn, key.from));
                 if (!keyMatches) {
-                    return {
-                        proofs: [],
-                        sql: boundedSql,
-                        repairs,
-                        error: `The join ${join.leftColumn} = ${join.rightColumn} uses different keys than relationship "${edge.relationshipId}" declares (${edge.keys.map((key) => `${key.from}=${key.to}`).join(', ')}). Review the declared keys before executing.`,
-                    };
+                    return failed(`The join ${join.leftColumn} = ${join.rightColumn} uses different keys than relationship "${edge.relationshipId}" declares (${edge.keys.map((key) => `${key.from}=${key.to}`).join(', ')}). Review the declared keys before executing.`, boundedSql, repairs, [], 'relationship_key_mismatch');
                 }
                 joinEdges.set(index, edge);
             }
@@ -3594,7 +3662,7 @@ export async function startLocalServer(opts) {
                 }
             }
         }
-        if (probeableJoins.length < analysis.joins.length) {
+        if (analysis.parsed && probeableJoins.length < analysis.joins.length) {
             repairs.push(`Skipped join probes for ${analysis.joins.length - probeableJoins.length} join(s) on derived (CTE) relations; the final query execution validates them.`);
         }
         const proofs = [];
@@ -3615,14 +3683,21 @@ export async function startLocalServer(opts) {
                 // answer — these gates only inspect the raw key samples.
                 const contradiction = exploratoryProbeContradiction(raw.rows, join, joinEdges.get(index));
                 if (contradiction) {
-                    return { proofs, sql: boundedSql, repairs, error: contradiction };
+                    return failed(contradiction, boundedSql, repairs, proofs, 'relationship_probe_contradiction');
                 }
             }
             const result = await executeGeneratedArtifactForAgent(question, boundedSql, undefined, activeConnection);
             return { result, proofs, sql: boundedSql, repairs };
         }
         catch (error) {
-            return { proofs, sql: boundedSql, repairs, error: error instanceof Error ? error.message : String(error) };
+            const failure = normalizeWarehouseSqlFailure(error, activeConnection.driver);
+            return {
+                proofs,
+                sql: boundedSql,
+                repairs,
+                error: failure.redactedMessage,
+                warehouseFailure: failure,
+            };
         }
     };
     /**
@@ -3728,6 +3803,115 @@ export async function startLocalServer(opts) {
             return [];
         }
     };
+    const boundedRepairError = (message, status, warehouseFailure) => Object.assign(new Error(message), { status, ...(warehouseFailure ? { warehouseFailure } : {}) });
+    /**
+     * Shared one-attempt SQL repair for Ask and Notebook. It never creates a
+     * conversation, writes a DQL file, changes targets, or promotes trust.
+     */
+    const executeBoundedSqlRepair = async (input) => {
+        let result;
+        let repairedSql = input.sourceSql;
+        let repairMode = 'deterministic';
+        let firstFailure;
+        try {
+            result = await executeGeneratedSqlDirect(input.question, input.sourceSql, undefined, input.targetConnection, { sqlParams: input.sqlParams, variables: input.variables });
+        }
+        catch (error) {
+            firstFailure = normalizeWarehouseSqlFailure(error, input.targetConnection.driver);
+        }
+        if (!result) {
+            if (firstFailure?.retryDisposition !== 'model_repair') {
+                throw boundedRepairError(firstFailure?.redactedMessage ?? 'The deterministic repair did not produce an executable query.', 422, firstFailure);
+            }
+            const provider = await createBlockStudioAssistProvider(projectRoot);
+            if (!provider) {
+                throw boundedRepairError('Configure an available AI provider in Settings to repair this query.', 409);
+            }
+            let schemaContext;
+            try {
+                schemaContext = await getSchemaContextForAgent(input.question, 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 failed read-only analytical SQL statement.',
+                            'Return exactly one JSON object in a ```json fence with keys summary, sql, viz, outputs.',
+                            'Preserve the requested grain, filters, output columns, and aggregation semantics.',
+                            input.sqlParams?.length
+                                ? 'Preserve every positional parameter placeholder exactly; do not add, remove, or renumber placeholders.'
+                                : '',
+                            'Use only relations and columns present in the supplied schema context.',
+                            'Never emit internal DQL relation identities such as source::, model::, seed::, or snapshot::.',
+                            'Do not add writes, DDL, multiple statements, or commentary outside the JSON fence.',
+                        ].join(' '),
+                    },
+                    {
+                        role: 'user',
+                        content: JSON.stringify({
+                            question: input.question,
+                            driver: input.targetConnection.driver,
+                            failure: firstFailure.redactedMessage,
+                            sql: input.sourceSql,
+                            parameters: input.sqlParams?.map((parameter) => ({
+                                name: parameter.name,
+                                placeholder: `$${parameter.position}`,
+                            })),
+                            schema: boundedSchema,
+                        }),
+                    },
+                ], { maxTokens: 1200, temperature: 0 });
+            }
+            catch {
+                throw boundedRepairError('The AI provider could not complete this repair. Check Provider Settings and retry.', 502);
+            }
+            const proposal = parseProposal(raw);
+            if (!proposal.sql?.trim()) {
+                throw boundedRepairError('The AI repair did not return an executable SQL statement.', 422);
+            }
+            repairedSql = proposal.sql.trim();
+            const requiredPlaceholders = (input.sqlParams ?? []).map((parameter) => `$${parameter.position}`);
+            if (requiredPlaceholders.some((placeholder) => !new RegExp(`${placeholder.replace('$', '\\$')}\\b`).test(repairedSql))) {
+                throw boundedRepairError('The repair changed this cell\'s parameter contract, so DQL stopped it before execution.', 422);
+            }
+            repairMode = 'ai';
+            try {
+                result = await executeGeneratedSqlDirect(input.question, repairedSql, undefined, input.targetConnection, { sqlParams: input.sqlParams, variables: input.variables });
+            }
+            catch (error) {
+                const failure = normalizeWarehouseSqlFailure(error, input.targetConnection.driver);
+                throw boundedRepairError(failure.redactedMessage, 422, failure);
+            }
+        }
+        // Keep preview-only row bounds out of editable notebook source. The one
+        // deterministic source rewrite we do persist is decoding internal graph
+        // identities, because those can never execute as warehouse SQL.
+        let rewrites = [];
+        if (internalRelationIdsInSql(repairedSql).length > 0) {
+            const normalizedSource = await prepareAnalyticalExecutionSql({
+                sql: repairedSql,
+                subject: 'Repaired SQL',
+                executor,
+                connection: input.targetConnection,
+                projectRoot,
+                projectConfig,
+                enforceReadOnly: true,
+            });
+            repairedSql = normalizedSource.decodedSql;
+            rewrites = normalizedSource.rewrites;
+        }
+        return { result, repairedSql, repairMode, firstFailure, rewrites };
+    };
     const generateInvestigationSqlForApp = async (input) => {
         const governed = resolveGovernedAnswerRunner(projectRoot);
         const resolvedProvider = governed?.provider ?? null;
@@ -4784,9 +4968,10 @@ export async function startLocalServer(opts) {
      */
     const MIN_COMPRESS_BYTES = 1024;
     const COMPRESSIBLE = /^(?:text\/(?!event-stream)|application\/(?:json|javascript|xml|wasm)|image\/svg)/i;
-    const withCompression = (request, response) => {
+    const withCompression = (request, rawResponse) => {
+        const response = rawResponse;
         if (!/\bgzip\b/i.test(String(request.headers['accept-encoding'] ?? '')))
-            return response;
+            return rawResponse;
         const writeHead = response.writeHead.bind(response);
         const end = response.end.bind(response);
         const write = response.write.bind(response);
@@ -4857,7 +5042,7 @@ export async function startLocalServer(opts) {
             });
             return end(gz);
         });
-        return response;
+        return rawResponse;
     };
     const server = createServer((req, res) => {
         res = withCompression(req, res);
@@ -5517,15 +5702,79 @@ export async function startLocalServer(opts) {
             }
             if (req.method === 'GET' && path === '/api/modeling/dbt-first/inventory') {
                 const requestId = apiRequestId('modeling-inventory');
-                const snapshot = projectSnapshot();
+                const physicalOnly = url.searchParams.get('physicalOnly') === 'true';
+                const modelingEnabled = projectConfig.manifestVersion === 3 && projectConfig.modeling?.mode === 'dbt-first';
+                if (physicalOnly && !modelingEnabled) {
+                    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(apiErrorEnvelope({
+                        requestId,
+                        code: 'DBT_FIRST_NOT_ENABLED',
+                        message: 'dbt-first modeling is not enabled. Connect and apply a dbt project from Settings → Project & dbt.',
+                        nextActions: ['Open Settings → Project & dbt and apply a valid dbt project.'],
+                    })));
+                    return;
+                }
+                const dbtProjectDir = findDbtProjectPath(projectRoot, projectConfig);
+                const configuredManifestPath = projectConfig.dbt?.manifestPath ?? 'target/manifest.json';
+                const expectedManifestPath = resolve(dbtProjectDir, configuredManifestPath);
+                if (physicalOnly && !existsSync(expectedManifestPath)) {
+                    res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(apiErrorEnvelope({
+                        requestId,
+                        code: 'DBT_MANIFEST_NOT_FOUND',
+                        message: `The configured dbt manifest was not found at ${configuredManifestPath}.`,
+                        details: { manifestPath: configuredManifestPath },
+                        nextActions: ['Run dbt parse, dbt compile, or dbt build, then refresh the database catalog.'],
+                    })));
+                    return;
+                }
+                let snapshot;
+                if (physicalOnly) {
+                    try {
+                        snapshot = projectSnapshot();
+                    }
+                    catch (error) {
+                        res.writeHead(422, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON(apiErrorEnvelope({
+                            requestId,
+                            code: 'DBT_MANIFEST_COMPILE_FAILED',
+                            message: apiErrorMessage(error),
+                            details: { manifestPath: configuredManifestPath },
+                            nextActions: ['Fix or rebuild the dbt manifest, then refresh the database catalog.'],
+                        })));
+                        return;
+                    }
+                }
+                else {
+                    snapshot = projectSnapshot();
+                }
                 const manifest = snapshot.manifest;
-                const limit = Math.min(200, Math.max(1, Number(url.searchParams.get('limit')) || 50));
+                if (physicalOnly && (manifest.manifestVersion !== 3 || !manifest.modeling || !manifest.dbtProvenance)) {
+                    res.writeHead(422, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(apiErrorEnvelope({
+                        requestId,
+                        snapshotId: snapshot.snapshotId,
+                        code: 'DBT_MANIFEST_COMPILE_FAILED',
+                        message: snapshot.error ?? 'DQL could not compile the dbt database catalog.',
+                        details: { manifestPath: configuredManifestPath },
+                        nextActions: ['Review the dbt artifact, rebuild it, then refresh the database catalog.'],
+                    })));
+                    return;
+                }
+                // PERF-001 / CTX-005: only the Database browser opts into the smaller,
+                // physical-relation contract. Existing modeling consumers retain their
+                // original inventory scope and pagination defaults.
+                const maxLimit = physicalOnly ? 100 : 200;
+                const defaultLimit = physicalOnly ? 25 : 50;
+                const limit = Math.min(maxLimit, Math.max(1, Number(url.searchParams.get('limit')) || defaultLimit));
                 const cursor = Math.max(0, Number(url.searchParams.get('cursor')) || 0);
                 const query = (url.searchParams.get('q') ?? '').trim().toLowerCase();
                 const queryTokens = query.split(/[^a-z0-9]+/).filter(Boolean);
                 const domain = (url.searchParams.get('domain') ?? '').trim();
                 const boundByDbtId = new Map(Object.values(manifest.modeling?.entities ?? {}).map((entity) => [entity.dbtUniqueId, entity]));
+                const physicalIds = physicalOnly ? physicalDbtRelationIds(expectedManifestPath) : undefined;
                 const nodes = Object.values(manifest.dbtProvenance?.nodes ?? {})
+                    .filter((node) => !physicalOnly || (Boolean(node.relation) && (!physicalIds || physicalIds.has(node.uniqueId))))
                     .filter((node) => {
                     if (!queryTokens.length)
                         return true;
@@ -5558,6 +5807,11 @@ export async function startLocalServer(opts) {
                     nextCursor: cursor + limit < nodes.length ? cursor + limit : null,
                     total: nodes.length,
                     snapshotId: snapshot.snapshotId,
+                    ...(physicalOnly ? {
+                        manifestPath: manifest.dbtProvenance.manifestPath,
+                        projectName: manifest.dbtProvenance.projectName,
+                        scope: 'dbt_relations',
+                    } : {}),
                 }));
                 return;
             }
@@ -5710,7 +5964,7 @@ export async function startLocalServer(opts) {
                     if (!body.expectedSnapshotId || body.expectedSnapshotId !== snapshot.snapshotId)
                         throw Object.assign(new Error('Project sources changed before relationship validation.'), { code: 'SOURCE_CHANGED' });
                     const manifest = snapshot.manifest;
-                    const activeConnection = requireActiveConnection();
+                    const activeConnection = await resolveExecutionConnection(body);
                     const evidence = await validateModelingRelationship(body.relationship, manifest, (sql) => executor.executeQuery(sql, [], {}, activeConnection), (identifier) => getDialect(activeConnection.driver).quoteIdentifier(identifier));
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ requestId, snapshotId: snapshot.snapshotId, evidence }));
@@ -5735,6 +5989,195 @@ export async function startLocalServer(opts) {
                 res.end(serializeJSON({ runs, total: agentRunStore.list().length, limit }));
                 return;
             }
+            /**
+             * One-click bounded execution repair.
+             *
+             * The source run is immutable. First, retry its exact SQL through the
+             * shared deterministic preparation boundary (this repairs internal IDs and
+             * dialect-safe row bounds without an LLM). Only a connector-classified
+             * model-repair failure may spend one provider call to rewrite the SQL. The
+             * derived SQL is still read-only, bounded, and executed on the source run's
+             * exact target before a replacement card is returned.
+             *
+             * Acceptance: API-003, API-007, UI-012, UI-013, SEC-004, E2E-014.
+             */
+            if (req.method === 'POST' && /^\/api\/agent-runs\/[^/]+\/repair-execution$/.test(path)) {
+                const match = path.match(/^\/api\/agent-runs\/([^/]+)\/repair-execution$/);
+                const sourceRunId = decodeURIComponent(match?.[1] ?? '');
+                const sourceRun = await agentRunStore.get(sourceRunId);
+                if (!sourceRun) {
+                    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Agent run not found.' }));
+                    return;
+                }
+                const derivedRunId = `${sourceRun.id}:repair:1`;
+                const existing = await agentRunStore.get(derivedRunId);
+                if (existing) {
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ run: existing }));
+                    return;
+                }
+                const sourceSql = repairableSqlFromAgentRun(sourceRun);
+                const retainedFailure = warehouseFailureFromAgentRun(sourceRun);
+                if (!sourceSql || !analyticalFailureAllowsDeterministicRetry(retainedFailure)) {
+                    res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        error: sourceSql
+                            ? 'This failure requires authorized access or a policy change and cannot be repaired by AI.'
+                            : 'This run has no retained SQL statement to repair.',
+                        ...(retainedFailure ? { warehouseFailure: retainedFailure } : {}),
+                    }));
+                    return;
+                }
+                const body = agentRunRecord(await readJSON(req).catch(() => null));
+                const threadId = agentRunString(body?.threadId);
+                let targetConnection;
+                try {
+                    targetConnection = await resolveAgentRunExecutionConnection({
+                        question: sourceRun.question,
+                        executionTarget: sourceRun.executionTarget,
+                    });
+                }
+                catch (error) {
+                    res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: apiErrorMessage(error) }));
+                    return;
+                }
+                const targetConnectionName = sourceRun.executionTarget?.target === 'connection'
+                    ? sourceRun.executionTarget.connectionName
+                    : sourceRun.executionTarget?.target === 'local'
+                        ? 'local'
+                        : projectConfig.defaultConnectionName;
+                let repaired;
+                try {
+                    repaired = await executeBoundedSqlRepair({
+                        question: sourceRun.question,
+                        sourceSql,
+                        targetConnection,
+                        targetConnectionName,
+                    });
+                }
+                catch (error) {
+                    const repairError = error;
+                    res.writeHead(repairError.status ?? 500, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        error: repairError.message,
+                        ...(repairError.warehouseFailure ? { warehouseFailure: repairError.warehouseFailure } : {}),
+                    }));
+                    return;
+                }
+                const { result, repairedSql, repairMode, firstFailure } = repaired;
+                const completedAt = new Date().toISOString();
+                const preview = agentResultToSynthesisPreview(result);
+                const synthesis = await synthesizeAnswer({
+                    question: sourceRun.question,
+                    audience: 'stakeholder',
+                    resultPreview: preview,
+                    sql: repairedSql,
+                    draftText: `The repaired query returned ${result.rowCount} row${result.rowCount === 1 ? '' : 's'}.`,
+                    ...(preview ? { columnFormats: agentColumnDisplayFormats(projectRoot, preview.columns) } : {}),
+                });
+                const sourceFailure = analyticalFailedRunFromAgentRun(sourceRun)?.failure;
+                const artifact = agentRunArtifact('answer', 'Repaired analytical answer', {
+                    kind: 'uncertified',
+                    certification: 'analyst_review_required',
+                    reviewStatus: 'analyst_review_required',
+                    trustLabel: 'AI-generated · review required',
+                    answer: synthesis.text,
+                    text: synthesis.text,
+                    result,
+                    proposedSql: repairedSql,
+                    sql: result.sql ?? repairedSql,
+                    dqlArtifact: result.dqlArtifact,
+                    previousAttempt: {
+                        sourceRunId: sourceRun.id,
+                        sql: sourceSql,
+                        failure: retainedFailure ?? firstFailure,
+                    },
+                    repair: { attempt: 1, mode: repairMode },
+                }, undefined, 'review_required');
+                const evaluation = {
+                    id: `${derivedRunId}:execution`,
+                    label: 'Repaired query execution',
+                    passed: true,
+                    severity: 'info',
+                    message: `The ${repairMode === 'ai' ? 'AI-repaired' : 'deterministically normalized'} read-only query executed on the original target.`,
+                };
+                const repairStep = {
+                    id: `${derivedRunId}:step`,
+                    index: 0,
+                    route: 'generated_answer',
+                    resolvedRoute: 'generated_answer',
+                    goal: 'Repair and execute the failed analytical query on its original target.',
+                    successCriteria: ['Read-only validation passes.', 'The original execution target returns a bounded result.'],
+                    status: 'repaired',
+                    attempts: 1,
+                    summary: evaluation.message,
+                    evaluations: [evaluation],
+                    artifacts: [artifact],
+                };
+                const events = [
+                    { id: `${derivedRunId}:repair`, runId: derivedRunId, type: 'repair.attempted', at: completedAt, message: 'Started one bounded query repair.', route: 'generated_answer' },
+                    { id: `${derivedRunId}:artifact`, runId: derivedRunId, type: 'artifact.created', at: completedAt, message: 'Created the repaired result artifact.', route: 'generated_answer', trustState: 'review_required' },
+                    { id: `${derivedRunId}:complete`, runId: derivedRunId, type: 'run.completed', at: completedAt, message: 'The repaired query executed successfully.', route: 'generated_answer', status: 'needs_review', trustState: 'review_required' },
+                ];
+                const derivedRun = {
+                    id: derivedRunId,
+                    question: sourceRun.question,
+                    requestedMode: sourceRun.requestedMode,
+                    route: 'generated_answer',
+                    status: 'needs_review',
+                    trustState: 'review_required',
+                    stopReason: 'generated_review_required',
+                    startedAt: completedAt,
+                    completedAt,
+                    selectedObject: sourceRun.selectedObject,
+                    executionTarget: sourceRun.executionTarget,
+                    routeDecision: sourceRun.routeDecision,
+                    plan: sourceRun.plan,
+                    steps: [repairStep],
+                    summary: synthesis.text,
+                    answer: synthesis.text,
+                    answerKind: 'governed',
+                    artifacts: [artifact],
+                    evaluations: [evaluation],
+                    events,
+                    nextActions: sourceRun.nextActions,
+                    repairAttempts: 1,
+                    lifecycle: {
+                        version: 1,
+                        state: 'terminal',
+                        phase: 'run.completed',
+                        revision: 1,
+                        eventCursor: events.length,
+                        startedAt: completedAt,
+                        updatedAt: completedAt,
+                        completedAt,
+                    },
+                    diagnosticReceipt: {
+                        version: 1,
+                        runId: derivedRunId,
+                        phase: 'run.completed',
+                        route: 'generated_answer',
+                        plan: sourceRun.plan,
+                        steps: [repairStep],
+                        artifacts: [artifact],
+                        evaluations: [evaluation],
+                    },
+                    derivation: {
+                        version: 1,
+                        kind: 'analytical_repair',
+                        sourceRunId: sourceRun.id,
+                        ...(sourceFailure?.failureId ? { sourceFailureId: sourceFailure.failureId } : {}),
+                        attempt: 1,
+                    },
+                };
+                await agentRunStore.save(derivedRun);
+                recordConversationTurn(threadId ? getConversationStore() : null, threadId, derivedRun);
+                res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ run: derivedRun }));
+                return;
+            }
             if (req.method === 'POST' && /^\/api\/agent-runs\/[^/]+\/analytical-repair$/.test(path)) {
                 const match = path.match(/^\/api\/agent-runs\/([^/]+)\/analytical-repair$/);
                 const id = decodeURIComponent(match?.[1] ?? '');
@@ -10062,10 +10505,20 @@ export async function startLocalServer(opts) {
                     // of the same 7,500+ object catalog while keeping the route compatible
                     // for older clients.
                     const includeSemantic = url.searchParams.get('includeSemantic') !== 'false';
+                    const dbtManifestPath = resolveDbtManifestPath(projectRoot, cfg);
+                    let databaseTree = [];
+                    if (cfg.manifestVersion === 3 && cfg.modeling?.mode === 'dbt-first' && dbtManifestPath) {
+                        try {
+                            databaseTree = buildDbtDatabaseSchemaTree(projectSnapshot().manifest, 25, physicalDbtRelationIds(dbtManifestPath));
+                        }
+                        catch {
+                            // Keep the rest of Block Studio available while dbt is rebuilt.
+                        }
+                    }
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({
                         semanticTree: includeSemantic && semanticLayer ? buildSemanticTree(semanticLayer, semanticImportManifest) : null,
-                        databaseTree: await buildDatabaseSchemaTree(projectRoot, executor, connection),
+                        databaseTree,
                         connection: {
                             default: defaultKey,
                             current: defaultKey,
@@ -11836,13 +12289,17 @@ export async function startLocalServer(opts) {
             // GET /api/describe-table?table=schema.table — returns columns for a specific table
             if (req.method === 'GET' && path === '/api/describe-table') {
                 try {
-                    const tablePath = url.searchParams.get('table') ?? '';
-                    const schemaName = url.searchParams.get('schema') ?? undefined;
-                    if (!tablePath) {
+                    const requestedRelation = url.searchParams.get('relation')?.trim() ?? '';
+                    const legacyTable = url.searchParams.get('table')?.trim() ?? '';
+                    const legacySchema = url.searchParams.get('schema')?.trim() ?? '';
+                    const relationParts = splitQualifiedRelationIdentifier(requestedRelation || [legacySchema, legacyTable].filter(Boolean).join('.'));
+                    if (!relationParts?.length) {
                         res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
-                        res.end(serializeJSON({ error: 'Missing table parameter' }));
+                        res.end(serializeJSON({ error: 'A safe dbt relation is required.' }));
                         return;
                     }
+                    const tablePath = relationParts.at(-1);
+                    const schemaName = relationParts.length > 1 ? relationParts.slice(0, -1).join('.') : undefined;
                     // Try connector.listColumns() first
                     let columns = [];
                     const activeConnection = connection;
@@ -11851,7 +12308,11 @@ export async function startLocalServer(opts) {
                             throw new Error('No active connection');
                         const connector = await executor.getConnector(activeConnection);
                         if (typeof connector.listColumns === 'function') {
-                            const rawCols = await connector.listColumns(schemaName, tablePath);
+                            // Connector contracts accept one schema plus one table. For a
+                            // three-part dbt relation, the active connection owns the database
+                            // and the final namespace segment is the schema.
+                            const connectorSchema = schemaName?.split('.').filter(Boolean).at(-1);
+                            const rawCols = await connector.listColumns(connectorSchema, tablePath);
                             columns = rawCols.map((c) => ({ name: c.name, type: c.dataType }));
                         }
                     }
@@ -11863,17 +12324,15 @@ export async function startLocalServer(opts) {
                         try {
                             const isFile = /\.(csv|parquet|json)$/i.test(tablePath) || tablePath.startsWith('data/');
                             const safePath = tablePath.replace(/'/g, "''");
-                            const qualifiedIdentifier = tablePath.split('.').map((p) => `"${p.replace(/"/g, '""')}"`).join('.');
+                            if (!activeConnection)
+                                throw new Error('No active connection');
+                            const dialect = getDialect(activeConnection.driver);
+                            const qualifiedIdentifier = relationParts.map((part) => dialect.quoteIdentifier(part)).join('.');
                             const sql = isFile
                                 ? `DESCRIBE SELECT * FROM read_csv_auto('${safePath}') LIMIT 0`
                                 : `DESCRIBE ${qualifiedIdentifier}`;
-                            if (!activeConnection)
-                                throw new Error('No active connection');
                             const result = await executor.executeQuery(sql, [], {}, activeConnection);
-                            columns = result.rows.map((row) => ({
-                                name: String(row['column_name'] ?? row['Field'] ?? ''),
-                                type: String(row['column_type'] ?? row['Type'] ?? ''),
-                            }));
+                            columns = schemaColumnsFromDescribeRows(result.rows);
                         }
                         catch {
                             // empty columns
@@ -11962,6 +12421,187 @@ 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.
+             */
+            if (req.method === 'POST' && path === '/api/notebook/repair-execution') {
+                let body = {};
+                let execContext = null;
+                const start = Date.now();
+                try {
+                    body = await readJSON(req);
+                    execContext = notebookExecutionContext(body.executionContext);
+                    const cell = normalizeNotebookCell(body.cell);
+                    if (!cell || (cell.type !== 'sql' && cell.type !== 'dql')) {
+                        res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ error: 'An editable SQL or DQL notebook cell is required.' }));
+                        return;
+                    }
+                    if (cell.type === 'dql' && /^\s*@block\(/i.test(cell.source)) {
+                        res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ error: 'Customize the bound block as a notebook copy before repairing it.' }));
+                        return;
+                    }
+                    const embeddedSourceSql = notebookCellRepairSql(cell);
+                    if (!embeddedSourceSql) {
+                        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.' }));
+                        return;
+                    }
+                    if (cell.type === 'sql' && /\{\{[^}]+\}\}/.test(cell.source)) {
+                        res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ error: 'Run or repair the referenced upstream cell before repairing this dependent query.' }));
+                        return;
+                    }
+                    const targetConnection = await resolveExecutionConnection(body);
+                    const submittedError = typeof body.error === 'string' ? body.error.trim() : '';
+                    const submittedFailure = body.failure && typeof body.failure === 'object' && !Array.isArray(body.failure)
+                        ? body.failure
+                        : undefined;
+                    const failureCode = typeof submittedFailure?.code === 'string' ? submittedFailure.code : undefined;
+                    if (!notebookFailureAllowsBackgroundRepair({ code: failureCode, message: submittedError })) {
+                        res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ error: 'This failure needs a data, access, parameter, or notebook dependency change and cannot be auto-fixed safely.' }));
+                        return;
+                    }
+                    const retainedFailure = submittedError
+                        ? normalizeWarehouseSqlFailure({ code: failureCode, message: submittedError }, targetConnection.driver)
+                        : undefined;
+                    if (!analyticalFailureAllowsDeterministicRetry(retainedFailure)) {
+                        res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({
+                            error: 'This failure requires authorized access or a policy change and cannot be repaired in the background.',
+                            warehouseFailure: retainedFailure,
+                        }));
+                        return;
+                    }
+                    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);
+                    }
+                    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
+                        : executionTarget.target === 'local'
+                            ? 'local'
+                            : projectConfig.defaultConnectionName;
+                    const question = [
+                        `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 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);
+                    }
+                    else {
+                        repairedSource = repaired.repairedSql;
+                    }
+                    if (!repairedSource) {
+                        throw boundedRepairError('DQL could not safely replace the embedded query in this cell.', 422);
+                    }
+                    // Prove the repaired DQL wrapper still compiles. SQL execution above
+                    // already proved the corrected statement on the selected target.
+                    if (cell.type === 'dql') {
+                        const validationPlan = buildExecutionPlan({ ...cell, source: repairedSource }, {
+                            semanticLayer,
+                            driver: targetConnection.driver,
+                            parameters: invocation?.values,
+                        });
+                        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 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);
+                        }
+                    }
+                    if (execContext?.notebookPath) {
+                        recordNotebookQueryRun(projectRoot, {
+                            notebookPath: execContext.notebookPath,
+                            cellId: execContext.cellId ?? cell.id,
+                            cellName: execContext.cellName ?? cell.title,
+                            source: execContext.source ?? (cell.type === 'dql' ? 'notebook_dql_cell' : 'notebook_sql_cell'),
+                            status: 'success',
+                            rowCount: repaired.result.rowCount ?? repaired.result.rows.length,
+                            durationMs: Date.now() - start,
+                            sql: repaired.repairedSql,
+                        });
+                    }
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        ok: true,
+                        source: repairedSource,
+                        repairedSql: repaired.repairedSql,
+                        repairMode: repaired.repairMode,
+                        result: repaired.result,
+                        executionTarget,
+                        executionContext: notebookExecutionIdentity(execContext, cell.id),
+                        compiledSql: repaired.repairedSql,
+                        executedSql: repaired.result.sql ?? repaired.repairedSql,
+                        executionReceipt: repaired.result.executionReceipt,
+                    }));
+                }
+                catch (error) {
+                    const repairError = error;
+                    if (execContext?.notebookPath) {
+                        recordNotebookQueryRun(projectRoot, {
+                            notebookPath: execContext.notebookPath,
+                            cellId: execContext.cellId,
+                            cellName: execContext.cellName,
+                            source: execContext.source ?? 'notebook_cell_repair',
+                            status: 'error',
+                            durationMs: Date.now() - start,
+                            errorCode: repairError.warehouseFailure?.category ?? repairError.message,
+                            sql: typeof body.attemptedSql === 'string' ? body.attemptedSql : undefined,
+                        });
+                    }
+                    res.writeHead(repairError.status ?? 500, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        error: repairError.message,
+                        ...(repairError.warehouseFailure ? { warehouseFailure: repairError.warehouseFailure } : {}),
+                    }));
+                }
+                return;
+            }
             if (req.method === 'POST' && path === '/api/query') {
                 let body;
                 let execContext = null;
@@ -12005,7 +12645,15 @@ export async function startLocalServer(opts) {
                         }));
                         return;
                     }
-                    const prepared = prepareLocalExecution(semantic.sql, executionConnection, projectRoot, projectConfig);
+                    const preparation = await prepareAnalyticalExecutionSql({
+                        sql: semantic.sql,
+                        subject: 'Notebook query',
+                        executor,
+                        connection: executionConnection,
+                        projectRoot,
+                        projectConfig,
+                    });
+                    const prepared = { sql: preparation.preparedSql, connection: preparation.connection };
                     const app = loadRuntimeApp(projectRoot, typeof body.appId === 'string' ? body.appId : activePersonaAppId());
                     const domain = typeof body.domain === 'string' ? body.domain : app?.domain;
                     assertAppAccess({ app, domain, level: 'execute' });
@@ -12033,8 +12681,8 @@ export async function startLocalServer(opts) {
                         ...normalized,
                         executionContext: notebookExecutionIdentity(execContext),
                         executionTarget: executionTargetDescriptor(body),
-                        compiledSql: semantic.sql,
-                        executedSql: prepared.sql,
+                        compiledSql: preparation.decodedSql,
+                        executedSql: preparation.executedSql,
                     });
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(payload);
@@ -12705,6 +13353,11 @@ export async function startLocalServer(opts) {
             if (req.method === 'POST' && path === '/api/dql/artifacts/execute') {
                 try {
                     const body = await readJSON(req);
+                    const targetConnection = await resolveExecutionConnection(body);
+                    const targetDescriptor = executionTargetDescriptor(body);
+                    const targetConnectionName = targetDescriptor.target === 'connection'
+                        ? targetDescriptor.connectionName
+                        : 'local';
                     const requestedArtifact = normalizeDqlArtifactReference(body.artifact);
                     const requestedBlockName = typeof body.blockName === 'string' ? body.blockName.trim() : '';
                     let source = requestedArtifact?.source ?? '';
@@ -12762,7 +13415,7 @@ export async function startLocalServer(opts) {
                         parameters,
                         question: typeof body.question === 'string' ? body.question : undefined,
                         rowLimit: requestedArtifact?.limit,
-                    });
+                    }, targetConnection, targetConnectionName);
                     const actualReceipt = result.executionReceipt;
                     // Same reasoning: if the canonical block was reloaded, its compiled SQL
                     // is EXPECTED to differ, so this determinism check would fire on a
@@ -12917,26 +13570,16 @@ export async function startLocalServer(opts) {
                         res.end(serializeJSON({ cellType: cell.type, result: null }));
                         return;
                     }
-                    // DECODE, THEN VALIDATE. A leaked `source::db.schema.table` is an internal
-                    // retrieval key whose suffix IS the physical relation, so rejecting the
-                    // cell and asking the user (or another AI round trip) to repair it was
-                    // busywork for a mechanical substitution. Anything still unresolvable
-                    // after this — a BARE `source::orders`, which names no database or
-                    // schema — genuinely cannot be decoded and still fails here.
-                    let decodedSql = resolveInternalRelationIds(executableSql, EMPTY_SCHEMA_GROUNDING);
-                    let bareResolution = null;
-                    if (internalDqlRelationIdValidationError(decodedSql, 'x')) {
-                        bareResolution = await resolveBareInternalRelationIds(decodedSql, executor, cellConnection);
-                        decodedSql = bareResolution.sql;
-                    }
-                    const internalRelationError = internalDqlRelationIdValidationError(decodedSql, cell.type === 'dql' ? 'DQL query' : 'Notebook query', 
-                    // A probe that came back empty is PROOF the relation is not visible
-                    // to this connection, so the refusal states that instead of sending
-                    // the user to an AI repair that cannot conjure a missing table.
-                    bareResolution ? { probed: true, ambiguous: bareResolution.ambiguous } : undefined);
-                    if (internalRelationError)
-                        throw new DqlInternalRelationIdError(internalRelationError);
-                    const prepared = prepareLocalExecution(decodedSql, cellConnection, projectRoot, projectConfig);
+                    const preparation = await prepareAnalyticalExecutionSql({
+                        sql: executableSql,
+                        subject: cell.type === 'dql' ? 'DQL query' : 'Notebook query',
+                        executor,
+                        connection: cellConnection,
+                        projectRoot,
+                        projectConfig,
+                    });
+                    const decodedSql = preparation.decodedSql;
+                    const prepared = { sql: preparation.preparedSql, connection: preparation.connection };
                     const app = loadRuntimeApp(projectRoot, typeof body.appId === 'string' ? body.appId : activePersonaAppId());
                     assertAppAccess({ app, domain: resolved.domain ?? app?.domain, level: 'execute' });
                     const semanticExecution = semanticCompose?.compiled
@@ -15281,6 +15924,60 @@ export function prepareLocalExecution(sql, connection, projectRoot, projectConfi
         connection: normalizedConnection,
     };
 }
+/**
+ * One host-owned SQL preparation boundary shared by Ask and Notebook.
+ *
+ * Surface-specific compilation happens before this function and surface policy
+ * (for example exploratory join proof) may run around it, but no analytical
+ * entrypoint may decode internal IDs, resolve dbt paths, enforce read-only
+ * execution, or append a preview bound differently anymore.
+ *
+ * Acceptance: API-003, API-006, API-007, EXP-001, E2E-014.
+ */
+export async function prepareAnalyticalExecutionSql(input) {
+    const sourceSql = input.sql.trim();
+    const rewrites = [];
+    let decodedSql = resolveInternalRelationIds(sourceSql, EMPTY_SCHEMA_GROUNDING, 'qualified', rewrites);
+    let bareResolution = null;
+    if (internalDqlRelationIdValidationError(decodedSql, 'x')) {
+        bareResolution = await resolveBareInternalRelationIds(decodedSql, input.executor, input.connection);
+        decodedSql = bareResolution.sql;
+        rewrites.push(...bareResolution.resolved);
+    }
+    const internalRelationError = internalDqlRelationIdValidationError(decodedSql, input.subject, bareResolution
+        ? { probed: true, ambiguous: bareResolution.ambiguous }
+        : undefined);
+    if (internalRelationError) {
+        throw tagAnalyticalError(new DqlInternalRelationIdError(internalRelationError), {
+            origin: bareResolution?.ambiguous.length ? 'ambiguity' : 'retrieval_gap',
+            stage: 'grounding',
+            code: bareResolution?.ambiguous.length ? 'ambiguous_relation' : 'unknown_relation',
+        });
+    }
+    const prepared = prepareLocalExecution(decodedSql, input.connection, input.projectRoot, input.projectConfig);
+    if (input.enforceReadOnly) {
+        const readOnlyError = readOnlySqlValidationError(prepared.sql, input.subject, input.connection.driver);
+        if (readOnlyError) {
+            throw analyticalError(readOnlyError, {
+                origin: 'governance_gate',
+                stage: 'validation',
+                code: 'unsafe_sql',
+            });
+        }
+    }
+    const rowBound = input.rowLimit === undefined
+        ? undefined
+        : buildRowBoundedSql(prepared.sql, input.rowLimit, input.connection.driver);
+    return {
+        sourceSql,
+        decodedSql,
+        preparedSql: prepared.sql,
+        executedSql: rowBound?.sql ?? prepared.sql,
+        connection: prepared.connection,
+        rewrites,
+        ...(rowBound ? { rowBound } : {}),
+    };
+}
 export function dashboardRuntimeVariables(dashboard, overrides = {}) {
     const variables = {};
     for (const param of dashboard.params ?? []) {
@@ -16452,6 +17149,55 @@ function normalizeNotebookCell(value) {
         config: candidate.config,
     };
 }
+export function notebookCellRepairSql(cell) {
+    if (cell.type === 'sql')
+        return cell.source.trim() || undefined;
+    if (cell.type !== 'dql')
+        return undefined;
+    const match = /\bquery\s*=\s*"""([\s\S]*?)"""/i.exec(cell.source);
+    return match?.[1]?.trim() || undefined;
+}
+export function replaceNotebookDqlQueryForRepair(source, sql) {
+    const queryField = /\b(query\s*=\s*""")([\s\S]*?)(""")/i;
+    if (!queryField.test(source) || !sql.trim())
+        return undefined;
+    return source.replace(queryField, (_match, open, _body, close) => (`${open}\n${sql.trim()}\n  ${close}`));
+}
+const NOTEBOOK_BACKGROUND_REPAIR_BLOCKED_CODES = new Set([
+    'AMBIGUOUS_NOTEBOOK_DEPENDENCY',
+    'CROSS_ENGINE_JOIN_REQUIRED',
+    'EXECUTION_TARGET_MISMATCH',
+    'SEMANTIC_SOURCE_DRIFT',
+    'STALE_CELL_EXECUTION',
+    'UPSTREAM_RESULT_UNAVAILABLE',
+    'UNAUTHORIZED',
+]);
+/**
+ * Notebook background repair is deliberately narrower than conversational
+ * repair. Access, policy, target, parameter, and dependency failures require a
+ * user decision; only query-shape failures may enter the one-attempt loop.
+ * Acceptance: API-006, API-007, UI-012, UI-013, SEC-004, E2E-014.
+ */
+export function notebookFailureAllowsBackgroundRepair(input) {
+    const code = input.code?.trim().toUpperCase();
+    const message = input.message?.trim() ?? '';
+    if (!message)
+        return false;
+    if (code && NOTEBOOK_BACKGROUND_REPAIR_BLOCKED_CODES.has(code))
+        return false;
+    return !/(?:permission|not authorized|unauthori[sz]ed|access denied|authentication|credential|policy|unsafe|read[- ]only|cancel(?:led|ed)|required parameters?|provide required|cross[- ]engine|upstream (?:cell|result)|notebook dependency|target mismatch|source drift|matched more than one schema)/i.test(message);
+}
+export function applyNotebookRepairRewrites(sql, rewrites) {
+    return rewrites.reduce((current, rewrite) => {
+        const pattern = rewrite.from.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        return current.replace(new RegExp(pattern, 'g'), rewrite.to);
+    }, sql);
+}
+export function restoreNotebookDqlParameterInterpolations(sql, parameters) {
+    return [...parameters]
+        .sort((left, right) => right.position - left.position)
+        .reduce((current, parameter) => current.replace(new RegExp(`\\$${parameter.position}\\b`, 'g'), `\${${parameter.name}}`), sql);
+}
 function resolveNotebookBlockReferenceCell(cell, projectRoot) {
     if (cell.type !== 'dql')
         return { cell };
@@ -16645,6 +17391,68 @@ function readUserPrefs(userPrefsPath) {
 function writeUserPrefs(userPrefsPath, prefs) {
     writeFileSync(userPrefsPath, JSON.stringify(prefs, null, 2) + '\n', 'utf-8');
 }
+/** Normalize DESCRIBE output across Snowflake, DuckDB, and PostgreSQL shapes. */
+export function schemaColumnsFromDescribeRows(rows) {
+    return rows.map((row) => ({
+        name: String(row['column_name'] ?? row['COLUMN_NAME'] ?? row['Field'] ?? row['FIELD'] ?? row['name'] ?? row['NAME'] ?? ''),
+        type: String(row['column_type'] ?? row['COLUMN_TYPE'] ?? row['data_type'] ?? row['DATA_TYPE'] ?? row['Type'] ?? row['TYPE'] ?? row['type'] ?? ''),
+    })).filter((column) => Boolean(column.name));
+}
+/** Parse dbt relation strings without letting relation text become SQL syntax. */
+export function splitQualifiedRelationIdentifier(value) {
+    const rawParts = [];
+    let current = '';
+    let quote = null;
+    for (let index = 0; index < value.length; index += 1) {
+        const char = value[index];
+        if (quote) {
+            current += char;
+            if (char === quote) {
+                const next = value[index + 1];
+                if ((quote === '"' || quote === '`') && next === quote) {
+                    current += next;
+                    index += 1;
+                }
+                else {
+                    quote = null;
+                }
+            }
+            continue;
+        }
+        if (char === '"' || char === '`') {
+            quote = char;
+            current += char;
+            continue;
+        }
+        if (char === '[') {
+            quote = ']';
+            current += char;
+            continue;
+        }
+        if (char === '.') {
+            rawParts.push(current);
+            current = '';
+            continue;
+        }
+        current += char;
+    }
+    if (quote)
+        return null;
+    rawParts.push(current);
+    if (rawParts.length === 0 || rawParts.length > 4)
+        return null;
+    const decoded = rawParts.map((raw) => {
+        const token = raw.trim();
+        if (/^"(?:[^"]|"")+"$/.test(token))
+            return token.slice(1, -1).replace(/""/g, '"');
+        if (/^`(?:[^`]|``)+`$/.test(token))
+            return token.slice(1, -1).replace(/``/g, '`');
+        if (/^\[[^\]]+\]$/.test(token))
+            return token.slice(1, -1).replace(/\]\]/g, ']');
+        return /^[A-Za-z_][A-Za-z0-9_$]*$/.test(token) ? token : null;
+    });
+    return decoded.every((part) => Boolean(part)) ? decoded : null;
+}
 async function introspectSchema(executor, connection, options = {}) {
     let tables = [];
     const columnsByPath = new Map();
@@ -16699,77 +17507,93 @@ async function introspectSchema(executor, connection, options = {}) {
     }
     return { tables, columnsByPath };
 }
-function buildDatabaseSchemaTree(projectRoot, executor, connection) {
-    return (async () => {
-        const dataFiles = scanDataFiles(projectRoot);
-        const dbTables = connection
-            ? (await introspectSchema(executor, connection, { limit: 1_000 })).tables
-            : [];
-        const schemaMap = new Map();
-        for (const table of dbTables) {
-            const schemaName = table.schema || 'default';
-            const existing = schemaMap.get(schemaName) ?? [];
-            existing.push({ name: table.name, path: table.path, type: table.type });
-            schemaMap.set(schemaName, existing);
-        }
-        const databaseNodes = Array.from(schemaMap.entries())
-            .sort((a, b) => a[0].localeCompare(b[0]))
-            .map(([schemaName, tables]) => ({
-            id: `db-schema:${schemaName}`,
-            label: schemaName,
-            kind: 'schema',
-            children: tables
-                .sort((a, b) => a.name.localeCompare(b.name))
-                .map((table) => ({
-                id: `db-table:${table.path}`,
-                label: table.name,
-                kind: 'table',
-                path: table.path,
-                type: table.type,
-                // Warehouse columns are loaded lazily for the selected table.
-                children: [],
-            })),
-        }));
-        // Eagerly resolve file columns via DuckDB DESCRIBE
-        if (dataFiles.length > 0) {
-            const fileChildren = [];
-            for (const file of dataFiles) {
-                let columns = [];
-                if (connection) {
-                    try {
-                        const ext = file.name.split('.').pop()?.toLowerCase();
-                        const readFn = ext === 'parquet' ? 'read_parquet' : ext === 'json' ? 'read_json_auto' : 'read_csv_auto';
-                        const descResult = await executor.executeQuery(`DESCRIBE SELECT * FROM ${readFn}('${file.path.replace(/'/g, "''")}') LIMIT 0`, [], {}, connection);
-                        columns = descResult.rows.map((row) => ({
-                            id: `db-column:${file.path}:${String(row['column_name'] ?? '')}`,
-                            label: String(row['column_name'] ?? ''),
-                            kind: 'column',
-                            path: file.path,
-                            type: String(row['column_type'] ?? ''),
-                        }));
-                    }
-                    catch {
-                        // file column discovery failed — empty children is fine
-                    }
-                }
-                fileChildren.push({
-                    id: `db-table:${file.path}`,
-                    label: file.name,
-                    kind: 'table',
-                    path: file.path,
-                    type: 'FILE',
-                    children: columns,
-                });
+const dbtPhysicalRelationCache = new Map();
+/**
+ * Display-only physical relation filter sourced from the raw dbt artifact.
+ * This deliberately does not mutate DQLManifest or the agent metadata/indexes.
+ */
+function physicalDbtRelationIds(manifestPath) {
+    try {
+        const stat = statSync(manifestPath);
+        const version = `${stat.size}:${stat.mtimeMs}`;
+        const cached = dbtPhysicalRelationCache.get(manifestPath);
+        if (cached?.version === version)
+            return cached.ids;
+        const raw = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+        const ids = new Set();
+        for (const collectionName of ['nodes', 'sources']) {
+            const collection = raw[collectionName];
+            if (!collection || typeof collection !== 'object' || Array.isArray(collection))
+                continue;
+            for (const [fallbackId, value] of Object.entries(collection)) {
+                if (!value || typeof value !== 'object' || Array.isArray(value))
+                    continue;
+                const node = value;
+                const resourceType = String(node.resource_type ?? (collectionName === 'sources' ? 'source' : ''));
+                if (resourceType !== 'model' && resourceType !== 'source')
+                    continue;
+                const config = node.config && typeof node.config === 'object' && !Array.isArray(node.config)
+                    ? node.config
+                    : {};
+                if (resourceType === 'model' && String(config.materialized ?? '').toLowerCase() === 'ephemeral')
+                    continue;
+                ids.add(typeof node.unique_id === 'string' ? node.unique_id : fallbackId);
             }
-            databaseNodes.unshift({
-                id: 'db-schema:files',
-                label: 'files',
-                kind: 'schema',
-                children: fileChildren,
-            });
         }
-        return databaseNodes;
-    })();
+        dbtPhysicalRelationCache.set(manifestPath, { version, ids });
+        return ids;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function buildDbtDatabaseSchemaTree(manifest, limit = 25, physicalIds) {
+    // PERF-001 / CTX-005: Block Studio must not enumerate the connected account.
+    // Its initial editor context is the first bounded page of physical relations
+    // declared by the connected dbt artifact; columns remain lazy point-lookups.
+    const boundedLimit = Math.min(100, Math.max(1, Math.floor(limit)));
+    const seen = new Set();
+    const tables = Object.values(manifest.dbtProvenance?.nodes ?? {})
+        .filter((node) => Boolean(node.relation) && (!physicalIds || physicalIds.has(node.uniqueId)))
+        .sort((a, b) => a.uniqueId.localeCompare(b.uniqueId))
+        .flatMap((node) => {
+        const path = node.relation;
+        const key = path.toLowerCase();
+        if (seen.has(key))
+            return [];
+        seen.add(key);
+        const parts = path.split('.').filter(Boolean);
+        return [{
+                schema: parts.length > 1 ? parts.slice(0, -1).join('.') : 'default',
+                name: parts.at(-1) ?? node.name,
+                path,
+                type: node.resourceType === 'source' ? 'DBT_SOURCE' : 'DBT_MODEL',
+            }];
+    })
+        .slice(0, boundedLimit);
+    const bySchema = new Map();
+    for (const table of tables) {
+        const current = bySchema.get(table.schema) ?? [];
+        current.push(table);
+        bySchema.set(table.schema, current);
+    }
+    return Array.from(bySchema.entries())
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([schema, schemaTables]) => ({
+        id: `db-schema:${schema}`,
+        label: schema,
+        kind: 'schema',
+        children: schemaTables
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .map((table) => ({
+            id: `db-table:${table.path}`,
+            label: table.name,
+            kind: 'table',
+            path: table.path,
+            type: table.type,
+            children: [],
+        })),
+    }));
 }
 export function openBlockStudioDocument(projectRoot, relativePath, semanticLayer) {
     const normalizedPath = normalize(relativePath).replace(/^\/+/, '');
@@ -23332,6 +24156,35 @@ ${predicates.map((predicate) => `    ${predicate}`).join(' OR\n')}
 ORDER BY table_schema, table_name, ordinal_position
 LIMIT 400`;
 }
+/**
+ * Conservative fallback for deciding whether an unparsed statement still
+ * needs DQL's structural join validation. Join-free SELECT syntax may be
+ * newer than the local parser and can safely continue to the read-only
+ * warehouse boundary; an unparsed join must never bypass relationship proof.
+ */
+export function sqlMayContainJoin(sql) {
+    const normalized = stripSqlStringsAndComments(sql)
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (/\bjoin\b/i.test(normalized))
+        return true;
+    const fromMatch = /\bfrom\b/i.exec(normalized);
+    if (!fromMatch)
+        return false;
+    const tail = normalized.slice(fromMatch.index + fromMatch[0].length);
+    const clauseMatch = /\b(where|group\s+by|having|qualify|order\s+by|limit|fetch|union|intersect|except)\b/i.exec(tail);
+    const fromClause = clauseMatch ? tail.slice(0, clauseMatch.index) : tail;
+    let depth = 0;
+    for (const char of fromClause) {
+        if (char === '(')
+            depth += 1;
+        else if (char === ')')
+            depth = Math.max(0, depth - 1);
+        else if (char === ',' && depth === 0)
+            return true;
+    }
+    return false;
+}
 /**
  * Resolve a BARE internal graph identity (`source::orders` — a name with no
  * database or schema) against the warehouse.