@useatlas/create 0.0.5 → 0.0.7

package/templates/nextjs-standalone/src/lib/config.ts

@@ -32,6 +32,17 @@ import type { ToolRegistry } from "./tools/registry";
 import { ACTION_APPROVAL_MODES, type ActionApprovalMode } from "@atlas/api/lib/action-types";
 import { ATLAS_ROLES } from "@atlas/api/lib/auth/types";
 
+// ---------------------------------------------------------------------------
+// Sandbox backend names (used in config validation and explore backend selection)
+// ---------------------------------------------------------------------------
+
+/**
+ * Backend names operators can use in `sandbox.priority`.
+ * Plugin backends are always tried first and are not included here.
+ */
+const SANDBOX_BACKEND_NAMES = ["vercel-sandbox", "nsjail", "sidecar", "just-bash"] as const;
+export type SandboxBackendName = (typeof SANDBOX_BACKEND_NAMES)[number];
+
 const log = createLogger("config");
 
 // ---------------------------------------------------------------------------
@@ -91,6 +102,8 @@ const PerActionConfigSchema = z.object({
   approval: ActionApprovalSchema.optional(),
   /** Minimum role required to approve this action. Overrides the approval mode's default role mapping. */
   requiredRole: AtlasRoleSchema.optional(),
+  /** Execution timeout in milliseconds. Overrides the global defaults.timeout. */
+  timeout: z.number().int().positive().optional(),
   credentials: z.record(z.string(), z.object({ env: z.string() })).optional(),
   rateLimit: z.number().int().positive().optional(),
 }).passthrough();
