@palbase/backend 33.0.2 → 34.1.0

package/dist/index.cjs

@@ -102,11 +102,13 @@ __export(src_exports, {
   __runWithRuntime: () => __runWithRuntime,
   __setRuntime: () => __setRuntime,
   assertNoOrphanEntryPoints: () => assertNoOrphanEntryPoints,
+  assertQueryManifest: () => assertQueryManifest,
   assertZeroArgConstructor: () => assertZeroArgConstructor,
   bigint: () => bigint,
   boolean: () => boolean,
   buildContainer: () => buildContainer,
   buildModuleClients: () => buildModuleClients,
+  can: () => can,
   col: () => col,
   controllersOf: () => controllersOf,
   dec: () => dec,
@@ -115,8 +117,10 @@ __export(src_exports, {
   defineDefaultAuth: () => defineDefaultAuth,
   defineError: () => defineError,
   defineMiddleware: () => defineMiddleware,
+  defineQuery: () => defineQuery,
   defineSchema: () => defineSchema,
   defineTable: () => defineTable,
+  defineWorkload: () => defineWorkload,
   enumType: () => enumType,
   exprCtx: () => exprCtx,
   getErrorRegistry: () => getErrorRegistry,
@@ -152,6 +156,7 @@ __export(src_exports, {
   ownerOnly: () => ownerOnly,
   policy: () => policy,
   publicChannel: () => publicChannel,
+  queryManifest: () => queryManifest,
   raw: () => raw,
   recordThrows: () => recordThrows,
   resolveEffectiveAuth: () => resolveEffectiveAuth,
@@ -165,7 +170,7 @@ __export(src_exports, {
   vector: () => vector,
   webhooksOf: () => webhooksOf,
   withRetry: () => withRetry,
-  z: () => import_zod2.z
+  z: () => import_zod4.z
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -741,260 +746,54 @@ function translateRejection(err, builder) {
 }
 __name(translateRejection, "translateRejection");
 
-// src/errors.ts
-var HTTP_ERROR_BRAND = /* @__PURE__ */ Symbol.for("palbase.backend.httpError");
-var HttpError = class extends Error {
-  static {
-    __name(this, "HttpError");
-  }
-  status;
-  error;
-  errorDescription;
-  data;
-  /** See {@link HTTP_ERROR_BRAND} — how the engine recognises this across SDK copies. */
-  [HTTP_ERROR_BRAND] = true;
-  constructor(status, error, errorDescription, data) {
-    super(errorDescription);
-    this.name = "HttpError";
-    this.status = status;
-    this.error = error;
-    this.errorDescription = errorDescription;
-    if (data !== void 0) {
-      this.data = data;
-    }
-  }
-  /**
-  * Serialize to the standard Palbase error response format.
-  * The `requestId` is injected by the runtime layer from the request context.
-  * When called without arguments (e.g. JSON.stringify), request_id is omitted.
-  * When `data` is set, it is appended as a strict-superset field.
-  */
-  toJSON(requestId) {
-    const result = {
-      error: this.error,
-      error_description: this.errorDescription,
-      status: this.status
-    };
-    if (requestId) {
-      result.request_id = requestId;
-    }
-    if (this.data !== void 0) {
-      result.data = this.data;
-    }
-    return result;
-  }
-};
-var PalError = class extends HttpError {
-  static {
-    __name(this, "PalError");
-  }
-  constructor(status, code, description, data) {
-    super(status, code, description, data);
-    this.name = "PalError";
-  }
-};
-var NamedHttpError = class NamedHttpError2 extends HttpError {
-  static {
-    __name(this, "NamedHttpError");
-  }
-  constructor(status, defaultCode, name, message, code, data) {
-    super(status, code ?? defaultCode, message ?? defaultMessage(name), data);
-    this.name = name;
-  }
-};
-function defaultMessage(name) {
-  const spaced = name.replace(/([a-z0-9])([A-Z])/g, "$1 $2");
-  return spaced.charAt(0).toUpperCase() + spaced.slice(1).toLowerCase();
-}
-__name(defaultMessage, "defaultMessage");
-var BadRequest = class extends NamedHttpError {
-  static {
-    __name(this, "BadRequest");
-  }
-  constructor(data, message) {
-    super(400, "bad_request", "BadRequest", message, void 0, data);
-  }
-};
-var Unauthorized = class extends NamedHttpError {
-  static {
-    __name(this, "Unauthorized");
-  }
-  constructor(message, code, data) {
-    super(401, "unauthorized", "Unauthorized", message, code, data);
-  }
-};
-var Forbidden = class extends NamedHttpError {
-  static {
-    __name(this, "Forbidden");
-  }
-  constructor(message, code, data) {
-    super(403, "forbidden", "Forbidden", message, code, data);
-  }
-};
-var NotFound = class extends NamedHttpError {
-  static {
-    __name(this, "NotFound");
-  }
-  constructor(message, code, data) {
-    super(404, "not_found", "NotFound", message, code, data);
-  }
-};
-var Conflict = class extends NamedHttpError {
-  static {
-    __name(this, "Conflict");
-  }
-  constructor(message, code, data) {
-    super(409, "conflict", "Conflict", message, code, data);
-  }
-};
-var UniqueViolation = class extends Conflict {
-  static {
-    __name(this, "UniqueViolation");
-  }
-  /**
-  * Whether `e` is a unique violation — REGARDLESS of which copy of this SDK
-  * constructed it.
-  *
-  * Use this instead of `instanceof`. Measured on a live stack: a controller
-  * bundle INLINES its own copy of `@palbase/backend`, and the engine that
-  * raises this error is the runtime's copy. Two copies, two class identities,
-  * and `e instanceof UniqueViolation` is false in the one place a caller
-  * writes it — a check that reads as correct and silently never matches.
-  */
-  static is(e) {
-    return typeof e === "object" && e !== null && e.name === "UniqueViolation" && typeof e.constraint === "string";
-  }
-  /** The unique constraint the statement violated, as Postgres named it.
-  * `""` when the driver did not say which — see `engine/db.ts`. */
-  constraint;
-  constructor(constraint, message, code, data) {
-    super(message ?? "Unique constraint violated", code ?? "unique_violation", data);
-    this.name = "UniqueViolation";
-    this.constraint = constraint;
-  }
-};
-function isRetryable(e) {
-  return typeof e === "object" && e !== null && e.retryable === true && typeof e.sqlstate === "string";
-}
-__name(isRetryable, "isRetryable");
-var SerializationFailure = class extends Conflict {
-  static {
-    __name(this, "SerializationFailure");
-  }
-  retryable = true;
-  sqlstate;
-  static is(e) {
-    return typeof e === "object" && e !== null && e.name === "SerializationFailure";
-  }
-  constructor(sqlstate = "40001", message, data) {
-    super(message ?? "i\u015Flem e\u015Fzamanl\u0131 bir i\u015Flemle serile\u015Ftirilemedi \u2014 ayn\u0131 i\u015Flemi ba\u015Ftan \xE7al\u0131\u015Ft\u0131r\u0131n ($transaction'a { retry: n } verebilirsiniz)", "serialization_failure", data);
-    this.name = "SerializationFailure";
-    this.sqlstate = sqlstate;
-  }
-};
-var DeadlockDetected = class extends Conflict {
-  static {
-    __name(this, "DeadlockDetected");
-  }
-  retryable = true;
-  sqlstate;
-  static is(e) {
-    return typeof e === "object" && e !== null && e.name === "DeadlockDetected";
-  }
-  constructor(sqlstate = "40P01", message, data) {
-    super(message ?? "deadlock: iki i\u015Flem birbirinin kilidini bekledi ve bu i\u015Flem iptal edildi \u2014 kilit s\u0131ras\u0131n\u0131 sabitlemek i\xE7in Database.$lockRows(tablo, id'ler) kullan\u0131n", "deadlock_detected", data);
-    this.name = "DeadlockDetected";
-    this.sqlstate = sqlstate;
-  }
-};
-var TooManyRequests = class extends NamedHttpError {
-  static {
-    __name(this, "TooManyRequests");
-  }
-  constructor(data, message) {
-    super(429, "too_many_requests", "TooManyRequests", message, void 0, data);
-  }
-};
-
-// src/db/typed-db.ts
-function makeTypedTable(name, raw2) {
-  return {
-    insert: /* @__PURE__ */ __name((data) => raw2.insert(name, data), "insert"),
-    aggregate: /* @__PURE__ */ __name((q) => raw2.aggregate(name, q), "aggregate"),
-    insertMany: /* @__PURE__ */ __name((rows, opts) => raw2.insertMany(name, rows, opts), "insertMany"),
-    put: /* @__PURE__ */ __name((q) => raw2.put(name, q.data, {
-      onConflict: q.onConflict
-    }), "put"),
-    update: /* @__PURE__ */ __name((q) => raw2.update(name, q.where.id, q.set), "update"),
-    delete: /* @__PURE__ */ __name((id) => raw2.delete(name, id), "delete"),
-    findById: /* @__PURE__ */ __name((id) => raw2.findById(name, id), "findById"),
-    findMany: /* @__PURE__ */ __name((q) => {
-      const { where, ...opts } = q ?? {};
-      return raw2.findMany(name, where, opts);
-    }, "findMany"),
-    updateMany: /* @__PURE__ */ __name((q) => raw2.updateMany(name, q.where, q.set, q.returning === void 0 ? void 0 : {
-      returning: q.returning
-    }), "updateMany"),
-    deleteMany: /* @__PURE__ */ __name((q) => raw2.deleteMany(name, q.where), "deleteMany"),
-    count: /* @__PURE__ */ __name((q) => raw2.count(name, q?.where), "count")
-  };
-}
-__name(makeTypedTable, "makeTypedTable");
-function makeTypedDB(schema, raw2) {
-  const tables = {};
-  for (const key of Object.keys(schema.tables)) {
-    const tableDef = schema.tables[key];
-    if (tableDef !== void 0) {
-      tables[key] = makeTypedTable(tableDef.name, raw2);
-    }
-  }
+// src/db/workload.ts
+function defineWorkload(name, options) {
   const result = {
-    tables,
-    transaction(fn) {
-      const builder = new TxPlanBuilder();
-      const planTables = {};
-      for (const key of Object.keys(schema.tables)) {
-        const tableDef = schema.tables[key];
-        if (tableDef !== void 0) planTables[key] = builder.table(tableDef.name);
-      }
-      return runTxPlan(raw2, {
-        tables: planTables
-      }, builder, fn);
-    }
+    name,
+    concurrency: options.concurrency,
+    queueLimit: options.queueLimit,
+    tenantConcurrency: options.tenantConcurrency ?? options.concurrency,
+    tenantQueueLimit: options.tenantQueueLimit ?? options.queueLimit,
+    queueTimeoutMs: options.queueTimeoutMs ?? 1e3,
+    tenantClaim: options.tenantClaim ?? "tenant_id"
   };
-  return result;
-}
-__name(makeTypedDB, "makeTypedDB");
-function col(name) {
-  return brandRef({
-    $col: name
-  }, "col");
-}
-__name(col, "col");
-async function withRetry(fn, opts = {}) {
-  const budget = opts.retry ?? 0;
-  let attempt = 0;
-  for (; ; ) {
-    try {
-      return await fn();
-    } catch (e) {
-      if (attempt >= budget || !isRetryable(e)) throw e;
-      attempt += 1;
-    }
+  validateWorkload(result);
+  return Object.freeze(result);
+}
+__name(defineWorkload, "defineWorkload");
+function validateWorkload(value) {
+  if (typeof value.name !== "string" || !/^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$/.test(value.name)) throw new Error("workload name must be 1\u201364 letters/digits/dots/dashes");
+  for (const name of [
+    "concurrency",
+    "tenantConcurrency",
+    "queueLimit",
+    "tenantQueueLimit",
+    "queueTimeoutMs"
+  ]) {
+    const n = value[name], min = name.endsWith("Limit") ? 0 : 1;
+    const max = name === "queueTimeoutMs" ? 6e4 : name.endsWith("Limit") ? 1e4 : 1e3;
+    if (!Number.isInteger(n) || n < min || n > max) throw new Error(`workload ${name} must be an integer between ${min} and ${max}`);
+  }
+  if (value.tenantConcurrency > value.concurrency || value.tenantQueueLimit > value.queueLimit) throw new Error("workload tenant limits cannot exceed global limits");
+  if (typeof value.tenantClaim !== "string" || !/^[a-zA-Z][a-zA-Z0-9_]{0,63}$/.test(value.tenantClaim)) throw new Error("workload tenantClaim must be a top-level claim name");
+}
+__name(validateWorkload, "validateWorkload");
+
+// src/db/transaction-options.ts
+function retryBudget(value) {
+  const n = value ?? 0;
+  if (!Number.isInteger(n) || n < 0 || n > 10) {
+    throw new Error("transaction retry must be an integer between 0 and 10");
   }
+  return n;
 }
-__name(withRetry, "withRetry");
-function sqlFragment(strings, ...values) {
-  return brandRef({
-    $sql: {
-      text: [
-        ...strings
-      ],
-      values
-    }
-  }, "sql");
+__name(retryBudget, "retryBudget");
+function assertPlanRetry(options) {
+  if (retryBudget(options?.retry) !== 0) {
+    throw new Error("Database.$transaction is a savepoint plan on the request transaction and cannot retry its snapshot or COMMIT. Use Database.$atomic(async tx => { ... }, { retry, isolation }) and put all decision reads and writes inside that callback.");
+  }
 }
-__name(sqlFragment, "sqlFragment");
+__name(assertPlanRetry, "assertPlanRetry");
 
 // src/db/schema-json.ts
 function defOf(column) {
@@ -1177,6 +976,11 @@ function tableToJSON(table, schemaName) {
     // drifts — the direction it drifted last time was "expose everything", and
     // the live proof was one user reading another's rows.
     rls: table.rls,
+    // KOŞAN SÜRÜMÜN SÖZÜ TELE ÇIKAR — yoksa daralma kapısı onu göremez.
+    // `ColumnJSON.ignored` ile aynı sözleşme: işaretlenmemişse alan YOK.
+    ...table.ignored === true ? {
+      ignored: true
+    } : {},
     policies: (table.policies ?? []).map(policyToJSON)
   };
   if (table.primaryKey !== void 0 && table.primaryKey.length > 0) {
@@ -1407,6 +1211,14 @@ function makeTableProxy(ops, prefix) {
         update: /* @__PURE__ */ __name((q) => ops().update(name, q.where.id, q.set), "update"),
         delete: /* @__PURE__ */ __name((id) => ops().delete(name, id), "delete"),
         findById: /* @__PURE__ */ __name((id) => ops().findById(name, id), "findById"),
+        findUnique: /* @__PURE__ */ __name((q) => ops().findUnique(name, q.where, {
+          select: q.select,
+          with: q.with
+        }), "findUnique"),
+        page: /* @__PURE__ */ __name((q) => {
+          const { where, ...opts } = q ?? {};
+          return ops().page(name, where, opts);
+        }, "page"),
         findMany: /* @__PURE__ */ __name((q) => {
           const { where, ...opts } = q ?? {};
           return ops().findMany(name, where, opts);
@@ -1444,10 +1256,16 @@ function makeTypedSurface(raw2) {
   const reco = raw2;
   const ops = {
     $query: /* @__PURE__ */ __name((sql, params) => raw2.query(sql, params), "$query"),
+    $diagnostics: /* @__PURE__ */ __name(() => raw2.diagnostics(), "$diagnostics"),
+    $readQuery: /* @__PURE__ */ __name((query) => raw2.readQuery(query), "$readQuery"),
+    $compileQuery: /* @__PURE__ */ __name((query) => raw2.compileQuery(query), "$compileQuery"),
+    $explainQuery: /* @__PURE__ */ __name((query) => raw2.explainQuery(query), "$explainQuery"),
     $insert: /* @__PURE__ */ __name((table, data) => raw2.insert(table, data), "$insert"),
     $update: /* @__PURE__ */ __name((table, id, data) => raw2.update(table, id, data), "$update"),
     $delete: /* @__PURE__ */ __name((table, id) => raw2.delete(table, id), "$delete"),
     $findById: /* @__PURE__ */ __name((table, id) => raw2.findById(table, id), "$findById"),
+    $findUnique: /* @__PURE__ */ __name((table, where, opts) => raw2.findUnique(table, where, opts), "$findUnique"),
+    $page: /* @__PURE__ */ __name((table, query, opts) => raw2.page(table, query, opts), "$page"),
     $findMany: /* @__PURE__ */ __name((table, query, opts) => raw2.findMany(table, query, opts), "$findMany"),
     $put: /* @__PURE__ */ __name((table, data, opts) => raw2.put(table, data, opts), "$put"),
     // `opts` İLETİLİR. Düşürüldüğü sürece `Database.$updateMany(t, w, s,
@@ -1470,16 +1288,51 @@ function makeTypedSurface(raw2) {
     $supersede: /* @__PURE__ */ __name((table, id, row) => raw2.supersede(table, id, row), "$supersede")
   };
   const base = Object.assign(ops, {
+    $atomic(fn, options) {
+      if (typeof raw2.atomic !== "function") {
+        throw new Error("This Database handle cannot open a root transaction; nested $atomic is not supported");
+      }
+      const parent = __requestALS.getStore();
+      let runtime2;
+      try {
+        runtime2 = __getRuntime();
+      } catch {
+      }
+      return raw2.atomic(async (tx) => {
+        const typed = makeTypedSurface(tx);
+        const invoke = /* @__PURE__ */ __name(() => fn(typed), "invoke");
+        if (!runtime2) return invoke();
+        const refuse2 = /* @__PURE__ */ __name(() => {
+          throw new Error("Database.$atomic owns one transaction and identity; nested roots and $asService are not allowed");
+        }, "refuse");
+        const ambient = Object.assign({}, tx, {
+          atomic: refuse2,
+          asService: refuse2
+        });
+        return __requestALS.run({
+          ...parent,
+          runtime: {
+            ...runtime2,
+            Database: ambient
+          }
+        }, invoke);
+      }, options);
+    },
     // Both surfaces get it: a savepoint on the service transaction is as useful
     // as one on the request's, and each is bound to its own connection.
     $attempt: /* @__PURE__ */ __name((fn) => raw2.attempt(fn), "$attempt"),
     $transaction(fn, opts) {
-      return withRetry(() => {
-        const builder = new TxPlanBuilder();
-        return runTxPlan(raw2, makeTxPlanHandle(builder), builder, fn);
-      }, opts ?? {});
-    }
-  });
+      assertPlanRetry(opts);
+      const builder = new TxPlanBuilder();
+      return runTxPlan(raw2, makeTxPlanHandle(builder), builder, fn);
+    },
+    $command(fn, options) {
+      const builder = new TxPlanBuilder();
+      return runTxPlan({
+        txPlan: /* @__PURE__ */ __name((plan) => raw2.command(plan, options), "txPlan")
+      }, makeTxPlanHandle(builder), builder, fn);
+    }
+  });
   return new Proxy(base, {
     get(target, prop, receiver) {
       if (prop === "tables") return makeTableProxy(() => reco, "");
@@ -2738,6 +2591,7 @@ function buildModuleClients(cfg) {
 __name(buildModuleClients, "buildModuleClients");
 
 // src/db/policy.ts
+var import_zod = require("zod");
 var PolicyExprRef = class _PolicyExprRef {
   static {
     __name(this, "PolicyExprRef");
@@ -2970,6 +2824,45 @@ function policy(name) {
   return new PolicyBuilder(name);
 }
 __name(policy, "policy");
+function can(table) {
+  const def = table;
+  if (typeof def.name !== "string" || def.columns === null || typeof def.columns !== "object" || !Array.isArray(def.policies)) {
+    throw new Error("can(<table>): expects the schema's table definition \u2014 can(publicSchema.tables.notes) \u2014 not the defineTable handle (`notes`)");
+  }
+  if (Object.prototype.hasOwnProperty.call(table.columns, "can")) {
+    throw new Error(`can(${table.name}): the table declares a column named "can", so the row carries that column and no policy echo \u2014 rename the column to get can`);
+  }
+  const rel = reservedCanRelation(table.name, table.columns);
+  if (rel !== null) {
+    throw new Error(`can(${table.name}): ${rel}`);
+  }
+  const names = table.policies.filter((p) => p.command === "update" && p.permissive !== false && Buffer.byteLength(`can:${p.name}`, "utf8") <= 63).map((p) => p.name);
+  if (names.length === 0) {
+    const all = table.policies.filter((p) => p.command === "all").map((p) => p.name);
+    const hint = all.length > 0 ? ` The table's ${all.map((n) => `"${n}"`).join(", ")} ${all.length === 1 ? "policy is" : "policies are"} for("all") \u2014 for("all") governs UPDATE but is not a named update policy and never appears in can.` : "";
+    throw new Error(`can(${table.name}): the table declares no update policy \u2014 there is nothing a row could echo. Name one with policy("<name>").for("update").using(\u2026) first.${hint}`);
+  }
+  return import_zod.z.array(import_zod.z.enum(names));
+}
+__name(can, "can");
+function reservedCanRelation(tableName, columns) {
+  if (tableName === "can") {
+    return `a table named "can" would put a relation named "can" on every parent it references \u2014 rename the table`;
+  }
+  for (const [col2, b] of Object.entries(columns)) {
+    const def = b._def;
+    if (def.referencesThunk === void 0 && def.selfRefColumn === void 0) continue;
+    if (def.reverseAs === "can") {
+      return `column "${col2}" names its reverse relation "can" \u2014 the parent's rows would carry a relation where can is reserved; pick another reverseAs`;
+    }
+    const forward = def.owns === true ? "owner" : def.refAs ?? (col2.endsWith("_id") ? col2.slice(0, -3) : col2);
+    if (forward === "can") {
+      return `column "${col2}" would be read as a relation named "can" (${def.refAs === void 0 ? "derived from the column name" : "its as: option"}) \u2014 can is reserved for the policy echo; rename it`;
+    }
+  }
+  return null;
+}
+__name(reservedCanRelation, "reservedCanRelation");
 
 // src/db/schema.ts
 var IndexBuilder = class {
@@ -3047,6 +2940,10 @@ function defineTable(name, input) {
   if (name.trim() === "") {
     throw new Error("defineTable(name, \u2026): name must not be empty");
   }
+  {
+    const reserved = reservedCanRelation(name, input.columns);
+    if (reserved !== null) throw new Error(`defineTable(${JSON.stringify(name)}): ${reserved}`);
+  }
   const policies = (input.policies?.(exprCtx(Object.keys(input.columns), 0, name)) ?? []).map(toPolicyDef);
   const rls = policies.length > 0 || input.rls !== false;
   const owned2 = {};
@@ -3075,6 +2972,7 @@ function defineTable(name, input) {
   const declaredIndexes = (input.indexes?.(exprCtx(Object.keys(input.columns), 0, name)) ?? []).map((i) => i instanceof IndexBuilder ? i._def : i);
   if (declaredIndexes.length > 0) def.indexes = declaredIndexes;
   if (input.appendOnly === true) def.appendOnly = true;
+  if (input.ignored === true) def.ignored = true;
   if (input.search !== void 0) {
     const s = input.search;
     if (s.from !== void 0) {
@@ -3134,6 +3032,13 @@ function defineTable(name, input) {
 }
 __name(defineTable, "defineTable");
 var declaringSchemaOf = /* @__PURE__ */ new WeakMap();
+function declaredTableKey(table) {
+  const metadata = table[TABLE_META];
+  const schema = declaringSchemaOf.get(metadata);
+  if (schema === void 0) throw new Error(`defineQuery: table ${metadata.name} must belong to defineSchema before defining its query`);
+  return qualifiedTableKey(schema, metadata.name);
+}
+__name(declaredTableKey, "declaredTableKey");
 function resolveReferences(tables, schemaName) {
   for (const table of Object.values(tables)) {
     for (const [colName, builder] of Object.entries(table.columns)) {
@@ -3603,135 +3508,424 @@ var ColumnBuilder = class _ColumnBuilder {
       codec
     });
   }
-  transform(fns) {
-    if (this._def.codec !== void 0) {
-      throw new Error(`column already declares a named codec; .transform() and .as*() are two ways to say the same thing \u2014 keep the codec.`);
-    }
-    return new _ColumnBuilder(this._def.type, {
-      ...this._def,
-      transform: fns
-    });
+  transform(fns) {
+    if (this._def.codec !== void 0) {
+      throw new Error(`column already declares a named codec; .transform() and .as*() are two ways to say the same thing \u2014 keep the codec.`);
+    }
+    return new _ColumnBuilder(this._def.type, {
+      ...this._def,
+      transform: fns
+    });
+  }
+};
+function uuid() {
+  return new ColumnBuilder("uuid");
+}
+__name(uuid, "uuid");
+function text() {
+  return new ColumnBuilder("text");
+}
+__name(text, "text");
+function integer() {
+  return new ColumnBuilder("integer");
+}
+__name(integer, "integer");
+function bigint() {
+  return new ColumnBuilder("bigint");
+}
+__name(bigint, "bigint");
+function numeric() {
+  return new ColumnBuilder("numeric");
+}
+__name(numeric, "numeric");
+function boolean() {
+  return new ColumnBuilder("boolean");
+}
+__name(boolean, "boolean");
+function timestamp() {
+  return new ColumnBuilder("timestamp");
+}
+__name(timestamp, "timestamp");
+function jsonb() {
+  return new ColumnBuilder("jsonb");
+}
+__name(jsonb, "jsonb");
+function enumType(name, values) {
+  const builder = new ColumnBuilder("enum");
+  builder._def.enumName = name;
+  builder._def.enumValues = [
+    ...values
+  ];
+  return builder;
+}
+__name(enumType, "enumType");
+function vector(dimensions) {
+  if (!Number.isInteger(dimensions) || dimensions < 1 || dimensions > 2e3) {
+    throw new Error(`vector(): dimensions must be an integer in [1, 2000], got ${String(dimensions)}`);
+  }
+  const b = new ColumnBuilder("vector");
+  b._def.dimensions = dimensions;
+  return b;
+}
+__name(vector, "vector");
+function ownedByUser() {
+  const b = new ColumnBuilder("text");
+  b._def.nullable = false;
+  b._def.references = {
+    table: "auth.users",
+    column: "id"
+  };
+  b._def.onDeleteAction = "cascade";
+  b._def.owns = true;
+  return b;
+}
+__name(ownedByUser, "ownedByUser");
+function userRef(opts) {
+  const b = new ColumnBuilder("text");
+  b._def.references = {
+    table: "auth.users",
+    column: "id"
+  };
+  b._def.onDeleteAction = opts.onDelete;
+  if (opts.as !== void 0) b._def.refAs = opts.as;
+  return b;
+}
+__name(userRef, "userRef");
+function installationRef(opts) {
+  const b = new ColumnBuilder("text");
+  b._def.references = {
+    table: "auth.installations",
+    column: "id"
+  };
+  b._def.onDeleteAction = opts.onDelete;
+  if (opts.as !== void 0) b._def.refAs = opts.as;
+  return b;
+}
+__name(installationRef, "installationRef");
+
+// src/db/raw.ts
+function raw(name, up, opts) {
+  return {
+    name,
+    up,
+    ...opts?.down != null ? {
+      down: opts.down
+    } : {}
+  };
+}
+__name(raw, "raw");
+
+// src/db/embedding.ts
+var openai = {
+  embedding(model, opts) {
+    return {
+      provider: "openai",
+      model,
+      apiKeyName: opts?.apiKeyName ?? "OPENAI_API_KEY",
+      ...opts?.dimensions !== void 0 ? {
+        dimensions: opts.dimensions
+      } : {},
+      ...opts?.baseURL !== void 0 ? {
+        baseURL: opts.baseURL
+      } : {}
+    };
+  },
+  chat(model) {
+    return {
+      provider: "openai",
+      model
+    };
+  }
+};
+
+// src/db/sqlstate.ts
+var SQLSTATE = Object.freeze({
+  serializationFailure: "40001",
+  deadlockDetected: "40P01",
+  commandGuardFailed: "PBC01"
+});
+function isTransactionRollbackState(state) {
+  return state === SQLSTATE.serializationFailure || state === SQLSTATE.deadlockDetected;
+}
+__name(isTransactionRollbackState, "isTransactionRollbackState");
+
+// src/errors.ts
+var HTTP_ERROR_BRAND = /* @__PURE__ */ Symbol.for("palbase.backend.httpError");
+var HttpError = class extends Error {
+  static {
+    __name(this, "HttpError");
+  }
+  status;
+  error;
+  errorDescription;
+  data;
+  /** See {@link HTTP_ERROR_BRAND} — how the engine recognises this across SDK copies. */
+  [HTTP_ERROR_BRAND] = true;
+  constructor(status, error, errorDescription, data) {
+    super(errorDescription);
+    this.name = "HttpError";
+    this.status = status;
+    this.error = error;
+    this.errorDescription = errorDescription;
+    if (data !== void 0) {
+      this.data = data;
+    }
+  }
+  /**
+  * Serialize to the standard Palbase error response format.
+  * The `requestId` is injected by the runtime layer from the request context.
+  * When called without arguments (e.g. JSON.stringify), request_id is omitted.
+  * When `data` is set, it is appended as a strict-superset field.
+  */
+  toJSON(requestId) {
+    const result = {
+      error: this.error,
+      error_description: this.errorDescription,
+      status: this.status
+    };
+    if (requestId) {
+      result.request_id = requestId;
+    }
+    if (this.data !== void 0) {
+      result.data = this.data;
+    }
+    return result;
+  }
+};
+var PalError = class extends HttpError {
+  static {
+    __name(this, "PalError");
+  }
+  constructor(status, code, description, data) {
+    super(status, code, description, data);
+    this.name = "PalError";
+  }
+};
+var NamedHttpError = class NamedHttpError2 extends HttpError {
+  static {
+    __name(this, "NamedHttpError");
+  }
+  constructor(status, defaultCode, name, message, code, data) {
+    super(status, code ?? defaultCode, message ?? defaultMessage(name), data);
+    this.name = name;
+  }
+};
+function defaultMessage(name) {
+  const spaced = name.replace(/([a-z0-9])([A-Z])/g, "$1 $2");
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1).toLowerCase();
+}
+__name(defaultMessage, "defaultMessage");
+var BadRequest = class extends NamedHttpError {
+  static {
+    __name(this, "BadRequest");
+  }
+  constructor(data, message) {
+    super(400, "bad_request", "BadRequest", message, void 0, data);
+  }
+};
+var Unauthorized = class extends NamedHttpError {
+  static {
+    __name(this, "Unauthorized");
+  }
+  constructor(message, code, data) {
+    super(401, "unauthorized", "Unauthorized", message, code, data);
+  }
+};
+var Forbidden = class extends NamedHttpError {
+  static {
+    __name(this, "Forbidden");
+  }
+  constructor(message, code, data) {
+    super(403, "forbidden", "Forbidden", message, code, data);
+  }
+};
+var NotFound = class extends NamedHttpError {
+  static {
+    __name(this, "NotFound");
+  }
+  constructor(message, code, data) {
+    super(404, "not_found", "NotFound", message, code, data);
+  }
+};
+var Conflict = class extends NamedHttpError {
+  static {
+    __name(this, "Conflict");
+  }
+  constructor(message, code, data) {
+    super(409, "conflict", "Conflict", message, code, data);
+  }
+};
+var UniqueViolation = class extends Conflict {
+  static {
+    __name(this, "UniqueViolation");
+  }
+  /**
+  * Whether `e` is a unique violation — REGARDLESS of which copy of this SDK
+  * constructed it.
+  *
+  * Use this instead of `instanceof`. Measured on a live stack: a controller
+  * bundle INLINES its own copy of `@palbase/backend`, and the engine that
+  * raises this error is the runtime's copy. Two copies, two class identities,
+  * and `e instanceof UniqueViolation` is false in the one place a caller
+  * writes it — a check that reads as correct and silently never matches.
+  */
+  static is(e) {
+    return typeof e === "object" && e !== null && e.name === "UniqueViolation" && typeof e.constraint === "string";
+  }
+  /** The unique constraint the statement violated, as Postgres named it.
+  * `""` when the driver did not say which — see `engine/db.ts`. */
+  constraint;
+  constructor(constraint, message, code, data) {
+    super(message ?? "Unique constraint violated", code ?? "unique_violation", data);
+    this.name = "UniqueViolation";
+    this.constraint = constraint;
+  }
+};
+function isRetryable(e) {
+  return typeof e === "object" && e !== null && e.retryable === true && isTransactionRollbackState(e.sqlstate);
+}
+__name(isRetryable, "isRetryable");
+var SerializationFailure = class extends Conflict {
+  static {
+    __name(this, "SerializationFailure");
+  }
+  retryable = true;
+  sqlstate;
+  static is(e) {
+    return typeof e === "object" && e !== null && e.name === "SerializationFailure";
+  }
+  constructor(sqlstate = SQLSTATE.serializationFailure, message, data) {
+    super(message ?? "i\u015Flem e\u015Fzamanl\u0131 bir i\u015Flemle serile\u015Ftirilemedi \u2014 ayn\u0131 i\u015Flemi ba\u015Ftan \xE7al\u0131\u015Ft\u0131r\u0131n (karar okumalar\u0131 ve yazmalar\u0131 $atomic i\xE7ine al\u0131p { retry: n } verin)", "serialization_failure", data);
+    this.name = "SerializationFailure";
+    this.sqlstate = sqlstate;
+  }
+};
+var DeadlockDetected = class extends Conflict {
+  static {
+    __name(this, "DeadlockDetected");
+  }
+  retryable = true;
+  sqlstate;
+  static is(e) {
+    return typeof e === "object" && e !== null && e.name === "DeadlockDetected";
+  }
+  constructor(sqlstate = SQLSTATE.deadlockDetected, message, data) {
+    super(message ?? "deadlock: iki i\u015Flem birbirinin kilidini bekledi ve bu i\u015Flem iptal edildi \u2014 kilit s\u0131ras\u0131n\u0131 sabitlemek i\xE7in Database.$lockRows(tablo, id'ler) kullan\u0131n", "deadlock_detected", data);
+    this.name = "DeadlockDetected";
+    this.sqlstate = sqlstate;
+  }
+};
+var TooManyRequests = class extends NamedHttpError {
+  static {
+    __name(this, "TooManyRequests");
+  }
+  constructor(data, message) {
+    super(429, "too_many_requests", "TooManyRequests", message, void 0, data);
   }
 };
-function uuid() {
-  return new ColumnBuilder("uuid");
-}
-__name(uuid, "uuid");
-function text() {
-  return new ColumnBuilder("text");
-}
-__name(text, "text");
-function integer() {
-  return new ColumnBuilder("integer");
-}
-__name(integer, "integer");
-function bigint() {
-  return new ColumnBuilder("bigint");
-}
-__name(bigint, "bigint");
-function numeric() {
-  return new ColumnBuilder("numeric");
-}
-__name(numeric, "numeric");
-function boolean() {
-  return new ColumnBuilder("boolean");
-}
-__name(boolean, "boolean");
-function timestamp() {
-  return new ColumnBuilder("timestamp");
-}
-__name(timestamp, "timestamp");
-function jsonb() {
-  return new ColumnBuilder("jsonb");
-}
-__name(jsonb, "jsonb");
-function enumType(name, values) {
-  const builder = new ColumnBuilder("enum");
-  builder._def.enumName = name;
-  builder._def.enumValues = [
-    ...values
-  ];
-  return builder;
+
+// src/db/typed-db.ts
+function makeTypedTable(name, raw2) {
+  return {
+    insert: /* @__PURE__ */ __name((data) => raw2.insert(name, data), "insert"),
+    aggregate: /* @__PURE__ */ __name((q) => raw2.aggregate(name, q), "aggregate"),
+    insertMany: /* @__PURE__ */ __name((rows, opts) => raw2.insertMany(name, rows, opts), "insertMany"),
+    put: /* @__PURE__ */ __name((q) => raw2.put(name, q.data, {
+      onConflict: q.onConflict
+    }), "put"),
+    update: /* @__PURE__ */ __name((q) => raw2.update(name, q.where.id, q.set), "update"),
+    delete: /* @__PURE__ */ __name((id) => raw2.delete(name, id), "delete"),
+    findUnique: /* @__PURE__ */ __name((q) => raw2.findUnique(name, q.where, {
+      select: q.select
+    }), "findUnique"),
+    findById: /* @__PURE__ */ __name((id) => raw2.findById(name, id), "findById"),
+    page: /* @__PURE__ */ __name((q) => {
+      const { where, ...opts } = q ?? {};
+      return raw2.page(name, where, opts);
+    }, "page"),
+    findMany: /* @__PURE__ */ __name((q) => {
+      const { where, ...opts } = q ?? {};
+      return raw2.findMany(name, where, opts);
+    }, "findMany"),
+    updateMany: /* @__PURE__ */ __name((q) => raw2.updateMany(name, q.where, q.set, q.returning === void 0 ? void 0 : {
+      returning: q.returning
+    }), "updateMany"),
+    deleteMany: /* @__PURE__ */ __name((q) => raw2.deleteMany(name, q.where), "deleteMany"),
+    count: /* @__PURE__ */ __name((q) => raw2.count(name, q?.where), "count")
+  };
 }
-__name(enumType, "enumType");
-function vector(dimensions) {
-  if (!Number.isInteger(dimensions) || dimensions < 1 || dimensions > 2e3) {
-    throw new Error(`vector(): dimensions must be an integer in [1, 2000], got ${String(dimensions)}`);
+__name(makeTypedTable, "makeTypedTable");
+function makeTypedDB(schema, raw2) {
+  const tables = {};
+  for (const key of Object.keys(schema.tables)) {
+    const tableDef = schema.tables[key];
+    if (tableDef !== void 0) {
+      tables[key] = makeTypedTable(qualifiedTableKey(schema.name, tableDef.name), raw2);
+    }
   }
-  const b = new ColumnBuilder("vector");
-  b._def.dimensions = dimensions;
-  return b;
-}
-__name(vector, "vector");
-function ownedByUser() {
-  const b = new ColumnBuilder("text");
-  b._def.nullable = false;
-  b._def.references = {
-    table: "auth.users",
-    column: "id"
+  const result = {
+    tables,
+    diagnostics: /* @__PURE__ */ __name(() => raw2.diagnostics(), "diagnostics"),
+    readQuery: /* @__PURE__ */ __name((query) => raw2.readQuery(query), "readQuery"),
+    compileQuery: /* @__PURE__ */ __name((query) => raw2.compileQuery(query), "compileQuery"),
+    explainQuery: /* @__PURE__ */ __name((query) => raw2.explainQuery(query), "explainQuery"),
+    command(fn, options) {
+      const builder = new TxPlanBuilder();
+      const planTables = Object.fromEntries(Object.entries(schema.tables).map(([key, table]) => [
+        key,
+        builder.table(qualifiedTableKey(schema.name, table.name))
+      ]));
+      return runTxPlan({
+        txPlan: /* @__PURE__ */ __name((plan) => raw2.command(plan, options), "txPlan")
+      }, {
+        tables: planTables
+      }, builder, fn);
+    },
+    transaction(fn) {
+      const builder = new TxPlanBuilder();
+      const planTables = {};
+      for (const key of Object.keys(schema.tables)) {
+        const tableDef = schema.tables[key];
+        if (tableDef !== void 0) planTables[key] = builder.table(qualifiedTableKey(schema.name, tableDef.name));
+      }
+      return runTxPlan(raw2, {
+        tables: planTables
+      }, builder, fn);
+    }
   };
-  b._def.onDeleteAction = "cascade";
-  b._def.owns = true;
-  return b;
+  return result;
 }
-__name(ownedByUser, "ownedByUser");
-function userRef(opts) {
-  const b = new ColumnBuilder("text");
-  b._def.references = {
-    table: "auth.users",
-    column: "id"
-  };
-  b._def.onDeleteAction = opts.onDelete;
-  if (opts.as !== void 0) b._def.refAs = opts.as;
-  return b;
+__name(makeTypedDB, "makeTypedDB");
+function col(name) {
+  return brandRef({
+    $col: name
+  }, "col");
 }
-__name(userRef, "userRef");
-function installationRef(opts) {
-  const b = new ColumnBuilder("text");
-  b._def.references = {
-    table: "auth.installations",
-    column: "id"
-  };
-  b._def.onDeleteAction = opts.onDelete;
-  if (opts.as !== void 0) b._def.refAs = opts.as;
-  return b;
+__name(col, "col");
+async function withRetry(fn, opts = {}) {
+  const budget = retryBudget(opts.retry);
+  let attempt = 0;
+  for (; ; ) {
+    try {
+      return await fn();
+    } catch (e) {
+      if (attempt >= budget || !isRetryable(e)) throw e;
+      attempt += 1;
+    }
+  }
 }
-__name(installationRef, "installationRef");
-
-// src/db/raw.ts
-function raw(name, up, opts) {
-  return {
-    name,
-    up,
-    ...opts?.down != null ? {
-      down: opts.down
-    } : {}
-  };
+__name(withRetry, "withRetry");
+function sqlFragment(strings, ...values) {
+  return brandRef({
+    $sql: {
+      text: [
+        ...strings
+      ],
+      values
+    }
+  }, "sql");
 }
-__name(raw, "raw");
-
-// src/db/embedding.ts
-var openai = {
-  embedding(model, opts) {
-    return {
-      provider: "openai",
-      model,
-      apiKeyName: opts?.apiKeyName ?? "OPENAI_API_KEY",
-      ...opts?.dimensions !== void 0 ? {
-        dimensions: opts.dimensions
-      } : {},
-      ...opts?.baseURL !== void 0 ? {
-        baseURL: opts.baseURL
-      } : {}
-    };
-  },
-  chat(model) {
-    return {
-      provider: "openai",
-      model
-    };
-  }
-};
+__name(sqlFragment, "sqlFragment");
 
 // src/refusals.ts
 var DECLARATION_REFUSAL = /* @__PURE__ */ Symbol.for("palbase.backend.declarationRefusal");
@@ -3751,6 +3945,39 @@ function isDeclarationRefused(e) {
 }
 __name(isDeclarationRefused, "isDeclarationRefused");
 
+// src/db/unique.ts
+function uniqueKeysOf(table) {
+  const columns = table.columns ?? {};
+  const inlinePrimary = [], keys = [];
+  for (const [name, value] of Object.entries(columns)) {
+    const col2 = value && typeof value === "object" && "_def" in value ? value._def : value;
+    if (col2?.primaryKey) inlinePrimary.push(name);
+    if (col2?.unique) keys.push([
+      name
+    ]);
+  }
+  const primary = table.primaryKey ?? inlinePrimary;
+  if (primary.length) keys.unshift([
+    ...primary
+  ]);
+  for (const key of table.unique ?? []) keys.push([
+    ...key.columns
+  ]);
+  const seen = /* @__PURE__ */ new Set();
+  return keys.filter((key) => {
+    if (!key.length || new Set(key).size !== key.length || key.some((col2) => !Object.hasOwn(columns, col2))) {
+      throw new Error("Unique lookup requires a nonempty declared key of distinct, known columns");
+    }
+    const identity = JSON.stringify([
+      ...key
+    ].sort());
+    if (seen.has(identity)) return false;
+    seen.add(identity);
+    return true;
+  });
+}
+__name(uniqueKeysOf, "uniqueKeysOf");
+
 // src/db/env-gen.ts
 function baseTsType(def) {
   if (def.codec !== void 0 && def.codec in CODECS) {
@@ -3902,6 +4129,9 @@ function tableBlock(table, relations, indent) {
   const rowLines = cols.map(([col2, builder]) => {
     return `${indent}    ${col2}: ${rowType(builder._def)};`;
   });
+  const hasCanColumn = Object.prototype.hasOwnProperty.call(table.columns, "can") || relations.some((r) => r.name === "can");
+  const canNames = (table.policies ?? []).filter((p) => p.command === "update" && p.permissive !== false && Buffer.byteLength(`can:${p.name}`, "utf8") <= 63).map((p) => JSON.stringify(p.name));
+  const canLine = hasCanColumn ? null : `${indent}    can: ${canNames.length === 0 ? "never[]" : `(${canNames.join(" | ")})[]`};`;
   const insertLines = cols.map(([col2, builder]) => {
     const def = builder._def;
     const opt = optionalOnInsert(def) ? "?" : "";
@@ -3912,11 +4142,15 @@ function tableBlock(table, relations, indent) {
     `${indent}${table.name}: {`,
     `${indent}  row: {`,
     ...rowLines,
+    ...canLine === null ? [] : [
+      canLine
+    ],
     `${indent}  };`,
     `${indent}  insert: {`,
     ...insertLines,
     `${indent}  };`,
     `${indent}  relations: {${relEntries === "" ? "" : ` ${relEntries} `}};`,
+    `${indent}  uniqueKeys: ${JSON.stringify(uniqueKeysOf(table))};`,
     // searchable: vector kolonu YA DA search beyanı → EnvTypedTable'da search()
     // üyesini açan yapısal bayrak (FR-013). Yokken satır hiç üretilmez ki
     // mevcut şemaların d.ts'i bayt-aynı kalsın.
@@ -4733,18 +4967,18 @@ __name(defineMiddleware, "defineMiddleware");
 
 // src/error-registry.ts
 var import_zod_to_openapi = require("@asteasolutions/zod-to-openapi");
-var import_zod = require("zod");
-(0, import_zod_to_openapi.extendZodWithOpenApi)(import_zod.z);
+var import_zod2 = require("zod");
+(0, import_zod_to_openapi.extendZodWithOpenApi)(import_zod2.z);
 var ERROR_REGISTRY = /* @__PURE__ */ Symbol.for("palbase.backend.errorRegistry");
 var BUILTIN_DATA_SCHEMAS = {
-  bad_request: import_zod.z.object({
-    fields: import_zod.z.array(import_zod.z.object({
-      field: import_zod.z.string(),
-      message: import_zod.z.string()
+  bad_request: import_zod2.z.object({
+    fields: import_zod2.z.array(import_zod2.z.object({
+      field: import_zod2.z.string(),
+      message: import_zod2.z.string()
     }))
   }),
-  too_many_requests: import_zod.z.object({
-    retryAfter: import_zod.z.number().int()
+  too_many_requests: import_zod2.z.object({
+    retryAfter: import_zod2.z.number().int()
   })
 };
 function getErrorRegistry() {
@@ -4861,7 +5095,7 @@ __name(defineError, "defineError");
 function digestOf(code, dataSchema) {
   const TMP_REF = "__PalbaseErrorDataDigest";
   const tmpRegistry = new import_zod_to_openapi.OpenAPIRegistry();
-  tmpRegistry.register(TMP_REF, import_zod.z.object({
+  tmpRegistry.register(TMP_REF, import_zod2.z.object({
     data: dataSchema
   }).openapi(TMP_REF));
   const generated = new import_zod_to_openapi.OpenApiGeneratorV31(tmpRegistry.definitions).generateComponents();
@@ -5455,7 +5689,188 @@ function getJobConfig(ctor, container) {
 __name(getJobConfig, "getJobConfig");
 
 // src/index.ts
-var import_zod2 = require("zod");
+var import_zod4 = require("zod");
+
+// src/db/query.ts
+var import_zod3 = require("zod");
+var import_zod_to_openapi2 = require("@asteasolutions/zod-to-openapi");
+
+// src/db/query-contract.ts
+function queryColumnContract(column) {
+  const def = column && typeof column === "object" && "_def" in column ? column._def : column;
+  if (!def?.type) throw new Error("Query contract requires declared column types");
+  if (def.transform !== void 0 && def.codec === void 0) throw new Error("Query contracts require a named codec instead of a free-form column transform");
+  return {
+    type: def.type,
+    nullable: def.nullable === true,
+    ...def.codec === void 0 ? {} : {
+      codec: def.codec
+    },
+    ...def.enumValues === void 0 ? {} : {
+      enumValues: [
+        ...def.enumValues
+      ]
+    },
+    ...def.dimensions === void 0 ? {} : {
+      dimensions: def.dimensions
+    }
+  };
+}
+__name(queryColumnContract, "queryColumnContract");
+function stableContract(value) {
+  if (Array.isArray(value)) return `[${value.map(stableContract).join(",")}]`;
+  if (value && typeof value === "object") return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableContract(value[key])}`).join(",")}}`;
+  return JSON.stringify(value) ?? "null";
+}
+__name(stableContract, "stableContract");
+
+// src/db/query.ts
+(0, import_zod_to_openapi2.extendZodWithOpenApi)(import_zod3.z);
+function responseColumn(column, validator) {
+  const contract = queryColumnContract(column);
+  let schema;
+  if (validator) return validator;
+  if (contract.codec === "number") schema = import_zod3.z.number().finite();
+  else if (contract.codec === "decimal") schema = import_zod3.z.string();
+  else switch (contract.type) {
+    case "integer":
+      schema = import_zod3.z.number().int().min(-2147483648).max(2147483647);
+      break;
+    case "boolean":
+      schema = import_zod3.z.boolean();
+      break;
+    case "vector":
+      schema = import_zod3.z.array(import_zod3.z.number().finite());
+      break;
+    case "enum": {
+      const values = contract.enumValues;
+      if (!values?.length) throw new Error("Query response requires declared enum values");
+      schema = import_zod3.z.enum(values);
+      break;
+    }
+    case "uuid":
+    case "text":
+    case "timestamp":
+    case "numeric":
+    case "bigint":
+      schema = import_zod3.z.string();
+      break;
+    case "jsonb":
+      throw new Error("Query response requires a fields validator for a selected jsonb column: its TypeScript payload is erased at runtime");
+    default:
+      throw new Error(`Query response does not support column type ${contract.type}`);
+  }
+  return contract.nullable ? schema.nullable() : schema;
+}
+__name(responseColumn, "responseColumn");
+function defineQuery(name, options) {
+  if (typeof name !== "string" || !/^[A-Za-z][A-Za-z0-9_]{0,127}$/.test(name)) throw new Error("defineQuery requires a stable name of 1\u2013128 letters, digits or underscores");
+  const table = declaredTableKey(options.table);
+  const select = [
+    ...options.select
+  ];
+  if (!select.length || new Set(select).size !== select.length) throw new Error(`Query ${name}: select must be explicit, nonempty and distinct`);
+  const shape = {}, columns = {};
+  for (const key of select) {
+    if (!Object.hasOwn(options.table[TABLE_META].columns, key)) throw new Error(`Query ${name}: unknown column ${key}`);
+    columns[key] = queryColumnContract(options.table[key]);
+    shape[key] = responseColumn(options.table[key], options.fields?.[key]);
+  }
+  const response = import_zod3.z.array(import_zod3.z.object(shape).strict());
+  const queryInput = options.input, where = options.where, limit = options.limit;
+  const orderBy = options.orderBy === void 0 ? void 0 : JSON.parse(JSON.stringify(options.orderBy));
+  const prepare = /* @__PURE__ */ __name((input) => {
+    const parsed = queryInput.parse(input);
+    const filter = where === void 0 ? {} : where(parsed);
+    if (!filter || typeof filter !== "object" || Array.isArray(filter) || typeof filter.then === "function") {
+      throw new Error(`Query ${name}: where must return a synchronous filter object`);
+    }
+    const size = typeof limit === "function" ? limit(parsed) : limit;
+    if (limit !== void 0 && (typeof size !== "number" || !Number.isSafeInteger(size) || size < 0)) throw new Error(`Query ${name}: limit must produce a nonnegative safe integer`);
+    return {
+      name,
+      table,
+      columns: JSON.parse(JSON.stringify(columns)),
+      where: filter,
+      options: {
+        select: [
+          ...select
+        ],
+        ...orderBy === void 0 ? {} : {
+          orderBy: structuredClone(orderBy)
+        },
+        ...limit === void 0 ? {} : {
+          limit: size
+        }
+      }
+    };
+  }, "prepare");
+  const attach = /* @__PURE__ */ __name((schema) => {
+    const api = {
+      queryName: name,
+      input: queryInput,
+      prepare,
+      async run(database, input) {
+        const request = prepare(input);
+        const rows = await ("$readQuery" in database ? database.$readQuery(request) : database.readQuery(request));
+        return schema.parse(rows);
+      },
+      sql(database, input) {
+        const request = prepare(input);
+        return "$compileQuery" in database ? database.$compileQuery(request) : database.compileQuery(request);
+      },
+      explain(database, input) {
+        const request = prepare(input);
+        return "$explainQuery" in database ? database.$explainQuery(request) : database.explainQuery(request);
+      },
+      contract() {
+        const registry2 = new import_zod_to_openapi2.OpenAPIRegistry();
+        registry2.register(`${name}Input`, queryInput);
+        registry2.register(`${name}Response`, schema);
+        return JSON.parse(JSON.stringify({
+          name,
+          table,
+          select,
+          columns,
+          components: new import_zod_to_openapi2.OpenApiGeneratorV31(registry2.definitions).generateComponents().components
+        }));
+      }
+    };
+    for (const key of [
+      "min",
+      "max",
+      "length",
+      "describe",
+      "openapi"
+    ]) {
+      const modify = schema[key].bind(schema);
+      Object.defineProperty(schema, key, {
+        value: /* @__PURE__ */ __name((...args) => attach(modify(...args)), "value"),
+        configurable: true
+      });
+    }
+    return Object.assign(schema, api);
+  }, "attach");
+  return attach(response);
+}
+__name(defineQuery, "defineQuery");
+function queryManifest(queries) {
+  const sorted = [
+    ...queries
+  ].sort((a, b) => a.queryName.localeCompare(b.queryName));
+  if (new Set(sorted.map((query) => query.queryName)).size !== sorted.length) throw new Error("Query manifest contains duplicate names");
+  return JSON.parse(stableContract({
+    version: 1,
+    queries: sorted.map((query) => query.contract())
+  }));
+}
+__name(queryManifest, "queryManifest");
+function assertQueryManifest(queries, baseline) {
+  if (stableContract(queryManifest(queries)) !== stableContract(baseline)) {
+    throw new Error("Query contract drift: compare queryManifest() with the committed manifest and review the API/client changes before updating it");
+  }
+}
+__name(assertQueryManifest, "assertQueryManifest");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Auth,
@@ -5539,11 +5954,13 @@ var import_zod2 = require("zod");
   __runWithRuntime,
   __setRuntime,
   assertNoOrphanEntryPoints,
+  assertQueryManifest,
   assertZeroArgConstructor,
   bigint,
   boolean,
   buildContainer,
   buildModuleClients,
+  can,
   col,
   controllersOf,
   dec,
@@ -5552,8 +5969,10 @@ var import_zod2 = require("zod");
   defineDefaultAuth,
   defineError,
   defineMiddleware,
+  defineQuery,
   defineSchema,
   defineTable,
+  defineWorkload,
   enumType,
   exprCtx,
   getErrorRegistry,
@@ -5589,6 +6008,7 @@ var import_zod2 = require("zod");
   ownerOnly,
   policy,
   publicChannel,
+  queryManifest,
   raw,
   recordThrows,
   resolveEffectiveAuth,