@askdb/studio 0.2.0-beta.4 → 0.2.0-beta.41

package/dist/server.js

@@ -1,56 +1,138 @@
-import { existsSync, readFileSync, rmSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { createServer } from "node:http";
-import { extname, relative, join, resolve } from "node:path";
+import { extname, relative, join, resolve, dirname, sep } from "node:path";
+import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { generateText as defaultGenerateText } from "ai";
-import { getAskDbRuntimeConfig } from "@askdb/config";
-import { ask, askDbAiKeyMissingMessage, createAskDbEmbeddingModel, createAskDbLanguageModelFromEnv, isBuiltInDialectId, loadSchema, resolveAskDbAiConfig, resolveAskDbEmbeddingConfig, suggestEnrichment, } from "@askdb/core";
-import { buildSchemaIndex, chunkContentHash, chunkSchema, createRetriever, loadChunkerSourcesFromDir, } from "@askdb/rag";
-import { createAiSdkEmbedder } from "@askdb/rag/embedders/ai-sdk";
-import { createFileStore } from "@askdb/rag/stores/file";
-import { createMemoryStore } from "@askdb/rag/stores/memory";
-import { createPgvectorStore } from "@askdb/rag/stores/pgvector";
-import { buildDefaultTableBody, buildFrontmatter, buildSuggestionContext, buildSuggestionTarget, buildTableDraft, loadWorkspace, replaceH2Section, replaceTableDescription, saveTable, } from "@askdb/enrich";
-const CLIENT_DIR = fileURLToPath(new URL("./client/", import.meta.url));
+import { ASKDB_AI_PROVIDERS, bootstrapAskDbEnv, getAskDbRuntimeConfig, } from "@askdb/config";
+import { createAiRegistry, resolveReasoningEffort, } from "@askdb/ai";
+import { ask, DEFAULT_TENANT_SQL_MODE, formatSchemaV2ForNlToSql, formatSensitiveReference, isBuiltInDialectId, loadSchema, saveSchemaFile, schemaHasSensitiveIdentifiers, SensitiveEnrichmentTargetError, SqlValidationError, validateSensitiveReferences, suggestEnrichment, tenantScopeSchema, SchemaParseError, tenantPolicyFrontmatterSchema, } from "@askdb/core";
+import { buildSchemaIndex, chunkContentHash, chunkSchema, aiSdkEmbedderId, createAiSdkEmbedder, createFileStore, createMemoryStore, createPgvectorStore, createRetriever, detectEmbeddingDimensions, loadChunkerSourcesFromDir, PgvectorDimensionMismatchError, } from "@askdb/rag";
+import { buildDefaultTableBody, buildFrontmatter, buildSuggestionContext, buildSuggestionTarget, buildTableDraft, loadWorkspace, replaceH2Section, replaceTableDescription, saveConcepts, saveTable, saveTenantPolicy, } from "@askdb/enrich";
+import { EXECUTE_DRIVER_REGISTRY, executeDialectFor, isDriverInstalled, isStudioExecuteProvider, validateExecuteSql, } from "./execute-registry.js";
+import { lockfilePackageManager, packageManagerAddArgs, packageManagerSpawnSpec, } from "./package-manager.js";
+import { resolveStudioIntrospectionPlan, runStudioIntrospection } from "./introspection.js";
+import { probeSetupState, writeSetupConfig, SetupError } from "./setup.js";
+import { checkApiRequest, checkHost, createStudioSessionToken, injectSessionToken, } from "./request-guard.js";
+// Batteries-included surface: every built-in provider is registered, and each
+// loads its @ai-sdk/* package only when first used, so env config alone
+// selects the provider.
+const ai = createAiRegistry();
+const DEFAULT_CLIENT_DIR = fileURLToPath(new URL("./client/", import.meta.url));
+let clientDirForTests;
+/** @internal Tests only — serve client assets from another directory. */
+export function setStudioClientDirForTests(dir) {
+    clientDirForTests = dir;
+}
+function clientDir() {
+    return clientDirForTests ?? DEFAULT_CLIENT_DIR;
+}
 const STUDIO_RAG_MOCK_DIMENSIONS = 64;
 const STUDIO_RAG_MOCK_EMBEDDER_ID = `studio:mock-lexical-${STUDIO_RAG_MOCK_DIMENSIONS}`;
-const DEFAULT_EMBEDDING_MODEL = "text-embedding-3-small";
 let studioPgvectorStoreFactoryForTests;
 export function setStudioPgvectorStoreFactoryForTests(factory) {
     studioPgvectorStoreFactoryForTests = factory;
 }
 export function createStudioServer(options) {
     const schemaDir = resolve(options.schema);
-    if (!existsSync(schemaDir)) {
+    const setupReason = options.setupReason ?? null;
+    if (!setupReason && !existsSync(schemaDir)) {
         throw new Error(`schema directory not found: ${schemaDir}`);
     }
     const state = {
         schemaDir,
-        workspace: loadWorkspace(schemaDir),
+        workspace: setupReason ? null : loadWorkspace(schemaDir),
+        setupReason,
     };
-    return createServer(async (req, res) => {
+    const sessionToken = createStudioSessionToken();
+    const server = createServer(async (req, res) => {
         try {
+            // Host allowlist on every request (static assets included) — defeats DNS rebinding.
+            const hostFailure = checkHost(req, options.host);
+            if (hostFailure) {
+                return writeJson(res, hostFailure.status, { error: { message: hostFailure.message } });
+            }
             const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+            // Origin, session token, and content-type checks on every API call.
+            if (url.pathname.startsWith("/api/")) {
+                const apiFailure = checkApiRequest(req, sessionToken);
+                if (apiFailure) {
+                    return writeJson(res, apiFailure.status, { error: { message: apiFailure.message } });
+                }
+            }
             if (req.method === "GET" && url.pathname === "/") {
-                return serveClientFile(res, "index.html");
+                return serveIndexHtml(res, sessionToken);
             }
             if (req.method === "GET" && url.pathname.startsWith("/assets/")) {
                 return serveClientFile(res, decodeURIComponent(url.pathname.slice(1)));
             }
+            if (req.method === "GET" && url.pathname === "/api/setup/status") {
+                return writeJson(res, 200, buildSetupStatus(state));
+            }
+            if (req.method === "POST" && url.pathname === "/api/setup/config") {
+                if (!isLoopbackRequest(req)) {
+                    return writeJson(res, 403, { error: { message: "Setup is only available from loopback clients." } });
+                }
+                const body = await readJson(req);
+                const result = handleSetupConfig(state, body);
+                return writeJson(res, 200, result);
+            }
+            if (req.method === "POST" && url.pathname === "/api/setup/introspect") {
+                if (!isLoopbackRequest(req)) {
+                    return writeJson(res, 403, { error: { message: "Setup is only available from loopback clients." } });
+                }
+                const result = await handleSetupIntrospect(state);
+                return writeJson(res, 200, result);
+            }
+            // Everything below needs a loaded workspace — route setup-mode clients to the wizard.
+            if (state.setupReason && url.pathname.startsWith("/api/")) {
+                return writeJson(res, 409, {
+                    error: { message: "Studio needs setup. Open Studio in the browser to finish the guided setup." },
+                    setup: buildSetupStatus(state),
+                });
+            }
             if (req.method === "GET" && url.pathname === "/api/workspace") {
-                return writeJson(res, 200, serializeWorkspace(state.workspace));
+                return writeJson(res, 200, serializeWorkspace(requireWorkspace(state)));
+            }
+            if (req.method === "GET" && url.pathname === "/api/introspect/status") {
+                requireWorkspace(state);
+                return writeJson(res, 200, await buildIntrospectionPlanDto());
+            }
+            if (req.method === "POST" && url.pathname === "/api/introspect") {
+                if (!isLoopbackRequest(req)) {
+                    return writeJson(res, 403, { error: { message: "Resync is only available from loopback clients." } });
+                }
+                const result = await handleResync(state);
+                return writeJson(res, 200, result);
             }
             if (req.method === "POST" && url.pathname.startsWith("/api/tables/")) {
                 const tableId = decodeURIComponent(url.pathname.slice("/api/tables/".length));
                 const body = await readJson(req);
                 const draft = parseTableDraftBody(body);
                 saveDraft(state, tableId, draft);
-                return writeJson(res, 200, serializeWorkspace(state.workspace));
+                return writeJson(res, 200, serializeWorkspace(requireWorkspace(state)));
+            }
+            if (req.method === "POST" && url.pathname === "/api/concepts") {
+                const body = await readJson(req);
+                const concepts = parseConceptsBody(body);
+                saveConceptsDraft(state, concepts);
+                return writeJson(res, 200, serializeWorkspace(requireWorkspace(state)));
+            }
+            if (req.method === "POST" && url.pathname === "/api/tenant-policy") {
+                const body = await readJson(req);
+                const { frontmatter, bodyText } = parseTenantPolicyBody(body);
+                saveTenantPolicyDraft(state, frontmatter, bodyText);
+                return writeJson(res, 200, serializeWorkspace(requireWorkspace(state)));
+            }
+            if (req.method === "POST" && url.pathname === "/api/suggest-tenant-policy") {
+                const draft = await suggestTenantPolicyDraft(state);
+                return writeJson(res, 200, draft);
             }
             if (req.method === "POST" && url.pathname === "/api/suggest") {
                 const body = await readJson(req);
                 const source = parseSuggestSource(body);
-                const candidates = await suggestForSource(state.workspace, source);
+                const candidates = await suggestForSource(state, source);
                 return writeJson(res, 200, { candidates });
             }
             if (req.method === "GET" && url.pathname === "/api/rag/status") {
@@ -72,26 +154,56 @@ export function createStudioServer(options) {
                 const result = await askSampleQuestion(state, options);
                 return writeJson(res, 200, result);
             }
+            if (req.method === "GET" && url.pathname === "/api/history") {
+                return writeJson(res, 200, readPlaygroundHistory(state.schemaDir));
+            }
+            if (req.method === "POST" && url.pathname === "/api/history") {
+                const body = await readJson(req);
+                const entry = parsePlaygroundHistoryEntry(body);
+                appendPlaygroundHistory(state.schemaDir, entry);
+                return writeJson(res, 200, { ok: true });
+            }
+            if (req.method === "DELETE" && url.pathname.startsWith("/api/history/")) {
+                const id = decodeURIComponent(url.pathname.slice("/api/history/".length));
+                const result = deletePlaygroundHistoryEntry(state.schemaDir, id);
+                return writeJson(res, 200, result);
+            }
+            if (req.method === "GET" && url.pathname === "/api/execute/status") {
+                const result = await getExecuteStatus(state.schemaDir);
+                return writeJson(res, 200, result);
+            }
+            if (req.method === "POST" && url.pathname === "/api/execute/install-driver") {
+                if (!isLoopbackRequest(req)) {
+                    return writeJson(res, 403, { error: { message: "Driver install is only available from loopback clients." } });
+                }
+                const body = await readJson(req);
+                const result = await installExecuteDriver(body, state.schemaDir);
+                return writeJson(res, 200, result);
+            }
+            if (req.method === "POST" && url.pathname === "/api/execute") {
+                const body = await readJson(req);
+                const result = await executeQuery(body, state.schemaDir);
+                return writeJson(res, 200, result);
+            }
             if (req.method === "GET" && !url.pathname.startsWith("/api/")) {
-                return serveClientFile(res, "index.html");
+                return serveIndexHtml(res, sessionToken);
             }
             writeJson(res, 404, { error: { message: "Not found" } });
         }
         catch (error) {
-            const status = error instanceof StudioHttpError ? error.status : 500;
+            const status = error instanceof StudioHttpError || error instanceof SetupError ? error.status : 500;
             writeJson(res, status, {
                 error: { message: error instanceof Error ? error.message : String(error) },
             });
         }
     });
+    return Object.assign(server, { sessionToken });
 }
 export function serializeWorkspace(workspace) {
     const rt = getAskDbRuntimeConfig();
     const aiConfig = (() => {
         try {
-            return resolveAskDbAiConfig(rt.ai.aiEnv, {
-                modelEnvVar: rt.ai.studioModel ? "ASKDB_STUDIO_MODEL" : undefined,
-            });
+            return ai.resolveAiConfig(rt.ai.aiEnv);
         }
         catch {
             // A misconfigured AI env (e.g. azure without resourceName) shouldn't crash the workspace
@@ -99,13 +211,19 @@ export function serializeWorkspace(workspace) {
             return undefined;
         }
     })();
+    const schema = loadSchema(workspace.schemaDir);
+    const schemaProvider = "provider" in schema && typeof schema.provider === "string" ? schema.provider : undefined;
+    const dialect = rt.nlToSql.dialect ??
+        (schemaProvider && isBuiltInDialectId(schemaProvider) ? schemaProvider : "postgres");
     return {
         schemaDir: workspace.schemaDir,
+        schemaPathRelative: toRelativeSchemaPath(workspace.schemaDir),
         schemaId: workspace.physical.schemaId,
+        dialect,
         warnings: workspace.warnings,
         aiConfigured: Boolean(aiConfig),
-        model: aiConfig?.model ?? "gpt-4o-mini",
-        aiProvider: aiConfig?.provider ?? "openai",
+        model: aiConfig?.model ?? rt.ai.language.model ?? "provider default",
+        aiProvider: aiConfig?.provider ?? rt.ai.language.provider,
         tables: workspace.tables.map((table) => {
             const draft = buildTableDraft(table.physical, table.parsed);
             return {
@@ -116,16 +234,225 @@ export function serializeWorkspace(workspace) {
                 missingColumnIds: workspace.warnings
                     .filter((warning) => warning.kind === "missing_column_md" && warning.tableId === table.physical.id)
                     .map((warning) => warning.columnId),
+                escalatedByOtherFiles: table.escalatedByOtherFiles ?? [],
             };
         }),
         concepts: workspace.concepts?.frontmatter.concepts ?? [],
+        tenantPolicy: schema.tenantPolicy ?? null,
+    };
+}
+function toRelativeSchemaPath(schemaDir) {
+    const rel = relative(process.cwd(), schemaDir);
+    if (rel === "")
+        return ".";
+    if (rel.startsWith("..") || rel.includes(`..${sep}`))
+        return schemaDir;
+    return rel.startsWith(".") ? rel : `./${rel}`;
+}
+// ---------------------------------------------------------------------------
+// Setup wizard + server-side introspection (resync)
+// ---------------------------------------------------------------------------
+function requireWorkspace(state) {
+    if (!state.workspace) {
+        throw new StudioHttpError(409, "Studio is in setup mode — finish the guided setup first.");
+    }
+    return state.workspace;
+}
+function buildSetupStatus(state) {
+    const projectDir = process.cwd();
+    if (!state.setupReason) {
+        return {
+            needed: false,
+            reason: null,
+            projectDir,
+            configPath: null,
+            outputDir: state.schemaDir,
+            configLoadError: null,
+        };
+    }
+    const probe = probeSetupState(projectDir);
+    return {
+        needed: true,
+        reason: probe.hasConfig ? "no-artifact" : "no-config",
+        projectDir,
+        configPath: probe.configPath,
+        outputDir: probe.outputDir,
+        configLoadError: probe.loadError,
+    };
+}
+function handleSetupConfig(state, body) {
+    if (!state.setupReason) {
+        throw new StudioHttpError(409, "Studio is already set up — edit askdb.config.ts directly.");
+    }
+    const input = parseSetupConfigBody(body);
+    const result = writeSetupConfig(process.cwd(), input);
+    // Config now exists; the artifact usually doesn't yet.
+    const probe = probeSetupState(process.cwd());
+    if (probe.hasArtifact && probe.outputDir) {
+        state.schemaDir = probe.outputDir;
+        state.workspace = loadWorkspace(probe.outputDir);
+        state.setupReason = null;
+    }
+    else {
+        state.setupReason = "no-artifact";
+    }
+    return {
+        configPath: result.configPath,
+        envExamplePath: result.envExamplePath,
+        envVars: result.envVars,
+        installed: result.installed,
+        manualInstallCommand: result.manualInstallCommand,
+        packageJsonCreated: result.packageJsonCreated,
+        status: buildSetupStatus(state),
+    };
+}
+async function handleSetupIntrospect(state) {
+    if (!state.setupReason) {
+        throw new StudioHttpError(409, "Studio is already set up — use Resync schema instead.");
+    }
+    // probeSetupState re-bootstraps, picking up any .env created since server start.
+    const probe = probeSetupState(process.cwd());
+    if (!probe.hasConfig) {
+        throw new StudioHttpError(409, "Write askdb.config.ts first (setup step 1).");
+    }
+    if (probe.loadError || !probe.outputDir) {
+        throw new StudioHttpError(409, `askdb.config.ts exists but could not be loaded: ${probe.loadError ?? "unknown error"}. ` +
+            "Install the project dependencies shown in setup step 1, then retry.");
+    }
+    const outDir = probe.outputDir;
+    const run = await runStudioIntrospection({
+        outDir,
+        hasExistingArtifact: existsSync(join(outDir, "schema.json")),
+    });
+    state.schemaDir = outDir;
+    state.workspace = loadWorkspace(outDir);
+    state.setupReason = null;
+    return {
+        ok: true,
+        engine: run.engine,
+        schemaId: run.schemaId,
+        tables: run.tables,
+        warnings: run.warnings,
+        workspace: serializeWorkspace(state.workspace),
     };
 }
+async function handleResync(state) {
+    const workspace = requireWorkspace(state);
+    // Refresh the runtime snapshot so config edits made while Studio runs are honored.
+    try {
+        bootstrapAskDbEnv({ cwd: process.cwd() });
+    }
+    catch {
+        // Keep the snapshot the server started with when the config disappeared mid-session.
+    }
+    const run = await runStudioIntrospection({
+        outDir: state.schemaDir,
+        schemaId: workspace.physical.schemaId,
+        hasExistingArtifact: true,
+    });
+    state.workspace = loadWorkspace(state.schemaDir);
+    return {
+        ok: true,
+        engine: run.engine,
+        schemaId: run.schemaId,
+        tables: run.tables,
+        warnings: run.warnings,
+        workspace: serializeWorkspace(state.workspace),
+    };
+}
+async function buildIntrospectionPlanDto() {
+    const plan = await resolveStudioIntrospectionPlan();
+    return plan.ok
+        ? { ok: true, engine: plan.engine, sourceLabel: plan.sourceLabel }
+        : { ok: false, engine: plan.engine, error: plan.error };
+}
+function parseSetupConfigBody(body) {
+    if (!isRecord(body)) {
+        throw new StudioHttpError(400, "Request body must be a JSON object.");
+    }
+    const databases = ["postgres", "mysql", "sqlite", "sqlserver", "prisma"];
+    // Every provider with an askdb.config.* branch; @askdb/client's provider-config-drift test asserts this matches @askdb/ai's built-in table.
+    const aiProviders = ASKDB_AI_PROVIDERS;
+    const ragStores = ["file", "memory", "pgvector"];
+    const executeProviders = ["postgres", "mysql", "sqlite", "sqlserver"];
+    if (typeof body.database !== "string" || !databases.includes(body.database)) {
+        throw new StudioHttpError(400, `\`database\` must be one of: ${databases.join(", ")}.`);
+    }
+    if (typeof body.aiProvider !== "string" ||
+        !aiProviders.includes(body.aiProvider)) {
+        throw new StudioHttpError(400, `\`aiProvider\` must be one of: ${aiProviders.join(", ")}.`);
+    }
+    if (body.ragStore !== undefined && !ragStores.includes(body.ragStore)) {
+        throw new StudioHttpError(400, `\`ragStore\` must be one of: ${ragStores.join(", ")}.`);
+    }
+    if (body.studioExecuteProvider !== undefined &&
+        !executeProviders.includes(body.studioExecuteProvider)) {
+        throw new StudioHttpError(400, `\`studioExecuteProvider\` must be one of: ${executeProviders.join(", ")}.`);
+    }
+    if (body.studioExecute !== undefined && typeof body.studioExecute !== "boolean") {
+        throw new StudioHttpError(400, "`studioExecute` must be a boolean.");
+    }
+    const optionalString = (key) => {
+        const value = body[key];
+        if (value === undefined || value === null || value === "")
+            return undefined;
+        if (typeof value !== "string")
+            throw new StudioHttpError(400, `\`${key}\` must be a string.`);
+        return value;
+    };
+    return {
+        database: body.database,
+        aiProvider: body.aiProvider,
+        connectionEnv: optionalString("connectionEnv"),
+        sqliteFile: optionalString("sqliteFile"),
+        prismaSchema: optionalString("prismaSchema"),
+        aiKeyEnv: optionalString("aiKeyEnv"),
+        aiModelEnv: optionalString("aiModelEnv"),
+        schemaOut: optionalString("schemaOut"),
+        ragStore: body.ragStore,
+        pgvectorEnv: optionalString("pgvectorEnv"),
+        studioExecute: body.studioExecute,
+        studioExecuteProvider: body.studioExecuteProvider,
+        studioExecuteConnectionEnv: optionalString("studioExecuteConnectionEnv"),
+        studioExecuteSqliteFile: optionalString("studioExecuteSqliteFile"),
+    };
+}
+function saveConceptsDraft(state, concepts) {
+    saveConcepts(requireWorkspace(state), { concepts });
+    state.workspace = loadWorkspace(state.schemaDir);
+}
+function saveTenantPolicyDraft(state, frontmatter, body) {
+    // `saveTenantPolicy` refuses a policy `loadSchema` would reject (e.g. two root labels
+    // deriving one placeholder) before writing; that's the caller's mistake, so 400.
+    try {
+        saveTenantPolicy(requireWorkspace(state), frontmatter, body);
+    }
+    catch (error) {
+        if (error instanceof SchemaParseError)
+            throw new StudioHttpError(400, error.message);
+        throw error;
+    }
+    state.workspace = loadWorkspace(state.schemaDir);
+}
+function parseTenantPolicyBody(body) {
+    if (!isRecord(body) || !isRecord(body.frontmatter)) {
+        throw new StudioHttpError(400, "`frontmatter` object is required.");
+    }
+    const parsed = tenantPolicyFrontmatterSchema.safeParse(body.frontmatter);
+    if (!parsed.success) {
+        throw new StudioHttpError(400, `Invalid tenant policy: ${parsed.error.message}`);
+    }
+    const bodyText = typeof body.body === "string" ? body.body : "";
+    return { frontmatter: parsed.data, bodyText };
+}
 function saveDraft(state, tableId, draft) {
-    const table = state.workspace.tables.find((candidate) => candidate.physical.id === tableId);
+    const workspace = requireWorkspace(state);
+    const table = workspace.tables.find((candidate) => candidate.physical.id === tableId);
     if (!table)
         throw new StudioHttpError(404, `No such table: ${tableId}`);
-    const frontmatter = buildFrontmatter(table.physical, state.workspace.physical.schemaId, draft);
+    // Passing the file's current front-matter keeps entries for other tables' columns
+    // (e.g. a misplaced `sensitive: true`), which the draft does not carry.
+    const frontmatter = buildFrontmatter(table.physical, workspace.physical.schemaId, draft, table.parsed?.frontmatter);
     let body = table.parsed
         ? replaceTableDescription(table.parsed.body, draft.description)
         : buildDefaultTableBody(table.physical.name, draft.description);
@@ -135,32 +462,191 @@ function saveDraft(state, tableId, draft) {
     if (draft.exampleQuestions !== undefined) {
         body = replaceH2Section(body, "Example questions", draft.exampleQuestions);
     }
-    saveTable(state.workspace, tableId, frontmatter, body);
+    saveTable(workspace, tableId, frontmatter, body);
     state.workspace = loadWorkspace(state.schemaDir);
 }
-async function suggestForSource(workspace, source) {
+async function suggestForSource(state, source) {
     const rt = getAskDbRuntimeConfig();
-    const modelEnvVar = rt.ai.studioModel
-        ? "ASKDB_STUDIO_MODEL"
-        : rt.ai.tuiModel
-            ? "ASKDB_TUI_MODEL"
-            : undefined;
-    const model = await createAskDbLanguageModelFromEnv(rt.ai.aiEnv, {
-        modelEnvVar,
-    });
-    if (!model) {
-        throw new StudioHttpError(400, askDbAiKeyMissingMessage("AI enrichment suggestions"));
+    const aiConfig = ai.resolveAiConfig(rt.ai.aiEnv);
+    if (!aiConfig) {
+        throw new StudioHttpError(400, ai.keyMissingMessage("AI enrichment suggestions"));
+    }
+    const model = await ai.createLanguageModel(aiConfig);
+    const reasoningEffort = resolveReasoningEffort(rt.ai.aiEnv, "enrichment");
+    const providerOptions = reasoningEffort
+        ? ai.resolveProviderOptions(aiConfig, { reasoningEffort })
+        : undefined;
+    // `loadSchema()` carries effective sensitivity (front-matter escalations included), and the
+    // prompt follows `modes.omitSensitiveFromPrompt` as `ask()` does (#625, ADR 0026).
+    requireWorkspace(state);
+    const schema = loadSchema(state.schemaDir);
+    let candidates;
+    try {
+        candidates = await suggestEnrichment(buildSuggestionTarget(schema, source), buildSuggestionContext(schema, source.tableId), model, {
+            omitSensitiveIdentifiersFromPrompt: rt.modes.omitSensitiveFromPrompt,
+            ...(providerOptions ? { providerOptions } : {}),
+        });
+    }
+    catch (error) {
+        if (error instanceof SensitiveEnrichmentTargetError) {
+            throw new StudioHttpError(400, "This column is sensitive, and `modes.omitSensitiveFromPrompt` keeps sensitive columns out of the model's prompt, so Studio can't suggest for it.");
+        }
+        throw error;
     }
-    const candidates = await suggestEnrichment(buildSuggestionTarget(workspace, source), buildSuggestionContext(workspace, source.tableId), model);
     return candidates.map((candidate) => ({ text: candidate.text }));
 }
+/**
+ * The schema as the tenant-policy draft sends it to the model, with the sensitivity rules
+ * `ask()` applies (#324): `formatSchemaV2ForNlToSql` tags sensitive columns, or withholds
+ * them when `omitSensitive` is on. Only the physical layer goes in (names, types, keys and
+ * foreign keys), never descriptions, aliases or common query language, and untracked tables
+ * stay out as they do for `ask()`. A foreign key is listed only when both of its columns are.
+ * `warnings` names the primary and foreign keys withheld as sensitive, which the draft can't
+ * scope through.
+ */
+function tenantPolicySchemaForPrompt(schema, omitSensitive) {
+    const tracked = schema.tables.filter((table) => table.tracked !== false);
+    const physical = {
+        schemaId: schema.schemaId,
+        warnings: [],
+        tables: tracked.map((table) => ({
+            id: table.id,
+            name: table.name,
+            schema: table.schema,
+            sensitive: table.sensitive,
+            columns: table.columns.map((column) => ({
+                id: column.id,
+                name: column.name,
+                type: column.type,
+                nullable: column.nullable,
+                primaryKey: column.primaryKey,
+                sensitive: column.sensitive,
+            })),
+        })),
+    };
+    const { ddl } = formatSchemaV2ForNlToSql(physical, { omitSensitiveIdentifiersFromPrompt: omitSensitive });
+    // The formatter prints no foreign keys yet, so Studio lists them, mirroring the formatter's
+    // omission rule (packages/core/src/schema/v2/format.ts): a column is withheld when omission
+    // is on and it is sensitive, which `loadSchema()` sets on every column of a sensitive table.
+    // When core prints foreign keys (#349, step 5), use its lines and delete this block (ADR 0021).
+    const names = new Map();
+    const withheld = new Set();
+    for (const table of schema.tables) {
+        for (const column of table.columns) {
+            names.set(column.id, `${table.schema}.${table.name}.${column.name}`);
+            if (omitSensitive && column.sensitive)
+                withheld.add(column.id);
+        }
+    }
+    const nameOf = (id) => names.get(id) ?? id;
+    const listed = new Set();
+    const withheldKeys = [];
+    for (const table of tracked) {
+        for (const column of table.columns) {
+            if (!withheld.has(column.id))
+                listed.add(column.id);
+            else if (column.primaryKey)
+                withheldKeys.push(`${nameOf(column.id)} (primary key)`);
+        }
+    }
+    const foreignKeys = [];
+    for (const fk of tracked.flatMap((table) => table.relationships ?? [])) {
+        if (listed.has(fk.from) && listed.has(fk.to))
+            foreignKeys.push(`- ${fk.from} -> ${fk.to}`);
+        else if (withheld.has(fk.from) || withheld.has(fk.to)) {
+            withheldKeys.push(`${nameOf(fk.from)} → ${nameOf(fk.to)} (foreign key)`);
+        }
+    }
+    const warnings = withheldKeys.length > 0
+        ? [
+            `Withheld from the model because they're marked sensitive: ${withheldKeys.join(", ")}. ` +
+                "If any of them carries tenant scope, add it to the policy by hand.",
+        ]
+        : [];
+    return {
+        schemaId: schema.schemaId,
+        schemaDdl: foreignKeys.length > 0 ? `${ddl}\n\nForeign keys:\n${foreignKeys.join("\n")}` : ddl,
+        tableIds: tracked.map((table) => table.id),
+        warnings,
+    };
+}
+async function suggestTenantPolicyDraft(state) {
+    const rt = getAskDbRuntimeConfig();
+    const model = await ai.createLanguageModelFromEnv(rt.ai.aiEnv);
+    if (!model) {
+        throw new StudioHttpError(400, ai.keyMissingMessage("AI tenant policy suggestion"));
+    }
+    requireWorkspace(state);
+    const { schemaId, schemaDdl, tableIds, warnings } = tenantPolicySchemaForPrompt(loadSchema(state.schemaDir), rt.modes.omitSensitiveFromPrompt);
+    const systemPrompt = `You are an expert database architect specializing in multi-tenant SaaS systems.
+You analyze database schemas and produce a tenant-policy configuration in a specific JSON format.
+
+The tenant policy identifies:
+1. **roots** — Tables whose rows represent tenants (organizations, companies, accounts, etc).
+   Each root has: id (table ID like "table:public.orgs"), tenantIdColumn (column ref like "table:public.orgs#id"), label (human-readable name).
+   If a root has a parent root (e.g. sub_org belongs to org), include parent: { root: "<parent-root-id>", foreignKey: "<fk-column-ref>" }.
+2. **hierarchy** — Edges showing parent→child relationships between roots or tenant-scoped tables.
+   Each edge: { parent: "<table-id>", child: "<table-id>", foreignKey: "<child-fk-column-ref>" }.
+3. **scopedTables** — Tables that belong to a tenant via a direct column or a JOIN chain.
+   Each entry: { id: "<table-id>", scopeThrough: [{ root: "<root-id>", column: "<column-ref>" }] } for direct FK,
+   or { id: "<table-id>", scopeThrough: [{ root: "<root-id>", join: [{ from: "<col-ref>", to: "<col-ref>" }] }] } for indirect.
+4. **polymorphicTables** — Tables with a type/id polymorphic association pattern.
+   Each entry: { id: "<table-id>", typeColumn: "<col-ref>", idColumn: "<col-ref>", mapping: { "<type_value>": "<target-table-id>" } }.
+5. **globalTables** — Tables shared across all tenants (lookup tables, reference data). Array of table IDs.
+6. **enforcement** — "strict" (reject queries on unknown tables) or "warn" (allow with warnings).
+
+Column references use the format "table:<schema>.<table>#<column>".
+Table IDs use the format "table:<schema>.<table>".
+
+Available table IDs: ${JSON.stringify(tableIds)}
+
+Return a JSON object with two keys:
+- "frontmatter": the TenantPolicyFrontmatter object (schemaId, enforcement, roots, hierarchy?, scopedTables?, polymorphicTables?, globalTables?)
+- "body": a markdown body string with sections "## Hierarchy", "## Scope rules", "## Sensitive interactions" explaining the policy in plain English.
+
+Return ONLY valid JSON, no markdown fences or explanations.`;
+    const userPrompt = `Analyze this database schema and draft a complete multi-tenant policy.
+
+Schema ID: ${schemaId}
+
+${schemaDdl}
+
+Look for:
+- Tables that represent organizations, companies, accounts, tenants, or workspaces — these are roots.
+- Foreign key columns like org_id, company_id, tenant_id, account_id that scope data to a tenant.
+- Tables with no tenant FK that are clearly shared/global (lookup tables, enums, config).
+- Polymorphic association patterns (type_column + id_column pointing to multiple parent tables).
+- Multi-level hierarchies (org → team → user, company → department → employee).
+
+If the schema has no clear multi-tenant pattern, still make your best guess at what would be the tenant root.`;
+    const result = await defaultGenerateText({
+        model,
+        instructions: systemPrompt,
+        prompt: userPrompt,
+    });
+    let parsed;
+    try {
+        parsed = JSON.parse(result.text);
+    }
+    catch {
+        throw new StudioHttpError(500, `AI returned invalid JSON for tenant policy suggestion. Raw text: ${result.text.slice(0, 500)}`);
+    }
+    // Validate frontmatter shape
+    const validation = tenantPolicyFrontmatterSchema.safeParse(parsed.frontmatter);
+    if (!validation.success) {
+        throw new StudioHttpError(500, `AI-generated tenant policy frontmatter is invalid: ${validation.error.issues.map((i) => i.message).join("; ")}`);
+    }
+    return { frontmatter: validation.data, body: parsed.body, warnings };
+}
 async function askSampleQuestion(state, options) {
     const rt = getAskDbRuntimeConfig();
     const mockSql = rt.dev.mockSql;
-    const aiConfig = mockSql ? undefined : resolveAskDbAiConfig(rt.ai.aiEnv);
+    const aiConfig = mockSql ? undefined : ai.resolveAiConfig(rt.ai.aiEnv);
     if (!mockSql && !aiConfig) {
-        throw new StudioHttpError(400, `${askDbAiKeyMissingMessage("Sample NL-to-SQL generation")} Set ASKDB_MOCK_SQL to bypass the live model.`);
+        throw new StudioHttpError(400, `${ai.keyMissingMessage("Sample NL-to-SQL generation")} Set dev.mockSql in askdb.config to bypass the live model.`);
     }
+    const reasoningEffort = mockSql ? undefined : resolveReasoningEffort(rt.ai.aiEnv, "nlToSql");
+    const providerOptions = aiConfig && reasoningEffort ? ai.resolveProviderOptions(aiConfig, { reasoningEffort }) : undefined;
     const schema = loadSchema(state.schemaDir);
     const retrievedChunks = [];
     const usage = createRequestUsageCollector();
@@ -169,9 +655,7 @@ async function askSampleQuestion(state, options) {
         : undefined;
     const model = mockSql
         ? undefined
-        : (await createAskDbLanguageModelFromEnv(rt.ai.aiEnv, {
-            modelEnvVar: rt.ai.studioModel ? "ASKDB_STUDIO_MODEL" : undefined,
-        }));
+        : (await ai.createLanguageModelFromEnv(rt.ai.aiEnv));
     const schemaProvider = "provider" in schema && typeof schema.provider === "string"
         ? schema.provider
         : undefined;
@@ -183,6 +667,11 @@ async function askSampleQuestion(state, options) {
         model,
         dialect,
         explain: true,
+        // `ask()` doesn't read config, so each host applies `modes.omitSensitiveFromPrompt`
+        // itself, as `@askdb/client` does (#601).
+        ...(rt.modes.omitSensitiveFromPrompt ? { omitSensitiveIdentifiersFromNlToSqlPrompt: true } : {}),
+        ...(options.tenantScope ? { tenantScope: options.tenantScope } : {}),
+        ...(options.tenantSqlMode ? { tenantSqlMode: options.tenantSqlMode } : {}),
         ...(ragIndex
             ? {
                 retriever: async (params) => {
@@ -207,6 +696,7 @@ async function askSampleQuestion(state, options) {
             }
             : {
                 generateText: createTrackedGenerateText(usage),
+                ...(providerOptions ? { providerOptions } : {}),
             },
     }).finally(async () => {
         await ragIndex?.dispose();
@@ -219,6 +709,14 @@ async function askSampleQuestion(state, options) {
             enabled: options.useRag,
             chunks: options.useRag ? retrievedChunks.map(serializeRagResult) : [],
         },
+        tenant: options.tenantScope
+            ? {
+                enabled: true,
+                sqlMode: options.tenantSqlMode ?? DEFAULT_TENANT_SQL_MODE,
+                bindings: result.tenantBindings ?? [],
+                params: result.tenantParams ?? [],
+            }
+            : null,
         usage: usage.toDto(),
     };
 }
@@ -227,14 +725,17 @@ async function getRagStatus(state) {
     const sources = loadChunkerSourcesFromDir(state.schemaDir);
     const chunkResult = chunkSchema(sources);
     const lockPath = join(state.schemaDir, "schema.lock.json");
-    const lock = readOptionalJson(lockPath);
+    const lock = resolveStudioRagStoreConfig(state).kind === "memory"
+        ? state.ragMemoryIndex
+        : readOptionalJson(lockPath);
     const currentHashes = Object.fromEntries(chunkResult.chunks.map((chunk) => [chunk.id, chunkContentHash(chunk.text)]));
     const lockHashes = lock?.hashes ?? {};
     const hashIds = Object.keys(currentHashes);
-    const store = await openStudioRagStore(state, config.dimensions);
+    const store = await openStudioRagStore(state, { dimensions: config.dimensions });
     try {
         const chunksIndexed = await countStudioRagStoreChunks(store, sources.schema.schemaId);
         const stale = !lock ||
+            lock.incomplete === true ||
             lock.embedderId !== config.embedderId ||
             Object.keys(lockHashes).length !== hashIds.length ||
             hashIds.some((id) => lockHashes[id] !== currentHashes[id]) ||
@@ -275,8 +776,9 @@ async function getRagStatus(state) {
             updatedAt: lock?.updatedAt ?? null,
             chunksTotal: chunkResult.chunks.length,
             chunksIndexed,
-            dimensions: config.dimensions,
-            expectedDimensions: config.dimensions,
+            // The width the last index build learned from the model, else the one configured.
+            dimensions: lock?.dimensions ?? config.dimensions ?? null,
+            expectedDimensions: config.dimensions ?? null,
             sensitiveExcluded: chunkResult.stats.sensitiveExcluded,
             sensitiveIncluded: chunkResult.stats.sensitiveIncluded,
             files: fileArtifacts,
@@ -289,27 +791,40 @@ async function getRagStatus(state) {
 async function indexRag(state) {
     const config = resolveStudioRagEmbedderConfig();
     if (!config.configured) {
-        throw new StudioHttpError(400, studioRagAiSdkKeyMissingMessage());
+        throw new StudioHttpError(400, studioRagAiSdkKeyMissingMessage(config));
     }
     const usage = createRequestUsageCollector();
     clearIncompatibleRagStore(state, config);
     const sources = loadChunkerSourcesFromDir(state.schemaDir);
-    const store = await openStudioRagStore(state, config.dimensions);
+    const embedder = await createStudioRagEmbedder(config, usage);
     let result;
+    let store;
     try {
+        // A new pgvector table needs its width up front: the configured one, else the model's own.
+        const dimensions = config.dimensions ??
+            (resolveStudioRagStoreConfig(state).kind === "pgvector" ? await detectEmbeddingDimensions(embedder) : undefined);
+        store = await openStudioRagStore(state, { dimensions, provision: true });
         result = await buildSchemaIndex({
             schema: sources,
-            embedder: await createStudioRagEmbedder(config, usage),
+            embedder,
             store: store.store,
             embedderId: config.embedderId,
             lockFilePath: join(state.schemaDir, "schema.lock.json"),
         });
+        if (store.kind === "memory") {
+            state.ragMemoryIndex = {
+                embedderId: config.embedderId,
+                updatedAt: new Date().toISOString(),
+                dimensions: store.store.describe?.().dimensions,
+                hashes: Object.fromEntries(result.chunks.map((chunk) => [chunk.id, chunkContentHash(chunk.text)])),
+            };
+        }
     }
     catch (error) {
         throw formatStudioRagOperationError(error, config);
     }
     finally {
-        await store.dispose();
+        await store?.dispose();
     }
     return {
         status: await getRagStatus(state),
@@ -347,7 +862,7 @@ async function queryRag(state, query) {
 async function createCurrentStudioRagIndex(state, action, usage) {
     const config = resolveStudioRagEmbedderConfig();
     if (!config.configured) {
-        throw new StudioHttpError(400, studioRagAiSdkKeyMissingMessage());
+        throw new StudioHttpError(400, studioRagAiSdkKeyMissingMessage(config));
     }
     const status = (await getRagStatus(state));
     if (!status.hasIndex) {
@@ -359,7 +874,7 @@ async function createCurrentStudioRagIndex(state, action, usage) {
     if (!status.schemaId || typeof status.chunksTotal !== "number") {
         throw new StudioHttpError(500, "Studio RAG status is missing schema metadata.");
     }
-    const store = await openStudioRagStore(state, config.dimensions);
+    const store = await openStudioRagStore(state, { dimensions: config.dimensions });
     return {
         config,
         status: {
@@ -377,22 +892,26 @@ async function createCurrentStudioRagIndex(state, action, usage) {
 }
 function resolveStudioRagStoreConfig(state) {
     const rt = getAskDbRuntimeConfig();
-    const kind = rt.structured.rag.store;
+    const kind = rt.rag.store;
     if (kind === "memory")
         return { kind };
     if (kind === "file") {
-        const basePath = rt.structured.rag.storeConfig.file?.basePath?.trim();
+        const basePath = rt.rag.storeConfig.file?.basePath?.trim();
         return { kind, basePath: basePath ? resolve(basePath) : join(state.schemaDir, "schema") };
     }
     const connectionString = pickFlat(rt.flat, "ASKDB_PGVECTOR_URL");
     return {
         kind,
         connectionString,
-        table: rt.structured.rag.storeConfig.pgvector?.table?.trim() || undefined,
+        table: rt.rag.storeConfig.pgvector?.table?.trim() || undefined,
         indexStrategy: pickFlat(rt.flat, "ASKDB_PGVECTOR_INDEX_STRATEGY"),
     };
 }
-async function openStudioRagStore(state, dimensions) {
+/**
+ * Opens the configured store. `provision` creates the pgvector table when it's missing, at
+ * `dimensions`; without it, a pgvector store only reads and writes an existing table.
+ */
+async function openStudioRagStore(state, { dimensions, provision = false }) {
     const config = resolveStudioRagStoreConfig(state);
     if (config.kind === "memory") {
         state.ragMemoryStore ??= createMemoryStore();
@@ -420,9 +939,19 @@ async function openStudioRagStore(state, dimensions) {
     const store = pgvectorFactory({
         connectionString: config.connectionString,
         table: config.table,
-        dimensions,
+        ...(dimensions !== undefined ? { dimensions } : {}),
         ...(config.indexStrategy ? { indexStrategy: config.indexStrategy } : {}),
     });
+    if (provision) {
+        try {
+            await store.ensureSchema();
+        }
+        catch (error) {
+            // The caller never receives this store, so close its pool here (a width refusal has opened it).
+            await store.close().catch(() => { });
+            throw error;
+        }
+    }
     return {
         kind: "pgvector",
         store,
@@ -434,6 +963,10 @@ async function openStudioRagStore(state, dimensions) {
     };
 }
 async function countStudioRagStoreChunks(store, schemaId) {
+    // A pgvector table that doesn't exist yet holds nothing; the first index build creates it.
+    if (typeof store.store.tableDimensions === "function" && (await store.store.tableDimensions()) === undefined) {
+        return 0;
+    }
     if (typeof store.store.count === "function") {
         return store.store.count({ schemaId });
     }
@@ -446,16 +979,9 @@ function pickFlat(flat, key) {
     const value = flat[key];
     return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
 }
-function pickEnv(env, key) {
-    const v = env[key];
-    return typeof v === "string" && v.trim() !== "" ? v.trim() : undefined;
-}
 function resolveStudioRagEmbedderConfig() {
-    const rt = getAskDbRuntimeConfig();
-    const base = rt.ai.aiEnv;
-    const explicitKind = pickEnv(base, "ASKDB_RAG_EMBEDDER") ?? pickEnv(base, "ASKDB_STUDIO_RAG_EMBEDDER");
-    const kind = explicitKind?.toLowerCase();
-    if (kind === "mock") {
+    const embedding = getAskDbRuntimeConfig().ai.embedding;
+    if (!embedding) {
         return {
             kind: "mock",
             embedderId: STUDIO_RAG_MOCK_EMBEDDER_ID,
@@ -464,72 +990,40 @@ function resolveStudioRagEmbedderConfig() {
             label: "Mock lexical",
         };
     }
-    if (kind !== undefined && kind !== "ai-sdk" && kind !== "openai") {
-        throw new StudioHttpError(400, `Unsupported Studio RAG embedder: ${kind}`);
-    }
-    const env = buildStudioRagEmbeddingEnv(kind, base);
-    const aiConfig = resolveAskDbEmbeddingConfig(env, {
-        modelEnvVar: "ASKDB_STUDIO_RAG_EMBEDDER_MODEL",
-        modelDefault: DEFAULT_EMBEDDING_MODEL,
-    });
-    if (!aiConfig && kind === undefined) {
-        return {
-            kind: "mock",
-            embedderId: STUDIO_RAG_MOCK_EMBEDDER_ID,
-            dimensions: STUDIO_RAG_MOCK_DIMENSIONS,
-            configured: true,
-            label: "Mock lexical",
-        };
-    }
-    const provider = aiConfig?.provider ?? fallbackStudioRagProvider(kind, base);
-    const model = aiConfig?.model ?? DEFAULT_EMBEDDING_MODEL;
-    const dimensionOverride = readPositiveIntegerEnv(pickEnv(base, "ASKDB_RAG_EMBEDDER_DIMENSIONS") ??
-        pickEnv(base, "ASKDB_STUDIO_RAG_EMBEDDER_DIMENSIONS"));
-    const dimensions = dimensionOverride ?? defaultEmbeddingDimensions(model);
+    // The env holds the embedding connection only, so no other provider's key can reach it (#345).
+    const aiConfig = ai.resolveEmbeddingConfig(embedding.env);
+    // The adapter's canonical name (`foundry` resolves to `azure`) keeps existing index ids stable.
+    const provider = aiConfig?.provider ?? embedding.provider;
+    const model = embedding.model;
+    const dimensions = embedding.dimensions;
     return {
         kind: "ai-sdk",
         provider,
-        embedderId: `ai-sdk:${provider}:${model}:${dimensions}`,
+        configuredProvider: embedding.provider,
+        connection: embedding.connection,
+        embedderId: aiSdkEmbedderId({ provider, model, dimensions }),
         dimensions,
         configured: Boolean(aiConfig),
         label: `AI SDK (${provider})`,
         model,
         baseUrl: aiConfig?.baseURL,
         aiConfig,
-        requestDimensions: dimensionOverride,
-    };
-}
-function buildStudioRagEmbeddingEnv(kind, base) {
-    const apiKeyOverride = pickEnv(base, "ASKDB_RAG_EMBEDDER_API_KEY") ?? pickEnv(base, "ASKDB_STUDIO_RAG_EMBEDDER_API_KEY");
-    const modelOverride = pickEnv(base, "ASKDB_RAG_EMBEDDER_MODEL") ?? pickEnv(base, "ASKDB_STUDIO_RAG_EMBEDDER_MODEL");
-    const baseUrlOverride = pickEnv(base, "ASKDB_RAG_EMBEDDER_BASE_URL") ?? pickEnv(base, "ASKDB_STUDIO_RAG_EMBEDDER_BASE_URL");
-    return {
-        ...base,
-        ...(kind === "openai" ? { ASKDB_AI_PROVIDER: "openai" } : {}),
-        ...(apiKeyOverride ? { ASKDB_AI_API_KEY: apiKeyOverride } : {}),
-        ...(modelOverride ? { ASKDB_STUDIO_RAG_EMBEDDER_MODEL: modelOverride } : {}),
-        ...(baseUrlOverride ? { ASKDB_AI_BASE_URL: baseUrlOverride } : {}),
+        // Only an explicit ai.embedding.dimensions is sent; otherwise the model's own width applies.
+        requestDimensions: embedding.dimensions,
     };
 }
-function fallbackStudioRagProvider(kind, base) {
-    if (kind === "openai")
-        return "openai";
-    const raw = (pickEnv(base, "ASKDB_AI_PROVIDER") ?? "").toLowerCase();
-    return raw === "azure" || raw === "azure-openai" || raw === "foundry"
-        ? "azure"
-        : "openai";
-}
-function studioRagAiSdkKeyMissingMessage() {
-    return ("Studio RAG AI SDK embeddings require a configured AI provider key. " +
-        "Set ASKDB_AI_API_KEY or the provider-native key, or set ASKDB_RAG_EMBEDDER=mock for the local lexical embedder.");
+function studioRagAiSdkKeyMissingMessage(config) {
+    return (`Studio RAG embeddings need an API key on the ai.embedding connection ` +
+        `("${config.connection}" in ai.providerConfig.${config.configuredProvider}). ` +
+        'Set it in askdb.config.*, or set rag.embedder: "mock" for the local lexical embedder.');
 }
 async function createStudioRagEmbedder(config, usage) {
     if (config.kind === "mock")
         return createStudioMockEmbedder(config.dimensions);
     if (!config.aiConfig) {
-        throw new StudioHttpError(400, studioRagAiSdkKeyMissingMessage());
+        throw new StudioHttpError(400, studioRagAiSdkKeyMissingMessage(config));
     }
-    const model = await createAskDbEmbeddingModel(config.aiConfig, {
+    const model = await ai.createEmbeddingModel(config.aiConfig, {
         dimensions: config.requestDimensions,
     });
     return createAiSdkEmbedder({
@@ -547,6 +1041,9 @@ async function createStudioRagEmbedder(config, usage) {
 function formatStudioRagOperationError(error, config) {
     if (error instanceof StudioHttpError)
         return error;
+    if (error instanceof PgvectorDimensionMismatchError) {
+        return new StudioHttpError(409, studioRagWidthMismatchMessage(error, config));
+    }
     if (config.kind === "mock") {
         return new StudioHttpError(500, error instanceof Error ? error.message : String(error));
     }
@@ -555,7 +1052,7 @@ function formatStudioRagOperationError(error, config) {
         return new StudioHttpError(500, error instanceof Error ? error.message : String(error));
     }
     const parts = [
-        `Studio RAG embedding request failed for provider ${config.provider}, model ${config.model}.`,
+        `Studio RAG embedding request failed for ai.embedding (provider ${config.configuredProvider}, connection ${config.connection}, model ${config.model}).`,
     ];
     if (config.baseUrl)
         parts.push(`Base URL: ${config.baseUrl}.`);
@@ -568,6 +1065,20 @@ function formatStudioRagOperationError(error, config) {
         parts.push(`Error: ${error.message}`);
     return new StudioHttpError(502, parts.join(" "));
 }
+/** An existing pgvector table of another width: say where the new width comes from and how to resolve it, in config terms. */
+function studioRagWidthMismatchMessage(error, config) {
+    const mismatch = `pgvector table "${error.table}" holds ${error.tableDimensions}-dimension vectors, but`;
+    const rebuild = `Drop the table (DROP TABLE "${error.table}";) and build the index again`;
+    const newTable = "point rag.storeConfig.pgvector.table at a new table";
+    if (config.kind === "mock") {
+        return `${mismatch} the mock embedder writes ${error.dimensions}. ${rebuild}, or ${newTable}.`;
+    }
+    const source = config.dimensions !== undefined
+        ? `ai.embedding.dimensions asks for ${error.dimensions}`
+        : `embedding model ${config.model} returns ${error.dimensions}`;
+    return (`${mismatch} ${source}. ${rebuild}, ${newTable}, ` +
+        `or set ai.embedding.dimensions: ${error.tableDimensions} if model ${config.model} supports that width.`);
+}
 function findApiCallError(error) {
     const queue = [error];
     for (let i = 0; i < queue.length; i++) {
@@ -602,30 +1113,20 @@ function clearIncompatibleRagStore(state, config) {
         return;
     const embeddingsJsonPath = `${store.basePath}.embeddings.json`;
     const embeddings = readOptionalJson(embeddingsJsonPath);
-    if (embeddings?.dimensions === undefined || embeddings.dimensions === config.dimensions)
+    if (embeddings?.dimensions === undefined)
+        return;
+    // The file store refuses mixed widths. When the width isn't known up front, vectors from a
+    // different embedder may not match it, so they go too.
+    const lockPath = join(state.schemaDir, "schema.lock.json");
+    const compatible = config.dimensions !== undefined
+        ? embeddings.dimensions === config.dimensions
+        : readOptionalJson(lockPath)?.embedderId === config.embedderId;
+    if (compatible)
         return;
-    for (const path of [
-        `${store.basePath}.embeddings.json`,
-        `${store.basePath}.embeddings.bin`,
-        join(state.schemaDir, "schema.lock.json"),
-    ]) {
+    for (const path of [`${store.basePath}.embeddings.json`, `${store.basePath}.embeddings.bin`, lockPath]) {
         rmSync(path, { force: true });
     }
 }
-function defaultEmbeddingDimensions(model) {
-    if (model === "text-embedding-3-large")
-        return 3072;
-    return 1536;
-}
-function readPositiveIntegerEnv(value) {
-    if (value === undefined || value.trim() === "")
-        return undefined;
-    const parsed = Number(value);
-    if (!Number.isInteger(parsed) || parsed <= 0) {
-        throw new StudioHttpError(400, `Invalid Studio RAG embedding dimensions: ${value}`);
-    }
-    return parsed;
-}
 function serializeRagResult(result) {
     return {
         id: result.id,
@@ -657,6 +1158,401 @@ function stableTokenHash(token) {
     }
     return hash >>> 0;
 }
+// ---------------------------------------------------------------------------
+// Playground history helpers
+// ---------------------------------------------------------------------------
+const HISTORY_MAX_STORED = 200;
+const HISTORY_MAX_RETURNED = 50;
+const HISTORY_FILE_NAME = "playground-history.json";
+function playgroundHistoryPath(schemaDir) {
+    return join(schemaDir, HISTORY_FILE_NAME);
+}
+function readPlaygroundHistory(schemaDir) {
+    const raw = readOptionalJson(playgroundHistoryPath(schemaDir));
+    const entries = Array.isArray(raw) ? raw : [];
+    return { entries: entries.slice(0, HISTORY_MAX_RETURNED) };
+}
+function appendPlaygroundHistory(schemaDir, entry) {
+    const histPath = playgroundHistoryPath(schemaDir);
+    const raw = readOptionalJson(histPath);
+    const existing = Array.isArray(raw)
+        ? raw
+        : [];
+    const newEntry = {
+        ...entry,
+        id: randomUUID(),
+        timestamp: new Date().toISOString(),
+    };
+    const updated = [newEntry, ...existing].slice(0, HISTORY_MAX_STORED);
+    ensureSchemaDirGitignore(schemaDir);
+    saveSchemaFile(schemaDir, HISTORY_FILE_NAME, JSON.stringify(updated, null, 2));
+}
+/**
+ * Keep Playground history (questions + generated SQL, local-only) out of git.
+ * The schema artifact directory is meant to be committed, so Studio makes sure
+ * its `.gitignore` lists `playground-history.json` before writing the file.
+ *
+ * - No `.gitignore` yet: write one that also ignores `.env` files — the same
+ *   rules `askdb init` writes (plan 043) — unless the schema dir is the project
+ *   root, where ignoring `.env` is the project's call, not Studio's.
+ * - Existing `.gitignore` without the entry: add the entry at the end and keep
+ *   every existing byte as it was.
+ * - Both are saved with `saveSchemaFile()`, so a `.gitignore` that is a symbolic
+ *   link is refused, not written through (ADR 0028).
+ * - Failure is non-fatal: history still saves.
+ */
+function ensureSchemaDirGitignore(schemaDir) {
+    const gitignorePath = join(schemaDir, ".gitignore");
+    try {
+        if (existsSync(gitignorePath)) {
+            // Kept as bytes: Git matches patterns byte for byte, and a non-UTF-8 file name
+            // in an existing line must survive the rewrite.
+            const content = readFileSync(gitignorePath);
+            const lines = content.toString("utf8").split(/\r?\n/).map((line) => line.trim());
+            if (lines.includes(HISTORY_FILE_NAME) || lines.includes(`/${HISTORY_FILE_NAME}`))
+                return;
+            const separator = content.length === 0 || content.at(-1) === 0x0a ? "" : "\n";
+            const entry = `${separator}# AskDB Studio Playground history (local only)\n${HISTORY_FILE_NAME}\n`;
+            saveSchemaFile(schemaDir, ".gitignore", Buffer.concat([content, Buffer.from(entry, "utf8")]));
+            return;
+        }
+        const lines = [
+            "# Written by AskDB Studio.",
+            "#",
+            "# The schema artifact in this directory is meant to be committed: schema.json",
+            "# plus any enrichment you author in Studio. Playground history (your questions",
+            "# and generated SQL) is local only.",
+            HISTORY_FILE_NAME,
+        ];
+        if (!isProjectRootDir(schemaDir)) {
+            lines.push("", "# Credentials: keep API keys and connection strings out of version control", "# even when they live here.", ".env", ".env.*", "!.env.example");
+        }
+        saveSchemaFile(schemaDir, ".gitignore", `${lines.join("\n")}\n`);
+    }
+    catch {
+        // Non-fatal: the history write matters more than this defensive file.
+    }
+}
+function isProjectRootDir(dir) {
+    if (existsSync(join(dir, "package.json")))
+        return true;
+    try {
+        return readdirSync(dir).some((name) => name.startsWith("askdb.config."));
+    }
+    catch {
+        return false;
+    }
+}
+function deletePlaygroundHistoryEntry(schemaDir, id) {
+    const histPath = playgroundHistoryPath(schemaDir);
+    const raw = readOptionalJson(histPath);
+    const existing = Array.isArray(raw)
+        ? raw
+        : [];
+    const filtered = existing.filter((e) => e.id !== id);
+    if (filtered.length === existing.length) {
+        return { ok: false, error: "not found" };
+    }
+    saveSchemaFile(schemaDir, HISTORY_FILE_NAME, JSON.stringify(filtered, null, 2));
+    return { ok: true };
+}
+const HISTORY_LIMITS = {
+    question: 4_000,
+    sql: 100_000,
+    explain: 100_000,
+    /** Serialized JSON size for `tenantScope` / `tenantParams`. */
+    json: 20_000,
+    error: 2_000,
+    ragChunkIds: 200,
+    ragChunkId: 512,
+};
+/**
+ * Validate a history entry and copy **only** the known fields — the file is
+ * written inside the schema artifact directory, so nothing unexpected (or
+ * unbounded) from the request body may be persisted.
+ */
+function parsePlaygroundHistoryEntry(body) {
+    if (!isRecord(body)) {
+        throw new StudioHttpError(400, "Request body must be a JSON object.");
+    }
+    const question = requireBoundedString(body.question, "question", HISTORY_LIMITS.question);
+    if (question.trim() === "") {
+        throw new StudioHttpError(400, "`question` is required.");
+    }
+    if (body.mode !== "full" && body.mode !== "rag") {
+        throw new StudioHttpError(400, "`mode` must be `full` or `rag`.");
+    }
+    if (body.sqlMode !== "sql-only" && body.sqlMode !== "sql-params") {
+        throw new StudioHttpError(400, "`sqlMode` must be `sql-only` or `sql-params`.");
+    }
+    const entry = {
+        question,
+        mode: body.mode,
+        sqlMode: body.sqlMode,
+        sql: requireBoundedString(body.sql, "sql", HISTORY_LIMITS.sql),
+    };
+    if (body.explain !== undefined && body.explain !== null) {
+        entry.explain = requireBoundedString(body.explain, "explain", HISTORY_LIMITS.explain);
+    }
+    if (body.tenantScope !== undefined && body.tenantScope !== null) {
+        entry.tenantScope = requireBoundedJsonObject(body.tenantScope, "tenantScope");
+    }
+    if (body.tenantParams !== undefined && body.tenantParams !== null) {
+        entry.tenantParams = requireBoundedJsonObject(body.tenantParams, "tenantParams");
+    }
+    if (body.executionResult !== undefined && body.executionResult !== null) {
+        const r = body.executionResult;
+        if (!isRecord(r) ||
+            !isNonNegativeFinite(r.rowCount) ||
+            !isNonNegativeFinite(r.durationMs) ||
+            typeof r.truncated !== "boolean") {
+            throw new StudioHttpError(400, "`executionResult` must be { rowCount: number, durationMs: number, truncated: boolean, error?: string }.");
+        }
+        entry.executionResult = {
+            rowCount: r.rowCount,
+            durationMs: r.durationMs,
+            truncated: r.truncated,
+            ...(r.error !== undefined
+                ? { error: requireBoundedString(r.error, "executionResult.error", HISTORY_LIMITS.error) }
+                : {}),
+        };
+    }
+    if (body.ragChunkIds !== undefined && body.ragChunkIds !== null) {
+        if (!Array.isArray(body.ragChunkIds) ||
+            body.ragChunkIds.length > HISTORY_LIMITS.ragChunkIds ||
+            !body.ragChunkIds.every((id) => typeof id === "string" && id.length <= HISTORY_LIMITS.ragChunkId)) {
+            throw new StudioHttpError(400, `\`ragChunkIds\` must be an array of at most ${HISTORY_LIMITS.ragChunkIds} strings.`);
+        }
+        entry.ragChunkIds = [...body.ragChunkIds];
+    }
+    return entry;
+}
+function requireBoundedString(value, field, maxLength) {
+    if (typeof value !== "string") {
+        throw new StudioHttpError(400, `\`${field}\` must be a string.`);
+    }
+    if (value.length > maxLength) {
+        throw new StudioHttpError(400, `\`${field}\` is too long (max ${maxLength} characters).`);
+    }
+    return value;
+}
+function requireBoundedJsonObject(value, field) {
+    if (!isRecord(value)) {
+        throw new StudioHttpError(400, `\`${field}\` must be a JSON object.`);
+    }
+    if (JSON.stringify(value).length > HISTORY_LIMITS.json) {
+        throw new StudioHttpError(400, `\`${field}\` is too large (max ${HISTORY_LIMITS.json} characters as JSON).`);
+    }
+    return value;
+}
+function isNonNegativeFinite(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+// ---------------------------------------------------------------------------
+// Execute endpoint helpers
+// ---------------------------------------------------------------------------
+const EXECUTE_DISABLED_MESSAGE = "Studio execute is off. To run generated SQL from the Playground, set `studio.execute.enabled: true` " +
+    "and an execute connection (`studio.execute.databaseUrl`, or `studio.execute.file` for SQLite) in " +
+    "askdb.config.ts, ideally for a read-only database role, then restart Studio.";
+function executeNotConfiguredMessage(exec) {
+    const field = exec.provider === "sqlite" ? "studio.execute.file" : "studio.execute.databaseUrl";
+    const base = `No execute connection configured. Set \`${field}\` in askdb.config.ts (ideally a read-only database role).`;
+    return exec.introspectionConnectionAvailable
+        ? `${base} Studio no longer reuses the introspection connection by default; set \`studio.execute.useIntrospectionConnection: true\` to opt in.`
+        : base;
+}
+async function getExecuteStatus(schemaDir) {
+    const rt = getAskDbRuntimeConfig();
+    const exec = rt.studio.execute;
+    const { provider, databaseUrl, file } = exec;
+    const def = EXECUTE_DRIVER_REGISTRY[provider];
+    const projectRoot = findProjectRoot(schemaDir) ?? schemaDir;
+    const installed = isDriverInstalled(def.packageName, projectRoot);
+    const connectionKind = provider === "sqlite" ? "file" : "url";
+    const configured = connectionKind === "file" ? Boolean(file) : Boolean(databaseUrl);
+    const disabledReason = !exec.enabled
+        ? EXECUTE_DISABLED_MESSAGE
+        : !configured
+            ? executeNotConfiguredMessage(exec)
+            : null;
+    return {
+        enabled: exec.enabled,
+        disabledReason,
+        timeoutMs: exec.timeoutMs,
+        maxRows: exec.maxRows,
+        provider,
+        label: def.label,
+        configured,
+        connectionKind,
+        packageName: def.packageName,
+        installed,
+        installCommand: def.installCommand,
+        canInstallFromStudio: exec.enabled,
+        manualInstallReason: null,
+    };
+}
+async function installExecuteDriver(body, schemaDir) {
+    const rt = getAskDbRuntimeConfig();
+    if (!rt.studio.execute.enabled) {
+        throw new StudioHttpError(403, EXECUTE_DISABLED_MESSAGE);
+    }
+    // Accept the configured provider or an explicit allowlisted provider. `Object.hasOwn`
+    // (via isStudioExecuteProvider) rejects inherited keys such as "constructor".
+    let provider = rt.studio.execute.provider;
+    if (isRecord(body) && body.provider !== undefined) {
+        if (!isStudioExecuteProvider(body.provider)) {
+            throw new StudioHttpError(400, `Unknown provider: ${JSON.stringify(body.provider)}. Expected one of: ${Object.keys(EXECUTE_DRIVER_REGISTRY).join(", ")}.`);
+        }
+        provider = body.provider;
+    }
+    const def = EXECUTE_DRIVER_REGISTRY[provider];
+    const detection = detectPackageManager(schemaDir, def.packageName);
+    if (detection.manualReason !== null) {
+        return {
+            ok: false,
+            provider,
+            packageName: def.packageName,
+            command: [],
+            error: detection.manualReason,
+            installed: false,
+        };
+    }
+    const { packageManager, projectRoot, spawnSpec } = detection;
+    const { stdout, stderr, code } = await spawnCommand(spawnSpec, projectRoot);
+    const installed = isDriverInstalled(def.packageName, projectRoot);
+    return {
+        ok: code === 0,
+        provider,
+        packageName: def.packageName,
+        command: [spawnSpec.command, ...spawnSpec.args],
+        stdout,
+        stderr,
+        error: code !== 0 ? `${packageManager} exited with code ${code}` : undefined,
+        installed,
+    };
+}
+function detectPackageManager(cwd, packageName) {
+    // Walk up from schemaDir to find the project root's lockfile.
+    const projectRoot = findProjectRoot(cwd);
+    if (!projectRoot) {
+        return { manualReason: `Could not locate a package.json above ${cwd}. Run the install manually.` };
+    }
+    const pm = lockfilePackageManager(projectRoot);
+    if (!pm) {
+        return { manualReason: `No recognized lockfile found in ${projectRoot}. Run: pnpm add ${packageName}` };
+    }
+    return {
+        manualReason: null,
+        packageManager: pm,
+        projectRoot,
+        spawnSpec: packageManagerSpawnSpec(pm, packageManagerAddArgs(pm, [packageName])),
+    };
+}
+function findProjectRoot(startDir) {
+    let current = resolve(startDir);
+    for (let i = 0; i < 20; i++) {
+        if (existsSync(join(current, "package.json")))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+    return null;
+}
+function spawnCommand(spec, cwd) {
+    return new Promise((resolve) => {
+        const proc = spawn(spec.command, spec.args, { cwd, shell: spec.shell, stdio: ["ignore", "pipe", "pipe"] });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        proc.stdout.on("data", (chunk) => stdoutChunks.push(chunk));
+        proc.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+        proc.on("close", (code) => {
+            resolve({
+                stdout: Buffer.concat(stdoutChunks).toString("utf8").slice(0, 4096),
+                stderr: Buffer.concat(stderrChunks).toString("utf8").slice(0, 4096),
+                code: code ?? 1,
+            });
+        });
+        proc.on("error", (err) => {
+            resolve({ stdout: "", stderr: err.message, code: 1 });
+        });
+    });
+}
+async function executeQuery(body, schemaDir) {
+    const rt = getAskDbRuntimeConfig();
+    const exec = rt.studio.execute;
+    if (!exec.enabled) {
+        throw new StudioHttpError(403, EXECUTE_DISABLED_MESSAGE);
+    }
+    if (!isRecord(body) || typeof body.sql !== "string" || body.sql.trim() === "") {
+        throw new StudioHttpError(400, "`sql` is required.");
+    }
+    if (body.params !== undefined && !Array.isArray(body.params)) {
+        throw new StudioHttpError(400, "`params` must be an array.");
+    }
+    const params = body.params ?? [];
+    // Same read-only SELECT guardrail `ask()` applies, for the execute engine's
+    // dialect — rejects multi-statement input, comments, DDL/DML keywords, …
+    // before anything reaches a driver.
+    let sql;
+    try {
+        sql = validateExecuteSql(exec.provider, body.sql, rt.nlToSql.dialect);
+    }
+    catch (error) {
+        if (error instanceof SqlValidationError) {
+            throw new StudioHttpError(400, `SQL rejected by the read-only guardrail (${error.rule}): ${error.message}`);
+        }
+        throw error;
+    }
+    const warnings = sensitiveExecuteWarnings(sql, schemaDir, executeDialectFor(exec.provider, rt.nlToSql.dialect));
+    const projectRoot = findProjectRoot(schemaDir) ?? schemaDir;
+    const def = EXECUTE_DRIVER_REGISTRY[exec.provider];
+    const result = await def.execute({
+        connectionString: exec.databaseUrl,
+        file: exec.file,
+        sql,
+        params,
+        projectRoot,
+        timeoutMs: exec.timeoutMs,
+        maxRows: exec.maxRows,
+    });
+    if (!result.ok && /^No (connection URL|SQLite file path) configured/.test(result.error)) {
+        return { ok: false, error: executeNotConfiguredMessage(exec) };
+    }
+    return result.ok && warnings.length > 0 ? { ...result, warnings } : result;
+}
+/**
+ * Warn (never block) when the SQL references identifiers marked `sensitive` —
+ * the same check `ask()` runs in its default `"warn"` mode. Studio has no
+ * strict-mode setting; hosts that need enforcement call
+ * `validateSensitiveReferences(sql, schema, { mode: "strict" })` themselves.
+ */
+function sensitiveExecuteWarnings(sql, schemaDir, dialect) {
+    let schema;
+    try {
+        schema = loadSchema(schemaDir);
+    }
+    catch {
+        return [];
+    }
+    if (!schemaHasSensitiveIdentifiers(schema))
+        return [];
+    const result = validateSensitiveReferences(sql, schema, { mode: "warn", dialect });
+    if (result.references.length === 0)
+        return [];
+    return [
+        `This query reads identifiers marked sensitive: ${result.references.map(formatSensitiveReference).join(", ")}.`,
+    ];
+}
+function isLoopbackRequest(req) {
+    const socket = req.socket;
+    const remoteAddress = socket?.remoteAddress ?? "";
+    return (remoteAddress === "127.0.0.1" ||
+        remoteAddress === "::1" ||
+        remoteAddress === "::ffff:127.0.0.1" ||
+        remoteAddress === "localhost");
+}
 function readOptionalJson(path) {
     if (!existsSync(path))
         return undefined;
@@ -667,6 +1563,17 @@ function readOptionalJson(path) {
         return undefined;
     }
 }
+function parseConceptsBody(body) {
+    if (!isRecord(body) || !Array.isArray(body.concepts)) {
+        throw new StudioHttpError(400, "`concepts` array is required.");
+    }
+    for (const concept of body.concepts) {
+        if (!isRecord(concept) || typeof concept.id !== "string" || typeof concept.label !== "string") {
+            throw new StudioHttpError(400, "Each concept requires a string `id` and `label`.");
+        }
+    }
+    return body.concepts;
+}
 function parseTableDraftBody(body) {
     if (!isRecord(body) || !isRecord(body.draft)) {
         throw new StudioHttpError(400, "`draft` is required.");
@@ -715,9 +1622,26 @@ function parseAskBody(body) {
     if (mode !== "full" && mode !== "rag") {
         throw new StudioHttpError(400, "`mode` must be `full` or `rag`.");
     }
+    let tenantScope;
+    if (body.tenantScope !== undefined && body.tenantScope !== null) {
+        const parsed = tenantScopeSchema.safeParse(body.tenantScope);
+        if (!parsed.success) {
+            throw new StudioHttpError(400, `Invalid tenantScope: ${parsed.error.message}`);
+        }
+        tenantScope = parsed.data;
+    }
+    let tenantSqlMode;
+    if (typeof body.tenantSqlMode === "string") {
+        if (body.tenantSqlMode !== "sql-only" && body.tenantSqlMode !== "sql-params") {
+            throw new StudioHttpError(400, "`tenantSqlMode` must be `sql-only` or `sql-params`.");
+        }
+        tenantSqlMode = body.tenantSqlMode;
+    }
     return {
         question: body.question.trim(),
         useRag: mode === "rag",
+        tenantScope,
+        tenantSqlMode,
     };
 }
 function parseRagQuery(body) {
@@ -787,8 +1711,10 @@ function createRequestUsageCollector() {
 function normalizeGenerationUsage(value) {
     if (!isRecord(value))
         return undefined;
-    const promptTokens = readFiniteNumber(value.promptTokens);
-    const completionTokens = readFiniteNumber(value.completionTokens);
+    // ai@6 LanguageModelUsage uses inputTokens/outputTokens rather than the
+    // legacy promptTokens/completionTokens names.
+    const promptTokens = readFiniteNumber(value.promptTokens) ?? readFiniteNumber(value.inputTokens);
+    const completionTokens = readFiniteNumber(value.completionTokens) ?? readFiniteNumber(value.outputTokens);
     const totalTokens = readFiniteNumber(value.totalTokens);
     if (promptTokens === undefined && completionTokens === undefined && totalTokens === undefined) {
         return undefined;
@@ -820,11 +1746,36 @@ function sumNullable(values) {
 function readFiniteNumber(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
+/** Largest JSON request body Studio accepts. */
+export const MAX_JSON_BODY_BYTES = 1024 * 1024;
+function bodyTooLarge() {
+    return new StudioHttpError(413, `Request body is too large (limit ${MAX_JSON_BODY_BYTES} bytes).`);
+}
 async function readJson(req) {
+    const declared = Number(req.headers["content-length"]);
+    if (Number.isFinite(declared) && declared > MAX_JSON_BODY_BYTES) {
+        // Node discards the unread body after the 413 response is sent.
+        throw bodyTooLarge();
+    }
     const chunks = [];
+    let size = 0;
+    let overflow = false;
     for await (const chunk of req) {
-        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+        // Keep draining (without buffering) once over the limit, so the client
+        // can read the 413 instead of hitting a reset connection.
+        if (overflow)
+            continue;
+        const buf = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+        size += buf.length;
+        if (size > MAX_JSON_BODY_BYTES) {
+            overflow = true;
+            chunks.length = 0;
+            continue;
+        }
+        chunks.push(buf);
     }
+    if (overflow)
+        throw bodyTooLarge();
     if (chunks.length === 0)
         return {};
     try {
@@ -844,25 +1795,49 @@ function writeText(res, status, contentType, body) {
     });
     res.end(body);
 }
-function serveClientFile(res, relativePath) {
-    const filePath = resolve(CLIENT_DIR, relativePath);
-    const fileRelativeToClientDir = relative(CLIENT_DIR, filePath);
+function resolveClientFile(res, relativePath) {
+    const root = clientDir();
+    const filePath = resolve(root, relativePath);
+    const fileRelativeToClientDir = relative(root, filePath);
     if (fileRelativeToClientDir.startsWith("..") || fileRelativeToClientDir === "") {
-        return writeJson(res, 404, { error: { message: "Not found" } });
+        writeJson(res, 404, { error: { message: "Not found" } });
+        return null;
     }
     if (!existsSync(filePath)) {
-        return writeJson(res, 500, {
+        writeJson(res, 500, {
             error: {
                 message: "Studio client assets are missing. Run `pnpm --filter @askdb/studio build` before starting Studio.",
             },
         });
+        return null;
     }
+    return filePath;
+}
+function serveClientFile(res, relativePath) {
+    const filePath = resolveClientFile(res, relativePath);
+    if (!filePath)
+        return;
     res.writeHead(200, {
         "content-type": contentTypeFor(filePath),
         "cache-control": "no-store",
     });
     res.end(readFileSync(filePath));
 }
+/** Serve the SPA shell with this launch's session token injected. */
+function serveIndexHtml(res, sessionToken) {
+    const filePath = resolveClientFile(res, "index.html");
+    if (!filePath)
+        return;
+    res.writeHead(200, {
+        "content-type": "text/html; charset=utf-8",
+        "cache-control": "no-store",
+        // The page carries the session token and drives SQL execution — never let
+        // another site frame it (clickjacking).
+        "x-frame-options": "DENY",
+        "content-security-policy": "frame-ancestors 'none'",
+    });
+    res.end(injectSessionToken(readFileSync(filePath, "utf8"), sessionToken));
+}
 function contentTypeFor(path) {
     switch (extname(path)) {
         case ".html":