@palbase/backend 17.4.0 → 18.0.1

package/dist/index.d.ts

@@ -1,245 +1,16 @@
-import { C as CacheClient, E as EnvTypedDatabase, P as PalbaseDocsClient, a as PalbaseFlagsClient, L as Logger, b as PalbaseNotificationsClient, c as PalbaseRealtimeClient, D as DBClient, d as PalbaseStorageClient, S as SchemaDef, A as AuthSpec, R as RateLimitConfig, H as HttpError } from './index-VLrU7rSW.js';
-export { e as AuthConfig, B as BadRequest, f as ClientInfo, g as ColumnBuilder, h as ColumnDef, i as ColumnMap, j as ColumnType, k as Conflict, l as DBOps, m as EXTENSION_DEPENDENCIES, n as EnvServiceDatabase, o as EnvTables, p as EnvTypedTable, q as ErrorDef, r as ErrorMap, s as ErrorThrowers, F as FileContext, t as Forbidden, u as HttpMethod, I as InsertShape, M as Materialized, v as Middleware, w as MiddlewareContext, x as MiddlewareHandler, N as NotFound, O as OnDeleteAction, y as PALBASE_EXTENSIONS, z as PBRequest, G as PalError, J as PalbaseAnalyticsClient, K as PalbaseAnalyticsManagementNamespace, Q as PalbaseAnalyticsProperties, T as PalbaseAnalyticsQueryNamespace, U as PalbaseAttestAndroidParams, V as PalbaseAttestAndroidResult, W as PalbaseAttestiOSParams, X as PalbaseAttestiOSResult, Y as PalbaseAuthClient, Z as PalbaseBatchOverrideOperation, _ as PalbaseBatchSetOverridesResult, $ as PalbaseBindDeviceParams, a0 as PalbaseBucketClient, a1 as PalbaseClearAllOverridesResult, a2 as PalbaseClearOverrideResult, a3 as PalbaseCohortQueryInput, a4 as PalbaseCohortResult, a5 as PalbaseCollectionRef, a6 as PalbaseCountQueryInput, a7 as PalbaseCountResult, a8 as PalbaseCreateLinkParams, a9 as PalbaseDeviceInfo, aa as PalbaseDeviceTokenView, ab as PalbaseDocumentRef, ac as PalbaseDocumentSnapshot, ad as PalbaseEmailClient, ae as PalbaseEmailSendParams, af as PalbaseEmailSendResponse, ag as PalbaseEventNamesResult, ah as PalbaseEventsQueryInput, ai as PalbaseEventsResult, aj as PalbaseExtension, ak as PalbaseFileObject, al as PalbaseFlag, am as PalbaseFlagContext, an as PalbaseFlagSource, ao as PalbaseFlagValue, ap as PalbaseFlagVariant, aq as PalbaseFlagsServiceClient, ar as PalbaseFunctionsClient, as as PalbaseFunnelQueryInput, at as PalbaseFunnelResult, au as PalbaseIdentifyTraits, av as PalbaseInboxClient, aw as PalbaseInboxListOptions, ax as PalbaseInboxListResult, ay as PalbaseInboxMessage, az as PalbaseInboxSendParams, aA as PalbaseInboxSendResponse, aB as PalbaseInitialLink, aC as PalbaseInvokeOptions, aD as PalbaseLink, aE as PalbaseLinkAnalytics, aF as PalbaseLinkDetails, aG as PalbaseLinksClient, aH as PalbaseListLinksOptions, aI as PalbaseListLinksResult, aJ as PalbaseListOptions, aK as PalbaseMatchParams, aL as PalbaseMultiChannelResponse, aM as PalbaseOverviewResult, aN as PalbasePreferences, aO as PalbasePreferencesClient, aP as PalbasePushClient, aQ as PalbasePushSendParams, aR as PalbasePushSendResponse, aS as PalbaseQrCodeOptions, aT as PalbaseQuerySnapshot, aU as PalbaseRegisterDeviceParams, aV as PalbaseResult, aW as PalbaseRetentionQueryInput, aX as PalbaseRetentionResult, aY as PalbaseSession, aZ as PalbaseSetOverrideResult, a_ as PalbaseSetOverridesResult, a$ as PalbaseSignedUrlResponse, b0 as PalbaseSmsClient, b1 as PalbaseSmsSendParams, b2 as PalbaseSmsSendResponse, b3 as PalbaseTransformOptions, b4 as PalbaseUpdateLinkParams, b5 as PalbaseUploadOptions, b6 as PalbaseUser, b7 as PalbaseUserDetailResult, b8 as PalbaseUsersQueryInput, b9 as PalbaseUsersResult, ba as PalbaseVerifyRequestSignatureParams, bb as PalbaseWhereOperator, bc as PolicyBuilder, bd as PolicyCommand, be as PolicyDef, bf as PolicyMode, bg as RawConstraintDef, bh as Ref, bi as RowShape, bj as SchemaInput, bk as TableDef, bl as TableInput, bm as TooManyRequests, bn as TxColumnExpr, bo as TxInsertShape, bp as TxInsertValue, bq as TxNow, br as TxPlan, bs as TxPlanBody, bt as TxPlanError, bu as TxPlanHandle, bv as TxPlanOpResult, bw as TxPlanRejection, bx as TxPlanResponse, by as TxRefError, bz as TxRow, bA as TxRows, bB as TxSelectOptions, bC as TxSetShape, bD as TxSetValue, bE as TxTable, bF as TxTables, bG as TxWhere, bH as TxWireExpr, bI as TxWireGuard, bJ as TxWireOp, bK as TxWireRef, bL as TxWireValue, bM as TypedDB, bN as TypedTable, bO as TypedTx, bP as Unauthorized, bQ as UserT, bR as VerifiedDevice, bS as bigint, bT as boolean, bU as dec, bV as defineMiddleware, bW as defineSchema, bX as enumType, bY as inc, bZ as integer, b_ as isPalbaseExtension, b$ as jsonb, c0 as makeTypedDB, c1 as now, c2 as numeric, c3 as policy, c4 as raw, c5 as text, c6 as timestamp, c7 as uuid } from './index-VLrU7rSW.js';
-import { AsyncLocalStorage } from 'node:async_hooks';
+import { g as PalbaseResult, A as AuthSpec, H as HttpError } from './endpoint-B0LpZixz.js';
+export { h as AuthConfig, B as BadRequest, C as CacheClient, i as ClientInfo, j as Conflict, D as DBClient, k as DBOps, E as ErrorDef, l as ErrorMap, m as ErrorThrowers, F as FileContext, n as Forbidden, o as HttpMethod, L as Logger, M as Materialized, p as Middleware, q as MiddlewareContext, r as MiddlewareHandler, N as NotFound, s as PBRequest, t as PalError, u as PalbaseAnalyticsClient, v as PalbaseAnalyticsManagementNamespace, w as PalbaseAnalyticsProperties, x as PalbaseAnalyticsQueryNamespace, y as PalbaseAttestAndroidParams, z as PalbaseAttestAndroidResult, G as PalbaseAttestiOSParams, I as PalbaseAttestiOSResult, J as PalbaseAuthClient, K as PalbaseBatchOverrideOperation, O as PalbaseBatchSetOverridesResult, Q as PalbaseBindDeviceParams, e as PalbaseBucketClient, U as PalbaseClearAllOverridesResult, V as PalbaseClearOverrideResult, W as PalbaseCohortQueryInput, X as PalbaseCohortResult, Y as PalbaseCollectionRef, Z as PalbaseCountQueryInput, _ as PalbaseCountResult, $ as PalbaseCreateLinkParams, a0 as PalbaseDeviceInfo, a1 as PalbaseDeviceTokenView, P as PalbaseDocsClient, a2 as PalbaseDocumentRef, a3 as PalbaseDocumentSnapshot, a4 as PalbaseEmailClient, a5 as PalbaseEmailSendParams, a6 as PalbaseEmailSendResponse, a7 as PalbaseEventNamesResult, a8 as PalbaseEventsQueryInput, a9 as PalbaseEventsResult, aa as PalbaseFileObject, ab as PalbaseFlag, ac as PalbaseFlagContext, ad as PalbaseFlagSource, ae as PalbaseFlagValue, af as PalbaseFlagVariant, a as PalbaseFlagsClient, ag as PalbaseFlagsServiceClient, ah as PalbaseFunctionsClient, ai as PalbaseFunnelQueryInput, aj as PalbaseFunnelResult, ak as PalbaseIdentifyTraits, al as PalbaseInboxClient, am as PalbaseInboxListOptions, an as PalbaseInboxListResult, ao as PalbaseInboxMessage, ap as PalbaseInboxSendParams, aq as PalbaseInboxSendResponse, ar as PalbaseInitialLink, as as PalbaseInvokeOptions, at as PalbaseLink, au as PalbaseLinkAnalytics, av as PalbaseLinkDetails, aw as PalbaseLinksClient, ax as PalbaseListLinksOptions, ay as PalbaseListLinksResult, az as PalbaseListOptions, aA as PalbaseMatchParams, aB as PalbaseMultiChannelResponse, b as PalbaseNotificationsClient, aC as PalbaseOverviewResult, aD as PalbasePreferences, aE as PalbasePreferencesClient, aF as PalbasePushClient, aG as PalbasePushSendParams, aH as PalbasePushSendResponse, aI as PalbaseQrCodeOptions, aJ as PalbaseQuerySnapshot, c as PalbaseRealtimeClient, aK as PalbaseRegisterDeviceParams, aL as PalbaseRetentionQueryInput, aM as PalbaseRetentionResult, aN as PalbaseSession, aO as PalbaseSetOverrideResult, aP as PalbaseSetOverridesResult, aQ as PalbaseSignedUrlResponse, aR as PalbaseSmsClient, aS as PalbaseSmsSendParams, aT as PalbaseSmsSendResponse, d as PalbaseStorageClient, aU as PalbaseTransformOptions, aV as PalbaseUpdateLinkParams, aW as PalbaseUploadOptions, aX as PalbaseUser, aY as PalbaseUserDetailResult, aZ as PalbaseUsersQueryInput, a_ as PalbaseUsersResult, a$ as PalbaseVerifyRequestSignatureParams, b0 as PalbaseWhereOperator, R as RateLimitConfig, b1 as Ref, S as SecretsService, b2 as TooManyRequests, b3 as TxColumnExpr, b4 as TxInsertShape, b5 as TxInsertValue, b6 as TxNow, T as TxPlanBody, b7 as TxPlanError, b8 as TxPlanHandle, b9 as TxPlanOpResult, ba as TxPlanRejection, f as TxPlanResponse, bb as TxRefError, bc as TxRow, bd as TxRows, be as TxSelectOptions, bf as TxSetShape, bg as TxSetValue, bh as TxTable, bi as TxWhere, bj as TxWireExpr, bk as TxWireGuard, bl as TxWireOp, bm as TxWireRef, bn as TxWireValue, bo as Unauthorized, bp as UserT, bq as VerifiedDevice, br as dec, bs as defineMiddleware, bt as inc, bu as now } from './endpoint-B0LpZixz.js';
+import { M as ModuleClients } from './index-DZDUMth5.js';
+export { C as Cache, D as Database, a as Documents, F as Flags, L as LimitState, b as Log, N as Notifications, P as Purchases, c as PurchasesService, R as Realtime, d as RequestStore, e as RuntimeServices, S as Secrets, f as SpendOptions, g as Storage, h as StoreEnv, _ as __getRuntime, i as __requestALS, j as __runWithRuntime, k as __setRuntime } from './index-DZDUMth5.js';
 import { EntitlementKey, LimitKey } from './purchases/keys.js';
