@askdb/studio 0.2.0-beta.35 → 0.2.0-beta.37

package/dist/server.js

@@ -1,27 +1,35 @@
 import { randomUUID } from "node:crypto";
-import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { createServer } from "node:http";
 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 { bootstrapAskDbEnv, getAskDbRuntimeConfig } from "@askdb/config";
+import { ASKDB_AI_PROVIDERS, bootstrapAskDbEnv, getAskDbRuntimeConfig, } from "@askdb/config";
 import { createAiRegistry, resolveReasoningEffort, } from "@askdb/ai";
-import { anthropicProvider } from "@askdb/ai-anthropic";
-import { azureProvider } from "@askdb/ai-azure";
-import { googleProvider } from "@askdb/ai-google";
-import { openaiProvider } from "@askdb/ai-openai";
-import { ask, isBuiltInDialectId, loadSchema, suggestEnrichment, tenantScopeSchema, writeTenantPolicyMarkdown, tenantPolicyFrontmatterSchema, } from "@askdb/core";
-import { buildSchemaIndex, chunkContentHash, chunkSchema, createAiSdkEmbedder, createFileStore, createMemoryStore, createPgvectorStore, createRetriever, loadChunkerSourcesFromDir, } from "@askdb/rag";
+import { ask, formatSensitiveReference, isBuiltInDialectId, loadSchema, schemaHasSensitiveIdentifiers, SqlValidationError, validateSensitiveReferences, suggestEnrichment, tenantScopeSchema, normalizeTenantPolicy, parseTenantPolicyMarkdown, SchemaParseError, writeTenantPolicyMarkdown, 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, } from "@askdb/enrich";
-import { EXECUTE_DRIVER_REGISTRY, isDriverInstalled } from "./execute-registry.js";
+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";
-const ai = createAiRegistry([openaiProvider, azureProvider, googleProvider, anthropicProvider]);
-const CLIENT_DIR = fileURLToPath(new URL("./client/", import.meta.url));
+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;
@@ -37,11 +45,24 @@ export function createStudioServer(options) {
         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)));
@@ -165,7 +186,7 @@ export function createStudioServer(options) {
                 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" } });
         }
@@ -176,6 +197,7 @@ export function createStudioServer(options) {
             });
         }
     });
+    return Object.assign(server, { sessionToken });
 }
 export function serializeWorkspace(workspace) {
     const rt = getAskDbRuntimeConfig();
@@ -200,8 +222,8 @@ export function serializeWorkspace(workspace) {
         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 {
@@ -212,6 +234,7 @@ 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 ?? [],
@@ -348,7 +371,8 @@ function parseSetupConfigBody(body) {
         throw new StudioHttpError(400, "Request body must be a JSON object.");
     }
     const databases = ["postgres", "mysql", "sqlite", "sqlserver", "prisma"];
-    const aiProviders = ["openai", "anthropic", "google", "azure", "foundry"];
+    // 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)) {
@@ -398,8 +422,21 @@ function saveConceptsDraft(state, concepts) {
     state.workspace = loadWorkspace(state.schemaDir);
 }
 function saveTenantPolicy(state, frontmatter, body) {
+    const workspace = requireWorkspace(state);
     const filePath = join(state.schemaDir, "tenant-policy.md");
     const md = writeTenantPolicyMarkdown(frontmatter, body);
+    // Run core's own load-time validation before writing: a policy that `loadSchema` would
+    // reject (e.g. two root labels deriving one placeholder) must not reach disk, or every
+    // later request fails until the file is fixed by hand.
+    try {
+        const physical = workspace.physical;
+        normalizeTenantPolicy(parseTenantPolicyMarkdown(md, filePath), new Set(physical.tables.map((table) => table.id)), new Set(physical.tables.flatMap((table) => table.columns.map((column) => column.id))));
+    }
+    catch (error) {
+        if (error instanceof SchemaParseError)
+            throw new StudioHttpError(400, error.message);
+        throw error;
+    }
     writeFileSync(filePath, md, "utf8");
     state.workspace = loadWorkspace(state.schemaDir);
 }
@@ -419,7 +456,9 @@ function saveDraft(state, tableId, draft) {
     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, 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);
@@ -619,14 +658,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]) ||
@@ -667,8 +709,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,
@@ -681,27 +724,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),
@@ -739,7 +795,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) {
@@ -751,7 +807,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: {
@@ -769,22 +825,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();
@@ -812,10 +872,19 @@ async function openStudioRagStore(state, dimensions) {
     const store = pgvectorFactory({
         connectionString: config.connectionString,
         table: config.table,
-        dimensions,
+        ...(dimensions !== undefined ? { dimensions } : {}),
         ...(config.indexStrategy ? { indexStrategy: config.indexStrategy } : {}),
     });
-    await store.ensureSchema();
+    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,
@@ -827,6 +896,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 });
     }