@@ -103,15 +116,36 @@ const ActionsConfigSchema = z.object({
 
 export type ActionsConfig = z.infer<typeof ActionsConfigSchema>;
 
-const RLSPolicySchema = z.object({
-  /** Tables this policy applies to. Use ["*"] for all tables. */
-  tables: z.array(z.string().min(1)).min(1),
-  /** Column name to filter on in the matched tables. Must be a valid SQL identifier. */
+const RLSConditionSchema = z.object({
+  /** Column name to filter on. Must be a valid SQL identifier. */
   column: z.string().min(1).regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, "Must be a valid column name"),
   /** Claim path to extract the filter value from the user's claims. Supports dot-delimited paths. */
   claim: z.string().min(1),
 });
 
+export type RLSCondition = z.infer<typeof RLSConditionSchema>;
+
+const RLSPolicySchema = z.object({
+  /** Tables this policy applies to. Use ["*"] for all tables. */
+  tables: z.array(z.string().min(1)).min(1),
+  /** Column name to filter on (single-condition shorthand). */
+  column: z.string().min(1).regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, "Must be a valid column name").optional(),
+  /** Claim path (single-condition shorthand). */
+  claim: z.string().min(1).optional(),
+  /** Multiple column/claim conditions — ANDed together within this policy. */
+  conditions: z.array(RLSConditionSchema).min(1).optional(),
+}).refine(
+  (p) => {
+    const hasSingle = p.column !== undefined || p.claim !== undefined;
+    const hasConditions = p.conditions !== undefined;
+    if (hasSingle && hasConditions) return false;
+    if (!hasSingle && !hasConditions) return false;
+    if (hasSingle && (p.column === undefined || p.claim === undefined)) return false;
+    return true;
+  },
+  { message: "Each policy must specify either { column, claim } or { conditions: [...] }, not both" },
+);
+
 export type RLSPolicy = z.infer<typeof RLSPolicySchema>;
 
 const RLSConfigSchema = z.object({
@@ -119,6 +153,8 @@ const RLSConfigSchema = z.object({
   enabled: z.boolean().default(false),
   /** RLS policies. Each policy maps a claim to a column on one or more tables. */
   policies: z.array(RLSPolicySchema).default([]),
+  /** How to combine conditions from different policies. "and" (default) requires all policies to match. "or" requires at least one policy to match. */
+  combineWith: z.enum(["and", "or"]).default("and"),
 }).refine(
   (cfg) => !cfg.enabled || cfg.policies.length > 0,
   { message: "RLS is enabled but no policies are defined", path: ["policies"] },
@@ -126,6 +162,90 @@ const RLSConfigSchema = z.object({
 
 export type RLSConfig = z.infer<typeof RLSConfigSchema>;
 
+const SandboxConfigSchema = z.object({
+  /**
+   * Ordered list of explore backends to try. The first available backend is
+   * used. Plugin backends are always tried first (not listed here).
+   *
+   * Valid values: "vercel-sandbox", "nsjail", "sidecar", "just-bash".
+   *
+   * @example ["sidecar", "nsjail", "just-bash"]
+   */
+  priority: z.array(z.enum(SANDBOX_BACKEND_NAMES)).min(1)
+    .refine(
+      (arr) => new Set(arr).size === arr.length,
+      { message: "sandbox.priority must not contain duplicate backend names" },
+    )
+    .optional(),
+});
+
+export type SandboxConfig = z.infer<typeof SandboxConfigSchema>;
+
+/** Modules that can never be unblocked via `allowModules`. */
+const PYTHON_CRITICAL_MODULES = ["os", "subprocess", "sys", "shutil"];
+
+const PythonConfigSchema = z.object({
+  /** Additional modules to block (added to the default blocked list). */
+  blockedModules: z.array(z.string().min(1, "Module name must not be empty")).default([]),
+  /** Modules to remove from the default blocked list. Critical modules (os, subprocess, sys, shutil) cannot be unblocked. */
+  allowModules: z.array(z.string().min(1, "Module name must not be empty")).default([]),
+}).refine(
+  (cfg) => !cfg.allowModules.some((m: string) => PYTHON_CRITICAL_MODULES.includes(m)),
+  {
+    message: `Cannot unblock critical Python modules (${PYTHON_CRITICAL_MODULES.join(", ")}). These are blocked regardless of configuration.`,
+    path: ["allowModules"],
+  },
+);
+
+export type PythonConfig = z.infer<typeof PythonConfigSchema>;
+
+const OrgPoolConfigSchema = z.object({
+  /** Max connections per pool per org. Default 5. */
+  maxConnections: z.number().int().positive().default(5),
+  /** Idle timeout in ms for per-org pool connections. Default 30000. */
+  idleTimeoutMs: z.number().int().positive().default(30000),
+  /** Max org pool sets before LRU eviction. Default 50. */
+  maxOrgs: z.number().int().positive().default(50),
+  /** Warmup probes when an org pool is first created. Default 2. */
+  warmupProbes: z.number().int().nonnegative().default(2),
+  /** Consecutive query errors before auto-drain of an org pool. Default 5. */
+  drainThreshold: z.number().int().positive().default(5),
+});
+
+export type OrgPoolConfigInput = z.input<typeof OrgPoolConfigSchema>;
+
+const PoolConfigSchema = z.object({
+  /** Per-org pool isolation settings. When configured, each org gets its own
+   *  connection pool for noisy-neighbor isolation in SaaS mode. */
+  perOrg: OrgPoolConfigSchema.optional(),
+});
+
+const RegionConfigSchema = z.object({
+  /** Human-readable region label for the admin console. */
+  label: z.string().min(1),
+  /** Database URL for the region's internal database. */
+  databaseUrl: z.string().min(1, "Region database URL must not be empty"),
+  /** Optional datasource URL override for analytics in this region. */
+  datasourceUrl: z.string().min(1).optional(),
+});
+
+export type RegionConfigInput = z.input<typeof RegionConfigSchema>;
+
+const ResidencyConfigSchema = z.object({
+  /** Available regions and their database configuration. Keys are region identifiers (e.g. "eu-west"). */
+  regions: z.record(z.string().min(1), RegionConfigSchema).refine(
+    (r) => Object.keys(r).length > 0,
+    { message: "At least one region must be configured when residency is enabled" },
+  ),
+  /** Default region for new workspaces. Must be a key in the regions map. */
+  defaultRegion: z.string().min(1),
+}).refine(
+  (cfg) => cfg.defaultRegion in cfg.regions,
+  { message: "defaultRegion must be one of the configured regions", path: ["defaultRegion"] },
+);
+
+export type ResidencyConfig = z.infer<typeof ResidencyConfigSchema>;
+
 const AtlasConfigSchema = z.object({
   /**
    * Named datasource connections. The "default" key is used when no
@@ -195,6 +315,98 @@ const AtlasConfigSchema = z.object({
    * automatic WHERE clause injection based on the authenticated user's claims.
    */
   rls: RLSConfigSchema.optional(),
+
+  /**
+   * Sandbox / explore backend configuration. Override the default backend
+   * selection priority for the explore tool.
+   */
+  sandbox: SandboxConfigSchema.optional(),
+
+  /**
+   * Python tool import guard configuration. Customize which modules are
+   * blocked or allowed in the defense-in-depth import checker.
+   */
+  python: PythonConfigSchema.optional(),
+
+  /**
+   * Session timeout configuration. Idle timeout invalidates sessions that
+   * haven't been used within the specified duration. Absolute timeout
+   * invalidates sessions after a fixed duration regardless of activity.
+   * Values are in seconds. 0 means disabled.
+   */
+  session: z.object({
+    /** Seconds of inactivity before a session is invalidated. 0 = disabled. */
+    idleTimeout: z.number().int().nonnegative().default(0),
+    /** Maximum session lifetime in seconds from creation. 0 = disabled. */
+    absoluteTimeout: z.number().int().nonnegative().default(0),
+  }).optional(),
+
+  /**
+   * Semantic index configuration. When enabled (default), a pre-computed
+   * summary of the semantic layer is injected into the agent system prompt
+   * to reduce explore tool calls.
+   */
+  semanticIndex: z.object({
+    /** Whether the semantic index is enabled. Default: true. */
+    enabled: z.boolean().default(true),
+  }).optional(),
+
+  /**
+   * Connection pool configuration. The `perOrg` sub-key enables tenant-scoped
+   * pooling in SaaS mode — each org gets isolated pool instances to prevent
+   * noisy-neighbor issues.
+   */
+  pool: PoolConfigSchema.optional(),
+
+  /**
+   * Query result cache configuration. When enabled (default), identical
+   * queries return cached results within the TTL. Cache keys include
+   * orgId for tenant isolation.
+   */
+  cache: z.object({
+    /** Whether query caching is enabled. Default: true. */
+    enabled: z.boolean().default(true),
+    /** Time-to-live in milliseconds. Default: 300000 (5 minutes). */
+    ttl: z.number().int().positive().default(300_000),
+    /** Maximum number of cached entries. Default: 1000. */
+    maxSize: z.number().int().positive().default(1000),
+  }).optional(),
+
+  /**
+   * Dynamic learning configuration. Controls how learned query patterns
+   * are promoted and injected into agent context.
+   */
+  learn: z.object({
+    /** Minimum confidence score for a pattern to be eligible for auto-promotion. Default: 0.7. */
+    confidenceThreshold: z.number().min(0).max(1).default(0.7),
+  }).optional(),
+
+  /**
+   * Enterprise feature gating. When enabled, enterprise-only features
+   * in `/ee` are unlocked at runtime. A license key is required for
+   * production use. AGPL core is completely unaffected when this is
+   * absent or disabled.
+   */
+  enterprise: z.object({
+    /** Whether enterprise features are enabled. Default: false. */
+    enabled: z.boolean().default(false),
+    /** License key for enterprise features. */
+    licenseKey: z.string().min(1).optional(),
+  }).optional(),
+
+  /**
+   * Deploy mode. "saas" enables hosted product features (enterprise-gated),
+   * "self-hosted" disables them, "auto" (default) detects from environment.
+   * The resolved binary value is exposed as `deployMode` on ResolvedConfig.
+   */
+  deployMode: z.enum(["auto", "saas", "self-hosted"]).optional().default("auto"),
+
+  /**
+   * Data residency configuration. When configured, workspaces are assigned
+   * to geographic regions and connections route to region-specific databases.
+   * Requires enterprise features to be enabled.
+   */
+  residency: ResidencyConfigSchema.optional(),
 });
 
 /** The output type after Zod parsing (defaults applied, all fields present). */
@@ -203,8 +415,8 @@ export type AtlasConfig = z.infer<typeof AtlasConfigSchema>;
 /** The input type for user-authored config (optional fields allowed). */
 export type AtlasConfigInput = z.input<typeof AtlasConfigSchema>;
 
-/** Expose schemas for external validation (e.g. tests). */
-export { AtlasConfigSchema, RateLimitConfigSchema, RLSPolicySchema, RLSConfigSchema };
+/** Expose schemas and formatter for external validation (e.g. tests, CLI). */
+export { AtlasConfigSchema, RateLimitConfigSchema, RLSConditionSchema, RLSPolicySchema, RLSConfigSchema, SandboxConfigSchema, PythonConfigSchema, PoolConfigSchema, OrgPoolConfigSchema, ResidencyConfigSchema };
 
 /**
  * The resolved config after merging the config file with env var defaults.
@@ -230,6 +442,26 @@ export interface ResolvedConfig {
   };
   /** Row-Level Security configuration. */
   rls?: RLSConfig;
+  /** Sandbox / explore backend configuration. */
+  sandbox?: SandboxConfig;
+  /** Python tool import guard overrides. */
+  python?: PythonConfig;
+  /** Session timeout configuration. */
+  session?: { idleTimeout: number; absoluteTimeout: number };
+  /** Semantic index configuration. */
+  semanticIndex?: { enabled: boolean };
+  /** Connection pool configuration for tenant-scoped pooling. */
+  pool?: { perOrg?: { maxConnections: number; idleTimeoutMs: number; maxOrgs: number; warmupProbes: number; drainThreshold: number } };
+  /** Query result cache configuration. */
+  cache?: { enabled: boolean; ttl: number; maxSize: number };
+  /** Dynamic learning configuration. */
+  learn?: { confidenceThreshold: number };
+  /** Enterprise feature gating. */
+  enterprise?: { enabled: boolean; licenseKey?: string };
+  /** Data residency configuration for region-based routing. */
+  residency?: ResidencyConfig;
+  /** Resolved deploy mode — binary "saas" or "self-hosted" (auto is resolved at boot). */
+  deployMode?: "saas" | "self-hosted";
   /** Whether the config was loaded from a file or synthesized from env vars. */
   source: "file" | "env";
 }
@@ -331,7 +563,39 @@ export function configFromEnv(): ResolvedConfig {
         `Got: ATLAS_RLS_COLUMN=${column ?? "(unset)"}, ATLAS_RLS_CLAIM=${claim ?? "(unset)"}`,
       );
     }
-    rls = { enabled: true, policies: [{ tables: ["*"], column, claim }] };
+    const rlsParseResult = RLSConfigSchema.safeParse({
+      enabled: true,
+      policies: [{ tables: ["*"], column, claim }],
+      combineWith: "and",
+    });
+    if (!rlsParseResult.success) {
+      throw new Error(
+        `Invalid RLS environment variable configuration: ${rlsParseResult.error.issues.map((i) => i.message).join("; ")}. ` +
+        `Check ATLAS_RLS_COLUMN (must be a valid SQL identifier) and ATLAS_RLS_CLAIM.`,
+      );
+    }
+    rls = rlsParseResult.data;
+  }
+
+  // Sandbox priority from env var (comma-separated backend names)
+  let sandbox: SandboxConfig | undefined;
+  const rawPriority = process.env.ATLAS_SANDBOX_PRIORITY;
+  if (rawPriority) {
+    const names = rawPriority.split(",").map((s) => s.trim()).filter(Boolean);
+    if (names.length === 0) {
+      throw new Error(
+        `ATLAS_SANDBOX_PRIORITY is set but empty after parsing. ` +
+        `Expected comma-separated backend names: ${SANDBOX_BACKEND_NAMES.join(", ")}`,
+      );
+    }
+    const parseResult = SandboxConfigSchema.safeParse({ priority: names });
+    if (!parseResult.success) {
+      throw new Error(
+        `Invalid ATLAS_SANDBOX_PRIORITY: ${parseResult.error.issues.map((i) => i.message).join("; ")}. ` +
+        `Valid backends: ${SANDBOX_BACKEND_NAMES.join(", ")}`,
+      );
+    }
+    sandbox = parseResult.data;
   }
 
   return {
@@ -343,6 +607,48 @@ export function configFromEnv(): ResolvedConfig {
     maxTotalConnections: 100,
     ...(scheduler ? { scheduler } : {}),
     ...(rls ? { rls } : {}),
+    ...(sandbox ? { sandbox } : {}),
+    // Session timeout from env vars
+    ...((() => {
+      const idle = parseInt(process.env.ATLAS_SESSION_IDLE_TIMEOUT ?? "", 10);
+      const abs = parseInt(process.env.ATLAS_SESSION_ABSOLUTE_TIMEOUT ?? "", 10);
+      const idleTimeout = Number.isFinite(idle) && idle > 0 ? idle : 0;
+      const absoluteTimeout = Number.isFinite(abs) && abs > 0 ? abs : 0;
+      return (idleTimeout > 0 || absoluteTimeout > 0) ? { session: { idleTimeout, absoluteTimeout } } : {};
+    })()),
+    // Semantic index from env vars
+    ...(process.env.ATLAS_SEMANTIC_INDEX_ENABLED === "false"
+      ? { semanticIndex: { enabled: false } }
+      : {}),
+    // Cache config from env vars
+    ...((() => {
+      const enabled = process.env.ATLAS_CACHE_ENABLED !== "false" && process.env.ATLAS_CACHE_ENABLED !== "0";
+      const ttl = parseInt(process.env.ATLAS_CACHE_TTL ?? "", 10);
+      const maxSize = parseInt(process.env.ATLAS_CACHE_MAX_SIZE ?? "", 10);
+      return {
+        cache: {
+          enabled,
+          ttl: Number.isFinite(ttl) && ttl > 0 ? ttl : 300_000,
+          maxSize: Number.isFinite(maxSize) && maxSize > 0 ? maxSize : 1000,
+        },
+      };
+    })()),
+    // Learn config from env vars
+    ...((() => {
+      const threshold = parseFloat(process.env.ATLAS_LEARN_CONFIDENCE_THRESHOLD ?? "");
+      return {
+        learn: {
+          confidenceThreshold: Number.isFinite(threshold) && threshold >= 0 && threshold <= 1 ? threshold : 0.7,
+        },
+      };
+    })()),
+    // Enterprise config from env vars
+    enterprise: {
+      enabled: process.env.ATLAS_ENTERPRISE_ENABLED === "true",
+      ...(process.env.ATLAS_ENTERPRISE_LICENSE_KEY
+        ? { licenseKey: process.env.ATLAS_ENTERPRISE_LICENSE_KEY }
+        : {}),
+    },
     source: "env",
   };
 }
@@ -475,6 +781,184 @@ function validatePlugins(plugins: unknown[]): void {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Zod error formatting
+// ---------------------------------------------------------------------------
+
+/** Loosely-typed Zod issue — works across Zod v3 and v4. */
+type Issue = z.ZodError["issues"][number];
+
+/**
+ * Human-readable labels for config fields. Used to give context beyond
+ * raw Zod type names (e.g. "connection URL" for datasources.*.url).
+ */
+const FIELD_HINTS: Record<string, string> = {
+  "datasources.*.url": "connection URL",
+  auth: "auth mode",
+  semanticLayer: "path to the semantic layer directory",
+  maxTotalConnections: "max total pool connections",
+};
+
+/** Map of common misspellings/variants to the correct value. */
+const COMMON_SUGGESTIONS: Record<string, Record<string, string>> = {
+  auth: {
+    "apiKey": "api-key",
+    "api_key": "api-key",
+    "apikey": "api-key",
+    "API-KEY": "api-key",
+    "API_KEY": "api-key",
+    "basic": "api-key",
+    "bearer": "byot",
+    "token": "byot",
+    "bring-your-own-token": "byot",
+    "true": "managed",
+    "false": "none",
+    "off": "none",
+    "on": "auto",
+    "default": "auto",
+  },
+};
+
+/**
+ * Look up a human-readable hint for a field path. Supports wildcards:
+ * `datasources.mydb.url` matches `datasources.*.url`.
+ */
+function getFieldHint(fieldPath: string): string | undefined {
+  if (FIELD_HINTS[fieldPath]) return FIELD_HINTS[fieldPath];
+  // Try wildcard: replace middle segments with *
+  const parts = fieldPath.split(".");
+  if (parts.length >= 3) {
+    const wildcard = `${parts[0]}.*.${parts.slice(2).join(".")}`;
+    if (FIELD_HINTS[wildcard]) return FIELD_HINTS[wildcard];
+  }
+  return undefined;
+}
+
+/**
+ * Extract the received value from the issue's message (Zod v4 encodes
+ * it in the message string rather than a dedicated field).
+ */
+function extractReceived(issue: Issue): string | undefined {
+  // Zod v4 invalid_type message: "Invalid input: expected string, received number"
+  const match = issue.message.match(/received (\S+)/);
+  if (match) return match[1];
+  return undefined;
+}
+
+/**
+ * Check if the received value for a field has a common suggestion.
+ */
+function getSuggestion(fieldPath: string, input: unknown): string | undefined {
+  const topField = fieldPath.split(".")[0];
+  const suggestions = COMMON_SUGGESTIONS[topField];
+  if (!suggestions || typeof input !== "string") return undefined;
+  const correct = suggestions[input];
+  if (correct) return `Did you mean "${correct}"?`;
+  return undefined;
+}
+
+/**
+ * Format a single Zod issue into a human-readable line.
+ */
+function formatIssue(issue: Issue, rawInput: unknown): string {
+  const fieldPath = issue.path.length > 0
+    ? issue.path.map(String).join(".")
+    : "(root)";
+  const hint = getFieldHint(fieldPath);
+
+  // Resolve the value that was actually passed for this path
+  let inputAtPath: unknown = rawInput;
+  for (const segment of issue.path) {
+    if (inputAtPath != null && typeof inputAtPath === "object") {
+      inputAtPath = (inputAtPath as Record<string, unknown>)[String(segment)];
+    } else {
+      inputAtPath = undefined;
+      break;
+    }
+  }
+
+  let line: string;
+  // Use unknown-typed accessor to handle Zod v4 issue shapes safely
+  const issueObj = issue as unknown as Record<string, unknown>;
+
+  switch (issue.code) {
+    case "invalid_type": {
+      const expected = String(issueObj.expected ?? "unknown");
+      const received = extractReceived(issue) ?? typeof inputAtPath;
+      const expectedLabel = hint ? `${expected} (${hint})` : expected;
+      line = `Config error at ${fieldPath}: expected ${expectedLabel}, got ${received}`;
+      break;
+    }
+    case "invalid_union": {
+      // Zod v4: `errors` is an array of issue arrays
+      const unionErrors = issueObj.errors as unknown[][] | undefined;
+      const validOptions: string[] = [];
+      if (unionErrors) {
+        for (const errGroup of unionErrors) {
+          const issues = Array.isArray(errGroup) ? errGroup : [];
+          for (const sub of issues) {
+            const subObj = sub as Record<string, unknown>;
+            // Zod v4 uses "invalid_value" with a "values" array
+            if (subObj.code === "invalid_value" && Array.isArray(subObj.values)) {
+              for (const v of subObj.values) {
+                const opt = `"${v}"`;
+                if (!validOptions.includes(opt)) validOptions.push(opt);
+              }
+            }
+            // Zod v3 uses "invalid_literal" with "expected"
+            if (subObj.code === "invalid_literal" && subObj.expected !== undefined) {
+              const opt = `"${subObj.expected}"`;
+              if (!validOptions.includes(opt)) validOptions.push(opt);
+            }
+          }
+        }
+      }
+      if (validOptions.length > 0) {
+        line = `Config error at ${fieldPath}: invalid value. Valid options: ${validOptions.join(", ")}`;
+      } else {
+        line = `Config error at ${fieldPath}: ${issue.message}`;
+      }
+      break;
+    }
+    case "invalid_value": {
+      // Zod v4 uses "invalid_value" for enums and literals
+      const values = issueObj.values as unknown[] | undefined;
+      if (values && values.length > 0) {
+        line = `Config error at ${fieldPath}: invalid value. Valid options: ${values.map((o) => `"${o}"`).join(", ")}`;
+      } else {
+        line = `Config error at ${fieldPath}: ${issue.message}`;
+      }
+      break;
+    }
+    default: {
+      line = `Config error at ${fieldPath}: ${issue.message}`;
+    }
+  }
+
+  // Append suggestion for common mistakes
+  const suggestion = getSuggestion(fieldPath, inputAtPath);
+  if (suggestion) {
+    line += ` — ${suggestion}`;
+  }
+
+  return line;
+}
+
+/**
+ * Format a ZodError into human-readable, multi-line error messages.
+ *
+ * Each line shows the field path, expected type, and received value.
+ * Common mistakes get targeted suggestions (e.g. "did you mean 'api-key'?").
+ * All errors are shown, not just the first one.
+ *
+ * @param error - The ZodError to format.
+ * @param rawInput - The original input that was validated (used to resolve
+ *   actual received values and to generate suggestions).
+ */
+export function formatZodErrors(error: z.ZodError, rawInput?: unknown): string {
+  return error.issues.map((issue) => `  - ${formatIssue(issue, rawInput)}`).join("\n");
+}
+
 /**
  * Validate a raw config object against the Zod schema and return a
  * ResolvedConfig. Throws on validation failure with human-readable errors.
@@ -488,10 +972,7 @@ export function validateAndResolve(raw: unknown): ResolvedConfig {
 
   const parseResult = AtlasConfigSchema.safeParse(raw);
   if (!parseResult.success) {
-    const formatted = parseResult.error.issues
-      .map((issue) => `  - ${issue.path.join(".")}: ${issue.message}`)
-      .join("\n");
-    throw new Error(`Invalid atlas.config.ts:\n${formatted}`);
+    throw new Error(`Invalid atlas.config.ts:\n${formatZodErrors(parseResult.error, raw)}`);
   }
 
   const config = parseResult.data;
@@ -511,6 +992,15 @@ export function validateAndResolve(raw: unknown): ResolvedConfig {
     ...(config.plugins?.length ? { plugins: config.plugins } : {}),
     ...(config.scheduler ? { scheduler: config.scheduler } : {}),
     ...(config.rls ? { rls: config.rls } : {}),
+    ...(config.sandbox ? { sandbox: config.sandbox } : {}),
+    ...(config.python ? { python: config.python } : {}),
+    ...(config.session ? { session: config.session } : {}),
+    ...(config.semanticIndex ? { semanticIndex: config.semanticIndex } : {}),
+    ...(config.pool ? { pool: config.pool } : {}),
+    ...(config.cache ? { cache: config.cache } : {}),
+    ...(config.learn ? { learn: config.learn } : {}),
+    ...(config.enterprise ? { enterprise: config.enterprise } : {}),
+    ...(config.residency ? { residency: config.residency } : {}),
     source: "file",
   };
 }
@@ -531,6 +1021,43 @@ export function validateAndResolve(raw: unknown): ResolvedConfig {
  * @throws {Error} When the config file exists but is invalid (Zod errors
  *   are formatted into a human-readable message).
  */
+/**
+ * Resolve the deploy mode for a ResolvedConfig.
+ *
+ * Tries to load `resolveDeployMode` from the enterprise (`ee/`) package.
+ * When the enterprise module is not available, falls back to `"self-hosted"`.
+ * Mutates `resolved.deployMode` in place and logs the result.
+ */
+async function applyDeployMode(
+  resolved: ResolvedConfig,
+  configFileValue?: "auto" | "saas" | "self-hosted",
+): Promise<void> {
+  // Env var takes priority over config file; config file takes priority over default
+  const rawSetting = (process.env.ATLAS_DEPLOY_MODE ?? configFileValue) as
+    | "saas" | "self-hosted" | "auto" | undefined;
+
+  // Warn on unrecognized values
+  if (rawSetting && !["auto", "saas", "self-hosted"].includes(rawSetting)) {
+    log.warn(
+      { value: rawSetting },
+      "Unrecognized ATLAS_DEPLOY_MODE value — treating as auto",
+    );
+  }
+
+  try {
+    const { resolveDeployMode } = await import("@atlas/ee/deploy-mode");
+    resolved.deployMode = resolveDeployMode(rawSetting);
+  } catch (err) {
+    // ee/ module not available — default to self-hosted
+    log.debug(
+      { err: err instanceof Error ? err.message : String(err) },
+      "Deploy mode resolution unavailable — defaulting to self-hosted",
+    );
+    resolved.deployMode = "self-hosted";
+  }
+  log.info({ deployMode: resolved.deployMode }, "Deploy mode resolved");
+}
+
 export async function loadConfig(
   projectRoot: string = process.cwd(),
 ): Promise<ResolvedConfig> {
@@ -539,11 +1066,15 @@ export async function loadConfig(
   if (raw === null) {
     log.info("No atlas.config.ts found — using environment variables");
     const resolved = configFromEnv();
+    await applyDeployMode(resolved);
     _resolved = resolved;
     return resolved;
   }
 
+  const configDeployMode = (raw as Record<string, unknown>).deployMode as
+    | "auto" | "saas" | "self-hosted" | undefined;
   const resolved = validateAndResolve(raw);
+  await applyDeployMode(resolved, configDeployMode);
 
   log.info(
     {
@@ -556,6 +1087,18 @@ export async function loadConfig(
   );
 
   _resolved = resolved;
+
+  // Flush query cache on config reload to avoid stale results
+  try {
+    const { flushCache } = await import("@atlas/api/lib/cache/index");
+    flushCache();
+  } catch (err) {
+    // Dynamic import may fail on first load before cache is wired — other errors must be logged
+    if (err instanceof Error && !err.message.includes("Cannot find module")) {
+      log.warn({ err: err.message }, "Failed to flush query cache during config reload");
+    }
+  }
+
   return resolved;
 }
 
@@ -585,6 +1128,10 @@ export async function applyDatasources(
 
   connRegistry.setMaxTotalConnections(config.maxTotalConnections);
 
+  if (config.pool?.perOrg) {
+    connRegistry.setOrgPoolConfig(config.pool.perOrg);
+  }
+
   for (const [id, ds] of Object.entries(config.datasources)) {
     try {
       log.info({ connectionId: id }, "Registering datasource from config");
@@ -700,3 +1247,8 @@ export async function initializeConfig(
 export function _resetConfig(): void {
   _resolved = null;
 }
+
+/** Set the cached config directly. For testing only. */
+export function _setConfigForTest(config: ResolvedConfig | null): void {
+  _resolved = config;
+}