@xylex-group/athena 2.1.2 → 2.4.0

package/dist/cli/index.js

@@ -1,10 +1,15 @@
-import { mkdir, writeFile } from 'fs/promises';
+import { mkdir, writeFile, stat } from 'fs/promises';
 import { resolve, dirname, posix } from 'path';
 import { existsSync, readFileSync } from 'fs';
 import { pathToFileURL } from 'url';
 
 // src/generator/pipeline.ts
 
+// src/utils/slugify.ts
+function slugify(input) {
+  return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64);
+}
+
 // src/generator/naming.ts
 var IDENTIFIER_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
 var RESERVED_IDENTIFIERS = /* @__PURE__ */ new Set([
@@ -100,7 +105,7 @@ function applyNamingStyle(input, style) {
     case "snake":
       return words.map((word) => word.toLowerCase()).join("_");
     case "kebab":
-      return words.map((word) => word.toLowerCase()).join("-");
+      return slugify(words.join("-"));
     default:
       return input;
   }
@@ -353,6 +358,19 @@ function isAthenaGatewayError(error) {
   return error instanceof AthenaGatewayError;
 }
 
+// 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 AthenaErrorCode = {
   UniqueViolation: "UNIQUE_VIOLATION",
@@ -373,20 +391,41 @@ 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);
 }
 function isRecord(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
+function firstNonEmptyString(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value.trim();
+    }
+  }
+  return void 0;
+}
+function messageFromUnknownError(error) {
+  if (typeof error === "string" && error.trim().length > 0) {
+    return error.trim();
+  }
+  if (error instanceof Error && error.message.trim().length > 0) {
+    return error.message.trim();
+  }
+  if (!isRecord(error)) {
+    return void 0;
+  }
+  return firstNonEmptyString(error.message, error.error, error.details);
+}
+function gatewayCodeFromUnknownError(error) {
+  if (!isRecord(error) || typeof error.gatewayCode !== "string") {
+    return void 0;
+  }
+  return error.gatewayCode;
+}
+function isAthenaResultErrorLike(value) {
+  return isRecord(value) && typeof value.message === "string" && (value.athenaCode === void 0 || isAthenaErrorCode(value.athenaCode)) && (value.kind === void 0 || isAthenaErrorKind(value.kind)) && (value.category === void 0 || isAthenaErrorCategory(value.category)) && (value.retryable === void 0 || typeof value.retryable === "boolean") && (value.status === void 0 || typeof value.status === "number");
+}
 function isAthenaErrorKind(value) {
   return value === "unique_violation" || value === "not_found" || value === "validation" || value === "auth" || value === "rate_limit" || value === "transient" || value === "unknown";
 }
