@palbase/backend 33.0.1 → 34.0.0

package/dist/index.cjs

@@ -102,6 +102,7 @@ __export(src_exports, {
   __runWithRuntime: () => __runWithRuntime,
   __setRuntime: () => __setRuntime,
   assertNoOrphanEntryPoints: () => assertNoOrphanEntryPoints,
+  assertQueryManifest: () => assertQueryManifest,
   assertZeroArgConstructor: () => assertZeroArgConstructor,
   bigint: () => bigint,
   boolean: () => boolean,
@@ -115,8 +116,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 +155,7 @@ __export(src_exports, {
   ownerOnly: () => ownerOnly,
   policy: () => policy,
   publicChannel: () => publicChannel,
+  queryManifest: () => queryManifest,
   raw: () => raw,
   recordThrows: () => recordThrows,
   resolveEffectiveAuth: () => resolveEffectiveAuth,
@@ -165,7 +169,7 @@ __export(src_exports, {
   vector: () => vector,
   webhooksOf: () => webhooksOf,
   withRetry: () => withRetry,
-  z: () => import_zod2.z
+  z: () => import_zod3.z
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -741,260 +745,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) {
@@ -1407,6 +1205,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 +1250,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,14 +1282,49 @@ 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, {
@@ -3134,6 +2981,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)) {
@@ -3733,6 +3587,295 @@ var openai = {
   }
 };
 
+// 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);
+  }
+};
+
+// 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(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 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);
+    }
+  };
+  return result;
+}
+__name(makeTypedDB, "makeTypedDB");
+function col(name) {
+  return brandRef({
+    $col: name
+  }, "col");
+}
+__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(withRetry, "withRetry");
+function sqlFragment(strings, ...values) {
+  return brandRef({
+    $sql: {
+      text: [
+        ...strings
+      ],
+      values
+    }
+  }, "sql");
+}
+__name(sqlFragment, "sqlFragment");
+
 // src/refusals.ts
 var DECLARATION_REFUSAL = /* @__PURE__ */ Symbol.for("palbase.backend.declarationRefusal");
 var DeclarationRefused = class extends Error {
@@ -3751,6 +3894,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) {
@@ -3917,6 +4093,7 @@ function tableBlock(table, relations, indent) {
     ...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.
@@ -5455,7 +5632,188 @@ function getJobConfig(ctor, container) {
 __name(getJobConfig, "getJobConfig");
 
 // src/index.ts
+var import_zod3 = require("zod");
+
+// src/db/query.ts
 var import_zod2 = 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_zod2.z);
+function responseColumn(column, validator) {
+  const contract = queryColumnContract(column);
+  let schema;
+  if (validator) return validator;
+  if (contract.codec === "number") schema = import_zod2.z.number().finite();
+  else if (contract.codec === "decimal") schema = import_zod2.z.string();
+  else switch (contract.type) {
+    case "integer":
+      schema = import_zod2.z.number().int().min(-2147483648).max(2147483647);
+      break;
+    case "boolean":
+      schema = import_zod2.z.boolean();
+      break;
+    case "vector":
+      schema = import_zod2.z.array(import_zod2.z.number().finite());
+      break;
+    case "enum": {
+      const values = contract.enumValues;
+      if (!values?.length) throw new Error("Query response requires declared enum values");
+      schema = import_zod2.z.enum(values);
+      break;
+    }
+    case "uuid":
+    case "text":
+    case "timestamp":
+    case "numeric":
+    case "bigint":
+      schema = import_zod2.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_zod2.z.array(import_zod2.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,6 +5897,7 @@ var import_zod2 = require("zod");
   __runWithRuntime,
   __setRuntime,
   assertNoOrphanEntryPoints,
+  assertQueryManifest,
   assertZeroArgConstructor,
   bigint,
   boolean,
@@ -5552,8 +5911,10 @@ var import_zod2 = require("zod");
   defineDefaultAuth,
   defineError,
   defineMiddleware,
+  defineQuery,
   defineSchema,
   defineTable,
+  defineWorkload,
   enumType,
   exprCtx,
   getErrorRegistry,
@@ -5589,6 +5950,7 @@ var import_zod2 = require("zod");
   ownerOnly,
   policy,
   publicChannel,
+  queryManifest,
   raw,
   recordThrows,
   resolveEffectiveAuth,