@useatlas/create 0.0.6 → 0.0.7

package/templates/docker/src/lib/tools/sql.ts

@@ -15,22 +15,89 @@
 
 import { tool } from "ai";
 import { z } from "zod";
+import { Effect } from "effect";
 import { Parser } from "node-sql-parser";
-import { connections, detectDBType } from "@atlas/api/lib/db/connection";
+import { connections, detectDBType, ConnectionNotRegisteredError, NoDatasourceConfiguredError, PoolCapacityExceededError } from "@atlas/api/lib/db/connection";
 import type { DBConnection, DBType } from "@atlas/api/lib/db/connection";
-import { getWhitelistedTables } from "@atlas/api/lib/semantic";
+import { getWhitelistedTables, getOrgWhitelistedTables } from "@atlas/api/lib/semantic";
 import { logQueryAudit } from "@atlas/api/lib/auth/audit";
 import { SENSITIVE_PATTERNS } from "@atlas/api/lib/security";
 import { withSpan } from "@atlas/api/lib/tracing";
 import { createLogger, getRequestContext } from "@atlas/api/lib/logger";
-import { acquireSourceSlot, decrementSourceConcurrency } from "@atlas/api/lib/db/source-rate-limit";
+import { withSourceSlot } from "@atlas/api/lib/db/source-rate-limit";
 import { getConfig } from "@atlas/api/lib/config";
-import { resolveRLSFilters, injectRLSConditions } from "@atlas/api/lib/rls";
+import { resolveRLSFilters, injectRLSConditions, type RLSFilterGroup } from "@atlas/api/lib/rls";
+import { getSetting, getSettingAuto } from "@atlas/api/lib/settings";
+import { getCache, buildCacheKey, cacheEnabled, getDefaultTtl } from "@atlas/api/lib/cache/index";
+import { proposePatternIfNovel } from "@atlas/api/lib/learn/pattern-proposer";
+import {
+  ConnectionNotFoundError, PoolExhaustedError, NoDatasourceError,
+  QueryExecutionError, RateLimitExceededError, ConcurrencyLimitError,
+  RLSError, PluginRejectedError,
+} from "@atlas/api/lib/effect/errors";
 
 const log = createLogger("sql");
 
 const parser = new Parser();
 
+// ── Classification ──────────────────────────────────────────────────
+
+interface SQLClassification {
+  readonly tablesAccessed: string[];
+  readonly columnsAccessed: string[];
+}
+
+type SQLValidationResult =
+  | { valid: true; error?: undefined; classification: SQLClassification }
+  | { valid: false; error: string; classification?: undefined };
+
+/**
+ * Extract table and column references from validated SQL.
+ *
+ * Uses node-sql-parser's tableList/columnList helpers.
+ * CTE names are excluded from tablesAccessed.
+ * SELECT * is stored as ["*"] in columnsAccessed.
+ * Best-effort: returns empty arrays on extraction failure.
+ */
+export function extractClassification(
+  sql: string,
+  dialect: string,
+  cteNames: Set<string>,
+): SQLClassification {
+  try {
+    const tableRefs = parser.tableList(sql, { database: dialect });
+    const tablesAccessed = [...new Set(
+      tableRefs
+        .map((ref) => {
+          const parts = ref.split("::");
+          return parts.pop()?.toLowerCase() ?? "";
+        })
+        .filter((t) => t && !cteNames.has(t)),
+    )];
+
+    const columnRefs = parser.columnList(sql, { database: dialect });
+    const columnsAccessed = [...new Set(
+      columnRefs
+        .map((ref) => {
+          const parts = ref.split("::");
+          const col = parts.pop() ?? "";
+          // node-sql-parser uses "(.*)" for SELECT *
+          if (col === "(.*)") return "*";
+          return col.toLowerCase();
+        })
+        .filter(Boolean),
+    )];
+
+    return { tablesAccessed, columnsAccessed };
+  } catch (err) {
+    log.warn(
+      { err: err instanceof Error ? err : new Error(String(err)), sql: sql.slice(0, 200), dialect },
+      "Classification extraction failed — storing empty arrays",
+    );
+    return { tablesAccessed: [], columnsAccessed: [] };
+  }
+}
+
 /**
  * Strip SQL comments for regex guard testing.
  *
@@ -130,7 +197,7 @@ function getExtraPatterns(dbType: DBType | string, connectionId?: string): RegEx
   }
 }
 
-export function validateSQL(sql: string, connectionId?: string): { valid: boolean; error?: string } {
+export function validateSQL(sql: string, connectionId?: string): SQLValidationResult {
   // Resolve DB type for this connection.
   // When an explicit connectionId is given but not found, return a validation
   // error instead of silently falling back — wrong parser mode is a security risk.
@@ -139,14 +206,14 @@ export function validateSQL(sql: string, connectionId?: string): { valid: boolea
     try {
       dbType = connections.getDBType(connectionId);
     } catch (err) {
-      log.debug({ err, connectionId }, "getDBType failed for connectionId");
+      log.warn({ err, connectionId }, "getDBType failed for connectionId");
       return { valid: false, error: `Connection "${connectionId}" is not registered.` };
     }
   } else {
     try {
       dbType = detectDBType();
     } catch (err) {
-      log.debug({ err }, "detectDBType failed — no valid datasource configured");
+      log.warn({ err }, "detectDBType failed — no valid datasource configured");
       return { valid: false, error: "No valid datasource configured. Set ATLAS_DATASOURCE_URL to a PostgreSQL or MySQL connection string, or register a datasource plugin." };
     }
   }
@@ -196,12 +263,9 @@ export function validateSQL(sql: string, connectionId?: string): { valid: boolea
           error: `Only SELECT statements are allowed, got: ${stmt.type}`,
         };
       }
-      // CTE extraction: node-sql-parser doesn't expose .with in its type definitions,
-      // but the property exists at runtime for SELECT statements with CTEs.
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      if (Array.isArray((stmt as any).with)) {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        for (const cte of (stmt as any).with) {
+      // Extract CTE names so they can be excluded from the table whitelist check
+      if (Array.isArray(stmt.with)) {
+        for (const cte of stmt.with) {
           const name = cte?.name?.value ?? cte?.name;
           if (typeof name === "string") cteNames.add(name.toLowerCase());
         }
@@ -215,11 +279,15 @@ export function validateSQL(sql: string, connectionId?: string): { valid: boolea
     };
   }
 
-  // 3. Table whitelist check
-  if (process.env.ATLAS_TABLE_WHITELIST !== "false") {
+  // 3. Table whitelist check — use getSettingAuto for SaaS hot-reload
+  const whitelistSetting = getSettingAuto("ATLAS_TABLE_WHITELIST") ?? process.env.ATLAS_TABLE_WHITELIST;
+  if (whitelistSetting !== "false") {
     try {
       const tables = parser.tableList(trimmed, { database: parserDatabase(dbType, connectionId) });
-      const allowed = getWhitelistedTables(connectionId);
+      const orgId = getRequestContext()?.user?.activeOrganizationId;
+      const allowed = orgId
+        ? getOrgWhitelistedTables(orgId, connectionId)
+        : getWhitelistedTables(connectionId);
 
       for (const ref of tables) {
         // tableList returns "select::schema::table" format
@@ -249,9 +317,10 @@ export function validateSQL(sql: string, connectionId?: string): { valid: boolea
           }
         }
       }
-    } catch {
+    } catch (err) {
       // Table extraction uses the same parser that just succeeded in step 2.
       // If it fails here, reject to avoid bypassing the whitelist.
+      log.warn({ err, sql: trimmed.slice(0, 200) }, "Table extraction failed after successful AST parse");
       return {
         valid: false,
         error: "Could not verify table permissions. Rewrite using standard SQL syntax.",
@@ -259,265 +328,207 @@ export function validateSQL(sql: string, connectionId?: string): { valid: boolea
     }
   }
 
-  return { valid: true };
+  // 4. Extract classification data (best-effort, never blocks validation)
+  const classification = extractClassification(
+    trimmed,
+    parserDatabase(dbType, connectionId),
+    cteNames,
+  );
+
+  return { valid: true, classification };
 }
 
-const ROW_LIMIT = parseInt(process.env.ATLAS_ROW_LIMIT ?? "1000", 10);
-const QUERY_TIMEOUT = parseInt(
-  process.env.ATLAS_QUERY_TIMEOUT ?? "30000",
-  10
-);
+let lastWarnedRowLimit: string | undefined;
 
-export const executeSQL = tool({
-  description: `Execute a read-only SQL query against the database. Only SELECT statements are allowed.
+/** Read row limit from settings cache (DB override > env var > default). Called per-query so admin changes take effect without restart. */
+function getRowLimit(): number {
+  const raw = getSetting("ATLAS_ROW_LIMIT") ?? "1000";
+  const n = parseInt(raw, 10);
+  if (!Number.isFinite(n) || n <= 0) {
+    if (raw !== lastWarnedRowLimit) {
+      log.warn({ value: raw }, "Invalid ATLAS_ROW_LIMIT value; using default 1000");
+      lastWarnedRowLimit = raw;
+    }
+    return 1000;
+  }
+  return n;
+}
 
