@xylex-group/athena 2.1.2 → 2.3.0

package/dist/index.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'fs';
 import { resolve, dirname, posix } from 'path';
 import { pathToFileURL } from 'url';
-import { mkdir, writeFile } from 'fs/promises';
+import { mkdir, writeFile, stat } from 'fs/promises';
 
 // src/gateway/errors.ts
 var AthenaGatewayError = class _AthenaGatewayError extends Error {
@@ -91,23 +91,39 @@ function normalizeHeaderValue(value) {
 function isRecord(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 (!isRecord(payload)) return null;
+  return isRecord(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 = isRecord(payload) ? payload : null;
+  return payloadRecord ? nonEmptyString(payloadRecord.statusText) ?? null : null;
+}
 function detailsFromError(error) {
   return error.toDetails();
 }
@@ -278,6 +294,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),
@@ -296,11 +313,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),
@@ -312,6 +331,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,
@@ -331,6 +351,7 @@ async function callAthena(config, endpoint, method, payload, options) {
     return {
       ok: false,
       status: 0,
+      statusText: null,
       data: null,
       error: networkError.message,
       errorDetails: detailsFromError(networkError),
@@ -372,10 +393,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(identifier2) {
   return `"${identifier2.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(identifier2) {
   return identifier2.split(".").map((segment) => quoteIdentifierSegment(segment)).join(".");
 }
@@ -384,23 +424,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 = [];
@@ -500,6 +544,231 @@ function identifier(...segments) {
   return new SqlIdentifierPath(expandedSegments);
 }
 
+// src/auth/react-email.ts
+var reactEmailRenderModulePromise;
+function isRecord2(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}`
+    );
+  }
+}
+function createAuthReactEmailInput(component, props, overrides = {}) {
+  return {
+    ...overrides,
+    component,
+    props
+  };
+}
+function defineAuthEmailTemplate(definition) {
+  const react = (props, overrides) => createAuthReactEmailInput(definition.component, props, {
+    ...definition.defaults,
+    ...overrides
+  });
+  return {
+    component: definition.component,
+    react,
+    toTemplateCreate: (input) => {
+      const templateKey = input.templateKey ?? definition.templateKey;
+      const subjectTemplate = input.subjectTemplate ?? definition.subjectTemplate;
+      if (!templateKey) {
+        throw new Error("defineAuthEmailTemplate.toTemplateCreate requires templateKey");
+      }
+      if (!subjectTemplate) {
+        throw new Error("defineAuthEmailTemplate.toTemplateCreate requires subjectTemplate");
+      }
+      const { props, react: reactOverrides, ...rest } = input;
+      return {
+        ...rest,
+        templateKey,
+        subjectTemplate,
+        react: react(props, reactOverrides)
+      };
+    },
+    toTemplateUpdate: (input) => {
+      const { props, react: reactOverrides, ...rest } = input;
+      return {
+        ...rest,
+        react: react(props, reactOverrides)
+      };
+    }
+  };
+}
+async function renderAthenaReactEmail(input, options) {
+  if (!isRecord2(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) && isRecord2(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";
@@ -509,7 +778,7 @@ var SDK_HEADER_VALUE2 = `${SDK_NAME2} ${SDK_VERSION2}`;
 function normalizeBaseUrl(baseUrl) {
   return (baseUrl ?? DEFAULT_AUTH_BASE_URL).replace(/\/$/, "");
 }
-function isRecord2(value) {
+function isRecord3(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function normalizeHeaderValue2(value) {
@@ -534,7 +803,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 (isRecord3(payload)) {
     const messageCandidates = [payload.error, payload.message, payload.details];
     for (const candidate of messageCandidates) {
       if (typeof candidate === "string" && candidate.trim().length > 0) {
@@ -860,6 +1129,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",
@@ -887,7 +1169,7 @@ function createAuthClient(config = {}) {
         data: null
       };
     }
-    const fallbackStatus = isRecord2(fallback.data) && typeof fallback.data.ok === "boolean" ? fallback.data.ok ? "ok" : "error" : "ok";
+    const fallbackStatus = isRecord3(fallback.data) && typeof fallback.data.ok === "boolean" ? fallback.data.ok ? "ok" : "error" : "ok";
     return {
       ...fallback,
       data: {
@@ -1323,8 +1605,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),
@@ -1336,17 +1626,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: {
@@ -1538,6 +1844,19 @@ function createAuthClient(config = {}) {
   };
 }
 
+// src/utils/parse-boolean-flag.ts
+function parseBooleanFlag(rawValue, fallback) {
+  if (!rawValue) return fallback;
+  const normalized = rawValue.trim().toLowerCase();
+  if (normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on") {
+    return true;
+  }
+  if (normalized === "0" || normalized === "false" || normalized === "no" || normalized === "off") {
+    return false;
+  }
+  return fallback;
+}
+
 // src/auxiliaries.ts
 var AthenaErrorKind = {
   UniqueViolation: "unique_violation",
@@ -1567,16 +1886,8 @@ var AthenaErrorCategory = {
   Database: "database",
   Unknown: "unknown"
 };
-function parseBooleanFlag(rawValue, fallback) {
-  if (!rawValue) return fallback;
-  const normalized = rawValue.trim().toLowerCase();
-  if (normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on") {
-    return true;
-  }
-  if (normalized === "0" || normalized === "false" || normalized === "no" || normalized === "off") {
-    return false;
-  }
-  return fallback;
+function parseBooleanFlag2(rawValue, fallback) {
+  return parseBooleanFlag(rawValue, fallback);
 }
 var AthenaError = class extends Error {
   code;
@@ -1600,9 +1911,38 @@ var AthenaError = class extends Error {
     this.raw = input.raw;
   }
 };
-function isRecord3(value) {
+function isRecord4(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 (!isRecord4(error)) {
+    return void 0;
+  }
+  return firstNonEmptyString(error.message, error.error, error.details);
+}
+function gatewayCodeFromUnknownError(error) {
+  if (!isRecord4(error) || typeof error.gatewayCode !== "string") {
+    return void 0;
+  }
+  return error.gatewayCode;
+}
+function isAthenaResultErrorLike(value) {
+  return isRecord4(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";
 }
@@ -1613,7 +1953,7 @@ function isAthenaErrorCategory(value) {
   return value === "transport" || value === "client" || value === "server" || value === "database" || value === "unknown";
 }
 function isNormalizedAthenaError(value) {
-  return isRecord3(value) && isAthenaErrorKind(value.kind) && isAthenaErrorCode(value.code) && isAthenaErrorCategory(value.category) && typeof value.retryable === "boolean" && typeof value.message === "string" && "raw" in value;
+  return isRecord4(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) {
@@ -1626,7 +1966,7 @@ function withContextOverrides(normalized, context) {
   };
 }
 function resolveAttachedNormalizedError(resultOrError) {
-  if (!isRecord3(resultOrError)) return void 0;
+  if (!isRecord4(resultOrError)) return void 0;
   if (!("__athenaNormalizedError" in resultOrError)) return void 0;
   const candidate = resultOrError.__athenaNormalizedError;
   return isNormalizedAthenaError(candidate) ? candidate : void 0;
@@ -1645,7 +1985,7 @@ function contextHint(context) {
   return `Identity: ${identity}`;
 }
 function isAthenaResultLike(value) {
-  return isRecord3(value) && "status" in value && "error" in value && "data" in value && typeof value.status === "number";
+  return isRecord4(value) && "status" in value && "error" in value && "data" in value && typeof value.status === "number";
 }
 function operationFromDetails(details) {
   if (!details?.endpoint) return void 0;
@@ -1742,15 +2082,16 @@ function toAthenaGatewayError(source, fallbackMessage, context) {
     return source;
   }
   if (isAthenaResultLike(source) && source.errorDetails) {
+    const message2 = messageFromUnknownError(source.error) ?? source.errorDetails.message ?? fallbackMessage;
     return new AthenaGatewayError({
       code: source.errorDetails.code,
-      message: source.error ?? source.errorDetails.message,
+      message: message2,
       status: source.status,
       endpoint: source.errorDetails.endpoint,
       method: source.errorDetails.method,
       requestId: source.errorDetails.requestId,
-      hint: source.errorDetails.hint,
-      cause: source.errorDetails.cause
+      hint: (isRecord4(source.error) ? firstNonEmptyString(source.error.hint) : void 0) ?? source.errorDetails.hint,
+      cause: (isRecord4(source.error) ? firstNonEmptyString(source.error.cause) : void 0) ?? source.errorDetails.cause
     });
   }
   const normalized = normalizeAthenaError(source, context);
@@ -1772,13 +2113,50 @@ function normalizeAthenaError(resultOrError, context) {
     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 = resultOrError.error ?? details?.message ?? `Athena ${context?.operation ?? operationFromDetails(details) ?? "request"} failed`;
+    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 kind2 = classifyKind(resultOrError.status, details?.code, message2);
-    const code = toAthenaErrorCode(kind2, resultOrError.status, details?.code);
+    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,
@@ -1815,7 +2193,7 @@ function normalizeAthenaError(resultOrError, context) {
     };
   }
   if (resultOrError instanceof Error) {
-    const maybeStatus = isRecord3(resultOrError) && typeof resultOrError.status === "number" ? resultOrError.status : void 0;
+    const maybeStatus = isRecord4(resultOrError) && typeof resultOrError.status === "number" ? resultOrError.status : void 0;
     const kind2 = classifyKind(maybeStatus, void 0, resultOrError.message);
     return {
       kind: kind2,
@@ -2032,45 +2410,527 @@ function createDbModule(input) {
   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 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 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) {
-    result.count = response.count;
-  }
-  return result;
-}
-function attachNormalizedError(result, normalizedError) {
-  Object.defineProperty(result, ATHENA_NORMALIZED_ERROR_KEY, {
-    value: normalizedError,
-    enumerable: false,
-    configurable: true,
-    writable: false
-  });
+  if (response.count !== void 0) {
+    result.count = response.count;
+  }
+  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
+      });
+    }
+  };
 }
-function createResultFormatter(experimental) {
-  if (!experimental?.enableErrorNormalization) {
-    return formatResult;
+async function executeWithQueryTrace(tracer, context, runner, callsiteOverride) {
+  if (!tracer) {
+    return runner();
   }
-  return (response, context) => {
-    const result = formatResult(response);
-    if (result.error == null) {
-      return result;
-    }
-    const normalizedError = normalizeAthenaError(result, context);
-    attachNormalizedError(result, normalizedError);
+  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;
@@ -2092,15 +2952,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;
   };
@@ -2108,7 +2969,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);
@@ -2116,7 +2977,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);
@@ -2139,21 +3000,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)) {
@@ -2176,25 +3028,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;
@@ -2272,6 +3191,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) {
@@ -2383,7 +3533,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);
       }
@@ -2446,14 +3596,15 @@ function createRpcFilterMethods(filters, self) {
     }
   };
 }
-function createRpcBuilder(functionName, args, baseOptions, client, formatGatewayResult) {
+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,
@@ -2467,14 +3618,30 @@ function createRpcBuilder(functionName, args, baseOptions, client, formatGateway
       offset: state.offset,
       order: state.order
     };
-    const response = await client.rpcGateway(payload, mergedOptions);
-    return formatGatewayResult(response, { operation: "rpc" });
+    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;
   };
@@ -2484,10 +3651,10 @@ function createRpcBuilder(functionName, args, baseOptions, client, formatGateway
     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) {
@@ -2522,7 +3689,7 @@ function createRpcBuilder(functionName, args, baseOptions, client, formatGateway
   });
   return builder;
 }
-function createTableBuilder(tableName, client, formatGatewayResult) {
+function createTableBuilder(tableName, client, formatGatewayResult, tracer, experimental) {
   const state = {
     conditions: []
   };
@@ -2554,15 +3721,24 @@ function createTableBuilder(tableName, client, formatGatewayResult) {
     }
     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;
@@ -2571,53 +3747,107 @@ function createTableBuilder(tableName, client, formatGatewayResult) {
         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 formatGatewayResult(queryResponse, { table: resolvedTableName, operation: "select" });
+        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 formatGatewayResult(response, { table: resolvedTableName, operation: "select" });
+    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;
@@ -2634,11 +3864,75 @@ function createTableBuilder(tableName, client, formatGatewayResult) {
       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 = {
@@ -2651,12 +3945,27 @@ function createTableBuilder(tableName, client, formatGatewayResult) {
           if (mergedOptions?.defaultToNull !== void 0) {
             payload.default_to_null = mergedOptions.defaultToNull;
           }
-          const response = await client.insertGateway(payload, mergedOptions);
-          return formatGatewayResult(response, { table: resolvedTableName, operation: "insert" });
+          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 = {
@@ -2669,14 +3978,30 @@ function createTableBuilder(tableName, client, formatGatewayResult) {
         if (mergedOptions?.defaultToNull !== void 0) {
           payload.default_to_null = mergedOptions.defaultToNull;
         }
-        const response = await client.insertGateway(payload, mergedOptions);
-        return formatGatewayResult(response, { table: resolvedTableName, operation: "insert" });
+        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 = {
@@ -2691,12 +4016,27 @@ function createTableBuilder(tableName, client, formatGatewayResult) {
           if (mergedOptions?.defaultToNull !== void 0) {
             payload.default_to_null = mergedOptions.defaultToNull;
           }
-          const response = await client.insertGateway(payload, mergedOptions);
-          return formatGatewayResult(response, { table: resolvedTableName, operation: "insert" });
+          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 = {
@@ -2711,13 +4051,29 @@ function createTableBuilder(tableName, client, formatGatewayResult) {
         if (mergedOptions?.defaultToNull !== void 0) {
           payload.default_to_null = mergedOptions.defaultToNull;
         }
-        const response = await client.insertGateway(payload, mergedOptions);
-        return formatGatewayResult(response, { table: resolvedTableName, operation: "insert" });
+        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);
@@ -2732,10 +4088,25 @@ function createTableBuilder(tableName, client, formatGatewayResult) {
         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 formatGatewayResult(response, { table: resolvedTableName, operation: "update" });
+        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);
@@ -2747,7 +4118,8 @@ function createTableBuilder(tableName, client, formatGatewayResult) {
       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 = {
@@ -2760,13 +4132,33 @@ function createTableBuilder(tableName, client, formatGatewayResult) {
         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 formatGatewayResult(response, { table: resolvedTableName, operation: "delete" });
+        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) {
@@ -2775,14 +4167,29 @@ function createTableBuilder(tableName, client, formatGatewayResult) {
   });
   return builder;
 }
-function createQueryBuilder(client, formatGatewayResult) {
+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 formatGatewayResult(response, { operation: "query" });
+    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) {
@@ -2794,8 +4201,9 @@ function createClientFromConfig(config) {
     headers: config.headers
   });
   const formatGatewayResult = createResultFormatter(config.experimental);
+  const queryTracer = createQueryTracer(config.experimental);
   const auth = createAuthClient(config.auth);
-  const from = (table) => createTableBuilder(table, gateway, formatGatewayResult);
+  const from = (table) => createTableBuilder(table, gateway, formatGatewayResult, queryTracer, config.experimental);
   const rpc = (fn, args, options) => {
     const normalizedFn = fn.trim();
     if (!normalizedFn) {
@@ -2806,10 +4214,12 @@ function createClientFromConfig(config) {
       args,
       options,
       gateway,
-      formatGatewayResult
+      formatGatewayResult,
+      queryTracer,
+      captureTraceCallsite(queryTracer)
     );
   };
-  const query = createQueryBuilder(gateway, formatGatewayResult);
+  const query = createQueryBuilder(gateway, formatGatewayResult, queryTracer);
   const db = createDbModule({ from, rpc, query });
   return {
     from,
@@ -2824,12 +4234,40 @@ function toBackendConfig(b) {
   if (!b) return DEFAULT_BACKEND;
   return typeof b === "string" ? { type: b } : b;
 }
+function mergeAuthClientConfig(current, next) {
+  const merged = {
+    ...current ?? {},
+    ...next
+  };
+  if (current?.headers || next.headers) {
+    merged.headers = {
+      ...current?.headers ?? {},
+      ...next.headers ?? {}
+    };
+  }
+  return merged;
+}
+function mergeExperimentalOptions(current, next) {
+  const merged = {
+    ...current ?? {},
+    ...next
+  };
+  if (current?.traceQueries && typeof current.traceQueries === "object" && next.traceQueries && typeof next.traceQueries === "object") {
+    merged.traceQueries = {
+      ...current.traceQueries,
+      ...next.traceQueries
+    };
+  }
+  return merged;
+}
 var AthenaClientBuilderImpl = class {
   baseUrl;
   apiKey;
   backendConfig = DEFAULT_BACKEND;
   clientName;
   defaultHeaders;
+  authConfig;
+  experimentalOptions;
   isHealthTrackingEnabled = false;
   url(url) {
     this.baseUrl = url;
@@ -2851,6 +4289,35 @@ var AthenaClientBuilderImpl = class {
     this.defaultHeaders = headers;
     return this;
   }
+  auth(config) {
+    this.authConfig = mergeAuthClientConfig(this.authConfig, config);
+    return this;
+  }
+  experimental(options) {
+    this.experimentalOptions = mergeExperimentalOptions(this.experimentalOptions, options);
+    return this;
+  }
+  options(options) {
+    if (options.client !== void 0) {
+      this.clientName = options.client;
+    }
+    if (options.backend !== void 0) {
+      this.backendConfig = toBackendConfig(options.backend);
+    }
+    if (options.headers !== void 0) {
+      this.defaultHeaders = {
+        ...this.defaultHeaders ?? {},
+        ...options.headers
+      };
+    }
+    if (options.auth !== void 0) {
+      this.authConfig = mergeAuthClientConfig(this.authConfig, options.auth);
+    }
+    if (options.experimental !== void 0) {
+      this.experimentalOptions = mergeExperimentalOptions(this.experimentalOptions, options.experimental);
+    }
+    return this;
+  }
   healthTracking(enabled) {
     this.isHealthTrackingEnabled = enabled;
     return this;
@@ -2865,7 +4332,9 @@ var AthenaClientBuilderImpl = class {
       client: this.clientName,
       backend: this.backendConfig,
       headers: this.defaultHeaders,
-      healthTracking: this.isHealthTrackingEnabled
+      healthTracking: this.isHealthTrackingEnabled,
+      auth: this.authConfig,
+      experimental: this.experimentalOptions
     });
   }
 };
@@ -3480,7 +4949,7 @@ function resolveNullishValue(mode) {
   if (mode === "null") return null;
   return "";
 }
-function isRecord4(value) {
+function isRecord7(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function isNullableColumn(model, key) {
@@ -3489,7 +4958,7 @@ function isNullableColumn(model, key) {
 }
 function toModelFormDefaults(model, values, options) {
   const source = values;
-  if (!isRecord4(source)) {
+  if (!isRecord7(source)) {
     return {};
   }
   const mode = options?.nullishMode ?? "empty-string";
@@ -3745,7 +5214,7 @@ function normalizeBooleanFlag(rawValue, fallback) {
     return rawValue;
   }
   if (typeof rawValue === "string") {
-    return parseBooleanFlag(rawValue, fallback);
+    return parseBooleanFlag2(rawValue, fallback);
   }
   return fallback;
 }
@@ -3920,6 +5389,11 @@ async function loadGeneratorConfig(options = {}) {
   }
 }
 
+// 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([
@@ -4015,7 +5489,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;
   }
@@ -4533,7 +6007,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 ?? [];
   }
@@ -4628,10 +6102,24 @@ function resolveGeneratorProvider(providerConfig, experimentalFlags) {
   }
   throw new Error(`Unsupported generator provider kind: ${providerConfig.kind ?? "unknown"}`);
 }
+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);
@@ -4658,6 +6146,6 @@ async function runSchemaGenerator(options = {}) {
   };
 }
 
-export { AthenaClient, AthenaError, AthenaErrorCategory, AthenaErrorCode, AthenaErrorKind, AthenaGatewayError, Backend, DEFAULT_POSTGRES_SCHEMAS, assertInt, coerceInt, createAuthClient, createClient, createModelFormAdapter, createPostgresIntrospectionProvider, createTypedClient, defineDatabase, defineGeneratorConfig, defineModel, defineRegistry, defineSchema, findGeneratorConfigPath, generateArtifactsFromSnapshot, identifier, isAthenaGatewayError, isOk, loadGeneratorConfig, normalizeAthenaError, normalizeGeneratorConfig, normalizeSchemaSelection, parseBooleanFlag, requireAffected, requireSuccess, resolveGeneratorProvider, resolvePostgresColumnType, resolveProviderSchemas, runSchemaGenerator, toModelFormDefaults, toModelPayload, unwrap, unwrapOne, unwrapRows, withRetry };
+export { AthenaClient, AthenaError, AthenaErrorCategory, AthenaErrorCode, AthenaErrorKind, AthenaGatewayError, Backend, DEFAULT_POSTGRES_SCHEMAS, assertInt, coerceInt, createAuthClient, createAuthReactEmailInput, createClient, createModelFormAdapter, createPostgresIntrospectionProvider, createTypedClient, defineAuthEmailTemplate, defineDatabase, defineGeneratorConfig, defineModel, defineRegistry, defineSchema, findGeneratorConfigPath, generateArtifactsFromSnapshot, identifier, isAthenaGatewayError, isOk, loadGeneratorConfig, normalizeAthenaError, normalizeGeneratorConfig, normalizeSchemaSelection, parseBooleanFlag2 as parseBooleanFlag, renderAthenaReactEmail, requireAffected, requireSuccess, resolveGeneratorProvider, resolvePostgresColumnType, resolveProviderSchemas, runSchemaGenerator, toModelFormDefaults, toModelPayload, unwrap, unwrapOne, unwrapRows, withRetry };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map