@xylex-group/athena 2.0.0 → 2.3.0

package/dist/cli/index.js

@@ -1,11 +1,15 @@
-import { mkdir, writeFile } from 'fs/promises';
+import { mkdir, writeFile, stat } from 'fs/promises';
 import { resolve, dirname, posix } from 'path';
-import { existsSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { pathToFileURL } from 'url';
-import { Pool } from 'pg';
 
 // src/generator/pipeline.ts
 
+// src/utils/slugify.ts
+function slugify(input) {
+  return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64);
+}
+
 // src/generator/naming.ts
 var IDENTIFIER_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
 var RESERVED_IDENTIFIERS = /* @__PURE__ */ new Set([
@@ -101,7 +105,7 @@ function applyNamingStyle(input, style) {
     case "snake":
       return words.map((word) => word.toLowerCase()).join("_");
     case "kebab":
-      return words.map((word) => word.toLowerCase()).join("-");
+      return slugify(words.join("-"));
     default:
       return input;
   }
@@ -147,9 +151,13 @@ function resolvePlaceholderMap(baseTokens, outputConfig) {
   const resolved = {
     ...baseTokens
   };
+  const reservedTokenKeys = new Set(Object.keys(baseTokens));
   const entries = Object.entries(outputConfig.placeholderMap ?? {});
   for (let index = 0; index < entries.length; index += 1) {
     const [key, value] = entries[index];
+    if (reservedTokenKeys.has(key)) {
+      continue;
+    }
     let current = value;
     for (let depth = 0; depth < 8; depth += 1) {
       const next = renderTemplate(current, resolved);
@@ -346,8 +354,11 @@ var AthenaGatewayError = class _AthenaGatewayError extends Error {
     });
   }
 };
+function isAthenaGatewayError(error) {
+  return error instanceof AthenaGatewayError;
+}
 
-// src/auxiliaries.ts
+// src/utils/parse-boolean-flag.ts
 function parseBooleanFlag(rawValue, fallback) {
   if (!rawValue) return fallback;
   const normalized = rawValue.trim().toLowerCase();
@@ -360,6 +371,293 @@ function parseBooleanFlag(rawValue, fallback) {
   return fallback;
 }
 
+// src/auxiliaries.ts
+var AthenaErrorCode = {
+  UniqueViolation: "UNIQUE_VIOLATION",
+  NotFound: "NOT_FOUND",
+  ValidationFailed: "VALIDATION_FAILED",
+  AuthUnauthorized: "AUTH_UNAUTHORIZED",
+  AuthForbidden: "AUTH_FORBIDDEN",
+  RateLimited: "RATE_LIMITED",
+  NetworkUnavailable: "NETWORK_UNAVAILABLE",
+  TransientFailure: "TRANSIENT_FAILURE",
+  HttpFailure: "HTTP_FAILURE",
+  Unknown: "UNKNOWN"
+};
+var AthenaErrorCategory = {
+  Transport: "transport",
+  Client: "client",
+  Server: "server",
+  Database: "database",
+  Unknown: "unknown"
+};
+function parseBooleanFlag2(rawValue, fallback) {
+  return parseBooleanFlag(rawValue, fallback);
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function firstNonEmptyString(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value.trim();
+    }
+  }
+  return void 0;
+}
+function messageFromUnknownError(error) {
+  if (typeof error === "string" && error.trim().length > 0) {
+    return error.trim();
+  }
+  if (error instanceof Error && error.message.trim().length > 0) {
+    return error.message.trim();
+  }
+  if (!isRecord(error)) {
+    return void 0;
+  }
+  return firstNonEmptyString(error.message, error.error, error.details);
+}
+function gatewayCodeFromUnknownError(error) {
+  if (!isRecord(error) || typeof error.gatewayCode !== "string") {
+    return void 0;
+  }
+  return error.gatewayCode;
+}
+function isAthenaResultErrorLike(value) {
+  return isRecord(value) && typeof value.message === "string" && (value.athenaCode === void 0 || isAthenaErrorCode(value.athenaCode)) && (value.kind === void 0 || isAthenaErrorKind(value.kind)) && (value.category === void 0 || isAthenaErrorCategory(value.category)) && (value.retryable === void 0 || typeof value.retryable === "boolean") && (value.status === void 0 || typeof value.status === "number");
+}
+function isAthenaErrorKind(value) {
+  return value === "unique_violation" || value === "not_found" || value === "validation" || value === "auth" || value === "rate_limit" || value === "transient" || value === "unknown";
+}
+function isAthenaErrorCode(value) {
+  return value === "UNIQUE_VIOLATION" || value === "NOT_FOUND" || value === "VALIDATION_FAILED" || value === "AUTH_UNAUTHORIZED" || value === "AUTH_FORBIDDEN" || value === "RATE_LIMITED" || value === "NETWORK_UNAVAILABLE" || value === "TRANSIENT_FAILURE" || value === "HTTP_FAILURE" || value === "UNKNOWN";
+}
+function isAthenaErrorCategory(value) {
+  return value === "transport" || value === "client" || value === "server" || value === "database" || value === "unknown";
+}
+function isNormalizedAthenaError(value) {
+  return isRecord(value) && isAthenaErrorKind(value.kind) && isAthenaErrorCode(value.code) && isAthenaErrorCategory(value.category) && typeof value.retryable === "boolean" && typeof value.message === "string" && "raw" in value;
+}
+function withContextOverrides(normalized, context) {
+  if (!context?.table && !context?.operation) {
+    return normalized;
+  }
+  return {
+    ...normalized,
+    table: context.table ?? normalized.table,
+    operation: context.operation ?? normalized.operation
+  };
+}
+function resolveAttachedNormalizedError(resultOrError) {
+  if (!isRecord(resultOrError)) return void 0;
+  if (!("__athenaNormalizedError" in resultOrError)) return void 0;
+  const candidate = resultOrError.__athenaNormalizedError;
+  return isNormalizedAthenaError(candidate) ? candidate : void 0;
+}
+function isAthenaResultLike(value) {
+  return isRecord(value) && "status" in value && "error" in value && "data" in value && typeof value.status === "number";
+}
+function operationFromDetails(details) {
+  if (!details?.endpoint) return void 0;
+  if (details.endpoint === "/gateway/fetch" || details.endpoint === "/gateway/query") return "select";
+  if (details.endpoint === "/gateway/insert") return "insert";
+  if (details.endpoint === "/gateway/update") return "update";
+  if (details.endpoint === "/gateway/delete") return "delete";
+  if (details.endpoint === "/gateway/rpc" || details.endpoint.startsWith("/rpc/")) return "rpc";
+  return void 0;
+}
+function matchRegex(input, patterns) {
+  for (const pattern of patterns) {
+    const match = pattern.exec(input);
+    if (match?.[1]) return match[1];
+  }
+  return void 0;
+}
+function extractConstraint(message) {
+  return matchRegex(message, [
+    /unique constraint\s+["'`]([^"'`]+)["'`]/i,
+    /constraint\s+["'`]([^"'`]+)["'`]/i
+  ]);
+}
+function extractTable(message) {
+  return matchRegex(message, [
+    /(?:table|relation)\s+["'`]([^"'`]+)["'`]/i,
+    /on\s+table\s+([a-zA-Z0-9_.]+)/i
+  ]);
+}
+function classifyKind(status, code, message) {
+  const lower = message.toLowerCase();
+  const hasUniquePattern = lower.includes("unique constraint") || lower.includes("duplicate key") || lower.includes("already exists") || lower.includes("duplicate");
+  const hasNotFoundPattern = lower.includes("not found") || lower.includes("no rows");
+  const hasValidationPattern = lower.includes("validation") || lower.includes("invalid") || lower.includes("malformed");
+  const hasAuthPattern = lower.includes("unauthorized") || lower.includes("forbidden") || lower.includes("auth");
+  const hasRateLimitPattern = lower.includes("rate limit") || lower.includes("too many requests");
+  const hasTransientPattern = lower.includes("timeout") || lower.includes("temporar") || lower.includes("connection reset") || lower.includes("socket") || lower.includes("deadlock");
+  if (status === 409 || hasUniquePattern) return "unique_violation";
+  if (status === 404 || hasNotFoundPattern) return "not_found";
+  if (status === 401 || status === 403 || hasAuthPattern) return "auth";
+  if (status === 429 || hasRateLimitPattern) return "rate_limit";
+  if (status === 400 || status === 422 || hasValidationPattern) return "validation";
+  if (code === "NETWORK_ERROR" || status === 0 || status !== void 0 && status >= 500 || hasTransientPattern) {
+    return "transient";
+  }
+  return "unknown";
+}
+function toAthenaErrorCode(kind, status, gatewayCode) {
+  if (gatewayCode === "NETWORK_ERROR" || kind === "transient" && status === 0) {
+    return AthenaErrorCode.NetworkUnavailable;
+  }
+  switch (kind) {
+    case "unique_violation":
+      return AthenaErrorCode.UniqueViolation;
+    case "not_found":
+      return AthenaErrorCode.NotFound;
+    case "validation":
+      return AthenaErrorCode.ValidationFailed;
+    case "rate_limit":
+      return AthenaErrorCode.RateLimited;
+    case "auth":
+      if (status === 403) {
+        return AthenaErrorCode.AuthForbidden;
+      }
+      return AthenaErrorCode.AuthUnauthorized;
+    case "transient":
+      return status !== void 0 && status >= 500 ? AthenaErrorCode.HttpFailure : AthenaErrorCode.TransientFailure;
+    case "unknown":
+    default:
+      return status !== void 0 && status >= 400 ? AthenaErrorCode.HttpFailure : AthenaErrorCode.Unknown;
+  }
+}
+function toAthenaErrorCategory(kind, status) {
+  if (kind === "transient" && (status === 0 || status === void 0)) {
+    return AthenaErrorCategory.Transport;
+  }
+  if (kind === "unique_violation") return AthenaErrorCategory.Database;
+  if (kind === "validation" || kind === "auth" || kind === "not_found") return AthenaErrorCategory.Client;
+  if (kind === "rate_limit" || kind === "transient") return AthenaErrorCategory.Server;
+  return AthenaErrorCategory.Unknown;
+}
+function isRetryable(kind, status) {
+  if (kind === "rate_limit" || kind === "transient") return true;
+  return status !== void 0 && status >= 500;
+}
+function normalizeAthenaError(resultOrError, context) {
+  const attached = resolveAttachedNormalizedError(resultOrError);
+  if (attached) {
+    return withContextOverrides(attached, context);
+  }
+  if (isAthenaResultLike(resultOrError)) {
+    if (isAthenaResultErrorLike(resultOrError.error)) {
+      return {
+        kind: resultOrError.error.kind ?? classifyKind(resultOrError.status, gatewayCodeFromUnknownError(resultOrError.error), resultOrError.error.message),
+        code: resultOrError.error.athenaCode ?? toAthenaErrorCode(
+          resultOrError.error.kind ?? classifyKind(
+            resultOrError.status,
+            gatewayCodeFromUnknownError(resultOrError.error),
+            resultOrError.error.message
+          ),
+          resultOrError.error.status ?? resultOrError.status,
+          gatewayCodeFromUnknownError(resultOrError.error)
+        ),
+        category: resultOrError.error.category ?? toAthenaErrorCategory(
+          resultOrError.error.kind ?? classifyKind(
+            resultOrError.status,
+            gatewayCodeFromUnknownError(resultOrError.error),
+            resultOrError.error.message
+          ),
+          resultOrError.error.status ?? resultOrError.status
+        ),
+        retryable: resultOrError.error.retryable ?? isRetryable(
+          resultOrError.error.kind ?? classifyKind(
+            resultOrError.status,
+            gatewayCodeFromUnknownError(resultOrError.error),
+            resultOrError.error.message
+          ),
+          resultOrError.error.status ?? resultOrError.status
+        ),
+        status: resultOrError.error.status ?? resultOrError.status,
+        constraint: resultOrError.error.constraint,
+        table: context?.table ?? resultOrError.error.table,
+        operation: context?.operation ?? resultOrError.error.operation,
+        message: resultOrError.error.message,
+        raw: resultOrError.error.raw ?? resultOrError.raw
+      };
+    }
+    const details = resultOrError.errorDetails;
+    const message2 = messageFromUnknownError(resultOrError.error) ?? details?.message ?? `Athena ${context?.operation ?? operationFromDetails(details) ?? "request"} failed`;
+    const operation = context?.operation ?? operationFromDetails(details);
+    const table = context?.table ?? extractTable(message2);
+    const constraint = extractConstraint(message2);
+    const gatewayCode = details?.code ?? gatewayCodeFromUnknownError(resultOrError.error);
+    const kind2 = classifyKind(resultOrError.status, gatewayCode, message2);
+    const code = toAthenaErrorCode(kind2, resultOrError.status, gatewayCode);
+    const category = toAthenaErrorCategory(kind2, resultOrError.status);
+    return {
+      kind: kind2,
+      code,
+      category,
+      retryable: isRetryable(kind2, resultOrError.status),
+      status: resultOrError.status,
+      constraint,
+      table,
+      operation,
+      message: message2,
+      raw: resultOrError.raw
+    };
+  }
+  if (isAthenaGatewayError(resultOrError)) {
+    const details = resultOrError.toDetails();
+    const operation = context?.operation ?? operationFromDetails(details);
+    const table = context?.table ?? extractTable(resultOrError.message);
+    const constraint = extractConstraint(resultOrError.message);
+    const kind2 = classifyKind(resultOrError.status, resultOrError.code, resultOrError.message);
+    const code = toAthenaErrorCode(kind2, resultOrError.status, resultOrError.code);
+    const category = toAthenaErrorCategory(kind2, resultOrError.status);
+    return {
+      kind: kind2,
+      code,
+      category,
+      retryable: isRetryable(kind2, resultOrError.status),
+      status: resultOrError.status,
+      constraint,
+      table,
+      operation,
+      message: resultOrError.message,
+      raw: resultOrError
+    };
+  }
+  if (resultOrError instanceof Error) {
+    const maybeStatus = isRecord(resultOrError) && typeof resultOrError.status === "number" ? resultOrError.status : void 0;
+    const kind2 = classifyKind(maybeStatus, void 0, resultOrError.message);
+    return {
+      kind: kind2,
+      code: toAthenaErrorCode(kind2, maybeStatus),
+      category: toAthenaErrorCategory(kind2, maybeStatus),
+      retryable: isRetryable(kind2, maybeStatus),
+      status: maybeStatus,
+      constraint: extractConstraint(resultOrError.message),
+      table: context?.table ?? extractTable(resultOrError.message),
+      operation: context?.operation,
+      message: resultOrError.message,
+      raw: resultOrError
+    };
+  }
+  const message = typeof resultOrError === "string" ? resultOrError : "Unknown Athena error";
+  const kind = classifyKind(void 0, void 0, message);
+  return {
+    kind,
+    code: toAthenaErrorCode(kind, void 0),
+    category: toAthenaErrorCategory(kind, void 0),
+    retryable: isRetryable(kind, void 0),
+    status: void 0,
+    constraint: extractConstraint(message),
+    table: context?.table ?? extractTable(message),
+    operation: context?.operation,
+    message,
+    raw: resultOrError
+  };
+}
+
 // src/generator/schema-selection.ts
 var DEFAULT_POSTGRES_SCHEMAS = ["public"];
 function collectSchemaNames(input) {
@@ -390,6 +688,7 @@ function resolveProviderSchemas(providerConfig) {
 }
 
 // src/generator/config.ts
+var POSTGRES_PROTOCOLS = /* @__PURE__ */ new Set(["postgres:", "postgresql:"]);
 var DEFAULT_CONFIG_CANDIDATES = [
   "athena.config.ts",
   "athena.config.js",
@@ -419,12 +718,157 @@ var DEFAULT_EXPERIMENTAL_FLAGS = {
   postgresGatewayIntrospection: false,
   scyllaProviderContracts: true
 };
+var PROJECT_ENV_FILENAMES = [".env", ".env.local"];
+var DIRECT_CONNECTION_STRING_ENV_KEYS = [
+  "ATHENA_GENERATOR_PG_URL",
+  "DATABASE_URL",
+  "PG_URL",
+  "POSTGRES_URL",
+  "POSTGRESQL_URL"
+];
+var POSTGRES_DATABASE_ENV_KEYS = ["ATHENA_GENERATOR_DB", "ATHENA_DATABASE", "PGDATABASE"];
+var POSTGRES_PASSWORD_ENV_KEYS = ["ATHENA_GENERATOR_PG_PASSWORD", "PGPASSWORD"];
+var GATEWAY_URL_ENV_KEYS = ["ATHENA_URL", "ATHENA_GATEWAY_URL", "ATHENA_GENERATOR_URL"];
+var GATEWAY_API_KEY_ENV_KEYS = [
+  "ATHENA_API_KEY",
+  "ATHENA_GATEWAY_API_KEY",
+  "ATHENA_GENERATOR_API_KEY"
+];
+function normalizeRawEnvValue(rawValue) {
+  if (rawValue.startsWith('"') && rawValue.endsWith('"') && rawValue.length >= 2) {
+    const inner = rawValue.slice(1, -1);
+    return inner.replace(/\\n/g, "\n").replace(/\\r/g, "\r").replace(/\\t/g, "	").replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+  }
+  if (rawValue.startsWith("'") && rawValue.endsWith("'") && rawValue.length >= 2) {
+    return rawValue.slice(1, -1);
+  }
+  const commentIndex = rawValue.search(/\s+#/);
+  const withoutComment = commentIndex >= 0 ? rawValue.slice(0, commentIndex) : rawValue;
+  return withoutComment.trim();
+}
+function parseEnvLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith("#")) {
+    return void 0;
+  }
+  const match = trimmed.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+  if (!match) {
+    return void 0;
+  }
+  const [, key, rawValue] = match;
+  return [key, normalizeRawEnvValue(rawValue.trim())];
+}
+function readProjectEnvEntries(cwd) {
+  const nodeEnv = process.env.NODE_ENV?.trim();
+  const filenames = [
+    ...PROJECT_ENV_FILENAMES,
+    ...nodeEnv ? [`.env.${nodeEnv}`, `.env.${nodeEnv}.local`] : []
+  ];
+  const entries = /* @__PURE__ */ new Map();
+  for (const filename of filenames) {
+    const absolutePath = resolve(cwd, filename);
+    if (!existsSync(absolutePath)) {
+      continue;
+    }
+    const content = readFileSync(absolutePath, "utf8");
+    const lines = content.split(/\r?\n/g);
+    for (const line of lines) {
+      const parsed = parseEnvLine(line);
+      if (!parsed) {
+        continue;
+      }
+      const [key, value] = parsed;
+      entries.set(key, value);
+    }
+  }
+  return entries;
+}
+function applyProjectEnv(cwd) {
+  const envEntries = readProjectEnvEntries(cwd);
+  if (envEntries.size === 0) {
+    return () => {
+    };
+  }
+  const initialKeys = new Set(
+    Object.keys(process.env).filter((key) => process.env[key] !== void 0)
+  );
+  const staged = /* @__PURE__ */ new Map();
+  for (const [key, value] of envEntries.entries()) {
+    if (initialKeys.has(key)) {
+      continue;
+    }
+    staged.set(key, value);
+  }
+  for (const [key, value] of staged.entries()) {
+    process.env[key] = value;
+  }
+  return () => {
+    for (const key of staged.keys()) {
+      delete process.env[key];
+    }
+  };
+}
+function readEnvStringValue(key) {
+  const value = process.env[key];
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function resolveFallbackValue(fallbackKeys) {
+  for (const key of fallbackKeys) {
+    const value = readEnvStringValue(key);
+    if (value) {
+      return value;
+    }
+  }
+  return void 0;
+}
+function normalizeOptionalString(value, fallbackKeys) {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (trimmed.length > 0) {
+      return trimmed;
+    }
+  }
+  return resolveFallbackValue(fallbackKeys);
+}
+function normalizeRequiredString(value, fieldLabel, fallbackKeys) {
+  const resolved = normalizeOptionalString(value, fallbackKeys);
+  if (resolved) {
+    return resolved;
+  }
+  throw new Error(
+    `Generator config is missing ${fieldLabel}. Set ${fieldLabel} directly or provide one of: ${fallbackKeys.join(", ")}.`
+  );
+}
+function applyPostgresPasswordFallback(connectionString) {
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(connectionString);
+  } catch {
+    return connectionString;
+  }
+  if (!POSTGRES_PROTOCOLS.has(parsedUrl.protocol)) {
+    return connectionString;
+  }
+  if (!parsedUrl.username || parsedUrl.password) {
+    return connectionString;
+  }
+  const fallbackPassword = resolveFallbackValue(POSTGRES_PASSWORD_ENV_KEYS);
+  if (!fallbackPassword) {
+    return connectionString;
+  }
+  parsedUrl.password = fallbackPassword;
+  return parsedUrl.toString();
+}
 function normalizeBooleanFlag(rawValue, fallback) {
   if (typeof rawValue === "boolean") {
     return rawValue;
   }
   if (typeof rawValue === "string") {
-    return parseBooleanFlag(rawValue, fallback);
+    return parseBooleanFlag2(rawValue, fallback);
   }
   return fallback;
 }
@@ -464,9 +908,41 @@ function normalizeOutputConfig(output) {
   };
 }
 function normalizeProviderConfig(provider) {
-  if (provider.kind === "postgres") {
+  if (provider.kind === "postgres" && provider.mode === "direct") {
+    const connectionString = normalizeRequiredString(
+      provider.connectionString,
+      "provider.connectionString",
+      DIRECT_CONNECTION_STRING_ENV_KEYS
+    );
+    const database = normalizeOptionalString(provider.database, POSTGRES_DATABASE_ENV_KEYS);
+    return {
+      ...provider,
+      connectionString: applyPostgresPasswordFallback(connectionString),
+      database,
+      schemas: normalizeSchemaSelection(provider.schemas)
+    };
+  }
+  if (provider.kind === "postgres" && provider.mode === "gateway") {
+    const gatewayUrl = normalizeRequiredString(
+      provider.gatewayUrl,
+      "provider.gatewayUrl",
+      GATEWAY_URL_ENV_KEYS
+    );
+    const apiKey = normalizeRequiredString(
+      provider.apiKey,
+      "provider.apiKey",
+      GATEWAY_API_KEY_ENV_KEYS
+    );
+    const database = normalizeRequiredString(
+      provider.database,
+      "provider.database",
+      POSTGRES_DATABASE_ENV_KEYS
+    );
     return {
       ...provider,
+      gatewayUrl,
+      apiKey,
+      database,
       schemas: normalizeSchemaSelection(provider.schemas)
     };
   }
@@ -525,6 +1001,11 @@ function extractConfigExport(module) {
     if (moduleExports && typeof moduleExports === "object") {
       queue.push(moduleExports);
     }
+    for (const value of Object.values(record)) {
+      if (value && typeof value === "object") {
+        queue.push(value);
+      }
+    }
   }
   throw new Error(
     "Generator config file must export a config object as default export or `config`."
@@ -539,19 +1020,24 @@ function importConfigModule(moduleSpecifier) {
 }
 async function loadGeneratorConfig(options = {}) {
   const cwd = options.cwd ?? process.cwd();
+  const restoreProjectEnv = applyProjectEnv(cwd);
   const resolvedPath = options.configPath ? resolve(cwd, options.configPath) : findGeneratorConfigPath(cwd);
   if (!resolvedPath) {
     throw new Error(
       `No generator config found in ${cwd}. Expected one of: ${DEFAULT_CONFIG_CANDIDATES.join(", ")}`
     );
   }
-  const moduleUrl = pathToFileURL(resolvedPath);
-  const module = await importConfigModule(`${moduleUrl.href}?cacheBust=${Date.now()}`);
-  const rawConfig = extractConfigExport(module);
-  return {
-    configPath: resolvedPath,
-    config: normalizeGeneratorConfig(rawConfig)
-  };
+  try {
+    const moduleUrl = pathToFileURL(resolvedPath);
+    const module = await importConfigModule(`${moduleUrl.href}?cacheBust=${Date.now()}`);
+    const rawConfig = extractConfigExport(module);
+    return {
+      configPath: resolvedPath,
+      config: normalizeGeneratorConfig(rawConfig)
+    };
+  } finally {
+    restoreProjectEnv();
+  }
 }
 
 // src/generator/renderer.ts
@@ -693,13 +1179,65 @@ function assertNoDuplicatePaths(files) {
         [
           `Generator output collision detected for path: ${file.path}`,
           `Collision: ${existing.kind} and ${file.kind}.`,
-          "When syncing multiple schemas, include a schema placeholder such as {schema} or {schema_kebab} in model/schema output targets."
+          "Use explicit placeholders such as {model}, {model_kebab}, {schema}, or {schema_kebab} in output targets so each artifact resolves to a unique path."
         ].join(" ")
       );
     }
     seen.set(file.path, file);
   }
 }
+function addSchemaSegmentToPath(pathValue, schemaName) {
+  const normalizedPath = normalizePath(pathValue);
+  const parsedPath = posix.parse(normalizedPath);
+  const schemaSegment = applyNamingStyle(schemaName, "kebab");
+  if (!schemaSegment) {
+    return normalizedPath;
+  }
+  const dir = parsedPath.dir.length > 0 ? `${parsedPath.dir}/${schemaSegment}` : schemaSegment;
+  return normalizePath(posix.join(dir, parsedPath.base));
+}
+function scopeDuplicateDescriptorPathsBySchema(descriptors) {
+  const nextDescriptors = descriptors.map((descriptor) => ({ ...descriptor }));
+  const duplicates = /* @__PURE__ */ new Map();
+  for (let index = 0; index < nextDescriptors.length; index += 1) {
+    const descriptor = nextDescriptors[index];
+    const indexes = duplicates.get(descriptor.filePath) ?? [];
+    indexes.push(index);
+    duplicates.set(descriptor.filePath, indexes);
+  }
+  let appliedSchemaScoping = false;
+  for (const indexes of duplicates.values()) {
+    if (indexes.length <= 1) {
+      continue;
+    }
+    const schemaNames = new Set(indexes.map((index) => nextDescriptors[index].schemaName));
+    if (schemaNames.size <= 1) {
+      continue;
+    }
+    for (const index of indexes) {
+      const descriptor = nextDescriptors[index];
+      descriptor.filePath = addSchemaSegmentToPath(descriptor.filePath, descriptor.schemaName);
+    }
+    appliedSchemaScoping = true;
+  }
+  if (!appliedSchemaScoping) {
+    return nextDescriptors;
+  }
+  const normalizedPaths = /* @__PURE__ */ new Set();
+  for (const descriptor of nextDescriptors) {
+    if (normalizedPaths.has(descriptor.filePath)) {
+      throw new Error(
+        [
+          `Generator output collision detected for path: ${descriptor.filePath}`,
+          "Automatic schema path scoping was applied but collisions remain.",
+          "Add explicit placeholders such as {model}, {model_kebab}, {schema}, or {schema_kebab} to your output targets."
+        ].join(" ")
+      );
+    }
+    normalizedPaths.add(descriptor.filePath);
+  }
+  return nextDescriptors;
+}
 var ArtifactComposer = class {
   constructor(snapshot, config) {
     this.snapshot = snapshot;
@@ -738,7 +1276,8 @@ var ArtifactComposer = class {
         });
       }
     }
-    const schemaDescriptors = Object.keys(this.snapshot.schemas).sort().map((schemaName) => {
+    const scopedModelDescriptors = scopeDuplicateDescriptorPathsBySchema(modelDescriptors);
+    let schemaDescriptors = Object.keys(this.snapshot.schemas).sort().map((schemaName) => {
       const schemaPath = normalizePath(
         renderOutputPath(this.config.output.targets.schema, {
           provider: providerName,
@@ -756,9 +1295,10 @@ var ArtifactComposer = class {
           this.config.naming.schemaConst,
           "schema"
         ),
-        models: modelDescriptors.filter((model) => model.schemaName === schemaName)
+        models: scopedModelDescriptors.filter((model) => model.schemaName === schemaName)
       };
     });
+    schemaDescriptors = scopeDuplicateDescriptorPathsBySchema(schemaDescriptors);
     const databasePath = normalizePath(
       renderOutputPath(this.config.output.targets.database, {
         provider: providerName,
@@ -778,7 +1318,7 @@ var ArtifactComposer = class {
       schemas: schemaDescriptors
     };
     const files = [];
-    for (const modelDescriptor of modelDescriptors) {
+    for (const modelDescriptor of scopedModelDescriptors) {
       files.push(renderModelArtifact(this.snapshot, modelDescriptor, this.config));
     }
     for (const schemaDescriptor of schemaDescriptors) {
@@ -842,26 +1382,42 @@ function parseResponseBody(rawText, contentType) {
 function normalizeHeaderValue(value) {
   return value ? value : void 0;
 }
-function isRecord(value) {
+function isRecord2(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+}
+function resolveStructuredErrorPayload(payload) {
+  if (!isRecord2(payload)) return null;
+  return isRecord2(payload.error) ? payload.error : payload;
+}
 function resolveRequestId(headers) {
   return headers.get("x-request-id") ?? headers.get("x-correlation-id") ?? headers.get("x-athena-request-id") ?? void 0;
 }
 function resolveErrorMessage(payload, fallback) {
-  if (isRecord(payload)) {
-    const messageCandidates = [payload.error, payload.message, payload.details];
+  const structuredPayload = resolveStructuredErrorPayload(payload);
+  if (structuredPayload) {
+    const messageCandidates = [structuredPayload.message, structuredPayload.error, structuredPayload.details];
     for (const candidate of messageCandidates) {
-      if (typeof candidate === "string" && candidate.trim().length > 0) {
-        return candidate.trim();
-      }
+      const resolved = nonEmptyString(candidate);
+      if (resolved) return resolved;
     }
   }
-  if (typeof payload === "string" && payload.trim().length > 0) {
-    return payload.trim();
-  }
+  const rawMessage = nonEmptyString(payload);
+  if (rawMessage) return rawMessage;
   return fallback;
 }
+function resolveErrorHint(payload) {
+  const structuredPayload = resolveStructuredErrorPayload(payload);
+  return structuredPayload ? nonEmptyString(structuredPayload.hint) : void 0;
+}
+function resolveStatusText(response, payload) {
+  const rawStatusText = nonEmptyString(response.statusText);
+  if (rawStatusText) return rawStatusText;
+  const payloadRecord = isRecord2(payload) ? payload : null;
+  return payloadRecord ? nonEmptyString(payloadRecord.statusText) ?? null : null;
+}
 function detailsFromError(error) {
   return error.toDetails();
 }
@@ -1032,6 +1588,7 @@ async function callAthena(config, endpoint, method, payload, options) {
       return {
         ok: false,
         status: response.status,
+        statusText: resolveStatusText(response, parsedBody.parsed),
         data: null,
         error: invalidJsonError.message,
         errorDetails: detailsFromError(invalidJsonError),
@@ -1039,7 +1596,7 @@ async function callAthena(config, endpoint, method, payload, options) {
       };
     }
     const parsed = parsedBody.parsed;
-    const parsedPayload = isRecord(parsed) ? parsed : null;
+    const parsedPayload = isRecord2(parsed) ? parsed : null;
     if (!response.ok) {
       const httpError = new AthenaGatewayError({
         code: "HTTP_ERROR",
@@ -1050,11 +1607,13 @@ async function callAthena(config, endpoint, method, payload, options) {
         status: response.status,
         endpoint,
         method,
-        requestId
+        requestId,
+        hint: resolveErrorHint(parsed)
       });
       return {
         ok: false,
         status: response.status,
+        statusText: resolveStatusText(response, parsed),
         data: null,
         error: httpError.message,
         errorDetails: detailsFromError(httpError),
@@ -1066,6 +1625,7 @@ async function callAthena(config, endpoint, method, payload, options) {
     return {
       ok: true,
       status: response.status,
+      statusText: resolveStatusText(response, parsed),
       data: payloadData ?? null,
       count: payloadCount,
       error: void 0,
@@ -1085,6 +1645,7 @@ async function callAthena(config, endpoint, method, payload, options) {
     return {
       ok: false,
       status: 0,
+      statusText: null,
       data: null,
       error: networkError.message,
       errorDetails: detailsFromError(networkError),
@@ -1126,10 +1687,29 @@ function createAthenaGatewayClient(config = {}) {
 // src/sql-identifiers.ts
 var SIMPLE_IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 var COMPOSITE_IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/;
-var ALIAS_PATTERN = /^([A-Za-z_][A-Za-z0-9_.]*)\s+(?:as\s+)?([A-Za-z_][A-Za-z0-9_]*)$/i;
+var SQL_ALIAS_PATTERN = /^([A-Za-z_][A-Za-z0-9_.]*)\s+(?:as\s+)?([A-Za-z_][A-Za-z0-9_]*)$/i;
+var RESPONSE_ALIAS_PATTERN = /^([A-Za-z_][A-Za-z0-9_]*)\s*:\s*([A-Za-z_][A-Za-z0-9_.]*)$/i;
 function quoteIdentifierSegment(identifier) {
   return `"${identifier.replace(/"/g, '""')}"`;
 }
+function parseAliasedIdentifierToken(token) {
+  const responseAliasMatch = RESPONSE_ALIAS_PATTERN.exec(token);
+  if (responseAliasMatch) {
+    const [, aliasIdentifier2, baseIdentifier2] = responseAliasMatch;
+    if (COMPOSITE_IDENTIFIER_PATTERN.test(baseIdentifier2) && SIMPLE_IDENTIFIER_PATTERN.test(aliasIdentifier2)) {
+      return { baseIdentifier: baseIdentifier2, aliasIdentifier: aliasIdentifier2 };
+    }
+  }
+  const sqlAliasMatch = SQL_ALIAS_PATTERN.exec(token);
+  if (!sqlAliasMatch) {
+    return null;
+  }
+  const [, baseIdentifier, aliasIdentifier] = sqlAliasMatch;
+  if (!COMPOSITE_IDENTIFIER_PATTERN.test(baseIdentifier) || !SIMPLE_IDENTIFIER_PATTERN.test(aliasIdentifier)) {
+    return null;
+  }
+  return { baseIdentifier, aliasIdentifier };
+}
 function quoteQualifiedIdentifier(identifier) {
   return identifier.split(".").map((segment) => quoteIdentifierSegment(segment)).join(".");
 }
@@ -1138,23 +1718,27 @@ function quoteSelectToken(token) {
   if (COMPOSITE_IDENTIFIER_PATTERN.test(token)) {
     return quoteQualifiedIdentifier(token);
   }
-  const aliasMatch = ALIAS_PATTERN.exec(token);
-  if (!aliasMatch) {
-    return token;
-  }
-  const [, baseIdentifier, aliasIdentifier] = aliasMatch;
-  if (!COMPOSITE_IDENTIFIER_PATTERN.test(baseIdentifier) || !SIMPLE_IDENTIFIER_PATTERN.test(aliasIdentifier)) {
+  const aliasedIdentifier = parseAliasedIdentifierToken(token);
+  if (!aliasedIdentifier) {
     return token;
   }
+  const { baseIdentifier, aliasIdentifier } = aliasedIdentifier;
   return `${quoteQualifiedIdentifier(baseIdentifier)} AS ${quoteIdentifierSegment(aliasIdentifier)}`;
 }
+function quoteSelectColumnToken(token) {
+  const trimmed = token.trim();
+  if (!trimmed || trimmed === "*") return trimmed || "*";
+  const responseAliasMatch = RESPONSE_ALIAS_PATTERN.exec(trimmed);
+  if (responseAliasMatch) {
+    const [, aliasIdentifier, baseIdentifier] = responseAliasMatch;
+    return `${quoteQualifiedIdentifier(baseIdentifier)} AS ${quoteIdentifierSegment(aliasIdentifier)}`;
+  }
+  return quoteQualifiedIdentifier(trimmed);
+}
 function canAutoQuoteToken(token) {
   if (token === "*") return true;
   if (COMPOSITE_IDENTIFIER_PATTERN.test(token)) return true;
-  const aliasMatch = ALIAS_PATTERN.exec(token);
-  if (!aliasMatch) return false;
-  const [, baseIdentifier, aliasIdentifier] = aliasMatch;
-  return COMPOSITE_IDENTIFIER_PATTERN.test(baseIdentifier) && SIMPLE_IDENTIFIER_PATTERN.test(aliasIdentifier);
+  return parseAliasedIdentifierToken(token) != null;
 }
 function splitTopLevelCommaSeparated(input) {
   const parts = [];
@@ -1238,6 +1822,190 @@ function quoteSelectColumnsExpression(columns) {
   return tokens.map(quoteSelectToken).join(", ");
 }
 
+// src/auth/react-email.ts
+var reactEmailRenderModulePromise;
+function isRecord3(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isFunction(value) {
+  return typeof value === "function";
+}
+function toStringOrUndefined(value) {
+  if (typeof value !== "string") return void 0;
+  return value;
+}
+function nowIsoString() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function emitReactEmailEvent(observe, phase, input = {}) {
+  if (!observe) return;
+  try {
+    observe({
+      phase,
+      timestamp: nowIsoString(),
+      ...input
+    });
+  } catch {
+  }
+}
+function mergeRenderDefaults(input, defaults) {
+  return {
+    ...input,
+    pretty: input.pretty ?? defaults?.pretty,
+    includePlainText: input.includePlainText ?? defaults?.includePlainText
+  };
+}
+function mergeRuntimeOptions(options) {
+  if (!options) return void 0;
+  return {
+    defaults: options.defaults,
+    observe: options.observe,
+    route: "route" in options ? options.route : void 0
+  };
+}
+async function resolveReactEmailRenderModule() {
+  if (!reactEmailRenderModulePromise) {
+    reactEmailRenderModulePromise = (async () => {
+      try {
+        const loaded = await import('@react-email/render');
+        if (!isFunction(loaded.render)) {
+          throw new Error("missing render(...) export");
+        }
+        return {
+          render: loaded.render,
+          toPlainText: isFunction(loaded.toPlainText) ? loaded.toPlainText : void 0,
+          pretty: isFunction(loaded.pretty) ? loaded.pretty : void 0
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(
+          `React Email rendering requires @react-email/render. Install it in your project (for example: pnpm add @react-email/render). Loader error: ${message}`
+        );
+      }
+    })();
+  }
+  if (!reactEmailRenderModulePromise) {
+    throw new Error("React Email renderer module failed to initialize");
+  }
+  return reactEmailRenderModulePromise;
+}
+async function resolveReactEmailElement(input) {
+  if (input.element != null) {
+    return input.element;
+  }
+  if (!input.component) {
+    throw new Error("react email payload requires either `element` or `component`");
+  }
+  try {
+    const reactModule = await import('react');
+    if (typeof reactModule.createElement !== "function") {
+      throw new Error("react createElement(...) export is unavailable");
+    }
+    return reactModule.createElement(
+      input.component,
+      input.props ?? {}
+    );
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `React Email component rendering requires react runtime support. Install react in your project. Loader error: ${message}`
+    );
+  }
+}
+async function renderAthenaReactEmail(input, options) {
+  if (!isRecord3(input)) {
+    throw new Error("react email payload must be an object");
+  }
+  const runtimeOptions = mergeRuntimeOptions(options);
+  const start = Date.now();
+  emitReactEmailEvent(runtimeOptions?.observe, "render:start", {
+    route: runtimeOptions?.route,
+    message: "Rendering react email payload"
+  });
+  try {
+    const normalizedInput = mergeRenderDefaults(input, runtimeOptions?.defaults);
+    const element = await resolveReactEmailElement(normalizedInput);
+    const renderModule = await resolveReactEmailRenderModule();
+    const htmlValue = await renderModule.render(element);
+    const renderedHtml = typeof htmlValue === "string" ? htmlValue : String(htmlValue ?? "");
+    if (!renderedHtml.trim()) {
+      throw new Error("react email renderer returned an empty HTML string");
+    }
+    let html = renderedHtml;
+    if (normalizedInput.pretty && renderModule.pretty) {
+      const prettyValue = await renderModule.pretty(renderedHtml);
+      if (typeof prettyValue === "string" && prettyValue.trim().length > 0) {
+        html = prettyValue;
+      }
+    }
+    const explicitText = toStringOrUndefined(normalizedInput.text);
+    if (explicitText !== void 0) {
+      emitReactEmailEvent(runtimeOptions?.observe, "render:success", {
+        route: runtimeOptions?.route,
+        durationMs: Date.now() - start,
+        message: "Rendered react email with explicit text"
+      });
+      return {
+        html,
+        text: explicitText
+      };
+    }
+    if (normalizedInput.includePlainText === false || !renderModule.toPlainText) {
+      emitReactEmailEvent(runtimeOptions?.observe, "render:success", {
+        route: runtimeOptions?.route,
+        durationMs: Date.now() - start,
+        message: "Rendered react email without plain-text derivation"
+      });
+      return { html };
+    }
+    const plainTextValue = await renderModule.toPlainText(html);
+    const plainText = toStringOrUndefined(plainTextValue);
+    emitReactEmailEvent(runtimeOptions?.observe, "render:success", {
+      route: runtimeOptions?.route,
+      durationMs: Date.now() - start,
+      message: plainText ? "Rendered react email with derived plain text" : "Rendered react email HTML only"
+    });
+    if (plainText === void 0) {
+      return { html };
+    }
+    return {
+      html,
+      text: plainText
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    emitReactEmailEvent(runtimeOptions?.observe, "render:error", {
+      route: runtimeOptions?.route,
+      durationMs: Date.now() - start,
+      error: message,
+      message: "Failed to render react email payload"
+    });
+    throw error;
+  }
+}
+async function resolveReactEmailPayloadFields(input, fields, options) {
+  const { react, ...payloadWithoutReact } = input;
+  if (!react) {
+    return payloadWithoutReact;
+  }
+  const rendered = await renderAthenaReactEmail(react, options);
+  const payload = {
+    ...payloadWithoutReact
+  };
+  payload[fields.htmlField] = rendered.html;
+  const currentTextValue = payload[fields.textField];
+  if (rendered.text !== void 0 && (currentTextValue === void 0 || currentTextValue === null || currentTextValue === "")) {
+    payload[fields.textField] = rendered.text;
+  }
+  if (fields.variablesField && (payload[fields.variablesField] === void 0 || payload[fields.variablesField] === null) && isRecord3(react.props)) {
+    const derivedVariables = Object.keys(react.props);
+    if (derivedVariables.length > 0) {
+      payload[fields.variablesField] = derivedVariables;
+    }
+  }
+  return payload;
+}
+
 // src/auth/client.ts
 var DEFAULT_AUTH_BASE_URL = "http://localhost:3001/api/auth";
 var FALLBACK_SDK_VERSION2 = "1.0.0";
@@ -1247,7 +2015,7 @@ var SDK_HEADER_VALUE2 = `${SDK_NAME2} ${SDK_VERSION2}`;
 function normalizeBaseUrl(baseUrl) {
   return (baseUrl ?? DEFAULT_AUTH_BASE_URL).replace(/\/$/, "");
 }
-function isRecord2(value) {
+function isRecord4(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function normalizeHeaderValue2(value) {
@@ -1272,7 +2040,7 @@ function resolveRequestId2(headers) {
   return headers.get("x-request-id") ?? headers.get("x-correlation-id") ?? headers.get("x-athena-request-id") ?? void 0;
 }
 function resolveErrorMessage2(payload, fallback) {
-  if (isRecord2(payload)) {
+  if (isRecord4(payload)) {
     const messageCandidates = [payload.error, payload.message, payload.details];
     for (const candidate of messageCandidates) {
       if (typeof candidate === "string" && candidate.trim().length > 0) {
@@ -1598,6 +2366,19 @@ function createAuthClient(config = {}) {
       options
     );
   };
+  const withReactEmailRoute = (route) => ({
+    ...resolvedConfig.reactEmail,
+    route
+  });
+  const resolveAdminEmailPayload = (route, input) => resolveReactEmailPayloadFields(input, {
+    htmlField: "htmlBody",
+    textField: "textBody"
+  }, withReactEmailRoute(route));
+  const resolveAdminEmailTemplatePayload = (route, input) => resolveReactEmailPayloadFields(input, {
+    htmlField: "htmlTemplate",
+    textField: "textTemplate",
+    variablesField: "variables"
+  }, withReactEmailRoute(route));
   const listUserEmailsWithFallback = async (input, options) => {
     const primary = await getWithQuery(
       "/email/list",
@@ -1625,7 +2406,7 @@ function createAuthClient(config = {}) {
         data: null
       };
     }
-    const fallbackStatus = isRecord2(fallback.data) && typeof fallback.data.ok === "boolean" ? fallback.data.ok ? "ok" : "error" : "ok";
+    const fallbackStatus = isRecord4(fallback.data) && typeof fallback.data.ok === "boolean" ? fallback.data.ok ? "ok" : "error" : "ok";
     return {
       ...fallback,
       data: {
@@ -2061,8 +2842,16 @@ function createAuthClient(config = {}) {
       email: {
         list: (input, options) => getWithQuery("/admin/email/list", input, options),
         get: (input, options) => getWithQuery("/admin/email/get", input, options),
-        create: (input, options) => postGeneric("/admin/email/create", input, options),
-        update: (input, options) => postGeneric("/admin/email/update", input, options),
+        create: async (input, options) => postGeneric(
+          "/admin/email/create",
+          await resolveAdminEmailPayload("/admin/email/create", input),
+          options
+        ),
+        update: async (input, options) => postGeneric(
+          "/admin/email/update",
+          await resolveAdminEmailPayload("/admin/email/update", input),
+          options
+        ),
         delete: (input, options) => postGeneric("/admin/email/delete", input, options),
         failure: {
           list: (input, options) => getWithQuery("/admin/email-failure/list", input, options),
@@ -2074,17 +2863,33 @@ function createAuthClient(config = {}) {
         template: {
           list: (input, options) => getWithQuery("/admin/email-template/list", input, options),
           get: (input, options) => getWithQuery("/admin/email-template/get", input, options),
-          create: (input, options) => postGeneric("/admin/email-template/create", input, options),
-          update: (input, options) => postGeneric("/admin/email-template/update", input, options),
+          create: async (input, options) => postGeneric(
+            "/admin/email-template/create",
+            await resolveAdminEmailTemplatePayload("/admin/email-template/create", input),
+            options
+          ),
+          update: async (input, options) => postGeneric(
+            "/admin/email-template/update",
+            await resolveAdminEmailTemplatePayload("/admin/email-template/update", input),
+            options
+          ),
           delete: (input, options) => postGeneric("/admin/email-template/delete", input, options)
         }
       },
       emailTemplate: {
         get: (input, options) => getWithQuery("/admin/email-template/get", input, options),
-        create: (input, options) => postGeneric("/admin/email-template/create", input, options),
+        create: async (input, options) => postGeneric(
+          "/admin/email-template/create",
+          await resolveAdminEmailTemplatePayload("/admin/email-template/create", input),
+          options
+        ),
         delete: (input, options) => postGeneric("/admin/email-template/delete", input, options),
         list: (input, options) => getWithQuery("/admin/email-template/list", input, options),
-        update: (input, options) => postGeneric("/admin/email-template/update", input, options)
+        update: async (input, options) => postGeneric(
+          "/admin/email-template/update",
+          await resolveAdminEmailTemplatePayload("/admin/email-template/update", input),
+          options
+        )
       }
     },
     apiKey: {
@@ -2276,16 +3081,313 @@ function createAuthClient(config = {}) {
   };
 }
 
-// src/client.ts
-var DEFAULT_COLUMNS = "*";
+// src/db/module.ts
+function createDbModule(input) {
+  const db = {
+    from(table) {
+      return input.from(table);
+    },
+    select(table, columns, options) {
+      return input.from(table).select(columns, options);
+    },
+    insert(table, values, options) {
+      return Array.isArray(values) ? input.from(table).insert(values, options) : input.from(table).insert(values, options);
+    },
+    upsert(table, values, options) {
+      return Array.isArray(values) ? input.from(table).upsert(values, options) : input.from(table).upsert(values, options);
+    },
+    update(table, values, options) {
+      return input.from(table).update(values, options);
+    },
+    delete(table, options) {
+      return input.from(table).delete(options);
+    },
+    rpc(fn, args, options) {
+      return input.rpc(fn, args, options);
+    },
+    query(query, options) {
+      return input.query(query, options);
+    }
+  };
+  return db;
+}
+
+// src/query-ast.ts
 var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var FILTER_OPERATORS = /* @__PURE__ */ new Set([
+  "eq",
+  "neq",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "like",
+  "ilike",
+  "is",
+  "in",
+  "contains",
+  "containedBy"
+]);
+var BOOLEAN_SAFE_OPERATORS = /* @__PURE__ */ new Set([
+  "eq",
+  "neq",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "like",
+  "ilike",
+  "is"
+]);
+function isRecord5(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isUuidString(value) {
+  return UUID_PATTERN.test(value.trim());
+}
+function isUuidIdentifierColumn(column) {
+  return column === "id" || /(?:^|_)uuid(?:_|$)/i.test(column) || /_id$/i.test(column);
+}
+function shouldUseUuidTextComparison(column, value) {
+  return typeof value === "string" && isUuidString(value) && isUuidIdentifierColumn(column);
+}
+function isRelationSelectNode(value) {
+  return isRecord5(value) && isRecord5(value.select);
+}
+function normalizeIdentifier(value, label) {
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+  return normalized;
+}
+function stringifyFilterValue(value) {
+  if (Array.isArray(value)) {
+    return value.join(",");
+  }
+  return String(value);
+}
+function buildGatewayCondition(operator, column, value) {
+  const condition = { operator };
+  if (column) {
+    condition.column = column;
+    if (operator === "eq") {
+      condition.eq_column = column;
+    }
+  }
+  if (value !== void 0) {
+    condition.value = value;
+    if (operator === "eq") {
+      condition.eq_value = value;
+    }
+  }
+  if (operator === "eq" && column && value !== void 0 && shouldUseUuidTextComparison(column, value)) {
+    condition.column_cast = "text";
+    condition.eq_column_cast = "text";
+  }
+  return condition;
+}
+function compileRelationToken(key, node) {
+  const nested = compileSelectShape(node.select);
+  const propertyKey = normalizeIdentifier(key, "select relation key");
+  const relationToken = normalizeIdentifier(node.via ?? propertyKey, "select relation token");
+  const alias = node.as?.trim() || (relationToken !== propertyKey ? propertyKey : "");
+  const prefix = alias ? `${alias}:` : "";
+  return `${prefix}${relationToken}(${nested})`;
+}
+function compileSelectShape(select) {
+  if (!isRecord5(select)) {
+    throw new Error("findMany select must be an object");
+  }
+  const tokens = [];
+  for (const [rawKey, rawValue] of Object.entries(select)) {
+    if (rawValue === void 0) {
+      continue;
+    }
+    if (rawValue === true) {
+      tokens.push(normalizeIdentifier(rawKey, "select column"));
+      continue;
+    }
+    if (isRelationSelectNode(rawValue)) {
+      tokens.push(compileRelationToken(rawKey, rawValue));
+      continue;
+    }
+    throw new Error(`Unsupported select node for "${rawKey}"`);
+  }
+  if (tokens.length === 0) {
+    throw new Error("findMany select requires at least one field");
+  }
+  return tokens.join(",");
+}
+function compileColumnWhere(column, input) {
+  const normalizedColumn = normalizeIdentifier(column, "where column");
+  if (!isRecord5(input)) {
+    return [buildGatewayCondition("eq", normalizedColumn, input)];
+  }
+  const conditions = [];
+  for (const [rawOperator, rawValue] of Object.entries(input)) {
+    if (rawValue === void 0) {
+      continue;
+    }
+    if (!FILTER_OPERATORS.has(rawOperator)) {
+      throw new Error(`Unsupported where operator "${rawOperator}" on "${normalizedColumn}"`);
+    }
+    if ((rawOperator === "in" || rawOperator === "contains" || rawOperator === "containedBy") && !Array.isArray(rawValue)) {
+      throw new Error(`where.${normalizedColumn}.${rawOperator} requires an array value`);
+    }
+    conditions.push(
+      buildGatewayCondition(
+        rawOperator,
+        normalizedColumn,
+        rawValue
+      )
+    );
+  }
+  if (conditions.length === 0) {
+    throw new Error(`where.${normalizedColumn} requires at least one operator`);
+  }
+  return conditions;
+}
+function compileBooleanExpressionTerms(clause, label) {
+  if (!isRecord5(clause)) {
+    throw new Error(`findMany where.${label} clauses must be objects`);
+  }
+  const entries = Object.entries(clause).filter(([, value]) => value !== void 0);
+  if (entries.length !== 1) {
+    throw new Error(`findMany where.${label} clauses must target exactly one column`);
+  }
+  const [rawColumn, rawValue] = entries[0];
+  const column = normalizeIdentifier(rawColumn, `where.${label} column`);
+  if (!isRecord5(rawValue)) {
+    return [`${column}.eq.${stringifyFilterValue(rawValue)}`];
+  }
+  const operatorEntries = Object.entries(rawValue).filter(([, value]) => value !== void 0);
+  if (operatorEntries.length === 0) {
+    throw new Error(`findMany where.${label}.${column} requires at least one operator`);
+  }
+  if (label === "not" && operatorEntries.length > 1) {
+    throw new Error("findMany where.not only supports a single lossless operator expression");
+  }
+  return operatorEntries.map(([rawOperator, rawOperand]) => {
+    if (!BOOLEAN_SAFE_OPERATORS.has(rawOperator)) {
+      throw new Error(`findMany where.${label} only supports lossless scalar operators`);
+    }
+    if (Array.isArray(rawOperand)) {
+      throw new Error(`findMany where.${label} does not support array-valued operators`);
+    }
+    return `${column}.${rawOperator}.${stringifyFilterValue(rawOperand)}`;
+  });
+}
+function compileWhere(where) {
+  if (where === void 0) {
+    return void 0;
+  }
+  if (!isRecord5(where)) {
+    throw new Error("findMany where must be an object");
+  }
+  const conditions = [];
+  for (const [rawKey, rawValue] of Object.entries(where)) {
+    if (rawValue === void 0) {
+      continue;
+    }
+    if (rawKey === "or") {
+      if (!Array.isArray(rawValue) || rawValue.length === 0) {
+        throw new Error("findMany where.or must be a non-empty array");
+      }
+      const expressions = rawValue.flatMap(
+        (value) => compileBooleanExpressionTerms(value, "or")
+      );
+      conditions.push(buildGatewayCondition("or", void 0, expressions.join(",")));
+      continue;
+    }
+    if (rawKey === "not") {
+      const expressions = compileBooleanExpressionTerms(rawValue, "not");
+      if (expressions.length !== 1) {
+        throw new Error("findMany where.not must compile to exactly one lossless expression");
+      }
+      conditions.push(buildGatewayCondition("not", void 0, expressions[0]));
+      continue;
+    }
+    conditions.push(...compileColumnWhere(rawKey, rawValue));
+  }
+  return conditions.length > 0 ? conditions : void 0;
+}
+function resolveOrderDirection(input) {
+  if (typeof input === "boolean") {
+    return input === false ? "descending" : "ascending";
+  }
+  if (typeof input === "string") {
+    const normalized = input.trim().toLowerCase();
+    if (normalized === "asc" || normalized === "ascending") {
+      return "ascending";
+    }
+    if (normalized === "desc" || normalized === "descending") {
+      return "descending";
+    }
+    throw new Error(`Unsupported orderBy direction "${input}"`);
+  }
+  return input.ascending === false ? "descending" : "ascending";
+}
+function compileOrderBy(orderBy) {
+  if (orderBy === void 0) {
+    return void 0;
+  }
+  if (!isRecord5(orderBy)) {
+    throw new Error("findMany orderBy must be an object");
+  }
+  if ("column" in orderBy) {
+    return {
+      field: normalizeIdentifier(String(orderBy.column), "orderBy column"),
+      direction: orderBy.ascending === false ? "descending" : "ascending"
+    };
+  }
+  const entries = Object.entries(orderBy).filter(([, value]) => value !== void 0);
+  if (entries.length === 0) {
+    return void 0;
+  }
+  if (entries.length > 1) {
+    throw new Error("findMany orderBy only supports a single column in v1");
+  }
+  const [column, input] = entries[0];
+  return {
+    field: normalizeIdentifier(column, "orderBy column"),
+    direction: resolveOrderDirection(input)
+  };
+}
+
+// src/client.ts
+var DEFAULT_COLUMNS = "*";
 var SAFE_CAST_PATTERN = /^[a-z_][a-z0-9_]*(?:\[\])?$/i;
+var ATHENA_NORMALIZED_ERROR_KEY = "__athenaNormalizedError";
+var QUERY_TRACE_STACK_SKIP_PATTERNS = [
+  "src\\client.ts",
+  "src/client.ts",
+  "dist\\client.",
+  "dist/client.",
+  "node_modules\\@xylex-group\\athena",
+  "node_modules/@xylex-group/athena",
+  "node:internal",
+  "internal/process"
+];
+function canUseFindManyAstTransport(state) {
+  return state.conditions.length === 0 && state.offset === void 0 && state.currentPage === void 0 && state.pageSize === void 0 && state.totalPages === void 0;
+}
+function toFindManyAstOrder(order) {
+  if (!order) {
+    return void 0;
+  }
+  return {
+    column: order.field,
+    ascending: order.direction !== "descending"
+  };
+}
 function formatResult(response) {
   const result = {
     data: response.data ?? null,
-    error: response.error ?? null,
+    error: null,
     errorDetails: response.errorDetails ?? null,
     status: response.status,
+    statusText: response.statusText ?? null,
     raw: response.raw
   };
   if (response.count !== void 0) {
@@ -2293,6 +3395,245 @@ function formatResult(response) {
   }
   return result;
 }
+function attachNormalizedError(result, normalizedError) {
+  Object.defineProperty(result, ATHENA_NORMALIZED_ERROR_KEY, {
+    value: normalizedError,
+    enumerable: false,
+    configurable: true,
+    writable: false
+  });
+}
+function createResultFormatter(experimental) {
+  return (response, context) => {
+    const result = formatResult(response);
+    if (response.error == null && response.errorDetails == null) {
+      return result;
+    }
+    const normalizedError = normalizeAthenaError(
+      {
+        ...result,
+        error: response.error ?? response.errorDetails?.message ?? null
+      },
+      context
+    );
+    result.error = createResultError(response, result, normalizedError);
+    attachNormalizedError(result, normalizedError);
+    return result;
+  };
+}
+function isRecord6(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function firstNonEmptyString2(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value.trim();
+    }
+  }
+  return void 0;
+}
+function resolveStructuredErrorPayload2(raw) {
+  if (!isRecord6(raw)) return null;
+  return isRecord6(raw.error) ? raw.error : raw;
+}
+function resolveStructuredErrorDetails(payload, message) {
+  if (!payload || !("details" in payload)) {
+    return null;
+  }
+  const details = payload.details;
+  if (details == null) {
+    return null;
+  }
+  if (typeof details === "string" && details.trim() === message.trim()) {
+    return null;
+  }
+  return details;
+}
+function createResultError(response, result, normalized) {
+  const rawRecord = isRecord6(response.raw) ? response.raw : null;
+  const payload = resolveStructuredErrorPayload2(response.raw);
+  const message = firstNonEmptyString2(
+    response.error,
+    payload?.message,
+    payload?.error,
+    payload?.details,
+    response.errorDetails?.message,
+    normalized.message
+  ) ?? normalized.message;
+  const statusText = firstNonEmptyString2(response.statusText, rawRecord?.statusText) ?? null;
+  const hint = firstNonEmptyString2(payload?.hint, response.errorDetails?.hint) ?? null;
+  const code = firstNonEmptyString2(payload?.code) ?? normalized.code;
+  const details = resolveStructuredErrorDetails(payload, message) ?? response.errorDetails?.cause ?? null;
+  return {
+    message,
+    code,
+    athenaCode: normalized.code,
+    gatewayCode: response.errorDetails?.code ?? null,
+    kind: normalized.kind,
+    category: normalized.category,
+    retryable: normalized.retryable,
+    details,
+    hint,
+    status: result.status,
+    statusText,
+    constraint: normalized.constraint,
+    table: normalized.table,
+    operation: normalized.operation,
+    endpoint: response.errorDetails?.endpoint,
+    method: response.errorDetails?.method,
+    requestId: response.errorDetails?.requestId,
+    cause: response.errorDetails?.cause,
+    raw: result.raw
+  };
+}
+function parseQueryTraceCallsiteFrame(frame) {
+  const trimmed = frame.trim();
+  if (!trimmed) {
+    return null;
+  }
+  let body = trimmed.replace(/^at\s+/, "");
+  if (body.startsWith("async ")) {
+    body = body.slice(6);
+  }
+  let functionName;
+  let location = body;
+  const wrappedMatch = body.match(/^(.*?)\s+\((.*)\)$/);
+  if (wrappedMatch) {
+    functionName = wrappedMatch[1].trim() || void 0;
+    location = wrappedMatch[2].trim();
+  }
+  const locationMatch = location.match(/^(.*):(\d+):(\d+)$/);
+  if (!locationMatch) {
+    return null;
+  }
+  const filePath = locationMatch[1].replace(/^file:\/\//, "");
+  const line = Number(locationMatch[2]);
+  const column = Number(locationMatch[3]);
+  if (!Number.isFinite(line) || !Number.isFinite(column)) {
+    return null;
+  }
+  const normalizedPath = filePath.replace(/\\/g, "/");
+  const fileName = normalizedPath.split("/").at(-1) ?? filePath;
+  return {
+    filePath,
+    fileName,
+    line,
+    column,
+    frame: trimmed,
+    functionName
+  };
+}
+function captureQueryTraceCallsite() {
+  const stack = new Error().stack;
+  if (!stack) return null;
+  const frames = stack.split("\n").slice(2).map((frame) => frame.trim()).filter(Boolean);
+  for (const frame of frames) {
+    if (QUERY_TRACE_STACK_SKIP_PATTERNS.some((pattern) => frame.includes(pattern))) {
+      continue;
+    }
+    const callsite = parseQueryTraceCallsiteFrame(frame);
+    if (callsite) return callsite;
+  }
+  const fallback = frames.find((frame) => !frame.includes("captureQueryTraceCallsite"));
+  return fallback ? parseQueryTraceCallsiteFrame(fallback) : null;
+}
+function defaultQueryTraceLogger(event) {
+  const target = event.table ?? event.functionName ?? "gateway";
+  const outcomeState = event.outcome?.error ? "error" : "ok";
+  const banner = `[athena-js][trace] ${event.operation.toUpperCase()} ${event.endpoint} ${target} ${event.durationMs}ms ${outcomeState}`;
+  console.info(banner, event);
+}
+function captureTraceCallsite(tracer) {
+  return tracer?.captureCallsite() ?? null;
+}
+function createTraceCallsiteStore(tracer, initialCallsite) {
+  let storedCallsite = initialCallsite ?? void 0;
+  return {
+    resolve(callsite) {
+      if (callsite) {
+        storedCallsite = callsite;
+        return callsite;
+      }
+      if (storedCallsite !== void 0) {
+        return storedCallsite;
+      }
+      const capturedCallsite = captureTraceCallsite(tracer);
+      if (capturedCallsite) {
+        storedCallsite = capturedCallsite;
+      }
+      return capturedCallsite;
+    }
+  };
+}
+function createQueryTracer(experimental) {
+  const traceOption = experimental?.traceQueries;
+  if (!traceOption) {
+    return void 0;
+  }
+  const logger = typeof traceOption === "object" && traceOption.logger ? traceOption.logger : defaultQueryTraceLogger;
+  const emit = (event) => {
+    try {
+      logger(event);
+    } catch (error) {
+      console.warn("[athena-js][trace] logger failed", error);
+    }
+  };
+  return {
+    captureCallsite: captureQueryTraceCallsite,
+    publishSuccess(context, result, durationMs, callsite) {
+      emit({
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        durationMs,
+        operation: context.operation,
+        endpoint: context.endpoint,
+        table: context.table,
+        functionName: context.functionName,
+        sql: context.sql,
+        payload: context.payload,
+        options: context.options,
+        callsite,
+        outcome: {
+          status: result.status,
+          error: result.error,
+          errorDetails: result.errorDetails ?? null,
+          count: result.count ?? null,
+          data: result.data,
+          raw: result.raw
+        }
+      });
+    },
+    publishFailure(context, error, durationMs, callsite) {
+      emit({
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        durationMs,
+        operation: context.operation,
+        endpoint: context.endpoint,
+        table: context.table,
+        functionName: context.functionName,
+        sql: context.sql,
+        payload: context.payload,
+        options: context.options,
+        callsite,
+        thrownError: error
+      });
+    }
+  };
+}
+async function executeWithQueryTrace(tracer, context, runner, callsiteOverride) {
+  if (!tracer) {
+    return runner();
+  }
+  const callsite = callsiteOverride ?? tracer.captureCallsite();
+  const startedAt = Date.now();
+  try {
+    const result = await runner();
+    tracer.publishSuccess(context, result, Date.now() - startedAt, callsite);
+    return result;
+  } catch (error) {
+    tracer.publishFailure(context, error, Date.now() - startedAt, callsite);
+    throw error;
+  }
+}
 function toSingleResult(response) {
   const payload = response.data;
   const singleData = Array.isArray(payload) ? payload.length ? payload[0] : null : payload ?? null;
@@ -2313,15 +3654,16 @@ function asAthenaJsonObject(value) {
 function asAthenaJsonObjectArray(values) {
   return values;
 }
-function createMutationQuery(executor, defaultColumns = DEFAULT_COLUMNS) {
+function createMutationQuery(executor, defaultColumns = DEFAULT_COLUMNS, tracer, initialCallsite) {
   let selectedColumns = defaultColumns === null ? void 0 : defaultColumns;
   let selectedOptions;
   let promise = null;
-  const run = (columns, options) => {
+  const callsiteStore = createTraceCallsiteStore(tracer, initialCallsite);
+  const run = (columns, options, callsite) => {
     const payloadColumns = columns ?? selectedColumns;
     const payloadOptions = options ?? selectedOptions;
     if (!promise) {
-      promise = executor(payloadColumns, payloadOptions);
+      promise = executor(payloadColumns, payloadOptions, callsiteStore.resolve(callsite));
     }
     return promise;
   };
@@ -2329,7 +3671,7 @@ function createMutationQuery(executor, defaultColumns = DEFAULT_COLUMNS) {
     select(columns = selectedColumns, options) {
       selectedColumns = columns;
       selectedOptions = options ?? selectedOptions;
-      return run(columns, options);
+      return run(columns, options, captureTraceCallsite(tracer));
     },
     returning(columns = selectedColumns, options) {
       return mutationQuery.select(columns, options);
@@ -2337,7 +3679,7 @@ function createMutationQuery(executor, defaultColumns = DEFAULT_COLUMNS) {
     single(columns = selectedColumns, options) {
       selectedColumns = columns;
       selectedOptions = options ?? selectedOptions;
-      return run(columns, options).then(toSingleResult);
+      return run(columns, options, captureTraceCallsite(tracer)).then(toSingleResult);
     },
     maybeSingle(columns = selectedColumns, options) {
       return mutationQuery.single(columns, options);
@@ -2360,21 +3702,12 @@ function getResourceId(state) {
   );
   return candidate?.value?.toString();
 }
-function stringifyFilterValue(value) {
+function stringifyFilterValue2(value) {
   if (Array.isArray(value)) {
     return value.join(",");
   }
   return String(value);
 }
-function isUuidString(value) {
-  return UUID_PATTERN.test(value.trim());
-}
-function isUuidIdentifierColumn(column) {
-  return column === "id" || /(?:^|_)uuid(?:_|$)/i.test(column) || /_id$/i.test(column);
-}
-function shouldUseUuidTextComparison(column, value) {
-  return typeof value === "string" && isUuidString(value) && isUuidIdentifierColumn(column);
-}
 function normalizeCast(cast) {
   const normalized = cast.trim().toLowerCase();
   if (!SAFE_CAST_PATTERN.test(normalized)) {
@@ -2397,25 +3730,92 @@ function withCast(expression, cast) {
 }
 function buildSelectColumnsClause(columns) {
   if (Array.isArray(columns)) {
-    return columns.map((column) => quoteQualifiedIdentifier(column)).join(", ");
+    return columns.map((column) => quoteSelectColumnToken(column)).join(", ");
   }
   return quoteSelectColumnsExpression(columns);
 }
+function parseIdentifierSegment(input) {
+  const trimmed = input.trim();
+  if (!trimmed) return null;
+  if (!trimmed.startsWith('"')) {
+    return {
+      normalizedValue: trimmed.toLowerCase()
+    };
+  }
+  let value = "";
+  let index = 1;
+  let closed = false;
+  while (index < trimmed.length) {
+    const char = trimmed[index];
+    const next = index + 1 < trimmed.length ? trimmed[index + 1] : "";
+    if (char === '"' && next === '"') {
+      value += '"';
+      index += 2;
+      continue;
+    }
+    if (char === '"') {
+      closed = true;
+      index += 1;
+      break;
+    }
+    value += char;
+    index += 1;
+  }
+  if (!closed || trimmed.slice(index).trim().length > 0 || !value.trim()) {
+    return null;
+  }
+  return {
+    normalizedValue: value
+  };
+}
+function splitQualifiedTableName(tableName) {
+  const trimmed = tableName.trim();
+  let inQuotes = false;
+  for (let index = 0; index < trimmed.length; index += 1) {
+    const char = trimmed[index];
+    const next = index + 1 < trimmed.length ? trimmed[index + 1] : "";
+    if (char === '"') {
+      if (inQuotes && next === '"') {
+        index += 1;
+        continue;
+      }
+      inQuotes = !inQuotes;
+      continue;
+    }
+    if (char === "." && !inQuotes) {
+      const schemaSegment = trimmed.slice(0, index).trim();
+      const tableSegment = trimmed.slice(index + 1).trim();
+      if (!schemaSegment || !tableSegment) {
+        return null;
+      }
+      return { schemaSegment };
+    }
+  }
+  return null;
+}
 function resolveTableNameForCall(tableName, schema) {
   if (!schema) return tableName;
   const normalizedSchema = schema.trim();
   if (!normalizedSchema) {
     throw new Error("schema option must be a non-empty string");
   }
-  if (tableName.includes(".")) {
-    if (tableName.startsWith(`${normalizedSchema}.`)) {
-      return tableName;
+  const normalizedTableName = tableName.trim();
+  const parsedSchema = parseIdentifierSegment(normalizedSchema);
+  if (!parsedSchema) {
+    throw new Error("schema option must be a non-empty string");
+  }
+  const qualified = splitQualifiedTableName(normalizedTableName);
+  if (qualified) {
+    const parsedTableSchema = parseIdentifierSegment(qualified.schemaSegment);
+    const sameSchema = parsedTableSchema ? parsedTableSchema.normalizedValue === parsedSchema.normalizedValue : normalizedTableName.startsWith(`${normalizedSchema}.`);
+    if (sameSchema) {
+      return normalizedTableName;
     }
     throw new Error(
-      `schema option "${normalizedSchema}" conflicts with schema-qualified table "${tableName}"`
+      `schema option "${normalizedSchema}" conflicts with schema-qualified table "${normalizedTableName}"`
     );
   }
-  return `${normalizedSchema}.${tableName}`;
+  return `${normalizedSchema}.${normalizedTableName}`;
 }
 function conditionToSqlClause(condition) {
   if (!condition.column) return null;
@@ -2493,6 +3893,237 @@ function buildTypedSelectQuery(input) {
   }
   return `${sqlParts.join(" ")};`;
 }
+function sanitizeSqlComment(comment) {
+  return comment.replace(/\*\//g, "* /");
+}
+function toSqlJsonLiteral(value) {
+  if (value === void 0) return "DEFAULT";
+  if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return toSqlLiteral(value);
+  }
+  return `'${escapeSqlStringLiteral(JSON.stringify(value))}'::jsonb`;
+}
+function conditionToDebugSqlClause(condition) {
+  const exact = conditionToSqlClause(condition);
+  if (exact) return exact;
+  const rawCondition = sanitizeSqlComment(JSON.stringify(condition));
+  if (!condition.column) {
+    return `TRUE /* unsupported condition: ${rawCondition} */`;
+  }
+  const column = withCast(quoteQualifiedIdentifier(condition.column), condition.column_cast);
+  const value = condition.value;
+  const rhs = withCast(toSqlJsonLiteral(value), condition.value_cast);
+  switch (condition.operator) {
+    case "contains":
+      return `${column} @> ${rhs}`;
+    case "containedBy":
+      return `${column} <@ ${rhs}`;
+    case "not":
+      return `TRUE /* NOT expression passthrough: ${rawCondition} */`;
+    case "or":
+      return `TRUE /* OR expression passthrough: ${rawCondition} */`;
+    default:
+      return `TRUE /* unsupported condition: ${rawCondition} */`;
+  }
+}
+function resolvePagination(input) {
+  let limit = input.limit;
+  let offset = input.offset;
+  if (limit === void 0 && input.pageSize !== void 0) {
+    limit = input.pageSize;
+  }
+  if (offset === void 0 && input.pageSize !== void 0 && input.currentPage !== void 0 && input.currentPage > 0) {
+    offset = (input.currentPage - 1) * input.pageSize;
+  }
+  return { limit, offset };
+}
+function appendOrderLimitOffset(sqlParts, order, limit, offset) {
+  if (order?.field) {
+    const direction = order.direction === "descending" ? "DESC" : "ASC";
+    sqlParts.push(`ORDER BY ${quoteQualifiedIdentifier(order.field)} ${direction}`);
+  }
+  if (limit !== void 0) {
+    sqlParts.push(`LIMIT ${Math.max(0, Math.trunc(limit))}`);
+  }
+  if (offset !== void 0) {
+    sqlParts.push(`OFFSET ${Math.max(0, Math.trunc(offset))}`);
+  }
+}
+function buildDebugSelectQuery(input) {
+  const sqlParts = [
+    `SELECT ${buildSelectColumnsClause(input.columns)} FROM ${quoteQualifiedIdentifier(input.tableName)}`
+  ];
+  if (input.conditions?.length) {
+    const whereClauses = input.conditions.map(conditionToDebugSqlClause);
+    sqlParts.push(`WHERE ${whereClauses.join(" AND ")}`);
+  }
+  const pagination = resolvePagination(input);
+  appendOrderLimitOffset(sqlParts, input.order, pagination.limit, pagination.offset);
+  return `${sqlParts.join(" ")};`;
+}
+function resolveDebugTableIdentifier(tableName) {
+  if (!tableName?.trim()) {
+    return '"__unknown_table__"';
+  }
+  return quoteQualifiedIdentifier(tableName);
+}
+function buildInsertDebugSql(payload) {
+  const rows = Array.isArray(payload.insert_body) ? payload.insert_body : [payload.insert_body];
+  const columns = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const row of rows) {
+    for (const column of Object.keys(row)) {
+      if (seen.has(column)) continue;
+      seen.add(column);
+      columns.push(column);
+    }
+  }
+  const sqlParts = [`INSERT INTO ${quoteQualifiedIdentifier(payload.table_name)}`];
+  if (!rows.length || !columns.length) {
+    sqlParts.push("DEFAULT VALUES");
+    if (rows.length > 1) {
+      sqlParts.push(`/* trace: ${rows.length} rows collapsed to DEFAULT VALUES */`);
+    }
+  } else {
+    const valuesClause = rows.map((row) => {
+      const values = columns.map((column) => {
+        const hasColumn = Object.prototype.hasOwnProperty.call(row, column);
+        if (!hasColumn) {
+          return payload.default_to_null ? "NULL" : "DEFAULT";
+        }
+        const rowValue = row[column];
+        return toSqlJsonLiteral(rowValue);
+      });
+      return `(${values.join(", ")})`;
+    }).join(", ");
+    const columnClause = columns.map((column) => quoteQualifiedIdentifier(column)).join(", ");
+    sqlParts.push(`(${columnClause})`);
+    sqlParts.push(`VALUES ${valuesClause}`);
+  }
+  if (payload.on_conflict) {
+    const conflictColumns = Array.isArray(payload.on_conflict) ? payload.on_conflict.map((column) => quoteQualifiedIdentifier(column)).join(", ") : payload.on_conflict;
+    if (payload.update_body && Object.keys(payload.update_body).length > 0) {
+      const assignments = Object.entries(payload.update_body).map(
+        ([column, value]) => `${quoteQualifiedIdentifier(column)} = ${toSqlJsonLiteral(value)}`
+      );
+      sqlParts.push(`ON CONFLICT (${conflictColumns}) DO UPDATE SET ${assignments.join(", ")}`);
+    } else {
+      sqlParts.push(`ON CONFLICT (${conflictColumns}) DO NOTHING`);
+    }
+  }
+  if (payload.columns) {
+    sqlParts.push(`RETURNING ${buildSelectColumnsClause(payload.columns)}`);
+  }
+  return `${sqlParts.join(" ")};`;
+}
+function buildUpdateDebugSql(payload) {
+  const set = payload.set ?? payload.data ?? {};
+  const assignments = Object.entries(set).map(
+    ([column, value]) => `${quoteQualifiedIdentifier(column)} = ${toSqlJsonLiteral(value)}`
+  );
+  const sqlParts = [
+    `UPDATE ${resolveDebugTableIdentifier(payload.table_name)} SET ${assignments.length ? assignments.join(", ") : "/* empty set */"}`
+  ];
+  if (payload.conditions?.length) {
+    const whereClauses = payload.conditions.map(conditionToDebugSqlClause);
+    sqlParts.push(`WHERE ${whereClauses.join(" AND ")}`);
+  }
+  const pagination = resolvePagination({
+    currentPage: payload.current_page,
+    pageSize: payload.page_size
+  });
+  appendOrderLimitOffset(sqlParts, payload.sort_by, pagination.limit, pagination.offset);
+  if (payload.columns) {
+    sqlParts.push(`RETURNING ${buildSelectColumnsClause(payload.columns)}`);
+  }
+  return `${sqlParts.join(" ")};`;
+}
+function buildDeleteDebugSql(payload) {
+  const sqlParts = [`DELETE FROM ${quoteQualifiedIdentifier(payload.table_name)}`];
+  const whereClauses = [];
+  if (payload.resource_id) {
+    whereClauses.push(`"resource_id" = ${toSqlLiteral(payload.resource_id)}`);
+  }
+  if (payload.conditions?.length) {
+    whereClauses.push(...payload.conditions.map(conditionToDebugSqlClause));
+  }
+  if (whereClauses.length) {
+    sqlParts.push(`WHERE ${whereClauses.join(" AND ")}`);
+  }
+  const pagination = resolvePagination({
+    currentPage: payload.current_page,
+    pageSize: payload.page_size
+  });
+  appendOrderLimitOffset(sqlParts, payload.sort_by, pagination.limit, pagination.offset);
+  if (payload.columns) {
+    sqlParts.push(`RETURNING ${buildSelectColumnsClause(payload.columns)}`);
+  }
+  return `${sqlParts.join(" ")};`;
+}
+function rpcFilterToSqlClause(filter) {
+  const column = quoteQualifiedIdentifier(filter.column);
+  const value = filter.value;
+  switch (filter.operator) {
+    case "eq":
+    case "neq":
+    case "gt":
+    case "gte":
+    case "lt":
+    case "lte":
+    case "like":
+    case "ilike": {
+      if (value === void 0 || Array.isArray(value)) {
+        return `TRUE /* unsupported rpc filter: ${sanitizeSqlComment(JSON.stringify(filter))} */`;
+      }
+      const operatorMap = {
+        eq: "=",
+        neq: "!=",
+        gt: ">",
+        gte: ">=",
+        lt: "<",
+        lte: "<=",
+        like: "LIKE",
+        ilike: "ILIKE"
+      };
+      return `${column} ${operatorMap[filter.operator]} ${toSqlLiteral(value)}`;
+    }
+    case "is":
+      if (value === null) return `${column} IS NULL`;
+      if (value === true) return `${column} IS TRUE`;
+      if (value === false) return `${column} IS FALSE`;
+      return `TRUE /* unsupported rpc filter: ${sanitizeSqlComment(JSON.stringify(filter))} */`;
+    case "in":
+      if (!Array.isArray(value)) {
+        return `TRUE /* unsupported rpc filter: ${sanitizeSqlComment(JSON.stringify(filter))} */`;
+      }
+      if (value.length === 0) return "FALSE";
+      return `${column} IN (${value.map((item) => toSqlLiteral(item)).join(", ")})`;
+    default:
+      return `TRUE /* unsupported rpc filter: ${sanitizeSqlComment(JSON.stringify(filter))} */`;
+  }
+}
+function buildRpcDebugSql(payload) {
+  const argsEntries = payload.args ? Object.entries(payload.args) : [];
+  const argsClause = argsEntries.map(([key, value]) => `${quoteQualifiedIdentifier(key)} => ${toSqlJsonLiteral(value)}`).join(", ");
+  const functionRef = payload.schema ? `${quoteQualifiedIdentifier(payload.schema)}.${quoteQualifiedIdentifier(payload.function)}` : quoteQualifiedIdentifier(payload.function);
+  const sqlParts = [
+    `SELECT ${payload.select ? quoteSelectColumnsExpression(payload.select) : "*"} FROM ${functionRef}(${argsClause})`
+  ];
+  if (payload.filters?.length) {
+    sqlParts.push(`WHERE ${payload.filters.map(rpcFilterToSqlClause).join(" AND ")}`);
+  }
+  if (payload.order?.column) {
+    const direction = payload.order.ascending === false ? "DESC" : "ASC";
+    sqlParts.push(`ORDER BY ${quoteQualifiedIdentifier(payload.order.column)} ${direction}`);
+  }
+  if (payload.limit !== void 0) {
+    sqlParts.push(`LIMIT ${Math.max(0, Math.trunc(payload.limit))}`);
+  }
+  if (payload.offset !== void 0) {
+    sqlParts.push(`OFFSET ${Math.max(0, Math.trunc(payload.offset))}`);
+  }
+  return `${sqlParts.join(" ")};`;
+}
 function createFilterMethods(state, addCondition, self) {
   return {
     eq(column, value) {
@@ -2604,7 +4235,7 @@ function createFilterMethods(state, addCondition, self) {
     not(columnOrExpression, operator, value) {
       const expression = String(columnOrExpression);
       if (operator != null && value !== void 0) {
-        addCondition("not", void 0, `${expression}.${operator}.${stringifyFilterValue(value)}`);
+        addCondition("not", void 0, `${expression}.${operator}.${stringifyFilterValue2(value)}`);
       } else {
         addCondition("not", void 0, expression);
       }
@@ -2667,14 +4298,15 @@ function createRpcFilterMethods(filters, self) {
     }
   };
 }
-function createRpcBuilder(functionName, args, baseOptions, client) {
+function createRpcBuilder(functionName, args, baseOptions, client, formatGatewayResult, tracer, initialCallsite) {
   const state = {
     filters: []
   };
   let selectedColumns;
   let selectedOptions;
   let promise = null;
-  const executeRpc = async (columns, options) => {
+  const callsiteStore = createTraceCallsiteStore(tracer, initialCallsite);
+  const executeRpc = async (columns, options, callsite) => {
     const mergedOptions = mergeOptions(baseOptions, options);
     const payload = {
       function: functionName,
@@ -2688,14 +4320,30 @@ function createRpcBuilder(functionName, args, baseOptions, client) {
       offset: state.offset,
       order: state.order
     };
-    const response = await client.rpcGateway(payload, mergedOptions);
-    return formatResult(response);
+    const endpoint = mergedOptions?.get ? `/rpc/${functionName}` : "/gateway/rpc";
+    const sql = buildRpcDebugSql(payload);
+    return executeWithQueryTrace(
+      tracer,
+      {
+        operation: "rpc",
+        endpoint,
+        functionName,
+        sql,
+        payload,
+        options: mergedOptions
+      },
+      async () => {
+        const response = await client.rpcGateway(payload, mergedOptions);
+        return formatGatewayResult(response, { operation: "rpc" });
+      },
+      callsite
+    );
   };
-  const run = (columns, options) => {
+  const run = (columns, options, callsite) => {
     const payloadColumns = columns ?? selectedColumns;
     const payloadOptions = options ?? selectedOptions;
     if (!promise) {
-      promise = executeRpc(payloadColumns, payloadOptions);
+      promise = executeRpc(payloadColumns, payloadOptions, callsiteStore.resolve(callsite));
     }
     return promise;
   };
@@ -2705,10 +4353,10 @@ function createRpcBuilder(functionName, args, baseOptions, client) {
     select(columns = selectedColumns, options) {
       selectedColumns = columns;
       selectedOptions = options ?? selectedOptions;
-      return run(columns, options);
+      return run(columns, options, captureTraceCallsite(tracer));
     },
     async single(columns, options) {
-      const result = await run(columns, options);
+      const result = await run(columns, options, captureTraceCallsite(tracer));
       return toSingleResult(result);
     },
     maybeSingle(columns, options) {
@@ -2743,7 +4391,7 @@ function createRpcBuilder(functionName, args, baseOptions, client) {
   });
   return builder;
 }
-function createTableBuilder(tableName, client) {
+function createTableBuilder(tableName, client, formatGatewayResult, tracer, experimental) {
   const state = {
     conditions: []
   };
@@ -2775,15 +4423,24 @@ function createTableBuilder(tableName, client) {
     }
     state.conditions.push(condition);
   };
+  const snapshotState = () => ({
+    conditions: state.conditions.map((condition) => ({ ...condition })),
+    limit: state.limit,
+    offset: state.offset,
+    order: state.order ? { ...state.order } : void 0,
+    currentPage: state.currentPage,
+    pageSize: state.pageSize,
+    totalPages: state.totalPages
+  });
   const builder = {};
   const filterMethods = createFilterMethods(
     state,
     addCondition,
     builder
   );
-  const runSelect = async (columns = DEFAULT_COLUMNS, options) => {
+  const runSelect = async (columns = DEFAULT_COLUMNS, options, executionState = snapshotState(), callsite) => {
     const resolvedTableName = resolveTableNameForCall(tableName, options?.schema);
-    const conditions = state.conditions.length ? state.conditions.map((condition) => ({ ...condition })) : void 0;
+    const conditions = executionState.conditions.length ? executionState.conditions.map((condition) => ({ ...condition })) : void 0;
     const hasTypedEqualityComparison = conditions?.some(
       (condition) => condition.operator === "eq" && (condition.value_cast !== void 0 || condition.column_cast !== void 0)
     ) ?? false;
@@ -2792,53 +4449,107 @@ function createTableBuilder(tableName, client) {
         tableName: resolvedTableName,
         columns,
         conditions,
-        limit: state.limit,
-        offset: state.offset,
-        currentPage: state.currentPage,
-        pageSize: state.pageSize,
-        order: state.order
+        limit: executionState.limit,
+        offset: executionState.offset,
+        currentPage: executionState.currentPage,
+        pageSize: executionState.pageSize,
+        order: executionState.order
       });
       if (query) {
-        const queryResponse = await client.queryGateway({ query }, options);
-        return formatResult(queryResponse);
+        const payload2 = { query };
+        return executeWithQueryTrace(
+          tracer,
+          {
+            operation: "select",
+            endpoint: "/gateway/query",
+            table: resolvedTableName,
+            sql: query,
+            payload: payload2,
+            options
+          },
+          async () => {
+            const queryResponse = await client.queryGateway(payload2, options);
+            return formatGatewayResult(queryResponse, { table: resolvedTableName, operation: "select" });
+          },
+          callsite
+        );
       }
     }
     const payload = {
       table_name: resolvedTableName,
       columns,
       conditions,
-      limit: state.limit,
-      offset: state.offset,
-      current_page: state.currentPage,
-      page_size: state.pageSize,
-      total_pages: state.totalPages,
-      sort_by: state.order,
+      limit: executionState.limit,
+      offset: executionState.offset,
+      current_page: executionState.currentPage,
+      page_size: executionState.pageSize,
+      total_pages: executionState.totalPages,
+      sort_by: executionState.order,
       strip_nulls: options?.stripNulls ?? true,
       count: options?.count,
       head: options?.head
     };
-    const response = await client.fetchGateway(payload, options);
-    return formatResult(response);
+    const sql = buildDebugSelectQuery({
+      tableName: resolvedTableName,
+      columns,
+      conditions,
+      limit: executionState.limit,
+      offset: executionState.offset,
+      currentPage: executionState.currentPage,
+      pageSize: executionState.pageSize,
+      order: executionState.order
+    });
+    return executeWithQueryTrace(
+      tracer,
+      {
+        operation: "select",
+        endpoint: "/gateway/fetch",
+        table: resolvedTableName,
+        sql,
+        payload,
+        options
+      },
+      async () => {
+        const response = await client.fetchGateway(payload, options);
+        return formatGatewayResult(response, { table: resolvedTableName, operation: "select" });
+      },
+      callsite
+    );
   };
-  const createSelectChain = (columns, options) => {
+  const createSelectChain = (columns, options, initialCallsite) => {
     const chain = {};
+    const callsiteStore = createTraceCallsiteStore(tracer, initialCallsite);
     const filterMethods2 = createFilterMethods(state, addCondition, chain);
     Object.assign(chain, filterMethods2, {
       async single(cols, opts) {
-        const r = await runSelect(cols ?? columns, opts ?? options);
+        const r = await runSelect(
+          cols ?? columns,
+          opts ?? options,
+          snapshotState(),
+          callsiteStore.resolve(captureTraceCallsite(tracer))
+        );
         return toSingleResult(r);
       },
       maybeSingle(cols, opts) {
         return chain.single(cols, opts);
       },
       then(onfulfilled, onrejected) {
-        return runSelect(columns, options).then(onfulfilled, onrejected);
+        return runSelect(
+          columns,
+          options,
+          snapshotState(),
+          callsiteStore.resolve()
+        ).then(onfulfilled, onrejected);
       },
       catch(onrejected) {
-        return runSelect(columns, options).catch(onrejected);
+        return runSelect(columns, options, snapshotState(), callsiteStore.resolve()).catch(
+          onrejected
+        );
       },
       finally(onfinally) {
-        return runSelect(columns, options).finally(onfinally);
+        return runSelect(columns, options, snapshotState(), callsiteStore.resolve()).finally(
+          onfinally
+        );
       }
     });
     return chain;
@@ -2855,11 +4566,75 @@ function createTableBuilder(tableName, client) {
       return builder;
     },
     select(columns = DEFAULT_COLUMNS, options) {
-      return createSelectChain(columns, options);
+      return createSelectChain(columns, options, captureTraceCallsite(tracer));
+    },
+    async findMany(options) {
+      const columns = compileSelectShape(options.select);
+      const baseState = snapshotState();
+      const executionState = snapshotState();
+      const callsite = captureTraceCallsite(tracer);
+      const compiledWhere = compileWhere(options.where);
+      if (compiledWhere?.length) {
+        executionState.conditions.push(...compiledWhere);
+      }
+      if (options.orderBy !== void 0) {
+        executionState.order = compileOrderBy(options.orderBy);
+      }
+      if (options.limit !== void 0) {
+        executionState.limit = options.limit;
+      }
+      if (experimental?.findManyAst && canUseFindManyAstTransport(baseState)) {
+        const resolvedTableName = resolveTableNameForCall(tableName, void 0);
+        const payload = {
+          table_name: resolvedTableName,
+          select: options.select
+        };
+        if (options.where !== void 0) {
+          payload.where = options.where;
+        }
+        const astOrder = toFindManyAstOrder(executionState.order);
+        if (astOrder !== void 0) {
+          payload.orderBy = astOrder;
+        }
+        if (executionState.limit !== void 0) {
+          payload.limit = executionState.limit;
+        }
+        const sql = buildDebugSelectQuery({
+          tableName: resolvedTableName,
+          columns,
+          conditions: executionState.conditions,
+          limit: executionState.limit,
+          order: executionState.order
+        });
+        return executeWithQueryTrace(
+          tracer,
+          {
+            operation: "select",
+            endpoint: "/gateway/fetch",
+            table: resolvedTableName,
+            sql,
+            payload
+          },
+          async () => {
+            const response = await client.fetchGateway(
+              payload
+            );
+            return formatGatewayResult(response, { table: resolvedTableName, operation: "select" });
+          },
+          callsite
+        );
+      }
+      return runSelect(
+        columns,
+        void 0,
+        executionState,
+        callsite
+      );
     },
     insert(values, options) {
+      const mutationCallsite = captureTraceCallsite(tracer);
       if (Array.isArray(values)) {
-        const executeInsertMany = async (columns, selectOptions) => {
+        const executeInsertMany = async (columns, selectOptions, callsite) => {
           const mergedOptions = mergeOptions(options, selectOptions);
           const resolvedTableName = resolveTableNameForCall(tableName, mergedOptions?.schema);
           const payload = {
@@ -2872,12 +4647,27 @@ function createTableBuilder(tableName, client) {
           if (mergedOptions?.defaultToNull !== void 0) {
             payload.default_to_null = mergedOptions.defaultToNull;
           }
-          const response = await client.insertGateway(payload, mergedOptions);
-          return formatResult(response);
+          const sql = buildInsertDebugSql(payload);
+          return executeWithQueryTrace(
+            tracer,
+            {
+              operation: "insert",
+              endpoint: "/gateway/insert",
+              table: resolvedTableName,
+              sql,
+              payload,
+              options: mergedOptions
+            },
+            async () => {
+              const response = await client.insertGateway(payload, mergedOptions);
+              return formatGatewayResult(response, { table: resolvedTableName, operation: "insert" });
+            },
+            callsite
+          );
         };
-        return createMutationQuery(executeInsertMany);
+        return createMutationQuery(executeInsertMany, DEFAULT_COLUMNS, tracer, mutationCallsite);
       }
-      const executeInsertOne = async (columns, selectOptions) => {
+      const executeInsertOne = async (columns, selectOptions, callsite) => {
         const mergedOptions = mergeOptions(options, selectOptions);
         const resolvedTableName = resolveTableNameForCall(tableName, mergedOptions?.schema);
         const payload = {
@@ -2890,14 +4680,30 @@ function createTableBuilder(tableName, client) {
         if (mergedOptions?.defaultToNull !== void 0) {
           payload.default_to_null = mergedOptions.defaultToNull;
         }
-        const response = await client.insertGateway(payload, mergedOptions);
-        return formatResult(response);
+        const sql = buildInsertDebugSql(payload);
+        return executeWithQueryTrace(
+          tracer,
+          {
+            operation: "insert",
+            endpoint: "/gateway/insert",
+            table: resolvedTableName,
+            sql,
+            payload,
+            options: mergedOptions
+          },
+          async () => {
+            const response = await client.insertGateway(payload, mergedOptions);
+            return formatGatewayResult(response, { table: resolvedTableName, operation: "insert" });
+          },
+          callsite
+        );
       };
-      return createMutationQuery(executeInsertOne);
+      return createMutationQuery(executeInsertOne, DEFAULT_COLUMNS, tracer, mutationCallsite);
     },
     upsert(values, options) {
+      const mutationCallsite = captureTraceCallsite(tracer);
       if (Array.isArray(values)) {
-        const executeUpsertMany = async (columns, selectOptions) => {
+        const executeUpsertMany = async (columns, selectOptions, callsite) => {
           const mergedOptions = mergeOptions(options, selectOptions);
           const resolvedTableName = resolveTableNameForCall(tableName, mergedOptions?.schema);
           const payload = {
@@ -2912,12 +4718,27 @@ function createTableBuilder(tableName, client) {
           if (mergedOptions?.defaultToNull !== void 0) {
             payload.default_to_null = mergedOptions.defaultToNull;
           }
-          const response = await client.insertGateway(payload, mergedOptions);
-          return formatResult(response);
+          const sql = buildInsertDebugSql(payload);
+          return executeWithQueryTrace(
+            tracer,
+            {
+              operation: "upsert",
+              endpoint: "/gateway/insert",
+              table: resolvedTableName,
+              sql,
+              payload,
+              options: mergedOptions
+            },
+            async () => {
+              const response = await client.insertGateway(payload, mergedOptions);
+              return formatGatewayResult(response, { table: resolvedTableName, operation: "insert" });
+            },
+            callsite
+          );
         };
-        return createMutationQuery(executeUpsertMany);
+        return createMutationQuery(executeUpsertMany, DEFAULT_COLUMNS, tracer, mutationCallsite);
       }
-      const executeUpsertOne = async (columns, selectOptions) => {
+      const executeUpsertOne = async (columns, selectOptions, callsite) => {
         const mergedOptions = mergeOptions(options, selectOptions);
         const resolvedTableName = resolveTableNameForCall(tableName, mergedOptions?.schema);
         const payload = {
@@ -2932,13 +4753,29 @@ function createTableBuilder(tableName, client) {
         if (mergedOptions?.defaultToNull !== void 0) {
           payload.default_to_null = mergedOptions.defaultToNull;
         }
-        const response = await client.insertGateway(payload, mergedOptions);
-        return formatResult(response);
+        const sql = buildInsertDebugSql(payload);
+        return executeWithQueryTrace(
+          tracer,
+          {
+            operation: "upsert",
+            endpoint: "/gateway/insert",
+            table: resolvedTableName,
+            sql,
+            payload,
+            options: mergedOptions
+          },
+          async () => {
+            const response = await client.insertGateway(payload, mergedOptions);
+            return formatGatewayResult(response, { table: resolvedTableName, operation: "insert" });
+          },
+          callsite
+        );
       };
-      return createMutationQuery(executeUpsertOne);
+      return createMutationQuery(executeUpsertOne, DEFAULT_COLUMNS, tracer, mutationCallsite);
     },
     update(values, options) {
-      const executeUpdate = async (columns, selectOptions) => {
+      const mutationCallsite = captureTraceCallsite(tracer);
+      const executeUpdate = async (columns, selectOptions, callsite) => {
         const filters = state.conditions.length ? [...state.conditions] : void 0;
         const mergedOptions = mergeOptions(options, selectOptions);
         const resolvedTableName = resolveTableNameForCall(tableName, mergedOptions?.schema);
@@ -2953,10 +4790,25 @@ function createTableBuilder(tableName, client) {
         if (state.pageSize !== void 0) payload.page_size = state.pageSize;
         if (state.totalPages !== void 0) payload.total_pages = state.totalPages;
         if (columns) payload.columns = columns;
-        const response = await client.updateGateway(payload, mergedOptions);
-        return formatResult(response);
+        const sql = buildUpdateDebugSql(payload);
+        return executeWithQueryTrace(
+          tracer,
+          {
+            operation: "update",
+            endpoint: "/gateway/update",
+            table: resolvedTableName,
+            sql,
+            payload,
+            options: mergedOptions
+          },
+          async () => {
+            const response = await client.updateGateway(payload, mergedOptions);
+            return formatGatewayResult(response, { table: resolvedTableName, operation: "update" });
+          },
+          callsite
+        );
       };
-      const mutation = createMutationQuery(executeUpdate, null);
+      const mutation = createMutationQuery(executeUpdate, null, tracer, mutationCallsite);
       const updateChain = {};
       const filterMethods2 = createFilterMethods(state, addCondition, updateChain);
       Object.assign(updateChain, filterMethods2, mutation);
@@ -2968,7 +4820,8 @@ function createTableBuilder(tableName, client) {
       if (!resourceId && !filters?.length) {
         throw new Error('delete requires a resource_id either via eq("resource_id", ...) or options.resourceId');
       }
-      const executeDelete = async (columns, selectOptions) => {
+      const mutationCallsite = captureTraceCallsite(tracer);
+      const executeDelete = async (columns, selectOptions, callsite) => {
         const mergedOptions = mergeOptions(options, selectOptions);
         const resolvedTableName = resolveTableNameForCall(tableName, mergedOptions?.schema);
         const payload = {
@@ -2981,13 +4834,33 @@ function createTableBuilder(tableName, client) {
         if (state.pageSize !== void 0) payload.page_size = state.pageSize;
         if (state.totalPages !== void 0) payload.total_pages = state.totalPages;
         if (columns) payload.columns = columns;
-        const response = await client.deleteGateway(payload, mergedOptions);
-        return formatResult(response);
+        const sql = buildDeleteDebugSql(payload);
+        return executeWithQueryTrace(
+          tracer,
+          {
+            operation: "delete",
+            endpoint: "/gateway/delete",
+            table: resolvedTableName,
+            sql,
+            payload,
+            options: mergedOptions
+          },
+          async () => {
+            const response = await client.deleteGateway(payload, mergedOptions);
+            return formatGatewayResult(response, { table: resolvedTableName, operation: "delete" });
+          },
+          callsite
+        );
       };
-      return createMutationQuery(executeDelete, null);
+      return createMutationQuery(executeDelete, null, tracer, mutationCallsite);
     },
     async single(columns, options) {
-      const response = await builder.select(columns, options);
+      const response = await runSelect(
+        columns ?? DEFAULT_COLUMNS,
+        options,
+        snapshotState(),
+        captureTraceCallsite(tracer)
+      );
       return toSingleResult(response);
     },
     async maybeSingle(columns, options) {
@@ -2996,14 +4869,29 @@ function createTableBuilder(tableName, client) {
   });
   return builder;
 }
-function createQueryBuilder(client) {
+function createQueryBuilder(client, formatGatewayResult, tracer) {
   return async function query(query, options) {
     const normalizedQuery = query.trim();
     if (!normalizedQuery) {
       throw new Error("query requires a non-empty string");
     }
-    const response = await client.queryGateway({ query: normalizedQuery }, options);
-    return formatResult(response);
+    const payload = { query: normalizedQuery };
+    const callsite = captureTraceCallsite(tracer);
+    return executeWithQueryTrace(
+      tracer,
+      {
+        operation: "query",
+        endpoint: "/gateway/query",
+        sql: normalizedQuery,
+        payload,
+        options
+      },
+      async () => {
+        const response = await client.queryGateway(payload, options);
+        return formatGatewayResult(response, { operation: "query" });
+      },
+      callsite
+    );
   };
 }
 function createClientFromConfig(config) {
@@ -3014,24 +4902,32 @@ function createClientFromConfig(config) {
     backend: config.backend,
     headers: config.headers
   });
+  const formatGatewayResult = createResultFormatter();
+  const queryTracer = createQueryTracer(config.experimental);
   const auth = createAuthClient(config.auth);
+  const from = (table) => createTableBuilder(table, gateway, formatGatewayResult, queryTracer, config.experimental);
+  const rpc = (fn, args, options) => {
+    const normalizedFn = fn.trim();
+    if (!normalizedFn) {
+      throw new Error("rpc requires a function name");
+    }
+    return createRpcBuilder(
+      normalizedFn,
+      args,
+      options,
+      gateway,
+      formatGatewayResult,
+      queryTracer,
+      captureTraceCallsite(queryTracer)
+    );
+  };
+  const query = createQueryBuilder(gateway, formatGatewayResult, queryTracer);
+  const db = createDbModule({ from, rpc, query });
   return {
-    from(table) {
-      return createTableBuilder(table, gateway);
-    },
-    rpc(fn, args, options) {
-      const normalizedFn = fn.trim();
-      if (!normalizedFn) {
-        throw new Error("rpc requires a function name");
-      }
-      return createRpcBuilder(
-        normalizedFn,
-        args,
-        options,
-        gateway
-      );
-    },
-    query: createQueryBuilder(gateway),
+    from,
+    db,
+    rpc,
+    query,
     auth: auth.auth
   };
 }
@@ -3040,77 +4936,16 @@ function toBackendConfig(b) {
   if (!b) return DEFAULT_BACKEND;
   return typeof b === "string" ? { type: b } : b;
 }
-var AthenaClientBuilderImpl = class {
-  baseUrl;
-  apiKey;
-  backendConfig = DEFAULT_BACKEND;
-  clientName;
-  defaultHeaders;
-  isHealthTrackingEnabled = false;
-  url(url) {
-    this.baseUrl = url;
-    return this;
-  }
-  key(apiKey) {
-    this.apiKey = apiKey;
-    return this;
-  }
-  backend(backend) {
-    this.backendConfig = toBackendConfig(backend);
-    return this;
-  }
-  client(clientName) {
-    this.clientName = clientName;
-    return this;
-  }
-  headers(headers) {
-    this.defaultHeaders = headers;
-    return this;
-  }
-  healthTracking(enabled) {
-    this.isHealthTrackingEnabled = enabled;
-    return this;
-  }
-  build() {
-    if (!this.baseUrl || !this.apiKey) {
-      throw new Error("AthenaClient requires url and key; call .url() and .key() before .build()");
-    }
-    return createClientFromConfig({
-      baseUrl: this.baseUrl,
-      apiKey: this.apiKey,
-      client: this.clientName,
-      backend: this.backendConfig,
-      headers: this.defaultHeaders,
-      healthTracking: this.isHealthTrackingEnabled
-    });
-  }
-};
-var AthenaClient = class _AthenaClient {
-  /** Create a fluent builder for a strongly-typed Athena SDK client. */
-  static builder() {
-    return new AthenaClientBuilderImpl();
-  }
-  /** Build a client from process environment variables. */
-  static fromEnvironment() {
-    const url = process.env.ATHENA_URL ?? process.env.ATHENA_GATEWAY_URL;
-    const key = process.env.ATHENA_API_KEY ?? process.env.ATHENA_GATEWAY_API_KEY;
-    if (!url || !key) {
-      throw new Error(
-        "ATHENA_URL and ATHENA_API_KEY (or ATHENA_GATEWAY_URL and ATHENA_GATEWAY_API_KEY) are required"
-      );
-    }
-    return _AthenaClient.builder().url(url).key(key).build();
-  }
-};
 function createClient(url, apiKey, options) {
-  const b = AthenaClient.builder().url(url).key(apiKey).backend(toBackendConfig(options?.backend));
-  if (options?.client) b.client(options.client);
-  if (options?.headers && Object.keys(options.headers).length > 0) b.headers(options.headers);
-  const client = b.build();
-  if (options?.auth) {
-    client.auth = createAuthClient(options.auth).auth;
-  }
-  return client;
+  return createClientFromConfig({
+    baseUrl: url,
+    apiKey,
+    client: options?.client,
+    backend: toBackendConfig(options?.backend),
+    headers: options?.headers,
+    auth: options?.auth,
+    experimental: options?.experimental
+  });
 }
 
 // src/schema/postgres-introspection-core.ts
@@ -3460,6 +5295,23 @@ var PostgresCatalogSnapshotAssembler = class {
     table.relations[key] = relation;
   }
 };
+
+// src/schema/postgres-provider.ts
+var pgPoolConstructorPromise;
+async function loadPgPoolConstructor() {
+  if (!pgPoolConstructorPromise) {
+    pgPoolConstructorPromise = import('pg').then((module) => {
+      const poolConstructor = module.Pool ?? module.default?.Pool;
+      if (!poolConstructor) {
+        throw new Error(
+          '@xylex-group/athena: Unable to load the PostgreSQL driver. Ensure "pg" is installed and this API runs in a Node.js server runtime.'
+        );
+      }
+      return poolConstructor;
+    });
+  }
+  return pgPoolConstructorPromise;
+}
 var PgCatalogClient = class {
   constructor(pool) {
     this.pool = pool;
@@ -3499,7 +5351,8 @@ var PostgresIntrospectionProvider = class {
   }
   async inspect(options) {
     const schemas = options?.schemas && options.schemas.length > 0 ? normalizePostgresCatalogSchemas(options.schemas) : this.schemas;
-    const pool = new Pool({
+    const PoolConstructor = await loadPgPoolConstructor();
+    const pool = new PoolConstructor({
       connectionString: this.connectionString
     });
     const catalogClient = new PgCatalogClient(pool);
@@ -3538,7 +5391,7 @@ var AthenaGatewayCatalogClient = class {
   async queryRows(query) {
     const result = await this.client.query(query);
     if (result.error || result.status < 200 || result.status >= 300) {
-      throw new Error(result.error ?? `Gateway query failed with status ${result.status}`);
+      throw new Error(result.error?.message ?? `Gateway query failed with status ${result.status}`);
     }
     return result.data ?? [];
   }
@@ -3635,10 +5488,24 @@ function resolveGeneratorProvider(providerConfig, experimentalFlags) {
 }
 
 // src/generator/pipeline.ts
+function canOverwriteArtifact(file) {
+  return file.kind === "model" || file.kind === "schema";
+}
+async function fileExists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
 async function writeArtifacts(files, cwd) {
   const writtenFiles = [];
   for (const file of files) {
     const absolutePath = resolve(cwd, file.path);
+    if (!canOverwriteArtifact(file) && await fileExists(absolutePath)) {
+      continue;
+    }
     await mkdir(dirname(absolutePath), { recursive: true });
     await writeFile(absolutePath, file.content, "utf8");
     writtenFiles.push(file.path);