@palbase/backend 17.3.0 → 18.0.0

package/dist/engine/index.cjs

@@ -0,0 +1,1797 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/engine/index.ts
+var engine_exports = {};
+__export(engine_exports, {
+  AuthVerifier: () => AuthVerifier,
+  BootRefused: () => BootRefused,
+  RateLimiter: () => RateLimiter,
+  buildRouteTable: () => buildRouteTable,
+  createApp: () => createApp,
+  createLazyTransaction: () => createLazyTransaction,
+  createOps: () => createOps,
+  createRequestDatabase: () => createRequestDatabase,
+  effectiveAuth: () => effectiveAuth,
+  hostAllowed: () => hostAllowed,
+  installEgressFence: () => installEgressFence,
+  loadConfig: () => loadConfig,
+  makeMemoryCache: () => makeMemoryCache,
+  matchRoute: () => matchRoute,
+  quoteIdent: () => quoteIdent,
+  scrubSecrets: () => scrubSecrets,
+  withTables: () => withTables
+});
+module.exports = __toCommonJS(engine_exports);
+
+// src/runtime.ts
+var import_node_async_hooks = require("async_hooks");
+
+// src/db/tx-plan.ts
+var TxRefError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TxRefError";
+  }
+};
+var TxPlanError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TxPlanError";
+  }
+};
+var EXPR = /* @__PURE__ */ Symbol.for("palbase.tx.expr");
+var REF = /* @__PURE__ */ Symbol.for("palbase.tx.ref");
+var ROW = /* @__PURE__ */ Symbol.for("palbase.tx.row");
+var ROWS = /* @__PURE__ */ Symbol.for("palbase.tx.rows");
+var TRAPPED_PROPS = [
+  "then",
+  "valueOf",
+  "toString",
+  "toJSON",
+  Symbol.toPrimitive
+];
+function trap(prop, what, hint) {
+  const name = typeof prop === "symbol" ? prop.description ?? String(prop) : prop;
+  throw new TxRefError(
+    `${what} was used as a value (via \`${name}\`). Nothing in a transaction callback has run yet, so there is no value to read. ${hint}`
+  );
+}
+function makeRef(op, field) {
+  const target = { [REF]: { op, field } };
+  return new Proxy(target, {
+    get(t, prop) {
+      if (prop === REF) return t[REF];
+      if (TRAPPED_PROPS.includes(prop)) {
+        trap(
+          prop,
+          `\`${field}\` of a row this transaction has not written yet`,
+          "Pass it to another operation in the same plan, or return it from the callback and read it after `transaction()` resolves."
+        );
+      }
+      return void 0;
+    }
+  });
+}
+function makeRowHandle(op) {
+  const target = { [ROW]: op };
+  return new Proxy(target, {
+    get(t, prop) {
+      if (prop === ROW) return t[ROW];
+      if (TRAPPED_PROPS.includes(prop)) {
+        trap(
+          prop,
+          "A row this transaction has not written yet",
+          "Read one of its columns to reference it, or return the row from the callback and read it after `transaction()` resolves."
+        );
+      }
+      if (typeof prop === "symbol") return void 0;
+      return makeRef(op, prop);
+    }
+  });
+}
+function refDescriptor(v) {
+  if (typeof v !== "object" || v === null) return null;
+  const d = v[REF];
+  return isRefDescriptor(d) ? d : null;
+}
+function isRefDescriptor(d) {
+  return typeof d === "object" && d !== null && typeof d.op === "number" && typeof d.field === "string";
+}
+function rowOpIndex(v) {
+  if (typeof v !== "object" || v === null) return null;
+  const op = v[ROW];
+  return typeof op === "number" ? op : null;
+}
+function exprOf(v) {
+  if (typeof v !== "object" || v === null) return null;
+  const e = v[EXPR];
+  return typeof e === "object" && e !== null ? e : null;
+}
+function isRowsHandle(v) {
+  return typeof v === "object" && v !== null && v[ROWS] !== void 0;
+}
+function encodeValue(value, column, allowColumnExpr) {
+  const ref = refDescriptor(value);
+  if (ref) return { $ref: { op: ref.op, field: ref.field } };
+  const expr = exprOf(value);
+  if (expr) {
+    if (expr.fn !== "now" && !allowColumnExpr) {
+      throw new TxPlanError(
+        `\`${column}\`: ${expr.fn}() reads the column's current value, so it is only valid in updateWhere(where, set).`
+      );
+    }
+    return { $expr: expr };
+  }
+  if (rowOpIndex(value) !== null) {
+    throw new TxPlanError(
+      `\`${column}\`: a row handle is not a value. Read the column you meant (e.g. \`row.id\`).`
+    );
+  }
+  if (isRowsHandle(value)) {
+    throw new TxPlanError(
+      `\`${column}\`: an operation result is not a value. Declare an expectation first (\`.expectOne(err)\`) and read a column from the row.`
+    );
+  }
+  assertNoNestedHandles(value, column);
+  return value;
+}
+function assertNoNestedHandles(value, column) {
+  if (typeof value !== "object" || value === null) return;
+  if (value instanceof Date) return;
+  if (refDescriptor(value) || exprOf(value) || rowOpIndex(value) !== null || isRowsHandle(value)) {
+    throw new TxPlanError(
+      `\`${column}\`: a plan handle is nested inside a value. The server would store it as literal JSON, not resolve it. Put the reference directly in the column.`
+    );
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) assertNoNestedHandles(item, column);
+    return;
+  }
+  for (const item of Object.values(value)) {
+    assertNoNestedHandles(item, column);
+  }
+}
+function encodeMap(map, allowColumnExpr) {
+  const out = {};
+  for (const key of Object.keys(map).sort()) {
+    const value = map[key];
+    if (value === void 0) continue;
+    out[key] = encodeValue(value, key, allowColumnExpr);
+  }
+  return out;
+}
+var SKIPPED_OP = -1;
+var TxRowsImpl = class {
+  constructor(builder, opIndex, what) {
+    this.builder = builder;
+    this.opIndex = opIndex;
+    this.what = what;
+  }
+  builder;
+  opIndex;
+  what;
+  // Present so `isRowsHandle` recognises the object; never read for its value.
+  [ROWS] = true;
+  guarded = false;
+  // The type-level `await` guard made real: TS rejects `await rows` at compile
+  // time, and reaching this means someone called `.then(...)` by hand.
+  then() {
+    throw new TxRefError(
+      `${this.what} cannot be awaited: a transaction callback builds a plan, it does not run statements. Remove the \`await\`.`
+    );
+  }
+  expectOne(error) {
+    this.declareGuard("one", 1, error);
+    if (this.opIndex === SKIPPED_OP) throw error;
+    return makeRowHandle(this.opIndex);
+  }
+  expectNone(error) {
+    this.declareGuard("none", 0, error);
+  }
+  expectAtLeast(n, error) {
+    assertGuardCount(n, "expectAtLeast");
+    this.declareGuard("atLeast", n, error);
+    if (this.opIndex === SKIPPED_OP && n > 0) throw error;
+  }
+  expectAtMost(n, error) {
+    assertGuardCount(n, "expectAtMost");
+    this.declareGuard("atMost", n, error);
+  }
+  declareGuard(kind, n, error) {
+    if (!(error instanceof Error)) {
+      throw new TxPlanError(
+        `${this.what}: an expectation needs the Error to throw when it does not hold (e.g. \`.expect\u2026(new Conflict("already accepted"))\`).`
+      );
+    }
+    if (this.guarded) {
+      throw new TxPlanError(
+        `${this.what} already has an expectation. One operation carries one expectation; declare the second one on its own operation.`
+      );
+    }
+    this.guarded = true;
+    if (this.opIndex === SKIPPED_OP) return;
+    this.builder.attachGuard(this.opIndex, kind, n, error);
+  }
+};
+function assertGuardCount(n, fn) {
+  if (!Number.isInteger(n) || n < 0) {
+    throw new TxPlanError(`${fn}(n) needs a non-negative integer, got ${String(n)}`);
+  }
+}
+var MAX_OPS = 1e3;
+var MAX_ROWS = 5e3;
+var TxPlanBuilder = class {
+  ops = [];
+  /** Errors handed to expectations, indexed by the `slot` the server echoes. */
+  slots = [];
+  /** The table surface handed to the callback. Untyped here; the public
+   * `transaction()` signatures put the schema types on top. */
+  table(name) {
+    return {
+      insert: (values) => {
+        const encoded = encodeMap(values, false);
+        if (Object.keys(encoded).length === 0) {
+          throw new TxPlanError(`${name}.insert() needs at least one column`);
+        }
+        return this.push({ op: "insert", table: name, values: encoded }, `${name}.insert()`);
+      },
+      insertMany: (rows) => {
+        if (rows.length === 0) {
+          return new TxRowsImpl(this, SKIPPED_OP, `${name}.insertMany()`);
+        }
+        if (rows.length > MAX_ROWS) {
+          throw new TxPlanError(
+            `${name}.insertMany() has ${rows.length} rows; the limit is ${MAX_ROWS}. Split the write across requests.`
+          );
+        }
+        const encoded = rows.map((row) => encodeMap(row, false));
+        assertUniformRows(encoded, name);
+        return this.push({ op: "insertMany", table: name, rows: encoded }, `${name}.insertMany()`);
+      },
+      updateWhere: (where, set) => {
+        const encodedWhere = encodeMap(where, false);
+        const encodedSet = encodeMap(set, true);
+        if (Object.keys(encodedWhere).length === 0) {
+          throw new TxPlanError(
+            `${name}.updateWhere() needs a filter. An update with no filter rewrites the whole table.`
+          );
+        }
+        if (Object.keys(encodedSet).length === 0) {
+          throw new TxPlanError(`${name}.updateWhere() needs at least one column to set`);
+        }
+        return this.push(
+          { op: "update", table: name, set: encodedSet, where: encodedWhere },
+          `${name}.updateWhere()`
+        );
+      },
+      deleteWhere: (where) => {
+        const encodedWhere = encodeMap(where, false);
+        if (Object.keys(encodedWhere).length === 0) {
+          throw new TxPlanError(
+            `${name}.deleteWhere() needs a filter. A delete with no filter empties the table.`
+          );
+        }
+        return this.push(
+          { op: "delete", table: name, where: encodedWhere },
+          `${name}.deleteWhere()`
+        );
+      },
+      select: (where, options) => {
+        const op = { op: "select", table: name };
+        const encodedWhere = encodeMap(where ?? {}, false);
+        if (Object.keys(encodedWhere).length > 0) op.where = encodedWhere;
+        if (options?.limit !== void 0) {
+          if (!Number.isInteger(options.limit) || options.limit < 0) {
+            throw new TxPlanError(
+              `${name}.select(): limit needs a non-negative integer, got ${String(options.limit)}`
+            );
+          }
+          op.limit = options.limit;
+        }
+        if (options?.lock !== void 0) op.lock = options.lock;
+        return this.push(op, `${name}.select()`);
+      }
+    };
+  }
+  push(op, what) {
+    if (this.ops.length >= MAX_OPS) {
+      throw new TxPlanError(
+        `this transaction has ${MAX_OPS} operations, which is the limit. Use insertMany() for bulk writes, or split the work across requests.`
+      );
+    }
+    const index = this.ops.length;
+    this.ops.push(op);
+    return new TxRowsImpl(this, index, what);
+  }
+  /** Attach an expectation to an op and record its error in the slot table. */
+  attachGuard(opIndex, kind, n, error) {
+    const op = this.ops[opIndex];
+    if (!op) throw new TxPlanError(`internal: expectation on unknown operation ${opIndex}`);
+    const slot = this.slots.length;
+    this.slots.push(error);
+    op.guard = { kind, n, slot };
+  }
+  /** The serialisable plan. Empty when the callback described no writes. */
+  body() {
+    return { ops: this.ops };
+  }
+  /** The error the server's `slot` selects, or `null` when it names one this
+   * plan never declared (a server/client disagreement, not a tenant error). */
+  errorForSlot(slot) {
+    return this.slots[slot] ?? null;
+  }
+};
+function assertUniformRows(rows, table) {
+  const first = rows[0];
+  if (!first) return;
+  const want = Object.keys(first);
+  const wantKey = want.join(",");
+  for (let i = 1; i < rows.length; i++) {
+    const got = Object.keys(rows[i]);
+    if (got.join(",") !== wantKey) {
+      throw new TxPlanError(
+        `${table}.insertMany(): every row must set the same columns. Row 0 sets [${want.join(", ")}] but row ${i} sets [${got.join(", ")}]. (A property set to \`undefined\` counts as absent \u2014 use \`null\`.)`
+      );
+    }
+  }
+}
+function materializeResult(value, results) {
+  const ref = refDescriptor(value);
+  if (ref) {
+    const row = rowOf(results, ref.op, `\`${ref.field}\``);
+    if (!(ref.field in row)) {
+      throw new TxPlanError(
+        `the transaction's operation ${ref.op} returned no column \`${ref.field}\`.`
+      );
+    }
+    return row[ref.field];
+  }
+  const rowOp = rowOpIndex(value);
+  if (rowOp !== null) return rowOf(results, rowOp, "a row");
+  if (isRowsHandle(value)) {
+    throw new TxPlanError(
+      "an operation result cannot be returned from a transaction callback: its row count is not known until the plan runs. Declare an expectation (`.expectOne(err)`) and return the row, or a column of it."
+    );
+  }
+  if (Array.isArray(value)) return value.map((item) => materializeResult(item, results));
+  if (isPlainObject(value)) {
+    const out = {};
+    for (const [key, item] of Object.entries(value)) out[key] = materializeResult(item, results);
+    return out;
+  }
+  return value;
+}
+function rowOf(results, opIndex, what) {
+  const result = results[opIndex];
+  if (!result) {
+    throw new TxPlanError(
+      `the transaction returned no result for operation ${opIndex}, so ${what} cannot be read.`
+    );
+  }
+  const row = result.rows[0];
+  if (!row) {
+    throw new TxPlanError(
+      `the transaction's operation ${opIndex} returned no row, so ${what} cannot be read.`
+    );
+  }
+  return row;
+}
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+async function runTxPlan(transport, tables, builder, fn) {
+  const returned = fn({ tables });
+  const body = builder.body();
+  if (body.ops.length === 0) {
+    return materializeResult(returned, []);
+  }
+  let response;
+  try {
+    response = await transport.txPlan(body);
+  } catch (err) {
+    throw translateRejection(err, builder);
+  }
+  return materializeResult(returned, response.results);
+}
+function translateRejection(err, builder) {
+  if (typeof err !== "object" || err === null) return err;
+  const rejection = err;
+  if (rejection.error_code !== "tx_guard_failed" || typeof rejection.slot !== "number") {
+    return err;
+  }
+  return builder.errorForSlot(rejection.slot) ?? err;
+}
+
+// src/runtime.ts
+var __requestALS = new import_node_async_hooks.AsyncLocalStorage();
+var runtime = null;
+function __runWithRuntime(services, fn) {
+  return __requestALS.run({ runtime: services }, fn);
+}
+function __getRuntime() {
+  const scoped = __requestALS.getStore();
+  if (scoped) return scoped.runtime;
+  if (runtime === null) {
+    throw new Error(
+      "Palbase services accessed outside a request scope. The Database/Documents/\u2026 singletons are only available inside an endpoint handler (or after the runtime has called __runWithRuntime / __setRuntime)."
+    );
+  }
+  return runtime;
+}
+function makeServiceProxy(key) {
+  const handler = {
+    get(_target, prop, receiver) {
+      const client = __getRuntime()[key];
+      const value = Reflect.get(client, prop, receiver);
+      return typeof value === "function" ? value.bind(client) : value;
+    }
+  };
+  return new Proxy({}, handler);
+}
+function makeTablesAccessor(ops) {
+  const tablesProxy = new Proxy(
+    {},
+    {
+      get(_t, prop) {
+        if (typeof prop !== "string") return void 0;
+        const name = prop;
+        return {
+          insert: (data) => ops().insert(name, data),
+          update: (id, data) => ops().update(name, id, data),
+          delete: (id) => ops().delete(name, id),
+          findById: (id) => ops().findById(name, id),
+          findMany: (query) => ops().findMany(name, query)
+        };
+      }
+    }
+  );
+  return tablesProxy;
+}
+var rawDatabase = makeServiceProxy("Database");
+function makeTypedSurface(raw) {
+  const ops = {
+    query: (sql, params) => raw.query(sql, params),
+    insert: (table, data) => raw.insert(table, data),
+    update: (table, id, data) => raw.update(table, id, data),
+    delete: (table, id) => raw.delete(table, id),
+    findById: (table, id) => raw.findById(table, id),
+    findMany: (table, query) => raw.findMany(table, query)
+  };
+  return Object.assign(ops, {
+    tables: makeTablesAccessor(() => raw),
+    transaction(fn) {
+      const builder = new TxPlanBuilder();
+      return runTxPlan(raw, makeTxTablesAccessor(builder), builder, fn);
+    }
+  });
+}
+function makeTxTablesAccessor(builder) {
+  const tablesProxy = new Proxy(
+    {},
+    {
+      get(_t, prop) {
+        if (typeof prop !== "string") return void 0;
+        return builder.table(prop);
+      }
+    }
+  );
+  return tablesProxy;
+}
+var Database = Object.assign(makeTypedSurface(rawDatabase), {
+  /**
+   * Lazily resolve the runtime's service-role sibling on each call. We do NOT
+   * cache it: `rawDatabase.asService()` reads the CURRENT request scope through
+   * the runtime proxy, and the per-request runtime injects a service client
+   * bound to that request's identity headers — caching would leak one request's
+   * sibling into another concurrent request.
+   */
+  asService() {
+    return makeTypedSurface(rawDatabase.asService());
+  }
+});
+var Documents = makeServiceProxy("Documents");
+function makeBucketsAccessor(storage) {
+  return new Proxy(
+    {},
+    {
+      get(_t, prop) {
+        if (typeof prop !== "string") return void 0;
+        return storage().bucket(prop);
+      }
+    }
+  );
+}
+var rawStorage = makeServiceProxy("Storage");
+var Storage = Object.assign(
+  {
+    // FORWARDED explicitly, not assigned onto the service proxy.
+    //
+    // `Object.assign(rawStorage, {buckets})` writes onto the proxy's TARGET, and
+    // the proxy's only trap is `get`, which forwards every read to the module
+    // client — so the property landed somewhere nothing reads and
+    // `Storage.buckets.docs` was `undefined` in a deployed handler. It
+    // typechecked, every test passed, and the live call answered
+    // "TypeError: undefined is not an object". `Database` never had the bug
+    // because it builds a plain surface the same way this now does.
+    bucket: (name) => rawStorage.bucket(name)
+  },
+  { buckets: makeBucketsAccessor(() => rawStorage) }
+);
+var Cache = makeServiceProxy("Cache");
+var Secrets = makeServiceProxy("Secrets");
+var Log = makeServiceProxy("Log");
+var Notifications = makeServiceProxy("Notifications");
+var Purchases = makeServiceProxy("Purchases");
+var rawFlags = makeServiceProxy("Flags");
+var Flags = Object.assign(
+  {
+    isEnabled(flagName, context) {
+      return rawFlags.isEnabled(flagName, context);
+    },
+    getVariant(flagName, context) {
+      return rawFlags.getVariant(flagName, context);
+    },
+    getAll(context) {
+      return rawFlags.getAll(context);
+    },
+    /**
+     * Resolve a flag's value, with an optional fallback.
+     *
+     * FORWARDED as of 2026-08-15. This surface is written out by hand, method
+     * by method, and `get` was missing from it — so the client implemented it,
+     * thirty assertions covered it, and `Flags.get("x")` was `undefined` in a
+     * deployed handler. Exactly the shape of the `Storage.buckets` defect found
+     * the same day: a hand-maintained forwarding list is a list somebody has to
+     * remember to update.
+     */
+    get(flagName, defaultOrContext, maybeContext) {
+      return rawFlags.get(flagName, defaultOrContext, maybeContext);
+    },
+    setOverride(key, value) {
+      return rawFlags.setOverride(key, value);
+    }
+  },
+  {
+    /**
+     * Lazily resolve the runtime's cross-user sibling on each call. We do NOT
+     * cache it: `rawFlags.asService()` reads the CURRENT request scope through
+     * the runtime proxy, so caching would leak one request's sibling into
+     * another concurrent request. Mirrors `Database.asService()`.
+     */
+    asService() {
+      return rawFlags.asService();
+    }
+  }
+);
+var Realtime = makeServiceProxy("Realtime");
+
+// src/errors.ts
+var HTTP_ERROR_BRAND = /* @__PURE__ */ Symbol.for("palbase.backend.httpError");
+function isHttpError(err) {
+  if (typeof err !== "object" || err === null) return false;
+  const e = err;
+  return e[HTTP_ERROR_BRAND] === true && typeof e.status === "number" && typeof e.error === "string" && typeof e.errorDescription === "string";
+}
+var HttpError = class extends Error {
+  status;
+  error;
+  errorDescription;
+  data;
+  /** See {@link HTTP_ERROR_BRAND} — how the engine recognises this across SDK copies. */
+  [HTTP_ERROR_BRAND] = true;
+  constructor(status, error, errorDescription, data) {
+    super(errorDescription);
+    this.name = "HttpError";
+    this.status = status;
+    this.error = error;
+    this.errorDescription = errorDescription;
+    if (data !== void 0) {
+      this.data = data;
+    }
+  }
+  /**
+   * Serialize to the standard Palbase error response format.
+   * The `requestId` is injected by the runtime layer from the request context.
+   * When called without arguments (e.g. JSON.stringify), request_id is omitted.
+   * When `data` is set, it is appended as a strict-superset field.
+   */
+  toJSON(requestId) {
+    const result = {
+      error: this.error,
+      error_description: this.errorDescription,
+      status: this.status
+    };
+    if (requestId) {
+      result.request_id = requestId;
+    }
+    if (this.data !== void 0) {
+      result.data = this.data;
+    }
+    return result;
+  }
+};
+
+// src/engine/config.ts
+var BootRefused = class extends Error {
+  missing;
+  constructor(missing, message) {
+    super(message);
+    this.name = "BootRefused";
+    this.missing = missing;
+  }
+};
+var MANDATORY = [
+  { key: "DATABASE_URL", what: "the stack's Postgres (Database module)" },
+  { key: "AUTH_JWKS_URL", what: "where this stack publishes its token signing keys (Auth module)" }
+];
+function loadConfig(env) {
+  const missing = MANDATORY.filter((m) => !env[m.key]?.trim()).map((m) => m.key);
+  if (missing.length > 0) {
+    const detail = MANDATORY.filter((m) => missing.includes(m.key)).map((m) => `  ${m.key.padEnd(16)}${m.what}`).join("\n");
+    throw new BootRefused(
+      missing,
+      `boot refused: mandatory module not configured \u2014 missing ${missing.join(", ")}.
+${detail}`
+    );
+  }
+  const port = Number(env.PORT ?? 3e3);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new BootRefused([], `boot refused: PORT is not a valid port number (got ${env.PORT}).`);
+  }
+  const poolMax = Number(env.DB_POOL_MAX ?? 10);
+  if (!Number.isInteger(poolMax) || poolMax < 1) {
+    throw new BootRefused([], `boot refused: DB_POOL_MAX must be a positive integer (got ${env.DB_POOL_MAX}).`);
+  }
+  return {
+    databaseUrl: env.DATABASE_URL.trim(),
+    authJwksUrl: env.AUTH_JWKS_URL.trim(),
+    authIssuer: env.AUTH_ISSUER?.trim() || void 0,
+    moduleBaseUrl: (env.MODULE_BASE_URL ?? "").replace(/\/+$/, ""),
+    // The secret storage signs its two internal calls with (authorize, and the
+    // completion that runs an @Upload handler). Empty means uploads are not
+    // wired, and both calls REFUSE — an unsigned completion would let anyone
+    // who knows a route path invent an upload that never happened.
+    uploadSecret: env.PALBASE_UPLOAD_SECRET ?? "",
+    anonKey: env.PALBASE_ANON_KEY ?? "",
+    serviceRoleKey: env.PALBASE_SERVICE_ROLE_KEY ?? "",
+    realtimeSecret: env.REALTIME_INGESTION_SECRET ?? "",
+    port,
+    dbRole: env.DB_ROLE ?? "backend_authenticated",
+    // Verified against the stack that provisions them, not from memory: the six
+    // roles and their attributes are declared in v2/internal/migrate/provision.go
+    // (`roleBackendServiceRole = "backend_service_role"`, NOLOGIN BYPASSRLS),
+    // and the live database agrees (pg_roles.rolbypassrls = true).
+    dbServiceRole: env.DB_SERVICE_ROLE ?? "backend_service_role",
+    poolMax
+  };
+}
+
+// src/engine/auth.ts
+function b64urlToBytes(s) {
+  const pad = s.replace(/-/g, "+").replace(/_/g, "/");
+  const full = pad.padEnd(Math.ceil(pad.length / 4) * 4, "=");
+  const bin = atob(full);
+  const out = new Uint8Array(new ArrayBuffer(bin.length));
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+var AuthVerifier = class {
+  keys = /* @__PURE__ */ new Map();
+  fetchedAt = 0;
+  inflight = null;
+  jwksUrl;
+  issuer;
+  fetchImpl;
+  ttl;
+  constructor(opts) {
+    this.jwksUrl = opts.jwksUrl;
+    this.issuer = opts.issuer;
+    this.fetchImpl = opts.fetchImpl ?? ((...a) => fetch(...a));
+    this.ttl = opts.keysetTtlMs ?? 5 * 6e4;
+  }
+  /** Fetch the keyset at most once per TTL, and at most once concurrently. */
+  async refresh() {
+    if (this.inflight) return this.inflight;
+    this.inflight = (async () => {
+      try {
+        const res = await this.fetchImpl(this.jwksUrl);
+        if (!res.ok) return;
+        const body = await res.json();
+        const next = /* @__PURE__ */ new Map();
+        for (const jwk of body.keys ?? []) {
+          if (jwk.kty !== "EC" || jwk.crv !== "P-256") continue;
+          try {
+            next.set(
+              jwk.kid,
+              await crypto.subtle.importKey(
+                "jwk",
+                { kty: "EC", crv: jwk.crv, x: jwk.x, y: jwk.y, ext: true },
+                { name: "ECDSA", namedCurve: "P-256" },
+                true,
+                ["verify"]
+              )
+            );
+          } catch {
+          }
+        }
+        if (next.size > 0) {
+          this.keys = next;
+          this.fetchedAt = Date.now();
+        }
+      } finally {
+        this.inflight = null;
+      }
+    })();
+    return this.inflight;
+  }
+  async key(kid) {
+    const stale = Date.now() - this.fetchedAt > this.ttl;
+    if (!this.keys.has(kid) || stale) await this.refresh();
+    return this.keys.get(kid) ?? null;
+  }
+  /**
+   * Verify an `Authorization` header value.
+   *
+   * @returns the verified claims, or `null` for absent / malformed / expired /
+   *   wrong-issuer / bad-signature. One `null` for every failure on purpose:
+   *   the caller answers 401 either way, and a detailed reason is an oracle.
+   */
+  async verify(authorization) {
+    if (!authorization || !authorization.startsWith("Bearer ")) return null;
+    const parts = authorization.slice(7).trim().split(".");
+    if (parts.length !== 3) return null;
+    const h = parts[0];
+    const p = parts[1];
+    const sig = parts[2];
+    if (h === void 0 || p === void 0 || sig === void 0) return null;
+    let header;
+    let claims;
+    try {
+      header = JSON.parse(new TextDecoder().decode(b64urlToBytes(h)));
+      claims = JSON.parse(new TextDecoder().decode(b64urlToBytes(p)));
+    } catch {
+      return null;
+    }
+    if (header.alg !== "ES256" || !header.kid) return null;
+    const key = await this.key(header.kid);
+    if (!key) return null;
+    let ok = false;
+    try {
+      ok = await crypto.subtle.verify(
+        { name: "ECDSA", hash: "SHA-256" },
+        key,
+        b64urlToBytes(sig),
+        new TextEncoder().encode(`${h}.${p}`)
+      );
+    } catch {
+      return null;
+    }
+    if (!ok) return null;
+    if (typeof claims.exp === "number" && claims.exp * 1e3 <= Date.now()) return null;
+    if (this.issuer && claims.iss !== this.issuer) return null;
+    return claims;
+  }
+};
+function effectiveAuth(routeAuth, controllerAuth) {
+  const spec = routeAuth !== void 0 ? routeAuth : controllerAuth;
+  if (spec === false) return { required: false, verifiedEmail: false };
+  if (spec === true || spec === void 0 || spec === null) return { required: true, verifiedEmail: false };
+  if (typeof spec !== "object") return { required: true, verifiedEmail: false };
+  const o = spec;
+  const role = typeof o.role === "string" && o.role.trim() !== "" ? o.role.trim() : void 0;
+  return {
+    required: o.required !== false,
+    role,
+    verifiedEmail: o.verifiedEmail === true
+  };
+}
+
+// src/engine/ratelimit.ts
+var RateLimiter = class {
+  /** Bound on distinct keys held, so an attacker cycling identities cannot
+   * grow this map without limit. On overflow the oldest windows are dropped —
+   * forgiving, consistent with the restart behaviour above. */
+  constructor(maxKeys = 1e5) {
+    this.maxKeys = maxKeys;
+  }
+  maxKeys;
+  buckets = /* @__PURE__ */ new Map();
+  /**
+   * Identify the caller: the signed-in user when the route resolved one,
+   * otherwise the address the edge forwarded. Callers the edge did not
+   * identify share one bucket — deliberately conservative, since the
+   * alternative is a limit anyone resets by omitting a header.
+   */
+  static key(routeId, userId, headers) {
+    if (userId) return `${routeId}\0u:${userId}`;
+    const fwd = headers.get("x-forwarded-for");
+    const addr = (fwd ? fwd.split(",")[0] ?? "" : headers.get("x-real-ip") ?? "").trim();
+    return `${routeId}\0a:${addr || "anonymous"}`;
+  }
+  /**
+   * @returns `null` when the request may proceed, or the number of seconds to
+   *   wait (never 0 — a caller told to wait 0 comes straight back to the same
+   *   refusal).
+   */
+  check(rule, key, now) {
+    if (!rule || !(rule.max > 0) || !(rule.window > 0)) return null;
+    const bucket = this.buckets.get(key);
+    if (!bucket || now >= bucket.resetAt) {
+      if (this.buckets.size >= this.maxKeys) this.evict(now);
+      this.buckets.set(key, { count: 1, resetAt: now + rule.window * 1e3 });
+      return null;
+    }
+    if (bucket.count < rule.max) {
+      bucket.count++;
+      return null;
+    }
+    return Math.max(1, Math.ceil((bucket.resetAt - now) / 1e3));
+  }
+  /** Drop expired windows; if none are expired, drop the earliest-resetting
+   * quarter so the map cannot wedge at the ceiling. */
+  evict(now) {
+    let dropped = 0;
+    for (const [k, b] of this.buckets) {
+      if (now >= b.resetAt) {
+        this.buckets.delete(k);
+        dropped++;
+      }
+    }
+    if (dropped > 0) return;
+    const byReset = [...this.buckets.entries()].sort((a, b) => a[1].resetAt - b[1].resetAt);
+    for (let i = 0; i < Math.ceil(byReset.length / 4); i++) {
+      const victim = byReset[i];
+      if (victim) this.buckets.delete(victim[0]);
+    }
+  }
+  /** Test seam. */
+  get size() {
+    return this.buckets.size;
+  }
+};
+
+// src/engine/cache.ts
+function makeMemoryCache(opts = {}) {
+  const maxEntries = opts.maxEntries ?? 5e4;
+  const now = opts.now ?? (() => Date.now());
+  const store = /* @__PURE__ */ new Map();
+  const inflight = /* @__PURE__ */ new Map();
+  const live = (key) => {
+    const e = store.get(key);
+    if (!e) return void 0;
+    if (e.expiresAt !== 0 && e.expiresAt <= now()) {
+      store.delete(key);
+      return void 0;
+    }
+    return e;
+  };
+  const evict = () => {
+    const t = now();
+    let dropped = 0;
+    for (const [k, e] of store) {
+      if (e.expiresAt !== 0 && e.expiresAt <= t) {
+        store.delete(k);
+        dropped++;
+      }
+    }
+    if (dropped > 0) return;
+    const order = [...store.entries()].sort(
+      (a, b) => (a[1].expiresAt || Infinity) - (b[1].expiresAt || Infinity)
+    );
+    for (let i = 0; i < Math.ceil(order.length / 4); i++) {
+      const victim = order[i];
+      if (victim) store.delete(victim[0]);
+    }
+  };
+  const set = async (key, value, ttl) => {
+    if (store.size >= maxEntries && !store.has(key)) evict();
+    store.set(key, { value, expiresAt: ttl && ttl > 0 ? now() + ttl * 1e3 : 0 });
+  };
+  return {
+    async get(key) {
+      const e = live(key);
+      return e ? e.value : null;
+    },
+    set,
+    async del(key) {
+      store.delete(key);
+    },
+    async incr(key) {
+      const e = live(key);
+      const next = (typeof e?.value === "number" ? e.value : 0) + 1;
+      store.set(key, { value: next, expiresAt: e?.expiresAt ?? 0 });
+      return next;
+    },
+    async getOrSet(key, ttl, fn) {
+      const hit = live(key);
+      if (hit) return hit.value;
+      const running = inflight.get(key);
+      if (running) return running;
+      const fill = (async () => {
+        try {
+          const value = await fn();
+          await set(key, value, ttl);
+          return value;
+        } finally {
+          inflight.delete(key);
+        }
+      })();
+      inflight.set(key, fill);
+      return fill;
+    }
+  };
+}
+
+// src/engine/db.ts
+function quoteIdent(name) {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+var BIND_SQL = "select set_config('role',$1,true), set_config('search_path','public',true), set_config('request.jwt.claims',$2,true)";
+function createLazyTransaction(sql, role, claimsJson, options = {}) {
+  const { lockTimeout } = options;
+  const bindSql = lockTimeout ? `${BIND_SQL}, set_config('lock_timeout',$3,true)` : BIND_SQL;
+  const bindParams = lockTimeout ? [role, claimsJson, lockTimeout] : [role, claimsJson];
+  let opening = null;
+  let release = null;
+  let fail = null;
+  let settled = null;
+  const ensure = () => {
+    if (opening) return opening;
+    opening = new Promise((resolveTx2, rejectTx) => {
+      const parked = new Promise((res, rej) => {
+        release = res;
+        fail = rej;
+      });
+      settled = sql.begin(async (tx) => {
+        await tx.unsafe(bindSql, bindParams);
+        resolveTx2(tx);
+        await parked;
+      }).catch((e) => {
+        rejectTx(e);
+        throw e;
+      });
+    });
+    return opening;
+  };
+  return {
+    ensure,
+    get opened() {
+      return opening !== null;
+    },
+    async commit() {
+      if (!opening) return;
+      release();
+      await settled;
+    },
+    async rollback(reason) {
+      if (!opening) return;
+      fail(reason);
+      await settled?.catch(() => void 0);
+    }
+  };
+}
+var resolveTx = async (tx) => typeof tx.ensure === "function" ? await tx.ensure() : tx;
+function asWireValue(value) {
+  if (value instanceof Date) return value.toISOString();
+  if (Array.isArray(value)) return value.map(asWireValue);
+  return value;
+}
+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);
+  return out;
+}
+function asWireRows(rows) {
+  return rows.map((row) => asWireRow(row));
+}
+function createOps(tx) {
+  const at = () => resolveTx(tx);
+  const ops = {
+    async query(sql, params = []) {
+      return asWireRows(await (await at()).unsafe(sql, params));
+    },
+    async insert(table, data) {
+      const cols = Object.keys(data);
+      if (cols.length === 0) throw new Error(`insert into ${table}: no columns given`);
+      const placeholders = cols.map((_, i) => `$${i + 1}`).join(", ");
+      const sql = `INSERT INTO ${quoteIdent(table)} (${cols.map(quoteIdent).join(", ")}) VALUES (${placeholders}) RETURNING *`;
+      const rows = await (await at()).unsafe(sql, cols.map((c) => data[c]));
+      const inserted = rows[0];
+      if (!inserted) {
+        throw new Error(
+          `insert into ${table} returned no row \u2014 the write was rejected (an RLS policy, most likely).`
+        );
+      }
+      return asWireRow(inserted);
+    },
+    async update(table, id, data) {
+      const cols = Object.keys(data);
+      if (cols.length === 0) return ops.findById(table, id);
+      const assignments = cols.map((c, i) => `${quoteIdent(c)} = $${i + 1}`).join(", ");
+      const sql = `UPDATE ${quoteIdent(table)} SET ${assignments} WHERE id = $${cols.length + 1} RETURNING *`;
+      const rows = await (await at()).unsafe(sql, [...cols.map((c) => data[c]), id]);
+      return rows[0] ? asWireRow(rows[0]) : null;
+    },
+    async delete(table, id) {
+      await (await at()).unsafe(`DELETE FROM ${quoteIdent(table)} WHERE id = $1`, [id]);
+    },
+    async findById(table, id) {
+      const rows = await (await at()).unsafe(
+        `SELECT * FROM ${quoteIdent(table)} WHERE id = $1`,
+        [id]
+      );
+      return rows[0] ? asWireRow(rows[0]) : null;
+    },
+    async findMany(table, query = {}) {
+      const cols = Object.keys(query);
+      const where = cols.length ? ` WHERE ${cols.map((c, i) => `${quoteIdent(c)} = $${i + 1}`).join(" AND ")}` : "";
+      return asWireRows(await (await at()).unsafe(
+        `SELECT * FROM ${quoteIdent(table)}${where}`,
+        cols.map((c) => query[c])
+      ));
+    },
+    /** 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)));
+    },
+    /**
+     * Execute a whole transaction plan — what `Database.transaction(fn)` builds.
+     *
+     * WHY IT RUNS HERE. The platform used to carry a complete implementation
+     * of this at `/internal-api/db/tx`, for tenant code that ran in an isolate
+     * with no connection of its own. Running the plan there means running it on
+     * a DIFFERENT connection: a transaction would not see the uncommitted
+     * writes of the request that started it, and the two would hold separate
+     * RLS bindings of the same identity. In this stack the tenant's code and
+     * the connection share a process, so the plan runs on the request's own
+     * transaction inside one SAVEPOINT — and that surface was removed on
+     * 2026-08-15, once this was the last thing that could have called it.
+     *
+     * Until 2026-08-15 it ran NOWHERE: `runTxPlan` called `transport.txPlan` and
+     * nothing here implemented it, so a live handler answered
+     * "transport.txPlan is not a function" while every test that covered
+     * transactions passed against a mock that did implement it.
+     */
+    async txPlan(plan) {
+      const live = await at();
+      return live.savepoint(async (sp) => {
+        const results = [];
+        for (const op of plan.ops) {
+          const rows = await runPlanOp(sp, op, results);
+          const result = { rows, rows_affected: rows.length };
+          results.push(result);
+          assertGuard(op, result);
+        }
+        return { results };
+      });
+    }
+  };
+  return ops;
+}
+var currentSchema = {};
+function setSchema(schema) {
+  const s = schema;
+  currentSchema = (s && "default" in s ? s.default : s) ?? {};
+}
+function withTables(ops, schema = currentSchema) {
+  const tables = {};
+  for (const key of Object.keys(schema.tables ?? {})) {
+    const name = schema.tables?.[key]?.name ?? key;
+    tables[key] = {
+      insert: (data) => ops.insert(name, data),
+      update: (id, data) => ops.update(name, id, data),
+      delete: (id) => ops.delete(name, id),
+      findById: (id) => ops.findById(name, id),
+      findMany: (query) => ops.findMany(name, query ?? {})
+    };
+  }
+  const base = /* @__PURE__ */ Object.create(null);
+  return Object.assign(base, ops, { tables });
+}
+var SERVICE_LOCK_TIMEOUT = "5s";
+function isLockTimeout(e) {
+  const code = e?.code;
+  const message = String(e?.message ?? "");
+  return code === "55P03" || /lock timeout/i.test(message);
+}
+function diagnosingDriver(sql) {
+  const explain = (e) => isLockTimeout(e) ? new Error(
+    `Database.asService() waited too long for a row lock. It runs in its OWN transaction, so a row this request already wrote through Database.* is locked against it until the request commits \u2014 a wait that cannot end. Do that row's work on one surface or the other. (${String(e?.message ?? e)})`
+  ) : e;
+  const wrapTx = (tx) => ({
+    async unsafe(text, params) {
+      try {
+        return await tx.unsafe(text, params);
+      } catch (e) {
+        throw explain(e);
+      }
+    },
+    savepoint(cb) {
+      return tx.savepoint((sp) => cb(wrapTx(sp)));
+    }
+  });
+  return {
+    unsafe: (text, params) => sql.unsafe(text, params),
+    begin: (cb) => sql.begin((tx) => cb(wrapTx(tx)))
+  };
+}
+function createRequestDatabase(sql, identity) {
+  const tx = createLazyTransaction(sql, identity.role, identity.claimsJson);
+  let serviceTx = null;
+  let serviceClient = null;
+  const asService = () => {
+    if (serviceClient === null) {
+      serviceTx = createLazyTransaction(
+        diagnosingDriver(sql),
+        identity.serviceRole,
+        identity.claimsJson,
+        { lockTimeout: SERVICE_LOCK_TIMEOUT }
+      );
+      serviceClient = withTables(createOps(serviceTx));
+    }
+    return serviceClient;
+  };
+  return {
+    client: Object.assign(withTables(createOps(tx)), { asService }),
+    async commit() {
+      await tx.commit();
+      await serviceTx?.commit();
+    },
+    async rollback(reason) {
+      await tx.rollback(reason);
+      await serviceTx?.rollback(reason);
+    }
+  };
+}
+var Args = class {
+  values = [];
+  bind(value) {
+    this.values.push(value);
+    return `$${this.values.length}`;
+  }
+};
+function isRef(v) {
+  return typeof v === "object" && v !== null && "$ref" in v;
+}
+function isExpr(v) {
+  return typeof v === "object" && v !== null && "$expr" in v;
+}
+function renderValue(value, column, args, results) {
+  if (isRef(value)) {
+    const source = results[value.$ref.op];
+    const row = source?.rows[0];
+    if (!row || !(value.$ref.field in row)) {
+      throw Object.assign(new Error(`op ${value.$ref.op} has no column "${value.$ref.field}" to reference`), {
+        error_code: "tx_ref_unresolved"
+      });
+    }
+    return args.bind(row[value.$ref.field]);
+  }
+  if (isExpr(value)) {
+    const fn = value.$expr;
+    if (fn.fn === "now") return "now()";
+    const operator = fn.fn === "inc" ? "+" : "-";
+    return `${quoteIdent(column)} ${operator} ${args.bind(fn.by)}`;
+  }
+  return args.bind(value);
+}
+function renderWhere(where, args, results) {
+  const cols = Object.keys(where ?? {});
+  if (cols.length === 0) return "";
+  const terms = cols.map((c) => {
+    const v = where[c];
+    if (v === null) return `${quoteIdent(c)} IS NULL`;
+    return `${quoteIdent(c)} = ${renderValue(v, c, args, results)}`;
+  });
+  return ` WHERE ${terms.join(" AND ")}`;
+}
+async function runPlanOp(sp, op, results) {
+  const args = new Args();
+  const table = quoteIdent(op.table);
+  let sql;
+  switch (op.op) {
+    case "insert": {
+      const cols = Object.keys(op.values ?? {});
+      const rendered = cols.map((c) => renderValue(op.values[c], c, args, results));
+      sql = cols.length ? `INSERT INTO ${table} (${cols.map(quoteIdent).join(", ")}) VALUES (${rendered.join(", ")}) RETURNING *` : `INSERT INTO ${table} DEFAULT VALUES RETURNING *`;
+      break;
+    }
+    case "insertMany": {
+      const rows = op.rows ?? [];
+      if (rows.length === 0 || !rows[0]) return [];
+      const cols = Object.keys(rows[0]);
+      const tuples = rows.map(
+        (r) => `(${cols.map((c) => renderValue(r[c], c, args, results)).join(", ")})`
+      );
+      sql = `INSERT INTO ${table} (${cols.map(quoteIdent).join(", ")}) VALUES ${tuples.join(", ")} RETURNING *`;
+      break;
+    }
+    case "update": {
+      const cols = Object.keys(op.set ?? {});
+      if (cols.length === 0) throw new Error(`update ${op.table}: nothing to set`);
+      const assignments = cols.map(
+        (c) => `${quoteIdent(c)} = ${renderValue(op.set[c], c, args, results)}`
+      );
+      sql = `UPDATE ${table} SET ${assignments.join(", ")}${renderWhere(op.where, args, results)} RETURNING *`;
+      break;
+    }
+    case "delete": {
+      sql = `DELETE FROM ${table}${renderWhere(op.where, args, results)} RETURNING *`;
+      break;
+    }
+    case "select": {
+      const limit = op.limit !== void 0 ? ` LIMIT ${Number(op.limit)}` : "";
+      const lock = op.lock === "update" ? " FOR UPDATE" : "";
+      sql = `SELECT * FROM ${table}${renderWhere(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);
+}
+function assertGuard(op, result) {
+  const guard = op.guard;
+  if (!guard) return;
+  const n = result.rows.length;
+  const ok = guard.kind === "one" ? n === 1 : guard.kind === "none" ? n === 0 : guard.kind === "atLeast" ? n >= guard.n : n <= guard.n;
+  if (ok) return;
+  throw Object.assign(new Error(`transaction expectation failed: ${guard.kind} (${n} row(s))`), {
+    error_code: "tx_guard_failed",
+    slot: guard.slot
+  });
+}
+
+// src/decorators/registry.ts
+var ROUTES = /* @__PURE__ */ Symbol.for("palbase.backend.routes");
+var RETURN_BUFFER = /* @__PURE__ */ Symbol.for("palbase.backend.returnBuffer");
+var THROWS_BUFFER = /* @__PURE__ */ Symbol.for("palbase.backend.throwsBuffer");
+function carrierOf(target) {
+  const ctor = typeof target === "function" ? target : target.constructor ?? target;
+  return ctor;
+}
+function getRoutes(ctor) {
+  const carrier = carrierOf(ctor);
+  const routes = carrier[ROUTES] ?? [];
+  const returnBuffer = carrier[RETURN_BUFFER];
+  if (returnBuffer) {
+    for (const route of routes) {
+      const buffered = returnBuffer[route.fnName];
+      if (buffered && route.returnSchema === void 0) {
+        route.returnSchema = buffered;
+      }
+    }
+  }
+  const throwsBuffer = carrier[THROWS_BUFFER];
+  if (throwsBuffer) {
+    for (const route of routes) {
+      const buffered = throwsBuffer[route.fnName];
+      if (buffered && route.throws === void 0) {
+        route.throws = buffered;
+      }
+    }
+  }
+  return routes.map((r) => ({
+    ...r,
+    params: r.params.slice(),
+    ...r.throws !== void 0 ? { throws: r.throws.slice() } : {}
+  }));
+}
+
+// src/engine/router.ts
+var CONTROLLER_META = /* @__PURE__ */ Symbol.for("palbase.backend.controllerMeta");
+function toSegments(path) {
+  return path.split("/").filter(Boolean).map((s) => s.startsWith("{") && s.endsWith("}") ? `:${s.slice(1, -1)}` : s);
+}
+function buildRouteTable(controllers) {
+  const table = [];
+  for (const Ctrl of controllers) {
+    const ctor = Ctrl;
+    const meta = ctor[CONTROLLER_META];
+    const basePath = meta?.basePath ?? "";
+    const routes = getRoutes(Ctrl);
+    if (routes.length === 0) {
+      const name = Ctrl.name ?? "<anonymous>";
+      throw new Error(
+        `controller ${name} collected zero routes. Either it declares no @Get/@Post/\u2026 , or its decorator metadata was erased at build time \u2014 check that the bundle was compiled with experimentalDecorators enabled.`
+      );
+    }
+    const instance = new ctor();
+    for (const r of routes) {
+      const full = `${basePath}${r.subpath ?? ""}` || "/";
+      table.push({
+        method: r.method,
+        segments: toSegments(full),
+        meta: r,
+        instance,
+        id: `${r.method} ${full}`,
+        controllerAuth: meta?.defaultAuth
+      });
+    }
+  }
+  return table;
+}
+function matchRoute(table, method, pathname) {
+  const parts = pathname.split("/").filter(Boolean);
+  for (const entry of table) {
+    if (entry.method !== method || entry.segments.length !== parts.length) continue;
+    const params = {};
+    let ok = true;
+    for (let i = 0; i < entry.segments.length; i++) {
+      const seg = entry.segments[i];
+      const got = parts[i];
+      if (seg === void 0 || got === void 0) {
+        ok = false;
+        break;
+      }
+      if (seg.charCodeAt(0) === 58) {
+        params[seg.slice(1)] = decodeURIComponent(got);
+      } else if (seg !== got) {
+        ok = false;
+        break;
+      }
+    }
+    if (ok) return { entry, params };
+  }
+  return null;
+}
+
+// src/engine/upload.ts
+var AUTHORIZE_PATH = "/__palbase/upload/authorize";
+var SIGNATURE_HEADER = "x-palbase-upload-signature";
+function renderPath(template, tokens) {
+  return template.replaceAll("{userId}", sanitizeSegment(tokens.userId ?? "anonymous")).replaceAll("{uploadId}", sanitizeSegment(tokens.uploadId)).replaceAll("{filename}", sanitizeSegment(tokens.filename ?? "file"));
+}
+function sanitizeSegment(raw) {
+  const cleaned = raw.replace(/[-]/g, "").replace(/[/\\]/g, "-").replace(/\.{2,}/g, ".").replace(/^\.+/, "").trim();
+  return cleaned === "" ? "file" : cleaned.slice(0, 200);
+}
+function grantFor(entry, ctx, bucketLimits) {
+  const cfg = entry?.meta?.options?.uploadConfig;
+  if (!cfg) return null;
+  return {
+    bucket: cfg.bucket,
+    path: renderPath(cfg.pathTemplate, {
+      userId: ctx.userId,
+      uploadId: ctx.uploadId,
+      filename: ctx.filename
+    }),
+    maxBytes: bucketLimits?.maxBytes ?? null,
+    mimeTypes: bucketLimits?.mimeTypes ?? null
+  };
+}
+var CompletionLedger = class {
+  constructor(capacity = 1024) {
+    this.capacity = capacity;
+  }
+  capacity;
+  seen = /* @__PURE__ */ new Map();
+  recall(uploadId) {
+    return this.seen.get(uploadId);
+  }
+  remember(uploadId, response) {
+    this.seen.delete(uploadId);
+    this.seen.set(uploadId, response);
+    while (this.seen.size > this.capacity) {
+      const oldest = this.seen.keys().next();
+      if (oldest.done) break;
+      this.seen.delete(oldest.value);
+    }
+  }
+  get size() {
+    return this.seen.size;
+  }
+};
+function verifySignature(presented, expected) {
+  if (presented.length !== expected.length) return false;
+  let diff = 0;
+  for (let i = 0; i < presented.length; i++) {
+    diff |= presented.charCodeAt(i) ^ expected.charCodeAt(i);
+  }
+  return diff === 0;
+}
+
+// src/engine/fence.ts
+var SECRET_ENV = [
+  "DATABASE_URL",
+  "PALBASE_SERVICE_ROLE_KEY",
+  "REALTIME_INGESTION_SECRET",
+  "INTERNAL_API_SECRET",
+  "STACK_ROOT_KEY",
+  "PEPPER",
+  "LOCAL_JWT_PEM"
+];
+function scrubSecrets(env) {
+  const removed = [];
+  const kept = [];
+  for (const name of SECRET_ENV) {
+    if (env[name] === void 0) continue;
+    delete env[name];
+    removed.push(name);
+  }
+  for (const name of Object.keys(env)) if (name.startsWith("PALBASE_VAR_")) kept.push(name);
+  return { removed, kept };
+}
+function hostAllowed(host, allow) {
+  const h = host.toLowerCase();
+  for (const raw of allow) {
+    const pattern = raw.trim().toLowerCase();
+    if (!pattern) continue;
+    if (pattern === h) return true;
+    if (pattern.startsWith("*.") && h.endsWith(pattern.slice(1)) && h.length > pattern.length - 1) {
+      return true;
+    }
+  }
+  return false;
+}
+function installEgressFence(policy) {
+  const original = globalThis.fetch.bind(globalThis);
+  const declared = policy.allow.length > 0;
+  const platform = (policy.alwaysAllow ?? []).map((h) => h.toLowerCase()).filter(Boolean);
+  if (!declared && policy.whenUndeclared === "allow") return original;
+  const fenced = async (input, init) => {
+    const url = typeof input === "string" ? new URL(input) : input instanceof URL ? input : new URL(input.url);
+    if (platform.includes(url.hostname.toLowerCase())) return original(input, init);
+    if (!declared || !hostAllowed(url.hostname, policy.allow)) {
+      throw new Error(
+        `egress denied: ${url.hostname} is not in this backend's declared allowlist. Add it to config/egress.ts and deploy.`
+      );
+    }
+    if (policy.timeoutMs > 0) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), policy.timeoutMs);
+      try {
+        return await original(input, { ...init, signal: init?.signal ?? controller.signal });
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+    return original(input, init);
+  };
+  globalThis.fetch = fenced;
+  return original;
+}
+
+// src/engine/index.ts
+var JSON_HEADERS = { "content-type": "application/json" };
+function envelope(error, description, status, requestId, extra) {
+  return new Response(
+    JSON.stringify({ error, error_description: description, status, request_id: requestId, ...extra }),
+    { status, headers: JSON_HEADERS }
+  );
+}
+function unavailable(name) {
+  throw new Error(
+    `${name} is unavailable. Either this backend was started without module clients (set MODULE_BASE_URL and the API keys so the engine can reach the module surface), or ${name} is not one of the modules this backend provides.`
+  );
+}
+function stubModule(name) {
+  return new Proxy(
+    {},
+    {
+      get: () => unavailable(name),
+      apply: () => unavailable(name)
+    }
+  );
+}
+async function defaultSqlDriver(config) {
+  const g = globalThis;
+  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({ url: config.databaseUrl, max: config.poolMax });
+}
+async function createApp(opts) {
+  const { config, controllers } = opts;
+  setSchema(opts.schema ?? {});
+  const routes = buildRouteTable(controllers);
+  if (routes.length === 0) {
+    throw new BootRefused([], "boot refused: zero endpoints collected \u2014 nothing would answer.");
+  }
+  const sql = opts.sql ?? await defaultSqlDriver(config);
+  await sql.unsafe("select 1");
+  const auth = new AuthVerifier({ jwksUrl: config.authJwksUrl, issuer: config.authIssuer });
+  const limiter = new RateLimiter();
+  const cache = opts.cache ?? makeMemoryCache();
+  const log = opts.logger ?? console;
+  const modules = opts.modules ?? {};
+  const runWithRuntime = opts.runtimeHooks?.__runWithRuntime ?? __runWithRuntime;
+  const requestALS = opts.runtimeHooks?.__requestALS ?? __requestALS;
+  const uploadSecret = config.uploadSecret ?? "";
+  const completions = new CompletionLedger();
+  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);
+    }
+    const body = await req.json().catch(() => null);
+    if (!body?.path || !body.uploadId) {
+      return envelope("bad_request", "authorize needs a path and an uploadId", 400, requestId);
+    }
+    const target = matchRoute(routes, body.method ?? "POST", body.path);
+    const spec = effectiveAuth(target?.entry.meta.options?.auth, target?.entry.controllerAuth);
+    const callerClaims = await auth.verify(req.headers.get("authorization"));
+    if (spec.required && !callerClaims) {
+      return envelope("unauthorized", "A valid access token is required", 401, requestId);
+    }
+    if (callerClaims && spec.role && callerClaims.role !== spec.role) {
+      return envelope("forbidden", `This endpoint requires the "${spec.role}" role`, 403, requestId);
+    }
+    const grant = grantFor(target?.entry, {
+      userId: typeof callerClaims?.sub === "string" ? callerClaims.sub : null,
+      uploadId: body.uploadId,
+      filename: body.filename
+    });
+    if (!grant) {
+      return envelope(
+        "not_an_upload_route",
+        `${body.method ?? "POST"} ${body.path} does not declare @Upload`,
+        400,
+        requestId
+      );
+    }
+    return new Response(JSON.stringify(grant), { status: 200, headers: JSON_HEADERS });
+  }
+  async function handle(req) {
+    const requestId = `req_${crypto.randomUUID()}`;
+    const url = new URL(req.url);
+    if (url.pathname === AUTHORIZE_PATH) {
+      return handleAuthorize(req, requestId);
+    }
+    const hit = matchRoute(routes, req.method, url.pathname);
+    if (!hit) return envelope("not_found", "No route matches this method and path", 404, requestId);
+    const { meta } = hit.entry;
+    const spec = effectiveAuth(meta.options?.auth, hit.entry.controllerAuth);
+    const claims = await auth.verify(req.headers.get("authorization"));
+    if (spec.required && !claims) {
+      return envelope("unauthorized", "A valid access token is required", 401, requestId);
+    }
+    const userId = typeof claims?.sub === "string" ? claims.sub : void 0;
+    if (claims && spec.role && claims.role !== spec.role) {
+      return envelope("forbidden", `This endpoint requires the "${spec.role}" role`, 403, requestId);
+    }
+    if (claims && spec.verifiedEmail && claims.email_verified !== true) {
+      return envelope("email_not_verified", "A verified email address is required", 403, requestId);
+    }
+    const retryAfter = limiter.check(
+      meta.options?.rateLimit,
+      RateLimiter.key(hit.entry.id, userId, req.headers),
+      Date.now()
+    );
+    if (retryAfter !== null) {
+      return new Response(
+        JSON.stringify({
+          error: "too_many_requests",
+          error_description: "Rate limit exceeded for this endpoint",
+          status: 429,
+          request_id: requestId
+        }),
+        { status: 429, headers: { ...JSON_HEADERS, "retry-after": String(retryAfter) } }
+      );
+    }
+    let completionUploadId = null;
+    const args = [];
+    let parsedBody;
+    let bodyRead = false;
+    for (const p of meta.params ?? []) {
+      switch (p.kind) {
+        case "body": {
+          if (!bodyRead) {
+            parsedBody = await req.json().catch(() => ({}));
+            bodyRead = true;
+          }
+          const r = p.schema.safeParse(parsedBody);
+          if (!r.success) {
+            return envelope("bad_request", "Request body failed validation", 400, requestId, {
+              fields: r.error.issues.map((i) => ({ field: i.path.join("."), message: i.message }))
+            });
+          }
+          args[p.index] = r.data;
+          break;
+        }
+        case "query": {
+          const r = p.schema.safeParse(Object.fromEntries(url.searchParams));
+          if (!r.success) {
+            return envelope("bad_request", "Query parameters failed validation", 400, requestId, {
+              fields: r.error.issues.map((i) => ({ field: i.path.join("."), message: i.message }))
+            });
+          }
+          args[p.index] = r.data;
+          break;
+        }
+        case "param":
+          args[p.index] = hit.params[p.name];
+          break;
+        case "headers":
+          args[p.index] = Object.fromEntries(req.headers);
+          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 ?? {}
+          } : null;
+          break;
+        case "uploadedObject": {
+          if (uploadSecret === "" || !verifySignature(req.headers.get(SIGNATURE_HEADER) ?? "", uploadSecret)) {
+            return envelope(
+              "unauthorized",
+              "This endpoint accepts uploads through storage, not directly",
+              401,
+              requestId
+            );
+          }
+          if (!bodyRead) {
+            parsedBody = await req.json().catch(() => ({}));
+            bodyRead = true;
+          }
+          const envelopeIn = parsedBody;
+          if (!envelopeIn?.uploadedObject) {
+            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) {
+              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 "req":
+          args[p.index] = req;
+          break;
+        default:
+          args[p.index] = void 0;
+      }
+    }
+    const db = createRequestDatabase(sql, {
+      role: config.dbRole,
+      serviceRole: config.dbServiceRole,
+      claimsJson: JSON.stringify(claims ?? {})
+    });
+    try {
+      const services = {
+        Database: db.client,
+        Cache: cache,
+        Log: log,
+        Documents: modules.Documents ?? stubModule("Documents"),
+        Storage: modules.Storage ?? stubModule("Storage"),
+        Notifications: modules.Notifications ?? stubModule("Notifications"),
+        Flags: modules.Flags ?? stubModule("Flags"),
+        Realtime: modules.Realtime ?? stubModule("Realtime"),
+        Purchases: modules.Purchases ?? stubModule("Purchases"),
+        // Named, never undefined. A backend started without a secrets client
+        // that returned `undefined` here would fail inside the handler as
+        // "Cannot read properties of undefined", which says nothing about what
+        // to configure — the stub says the name and the variable.
+        Secrets: modules.Secrets ?? stubModule("Secrets")
+      };
+      const result = await runWithRuntime(services, () => {
+        const box = requestALS.getStore();
+        if (box) {
+          box.userId = userId ?? null;
+          box.requestId = requestId;
+          box.idempotencyKey = req.headers.get("idempotency-key");
+        }
+        const method = hit.entry.instance[meta.fnName];
+        if (typeof method !== "function") {
+          throw new Error(
+            `route ${hit.entry.id} names method ${meta.fnName}, which the controller does not define`
+          );
+        }
+        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);
+          return envelope(
+            "output_invalid",
+            "The handler returned a value its declared return type rejects",
+            500,
+            requestId
+          );
+        }
+      }
+      if (result === void 0 || result === null) {
+        if (completionUploadId) {
+          completions.remember(completionUploadId, { status: 204, body: null, contentType: null });
+        }
+        return new Response(null, { status: 204 });
+      }
+      const payload = JSON.stringify(result);
+      if (completionUploadId) {
+        completions.remember(completionUploadId, {
+          status: 200,
+          body: payload,
+          contentType: JSON_HEADERS["content-type"] ?? "application/json"
+        });
+      }
+      return new Response(payload, { status: 200, headers: JSON_HEADERS });
+    } catch (err) {
+      await db.rollback(err);
+      if (isHttpError(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 {
+    handle,
+    routes,
+    config,
+    async shutdown() {
+      const closable = sql;
+      await closable.close?.();
+      await closable.end?.();
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthVerifier,
+  BootRefused,
+  RateLimiter,
+  buildRouteTable,
+  createApp,
+  createLazyTransaction,
+  createOps,
+  createRequestDatabase,
+  effectiveAuth,
+  hostAllowed,
+  installEgressFence,
+  loadConfig,
+  makeMemoryCache,
+  matchRoute,
+  quoteIdent,
+  scrubSecrets,
+  withTables
+});
+//# sourceMappingURL=index.cjs.map