@palbase/backend 33.0.2 → 34.1.0

package/docs/llms-full.txt

@@ -90,7 +90,7 @@ service the controllers call.
 
 > **Never** emit `defineController`, `defineHandler`, `defineEndpoint`, `route.get(...)`,
 > `req.input`, `req.params`, or `req.errors` — those are the removed legacy model
-> and will not compile against `@palbase/backend` 33.
+> and will not compile against `@palbase/backend` 34.
 
 ### Complete CRUD example (copy-pasteable, compiles)
 
@@ -931,6 +931,64 @@ Two helpers are available in every policy body:
 Both take the caller from `auth.uid()` and accept no user id, so a policy cannot
 ask about somebody else.
 
+### `can` — what a row says you may do
+
+Every row a table hands back carries `can: string[]`: the names of the table's
+named **update** policies whose `using` expression is true for THIS row and THIS
+caller. It is computed in the same `SELECT` that fetched the row — the policy is
+the only copy of the rule, and `can` is its echo.
+
+```ts
+const transfer = await Database.public.transfers.findById(id);
+transfer?.can; // e.g. ["transfers_approve"] — typed from db/public.ts
+```
+
+To put it on the wire, name it in the response schema — the enum comes from the
+policy declaration, never from a hand-typed list:
+
+```ts
+import { z, can } from "@palbase/backend";
+import publicSchema from "../../db/public";
+
+export const TransferSchema = z.object({
+  id: z.string(),
+  status: z.string(),
+  can: can(publicSchema.tables.transfers),
+});
+```
+
+The contract, word for word: **`can` is for the interface; it cannot be used for
+an authorization decision; it may be incomplete; the server decides again on
+every request.** A policy whose `using` the engine cannot select as a column is
+dropped from `can` with a `warn` line — it never becomes a silent `true`. In a
+raw-string `using`, write column names unqualified (`status`, not
+`transfers.status` or `public.transfers.status`) and wrap every
+`auth.has_permission(...)` in `(select …)`; a comment, an unbalanced parenthesis
+or an unterminated quote drops the policy the same way.
+
+Rows read under `Database.$asService()` carry `can: []`: no policy applies to
+the service role and every `TO` gate is false for it, so a row fetched there and
+handed to a user says nothing about what that user may do — read it as the user.
+
+Only `.for("update")` policies are echoed. A `.for("all")` policy such as
+`notes_owner` above governs UPDATE too, but it is not a named update policy and
+never appears in `can` — a table whose only policy is `for("all")` gets
+`can: []` on every row, and `can(table)` refuses it by name. To get an
+affordance, declare a separate `.for("update")` policy beside it (the template's
+`notes_edit_own` next to `notes_owner`).
+
+The name `can` is reserved for this echo. A table that declares a column named
+`can` keeps its column and gets no echo (with a `warn`); a **relation** named
+`can` — a table named `can`, a `can_id` foreign key, `as: "can"` or
+`reverseAs: "can"` — is refused by `defineTable` itself, because `row.can` and
+`relations.can` cannot both be true of one row.
+
+When the server refuses, the 403 body names the cure: `required: "transfers.approve"`.
+`pb.auth.onPermissionDenied { required in … }` (iOS) / `pb.auth.onPermissionDenied(required => …)`
+(web) fires on it, so a screen drawn from a stale `can` refetches and repairs itself.
+`pb.auth.permissions.holds("transfers.approve")` is the live, observable set of the
+caller's permissions — pushed over realtime the moment a role changes.
+
 ## Email verification
 
 The platform handles verification end to end. **You do not configure a sender**,
@@ -1075,6 +1133,69 @@ await Database.public.todos.delete(todo.id);
 
 See [schema.md](./schema.md) for the full typed-table surface.
 
+## Transaction boundaries and retries
+
+Ordinary Database writes commit when the request completes. `$transaction(fn)`
+builds a synchronous plan executed inside a savepoint of that same transaction.
+A savepoint cannot refresh its parent snapshot or retry the parent's COMMIT;
+passing a nonzero `retry` to `$transaction` is refused with a migration message.
+
+Use `$atomic` for an explicit, independently committed transaction with ordinary
+async reads and writes. Its promise resolves after COMMIT succeeds. Every retry
+opens a fresh transaction and reruns the complete callback, including decision
+reads. Choose `read committed`, `repeatable read` or `serializable` isolation.
+
+```ts
+import { Conflict, NotFound, decrement } from "@palbase/backend";
+
+const result = await Database.$atomic(async (tx) => {
+  const account = await tx.public.accounts.findById(accountId);
+  if (!account) throw new NotFound();
+  // All dependent writes, the ledger and an outbox event belong in this scope.
+  return tx.$transaction((plan) => {
+    return plan.public.accounts.updateWhere(
+      { id: accountId, balance: { gte: amount } },
+      { balance: decrement(amount) },
+    ).expectOne(new Conflict("Insufficient balance"));
+  });
+}, { isolation: "serializable", retry: 3, lockTimeoutMs: 1000, statementTimeoutMs: 5000 });
+```
+
+`retry` defaults to 0 and is limited to 10. Only serialization and deadlock
+failures are retried. A lost connection during COMMIT has an unknown outcome
+and is not automatically replayed; use an idempotency key to reconcile it.
+Keep external effects out of a retried callback: write an outbox record there
+and deliver it after commit.
+
+The complete [money-transfer.ts](./examples/money-transfer.ts) recipe uses the
+public `DBClient.atomic` seam, typed guards, exact integer minor units, a payload
+checked idempotency key, ordered account locks, balanced ledger entries and an
+outbox. Its `transferSchema` declares the database constraints and tenant RLS;
+export it from `db/public.ts`, review `palbase db plan` and run `palbase db apply`.
+It is the same transfer body used by the real PostgreSQL verification suite;
+importing it alone does not apply its constraints. Derive `input.tenant` from verified application scope. Use globally
+unique request keys, or include the tenant in the key. An outbox worker delivers
+after commit and consumers deduplicate by event id.
+
+`$atomic` commits independently: a later handler error does not undo it. Avoid
+writing the same data in the surrounding request transaction. The callback's
+typed `tx` and ambient `Database` calls share its transaction. Handles saved from
+another transaction, nested roots and `$asService()` inside it are refused.
+For service-role work choose `Database.$asService().$atomic(...)` before entering
+the callback; it keeps that one identity throughout every retry.
+
+The request's default and service-role surfaces remain separate transactions;
+their commits are not atomic together. Put a business operation's atomic writes
+in one `$atomic` scope. `fakeDatabase` does not emulate PostgreSQL isolation or
+commit/retry behavior; use a real PostgreSQL test for that boundary.
+
+Schema-aware timestamp results use UTC ISO strings with six fractional digits,
+preserving PostgreSQL microseconds through reads, returned writes, relations,
+aggregates and transaction plan references. Infinities, BC dates and years outside
+1–9999 retain PostgreSQL's text representation. These queries return the declared
+column shape. Raw `$query` results follow the driver's types; request `column::text`
+when a raw query must preserve timestamp precision rather than a JavaScript Date.
+
 ## Raw string-keyed operations
 
 For a table name computed at runtime, or for SQL the typed helpers do not
@@ -1752,6 +1873,251 @@ Guidelines:
     second surface waits for a lock the first cannot release until the handler
     returns. The service side gives up after five seconds and tells you this;
     the default side would wait until the edge cuts the request.