+import { S as SchemaDef } from './index-g-EzitI-.js';
+export { C as ColumnBuilder, a as ColumnDef, b as ColumnMap, c as ColumnType, d as EXTENSION_DEPENDENCIES, e as EnvServiceDatabase, f as EnvTables, E as EnvTypedDatabase, g as EnvTypedTable, I as InsertShape, O as OnDeleteAction, P as PALBASE_EXTENSIONS, h as PalbaseExtension, i as PolicyBuilder, j as PolicyCommand, k as PolicyDef, l as PolicyMode, R as RawConstraintDef, m as RowShape, n as SchemaInput, T as TableDef, o as TableInput, p as TxPlan, q as TxTables, r as TypedDB, s as TypedTable, t as TypedTx, u as bigint, v as boolean, w as defineSchema, x as enumType, y as integer, z as isPalbaseExtension, A as jsonb, B as makeTypedDB, D as numeric, F as policy, G as raw, H as text, J as timestamp, K as uuid } from './index-g-EzitI-.js';
 import { TableTypes, Tables } from './db/env.js';
+import { a as RouteOptions } from './registry-3BLYv4si.js';
+export { B as BucketDef, b as BucketOptions, H as HttpMethodUpper, I as ImageVariant, c as ParamKind, P as ParamMeta, R as RouteMeta, S as STORAGE_CONFIG_KIND, d as StorageConfig, e as StorageInput, T as ThrowDescriptor, f as Upload, U as UploadConfig, g as UploadedObject, h as bucket, i as defineStorage, j as getRoutes, p as parseFileSizeLimit, r as recordThrows, v as validateUploadAgainstStorage } from './registry-3BLYv4si.js';
 import { ZodTypeAny, z } from 'zod';
 export { z } from 'zod';
