@palbase/backend 35.0.1 → 36.0.1

package/dist/engine/index.cjs

@@ -703,25 +703,6 @@ function translateRejection(err, builder) {
 }
 __name(translateRejection, "translateRejection");
 
-// src/db/workload.ts
-function validateWorkload(value) {
-  if (typeof value.name !== "string" || !/^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$/.test(value.name)) throw new Error("workload name must be 1\u201364 letters/digits/dots/dashes");
-  for (const name of [
-    "concurrency",
-    "tenantConcurrency",
-    "queueLimit",
-    "tenantQueueLimit",
-    "queueTimeoutMs"
-  ]) {
-    const n = value[name], min = name.endsWith("Limit") ? 0 : 1;
-    const max = name === "queueTimeoutMs" ? 6e4 : name.endsWith("Limit") ? 1e4 : 1e3;
-    if (!Number.isInteger(n) || n < min || n > max) throw new Error(`workload ${name} must be an integer between ${min} and ${max}`);
-  }
-  if (value.tenantConcurrency > value.concurrency || value.tenantQueueLimit > value.queueLimit) throw new Error("workload tenant limits cannot exceed global limits");
-  if (typeof value.tenantClaim !== "string" || !/^[a-zA-Z][a-zA-Z0-9_]{0,63}$/.test(value.tenantClaim)) throw new Error("workload tenantClaim must be a top-level claim name");
-}
-__name(validateWorkload, "validateWorkload");
-
 // src/db/transaction-options.ts
 function retryBudget(value) {
   const n = value ?? 0;
@@ -753,10 +734,6 @@ function validateAtomicOptions(options) {
       throw new Error(`transaction ${name} must be a positive integer in milliseconds`);
     }
   }
-  if (options.workload !== void 0) validateWorkload(options.workload);
-  if (options.conflictKeys !== void 0 && (!options.workload || !Array.isArray(options.conflictKeys) || options.conflictKeys.length > 64 || options.conflictKeys.some((k) => typeof k !== "string" || k.length < 1 || k.length > 256))) {
-    throw new Error("conflictKeys requires a workload and at most 64 nonempty keys of at most 256 characters");
-  }
   if (options.signal !== void 0 && (typeof options.signal.aborted !== "boolean" || typeof options.signal.addEventListener !== "function")) {
     throw new Error("transaction signal must be an AbortSignal");
   }