+## Cursor pages and bulk counts
+
+`page` returns `{ rows, pageInfo }`. A projection narrows `rows` in TypeScript;
+the cursor keeps the ordering values independently, including fields omitted by
+`select`.
+
+```ts
+const page = await Database.public.todos.page({
+  select: ["id", "title"],
+  orderBy: { column: "created_at", direction: "desc" },
+  first: 50,
+  after: cursor, // omit for the first page
+});
+// Next: after: page.pageInfo.endCursor
+// Previous: last: 50, before: page.pageInfo.startCursor
+```
+
+Sizes are 1–1000 (default 50). Use `first`/`after` or `last`/`before` together.
+The engine appends every missing primary-key column to the ordering, including
+composite keys. `direction` and `nulls` are honored independently. Both directions
+return rows in the requested order. Empty pages have null cursors and report
+whether matching rows remain on the opposite side of the supplied boundary.
+The page and its flags use one PostgreSQL statement snapshot. Across requests,
+inserts, deletes and changes to ordering fields can change the list; a cursor is
+not a frozen snapshot. Prefer immutable ordering columns for exports.
+
+Install the table declaration and an index matching the tenant/filter columns
+followed by the ordering columns and primary key. Keyset pagination avoids
+scanning a skipped prefix; it does not provide arbitrary page-number jumps.
+JSON/vector ordering is refused. Text ordering follows the database collation.
+
+In the engine, cursor encryption uses `PALBASE_CURSOR_SECRET`, falling back to
+`PALBASE_SERVICE_ROLE_KEY`. Keep this secret shared across replicas and restarts;
+rotation invalidates existing cursors. Cursors are tied to the table declaration,
+filter, projection, relations, ordering and authorization claims (JWT issuance/
+expiry identifiers are excluded). Reusing one with another query or identity
+returns `BadRequest`. A malformed token is rejected before database access.
+Standalone engine consumers configure `setCursorKey(secret)` from the engine
+entrypoint. `fakeDatabase` requires an explicit page test double; PostgreSQL
+integration tests cover collation, RLS and cursor semantics.
+
+```ts
+const inserted = await Database.public.todos.insertMany(rows, {
+  returning: false,
+});
+```
+
+`inserted` is a number. The engine omits `RETURNING` and reads PostgreSQL's affected
+row count, including zero when `onConflict` with `action: "ignore"` skips every
+row. `action: "update"` counts both inserted and updated rows. The default returns
+rows as before; a dynamic boolean produces a `number | Row[]` type. This option
+belongs to the asynchronous bulk surface; declarative transaction plan row handles
+continue to return their rows. Custom SQL drivers must expose an integer `count`
+on a non-returning result. Empty input opens no connection. The batch remains one
+statement and participates in its enclosing transaction's rollback.
+
+## Reusable queries and response contracts
+
+`defineQuery` combines an explicit selection with a reusable input/filter. The
+result is also a Zod array schema: a controller can return
+`Promise<z.infer<typeof ListTodos>>`, and the existing build binder uses that
+same value for response validation, OpenAPI and generated clients.
+
+```ts
+export const ListTodos = defineQuery("ListTodos", {
+  table: todos, // a defineTable value already registered by defineSchema
+  input: z.object({ prefix: z.string().default("") }),
+  select: ["id", "title"],
+  where: ({ prefix }) => ({ title: { startsWith: prefix } }),
+  orderBy: { column: "id" },
+  limit: 50,
+});
+
+const rows = await ListTodos.run(Database, { prefix: "Buy" });
+const compiled = ListTodos.sql(Database, { prefix: "Buy" }); // no connection
+// compiled.sql and compiled.params describe the same statement run() executes.
+```
+
+`run` validates its input before SQL and its response before returning. SQL uses
+the same SELECT compiler as `findMany`, under the caller's transaction and RLS
+identity. Table names retain their declared schema. Selection is mandatory;
+unselected database columns cannot silently expand the API. Numeric/bigint and
+timestamp outputs retain their exact string representations, and named codecs
+determine the surfaced type. A selected `jsonb<T>()` needs a matching Zod schema
+in `fields: { payload: PayloadSchema }`, because its TypeScript payload is erased
+at runtime. Free-form column transforms require migration to a named codec.
+
+Keep a contract manifest in the application repository:
+
+```ts
+const generated = queryManifest([ListTodos]);
+// Write generated JSON for the initial, reviewed baseline.
+assertQueryManifest([ListTodos], committedManifest); // run in the CI/build check
+```
+
+The manifest contains input/response OpenAPI components, selected storage types,
+nullability and codecs. A changed contract fails the check until its diff is
+reviewed and the committed baseline is updated. The runtime also refuses a query
+whose selected columns disagree with the installed declaration, before SQL.
+This check compares declarations; migration validation still owns drift in the
+physical PostgreSQL schema. Queries currently project one table; use `findMany`
+or `page` for nested relation reads.
+
+`await ListTodos.explain(Database, input)` executes plain `EXPLAIN (FORMAT JSON)`
+with the same role and parameters. It never enables `ANALYZE`. Plans can contain
+filter literals, so inspect them in development/operator tooling. No EXPLAIN is
+run automatically on production requests. The complete controller/schema example
+is [examples/database-dx.ts](./examples/database-dx.ts).
+
+## Nested relations and unique lookups
+
+`with` accepts three relation edges, with independent selection, filtering,
+ordering and limits at each level. The whole read remains one SQL statement.
+Each related table retains RLS; `many` returns an array, `one` returns a row or
+null. Numeric/bigint strings, timestamp microseconds, vectors and named codecs
+are restored at each level. Joins use the foreign key's declared target column,
+including a non-primary unique column.
+
+```ts
+const customers = await Database.billing.customers.findMany({
+  select: ["id"],
+  with: { invoices: { select: ["id"], limit: 10,
+    with: { customer: { select: ["name"] } },
+  } },
+});
+
+const account = await Database.public.accounts.findUnique({
+  where: { tenant_id: tenantId, account_number: number },
+  select: ["balance"],
+});
+```
+
+The lookup example requires a declared unique/primary key on
+`["tenant_id", "account_number"]`. Regenerate `palbase-env.d.ts` to get exact key
+types. Supply one entire key; partial composites, mixed keys, operators and null
+values are refused. A missing or RLS-hidden row returns null. More than one match
+raises a constraint-drift error. The direct `makeTypedDB` facade validates keys
+at runtime; the generated `Database.<schema>.<table>` surface also checks them at
+compile time. `findById` keeps its existing `id`-column contract.
+
+## Commands and workload admission
+
+`$command` accepts the synchronous transaction-plan callback used by
+`$transaction`. It retains guards, dependent row references, sequential visibility
+and savepoint rollback. Its default `mode: "auto"` compiles supported plans when
+the helper is installed and uses the sequential path otherwise. Choose
+`mode: "compiled"` to require compilation or `mode: "sequential"` to opt out.
+It settles with its enclosing transaction; an independently durable command
+belongs inside `$atomic`.
+
+Enable the helper with `PALBASE_DB_COMMANDS=true`; standalone engine consumers
+call `installCommandExecutor(driver, roles)`. Installation needs DDL rights.
+Execution is `SECURITY INVOKER`, so the caller's role and RLS remain active.
+Compilation currently excludes SQL fragments, column codecs/transforms, vector
+tables, nullable WHERE references and certain JavaScript number/JSON scalar
+bindings whose driver semantics would differ. Strict mode refuses these before
+SQL; automatic mode preserves the sequential behavior. Plans with no row refs
+send parameterized statements in order on one connection without waiting for
+each result before submitting the next. SQL guards abort before later queued
+writes run, and the engine drains every result before rollback. These are still
+separate SQL statements, with sequential visibility. Plans with row refs use
+one invoker helper call with sequential statements inside PostgreSQL. The helper
+adds JSON/dynamic-SQL processing; measure the actual plan and network before
+selecting it for throughput. Fewer round trips alone do not guarantee a speedup.
+
+For contention on the same accounts/resources, declare a workload once:
+
+```ts
+const transfers = defineWorkload("transfers", {
+  concurrency: 16, queueLimit: 128,
+  tenantConcurrency: 8, tenantQueueLimit: 32, queueTimeoutMs: 1000,
+});
+
+await Database.$atomic(async tx => {
+  // Decision reads, idempotency claim, writes, ledger and outbox belong here.
+}, {
+  workload: transfers,
+  conflictKeys: [fromAccountId, toAccountId],
+  timeoutMs: 3000, signal, retry: 2,
+});
+```
+
+Overlapping resource keys are admitted in order. Independent keys and tenants
+can proceed while those requests wait. Queue size and per-tenant budgets are
+bounded; full/expired queues return 429 before opening a transaction. Tenant
+identity comes from the configured verified claim (`tenant_id`, then `sub`, then
+one anonymous bucket). Keys are shared within a workload; include the tenant in
+a key if resource IDs are only tenant-unique. Rejected/cancelled waiters leave the
+queue. The lease spans every retry and transaction settlement.
+
+These limits apply per engine/driver instance. Divide pool/admission budgets
+across replicas; PostgreSQL locks and constraints remain authoritative across
+instances. Admission is optional because independent work also pays its cost.
+Each driver supports at most 64 named workloads.
+
+`timeoutMs` includes queueing, callback work and retries. The default driver uses
+a separate control pool of at most two connections to cancel active PostgreSQL
+statements. Reserve those connections in the deployment budget. Standalone Bun
+drivers can use `withQueryCancellation(applicationPool, controlPool)` with the
+same server/login. The engine waits for cancellation and rollback before releasing
+the application connection. JavaScript callbacks themselves are not preempted;
+late DB handles are invalidated. Pool acquisition and an in-flight COMMIT still
+have to settle, so the deadline is not a hard wall-clock response guarantee.
+An acknowledged COMMIT stays successful; an unknown commit outcome is never
+automatically replayed.
+
+## Query diagnostics and budgets
+
+Set `PALBASE_DB_DIAGNOSTICS=true` for request summaries, or provide
+`EngineConfig.databaseDiagnostics` with `onQuery`/`onComplete` callbacks.
+Standalone consumers pass the same options as the third argument to
+`createRequestDatabase`. Diagnostics are disabled by default. For a route budget:
+
+```ts
+@Get("/", { databaseBudget: { maxQueries: 8, maxRows: 100, maxBytes: 65536 } })
+```
+
+Counts include application SQL, authorization reads, service queries and retries;
+transaction setup is timed separately. Query count is checked before SQL. Row
+and estimated JSON-byte budgets are checked after results arrive; use SQL limits
+and projections to avoid producing excessive data. A caught budget error still
+prevents COMMIT of the affected transaction. An earlier independent `$atomic`
+commit remains durable.
+
+Summaries correlate the route/request ID with query names and SQL fingerprints.
+`captureSource: true` adds a bounded runtime stack; `includeSql: true` adds bounded
+SQL text. Bind values are never recorded. Raw SQL text can itself contain inline
+literals. `Database.$diagnostics()` returns the current snapshot, or null when
+disabled; the completion callback includes settlement timings. Only the first
+200 completed statements are retained, while totals cover every statement.
+
+| Metric | Meaning |
+| --- | --- |
+| `queueMs` | Workload admission wait, including refused waits |
+| `poolMs` | Driver acquisition through transaction callback entry, including BEGIN |
+| `setupMs` | Isolation, cancellation ticket and role/claims setup |
+| `sqlMs` | Awaited driver time, including execution, lock and network waits |
+| `commitMs` / `rollbackMs` | Observed settlement waits |
+| `rows` / `bytes` | Returned root rows / estimated JSON result bytes, not wire bytes |
+| `commits` / `commitFailures` | Acknowledged commits / failed commit acknowledgements |
+| `rollbackRequests` / `retries` | Requested rollbacks / whole-transaction replays |
+
+Durations can overlap across concurrent operations; summing them is not request
+wall time. The driver cannot separate lock wait from server execution. Telemetry
+callback failures do not change an acknowledged transaction outcome.
 
 
 
