@palbase/backend 33.0.2 → 34.0.0

package/dist/{chunk-C6COAB3E.js → chunk-MNGZE2MM.js}

@@ -1,17 +1,23 @@
 import {
   DeclarationRefused,
   assertNoOrphanEntryPoints,
+  assertUniqueLookup,
   buildContainer,
-  buildRelations
-} from "./chunk-WWUG2QXF.js";
+  buildRelations,
+  uniqueKeysOf
+} from "./chunk-YX7UA7VC.js";
+import {
+  validateInsertManyOptions
+} from "./chunk-GHNC2UHS.js";
 import {
   __requestALS,
   __runStartHooks,
   __runWithRuntime
-} from "./chunk-TVCCR6SO.js";
+} from "./chunk-LOGL2ZHD.js";
 import {
-  CODECS
-} from "./chunk-XOX6RFPZ.js";
+  CODECS,
+  assertReadContract
+} from "./chunk-PRH45NZU.js";
 import {
   assertNoExpressionHandles,
   assertUsableFilter,
@@ -24,21 +30,31 @@ import {
   isSqlFragment,
   looksLikeUnbrandedPlanRef,
   looksLikeUnbrandedRef,
-  qualifiedTableKey
-} from "./chunk-SI4KGEM3.js";
+  qualifiedTableKey,
+  retryBudget,
+  validateAtomicOptions,
+  validateWorkload
+} from "./chunk-FOWA7PF4.js";
 import {
   getRoutes,
   resolveEffectiveAuth
-} from "./chunk-AAT5G7KY.js";
+} from "./chunk-JJW3L62T.js";
 import {
+  BadRequest,
   DeadlockDetected,
+  HttpError,
+  SQLSTATE,
   SerializationFailure,
+  TooManyRequests,
   UniqueViolation,
-  __name,
   isEngineRaised,
   isHttpError,
+  isRetryable,
   markEngineRaised
-} from "./chunk-KATPXCJ5.js";
+} from "./chunk-UMESJJRS.js";
+import {
+  __name
+} from "./chunk-VXPNPVAG.js";
 
 // src/engine/config.ts
 var BootRefused = class extends Error {
@@ -90,6 +106,8 @@ ${detail}`);
     uploadSecret: env.PALBASE_UPLOAD_SECRET ?? "",
     anonKey: env.PALBASE_ANON_KEY ?? "",
     serviceRoleKey: env.PALBASE_SERVICE_ROLE_KEY ?? "",
+    cursorSecret: env.PALBASE_CURSOR_SECRET,
+    enableCommands: env.PALBASE_DB_COMMANDS === "true",
     realtimeSecret: env.REALTIME_INGESTION_SECRET ?? "",
     port,
     dbRole: env.DB_ROLE ?? "backend_authenticated",
@@ -98,7 +116,14 @@ ${detail}`);
     // (`roleBackendServiceRole = "backend_service_role"`, NOLOGIN BYPASSRLS),
     // and the live database agrees (pg_roles.rolbypassrls = true).
     dbServiceRole: env.DB_SERVICE_ROLE ?? "backend_service_role",
-    poolMax
+    poolMax,
+    ...env.PALBASE_DB_DIAGNOSTICS === "true" ? {
+      databaseDiagnostics: {
+        onComplete: /* @__PURE__ */ __name((diagnostics) => {
+          console.log("palbase.database", JSON.stringify(diagnostics));
+        }, "onComplete")
+      }
+    } : {}
   };
 }
 __name(loadConfig, "loadConfig");
@@ -196,14 +221,14 @@ var AuthVerifier = class {
       return null;
     }
     if (header.alg !== "ES256" || !header.kid) return null;
-    const key = await this.key(header.kid);
-    if (!key) return null;
+    const key2 = await this.key(header.kid);
+    if (!key2) return null;
     let ok = false;
     try {
       ok = await crypto.subtle.verify({
         name: "ECDSA",
         hash: "SHA-256"
-      }, key, b64urlToBytes(sig), new TextEncoder().encode(`${h}.${p}`));
+      }, key2, b64urlToBytes(sig), new TextEncoder().encode(`${h}.${p}`));
     } catch {
       return null;
     }