@@ -916,7 +893,9 @@ function makeTableProxy(ops, prefix) {
         // Older than this run, but the run rewrote this proxy for
         // `Database.schema(name).tables.*` and would have carried the gap onto
         // the new surface too.
-        updateMany: /* @__PURE__ */ __name((q) => ops().updateMany(name, q.where, q.set), "updateMany"),
+        updateMany: /* @__PURE__ */ __name((q) => ops().updateMany(name, q.where, q.set, q.returning === void 0 ? void 0 : {
+          returning: q.returning
+        }), "updateMany"),
         deleteMany: /* @__PURE__ */ __name((q) => ops().deleteMany(name, q.where), "deleteMany"),
         count: /* @__PURE__ */ __name((q) => ops().count(name, q?.where), "count"),
         search: /* @__PURE__ */ __name((params) => ops().search(name, params), "search"),
@@ -936,9 +915,6 @@ function makeTypedSurface(raw) {
   const ops = {
     $query: /* @__PURE__ */ __name((sql, params) => raw.query(sql, params), "$query"),
     $diagnostics: /* @__PURE__ */ __name(() => raw.diagnostics(), "$diagnostics"),
-    $readQuery: /* @__PURE__ */ __name((query) => raw.readQuery(query), "$readQuery"),
-    $compileQuery: /* @__PURE__ */ __name((query) => raw.compileQuery(query), "$compileQuery"),
-    $explainQuery: /* @__PURE__ */ __name((query) => raw.explainQuery(query), "$explainQuery"),
     $insert: /* @__PURE__ */ __name((table, data) => raw.insert(table, data), "$insert"),
     $update: /* @__PURE__ */ __name((table, id, data) => raw.update(table, id, data), "$update"),
     $delete: /* @__PURE__ */ __name((table, id) => raw.delete(table, id), "$delete"),
@@ -1143,6 +1119,7 @@ var Realtime = makeServiceProxy("Realtime");
 var SQLSTATE = Object.freeze({
   serializationFailure: "40001",
   deadlockDetected: "40P01",
+  queryCancelled: "57014",
   commandGuardFailed: "PBC01"
 });
 function isTransactionRollbackState(state) {
@@ -1345,6 +1322,16 @@ ${detail}`);
   if (!Number.isInteger(poolMax) || poolMax < 1) {
     throw new BootRefused([], `boot refused: DB_POOL_MAX must be a positive integer (got ${env.DB_POOL_MAX}).`);
   }
+  const capacityNumber = /* @__PURE__ */ __name((key2, minimum, maximum) => {
+    if (env[key2] === void 0) return void 0;
+    const value = Number(env[key2]);
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum) throw new BootRefused([], `boot refused: ${key2} must be between ${minimum} and ${maximum}.`);
+    return value;
+  }, "capacityNumber");
+  const queueLimit = capacityNumber("PALBASE_DB_QUEUE_LIMIT", 0, 1e4);
+  const queueTimeoutMs = capacityNumber("PALBASE_DB_QUEUE_TIMEOUT_MS", 1, 6e4);
+  const tenantClaim = env.PALBASE_DB_TENANT_CLAIM;
+  if (tenantClaim !== void 0 && !/^[a-zA-Z][a-zA-Z0-9_]{0,63}$/.test(tenantClaim)) throw new BootRefused([], "boot refused: PALBASE_DB_TENANT_CLAIM must be a top-level trusted claim name.");
   return {
     databaseUrl: env.DATABASE_URL.trim(),
     authJwksUrl: env.AUTH_JWKS_URL.trim(),
@@ -1369,6 +1356,17 @@ ${detail}`);
     // and the live database agrees (pg_roles.rolbypassrls = true).
     dbServiceRole: env.DB_SERVICE_ROLE ?? "backend_service_role",
     poolMax,
+    databaseAdmission: {
+      ...queueLimit === void 0 ? {} : {
+        queueLimit
+      },
+      ...queueTimeoutMs === void 0 ? {} : {
+        queueTimeoutMs
+      },
+      ...tenantClaim === void 0 ? {} : {
+        tenantClaim
+      }
+    },
     ...env.PALBASE_DB_DIAGNOSTICS === "true" ? {
       databaseDiagnostics: {
         onComplete: /* @__PURE__ */ __name((diagnostics) => {
@@ -1892,46 +1890,6 @@ function validateInsertManyOptions(opts) {
 }
 __name(validateInsertManyOptions, "validateInsertManyOptions");
 
-// src/db/query-contract.ts
-function queryColumnContract(column) {
-  const def = column && typeof column === "object" && "_def" in column ? column._def : column;
-  if (!def?.type) throw new Error("Query contract requires declared column types");
-  if (def.transform !== void 0 && def.codec === void 0) throw new Error("Query contracts require a named codec instead of a free-form column transform");
-  return {
-    type: def.type,
-    nullable: def.nullable === true,
-    ...def.codec === void 0 ? {} : {
-      codec: def.codec
-    },
-    ...def.enumValues === void 0 ? {} : {
-      enumValues: [
-        ...def.enumValues
-      ]
-    },
-    ...def.dimensions === void 0 ? {} : {
-      dimensions: def.dimensions
-    }
-  };
-}
-__name(queryColumnContract, "queryColumnContract");
-function stableContract(value) {
-  if (Array.isArray(value)) return `[${value.map(stableContract).join(",")}]`;
-  if (value && typeof value === "object") return `{${Object.keys(value).sort().map((key2) => `${JSON.stringify(key2)}:${stableContract(value[key2])}`).join(",")}}`;
-  return JSON.stringify(value) ?? "null";
-}
-__name(stableContract, "stableContract");
-function assertReadContract(query, columns) {
-  if (!query.options.select.length || new Set(query.options.select).size !== query.options.select.length) {
-    throw new Error(`Query ${query.name}: select must contain distinct, explicit columns`);
-  }
-  for (const name of query.options.select) {
-    if (!columns || !Object.hasOwn(columns, name) || !Object.hasOwn(query.columns, name) || stableContract(queryColumnContract(columns[name])) !== stableContract(query.columns[name])) {
-      throw new Error(`Query ${query.name}: schema drift at ${query.table}.${name}; regenerate and review its response contract`);
-    }
-  }
-}
-__name(assertReadContract, "assertReadContract");
-
 // src/db/unique.ts
 function uniqueKeysOf(table) {
   const columns = table.columns ?? {};
@@ -2105,142 +2063,167 @@ function parameterChunks(sql) {
 __name(parameterChunks, "parameterChunks");
 
 // src/engine/admission.ts
-var WorkloadAdmission = class {
+var DatabaseAdmission = class {
   static {
-    __name(this, "WorkloadAdmission");
+    __name(this, "DatabaseAdmission");
   }
-  definition;
-  pending = [];
+  options;
   active = 0;
-  activeKeys = /* @__PURE__ */ new Set();
+  queued = 0;
   tenants = /* @__PURE__ */ new Map();
-  draining = false;
-  constructor(definition) {
-    this.definition = definition;
-    validateWorkload(definition);
+  // Map insertion order is the round-robin ring; each Set is FIFO. Grant and
+  // cancellation remove nodes directly, without scanning a 10,000-item queue.
+  pending = /* @__PURE__ */ new Map();
+  lastTenant;
+  accepted = 0;
+  rejected = {
+    full: 0,
+    timeout: 0,
+    cancelled: 0
+  };
+  limit;
+  timeout;
+  constructor(options) {
+    this.options = options;
+    this.limit = options.queueLimit ?? Math.min(512, Math.max(32, options.concurrency * 8));
+    this.timeout = options.queueTimeoutMs ?? 1e3;
+    if (!Number.isSafeInteger(options.concurrency) || options.concurrency < 1 || !Number.isSafeInteger(this.limit) || this.limit < 0 || this.limit > 1e4 || !Number.isSafeInteger(this.timeout) || this.timeout < 1 || this.timeout > 6e4) {
+      throw new Error("Invalid database pool or queue deployment settings");
+    }
   }
   get snapshot() {
     return {
       active: this.active,
-      queued: this.pending.length,
+      queued: this.queued,
       tenants: this.tenants.size,
-      keys: this.activeKeys.size
+      accepted: this.accepted,
+      rejected: {
+        ...this.rejected
+      }
+    };
+  }
+  rejection(reason2) {
+    this.rejected[reason2]++;
+    try {
+      this.options.onReject?.({
+        reason: reason2,
+        active: this.active,
+        queued: this.queued
+      });
+    } catch {
+    }
+  }
+  take(tenant, entered) {
+    this.active++;
+    this.accepted++;
+    this.lastTenant = tenant;
+    this.tenants.set(tenant, (this.tenants.get(tenant) ?? 0) + 1);
+    let released = false;
+    return {
+      queueMs: performance.now() - entered,
+      release: /* @__PURE__ */ __name(() => {
+        if (released) return;
+        released = true;
+        this.active--;
+        const count = this.tenants.get(tenant) - 1;
+        if (count) this.tenants.set(tenant, count);
+        else this.tenants.delete(tenant);
+        this.drain();
+      }, "release")
     };
   }
-  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({
+  drain() {
+    while (this.active < this.options.concurrency && this.queued) {
+      let tenant = this.pending.keys().next().value;
+      if (this.pending.size > 1 && tenant === this.lastTenant) {
+        const queue2 = this.pending.get(tenant);
+        this.pending.delete(tenant);
+        this.pending.set(tenant, queue2);
+        tenant = this.pending.keys().next().value;
+      }
+      const queue = this.pending.get(tenant), waiter = queue.values().next().value;
+      queue.delete(waiter);
+      this.pending.delete(tenant);
+      if (queue.size) this.pending.set(tenant, queue);
+      this.queued--;
+      waiter.cleanup();
+      waiter.grant(this.take(tenant, waiter.entered));
+    }
+  }
+  async acquire(claimsJson, signal) {
+    if (signal?.aborted) {
+      this.rejection("cancelled");
+      throw signal.reason ?? new Error("Database admission cancelled");
+    }
+    const claims = JSON.parse(claimsJson);
+    const value = this.options.tenantClaim ? claims[this.options.tenantClaim] : claims.sub;
+    const tenant = typeof value === "string" && value.length ? value : "__anonymous__";
+    const entered = performance.now();
+    if (this.active < this.options.concurrency && !this.queued) return this.take(tenant, entered);
+    if (this.queued >= this.limit) {
+      this.rejection("full");
+      throw new TooManyRequests({
         retryAfter: 1
-      }, `Database workload ${this.definition.name}: ${tenantFull ? "tenant" : "global"} queue is full`));
+      }, "Database queue is full");
     }
     return new Promise((grant, reject) => {
+      const queue = this.pending.get(tenant) ?? /* @__PURE__ */ new Set();
+      if (!this.pending.has(tenant)) this.pending.set(tenant, queue);
       const waiter = {
-        tenant,
-        keys: scoped,
-        entered: performance.now(),
         grant,
         reject,
-        cleanup: /* @__PURE__ */ __name(() => {
-        }, "cleanup")
+        entered,
+        cleanup() {
+        }
       };
-      const remove = /* @__PURE__ */ __name((reason2) => {
-        const index = this.pending.indexOf(waiter);
-        if (index === -1) return;
-        this.pending.splice(index, 1);
+      const remove = /* @__PURE__ */ __name((reason2, error) => {
+        if (!queue.delete(waiter)) return;
+        if (!queue.size) this.pending.delete(tenant);
+        this.queued--;
         waiter.cleanup();
-        reject(reason2);
+        this.rejection(reason2);
+        reject(error);
         this.drain();
       }, "remove");
-      const abort = /* @__PURE__ */ __name(() => remove(signal?.reason ?? new Error("Database admission cancelled")), "abort");
-      const timer = setTimeout(() => remove(new TooManyRequests({
+      const abort = /* @__PURE__ */ __name(() => remove("cancelled", signal?.reason ?? new Error("Database admission cancelled")), "abort");
+      const timer = setTimeout(() => remove("timeout", new TooManyRequests({
         retryAfter: 1
-      }, `Database workload ${this.definition.name}: queue deadline exceeded`)), this.definition.queueTimeoutMs);
+      }, "Database queue deadline exceeded")), this.timeout);
       waiter.cleanup = () => {
         clearTimeout(timer);
         signal?.removeEventListener("abort", abort);
       };
+      queue.add(waiter);
+      this.queued++;
       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 databases = /* @__PURE__ */ new WeakMap();
+function databaseAdmission(owner, options) {
+  let admission = databases.get(owner);
+  if (!admission) {
+    admission = new DatabaseAdmission(options ?? {
+      concurrency: 10
+    });
+    databases.set(owner, admission);
+  } else if (options) {
+    for (const key2 of [
+      "concurrency",
+      "queueLimit",
+      "queueTimeoutMs",
+      "tenantClaim"
+    ]) {
+      if (options[key2] !== admission.options[key2]) throw new Error("Database admission cannot be reconfigured while its pool is shared");
     }
   }
-};
-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");
+__name(databaseAdmission, "databaseAdmission");
 
 // src/engine/transaction-control.ts
 var TransactionControl = class {
@@ -2363,6 +2346,7 @@ var DatabaseTrace = class {
       sqlMs: 0,
       commitMs: 0,
       rollbackMs: 0,
+      connectionMs: 0,
       commits: 0,
       commitFailures: 0,
       rollbackRequests: 0,
@@ -2374,7 +2358,7 @@ var DatabaseTrace = class {
     if (this.failure) throw this.failure;
   }
   time(key2, started) {
-    this.state[key2] += performance.now() - started;
+    this.state[key2] = (this.state[key2] ?? 0) + performance.now() - started;
   }
   retry() {
     this.state.retries++;
@@ -2698,31 +2682,53 @@ function createLazyTransaction(sql, role, claimsJson, options = {}) {
         fail = rej;
       });
       void parked.catch(() => void 0);
-      const openingAt = options.trace ? performance.now() : 0;
-      settled = sql.begin(async (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"}`);
+      settled = (async () => {
+        const queuedAt = performance.now();
+        let lease;
+        try {
+          lease = await (sql.admission ?? databaseAdmission(sql)).acquire(claimsJson, options.control?.signal);
+        } finally {
+          options.trace?.time("queueMs", queuedAt);
         }
-        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 openingAt = performance.now();
+        let connectedAt;
+        try {
+          options.control?.check();
+          if (closed) throw new Error("Database transaction closed while waiting for admission");
+          return await sql.begin(async (tx) => {
+            connectedAt = performance.now();
+            options.trace?.time("poolMs", openingAt);
+            const setupAt = options.trace ? performance.now() : 0;
+            options.control?.check();
+            if (closed) throw new Error("Database transaction closed while waiting for its connection");
+            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(`WITH backend AS MATERIALIZED (
+              SELECT pid, backend_start::text AS started FROM pg_catalog.pg_stat_get_activity(pg_catalog.pg_backend_pid())
+            ) ${bindSql}, backend.pid, backend.started FROM backend`, bindParams);
+              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();
+            } else {
+              const binding = tx.unsafe(bindSql, bindParams);
+              await (options.control ? options.control.watch(binding) : binding);
+            }
+            options.trace?.time("setupMs", setupAt);
+            resolveTx2(scoped(tx));
+            await parked;
+          });
+        } finally {
+          if (connectedAt !== void 0) options.trace?.time("connectionMs", connectedAt);
+          lease.release();
         }
-        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) => {
+      })().catch((e) => {
         rejectTx(e);
         throw e;
       });
@@ -2739,10 +2745,13 @@ function createLazyTransaction(sql, role, claimsJson, options = {}) {
       if (pendingSavepoints.size) await Promise.allSettled([
         ...pendingSavepoints
       ]);
-      options.control?.check();
       options.trace?.check();
+      if (!opening) {
+        closed = true;
+        return;
+      }
+      options.control?.check();
       closed = true;
-      if (!opening) return;
       const started = options.trace ? performance.now() : 0;
       release();
       try {
@@ -2869,10 +2878,11 @@ function asTableRows(table, rows, withSpec, partial = false) {
     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);
+      const selected = typeof spec === "object" && "select" in spec && spec.select !== void 0;
+      if (Array.isArray(value)) row[rel.name] = asTableRows(rel.to, value, nested, selected);
       else if (value && typeof value === "object") row[rel.name] = asTableRows(rel.to, [
         value
-      ], nested)[0];
+      ], nested, selected)[0];
     }
   }
   for (const row of result) foldCan(table, row, partial);
@@ -3816,6 +3826,9 @@ function withClauses(table, spec, add, caller, parentAlias = "t", depth = 0, cou
     const i = ++counter.value;
     const childAlias = `w${i}`;
     const childKnown = schemaColumns(rel.to);
+    if (o["select"] !== void 0 && (!Array.isArray(o["select"]) || o["select"].length === 0)) {
+      throw new Error(`${caller}(${table}): with.${name}.select must be a non-empty array of columns`);
+    }
     const childCols = Array.isArray(o["select"]) && o["select"].length > 0 ? o["select"] : childKnown !== null ? [
       ...childKnown
     ] : [];
@@ -3919,7 +3932,10 @@ function pageSchema(table) {
 }
 __name(pageSchema, "pageSchema");
 function createOps(tx, context = {}) {
-  const at = /* @__PURE__ */ __name(() => resolveTx(tx), "at");
+  const at = /* @__PURE__ */ __name(() => {
+    const target = typeof tx === "function" ? tx() : tx;
+    return target instanceof Promise ? target.then(resolveTx) : resolveTx(target);
+  }, "at");
   const ops = {
     diagnostics() {
       return context.trace?.snapshot ?? null;
@@ -4370,22 +4386,6 @@ function createOps(tx, context = {}) {
       ]);
       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
-      }), void 0, true);
-    },
-    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, opts.select !== void 0);
@@ -4920,7 +4920,7 @@ function createOps(tx, context = {}) {
         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 {
+      if (compiled.steps.length === 0 && !compiled.pipeline?.length) return {
         results: []
       };
       if (compiled.pipeline) {
@@ -5193,6 +5193,7 @@ function diagnosingDriver(sql, surface = "service") {
     const state = sqlstateOf(e);
     if (state === SQLSTATE.serializationFailure) return markEngineRaised(new SerializationFailure(state));
     if (state === SQLSTATE.deadlockDetected) return markEngineRaised(new DeadlockDetected(state));
+    if (state === SQLSTATE.queryCancelled) return markEngineRaised(new HttpError(503, "database_query_cancelled", "Database statement was cancelled"));
     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)})`);
     }
@@ -5219,6 +5220,7 @@ function diagnosingDriver(sql, surface = "service") {
     }
   }), "wrapTx");
   return {
+    admission: sql.admission ?? databaseAdmission(sql),
     unsafe: /* @__PURE__ */ __name((text, params) => sql.unsafe(text, params), "unsafe"),
     cancelBackend: sql.cancelBackend?.bind(sql),
     begin: /* @__PURE__ */ __name((cb) => sql.begin((tx) => cb(wrapTx(tx))).catch((e) => {
@@ -5227,9 +5229,12 @@ function diagnosingDriver(sql, surface = "service") {
   };
 }
 __name(diagnosingDriver, "diagnosingDriver");
-function createRequestDatabase(sql, identity, diagnostics) {
+function createRequestDatabase(sql, identity, diagnostics, signal) {
   const trace = diagnostics === void 0 ? void 0 : new DatabaseTrace(diagnostics);
+  const requestControl = signal === void 0 ? void 0 : new TransactionControl(void 0, signal);
   let requestClosed = false;
+  let authorized = false, applicationTouched = false;
+  let authorizationRelease;
   const contextFor = /* @__PURE__ */ __name((role) => {
     let scope;
     return {
@@ -5248,19 +5253,21 @@ function createRequestDatabase(sql, identity, diagnostics) {
     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");
+    if (authorized && !applicationTouched && tx.opened) {
+      authorizationRelease ??= (async () => {
+        await tx.commit();
+        tx = requestTransaction();
+      })();
+    }
+    if (authorizationRelease) await authorizationRelease;
     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;
+    const atomicSignal = options.signal && signal ? AbortSignal.any([
+      options.signal,
+      signal
+    ]) : options.signal ?? signal;
+    const control = options.timeoutMs !== void 0 || atomicSignal !== void 0 ? new TransactionControl(options.timeoutMs, atomicSignal) : void 0;
     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 = [
@@ -5293,19 +5300,23 @@ function createRequestDatabase(sql, identity, diagnostics) {
       }
     } finally {
       control?.dispose();
-      lease?.release();
     }
   }, "atomic");
-  const tx = createLazyTransaction(diagnosingDriver(sql, "user"), identity.role, identity.claimsJson, {
-    trace
-  });
+  const requestTransaction = /* @__PURE__ */ __name(() => createLazyTransaction(diagnosingDriver(sql, "user"), identity.role, identity.claimsJson, {
+    trace,
+    control: requestControl
+  }), "requestTransaction");
+  let tx = requestTransaction();
   let serviceTx = null;
+  let serviceControl;
   let serviceClient = null;
   const asService = /* @__PURE__ */ __name(() => {
     if (serviceClient === null) {
+      serviceControl = signal === void 0 ? void 0 : new TransactionControl(void 0, signal);
       serviceTx = createLazyTransaction(diagnosingDriver(sql, "service"), identity.serviceRole, identity.claimsJson, {
         lockTimeout: SERVICE_LOCK_TIMEOUT,
-        trace
+        trace,
+        control: serviceControl
       });
       serviceClient = Object.assign(withTables(createOps(serviceTx, serviceContext)), {
         atomic: atomic(identity.serviceRole, "service")
@@ -5314,16 +5325,24 @@ function createRequestDatabase(sql, identity, diagnostics) {
     return serviceClient;
   }, "asService");
   return {
-    client: Object.assign(withTables(createOps(tx, userContext)), {
+    client: Object.assign(withTables(createOps(() => {
+      if (authorized) applicationTouched = true;
+      return authorizationRelease ? authorizationRelease.then(() => tx) : tx;
+    }, userContext)), {
       asService,
       atomic: atomic(identity.role, "user")
     }),
+    authorizationComplete() {
+      authorized = true;
+    },
     async commit() {
       requestClosed = true;
       try {
         await tx.commit();
         await serviceTx?.commit();
         trace?.complete("committed");
+        requestControl?.dispose();
+        serviceControl?.dispose();
       } catch (error) {
         trace?.failed();
         throw error;
@@ -5333,6 +5352,8 @@ function createRequestDatabase(sql, identity, diagnostics) {
       requestClosed = true;
       await tx.rollback(reason2);
       await serviceTx?.rollback(reason2);
+      requestControl?.dispose();
+      serviceControl?.dispose();
       trace?.complete("failed");
     }
   };
@@ -5640,7 +5661,7 @@ function compileCommand(plan) {
         };
       });
       steps.push({
-        chunks: parameterChunks(sql),
+        sql,
         bindings,
         guard: op.guard
       });
@@ -5663,11 +5684,15 @@ function compileCommand(plan) {
       rows_affected: 1
     });
   }
+  if (!hasRefs) return {
+    steps: [],
+    pipeline
+  };
   return {
-    steps,
-    ...hasRefs ? {} : {
-      pipeline
-    }
+    steps: steps.map(({ sql, ...step }) => sql === void 0 ? step : {
+      ...step,
+      chunks: parameterChunks(sql)
+    })
   };
 }
 __name(compileCommand, "compileCommand");
@@ -6130,9 +6155,11 @@ function makeSseWriter(opts) {
       if (!begun) {
         begun = true;
         chain = chain.then(() => opts.onFirstWrite()).then(() => opts.enqueue(frame));
+        void chain.catch(() => void 0);
         return;
       }
       chain = chain.then(() => opts.enqueue(frame));
+      void chain.catch(() => void 0);
     },
     started() {
       return begun;
@@ -6727,6 +6754,23 @@ async function createApp(opts) {
     throw new DeclarationRefused("boot refused: zero endpoints collected \u2014 nothing would answer.");
   }
   const sql = opts.sql ?? await defaultSqlDriver(config);
+  const admission = sql.admission ?? databaseAdmission(sql, {
+    concurrency: config.poolMax,
+    ...config.databaseAdmission
+  });
+  const inFlight = /* @__PURE__ */ new Set();
+  let shuttingDown;
+  let accepting = true;
+  async function serving(run) {
+    const work = run();
+    inFlight.add(work);
+    try {
+      return await work;
+    } finally {
+      inFlight.delete(work);
+    }
+  }
+  __name(serving, "serving");
   await sql.unsafe("select 1");
   setSchema(opts.schemas ?? []);
   setCursorKey(config.cursorSecret || config.serviceRoleKey || null);
@@ -6793,6 +6837,19 @@ async function createApp(opts) {
     }
   }
   __name(runInServiceScope, "runInServiceScope");
+  function errorResponse(err, endpoint, requestId) {
+    if (isHttpError(err)) {
+      if (isEngineRaised(err) || !AUTHOR_ANSWERED.has(err.status)) {
+        log.error(`[engine] unhandled ${err.error} in ${endpoint}`, err);
+      }
+      return envelope(err.error, err.errorDescription, err.status, requestId, err.data !== void 0 ? {
+        data: err.data
+      } : void 0);
+    }
+    log.error(`[engine] unhandled error in ${endpoint}`, err);
+    return envelope("internal_error", "The request could not be completed", 500, requestId);
+  }
+  __name(errorResponse, "errorResponse");
   async function handleAuthorize(req, requestId) {
     if (uploadSecret === "" || !verifySignature(req.headers.get(SIGNATURE_HEADER) ?? "", uploadSecret)) {
       return envelope("unauthorized", "This endpoint is not callable directly", 401, requestId);
@@ -6815,7 +6872,7 @@ async function createApp(opts) {
       ...config.databaseDiagnostics,
       endpoint: "upload authorization",
       requestId
-    });
+    }, req.signal);
     try {
       const refusal = await refuseUnlessAuthorized(uploadDb.client, spec, requestId, makeRoleResolver(uploadDb.client));
       if (refusal) {
@@ -6825,7 +6882,7 @@ async function createApp(opts) {
       await uploadDb.commit();
     } catch (err) {
       await uploadDb.rollback(err);
-      throw err;
+      return errorResponse(err, "upload authorization", requestId);
     }
     const grant = grantFor(target?.entry, {
       userId: typeof callerClaims?.sub === "string" ? callerClaims.sub : null,
@@ -6867,256 +6924,257 @@ async function createApp(opts) {
       ...meta.options.databaseBudget,
       endpoint: hit.entry.id,
       requestId
-    });
-    const rolesOfCaller = makeRoleResolver(db.client);
-    let dispatched = false;
-    const settleBeforeRefusal = /* @__PURE__ */ __name(async () => {
-      if (dispatched) return;
-      await db.rollback(new Error("request refused before dispatch"));
-    }, "settleBeforeRefusal");
-    const refusal = await refuseUnlessAuthorized(db.client, spec, requestId, rolesOfCaller);
-    if (refusal) {
-      await settleBeforeRefusal();
-      return refusal;
-    }
-    if (claims && spec.verifiedEmail && claims.email_verified !== true) {
-      await settleBeforeRefusal();
-      return envelope("email_not_verified", "A verified email address is required", 403, requestId);
-    }
-    let parsedBody;
-    let bodyRead = false;
-    let rawBody = null;
-    if (req.method !== "GET" && req.method !== "HEAD") {
-      const declared = Number(req.headers.get("content-length") ?? "");
-      if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+    }, req.signal);
+    try {
+      const rolesOfCaller = makeRoleResolver(db.client);
+      let dispatched = false;
+      const settleBeforeRefusal = /* @__PURE__ */ __name(async () => {
+        if (dispatched) return;
+        await db.rollback(new Error("request refused before dispatch"));
+      }, "settleBeforeRefusal");
+      const refusal = await refuseUnlessAuthorized(db.client, spec, requestId, rolesOfCaller);
+      if (refusal) {
+        await settleBeforeRefusal();
+        return refusal;
+      }
+      if (claims && spec.verifiedEmail && claims.email_verified !== true) {
+        await settleBeforeRefusal();
+        return envelope("email_not_verified", "A verified email address is required", 403, requestId);
+      }
+      let parsedBody;
+      let bodyRead = false;
+      let rawBody = null;
+      if (req.method !== "GET" && req.method !== "HEAD") {
+        const declared = Number(req.headers.get("content-length") ?? "");
+        if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+          await settleBeforeRefusal();
+          return new Response(JSON.stringify({
+            error: "payload_too_large",
+            error_description: `Request body exceeds ${MAX_BODY_BYTES} bytes`,
+            status: 413,
+            request_id: requestId
+          }), {
+            status: 413,
+            headers: JSON_HEADERS
+          });
+        }
+        const buf = await req.arrayBuffer().catch(() => null);
+        if (buf && buf.byteLength > MAX_BODY_BYTES) {
+          await settleBeforeRefusal();
+          return new Response(JSON.stringify({
+            error: "payload_too_large",
+            error_description: `Request body exceeds ${MAX_BODY_BYTES} bytes`,
+            status: 413,
+            request_id: requestId
+          }), {
+            status: 413,
+            headers: JSON_HEADERS
+          });
+        }
+        if (buf && buf.byteLength > 0) rawBody = new Uint8Array(buf);
+      }
+      const readParsedBody = /* @__PURE__ */ __name(() => {
+        if (bodyRead) return parsedBody;
+        bodyRead = true;
+        if (!rawBody) {
+          parsedBody = {};
+          return parsedBody;
+        }
+        try {
+          parsedBody = JSON.parse(new TextDecoder().decode(rawBody));
+        } catch {
+          parsedBody = {};
+        }
+        return parsedBody;
+      }, "readParsedBody");
+      const attest = await attestGate(req, rawBody, {
+        userId
+      });
+      if (attest.observation) observations.record(attest.observation);
+      if (attest.outcome === "reject") {
+        const headers = {
+          ...JSON_HEADERS
+        };
+        if (attest.nextChallenge) headers["x-palbase-attest-challenge"] = attest.nextChallenge;
         await settleBeforeRefusal();
         return new Response(JSON.stringify({
-          error: "payload_too_large",
-          error_description: `Request body exceeds ${MAX_BODY_BYTES} bytes`,
-          status: 413,
+          error: attest.reason,
+          error_description: "This endpoint requires a verified app instance",
+          status: 401,
           request_id: requestId
         }), {
-          status: 413,
-          headers: JSON_HEADERS
+          status: 401,
+          headers
         });
       }
-      const buf = await req.arrayBuffer().catch(() => null);
-      if (buf && buf.byteLength > MAX_BODY_BYTES) {
+      if (attest.device && claims) attestedDevice = attest.device;
+      attestChallengeOut = attest.nextChallenge;
+      const retryAfter = limiter.check(meta.options?.rateLimit, RateLimiter.key(hit.entry.id, userId, req.headers), Date.now());
+      if (retryAfter !== null) {
         await settleBeforeRefusal();
         return new Response(JSON.stringify({
-          error: "payload_too_large",
-          error_description: `Request body exceeds ${MAX_BODY_BYTES} bytes`,
-          status: 413,
-          request_id: requestId
+          error: "too_many_requests",
+          error_description: "Rate limit exceeded for this endpoint",
+          status: 429,
+          request_id: requestId,
+          data: {
+            retryAfter
+          }
         }), {
-          status: 413,
-          headers: JSON_HEADERS
+          status: 429,
+          headers: {
+            ...JSON_HEADERS,
+            "retry-after": String(retryAfter)
+          }
         });
       }
-      if (buf && buf.byteLength > 0) rawBody = new Uint8Array(buf);
-    }
-    const readParsedBody = /* @__PURE__ */ __name(() => {
-      if (bodyRead) return parsedBody;
-      bodyRead = true;
-      if (!rawBody) {
-        parsedBody = {};
-        return parsedBody;
-      }
-      try {
-        parsedBody = JSON.parse(new TextDecoder().decode(rawBody));
-      } catch {
-        parsedBody = {};
-      }
-      return parsedBody;
-    }, "readParsedBody");
-    const attest = await attestGate(req, rawBody, {
-      userId
-    });
-    if (attest.observation) observations.record(attest.observation);
-    if (attest.outcome === "reject") {
-      const headers = {
-        ...JSON_HEADERS
-      };
-      if (attest.nextChallenge) headers["x-palbase-attest-challenge"] = attest.nextChallenge;
-      await settleBeforeRefusal();
-      return new Response(JSON.stringify({
-        error: attest.reason,
-        error_description: "This endpoint requires a verified app instance",
-        status: 401,
-        request_id: requestId
-      }), {
-        status: 401,
-        headers
+      let completionUploadId = null;
+      const args = [];
+      let sseEnqueue = null;
+      let sseSettle = /* @__PURE__ */ __name(async () => {
+      }, "sseSettle");
+      const sseWriter = makeSseWriter({
+        enqueue: /* @__PURE__ */ __name((chunk) => sseEnqueue?.(chunk), "enqueue"),
+        onFirstWrite: /* @__PURE__ */ __name(() => sseSettle(), "onFirstWrite")
       });
-    }
-    if (attest.device && claims) attestedDevice = attest.device;
-    attestChallengeOut = attest.nextChallenge;
-    const retryAfter = limiter.check(meta.options?.rateLimit, RateLimiter.key(hit.entry.id, userId, req.headers), Date.now());
-    if (retryAfter !== null) {
-      await settleBeforeRefusal();
-      return new Response(JSON.stringify({
-        error: "too_many_requests",
-        error_description: "Rate limit exceeded for this endpoint",
-        status: 429,
-        request_id: requestId,
-        data: {
-          retryAfter
-        }
-      }), {
-        status: 429,
-        headers: {
-          ...JSON_HEADERS,
-          "retry-after": String(retryAfter)
-        }
-      });
-    }
-    let completionUploadId = null;
-    const args = [];
-    let sseEnqueue = null;
-    let sseSettle = /* @__PURE__ */ __name(async () => {
-    }, "sseSettle");
-    const sseWriter = makeSseWriter({
-      enqueue: /* @__PURE__ */ __name((chunk) => sseEnqueue?.(chunk), "enqueue"),
-      onFirstWrite: /* @__PURE__ */ __name(() => sseSettle(), "onFirstWrite")
-    });
-    for (const p of meta.params ?? []) {
-      switch (p.kind) {
-        case "body": {
-          readParsedBody();
-          const r = p.schema.safeParse(parsedBody);
-          if (!r.success) {
-            await settleBeforeRefusal();
-            return envelope("bad_request", "Request body failed validation", 400, requestId, {
-              data: {
-                fields: fieldErrors(r.error)
-              }
-            });
-          }
-          args[p.index] = r.data;
-          break;
-        }
-        case "query": {
-          const r = p.schema.safeParse(Object.fromEntries(url.searchParams));
-          if (!r.success) {
-            await settleBeforeRefusal();
-            return envelope("bad_request", "Query parameters failed validation", 400, requestId, {
-              data: {
-                fields: fieldErrors(r.error)
-              }
-            });
-          }
-          args[p.index] = r.data;
-          break;
-        }
-        case "param":
-          args[p.index] = hit.params[p.name];
-          break;
-        case "headers": {
-          const raw = Object.fromEntries(req.headers);
-          if (!p.schema) {
-            args[p.index] = raw;
+      for (const p of meta.params ?? []) {
+        switch (p.kind) {
+          case "body": {
+            readParsedBody();
+            const r = p.schema.safeParse(parsedBody);
+            if (!r.success) {
+              await settleBeforeRefusal();
+              return envelope("bad_request", "Request body failed validation", 400, requestId, {
+                data: {
+                  fields: fieldErrors(r.error)
+                }
+              });
+            }
+            args[p.index] = r.data;
             break;
           }
-          const r = p.schema.safeParse(headersFor(raw, p.schema));
-          if (!r.success) {
-            await settleBeforeRefusal();
-            return envelope("bad_request", "Request headers failed validation", 400, requestId, {
-              data: {
-                fields: fieldErrors(r.error)
-              }
-            });
-          }
-          args[p.index] = r.data;
-          break;
-        }
-        case "user":
-        case "optionalUser":
-          args[p.index] = claims ? {
-            id: userId,
-            email: claims.email,
-            role: claims.role,
-            emailVerified: claims.email_verified === true,
-            metadata: claims.metadata ?? {},
-            // The caller's APPLICATION roles, from `auth.user_roles` — the
-            // same resolution the gate used, so the handler cannot read a
-            // different set than the one it was admitted on. Never from a
-            // claim: a revoked role has to bite on the next request, and a
-            // token says only what was true when it was minted.
-            roles: await rolesOfCaller(),
-            // Server-owned and only ever filled from a verdict palauth
-            // returned. Never from a raw header, never from JWT metadata —
-            // the type has said so since it was written and this is the
-            // first writer.
-            device: attestedDevice
-          } : null;
-          break;
-        case "uploadedObject": {
-          if (uploadSecret === "" || !verifySignature(req.headers.get(SIGNATURE_HEADER) ?? "", uploadSecret)) {
-            await settleBeforeRefusal();
-            return envelope("unauthorized", "This endpoint accepts uploads through storage, not directly", 401, requestId);
-          }
-          readParsedBody();
-          const envelopeIn = parsedBody;
-          if (!envelopeIn?.uploadedObject) {
-            await settleBeforeRefusal();
-            return envelope("bad_request", "the completion call carried no uploaded object", 400, requestId);
+          case "query": {
+            const r = p.schema.safeParse(Object.fromEntries(url.searchParams));
+            if (!r.success) {
+              await settleBeforeRefusal();
+              return envelope("bad_request", "Query parameters failed validation", 400, requestId, {
+                data: {
+                  fields: fieldErrors(r.error)
+                }
+              });
+            }
+            args[p.index] = r.data;
+            break;
           }
-          const uploadId = envelopeIn.uploadedObject.uploadId;
-          if (typeof uploadId === "string" && uploadId !== "") {
-            const already = completions.recall(uploadId);
-            if (already) {
+          case "param":
+            args[p.index] = hit.params[p.name];
+            break;
+          case "headers": {
+            const raw = Object.fromEntries(req.headers);
+            if (!p.schema) {
+              args[p.index] = raw;
+              break;
+            }
+            const r = p.schema.safeParse(headersFor(raw, p.schema));
+            if (!r.success) {
               await settleBeforeRefusal();
-              return new Response(already.body, {
-                status: already.status,
-                headers: already.contentType ? {
-                  "content-type": already.contentType
-                } : void 0
+              return envelope("bad_request", "Request headers failed validation", 400, requestId, {
+                data: {
+                  fields: fieldErrors(r.error)
+                }
               });
             }
-            completionUploadId = uploadId;
+            args[p.index] = r.data;
+            break;
           }
-          args[p.index] = envelopeIn.uploadedObject;
-          parsedBody = envelopeIn.body ?? {};
-          break;
+          case "user":
+          case "optionalUser":
+            args[p.index] = claims ? {
+              id: userId,
+              email: claims.email,
+              role: claims.role,
+              emailVerified: claims.email_verified === true,
+              metadata: claims.metadata ?? {},
+              // The caller's APPLICATION roles, from `auth.user_roles` — the
+              // same resolution the gate used, so the handler cannot read a
+              // different set than the one it was admitted on. Never from a
+              // claim: a revoked role has to bite on the next request, and a
+              // token says only what was true when it was minted.
+              roles: await rolesOfCaller(),
+              // Server-owned and only ever filled from a verdict palauth
+              // returned. Never from a raw header, never from JWT metadata —
+              // the type has said so since it was written and this is the
+              // first writer.
+              device: attestedDevice
+            } : null;
+            break;
+          case "uploadedObject": {
+            if (uploadSecret === "" || !verifySignature(req.headers.get(SIGNATURE_HEADER) ?? "", uploadSecret)) {
+              await settleBeforeRefusal();
+              return envelope("unauthorized", "This endpoint accepts uploads through storage, not directly", 401, requestId);
+            }
+            readParsedBody();
+            const envelopeIn = parsedBody;
+            if (!envelopeIn?.uploadedObject) {
+              await settleBeforeRefusal();
+              return envelope("bad_request", "the completion call carried no uploaded object", 400, requestId);
+            }
+            const uploadId = envelopeIn.uploadedObject.uploadId;
+            if (typeof uploadId === "string" && uploadId !== "") {
+              const already = completions.recall(uploadId);
+              if (already) {
+                await settleBeforeRefusal();
+                return new Response(already.body, {
+                  status: already.status,
+                  headers: already.contentType ? {
+                    "content-type": already.contentType
+                  } : void 0
+                });
+              }
+              completionUploadId = uploadId;
+            }
+            args[p.index] = envelopeIn.uploadedObject;
+            parsedBody = envelopeIn.body ?? {};
+            break;
+          }
+          case "requestId":
+            args[p.index] = requestId;
+            break;
+          case "traceId":
+            args[p.index] = requestId;
+            break;
+          case "client":
+            args[p.index] = {
+              sdkVersion: req.headers.get("x-palbase-sdk-version"),
+              appVersion: req.headers.get("x-palbase-client-version"),
+              platform: req.headers.get("x-platform"),
+              osVersion: req.headers.get("x-os-version")
+            };
+            break;
+          case "req":
+            args[p.index] = req;
+            break;
+          // `@Signal()` — the raw request's AbortSignal, which enters the aborted
+          // state when the client disconnects. Measured on Bun: an infinite
+          // producer guarded by it stops within a few frames of the client dying.
+          // It is deliberately NOT reachable through `@Req()`: PBRequest carries
+          // request-scoped data and no signal.
+          case "signal":
+            args[p.index] = req.signal;
+            break;
+          // `@SseOut()` — the frame writer. Meaningful only on an `@Sse` route;
+          // on any other route it is an inert writer whose frames go nowhere,
+          // which is the same shape `@UploadedObject()` has off an `@Upload`
+          // route.
+          case "sseOut":
+            args[p.index] = sseWriter;
+            break;
+          default:
+            args[p.index] = void 0;
         }
-        case "requestId":
-          args[p.index] = requestId;
-          break;
-        case "traceId":
-          args[p.index] = requestId;
-          break;
-        case "client":
-          args[p.index] = {
-            sdkVersion: req.headers.get("x-palbase-sdk-version"),
-            appVersion: req.headers.get("x-palbase-client-version"),
-            platform: req.headers.get("x-platform"),
-            osVersion: req.headers.get("x-os-version")
-          };
-          break;
-        case "req":
-          args[p.index] = req;
-          break;
-        // `@Signal()` — the raw request's AbortSignal, which enters the aborted
-        // state when the client disconnects. Measured on Bun: an infinite
-        // producer guarded by it stops within a few frames of the client dying.
-        // It is deliberately NOT reachable through `@Req()`: PBRequest carries
-        // request-scoped data and no signal.
-        case "signal":
-          args[p.index] = req.signal;
-          break;
-        // `@SseOut()` — the frame writer. Meaningful only on an `@Sse` route;
-        // on any other route it is an inert writer whose frames go nowhere,
-        // which is the same shape `@UploadedObject()` has off an `@Upload`
-        // route.
-        case "sseOut":
-          args[p.index] = sseWriter;
-          break;
-        default:
-          args[p.index] = void 0;
       }
-    }
-    dispatched = true;
-    try {
+      db.authorizationComplete?.();
+      dispatched = true;
       const services = buildServices(db);
       if (meta.options?.sseConfig !== void 0) {
         let sseController;
@@ -7132,11 +7190,19 @@ async function createApp(opts) {
           } catch {
           }
         }, "sseEnqueue");
-        let sawFirstFrame;
-        const firstFrame = new Promise((r) => sawFirstFrame = r);
+        let sawFirstFrame, refuseFirstFrame;
+        const firstFrame = new Promise((resolve, reject) => {
+          sawFirstFrame = resolve;
+          refuseFirstFrame = reject;
+        });
         sseSettle = /* @__PURE__ */ __name(async () => {
-          await db.commit();
-          sawFirstFrame();
+          try {
+            await db.commit();
+            sawFirstFrame();
+          } catch (error) {
+            refuseFirstFrame(error);
+            throw error;
+          }
         }, "sseSettle");
         const guarded = {
           ...services,
@@ -7177,6 +7243,7 @@ async function createApp(opts) {
             status: 204
           });
         }
+        await firstFrame;
         void (async () => {
           await ran;
           await sseWriter.drained();
@@ -7210,15 +7277,16 @@ async function createApp(opts) {
         }
         return method.apply(hit.entry.instance, args);
       });
-      await db.commit();
       if (meta.returnSchema) {
         const v = meta.returnSchema.safeParse(result);
         if (!v.success) {
           log.error(`[engine] ${hit.entry.id} returned a value its declared type rejects`, v.error.issues);
+          await db.rollback(new Error("output_invalid"));
           return envelope("output_invalid", "The handler returned a value its declared return type rejects", 500, requestId);
         }
       }
-      if (result === void 0 || result === null) {
+      if (result === void 0 || result === null && !meta.returnSchema) {
+        await db.commit();
         if (completionUploadId) {
           completions.remember(completionUploadId, {
             status: 204,
@@ -7231,6 +7299,7 @@ async function createApp(opts) {
         });
       }
       const payload = JSON.stringify(result);
+      await db.commit();
       if (completionUploadId) {
         completions.remember(completionUploadId, {
           status: 200,
@@ -7247,16 +7316,7 @@ async function createApp(opts) {
       });
     } catch (err) {
       await db.rollback(err);
-      if (isHttpError(err)) {
-        if (isEngineRaised(err) || !AUTHOR_ANSWERED.has(err.status)) {
-          log.error(`[engine] unhandled ${err.error} in ${hit.entry.id}`, err);
-        }
-        return envelope(err.error, err.errorDescription, err.status, requestId, err.data !== void 0 ? {
-          data: err.data
-        } : void 0);
-      }
-      log.error(`[engine] unhandled error in ${hit.entry.id}`, err);
-      return envelope("internal_error", "The request could not be completed", 500, requestId);
+      return errorResponse(err, hit.entry.id, requestId);
     }
   }
   __name(handle, "handle");
@@ -7269,15 +7329,24 @@ async function createApp(opts) {
     throw err;
   }
   return {
-    handle,
+    handle: /* @__PURE__ */ __name((req) => !accepting ? Promise.resolve(envelope("runtime_draining", "This application is shutting down", 503, `req_${crypto.randomUUID()}`)) : serving(() => handle(req)), "handle"),
+    get databasePressure() {
+      return admission.snapshot;
+    },
     routes,
     config,
     container: liveContainer,
-    runInServiceScope,
-    async shutdown() {
-      await runShutdownHooks();
-      await closeDriver(sql);
-      released = true;
+    runInServiceScope: /* @__PURE__ */ __name((fn) => !accepting ? Promise.reject(new Error("This application is shutting down; no new database scope can start")) : serving(() => runInServiceScope(fn)), "runInServiceScope"),
+    shutdown() {
+      accepting = false;
+      return shuttingDown ??= (async () => {
+        while (inFlight.size) await Promise.allSettled([
+          ...inFlight
+        ]);
+        await runShutdownHooks();
+        await closeDriver(sql);
+        released = true;
+      })();
     }
   };
 }