@@ -2435,6 +2801,21 @@ calling user's rows — no `WHERE owner = …` needed in the handler. To read or
 write across all users (e.g. an admin job), use the explicit bypass:
 `Database.$asService()` (see [database.md](./database.md#bypassing-rls--databaseasservice)).
 
+Name your **update** policies deliberately: each name becomes a value in the row's
+`can` array (`row.can: ("transfers_approve" | "transfers_cancel")[]` in
+`palbase-env.d.ts`), and `can(table)` puts the same names into a response schema
+as an enum. Only `.for("update")` counts: a `.for("all")` policy like the
+owner policies above governs UPDATE but is never echoed, so a table with only
+`for("all")` policies carries `can: []`. In a raw-string `using`, write column
+names UNQUALIFIED (`status = 'pending_approval'`, not `transfers.status` or
+`public.transfers.status`) and wrap `auth.has_permission(...)` in `(select …)`:
+the engine selects the expression under a row alias, and a `using` it cannot
+carry there — a table qualifier, a comment, an unwrapped `has_permission`, a
+policy name longer than 59 bytes — is dropped from `can` with a `warn`, never
+spliced. A column or relation named `can` is reserved (see [auth.md](./auth.md)).
+`can` is for the interface; it cannot be used for an authorization decision; it
+may be incomplete; the server decides again on every request.
+
 ### How policies are applied
 
 On deploy, Palbase diffs your declared schema against the live database and

package/docs/schema.md

@@ -676,6 +676,21 @@ calling user's rows — no `WHERE owner = …` needed in the handler. To read or
 write across all users (e.g. an admin job), use the explicit bypass:
 `Database.$asService()` (see [database.md](./database.md#bypassing-rls--databaseasservice)).
 
+Name your **update** policies deliberately: each name becomes a value in the row's
+`can` array (`row.can: ("transfers_approve" | "transfers_cancel")[]` in
+`palbase-env.d.ts`), and `can(table)` puts the same names into a response schema
+as an enum. Only `.for("update")` counts: a `.for("all")` policy like the
+owner policies above governs UPDATE but is never echoed, so a table with only
+`for("all")` policies carries `can: []`. In a raw-string `using`, write column
+names UNQUALIFIED (`status = 'pending_approval'`, not `transfers.status` or
+`public.transfers.status`) and wrap `auth.has_permission(...)` in `(select …)`:
+the engine selects the expression under a row alias, and a `using` it cannot
+carry there — a table qualifier, a comment, an unwrapped `has_permission`, a
+policy name longer than 59 bytes — is dropped from `can` with a `warn`, never
+spliced. A column or relation named `can` is reserved (see [auth.md](./auth.md)).
+`can` is for the interface; it cannot be used for an authorization decision; it
+may be incomplete; the server decides again on every request.
+
 ### How policies are applied
 
 On deploy, Palbase diffs your declared schema against the live database and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palbase/backend",
-  "version": "33.0.2",
+  "version": "34.1.0",
   "description": "Palbase Backend SDK — class controllers (@Controller/@Get/@Post + @Body/@QueryParams/@Param), error classes, schema DSL",
   "license": "MIT",
   "repository": {
@@ -91,7 +91,6 @@
   "files": [
     "dist",
     "docs",
-    "stack-images.json",
     "stager",
     "template"
   ],

package/template/db/public.ts

@@ -31,6 +31,18 @@ const notes = defineTable("notes", {
       .using("user_id = (select auth.uid())")
       .withCheck("user_id = (select auth.uid())"),
 
+    // A NAMED update policy is also what the row's `can` array echoes back:
+    // `note.can` contains "notes_edit_own" when THIS caller may edit THIS row
+    // (typed from this file). Put it on the wire with
+    // `can(publicSchema.tables.notes)` in the response schema — the schema's
+    // table definition, not this handle. `can` is for the interface; it cannot be used for an
+    // authorization decision; it may be incomplete; the server decides again
+    // on every request.
+    policy("notes_edit_own")
+      .for("update")
+      .to("authenticated")
+      .using("user_id = (select auth.uid())"),
+
     // MODERATION, when you want it — delete these two if you do not.
     //
     // Roles are yours and there is no built-in "admin": you declare them from

package/template/package.json

@@ -9,7 +9,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@palbase/backend": "^33.0.0",
+    "@palbase/backend": "^34.0.0",
     "reflect-metadata": "^0.2.2"
   },
   "engines": {

package/dist/chunk-AAT5G7KY.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/decorators/registry.ts","../src/decorators/controller.ts"],"sourcesContent":["// The decorator registry — the single plain-data store the method + parameter\n// decorators write into, and the deploy/dispatch pipeline reads back. No\n// `reflect-metadata`, no `emitDecoratorMetadata`: the registry is built from the\n// decorator arguments + the parameter INDEX that esbuild/tsc preserve for legacy\n// parameter decorators (verified — see the design spec §0/§4.1).\n//\n// A controller class carries its route metadata on a symbol-keyed static\n// property (`ROUTES`). `@Get`/`@Post`/… append a {@link RouteMeta} entry;\n// `@Body`/`@User`/… append a {@link ParamMeta} entry onto the route for the\n// method they decorate. Because parameter decorators run BEFORE the method\n// decorator for the same member (TS evaluates innermost-first, params before the\n// method), the route entry may not exist yet when a param decorator fires — so\n// param metadata is buffered per method name and merged when the method\n// decorator creates the route entry.\nimport type { AuthSpec, RateLimitConfig } from \"../endpoint.js\";\nimport type { UploadConfig } from \"./upload.js\";\nimport type { SseConfig } from \"./sse.js\";\nimport type { ZodTypeAny } from \"zod\";\n\n/** The HTTP verbs a route may declare, upper-cased (the runtime router +\n * OpenAPI lower-case on their own). */\nexport type HttpMethodUpper = \"GET\" | \"POST\" | \"PUT\" | \"PATCH\" | \"DELETE\" | \"QUERY\";\n\n/** Route-level options accepted by the method decorators (`@Get`/`@Post`/…). */\nexport interface RouteOptions {\n  /** OVERRIDES the controller-level default auth for this one route. */\n  auth?: AuthSpec;\n  /** Per-route rate limit. */\n  rateLimit?: RateLimitConfig;\n  /** Direct-storage upload config — present ONLY on `@Upload` routes (the\n   * `@Get`/`@Post`/… decorators never set it). Its presence is what MARKS a\n   * route as an upload route through the whole pipeline (registry → flatten →\n   * openapi → codegen). The bytes go client→storage directly; the method body\n   * runs as the completion handler. See {@link UploadConfig} (decorators/upload.ts). */\n  uploadConfig?: UploadConfig;\n  /** Streaming config — present ONLY on `@Sse` routes (the `@Get`/`@Post`/…\n   * decorators never set it). Its presence is what MARKS a route as a streaming\n   * route through the whole pipeline (registry → flatten → openapi → codegen),\n   * exactly as `uploadConfig` does for uploads — never a special HTTP verb. An\n   * `@Sse` route registers POST like any input-bearing route, so the verb cannot\n   * carry the distinction. See {@link SseConfig} (decorators/sse.ts). */\n  sseConfig?: SseConfig;\n}\n\n/** The kind of value a parameter decorator injects. Drives both dispatch\n * (which request slice to inject) and codegen (which OpenAPI parameter source a\n * schema-bearing kind maps to). */\nexport type ParamKind =\n  | \"body\"\n  | \"query\"\n  | \"param\"\n  | \"headers\"\n  | \"user\"\n  | \"optionalUser\"\n  | \"client\"\n  | \"requestId\"\n  | \"traceId\"\n  | \"req\"\n  // `@UploadedObject()` — injects the uploaded object (completion input) on an\n  // `@Upload` route. No schema (the shape is the fixed UploadedObject type).\n  | \"uploadedObject\"\n  // `@SseOut()` — injects the frame writer on an `@Sse` route. No schema (the\n  // shape is the fixed SseWriter type).\n  | \"sseOut\"\n  // `@Signal()` — injects the request's AbortSignal, which aborts when the\n  // client disconnects. No schema. NOT derivable from `@Req()`: PBRequest\n  // carries only request-scoped data and has no signal (endpoint.ts:358-363).\n  | \"signal\";\n\n/** One parameter decorator's recorded metadata. `index` is the parameter\n * position esbuild/tsc preserve; `schema` is present for the schema-bearing\n * kinds (`body`/`query`/`headers`); `name` is the path-param name for `param`. */\nexport interface ParamMeta {\n  index: number;\n  kind: ParamKind;\n  /** Zod schema for `body`/`query`/`headers` (validation + codegen source). */\n  schema?: ZodTypeAny;\n  /** Path-param name for `@Param(\"id\")`. */\n  name?: string;\n}\n\n/** One inferred throw site: the error CLASS name (e.g. \"TodoLocked\") and its\n * wire code (e.g. \"todo_locked\"). `status`, `hasData`, and the data JSON schema\n * are NOT carried here — they resolve from the error registry by `code` at\n * extract/openapi time (single source of truth). */\nexport interface ThrowDescriptor {\n  name: string;\n  code: string;\n}\n\n/** One route's recorded metadata: the verb + subpath + method name + options,\n * the ordered parameter metas, and the resolved return schema (injected by the\n * codegen step — see `returnSchema`). */\nexport interface RouteMeta {\n  method: HttpMethodUpper;\n  subpath: string;\n  fnName: string;\n  options: RouteOptions;\n  params: ParamMeta[];\n  /** Response schema for the route, if any. Derived from the method's RETURN\n   * TYPE by codegen and written here via `recordReturn` (a generated top-level\n   * IIFE injected per controller), not by an author-written decorator. */\n  returnSchema?: ZodTypeAny;\n  /** Error classes this route can throw, if inferred. Derived from the method\n   * body + service call graph by the deploy stager's throw analysis and written\n   * here via `recordThrows` (a generated top-level IIFE injected per controller,\n   * the `recordReturn` twin), not by an author-written decorator. */\n  throws?: ThrowDescriptor[];\n}\n\n/** Symbol the route metadata list is stored under on a controller class. Using\n * a symbol (not a string key) keeps it off the public structural surface and\n * avoids any chance of an authored property collision. */\nexport const ROUTES: unique symbol = Symbol.for(\"palbase.backend.routes\");\n\n/** Symbol the per-method buffered parameter metas are stored under while a class\n * is being decorated. Parameter decorators fire before the method decorator, so\n * they buffer here keyed by method name; the method decorator drains the buffer\n * into the route entry it creates. */\nconst PARAM_BUFFER: unique symbol = Symbol.for(\"palbase.backend.paramBuffer\");\n\n/** A room's own slots. Rooms are NOT routes — no verb, no path, no params — so\n *  they get their own carrier slots instead of being squeezed into RouteMeta. */\nconst ROOM: unique symbol = Symbol.for(\"palbase.backend.room\");\nconst ROOM_HOOKS: unique symbol = Symbol.for(\"palbase.backend.roomHooks\");\n\n/** Symbol the per-method buffered return-type schemas are stored under while a\n * class's registry is being populated. The codegen-injected `recordReturn` call\n * can fire before OR after the method decorator; it buffers here keyed by method\n * name and `recordRoute` drains it into the route entry (and `recordReturn`\n * writes through if the route already exists). Buffering on BOTH sides means a\n * fully-formed route entry always carries its return schema — a raw-symbol\n * reader (the runtime) never has to re-merge. */\nconst RETURN_BUFFER: unique symbol = Symbol.for(\"palbase.backend.returnBuffer\");\n\n/** Symbol the per-method buffered throw descriptors are stored under while a\n * class's registry is being populated. The stager-injected `recordThrows` call\n * can fire before OR after the method decorator; it buffers here keyed by method\n * name and `recordRoute` drains it into the route entry (and `recordThrows`\n * writes through if the route already exists). Buffering on BOTH sides means a\n * fully-formed route entry always carries its throw descriptors — a raw-symbol\n * reader (the runtime) never has to re-merge. */\nconst THROWS_BUFFER: unique symbol = Symbol.for(\"palbase.backend.throwsBuffer\");\n\n/** A class constructor carrying the symbol-keyed registry slots. We type the\n * registry-bearing class as this so the decorators can read/write the slots\n * without `any` — a plain `Function` does not carry index signatures. */\ninterface RegistryCarrier {\n  [ROUTES]?: RouteMeta[];\n  [PARAM_BUFFER]?: Record<string, ParamMeta[]>;\n  [ROOM]?: RoomMeta;\n  [ROOM_HOOKS]?: RoomBuffer;\n  [RETURN_BUFFER]?: Record<string, ZodTypeAny>;\n  [THROWS_BUFFER]?: Record<string, ThrowDescriptor[]>;\n}\n\n/** Coerce a decorated target (class constructor or its prototype) into the\n * registry carrier that owns the slots. Method/param decorators receive the\n * PROTOTYPE as their target; the class decorator receives the constructor. We\n * always anchor the registry on the CONSTRUCTOR so `getRoutes(ctor)` finds it. */\nfunction carrierOf(target: object): RegistryCarrier {\n  // For instance-member decorators, `target` is the prototype; its `.constructor`\n  // is the class. For a static member or the class decorator, `target` is the\n  // constructor already. Resolve to the constructor either way.\n  const ctor =\n    typeof target === \"function\"\n      ? (target as unknown as RegistryCarrier)\n      : (((target as { constructor?: unknown }).constructor ??\n          target) as unknown as RegistryCarrier);\n  return ctor;\n}\n\n/** Get (creating if absent) the own route list for a class constructor. Own —\n * not inherited — so a subclass does not mutate its base's routes. */\nfunction ownRoutes(carrier: RegistryCarrier): RouteMeta[] {\n  if (!Object.prototype.hasOwnProperty.call(carrier, ROUTES)) {\n    carrier[ROUTES] = [];\n  }\n  return carrier[ROUTES] as RouteMeta[];\n}\n\n/** Get (creating if absent) the own per-method param buffer for a class. */\nfunction ownParamBuffer(carrier: RegistryCarrier): Record<string, ParamMeta[]> {\n  if (!Object.prototype.hasOwnProperty.call(carrier, PARAM_BUFFER)) {\n    carrier[PARAM_BUFFER] = {};\n  }\n  return carrier[PARAM_BUFFER] as Record<string, ParamMeta[]>;\n}\n\n/** Record a route (called by the method decorators). Drains any parameter\n * metas already buffered for `fnName` into the new route entry, then sorts them\n * by parameter index so dispatch can inject positionally. */\nexport function recordRoute(\n  target: object,\n  fnName: string,\n  method: HttpMethodUpper,\n  subpath: string,\n  options: RouteOptions,\n): void {\n  const carrier = carrierOf(target);\n  const routes = ownRoutes(carrier);\n  const buffer = ownParamBuffer(carrier);\n  const params = (buffer[fnName] ?? []).slice().sort((a, b) => a.index - b.index);\n  const route: RouteMeta = { method, subpath, fnName, options, params };\n  // Drain a buffered return schema (the recordReturn-ran-first ordering) so the\n  // route entry is complete the moment it's created — a raw-symbol consumer\n  // (the runtime extractor/worker) sees the return schema without re-merging.\n  const returnBuffer = carrier[RETURN_BUFFER];\n  if (returnBuffer && returnBuffer[fnName] !== undefined) {\n    route.returnSchema = returnBuffer[fnName];\n  }\n  // Same drain for buffered throw descriptors (the recordThrows-ran-first\n  // ordering) — the route entry is complete the moment it's created.\n  const throwsBuffer = carrier[THROWS_BUFFER];\n  if (throwsBuffer && throwsBuffer[fnName] !== undefined) {\n    route.throws = throwsBuffer[fnName];\n  }\n  routes.push(route);\n}\n\n/** Record one parameter decorator (called by `@Body`/`@User`/…). Buffers per\n * method name; the method decorator merges the buffer into the route entry. If\n * the route already exists (method decorator ran first — TS does evaluate the\n * method decorator AFTER its parameter decorators, but we stay order-robust),\n * the meta is also appended directly so neither ordering loses it. */\nexport function recordParam(target: object, fnName: string, meta: ParamMeta): void {\n  const carrier = carrierOf(target);\n  const buffer = ownParamBuffer(carrier);\n  (buffer[fnName] ??= []).push(meta);\n\n  // Order-robust: if the route already exists, merge in place + keep sorted.\n  const routes = carrier[ROUTES];\n  if (routes) {\n    const route = routes.find((r) => r.fnName === fnName);\n    if (route) {\n      route.params.push(meta);\n      route.params.sort((a, b) => a.index - b.index);\n    }\n  }\n}\n\n/** Attach a return schema to the route for `fnName` (called by the codegen\n * injection that reads the method's return type). If the route does not exist\n * yet, the schema is buffered (RETURN_BUFFER) and drained into the route by\n * `recordRoute` when the method decorator runs. */\nexport function recordReturn(target: object, fnName: string, schema: ZodTypeAny): void {\n  const carrier = carrierOf(target);\n  const routes = carrier[ROUTES];\n  const route = routes?.find((r) => r.fnName === fnName);\n  if (route) {\n    route.returnSchema = schema;\n    return;\n  }\n  if (!Object.prototype.hasOwnProperty.call(carrier, RETURN_BUFFER)) {\n    carrier[RETURN_BUFFER] = {};\n  }\n  const returnBuffer = carrier[RETURN_BUFFER];\n  if (returnBuffer) returnBuffer[fnName] = schema;\n}\n\n/** Attach the inferred throw descriptors to the route for `fnName` (called by\n * the stager-injected IIFE that carries the throw analysis result — the\n * `recordReturn` twin). If the route does not exist yet, the descriptors are\n * buffered (THROWS_BUFFER) and drained into the route by `recordRoute` when the\n * method decorator runs. */\nexport function recordThrows(target: object, fnName: string, throws: ThrowDescriptor[]): void {\n  const carrier = carrierOf(target);\n  const routes = carrier[ROUTES];\n  const route = routes?.find((r) => r.fnName === fnName);\n  if (route) {\n    route.throws = throws;\n    return;\n  }\n  if (!Object.prototype.hasOwnProperty.call(carrier, THROWS_BUFFER)) {\n    carrier[THROWS_BUFFER] = {};\n  }\n  const throwsBuffer = carrier[THROWS_BUFFER];\n  if (throwsBuffer) throwsBuffer[fnName] = throws;\n}\n\n/** Read the route metadata for a controller class (the deploy/dispatch entry\n * point). Applies any buffered return schemas + throw descriptors (for the\n * recordReturn/recordThrows-runs-before orderings) and returns a defensive copy\n * so callers cannot mutate the registry.\n */\nexport function getRoutes(ctor: object): RouteMeta[] {\n  const carrier = carrierOf(ctor);\n  const routes = carrier[ROUTES] ?? [];\n  const returnBuffer = carrier[RETURN_BUFFER];\n  if (returnBuffer) {\n    for (const route of routes) {\n      const buffered = returnBuffer[route.fnName];\n      if (buffered && route.returnSchema === undefined) {\n        route.returnSchema = buffered;\n      }\n    }\n  }\n  const throwsBuffer = carrier[THROWS_BUFFER];\n  if (throwsBuffer) {\n    for (const route of routes) {\n      const buffered = throwsBuffer[route.fnName];\n      if (buffered && route.throws === undefined) {\n        route.throws = buffered;\n      }\n    }\n  }\n  return routes.map((r) => ({\n    ...r,\n    params: r.params.slice(),\n    ...(r.throws !== undefined ? { throws: r.throws.slice() } : {}),\n  }));\n}\n\n// ── rooms ───────────────────────────────────────────────────────────────────\n\n/** Which lifecycle hook a method is bound to. */\nexport type RoomHook = \"authorize\" | \"first\" | \"join\" | \"leave\" | \"empty\";\n\nexport interface RoomMessageMeta {\n  fnName: string;\n  schema: ZodTypeAny;\n}\n\nexport interface RoomMeta {\n  pattern: string;\n  events: Record<string, ZodTypeAny>;\n  graceMs: number;\n  /** hook → the method name that implements it. */\n  hooks: Partial<Record<RoomHook, string>>;\n  /** inbound message name → its method and payload schema. */\n  messages: Record<string, RoomMessageMeta>;\n}\n\ninterface RoomBuffer {\n  hooks: Partial<Record<RoomHook, string>>;\n  messages: Record<string, RoomMessageMeta>;\n}\n\n/** Get (creating if absent) the own hook buffer. Own — not inherited — so a\n *  subclass never mutates its base's hooks. Member decorators fill this BEFORE\n *  the class decorator runs; controller.ts:203 depends on the same ordering. */\nfunction ownRoomBuffer(carrier: RegistryCarrier): RoomBuffer {\n  if (!Object.prototype.hasOwnProperty.call(carrier, ROOM_HOOKS)) {\n    carrier[ROOM_HOOKS] = { hooks: {}, messages: {} };\n  }\n  return carrier[ROOM_HOOKS] as RoomBuffer;\n}\n\n/** Record a lifecycle hook. A second method for the same hook is refused: two\n *  answers to \"who handles this\" cannot be resolved at dispatch, and silently\n *  keeping one is how a hook stops running without anyone being told. */\nexport function recordRoomHook(target: object, hook: RoomHook, fnName: string): void {\n  const buffer = ownRoomBuffer(carrierOf(target));\n  const existing = buffer.hooks[hook];\n  if (existing !== undefined && existing !== fnName) {\n    const label = `On${hook.charAt(0).toUpperCase()}${hook.slice(1)}`;\n    throw new Error(\n      `@${label} is declared twice in one room (${existing} and ${fnName}). ` +\n        `A room has one of each hook.`,\n    );\n  }\n  buffer.hooks[hook] = fnName;\n}\n\n/** Record an inbound message handler. */\nexport function recordRoomMessage(\n  target: object,\n  name: string,\n  fnName: string,\n  schema: ZodTypeAny,\n): void {\n  const buffer = ownRoomBuffer(carrierOf(target));\n  const existing = buffer.messages[name];\n  if (existing !== undefined && existing.fnName !== fnName) {\n    throw new Error(\n      `@OnMessage(\"${name}\") is declared twice in one room (${existing.fnName} and ${fnName}).`,\n    );\n  }\n  buffer.messages[name] = { fnName, schema };\n}\n\n/** Record the room itself (called by the class decorator), draining the buffer\n *  the member decorators already filled. */\nexport function recordRoom(\n  ctor: object,\n  meta: Omit<RoomMeta, \"hooks\" | \"messages\">,\n): void {\n  const carrier = carrierOf(ctor);\n  const buffer = ownRoomBuffer(carrier);\n  carrier[ROOM] = { ...meta, hooks: buffer.hooks, messages: buffer.messages };\n  // AND into the shared class registry, the same slot @Controller pushes to.\n  //\n  // Without this line a room compiles, bundles and deploys, and is never called:\n  // the bundler's entry exports `SDK.getRegisteredControllers()` and the runtime\n  // reads its rooms out of THAT list (server.ts's `collectRooms`). A room that\n  // only marks its own constructor is a room nobody can find — measured, on the\n  // fixture, at the last gate before it would have worked.\n  //\n  // Rooms and controllers share one list because they are one thing to the\n  // loader: classes a bundle declared. What each IS is decided by the marker it\n  // carries, never by which list it arrived in.\n  const g = globalThis as unknown as Record<symbol, unknown[] | undefined>;\n  const REGISTRY = Symbol.for(\"palbase.backend.allControllers\");\n  const all = (g[REGISTRY] ??= []);\n  if (!all.includes(ctor)) all.push(ctor);\n}\n\n/** The room a class declares, or undefined. A class with no `@Room` is not a\n *  room — the marker is the CONFIG's presence, never a name or a base class\n *  (the rule upload.ts:13-16 states for uploads). */\nexport function getRoom(ctor: object): RoomMeta | undefined {\n  const carrier = carrierOf(ctor);\n  if (!Object.prototype.hasOwnProperty.call(carrier, ROOM)) return undefined;\n  return carrier[ROOM] as RoomMeta;\n}\n","// `@Controller(basePath, options?)` — the class decorator that marks a class as\n// a Palbase backend controller. It stamps a non-enumerable `__palbase`\n// discriminant + the resolved controller metadata onto the class so the\n// deploy/dispatch pipeline (and `isController`/`resolveController`) can detect\n// and read it without `reflect-metadata`.\nimport type { AuthSpec } from \"../endpoint.js\";\nimport { getRoutes } from \"./registry.js\";\n\n/** The controller metadata stamped onto a `@Controller`-decorated class. The\n * default export of a `controllers/*.controller.ts` file resolves to this via\n * {@link resolveController}. */\nexport interface ControllerMeta {\n  /** Discriminant the runtime + tooling read. */\n  readonly __palbase: \"controller\";\n  /** The base path every route in this controller mounts under (e.g. \"/todos\"). */\n  basePath: string;\n  /** Controller-level default auth, applied to routes that don't set their own\n   * (`@Get(\"/x\", { auth })` overrides this). `undefined` ⇒ the application\n   * default ({@link defineDefaultAuth}), and secure-by-default below that —\n   * see {@link resolveEffectiveAuth} for the whole cascade. */\n  defaultAuth?: AuthSpec;\n}\n\n/** Options accepted by `@Controller`. */\nexport interface ControllerOptions {\n  /** Default auth for ALL routes in this controller (route-level overrides;\n   * omitting it falls through to the application default declared with\n   * {@link defineDefaultAuth}). */\n  auth?: AuthSpec;\n}\n\n/** Symbol the controller metadata is stamped under. Symbol-keyed (not a string\n * property) so it never collides with an authored member and stays off the\n * structural surface. */\nexport const CONTROLLER_META: unique symbol = Symbol.for(\"palbase.backend.controllerMeta\");\n\n/**\n * Every class `@Controller` has decorated, in decoration order.\n *\n * This is what lets a controller file need no export at all: importing the file\n * runs the decorator, the decorator records the class here, and the runtime\n * reads the list. Without it the only handle on a class is its export name, so\n * every controller had to be exported AND named in a generated entry — the\n * ceremony NestJS still charges (`export class` PLUS\n * `@Module({controllers:[…]})`).\n *\n * Keyed on a well-known Symbol against globalThis rather than held in a module\n * variable, because a deployed bundle inlines its own copy of this package: two\n * copies would keep two lists, and the runtime would read the empty one. The\n * same hazard `runtimeHooks` exists for, closed the same way — one shared slot.\n */\nconst REGISTRY: unique symbol = Symbol.for(\"palbase.backend.allControllers\") as never;\n\nfunction registry(): unknown[] {\n  const g = globalThis as unknown as Record<symbol, unknown[] | undefined>;\n  const existing = g[REGISTRY];\n  if (existing) return existing;\n  const fresh: unknown[] = [];\n  g[REGISTRY] = fresh;\n  return fresh;\n}\n\n/**\n * The controller classes this process has loaded, in decoration order.\n *\n * Decoration order is import order, which the bundler fixes by sorting the\n * files it emits imports for — so two builds of one tree produce the same\n * route table, and route precedence is not a function of module-resolution\n * accidents.\n */\nexport function getRegisteredControllers(): readonly unknown[] {\n  return registry().slice();\n}\n\n/** Empty the registry. For tests, which load controllers repeatedly. */\nexport function __resetRegisteredControllers(): void {\n  registry().length = 0;\n}\n\n/**\n * The APPLICATION-level default auth.\n *\n * Held on globalThis under a well-known Symbol for exactly the reason\n * {@link REGISTRY} is: a deployed bundle inlines its own copy of this package,\n * and two copies keeping two defaults is how a security setting silently\n * becomes two different settings.\n */\nconst APP_DEFAULT_AUTH: unique symbol = Symbol.for(\"palbase.backend.appDefaultAuth\") as never;\n\nfunction appAuthSlot(): Record<symbol, AuthSpec | undefined> {\n  return globalThis as unknown as Record<symbol, AuthSpec | undefined>;\n}\n\n/**\n * Declare the default auth for EVERY route in the application — the ring the\n * cascade consults when neither the route nor its controller says anything.\n *\n * The measured problem it removes: `auth: { verifiedEmail: true }` repeated by\n * hand on ten `@Controller`s. A security setting that must be repeated is a\n * security setting that will be forgotten — the eleventh controller opens the\n * door and nothing says so.\n *\n * Call it at MODULE SCOPE in a file the application imports (the controllers'\n * own barrel, or a module a controller imports). The cascade reads this slot\n * when the route table is built and when the spec is emitted — both of which\n * run after module loading — so declaration order does not matter, but being\n * imported at all does.\n *\n * @example\n * defineDefaultAuth({ verifiedEmail: true });  // every route, unless it says otherwise\n */\nexport function defineDefaultAuth(auth: AuthSpec): void {\n  appAuthSlot()[APP_DEFAULT_AUTH] = auth;\n}\n\n/** The declared application default, or `undefined` when none was declared. */\nexport function getDefaultAuth(): AuthSpec | undefined {\n  return appAuthSlot()[APP_DEFAULT_AUTH];\n}\n\n/** Clear the application default. For tests, which declare it repeatedly. */\nexport function __resetDefaultAuth(): void {\n  delete appAuthSlot()[APP_DEFAULT_AUTH];\n}\n\n/**\n * THE auth cascade: route → controller → application → `true`.\n *\n * One function, every caller — the route table (`engine/router.ts`) and the\n * spec emitter (`openapi/controllers.ts`) ASK for the answer instead of\n * spelling the chain themselves. Two hand-written copies of a cascade is how\n * the build-time answer and the runtime answer come to disagree about who may\n * call an endpoint, and the disagreement shows up as an open door.\n *\n * The terminal `true` is secure-by-default and is load-bearing: a route that\n * declared nothing, under a controller that declared nothing, in an\n * application that declared nothing, is CLOSED.\n */\nexport function resolveEffectiveAuth(\n  routeAuth: AuthSpec | undefined,\n  controllerAuth: AuthSpec | undefined,\n): AuthSpec {\n  return routeAuth ?? controllerAuth ?? getDefaultAuth() ?? true;\n}\n\n/** A class carrying the stamped controller metadata + discriminant. */\ninterface ControllerCarrier {\n  __palbase?: \"controller\";\n  [CONTROLLER_META]?: ControllerMeta;\n}\n\n/** The one path segment the platform owns. The isolate matches\n * `^/webhooks/([^/]+)$` on the raw request path BEFORE controller dispatch, so\n * anything a controller resolves to under it answers `404 webhook_not_found`\n * and never runs. */\nconst RESERVED_FIRST_SEGMENT = \"webhooks\";\n\n/**\n * Throw if `path` resolves under the reserved segment. Segments are compared the\n * way the isolate compares them — `split(\"/\").filter(Boolean)` — NOT by string\n * prefix, because empty segments collapse there: `@Controller(\"/\")` +\n * `@Post(\"/webhooks/x\")` composes to `//webhooks/x`, which the isolate serves as\n * `/webhooks/x`. A prefix check reads that as safe; the segment check does not.\n * `/webhooksy` stays allowed for the same reason — it is a different segment.\n *\n * Every verb is refused, not just the POST the isolate currently intercepts: the\n * reservation is of the URL namespace, so a `@Get(\"/webhooks/x\")` that happens\n * to work today would be silently shadowed the moment the isolate's method gate\n * widens. Refusing at build is recoverable; discovering it as a 404 is not.\n */\nfunction assertNotReserved(path: string, subject: string): void {\n  const [first] = path.split(\"/\").filter(Boolean);\n  if (first === RESERVED_FIRST_SEGMENT) {\n    throw new Error(\n      `${subject} resolves under the reserved /${RESERVED_FIRST_SEGMENT} path — ` +\n        \"inbound webhooks are served there and would shadow this route\",\n    );\n  }\n}\n\n/**\n * Mark a class as a Palbase backend controller. `basePath` is the mount path\n * for every route the class declares; `options.auth` sets the controller-level\n * default auth (a route's own `auth` overrides it; absent ⇒ secure-by-default).\n *\n * @example\n * \\@Controller(\"/todos\", { auth: false })\n * export class TodosController {\n *   \\@Get(\"\") list(\\@QueryParams(ListTodosQuery) q: ListTodosQuery): TodoSchema[] { … }\n * }\n */\nexport function Controller(basePath: string, options: ControllerOptions = {}) {\n  return function <T extends abstract new (...args: never[]) => object>(ctor: T): T {\n    // /webhooks/* belongs to the platform: the isolate matches the inbound\n    // webhook route before controller dispatch, so a controller mounted here\n    // would never receive a request. Silent shadowing is the failure mode this\n    // whole change exists to remove, so refuse it at build.\n    //\n    // The COMPOSED path is what gets shadowed, not the base path. `@Controller(\"\")`\n    // and `@Controller(\"/\")` both pass a base-path-only check while a\n    // `@Post(\"/webhooks/stripe\")` inside them resolves to exactly the path the\n    // isolate intercepts. Method decorators run BEFORE the class decorator (TS\n    // evaluates members first), so every route this class declares is already in\n    // the registry here — which is why the composed check can live at this one\n    // seam instead of on the dispatch read path. The `@Controller(\"\") +\n    // @Post(\"/webhooks/stripe\")` test is the lock on that ordering: if it ever\n    // stopped holding, that test goes red.\n    assertNotReserved(basePath, `@Controller(\"${basePath}\")`);\n    for (const route of getRoutes(ctor)) {\n      assertNotReserved(\n        `${basePath}${route.subpath}`,\n        `@${route.method}(\"${route.subpath}\") in @Controller(\"${basePath}\")`,\n      );\n    }\n\n    const carrier = ctor as unknown as ControllerCarrier;\n    const meta: ControllerMeta = {\n      __palbase: \"controller\",\n      basePath,\n      ...(options.auth !== undefined ? { defaultAuth: options.auth } : {}),\n    };\n    // Non-enumerable so it doesn't leak onto instances / structural checks.\n    Object.defineProperty(carrier, CONTROLLER_META, {\n      value: meta,\n      enumerable: false,\n      configurable: true,\n      writable: false,\n    });\n    // The bare `__palbase` discriminant is the cheap detection marker the\n    // runtime/extractor checks; keep it readable but non-enumerable.\n    Object.defineProperty(carrier, \"__palbase\", {\n      value: \"controller\",\n      enumerable: false,\n      configurable: true,\n      writable: false,\n    });\n    // Record it, so importing the file is enough and exporting is optional.\n    // Guarded against a double-decoration re-entering the same class twice.\n    const all = registry();\n    if (!all.includes(ctor)) all.push(ctor);\n    return ctor;\n  };\n}\n\n/** True when `value` is a `@Controller`-decorated class (cheap discriminant\n * check). Accepts the class constructor (the default export of a controller\n * file). */\nexport function isController(value: unknown): boolean {\n  if (typeof value !== \"function\" && (typeof value !== \"object\" || value === null)) {\n    return false;\n  }\n  const carrier = value as ControllerCarrier;\n  return carrier.__palbase === \"controller\" && carrier[CONTROLLER_META] !== undefined;\n}\n\n/** Read the resolved controller metadata off a `@Controller`-decorated class.\n * Throws if the class was not decorated — callers should gate with\n * {@link isController} first (the loader does). */\nexport function resolveController(ctor: unknown): ControllerMeta {\n  if (typeof ctor !== \"function\" && (typeof ctor !== \"object\" || ctor === null)) {\n    throw new TypeError(\"resolveController: value is not a class\");\n  }\n  const meta = (ctor as ControllerCarrier)[CONTROLLER_META];\n  if (!meta) {\n    throw new TypeError(\n      \"resolveController: class is not a @Controller — decorate it with `@Controller(path)` and list it in a module's `controllers`\",\n    );\n  }\n  return meta;\n}\n\n/**\n * A class the runtime constructs takes NO constructor parameters.\n *\n * ONE writer, four callers (controller, hook, job, webhook) and the build's own\n * check. Four hand-written copies of this message is how the four come to\n * disagree about what is refused — and the disagreement is silent, because a\n * class that slips past one of them still ends up with `undefined` fields.\n *\n * Why it is refused rather than injected: there is no container. The parameter\n * would arrive `undefined`, the code would compile, deploy, and fail at the\n * first request that touches the field — the most expensive place to learn it.\n */\nexport function assertZeroArgConstructor(Ctrl: unknown, kind: string): void {\n  const arity = (Ctrl as { length?: number }).length ?? 0;\n  if (arity === 0) return;\n\n  // This function's NAME is a promise: whatever reaches it will be constructed\n  // with a zero-argument constructor. Letting a class with parameters through\n  // would make the name a lie — worse than the rename FR-029 guards against.\n  //\n  // An earlier design made it \"declaration-aware\": pass when metadata matches\n  // arity. Measured, that re-opens the exact silence this exists to close.\n  // ANY decorator triggers metadata emission, not just `@Injectable`:\n  //\n  //     @Job(...) class J { constructor(repo: unknown) {} }\n  //       → design:paramtypes = [Object]        ← matches arity\n  //\n  // so J would pass, then be built with `new J()`, and `repo` would be\n  // `undefined` at the first scheduled run. Four tests in this repo asserted\n  // that refusal and all four went red; the tests were right.\n  //\n  // What changed instead is the MESSAGE, and who calls this. Callers holding a\n  // container resolve from it and never come here (router.ts, job/hook/webhook);\n  // this stays the guard for the container-less path, and keeps its promise.\n  const name = (Ctrl as { name?: string }).name ?? \"<anonymous>\";\n  throw new Error(\n    `${kind} ${name} declares a constructor with ${arity} parameter(s), and this path ` +\n      `builds it with a zero-argument constructor — every parameter would arrive as ` +\n      `undefined. If you meant to inject them, add @Injectable() to ${name} and list it ` +\n      `in a module's providers, so the container builds it instead.`,\n  );\n}\n"],"mappings":"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","names":["ROUTES","Symbol","for","PARAM_BUFFER","ROOM","ROOM_HOOKS","RETURN_BUFFER","THROWS_BUFFER","carrierOf","target","ctor","ownRoutes","carrier","Object","prototype","hasOwnProperty","call","ownParamBuffer","recordRoute","fnName","method","subpath","options","routes","buffer","params","slice","sort","a","b","index","route","returnBuffer","undefined","returnSchema","throwsBuffer","throws","push","recordParam","meta","find","r","recordThrows","target","fnName","throws","carrier","carrierOf","routes","ROUTES","route","find","r","Object","prototype","hasOwnProperty","call","THROWS_BUFFER","throwsBuffer","getRoutes","ctor","returnBuffer","RETURN_BUFFER","buffered","returnSchema","undefined","map","params","slice","ownRoomBuffer","ROOM_HOOKS","hooks","messages","recordRoomHook","hook","buffer","existing","label","charAt","toUpperCase","Error","recordRoomMessage","name","schema","recordRoom","meta","ROOM","g","globalThis","REGISTRY","Symbol","for","all","includes","push","getRoom","CONTROLLER_META","Symbol","for","REGISTRY","registry","g","globalThis","existing","fresh","getRegisteredControllers","slice","__resetRegisteredControllers","length","APP_DEFAULT_AUTH","appAuthSlot","defineDefaultAuth","auth","getDefaultAuth","__resetDefaultAuth","resolveEffectiveAuth","routeAuth","controllerAuth","RESERVED_FIRST_SEGMENT","assertNotReserved","path","subject","first","split","filter","Boolean","Error","Controller","basePath","options","ctor","route","getRoutes","subpath","method","carrier","meta","__palbase","undefined","defaultAuth","Object","defineProperty","value","enumerable","configurable","writable","all","includes","push","isController","resolveController","TypeError","assertZeroArgConstructor","Ctrl","kind","arity","name"]}