@@ -839,33 +912,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");
-    const kind = explicitKind?.toLowerCase();
-    if (kind === "mock") {
-        return {
-            kind: "mock",
-            embedderId: STUDIO_RAG_MOCK_EMBEDDER_ID,
-            dimensions: STUDIO_RAG_MOCK_DIMENSIONS,
-            configured: true,
-            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 = ai.resolveEmbeddingConfig(env, {
-        modelEnvVar: "ASKDB_RAG_EMBEDDER_MODEL",
-        modelDefault: DEFAULT_EMBEDDING_MODEL,
-    });
-    if (!aiConfig && kind === undefined) {
+    const embedding = getAskDbRuntimeConfig().ai.embedding;
+    if (!embedding) {
         return {
             kind: "mock",
             embedderId: STUDIO_RAG_MOCK_EMBEDDER_ID,
@@ -874,50 +923,38 @@ function resolveStudioRagEmbedderConfig() {
             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"));
-    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");
-    const baseUrlOverride = pickEnv(base, "ASKDB_RAG_EMBEDDER_BASE_URL");
-    return {
-        ...base,
-        ...(kind === "openai" ? { ASKDB_AI_PROVIDER: "openai" } : {}),
-        ...(apiKeyOverride ? { ASKDB_AI_API_KEY: apiKeyOverride } : {}),
-        ...(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 ai.createEmbeddingModel(config.aiConfig, {
         dimensions: config.requestDimensions,
@@ -937,6 +974,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));
     }
@@ -945,7 +985,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}.`);
@@ -958,6 +998,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++) {
@@ -992,30 +1046,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,
@@ -1052,8 +1096,9 @@ function stableTokenHash(token) {
 // ---------------------------------------------------------------------------
 const HISTORY_MAX_STORED = 200;
 const HISTORY_MAX_RETURNED = 50;
+const HISTORY_FILE_NAME = "playground-history.json";
 function playgroundHistoryPath(schemaDir) {
-    return join(schemaDir, "playground-history.json");
+    return join(schemaDir, HISTORY_FILE_NAME);
 }
 function readPlaygroundHistory(schemaDir) {
     const raw = readOptionalJson(playgroundHistoryPath(schemaDir));
@@ -1072,8 +1117,59 @@ function appendPlaygroundHistory(schemaDir, entry) {
         timestamp: new Date().toISOString(),
     };
     const updated = [newEntry, ...existing].slice(0, HISTORY_MAX_STORED);
+    ensureSchemaDirGitignore(schemaDir);
     writeFileSync(histPath, JSON.stringify(updated, null, 2), "utf8");
 }
+/**
+ * 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: append the entry; never rewrite.
+ * - Failure is non-fatal: history still saves.
+ */
+function ensureSchemaDirGitignore(schemaDir) {
+    const gitignorePath = join(schemaDir, ".gitignore");
+    try {
+        if (existsSync(gitignorePath)) {
+            const content = readFileSync(gitignorePath, "utf8");
+            const lines = content.split(/\r?\n/).map((line) => line.trim());
+            if (lines.includes(HISTORY_FILE_NAME) || lines.includes(`/${HISTORY_FILE_NAME}`))
+                return;
+            const separator = content === "" || content.endsWith("\n") ? "" : "\n";
+            appendFileSync(gitignorePath, `${separator}# AskDB Studio Playground history (local only)\n${HISTORY_FILE_NAME}\n`, "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");
+        }
+        writeFileSync(gitignorePath, `${lines.join("\n")}\n`, "utf8");
+    }
+    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);
@@ -1087,36 +1183,130 @@ function deletePlaygroundHistoryEntry(schemaDir, id) {
     writeFileSync(histPath, JSON.stringify(filtered, null, 2), "utf8");
     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.");
     }
-    if (typeof body.question !== "string" || body.question.trim() === "") {
+    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 (typeof body.sqlMode !== "string") {
-        throw new StudioHttpError(400, "`sqlMode` is required.");
+    if (body.sqlMode !== "sql-only" && body.sqlMode !== "sql-params") {
+        throw new StudioHttpError(400, "`sqlMode` must be `sql-only` or `sql-params`.");
     }
-    if (typeof body.sql !== "string") {
-        throw new StudioHttpError(400, "`sql` is required.");
+    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 body;
+    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 { provider, databaseUrl, file } = rt.studio.execute;
+    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,
@@ -1124,50 +1314,44 @@ async function getExecuteStatus(schemaDir) {
         packageName: def.packageName,
         installed,
         installCommand: def.installCommand,
-        canInstallFromStudio: true,
+        canInstallFromStudio: exec.enabled,
         manualInstallReason: null,
     };
 }
 async function installExecuteDriver(body, schemaDir) {
     const rt = getAskDbRuntimeConfig();
-    const configuredProvider = rt.studio.execute.provider;
-    // Accept the configured provider or an explicit allowlisted provider.
-    let provider = configuredProvider;
-    if (isRecord(body) && typeof body.provider === "string") {
-        const requested = body.provider;
-        if (!(requested in EXECUTE_DRIVER_REGISTRY)) {
-            return {
-                ok: false,
-                provider: configuredProvider,
-                packageName: EXECUTE_DRIVER_REGISTRY[configuredProvider].packageName,
-                command: [],
-                error: `Unknown provider: ${body.provider}`,
-                installed: false,
-            };
+    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 = requested;
+        provider = body.provider;
     }
     const def = EXECUTE_DRIVER_REGISTRY[provider];
-    const { packageManager, command, args, manualReason } = detectPackageManager(schemaDir, def.packageName);
-    if (manualReason) {
+    const detection = detectPackageManager(schemaDir, def.packageName);
+    if (detection.manualReason !== null) {
         return {
             ok: false,
             provider,
             packageName: def.packageName,
             command: [],
-            error: manualReason,
+            error: detection.manualReason,
             installed: false,
         };
     }
-    // Run the install.
-    const { stdout, stderr, code } = await spawnCommand(command, args, schemaDir);
-    const projectRoot = findProjectRoot(schemaDir) ?? schemaDir;
+    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: [command, ...args],
+        command: [spawnSpec.command, ...spawnSpec.args],
         stdout,
         stderr,
         error: code !== 0 ? `${packageManager} exited with code ${code}` : undefined,
@@ -1178,50 +1362,17 @@ function detectPackageManager(cwd, packageName) {
     // Walk up from schemaDir to find the project root's lockfile.
     const projectRoot = findProjectRoot(cwd);
     if (!projectRoot) {
-        return {
-            packageManager: "",
-            command: "",
-            args: [],
-            manualReason: `Could not locate a package.json above ${cwd}. Run the install manually.`,
-        };
-    }
-    if (existsSync(join(projectRoot, "pnpm-lock.yaml"))) {
-        return {
-            packageManager: "pnpm",
-            command: "pnpm",
-            args: ["add", packageName],
-            manualReason: null,
-        };
-    }
-    if (existsSync(join(projectRoot, "package-lock.json"))) {
-        return {
-            packageManager: "npm",
-            command: "npm",
-            args: ["install", packageName],
-            manualReason: null,
-        };
-    }
-    if (existsSync(join(projectRoot, "yarn.lock"))) {
-        return {
-            packageManager: "yarn",
-            command: "yarn",
-            args: ["add", packageName],
-            manualReason: null,
-        };
+        return { manualReason: `Could not locate a package.json above ${cwd}. Run the install manually.` };
     }
-    if (existsSync(join(projectRoot, "bun.lockb")) || existsSync(join(projectRoot, "bun.lock"))) {
-        return {
-            packageManager: "bun",
-            command: "bun",
-            args: ["add", packageName],
-            manualReason: null,
-        };
+    const pm = lockfilePackageManager(projectRoot);
+    if (!pm) {
+        return { manualReason: `No recognized lockfile found in ${projectRoot}. Run: pnpm add ${packageName}` };
     }
     return {
-        packageManager: "",
-        command: "",
-        args: [],
-        manualReason: `No recognized lockfile found in ${projectRoot}. Run: pnpm add ${packageName}`,
+        manualReason: null,
+        packageManager: pm,
+        projectRoot,
+        spawnSpec: packageManagerSpawnSpec(pm, packageManagerAddArgs(pm, [packageName])),
     };
 }
 function findProjectRoot(startDir) {
@@ -1236,9 +1387,9 @@ function findProjectRoot(startDir) {
     }
     return null;
 }
-function spawnCommand(command, args, cwd) {
+function spawnCommand(spec, cwd) {
     return new Promise((resolve) => {
-        const proc = spawn(command, args, { cwd, shell: false, stdio: ["ignore", "pipe", "pipe"] });
+        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));
@@ -1257,15 +1408,69 @@ function spawnCommand(command, args, cwd) {
 }
 async function executeQuery(body, schemaDir) {
     const rt = getAskDbRuntimeConfig();
-    const { provider, databaseUrl, file } = rt.studio.execute;
+    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() === "") {
-        return { ok: false, error: "`sql` is required." };
+        throw new StudioHttpError(400, "`sql` is required.");
     }
-    const sql = body.sql;
-    const params = Array.isArray(body.params) ? body.params : [];
+    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[provider];
-    return def.execute({ connectionString: databaseUrl, file, sql, params, projectRoot });
+    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;
@@ -1468,11 +1673,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 {
@@ -1492,25 +1722,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":