-Rules:
-- Always read the relevant entity schema from the semantic layer BEFORE writing SQL
-- Use exact column names from the schema — never guess
-- Use canonical metric SQL from metrics/*.yml when available
-- Include a LIMIT clause for large result sets
-- If a query fails, fix the issue — do not retry the same SQL`,
+let lastWarnedQueryTimeout: string | undefined;
 
-  inputSchema: z.object({
-    sql: z.string().describe("The SELECT query to execute"),
-    explanation: z
-      .string()
-      .describe("Brief explanation of what this query does and why"),
-    connectionId: z
-      .string()
-      .optional()
-      .describe(
-        "Target connection ID. Check the entity YAML's `connection` field to determine which source a table belongs to. Omit for the default connection.",
-      ),
-  }),
+/** Read query timeout from settings cache (DB override > env var > default). Called per-query so admin changes take effect without restart. */
+function getQueryTimeout(): number {
+  const raw = getSetting("ATLAS_QUERY_TIMEOUT") ?? "30000";
+  const n = parseInt(raw, 10);
+  if (!Number.isFinite(n) || n <= 0) {
+    if (raw !== lastWarnedQueryTimeout) {
+      log.warn({ value: raw }, "Invalid ATLAS_QUERY_TIMEOUT value; using default 30000ms");
+      lastWarnedQueryTimeout = raw;
+    }
+    return 30000;
+  }
+  return n;
+}
 
