@xylex-group/athena 2.6.0 → 2.8.0

package/dist/browser.cjs

@@ -1,5 +1,7 @@
 'use strict';
 
+var zod = require('zod');
+
 // src/gateway/errors.ts
 var AthenaGatewayError = class _AthenaGatewayError extends Error {
   code;
@@ -668,9 +670,16 @@ var getSessionCookie = (request, config) => {
   const { cookieName = "session_token", cookiePrefix = "athena-auth" } = config || {};
   const parsedCookie = parseCookies(cookies);
   const getCookie = (name) => parsedCookie.get(name) || parsedCookie.get(`${SECURE_COOKIE_PREFIX}${name}`);
-  const sessionToken = getCookie(`${cookiePrefix}.${cookieName}`) || getCookie(`${cookiePrefix}-${cookieName}`);
-  if (sessionToken) {
-    return sessionToken;
+  const candidateCookieNames = Array.from(/* @__PURE__ */ new Set([
+    cookieName,
+    cookieName.replace(/_/g, "-"),
+    cookieName.replace(/-/g, "_")
+  ])).filter(Boolean);
+  for (const candidateName of candidateCookieNames) {
+    const sessionToken = getCookie(`${cookiePrefix}.${candidateName}`) || getCookie(`${cookiePrefix}-${candidateName}`);
+    if (sessionToken) {
+      return sessionToken;
+    }
   }
   return null;
 };
@@ -793,7 +802,7 @@ var getCookieCache = async (request, config) => {
 
 // package.json
 var package_default = {
-  version: "2.6.0"
+  version: "2.8.0"
 };
 
 // src/sdk-version.ts
@@ -3110,7 +3119,7 @@ function normalizeAthenaError(resultOrError, context) {
     const details = resultOrError.errorDetails;
     const message2 = messageFromUnknownError(resultOrError.error) ?? details?.message ?? `Athena ${context?.operation ?? operationFromDetails(details) ?? "request"} failed`;
     const operation = context?.operation ?? operationFromDetails(details);
-    const table = context?.table ?? extractTable(message2);
+    const table2 = context?.table ?? extractTable(message2);
     const constraint = extractConstraint(message2);
     const gatewayCode = details?.code ?? gatewayCodeFromUnknownError(resultOrError.error);
     const kind2 = classifyKind(resultOrError.status, gatewayCode, message2);
@@ -3123,7 +3132,7 @@ function normalizeAthenaError(resultOrError, context) {
       retryable: isRetryable(kind2, resultOrError.status),
       status: resultOrError.status,
       constraint,
-      table,
+      table: table2,
       operation,
       message: message2,
       raw: resultOrError.raw
@@ -3132,7 +3141,7 @@ function normalizeAthenaError(resultOrError, context) {
   if (isAthenaGatewayError(resultOrError)) {
     const details = resultOrError.toDetails();
     const operation = context?.operation ?? operationFromDetails(details);
-    const table = context?.table ?? extractTable(resultOrError.message);
+    const table2 = context?.table ?? extractTable(resultOrError.message);
     const constraint = extractConstraint(resultOrError.message);
     const kind2 = classifyKind(resultOrError.status, resultOrError.code, resultOrError.message);
     const code = toAthenaErrorCode(kind2, resultOrError.status, resultOrError.code);
@@ -3144,7 +3153,7 @@ function normalizeAthenaError(resultOrError, context) {
       retryable: isRetryable(kind2, resultOrError.status),
       status: resultOrError.status,
       constraint,
-      table,
+      table: table2,
       operation,
       message: resultOrError.message,
       raw: resultOrError
@@ -3340,23 +3349,24 @@ async function withRetry(config, fn) {
 // src/db/module.ts
 function createDbModule(input) {
   const db = {
-    from(table, options) {
-      return input.from(table, options);
-    },
-    select(table, columns, options) {
-      return input.from(table).select(columns, options);
+    from: input.from,
+    select(table2, first, second) {
+      if (first && typeof first === "object" && !Array.isArray(first)) {
+        return input.from(table2).select(void 0, first);
+      }
+      return input.from(table2).select(first, second);
     },
-    insert(table, values, options) {
-      return Array.isArray(values) ? input.from(table).insert(values, options) : input.from(table).insert(values, options);
+    insert(table2, values, options) {
+      return Array.isArray(values) ? input.from(table2).insert(values, options) : input.from(table2).insert(values, options);
     },
-    upsert(table, values, options) {
-      return Array.isArray(values) ? input.from(table).upsert(values, options) : input.from(table).upsert(values, options);
+    upsert(table2, values, options) {
+      return Array.isArray(values) ? input.from(table2).upsert(values, options) : input.from(table2).upsert(values, options);
     },
-    update(table, values, options) {
-      return input.from(table).update(values, options);
+    update(table2, values, options) {
+      return input.from(table2).update(values, options);
     },
-    delete(table, options) {
-      return input.from(table).delete(options);
+    delete(table2, options) {
+      return input.from(table2).delete(options);
     },
     rpc(fn, args, options) {
       return input.rpc(fn, args, options);
@@ -3368,6 +3378,344 @@ function createDbModule(input) {
   return db;
 }
 
+// src/storage/file.ts
+function createStorageFileModule(base, config = {}) {
+  const upload = async (input, options) => {
+    const sources = normalizeUploadSources(input);
+    validateUploadConstraints(sources, input);
+    const uploadRequests = sources.map((source, index) => {
+      const storageKey = resolveUploadStorageKey(input, source, index, options, config);
+      return {
+        source,
+        uploadRequest: {
+          s3_id: input.s3_id,
+          bucket: input.bucket,
+          storage_key: storageKey,
+          name: input.name ?? source.fileName,
+          original_name: input.original_name ?? source.fileName,
+          resource_id: input.resource_id ?? input.resourceId,
+          mime_type: input.mime_type ?? source.contentType,
+          content_type: input.content_type ?? source.contentType,
+          size_bytes: source.sizeBytes,
+          public: input.public,
+          metadata: input.metadata
+        }
+      };
+    });
+    input.onProgress?.(createProgressSnapshot("preparing", sources, 0, 0, 0));
+    const uploadUrls = uploadRequests.length === 1 ? [await base.createStorageUploadUrl(uploadRequests[0].uploadRequest, options)] : (await base.createStorageUploadUrls({ files: uploadRequests.map((request) => request.uploadRequest) }, options)).files;
+    const aggregateLoaded = new Array(uploadRequests.length).fill(0);
+    const uploaded = [];
+    for (let index = 0; index < uploadRequests.length; index += 1) {
+      const request = uploadRequests[index];
+      const uploadUrl = uploadUrls[index];
+      const response = await putUploadBody(uploadUrl.upload.url, request.source, input, options, (progress) => {
+        aggregateLoaded[index] = progress.loaded;
+        input.onProgress?.(createProgressSnapshot("uploading", sources, index, progress.loaded, sum(aggregateLoaded)));
+      });
+      uploaded.push({
+        file: uploadUrl.file,
+        upload: uploadUrl.upload,
+        source: request.source.source,
+        fileName: request.source.fileName,
+        storage_key: request.uploadRequest.storage_key,
+        response
+      });
+      aggregateLoaded[index] = request.source.sizeBytes;
+      input.onProgress?.(createProgressSnapshot("complete", sources, index, request.source.sizeBytes, sum(aggregateLoaded)));
+    }
+    return {
+      files: uploaded,
+      count: uploaded.length
+    };
+  };
+  const download = ((input, queryOrOptions, maybeOptions) => {
+    const { fileIds, query, options } = normalizeDownloadArgs(input, queryOrOptions, maybeOptions);
+    const downloads = fileIds.map((fileId) => base.getStorageFileProxy(fileId, query, options));
+    return Array.isArray(input) || isRecord5(input) && Array.isArray(input.fileIds) ? Promise.all(downloads) : downloads[0];
+  });
+  const deleteFile = ((input, options) => {
+    if (Array.isArray(input)) {
+      return Promise.all(input.map((fileId) => base.deleteStorageFile(fileId, options)));
+    }
+    return base.deleteStorageFile(input, options);
+  });
+  return {
+    upload,
+    download,
+    list(input, options) {
+      const prefix = resolveStoragePath(input.prefix ?? "", input, options, config);
+      return base.listStorageFiles(
+        {
+          s3_id: input.s3_id,
+          prefix
+        },
+        options
+      );
+    },
+    delete: deleteFile
+  };
+}
+function resolveStoragePath(path, input, options, config = {}) {
+  const context = createPathContext(input, options, config);
+  const prefixPath = input.prefixPath ?? config.prefixPath;
+  const prefix = typeof prefixPath === "function" ? prefixPath(context) : prefixPath;
+  return joinStoragePath(renderStorageTemplate(prefix ?? "", context), renderStorageTemplate(path, context));
+}
+function resolveUploadStorageKey(input, source, index, options, config) {
+  const explicitKey = input.storage_key ?? input.storageKey;
+  const keyTemplate = input.storageKeyTemplate;
+  const fallbackName = source.fileName;
+  const context = createPathContext(input, options, config);
+  const key = keyTemplate ? renderStorageTemplate(keyTemplate, {
+    ...context,
+    vars: {
+      ...context.vars,
+      index,
+      fileName: source.fileName,
+      name: source.fileName
+    }
+  }) : explicitKey ?? fallbackName;
+  return resolveStoragePath(key, input, options, config);
+}
+function normalizeUploadSources(input) {
+  const files = toArray(input.files);
+  if (files.length === 0) {
+    throw new Error("athena.storage.file.upload requires at least one file");
+  }
+  return files.map((source, index) => {
+    const fileName = input.fileName ?? sourceName(source) ?? `file-${index + 1}`;
+    const sizeBytes = sourceSize(source);
+    const contentType = input.content_type ?? input.mime_type ?? sourceContentType(source);
+    return {
+      source,
+      fileName,
+      sizeBytes,
+      contentType
+    };
+  });
+}
+function validateUploadConstraints(sources, input) {
+  const maxFiles = input.maxFiles ?? 1;
+  if (sources.length > maxFiles) {
+    throw new Error(`athena.storage.file.upload accepts at most ${maxFiles} file${maxFiles === 1 ? "" : "s"} for this call`);
+  }
+  const maxFileSizeBytes = input.maxFileSizeBytes ?? (input.maxFileSizeMb === void 0 ? void 0 : Math.floor(input.maxFileSizeMb * 1024 * 1024));
+  if (maxFileSizeBytes !== void 0) {
+    const tooLarge = sources.find((source) => source.sizeBytes > maxFileSizeBytes);
+    if (tooLarge) {
+      throw new Error(`athena.storage.file.upload rejected ${tooLarge.fileName}: file exceeds ${maxFileSizeBytes} bytes`);
+    }
+  }
+  const allowedExtensions = normalizeExtensions(input.allowedExtensions ?? input.extensions);
+  if (allowedExtensions.size > 0) {
+    const invalid = sources.find((source) => !allowedExtensions.has(fileExtension(source.fileName)));
+    if (invalid) {
+      throw new Error(`athena.storage.file.upload rejected ${invalid.fileName}: extension is not allowed`);
+    }
+  }
+}
+async function putUploadBody(url, source, input, options, onProgress) {
+  const headers = new Headers(input.uploadHeaders);
+  if (source.contentType && !headers.has("Content-Type")) {
+    headers.set("Content-Type", source.contentType);
+  }
+  if (typeof XMLHttpRequest !== "undefined") {
+    return putUploadBodyWithXhr(url, source, headers, options, onProgress);
+  }
+  onProgress({ loaded: 0 });
+  const response = await fetch(url, {
+    method: "PUT",
+    headers,
+    body: source.source,
+    signal: options?.signal
+  });
+  if (!response.ok) {
+    throw new Error(`athena.storage.file.upload failed with status ${response.status}`);
+  }
+  onProgress({ loaded: source.sizeBytes });
+  return response;
+}
+function putUploadBodyWithXhr(url, source, headers, options, onProgress) {
+  const Xhr = XMLHttpRequest;
+  if (Xhr === void 0) {
+    return Promise.reject(new Error("athena.storage.file.upload requires XMLHttpRequest in this runtime"));
+  }
+  return new Promise((resolve, reject) => {
+    const xhr = new Xhr();
+    const abort = () => xhr.abort();
+    xhr.open("PUT", url);
+    headers.forEach((value, key) => xhr.setRequestHeader(key, value));
+    xhr.upload.onprogress = (event) => {
+      onProgress({ loaded: event.loaded });
+    };
+    xhr.onload = () => {
+      if (options?.signal) {
+        options.signal.removeEventListener("abort", abort);
+      }
+      if (xhr.status < 200 || xhr.status >= 300) {
+        reject(new Error(`athena.storage.file.upload failed with status ${xhr.status}`));
+        return;
+      }
+      onProgress({ loaded: source.sizeBytes });
+      resolve(new Response(xhr.response, {
+        status: xhr.status,
+        statusText: xhr.statusText,
+        headers: parseXhrHeaders(xhr.getAllResponseHeaders())
+      }));
+    };
+    xhr.onerror = () => {
+      if (options?.signal) {
+        options.signal.removeEventListener("abort", abort);
+      }
+      reject(new Error("athena.storage.file.upload failed with a network error"));
+    };
+    xhr.onabort = () => {
+      if (options?.signal) {
+        options.signal.removeEventListener("abort", abort);
+      }
+      reject(new DOMException("Upload aborted", "AbortError"));
+    };
+    if (options?.signal) {
+      if (options.signal.aborted) {
+        abort();
+        return;
+      }
+      options.signal.addEventListener("abort", abort, { once: true });
+    }
+    xhr.send(source.source);
+  });
+}
+function normalizeDownloadArgs(input, queryOrOptions, maybeOptions) {
+  if (typeof input === "string") {
+    return { fileIds: [input], query: queryOrOptions, options: maybeOptions };
+  }
+  if (Array.isArray(input)) {
+    return { fileIds: [...input], query: queryOrOptions, options: maybeOptions };
+  }
+  const downloadInput = input;
+  const { fileId, fileIds, ...query } = downloadInput;
+  return {
+    fileIds: fileIds ? [...fileIds] : fileId ? [fileId] : [],
+    query,
+    options: queryOrOptions
+  };
+}
+function createPathContext(input, options, config) {
+  const organizationId = input.organizationId ?? input.organization_id ?? options?.organizationId ?? void 0;
+  const userId = input.userId ?? input.user_id ?? options?.userId ?? void 0;
+  const resourceId = input.resourceId ?? input.resource_id ?? void 0;
+  const vars = {
+    ...config.vars ?? {},
+    ...input.vars ?? {}
+  };
+  if (organizationId !== void 0) {
+    vars.organizationId = organizationId;
+    vars.organization_id = organizationId;
+  }
+  if (userId !== void 0) {
+    vars.userId = userId;
+    vars.user_id = userId;
+  }
+  if (resourceId !== void 0) {
+    vars.resourceId = resourceId;
+    vars.resource_id = resourceId;
+  }
+  return {
+    vars,
+    env: {
+      ...readProcessEnv(),
+      ...config.env ?? {},
+      ...input.env ?? {}
+    },
+    organizationId,
+    organization_id: organizationId,
+    userId,
+    user_id: userId,
+    resourceId,
+    resource_id: resourceId
+  };
+}
+function renderStorageTemplate(template, context) {
+  return template.replace(/\$\{([^}]+)\}|\{([^}]+)\}/g, (_match, shellToken, braceToken) => {
+    const token = (shellToken ?? braceToken ?? "").trim();
+    if (!token) return "";
+    const value = resolveTemplateToken(token, context);
+    return value === void 0 || value === null ? "" : String(value);
+  });
+}
+function resolveTemplateToken(token, context) {
+  if (token.startsWith("env.")) {
+    return context.env[token.slice(4)];
+  }
+  if (token in context.vars) {
+    return context.vars[token];
+  }
+  return context.env[token];
+}
+function joinStoragePath(...parts) {
+  return parts.map((part) => part.trim().replace(/^\/+|\/+$/g, "")).filter(Boolean).join("/");
+}
+function toArray(files) {
+  if (isUploadSource(files)) return [files];
+  return Array.from(files);
+}
+function isUploadSource(value) {
+  return value instanceof Blob || value instanceof ArrayBuffer || value instanceof Uint8Array;
+}
+function sourceName(source) {
+  return isRecord5(source) && typeof source.name === "string" && source.name.trim() ? source.name.trim() : void 0;
+}
+function sourceSize(source) {
+  if (source instanceof Blob) return source.size;
+  return source.byteLength;
+}
+function sourceContentType(source) {
+  return source instanceof Blob && source.type.trim() ? source.type.trim() : void 0;
+}
+function normalizeExtensions(extensions) {
+  return new Set((extensions ?? []).map((extension) => extension.replace(/^\./, "").toLowerCase()).filter(Boolean));
+}
+function fileExtension(fileName) {
+  const lastDot = fileName.lastIndexOf(".");
+  return lastDot === -1 ? "" : fileName.slice(lastDot + 1).toLowerCase();
+}
+function createProgressSnapshot(phase, sources, fileIndex, loaded, aggregateLoaded) {
+  const total = sources[fileIndex]?.sizeBytes ?? 0;
+  const aggregateTotal = sources.reduce((totalBytes, source) => totalBytes + source.sizeBytes, 0);
+  return {
+    phase,
+    fileIndex,
+    fileCount: sources.length,
+    fileName: sources[fileIndex]?.fileName ?? "",
+    loaded,
+    total,
+    percent: total > 0 ? Math.round(loaded / total * 100) : 100,
+    aggregateLoaded,
+    aggregateTotal,
+    aggregatePercent: aggregateTotal > 0 ? Math.round(aggregateLoaded / aggregateTotal * 100) : 100
+  };
+}
+function sum(values) {
+  return values.reduce((total, value) => total + value, 0);
+}
+function parseXhrHeaders(raw) {
+  const headers = new Headers();
+  for (const line of raw.trim().split(/[\r\n]+/)) {
+    const index = line.indexOf(":");
+    if (index === -1) continue;
+    headers.set(line.slice(0, index).trim(), line.slice(index + 1).trim());
+  }
+  return headers;
+}
+function readProcessEnv() {
+  const processLike = globalThis.process;
+  return processLike?.env ?? {};
+}
+function isRecord5(value) {
+  return Boolean(value) && typeof value === "object";
+}
+
 // src/storage/module.ts
 var storageSdkManifest = {
   namespace: "storage",
@@ -3576,7 +3924,7 @@ var AthenaStorageError = class extends Error {
     };
   }
 };
-function isRecord5(value) {
+function isRecord6(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function causeToString(cause) {
@@ -3687,11 +4035,20 @@ function appendQuery(path, query) {
 function storagePath(path) {
   return path;
 }
+function resolveStorageEndpointPath(endpoint, runtimeOptions) {
+  if (!runtimeOptions?.stripBasePath) {
+    return endpoint;
+  }
+  const [pathname, queryText] = String(endpoint).split("?", 2);
+  const trimmedPathname = pathname.startsWith("/storage/") ? pathname.slice("/storage".length) : pathname === "/storage" ? "/" : pathname;
+  const resolvedPath = trimmedPathname.startsWith("/") ? trimmedPathname : `/${trimmedPathname}`;
+  return storagePath(queryText ? `${resolvedPath}?${queryText}` : resolvedPath);
+}
 function withPathParam(path, name, value) {
   return path.replace(`{${name}}`, encodeURIComponent(value));
 }
 function resolveErrorMessage3(payload, fallback) {
-  if (isRecord5(payload)) {
+  if (isRecord6(payload)) {
     const message = payload.message ?? payload.error ?? payload.details;
     if (typeof message === "string" && message.trim()) {
       return message.trim();
@@ -3703,12 +4060,12 @@ function resolveErrorMessage3(payload, fallback) {
   return fallback;
 }
 function resolveErrorHint2(payload) {
-  if (!isRecord5(payload)) return void 0;
+  if (!isRecord6(payload)) return void 0;
   const hint = payload.hint ?? payload.suggestion;
   return typeof hint === "string" && hint.trim() ? hint.trim() : void 0;
 }
 function resolveErrorCause(payload) {
-  if (!isRecord5(payload)) return void 0;
+  if (!isRecord6(payload)) return void 0;
   const cause = payload.cause ?? payload.reason;
   return typeof cause === "string" && cause.trim() ? cause.trim() : void 0;
 }
@@ -3725,8 +4082,8 @@ async function callStorageEndpoint(gateway, endpoint, method, envelope, payload,
   let url;
   let headers;
   try {
-    const baseUrl = options?.baseUrl ? normalizeAthenaGatewayBaseUrl(options.baseUrl) : gateway.baseUrl;
-    url = buildAthenaGatewayUrl(baseUrl, endpoint);
+    const baseUrl = options?.baseUrl ? normalizeAthenaGatewayBaseUrl(options.baseUrl) : runtimeOptions?.baseUrl ? normalizeAthenaGatewayBaseUrl(runtimeOptions.baseUrl) : gateway.baseUrl;
+    url = buildAthenaGatewayUrl(baseUrl, resolveStorageEndpointPath(endpoint, runtimeOptions));
     headers = gateway.buildHeaders(options);
   } catch (error) {
     return rejectStorageError(
@@ -3827,7 +4184,7 @@ async function callStorageEndpoint(gateway, endpoint, method, envelope, payload,
     );
   }
   if (envelope === "athena") {
-    if (!isRecord5(parsedBody.parsed) || !("data" in parsedBody.parsed)) {
+    if (!isRecord6(parsedBody.parsed) || !("data" in parsedBody.parsed)) {
       return rejectStorageError(
         {
           code: "INVALID_ATHENA_ENVELOPE",
@@ -3850,8 +4207,8 @@ async function callStorageBinaryEndpoint(gateway, endpoint, method, options, run
   let url;
   let headers;
   try {
-    const baseUrl = options?.baseUrl ? normalizeAthenaGatewayBaseUrl(options.baseUrl) : gateway.baseUrl;
-    url = buildAthenaGatewayUrl(baseUrl, endpoint);
+    const baseUrl = options?.baseUrl ? normalizeAthenaGatewayBaseUrl(options.baseUrl) : runtimeOptions?.baseUrl ? normalizeAthenaGatewayBaseUrl(runtimeOptions.baseUrl) : gateway.baseUrl;
+    url = buildAthenaGatewayUrl(baseUrl, resolveStorageEndpointPath(endpoint, runtimeOptions));
     headers = gateway.buildHeaders(options);
   } catch (error) {
     return rejectStorageError(
@@ -3935,129 +4292,678 @@ async function callStorageBinaryEndpoint(gateway, endpoint, method, options, run
     runtimeOptions
   );
 }
-function createStorageModule(gateway, runtimeOptions) {
+function isBlobBody(body) {
+  return typeof Blob !== "undefined" && body instanceof Blob;
+}
+function isReadableStreamBody(body) {
+  return typeof ReadableStream !== "undefined" && body instanceof ReadableStream;
+}
+async function putPresignedUploadBody(uploadUrl, uploadHeaders, body, options) {
+  const headers = new Headers(uploadHeaders);
+  Object.entries(options?.headers ?? {}).forEach(([key, value]) => headers.set(key, value));
+  if (!headers.has("Content-Type") && isBlobBody(body) && body.type) {
+    headers.set("Content-Type", body.type);
+  }
+  const init = {
+    method: "PUT",
+    headers,
+    body,
+    signal: options?.signal
+  };
+  if (isReadableStreamBody(body)) {
+    init.duplex = "half";
+  }
+  return fetch(uploadUrl, init);
+}
+function attachManagedUpload(upload) {
+  const headers = {};
+  return {
+    ...upload,
+    method: "PUT",
+    headers,
+    expiresAt: upload.expires_at,
+    put(body, options) {
+      return putPresignedUploadBody(upload.url, headers, body, options);
+    }
+  };
+}
+function attachUploadHelper(response) {
+  return {
+    ...response,
+    upload: attachManagedUpload(response.upload)
+  };
+}
+function attachUploadHelpers(response) {
+  return {
+    files: response.files.map(attachUploadHelper)
+  };
+}
+function normalizeUploadUrlRequest(input) {
+  const s3_id = input.s3_id ?? input.s3Id;
+  const storage_key = input.storage_key ?? input.storageKey;
+  if (!s3_id?.trim()) {
+    throw new Error("athena.storage.file.upload requires s3_id or s3Id");
+  }
+  if (!storage_key?.trim()) {
+    throw new Error("athena.storage.file.upload requires storage_key or storageKey");
+  }
+  const fileName = input.fileName?.trim();
+  const originalName = input.originalName?.trim();
   return {
+    s3_id,
+    bucket: input.bucket,
+    storage_key,
+    name: input.name ?? fileName,
+    original_name: input.original_name ?? originalName ?? fileName,
+    resource_id: input.resource_id ?? input.resourceId,
+    mime_type: input.mime_type ?? input.mimeType,
+    content_type: input.content_type ?? input.contentType,
+    size_bytes: input.size_bytes ?? input.sizeBytes,
+    file_id: input.file_id ?? input.fileId,
+    public: input.public,
+    visibility: input.visibility,
+    metadata: input.metadata
+  };
+}
+async function callStorageUploadBinaryEndpoint(gateway, endpoint, body, options, runtimeOptions) {
+  let url;
+  let headers;
+  try {
+    const baseUrl = options?.baseUrl ? normalizeAthenaGatewayBaseUrl(options.baseUrl) : runtimeOptions?.baseUrl ? normalizeAthenaGatewayBaseUrl(runtimeOptions.baseUrl) : gateway.baseUrl;
+    url = buildAthenaGatewayUrl(baseUrl, resolveStorageEndpointPath(endpoint, runtimeOptions));
+    headers = gateway.buildHeaders(options);
+  } catch (error) {
+    return rejectStorageError(
+      {
+        code: storageCodeFromUnknown(error),
+        message: error instanceof Error ? error.message : `Athena storage PUT ${endpoint} failed before sending the request`,
+        status: isAthenaGatewayError(error) ? error.status : 0,
+        endpoint,
+        method: "PUT",
+        raw: error,
+        requestId: isAthenaGatewayError(error) ? error.requestId : void 0,
+        hint: isAthenaGatewayError(error) ? error.hint : void 0,
+        cause: error
+      },
+      options,
+      runtimeOptions
+    );
+  }
+  delete headers["Content-Type"];
+  delete headers["content-type"];
+  if (isBlobBody(body) && body.type) {
+    headers["Content-Type"] = body.type;
+  }
+  const requestInit = {
+    method: "PUT",
+    headers,
+    body,
+    signal: options?.signal
+  };
+  if (isReadableStreamBody(body)) {
+    requestInit.duplex = "half";
+  }
+  let response;
+  try {
+    response = await fetch(url, requestInit);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return rejectStorageError(
+      {
+        code: "NETWORK_ERROR",
+        message: `Network error while calling Athena storage PUT ${endpoint}: ${message}`,
+        status: 0,
+        endpoint,
+        method: "PUT",
+        cause: error
+      },
+      options,
+      runtimeOptions
+    );
+  }
+  let rawText;
+  try {
+    rawText = await response.text();
+  } catch (error) {
+    return rejectStorageError(
+      {
+        code: "NETWORK_ERROR",
+        message: `Athena storage PUT ${endpoint} response body could not be read`,
+        status: response.status,
+        endpoint,
+        method: "PUT",
+        requestId: headerValue(response.headers, ["x-athena-request-id", "x-request-id", "request-id"]),
+        cause: error
+      },
+      options,
+      runtimeOptions
+    );
+  }
+  const parsedBody = parseResponseBody3(rawText ?? "", response.headers.get("content-type"));
+  const requestId = headerValue(response.headers, ["x-athena-request-id", "x-request-id", "request-id"]);
+  if (parsedBody.parseFailed) {
+    return rejectStorageError(
+      {
+        code: "INVALID_JSON",
+        message: `Athena storage PUT ${endpoint} returned malformed JSON`,
+        status: response.status,
+        endpoint,
+        method: "PUT",
+        requestId,
+        raw: parsedBody.parsed
+      },
+      options,
+      runtimeOptions
+    );
+  }
+  if (!response.ok) {
+    return rejectStorageError(
+      {
+        code: "HTTP_ERROR",
+        message: resolveErrorMessage3(
+          parsedBody.parsed,
+          `Athena storage PUT ${endpoint} failed with status ${response.status}`
+        ),
+        status: response.status,
+        endpoint,
+        method: "PUT",
+        requestId,
+        hint: resolveErrorHint2(parsedBody.parsed),
+        cause: resolveErrorCause(parsedBody.parsed),
+        raw: parsedBody.parsed
+      },
+      options,
+      runtimeOptions
+    );
+  }
+  if (!isRecord6(parsedBody.parsed) || !("data" in parsedBody.parsed)) {
+    return rejectStorageError(
+      {
+        code: "INVALID_ATHENA_ENVELOPE",
+        message: `Athena storage PUT ${endpoint} returned an invalid Athena envelope`,
+        status: response.status,
+        endpoint,
+        method: "PUT",
+        requestId,
+        raw: parsedBody.parsed
+      },
+      options,
+      runtimeOptions
+    );
+  }
+  return parsedBody.parsed.data;
+}
+function createStorageModule(gateway, runtimeOptions) {
+  const resolvedRuntimeOptions = runtimeOptions;
+  const callRaw = (path, method, payload, options) => callStorageEndpoint(
+    gateway,
+    storagePath(path),
+    method,
+    "raw",
+    payload,
+    options,
+    resolvedRuntimeOptions
+  );
+  const callAthena2 = (path, method, payload, options) => callStorageEndpoint(
+    gateway,
+    storagePath(path),
+    method,
+    "athena",
+    payload,
+    options,
+    resolvedRuntimeOptions
+  );
+  const base = {
     listStorageCatalogs(options) {
-      return callStorageEndpoint(gateway, storagePath("/storage/catalogs"), "GET", "raw", void 0, options, runtimeOptions);
+      return callRaw("/storage/catalogs", "GET", void 0, options);
     },
     createStorageCatalog(input, options) {
-      return callStorageEndpoint(gateway, storagePath("/storage/catalogs"), "POST", "raw", input, options, runtimeOptions);
+      return callRaw("/storage/catalogs", "POST", input, options);
     },
     updateStorageCatalog(id, input, options) {
-      return callStorageEndpoint(
-        gateway,
-        storagePath(withPathParam("/storage/catalogs/{id}", "id", id)),
-        "PATCH",
-        "raw",
-        input,
-        options,
-        runtimeOptions
-      );
+      return callRaw(withPathParam("/storage/catalogs/{id}", "id", id), "PATCH", input, options);
     },
     deleteStorageCatalog(id, options) {
-      return callStorageEndpoint(
-        gateway,
-        storagePath(withPathParam("/storage/catalogs/{id}", "id", id)),
-        "DELETE",
-        "raw",
-        void 0,
-        options,
-        runtimeOptions
-      );
+      return callRaw(withPathParam("/storage/catalogs/{id}", "id", id), "DELETE", void 0, options);
     },
     listStorageCredentials(options) {
-      return callStorageEndpoint(gateway, storagePath("/storage/credentials"), "GET", "raw", void 0, options, runtimeOptions);
+      return callRaw("/storage/credentials", "GET", void 0, options);
     },
     createStorageUploadUrl(input, options) {
-      return callStorageEndpoint(
-        gateway,
-        storagePath("/storage/files/upload-url"),
-        "POST",
-        "athena",
-        input,
-        options,
-        runtimeOptions
-      );
+      return callAthena2("/storage/files/upload-url", "POST", input, options);
     },
     createStorageUploadUrls(input, options) {
-      return callStorageEndpoint(
-        gateway,
-        storagePath("/storage/files/upload-urls"),
-        "POST",
-        "athena",
-        input,
-        options,
-        runtimeOptions
-      );
+      return callAthena2("/storage/files/upload-urls", "POST", input, options);
     },
     listStorageFiles(input, options) {
-      return callStorageEndpoint(gateway, storagePath("/storage/files/list"), "POST", "athena", input, options, runtimeOptions);
+      return callAthena2("/storage/files/list", "POST", input, options);
     },
     getStorageFile(fileId, options) {
-      return callStorageEndpoint(
-        gateway,
-        storagePath(withPathParam("/storage/files/{file_id}", "file_id", fileId)),
-        "GET",
-        "athena",
-        void 0,
-        options,
-        runtimeOptions
-      );
+      return callAthena2(withPathParam("/storage/files/{file_id}", "file_id", fileId), "GET", void 0, options);
     },
     getStorageFileUrl(fileId, query, options) {
       const path = appendQuery(
         withPathParam("/storage/files/{file_id}/url", "file_id", fileId),
         query
       );
-      return callStorageEndpoint(gateway, storagePath(path), "GET", "athena", void 0, options, runtimeOptions);
+      return callAthena2(path, "GET", void 0, options);
     },
     getStorageFileProxy(fileId, query, options) {
       const path = appendQuery(
         withPathParam("/storage/files/{file_id}/proxy", "file_id", fileId),
         query
       );
-      return callStorageBinaryEndpoint(gateway, storagePath(path), "GET", options, runtimeOptions);
+      return callStorageBinaryEndpoint(gateway, storagePath(path), "GET", options, resolvedRuntimeOptions);
     },
     updateStorageFile(fileId, input, options) {
-      return callStorageEndpoint(
-        gateway,
-        storagePath(withPathParam("/storage/files/{file_id}", "file_id", fileId)),
-        "PATCH",
-        "athena",
-        input,
-        options,
-        runtimeOptions
-      );
+      return callAthena2(withPathParam("/storage/files/{file_id}", "file_id", fileId), "PATCH", input, options);
     },
     deleteStorageFile(fileId, options) {
-      return callStorageEndpoint(
-        gateway,
-        storagePath(withPathParam("/storage/files/{file_id}", "file_id", fileId)),
-        "DELETE",
-        "athena",
-        void 0,
-        options,
-        runtimeOptions
-      );
+      return callAthena2(withPathParam("/storage/files/{file_id}", "file_id", fileId), "DELETE", void 0, options);
     },
     setStorageFileVisibility(fileId, input, options) {
-      return callStorageEndpoint(
+      return callAthena2(withPathParam("/storage/files/{file_id}/visibility", "file_id", fileId), "PATCH", input, options);
+    },
+    deleteStorageFolder(input, options) {
+      return callAthena2("/storage/folders/delete", "POST", input, options);
+    },
+    moveStorageFolder(input, options) {
+      return callAthena2("/storage/folders/move", "POST", input, options);
+    }
+  };
+  const fileFacade = createStorageFileModule(base, runtimeOptions);
+  const fileUpload = ((input, options) => {
+    if (isRecord6(input) && "files" in input) {
+      return fileFacade.upload(input, options);
+    }
+    return base.createStorageUploadUrl(
+      normalizeUploadUrlRequest(input),
+      options
+    ).then(attachUploadHelper);
+  });
+  const fileDelete = ((input, options) => fileFacade.delete(input, options));
+  const file = {
+    ...fileFacade,
+    upload: fileUpload,
+    uploadMany(input, options) {
+      return base.createStorageUploadUrls(
+        { files: input.files.map(normalizeUploadUrlRequest) },
+        options
+      ).then(attachUploadHelpers);
+    },
+    confirmUpload(fileId, input, options) {
+      return callAthena2(withPathParam("/storage/files/{file_id}/confirm-upload", "file_id", fileId), "POST", input ?? {}, options);
+    },
+    uploadBinary(fileId, body, options) {
+      return callStorageUploadBinaryEndpoint(
         gateway,
-        storagePath(withPathParam("/storage/files/{file_id}/visibility", "file_id", fileId)),
-        "PATCH",
-        "athena",
-        input,
+        storagePath(withPathParam("/storage/files/{file_id}/upload", "file_id", fileId)),
+        body,
         options,
-        runtimeOptions
+        resolvedRuntimeOptions
       );
     },
-    deleteStorageFolder(input, options) {
-      return callStorageEndpoint(gateway, storagePath("/storage/folders/delete"), "POST", "athena", input, options, runtimeOptions);
+    search(input, options) {
+      return callAthena2("/storage/files/search", "POST", input, options);
     },
-    moveStorageFolder(input, options) {
-      return callStorageEndpoint(gateway, storagePath("/storage/folders/move"), "POST", "athena", input, options, runtimeOptions);
+    get(fileId, options) {
+      return base.getStorageFile(fileId, options);
+    },
+    update(fileId, input, options) {
+      return base.updateStorageFile(fileId, input, options);
+    },
+    delete: fileDelete,
+    deleteMany(input, options) {
+      return callAthena2("/storage/files/delete-many", "POST", input, options);
+    },
+    updateMany(input, options) {
+      return callAthena2("/storage/files/update-many", "POST", input, options);
+    },
+    restore(fileId, options) {
+      return callAthena2(withPathParam("/storage/files/{file_id}/restore", "file_id", fileId), "POST", {}, options);
+    },
+    purge(fileId, options) {
+      return callAthena2(withPathParam("/storage/files/{file_id}/purge", "file_id", fileId), "DELETE", void 0, options);
+    },
+    copy(fileId, input, options) {
+      return callAthena2(withPathParam("/storage/files/{file_id}/copy", "file_id", fileId), "POST", input, options);
+    },
+    url(fileId, query, options) {
+      return base.getStorageFileUrl(fileId, query, options);
+    },
+    publicUrl(fileId, options) {
+      return callAthena2(withPathParam("/storage/files/{file_id}/public-url", "file_id", fileId), "GET", void 0, options);
+    },
+    proxy(fileId, query, options) {
+      return base.getStorageFileProxy(fileId, query, options);
+    },
+    visibility: {
+      set(fileId, input, options) {
+        return base.setStorageFileVisibility(fileId, input, options);
+      },
+      setMany(input, options) {
+        return callAthena2("/storage/files/visibility-many", "POST", input, options);
+      }
+    }
+  };
+  const credentials = {
+    list(options) {
+      return base.listStorageCredentials(options);
+    }
+  };
+  const catalog = {
+    list(options) {
+      return base.listStorageCatalogs(options);
+    },
+    create(input, options) {
+      return base.createStorageCatalog(input, options);
+    },
+    update(id, input, options) {
+      return base.updateStorageCatalog(id, input, options);
+    },
+    delete(id, options) {
+      return base.deleteStorageCatalog(id, options);
+    }
+  };
+  const folder = {
+    list(input, options) {
+      return callAthena2("/storage/folders/list", "POST", input, options);
+    },
+    tree(input, options) {
+      return callAthena2("/storage/folders/tree", "POST", input, options);
+    },
+    delete(input, options) {
+      return base.deleteStorageFolder(input, options);
+    },
+    move(input, options) {
+      return base.moveStorageFolder(input, options);
+    }
+  };
+  const permission = {
+    list(input, options) {
+      return callAthena2("/storage/permissions/list", "POST", input, options);
+    },
+    grant(input, options) {
+      return callAthena2("/storage/permissions/grant", "POST", input, options);
+    },
+    revoke(input, options) {
+      return callAthena2("/storage/permissions/revoke", "POST", input, options);
+    },
+    check(input, options) {
+      return callAthena2("/storage/permissions/check", "POST", input, options);
+    }
+  };
+  const objectFolder = {
+    create(input, options) {
+      return callAthena2("/storage/objects/folder", "POST", input, options);
+    },
+    delete(input, options) {
+      return callAthena2("/storage/objects/folder/delete", "POST", input, options);
+    },
+    rename(input, options) {
+      return callAthena2("/storage/objects/folder/rename", "POST", input, options);
+    }
+  };
+  const object = {
+    list(input, options) {
+      return callAthena2("/storage/objects", "POST", input, options);
+    },
+    head(input, options) {
+      return callAthena2("/storage/objects/head", "POST", input, options);
+    },
+    exists(input, options) {
+      return callAthena2("/storage/objects/exists", "POST", input, options);
+    },
+    validate(input, options) {
+      return callAthena2("/storage/objects/validate", "POST", input, options);
+    },
+    update(input, options) {
+      return callAthena2("/storage/objects/update", "POST", input, options);
+    },
+    copy(input, options) {
+      return callAthena2("/storage/objects/copy", "POST", input, options);
+    },
+    url(input, options) {
+      return callAthena2("/storage/objects/url", "POST", input, options);
+    },
+    publicUrl(input, options) {
+      return callAthena2("/storage/objects/public-url", "POST", input, options);
+    },
+    delete(input, options) {
+      return callAthena2("/storage/objects/delete", "POST", input, options);
+    },
+    uploadUrl(input, options) {
+      return callAthena2("/storage/objects/upload-url", "POST", input, options);
+    },
+    folder: objectFolder
+  };
+  const bucket = {
+    list(input, options) {
+      return callAthena2("/storage/buckets/list", "POST", input, options);
+    },
+    create(input, options) {
+      return callAthena2("/storage/buckets/create", "POST", input, options);
+    },
+    delete(input, options) {
+      return callAthena2("/storage/buckets/delete", "POST", input, options);
+    },
+    cors: {
+      get(input, options) {
+        return callAthena2("/storage/buckets/cors", "POST", input, options);
+      },
+      set(input, options) {
+        return callAthena2("/storage/buckets/cors/set", "POST", input, options);
+      },
+      delete(input, options) {
+        return callAthena2("/storage/buckets/cors/delete", "POST", input, options);
+      }
+    }
+  };
+  const multipart = {
+    create(input, options) {
+      return callAthena2("/storage/multipart/create", "POST", input, options);
+    },
+    signPart(input, options) {
+      return callAthena2("/storage/multipart/sign-part", "POST", input, options);
+    },
+    complete(input, options) {
+      return callAthena2("/storage/multipart/complete", "POST", input, options);
+    },
+    abort(input, options) {
+      return callAthena2("/storage/multipart/abort", "POST", input, options);
+    },
+    listParts(input, options) {
+      return callAthena2("/storage/multipart/list-parts", "POST", input, options);
+    }
+  };
+  const audit = {
+    list(input, options) {
+      return callAthena2("/storage/audit/list", "POST", input, options);
     }
   };
+  return {
+    ...base,
+    credentials,
+    catalog,
+    file,
+    folder,
+    permission,
+    object,
+    bucket,
+    multipart,
+    audit,
+    delete: file.delete
+  };
+}
+
+// src/client-builder.ts
+var DEFAULT_BACKEND = { type: "athena" };
+function toBackendConfig(value) {
+  if (!value) return DEFAULT_BACKEND;
+  return typeof value === "string" ? { type: value } : value;
+}
+function mergeHeaders(current, next) {
+  return {
+    ...current ?? {},
+    ...next
+  };
+}
+function mergeAuthClientConfig(current, next) {
+  const merged = {
+    ...current ?? {},
+    ...next
+  };
+  if (current?.headers || next.headers) {
+    merged.headers = mergeHeaders(current?.headers, next.headers ?? {});
+  }
+  return merged;
+}
+function mergeExperimentalOptions(current, next) {
+  const merged = {
+    ...current ?? {},
+    ...next
+  };
+  if (current?.traceQueries && typeof current.traceQueries === "object" && next.traceQueries && typeof next.traceQueries === "object") {
+    merged.traceQueries = {
+      ...current.traceQueries,
+      ...next.traceQueries
+    };
+  }
+  if (current?.storage || next.storage) {
+    merged.storage = {
+      ...current?.storage ?? {},
+      ...next.storage ?? {}
+    };
+  }
+  return merged;
+}
+function resolveBuilderReturn(builder, storageEnabled, strictEnabled) {
+  return builder;
+}
+var AthenaClientBuilderImpl = class {
+  constructor(buildClient) {
+    this.buildClient = buildClient;
+  }
+  rootUrl;
+  apiKey;
+  backendConfig = DEFAULT_BACKEND;
+  clientName;
+  defaultHeaders;
+  authConfig;
+  dbUrlOverride;
+  gatewayUrlOverride;
+  authUrlOverride;
+  storageUrlOverride;
+  experimentalOptions;
+  url(url) {
+    this.rootUrl = url;
+    return this;
+  }
+  key(apiKey) {
+    this.apiKey = apiKey;
+    return this;
+  }
+  backend(backend) {
+    this.backendConfig = toBackendConfig(backend);
+    return this;
+  }
+  client(clientName) {
+    this.clientName = clientName;
+    return this;
+  }
+  headers(headers) {
+    this.defaultHeaders = headers;
+    return this;
+  }
+  auth(config) {
+    this.authConfig = mergeAuthClientConfig(this.authConfig, config);
+    return this;
+  }
+  experimental(options) {
+    this.experimentalOptions = mergeExperimentalOptions(this.experimentalOptions, options);
+    if (options.athenaStorageBackend && options.typecheckColumns) {
+      return resolveBuilderReturn(this);
+    }
+    if (options.athenaStorageBackend) {
+      return resolveBuilderReturn(this);
+    }
+    if (options.typecheckColumns) {
+      return resolveBuilderReturn(this);
+    }
+    return this;
+  }
+  options(options) {
+    if (options.client !== void 0) {
+      this.clientName = options.client;
+    }
+    if (options.backend !== void 0) {
+      this.backendConfig = toBackendConfig(options.backend);
+    }
+    if (options.headers !== void 0) {
+      this.defaultHeaders = mergeHeaders(this.defaultHeaders, options.headers);
+    }
+    if (options.auth !== void 0) {
+      this.authConfig = mergeAuthClientConfig(this.authConfig, options.auth);
+    }
+    if (options.db?.url !== void 0 && options.db.url !== null) {
+      this.dbUrlOverride = options.db.url;
+    }
+    if (options.gateway?.url !== void 0 && options.gateway.url !== null) {
+      this.gatewayUrlOverride = options.gateway.url;
+    }
+    if (options.dbUrl !== void 0 && options.dbUrl !== null) {
+      this.dbUrlOverride = options.dbUrl;
+    }
+    if (options.gatewayUrl !== void 0 && options.gatewayUrl !== null) {
+      this.gatewayUrlOverride = options.gatewayUrl;
+    }
+    if (options.authUrl !== void 0 && options.authUrl !== null) {
+      this.authUrlOverride = options.authUrl;
+    }
+    if (options.storage?.url !== void 0 && options.storage.url !== null) {
+      this.storageUrlOverride = options.storage.url;
+    }
+    if (options.storageUrl !== void 0 && options.storageUrl !== null) {
+      this.storageUrlOverride = options.storageUrl;
+    }
+    if (options.experimental !== void 0) {
+      this.experimentalOptions = mergeExperimentalOptions(this.experimentalOptions, options.experimental);
+    }
+    if (options.experimental?.athenaStorageBackend && options.experimental.typecheckColumns) {
+      return resolveBuilderReturn(this);
+    }
+    if (options.experimental?.athenaStorageBackend) {
+      return resolveBuilderReturn(this);
+    }
+    if (options.experimental?.typecheckColumns) {
+      return resolveBuilderReturn(this);
+    }
+    return this;
+  }
+  build() {
+    if (!this.rootUrl && !this.dbUrlOverride && !this.gatewayUrlOverride || !this.apiKey) {
+      throw new Error(
+        "AthenaClient requires key plus either .url() or a db/gateway override before .build()"
+      );
+    }
+    return this.buildClient({
+      url: this.rootUrl,
+      key: this.apiKey,
+      client: this.clientName,
+      backend: this.backendConfig,
+      headers: this.defaultHeaders,
+      db: this.dbUrlOverride ? { url: this.dbUrlOverride } : void 0,
+      gateway: this.gatewayUrlOverride ? { url: this.gatewayUrlOverride } : void 0,
+      auth: this.authConfig,
+      authUrl: this.authUrlOverride,
+      storage: this.storageUrlOverride ? { url: this.storageUrlOverride } : void 0,
+      storageUrl: this.storageUrlOverride,
+      experimental: this.experimentalOptions
+    });
+  }
+};
+function createAthenaClientBuilder(buildClient) {
+  return new AthenaClientBuilderImpl(buildClient);
 }
 
 // src/query-ast.ts
@@ -4087,7 +4993,7 @@ var BOOLEAN_SAFE_OPERATORS = /* @__PURE__ */ new Set([
   "ilike",
   "is"
 ]);
-function isRecord6(value) {
+function isRecord7(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function isUuidString(value) {
@@ -4100,7 +5006,7 @@ function shouldUseUuidTextComparison(column, value) {
   return typeof value === "string" && isUuidString(value) && isUuidIdentifierColumn(column);
 }
 function isRelationSelectNode(value) {
-  return isRecord6(value) && isRecord6(value.select);
+  return isRecord7(value) && isRecord7(value.select);
 }
 function normalizeIdentifier(value, label) {
   const normalized = value.trim();
@@ -4156,7 +5062,7 @@ function compileRelationToken(key, node) {
   return `${prefix}${relationToken}(${nested})`;
 }
 function compileSelectShape(select) {
-  if (!isRecord6(select)) {
+  if (!isRecord7(select)) {
     throw new Error("findMany select must be an object");
   }
   const tokens = [];
@@ -4180,7 +5086,7 @@ function compileSelectShape(select) {
   return tokens.join(",");
 }
 function selectShapeUsesRelationSchema(select) {
-  if (!isRecord6(select)) {
+  if (!isRecord7(select)) {
     return false;
   }
   for (const rawValue of Object.values(select)) {
@@ -4198,7 +5104,7 @@ function selectShapeUsesRelationSchema(select) {
 }
 function compileColumnWhere(column, input) {
   const normalizedColumn = normalizeIdentifier(column, "where column");
-  if (!isRecord6(input)) {
+  if (!isRecord7(input)) {
     return [buildGatewayCondition("eq", normalizedColumn, input)];
   }
   const conditions = [];
@@ -4226,7 +5132,7 @@ function compileColumnWhere(column, input) {
   return conditions;
 }
 function compileBooleanExpressionTerms(clause, label) {
-  if (!isRecord6(clause)) {
+  if (!isRecord7(clause)) {
     throw new Error(`findMany where.${label} clauses must be objects`);
   }
   const entries = Object.entries(clause).filter(([, value]) => value !== void 0);
@@ -4235,7 +5141,7 @@ function compileBooleanExpressionTerms(clause, label) {
   }
   const [rawColumn, rawValue] = entries[0];
   const column = normalizeIdentifier(rawColumn, `where.${label} column`);
-  if (!isRecord6(rawValue)) {
+  if (!isRecord7(rawValue)) {
     return [`${column}.eq.${stringifyFilterValue(rawValue)}`];
   }
   const operatorEntries = Object.entries(rawValue).filter(([, value]) => value !== void 0);
@@ -4259,7 +5165,7 @@ function compileWhere(where) {
   if (where === void 0) {
     return void 0;
   }
-  if (!isRecord6(where)) {
+  if (!isRecord7(where)) {
     throw new Error("findMany where must be an object");
   }
   const conditions = [];
@@ -4309,7 +5215,7 @@ function compileOrderBy(orderBy) {
   if (orderBy === void 0) {
     return void 0;
   }
-  if (!isRecord6(orderBy)) {
+  if (!isRecord7(orderBy)) {
     throw new Error("findMany orderBy must be an object");
   }
   if ("column" in orderBy) {
@@ -4484,11 +5390,11 @@ function toFindManyAstOrder(order) {
     ascending: order.direction !== "descending"
   };
 }
-function isRecord7(value) {
+function isRecord8(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function normalizeFindManyAstColumnPredicate(value) {
-  if (!isRecord7(value)) {
+  if (!isRecord8(value)) {
     return {
       eq: value
     };
@@ -4512,7 +5418,7 @@ function normalizeFindManyAstBooleanOperand(clause) {
   return normalized;
 }
 function normalizeFindManyAstWhere(where) {
-  if (!where || !isRecord7(where)) {
+  if (!where || !isRecord8(where)) {
     return where;
   }
   const normalized = {};
@@ -4526,7 +5432,7 @@ function normalizeFindManyAstWhere(where) {
       );
       continue;
     }
-    if (key === "not" && isRecord7(value)) {
+    if (key === "not" && isRecord8(value)) {
       normalized.not = normalizeFindManyAstBooleanOperand(
         value
       );
@@ -4537,7 +5443,7 @@ function normalizeFindManyAstWhere(where) {
   return normalized;
 }
 function predicateRequiresUuidQueryFallback(column, value) {
-  if (!isRecord7(value)) {
+  if (!isRecord8(value)) {
     return shouldUseUuidTextComparison(column, value);
   }
   const eqValue = value.eq;
@@ -4555,7 +5461,7 @@ function booleanOperandRequiresUuidQueryFallback(clause) {
   return false;
 }
 function findManyAstWhereRequiresLegacyTransport(where) {
-  if (!where || !isRecord7(where)) {
+  if (!where || !isRecord8(where)) {
     return false;
   }
   for (const [key, value] of Object.entries(where)) {
@@ -4570,7 +5476,7 @@ function findManyAstWhereRequiresLegacyTransport(where) {
       }
       continue;
     }
-    if (key === "not" && isRecord7(value)) {
+    if (key === "not" && isRecord8(value)) {
       if (booleanOperandRequiresUuidQueryFallback(value)) {
         return true;
       }
@@ -4682,161 +5588,258 @@ function createSelectTransportPlan(input) {
   };
 }
 
-// src/client.ts
-var DEFAULT_COLUMNS = "*";
-var SAFE_CAST_PATTERN = /^[a-z_][a-z0-9_]*(?:\[\])?$/i;
-var ATHENA_NORMALIZED_ERROR_KEY = "__athenaNormalizedError";
-var QUERY_TRACE_STACK_SKIP_PATTERNS = [
-  "src\\client.ts",
-  "src/client.ts",
-  "dist\\client.",
-  "dist/client.",
-  "node_modules\\@xylex-group\\athena",
-  "node_modules/@xylex-group/athena",
-  "node:internal",
-  "internal/process"
-];
-function formatResult(response) {
-  const result = {
-    data: response.data ?? null,
-    error: null,
-    errorDetails: response.errorDetails ?? null,
-    status: response.status,
-    statusText: response.statusText ?? null,
-    raw: response.raw
+// src/query-debug-ast.ts
+var ATHENA_DEBUG_AST_KEY = "__athenaDebugAst";
+function cloneConditions(conditions) {
+  return conditions.map((condition) => ({ ...condition }));
+}
+function cloneTableBuilderStateAst(state) {
+  return {
+    conditions: cloneConditions(state.conditions),
+    limit: state.limit,
+    offset: state.offset,
+    order: state.order ? { ...state.order } : void 0,
+    currentPage: state.currentPage,
+    pageSize: state.pageSize,
+    totalPages: state.totalPages
   };
-  if (response.count !== void 0) {
-    result.count = response.count;
+}
+function cloneRpcBuilderStateAst(state) {
+  return {
+    filters: state.filters.map((filter) => ({ ...filter })),
+    limit: state.limit,
+    offset: state.offset,
+    order: state.order ? { ...state.order } : void 0
+  };
+}
+function toSelectTransportAst(plan) {
+  if (plan.kind === "query") {
+    return {
+      mode: "typed-query",
+      endpoint: "/gateway/query",
+      payload: plan.payload
+    };
   }
-  return result;
+  return {
+    mode: plan.payload.select !== void 0 ? "structured-fetch" : "compiled-fetch",
+    endpoint: "/gateway/fetch",
+    payload: plan.payload
+  };
 }
-var EXPERIMENTAL_READ_RETRY_CONFIG = {
-  retries: 2,
-  baseDelayMs: 100,
-  maxDelayMs: 1e3,
-  backoff: "exponential",
-  jitter: true
-};
-function attachNormalizedError(result, normalizedError) {
-  Object.defineProperty(result, ATHENA_NORMALIZED_ERROR_KEY, {
-    value: normalizedError,
-    enumerable: false,
-    configurable: true,
-    writable: false
-  });
+function resolveDebugTableName(tableName) {
+  return tableName ?? "__unknown_table__";
 }
-function createResultFormatter(experimental) {
-  return (response, context) => {
-    const result = formatResult(response);
-    if (response.error == null && response.errorDetails == null) {
-      return result;
+function buildSelectDebugAst(input) {
+  return {
+    version: 1,
+    kind: "select",
+    tableName: input.tableName,
+    input: {
+      columns: input.columns,
+      state: cloneTableBuilderStateAst(input.state)
+    },
+    transport: toSelectTransportAst(input.plan)
+  };
+}
+function buildFindManyCompiledDebugAst(input) {
+  return {
+    version: 1,
+    kind: "findMany",
+    tableName: input.tableName,
+    input: {
+      select: input.options.select,
+      where: input.options.where,
+      orderBy: input.options.orderBy,
+      limit: input.options.limit
+    },
+    compiled: {
+      columns: input.compiledColumns,
+      baseState: cloneTableBuilderStateAst(input.baseState),
+      executionState: cloneTableBuilderStateAst(input.executionState)
+    },
+    transport: planToFindManyTransport(input.plan)
+  };
+}
+function buildFindManyDirectDebugAst(input) {
+  return {
+    version: 1,
+    kind: "findMany",
+    tableName: input.tableName,
+    input: {
+      select: input.options.select,
+      where: input.options.where,
+      orderBy: input.options.orderBy,
+      limit: input.options.limit
+    },
+    compiled: {
+      columns: input.compiledColumns,
+      baseState: cloneTableBuilderStateAst(input.baseState),
+      executionState: cloneTableBuilderStateAst(input.executionState)
+    },
+    transport: {
+      mode: "direct-ast-fetch",
+      endpoint: "/gateway/fetch",
+      payload: input.payload
     }
-    const normalizedError = normalizeAthenaError(
-      {
-        ...result,
-        error: response.error ?? response.errorDetails?.message ?? null
-      },
-      context
-    );
-    result.error = createResultError(response, result, normalizedError);
-    attachNormalizedError(result, normalizedError);
-    return result;
   };
 }
-async function executeExperimentalRead(experimental, runner) {
-  if (!experimental?.retryReads) {
-    return runner();
+function planToFindManyTransport(plan) {
+  if (plan.kind === "query") {
+    return {
+      mode: "compiled-query",
+      endpoint: "/gateway/query",
+      payload: plan.payload
+    };
   }
-  let lastRetryableResult;
-  let lastRetrySignal = null;
-  try {
-    return await withRetry(
-      {
-        ...EXPERIMENTAL_READ_RETRY_CONFIG,
-        shouldRetry: (error) => error === lastRetrySignal || normalizeAthenaError(error).retryable
-      },
-      async () => {
-        const result = await runner();
-        if (result.error?.retryable) {
-          lastRetryableResult = result;
-          lastRetrySignal = result.error;
-          throw lastRetrySignal;
-        }
-        return result;
-      }
-    );
-  } catch (error) {
-    if (lastRetryableResult && error === lastRetrySignal) {
-      return lastRetryableResult;
+  return {
+    mode: plan.payload.select !== void 0 ? "structured-fetch" : "compiled-fetch",
+    endpoint: "/gateway/fetch",
+    payload: plan.payload
+  };
+}
+function buildInsertDebugAst(payload) {
+  return {
+    version: 1,
+    kind: "insert",
+    tableName: payload.table_name,
+    input: {
+      values: payload.insert_body,
+      returning: payload.columns,
+      count: payload.count,
+      head: payload.head,
+      defaultToNull: payload.default_to_null
+    },
+    transport: {
+      mode: "insert",
+      endpoint: "/gateway/insert",
+      payload
     }
-    throw error;
-  }
+  };
 }
-function isRecord8(value) {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+function buildUpsertDebugAst(payload) {
+  return {
+    version: 1,
+    kind: "upsert",
+    tableName: payload.table_name,
+    input: {
+      values: payload.insert_body,
+      updateBody: payload.update_body,
+      onConflict: payload.on_conflict,
+      returning: payload.columns,
+      count: payload.count,
+      head: payload.head,
+      defaultToNull: payload.default_to_null
+    },
+    transport: {
+      mode: "upsert",
+      endpoint: "/gateway/insert",
+      payload
+    }
+  };
 }
-function firstNonEmptyString2(...values) {
-  for (const value of values) {
-    if (typeof value === "string" && value.trim().length > 0) {
-      return value.trim();
+function buildUpdateDebugAst(input) {
+  return {
+    version: 1,
+    kind: "update",
+    tableName: resolveDebugTableName(input.payload.table_name),
+    input: {
+      values: input.payload.set,
+      state: cloneTableBuilderStateAst(input.state),
+      returning: input.payload.columns
+    },
+    transport: {
+      mode: "update",
+      endpoint: "/gateway/update",
+      payload: input.payload
     }
-  }
-  return void 0;
+  };
 }
-function resolveStructuredErrorPayload2(raw) {
-  if (!isRecord8(raw)) return null;
-  return isRecord8(raw.error) ? raw.error : raw;
+function buildDeleteDebugAst(input) {
+  return {
+    version: 1,
+    kind: "delete",
+    tableName: input.payload.table_name,
+    input: {
+      resourceId: input.payload.resource_id,
+      state: cloneTableBuilderStateAst(input.state),
+      returning: input.payload.columns
+    },
+    transport: {
+      mode: "delete",
+      endpoint: "/gateway/delete",
+      payload: input.payload
+    }
+  };
 }
-function resolveStructuredErrorDetails(payload, message) {
-  if (!payload || !("details" in payload)) {
-    return null;
+function buildRpcDebugAst(input) {
+  return {
+    version: 1,
+    kind: "rpc",
+    functionName: input.functionName,
+    input: {
+      args: input.args,
+      select: input.selectedColumns,
+      state: cloneRpcBuilderStateAst(input.state)
+    },
+    transport: {
+      mode: input.endpoint === "/gateway/rpc" ? "rpc-post" : "rpc-get",
+      endpoint: input.endpoint,
+      payload: input.payload
+    }
+  };
+}
+function buildRawQueryDebugAst(query) {
+  return {
+    version: 1,
+    kind: "query",
+    input: {
+      query
+    },
+    transport: {
+      mode: "raw-query",
+      endpoint: "/gateway/query",
+      payload: {
+        query
+      }
+    }
+  };
+}
+function attachAthenaDebugAst(target, ast) {
+  if (!ast) {
+    return;
   }
-  const details = payload.details;
-  if (details == null) {
-    return null;
+  if (!target || typeof target !== "object" && typeof target !== "function") {
+    return;
   }
-  if (typeof details === "string" && details.trim() === message.trim()) {
+  Object.defineProperty(target, ATHENA_DEBUG_AST_KEY, {
+    value: ast,
+    enumerable: false,
+    configurable: true,
+    writable: false
+  });
+}
+function getAthenaDebugAst(value) {
+  if (!value || typeof value !== "object" && typeof value !== "function") {
     return null;
   }
-  return details;
-}
-function createResultError(response, result, normalized) {
-  const rawRecord = isRecord8(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
-  };
+  return value[ATHENA_DEBUG_AST_KEY] ?? null;
 }
+
+// src/query-tracing.ts
+var QUERY_TRACE_STACK_SKIP_PATTERNS = [
+  "src\\client.ts",
+  "src/client.ts",
+  "src\\query-tracing.ts",
+  "src/query-tracing.ts",
+  "dist\\client.",
+  "dist/client.",
+  "dist\\query-tracing.",
+  "dist/query-tracing.",
+  "node_modules\\@xylex-group\\athena",
+  "node_modules/@xylex-group/athena",
+  "node:internal",
+  "internal/process"
+];
 function parseQueryTraceCallsiteFrame(frame) {
   const trimmed = frame.trim();
   if (!trimmed) {
@@ -4941,6 +5944,7 @@ function createQueryTracer(experimental) {
         functionName: context.functionName,
         sql: context.sql,
         payload: context.payload,
+        ast: context.ast,
         options: context.options,
         callsite,
         outcome: {
@@ -4963,6 +5967,7 @@ function createQueryTracer(experimental) {
         functionName: context.functionName,
         sql: context.sql,
         payload: context.payload,
+        ast: context.ast,
         options: context.options,
         callsite,
         thrownError: error
@@ -4971,20 +5976,196 @@ function createQueryTracer(experimental) {
   };
 }
 async function executeWithQueryTrace(tracer, context, runner, callsiteOverride) {
-  if (!tracer) {
-    return runner();
-  }
-  const callsite = callsiteOverride ?? tracer.captureCallsite();
-  const startedAt = Date.now();
+  const callsite = tracer ? callsiteOverride ?? tracer.captureCallsite() : null;
+  const startedAt = tracer ? Date.now() : 0;
   try {
     const result = await runner();
-    tracer.publishSuccess(context, result, Date.now() - startedAt, callsite);
+    attachAthenaDebugAst(result, context.ast);
+    if (tracer) {
+      tracer.publishSuccess(context, result, Date.now() - startedAt, callsite);
+    }
     return result;
   } catch (error) {
-    tracer.publishFailure(context, error, Date.now() - startedAt, callsite);
+    attachAthenaDebugAst(error, context.ast);
+    if (tracer) {
+      tracer.publishFailure(context, error, Date.now() - startedAt, callsite);
+    }
+    throw error;
+  }
+}
+
+// src/schema/model-target.ts
+function normalizeOptionalName(value) {
+  const normalized = value?.trim();
+  return normalized ? normalized : void 0;
+}
+function isAthenaModelTarget(value) {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const candidate = value;
+  return Boolean(candidate.meta && Array.isArray(candidate.meta.primaryKey));
+}
+function resolveAthenaModelTargetTableName(target, options = {}) {
+  const explicitTableName = normalizeOptionalName(target.meta.tableName);
+  if (explicitTableName) {
+    return explicitTableName;
+  }
+  const schemaName = normalizeOptionalName(target.meta.schema ?? options.fallbackSchema);
+  const modelName = normalizeOptionalName(target.meta.model ?? options.fallbackModel);
+  if (!modelName) {
+    throw new Error(
+      "Athena model target is missing meta.model or meta.tableName. Provide one of those before calling from(model)."
+    );
+  }
+  return schemaName ? `${schemaName}.${modelName}` : modelName;
+}
+
+// src/client.ts
+var DEFAULT_COLUMNS = "*";
+var SAFE_CAST_PATTERN = /^[a-z_][a-z0-9_]*(?:\[\])?$/i;
+var ATHENA_NORMALIZED_ERROR_KEY = "__athenaNormalizedError";
+function formatResult(response) {
+  const result = {
+    data: response.data ?? null,
+    error: null,
+    errorDetails: response.errorDetails ?? null,
+    status: response.status,
+    statusText: response.statusText ?? null,
+    raw: response.raw
+  };
+  if (response.count !== void 0) {
+    result.count = response.count;
+  }
+  return result;
+}
+var EXPERIMENTAL_READ_RETRY_CONFIG = {
+  retries: 2,
+  baseDelayMs: 100,
+  maxDelayMs: 1e3,
+  backoff: "exponential",
+  jitter: true
+};
+function attachNormalizedError(result, normalizedError) {
+  Object.defineProperty(result, ATHENA_NORMALIZED_ERROR_KEY, {
+    value: normalizedError,
+    enumerable: false,
+    configurable: true,
+    writable: false
+  });
+}
+function createResultFormatter(experimental) {
+  return (response, context) => {
+    const result = formatResult(response);
+    if (response.error == null && response.errorDetails == null) {
+      return result;
+    }
+    const normalizedError = normalizeAthenaError(
+      {
+        ...result,
+        error: response.error ?? response.errorDetails?.message ?? null
+      },
+      context
+    );
+    result.error = createResultError(response, result, normalizedError);
+    attachNormalizedError(result, normalizedError);
+    return result;
+  };
+}
+async function executeExperimentalRead(experimental, runner) {
+  if (!experimental?.retryReads) {
+    return runner();
+  }
+  let lastRetryableResult;
+  let lastRetrySignal = null;
+  try {
+    return await withRetry(
+      {
+        ...EXPERIMENTAL_READ_RETRY_CONFIG,
+        shouldRetry: (error) => error === lastRetrySignal || normalizeAthenaError(error).retryable
+      },
+      async () => {
+        const result = await runner();
+        if (result.error?.retryable) {
+          lastRetryableResult = result;
+          lastRetrySignal = result.error;
+          throw lastRetrySignal;
+        }
+        return result;
+      }
+    );
+  } catch (error) {
+    if (lastRetryableResult && error === lastRetrySignal) {
+      return lastRetryableResult;
+    }
     throw error;
   }
 }
+function isRecord9(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 (!isRecord9(raw)) return null;
+  return isRecord9(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 = isRecord9(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 toSingleResult(response) {
   const payload = response.data;
   const singleData = Array.isArray(payload) ? payload.length ? payload[0] : null : payload ?? null;
@@ -5012,6 +6193,15 @@ function asAthenaJsonObject(value) {
 function asAthenaJsonObjectArray(values) {
   return values;
 }
+function normalizeSelectColumnsInput(columns) {
+  if (columns === void 0) {
+    return void 0;
+  }
+  if (typeof columns === "string") {
+    return columns;
+  }
+  return [...columns];
+}
 function createMutationQuery(executor, defaultColumns = DEFAULT_COLUMNS, tracer, initialCallsite) {
   let selectedColumns = defaultColumns === null ? void 0 : defaultColumns;
   let selectedOptions;
@@ -5021,25 +6211,29 @@ function createMutationQuery(executor, defaultColumns = DEFAULT_COLUMNS, tracer,
     const payloadColumns = columns ?? selectedColumns;
     const payloadOptions = options ?? selectedOptions;
     if (!promise) {
-      promise = executor(payloadColumns, payloadOptions, callsiteStore.resolve(callsite));
+      promise = executor(
+        normalizeSelectColumnsInput(payloadColumns),
+        payloadOptions,
+        callsiteStore.resolve(callsite)
+      );
     }
     return promise;
   };
   const mutationQuery = {
-    select(columns = selectedColumns, options) {
+    select(columns, options) {
       selectedColumns = columns;
       selectedOptions = options ?? selectedOptions;
       return run(columns, options, captureTraceCallsite(tracer));
     },
-    returning(columns = selectedColumns, options) {
+    returning(columns, options) {
       return mutationQuery.select(columns, options);
     },
-    single(columns = selectedColumns, options) {
+    single(columns, options) {
       selectedColumns = columns;
       selectedOptions = options ?? selectedOptions;
       return run(columns, options, captureTraceCallsite(tracer)).then(toSingleResult);
     },
-    maybeSingle(columns = selectedColumns, options) {
+    maybeSingle(columns, options) {
       return mutationQuery.single(columns, options);
     },
     then(onfulfilled, onrejected) {
@@ -5596,7 +6790,10 @@ function createFilterMethods(state, addCondition, self) {
 }
 function toRpcSelect(columns) {
   if (!columns) return void 0;
-  return Array.isArray(columns) ? columns.join(",") : columns;
+  if (typeof columns === "string") {
+    return columns;
+  }
+  return columns.join(",");
 }
 function createRpcFilterMethods(filters, self) {
   const addFilter = (operator, column, value) => {
@@ -5645,7 +6842,7 @@ function createRpcFilterMethods(filters, self) {
     }
   };
 }
-function createRpcBuilder(functionName, args, baseOptions, client, formatGatewayResult, tracer, initialCallsite) {
+function createRpcBuilder(functionName, args, baseOptions, client, formatGatewayResult, tracer, initialCallsite, debugAstEnabled = false) {
   const state = {
     filters: []
   };
@@ -5655,6 +6852,7 @@ function createRpcBuilder(functionName, args, baseOptions, client, formatGateway
   const callsiteStore = createTraceCallsiteStore(tracer, initialCallsite);
   const executeRpc = async (columns, options, callsite) => {
     const mergedOptions = mergeOptions(baseOptions, options);
+    const normalizedSelectedColumns = normalizeSelectColumnsInput(columns);
     const payload = {
       function: functionName,
       args,
@@ -5669,6 +6867,14 @@ function createRpcBuilder(functionName, args, baseOptions, client, formatGateway
     };
     const endpoint = mergedOptions?.get ? `/rpc/${functionName}` : "/gateway/rpc";
     const sql = buildRpcDebugSql(payload);
+    const debugAst = debugAstEnabled ? buildRpcDebugAst({
+      functionName,
+      args,
+      selectedColumns: normalizedSelectedColumns,
+      state,
+      payload,
+      endpoint
+    }) : void 0;
     return executeWithQueryTrace(
       tracer,
       {
@@ -5677,6 +6883,7 @@ function createRpcBuilder(functionName, args, baseOptions, client, formatGateway
         functionName,
         sql,
         payload,
+        ast: debugAst,
         options: mergedOptions
       },
       async () => {
@@ -5697,7 +6904,7 @@ function createRpcBuilder(functionName, args, baseOptions, client, formatGateway
   const builder = {};
   const filterMethods = createRpcFilterMethods(state.filters, builder);
   Object.assign(builder, filterMethods, {
-    select(columns = selectedColumns, options) {
+    select(columns, options) {
       selectedColumns = columns;
       selectedOptions = options ?? selectedOptions;
       return run(columns, options, captureTraceCallsite(tracer));
@@ -5742,6 +6949,7 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
   const state = {
     conditions: []
   };
+  const debugAstEnabled = Boolean(experimental?.debugAst);
   const addCondition = (operator, column, value, hints) => {
     const condition = { operator };
     if (column) {
@@ -5785,15 +6993,27 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
     addCondition,
     builder
   );
-  const runSelect = async (columns = DEFAULT_COLUMNS, options, executionState = snapshotState(), callsite) => {
+  const runSelect = async (columns = DEFAULT_COLUMNS, options, executionState = snapshotState(), callsite, debugAstFactory) => {
+    const runtimeColumns = normalizeSelectColumnsInput(columns) ?? DEFAULT_COLUMNS;
     const resolvedTableName = resolveTableNameForCall(tableName, options?.schema);
     const plan = createSelectTransportPlan({
       tableName: resolvedTableName,
-      columns,
+      columns: runtimeColumns,
       state: executionState,
       options,
       buildTypedSelectQuery
     });
+    const debugAst = debugAstEnabled ? debugAstFactory?.({
+      tableName: resolvedTableName,
+      columns: runtimeColumns,
+      executionState,
+      plan
+    }) ?? buildSelectDebugAst({
+      tableName: resolvedTableName,
+      columns: runtimeColumns,
+      state: executionState,
+      plan
+    }) : void 0;
     if (plan.kind === "query") {
       return executeExperimentalRead(
         experimental,
@@ -5805,6 +7025,7 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
             table: resolvedTableName,
             sql: plan.query,
             payload: plan.payload,
+            ast: debugAst,
             options
           },
           async () => {
@@ -5829,6 +7050,7 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
           table: resolvedTableName,
           sql,
           payload: plan.payload,
+          ast: debugAst,
           options
         },
         async () => {
@@ -5842,7 +7064,11 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
   const createSelectChain = (columns, options, initialCallsite) => {
     const chain = {};
     const callsiteStore = createTraceCallsiteStore(tracer, initialCallsite);
-    const filterMethods2 = createFilterMethods(state, addCondition, chain);
+    const filterMethods2 = createFilterMethods(
+      state,
+      addCondition,
+      chain
+    );
     Object.assign(chain, filterMethods2, {
       async single(cols, opts) {
         const r = await runSelect(
@@ -5929,6 +7155,14 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
           limit: executionState.limit,
           order: executionState.order
         });
+        const debugAst = debugAstEnabled ? buildFindManyDirectDebugAst({
+          tableName: resolvedTableName,
+          options,
+          compiledColumns: columns,
+          baseState,
+          executionState,
+          payload
+        }) : void 0;
         return executeExperimentalRead(
           experimental,
           () => executeWithQueryTrace(
@@ -5938,7 +7172,8 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
               endpoint: "/gateway/fetch",
               table: resolvedTableName,
               sql,
-              payload
+              payload,
+              ast: debugAst
             },
             async () => {
               const response = await client.fetchGateway(
@@ -5954,7 +7189,15 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
         columns,
         void 0,
         executionState,
-        callsite
+        callsite,
+        debugAstEnabled ? ({ tableName: resolvedTableName, executionState: tracedState, plan }) => buildFindManyCompiledDebugAst({
+          tableName: resolvedTableName,
+          options,
+          compiledColumns: columns,
+          baseState,
+          executionState: tracedState,
+          plan
+        }) : void 0
       );
     },
     insert(values, options) {
@@ -5974,6 +7217,7 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
             payload.default_to_null = mergedOptions.defaultToNull;
           }
           const sql = buildInsertDebugSql(payload);
+          const debugAst = debugAstEnabled ? buildInsertDebugAst(payload) : void 0;
           return executeWithQueryTrace(
             tracer,
             {
@@ -5982,6 +7226,7 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
               table: resolvedTableName,
               sql,
               payload,
+              ast: debugAst,
               options: mergedOptions
             },
             async () => {
@@ -6007,6 +7252,7 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
           payload.default_to_null = mergedOptions.defaultToNull;
         }
         const sql = buildInsertDebugSql(payload);
+        const debugAst = debugAstEnabled ? buildInsertDebugAst(payload) : void 0;
         return executeWithQueryTrace(
           tracer,
           {
@@ -6015,6 +7261,7 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
             table: resolvedTableName,
             sql,
             payload,
+            ast: debugAst,
             options: mergedOptions
           },
           async () => {
@@ -6045,6 +7292,7 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
             payload.default_to_null = mergedOptions.defaultToNull;
           }
           const sql = buildInsertDebugSql(payload);
+          const debugAst = debugAstEnabled ? buildUpsertDebugAst(payload) : void 0;
           return executeWithQueryTrace(
             tracer,
             {
@@ -6053,6 +7301,7 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
               table: resolvedTableName,
               sql,
               payload,
+              ast: debugAst,
               options: mergedOptions
             },
             async () => {
@@ -6080,6 +7329,7 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
           payload.default_to_null = mergedOptions.defaultToNull;
         }
         const sql = buildInsertDebugSql(payload);
+        const debugAst = debugAstEnabled ? buildUpsertDebugAst(payload) : void 0;
         return executeWithQueryTrace(
           tracer,
           {
@@ -6088,6 +7338,7 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
             table: resolvedTableName,
             sql,
             payload,
+            ast: debugAst,
             options: mergedOptions
           },
           async () => {
@@ -6102,7 +7353,8 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
     update(values, options) {
       const mutationCallsite = captureTraceCallsite(tracer);
       const executeUpdate = async (columns, selectOptions, callsite) => {
-        const filters = state.conditions.length ? [...state.conditions] : void 0;
+        const executionState = snapshotState();
+        const filters = executionState.conditions.length ? [...executionState.conditions] : void 0;
         const mergedOptions = mergeOptions(options, selectOptions);
         const resolvedTableName = resolveTableNameForCall(tableName, mergedOptions?.schema);
         const payload = {
@@ -6111,12 +7363,16 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
           conditions: filters,
           strip_nulls: mergedOptions?.stripNulls ?? true
         };
-        if (state.order) payload.sort_by = state.order;
-        if (state.currentPage !== void 0) payload.current_page = state.currentPage;
-        if (state.pageSize !== void 0) payload.page_size = state.pageSize;
-        if (state.totalPages !== void 0) payload.total_pages = state.totalPages;
+        if (executionState.order) payload.sort_by = executionState.order;
+        if (executionState.currentPage !== void 0) payload.current_page = executionState.currentPage;
+        if (executionState.pageSize !== void 0) payload.page_size = executionState.pageSize;
+        if (executionState.totalPages !== void 0) payload.total_pages = executionState.totalPages;
         if (columns) payload.columns = columns;
         const sql = buildUpdateDebugSql(payload);
+        const debugAst = debugAstEnabled ? buildUpdateDebugAst({
+          state: executionState,
+          payload
+        }) : void 0;
         return executeWithQueryTrace(
           tracer,
           {
@@ -6125,6 +7381,7 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
             table: resolvedTableName,
             sql,
             payload,
+            ast: debugAst,
             options: mergedOptions
           },
           async () => {
@@ -6148,6 +7405,11 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
       }
       const mutationCallsite = captureTraceCallsite(tracer);
       const executeDelete = async (columns, selectOptions, callsite) => {
+        const executionState = snapshotState();
+        const debugState = {
+          ...executionState,
+          conditions: filters ? filters.map((condition) => ({ ...condition })) : []
+        };
         const mergedOptions = mergeOptions(options, selectOptions);
         const resolvedTableName = resolveTableNameForCall(tableName, mergedOptions?.schema);
         const payload = {
@@ -6155,12 +7417,16 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
           resource_id: resourceId,
           conditions: filters
         };
-        if (state.order) payload.sort_by = state.order;
-        if (state.currentPage !== void 0) payload.current_page = state.currentPage;
-        if (state.pageSize !== void 0) payload.page_size = state.pageSize;
-        if (state.totalPages !== void 0) payload.total_pages = state.totalPages;
+        if (executionState.order) payload.sort_by = executionState.order;
+        if (executionState.currentPage !== void 0) payload.current_page = executionState.currentPage;
+        if (executionState.pageSize !== void 0) payload.page_size = executionState.pageSize;
+        if (executionState.totalPages !== void 0) payload.total_pages = executionState.totalPages;
         if (columns) payload.columns = columns;
         const sql = buildDeleteDebugSql(payload);
+        const debugAst = debugAstEnabled ? buildDeleteDebugAst({
+          state: debugState,
+          payload
+        }) : void 0;
         return executeWithQueryTrace(
           tracer,
           {
@@ -6169,6 +7435,7 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
             table: resolvedTableName,
             sql,
             payload,
+            ast: debugAst,
             options: mergedOptions
           },
           async () => {
@@ -6196,6 +7463,7 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
   return builder;
 }
 function createQueryBuilder(client, formatGatewayResult, experimental, tracer) {
+  const debugAstEnabled = Boolean(experimental?.debugAst);
   return async function query(query, options) {
     const normalizedQuery = query.trim();
     if (!normalizedQuery) {
@@ -6212,6 +7480,7 @@ function createQueryBuilder(client, formatGatewayResult, experimental, tracer) {
           endpoint: "/gateway/query",
           sql: normalizedQuery,
           payload,
+          ast: debugAstEnabled ? buildRawQueryDebugAst(normalizedQuery) : void 0,
           options
         },
         async () => {
@@ -6223,6 +7492,63 @@ function createQueryBuilder(client, formatGatewayResult, experimental, tracer) {
     );
   };
 }
+function resolveClientServiceBaseUrl(value, label) {
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  return normalizeAthenaGatewayBaseUrl(value, { label });
+}
+function appendServicePath(baseUrl, segment) {
+  const normalizedBaseUrl = normalizeAthenaGatewayBaseUrl(baseUrl, { label: "Athena public base URL" });
+  return `${normalizedBaseUrl}/${segment.replace(/^\/+/, "")}`;
+}
+function resolveServiceUrlOverride(value, label) {
+  return resolveClientServiceBaseUrl(value, label);
+}
+function resolveServiceUrls(config) {
+  const baseUrl = resolveClientServiceBaseUrl(config.url, "Athena public base URL");
+  return {
+    dbUrl: resolveServiceUrlOverride(config.db?.url, "Athena DB base URL") ?? resolveServiceUrlOverride(config.gateway?.url, "Athena gateway base URL") ?? resolveServiceUrlOverride(config.dbUrl, "Athena DB base URL") ?? resolveServiceUrlOverride(config.gatewayUrl, "Athena gateway base URL") ?? (baseUrl ? appendServicePath(baseUrl, "db") : void 0),
+    authUrl: resolveServiceUrlOverride(config.auth?.url, "Athena auth base URL") ?? resolveServiceUrlOverride(config.auth?.baseUrl, "Athena auth base URL") ?? resolveServiceUrlOverride(config.authUrl, "Athena auth base URL") ?? (baseUrl ? appendServicePath(baseUrl, "auth") : void 0),
+    storageUrl: resolveServiceUrlOverride(config.storage?.url, "Athena storage base URL") ?? resolveServiceUrlOverride(config.storageUrl, "Athena storage base URL") ?? (baseUrl ? appendServicePath(baseUrl, "storage") : void 0)
+  };
+}
+function normalizeAuthClientConfig(auth, defaultBaseUrl) {
+  if (!auth && defaultBaseUrl === void 0) {
+    return void 0;
+  }
+  const { url, ...rest } = auth ?? {};
+  const normalized = {
+    ...rest
+  };
+  const resolvedBaseUrl = resolveClientServiceBaseUrl(
+    url ?? rest.baseUrl ?? defaultBaseUrl,
+    "Athena auth base URL"
+  );
+  if (resolvedBaseUrl !== void 0) {
+    normalized.baseUrl = resolvedBaseUrl;
+  }
+  return normalized;
+}
+function resolveCreateClientConfig(config) {
+  const resolvedUrls = resolveServiceUrls(config);
+  if (!resolvedUrls.dbUrl) {
+    throw new Error(
+      "Athena DB base URL is required. Pass createClient(url, key) for a unified root, or set db.url / gateway.url / gatewayUrl explicitly."
+    );
+  }
+  return {
+    baseUrl: resolvedUrls.dbUrl,
+    apiKey: config.key,
+    client: config.client,
+    backend: toBackendConfig(config.backend),
+    headers: config.headers,
+    auth: config.auth,
+    authUrl: resolvedUrls.authUrl,
+    storageUrl: resolvedUrls.storageUrl,
+    experimental: config.experimental
+  };
+}
 function createClientFromConfig(config) {
   const gatewayHeaders = {
     ...config.headers ?? {}
@@ -6239,184 +7565,112 @@ function createClientFromConfig(config) {
   });
   const formatGatewayResult = createResultFormatter(config.experimental);
   const queryTracer = createQueryTracer(config.experimental);
-  const auth = createAuthClient(config.auth);
-  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) {
-      throw new Error("rpc requires a function name");
+  const auth = createAuthClient(normalizeAuthClientConfig(config.auth, config.authUrl));
+  function from(tableOrModel, options) {
+    if (isAthenaModelTarget(tableOrModel)) {
+      if (options?.schema !== void 0) {
+        throw new Error(
+          "from(model) does not accept a schema override because the model already defines its target."
+        );
+      }
+      return createTableBuilder(
+        resolveAthenaModelTargetTableName(tableOrModel),
+        gateway,
+        formatGatewayResult,
+        queryTracer,
+        config.experimental
+      );
     }
-    return createRpcBuilder(
-      normalizedFn,
-      args,
-      options,
+    const resolvedTableName = resolveTableNameForCall(tableOrModel, options?.schema);
+    return createTableBuilder(
+      resolvedTableName,
       gateway,
       formatGatewayResult,
       queryTracer,
-      captureTraceCallsite(queryTracer)
+      config.experimental
     );
-  };
-  const query = createQueryBuilder(gateway, formatGatewayResult, config.experimental, queryTracer);
-  const db = createDbModule({ from, rpc, query });
-  const sdkClient = {
-    from,
-    db,
-    rpc,
-    query,
-    verifyConnection: gateway.verifyConnection,
-    auth: auth.auth
-  };
-  if (config.experimental?.athenaStorageBackend) {
-    const storageClient = {
-      ...sdkClient,
-      storage: createStorageModule(gateway, config.experimental.storage)
-    };
-    return storageClient;
-  }
-  return sdkClient;
-}
-var DEFAULT_BACKEND = { type: "athena" };
-function toBackendConfig(b) {
-  if (!b) return DEFAULT_BACKEND;
-  return typeof b === "string" ? { type: b } : b;
-}
-function mergeAuthClientConfig(current, next) {
-  const merged = {
-    ...current ?? {},
-    ...next
-  };
-  if (current?.headers || next.headers) {
-    merged.headers = {
-      ...current?.headers ?? {},
-      ...next.headers ?? {}
-    };
-  }
-  return merged;
-}
-function mergeExperimentalOptions(current, next) {
-  const merged = {
-    ...current ?? {},
-    ...next
-  };
-  if (current?.traceQueries && typeof current.traceQueries === "object" && next.traceQueries && typeof next.traceQueries === "object") {
-    merged.traceQueries = {
-      ...current.traceQueries,
-      ...next.traceQueries
-    };
   }
-  if (current?.storage || next.storage) {
-    merged.storage = {
-      ...current?.storage ?? {},
-      ...next.storage ?? {}
-    };
-  }
-  return merged;
-}
-var AthenaClientBuilderImpl = class {
-  baseUrl;
-  apiKey;
-  backendConfig = DEFAULT_BACKEND;
-  clientName;
-  defaultHeaders;
-  authConfig;
-  experimentalOptions;
-  url(url) {
-    this.baseUrl = url;
-    return this;
-  }
-  key(apiKey) {
-    this.apiKey = apiKey;
-    return this;
-  }
-  backend(backend) {
-    this.backendConfig = toBackendConfig(backend);
-    return this;
-  }
-  client(clientName) {
-    this.clientName = clientName;
-    return this;
-  }
-  headers(headers) {
-    this.defaultHeaders = headers;
-    return this;
-  }
-  auth(config) {
-    this.authConfig = mergeAuthClientConfig(this.authConfig, config);
-    return this;
-  }
-  experimental(options) {
-    this.experimentalOptions = mergeExperimentalOptions(this.experimentalOptions, options);
-    return options.athenaStorageBackend ? this : this;
-  }
-  options(options) {
-    if (options.client !== void 0) {
-      this.clientName = options.client;
-    }
-    if (options.backend !== void 0) {
-      this.backendConfig = toBackendConfig(options.backend);
-    }
-    if (options.headers !== void 0) {
-      this.defaultHeaders = {
-        ...this.defaultHeaders ?? {},
-        ...options.headers
-      };
-    }
-    if (options.auth !== void 0) {
-      this.authConfig = mergeAuthClientConfig(this.authConfig, options.auth);
-    }
-    if (options.experimental !== void 0) {
-      this.experimentalOptions = mergeExperimentalOptions(this.experimentalOptions, options.experimental);
-    }
-    return options.experimental?.athenaStorageBackend ? this : this;
-  }
-  build() {
-    if (!this.baseUrl || !this.apiKey) {
-      throw new Error("AthenaClient requires url and key; call .url() and .key() before .build()");
+  const rpc = (fn, args, options) => {
+    const normalizedFn = fn.trim();
+    if (!normalizedFn) {
+      throw new Error("rpc requires a function name");
     }
-    return createClientFromConfig({
-      baseUrl: this.baseUrl,
-      apiKey: this.apiKey,
-      client: this.clientName,
-      backend: this.backendConfig,
-      headers: this.defaultHeaders,
-      auth: this.authConfig,
-      experimental: this.experimentalOptions
-    });
+    return createRpcBuilder(
+      normalizedFn,
+      args,
+      options,
+      gateway,
+      formatGatewayResult,
+      queryTracer,
+      captureTraceCallsite(queryTracer),
+      Boolean(config.experimental?.debugAst)
+    );
+  };
+  const query = createQueryBuilder(
+    gateway,
+    formatGatewayResult,
+    config.experimental,
+    queryTracer
+  );
+  const db = createDbModule({ from, rpc, query });
+  const sdkClient = {
+    from,
+    db,
+    rpc,
+    query,
+    verifyConnection: gateway.verifyConnection,
+    auth: auth.auth
+  };
+  if (config.experimental?.athenaStorageBackend) {
+    const storageClient = {
+      ...sdkClient,
+      storage: createStorageModule(gateway, {
+        ...config.experimental.storage,
+        ...config.storageUrl ? {
+          baseUrl: config.storageUrl,
+          stripBasePath: true
+        } : {}
+      })
+    };
+    return storageClient;
   }
-};
-var AthenaClient = class _AthenaClient {
+  return sdkClient;
+}
+var AthenaClient = class {
   /** Create a fluent builder for a strongly-typed Athena SDK client. */
   static builder() {
-    return new AthenaClientBuilderImpl();
+    return createAthenaClientBuilder((config) => createClientFromConfig(resolveCreateClientConfig(config)));
   }
   /** Build a client from process environment variables. */
   static fromEnvironment() {
-    const url = process.env.ATHENA_URL ?? process.env.ATHENA_GATEWAY_URL;
+    const url = process.env.ATHENA_URL;
+    const gatewayUrl = process.env.ATHENA_DB_URL ?? process.env.ATHENA_GATEWAY_URL;
+    const authUrl = process.env.ATHENA_AUTH_URL;
+    const storageUrl = process.env.ATHENA_STORAGE_URL;
     const key = process.env.ATHENA_API_KEY ?? process.env.ATHENA_GATEWAY_API_KEY;
-    if (!url || !key) {
+    if (!url && !gatewayUrl || !key) {
       throw new Error(
-        "ATHENA_URL and ATHENA_API_KEY (or ATHENA_GATEWAY_URL and ATHENA_GATEWAY_API_KEY) are required"
+        "ATHENA_API_KEY plus ATHENA_URL or ATHENA_GATEWAY_URL (optionally ATHENA_DB_URL, ATHENA_AUTH_URL, ATHENA_STORAGE_URL) are required"
       );
     }
-    return _AthenaClient.builder().url(url).key(key).build();
+    return createClient({
+      url,
+      gatewayUrl,
+      authUrl,
+      storageUrl,
+      key
+    });
   }
 };
-function createClient(url, apiKey, options) {
-  return createClientFromConfig({
-    baseUrl: url,
-    apiKey,
-    client: options?.client,
-    backend: toBackendConfig(options?.backend),
-    headers: options?.headers,
-    auth: options?.auth,
-    experimental: options?.experimental
-  });
+function createClient(configOrUrl, apiKey, options) {
+  if (typeof configOrUrl === "string") {
+    return createClientFromConfig(resolveCreateClientConfig({
+      url: configOrUrl,
+      key: apiKey ?? "",
+      ...options
+    }));
+  }
+  return createClientFromConfig(resolveCreateClientConfig(configOrUrl));
 }
 
 // src/gateway/types.ts
@@ -6441,6 +7695,379 @@ function defineRegistry(databases) {
   return databases;
 }
 
+// src/schema/model-form.ts
+function resolveNullishValue(mode) {
+  if (mode === "undefined") return void 0;
+  if (mode === "null") return null;
+  return "";
+}
+function isRecord10(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isNullableColumn(model, key) {
+  const nullable = model.meta.nullable;
+  return nullable?.[key] === true;
+}
+function toModelFormDefaults(model, values, options) {
+  const source = values;
+  if (!isRecord10(source)) {
+    return {};
+  }
+  const mode = options?.nullishMode ?? "empty-string";
+  const nullishValue = resolveNullishValue(mode);
+  const result = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (value === null && isNullableColumn(model, key)) {
+      result[key] = nullishValue;
+      continue;
+    }
+    result[key] = value;
+  }
+  return result;
+}
+function toModelPayload(model, formValues, options) {
+  const emptyStringAsNull = options?.emptyStringAsNull ?? true;
+  const stripUndefined = options?.stripUndefined ?? true;
+  const result = {};
+  for (const [key, rawValue] of Object.entries(formValues)) {
+    if (rawValue === void 0 && stripUndefined) {
+      continue;
+    }
+    if (emptyStringAsNull && rawValue === "" && isNullableColumn(model, key)) {
+      result[key] = null;
+      continue;
+    }
+    result[key] = rawValue;
+  }
+  return result;
+}
+function createModelFormAdapter(model) {
+  return {
+    model,
+    toDefaults(values, options) {
+      return toModelFormDefaults(model, values, options);
+    },
+    toInsert(values, options) {
+      return toModelPayload(model, values, options);
+    },
+    toUpdate(values, options) {
+      return toModelPayload(model, values, options);
+    }
+  };
+}
+
+// src/schema/table-columns.ts
+var COLUMN_CONFIG = /* @__PURE__ */ Symbol("athena.column.config");
+function createColumnBuilder(config) {
+  return {
+    [COLUMN_CONFIG]: config,
+    optional() {
+      return createColumnBuilder({
+        ...config,
+        nullable: true
+      });
+    },
+    from(columnName) {
+      return createColumnBuilder({
+        ...config,
+        columnName
+      });
+    },
+    defaulted() {
+      return createColumnBuilder({
+        ...config,
+        hasDefault: true
+      });
+    },
+    generated() {
+      return createColumnBuilder({
+        ...config,
+        isGenerated: true
+      });
+    }
+  };
+}
+function isColumnBuilder(value) {
+  return value !== null && typeof value === "object" && COLUMN_CONFIG in value;
+}
+function getColumnConfig(column) {
+  return column[COLUMN_CONFIG];
+}
+function string() {
+  return createColumnBuilder({
+    kind: "string",
+    nullable: false,
+    hasDefault: false,
+    isGenerated: false
+  });
+}
+function number() {
+  return createColumnBuilder({
+    kind: "number",
+    nullable: false,
+    hasDefault: false,
+    isGenerated: false
+  });
+}
+function boolean() {
+  return createColumnBuilder({
+    kind: "boolean",
+    nullable: false,
+    hasDefault: false,
+    isGenerated: false
+  });
+}
+function json(schema) {
+  return createColumnBuilder({
+    kind: "json",
+    nullable: false,
+    hasDefault: false,
+    isGenerated: false,
+    jsonSchema: schema
+  });
+}
+function enumeration(values) {
+  if (values.length === 0) {
+    throw new Error("enumeration() requires at least one value");
+  }
+  return createColumnBuilder({
+    kind: "enumeration",
+    nullable: false,
+    hasDefault: false,
+    isGenerated: false,
+    enumValues: values
+  });
+}
+
+// src/schema/table-schemas.ts
+function isScalarFormKind(kind) {
+  return kind === "string" || kind === "number" || kind === "boolean" || kind === "enumeration";
+}
+function createBaseSchema(column) {
+  const config = getColumnConfig(column);
+  switch (config.kind) {
+    case "boolean":
+      return zod.z.boolean();
+    case "number":
+      return zod.z.number();
+    case "json":
+      return config.jsonSchema ?? zod.z.unknown();
+    case "enumeration":
+      if (!config.enumValues || config.enumValues.length === 0) {
+        return zod.z.string();
+      }
+      return zod.z.enum(config.enumValues);
+    case "string":
+    default:
+      return zod.z.string();
+  }
+}
+function applyNullable(schema, column) {
+  const config = getColumnConfig(column);
+  return config.nullable ? schema.nullable() : schema;
+}
+function applyInsertOptional(schema, column) {
+  const config = getColumnConfig(column);
+  return config.nullable || config.hasDefault ? schema.optional() : schema;
+}
+function createFormFieldSchema(column) {
+  const config = getColumnConfig(column);
+  const base = createBaseSchema(column);
+  let schema;
+  if (config.nullable && isScalarFormKind(config.kind)) {
+    schema = zod.z.union([base, zod.z.literal("")]).transform((value) => value === "" ? null : value);
+  } else {
+    schema = applyNullable(base, column);
+  }
+  if (config.nullable || config.hasDefault) {
+    schema = schema.optional();
+  }
+  return schema;
+}
+function buildTableSchemaBundle(model, columns) {
+  const rowShape = {};
+  const insertShape = {};
+  const updateShape = {};
+  const formShape = {};
+  for (const [columnName, column] of Object.entries(columns)) {
+    const config = getColumnConfig(column);
+    const base = createBaseSchema(column);
+    rowShape[columnName] = applyNullable(base, column);
+    if (config.isGenerated) {
+      continue;
+    }
+    insertShape[columnName] = applyInsertOptional(applyNullable(base, column), column);
+    updateShape[columnName] = applyNullable(base, column).optional();
+    formShape[columnName] = createFormFieldSchema(column);
+  }
+  const rowSchema = zod.z.object(rowShape);
+  const insertSchema = zod.z.object(insertShape);
+  const updateSchema = zod.z.object(updateShape);
+  const formSchema = zod.z.object(formShape).transform((value) => toModelPayload(model, value));
+  return {
+    row: rowSchema,
+    insert: insertSchema,
+    update: updateSchema,
+    form: formSchema
+  };
+}
+
+// src/schema/table-builder.ts
+function assertColumnRecord(columns) {
+  for (const [columnName, column] of Object.entries(columns)) {
+    if (!isColumnBuilder(column)) {
+      throw new Error(`Invalid column definition for "${columnName}"`);
+    }
+  }
+}
+function normalizeMappedNameInput(mappedName) {
+  const normalized = mappedName.trim();
+  if (!normalized) {
+    throw new Error("table.from() requires a non-empty table name");
+  }
+  return normalized;
+}
+function normalizeSchemaNameInput(schemaName) {
+  const normalized = schemaName.trim();
+  if (!normalized) {
+    throw new Error("table.schema() requires a non-empty schema name");
+  }
+  if (normalized.includes(".")) {
+    throw new Error(
+      'table.schema() expects a schema name without dots. Use .schema("schema").from("table") or .from("schema.table").'
+    );
+  }
+  return normalized;
+}
+function resolveTableTarget(logicalName, mappedName, explicitSchemaName) {
+  const physicalName = (mappedName ?? logicalName).trim();
+  if (!physicalName) {
+    throw new Error("table() requires a non-empty name");
+  }
+  const firstDot = physicalName.indexOf(".");
+  const lastDot = physicalName.lastIndexOf(".");
+  if (firstDot > 0 && firstDot === lastDot) {
+    const inlineSchema = physicalName.slice(0, firstDot).trim();
+    const inlineModel = physicalName.slice(firstDot + 1).trim();
+    if (!inlineSchema || !inlineModel) {
+      throw new Error('table.from() schema-qualified names must look like "schema.table"');
+    }
+    if (explicitSchemaName && explicitSchemaName !== inlineSchema) {
+      throw new Error(
+        `table schema "${explicitSchemaName}" conflicts with mapped table "${physicalName}"`
+      );
+    }
+    return {
+      schema: explicitSchemaName ?? inlineSchema,
+      model: inlineModel,
+      qualifiedName: `${explicitSchemaName ?? inlineSchema}.${inlineModel}`
+    };
+  }
+  if (explicitSchemaName) {
+    return {
+      schema: explicitSchemaName,
+      model: physicalName,
+      qualifiedName: `${explicitSchemaName}.${physicalName}`
+    };
+  }
+  return {
+    model: physicalName,
+    qualifiedName: physicalName
+  };
+}
+function toColumnMetadata(column) {
+  const config = getColumnConfig(column);
+  return {
+    kind: config.kind,
+    columnName: config.columnName,
+    nullable: config.nullable,
+    hasDefault: config.hasDefault,
+    isGenerated: config.isGenerated,
+    enumValues: config.enumValues
+  };
+}
+function buildNullableMap(columns) {
+  return Object.fromEntries(
+    Object.entries(columns).map(([columnName, column]) => [columnName, getColumnConfig(column).nullable])
+  );
+}
+function buildColumnMetadataMap(columns) {
+  return Object.fromEntries(
+    Object.entries(columns).map(([columnName, column]) => [columnName, toColumnMetadata(column)])
+  );
+}
+function finalizeTable(name, mappedName, schemaName, columns, primaryKey) {
+  const target = resolveTableTarget(name, mappedName, schemaName);
+  const model = defineModel({
+    meta: {
+      schema: target.schema,
+      model: target.model,
+      primaryKey: [...primaryKey],
+      nullable: buildNullableMap(columns),
+      columns: buildColumnMetadataMap(columns)
+    }
+  });
+  const schemas = buildTableSchemaBundle(model, columns);
+  return Object.assign(model, {
+    kind: "table",
+    name,
+    mappedName,
+    schemaName: target.schema,
+    tableName: target.model,
+    qualifiedName: target.qualifiedName,
+    columns,
+    schemas
+  });
+}
+function createColumnsBuilder(name, mappedName, schemaName, columns) {
+  assertColumnRecord(columns);
+  return {
+    name,
+    mappedName,
+    schemaName,
+    columns,
+    from(tableName) {
+      const normalizedTableName = normalizeMappedNameInput(tableName);
+      resolveTableTarget(name, normalizedTableName, schemaName);
+      return createColumnsBuilder(name, normalizedTableName, schemaName, columns);
+    },
+    schema(nextSchemaName) {
+      const normalizedSchemaName = normalizeSchemaNameInput(nextSchemaName);
+      resolveTableTarget(name, mappedName, normalizedSchemaName);
+      return createColumnsBuilder(name, mappedName, normalizedSchemaName, columns);
+    },
+    primaryKey(...keys) {
+      return finalizeTable(name, mappedName, schemaName, columns, keys);
+    }
+  };
+}
+function createTableBuilder2(name, mappedName, schemaName) {
+  return {
+    name,
+    mappedName,
+    schemaName,
+    from(tableName) {
+      const normalizedTableName = normalizeMappedNameInput(tableName);
+      resolveTableTarget(name, normalizedTableName, schemaName);
+      return createTableBuilder2(name, normalizedTableName, schemaName);
+    },
+    schema(nextSchemaName) {
+      const normalizedSchemaName = normalizeSchemaNameInput(nextSchemaName);
+      resolveTableTarget(name, mappedName, normalizedSchemaName);
+      return createTableBuilder2(name, mappedName, normalizedSchemaName);
+    },
+    columns(columns) {
+      return createColumnsBuilder(name, mappedName, schemaName, columns);
+    }
+  };
+}
+function table(name) {
+  if (!name.trim()) {
+    throw new Error("table() requires a non-empty name");
+  }
+  return createTableBuilder2(name, void 0, void 0);
+}
+
 // src/schema/typed-client.ts
 var TenantHeaderMapper = class {
   constructor(tenantKeyMap) {
@@ -6480,12 +8107,10 @@ var RegistryNavigator = class {
     return modelDef;
   }
   resolveTableName(schema, model, modelDef) {
-    if (modelDef.meta.tableName) {
-      return modelDef.meta.tableName;
-    }
-    const schemaName = modelDef.meta.schema ?? schema;
-    const modelName = modelDef.meta.model ?? model;
-    return `${schemaName}.${modelName}`;
+    return resolveAthenaModelTargetTableName(modelDef, {
+      fallbackSchema: schema,
+      fallbackModel: model
+    });
   }
 };
 var TypedAthenaClientImpl = class _TypedAthenaClientImpl {
@@ -6512,17 +8137,20 @@ var TypedAthenaClientImpl = class _TypedAthenaClientImpl {
     this.clientOptions = {
       backend: input.options?.backend,
       client: input.options?.client,
-      headers: input.options?.headers
+      headers: input.options?.headers,
+      experimental: input.options?.experimental
     };
     this.baseClient = createClient(this.url, this.apiKey, {
       backend: this.clientOptions.backend,
       client: this.clientOptions.client,
-      headers: this.tenantHeaderMapper.apply(this.clientOptions.headers, tenantContext)
+      headers: this.tenantHeaderMapper.apply(this.clientOptions.headers, tenantContext),
+      experimental: this.clientOptions.experimental
     });
     this.db = this.baseClient.db;
   }
-  from(table, options) {
-    return this.baseClient.from(table, options);
+  from(tableOrModel, options) {
+    const from = this.baseClient.from;
+    return from(tableOrModel, options);
   }
   rpc(fn, args, options) {
     return this.baseClient.rpc(fn, args, options);
@@ -6544,7 +8172,8 @@ var TypedAthenaClientImpl = class _TypedAthenaClientImpl {
         tenantContext: {
           ...this.tenantContext,
           ...context ?? {}
-        }
+        },
+        experimental: this.clientOptions.experimental
       }
     });
   }
@@ -6563,67 +8192,6 @@ function createTypedClient(registry, url, apiKey, options) {
   });
 }
 
-// src/schema/model-form.ts
-function resolveNullishValue(mode) {
-  if (mode === "undefined") return void 0;
-  if (mode === "null") return null;
-  return "";
-}
-function isRecord9(value) {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-function isNullableColumn(model, key) {
-  const nullable = model.meta.nullable;
-  return nullable?.[key] === true;
-}
-function toModelFormDefaults(model, values, options) {
-  const source = values;
-  if (!isRecord9(source)) {
-    return {};
-  }
-  const mode = options?.nullishMode ?? "empty-string";
-  const nullishValue = resolveNullishValue(mode);
-  const result = {};
-  for (const [key, value] of Object.entries(source)) {
-    if (value === null && isNullableColumn(model, key)) {
-      result[key] = nullishValue;
-      continue;
-    }
-    result[key] = value;
-  }
-  return result;
-}
-function toModelPayload(model, formValues, options) {
-  const emptyStringAsNull = options?.emptyStringAsNull ?? true;
-  const stripUndefined = options?.stripUndefined ?? true;
-  const result = {};
-  for (const [key, rawValue] of Object.entries(formValues)) {
-    if (rawValue === void 0 && stripUndefined) {
-      continue;
-    }
-    if (emptyStringAsNull && rawValue === "" && isNullableColumn(model, key)) {
-      result[key] = null;
-      continue;
-    }
-    result[key] = rawValue;
-  }
-  return result;
-}
-function createModelFormAdapter(model) {
-  return {
-    model,
-    toDefaults(values, options) {
-      return toModelFormDefaults(model, values, options);
-    },
-    toInsert(values, options) {
-      return toModelPayload(model, values, options);
-    },
-    toUpdate(values, options) {
-      return toModelPayload(model, values, options);
-    }
-  };
-}
-
 // src/generator/schema-selection.ts
 var DEFAULT_POSTGRES_SCHEMAS = ["public"];
 function collectSchemaNames(input) {
@@ -6918,15 +8486,15 @@ function readCookieFromHeaders(headers, name) {
   }
   return parseCookies(cookieHeader).get(name);
 }
-function isRecord10(value) {
+function isRecord11(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function resolveSessionCandidate(value) {
-  if (!isRecord10(value)) {
+  if (!isRecord11(value)) {
     return null;
   }
-  const session = isRecord10(value.session) ? value.session : void 0;
-  const user = isRecord10(value.user) ? value.user : void 0;
+  const session = isRecord11(value.session) ? value.session : void 0;
+  const user = isRecord11(value.user) ? value.user : void 0;
   if (session && typeof session.token === "string" && session.token.length > 0 && user) {
     return {
       session,
@@ -6936,7 +8504,7 @@ function resolveSessionCandidate(value) {
   return null;
 }
 function inferSessionPair(returned) {
-  return resolveSessionCandidate(returned) ?? (isRecord10(returned) ? resolveSessionCandidate(returned.data) : null) ?? (isRecord10(returned) ? resolveSessionCandidate(returned.session) : null);
+  return resolveSessionCandidate(returned) ?? (isRecord11(returned) ? resolveSessionCandidate(returned.data) : null) ?? (isRecord11(returned) ? resolveSessionCandidate(returned.session) : null);
 }
 function resolveResponseHeaders(ctx) {
   if (ctx.context.responseHeaders instanceof Headers) {
@@ -7324,6 +8892,7 @@ exports.Backend = Backend;
 exports.DEFAULT_POSTGRES_SCHEMAS = DEFAULT_POSTGRES_SCHEMAS;
 exports.assertInt = assertInt;
 exports.athenaAuth = athenaAuth;
+exports.boolean = boolean;
 exports.coerceInt = coerceInt;
 exports.createAthenaStorageError = createAthenaStorageError;
 exports.createAuthClient = createAuthClient;
@@ -7339,17 +8908,21 @@ exports.defineGeneratorConfig = defineGeneratorConfig;
 exports.defineModel = defineModel;
 exports.defineRegistry = defineRegistry;
 exports.defineSchema = defineSchema;
+exports.enumeration = enumeration;
 exports.findGeneratorConfigPath = findGeneratorConfigPath;
 exports.generateArtifactsFromSnapshot = generateArtifactsFromSnapshot;
 exports.generatorEnv = generatorEnv;
+exports.getAthenaDebugAst = getAthenaDebugAst;
 exports.identifier = identifier;
 exports.isAthenaGatewayError = isAthenaGatewayError;
 exports.isOk = isOk;
+exports.json = json;
 exports.loadGeneratorConfig = loadGeneratorConfig;
 exports.normalizeAthenaError = normalizeAthenaError;
 exports.normalizeAthenaGatewayBaseUrl = normalizeAthenaGatewayBaseUrl;
 exports.normalizeGeneratorConfig = normalizeGeneratorConfig;
 exports.normalizeSchemaSelection = normalizeSchemaSelection;
+exports.number = number;
 exports.parseBooleanFlag = parseBooleanFlag2;
 exports.renderAthenaReactEmail = renderAthenaReactEmail;
 exports.requireAffected = requireAffected;
@@ -7359,6 +8932,8 @@ exports.resolvePostgresColumnType = resolvePostgresColumnType;
 exports.resolveProviderSchemas = resolveProviderSchemas;
 exports.runSchemaGenerator = runSchemaGenerator;
 exports.storageSdkManifest = storageSdkManifest;
+exports.string = string;
+exports.table = table;
 exports.toModelFormDefaults = toModelFormDefaults;
 exports.toModelPayload = toModelPayload;
 exports.unwrap = unwrap;