@@ -458,6 +497,7 @@ function classifyKind(status, code, message) {
   if (status === 404 || hasNotFoundPattern) return "not_found";
   if (status === 401 || status === 403 || hasAuthPattern) return "auth";
   if (status === 429 || hasRateLimitPattern) return "rate_limit";
+  if (code === "INVALID_URL") return "validation";
   if (status === 400 || status === 422 || hasValidationPattern) return "validation";
   if (code === "NETWORK_ERROR" || status === 0 || status !== void 0 && status >= 500 || hasTransientPattern) {
     return "transient";
@@ -465,6 +505,9 @@ function classifyKind(status, code, message) {
   return "unknown";
 }
 function toAthenaErrorCode(kind, status, gatewayCode) {
+  if (gatewayCode === "INVALID_URL") {
+    return AthenaErrorCode.ValidationFailed;
+  }
   if (gatewayCode === "NETWORK_ERROR" || kind === "transient" && status === 0) {
     return AthenaErrorCode.NetworkUnavailable;
   }
@@ -508,13 +551,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,
@@ -792,7 +872,7 @@ function normalizeBooleanFlag(rawValue, fallback) {
     return rawValue;
   }
   if (typeof rawValue === "string") {
-    return parseBooleanFlag(rawValue, fallback);
+    return parseBooleanFlag2(rawValue, fallback);
   }
   return fallback;
 }
@@ -1281,8 +1361,74 @@ function generateArtifactsFromSnapshot(snapshot, config) {
   return new ArtifactComposer(snapshot, normalizedConfig).compose();
 }
 
+// src/gateway/url.ts
+var ATHENA_DEFAULT_BASE_URL = "https://athena-db.com";
+function describeReceivedValue(value) {
+  if (value === void 0) return "undefined";
+  if (value === null) return "null";
+  if (typeof value === "string") {
+    return value.trim().length > 0 ? JSON.stringify(value) : "an empty string";
+  }
+  return `${typeof value} ${JSON.stringify(value)}`;
+}
+function invalidBaseUrlError(message, hint) {
+  return new AthenaGatewayError({
+    code: "INVALID_URL",
+    message,
+    status: 0,
+    hint
+  });
+}
+function normalizeAthenaGatewayBaseUrl(input, options = {}) {
+  const label = options.label ?? "Athena gateway base URL";
+  const candidate = input ?? options.defaultBaseUrl;
+  if (candidate === void 0 || candidate === null) {
+    throw invalidBaseUrlError(
+      `${label} must be a non-empty absolute http(s) URL. Received ${describeReceivedValue(input)}.`,
+      'Set ATHENA_URL (or pass createClient(url, ...)) to a full URL such as "https://mirror3.athena-db.com".'
+    );
+  }
+  const trimmed = candidate.trim();
+  if (!trimmed) {
+    throw invalidBaseUrlError(
+      `${label} must be a non-empty absolute http(s) URL. Received ${describeReceivedValue(candidate)}.`,
+      'Set ATHENA_URL (or pass createClient(url, ...)) to a full URL such as "https://mirror3.athena-db.com".'
+    );
+  }
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    throw invalidBaseUrlError(
+      `${label} must be a valid absolute http(s) URL. Received ${describeReceivedValue(candidate)}.`,
+      'Use a full URL including the protocol, for example "https://mirror3.athena-db.com".'
+    );
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw invalidBaseUrlError(
+      `${label} must use http or https. Received ${JSON.stringify(trimmed)}.`,
+      'Use an Athena gateway URL such as "https://mirror3.athena-db.com".'
+    );
+  }
+  if (parsed.search || parsed.hash) {
+    throw invalidBaseUrlError(
+      `${label} must not include query parameters or hash fragments. Received ${JSON.stringify(trimmed)}.`,
+      'Pass only the base URL. Endpoint paths such as "/gateway/fetch" are appended by the SDK.'
+    );
+  }
+  return parsed.toString().replace(/\/+$/, "");
+}
+function buildAthenaGatewayUrl(baseUrl, path) {
+  if (!path.startsWith("/")) {
+    throw invalidBaseUrlError(
+      `Athena gateway path must start with "/". Received ${JSON.stringify(path)}.`,
+      'Use a leading slash such as "/gateway/fetch" or "/".'
+    );
+  }
+  return `${baseUrl}${path}`;
+}
+
 // src/gateway/client.ts
-var DEFAULT_BASE_URL = "https://athena-db.com";
 var DEFAULT_CLIENT = "railway_direct";
 var FALLBACK_SDK_VERSION = "1.3.0";
 var SDK_NAME = "xylex-group/athena";
@@ -1309,23 +1455,39 @@ function normalizeHeaderValue(value) {
 function isRecord2(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+}
+function resolveStructuredErrorPayload(payload) {
+  if (!isRecord2(payload)) return null;
+  return isRecord2(payload.error) ? payload.error : payload;
+}
 function resolveRequestId(headers) {
   return headers.get("x-request-id") ?? headers.get("x-correlation-id") ?? headers.get("x-athena-request-id") ?? void 0;
 }
 function resolveErrorMessage(payload, fallback) {
-  if (isRecord2(payload)) {
-    const messageCandidates = [payload.error, payload.message, payload.details];
+  const structuredPayload = resolveStructuredErrorPayload(payload);
+  if (structuredPayload) {
+    const messageCandidates = [structuredPayload.message, structuredPayload.error, structuredPayload.details];
     for (const candidate of messageCandidates) {
-      if (typeof candidate === "string" && candidate.trim().length > 0) {
-        return candidate.trim();
-      }
+      const resolved = nonEmptyString(candidate);
+      if (resolved) return resolved;
     }
   }
-  if (typeof payload === "string" && payload.trim().length > 0) {
-    return payload.trim();
-  }
+  const rawMessage = nonEmptyString(payload);
+  if (rawMessage) return rawMessage;
   return fallback;
 }
+function resolveErrorHint(payload) {
+  const structuredPayload = resolveStructuredErrorPayload(payload);
+  return structuredPayload ? nonEmptyString(structuredPayload.hint) : void 0;
+}
+function resolveStatusText(response, payload) {
+  const rawStatusText = nonEmptyString(response.statusText);
+  if (rawStatusText) return rawStatusText;
+  const payloadRecord = isRecord2(payload) ? payload : null;
+  return payloadRecord ? nonEmptyString(payloadRecord.statusText) ?? null : null;
+}
 function detailsFromError(error) {
   return error.toDetails();
 }
@@ -1463,9 +1625,168 @@ function buildHeaders(config, options) {
   });
   return headers;
 }
+function toInvalidUrlResponse(error, endpoint, method) {
+  const message = error instanceof Error ? error.message : String(error);
+  const gatewayError = error instanceof AthenaGatewayError ? error : new AthenaGatewayError({
+    code: "INVALID_URL",
+    message,
+    status: 0,
+    endpoint,
+    method,
+    cause: message,
+    hint: "Set ATHENA_URL to a full http(s) URL before running queries."
+  });
+  return {
+    ok: false,
+    status: 0,
+    statusText: null,
+    data: null,
+    error: gatewayError.message,
+    errorDetails: detailsFromError(
+      new AthenaGatewayError({
+        code: gatewayError.code,
+        message: gatewayError.message,
+        status: gatewayError.status,
+        endpoint,
+        method,
+        requestId: gatewayError.requestId,
+        hint: gatewayError.hint,
+        cause: gatewayError.causeDetail
+      })
+    ),
+    raw: null
+  };
+}
+function resolveGatewayBaseUrl(input) {
+  return normalizeAthenaGatewayBaseUrl(input, {
+    defaultBaseUrl: ATHENA_DEFAULT_BASE_URL
+  });
+}
+function resolveProbePath(path) {
+  if (!path) return "/";
+  if (!path.startsWith("/")) {
+    throw new AthenaGatewayError({
+      code: "INVALID_URL",
+      message: `Athena gateway probe path must start with "/". Received ${JSON.stringify(path)}.`,
+      status: 0,
+      hint: 'Use a leading slash such as "/" or "/health".'
+    });
+  }
+  return path;
+}
+function mergeConnectionHeaders(baseHeaders, headers) {
+  const merged = {
+    ...baseHeaders,
+    ...headers ?? {}
+  };
+  if (!merged["X-Athena-Sdk"] && !merged["x-athena-sdk"]) {
+    merged["X-Athena-Sdk"] = SDK_HEADER_VALUE;
+  }
+  return merged;
+}
+async function performConnectionCheck(baseUrl, requestHeaders, options) {
+  const path = resolveProbePath(options?.path);
+  const url = buildAthenaGatewayUrl(baseUrl, path);
+  try {
+    const response = await fetch(url, {
+      method: "GET",
+      headers: mergeConnectionHeaders(requestHeaders, options?.headers),
+      signal: options?.signal
+    });
+    const rawText = await response.text();
+    const requestId = resolveRequestId(response.headers);
+    const parsedBody = parseResponseBody(
+      rawText ?? "",
+      response.headers.get("content-type")
+    );
+    if (parsedBody.parseFailed) {
+      const invalidJsonError = new AthenaGatewayError({
+        code: "INVALID_JSON",
+        message: "Gateway probe returned malformed JSON",
+        status: response.status,
+        method: "GET",
+        requestId,
+        hint: "Verify the gateway response body is valid JSON.",
+        cause: rawText.slice(0, 300)
+      });
+      return {
+        ok: false,
+        reachable: true,
+        status: response.status,
+        statusText: resolveStatusText(response, parsedBody.parsed),
+        baseUrl,
+        url,
+        error: invalidJsonError.message,
+        errorDetails: detailsFromError(invalidJsonError),
+        raw: parsedBody.parsed
+      };
+    }
+    const parsed = parsedBody.parsed;
+    if (!response.ok) {
+      const httpError = new AthenaGatewayError({
+        code: "HTTP_ERROR",
+        message: resolveErrorMessage(
+          parsed,
+          `Athena gateway GET ${path} failed with status ${response.status}`
+        ),
+        status: response.status,
+        method: "GET",
+        requestId,
+        hint: resolveErrorHint(parsed)
+      });
+      return {
+        ok: false,
+        reachable: true,
+        status: response.status,
+        statusText: resolveStatusText(response, parsed),
+        baseUrl,
+        url,
+        error: httpError.message,
+        errorDetails: detailsFromError(httpError),
+        raw: parsed
+      };
+    }
+    return {
+      ok: true,
+      reachable: true,
+      status: response.status,
+      statusText: resolveStatusText(response, parsed),
+      baseUrl,
+      url,
+      error: void 0,
+      errorDetails: null,
+      raw: parsed
+    };
+  } catch (callError) {
+    const message = callError instanceof Error ? callError.message : String(callError);
+    const networkError = new AthenaGatewayError({
+      code: "NETWORK_ERROR",
+      message: `Network error while probing Athena gateway ${url}: ${message}`,
+      method: "GET",
+      cause: message,
+      hint: "Check gateway URL, DNS, and network reachability."
+    });
+    return {
+      ok: false,
+      reachable: false,
+      status: 0,
+      statusText: null,
+      baseUrl,
+      url,
+      error: networkError.message,
+      errorDetails: detailsFromError(networkError),
+      raw: null
+    };
+  }
+}
 async function callAthena(config, endpoint, method, payload, options) {
-  const baseUrl = (options?.baseUrl ?? config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
-  const url = `${baseUrl}${endpoint}`;
+  let baseUrl;
+  try {
+    baseUrl = resolveGatewayBaseUrl(options?.baseUrl ?? config.baseUrl);
+  } catch (error) {
+    return toInvalidUrlResponse(error, endpoint, method);
+  }
+  const url = buildAthenaGatewayUrl(baseUrl, endpoint);
   const headers = buildHeaders(config, options);
   try {
     const requestInit = {
@@ -1496,6 +1817,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),
@@ -1514,11 +1836,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),
@@ -1530,6 +1854,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,
@@ -1549,6 +1874,7 @@ async function callAthena(config, endpoint, method, payload, options) {
     return {
       ok: false,
       status: 0,
+      statusText: null,
       data: null,
       error: networkError.message,
       errorDetails: detailsFromError(networkError),
@@ -1557,32 +1883,44 @@ async function callAthena(config, endpoint, method, payload, options) {
   }
 }
 function createAthenaGatewayClient(config = {}) {
+  const normalizedBaseUrl = resolveGatewayBaseUrl(config.baseUrl);
+  const normalizedConfig = {
+    ...config,
+    baseUrl: normalizedBaseUrl
+  };
   return {
-    baseUrl: (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, ""),
+    baseUrl: normalizedBaseUrl,
     buildHeaders(options) {
-      return buildHeaders(config, options);
+      return buildHeaders(normalizedConfig, options);
+    },
+    verifyConnection(options) {
+      return performConnectionCheck(
+        normalizedBaseUrl,
+        buildHeaders(normalizedConfig),
+        options
+      );
     },
     fetchGateway(payload, options) {
-      return callAthena(config, "/gateway/fetch", "POST", payload, options);
+      return callAthena(normalizedConfig, "/gateway/fetch", "POST", payload, options);
     },
     insertGateway(payload, options) {
-      return callAthena(config, "/gateway/insert", "PUT", payload, options);
+      return callAthena(normalizedConfig, "/gateway/insert", "PUT", payload, options);
     },
     updateGateway(payload, options) {
-      return callAthena(config, "/gateway/update", "POST", payload, options);
+      return callAthena(normalizedConfig, "/gateway/update", "POST", payload, options);
     },
     deleteGateway(payload, options) {
-      return callAthena(config, "/gateway/delete", "DELETE", payload, options);
+      return callAthena(normalizedConfig, "/gateway/delete", "DELETE", payload, options);
     },
     rpcGateway(payload, options) {
       if (options?.get) {
         const endpoint = buildRpcGetEndpoint(payload);
-        return callAthena(config, endpoint, "GET", null, options);
+        return callAthena(normalizedConfig, endpoint, "GET", null, options);
       }
-      return callAthena(config, "/gateway/rpc", "POST", payload, options);
+      return callAthena(normalizedConfig, "/gateway/rpc", "POST", payload, options);
     },
     queryGateway(payload, options) {
-      return callAthena(config, "/gateway/query", "POST", payload, options);
+      return callAthena(normalizedConfig, "/gateway/query", "POST", payload, options);
     }
   };
 }
@@ -1590,10 +1928,29 @@ function createAthenaGatewayClient(config = {}) {
 // src/sql-identifiers.ts
 var SIMPLE_IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 var COMPOSITE_IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/;
-var ALIAS_PATTERN = /^([A-Za-z_][A-Za-z0-9_.]*)\s+(?:as\s+)?([A-Za-z_][A-Za-z0-9_]*)$/i;
+var SQL_ALIAS_PATTERN = /^([A-Za-z_][A-Za-z0-9_.]*)\s+(?:as\s+)?([A-Za-z_][A-Za-z0-9_]*)$/i;
+var RESPONSE_ALIAS_PATTERN = /^([A-Za-z_][A-Za-z0-9_]*)\s*:\s*([A-Za-z_][A-Za-z0-9_.]*)$/i;
 function quoteIdentifierSegment(identifier) {
   return `"${identifier.replace(/"/g, '""')}"`;
 }
+function parseAliasedIdentifierToken(token) {
+  const responseAliasMatch = RESPONSE_ALIAS_PATTERN.exec(token);
+  if (responseAliasMatch) {
+    const [, aliasIdentifier2, baseIdentifier2] = responseAliasMatch;
+    if (COMPOSITE_IDENTIFIER_PATTERN.test(baseIdentifier2) && SIMPLE_IDENTIFIER_PATTERN.test(aliasIdentifier2)) {
+      return { baseIdentifier: baseIdentifier2, aliasIdentifier: aliasIdentifier2 };
+    }
+  }
+  const sqlAliasMatch = SQL_ALIAS_PATTERN.exec(token);
+  if (!sqlAliasMatch) {
+    return null;
+  }
+  const [, baseIdentifier, aliasIdentifier] = sqlAliasMatch;
+  if (!COMPOSITE_IDENTIFIER_PATTERN.test(baseIdentifier) || !SIMPLE_IDENTIFIER_PATTERN.test(aliasIdentifier)) {
+    return null;
+  }
+  return { baseIdentifier, aliasIdentifier };
+}
 function quoteQualifiedIdentifier(identifier) {
   return identifier.split(".").map((segment) => quoteIdentifierSegment(segment)).join(".");
 }
@@ -1602,23 +1959,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 = [];
@@ -1702,6 +2063,190 @@ function quoteSelectColumnsExpression(columns) {
   return tokens.map(quoteSelectToken).join(", ");
 }
 
+// src/auth/react-email.ts
+var reactEmailRenderModulePromise;
+function isRecord3(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isFunction(value) {
+  return typeof value === "function";
+}
+function toStringOrUndefined(value) {
+  if (typeof value !== "string") return void 0;
+  return value;
+}
+function nowIsoString() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function emitReactEmailEvent(observe, phase, input = {}) {
+  if (!observe) return;
+  try {
+    observe({
+      phase,
+      timestamp: nowIsoString(),
+      ...input
+    });
+  } catch {
+  }
+}
+function mergeRenderDefaults(input, defaults) {
+  return {
+    ...input,
+    pretty: input.pretty ?? defaults?.pretty,
+    includePlainText: input.includePlainText ?? defaults?.includePlainText
+  };
+}
+function mergeRuntimeOptions(options) {
+  if (!options) return void 0;
+  return {
+    defaults: options.defaults,
+    observe: options.observe,
+    route: "route" in options ? options.route : void 0
+  };
+}
+async function resolveReactEmailRenderModule() {
+  if (!reactEmailRenderModulePromise) {
+    reactEmailRenderModulePromise = (async () => {
+      try {
+        const loaded = await import('@react-email/render');
+        if (!isFunction(loaded.render)) {
+          throw new Error("missing render(...) export");
+        }
+        return {
+          render: loaded.render,
+          toPlainText: isFunction(loaded.toPlainText) ? loaded.toPlainText : void 0,
+          pretty: isFunction(loaded.pretty) ? loaded.pretty : void 0
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(
+          `React Email rendering requires @react-email/render. Install it in your project (for example: pnpm add @react-email/render). Loader error: ${message}`
+        );
+      }
+    })();
+  }
+  if (!reactEmailRenderModulePromise) {
+    throw new Error("React Email renderer module failed to initialize");
+  }
+  return reactEmailRenderModulePromise;
+}
+async function resolveReactEmailElement(input) {
+  if (input.element != null) {
+    return input.element;
+  }
+  if (!input.component) {
+    throw new Error("react email payload requires either `element` or `component`");
+  }
+  try {
+    const reactModule = await import('react');
+    if (typeof reactModule.createElement !== "function") {
+      throw new Error("react createElement(...) export is unavailable");
+    }
+    return reactModule.createElement(
+      input.component,
+      input.props ?? {}
+    );
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `React Email component rendering requires react runtime support. Install react in your project. Loader error: ${message}`
+    );
+  }
+}
+async function renderAthenaReactEmail(input, options) {
+  if (!isRecord3(input)) {
+    throw new Error("react email payload must be an object");
+  }
+  const runtimeOptions = mergeRuntimeOptions(options);
+  const start = Date.now();
+  emitReactEmailEvent(runtimeOptions?.observe, "render:start", {
+    route: runtimeOptions?.route,
+    message: "Rendering react email payload"
+  });
+  try {
+    const normalizedInput = mergeRenderDefaults(input, runtimeOptions?.defaults);
+    const element = await resolveReactEmailElement(normalizedInput);
+    const renderModule = await resolveReactEmailRenderModule();
+    const htmlValue = await renderModule.render(element);
+    const renderedHtml = typeof htmlValue === "string" ? htmlValue : String(htmlValue ?? "");
+    if (!renderedHtml.trim()) {
+      throw new Error("react email renderer returned an empty HTML string");
+    }
+    let html = renderedHtml;
+    if (normalizedInput.pretty && renderModule.pretty) {
+      const prettyValue = await renderModule.pretty(renderedHtml);
+      if (typeof prettyValue === "string" && prettyValue.trim().length > 0) {
+        html = prettyValue;
+      }
+    }
+    const explicitText = toStringOrUndefined(normalizedInput.text);
+    if (explicitText !== void 0) {
+      emitReactEmailEvent(runtimeOptions?.observe, "render:success", {
+        route: runtimeOptions?.route,
+        durationMs: Date.now() - start,
+        message: "Rendered react email with explicit text"
+      });
+      return {
+        html,
+        text: explicitText
+      };
+    }
+    if (normalizedInput.includePlainText === false || !renderModule.toPlainText) {
+      emitReactEmailEvent(runtimeOptions?.observe, "render:success", {
+        route: runtimeOptions?.route,
+        durationMs: Date.now() - start,
+        message: "Rendered react email without plain-text derivation"
+      });
+      return { html };
+    }
+    const plainTextValue = await renderModule.toPlainText(html);
+    const plainText = toStringOrUndefined(plainTextValue);
+    emitReactEmailEvent(runtimeOptions?.observe, "render:success", {
+      route: runtimeOptions?.route,
+      durationMs: Date.now() - start,
+      message: plainText ? "Rendered react email with derived plain text" : "Rendered react email HTML only"
+    });
+    if (plainText === void 0) {
+      return { html };
+    }
+    return {
+      html,
+      text: plainText
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    emitReactEmailEvent(runtimeOptions?.observe, "render:error", {
+      route: runtimeOptions?.route,
+      durationMs: Date.now() - start,
+      error: message,
+      message: "Failed to render react email payload"
+    });
+    throw error;
+  }
+}
+async function resolveReactEmailPayloadFields(input, fields, options) {
+  const { react, ...payloadWithoutReact } = input;
+  if (!react) {
+    return payloadWithoutReact;
+  }
+  const rendered = await renderAthenaReactEmail(react, options);
+  const payload = {
+    ...payloadWithoutReact
+  };
+  payload[fields.htmlField] = rendered.html;
+  const currentTextValue = payload[fields.textField];
+  if (rendered.text !== void 0 && (currentTextValue === void 0 || currentTextValue === null || currentTextValue === "")) {
+    payload[fields.textField] = rendered.text;
+  }
+  if (fields.variablesField && (payload[fields.variablesField] === void 0 || payload[fields.variablesField] === null) && isRecord3(react.props)) {
+    const derivedVariables = Object.keys(react.props);
+    if (derivedVariables.length > 0) {
+      payload[fields.variablesField] = derivedVariables;
+    }
+  }
+  return payload;
+}
+
 // src/auth/client.ts
 var DEFAULT_AUTH_BASE_URL = "http://localhost:3001/api/auth";
 var FALLBACK_SDK_VERSION2 = "1.0.0";
@@ -1711,7 +2256,7 @@ var SDK_HEADER_VALUE2 = `${SDK_NAME2} ${SDK_VERSION2}`;
 function normalizeBaseUrl(baseUrl) {
   return (baseUrl ?? DEFAULT_AUTH_BASE_URL).replace(/\/$/, "");
 }
-function isRecord3(value) {
+function isRecord4(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function normalizeHeaderValue2(value) {
@@ -1736,7 +2281,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 (isRecord3(payload)) {
+  if (isRecord4(payload)) {
     const messageCandidates = [payload.error, payload.message, payload.details];
     for (const candidate of messageCandidates) {
       if (typeof candidate === "string" && candidate.trim().length > 0) {
@@ -2062,6 +2607,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",
@@ -2089,7 +2647,7 @@ function createAuthClient(config = {}) {
         data: null
       };
     }
-    const fallbackStatus = isRecord3(fallback.data) && typeof fallback.data.ok === "boolean" ? fallback.data.ok ? "ok" : "error" : "ok";
+    const fallbackStatus = isRecord4(fallback.data) && typeof fallback.data.ok === "boolean" ? fallback.data.ok ? "ok" : "error" : "ok";
     return {
       ...fallback,
       data: {
@@ -2525,9 +3083,17 @@ 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),
-        delete: (input, options) => postGeneric("/admin/email/delete", 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),
           get: (input, options) => getWithQuery("/admin/email-failure/get", input, options),
@@ -2538,17 +3104,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: {
@@ -2743,8 +3325,8 @@ function createAuthClient(config = {}) {
 // src/db/module.ts
 function createDbModule(input) {
   const db = {
-    from(table) {
-      return input.from(table);
+    from(table, options) {
+      return input.from(table, options);
     },
     select(table, columns, options) {
       return input.from(table).select(columns, options);
@@ -2771,17 +3353,551 @@ 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");
+  if (node.schema && node.via) {
+    throw new Error(
+      `findMany relation "${propertyKey}" cannot combine schema and via yet; use schema with the relation key, or use via without schema`
+    );
+  }
+  const relationTokenBase = normalizeIdentifier(node.via ?? propertyKey, "select relation token");
+  if (node.schema && relationTokenBase.includes(".")) {
+    throw new Error(
+      `findMany relation "${propertyKey}" already resolves to a qualified relation token; do not also set schema`
+    );
+  }
+  const relationSchema = node.schema?.trim();
+  const relationToken = relationSchema ? `${normalizeIdentifier(relationSchema, "select relation schema")}.${relationTokenBase}` : relationTokenBase;
+  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 selectShapeUsesRelationSchema(select) {
+  if (!isRecord5(select)) {
+    return false;
+  }
+  for (const rawValue of Object.values(select)) {
+    if (!isRelationSelectNode(rawValue)) {
+      continue;
+    }
+    if (typeof rawValue.schema === "string" && rawValue.schema.trim().length > 0) {
+      return true;
+    }
+    if (selectShapeUsesRelationSchema(rawValue.select)) {
+      return true;
+    }
+  }
+  return false;
+}
+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/gateway/structured-select.ts
+var IDENTIFIER_SEGMENT_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function isIdentifierPath(value) {
+  const segments = value.split(".").map((segment) => segment.trim());
+  return segments.length > 1 && segments.every((segment) => IDENTIFIER_SEGMENT_PATTERN.test(segment));
+}
+function extractRelationHead(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed) return "";
+  const aliasIndex = trimmed.indexOf(":");
+  const withoutAlias = aliasIndex >= 0 ? trimmed.slice(aliasIndex + 1).trim() : trimmed;
+  const modifierIndex = withoutAlias.indexOf("!");
+  return (modifierIndex >= 0 ? withoutAlias.slice(0, modifierIndex) : withoutAlias).trim();
+}
+function hasSchemaQualifiedRelationToken(select) {
+  let singleQuoted = false;
+  let doubleQuoted = false;
+  let tokenStart = 0;
+  for (let index = 0; index < select.length; index += 1) {
+    const char = select[index];
+    const next = index + 1 < select.length ? select[index + 1] : "";
+    if (singleQuoted) {
+      if (char === "'" && next === "'") {
+        index += 1;
+        continue;
+      }
+      if (char === "'") {
+        singleQuoted = false;
+      }
+      continue;
+    }
+    if (doubleQuoted) {
+      if (char === '"' && next === '"') {
+        index += 1;
+        continue;
+      }
+      if (char === '"') {
+        doubleQuoted = false;
+      }
+      continue;
+    }
+    if (char === "'") {
+      singleQuoted = true;
+      continue;
+    }
+    if (char === '"') {
+      doubleQuoted = true;
+      continue;
+    }
+    if (char === "(") {
+      const relationHead = extractRelationHead(select.slice(tokenStart, index));
+      if (isIdentifierPath(relationHead)) {
+        return true;
+      }
+      tokenStart = index + 1;
+      continue;
+    }
+    if (char === "," || char === ")") {
+      tokenStart = index + 1;
+    }
+  }
+  return false;
+}
+function toStructuredSelectString(columns) {
+  return Array.isArray(columns) ? columns.join(",") : columns;
+}
+function buildStructuredWhere(conditions) {
+  if (!conditions?.length) return void 0;
+  const where = {};
+  for (const condition of conditions) {
+    if (!condition.column) {
+      return null;
+    }
+    if (condition.column_cast !== void 0 || condition.value_cast !== void 0) {
+      return null;
+    }
+    const operand = condition.value;
+    const operator = condition.operator;
+    if (operator === "eq") {
+      if (operand === void 0) return null;
+    } else if (operator === "neq" || operator === "gt" || operator === "lt") {
+      if (operand === void 0) return null;
+    } else if (operator === "in") {
+      if (!Array.isArray(operand)) return null;
+    } else {
+      return null;
+    }
+    const existing = where[condition.column];
+    if (existing !== void 0 && (typeof existing !== "object" || existing === null || Array.isArray(existing))) {
+      return null;
+    }
+    const next = existing ?? {};
+    if (Object.prototype.hasOwnProperty.call(next, operator)) {
+      return null;
+    }
+    next[operator] = operand;
+    where[condition.column] = next;
+  }
+  return where;
+}
+function buildStructuredOrderBy(order) {
+  if (!order?.field) return void 0;
+  return {
+    [order.field]: order.direction === "descending" ? "desc" : "asc"
+  };
+}
+function buildStructuredSelectTransport(input) {
+  const select = toStructuredSelectString(input.columns).trim();
+  if (!select || select === "*") {
+    return null;
+  }
+  if (!hasSchemaQualifiedRelationToken(select)) {
+    return null;
+  }
+  if (input.count !== void 0 || input.head !== void 0) {
+    return {
+      error: "Schema-qualified nested select strings require structured select transport, which does not support count/head options in athena-js yet."
+    };
+  }
+  const where = buildStructuredWhere(input.conditions);
+  if (where === null) {
+    return {
+      error: "Schema-qualified nested select strings only support eq, neq, gt, lt, and in filters in athena-js structured select transport."
+    };
+  }
+  return {
+    select,
+    payload: {
+      table_name: input.tableName,
+      select,
+      where,
+      orderBy: buildStructuredOrderBy(input.order),
+      limit: input.limit,
+      offset: input.offset,
+      strip_nulls: input.stripNulls
+    }
+  };
+}
+
+// src/query-transport.ts
+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 resolvePagination(input) {
+  let limit = input.limit;
+  let offset = input.offset;
+  if (limit === void 0 && input.pageSize !== void 0) {
+    limit = Math.max(0, Math.trunc(input.pageSize));
+  }
+  if (offset === void 0 && input.pageSize !== void 0 && input.currentPage !== void 0 && input.currentPage > 0) {
+    offset = (Math.trunc(input.currentPage) - 1) * Math.max(0, Math.trunc(input.pageSize));
+  }
+  return { limit, offset };
+}
+function hasTypedEqualityComparison(conditions) {
+  return conditions?.some(
+    (condition) => condition.operator === "eq" && (condition.value_cast !== void 0 || condition.column_cast !== void 0)
+  ) ?? false;
+}
+function createSelectTransportPlan(input) {
+  const conditions = input.state.conditions.length ? input.state.conditions.map((condition) => ({ ...condition })) : void 0;
+  if (hasTypedEqualityComparison(conditions) && !input.options?.head && !input.options?.count && conditions) {
+    const query = input.buildTypedSelectQuery({
+      tableName: input.tableName,
+      columns: input.columns,
+      conditions,
+      limit: input.state.limit,
+      offset: input.state.offset,
+      currentPage: input.state.currentPage,
+      pageSize: input.state.pageSize,
+      order: input.state.order
+    });
+    if (query) {
+      return {
+        kind: "query",
+        query,
+        payload: { query }
+      };
+    }
+  }
+  const pagination = resolvePagination({
+    limit: input.state.limit,
+    offset: input.state.offset,
+    currentPage: input.state.currentPage,
+    pageSize: input.state.pageSize
+  });
+  const stripNulls = input.options?.stripNulls ?? true;
+  const structuredSelectTransport = buildStructuredSelectTransport({
+    tableName: input.tableName,
+    columns: input.columns,
+    conditions,
+    limit: pagination.limit,
+    offset: pagination.offset,
+    order: input.state.order,
+    stripNulls,
+    count: input.options?.count,
+    head: input.options?.head
+  });
+  if (structuredSelectTransport && "error" in structuredSelectTransport) {
+    throw new Error(structuredSelectTransport.error);
+  }
+  if (structuredSelectTransport) {
+    const { payload, select } = structuredSelectTransport;
+    return {
+      kind: "fetch",
+      payload,
+      debug: {
+        columns: select,
+        conditions,
+        limit: pagination.limit,
+        offset: pagination.offset,
+        order: input.state.order
+      }
+    };
+  }
+  return {
+    kind: "fetch",
+    payload: {
+      table_name: input.tableName,
+      columns: input.columns,
+      conditions,
+      limit: input.state.limit,
+      offset: input.state.offset,
+      current_page: input.state.currentPage,
+      page_size: input.state.pageSize,
+      total_pages: input.state.totalPages,
+      sort_by: input.state.order,
+      strip_nulls: stripNulls,
+      count: input.options?.count,
+      head: input.options?.head
+    },
+    debug: {
+      columns: input.columns,
+      conditions,
+      limit: input.state.limit,
+      offset: input.state.offset,
+      currentPage: input.state.currentPage,
+      pageSize: input.state.pageSize,
+      order: input.state.order
+    }
+  };
+}
+
 // 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 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) {
@@ -2798,19 +3914,236 @@ function attachNormalizedError(result, normalizedError) {
   });
 }
 function createResultFormatter(experimental) {
-  if (!experimental?.enableErrorNormalization) {
-    return formatResult;
-  }
   return (response, context) => {
     const result = formatResult(response);
-    if (result.error == null) {
+    if (response.error == null && response.errorDetails == null) {
       return result;
     }
-    const normalizedError = normalizeAthenaError(result, context);
+    const normalizedError = normalizeAthenaError(
+      {
+        ...result,
+        error: response.error ?? response.errorDetails?.message ?? null
+      },
+      context
+    );
+    result.error = createResultError(response, result, normalizedError);
     attachNormalizedError(result, normalizedError);
     return result;
   };
 }
+function isRecord6(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function firstNonEmptyString2(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value.trim();
+    }
+  }
+  return void 0;
+}
+function resolveStructuredErrorPayload2(raw) {
+  if (!isRecord6(raw)) return null;
+  return isRecord6(raw.error) ? raw.error : raw;
+}
+function resolveStructuredErrorDetails(payload, message) {
+  if (!payload || !("details" in payload)) {
+    return null;
+  }
+  const details = payload.details;
+  if (details == null) {
+    return null;
+  }
+  if (typeof details === "string" && details.trim() === message.trim()) {
+    return null;
+  }
+  return details;
+}
+function createResultError(response, result, normalized) {
+  const rawRecord = isRecord6(response.raw) ? response.raw : null;
+  const payload = resolveStructuredErrorPayload2(response.raw);
+  const message = firstNonEmptyString2(
+    response.error,
+    payload?.message,
+    payload?.error,
+    payload?.details,
+    response.errorDetails?.message,
+    normalized.message
+  ) ?? normalized.message;
+  const statusText = firstNonEmptyString2(response.statusText, rawRecord?.statusText) ?? null;
+  const hint = firstNonEmptyString2(payload?.hint, response.errorDetails?.hint) ?? null;
+  const code = firstNonEmptyString2(payload?.code) ?? normalized.code;
+  const details = resolveStructuredErrorDetails(payload, message) ?? response.errorDetails?.cause ?? null;
+  return {
+    message,
+    code,
+    athenaCode: normalized.code,
+    gatewayCode: response.errorDetails?.code ?? null,
+    kind: normalized.kind,
+    category: normalized.category,
+    retryable: normalized.retryable,
+    details,
+    hint,
+    status: result.status,
+    statusText,
+    constraint: normalized.constraint,
+    table: normalized.table,
+    operation: normalized.operation,
+    endpoint: response.errorDetails?.endpoint,
+    method: response.errorDetails?.method,
+    requestId: response.errorDetails?.requestId,
+    cause: response.errorDetails?.cause,
+    raw: result.raw
+  };
+}
+function parseQueryTraceCallsiteFrame(frame) {
+  const trimmed = frame.trim();
+  if (!trimmed) {
+    return null;
+  }
+  let body = trimmed.replace(/^at\s+/, "");
+  if (body.startsWith("async ")) {
+    body = body.slice(6);
+  }
+  let functionName;
+  let location = body;
+  const wrappedMatch = body.match(/^(.*?)\s+\((.*)\)$/);
+  if (wrappedMatch) {
+    functionName = wrappedMatch[1].trim() || void 0;
+    location = wrappedMatch[2].trim();
+  }
+  const locationMatch = location.match(/^(.*):(\d+):(\d+)$/);
+  if (!locationMatch) {
+    return null;
+  }
+  const filePath = locationMatch[1].replace(/^file:\/\//, "");
+  const line = Number(locationMatch[2]);
+  const column = Number(locationMatch[3]);
+  if (!Number.isFinite(line) || !Number.isFinite(column)) {
+    return null;
+  }
+  const normalizedPath = filePath.replace(/\\/g, "/");
+  const fileName = normalizedPath.split("/").at(-1) ?? filePath;
+  return {
+    filePath,
+    fileName,
+    line,
+    column,
+    frame: trimmed,
+    functionName
+  };
+}
+function captureQueryTraceCallsite() {
+  const stack = new Error().stack;
+  if (!stack) return null;
+  const frames = stack.split("\n").slice(2).map((frame) => frame.trim()).filter(Boolean);
+  for (const frame of frames) {
+    if (QUERY_TRACE_STACK_SKIP_PATTERNS.some((pattern) => frame.includes(pattern))) {
+      continue;
+    }
+    const callsite = parseQueryTraceCallsiteFrame(frame);
+    if (callsite) return callsite;
+  }
+  const fallback = frames.find((frame) => !frame.includes("captureQueryTraceCallsite"));
+  return fallback ? parseQueryTraceCallsiteFrame(fallback) : null;
+}
+function defaultQueryTraceLogger(event) {
+  const target = event.table ?? event.functionName ?? "gateway";
+  const outcomeState = event.outcome?.error ? "error" : "ok";
+  const banner = `[athena-js][trace] ${event.operation.toUpperCase()} ${event.endpoint} ${target} ${event.durationMs}ms ${outcomeState}`;
+  console.info(banner, event);
+}
+function captureTraceCallsite(tracer) {
+  return tracer?.captureCallsite() ?? null;
+}
+function createTraceCallsiteStore(tracer, initialCallsite) {
+  let storedCallsite = initialCallsite ?? void 0;
+  return {
+    resolve(callsite) {
+      if (callsite) {
+        storedCallsite = callsite;
+        return callsite;
+      }
+      if (storedCallsite !== void 0) {
+        return storedCallsite;
+      }
+      const capturedCallsite = captureTraceCallsite(tracer);
+      if (capturedCallsite) {
+        storedCallsite = capturedCallsite;
+      }
+      return capturedCallsite;
+    }
+  };
+}
+function createQueryTracer(experimental) {
+  const traceOption = experimental?.traceQueries;
+  if (!traceOption) {
+    return void 0;
+  }
+  const logger = typeof traceOption === "object" && traceOption.logger ? traceOption.logger : defaultQueryTraceLogger;
+  const emit = (event) => {
+    try {
+      logger(event);
+    } catch (error) {
+      console.warn("[athena-js][trace] logger failed", error);
+    }
+  };
+  return {
+    captureCallsite: captureQueryTraceCallsite,
+    publishSuccess(context, result, durationMs, callsite) {
+      emit({
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        durationMs,
+        operation: context.operation,
+        endpoint: context.endpoint,
+        table: context.table,
+        functionName: context.functionName,
+        sql: context.sql,
+        payload: context.payload,
+        options: context.options,
+        callsite,
+        outcome: {
+          status: result.status,
+          error: result.error,
+          errorDetails: result.errorDetails ?? null,
+          count: result.count ?? null,
+          data: result.data,
+          raw: result.raw
+        }
+      });
+    },
+    publishFailure(context, error, durationMs, callsite) {
+      emit({
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        durationMs,
+        operation: context.operation,
+        endpoint: context.endpoint,
+        table: context.table,
+        functionName: context.functionName,
+        sql: context.sql,
+        payload: context.payload,
+        options: context.options,
+        callsite,
+        thrownError: error
+      });
+    }
+  };
+}
+async function executeWithQueryTrace(tracer, context, runner, callsiteOverride) {
+  if (!tracer) {
+    return runner();
+  }
+  const callsite = callsiteOverride ?? tracer.captureCallsite();
+  const startedAt = Date.now();
+  try {
+    const result = await runner();
+    tracer.publishSuccess(context, result, Date.now() - startedAt, callsite);
+    return result;
+  } catch (error) {
+    tracer.publishFailure(context, error, Date.now() - startedAt, callsite);
+    throw error;
+  }
+}
 function toSingleResult(response) {
   const payload = response.data;
   const singleData = Array.isArray(payload) ? payload.length ? payload[0] : null : payload ?? null;
@@ -2831,15 +4164,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;
   };
@@ -2847,7 +4181,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);
@@ -2855,7 +4189,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);
@@ -2878,21 +4212,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)) {
@@ -2915,25 +4240,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;
@@ -3011,6 +4403,226 @@ 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 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) {
@@ -3122,7 +4734,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);
       }
@@ -3185,14 +4797,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,
@@ -3206,14 +4819,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;
   };
@@ -3223,10 +4852,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) {
@@ -3261,7 +4890,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: []
   };
@@ -3293,70 +4922,103 @@ 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 hasTypedEqualityComparison = conditions?.some(
-      (condition) => condition.operator === "eq" && (condition.value_cast !== void 0 || condition.column_cast !== void 0)
-    ) ?? false;
-    if (hasTypedEqualityComparison && !options?.head && !options?.count && conditions) {
-      const query = buildTypedSelectQuery({
-        tableName: resolvedTableName,
-        columns,
-        conditions,
-        limit: state.limit,
-        offset: state.offset,
-        currentPage: state.currentPage,
-        pageSize: state.pageSize,
-        order: state.order
-      });
-      if (query) {
-        const queryResponse = await client.queryGateway({ query }, options);
-        return formatGatewayResult(queryResponse, { table: resolvedTableName, operation: "select" });
-      }
-    }
-    const payload = {
-      table_name: resolvedTableName,
+    const plan = createSelectTransportPlan({
+      tableName: 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,
-      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" });
+      state: executionState,
+      options,
+      buildTypedSelectQuery
+    });
+    if (plan.kind === "query") {
+      return executeWithQueryTrace(
+        tracer,
+        {
+          operation: "select",
+          endpoint: "/gateway/query",
+          table: resolvedTableName,
+          sql: plan.query,
+          payload: plan.payload,
+          options
+        },
+        async () => {
+          const queryResponse = await client.queryGateway(plan.payload, options);
+          return formatGatewayResult(queryResponse, { table: resolvedTableName, operation: "select" });
+        },
+        callsite
+      );
+    }
+    const sql = buildDebugSelectQuery({
+      tableName: resolvedTableName,
+      ...plan.debug
+    });
+    return executeWithQueryTrace(
+      tracer,
+      {
+        operation: "select",
+        endpoint: "/gateway/fetch",
+        table: resolvedTableName,
+        sql,
+        payload: plan.payload,
+        options
+      },
+      async () => {
+        const response = await client.fetchGateway(plan.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;
@@ -3373,11 +5035,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) && !selectShapeUsesRelationSchema(options.select)) {
+        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 = {
@@ -3390,12 +5116,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 = {
@@ -3408,14 +5149,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 = {
@@ -3430,12 +5187,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 = {
@@ -3450,13 +5222,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);
@@ -3471,10 +5259,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);
@@ -3486,7 +5289,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 = {
@@ -3499,13 +5303,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) {
@@ -3514,14 +5338,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) {
@@ -3532,9 +5371,16 @@ function createClientFromConfig(config) {
     backend: config.backend,
     headers: config.headers
   });
-  const formatGatewayResult = createResultFormatter(config.experimental);
+  const formatGatewayResult = createResultFormatter();
+  const queryTracer = createQueryTracer(config.experimental);
   const auth = createAuthClient(config.auth);
-  const from = (table) => createTableBuilder(table, gateway, formatGatewayResult);
+  const from = (table, options) => createTableBuilder(
+    resolveTableNameForCall(table, options?.schema),
+    gateway,
+    formatGatewayResult,
+    queryTracer,
+    config.experimental
+  );
   const rpc = (fn, args, options) => {
     const normalizedFn = fn.trim();
     if (!normalizedFn) {
@@ -3545,16 +5391,19 @@ 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,
     db,
     rpc,
     query,
+    verifyConnection: gateway.verifyConnection,
     auth: auth.auth
   };
 }
@@ -4018,7 +5867,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 ?? [];
   }
@@ -4115,10 +5964,24 @@ function resolveGeneratorProvider(providerConfig, experimentalFlags) {
 }
 
 // src/generator/pipeline.ts
+function canOverwriteArtifact(file) {
+  return file.kind === "model" || file.kind === "schema";
+}
+async function fileExists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
 async function writeArtifacts(files, cwd) {
   const writtenFiles = [];
   for (const file of files) {
     const absolutePath = resolve(cwd, file.path);
+    if (!canOverwriteArtifact(file) && await fileExists(absolutePath)) {
+      continue;
+    }
     await mkdir(dirname(absolutePath), { recursive: true });
     await writeFile(absolutePath, file.content, "utf8");
     writtenFiles.push(file.path);