@@ -269,12 +294,12 @@ var RateLimiter = class {
   *   wait (never 0 — a caller told to wait 0 comes straight back to the same
   *   refusal).
   */
-  check(rule, key, now) {
+  check(rule, key2, now) {
     if (!rule || !(rule.max > 0) || !(rule.window > 0)) return null;
-    const bucket = this.buckets.get(key);
+    const bucket = this.buckets.get(key2);
     if (!bucket || now >= bucket.resetAt) {
       if (this.buckets.size >= this.maxKeys) this.evict(now);
-      this.buckets.set(key, {
+      this.buckets.set(key2, {
         count: 1,
         resetAt: now + rule.window * 1e3
       });
@@ -317,11 +342,11 @@ function makeMemoryCache(opts = {}) {
   const now = opts.now ?? (() => Date.now());
   const store = /* @__PURE__ */ new Map();
   const inflight = /* @__PURE__ */ new Map();
-  const live = /* @__PURE__ */ __name((key) => {
-    const e = store.get(key);
+  const live = /* @__PURE__ */ __name((key2) => {
+    const e = store.get(key2);
     if (!e) return void 0;
     if (e.expiresAt !== 0 && e.expiresAt <= now()) {
-      store.delete(key);
+      store.delete(key2);
       return void 0;
     }
     return e;
@@ -344,61 +369,742 @@ function makeMemoryCache(opts = {}) {
       if (victim) store.delete(victim[0]);
     }
   }, "evict");
-  const set = /* @__PURE__ */ __name(async (key, value, ttl) => {
-    if (store.size >= maxEntries && !store.has(key)) evict();
-    store.set(key, {
+  const set = /* @__PURE__ */ __name(async (key2, value, ttl) => {
+    if (store.size >= maxEntries && !store.has(key2)) evict();
+    store.set(key2, {
       value,
       expiresAt: ttl && ttl > 0 ? now() + ttl * 1e3 : 0
     });
   }, "set");
   return {
-    async get(key) {
-      const e = live(key);
+    async get(key2) {
+      const e = live(key2);
       return e ? e.value : null;
     },
     set,
-    async del(key) {
-      store.delete(key);
+    async del(key2) {
+      store.delete(key2);
     },
-    async incr(key) {
-      const e = live(key);
+    async incr(key2) {
+      const e = live(key2);
       const next = (typeof e?.value === "number" ? e.value : 0) + 1;
-      store.set(key, {
+      store.set(key2, {
         value: next,
         expiresAt: e?.expiresAt ?? 0
       });
       return next;
     },
-    async getOrSet(key, ttl, fn) {
-      const hit = live(key);
+    async getOrSet(key2, ttl, fn) {
+      const hit = live(key2);
       if (hit) return hit.value;
-      const running = inflight.get(key);
+      const running = inflight.get(key2);
       if (running) return running;
       const fill = (async () => {
         try {
           const value = await fn();
-          await set(key, value, ttl);
+          await set(key2, value, ttl);
           return value;
         } finally {
-          inflight.delete(key);
+          inflight.delete(key2);
         }
       })();
-      inflight.set(key, fill);
+      inflight.set(key2, fill);
       return fill;
     }
   };
 }
 __name(makeMemoryCache, "makeMemoryCache");
 
+// src/engine/db.ts
+import { AsyncLocalStorage } from "async_hooks";
+
+// src/engine/schema-cache.ts
+function memoTable(cache, schema, table, compute) {
+  if (!schema.tables || !Object.hasOwn(schema.tables, table)) return compute();
+  let tables = cache.get(schema);
+  if (!tables) {
+    tables = /* @__PURE__ */ new Map();
+    cache.set(schema, tables);
+  }
+  if (!tables.has(table)) tables.set(table, compute());
+  return tables.get(table);
+}
+__name(memoTable, "memoTable");
+function snapshotDeclaration(value, seen = /* @__PURE__ */ new WeakMap()) {
+  if (value === null || typeof value !== "object") return value;
+  const previous = seen.get(value);
+  if (previous) return previous;
+  if (value instanceof Date) return new Date(value.getTime());
+  const result = Array.isArray(value) ? [] : Object.create(Object.getPrototypeOf(value));
+  seen.set(value, result);
+  for (const key2 of Reflect.ownKeys(value)) {
+    if (Array.isArray(value) && key2 === "length") continue;
+    const descriptor = Object.getOwnPropertyDescriptor(value, key2);
+    if ("value" in descriptor) descriptor.value = snapshotDeclaration(descriptor.value, seen);
+    Object.defineProperty(result, key2, descriptor);
+  }
+  return Object.freeze(result);
+}
+__name(snapshotDeclaration, "snapshotDeclaration");
+
+// src/engine/cursor.ts
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "crypto";
+var key = null;
+var invalidPage = /* @__PURE__ */ __name((message, field = "page") => new BadRequest({
+  fields: [
+    {
+      field,
+      message
+    }
+  ]
+}, message), "invalidPage");
+function setCursorKey(secret) {
+  key = secret ? createHash("sha256").update("palbase:cursor:v1\0").update(secret).digest() : null;
+}
+__name(setCursorKey, "setCursorKey");
+function cursorKey() {
+  if (!key) throw new Error("Database.page needs PALBASE_CURSOR_SECRET or PALBASE_SERVICE_ROLE_KEY shared by all replicas");
+  return key;
+}
+__name(cursorKey, "cursorKey");
+function fingerprint(value) {
+  const stable = /* @__PURE__ */ __name((v) => {
+    if (typeof v === "bigint") return {
+      $bigint: v.toString()
+    };
+    if (v instanceof Date) return {
+      $date: v.toISOString()
+    };
+    if (Array.isArray(v)) return v.map(stable);
+    if (v && typeof v === "object") {
+      return Object.fromEntries(Object.keys(v).sort().map((k) => [
+        k,
+        stable(v[k])
+      ]));
+    }
+    return v;
+  }, "stable");
+  return createHash("sha256").update(JSON.stringify(stable(value))).digest("base64url");
+}
+__name(fingerprint, "fingerprint");
+function cursorIdentity(role, claimsJson) {
+  const claims = JSON.parse(claimsJson);
+  const { iat, exp, nbf, jti, ...authorization } = claims;
+  return fingerprint({
+    role,
+    authorization
+  });
+}
+__name(cursorIdentity, "cursorIdentity");
+function encodeCursor(secret, scope, values) {
+  const nonce = randomBytes(12);
+  const cipher = createCipheriv("aes-256-gcm", secret, nonce);
+  cipher.setAAD(Buffer.from(scope));
+  const body = Buffer.concat([
+    cipher.update(JSON.stringify(values), "utf8"),
+    cipher.final()
+  ]);
+  const token = `p1.${Buffer.concat([
+    nonce,
+    cipher.getAuthTag(),
+    body
+  ]).toString("base64url")}`;
+  if (token.length > 16384) throw invalidPage("page cursor values are too large; choose shorter ordering columns");
+  return token;
+}
+__name(encodeCursor, "encodeCursor");
+function decodeCursor(secret, scope, token, count) {
+  try {
+    if (typeof token !== "string" || token.length > 16384 || !/^p1\.[\w-]+$/.test(token)) throw new Error();
+    const data = Buffer.from(token.slice(3), "base64url");
+    if (data.length < 30 || data.toString("base64url") !== token.slice(3)) throw new Error();
+    const cipher = createDecipheriv("aes-256-gcm", secret, data.subarray(0, 12));
+    cipher.setAAD(Buffer.from(scope));
+    cipher.setAuthTag(data.subarray(12, 28));
+    const values = JSON.parse(Buffer.concat([
+      cipher.update(data.subarray(28)),
+      cipher.final()
+    ]).toString("utf8"));
+    if (!Array.isArray(values) || values.length !== count || values.some((v) => v !== null && typeof v !== "string")) throw new Error();
+    return values;
+  } catch {
+    throw invalidPage("Invalid cursor for this query or identity; restart from the first page", "cursor");
+  }
+}
+__name(decodeCursor, "decodeCursor");
+function pageOrder(columns, primaryKey, opts) {
+  const raw = opts;
+  if ("limit" in raw || "offset" in raw) throw invalidPage("page uses first/after or last/before, not limit/offset");
+  const backward = opts.last !== void 0 || opts.before !== void 0;
+  if (backward && (opts.first !== void 0 || opts.after !== void 0)) throw invalidPage("Use first/after or last/before in one page request");
+  const size = (backward ? opts.last : opts.first) ?? 50;
+  if (!Number.isInteger(size) || size < 1 || size > 1e3) throw invalidPage("page size must be an integer between 1 and 1000");
+  if (primaryKey.length === 0) throw new Error("page requires a declared primary key for a unique, stable ordering");
+  const input = opts.orderBy === void 0 ? [] : Array.isArray(opts.orderBy) ? opts.orderBy : [
+    opts.orderBy
+  ];
+  if (input.length > 16) throw invalidPage("page supports at most 16 ordering columns");
+  const seen = /* @__PURE__ */ new Set();
+  const order = [];
+  const add = /* @__PURE__ */ __name((o) => {
+    const def = columns[o?.column];
+    if (!Object.hasOwn(columns, o?.column) || !def) throw invalidPage(`page order column ${o?.column} is not declared`);
+    if (!(/* @__PURE__ */ new Set([
+      "uuid",
+      "text",
+      "integer",
+      "bigint",
+      "boolean",
+      "timestamp",
+      "numeric",
+      "enum"
+    ])).has(def.type ?? "")) {
+      throw invalidPage(`page cannot order ${o.column}: ${def.type ?? "unknown"} is not a supported scalar column`);
+    }
+    if (seen.has(o.column)) throw invalidPage(`page order column ${o.column} is repeated`);
+    if (o.direction !== void 0 && o.direction !== "asc" && o.direction !== "desc") throw invalidPage("page direction must be asc or desc");
+    if (o.nulls !== void 0 && o.nulls !== "first" && o.nulls !== "last") throw invalidPage("page nulls must be first or last");
+    const direction = o.direction ?? "asc";
+    seen.add(o.column);
+    order.push({
+      column: o.column,
+      direction,
+      nulls: o.nulls ?? (direction === "asc" ? "last" : "first"),
+      nullable: def.nullable !== false
+    });
+  }, "add");
+  for (const o of input) add(o);
+  for (const column of primaryKey) if (!seen.has(column)) add({
+    column,
+    direction: order.at(-1)?.direction ?? "asc"
+  });
+  return {
+    order,
+    size,
+    backward,
+    token: backward ? opts.before : opts.after
+  };
+}
+__name(pageOrder, "pageOrder");
+function pageBoundary(order, values, backward, bind, column, inclusive = false) {
+  const refs = values.map((v) => bind(v));
+  if (order.every((o) => !o.nullable && o.direction === order[0].direction) && values.every((v) => v !== null)) {
+    const greater = order[0].direction === "asc" !== backward;
+    return `(${order.map((o) => column(o.column)).join(", ")}) ${greater ? ">" : "<"}${inclusive ? "=" : ""} (${refs.join(", ")})`;
+  }
+  const parts = [];
+  const prefix = [];
+  for (let i = 0; i < order.length; i++) {
+    const o = order[i], c = column(o.column), r = refs[i];
+    const nullsLast = o.nulls === "last" !== backward;
+    const cmp = o.direction === "asc" !== backward ? ">" : "<";
+    const tail = values[i] === null ? nullsLast ? "false" : `${c} IS NOT NULL` : `(${c} ${cmp} ${r}${nullsLast ? ` OR ${c} IS NULL` : ""})`;
+    parts.push(`(${[
+      ...prefix,
+      tail
+    ].join(" AND ")})`);
+    prefix.push(`${c} IS NOT DISTINCT FROM ${r}`);
+  }
+  if (inclusive) parts.push(`(${prefix.join(" AND ")})`);
+  return `(${parts.join(" OR ")})`;
+}
+__name(pageBoundary, "pageBoundary");
+
+// src/engine/commands.ts
+var installed = /* @__PURE__ */ new WeakSet();
+var hasCommandExecutor = /* @__PURE__ */ __name((sql) => installed.has(sql), "hasCommandExecutor");
+var COMMAND_EXECUTOR_DDL = `
+CREATE SCHEMA IF NOT EXISTS palbase_runtime;
+CREATE OR REPLACE FUNCTION palbase_runtime.command_v1(steps jsonb) RETURNS jsonb
+LANGUAGE plpgsql VOLATILE SECURITY INVOKER SET search_path = pg_catalog, public AS $pb_command$
+DECLARE
+  results jsonb := '[]'::jsonb;
+  step jsonb; chunk jsonb; binding jsonb; source jsonb; rows jsonb;
+  statement text; rendered text; detail text; guard jsonb;
+  index integer := 0; affected integer; passed boolean;
+BEGIN
+  FOR step IN SELECT value FROM jsonb_array_elements(steps) LOOP
+    IF step->>'empty' = 'true' THEN rows := '[]'::jsonb;
+    ELSE
+      statement := '';
+      FOR chunk IN SELECT value FROM jsonb_array_elements(step->'chunks') LOOP
+        IF jsonb_typeof(chunk) = 'string' THEN statement := statement || (chunk #>> '{}');
+        ELSE
+          binding := step->'bindings'->((chunk->>'bind')::integer);
+          IF binding ? 'ref' THEN
+            source := results->((binding->'ref'->>'op')::integer)->'rows'->0;
+            IF source IS NULL OR NOT source ? (binding->'ref'->>'field') THEN
+              RAISE EXCEPTION 'Command reference has no source row/column; use expectOne before reading it'
+                USING ERRCODE = 'PBC02', DETAIL = jsonb_build_object('error_code','tx_ref_unresolved','op',index)::text;
+            END IF;
+            source := source->(binding->'ref'->>'field');
+          ELSE source := binding->'value'; END IF;
+          rendered := CASE WHEN source IS NULL OR source = 'null'::jsonb THEN NULL
+            WHEN binding->>'json' = 'true' THEN source::text
+            WHEN jsonb_typeof(source) = 'string' THEN source #>> '{}' ELSE source::text END;
+          -- PostgreSQL quotes the value itself. Values reach this function as
+          -- one bound JSON parameter, never as application-generated SQL text.
+          statement := statement || quote_nullable(rendered);
+        END IF;
+      END LOOP;
+      EXECUTE statement INTO rows;
+    END IF;
+    affected := jsonb_array_length(rows);
+    guard := step->'guard';
+    IF guard IS NOT NULL AND guard <> 'null'::jsonb THEN
+      passed := CASE guard->>'kind'
+        WHEN 'one' THEN affected = 1 WHEN 'none' THEN affected = 0
+        WHEN 'atLeast' THEN affected >= (guard->>'n')::integer
+        WHEN 'atMost' THEN affected <= (guard->>'n')::integer ELSE false END;
+      IF NOT passed THEN
+        RAISE EXCEPTION 'Command expectation failed'
+          USING ERRCODE = 'PBC01', DETAIL = jsonb_build_object('error_code','tx_guard_failed','slot',guard->'slot','op',index)::text;
+      END IF;
+    END IF;
+    results := results || jsonb_build_array(jsonb_build_object('rows',rows,'rows_affected',affected));
+    index := index + 1;
+  END LOOP;
+  RETURN jsonb_build_object('results',results);
+EXCEPTION WHEN SQLSTATE 'PBC01' OR SQLSTATE 'PBC02' THEN
+  GET STACKED DIAGNOSTICS detail = PG_EXCEPTION_DETAIL;
+  RETURN jsonb_build_object('error',detail::jsonb);
+END
+$pb_command$;
+REVOKE ALL ON FUNCTION palbase_runtime.command_v1(jsonb) FROM PUBLIC;
+CREATE OR REPLACE FUNCTION palbase_runtime.command_rows_v1(rows jsonb, guard jsonb) RETURNS jsonb
+LANGUAGE plpgsql VOLATILE SECURITY INVOKER SET search_path = pg_catalog, public AS $pb_rows$
+DECLARE affected integer := jsonb_array_length(rows); passed boolean;
+BEGIN
+  IF guard IS NOT NULL AND guard <> 'null'::jsonb THEN
+    passed := CASE guard->>'kind'
+      WHEN 'one' THEN affected = 1 WHEN 'none' THEN affected = 0
+      WHEN 'atLeast' THEN affected >= (guard->>'n')::integer
+      WHEN 'atMost' THEN affected <= (guard->>'n')::integer ELSE false END;
+    IF NOT passed THEN
+      RAISE EXCEPTION 'Command expectation failed'
+        USING ERRCODE = 'PBC01', DETAIL = jsonb_build_object('error_code','tx_guard_failed','slot',guard->'slot')::text;
+    END IF;
+  END IF;
+  RETURN rows;
+END
+$pb_rows$;
+REVOKE ALL ON FUNCTION palbase_runtime.command_rows_v1(jsonb,jsonb) FROM PUBLIC;
+`;
+async function installCommandExecutor(sql, roles) {
+  const quote = /* @__PURE__ */ __name((s) => `"${s.replace(/"/g, '""')}"`, "quote");
+  if (roles.length === 0) throw new Error("Command executor needs explicit runtime roles");
+  await sql.begin(async (tx) => {
+    await tx.unsafe("SELECT pg_advisory_xact_lock(196754721, 1)");
+    await tx.unsafe(COMMAND_EXECUTOR_DDL);
+    const list = [
+      ...new Set(roles)
+    ].map(quote).join(", ");
+    await tx.unsafe(`GRANT USAGE ON SCHEMA palbase_runtime TO ${list}`);
+    await tx.unsafe(`GRANT EXECUTE ON FUNCTION palbase_runtime.command_v1(jsonb) TO ${list}`);
+    await tx.unsafe(`GRANT EXECUTE ON FUNCTION palbase_runtime.command_rows_v1(jsonb,jsonb) TO ${list}`);
+  });
+  installed.add(sql);
+}
+__name(installCommandExecutor, "installCommandExecutor");
+function parameterChunks(sql) {
+  const chunks = [];
+  let start = 0, quote = null;
+  for (let i = 0; i < sql.length; i++) {
+    const c = sql[i];
+    if (quote) {
+      if (c === quote) {
+        if (sql[i + 1] === quote) i++;
+        else quote = null;
+      }
+      continue;
+    }
+    if (c === "'" || c === '"') {
+      quote = c;
+      continue;
+    }
+    if (c !== "$") continue;
+    const parameter = /^\$(\d+)\b/.exec(sql.slice(i));
+    if (!parameter) continue;
+    chunks.push(sql.slice(start, i), {
+      bind: Number(parameter[1]) - 1
+    });
+    i += parameter[0].length - 1;
+    start = i + 1;
+  }
+  chunks.push(sql.slice(start));
+  return chunks;
+}
+__name(parameterChunks, "parameterChunks");
+
+// src/engine/admission.ts
+var WorkloadAdmission = class {
+  static {
+    __name(this, "WorkloadAdmission");
+  }
+  definition;
+  pending = [];
+  active = 0;
+  activeKeys = /* @__PURE__ */ new Set();
+  tenants = /* @__PURE__ */ new Map();
+  draining = false;
+  constructor(definition) {
+    this.definition = definition;
+    validateWorkload(definition);
+  }
+  get snapshot() {
+    return {
+      active: this.active,
+      queued: this.pending.length,
+      tenants: this.tenants.size,
+      keys: this.activeKeys.size
+    };
+  }
+  acquire(tenant, keys, signal) {
+    if (signal?.aborted) return Promise.reject(signal.reason ?? new Error("Database admission cancelled"));
+    const normalized = [
+      ...new Set(keys)
+    ].sort();
+    if (normalized.length > 64 || normalized.some((k) => typeof k !== "string" || k.length === 0 || k.length > 256)) return Promise.reject(new Error("conflictKeys must contain at most 64 nonempty strings of at most 256 characters"));
+    const scoped = normalized;
+    const globalFull = this.pending.length >= this.definition.queueLimit;
+    const tenantFull = this.pending.filter((w) => w.tenant === tenant).length >= this.definition.tenantQueueLimit;
+    const canStart = this.active < this.definition.concurrency && (this.tenants.get(tenant) ?? 0) < this.definition.tenantConcurrency && scoped.every((k) => !this.activeKeys.has(k) && !this.pending.some((w) => w.keys.includes(k)));
+    if (!canStart && (globalFull || tenantFull)) {
+      return Promise.reject(new TooManyRequests({
+        retryAfter: 1
+      }, `Database workload ${this.definition.name}: ${tenantFull ? "tenant" : "global"} queue is full`));
+    }
+    return new Promise((grant, reject) => {
+      const waiter = {
+        tenant,
+        keys: scoped,
+        entered: performance.now(),
+        grant,
+        reject,
+        cleanup: /* @__PURE__ */ __name(() => {
+        }, "cleanup")
+      };
+      const remove = /* @__PURE__ */ __name((reason) => {
+        const index = this.pending.indexOf(waiter);
+        if (index === -1) return;
+        this.pending.splice(index, 1);
+        waiter.cleanup();
+        reject(reason);
+        this.drain();
+      }, "remove");
+      const abort = /* @__PURE__ */ __name(() => remove(signal?.reason ?? new Error("Database admission cancelled")), "abort");
+      const timer = setTimeout(() => remove(new TooManyRequests({
+        retryAfter: 1
+      }, `Database workload ${this.definition.name}: queue deadline exceeded`)), this.definition.queueTimeoutMs);
+      waiter.cleanup = () => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", abort);
+      };
+      signal?.addEventListener("abort", abort, {
+        once: true
+      });
+      this.pending.push(waiter);
+      if (signal?.aborted) abort();
+      else this.drain();
+    });
+  }
+  drain() {
+    if (this.draining) return;
+    this.draining = true;
+    try {
+      const blockedKeys = /* @__PURE__ */ new Set();
+      for (let index = 0; index < this.pending.length && this.active < this.definition.concurrency; ) {
+        const waiter = this.pending[index];
+        if ((this.tenants.get(waiter.tenant) ?? 0) >= this.definition.tenantConcurrency || waiter.keys.some((key2) => this.activeKeys.has(key2) || blockedKeys.has(key2))) {
+          for (const key2 of waiter.keys) blockedKeys.add(key2);
+          index++;
+          continue;
+        }
+        this.pending.splice(index, 1);
+        waiter.cleanup();
+        this.active++;
+        this.tenants.set(waiter.tenant, (this.tenants.get(waiter.tenant) ?? 0) + 1);
+        for (const key2 of waiter.keys) this.activeKeys.add(key2);
+        let released = false;
+        waiter.grant({
+          queueMs: performance.now() - waiter.entered,
+          release: /* @__PURE__ */ __name(() => {
+            if (released) return;
+            released = true;
+            this.active--;
+            const left = this.tenants.get(waiter.tenant) - 1;
+            if (left === 0) this.tenants.delete(waiter.tenant);
+            else this.tenants.set(waiter.tenant, left);
+            for (const key2 of waiter.keys) this.activeKeys.delete(key2);
+            this.drain();
+          }, "release")
+        });
+      }
+    } finally {
+      this.draining = false;
+    }
+  }
+};
+var registries = /* @__PURE__ */ new WeakMap();
+function workloadAdmission(owner, definition) {
+  validateWorkload(definition);
+  let registry = registries.get(owner);
+  if (!registry) {
+    registry = /* @__PURE__ */ new Map();
+    registries.set(owner, registry);
+  }
+  const existing = registry.get(definition.name);
+  if (existing) {
+    const d = existing.definition;
+    if (Object.keys(d).some((k) => d[k] !== definition[k])) throw new Error(`Workload ${definition.name} was already registered with different limits`);
+    return existing;
+  }
+  if (registry.size >= 64) throw new Error("At most 64 named database workloads may be registered per engine; declare and reuse them at module scope");
+  const admission = new WorkloadAdmission(Object.freeze({
+    ...definition
+  }));
+  registry.set(definition.name, admission);
+  return admission;
+}
+__name(workloadAdmission, "workloadAdmission");
+function workloadTenant(definition, claimsJson) {
+  const claims = JSON.parse(claimsJson);
+  const value = claims[definition.tenantClaim] ?? claims.sub;
+  return typeof value === "string" && value.length > 0 ? value : "__anonymous__";
+}
+__name(workloadTenant, "workloadTenant");
+
+// src/engine/transaction-control.ts
+var TransactionControl = class {
+  static {
+    __name(this, "TransactionControl");
+  }
+  controller = new AbortController();
+  active = /* @__PURE__ */ new Set();
+  cancelBackend;
+  cancellation = Promise.resolve();
+  timer;
+  unlink;
+  rejection;
+  deadline;
+  get signal() {
+    return this.controller.signal;
+  }
+  constructor(timeoutMs, external) {
+    this.deadline = timeoutMs === void 0 ? void 0 : performance.now() + timeoutMs;
+    this.rejection = new Promise((_, reject) => {
+      this.signal.addEventListener("abort", () => {
+        reject(this.signal.reason);
+        if (this.active.size && this.cancelBackend) {
+          this.cancellation = this.cancelBackend().catch(() => void 0);
+        } else {
+          for (const query of this.active) {
+            try {
+              query.cancel?.();
+            } catch {
+            }
+          }
+        }
+      }, {
+        once: true
+      });
+    });
+    void this.rejection.catch(() => void 0);
+    const abort = /* @__PURE__ */ __name(() => this.controller.abort(external?.reason ?? new DOMException("Database transaction cancelled", "AbortError")), "abort");
+    external?.addEventListener("abort", abort, {
+      once: true
+    });
+    this.unlink = () => external?.removeEventListener("abort", abort);
+    if (external?.aborted) abort();
+    if (timeoutMs !== void 0) this.timer = setTimeout(() => this.controller.abort(new HttpError(503, "database_deadline_exceeded", "Database transaction exceeded its deadline")), timeoutMs);
+  }
+  check() {
+    if (this.deadline !== void 0 && performance.now() >= this.deadline && !this.signal.aborted) {
+      this.controller.abort(new HttpError(503, "database_deadline_exceeded", "Database transaction exceeded its deadline"));
+    }
+    this.signal.throwIfAborted();
+  }
+  remainingMs() {
+    this.check();
+    return this.deadline === void 0 ? void 0 : Math.max(1, Math.ceil(this.deadline - performance.now()));
+  }
+  race(work) {
+    return Promise.race([
+      work,
+      this.rejection
+    ]);
+  }
+  bindBackend(cancel) {
+    this.cancelBackend = cancel;
+  }
+  /** Keep the application's connection parked until the cancellation request
+  * and all statements settle; a late cancel must not hit its next borrower. */
+  async drainCancellation() {
+    await this.cancellation;
+    await Promise.allSettled([
+      ...this.active
+    ]);
+  }
+  async watch(query) {
+    this.active.add(query);
+    try {
+      if (this.signal.aborted) query.cancel?.();
+      return await query;
+    } finally {
+      this.active.delete(query);
+    }
+  }
+  dispose() {
+    if (this.timer !== void 0) clearTimeout(this.timer);
+    this.unlink();
+  }
+};
+
+// src/engine/diagnostics.ts
+import { createHash as createHash2 } from "crypto";
+var DatabaseTrace = class {
+  static {
+    __name(this, "DatabaseTrace");
+  }
+  options;
+  start = performance.now();
+  ended;
+  failure;
+  state;
+  constructor(options) {
+    this.options = options;
+    for (const key2 of [
+      "maxQueries",
+      "maxRows",
+      "maxBytes"
+    ]) {
+      const value = options[key2];
+      if (value !== void 0 && (!Number.isSafeInteger(value) || value < 0)) throw new Error(`database ${key2} must be a nonnegative safe integer`);
+    }
+    this.state = {
+      endpoint: options.endpoint,
+      requestId: options.requestId,
+      outcome: "active",
+      elapsedMs: 0,
+      queries: 0,
+      rows: 0,
+      bytes: 0,
+      queueMs: 0,
+      poolMs: 0,
+      setupMs: 0,
+      sqlMs: 0,
+      commitMs: 0,
+      rollbackMs: 0,
+      commits: 0,
+      commitFailures: 0,
+      rollbackRequests: 0,
+      retries: 0,
+      statements: []
+    };
+  }
+  check() {
+    if (this.failure) throw this.failure;
+  }
+  time(key2, started) {
+    this.state[key2] += performance.now() - started;
+  }
+  retry() {
+    this.state.retries++;
+  }
+  committed() {
+    this.state.commits++;
+  }
+  commitFailed() {
+    this.state.commitFailures++;
+  }
+  failed() {
+    this.state.outcome = "failed";
+  }
+  rolledBack() {
+    this.state.rollbackRequests++;
+  }
+  refuse(kind) {
+    this.failure ??= new HttpError(500, "database_budget_exceeded", `Database ${kind} budget exceeded${this.options.endpoint ? ` in ${this.options.endpoint}` : ""}`);
+    throw this.failure;
+  }
+  emit(callback, event) {
+    try {
+      const result = callback?.(event);
+      if (result) void Promise.resolve(result).catch(() => void 0);
+    } catch {
+    }
+  }
+  async query(sql, name, run) {
+    this.check();
+    if (this.options.maxQueries !== void 0 && this.state.queries >= this.options.maxQueries) this.refuse("query count");
+    const ordinal = ++this.state.queries;
+    const event = {
+      ordinal,
+      fingerprint: createHash2("sha256").update(sql).digest("hex").slice(0, 24),
+      ...name === void 0 ? {} : {
+        name: name.slice(0, 128)
+      },
+      ...this.options.includeSql ? {
+        sql: sql.slice(0, 4096)
+      } : {},
+      durationMs: 0,
+      rows: 0,
+      bytes: 0
+    };
+    if (this.options.captureSource) event.source = new Error().stack?.split("\n").slice(1, 9).join("\n").slice(0, 2500);
+    const started = performance.now();
+    let measured = false;
+    try {
+      const result = await run();
+      event.durationMs = performance.now() - started;
+      measured = true;
+      if (Array.isArray(result)) {
+        event.rows = result.length;
+        event.bytes = Buffer.byteLength(JSON.stringify(result, (_, value) => typeof value === "bigint" ? value.toString() : value));
+      }
+      this.state.rows += event.rows;
+      this.state.bytes += event.bytes;
+      if (this.options.maxRows !== void 0 && this.state.rows > this.options.maxRows) this.refuse("returned rows");
+      if (this.options.maxBytes !== void 0 && this.state.bytes > this.options.maxBytes) this.refuse("result bytes");
+      return result;
+    } catch (error) {
+      const e = error;
+      event.errorCode = String(e?.sqlstate ?? e?.errno ?? e?.code ?? "query_failed").slice(0, 80);
+      throw error;
+    } finally {
+      if (!measured) event.durationMs = performance.now() - started;
+      this.state.sqlMs += event.durationMs;
+      const frozen = Object.freeze(event);
+      if (this.state.statements.length < 200) this.state.statements.push(frozen);
+      this.emit(this.options.onQuery, frozen);
+    }
+  }
+  get snapshot() {
+    return Object.freeze({
+      ...this.state,
+      elapsedMs: (this.ended ?? performance.now()) - this.start,
+      statements: Object.freeze([
+        ...this.state.statements
+      ].sort((a, b) => a.ordinal - b.ordinal))
+    });
+  }
+  complete(outcome) {
+    if (this.ended !== void 0) return;
+    this.ended = performance.now();
+    this.state.outcome = outcome;
+    this.emit(this.options.onComplete, this.snapshot);
+  }
+};
+
 // src/engine/db.ts
 function quoteIdent(name) {
   return `"${name.replace(/"/g, '""')}"`;
 }
 __name(quoteIdent, "quoteIdent");
-function quoteTable(key) {
-  const dot = key.indexOf(".");
-  if (dot === -1) return quoteIdent(key);
-  return `${quoteIdent(key.slice(0, dot))}.${quoteIdent(key.slice(dot + 1))}`;
+function quoteTable(key2) {
+  const dot = key2.indexOf(".");
+  if (dot === -1) return quoteIdent(key2);
+  return `${quoteIdent(key2.slice(0, dot))}.${quoteIdent(key2.slice(dot + 1))}`;
 }
 __name(quoteTable, "quoteTable");
 function encodePgArray(value) {
@@ -411,9 +1117,10 @@ function encodePgArray(value) {
 }
 __name(encodePgArray, "encodePgArray");
 var BIND_SQL = "select set_config('role',$1,true), set_config('search_path','public',true), set_config('request.jwt.claims',$2,true)";
+var atomicScope = new AsyncLocalStorage();
 function createLazyTransaction(sql, role, claimsJson, options = {}) {
   const { lockTimeout } = options;
-  const bindSql = lockTimeout ? `${BIND_SQL}, set_config('lock_timeout',$3,true)` : BIND_SQL;
+  let bindSql = lockTimeout ? `${BIND_SQL}, set_config('lock_timeout',$3,true)` : BIND_SQL;
   const bindParams = lockTimeout ? [
     role,
     claimsJson,
@@ -422,25 +1129,118 @@ function createLazyTransaction(sql, role, claimsJson, options = {}) {
     role,
     claimsJson
   ];
+  if (options.statementTimeout !== void 0) {
+    bindParams.push(options.statementTimeout);
+    bindSql += `, set_config('statement_timeout',$${bindParams.length},true)`;
+  }
   let opening = null;
   let release = null;
   let fail = null;
   let settled = null;
-  const ensure = /* @__PURE__ */ __name(() => {
+  let closed = false;
+  const assertAccess = /* @__PURE__ */ __name(() => {
+    if (closed) throw new Error("Database transaction has settled; its handle cannot be used again");
+    options.control?.check();
+    options.trace?.check();
+    if (atomicScope.getStore() !== options.scope) {
+      throw new Error("Database.$atomic cannot use a handle from another transaction or identity; use its tx argument");
+    }
+  }, "assertAccess");
+  let savepointALS;
+  let activeSavepoint;
+  const pendingSavepoints = /* @__PURE__ */ new Set();
+  const scoped = /* @__PURE__ */ __name((tx, checkParent = assertAccess, owner, children = /* @__PURE__ */ new Set()) => {
+    const access = /* @__PURE__ */ __name(() => {
+      checkParent();
+      if (activeSavepoint !== owner || savepointALS?.getStore() !== owner) {
+        throw new Error("Database connection belongs to another active savepoint; use its tx argument and await it before using the parent handle");
+      }
+    }, "access");
+    return {
+      async unsafe(text, params, metadata) {
+        access();
+        const run = /* @__PURE__ */ __name(() => {
+          const query = tx.unsafe(text, params);
+          return options.control ? options.control.watch(query) : query;
+        }, "run");
+        return options.trace ? options.trace.query(text, metadata?.name, run) : run();
+      },
+      async savepoint(fn) {
+        access();
+        const token = /* @__PURE__ */ Symbol("savepoint"), descendants = /* @__PURE__ */ new Set();
+        savepointALS ??= new AsyncLocalStorage();
+        activeSavepoint = token;
+        const work = (async () => {
+          try {
+            return await tx.savepoint(async (sp) => {
+              let ended = false;
+              const check = /* @__PURE__ */ __name(() => {
+                checkParent();
+                if (ended) throw new Error("Database savepoint has settled; its handle cannot be used again");
+              }, "check");
+              try {
+                const callback = savepointALS.run(token, () => fn(scoped(sp, check, token, descendants)));
+                return await (options.control ? options.control.race(callback) : callback);
+              } finally {
+                if (descendants.size) await Promise.allSettled([
+                  ...descendants
+                ]);
+                ended = true;
+              }
+            });
+          } finally {
+            activeSavepoint = owner;
+          }
+        })();
+        pendingSavepoints.add(work);
+        children.add(work);
+        try {
+          return await work;
+        } finally {
+          pendingSavepoints.delete(work);
+          children.delete(work);
+        }
+      }
+    };
+  }, "scoped");
+  const ensure = /* @__PURE__ */ __name(async () => {
+    assertAccess();
     if (opening) return opening;
     opening = new Promise((resolveTx2, rejectTx) => {
       const parked = new Promise((res, rej) => {
         release = res;
         fail = rej;
       });
+      void parked.catch(() => void 0);
+      const openingAt = options.trace ? performance.now() : 0;
       settled = sql.begin(async (tx) => {
-        await tx.unsafe(bindSql, bindParams);
-        resolveTx2(tx);
+        options.trace?.time("poolMs", openingAt);
+        const setupAt = options.trace ? performance.now() : 0;
+        options.control?.check();
+        if (options.isolation !== void 0 || options.readOnly !== void 0) {
+          const isolation = options.isolation ?? "read committed";
+          validateAtomicOptions({
+            isolation,
+            readOnly: options.readOnly
+          });
+          await tx.unsafe(`SET TRANSACTION ISOLATION LEVEL ${isolation.toUpperCase()}${options.readOnly === void 0 ? "" : options.readOnly ? " READ ONLY" : " READ WRITE"}`);
+        }
+        if (options.control && sql.cancelBackend) {
+          const ticket = await tx.unsafe("SELECT pg_backend_pid() AS pid, backend_start::text AS started FROM pg_stat_activity WHERE pid=pg_backend_pid()");
+          if (!Number.isInteger(ticket[0]?.pid) || typeof ticket[0]?.started !== "string") throw new Error("Database cancellation cannot identify its own backend");
+          options.control.bindBackend(() => sql.cancelBackend(ticket[0].pid, ticket[0].started));
+          options.control.check();
+        }
+        const binding = tx.unsafe(bindSql, bindParams);
+        await (options.control ? options.control.watch(binding) : binding);
+        options.trace?.time("setupMs", setupAt);
+        resolveTx2(scoped(tx));
         await parked;
       }).catch((e) => {
         rejectTx(e);
         throw e;
       });
+      void settled.catch(() => void 0);
     });
     return opening;
   }, "ensure");
@@ -450,14 +1250,37 @@ function createLazyTransaction(sql, role, claimsJson, options = {}) {
       return opening !== null;
     },
     async commit() {
+      if (pendingSavepoints.size) await Promise.allSettled([
+        ...pendingSavepoints
+      ]);
+      options.control?.check();
+      options.trace?.check();
+      closed = true;
       if (!opening) return;
+      const started = options.trace ? performance.now() : 0;
       release();
-      await settled;
+      try {
+        await settled;
+        options.trace?.committed();
+      } catch (error) {
+        options.trace?.commitFailed();
+        throw error;
+      } finally {
+        options.trace?.time("commitMs", started);
+      }
     },
     async rollback(reason) {
+      closed = true;
       if (!opening) return;
+      await options.control?.drainCancellation();
+      if (pendingSavepoints.size) await Promise.allSettled([
+        ...pendingSavepoints
+      ]);
+      const started = options.trace ? performance.now() : 0;
       fail(reason);
       await settled?.catch(() => void 0);
+      options.trace?.time("rollbackMs", started);
+      options.trace?.rolledBack();
     }
   };
 }
@@ -472,7 +1295,7 @@ __name(asWireValue, "asWireValue");
 function asWireRow(row) {
   if (row === null || typeof row !== "object") return row;
   const out = {};
-  for (const [key, value] of Object.entries(row)) out[key] = asWireValue(value);
+  for (const [key2, value] of Object.entries(row)) out[key2] = asWireValue(value);
   return out;
 }
 __name(asWireRow, "asWireRow");
@@ -484,7 +1307,7 @@ function toVectorLiteral(v) {
   return `[${v.join(",")}]`;
 }
 __name(toVectorLiteral, "toVectorLiteral");
-function vectorColumnsOf(schema, table) {
+function computeVectorColumns(schema, table) {
   const out = /* @__PURE__ */ new Set();
   const def = tableDefOf(table, schema);
   if (def) {
@@ -495,9 +1318,9 @@ function vectorColumnsOf(schema, table) {
   }
   return out;
 }
-__name(vectorColumnsOf, "vectorColumnsOf");
-function tableDefOf(key, schema = currentSchema) {
-  return schema.tables?.[key] ?? null;
+__name(computeVectorColumns, "computeVectorColumns");
+function tableDefOf(key2, schema = currentSchema) {
+  return schema.tables?.[key2] ?? null;
 }
 __name(tableDefOf, "tableDefOf");
 function reviveVectors(row, vectorCols) {
@@ -510,7 +1333,7 @@ function reviveVectors(row, vectorCols) {
   return row;
 }
 __name(reviveVectors, "reviveVectors");
-function transformsOf(schema, table) {
+function computeTransforms(schema, table) {
   const out = /* @__PURE__ */ new Map();
   const def = tableDefOf(table, schema);
   if (def) {
@@ -533,7 +1356,7 @@ function transformsOf(schema, table) {
   }
   return out;
 }
-__name(transformsOf, "transformsOf");
+__name(computeTransforms, "computeTransforms");
 function applyFromDb(row, transforms) {
   if (transforms.size === 0) return row;
   for (const [col, t] of transforms) {
@@ -550,10 +1373,23 @@ function asTableRow(table, row) {
   return applyFromDb(revived, transformsOf(currentSchema, table));
 }
 __name(asTableRow, "asTableRow");
-function asTableRows(table, rows) {
+function asTableRows(table, rows, withSpec) {
   const vectorCols = vectorColumnsOf(currentSchema, table);
   const transforms = transformsOf(currentSchema, table);
-  return rows.map((row) => applyFromDb(reviveVectors(asWireRow(row), vectorCols), transforms));
+  const result = rows.map((row) => applyFromDb(reviveVectors(asWireRow(row), vectorCols), transforms));
+  if (withSpec) for (const rel of currentRelations.get(table) ?? []) {
+    const spec = withSpec[rel.name];
+    if (!spec) continue;
+    const nested = typeof spec === "object" ? spec.with : void 0;
+    for (const row of result) {
+      const value = row[rel.name];
+      if (Array.isArray(value)) row[rel.name] = asTableRows(rel.to, value, nested);
+      else if (value && typeof value === "object") row[rel.name] = asTableRows(rel.to, [
+        value
+      ], nested)[0];
+    }
+  }
+  return result;
 }
 __name(asTableRows, "asTableRows");
 function asBindParams(table, cols, data, caller) {
@@ -796,7 +1632,7 @@ function excludeSql(pk, ids, add) {
   return ` AND t.${quoteIdent(pk)}::text <> ALL(ARRAY[${ids.map((x) => add(x)).join(", ")}])`;
 }
 __name(excludeSql, "excludeSql");
-function primaryKeyOf(table) {
+function computePrimaryKey(table) {
   const t = tableDefOf(table);
   const columns = t?.columns ?? {};
   const cols = Object.keys(columns);
@@ -816,7 +1652,7 @@ function primaryKeyOf(table) {
   const pks = cols.filter((c) => pkOf(columns[c]));
   return pks.length === 1 ? pks[0] : null;
 }
-__name(primaryKeyOf, "primaryKeyOf");
+__name(computePrimaryKey, "computePrimaryKey");
 function isSinglePkEquality(where, pk) {
   if (pk === null) return false;
   const keys = Object.keys(where);
@@ -831,12 +1667,43 @@ function assertNotAppendOnly(caller, table) {
   throw new Error(`${caller}(${table}): "${table}" append-only \u2014 sat\u0131r g\xFCncellenemez ya da silinemez. D\xFCzeltme i\xE7in TELAF\u0130 KAYDI ekleyin: insert("${table}", { \u2026 }) ile ters i\u015Fareti ta\u015F\u0131yan yeni bir sat\u0131r yaz\u0131n; ge\xE7mi\u015F oldu\u011Fu gibi kals\u0131n diye tablo b\xF6yle bildirilmi\u015F (appendOnly: true).`);
 }
 __name(assertNotAppendOnly, "assertNotAppendOnly");
-function schemaColumns(table) {
+function computeSchemaColumns(table) {
   const t = tableDefOf(table);
   const cols = t?.columns ? Object.keys(t.columns) : [];
   return cols.length > 0 ? new Set(cols) : null;
 }
-__name(schemaColumns, "schemaColumns");
+__name(computeSchemaColumns, "computeSchemaColumns");
+function timestampResult(expr) {
+  return `CASE WHEN isfinite(${expr}) AND extract(year FROM ${expr} AT TIME ZONE 'UTC') BETWEEN 1 AND 9999 THEN to_char(${expr} AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"') ELSE ${expr}::text END`;
+}
+__name(timestampResult, "timestampResult");
+function columnResult(table, column, alias) {
+  const expr = `${alias ? `${quoteIdent(alias)}.` : ""}${quoteIdent(column)}`;
+  return columnTypeOf(table, column) === "timestamp" ? timestampResult(expr) : expr;
+}
+__name(columnResult, "columnResult");
+function projectedColumn(table, column, alias) {
+  const expr = columnResult(table, column, alias);
+  return columnTypeOf(table, column) === "timestamp" ? `${expr} AS ${quoteIdent(column)}` : expr;
+}
+__name(projectedColumn, "projectedColumn");
+function rowProjection(table, alias, wildcard = alias ? `${alias}.*` : "*") {
+  const cols = schemaColumns(table);
+  if (!cols || !memoTable(timestampMemo, currentSchema, table, () => [
+    ...cols
+  ].some((c) => columnTypeOf(table, c) === "timestamp"))) return wildcard;
+  const projections = memoTable(projectionMemo, currentSchema, table, () => /* @__PURE__ */ new Map());
+  const key2 = alias ?? "";
+  let sql = projections.get(key2);
+  if (sql === void 0) {
+    sql = [
+      ...cols
+    ].map((c) => projectedColumn(table, c, alias)).join(", ");
+    projections.set(key2, sql);
+  }
+  return sql;
+}
+__name(rowProjection, "rowProjection");
 function colRefSql(table, known, ref, caller, alias = "t") {
   const name = ref.$col;
   const shapeOK = /^[A-Za-z_][A-Za-z0-9_]*$/.test(name);
@@ -850,13 +1717,13 @@ function selectClause(table, known, select) {
   if (select !== void 0 && select.length === 0) {
     throw new Error(`findMany(${table}): select bo\u015F bir liste ald\u0131 \u2014 bu "hepsini ver" DE\u011E\u0130L, "hi\xE7birini saymad\u0131m" demek. Projeksiyon istemiyorsan\u0131z anahtar\u0131 hi\xE7 koymay\u0131n; istiyorsan\u0131z en az bir kolon ad\u0131 verin.`);
   }
-  if (select === void 0) return "*";
+  if (select === void 0) return rowProjection(table, "t", "*");
   return select.map((col) => {
     const shapeOK = /^[A-Za-z_][A-Za-z0-9_]*$/.test(col);
     if (known !== null ? !known.has(col) : !shapeOK) {
       throw new Error(`findMany(${table}): select kolonu "${col}" tabloda yok`);
     }
-    return `t.${quoteIdent(col)}`;
+    return columnTypeOf(table, col) === "timestamp" ? projectedColumn(table, col, "t") : `t.${quoteIdent(col)}`;
   }).join(", ");
 }
 __name(selectClause, "selectClause");
@@ -926,7 +1793,7 @@ function compileWhereBare(table, colSet, where, add, caller = "search", alias =
   const transforms = transformsOf(currentSchema, table);
   const bindFor = /* @__PURE__ */ __name((col) => {
     const t = transforms.get(col);
-    return t?.toDb === void 0 ? add : (v) => add(v === null || v === void 0 ? v : t.toDb(v));
+    return (v) => add(t?.toDb === void 0 || v === null || v === void 0 ? v : t.toDb(v), col, table);
   }, "bindFor");
   assertUsableFilter(caller, table, where);
   if (isSqlFragment(where)) {
@@ -957,8 +1824,7 @@ function compileWhereBare(table, colSet, where, add, caller = "search", alias =
           const known = rels.map((r) => r.name).sort();
           throw new Error(`${caller}(${table}): has.${relName} diye bir ili\u015Fki yok` + (known.length > 0 ? ` (bilinenler: ${known.join(", ")}). \u0130li\u015Fkiler yabanc\u0131 anahtarlardan T\xDCRET\u0130L\u0130R; ad\u0131n\u0131 de\u011Fi\u015Ftirmek i\xE7in references(..., { as, reverseAs }).` : `. Bu tablo H\u0130\xC7 yabanc\u0131 anahtar bildirmiyor, ve ili\u015Fkiler onlardan T\xDCRET\u0130L\u0130R. Var olan bir veritaban\u0131ndan introspect edilmi\u015F \u015Femalarda bu s\u0131k olur: kolon \`text()\`/\`uuid()\` olarak durur, \`references(() => <tablo>.<kolon>)\` yoktur. Bildirdi\u011Finiz anda ili\u015Fki iki tarafta da adland\u0131r\u0131l\u0131r \u2014 ama bu CANLI veritaban\u0131na giden bir k\u0131s\u0131tt\u0131r ve mevcut yetim sat\u0131rlar onu d\xFC\u015F\xFCr\xFCr; \xF6nce onlar\u0131 say\u0131n.`));
         }
-        const ourCol = rel.kind === "many" ? primaryKeyOf(table) : rel.via;
-        const theirCol = rel.kind === "many" ? rel.via : primaryKeyOf(rel.to);
+        const [ourCol, theirCol] = relationColumns(table, rel);
         if (ourCol === null || theirCol === null) {
           const missing = ourCol === null ? table : rel.to;
           throw new Error(`${caller}(${table}): has.${relName} kurulam\u0131yor \u2014 "${missing}" tablosunun tek kolonlu bir primary key'i yok. Korelasyon bir anahtar ister; \xE7ok kolonlu anahtarda ili\u015Fki \xFCzerinden s\xFCzmek yerine sqlFragment ile yaz\u0131n.`);
@@ -1096,8 +1962,8 @@ async function embedQuery(embed, text) {
   if (secretReader === null) {
     throw new Error(`query embed: secret reader ba\u011Flanmam\u0131\u015F \u2014 ${embed.apiKeyName} okunam\u0131yor`);
   }
-  const key = await secretReader(embed.apiKeyName);
-  if (key === null || key === "") {
+  const key2 = await secretReader(embed.apiKeyName);
+  if (key2 === null || key2 === "") {
     throw new Error(`query embed: vault'ta ${embed.apiKeyName} yok (FR-021/FR-025)`);
   }
   const url = (embed.baseURL ?? "https://api.openai.com/v1").replace(/\/$/, "") + "/embeddings";
@@ -1108,7 +1974,7 @@ async function embedQuery(embed, text) {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        Authorization: `Bearer ${key}`
+        Authorization: `Bearer ${key2}`
       },
       body: JSON.stringify({
         model: embed.model,
@@ -1166,14 +2032,14 @@ function buildValueTuple(table, cols, data, add, caller) {
   }).join(", ");
 }
 __name(buildValueTuple, "buildValueTuple");
-function columnTypeOf(table, col) {
+function computeColumnType(table, col) {
   const def = tableDefOf(table);
   const c = def?.columns?.[col];
   if (c === void 0 || c === null) return null;
   const d = typeof c === "object" && "_def" in c ? c._def : c;
   return d !== null && typeof d === "object" && typeof d.type === "string" ? d.type : null;
 }
-__name(columnTypeOf, "columnTypeOf");
+__name(computeColumnType, "computeColumnType");
 var NUMERIC_PG_TYPES = /* @__PURE__ */ new Set([
   "integer",
   "bigint",
@@ -1183,23 +2049,44 @@ function aggregateExpr(table, fn, col, alias) {
   const q = `t.${quoteIdent(col)}`;
   const t = columnTypeOf(table, col);
   if (fn === "sum" || fn === "avg") return `${fn}(${q})::text AS ${quoteIdent(alias)}`;
+  if (t === "timestamp") return `${timestampResult(`${fn}(${q})`)} AS ${quoteIdent(alias)}`;
   return t !== null && NUMERIC_PG_TYPES.has(t) && t !== "integer" ? `${fn}(${q})::text AS ${quoteIdent(alias)}` : `${fn}(${q}) AS ${quoteIdent(alias)}`;
 }
 __name(aggregateExpr, "aggregateExpr");
-function jsonObjectFor(table, cols, alias) {
+function jsonObjectFor(table, cols, alias, extra = []) {
   const pairs = cols.map((c) => {
     const t = columnTypeOf(table, c);
-    const expr = t !== null && (t === "numeric" || t === "bigint") ? `${alias}.${quoteIdent(c)}::text` : `${alias}.${quoteIdent(c)}`;
+    const expr = t !== null && (t === "numeric" || t === "bigint") ? `${alias}.${quoteIdent(c)}::text` : t === "timestamp" ? timestampResult(`${alias}.${quoteIdent(c)}`) : `${alias}.${quoteIdent(c)}`;
     return `${quoteLiteral(c)}, ${expr}`;
   });
-  return `json_build_object(${pairs.join(", ")})`;
+  return `json_build_object(${[
+    ...pairs,
+    ...extra
+  ].join(", ")})`;
 }
 __name(jsonObjectFor, "jsonObjectFor");
-function withClauses(table, spec, add, caller) {
+function relationColumns(table, relation) {
+  const child = relation.kind === "many" ? relation.to : table;
+  const value = tableDefOf(child)?.columns?.[relation.via];
+  const column = value && typeof value === "object" && "_def" in value ? value._def : value;
+  const target = column?.references?.column ?? primaryKeyOf(relation.kind === "many" ? table : relation.to);
+  return relation.kind === "many" ? [
+    target,
+    relation.via
+  ] : [
+    relation.via,
+    target
+  ];
+}
+__name(relationColumns, "relationColumns");
+function withClauses(table, spec, add, caller, parentAlias = "t", depth = 0, counter = {
+  value: 0
+}) {
+  if (depth >= 3 && Object.values(spec).some(Boolean)) throw new Error(`${caller}(${table}): with supports at most three relation levels`);
   const rels = currentRelations.get(table) ?? [];
   const select = [];
   const joins = [];
-  let i = 0;
+  const jsonPairs = [];
   for (const [name, opt] of Object.entries(spec)) {
     if (opt === false || opt === void 0) continue;
     const rel = rels.find((r) => r.name === name);
@@ -1207,13 +2094,13 @@ function withClauses(table, spec, add, caller) {
       const known = rels.map((r) => r.name).sort();
       throw new Error(`${caller}(${table}): with.${name} diye bir ili\u015Fki yok` + (known.length > 0 ? ` (bilinenler: ${known.join(", ")})` : `. Bu tablo hi\xE7 yabanc\u0131 anahtar bildirmiyor ve ili\u015Fkiler onlardan T\xDCRET\u0130L\u0130R`) + `. \u0130li\u015Fkiler references(() => <tablo>.<kolon>) ile bildirilir.`);
     }
-    const ourCol = rel.kind === "many" ? primaryKeyOf(table) : rel.via;
-    const theirCol = rel.kind === "many" ? rel.via : primaryKeyOf(rel.to);
+    const [ourCol, theirCol] = relationColumns(table, rel);
     if (ourCol === null || theirCol === null) {
       throw new Error(`${caller}(${table}): with.${name} birincil anahtar bilmeden kurulamaz \u2014 ili\u015Fkinin bir ucu tablonun PK's\u0131 ve bu tablo tek kolonlu bir PK bildirmiyor.`);
     }
     const o = typeof opt === "object" && opt !== null ? opt : {};
-    const childAlias = `w${++i}`;
+    const i = ++counter.value;
+    const childAlias = `w${i}`;
     const childKnown = schemaColumns(rel.to);
     const childCols = Array.isArray(o["select"]) && o["select"].length > 0 ? o["select"] : childKnown !== null ? [
       ...childKnown
@@ -1226,28 +2113,100 @@ function withClauses(table, spec, add, caller) {
         throw new Error(`${caller}(${table}): with.${name}.select kolonu "${c}" "${rel.to}" tablosunda yok`);
       }
     }
-    const obj = jsonObjectFor(rel.to, childCols, childAlias);
+    const nestedSpec = o["with"];
+    if (nestedSpec !== void 0 && (nestedSpec === null || typeof nestedSpec !== "object" || Array.isArray(nestedSpec))) {
+      throw new Error(`${caller}(${table}): with.${name}.with must be a relation object`);
+    }
+    const nested = nestedSpec === void 0 ? {
+      joins: [],
+      jsonPairs: []
+    } : withClauses(rel.to, nestedSpec, add, caller, childAlias, depth + 1, counter);
+    const nestedJoins = nested.joins.length ? ` ${nested.joins.join(" ")}` : "";
+    const obj = jsonObjectFor(rel.to, childCols, childAlias, nested.jsonPairs);
     const innerWhere = o["where"] !== void 0 && o["where"] !== null ? compileWhereBare(rel.to, childKnown, o["where"], add, caller, childAlias, i) : "";
-    const link = `${childAlias}.${quoteIdent(theirCol)} = t.${quoteIdent(ourCol)}`;
+    const link = `${childAlias}.${quoteIdent(theirCol)} = ${parentAlias}.${quoteIdent(ourCol)}`;
     const cond = innerWhere === "" ? link : `${link} AND ${innerWhere}`;
-    const inner = orderClauseFor(rel.to, childKnown, o["orderBy"], childAlias) + limitClause(o["limit"]);
+    const requestedLimit = o["limit"];
+    limitClause(requestedLimit);
+    const relationLimit = rel.kind === "many" ? requestedLimit : Math.min(1, requestedLimit ?? 1);
+    const inner = orderClauseFor(rel.to, childKnown, o["orderBy"], childAlias) + limitClause(relationLimit);
     const outAlias = `wj${i}`;
     if (rel.kind === "many") {
-      joins.push(`LEFT JOIN LATERAL (SELECT coalesce(json_agg(x.o), '[]'::json) AS d FROM (SELECT ${obj} AS o FROM ${quoteTable(rel.to)} ${childAlias} WHERE ${cond}${inner}) x) ${quoteIdent(outAlias)} ON true`);
+      joins.push(`LEFT JOIN LATERAL (SELECT coalesce(json_agg(x.o), '[]'::json) AS d FROM (SELECT ${obj} AS o FROM ${quoteTable(rel.to)} ${childAlias}${nestedJoins} WHERE ${cond}${inner}) x) ${quoteIdent(outAlias)} ON true`);
     } else {
-      joins.push(`LEFT JOIN LATERAL (SELECT ${obj} AS d FROM ${quoteTable(rel.to)} ${childAlias} WHERE ${cond}${inner} LIMIT 1) ${quoteIdent(outAlias)} ON true`);
+      joins.push(`LEFT JOIN LATERAL (SELECT ${obj} AS d FROM ${quoteTable(rel.to)} ${childAlias}${nestedJoins} WHERE ${cond}${inner}) ${quoteIdent(outAlias)} ON true`);
     }
     select.push(`${quoteIdent(outAlias)}."d" AS ${quoteIdent(name)}`);
+    jsonPairs.push(`${quoteLiteral(name)}, ${quoteIdent(outAlias)}."d"`);
   }
   return {
     select,
-    joins
+    joins,
+    jsonPairs
   };
 }
 __name(withClauses, "withClauses");
-function createOps(tx) {
+function compileFindMany(table, query = {}, opts = {}) {
+  const params = [];
+  const add = /* @__PURE__ */ __name((v) => {
+    params.push(v);
+    return `$${params.length}`;
+  }, "add");
+  const known = schemaColumns(table);
+  const whereSql = compileWhere(table, known, query, add, "findMany");
+  const order = orderClause(table, known, opts.orderBy);
+  const limit = limitClause(opts.limit);
+  const offset = offsetClause(opts.offset, opts.limit);
+  const cols = selectClause(table, known, opts.select);
+  const w = opts.with !== void 0 && Object.keys(opts.with).length > 0 ? withClauses(table, opts.with, add, "findMany") : {
+    select: [],
+    joins: []
+  };
+  const selectList = w.select.length > 0 ? `${cols === "*" ? "t.*" : cols}, ${w.select.join(", ")}` : cols;
+  const joinSql = w.joins.length > 0 ? ` ${w.joins.join(" ")}` : "";
+  const sql = `SELECT ${selectList} FROM ${quoteTable(table)} t${joinSql} WHERE true${whereSql}${order}${limit}${offset}`;
+  return {
+    sql,
+    params
+  };
+}
+__name(compileFindMany, "compileFindMany");
+var uniqueKeysCache = /* @__PURE__ */ new WeakMap();
+var pageSchemaCache = /* @__PURE__ */ new WeakMap();
+function pageSchema(table) {
+  return memoTable(pageSchemaCache, currentSchema, table, () => {
+    const def = tableDefOf(table);
+    if (!def?.columns) throw new Error(`page(${table}) requires an installed table declaration`);
+    const columns = /* @__PURE__ */ Object.create(null);
+    const inlineKeys = [];
+    for (const [name, column] of Object.entries(def.columns)) {
+      const c = column;
+      const d = c._def ?? c;
+      columns[name] = {
+        type: d.type,
+        nullable: d.nullable
+      };
+      if (d.primaryKey) inlineKeys.push(name);
+    }
+    const primaryKey = def.primaryKey ?? inlineKeys;
+    for (const name of primaryKey) if (columns[name]) columns[name].nullable = false;
+    return {
+      columns,
+      primaryKey,
+      stamp: fingerprint({
+        columns,
+        primaryKey
+      })
+    };
+  });
+}
+__name(pageSchema, "pageSchema");
+function createOps(tx, context = {}) {
   const at = /* @__PURE__ */ __name(() => resolveTx(tx), "at");
   const ops = {
+    diagnostics() {
+      return context.trace?.snapshot ?? null;
+    },
     // Generic dönüş, çağıranın İDDİASIDIR (FR-021). Motor her zaman satır objeleri
     // üretir; `T` onlara bir ad vermekten ibarettir ve verilmezse `unknown` kalır —
     // yani "bilmiyorum", ki ham SQL için doğru cevap odur.
@@ -1261,7 +2220,7 @@ function createOps(tx) {
       const params = [];
       const add = /* @__PURE__ */ __name((v) => `$${params.push(v)}`, "add");
       const tuple = buildValueTuple(table, cols, data, add, "insert");
-      const sql = `INSERT INTO ${quoteTable(table)} (${cols.map(quoteIdent).join(", ")}) VALUES (${tuple}) RETURNING *`;
+      const sql = `INSERT INTO ${quoteTable(table)} (${cols.map(quoteIdent).join(", ")}) VALUES (${tuple}) RETURNING ${rowProjection(table)}`;
       const rows = await (await at()).unsafe(sql, params);
       const inserted = rows[0];
       if (!inserted) {
@@ -1283,8 +2242,9 @@ function createOps(tx) {
     * bir satırın fazla kolonu SESSİZCE YAZILMAZDI. Eksik kolon için `null`
     * yazın ya da varsayılanı istiyorsanız o satırları ayrı çağrıda ekleyin.
     */
-    async insertMany(table, rows, opts) {
-      if (rows.length === 0) return [];
+    insertMany: /* @__PURE__ */ __name(async function(table, rows, opts) {
+      validateInsertManyOptions(opts);
+      if (rows.length === 0) return opts?.returning === false ? 0 : [];
       const first = rows[0];
       const cols = Object.keys(first);
       if (cols.length === 0) throw new Error(`insertMany into ${table}: no columns given`);
@@ -1299,11 +2259,15 @@ function createOps(tx) {
       const params = [];
       const add = /* @__PURE__ */ __name((v) => `$${params.push(v)}`, "add");
       const tuples = rows.map((r) => `(${buildValueTuple(table, cols, r, add, "insertMany")})`);
-      const tail = opts !== void 0 && opts.onConflict.length > 0 ? ` ${onConflictTail(cols, opts.onConflict, opts.action ?? "ignore")}` : "";
-      const sql = `INSERT INTO ${quoteTable(table)} (${cols.map(quoteIdent).join(", ")}) VALUES ${tuples.join(", ")}${tail} RETURNING *`;
+      const tail = opts?.onConflict !== void 0 && opts.onConflict.length > 0 ? ` ${onConflictTail(cols, opts.onConflict, opts.action ?? "ignore")}` : "";
+      const sql = `INSERT INTO ${quoteTable(table)} (${cols.map(quoteIdent).join(", ")}) VALUES ${tuples.join(", ")}${tail}${opts?.returning === false ? "" : ` RETURNING ${rowProjection(table)}`}`;
       const out = await (await at()).unsafe(sql, params);
+      if (opts?.returning === false) {
+        if (!Number.isSafeInteger(out.count) || out.count < 0) throw new Error("insertMany returning:false requires a driver with an affected row count");
+        return out.count;
+      }
       return out.map((r) => asTableRow(table, r));
-    },
+    }, "insertMany"),
     /**
     * Bir ADI kilitle — satırı değil (FR-054).
     *
@@ -1317,9 +2281,9 @@ function createOps(tx) {
     * Transaction kapsamlısı commit/rollback'te Postgres tarafından bırakılır,
     * yani unutulması imkânsız.
     */
-    async advisoryXactLock(key) {
+    async advisoryXactLock(key2) {
       await (await at()).unsafe("select pg_advisory_xact_lock(hashtextextended($1, 0))", [
-        key
+        key2
       ]);
     },
     /**
@@ -1393,7 +2357,7 @@ function createOps(tx) {
           const params = [];
           const add = /* @__PURE__ */ __name((v) => `$${params.push(v)}`, "add");
           const tuple = buildValueTuple(table, cols, data, add, "claim");
-          const rows = await sp.unsafe(`INSERT INTO ${quoteTable(table)} (${cols.map(quoteIdent).join(", ")}) VALUES (${tuple}) RETURNING *`, params);
+          const rows = await sp.unsafe(`INSERT INTO ${quoteTable(table)} (${cols.map(quoteIdent).join(", ")}) VALUES (${tuple}) RETURNING ${rowProjection(table)}`, params);
           if (!rows[0]) {
             throw new Error(`claim(${table}): INSERT sat\u0131r d\xF6nd\xFCrmedi \u2014 yazma reddedildi (b\xFCy\xFCk olas\u0131l\u0131kla bir RLS policy'si).`);
           }
@@ -1410,7 +2374,7 @@ function createOps(tx) {
           return `$${params.length}`;
         }, "add");
         const where = keyCols.map((c) => `t.${quoteIdent(c)} = ${add(unique[c])}`).join(" AND ");
-        const found = await (await at()).unsafe(`SELECT * FROM ${quoteTable(table)} t WHERE ${where} LIMIT 1`, params);
+        const found = await (await at()).unsafe(`SELECT ${rowProjection(table, "t", "*")} FROM ${quoteTable(table)} t WHERE ${where} LIMIT 1`, params);
         if (!found[0]) {
           const named = constraintOf(e);
           throw new Error(`claim(${table}): benzersizlik ihlali${named ? ` (${named})` : ""} yakaland\u0131 ama ${keyCols.join(", ")} ile sat\u0131r bulunamad\u0131. Ya ihlal BA\u015EKA bir unique k\u0131s\u0131ttan geliyor \u2014 o zaman claim() bu \xE7a\u011Fr\u0131 i\xE7in yanl\u0131\u015F ara\xE7 \u2014 ya da sat\u0131r var ve bir RLS policy'si onu bu \xE7a\u011F\u0131randan gizliyor.`);
@@ -1447,13 +2411,13 @@ function createOps(tx) {
         const bindData = [];
         const addPut = /* @__PURE__ */ __name((v) => `$${bindData.push(v)}`, "addPut");
         const ph = buildValueTuple(table, cols, data, addPut, "put");
-        const insertSql = `INSERT INTO ${quoteTable(table)} (${cols.map(quoteIdent).join(", ")}) VALUES (${ph}) ON CONFLICT (${conflict.map(quoteIdent).join(", ")}) WHERE "valid_to" IS NULL DO NOTHING RETURNING *`;
+        const insertSql = `INSERT INTO ${quoteTable(table)} (${cols.map(quoteIdent).join(", ")}) VALUES (${ph}) ON CONFLICT (${conflict.map(quoteIdent).join(", ")}) WHERE "valid_to" IS NULL DO NOTHING RETURNING ${rowProjection(table)}`;
         const live = await at();
         const first = await live.unsafe(insertSql, bindData);
         if (first[0]) return asTableRow(table, first[0]);
         const condSql = conflict.map((c, i) => `${quoteIdent(c)} = $${i + 1}`).join(" AND ");
         const condBind = conflict.map((c) => data[c]);
-        const cur = await live.unsafe(`SELECT * FROM ${quoteTable(table)} WHERE ${condSql} AND "valid_to" IS NULL`, condBind);
+        const cur = await live.unsafe(`SELECT ${rowProjection(table)} FROM ${quoteTable(table)} WHERE ${condSql} AND "valid_to" IS NULL`, condBind);
         const old = cur[0];
         if (old === void 0) {
           throw new Error(`upsert into ${table}: e\u015Fzamanl\u0131 supersede yar\u0131\u015F\u0131 \u2014 ge\xE7erli sat\u0131r bulunamad\u0131, iste\u011Fi yineleyin (D-020)`);
@@ -1479,7 +2443,7 @@ function createOps(tx) {
       const conflictSet = new Set(conflict);
       const assignments = cols.filter((c) => !conflictSet.has(c)).map((c) => `${quoteIdent(c)} = EXCLUDED.${quoteIdent(c)}`);
       const action = assignments.length ? `DO UPDATE SET ${assignments.join(", ")}` : `DO UPDATE SET ${quoteIdent(conflict[0])} = EXCLUDED.${quoteIdent(conflict[0])}`;
-      const sql = `INSERT INTO ${quoteTable(table)} (${cols.map(quoteIdent).join(", ")}) VALUES (${placeholders}) ON CONFLICT (${conflict.map(quoteIdent).join(", ")}) ${action} RETURNING *`;
+      const sql = `INSERT INTO ${quoteTable(table)} (${cols.map(quoteIdent).join(", ")}) VALUES (${placeholders}) ON CONFLICT (${conflict.map(quoteIdent).join(", ")}) ${action} RETURNING ${rowProjection(table)}`;
       const rows = await (await at()).unsafe(sql, params);
       const row = rows[0];
       if (!row) {
@@ -1497,7 +2461,7 @@ function createOps(tx) {
         return `$${params.length}`;
       }, "add");
       const assignments = buildSetAssignments(table, cols, data, add, "update");
-      const sql = `UPDATE ${quoteTable(table)} SET ${assignments} WHERE id = ${add(id)} RETURNING *`;
+      const sql = `UPDATE ${quoteTable(table)} SET ${assignments} WHERE id = ${add(id)} RETURNING ${rowProjection(table)}`;
       const rows = await (await at()).unsafe(sql, params);
       return rows[0] ? asTableRow(table, rows[0]) : null;
     },
@@ -1549,9 +2513,9 @@ function createOps(tx) {
       assertHasPredicate(whereSql, "updateMany", table);
       const pk = primaryKeyOf(table);
       const wantRows = opts?.returning !== false;
-      const tail = wantRows ? "RETURNING *" : "RETURNING 1";
+      const tail = wantRows ? `RETURNING ${rowProjection(table, "t", "*")}` : "RETURNING 1";
       const simple = isSinglePkEquality(where, pk) || pk === null;
-      const body = simple ? `UPDATE ${quoteTable(table)} AS t SET ${assignments} WHERE true${whereSql} ${tail}` : `UPDATE ${quoteTable(table)} AS t SET ${assignments} FROM locked WHERE t.${quoteIdent(pk)} = locked.${quoteIdent(pk)} ` + (wantRows ? "RETURNING t.*" : "RETURNING 1");
+      const body = simple ? `UPDATE ${quoteTable(table)} AS t SET ${assignments} WHERE true${whereSql} ${tail}` : `UPDATE ${quoteTable(table)} AS t SET ${assignments} FROM locked WHERE t.${quoteIdent(pk)} = locked.${quoteIdent(pk)} ` + (wantRows ? `RETURNING ${rowProjection(table, "t")}` : "RETURNING 1");
       const lockedCte = simple ? "" : `WITH locked AS (SELECT t.${quoteIdent(pk)} FROM ${quoteTable(table)} t WHERE true${whereSql} ORDER BY t.${quoteIdent(pk)} FOR NO KEY UPDATE) `;
       const sql = wantRows ? `${lockedCte}${body}` : simple ? `WITH upd AS (${body}) SELECT count(*)::int AS n FROM upd` : `${lockedCte.replace(/ $/, "")}, upd AS (${body}) SELECT count(*)::int AS n FROM upd`;
       const out = await (await at()).unsafe(sql, params);
@@ -1636,7 +2600,7 @@ function createOps(tx) {
       }
       const groups = q.groupBy ?? [];
       for (const col of groups) check(col, "groupBy");
-      const groupSel = groups.map((c) => `t.${quoteIdent(c)} AS ${quoteIdent(`g__${c}`)}`);
+      const groupSel = groups.map((c) => `${columnTypeOf(table, c) === "timestamp" ? columnResult(table, c, "t") : `t.${quoteIdent(c)}`} AS ${quoteIdent(`g__${c}`)}`);
       const params = [];
       const add = /* @__PURE__ */ __name((v) => `$${params.push(v)}`, "add");
       const whereSql = compileWhere(table, known, q.where ?? {}, add, "aggregate");
@@ -1670,32 +2634,114 @@ function createOps(tx) {
       const rows = await (await at()).unsafe(sql, params);
       return Number(rows[0]?.n ?? 0);
     },
+    async findUnique(table, where, opts = {}) {
+      const keys = memoTable(uniqueKeysCache, currentSchema, table, () => uniqueKeysOf(tableDefOf(table) ?? {}));
+      assertUniqueLookup(table, keys, where);
+      const rows = await ops.findMany(table, where, {
+        ...opts,
+        select: opts.select === void 0 ? void 0 : [
+          ...opts.select
+        ],
+        limit: 2
+      });
+      if (rows.length > 1) throw new Error(`findUnique(${table}): deployed constraints disagree with the schema; multiple rows matched`);
+      return rows[0] ?? null;
+    },
     async findById(table, id) {
-      const rows = await (await at()).unsafe(`SELECT * FROM ${quoteTable(table)} WHERE id = $1`, [
+      const rows = await (await at()).unsafe(`SELECT ${rowProjection(table)} FROM ${quoteTable(table)} WHERE id = $1`, [
         id
       ]);
       return rows[0] ? asTableRow(table, rows[0]) : null;
     },
+    compileQuery(query) {
+      assertReadContract(query, tableDefOf(query.table)?.columns);
+      return compileFindMany(query.table, query.where, query.options);
+    },
+    async readQuery(query) {
+      const compiled = ops.compileQuery(query);
+      return asTableRows(query.table, await (await at()).unsafe(compiled.sql, compiled.params, {
+        name: query.name
+      }));
+    },
+    async explainQuery(query) {
+      const compiled = ops.compileQuery(query);
+      return await (await at()).unsafe(`EXPLAIN (FORMAT JSON) ${compiled.sql}`, compiled.params, {
+        name: `${query.name}.explain`
+      });
+    },
     async findMany(table, query = {}, opts = {}) {
+      const compiled = compileFindMany(table, query, opts);
+      return asTableRows(table, await (await at()).unsafe(compiled.sql, compiled.params), opts.with);
+    },
+    async page(table, query = {}, opts = {}) {
+      const secret = cursorKey();
+      const schema = pageSchema(table);
+      const { order, size, backward, token } = pageOrder(schema.columns, schema.primaryKey, opts);
       const params = [];
-      const add = /* @__PURE__ */ __name((v) => {
-        params.push(v);
-        return `$${params.length}`;
-      }, "add");
+      const add = /* @__PURE__ */ __name((v) => `$${params.push(v)}`, "add");
       const known = schemaColumns(table);
-      const whereSql = compileWhere(table, known, query, add, "findMany");
-      const order = orderClause(table, known, opts.orderBy);
-      const limit = limitClause(opts.limit);
-      const offset = offsetClause(opts.offset, opts.limit);
-      const cols = selectClause(table, known, opts.select);
-      const w = opts.with !== void 0 && Object.keys(opts.with).length > 0 ? withClauses(table, opts.with, add, "findMany") : {
+      const where = compileWhere(table, known, query, add, "page");
+      const cols = selectClause(table, known, opts.select === void 0 ? void 0 : [
+        ...opts.select
+      ]);
+      const scope = fingerprint({
+        table,
+        schema: schema.stamp,
+        order,
+        where,
+        params,
+        select: opts.select,
+        with: opts.with,
+        identity: context.cursorScope ?? "direct"
+      });
+      const values = token === void 0 ? void 0 : decodeCursor(secret, scope, token, order.length);
+      const column = /* @__PURE__ */ __name((name) => `t.${quoteIdent(name)}`, "column");
+      const boundary = values ? ` AND ${pageBoundary(order, values, backward, add, column)}` : "";
+      const opposite = values ? `EXISTS (SELECT 1 FROM ${quoteTable(table)} t WHERE true${where} AND ${pageBoundary(order, values, !backward, add, column, true)})` : "false";
+      let prefix = "__pb_page_";
+      const names = [
+        ...Object.keys(schema.columns),
+        ...Object.keys(opts.with ?? {})
+      ];
+      while (names.some((n) => n.startsWith(prefix))) prefix += "_";
+      const ordinal = `${prefix}ordinal`, other = `${prefix}opposite`;
+      const hidden = order.map((o, i) => `${prefix}${i}`);
+      const cursorCols = order.map((o, i) => `${columnTypeOf(table, o.column) === "timestamp" ? timestampResult(column(o.column)) : `${column(o.column)}::text`} AS ${quoteIdent(hidden[i])}`);
+      const w = opts.with && Object.keys(opts.with).length ? withClauses(table, opts.with, add, "page") : {
         select: [],
         joins: []
       };
-      const selectList = w.select.length > 0 ? `${cols === "*" ? "t.*" : cols}, ${w.select.join(", ")}` : cols;
-      const joinSql = w.joins.length > 0 ? ` ${w.joins.join(" ")}` : "";
-      const sql = `SELECT ${selectList} FROM ${quoteTable(table)} t${joinSql} WHERE true${whereSql}${order}${limit}${offset}`;
-      return asTableRows(table, await (await at()).unsafe(sql, params));
+      const nativeOrder = order.map((o) => `${column(o.column)} ${o.direction === "asc" !== backward ? "ASC" : "DESC"} NULLS ${o.nulls === "first" !== backward ? "FIRST" : "LAST"}`).join(", ");
+      const visible = cols === "*" ? "t.*" : cols;
+      const inner = `SELECT ${[
+        visible,
+        ...w.select,
+        ...cursorCols,
+        `row_number() OVER (ORDER BY ${nativeOrder}) AS ${quoteIdent(ordinal)}`
+      ].join(", ")} FROM ${quoteTable(table)} t ${w.joins.join(" ")} WHERE true${where}${boundary} ORDER BY ${nativeOrder} LIMIT ${size + 1}`;
+      const sql = `SELECT p.*, b.${quoteIdent(other)} FROM (SELECT ${opposite} AS ${quoteIdent(other)}) b LEFT JOIN LATERAL (${inner}) p ON true ORDER BY p.${quoteIdent(ordinal)}`;
+      const result = await (await at()).unsafe(sql, params);
+      const hasOpposite = result[0]?.[other] === true;
+      let rows = result.filter((row) => row[ordinal] !== null && row[ordinal] !== void 0);
+      const hasMore = rows.length > size;
+      rows = rows.slice(0, size);
+      if (backward) rows.reverse();
+      const cursor = /* @__PURE__ */ __name((row) => row ? encodeCursor(secret, scope, hidden.map((name) => row[name] === null ? null : String(row[name]))) : null, "cursor");
+      const pageInfo = {
+        startCursor: cursor(rows[0]),
+        endCursor: cursor(rows.at(-1)),
+        hasNextPage: backward ? hasOpposite : hasMore,
+        hasPreviousPage: backward ? hasMore : hasOpposite
+      };
+      for (const row of rows) for (const name of [
+        ...hidden,
+        ordinal,
+        other
+      ]) delete row[name];
+      return {
+        rows: asTableRows(table, rows, opts.with),
+        pageInfo
+      };
     },
     /**
     * Tek-SQL hibrit arama (FR-014): iki kol CTE + FULL OUTER JOIN + RRF
@@ -1800,7 +2846,7 @@ function createOps(tx) {
           kwC = `SELECT c.${pidQ} AS pid, c.chunk_seq, ROW_NUMBER() OVER (ORDER BY ts_rank_cd(c.palbase_fts, websearch_to_tsquery('simple', ${qpC})) DESC) AS r FROM ${quoteTable(ck.table)} c${parentJoinC}c.palbase_fts @@ websearch_to_tsquery('simple', ${qpC}) ORDER BY r LIMIT ${cpool}`;
         }
         const msC = params.minScore === void 0 ? "" : addC(params.minScore);
-        const colListC = cfg.cols.map((c) => `t.${quoteIdent(c)}`).join(", ");
+        const colListC = cfg.cols.map((c) => columnTypeOf(table, c) === "timestamp" ? projectedColumn(table, c, "t") : `t.${quoteIdent(c)}`).join(", ");
         const scoreC = scoreMul === "" ? "g._score" : `(g._score)${scoreMul}`;
         const assembleC = /* @__PURE__ */ __name((kwIn, withKwn) => {
           const kwnCol = withKwn ? `, (SELECT count(*) FROM kw)::int AS _kwn` : "";
@@ -1882,7 +2928,7 @@ function createOps(tx) {
         qpRef = qp;
         kwSql = `SELECT t.${quoteIdent(cfg.pk)} AS id, ROW_NUMBER() OVER (ORDER BY ts_rank_cd(t.palbase_fts, websearch_to_tsquery('simple', ${qp})) DESC) AS r FROM ${quoteTable(table)} t WHERE t.palbase_fts @@ websearch_to_tsquery('simple', ${qp})${whereSql} ORDER BY r LIMIT ${pool}`;
       }
-      const colList = cfg.cols.map((c) => `t.${quoteIdent(c)}`).join(", ");
+      const colList = cfg.cols.map((c) => columnTypeOf(table, c) === "timestamp" ? projectedColumn(table, c, "t") : `t.${quoteIdent(c)}`).join(", ");
       const msP = params.minScore === void 0 ? "" : add(params.minScore);
       const hlCol = params.highlight === true && wantText ? `, ts_headline('simple', ${ftsExprOf(cfg.ftsCols)}, websearch_to_tsquery('simple', ${qpRef})) AS _highlight` : "";
       const assemble = /* @__PURE__ */ __name((kwIn, withKwn) => {
@@ -2090,7 +3136,7 @@ function createOps(tx) {
         const params = [];
         const add = /* @__PURE__ */ __name((v) => `$${params.push(v)}`, "add");
         const tuple = buildValueTuple(table, cols, data, add, "supersede");
-        const rows = await sp.unsafe(`INSERT INTO ${quoteTable(table)} (${cols.map(quoteIdent).join(", ")}) VALUES (${tuple}) RETURNING *`, params);
+        const rows = await sp.unsafe(`INSERT INTO ${quoteTable(table)} (${cols.map(quoteIdent).join(", ")}) VALUES (${tuple}) RETURNING ${rowProjection(table)}`, params);
         if (!rows[0]) {
           throw new Error(`supersede(${table}): INSERT sat\u0131r d\xF6nd\xFCrmedi \u2014 yazma reddedildi (b\xFCy\xFCk olas\u0131l\u0131kla bir RLS policy'si)`);
         }
@@ -2100,7 +3146,7 @@ function createOps(tx) {
     /** A real SAVEPOINT inside the request's transaction. */
     async transaction(cb) {
       const live = await at();
-      return live.savepoint(async (sp) => cb(withTables(createOps(sp), currentSchema)));
+      return live.savepoint(async (sp) => cb(withTables(createOps(sp, context), currentSchema)));
     },
     /**
     * Run `fn` against a handle bound to a SAVEPOINT, so a failure inside it
@@ -2121,7 +3167,7 @@ function createOps(tx) {
     */
     async attempt(fn) {
       const live = await at();
-      return live.savepoint(async (sp) => fn(withTables(createOps(sp), currentSchema)));
+      return live.savepoint(async (sp) => fn(withTables(createOps(sp, context), currentSchema)));
     },
     /**
     * Execute a whole transaction plan — what `Database.$transaction(fn)` builds.
@@ -2141,6 +3187,62 @@ function createOps(tx) {
     * "transport.txPlan is not a function" while every test that covered
     * transactions passed against a mock that did implement it.
     */
+    async command(plan, options = {}) {
+      if (options.mode !== void 0 && ![
+        "auto",
+        "compiled",
+        "sequential"
+      ].includes(options.mode)) throw new Error("command mode must be auto, compiled or sequential");
+      if (options.mode === "sequential") return ops.txPlan(plan);
+      const compiled = context.commands ? compileCommand(plan) : {
+        reason: "the PostgreSQL command executor is not installed"
+      };
+      if ("reason" in compiled) {
+        if (options.mode === "compiled") throw new Error(`Command cannot compile: ${compiled.reason}. Use auto/sequential mode or installCommandExecutor at boot.`);
+        return ops.txPlan(plan);
+      }
+      if (compiled.steps.length === 0) return {
+        results: []
+      };
+      if (compiled.pipeline) {
+        return (await at()).savepoint(async (sp) => {
+          const settled = await Promise.allSettled(compiled.pipeline.map((statement) => sp.unsafe(statement.sql, statement.params)));
+          const failed = settled.find((result) => result.status === "rejected");
+          if (failed?.status === "rejected") {
+            const error = failed.reason;
+            if (sqlstateOf(error) === SQLSTATE.commandGuardFailed && typeof error.detail === "string") {
+              const detail = JSON.parse(error.detail);
+              if (detail.error_code === "tx_guard_failed" && Number.isInteger(detail.slot)) {
+                throw Object.assign(new Error("Command expectation failed"), detail);
+              }
+            }
+            throw error;
+          }
+          return {
+            results: settled.map((result, i) => {
+              const rows2 = result.value[0].rows;
+              return {
+                rows: asTableRows(plan.ops[i].table, rows2),
+                rows_affected: rows2.length
+              };
+            })
+          };
+        });
+      }
+      const rows = await (await at()).savepoint((sp) => sp.unsafe("SELECT palbase_runtime.command_v1($1::jsonb -> 'steps') AS result", [
+        {
+          steps: compiled.steps
+        }
+      ]));
+      const response = rows[0].result;
+      if (response.error) throw Object.assign(new Error(response.error.error_code === "tx_ref_unresolved" ? "Command reference has no source row/column; use expectOne before reading it" : "Command expectation failed"), response.error);
+      return {
+        results: response.results.map((result, i) => ({
+          ...result,
+          rows: asTableRows(plan.ops[i].table, result.rows)
+        }))
+      };
+    },
     async txPlan(plan) {
       const live = await at();
       return live.savepoint(async (sp) => {
@@ -2164,27 +3266,55 @@ function createOps(tx) {
 }
 __name(createOps, "createOps");
 var currentSchema = {};
+var columnsMemo = /* @__PURE__ */ new WeakMap();
+var primaryMemo = /* @__PURE__ */ new WeakMap();
+var vectorMemo = /* @__PURE__ */ new WeakMap();
+var transformMemo = /* @__PURE__ */ new WeakMap();
+var typeMemo = /* @__PURE__ */ new WeakMap();
+var timestampMemo = /* @__PURE__ */ new WeakMap();
+var projectionMemo = /* @__PURE__ */ new WeakMap();
+function schemaColumns(table) {
+  return memoTable(columnsMemo, currentSchema, table, () => computeSchemaColumns(table));
+}
+__name(schemaColumns, "schemaColumns");
+function primaryKeyOf(table) {
+  return memoTable(primaryMemo, currentSchema, table, () => computePrimaryKey(table));
+}
+__name(primaryKeyOf, "primaryKeyOf");
+function vectorColumnsOf(schema, table) {
+  return memoTable(vectorMemo, schema, table, () => computeVectorColumns(schema, table));
+}
+__name(vectorColumnsOf, "vectorColumnsOf");
+function transformsOf(schema, table) {
+  return memoTable(transformMemo, schema, table, () => computeTransforms(schema, table));
+}
+__name(transformsOf, "transformsOf");
+function columnTypeOf(table, col) {
+  const types = memoTable(typeMemo, currentSchema, table, () => new Map([
+    ...schemaColumns(table) ?? []
+  ].map((c) => [
+    c,
+    computeColumnType(table, c)
+  ])));
+  return types.get(col) ?? null;
+}
+__name(columnTypeOf, "columnTypeOf");
 var currentRelations = /* @__PURE__ */ new Map();
 function setSchema(schemas) {
-  cachedVectorSchema = null;
-  cachedTrgmSchema = null;
-  const tables = {};
+  const tables = /* @__PURE__ */ Object.create(null);
   for (const entry of schemas) {
     const mod = entry;
     const def = (mod && "default" in mod ? mod.default : mod) ?? {};
     const schemaName = def.name ?? "public";
-    for (const [key, table] of Object.entries(def.tables ?? {})) {
-      tables[qualifiedTableKey(schemaName, table.name ?? key)] = table;
+    for (const [key2, table] of Object.entries(def.tables ?? {})) {
+      tables[qualifiedTableKey(schemaName, table.name ?? key2)] = table;
     }
   }
-  currentSchema = {
-    tables
-  };
-  currentRelations = buildRelations(schemas.map((entry) => {
+  const relations = buildRelations(schemas.map((entry) => {
     const mod = entry;
     const def = (mod && "default" in mod ? mod.default : mod) ?? {};
-    const tables2 = {};
-    for (const [key, t] of Object.entries(def.tables ?? {})) {
+    const tables2 = /* @__PURE__ */ Object.create(null);
+    for (const [key2, t] of Object.entries(def.tables ?? {})) {
       const table = t ?? {};
       const columns = {};
       for (const [cname, c] of Object.entries(table.columns ?? {})) {
@@ -2194,9 +3324,9 @@ function setSchema(schemas) {
           _def: cd
         };
       }
-      tables2[key] = {
+      tables2[key2] = {
         ...table,
-        name: table.name ?? key,
+        name: table.name ?? key2,
         columns
       };
     }
@@ -2205,40 +3335,86 @@ function setSchema(schemas) {
       tables: tables2
     };
   }));
+  for (const key2 of Object.keys(tables)) tables[key2] = snapshotDeclaration(tables[key2]);
+  currentSchema = Object.freeze({
+    tables: Object.freeze(tables)
+  });
+  currentRelations = relations;
+  cachedVectorSchema = null;
+  cachedTrgmSchema = null;
 }
 __name(setSchema, "setSchema");
+var tableNamespaces = /* @__PURE__ */ new WeakMap();
 function withTables(ops, schema = currentSchema) {
-  const bind = /* @__PURE__ */ __name((key) => ({
-    insert: /* @__PURE__ */ __name((data) => ops.insert(key, data), "insert"),
-    update: /* @__PURE__ */ __name((id, data) => ops.update(key, id, data), "update"),
-    delete: /* @__PURE__ */ __name((id) => ops.delete(key, id), "delete"),
-    findById: /* @__PURE__ */ __name((id) => ops.findById(key, id), "findById"),
-    findMany: /* @__PURE__ */ __name((query, opts) => ops.findMany(key, query ?? {}, opts), "findMany"),
-    put: /* @__PURE__ */ __name((q) => ops.put(key, q.data, {
+  let namespaces = tableNamespaces.get(schema);
+  if (!namespaces) {
+    namespaces = /* @__PURE__ */ new Map();
+    for (const key2 of Object.keys(schema.tables ?? {})) {
+      const dot = key2.indexOf(".");
+      const name = dot === -1 ? "public" : key2.slice(0, dot);
+      const short = dot === -1 ? key2 : key2.slice(dot + 1);
+      if (!namespaces.has(name)) namespaces.set(name, /* @__PURE__ */ new Map());
+      namespaces.get(name).set(short, key2);
+    }
+    if (Object.isFrozen(schema) && Object.isFrozen(schema.tables)) tableNamespaces.set(schema, namespaces);
+  }
+  const bind = /* @__PURE__ */ __name((key2) => ({
+    insert: /* @__PURE__ */ __name((data) => ops.insert(key2, data), "insert"),
+    update: /* @__PURE__ */ __name((id, data) => ops.update(key2, id, data), "update"),
+    delete: /* @__PURE__ */ __name((id) => ops.delete(key2, id), "delete"),
+    findById: /* @__PURE__ */ __name((id) => ops.findById(key2, id), "findById"),
+    findUnique: /* @__PURE__ */ __name((where, opts) => ops.findUnique(key2, where, opts), "findUnique"),
+    findMany: /* @__PURE__ */ __name((query, opts) => ops.findMany(key2, query ?? {}, opts), "findMany"),
+    page: /* @__PURE__ */ __name((query, opts) => ops.page(key2, query ?? {}, opts), "page"),
+    put: /* @__PURE__ */ __name((q) => ops.put(key2, q.data, {
       onConflict: q.onConflict
     }), "put")
   }), "bind");
-  const tables = {};
-  for (const key of Object.keys(schema.tables ?? {})) {
-    if (!key.includes(".")) tables[key] = bind(key);
-  }
+  const surfaces = /* @__PURE__ */ new Map();
   const schemaOf = /* @__PURE__ */ __name((name) => {
-    const out = {};
-    const prefix = `${name}.`;
-    for (const key of Object.keys(schema.tables ?? {})) {
-      if (name === "public") {
-        if (!key.includes(".")) out[key] = bind(key);
-      } else if (key.startsWith(prefix)) {
-        out[key.slice(prefix.length)] = bind(key);
+    const cached = surfaces.get(name);
+    if (cached) return cached;
+    const names = namespaces.get(name) ?? /* @__PURE__ */ new Map();
+    const target = /* @__PURE__ */ Object.create(null);
+    const get = /* @__PURE__ */ __name((key2) => {
+      if (!Object.hasOwn(target, key2) && names.has(key2)) {
+        Object.defineProperty(target, key2, {
+          value: bind(names.get(key2)),
+          configurable: true,
+          enumerable: true,
+          writable: true
+        });
       }
-    }
-    return {
-      tables: out
+      return Reflect.get(target, key2);
+    }, "get");
+    const tables = new Proxy(target, {
+      get: /* @__PURE__ */ __name((t, key2, receiver) => typeof key2 === "string" ? get(key2) : Reflect.get(t, key2, receiver), "get"),
+      has: /* @__PURE__ */ __name((t, key2) => typeof key2 === "string" && names.has(key2) || Reflect.has(t, key2), "has"),
+      ownKeys: /* @__PURE__ */ __name((t) => [
+        .../* @__PURE__ */ new Set([
+          ...names.keys(),
+          ...Reflect.ownKeys(t)
+        ])
+      ], "ownKeys"),
+      getOwnPropertyDescriptor: /* @__PURE__ */ __name((t, key2) => Reflect.getOwnPropertyDescriptor(t, key2) ?? (typeof key2 === "string" && names.has(key2) ? {
+        configurable: true,
+        enumerable: true,
+        get: /* @__PURE__ */ __name(() => get(key2), "get")
+      } : void 0), "getOwnPropertyDescriptor"),
+      preventExtensions: /* @__PURE__ */ __name((t) => {
+        for (const key2 of names.keys()) get(key2);
+        return Reflect.preventExtensions(t);
+      }, "preventExtensions")
+    });
+    const surface = {
+      tables
     };
+    if (namespaces.has(name) || name === "public") surfaces.set(name, surface);
+    return surface;
   }, "schemaOf");
   const base = /* @__PURE__ */ Object.create(null);
   return Object.assign(base, ops, {
-    tables,
+    tables: schemaOf("public").tables,
     schema: schemaOf
   });
 }
@@ -2296,8 +3472,8 @@ function diagnosingDriver(sql, surface = "service") {
       return markEngineRaised(new UniqueViolation(constraintOf(e)));
     }
     const state = sqlstateOf(e);
-    if (state === "40001") return markEngineRaised(new SerializationFailure(state));
-    if (state === "40P01") return markEngineRaised(new DeadlockDetected(state));
+    if (state === SQLSTATE.serializationFailure) return markEngineRaised(new SerializationFailure(state));
+    if (state === SQLSTATE.deadlockDetected) return markEngineRaised(new DeadlockDetected(state));
     if (surface === "service" && isForeignKeyViolation(e)) {
       return new Error(`Database.$asService() hit a foreign key with nothing to point at. It runs in its OWN transaction on its OWN connection, so a row this request wrote through \`Database.*\` is not visible to it until the request commits \u2014 and the request cannot commit until the handler returns. If the row it needs is one this request just created, do both writes on ONE surface. (${original(e)})`);
     }
@@ -2307,11 +3483,16 @@ function diagnosingDriver(sql, surface = "service") {
     return e;
   }, "explain");
   const wrapTx = /* @__PURE__ */ __name((tx) => ({
-    async unsafe(text, params) {
+    unsafe(text, params) {
       try {
-        return await tx.unsafe(text, params);
+        const query = tx.unsafe(text, params);
+        const mapped = query.catch((e) => {
+          throw explain(e);
+        });
+        if (query.cancel) mapped.cancel = () => query.cancel();
+        return mapped;
       } catch (e) {
-        throw explain(e);
+        return Promise.reject(explain(e));
       }
     },
     savepoint(cb) {
@@ -2320,34 +3501,120 @@ function diagnosingDriver(sql, surface = "service") {
   }), "wrapTx");
   return {
     unsafe: /* @__PURE__ */ __name((text, params) => sql.unsafe(text, params), "unsafe"),
-    begin: /* @__PURE__ */ __name((cb) => sql.begin((tx) => cb(wrapTx(tx))), "begin")
+    cancelBackend: sql.cancelBackend?.bind(sql),
+    begin: /* @__PURE__ */ __name((cb) => sql.begin((tx) => cb(wrapTx(tx))).catch((e) => {
+      throw explain(e);
+    }), "begin")
   };
 }
 __name(diagnosingDriver, "diagnosingDriver");
-function createRequestDatabase(sql, identity) {
-  const tx = createLazyTransaction(diagnosingDriver(sql, "user"), identity.role, identity.claimsJson);
+function createRequestDatabase(sql, identity, diagnostics) {
+  const trace = diagnostics === void 0 ? void 0 : new DatabaseTrace(diagnostics);
+  let requestClosed = false;
+  const contextFor = /* @__PURE__ */ __name((role) => {
+    let scope;
+    return {
+      trace,
+      get cursorScope() {
+        return scope ??= cursorIdentity(role, identity.claimsJson);
+      },
+      get commands() {
+        return hasCommandExecutor(sql);
+      }
+    };
+  }, "contextFor");
+  const userContext = contextFor(identity.role);
+  const serviceContext = contextFor(identity.serviceRole);
+  const atomic = /* @__PURE__ */ __name((role, surface) => async (fn, options = {}) => {
+    validateAtomicOptions(options);
+    if (requestClosed) throw new Error("Database request has settled; it cannot open another transaction");
+    if (atomicScope.getStore() !== void 0) throw new Error("Nested Database.$atomic is not supported; use tx.$attempt for a savepoint");
+    const retries = retryBudget(options.retry);
+    const control = options.timeoutMs !== void 0 || options.signal !== void 0 ? new TransactionControl(options.timeoutMs, options.signal) : void 0;
+    let lease;
+    try {
+      control?.check();
+      if (options.workload) {
+        const queuedAt = trace ? performance.now() : 0;
+        try {
+          lease = await workloadAdmission(sql, options.workload).acquire(workloadTenant(options.workload, identity.claimsJson), options.conflictKeys ?? [], control?.signal);
+        } finally {
+          trace?.time("queueMs", queuedAt);
+        }
+      }
+      for (let attempt = 0; ; attempt++) {
+        control?.check();
+        const timeouts = [
+          options.statementTimeoutMs,
+          control?.remainingMs()
+        ].filter((n) => n !== void 0);
+        const scope = /* @__PURE__ */ Symbol("atomic transaction");
+        const root = createLazyTransaction(diagnosingDriver(sql, surface), role, identity.claimsJson, {
+          scope,
+          isolation: options.isolation,
+          readOnly: options.readOnly,
+          control,
+          trace,
+          lockTimeout: `${options.lockTimeoutMs ?? 5e3}ms`,
+          statementTimeout: timeouts.length === 0 ? void 0 : `${Math.min(...timeouts)}ms`
+        });
+        try {
+          const callback = atomicScope.run(scope, () => fn(withTables(createOps(root, surface === "user" ? userContext : serviceContext))));
+          const value = await (control ? control.race(callback) : callback);
+          control?.check();
+          await root.commit();
+          return value;
+        } catch (error) {
+          await root.rollback(error);
+          if (attempt >= retries || !isRetryable(error)) throw error;
+          trace?.retry();
+          const delay = new Promise((resolve) => setTimeout(resolve, Math.min(100, 2 ** attempt)));
+          await (control ? control.race(delay) : delay);
+        }
+      }
+    } finally {
+      control?.dispose();
+      lease?.release();
+    }
+  }, "atomic");
+  const tx = createLazyTransaction(diagnosingDriver(sql, "user"), identity.role, identity.claimsJson, {
+    trace
+  });
   let serviceTx = null;
   let serviceClient = null;
   const asService = /* @__PURE__ */ __name(() => {
     if (serviceClient === null) {
       serviceTx = createLazyTransaction(diagnosingDriver(sql, "service"), identity.serviceRole, identity.claimsJson, {
-        lockTimeout: SERVICE_LOCK_TIMEOUT
+        lockTimeout: SERVICE_LOCK_TIMEOUT,
+        trace
+      });
+      serviceClient = Object.assign(withTables(createOps(serviceTx, serviceContext)), {
+        atomic: atomic(identity.serviceRole, "service")
       });
-      serviceClient = withTables(createOps(serviceTx));
     }
     return serviceClient;
   }, "asService");
   return {
-    client: Object.assign(withTables(createOps(tx)), {
-      asService
+    client: Object.assign(withTables(createOps(tx, userContext)), {
+      asService,
+      atomic: atomic(identity.role, "user")
     }),
     async commit() {
-      await tx.commit();
-      await serviceTx?.commit();
+      requestClosed = true;
+      try {
+        await tx.commit();
+        await serviceTx?.commit();
+        trace?.complete("committed");
+      } catch (error) {
+        trace?.failed();
+        throw error;
+      }
     },
     async rollback(reason) {
+      requestClosed = true;
       await tx.rollback(reason);
       await serviceTx?.rollback(reason);
+      trace?.complete("failed");
     }
   };
 }
@@ -2357,8 +3624,13 @@ var Args = class Args2 {
     __name(this, "Args");
   }
   values = [];
-  bind(value) {
+  columns = [];
+  bind(value, column, table) {
     this.values.push(value);
+    this.columns.push({
+      column,
+      table
+    });
     return `$${this.values.length}`;
   }
 };
@@ -2444,7 +3716,7 @@ function planWhere(table, where, args, results) {
   }
   const resolved = resolveRefsDeep(where, results);
   const known = schemaColumns(table);
-  const bare = compileWhereBare(table, known, resolved, (v) => args.bind(v), "transaction plan");
+  const bare = compileWhereBare(table, known, resolved, (v, column, from) => args.bind(v, column, from), "transaction plan");
   return {
     sql: bare === "" ? "" : ` AND ${bare}`,
     resolved
@@ -2453,16 +3725,16 @@ function planWhere(table, where, args, results) {
 __name(planWhere, "planWhere");
 function bindMaybeVector(args, column, vectorCols, value, transforms) {
   if (column !== void 0 && vectorCols?.has(column) && Array.isArray(value)) {
-    return args.bind(toVectorLiteral(value));
+    return args.bind(toVectorLiteral(value), column);
   }
   const t = column !== void 0 ? transforms?.get(column) : void 0;
   if (t?.toDb !== void 0 && value !== null && value !== void 0) {
-    return args.bind(t.toDb(value));
+    return args.bind(t.toDb(value), column);
   }
-  return args.bind(value);
+  return args.bind(value, column);
 }
 __name(bindMaybeVector, "bindMaybeVector");
-async function runPlanOp(sp, op, results) {
+function compilePlanOp(op, results) {
   const opVectorCols = vectorColumnsOf(currentSchema, op.table);
   const opTransforms = transformsOf(currentSchema, op.table);
   const args = new Args();
@@ -2472,7 +3744,7 @@ async function runPlanOp(sp, op, results) {
     case "insert": {
       const cols = Object.keys(op.values ?? {});
       const rendered = cols.map((c) => renderValue(op.values[c], c, args, results, opVectorCols, opTransforms));
-      sql = cols.length ? `INSERT INTO ${table} (${cols.map(quoteIdent).join(", ")}) VALUES (${rendered.join(", ")}) RETURNING *` : `INSERT INTO ${table} DEFAULT VALUES RETURNING *`;
+      sql = cols.length ? `INSERT INTO ${table} (${cols.map(quoteIdent).join(", ")}) VALUES (${rendered.join(", ")}) RETURNING ${rowProjection(op.table)}` : `INSERT INTO ${table} DEFAULT VALUES RETURNING ${rowProjection(op.table)}`;
       break;
     }
     case "upsert": {
@@ -2485,17 +3757,17 @@ async function runPlanOp(sp, op, results) {
         });
       }
       const rendered = cols.map((c) => renderValue(op.values[c], c, args, results, opVectorCols, opTransforms));
-      sql = `INSERT INTO ${table} (${cols.map(quoteIdent).join(", ")}) VALUES (${rendered.join(", ")}) ${onConflictTail(cols, conflict, "update")} RETURNING *`;
+      sql = `INSERT INTO ${table} (${cols.map(quoteIdent).join(", ")}) VALUES (${rendered.join(", ")}) ${onConflictTail(cols, conflict, "update")} RETURNING ${rowProjection(op.table)}`;
       break;
     }
     case "insertMany": {
       const rows = op.rows ?? [];
-      if (rows.length === 0 || !rows[0]) return [];
+      if (rows.length === 0 || !rows[0]) return null;
       const cols = Object.keys(rows[0]);
       const tuples = rows.map((r) => `(${cols.map((c) => renderValue(r[c], c, args, results, opVectorCols, opTransforms)).join(", ")})`);
       const conflictCols = op.onConflict ?? [];
       const tail = op.action !== void 0 && conflictCols.length > 0 ? ` ${onConflictTail(cols, conflictCols, op.action)}` : "";
-      sql = `INSERT INTO ${table} (${cols.map(quoteIdent).join(", ")}) VALUES ${tuples.join(", ")}${tail} RETURNING *`;
+      sql = `INSERT INTO ${table} (${cols.map(quoteIdent).join(", ")}) VALUES ${tuples.join(", ")}${tail} RETURNING ${rowProjection(op.table)}`;
       break;
     }
     case "update": {
@@ -2511,12 +3783,12 @@ async function runPlanOp(sp, op, results) {
       const assignments = cols.map((c) => `${quoteIdent(c)} = ${renderValue(op.set[c], c, args, results, opVectorCols, opTransforms)}`);
       const planned = planWhere(op.table, op.where, args, results);
       const planPk = primaryKeyOf(op.table);
-      sql = isSinglePkEquality(planned.resolved, planPk) || planPk === null ? `UPDATE ${table} AS t SET ${assignments.join(", ")} WHERE true${planned.sql} RETURNING t.*` : `WITH locked AS (SELECT t.${quoteIdent(planPk)} FROM ${table} t WHERE true${planned.sql} ORDER BY t.${quoteIdent(planPk)} FOR NO KEY UPDATE) UPDATE ${table} AS t SET ${assignments.join(", ")} FROM locked WHERE t.${quoteIdent(planPk)} = locked.${quoteIdent(planPk)} RETURNING t.*`;
+      sql = isSinglePkEquality(planned.resolved, planPk) || planPk === null ? `UPDATE ${table} AS t SET ${assignments.join(", ")} WHERE true${planned.sql} RETURNING ${rowProjection(op.table, "t")}` : `WITH locked AS (SELECT t.${quoteIdent(planPk)} FROM ${table} t WHERE true${planned.sql} ORDER BY t.${quoteIdent(planPk)} FOR NO KEY UPDATE) UPDATE ${table} AS t SET ${assignments.join(", ")} FROM locked WHERE t.${quoteIdent(planPk)} = locked.${quoteIdent(planPk)} RETURNING ${rowProjection(op.table, "t")}`;
       break;
     }
     case "delete": {
       assertNotAppendOnly("deleteWhere", op.table);
-      sql = `DELETE FROM ${table} AS t WHERE true${renderWhere(op.table, op.where, args, results)} RETURNING t.*`;
+      sql = `DELETE FROM ${table} AS t WHERE true${renderWhere(op.table, op.where, args, results)} RETURNING ${rowProjection(op.table, "t")}`;
       break;
     }
     case "select": {
@@ -2529,15 +3801,157 @@ async function runPlanOp(sp, op, results) {
         limit = ` LIMIT ${n}`;
       }
       const lock = op.lock === "update" ? " FOR UPDATE" : "";
-      sql = `SELECT t.* FROM ${table} t WHERE true${renderWhere(op.table, op.where, args, results)}${limit}${lock}`;
+      sql = `SELECT ${rowProjection(op.table, "t")} FROM ${table} t WHERE true${renderWhere(op.table, op.where, args, results)}${limit}${lock}`;
       break;
     }
     default:
       throw new Error(`unknown operation "${String(op.op)}" in a transaction plan`);
   }
-  return await sp.unsafe(sql, args.values);
+  return {
+    sql,
+    params: args.values,
+    columns: args.columns
+  };
+}
+__name(compilePlanOp, "compilePlanOp");
+async function runPlanOp(sp, op, results) {
+  const statement = compilePlanOp(op, results);
+  return statement ? await sp.unsafe(statement.sql, statement.params) : [];
 }
 __name(runPlanOp, "runPlanOp");
+function compileCommand(plan) {
+  const symbols = /* @__PURE__ */ new Map();
+  const results = [];
+  const steps = [];
+  const pipeline = [];
+  let hasRefs = false;
+  const prefix = `command:${crypto.randomUUID()}:`;
+  const containsFragment = /* @__PURE__ */ __name((v) => isSqlFragment(v) || v !== null && typeof v === "object" && Object.values(v).some(containsFragment), "containsFragment");
+  const hasNullableFilterRef = /* @__PURE__ */ __name((v) => {
+    if (isRef(v)) {
+      const source = plan.ops[v.$ref.op];
+      return source !== void 0 && pageSchema(source.table).columns[v.$ref.field]?.nullable !== false;
+    }
+    return v !== null && typeof v === "object" && Object.values(v).some(hasNullableFilterRef);
+  }, "hasNullableFilterRef");
+  for (const op of plan.ops) {
+    if (!schemaColumns(op.table)?.size) return {
+      reason: `table ${op.table} has no installed declaration`
+    };
+    if (transformsOf(currentSchema, op.table).size || vectorColumnsOf(currentSchema, op.table).size) return {
+      reason: `${op.table} uses JavaScript codecs/transforms or vector values`
+    };
+    if (containsFragment(op)) return {
+      reason: "SQL fragments require the sequential path"
+    };
+    if (hasNullableFilterRef(op.where)) return {
+      reason: "nullable references in filters require the sequential path"
+    };
+  }
+  for (const [index, op] of plan.ops.entries()) {
+    const statement = compilePlanOp(op, results);
+    if (statement === null) {
+      steps.push({
+        empty: true,
+        guard: op.guard
+      });
+      pipeline.push({
+        sql: "SELECT palbase_runtime.command_rows_v1('[]'::jsonb,$1::jsonb) AS rows",
+        params: [
+          op.guard ?? null
+        ]
+      });
+    } else {
+      if (statement.params.some((v) => v === void 0 || typeof v === "symbol" || typeof v === "function" || typeof v === "number" && (!Number.isInteger(v) || v < -2147483648 || v > 2147483647))) {
+        return {
+          reason: "non-integer/wide numeric or non-JSON parameters require the sequential driver path; use exact decimal strings"
+        };
+      }
+      for (const [i, value] of statement.params.entries()) {
+        const target = statement.columns[i];
+        if (target.column === void 0 || columnTypeOf(target.table ?? op.table, target.column) !== "jsonb") continue;
+        const source = typeof value === "string" ? symbols.get(value) : void 0;
+        if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint" || source && "ref" in source && ![
+          "text",
+          "uuid",
+          "timestamp",
+          "enum"
+        ].includes(columnTypeOf(plan.ops[source.ref.op].table, source.ref.field) ?? "")) {
+          return {
+            reason: "JSONB scalar/ref binding requires the sequential driver path"
+          };
+        }
+      }
+      const wide = [
+        ...schemaColumns(op.table)
+      ].filter((c) => [
+        "bigint",
+        "numeric"
+      ].includes(columnTypeOf(op.table, c) ?? ""));
+      const exact = wide.length ? ` || jsonb_build_object(${wide.map((c) => `${quoteLiteral(c)}, r.${quoteIdent(c)}::text`).join(", ")})` : "";
+      const sql = `WITH command_rows AS (${statement.sql}) SELECT coalesce(jsonb_agg(to_jsonb(r)${exact}), '[]'::jsonb) FROM command_rows r`;
+      pipeline.push({
+        sql: `WITH command_rows AS (${statement.sql}) SELECT palbase_runtime.command_rows_v1(coalesce(jsonb_agg(to_jsonb(r)${exact}), '[]'::jsonb),$${statement.params.length + 1}::jsonb) AS rows FROM command_rows r`,
+        params: [
+          ...statement.params,
+          op.guard ?? null
+        ]
+      });
+      const bindings = statement.params.map((value, i) => {
+        const target = statement.columns[i];
+        const json = target.column !== void 0 && columnTypeOf(target.table ?? op.table, target.column) === "jsonb";
+        if (typeof value === "string" && symbols.has(value)) {
+          hasRefs = true;
+          return {
+            ...symbols.get(value),
+            json
+          };
+        }
+        if (typeof value === "bigint") return {
+          value: value.toString(),
+          json
+        };
+        if (value instanceof Date) return {
+          value: value.toISOString(),
+          json
+        };
+        return {
+          value,
+          json
+        };
+      });
+      steps.push({
+        chunks: parameterChunks(sql),
+        bindings,
+        guard: op.guard
+      });
+    }
+    const row = {};
+    for (const field of schemaColumns(op.table)) {
+      const token = `${prefix}${index}:${field}`;
+      symbols.set(token, {
+        ref: {
+          op: index,
+          field
+        }
+      });
+      row[field] = token;
+    }
+    results.push({
+      rows: [
+        row
+      ],
+      rows_affected: 1
+    });
+  }
+  return {
+    steps,
+    ...hasRefs ? {} : {
+      pipeline
+    }
+  };
+}
+__name(compileCommand, "compileCommand");
 function assertGuard(op, result) {
   const guard = op.guard;
   if (!guard) return;
@@ -2551,6 +3965,33 @@ function assertGuard(op, result) {
 }
 __name(assertGuard, "assertGuard");
 
+// src/engine/cancellation.ts
+function withQueryCancellation(application, control) {
+  if (application === control) throw new Error("Query cancellation requires a separate control pool");
+  const close = /* @__PURE__ */ __name(async (driver) => {
+    const d = driver;
+    if (d.close) await d.close();
+    else if (d.end) await d.end();
+  }, "close");
+  return {
+    unsafe: /* @__PURE__ */ __name((sql, params) => application.unsafe(sql, params), "unsafe"),
+    begin: /* @__PURE__ */ __name((fn) => application.begin(fn), "begin"),
+    async cancelBackend(pid, startedAt) {
+      await control.unsafe(`SELECT pg_cancel_backend(pid) FROM pg_stat_activity
+        WHERE pid=$1::integer AND backend_start=$2::timestamptz
+          AND usename=session_user AND datname=current_database() AND backend_type='client backend'`, [
+        pid,
+        startedAt
+      ]);
+    },
+    async close() {
+      await close(application);
+      await close(control);
+    }
+  };
+}
+__name(withQueryCancellation, "withQueryCancellation");
+
 // src/engine/router.ts
 var ROOM_META = /* @__PURE__ */ Symbol.for("palbase.backend.room");
 var CONTROLLER_META = /* @__PURE__ */ Symbol.for("palbase.backend.controllerMeta");
@@ -3055,10 +4496,13 @@ async function defaultSqlDriver(config) {
   if (!g.Bun?.SQL) {
     throw new BootRefused([], "boot refused: no SQL driver. Running outside Bun means the driver must be supplied \u2014 pass `sql` to createApp().");
   }
-  return new g.Bun.SQL({
+  return withQueryCancellation(new g.Bun.SQL({
     url: config.databaseUrl,
     max: config.poolMax
-  });
+  }), new g.Bun.SQL({
+    url: config.databaseUrl,
+    max: 2
+  }));
 }
 __name(defaultSqlDriver, "defaultSqlDriver");
 var AUTHOR_ANSWERED = /* @__PURE__ */ new Set([
@@ -3117,6 +4561,11 @@ async function createApp(opts) {
   const sql = opts.sql ?? await defaultSqlDriver(config);
   await sql.unsafe("select 1");
   setSchema(opts.schemas ?? []);
+  setCursorKey(config.cursorSecret || config.serviceRoleKey || null);
+  if (config.enableCommands) await installCommandExecutor(sql, [
+    config.dbRole,
+    config.dbServiceRole
+  ]);
   setSecretReader(opts.secretReader ?? null);
   const auth = new AuthVerifier({
     jwksUrl: config.authJwksUrl,
@@ -3162,6 +4611,9 @@ async function createApp(opts) {
       role: config.dbRole,
       serviceRole: config.dbServiceRole,
       claimsJson: "{}"
+    }, config.databaseDiagnostics === void 0 ? void 0 : {
+      ...config.databaseDiagnostics,
+      endpoint: "scheduled job"
     });
     try {
       const out = await runWithRuntime(buildServices(db), fn);
@@ -3191,6 +4643,10 @@ async function createApp(opts) {
       role: config.dbRole,
       serviceRole: config.dbServiceRole,
       claimsJson: JSON.stringify(callerClaims ?? {})
+    }, config.databaseDiagnostics === void 0 ? void 0 : {
+      ...config.databaseDiagnostics,
+      endpoint: "upload authorization",
+      requestId
     });
     try {
       const refusal = await refuseUnlessAuthorized(uploadDb.client, spec, requestId, makeRoleResolver(uploadDb.client));
@@ -3238,6 +4694,11 @@ async function createApp(opts) {
       role: config.dbRole,
       serviceRole: config.dbServiceRole,
       claimsJson: JSON.stringify(claims ?? {})
+    }, config.databaseDiagnostics === void 0 && meta.options.databaseBudget === void 0 ? void 0 : {
+      ...config.databaseDiagnostics,
+      ...meta.options.databaseBudget,
+      endpoint: hit.entry.id,
+      requestId
     });
     const rolesOfCaller = makeRoleResolver(db.client);
     let dispatched = false;
@@ -3667,11 +5128,15 @@ export {
   effectiveAuth,
   RateLimiter,
   makeMemoryCache,
+  setCursorKey,
+  COMMAND_EXECUTOR_DDL,
+  installCommandExecutor,
   quoteIdent,
   createLazyTransaction,
   createOps,
   withTables,
   createRequestDatabase,
+  withQueryCancellation,
   buildRouteTable,
   matchRoute,
   scrubSecrets,
@@ -3679,4 +5144,4 @@ export {
   installEgressFence,
   createApp
 };
-//# sourceMappingURL=chunk-C6COAB3E.js.map
+//# sourceMappingURL=chunk-MNGZE2MM.js.map