-
-/**
- * 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;
-    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;
-/** Object storage client (buckets, signed URLs). */
-declare const Storage: PalbaseStorageClient;
-/** JSON-typed cache (get/set/incr/getOrSet). */
-declare const Cache: CacheClient;
-/** 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;
+import 'node:async_hooks';
 
 /**
  * `@RequireEntitlement` and `@Spend` — access and metering at the decorator
@@ -260,7 +31,7 @@ declare const Realtime: PalbaseRealtimeClient;
  * decorators cannot introduce it.
  */
 
-type MethodDecorator$2 = (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+type MethodDecorator$1 = (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
 /**
  * Require an active entitlement. Answers 403 `entitlement_required` when it is
  * absent and consumes nothing.
@@ -268,7 +39,7 @@ type MethodDecorator$2 = (target: object, propertyKey: string | symbol, descript
  * The key is a member of the generated `EntitlementKey` union, so a typo is a
  * compile error rather than a gate that silently never matches.
  */
-declare function RequireEntitlement(key: EntitlementKey): MethodDecorator$2;
+declare function RequireEntitlement(key: EntitlementKey): MethodDecorator$1;
 /**
  * Consume one unit of a limit or credit for the request's subject.
  *
@@ -281,7 +52,115 @@ declare function RequireEntitlement(key: EntitlementKey): MethodDecorator$2;
  * side-effect, which is an explicit `Purchases.withSpend(...)` call, not a
  * decorator.
  */
-declare function Spend(key: LimitKey): MethodDecorator$2;
+declare function Spend(key: LimitKey): MethodDecorator$1;
+
+/**
+ * clients/index.ts — the composition root for the module clients.
+ *
+ * This is what the process calls once at boot. It builds the five clients the
+ * engine injects and nothing else.
+ *
+ * WHAT IS NOT BUILT HERE, and why each one is absent rather than forgotten:
+ *
+ *   - `auth`, `functions`, `analytics`, `links` — the SDK exports no singleton
+ *     for any of them (`runtime.ts` exports ten, and these four are not among
+ *     them), so no handler could reach them. They were constructed on every
+ *     boot and thrown away.
+ *   - `Purchases` — its client talks to palstore, and v2 contains no palstore
+ *     at all. The surface was unbacked before it was untyped. Dropped from v2
+ *     by the user's decision on 2026-08-15; the SDK's `src/purchases/` tree is
+ *     untouched and that decision is deferred, not silently taken.
+ *   - The V1 host/executor transport — the isolate it existed for was removed
+ *     on 2026-08-14. A single-tenant process has nobody to hide its own
+ *     tenant's credentials from.
+ */
+
+interface ModuleClientsConfig {
+    /** Where the platform answers. Empty means "not configured" — see below. */
+    baseUrl: string;
+    /** The publishable key. Used only when no service-role key is supplied. */
+    apiKey: string;
+    /**
+     * The service-role key, which is what a backend actually holds. Preferred
+     * over `apiKey`: this process IS the project's server.
+     */
+    serviceRoleKey: string;
+    /** The shared Realtime secret. Empty means realtime is not provisioned. */
+    realtimeApiJwtSecret: string;
+    /** The request's user, read from the SDK's own scope — never from a caller. */
+    getCurrentUserId: () => string | null;
+    /** Injected in tests; resolved at call time in production. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Build the module clients.
+ *
+ * Returns an EMPTY bundle when there is no base URL, deliberately: the engine
+ * then injects its named stubs, so a handler that reaches for `Storage` gets an
+ * error saying which module is unconfigured rather than a crash reading a
+ * property of undefined. Booting is not blocked — a project that never touches
+ * a module runs fine without one.
+ */
+declare function buildModuleClients(cfg: ModuleClientsConfig): ModuleClients;
+
+/**
+ * http.ts — the transport every module client speaks over.
+ *
+ * WHY IT IS HERE. This code, and the five clients built on it, spent their life
+ * in `v2/runtime/internal/runtime/module-clients.js`: 1,768 lines of untyped
+ * CommonJS that entered the SDK through an `@ts-expect-error` and left through
+ * `unknown` casts. The interfaces those clients implement were always in this
+ * package — only the implementations were outside it, where nothing checked one
+ * against the other. Two defects came through that gap on 2026-08-15 (a type
+ * that described a different server's columns; an accessor that was `undefined`
+ * in a deployed handler), and both were green on each side alone.
+ *
+ * WHAT IT IS NOT. Nothing Bun-specific lives here. The transport is a `fetch`
+ * the caller may supply, so this package stays runtime-agnostic and the process
+ * that knows which runtime it is decides what to hand in.
+ */
+
+/** Per-request options a module client may pass. */
+interface RequestOptions {
+    /** JSON-serialised unless it is a string, a Uint8Array, a Blob or FormData. */
+    body?: unknown;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+/**
+ * What a module client is given. An INTERFACE rather than a class, because the
+ * clients depend on this shape and not on the thing that implements it — which
+ * is what lets a test drive a whole client without a server.
+ */
+interface ModuleTransport {
+    /** The platform's base URL, for the rare client that must build a URL. */
+    readonly baseUrl: string;
+    request<T = unknown>(method: string, path: string, options?: RequestOptions): Promise<PalbaseResult<T>>;
+}
+interface TransportConfig {
+    baseUrl: string;
+    apiKey: string;
+    /**
+     * The `fetch` to use. Omitted means the ambient one — resolved at CALL time,
+     * never captured here: the egress fence replaces `globalThis.fetch` after the
+     * clients are built, and a captured reference would keep calling the
+     * un-fenced original.
+     */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * A module call that failed.
+ *
+ * `code` is the platform's own error code (`forbidden`, `not_found`, …) so a
+ * caller can branch on it without matching message text.
+ */
+declare class PalbaseModuleError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details: Record<string, unknown>;
+    constructor(code: string, message: string, status: number, details?: Record<string, unknown>);
+}
+declare function makeHttpClient(cfg: TransportConfig): ModuleTransport;
 
 /**
  * keys-gen.ts — generate the `palbase-purchases.d.ts` text from a catalog
@@ -350,6 +229,72 @@ declare function entitlementFor(ctor: object, fnName: string): EntitlementKey |
 /** What `fnName` spends, or undefined when it spends nothing. */
 declare function spendFor(ctor: object, fnName: string): SpendMeta | undefined;
 
+/** One column, flattened. Mirrors Go's `schema.ColumnJSON`. */
+interface ColumnJSON {
+    type: string;
+    nullable: boolean;
+    primaryKey: boolean;
+    defaultValue?: unknown;
+    defaultRandom?: boolean;
+    defaultNow?: boolean;
+    renamedFrom?: string;
+    references?: {
+        table: string;
+        column: string;
+    };
+    onDeleteAction?: string;
+    enumName?: string;
+    enumValues?: string[];
+    unique?: boolean;
+}
+/** One RLS policy. Mirrors Go's `schema.PolicyJSON`. */
+interface PolicyJSON {
+    name: string;
+    command: string;
+    roles: string[];
+    using: string | null;
+    withCheck: string | null;
+    permissive: boolean;
+}
+/** One table. Mirrors Go's `schema.TableJSON`. */
+interface TableJSON {
+    name: string;
+    columns: Record<string, ColumnJSON>;
+    rls: boolean;
+    policies: PolicyJSON[];
+    primaryKey?: string[];
+    uniqueConstraints?: {
+        name: string;
+        columns: string[];
+    }[];
+    rawConstraints?: {
+        name: string;
+        up: string;
+        down: string | null;
+    }[];
+    checks?: {
+        name: string;
+        expr: string;
+    }[];
+    indexes?: {
+        name: string;
+        columns: string[];
+    }[];
+}
+/** A whole declaration. Mirrors Go's `schema.SchemaJSON`. */
+interface SchemaJSON {
+    tables: Record<string, TableJSON>;
+    extensions: string[];
+}
+/**
+ * Serialize a `defineSchema(...)` result into the JSON the deploy applies.
+ *
+ * Keyed by the SQL table name rather than by the author's object key, because
+ * that is the name the live database answers to — and the diff on the other side
+ * compares against what it introspected.
+ */
+declare function toSchemaJSON(schema: SchemaDef): SchemaJSON;
+
 /**
  * env-gen.ts — generate the `palbase-env.d.ts` text from a `defineSchema()`
  * result.
@@ -376,143 +321,6 @@ declare function spendFor(ctor: object, fnName: string): SpendMeta | undefined;
  */
 declare function makeEnvDts(schema: SchemaDef): string;
 
-/**
- * storage.ts — the storage-buckets config-as-code DSL.
- *
- * `defineStorage({ buckets })` is the first MODULE config-as-code surface (the
- * sibling of `db/schema.ts`'s `defineSchema`). A `config/storage.ts` file
- * default-exports a `defineStorage(...)` result; on deploy the br-pod evaluates
- * it to JSON and reconciles the declared buckets against the tenant's live
- * buckets via the Storage admin API (create missing, update changed; never
- * auto-delete — dropping a bucket is destructive and warned only).
- *
- * Buckets are DECLARATIVE: name + access + size/mime limits. The FILES inside a
- * bucket are runtime state (uploaded via the SDK), never in git.
- *
- * @example
- * import { defineStorage, bucket } from "@palbase/backend";
- *
- * export default defineStorage({
- *   buckets: {
- *     avatars: bucket({
- *       public: true,
- *       fileSizeLimit: "5MB",
- *       allowedMimeTypes: ["image/png", "image/jpeg", "image/webp"],
- *     }),
- *     invoices: bucket({
- *       public: false,
- *       fileSizeLimit: "20MB",
- *       allowedMimeTypes: ["application/pdf"],
- *     }),
- *   },
- * });
- *
- * The returned value is the EXACT JSON shape the runtime's generic config
- * extractor (`config_extract.js`) emits and the Go apply step parses:
- *   { __config: "storage", buckets: { avatars: { public, fileSizeLimit, allowedMimeTypes }, ... } }
- * `fileSizeLimit` is always normalized to a number of bytes (or null when
- * omitted, meaning "no limit"); the apply step maps it to the Storage API's
- * `file_size_limit` field. `allowedMimeTypes` is the allowlist or null (any).
- */
-/** The discriminant written under `__config` so the eval/apply can tell which
- * module config a `config/*.ts` file describes. Storage is `"storage"`. */
-declare const STORAGE_CONFIG_KIND: "storage";
-/**
- * The author-facing options for a single bucket.
- *
- * - `public`: when true the bucket is served without a signed URL. Defaults to
- *   `false` (private — signed URLs only).
- * - `fileSizeLimit`: the per-object upload cap. Accepts a human string
- *   (`"5MB"`, `"20MB"`, `"1GB"`) or a bare number of BYTES. Omit for no limit.
- * - `allowedMimeTypes`: an allowlist of MIME types accepted on upload. Omit to
- *   allow any type. Each entry must look like `type/subtype` (e.g. `image/png`,
- *   `application/pdf`, or a wildcard `image/*`).
- */
-interface BucketOptions {
-    public?: boolean;
-    fileSizeLimit?: string | number;
-    allowedMimeTypes?: string[];
-    variants?: Record<string, ImageVariant>;
-}
-/**
- * One named rendition of an uploaded image — the same three knobs
- * `getPublicUrl(path, ...)` takes, given a name so the size lives with the
- * bucket instead of being retyped at every call site.
- *
- * At least one of `width` / `height` must be set (a variant that resizes
- * nothing and converts nothing is a typo, not a variant).
- */
-interface ImageVariant {
-    width?: number;
-    height?: number;
-    format?: "webp" | "avif" | "jpeg" | "png";
-}
-/**
- * The compiled, serializable bucket definition — the EXACT shape emitted to
- * JSON and consumed by the Go apply step.
- *
- * - `public`: always present (defaulted to `false`).
- * - `fileSizeLimit`: bytes as a number, or `null` for "no limit".
- * - `allowedMimeTypes`: the MIME allowlist, or `null` for "any type".
- */
-interface BucketDef {
-    public: boolean;
-    fileSizeLimit: number | null;
-    allowedMimeTypes: string[] | null;
-    /** Named renditions, or `null` when none are declared. Rendered on request by
-     * the image-transform route and cached — nothing extra is stored. */
-    variants: Record<string, ImageVariant> | null;
-}
-/** A storage config definition: the discriminant + a map of bucket name →
- * {@link BucketDef}. This is the value `defineStorage` returns and the runtime
- * config extractor serializes. */
-interface StorageConfig {
-    __config: typeof STORAGE_CONFIG_KIND;
-    buckets: Record<string, BucketDef>;
-}
-/** The author-facing input to `defineStorage`: a `buckets` map whose keys are
- * the bucket names and whose values are `bucket({...})` builders. */
-interface StorageInput {
-    buckets: Record<string, BucketDef>;
-}
-/**
- * Parse a `fileSizeLimit` into a number of bytes.
- *
- * - A bare number is taken as bytes verbatim (must be a non-negative integer).
- * - A string is `<number><unit>` (e.g. `"5MB"`, `"1.5GB"`, `"500kb"`); the unit
- *   is case-insensitive and optional (a bare numeric string = bytes). Binary
- *   units (1 MB = 1024 squared bytes) to match the Storage module's parser.
- *
- * Throws on a negative value, a non-finite number, or an unrecognized unit so a
- * bad limit fails at config-author time, not silently at deploy.
- */
-declare function parseFileSizeLimit(input: string | number): number;
-/**
- * Define a single bucket. The bucket NAME is supplied by the key in
- * `defineStorage({ buckets: { <name>: bucket({...}) } })`, so `bucket()` takes
- * only the options.
- *
- * Validates eagerly (at config-author time):
- *  - `fileSizeLimit` parses to a valid non-negative byte count.
- *  - each `allowedMimeTypes` entry is a `type/subtype` MIME string.
- *
- * Returns a normalized {@link BucketDef}: `public` defaulted to `false`,
- * `fileSizeLimit` as bytes-or-null, `allowedMimeTypes` deduped-or-null.
- */
-declare function bucket(opts?: BucketOptions): BucketDef;
-/**
- * Define the storage config for a project. The bucket NAME comes from each
- * object key (authors never repeat the name). Returns the discriminated
- * {@link StorageConfig} the runtime config extractor serializes and the Go
- * apply step reconciles.
- *
- * @example
- * export default defineStorage({
- *   buckets: { avatars: bucket({ public: true, fileSizeLimit: "5MB" }) },
- * });
- */
-declare function defineStorage(input: StorageInput): StorageConfig;
-
 /**
  * egress.ts — the tenant outbound-HTTP allowlist config-as-code DSL.
  *
@@ -1344,180 +1152,130 @@ declare function flag(opts: FlagOptions): FlagDef;
  */
 declare function defineFlags(input: FlagsInput): FlagsConfig;
 
-/** Options accepted by `@Controller`. */
-interface ControllerOptions {
-    /** Default auth for ALL routes in this controller (route-level overrides). */
-    auth?: AuthSpec;
-}
 /**
- * Mark a class as a Palbase backend controller. `basePath` is the mount path
- * for every route the class declares; `options.auth` sets the controller-level
- * default auth (a route's own `auth` overrides it; absent ⇒ secure-by-default).
+ * secrets.ts — the tenant SECRET REQUIREMENT config-as-code DSL.
+ *
+ * `defineSecrets({ secrets: [secret("NEO4J_PASSWORD")] })` declares WHICH secrets
+ * a backend needs to run. It declares the requirement, never the value: the value
+ * lives only in the vault, and nothing in this file — or in the repo it is
+ * committed to — ever holds one.
+ *
+ * The gap it closes: today a backend's dependence on a secret is written nowhere
+ * except inside the code that reads it (`process.env.NEO4J_PASSWORD`). Deploy a
+ * project into an environment where that secret was never set and the build
+ * passes, the pod starts, and the failure surfaces as a 500 on the first request
+ * that touches it — measured on todoapp, whose `/graph/*` routes returned 500 for
+ * exactly this reason. With the requirement declared, it travels WITH the code:
+ * `push` compares this list against the environment's vault and refuses the
+ * deploy, naming the missing secret, before anything ships.
  *
  * @example
- * \@Controller("/todos", { auth: false })
- * export class TodosController {
- *   \@Get("") list(\@QueryParams(ListTodosQuery) q: ListTodosQuery): TodoSchema[] { … }
- * }
- */
-declare function Controller(basePath: string, options?: ControllerOptions): <T extends abstract new (...args: never[]) => object>(ctor: T) => T;
-
-/** A legacy method decorator (`experimentalDecorators`): `(prototype, name,
- * descriptor)`. */
-type MethodDecorator$1 = (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
-/** A legacy parameter decorator: `(prototype, name, paramIndex)`. */
-type ParameterDecorator$1 = (target: object, propertyKey: string | symbol, parameterIndex: number) => void;
-/**
- * Direct-storage upload settings for an `@Upload` route. The br-pod validates an
- * authorize request against these (size/type), then mints a signed upload URL
- * that PINS the limits so storage itself rejects an over-limit / wrong-type PUT
- * — the client cannot exceed what it declared.
+ *   // config/secrets.ts
+ *   import { defineSecrets, secret } from "@palbase/backend";
+ *   export default defineSecrets({
+ *     secrets: [
+ *       secret("NEO4J_PASSWORD", { description: "graph store password" }),
+ *       secret("SENTRY_DSN", { required: false, description: "crash reporting" }),
+ *     ],
+ *   });
+ *
+ * `required` defaults to TRUE. A declaration exists to be checked, so the safe
+ * default is the checked one; `required: false` says the code has a working path
+ * when the secret is absent, and downgrades a missing secret to a warning.
+ *
+ * Emits: { __config: "secrets", secrets: [{ name, required, description }] }
+ * sorted by name, so the same declaration always evaluates to the same bytes and
+ * a config diff shows what an author changed rather than how they reordered it.
  */
-interface UploadConfig {
-    /**
-     * Target bucket NAME. MUST exist in `config/storage.ts` `defineStorage(...)`.
-     *
-     * The bucket is the SINGLE SOURCE OF TRUTH for the size limit + MIME allowlist:
-     * `bucket({ fileSizeLimit, allowedMimeTypes })`. Storage enforces those at the
-     * actual PUT (the only guard a client cannot skip), so `@Upload` deliberately
-     * does NOT take its own `maxSize`/`allowedTypes` — duplicating them here would
-     * let a route declare a tighter limit than its bucket that storage would not
-     * enforce (a real bypass: declare 10 bytes at authorize, then PUT up to the
-     * bucket ceiling straight at the signed URL). One bucket, one limit, enforced.
-     */
-    bucket: string;
+/** The discriminant written under `__config` so the deploy eval knows the kind. */
+declare const SECRETS_CONFIG_KIND: "secrets";
+/** The author-facing options for a single `secret()`. */
+interface SecretOptions {
     /**
-     * SERVER-side object key template. The client NEVER chooses the path. Tokens:
-     * `{userId}` (authenticated user id), `{uploadId}` (server-minted), and
-     * `{filename}` (the client-declared filename, sanitized). e.g.
-     * `"{userId}/{uploadId}-{filename}"`.
+     * Whether the deploy must REFUSE when this secret is absent from the target
+     * environment's vault. Omitted ⇒ `true`.
      */
-    pathTemplate: string;
+    required?: boolean;
+    /** What the secret is for — shown when the deploy reports it missing. */
+    description?: string;
 }
 /**
- * `@Upload(subpath, config)` — declare a direct-storage upload route. The method
- * body is the completion handler; `config.uploadConfig` drives the authorize
- * guard + signed-URL pinning.
+ * The compiled, serializable secret declaration — the EXACT shape emitted to
+ * JSON and consumed by the Go deploy step.
  *
- * @example
- * ＠Upload("/", { bucket: "docs", pathTemplate: "{userId}/{uploadId}-{filename}" })
- * async upload(＠UploadedObject() obj: UploadedObject, ＠User() user): Promise<DocResult> { ... }
- * // The size limit + MIME allowlist come from the "docs" bucket in
- * // config/storage.ts — storage enforces them at the PUT.
- */
-declare function Upload(subpath: string, config: UploadConfig & Pick<RouteOptions, "auth" | "rateLimit">): MethodDecorator$1;
-/**
- * The uploaded object, injected into an `@Upload` method body by
- * `@UploadedObject()` once storage confirms the upload. Bytes are NOT present
- * (they went straight to storage) — this is the metadata the completion handler
- * persists.
+ * - `name`: the environment-variable name the code reads, verbatim.
+ * - `required`: always present (defaulted to `true`).
+ * - `description`: the doc string, or `null`.
  */
-interface UploadedObject {
-    /** Server-minted id correlating authorize ↔ completion (idempotency key). */
-    uploadId: string;
-    /** Final object key in the bucket (rendered from `pathTemplate`). */
-    path: string;
-    /** Bucket the object landed in. */
-    bucket: string;
-    /** Object size in bytes, as reported by storage. */
-    size: number;
-    /** Object MIME type, as reported by storage. */
-    contentType: string;
+interface SecretDef {
+    name: string;
+    required: boolean;
+    description: string | null;
+}
+/** A secrets config definition: the discriminant + the name-sorted declarations.
+ * This is the value `defineSecrets` returns and the build's config extractor
+ * serializes into `.palbase/config.json`. */
+interface SecretsConfig {
+    __config: typeof SECRETS_CONFIG_KIND;
+    secrets: SecretDef[];
+}
+/** The author-facing input to `defineSecrets`: a list of `secret(...)` builders. */
+interface SecretsInput {
+    secrets: SecretDef[];
 }
 /**
- * `@UploadedObject()` — inject the uploaded object (`: UploadedObject`) into an
- * `@Upload` method body (the completion input). Only valid on an `@Upload`
- * route; the bytes are NOT present (they went directly to storage), this is the
- * confirmed object's metadata.
+ * Declare a single required (or optional) secret. Unlike `flag()` / `bucket()`,
+ * the NAME is an argument rather than an object key: a secret's name is not a
+ * label an author chooses, it is the exact env-var identifier the code already
+ * reads, so it belongs where it can be validated as one.
  *
- * Co-located with the {@link UploadedObject} TYPE so a single exported name
- * `UploadedObject` carries BOTH the decorator value and the type annotation.
+ * Validates eagerly (at config-author time):
+ *  - `name` is `[A-Z][A-Z0-9_]*` — anything else throws.
+ *  - `required` is a boolean; `description` is a string.
+ *
+ * Returns a normalized {@link SecretDef}: `required` defaulted to `true`,
+ * `description` trimmed-or-null.
  */
-declare function UploadedObject(): ParameterDecorator$1;
+declare function secret(name: string, opts?: SecretOptions): SecretDef;
 /**
- * Cross-check one `@Upload` route's uploadConfig against the project's
- * {@link StorageConfig}: the named bucket MUST exist in `defineStorage(...)`.
- * Throws a precise error so a typo fails at deploy, not at the first user upload.
- *
- * That is the ONLY cross-check: the size limit + MIME allowlist live on the
- * bucket (`bucket({ fileSizeLimit, allowedMimeTypes })`) and are enforced by
- * storage at the PUT. `@Upload` carries no `maxSize`/`allowedTypes` of its own,
- * so there is nothing to compare — one bucket, one limit, no drift.
+ * Define the secrets a backend needs. Returns the discriminated
+ * {@link SecretsConfig} the build's config extractor serializes and the deploy
+ * checks against the target environment's vault BEFORE shipping anything.
  *
- * `routeLabel` is used only for error messages (e.g. `docs.upload`).
+ * A name declared twice throws: two declarations of one name disagree about
+ * something (usually `required`), and silently keeping either one is how a
+ * secret stops being checked without anybody editing the check.
  */
-declare function validateUploadAgainstStorage(uploadConfig: UploadConfig, storage: StorageConfig, routeLabel: string): void;
+declare function defineSecrets(input: SecretsInput): SecretsConfig;
 
-/** The HTTP verbs a route may declare, upper-cased (the runtime router +
- * OpenAPI lower-case on their own). */
-type HttpMethodUpper = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "QUERY";
-/** Route-level options accepted by the method decorators (`@Get`/`@Post`/…). */
-interface RouteOptions {
-    /** OVERRIDES the controller-level default auth for this one route. */
+/** Options accepted by `@Controller`. */
+interface ControllerOptions {
+    /** Default auth for ALL routes in this controller (route-level overrides). */
     auth?: AuthSpec;
-    /** Per-route rate limit. */
-    rateLimit?: RateLimitConfig;
-    /** Direct-storage upload config — present ONLY on `@Upload` routes (the
-     * `@Get`/`@Post`/… decorators never set it). Its presence is what MARKS a
-     * route as an upload route through the whole pipeline (registry → flatten →
-     * openapi → codegen). The bytes go client→storage directly; the method body
-     * runs as the completion handler. See {@link UploadConfig} (decorators/upload.ts). */
-    uploadConfig?: UploadConfig;
-}
-/** The kind of value a parameter decorator injects. Drives both dispatch
- * (which request slice to inject) and codegen (which OpenAPI parameter source a
- * schema-bearing kind maps to). */
-type ParamKind = "body" | "query" | "param" | "headers" | "user" | "optionalUser" | "client" | "requestId" | "traceId" | "req" | "uploadedObject";
-/** One parameter decorator's recorded metadata. `index` is the parameter
- * position esbuild/tsc preserve; `schema` is present for the schema-bearing
- * kinds (`body`/`query`/`headers`); `name` is the path-param name for `param`. */
-interface ParamMeta {
-    index: number;
-    kind: ParamKind;
-    /** Zod schema for `body`/`query`/`headers` (validation + codegen source). */
-    schema?: ZodTypeAny;
-    /** Path-param name for `@Param("id")`. */
-    name?: string;
-}
-/** One inferred throw site: the error CLASS name (e.g. "TodoLocked") and its
- * wire code (e.g. "todo_locked"). `status`, `hasData`, and the data JSON schema
- * are NOT carried here — they resolve from the error registry by `code` at
- * extract/openapi time (single source of truth). */
-interface ThrowDescriptor {
-    name: string;
-    code: string;
 }
-/** One route's recorded metadata: the verb + subpath + method name + options,
- * the ordered parameter metas, and the resolved return schema (injected by the
- * codegen step — see `returnSchema`). */
-interface RouteMeta {
-    method: HttpMethodUpper;
-    subpath: string;
-    fnName: string;
-    options: RouteOptions;
-    params: ParamMeta[];
-    /** Response schema for the route, if any. Derived from the method's RETURN
-     * TYPE by codegen and written here via `recordReturn` (a generated top-level
-     * IIFE injected per controller), not by an author-written decorator. */
-    returnSchema?: ZodTypeAny;
-    /** Error classes this route can throw, if inferred. Derived from the method
-     * body + service call graph by the deploy stager's throw analysis and written
-     * here via `recordThrows` (a generated top-level IIFE injected per controller,
-     * the `recordReturn` twin), not by an author-written decorator. */
-    throws?: ThrowDescriptor[];
-}
-/** Attach the inferred throw descriptors to the route for `fnName` (called by
- * the stager-injected IIFE that carries the throw analysis result — the
- * `recordReturn` twin). If the route does not exist yet, the descriptors are
- * buffered (THROWS_BUFFER) and drained into the route by `recordRoute` when the
- * method decorator runs. */
-declare function recordThrows(target: object, fnName: string, throws: ThrowDescriptor[]): void;
-/** Read the route metadata for a controller class (the deploy/dispatch entry
- * point). Applies any buffered return schemas + throw descriptors (for the
- * recordReturn/recordThrows-runs-before orderings) and returns a defensive copy
- * so callers cannot mutate the registry.
+/**
+ * The controller classes this process has loaded, in decoration order.
+ *
+ * Decoration order is import order, which the bundler fixes by sorting the
+ * files it emits imports for — so two builds of one tree produce the same
+ * route table, and route precedence is not a function of module-resolution
+ * accidents.
+ */
+declare function getRegisteredControllers(): readonly unknown[];
+/** Empty the registry. For tests, which load controllers repeatedly. */
+declare function __resetRegisteredControllers(): void;
+/**
+ * Mark a class as a Palbase backend controller. `basePath` is the mount path
+ * for every route the class declares; `options.auth` sets the controller-level
+ * default auth (a route's own `auth` overrides it; absent ⇒ secure-by-default).
+ *
+ * @example
+ * \@Controller("/todos", { auth: false })
+ * export class TodosController {
+ *   \@Get("") list(\@QueryParams(ListTodosQuery) q: ListTodosQuery): TodoSchema[] { … }
+ * }
  */
-declare function getRoutes(ctor: object): RouteMeta[];
+declare function Controller(basePath: string, options?: ControllerOptions): <T extends abstract new (...args: never[]) => object>(ctor: T) => T;
 
 /** A legacy method decorator. */
 type MethodDecorator = (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
@@ -1898,4 +1656,4 @@ declare const documents: {
     onDocumentDeleted(handler: HookHandler<DocumentDeletedEvent>): ResolvedHook<DocumentDeletedEvent>;
 };
 
-export { type AcsOptions, type ApnsOptions, Body, type BucketDef, type BucketOptions, Cache, CacheClient, Client, Controller, type ControllerOptions, DBClient, DEFAULT_TEMPLATE_LOCALE, Database, type DefinedError, type DefinedErrorWithData, Delete, type DocumentCreatedEvent, type DocumentDeletedEvent, type DocumentUpdatedEvent, Documents, EGRESS_CONFIG_KIND, EGRESS_TIMEOUT_DEFAULT_MS, EGRESS_TIMEOUT_MAX_MS, EGRESS_TIMEOUT_MIN_MS, type EgressConfig, type EgressInput, type EmailTemplateContent, type EmailTemplateDef, type EmailTemplateOptions, EntitlementKey, EnvTypedDatabase, FLAGS_CONFIG_KIND, type FcmOptions, type FileDeletedEvent, type FileUploadedEvent, type FlagDef, type FlagJsonObject, type FlagJsonValue, type FlagOptions, type FlagType, type FlagValue, Flags, type FlagsConfig, type FlagsInput, Get, Headers, type HookHandler, type HookMeta, HttpError, type HttpMethodUpper, type ImageVariant, Job, type JobMeta, type JobOptions, LimitKey, type LimitState, Log, Logger, NOTIFICATIONS_CONFIG_KIND, Notifications, type NotificationsConfig, type NotificationsInput, On, OptionalUser, type OwnedTablesOf, PROVIDER_CATALOG, PalbaseDocsClient, PalbaseFlagsClient, PalbaseNotificationsClient, PalbaseRealtimeClient, PalbaseStorageClient, Param, type ParamKind, type ParamMeta, type PasswordResetEvent, Patch, Post, type ProviderCatalogEntry, type ProviderDef, type ProviderName, type ProviderOptions, Purchases, type PurchasesManifest, type PurchasesService, Put, Query, QueryParams, RESERVED_SECRET_PREFIX, RateLimitConfig, Realtime, type RegisteredError, Req, RequestId, type RequestStore, RequireEntitlement, type ResolvedHook, type ResolvedJob, type ResolvedWebhook, Resource, type ResourceEnv, type RouteMeta, type RouteOptions, type RuntimeServices, STORAGE_CONFIG_KIND, SchemaDef, type Seed, type SeedFor, type SeedJson, type SeedRowFor, type SendgridOptions, type SesOptions, type SignInEvent, type SignOutEvent, type SignatureSpec, type SmsTemplateContent, type SmsTemplateDef, type SmsTemplateOptions, type SmtpOptions, Spend, type SpendMeta, type SpendOptions, Storage, type StorageConfig, type StorageInput, type StoreEnv, TEST_USERS_CONFIG_KIND, type TableGraph, TableTypes, Tables, type TemplatesConfig, type TemplatesInput, type TestUserDef, type TestUserOptions, type TestUsersConfig, type TestUsersInput, type ThrowDescriptor, TraceId, type TwilioOptions, Upload, type UploadConfig, UploadedObject, User, type UserCreatedEvent, Webhook, type WebhookEventHandler, type WebhookMeta, type WebhookOptions, type WebhookProvider, type WebhookRequest, __getRuntime, __registerResource, __requestALS, __runResourceBoot, __runWithRuntime, __setRuntime, __shutdownResources, auth, bucket, buildProvider, defineEgress, defineError, defineFlags, defineNotifications, defineStorage, defineTestUsers, documents, entitlementFor, extractVariables, flag, getErrorRegistry, getJobConfig, getRoutes, getWebhookConfig, makeEnvDts, makePurchasesDts, parseFileSizeLimit, recordThrows, reservedSecretKey, spendFor, storage, testUser, validateUploadAgainstStorage };
+export { type AcsOptions, type ApnsOptions, Body, Client, type ColumnJSON, Controller, type ControllerOptions, DEFAULT_TEMPLATE_LOCALE, type DefinedError, type DefinedErrorWithData, Delete, type DocumentCreatedEvent, type DocumentDeletedEvent, type DocumentUpdatedEvent, EGRESS_CONFIG_KIND, EGRESS_TIMEOUT_DEFAULT_MS, EGRESS_TIMEOUT_MAX_MS, EGRESS_TIMEOUT_MIN_MS, type EgressConfig, type EgressInput, type EmailTemplateContent, type EmailTemplateDef, type EmailTemplateOptions, EntitlementKey, FLAGS_CONFIG_KIND, type FcmOptions, type FileDeletedEvent, type FileUploadedEvent, type FlagDef, type FlagJsonObject, type FlagJsonValue, type FlagOptions, type FlagType, type FlagValue, type FlagsConfig, type FlagsInput, Get, Headers, type HookHandler, type HookMeta, HttpError, Job, type JobMeta, type JobOptions, LimitKey, type ModuleClientsConfig, type ModuleTransport, NOTIFICATIONS_CONFIG_KIND, type NotificationsConfig, type NotificationsInput, On, OptionalUser, type OwnedTablesOf, PROVIDER_CATALOG, PalbaseModuleError, PalbaseResult, Param, type PasswordResetEvent, Patch, type PolicyJSON, Post, type ProviderCatalogEntry, type ProviderDef, type ProviderName, type ProviderOptions, type PurchasesManifest, Put, Query, QueryParams, RESERVED_SECRET_PREFIX, type RegisteredError, Req, RequestId, type RequestOptions, RequireEntitlement, type ResolvedHook, type ResolvedJob, type ResolvedWebhook, Resource, type ResourceEnv, RouteOptions, SECRETS_CONFIG_KIND, SchemaDef, type SchemaJSON, type SecretDef, type SecretOptions, type SecretsConfig, type SecretsInput, type Seed, type SeedFor, type SeedJson, type SeedRowFor, type SendgridOptions, type SesOptions, type SignInEvent, type SignOutEvent, type SignatureSpec, type SmsTemplateContent, type SmsTemplateDef, type SmsTemplateOptions, type SmtpOptions, Spend, type SpendMeta, TEST_USERS_CONFIG_KIND, type TableGraph, type TableJSON, TableTypes, Tables, type TemplatesConfig, type TemplatesInput, type TestUserDef, type TestUserOptions, type TestUsersConfig, type TestUsersInput, TraceId, type TransportConfig, type TwilioOptions, User, type UserCreatedEvent, Webhook, type WebhookEventHandler, type WebhookMeta, type WebhookOptions, type WebhookProvider, type WebhookRequest, __registerResource, __resetRegisteredControllers, __runResourceBoot, __shutdownResources, auth, buildModuleClients, buildProvider, defineEgress, defineError, defineFlags, defineNotifications, defineSecrets, defineTestUsers, documents, entitlementFor, extractVariables, flag, getErrorRegistry, getJobConfig, getRegisteredControllers, getWebhookConfig, makeEnvDts, makeHttpClient, makePurchasesDts, reservedSecretKey, secret, spendFor, storage, testUser, toSchemaJSON };