-  execute: async ({ sql, explanation, connectionId }) => {
-    const connId = connectionId ?? "default";
+// ── Effect Pipeline ──────────────────────────────────────────────────
 
-    // Validate connection exists before proceeding.
-    // Use getDefault() for "default" to trigger lazy initialization from
-    // ATLAS_DATASOURCE_URL — plain get("default") throws on fresh startup.
-    let db: DBConnection;
-    let dbType: DBType;
-    try {
-      if (connId === "default") {
-        db = connections.getDefault();
-        dbType = connections.getDBType(connId);
-      } else {
-        db = connections.get(connId);
-        dbType = connections.getDBType(connId);
-      }
-    } catch {
-      return {
-        success: false,
-        error: `Connection "${connId}" is not registered. Available: ${connections.list().join(", ") || "(none)"}`,
-      };
-    }
+type CustomValidator = (sql: string) => { valid: boolean; reason?: string } | Promise<{ valid: boolean; reason?: string }>;
 
-    const targetHost = connections.getTargetHost(connId);
+/** Union of all errors the pipeline can produce in the error channel. */
+type PipelineError =
+  | ConnectionNotFoundError
+  | PoolExhaustedError
+  | NoDatasourceError
+  | RateLimitExceededError
+  | ConcurrencyLimitError
+  | RLSError
+  | PluginRejectedError
+  | QueryExecutionError;
 
-    // Check for a custom validator (non-SQL datasource plugins like SOQL, GraphQL).
-    // When present, it completely replaces the standard SQL validation pipeline.
-    // If absent, validateSQL is used instead — validators are mutually exclusive.
-    const customValidator = connections.getValidator(connId);
-    const normalizedSql = sql.trim().replace(/;\s*$/, "").trimEnd();
-    if (customValidator) {
-      let result: { valid: boolean; reason?: string };
-      try {
-        result = customValidator(normalizedSql);
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        log.error({ err, connectionId: connId, sql: normalizedSql.slice(0, 200) }, "Custom validator threw an exception");
-        logQueryAudit({
-          sql: normalizedSql.slice(0, 2000),
-          durationMs: 0,
-          rowCount: null,
-          success: false,
-          error: `Custom validator error: ${message}`,
-          sourceId: connId,
-          sourceType: dbType,
-        });
-        return { success: false, error: `Query validation failed for connection "${connId}": internal validator error` };
-      }
-      if (typeof result?.valid !== "boolean") {
-        log.error({ connectionId: connId, returnValue: result }, "Custom validator returned invalid shape");
-        logQueryAudit({
-          sql: normalizedSql.slice(0, 2000),
-          durationMs: 0,
-          rowCount: null,
-          success: false,
-          error: "Custom validator returned invalid result",
-          sourceId: connId,
-          sourceType: dbType,
+/** Resolve the database connection. Fails with tagged connection errors. */
+function resolveConnectionEffect(
+  connId: string,
+  orgId: string | undefined,
+): Effect.Effect<
+  { db: DBConnection; dbType: DBType },
+  ConnectionNotFoundError | PoolExhaustedError | NoDatasourceError
+> {
+  return Effect.try({
+    try: () => {
+      let db: DBConnection;
+      if (orgId) db = connections.getForOrg(orgId, connId);
+      else if (connId === "default") db = connections.getDefault();
+      else db = connections.get(connId);
+      const dbType = connections.getDBType(connId);
+      return { db, dbType };
+    },
+    catch: (err) => {
+      if (err instanceof ConnectionNotRegisteredError) {
+        return new ConnectionNotFoundError({
+          message: `Connection "${connId}" is not registered. Available: ${connections.list().join(", ") || "(none)"}`,
+          connectionId: connId,
+          available: connections.list(),
         });
-        return { success: false, error: `Query validation misconfigured for connection "${connId}"` };
       }
-      if (!result.valid) {
-        logQueryAudit({
-          sql: normalizedSql.slice(0, 2000),
-          durationMs: 0,
-          rowCount: null,
-          success: false,
-          error: `Validation rejected: ${result.reason ?? "Query rejected by custom validator"}`,
-          sourceId: connId,
-          sourceType: dbType,
-        });
-        return { success: false, error: result.reason ?? "Query rejected by custom validator" };
+      if (err instanceof NoDatasourceConfiguredError) {
+        return new NoDatasourceError({ message: (err as Error).message });
       }
-    } else {
-      const validation = validateSQL(sql, connId);
-      if (!validation.valid) {
-        logQueryAudit({
-          sql: sql.slice(0, 2000),
-          durationMs: 0,
-          rowCount: null,
-          success: false,
-          error: `Validation rejected: ${validation.error}`,
-          sourceId: connId,
-          sourceType: dbType,
+      if (err instanceof PoolCapacityExceededError) {
+        log.warn({ connectionId: connId, orgId }, "Org pool capacity exceeded");
+        return new PoolExhaustedError({
+          message: "Connection pool capacity reached — the system is handling many concurrent tenants. Try again shortly.",
+          current: err.currentSlots,
+          max: err.maxTotalConnections,
         });
-        return { success: false, error: validation.error };
       }
-    }
-
-    // Per-source rate limiting — atomic check-and-acquire
-    const slot = acquireSourceSlot(connId);
-    if (!slot.acquired) {
-      logQueryAudit({
-        sql: sql.slice(0, 2000),
-        durationMs: 0,
-        rowCount: null,
-        success: false,
-        error: `Rate limited: ${slot.reason}`,
-        sourceId: connId,
-        sourceType: dbType,
-        targetHost,
+      const message = err instanceof Error ? err.message : String(err);
+      log.error({ err, connectionId: connId }, "Unexpected error during connection lookup");
+      return new ConnectionNotFoundError({
+        message: `Connection "${connId}" failed to initialize: ${message}`,
+        connectionId: connId,
+        available: connections.list(),
       });
-      return {
-        success: false,
-        error: slot.reason ?? "Rate limited",
-        ...(slot.retryAfterMs != null && { retryAfterMs: slot.retryAfterMs }),
-      };
+    },
+  });
+}
+
+/**
+ * Run query validation (custom validator or standard SQL).
+ * Returns a result object — validation rejection is a normal outcome, not an error channel event.
+ * `auditError` preserves specific error detail for audit logs.
+ */
+function runQueryValidationEffect(
+  sql: string,
+  connId: string,
+  dbType: DBType | string,
+  customValidator: CustomValidator | undefined,
+): Effect.Effect<{ ok: true; classification?: SQLClassification } | { ok: false; error: string; auditError: string }> {
+  if (!customValidator) {
+    const validation = validateSQL(sql, connId);
+    if (!validation.valid) {
+      return Effect.succeed({ ok: false as const, error: validation.error, auditError: `Validation rejected: ${validation.error}` });
     }
+    return Effect.succeed({ ok: true as const, classification: validation.classification });
+  }
 
-    const { dispatchHook, dispatchMutableHook } = await import("@atlas/api/lib/plugins/hooks");
-    let mutatedSql: string;
+  // Custom validator (async) — errors are caught and returned as result values, not thrown
+  return Effect.promise(async () => {
+    let result: { valid: boolean; reason?: string };
     try {
-      const hookCtx = { sql, connectionId: connId } as const;
-      mutatedSql = await dispatchMutableHook(
-        "beforeQuery",
-        hookCtx,
-        "sql",
-      );
+      result = await customValidator(sql);
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      decrementSourceConcurrency(connId);
-      logQueryAudit({
-        sql: sql.slice(0, 2000),
-        durationMs: 0,
-        rowCount: null,
-        success: false,
-        error: `Plugin rejected: ${message}`,
-        sourceId: connId,
-        sourceType: dbType,
-        targetHost,
-      });
-      return { success: false, error: `Query rejected by plugin: ${message}` };
+      log.error({ err, connectionId: connId, sql: sql.slice(0, 200) }, "Custom validator threw an exception");
+      return { ok: false as const, error: `Query validation failed for connection "${connId}": internal validator error`, auditError: `Custom validator error: ${message}` };
+    }
+    if (typeof result?.valid !== "boolean") {
+      log.error({ connectionId: connId, returnValue: result }, "Custom validator returned invalid shape");
+      return { ok: false as const, error: `Query validation misconfigured for connection "${connId}"`, auditError: "Custom validator returned invalid result" };
+    }
+    if (!result.valid) {
+      const reason = result.reason ?? "Query rejected by custom validator";
+      return { ok: false as const, error: reason, auditError: `Validation rejected: ${reason}` };
     }
+    return { ok: true as const, classification: undefined as SQLClassification | undefined };
+  });
+}
 
-    // Re-validate if a plugin rewrote the SQL — a plugin could introduce DML,
-    // disallowed tables, or invalid syntax that would bypass the initial validation
-    let normalizedMutated = mutatedSql.trim().replace(/;\s*$/, "").trimEnd();
-    if (normalizedMutated !== normalizedSql) {
-      if (customValidator) {
-        let reresult: { valid: boolean; reason?: string };
-        try {
-          reresult = customValidator(normalizedMutated);
-        } catch (err) {
-          decrementSourceConcurrency(connId);
-          const message = err instanceof Error ? err.message : String(err);
-          log.error({ err, connectionId: connId, sql: normalizedMutated.slice(0, 200) }, "Custom validator threw during re-validation of plugin-mutated query");
-          logQueryAudit({
-            sql: normalizedMutated.slice(0, 2000),
-            durationMs: 0,
-            rowCount: null,
-            success: false,
-            error: `Custom validator error on rewritten query: ${message}`,
-            sourceId: connId,
-            sourceType: dbType,
-            targetHost,
-          });
-          return { success: false, error: `Re-validation failed for connection "${connId}": internal validator error` };
-        }
-        if (typeof reresult?.valid !== "boolean") {
-          decrementSourceConcurrency(connId);
-          log.error({ connectionId: connId, returnValue: reresult }, "Custom validator returned invalid shape during re-validation");
-          logQueryAudit({
-            sql: normalizedMutated.slice(0, 2000),
-            durationMs: 0,
-            rowCount: null,
-            success: false,
-            error: "Custom validator returned invalid result during re-validation",
-            sourceId: connId,
-            sourceType: dbType,
-            targetHost,
-          });
-          return { success: false, error: `Query validation misconfigured for connection "${connId}"` };
-        }
-        if (!reresult.valid) {
-          decrementSourceConcurrency(connId);
-          logQueryAudit({
-            sql: normalizedMutated.slice(0, 2000),
-            durationMs: 0,
-            rowCount: null,
-            success: false,
-            error: `Plugin-rewritten SQL failed validation: ${reresult.reason ?? "Query rejected by custom validator"}`,
-            sourceId: connId,
-            sourceType: dbType,
-            targetHost,
-          });
-          return { success: false, error: `Plugin-rewritten SQL failed validation: ${reresult.reason ?? "Query rejected by custom validator"}` };
+/** Apply RLS conditions. Returns the (possibly modified) SQL. Fails with RLSError. */
+function applyRLSEffect(
+  sql: string,
+  connId: string,
+  dbType: DBType | string,
+  targetHost: string | undefined,
+): Effect.Effect<string, RLSError> {
+  return Effect.gen(function* () {
+    const config = getConfig();
+    let rlsConfig = config?.rls;
+
+    // In SaaS mode only, overlay settings-based RLS config for hot-reload.
+    // Only activates when there is a DB override for ATLAS_RLS_ENABLED — env
+    // vars and defaults are handled by the boot-time config and don't trigger
+    // the overlay, preserving multi-policy configs from atlas.config.ts.
+    if (config?.deployMode === "saas") {
+      const rlsEnabledSetting = getSettingAuto("ATLAS_RLS_ENABLED");
+      if (rlsEnabledSetting !== undefined) {
+        if (rlsEnabledSetting !== "true") {
+          // Explicitly disabled via settings — skip RLS
+          return sql;
         }
-      } else {
-        const revalidation = validateSQL(mutatedSql, connId);
-        if (!revalidation.valid) {
-          decrementSourceConcurrency(connId);
-          logQueryAudit({
-            sql: mutatedSql.slice(0, 2000),
-            durationMs: 0,
-            rowCount: null,
-            success: false,
-            error: `Plugin-rewritten SQL failed validation: ${revalidation.error}`,
-            sourceId: connId,
-            sourceType: dbType,
-            targetHost,
+        // Setting says enabled — build/overlay config from settings
+        const column = getSettingAuto("ATLAS_RLS_COLUMN");
+        const claim = getSettingAuto("ATLAS_RLS_CLAIM");
+        if (column && claim) {
+          rlsConfig = {
+            enabled: true,
+            policies: [{ tables: ["*"], column, claim }],
+            combineWith: rlsConfig?.combineWith ?? "and",
+          };
+        } else {
+          // RLS enabled but missing required config — fail closed
+          log.error(
+            { column: !!column, claim: !!claim },
+            "RLS enabled via settings but ATLAS_RLS_COLUMN or ATLAS_RLS_CLAIM is missing — blocking query",
+          );
+          return yield* new RLSError({
+            message: "Row-level security is enabled but not fully configured. Contact your administrator.",
+            phase: "filter",
           });
-          return { success: false, error: `Plugin-rewritten SQL failed validation: ${revalidation.error}` };
         }
       }
     }
 
-    // --- RLS: inject WHERE conditions based on user claims ---
-    // Applied after validation + plugin hooks so plugins cannot strip RLS.
-    // Skipped for custom validators (non-SQL languages like SOQL).
-    const config = getConfig();
-    const rlsConfig = config?.rls;
-    if (rlsConfig?.enabled && !customValidator) {
-      if (!config) {
-        // Config not loaded — fail-closed rather than risk missing RLS.
-        decrementSourceConcurrency(connId);
-        log.error("getConfig() returned null during RLS-enabled SQL execution — config not loaded");
-        return { success: false, error: "Server configuration not initialized. Please retry." };
-      }
-      const ctx = getRequestContext();
-      const user = ctx?.user;
+    if (!rlsConfig?.enabled) return sql;
 
-      // Extract tables from the (possibly plugin-mutated) SQL
-      let queriedTables: Set<string>;
-      try {
+    const ctx = getRequestContext();
+    const user = ctx?.user;
+
+    // Extract tables
+    const queriedTables = yield* Effect.try({
+      try: () => {
         const dialect = parserDatabase(dbType, connId);
-        const tableRefs = parser.tableList(normalizedMutated, { database: dialect });
-        queriedTables = new Set(
+        const tableRefs = parser.tableList(sql, { database: dialect });
+        return new Set(
           tableRefs
             .map((ref) => {
               const parts = ref.split("::");
@@ -525,156 +536,561 @@ Rules:
             })
             .filter(Boolean),
         );
-      } catch (tableErr) {
-        decrementSourceConcurrency(connId);
+      },
+      catch: (tableErr) => {
         const tableErrMsg = tableErr instanceof Error ? tableErr.message : String(tableErr);
-        log.error({ err: tableErr, sql: normalizedMutated.slice(0, 200) }, "RLS: failed to extract table list from query");
+        log.error({ err: tableErr, sql: sql.slice(0, 200) }, "RLS: failed to extract table list from query");
         logQueryAudit({
-          sql: normalizedMutated.slice(0, 2000),
-          durationMs: 0,
-          rowCount: null,
-          success: false,
+          sql: sql.slice(0, 2000), durationMs: 0, rowCount: null, success: false,
           error: `RLS: could not extract tables from query: ${tableErrMsg}`,
-          sourceId: connId,
-          sourceType: dbType,
-          targetHost,
+          sourceId: connId, sourceType: dbType, targetHost,
         });
-        return { success: false, error: "Query could not be analyzed for row-level security. Rewrite using standard SQL." };
-      }
-
-      const filterResult = resolveRLSFilters(user, queriedTables, rlsConfig);
-      if ("error" in filterResult) {
-        decrementSourceConcurrency(connId);
-        log.warn({ error: filterResult.error, userId: user?.id }, "RLS filter resolution failed — query blocked");
-        logQueryAudit({
-          sql: normalizedMutated.slice(0, 2000),
-          durationMs: 0,
-          rowCount: null,
-          success: false,
-          error: `RLS blocked: ${filterResult.error}`,
-          sourceId: connId,
-          sourceType: dbType,
-          targetHost,
+        return new RLSError({
+          message: "Query could not be analyzed for row-level security. Rewrite using standard SQL.",
+          phase: "extraction",
         });
-        return { success: false, error: filterResult.error };
-      }
+      },
+    });
 
-      if (filterResult.filters.length > 0) {
-        try {
-          normalizedMutated = injectRLSConditions(normalizedMutated, filterResult.filters, dbType);
-          log.debug(
-            { filters: filterResult.filters.length, userId: user?.id },
-            "RLS conditions injected",
-          );
-        } catch (err) {
-          decrementSourceConcurrency(connId);
+    // Resolve filters
+    const filterResult = resolveRLSFilters(user, queriedTables, rlsConfig);
+    if ("error" in filterResult) {
+      log.warn({ error: filterResult.error, userId: user?.id }, "RLS filter resolution failed — query blocked");
+      logQueryAudit({
+        sql: sql.slice(0, 2000), durationMs: 0, rowCount: null, success: false,
+        error: `RLS blocked: ${filterResult.error}`,
+        sourceId: connId, sourceType: dbType, targetHost,
+      });
+      return yield* new RLSError({ message: filterResult.error, phase: "filter" });
+    }
+
+    // Inject conditions
+    const hasFilters = filterResult.groups.some((g: RLSFilterGroup) => g.filters.length > 0);
+    if (hasFilters) {
+      const injected = yield* Effect.try({
+        try: () => injectRLSConditions(sql, filterResult.groups, filterResult.combineWith, dbType),
+        catch: (err) => {
           const msg = err instanceof Error ? err.message : String(err);
           log.error({ err, userId: user?.id }, "RLS injection failed — query blocked");
           logQueryAudit({
-            sql: normalizedMutated.slice(0, 2000),
-            durationMs: 0,
-            rowCount: null,
-            success: false,
+            sql: sql.slice(0, 2000), durationMs: 0, rowCount: null, success: false,
             error: `RLS injection failed: ${msg}`,
-            sourceId: connId,
-            sourceType: dbType,
-            targetHost,
+            sourceId: connId, sourceType: dbType, targetHost,
           });
-          return { success: false, error: "Query could not be processed for row-level security." };
-        }
-      }
+          return new RLSError({ message: "Query could not be processed for row-level security.", phase: "injection" });
+        },
+      });
+      log.debug(
+        { groups: filterResult.groups.length, combineWith: filterResult.combineWith, userId: user?.id },
+        "RLS conditions injected",
+      );
+      return injected;
     }
 
-    // Auto-append LIMIT if not present.
-    // Custom validators are responsible for their own pagination — non-SQL
-    // languages (SOQL, GraphQL) may not support the LIMIT keyword.
-    let querySql = normalizedMutated;
-    if (!customValidator && !/\bLIMIT\b/i.test(querySql)) {
-      querySql += ` LIMIT ${ROW_LIMIT}`;
-    }
+    return sql;
+  });
+}
 
-    // Includes connection acquisition time; the OTel span inside withSpan
-    // covers only the actual query execution against the database.
-    const start = performance.now();
-    try {
-      const result = await withSpan(
+/**
+ * Execute a validated query with tracing, cache write, audit logging, plugin hooks,
+ * and error filtering. Called inside withSourceSlot — concurrency release is automatic.
+ */
+function executeAndAuditEffect(opts: {
+  db: DBConnection;
+  dbType: DBType;
+  connId: string;
+  orgId: string | undefined;
+  targetHost: string | undefined;
+  querySql: string;
+  queryTimeout: number;
+  rowLimit: number;
+  explanation: string;
+  classification: SQLClassification | undefined;
+  cacheKey: string | null;
+  hookMetadata: Record<string, unknown>;
+  dispatchHook: (event: "afterQuery", ctx: Record<string, unknown>) => Promise<void>;
+}): Effect.Effect<Record<string, unknown>, QueryExecutionError> {
+  const {
+    db, dbType, connId, orgId, targetHost, querySql, queryTimeout,
+    rowLimit, explanation, classification, cacheKey, hookMetadata, dispatchHook,
+  } = opts;
+
+  const start = performance.now();
+
+  return Effect.tryPromise({
+    try: () =>
+      withSpan(
         "atlas.sql.execute",
-        {
-          "db.system": dbType,
-          "db.statement": querySql.slice(0, 200),
-        },
-        () => db.query(querySql, QUERY_TIMEOUT),
-      );
+        { "db.system": dbType, "atlas.connection_id": connId },
+        () => db.query(querySql, queryTimeout),
+        (r) => ({ "atlas.row_count": r.rows.length, "atlas.column_count": r.columns.length }),
+      ),
+    catch: (err) => {
       const durationMs = Math.round(performance.now() - start);
-      const truncated = result.rows.length >= ROW_LIMIT;
+      const message = err instanceof Error ? err.message : "Unknown database error";
+
+      connections.recordQuery(connId, durationMs, orgId);
+      connections.recordError(connId, orgId);
+
+      // SLA metric (fire-and-forget, enterprise feature)
+      if (orgId) {
+        import("@atlas/ee/sla/index")
+          .then(({ recordQueryMetric }) => recordQueryMetric(orgId, durationMs, true))
+          .catch((slaErr) => {
+            // Dynamic import failure = ee not installed (expected in non-enterprise).
+            // Runtime error from recordQueryMetric = log warning for diagnostics.
+            if (slaErr instanceof Error && !slaErr.message.includes("Cannot find module")) {
+              log.warn({ err: slaErr.message, connectionId: connId }, "SLA metric recording failed");
+            }
+          });
+      }
 
       try {
         logQueryAudit({
-          sql: querySql,
-          durationMs,
-          rowCount: result.rows.length,
-          success: true,
-          sourceId: connId,
-          sourceType: dbType,
-          targetHost,
+          sql: querySql, durationMs, rowCount: null, success: false, error: message,
+          sourceId: connId, sourceType: dbType, targetHost,
+          tablesAccessed: classification?.tablesAccessed,
+          columnsAccessed: classification?.columnsAccessed,
         });
       } catch (auditErr) {
         log.warn({ err: auditErr }, "Failed to write query audit log");
       }
 
-      await dispatchHook("afterQuery", {
-        sql: querySql,
-        connectionId: connId,
-        result: { columns: result.columns, rows: result.rows },
-        durationMs,
-      });
+      // Filter sensitive errors before returning to the agent
+      if (SENSITIVE_PATTERNS.test(message)) {
+        return new QueryExecutionError({ message: "Database query failed — check server logs for details." });
+      }
+      const dbErr = err as { hint?: string; position?: string };
+      let detail = message;
+      if (dbErr.hint) detail += ` — Hint: ${dbErr.hint}`;
+      if (dbErr.position) detail += ` (at character ${dbErr.position})`;
+      return new QueryExecutionError({ message: detail, hint: dbErr.hint, position: dbErr.position });
+    },
+  }).pipe(
+    // Success path: metrics, cache, audit, hooks, masking
+    Effect.flatMap((result) =>
+      Effect.tryPromise({
+        try: async () => {
+          const durationMs = Math.round(performance.now() - start);
+          const truncated = result.rows.length >= rowLimit;
+
+          connections.recordQuery(connId, durationMs, orgId);
+          connections.recordSuccess(connId, orgId);
+
+          // SLA metric (fire-and-forget, enterprise feature)
+          if (orgId) {
+            try {
+              const { recordQueryMetric } = await import("@atlas/ee/sla/index");
+              recordQueryMetric(orgId, durationMs, false);
+            } catch (err) {
+              // Dynamic import failure = ee not installed (expected in non-enterprise).
+              // Runtime error from recordQueryMetric = log warning for diagnostics.
+              if (err instanceof Error && !err.message.includes("Cannot find module")) {
+                log.warn({ err: err.message, connectionId: connId }, "SLA metric recording failed");
+              }
+            }
+          }
+
+          // Cache write (fail open)
+          if (cacheKey) {
+            try {
+              getCache().set(cacheKey, {
+                columns: result.columns, rows: result.rows,
+                cachedAt: Date.now(), ttl: getDefaultTtl(),
+              });
+            } catch (cacheErr) {
+              log.error({ err: cacheErr, connectionId: connId }, "Cache write failed — result not cached");
+            }
+          }
+
+          try {
+            logQueryAudit({
+              sql: querySql, durationMs, rowCount: result.rows.length, success: true,
+              sourceId: connId, sourceType: dbType, targetHost,
+              tablesAccessed: classification?.tablesAccessed,
+              columnsAccessed: classification?.columnsAccessed,
+            });
+          } catch (auditErr) {
+            log.warn({ err: auditErr }, "Failed to write query audit log");
+          }
+
+          try {
+            await dispatchHook("afterQuery", {
+              sql: querySql, connectionId: connId,
+              result: { columns: result.columns, rows: result.rows },
+              durationMs,
+            });
+          } catch (hookErr) {
+            log.warn(
+              { err: hookErr instanceof Error ? hookErr.message : String(hookErr), connectionId: connId },
+              "afterQuery hook failed — query result unaffected",
+            );
+          }
 
+          // Pattern learning (fire-and-forget)
+          proposePatternIfNovel({
+            sql: querySql, dialect: parserDatabase(dbType, connId), connectionId: connId,
+          });
+
+          // PII masking (fails open)
+          let maskedRows = result.rows;
+          let maskingApplied = false;
+          if (classification?.tablesAccessed.length && orgId) {
+            try {
+              const { applyMasking } = await import("@atlas/ee/compliance/masking");
+              const maskCtx = getRequestContext();
+              maskedRows = await applyMasking({
+                columns: result.columns, rows: result.rows,
+                tablesAccessed: classification.tablesAccessed,
+                orgId, userRole: maskCtx?.user?.role,
+              });
+              maskingApplied = maskedRows !== result.rows;
+            } catch (err) {
+              log.warn(
+                { err: err instanceof Error ? err.message : String(err), connectionId: connId },
+                "PII masking failed — returning unmasked results",
+              );
+            }
+          }
+
+          const hasHookMeta = Object.keys(hookMetadata).length > 0;
+          return {
+            success: true,
+            explanation,
+            row_count: maskedRows.length,
+            columns: result.columns,
+            rows: maskedRows,
+            truncated,
+            cached: false,
+            maskingApplied,
+            ...(hasHookMeta && { metadata: hookMetadata }),
+          } as Record<string, unknown>;
+        },
+        catch: (err) => {
+          // Query succeeded but post-processing failed — return the error
+          // rather than losing the completed query result as an unrecoverable defect.
+          const message = err instanceof Error ? err.message : String(err);
+          log.error({ err, connectionId: connId }, "Post-query processing failed after successful execution");
+          return new QueryExecutionError({ message: `Query succeeded but post-processing failed: ${message}` });
+        },
+      }),
+    ),
+  );
+}
+
+/** Map a pipeline error to the tool's {success: false} response format. Exhaustive over PipelineError. */
+function pipelineErrorToResponse(error: PipelineError): Record<string, unknown> {
+  switch (error._tag) {
+    case "RateLimitExceededError":
       return {
-        success: true,
-        explanation,
-        row_count: result.rows.length,
-        columns: result.columns,
-        rows: result.rows,
-        truncated,
+        success: false,
+        error: error.message,
+        ...(error.retryAfterMs != null && { retryAfterMs: error.retryAfterMs }),
       };
-    } catch (err) {
-      const durationMs = Math.round(performance.now() - start);
-      const message =
-        err instanceof Error ? err.message : "Unknown database error";
+    case "ConcurrencyLimitError":
+    case "ConnectionNotFoundError":
+    case "PoolExhaustedError":
+    case "NoDatasourceError":
+    case "RLSError":
+    case "PluginRejectedError":
+    case "QueryExecutionError":
+      return { success: false, error: error.message };
+    default: {
+      const _exhaustive: never = error;
+      return { success: false, error: `Unknown pipeline error: ${(_exhaustive as { message: string }).message}` };
+    }
+  }
+}
 
-      try {
+export const executeSQL = tool({
+  description: `Execute a read-only SQL query against the database. Only SELECT statements are allowed.
+
+Rules:
+- Always read the relevant entity schema from the semantic layer BEFORE writing SQL
+- Use exact column names from the schema — never guess
+- Use canonical metric SQL from metrics/*.yml when available
+- Include a LIMIT clause for large result sets
+- If a query fails, fix the issue — do not retry the same SQL`,
+
+  inputSchema: z.object({
+    sql: z.string().describe("The SELECT query to execute"),
+    explanation: z
+      .string()
+      .describe("Brief explanation of what this query does and why"),
+    connectionId: z
+      .string()
+      .optional()
+      .describe(
+        "Target connection ID. Check the entity YAML's `connection` field to determine which source a table belongs to. Omit for the default connection.",
+      ),
+  }),
+
+  execute: async ({ sql, explanation, connectionId }) => {
+    const connId = connectionId ?? "default";
+
+    // The full pipeline runs as an Effect.gen program. Tagged errors flow through
+    // the error channel; expected rejections (validation, approval, cache) return
+    // as {success: false} values. At the boundary, catchAll maps errors to responses.
+    const pipeline = Effect.gen(function* () {
+      // Resolve org context for tenant-scoped pool isolation
+      const reqCtx = getRequestContext();
+      const orgId = connections.isOrgPoolingEnabled()
+        ? reqCtx?.user?.activeOrganizationId
+        : undefined;
+
+      // Step 1: Resolve connection (tagged errors)
+      const { db, dbType } = yield* resolveConnectionEffect(connId, orgId);
+
+      const targetHost = connections.getTargetHost(connId);
+      const customValidator = connections.getValidator(connId);
+      const normalizedSql = sql.trim().replace(/;\s*$/, "").trimEnd();
+
+      // Step 2: Validate (custom validator or standard SQL validation)
+      const initial = yield* runQueryValidationEffect(normalizedSql, connId, dbType, customValidator);
+      if (!initial.ok) {
         logQueryAudit({
-          sql: querySql,
-          durationMs,
-          rowCount: null,
-          success: false,
-          error: message,
-          sourceId: connId,
-          sourceType: dbType,
-          targetHost,
+          sql: normalizedSql.slice(0, 2000), durationMs: 0, rowCount: null, success: false,
+          error: initial.auditError, sourceId: connId, sourceType: dbType,
         });
-      } catch (auditErr) {
-        log.warn({ err: auditErr }, "Failed to write query audit log");
+        return { success: false, error: initial.error };
       }
+      // Classification is only populated for standard SQL (validateSQL path).
+      // Custom validators (SOQL, GraphQL) bypass node-sql-parser so classification
+      // stays undefined — their audit entries store NULL for tables/columns_accessed.
+      const classification = initial.classification;
 
-      // Block errors that might expose connection details or internal state
-      if (SENSITIVE_PATTERNS.test(message)) {
-        return { success: false, error: "Database query failed — check server logs for details." };
-      }
+      // Step 3: Enterprise approval check (fail-open for availability, hard-fail for request creation)
+      if (classification) {
+        const approvalResult = yield* Effect.tryPromise({
+          try: async () => {
+            // Phase 1: check availability (fail open)
+            let approvalMatch: { required: boolean; matchedRules: { id: string; name: string }[] } | null = null;
+            try {
+              const { checkApprovalRequired } = await import("@atlas/ee/governance/approval");
+              const checkReqCtx = getRequestContext();
+              const checkOrgId = checkReqCtx?.user?.activeOrganizationId;
+              approvalMatch = await checkApprovalRequired(
+                checkOrgId, classification.tablesAccessed, classification.columnsAccessed,
+              );
+            } catch (err) {
+              log.warn(
+                { err: err instanceof Error ? err.message : String(err), connectionId: connId },
+                "Approval check failed — proceeding without approval gate",
+              );
+            }
 
-      // Surface the full DB error to the agent for self-correction
-      // (includes column-not-found, syntax, timeout, type mismatch, etc.)
-      const dbErr = err as { hint?: string; position?: string };
-      let detail = message;
-      if (dbErr.hint) {
-        detail += ` — Hint: ${dbErr.hint}`;
+            // Phase 2: create request (hard fail — governance bypass is worse than a failed query)
+            if (approvalMatch?.required) {
+              const { createApprovalRequest, hasApprovedRequest } = await import("@atlas/ee/governance/approval");
+              const reqCtxForApproval = getRequestContext();
+              const approvalOrgId = reqCtxForApproval?.user?.activeOrganizationId;
+              const userId = reqCtxForApproval?.user?.id;
+              const userEmail = reqCtxForApproval?.user?.label ?? null;
+
+              if (!userId || !approvalOrgId) {
+                log.warn(
+                  { connectionId: connId, orgId: approvalOrgId },
+                  "Approval required but user identity unavailable — blocking query",
+                );
+                return {
+                  success: false,
+                  error: "This query requires approval but the requester identity could not be determined. Please sign in and try again.",
+                };
+              }
+
+              const alreadyApproved = await hasApprovedRequest(approvalOrgId, userId, normalizedSql);
+              if (!alreadyApproved) {
+                const firstRule = approvalMatch.matchedRules[0];
+                const approvalReq = await createApprovalRequest({
+                  orgId: approvalOrgId,
+                  ruleId: firstRule.id,
+                  ruleName: firstRule.name,
+                  requesterId: userId,
+                  requesterEmail: userEmail,
+                  querySql: normalizedSql,
+                  explanation,
+                  connectionId: connId,
+                  tablesAccessed: classification.tablesAccessed,
+                  columnsAccessed: classification.columnsAccessed,
+                });
+                logQueryAudit({
+                  sql: normalizedSql.slice(0, 2000), durationMs: 0, rowCount: null, success: false,
+                  error: `Approval required: ${firstRule.name}`,
+                  sourceId: connId, sourceType: dbType, targetHost,
+                });
+                return {
+                  success: false,
+                  approval_required: true,
+                  approval_request_id: approvalReq.id,
+                  matched_rules: approvalMatch.matchedRules.map((r: { name: string }) => r.name),
+                  message: `This query requires approval before execution. Rule: "${firstRule.name}". ` +
+                    `An approval request has been submitted (ID: ${approvalReq.id}). ` +
+                    `An admin must approve it before the query can run.`,
+                };
+              }
+            }
+            return null; // proceed to execution
+          },
+          catch: (err) => {
+            // Phase 2 failure — governance bypass is worse than a failed query.
+            // Surface as a typed error so it reaches the agent as {success: false}.
+            const message = err instanceof Error ? err.message : String(err);
+            log.error({ err, connectionId: connId }, "Approval request creation failed — blocking query");
+            return new QueryExecutionError({ message: `Approval workflow failed: ${message}` });
+          },
+        });
+        if (approvalResult !== null) return approvalResult;
       }
-      if (dbErr.position) {
-        detail += ` (at character ${dbErr.position})`;
+
+      // Step 4: Cache check (short-circuit on hit)
+      let cacheKey: string | null = null;
+      if (cacheEnabled()) {
+        try {
+          const ctx = getRequestContext();
+          const cacheOrgId = ctx?.user?.activeOrganizationId;
+          const claims = ctx?.user?.claims;
+          cacheKey = buildCacheKey(normalizedSql, connId, cacheOrgId, claims);
+          const cached = getCache().get(cacheKey);
+          if (cached) {
+            logQueryAudit({
+              sql: normalizedSql.slice(0, 2000), durationMs: 0, rowCount: cached.rows.length,
+              success: true, sourceId: connId, sourceType: dbType, targetHost,
+            });
+            // Apply PII masking to cached results (same as live query path)
+            const cacheResponse = yield* Effect.tryPromise({
+              try: async () => {
+                let cachedRows = cached.rows;
+                let cachedMaskingApplied = false;
+                if (classification?.tablesAccessed.length && orgId) {
+                  try {
+                    const { applyMasking } = await import("@atlas/ee/compliance/masking");
+                    cachedRows = await applyMasking({
+                      columns: cached.columns, rows: cached.rows,
+                      tablesAccessed: classification.tablesAccessed,
+                      orgId, userRole: ctx?.user?.role,
+                    });
+                    cachedMaskingApplied = cachedRows !== cached.rows;
+                  } catch (err) {
+                    log.warn(
+                      { err: err instanceof Error ? err.message : String(err), connectionId: connId },
+                      "PII masking failed on cached results — returning unmasked results",
+                    );
+                  }
+                }
+                return {
+                  success: true, explanation, row_count: cachedRows.length,
+                  columns: cached.columns, rows: cachedRows,
+                  truncated: cachedRows.length >= getRowLimit(), cached: true,
+                  maskingApplied: cachedMaskingApplied,
+                };
+              },
+              catch: (err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                log.error({ err, connectionId: connId }, "Cache response processing failed");
+                return new QueryExecutionError({ message: `Cache response processing failed: ${message}` });
+              },
+            });
+            return cacheResponse;
+          }
+        } catch (cacheErr) {
+          log.error({ err: cacheErr, connectionId: connId }, "Cache read failed — executing query against database");
+          cacheKey = null;
+        }
       }
-      return { success: false, error: detail };
-    } finally {
-      decrementSourceConcurrency(connId);
-    }
+
+      // Step 5: Execute inside a rate-limit slot (concurrency release is automatic)
+      return yield* withSourceSlot(connId,
+        Effect.gen(function* () {
+          // Plugin beforeQuery hook (may rewrite SQL)
+          const { dispatchHook, dispatchMutableHook } = yield* Effect.tryPromise({
+            try: () => import("@atlas/api/lib/plugins/hooks"),
+            catch: (err) => {
+              const message = err instanceof Error ? err.message : String(err);
+              log.error({ err, connectionId: connId }, "Failed to load plugin hooks module");
+              return new PluginRejectedError({ message: `Plugin system unavailable: ${message}`, connectionId: connId });
+            },
+          });
+          const hookMetadata: Record<string, unknown> = {};
+          const hookCtx = { sql, connectionId: connId, metadata: hookMetadata };
+          const mutatedSql = yield* Effect.tryPromise({
+            try: () => dispatchMutableHook("beforeQuery", hookCtx, "sql"),
+            catch: (err) => {
+              const message = err instanceof Error ? err.message : String(err);
+              return new PluginRejectedError({
+                message: `Query rejected by plugin: ${message}`,
+                connectionId: connId,
+              });
+            },
+          }).pipe(
+            Effect.tapError((error) =>
+              Effect.sync(() =>
+                logQueryAudit({
+                  sql: sql.slice(0, 2000), durationMs: 0, rowCount: null, success: false,
+                  error: `Plugin rejected: ${error.message}`,
+                  sourceId: connId, sourceType: dbType, targetHost,
+                }),
+              ),
+            ),
+          );
+
+          // Re-validate if plugin rewrote the SQL
+          let normalizedMutated = mutatedSql.trim().replace(/;\s*$/, "").trimEnd();
+          if (normalizedMutated !== normalizedSql) {
+            const revalidation = yield* runQueryValidationEffect(normalizedMutated, connId, dbType, customValidator);
+            if (!revalidation.ok) {
+              logQueryAudit({
+                sql: normalizedMutated.slice(0, 2000), durationMs: 0, rowCount: null, success: false,
+                error: `Plugin-rewritten SQL failed validation: ${revalidation.auditError}`,
+                sourceId: connId, sourceType: dbType, targetHost,
+              });
+              return { success: false, error: `Plugin-rewritten SQL failed validation: ${revalidation.error}` };
+            }
+          }
+
+          // RLS: inject WHERE conditions (skipped for custom validators / non-SQL languages)
+          if (!customValidator) {
+            normalizedMutated = yield* applyRLSEffect(normalizedMutated, connId, dbType, targetHost);
+          }
+
+          // Auto-append LIMIT if not present
+          const rowLimit = getRowLimit();
+          const queryTimeout = getQueryTimeout();
+          let querySql = normalizedMutated;
+          if (!customValidator && !/\bLIMIT\b/i.test(querySql)) {
+            querySql += ` LIMIT ${rowLimit}`;
+          }
+
+          // Execute the query
+          return yield* executeAndAuditEffect({
+            db, dbType, connId, orgId, targetHost, querySql, queryTimeout,
+            rowLimit, explanation, classification, cacheKey: cacheKey ?? null,
+            hookMetadata, dispatchHook,
+          });
+        }),
+      ).pipe(
+        // Audit log rate-limit rejections (inner errors have their own audit handling)
+        Effect.tapError((error) => {
+          if (error._tag === "RateLimitExceededError" || error._tag === "ConcurrencyLimitError") {
+            return Effect.sync(() =>
+              logQueryAudit({
+                sql: sql.slice(0, 2000), durationMs: 0, rowCount: null, success: false,
+                error: `Rate limited: ${error.message}`,
+                sourceId: connId, sourceType: dbType, targetHost,
+              }),
+            );
+          }
+          return Effect.void;
+        }),
+      );
+    });
+
+    // Run the pipeline, mapping tagged errors to {success: false} tool responses
+    return Effect.runPromise(
+      pipeline.pipe(
+        Effect.catchAll((error: PipelineError) =>
+          Effect.succeed(pipelineErrorToResponse(error)),
+        ),
+      ),
+    );
   },
 });