@palbase/backend 17.4.0 → 18.0.0

package/dist/index-DZDUMth5.d.ts

@@ -0,0 +1,839 @@
+import { Buckets, BucketTypes } from './db/env.js';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { C as CacheClient, P as PalbaseDocsClient, a as PalbaseFlagsClient, L as Logger, b as PalbaseNotificationsClient, c as PalbaseRealtimeClient, D as DBClient, S as SecretsService, d as PalbaseStorageClient, e as PalbaseBucketClient, T as TxPlanBody, f as TxPlanResponse } from './endpoint-B0LpZixz.js';
+import { E as EnvTypedDatabase } from './index-g-EzitI-.js';
+import { R as RouteMeta } from './registry-3BLYv4si.js';
+
+/**
+ * The purchases surface the decorators need, declared as a NARROW STRUCTURAL
+ * interface rather than an import of `@palstore/purchases`.
+ *
+ * `PurchasesClient` (palstore's `sk_` backend SDK) satisfies this shape as-is,
+ * so the runtime injects the real client with no adapter — but `@palbase/backend`
+ * itself gains no dependency on it. That matters: this package is published
+ * public and baked into the br-pod image from a tarball, so a dependency on an
+ * unpublished sibling would break `npm install palbase-backend.tgz`. It is also
+ * the pattern `withSpend` already uses for the same reason (`SpendCapableClient`
+ * in palstore's own spend.ts: "a narrow structural interface … so this file has
+ * no dependency on client.ts").
+ *
+ * The methods here are a SUBSET of `PurchasesClient` — only what the two
+ * decorators call. Grants, refunds, credits and customer-info reads stay off
+ * this interface: a tenant that wants them imports the palstore SDK directly.
+ */
+/** Store environment a subject is fixed to. Mirrors `StoreEnv` in `@palstore/purchases`. */
+type StoreEnv = "production" | "sandbox";
+/** Quota/credit state carried by a 429. Mirrors `LimitState` in `@palstore/purchases`
+ * (SPEC-purchases-v1 §11) — re-declared, not imported, for the reason above. */
+interface LimitState {
+    key: string;
+    scope: string;
+    window: string;
+    used: number;
+    reserved: number;
+    max: number;
+    remaining: number;
+    resetAt: string;
+}
+/** Options for one spend. `idempotencyKey` is required by the server (§9). */
+interface SpendOptions {
+    /** Defaults to 1. */
+    count?: number;
+    idempotencyKey: string;
+}
+interface PurchasesService {
+    /** Map a tenant-side user reference to its palstore subject, creating one on
+     * first sight. Server-authoritative — the caller never names a subject. */
+    resolveSubject(input: {
+        userRef: string;
+        storeEnv: StoreEnv;
+    }): Promise<{
+        subjectId: string;
+    }>;
+    /** Resolve silently when `entitlementKey` is active for `subjectId`; throw
+     * `EntitlementRequiredError` otherwise. Consumes nothing. */
+    require(subjectId: string, entitlementKey: string): Promise<void>;
+    /** Reserve → run `handler` → commit on success, cancel on throw, always
+     * rethrowing the handler's own error. The whole reason the decorators are a
+     * thin layer: this lifecycle is already written and tested in palstore's SDK. */
+    withSpend<T>(subjectId: string, key: string, opts: SpendOptions, handler: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * runtime.ts — request-scoped service singletons.
+ *
+ * The backend SDK no longer threads a `ctx` god-object through every handler.
+ * Instead, controller methods import PascalCase service singletons directly:
+ *
+ *   import { Controller, Post, Body, Database } from "@palbase/backend";
+ *
+ *   \@Controller("/todos")
+ *   export default class TodosController {
+ *     \@Post("") create(\@Body(CreateTodoBody) body: CreateTodoBody): unknown {
+ *       return Database.insert("todos", { title: body.title });
+ *     }
+ *   }
+ *
+ * The singletons are thin Proxies. Every property access forwards to the live
+ * client for the CURRENT request scope, resolved through {@link __getRuntime}.
+ *
+ * # Request-scope resolution (persistent app-server)
+ *
+ * The runtime is a long-running Node process that serves many concurrent
+ * requests on one event loop (NOT a fresh subprocess per request). A single
+ * module-global slot would let one in-flight request's services bleed into
+ * another's. So the services are carried in an {@link AsyncLocalStorage} store
+ * ({@link __requestALS}) that the runtime sets per request with
+ * {@link __runWithRuntime}; every async continuation of that request reads its
+ * own store. `__getRuntime` reads the ALS store first; the module-global slot
+ * (set by {@link __setRuntime}) is only a fallback for callers that run OUTSIDE
+ * an ALS scope (dev-server, unit tests, the legacy single-shot path). Because
+ * each `br-<ref>` pod is single-tenant, there is no cross-tenant leakage; the
+ * ALS store is what prevents cross-REQUEST leakage within the shared process.
+ *
+ * The seam that makes `import { Database } from "@palbase/backend"` resolve to
+ * the runtime-injected client: `@palbase/backend` is marked esbuild-EXTERNAL
+ * when the tenant bundle is built, and the package is installed globally in the
+ * pod (NODE_PATH=/usr/local/lib/node_modules). So worker.js's
+ * `require('@palbase/backend')` and the bundle's `import` resolve to ONE shared
+ * module instance — the ALS store and `__setRuntime` slot on that instance are
+ * visible to the singletons the bundle imported.
+ */
+
+/** The set of live clients the runtime injects per request scope.
+ *
+ * Realtime is BROADCAST-ONLY here (a stateless handler can push an event but
+ * cannot hold a subscription socket — `subscribe()` lives on the client SDK).
+ *
+ * EXCLUDED on purpose: Functions, Links, Analytics, Auth. They are not
+ * exposed as backend handler singletons (auth lives on the client SDK; the rest
+ * are out of scope for backend endpoints). */
+interface RuntimeServices {
+    Database: DBClient;
+    Secrets: SecretsService;
+    Documents: PalbaseDocsClient;
+    Storage: PalbaseStorageClient;
+    Cache: CacheClient;
+    Log: Logger;
+    Notifications: PalbaseNotificationsClient;
+    Flags: PalbaseFlagsClient;
+    Realtime: PalbaseRealtimeClient;
+    Purchases: PurchasesService;
+}
+/**
+ * The per-request ALS box.
+ *
+ * `runtime` is the service bundle. `userId` is the request's authenticated user
+ * id, written by the runtime immediately after it assembles the request object
+ * (worker.js: `requestALS.getStore().userId = pbReq.user?.id || null`) and
+ * `null` on an anonymous request. It was already being written there for the
+ * Flags client's auto-bind; declaring it here makes the existing contract typed
+ * instead of implicit, which is what lets `currentSubjectId()` read a
+ * server-owned identity rather than trusting anything the caller sent.
+ */
+interface RequestStore {
+    runtime: RuntimeServices;
+    userId?: string | null;
+    /** This request's id (`req_…`), written by the runtime. Used as the spend
+     * idempotency scope when the caller supplied no `Idempotency-Key`. */
+    requestId?: string;
+    /** The caller's `Idempotency-Key` header, or `null` when absent. What makes a
+     * client's retry replay its first result instead of charging twice. */
+    idempotencyKey?: string | null;
+}
+/**
+ * Per-request store. The persistent runtime runs each request inside
+ * {@link __runWithRuntime}, so every async continuation of that request reads
+ * its OWN `runtime` (and any other request-scoped fields the runtime adds).
+ *
+ * Exported with a `__` prefix so the runtime (worker.js) shares the SAME ALS
+ * instance across the one module instance — two ALS instances would silently
+ * not see each other's stores. NOT part of the public author-facing API.
+ */
+declare const __requestALS: AsyncLocalStorage<RequestStore>;
+/** Install the live clients in the process-global fallback slot.
+ *
+ * Persistent-server requests should use {@link __runWithRuntime} instead; this
+ * remains for dev-server / tests / the legacy single-shot path that run without
+ * an ALS scope. NOT part of the public author-facing API. */
+declare function __setRuntime(services: RuntimeServices): void;
+/** Run `fn` with `services` bound as the request-scoped runtime.
+ *
+ * The persistent worker calls this once per request so concurrent requests
+ * never share a services slot. NOT part of the public author-facing API. */
+declare function __runWithRuntime<T>(services: RuntimeServices, fn: () => T): T;
+/** Read the live clients, throwing if accessed outside a request scope.
+ *
+ * Resolves the ALS store first (persistent server, per-request), then the
+ * process-global fallback (dev-server / tests). NOT part of the public
+ * author-facing API — used by the runtime and the singleton Proxies. */
+declare function __getRuntime(): RuntimeServices;
+/**
+ * The project's own Postgres (pgx, schema `env_<envId>`).
+ *
+ * Typed by default: `Database.tables.<name>.insert({...})` is typed against
+ * the project's generated `palbase-env.d.ts` with NO import and NO generic.
+ * The raw string ops (`query`/`insert`/`update`/`delete`/`findById`/`findMany`)
+ * are also available for dynamic table names and read-only SQL.
+ *
+ * RLS is enforced by default (the runtime runs each op as `authenticated` with
+ * the verified user's claims). To bypass RLS, call `Database.asService()` —
+ * explicit and greppable — which runs as the `service_role` (BYPASSRLS).
+ *
+ * @example
+ * import { Database } from "@palbase/backend";
+ *
+ * const todo = await Database.tables.todos.insert({ title: req.input.title });
+ * todo.id; // string ✓
+ * const rows = await Database.query("SELECT id FROM todos WHERE done = $1", [false]);
+ * const all  = await Database.asService().tables.todos.findMany({}); // RLS bypass
+ */
+declare const Database: EnvTypedDatabase;
+/** Firestore-like document client (PalDocs). */
+declare const Documents: PalbaseDocsClient;
+/**
+ * `buckets.<name>` — the storage twin of `Database.tables.<name>`, and the same
+ * mechanism: `config/storage.ts` generates a `Buckets` augmentation into
+ * `palbase-env.d.ts`, so a bucket name is a property with no import and no
+ * generic, and a typo is a compile error.
+ *
+ * The intermediate `.buckets` is there for the reason `.tables` is: bucket
+ * names must not share a namespace with the client's own methods, or the day
+ * somebody declares a bucket called `bucket` the surface breaks.
+ */
+type EnvBuckets = {
+    [K in keyof Buckets]: TypedBucketClient<Buckets[K] extends BucketTypes ? Buckets[K] : BucketTypes>;
+};
+/** One bucket, with its declared variant names in the type. */
+interface TypedBucketClient<B extends BucketTypes> extends Omit<PalbaseBucketClient, "getPublicUrl"> {
+    /** The public URL for the object, or for one of THIS bucket's declared
+     * renditions. A name the bucket does not declare is a compile error. */
+    getPublicUrl(path: string, options?: {
+        variant?: B["variants"];
+    }): string;
+}
+/**
+ * Object storage: buckets, objects, renditions and signed URLs.
+ *
+ * `Storage.buckets.posts.upload(...)` is the typed path. `Storage.bucket(name)`
+ * remains for a name computed at runtime — rare, and it gives up the typing,
+ * which is the honest trade rather than a second blessed way to do it.
+ */
+declare const Storage: PalbaseStorageClient & {
+    buckets: EnvBuckets;
+};
+/** JSON-typed cache (get/set/incr/getOrSet). */
+declare const Cache: CacheClient;
+/**
+ * This tenant's secrets — API keys, provider credentials, signing material the
+ * BACKEND owns.
+ *
+ * `await Secrets.get("STRIPE_KEY")` in a handler. There is no `.env` to read
+ * and no file to mount: a secret is written through the vault's authenticated
+ * API (or the CLI/MCP that calls it), and this is how the deployed code reads
+ * it back. A name this tenant has not set answers null — as does every name
+ * the STACK holds, because no route returns a platform secret's value at all.
+ */
+declare const Secrets: SecretsService;
+/** Structured logger. */
+declare const Log: Logger;
+/** Push / email / SMS / in-app notifications. */
+declare const Notifications: PalbaseNotificationsClient;
+/**
+ * Palstore purchases (entitlements + quota/credit spend).
+ *
+ * Reached by handlers through the `@RequireEntitlement` / `@Spend` decorators
+ * rather than called directly in the common case; exposed as a singleton for
+ * the cases the decorators deliberately do not cover (a dynamic spend count,
+ * which must run BEFORE the billable side-effect).
+ */
+declare const Purchases: PurchasesService;
+/**
+ * Feature flags.
+ *
+ * Mirrors the `Database` / `Database.asService()` model. The default surface is
+ * RLS-equivalent for flags: reads resolve against the CURRENT request user and
+ * `Flags.setOverride(key, value)` writes an override for that same signed-in
+ * user (no userId argument, no admin power). Cross-user admin writes
+ * (`setOverrideForUser`, …) live behind `Flags.asService()` — explicit and
+ * greppable, just like `Database.asService()`.
+ *
+ * @example
+ * import { Flags } from "@palbase/backend";
+ *
+ * if (await Flags.isEnabled("new_checkout")) { ... }            // current user
+ * await Flags.setOverride("new_checkout", true);                // current user
+ * await Flags.asService().setOverrideForUser("u_9", "x", true); // cross-user
+ */
+declare const Flags: PalbaseFlagsClient;
+/**
+ * The Realtime broadcast singleton for the current request scope. Backend-side
+ * Realtime is BROADCAST-ONLY (a stateless handler can push but not subscribe —
+ * `subscribe()` lives on the client SDK's `pb.realtime`). Fire-and-forget:
+ * `broadcast` resolves once accepted (or with an `error`), never blocking the
+ * handler on subscribers.
+ *
+ * @example
+ * import { Realtime } from "@palbase/backend";
+ *
+ * await Realtime.broadcast("room:42", "message", { text, from: user.id });
+ */
+declare const Realtime: PalbaseRealtimeClient;
+
+/**
+ * engine/config.ts — settings from the environment, and the gate that refuses
+ * to boot without them.
+ *
+ * A mandatory module that is not configured must stop the process, by name.
+ * The failure this prevents is the expensive one: a stack that boots, passes
+ * its probes, and answers 500 on first contact — where the missing value is
+ * discovered by a customer rather than by the operator who could fix it.
+ *
+ * Database and Auth are mandatory. That is a product decision (2026-08-14), not
+ * a technical necessity: a backend whose data layer or whose notion of "who is
+ * calling" is undefined has nothing safe to do with a request.
+ */
+/** Everything the engine needs to serve. Built once, at boot, never re-read. */
+interface EngineConfig {
+    /** Postgres connection string. MANDATORY. */
+    databaseUrl: string;
+    /** Where this stack publishes its token signing keys. MANDATORY. */
+    authJwksUrl: string;
+    /** When set, a token whose `iss` differs is rejected. */
+    authIssuer?: string;
+    /** Base URL of the module surface (`/v1/*`, `/auth/*`). Empty ⇒ module
+     * singletons throw a named error on first use rather than silently no-op. */
+    moduleBaseUrl: string;
+    /** Shared secret storage signs its internal upload calls with. Empty means
+     * uploads are not wired, and those calls are refused. */
+    uploadSecret: string;
+    /** Publishable key, sent as `apikey` on module calls. */
+    anonKey: string;
+    /** Secret key. Used for privileged module calls. */
+    serviceRoleKey: string;
+    /** HMAC the realtime broadcast token is signed with. Empty ⇒ broadcast
+     * returns a clear `realtime_unconfigured` error instead of failing silently. */
+    realtimeSecret: string;
+    port: number;
+    /** The Postgres role each request is bound to. RLS policies are written
+     * against it, so changing it changes who the database thinks is asking. */
+    dbRole: string;
+    /**
+     * The Postgres role `Database.asService()` is bound to. It is the one that
+     * carries BYPASSRLS, which is the whole of what "as service" means — a name
+     * pointing at a role without it does not fail, it returns fewer rows.
+     *
+     * Configurable for the same reason `dbRole` is, and beside it on purpose: a
+     * stack that renames one of the pair must rename both, or the request and its
+     * service sibling stop being two identities of the same installation.
+     */
+    dbServiceRole: string;
+    poolMax: number;
+}
+/** Thrown when a mandatory module is unconfigured. Carries the missing names. */
+declare class BootRefused extends Error {
+    readonly missing: readonly string[];
+    constructor(missing: readonly string[], message: string);
+}
+/**
+ * Read the engine's settings, or refuse.
+ *
+ * @throws {BootRefused} naming every missing mandatory value at once — one
+ *   restart per missing variable is a bad way to learn what a stack needs.
+ */
+declare function loadConfig(env: Record<string, string | undefined>): EngineConfig;
+
+/**
+ * engine/db.ts — a real pooled connection, and the identity every request is
+ * bound to inside it.
+ *
+ * # Why one transaction per request
+ *
+ * In the isolate architecture every `Database.*` call was its own HTTP hop to a
+ * capability surface, so two writes in one handler could not be atomic — a
+ * handler that wrote and then threw left the first write behind. Here the whole
+ * request runs inside one transaction: it commits when the handler returns and
+ * rolls back when it throws. Atomicity stops being something the author has to
+ * ask for.
+ *
+ * # Why it opens lazily
+ *
+ * A handler that touches no table must cost no round trip. Opening eagerly cost
+ * four (BEGIN + bind + … + COMMIT) on endpoints that never query — measured at
+ * 1,243 rps against 31,579 for the same endpoint once the open became lazy.
+ *
+ * # How the caller's identity reaches RLS
+ *
+ * One statement, not three:
+ *
+ *   select set_config('role',$1,true),
+ *          set_config('search_path','public',true),
+ *          set_config('request.jwt.claims',$2,true)
+ *
+ * `set_config(..., is_local => true)` is transaction-scoped exactly like
+ * `SET LOCAL`, but takes BOUND PARAMETERS, which `SET LOCAL` cannot. So the
+ * role and the caller's claims travel as parameters — user identity is never
+ * spliced into SQL text — and `auth.uid()` resolves inside RLS policies, which
+ * means the row filter is enforced by Postgres rather than by our code.
+ */
+
+/** The slice of a SQL driver the engine uses. `Bun.sql` satisfies it. */
+interface SqlDriver {
+    /** Run a parameterised statement. */
+    unsafe(sql: string, params?: unknown[]): Promise<unknown>;
+    /** Open a transaction; the driver commits when `cb` resolves and rolls back
+     * when it rejects. */
+    begin<T>(cb: (tx: SqlTx) => Promise<T>): Promise<T>;
+}
+interface SqlTx {
+    unsafe(sql: string, params?: unknown[]): Promise<unknown>;
+    savepoint<T>(cb: (sp: SqlTx) => Promise<T>): Promise<T>;
+}
+type Row = Record<string, unknown>;
+/** Quote an identifier. Table and column names reach here from the schema and
+ * from handler arguments; neither is allowed to become syntax. */
+declare function quoteIdent(name: string): string;
+/**
+ * A transaction that does not exist until somebody reads or writes.
+ *
+ * `begin(cb)` is callback-scoped, so to hold one open across a whole request
+ * the callback parks on a promise this object controls: `commit()` resolves it
+ * (the driver commits), `rollback()` rejects it (the driver rolls back). A
+ * request that never touches the database never enters the callback at all.
+ */
+declare function createLazyTransaction(sql: SqlDriver, role: string, claimsJson: string, options?: {
+    lockTimeout?: string;
+}): {
+    ensure: () => Promise<SqlTx>;
+    readonly opened: boolean;
+    commit(): Promise<void>;
+    rollback(reason: unknown): Promise<void>;
+};
+type LazyTransaction = ReturnType<typeof createLazyTransaction>;
+/** Either a live driver transaction or the lazy holder above. */
+type TxLike = SqlTx | LazyTransaction;
+/** The six string-keyed operations, plus an interactive `transaction`. */
+declare function createOps(tx: TxLike): {
+    query(sql: string, params?: unknown[]): Promise<Row[]>;
+    insert(table: string, data: Row): Promise<Row>;
+    update(table: string, id: string, data: Row): Promise<Row | null>;
+    delete(table: string, id: string): Promise<void>;
+    findById(table: string, id: string): Promise<Row | null>;
+    findMany(table: string, query?: Row): Promise<Row[]>;
+    /** A real SAVEPOINT inside the request's transaction. */
+    transaction<T>(cb: (t: unknown) => Promise<T>): Promise<T>;
+    /**
+     * 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.
+     */
+    txPlan(plan: TxPlanBody): Promise<TxPlanResponse>;
+};
+/**
+ * Merge the typed `.tables` accessor onto a raw op surface.
+ *
+ * Mirrors what the pod runtime does, including the recursive application to the
+ * transaction callback: without it `tx.tables.rooms.insert(...)` throws
+ * "Cannot read properties of undefined".
+ */
+declare function withTables<T extends ReturnType<typeof createOps>>(ops: T, schema?: {
+    tables?: Record<string, {
+        name?: string;
+    }>;
+}): T & {
+    tables: Record<string, unknown>;
+};
+/** The two transactions a request may hold, and the single `Database` over them. */
+interface RequestDatabase {
+    /** What the engine injects as the request's `Database` singleton. */
+    readonly client: DBClient;
+    /** Commit whatever was opened. Called once, after the handler returns. */
+    commit(): Promise<void>;
+    /** Roll back whatever was opened. Called once, when the handler throws. */
+    rollback(reason: unknown): Promise<void>;
+}
+/**
+ * The `Database` one request sees: RLS-enforced by default, with the
+ * service-role sibling behind `asService()`.
+ *
+ * # Why the sibling cannot ride the request's own transaction
+ *
+ * The role reaches Postgres ONCE, in the BEGIN's bind statement, and it is
+ * transaction-scoped. So a sibling built on the same transaction runs as
+ * `backend_authenticated` no matter what it is called — RLS still filters every
+ * row and `asService()` silently means nothing. That is the failure mode worth
+ * naming: it does not throw, it does not log, it simply returns the caller's own
+ * rows where the author asked for everyone's, and a handler that trusts it
+ * (`if (existing) throw new Conflict()`) makes the wrong decision on data it was
+ * never shown.
+ *
+ * The obvious repair — re-issue `set_config('role', …)` around each service op
+ * — is worse than the bug. Two statements are not one: `Promise.all([
+ * Database.query(…), Database.asService().query(…) ])` interleaves them on the
+ * single connection, and the user's query can execute between the service's
+ * set-role and its own statement. That is RLS silently OFF on the DEFAULT path,
+ * which is precisely the direction a security seam must never fail.
+ *
+ * So the service surface gets its own transaction, on its own connection, bound
+ * to the service role at BEGIN. The identity separation is physical: no
+ * statement of either surface can change what the other runs as.
+ *
+ * # What that costs, stated plainly
+ *
+ * - **One extra connection per request that uses it**, and only then: the second
+ *   transaction is lazy exactly like the first, so `asService()` called and
+ *   never used opens nothing.
+ * - **Called twice, it is the same surface** — one transaction per REQUEST, not
+ *   per call — so a handler cannot leak connections by reaching for it in a
+ *   loop.
+ * - **The two are not atomic with each other.** Both settle with the request
+ *   (commit when the handler returns, roll back when it throws), but they settle
+ *   as two transactions: if the second COMMIT fails, the first has already
+ *   landed. The request's own work commits first, so the failure that survives
+ *   is never "the audit row exists and the thing it audits does not".
+ * - **They can wait on each other's locks.** Bounded in the service direction by
+ *   {@link SERVICE_LOCK_TIMEOUT}; in the other direction — a `Database.*` write
+ *   to a row `asService()` has already written — the wait is the request's own,
+ *   and the answer is not to write one row from both surfaces.
+ *
+ * # Claims travel unchanged
+ *
+ * The service transaction carries the SAME `request.jwt.claims` as the user's.
+ * `asService()` changes what the caller may TOUCH, not who they are, so
+ * `auth.uid()` still resolves inside a trigger or a column default. It is also
+ * the fail-closed direction: a service role provisioned WITHOUT `BYPASSRLS`
+ * (measured live on 2026-08-13, created by hand during a diagnosis) is not named
+ * by any policy, so it reads zero rows instead of quietly reading everyone's.
+ */
+declare function createRequestDatabase(sql: SqlDriver, identity: {
+    role: string;
+    serviceRole: string;
+    claimsJson: string;
+}): RequestDatabase;
+
+interface RouteEntry {
+    method: string;
+    /** Path segments; a parameter segment is stored as `:name`. */
+    segments: string[];
+    meta: RouteMeta;
+    /** The controller instance the method is invoked on. */
+    instance: Record<string, (...args: unknown[]) => unknown>;
+    /** `GET /todos/{id}` — stable, human-readable, used as the rate-limit key. */
+    id: string;
+    /** The controller's `auth` default, if it declared one. */
+    controllerAuth: unknown;
+}
+/**
+ * Build the table from controller classes.
+ *
+ * @throws when a class carries no routes — a controller that collected zero
+ *   endpoints is the silent failure this whole runtime is built to refuse, and
+ *   it must be loud at boot rather than a 404 in production.
+ */
+declare function buildRouteTable(controllers: readonly unknown[]): RouteEntry[];
+interface RouteMatch {
+    entry: RouteEntry;
+    params: Record<string, string>;
+}
+/** First match wins; the table is small and declaration order is the tiebreak. */
+declare function matchRoute(table: readonly RouteEntry[], method: string, pathname: string): RouteMatch | null;
+
+/**
+ * engine/auth.ts — verifying the stack's own access tokens.
+ *
+ * The engine does this itself rather than trusting a header stamped upstream.
+ * In the isolate architecture a gateway verified the token and the runtime read
+ * the result; a backend that boots on its own has no such upstream, so the
+ * verification lives here — against the keys the stack publishes.
+ *
+ * Deliberately narrow: ES256 over P-256, which is what palauth mints. An
+ * unrecognised `alg` is refused rather than accommodated, because the classic
+ * JWT break is a verifier that is helpful about algorithms.
+ */
+/** The claims the engine reads. Everything else rides along untyped. */
+interface VerifiedClaims extends Record<string, unknown> {
+    sub?: string;
+    role?: string;
+    email?: string;
+    email_verified?: boolean;
+    exp?: number;
+    iss?: string;
+}
+interface AuthVerifierOptions {
+    jwksUrl: string;
+    issuer?: string;
+    /** Injectable for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** How long a fetched keyset is trusted before it is fetched again. A key
+     * rotation must become visible without a restart, and an unknown `kid` must
+     * not be able to force a fetch per request (that is a free DoS lever). */
+    keysetTtlMs?: number;
+}
+declare class AuthVerifier {
+    private keys;
+    private fetchedAt;
+    private inflight;
+    private readonly jwksUrl;
+    private readonly issuer?;
+    private readonly fetchImpl;
+    private readonly ttl;
+    constructor(opts: AuthVerifierOptions);
+    /** Fetch the keyset at most once per TTL, and at most once concurrently. */
+    private refresh;
+    private key;
+    /**
+     * 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.
+     */
+    verify(authorization: string | null | undefined): Promise<VerifiedClaims | null>;
+}
+/** What a route demands, after the route's own spec and the controller's
+ * default have been reconciled. */
+interface EffectiveAuth {
+    required: boolean;
+    role?: string;
+    verifiedEmail: boolean;
+}
+/**
+ * Reconcile route-level and controller-level auth.
+ *
+ * The route's own spec wins when it says anything at all; otherwise the
+ * controller's default applies; when NEITHER speaks, the answer is `required`.
+ * That last clause is the whole point — a route that forgot to declare must be
+ * closed, not open. (Measured: an engine that only read the route level served
+ * a controller marked `auth: false` as 401, and would have served the reverse
+ * mistake as an open endpoint.)
+ */
+declare function effectiveAuth(routeAuth: unknown, controllerAuth: unknown): EffectiveAuth;
+
+/**
+ * engine/ratelimit.ts — the customer's own per-route limit, enforced here.
+ *
+ * This is the PRODUCT feature (`@Get("/x", { rateLimit: { max, window } })`),
+ * not a quota the platform imposes. It runs in this process, on this pod,
+ * because the route table lives here: the edge proxies by path and has never
+ * seen a route's options, so teaching it would mean shipping the table twice
+ * and keeping the copies in step.
+ *
+ * Fixed window, in memory. A single-tenant backend is the whole stack rather
+ * than a shard of it, so "in process" is not an approximation. A restart
+ * forgets the window, which for an endpoint guard fails in the right
+ * direction: it forgives, it never invents a refusal.
+ */
+interface RateLimitRule {
+    max: number;
+    /** Seconds. */
+    window: number;
+}
+declare class RateLimiter {
+    private readonly maxKeys;
+    private buckets;
+    /** 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?: number);
+    /**
+     * 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: string, userId: string | undefined, headers: Headers): string;
+    /**
+     * @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: RateLimitRule | undefined, key: string, now: number): number | null;
+    /** Drop expired windows; if none are expired, drop the earliest-resetting
+     * quarter so the map cannot wedge at the ceiling. */
+    private evict;
+    /** Test seam. */
+    get size(): number;
+}
+
+/**
+ * engine/cache.ts — the cache, in this process's own memory.
+ *
+ * A stack that serves one tenant has nobody to share a cache with; palsvc drew
+ * exactly this conclusion for itself when it dropped Redis, and a backend that
+ * reaches over a network for a hash map is paying a round trip for nothing.
+ *
+ * JSON-typed, matching `CacheClient`: values round-trip as whatever was stored.
+ */
+
+interface MemoryCacheOptions {
+    /** Bound on entries held. On overflow the soonest-to-expire are dropped. */
+    maxEntries?: number;
+    /** Injectable clock, for tests. */
+    now?: () => number;
+}
+/**
+ * Build an in-process cache.
+ *
+ * `getOrSet` is single-flight: concurrent misses on one key share one fill, so
+ * a cold key under load does not become N identical expensive calls.
+ */
+declare function makeMemoryCache(opts?: MemoryCacheOptions): CacheClient;
+
+/**
+ * engine/fence.ts — what the tenant's own code may reach.
+ *
+ * The isolate used to answer this by construction: tenant code ran in a realm
+ * with no ambient network and an environment scrubbed of every secret, and each
+ * privileged call hopped to a host that held the credentials. Running the
+ * backend as one process removes that wall, so the two guarantees it carried
+ * have to be re-made here — deliberately, and with the honest note that a
+ * same-process fence is a SPEED BUMP against the tenant's own code, not a
+ * sandbox. The real boundary is the machine: each tenant has its own.
+ *
+ * That is not a hole, it is a scope. The tenant owns this database and this
+ * network namespace; the thing worth preventing is an ACCIDENT — a dependency
+ * that reads `process.env` and posts it somewhere, a handler that opens its own
+ * unscoped connection and quietly serves every user's rows — not a determined
+ * operator attacking their own stack.
+ */
+interface ScrubResult {
+    removed: string[];
+    kept: string[];
+}
+/**
+ * Delete the engine's own credentials from `process.env`.
+ *
+ * MUST run AFTER the config is read and BEFORE the tenant bundle is imported —
+ * a bundle's module-level code runs at import, so a scrub that comes later has
+ * already lost the race.
+ *
+ * The tenant's OWN variables (`PALBASE_VAR_*` and anything else) are untouched:
+ * this removes what the platform put there, not what the operator did.
+ *
+ * Why RLS makes this matter: the engine binds every request to the caller with
+ * `set_config('role', …)` so Postgres does the row filtering. Code that finds
+ * `DATABASE_URL` can open its own connection as the owner and read every user's
+ * rows — not by attacking anything, just by using a driver.
+ */
+declare function scrubSecrets(env: Record<string, string | undefined>): ScrubResult;
+interface EgressPolicy {
+    /** Hostnames the tenant declared. Empty ⇒ no declaration was made. */
+    allow: readonly string[];
+    /** Per-call ceiling in ms. 0 ⇒ no ceiling declared. */
+    timeoutMs: number;
+    /** What to do when nothing was declared. */
+    whenUndeclared: "allow" | "deny";
+    /**
+     * Hosts the BACKEND ITSELF needs: its module surface, the JWKS it verifies
+     * tokens against, the artifact store it reloads from.
+     *
+     * These are not egress. `config/egress.ts` declares where the tenant's own
+     * code may reach; a call to the platform this backend is part of is internal
+     * traffic, and fencing it means the first deploy with an allowlist takes the
+     * backend down — which is exactly what happened when this list did not exist:
+     * every request 500'd with "egress denied: palsvc is not in this backend's
+     * declared allowlist", and the artifact reload loop stopped with it.
+     */
+    alwaysAllow?: readonly string[];
+}
+/** `api.stripe.com` matches itself; `*.stripe.com` matches any subdomain. */
+declare function hostAllowed(host: string, allow: readonly string[]): boolean;
+/**
+ * Install the tenant's declared outbound allowlist over `globalThis.fetch`.
+ *
+ * The engine's own traffic is exempted by HOST (`alwaysAllow`), not by holding
+ * a captured reference: the module clients and the verifier resolve
+ * `globalThis.fetch` at CALL time, so a captured original never reaches them.
+ * That distinction is not academic — the first version of this file claimed the
+ * capture worked, and every request 500'd on the first deploy that declared an
+ * allowlist.
+ *
+ * @returns the original fetch, for the engine's own use.
+ */
+declare function installEgressFence(policy: EgressPolicy): typeof fetch;
+
+/**
+ * engine/index.ts — the engine: a backend that boots itself.
+ *
+ * `createApp` turns a set of `@Controller` classes into a `fetch(Request)`
+ * handler. No V8 isolate, no capability hop: this process owns its database
+ * pool, verifies its own tokens, applies its own rate limits, and calls the
+ * modules directly.
+ *
+ *   import { createApp, loadConfig } from "@palbase/backend/engine";
+ *
+ *   const app = await createApp({
+ *     config: loadConfig(process.env),
+ *     controllers: [TodosController],
+ *     schema,
+ *   });
+ *   Bun.serve({ port: app.config.port, fetch: app.handle });
+ *
+ * The Web-standard `fetch` signature is the point: the same handler runs under
+ * Bun, Deno and any host that speaks Request/Response, so "works locally" and
+ * "works in the cloud" are the same code path rather than two.
+ */
+
+/** The `__`-prefixed request-scope seam, as re-exported by a deployed bundle. */
+interface RuntimeHooks {
+    __runWithRuntime: typeof __runWithRuntime;
+    __requestALS: typeof __requestALS;
+}
+/** The module singletons the engine injects, minus the two it owns itself. */
+type ModuleClients = Partial<Pick<RuntimeServices, "Documents" | "Storage" | "Notifications" | "Flags" | "Realtime" | "Purchases" | "Secrets">>;
+interface CreateAppOptions {
+    config: EngineConfig;
+    /** `@Controller` classes. A class that collected zero routes is fatal. */
+    controllers: readonly unknown[];
+    /** The project's `defineSchema()` result, for the typed `.tables` surface. */
+    schema?: unknown;
+    /** The SQL driver. Omitted ⇒ built from `Bun.sql` when running under Bun. */
+    sql?: SqlDriver;
+    /** Module clients. Omitted ⇒ each corresponding singleton throws when used. */
+    modules?: ModuleClients;
+    /** Cache. Omitted ⇒ this process's own memory. */
+    cache?: CacheClient;
+    /**
+     * The request-scope hooks to run handlers inside.
+     *
+     * MUST come from the SAME `@palbase/backend` module instance the loaded
+     * controllers were bundled against. A deployed bundle inlines its own copy of
+     * the SDK and re-exports these two; the engine here has its own. Two copies
+     * mean two AsyncLocalStorage instances, and the store this engine sets is not
+     * the store the handler's `Database` proxy reads — every service would be
+     * undefined at the first call, with nothing in the logs to say why. So the
+     * host passes the BUNDLE's hooks and the seam closes.
+     *
+     * Omitted ⇒ this module's own, which is correct only when the controllers
+     * were built against this same instance (tests, a single-package project).
+     */
+    runtimeHooks?: RuntimeHooks;
+    logger?: Pick<Console, "info" | "warn" | "error" | "debug">;
+}
+interface App {
+    handle: (req: Request) => Promise<Response>;
+    routes: readonly RouteEntry[];
+    config: EngineConfig;
+    /** Close the pool and release resources. */
+    shutdown: () => Promise<void>;
+}
+/**
+ * Build the app. Fails fast: the database is reached here, at boot, rather than
+ * on the first request that needs it.
+ */
+declare function createApp(opts: CreateAppOptions): Promise<App>;
+
+export { type App as A, BootRefused as B, Cache as C, Database as D, type EgressPolicy as E, Flags as F, effectiveAuth as G, hostAllowed as H, installEgressFence as I, loadConfig as J, makeMemoryCache as K, type LimitState as L, type ModuleClients as M, Notifications as N, matchRoute as O, Purchases as P, quoteIdent as Q, Realtime as R, Secrets as S, scrubSecrets as T, withTables as U, __getRuntime as _, Documents as a, Log as b, type PurchasesService as c, type RequestStore as d, type RuntimeServices as e, type SpendOptions as f, Storage as g, type StoreEnv as h, __requestALS as i, __runWithRuntime as j, __setRuntime as k, AuthVerifier as l, type CreateAppOptions as m, type EngineConfig as n, RateLimiter as o, type RequestDatabase as p, type RouteEntry as q, type RuntimeHooks as r, type ScrubResult as s, type SqlDriver as t, type SqlTx as u, buildRouteTable as v, createApp as w, createLazyTransaction as x, createOps as y, createRequestDatabase as z };