@palbase/backend 23.1.0 → 24.0.1

package/template/AGENTS.md

@@ -18,10 +18,19 @@ import { Controller, Get, Post, Patch, Delete, Body, QueryParams, Param, User, z
 
 ```
 controllers/<name>.controller.ts   a @Controller class; each method is a route
+services/<name>.service.ts         the logic, as a plain class
 db/schema.ts                       the database: tables, columns, RLS policies
-config/secrets.ts                  the secrets this backend needs (names only)
+palbase-stack.d.ts                 GENERATED — the names your stack actually holds
+palbase-env.d.ts                   GENERATED — your tables, as types
 ```
 
+Both generated files are written by `palbase build` and **committed**. They are
+what makes `Secrets.get("X")`, `Flags.isEnabled("y")`, `@Upload({ bucket })` and
+`Database.tables.*` compile: the names come from the stack and the schema, so
+there is no second list in this repo to drift out of date. A project that has
+never run `palbase build` has no valid names and those calls will not compile —
+that is the gate working, not a rough edge. Run it once and commit both files.
+
 Two folders appear as the project grows, and both are conventions the tooling
 already understands:
 
@@ -137,7 +146,18 @@ throw new TooManyRequests({ retryAfter: 30 });          // data-first
 
 Every route requires a signed-in user by default. `@Controller("/x", { auth: false })`
 opens all of a class's routes; `@Get("", { auth: true })` overrides it for one.
-Resolution is route → controller → default `true`.
+
+An application-wide default sits under those two:
+
+```ts
+import { defineDefaultAuth } from "@palbase/backend";
+defineDefaultAuth({ verifiedEmail: true });   // every route, unless it says otherwise
+```
+
+Put that call in `auth.ts` at the project root — the bundler imports that file by
+name, so the declaration cannot be silently left out of the build. Resolution is
+route → controller → application → `true`. Writing the same auth setting on ten
+controllers is how the eleventh one gets forgotten.
 
 ## Models — schemas, one file per endpoint
 
@@ -155,27 +175,53 @@ Shared response schemas go in `models/<controller>/shared.ts`.
 
 ## Services — business logic
 
-Plain classes exported as a singleton. No DI container, no decorators.
+Plain classes wired as a module-level singleton. No DI container, no decorators
+— and this is the ONLY supported way to hold a dependency anywhere in this
+runtime. A controller, hook, job or webhook is constructed with **no arguments**;
+one that declares a constructor parameter is refused at build with the class
+named, because there is no injector to fill it and the field would simply be
+`undefined` in production.
 
-```ts
-// services/todo.service.ts
-import { Database } from "@palbase/backend";
+`services/note.service.ts` in this scaffold is the worked example. The shape:
 
-export class TodoService {
-  list(userId: string) {
-    return Database.tables.todos.findMany({ user_id: userId });
-  }
-  create(userId: string, title: string) {
-    return Database.tables.todos.insert({ user_id: userId, title });
-  }
+```ts
+export class NoteService {
+  private readonly notes: typeof Database.tables.notes;
+  // Assigned in the BODY — `constructor(private notes: …)` is a parameter
+  // property, and Node's type-stripping test runner refuses those per FILE.
+  constructor(notes: typeof Database.tables.notes) { this.notes = notes; }
+  list(userId: string) { return this.notes.findMany({ user_id: userId }); }
 }
 
-export const todoService = new TodoService();
+/** Controllers import THIS, never the class. */
+export const noteService = new NoteService(Database.tables.notes);
 ```
 
-`Database.tables.<name>` gives `insert`, `update(id, data)`, `delete(id)`,
-`findById(id)`, `findMany(filter?)`, and `Database.transaction(fn)` for a plan
-that commits or rolls back as one.
+The constructor is the seam: the class is handed the table rather than reaching
+for the singleton, so a test constructs it with a stand-in and never needs a
+database. `fakeDatabase()` from `@palbase/backend/test` is that stand-in when you
+want the whole surface instead of one table.
+
+`Database.tables.<name>` gives:
+
+| | |
+|---|---|
+| `insert(row)` · `upsert(row, { onConflict })` | write one |
+| `update(id, data)` · `delete(id)` | write one, by id |
+| `updateMany(where, set)` · `deleteMany(where)` | write every row the filter matches, in ONE statement |
+| `findById(id)` · `findMany(where?, opts?)` | read |
+| `count(where?)` | how many match |
+
+`where` takes a plain value for equality or an operator object —
+`{ n: { gte: 3 } }`, `{ id: { in: [...] } }`, also `gt` / `lt` / `lte` / `neq`.
+`opts` takes `{ orderBy: { column, direction }, limit, offset }`, so ordering and
+paging happen in SQL rather than in JavaScript after fetching everything.
+`updateMany`/`deleteMany` REFUSE an empty filter — a whole-table write is not
+something to reach by accident.
+
+`Database.transaction(fn)` runs a plan that commits or rolls back as one, and
+`Database.attempt(fn)` opens a savepoint so one failed write does not poison the
+rest of the request.
 
 ## The database — declared, not migrated
 
@@ -194,37 +240,62 @@ RLS is on by default and a table with no policies is deny-all. Add
 `policies: [policy(...)]` so Postgres enforces ownership — a query that forgets
 its `where user_id = …` still cannot read another user's rows.
 
-After a schema change, regenerate the typed surface so `Database.tables.*` keeps
-matching what is actually there (`palbase --help` names the command).
+After a schema change run `palbase build`: it regenerates BOTH generated files —
+`palbase-env.d.ts` (your tables) and `palbase-stack.d.ts` (the stack's names) —
+so `Database.tables.*` keeps matching what is actually there. Commit them.
 
-## Config as code
+## Secrets, flags, buckets — read from the stack
 
-`config/*.ts` declares module configuration the same git-authoritative way the
-schema does, applied on deploy:
+There is no `config/` directory and nothing to declare in this repo. Settings are
+written to the STACK with the CLI, and the code READS them:
 
-- `config/secrets.ts` — `defineSecrets({ secrets: [secret("NAME", …)] })`
-- `config/storage.ts` — `defineStorage(...)` buckets
-- `config/notifications.ts` — `defineNotifications(...)` providers
-- `config/flags.ts` — `defineFlags(...)` feature flags
+```ts
+import { Secrets, Flags } from "@palbase/backend";
+const dsn = await Secrets.get("SENTRY_DSN");     // compiles only if the stack holds it
+if (await Flags.isEnabled("newCheckout")) { … }  // same
+```
+
+The name in the quotes is checked by the compiler against `palbase-stack.d.ts`,
+which `palbase build` generates from the stack. A secret's VALUE never enters
+this repository, and you never read `process.env` for one.
+
+Writing a setting is a CLI job, not a code job — `palbase --help` names the
+commands (`secret`, `flags`, `storage`, `notifications`, `auth`). Settings have
+one door; a second one is how the two come to disagree.
 
-### Secrets
+## Lifecycle — for things that are expensive to build
 
-A secret's **value** never enters this repository. `config/secrets.ts` declares
-the NAME and whether it is required; the value lives in the environment's vault
-and reaches the process through `Secrets.get("NAME")`:
+Most handlers need nothing here: the SDK's singletons are already pooled. But a
+long-lived object you build yourself needs somewhere to close, and a process that
+never closes one leaks it per deploy:
 
 ```ts
-import { Secrets } from "@palbase/backend";
-const dsn = await Secrets.get("SENTRY_DSN"); // string | null
+import { onStart, onShutdown } from "@palbase/backend";
+
+let client: SomeClient | undefined;
+onStart("graph", () => { client = SomeClient.create({ maxPoolSize: 8 }); });
+onShutdown("graph", async () => { await client?.close(); });
 ```
 
-Declaring it is what turns a missing secret into a refused push that names it,
-instead of a 500 on the first request that touches it. Never read
-`process.env` for one, and never commit a `.env`.
+The NAME is the first argument, and it is what a failure is reported by — a stack
+trace through an anonymous closure names nothing. `onStart` runs ONCE as the app
+comes up, and a hook that throws refuses the boot rather than letting the app
+serve traffic with a half-built dependency. `onShutdown` hooks run in reverse
+order and are best-effort: one that throws is reported and the rest still run.
 
-Provider certs and keys are the same rule: author them with the guided CLI,
-which uploads the file to the vault and writes only the non-secret fields into
-`config/notifications.ts`.
+**These hooks run OUTSIDE a request, so no Palbase service is reachable from
+them** — `Secrets`, `Database`, `Log` and the rest all throw "accessed outside a
+request scope". If your object needs a secret, build it lazily on first use
+inside a handler instead:
+
+```ts
+let client: SomeClient | undefined;
+async function graph() {
+  client ??= SomeClient.create({ url: await Secrets.get("GRAPH_URL") });
+  return client;
+}
+onShutdown("graph", async () => { await client?.close(); });
+```
 
 ## Tests
 
@@ -233,9 +304,18 @@ install and nothing to configure — Node discovers the files and strips the typ
 itself.
 
 Test the **service** layer. Controllers are thin by construction, so the logic
-that can be wrong lives in a service, which is a plain class you construct
-directly. A service that needs `Database` takes it as a constructor argument
-instead of importing the singleton, and the test passes a stand-in.
+that can be wrong lives in a service — a plain class you construct directly with
+a stand-in, exactly as `services/note.service.ts` is written. For a stand-in
+covering the whole database surface rather than one table:
+
+```ts
+import { fakeDatabase } from "@palbase/backend/test";
+const { db, queries } = fakeDatabase();
+```
+
+It answers `tables.*` from memory and records the `query` calls made. What it
+does NOT do is enforce RLS, constraints or unique violations — those are real
+database behaviour, and the test that proves them runs against a real one.
 
 Node **strips** types, it never emits code, so TypeScript features that require
 emitted code are refused outright: parameter properties (`constructor(private x: T)`),

package/template/controllers/notes.controller.ts

@@ -0,0 +1,64 @@
+import { Body, Controller, Delete, Get, NotFound, Param, Post, User, z } from "@palbase/backend";
+import type { UserT } from "@palbase/backend";
+
+import { noteService } from "../services/note.service";
+
+// The other half of the vertical that starts in `services/note.service.ts`.
+//
+// Everything a controller does here is HTTP: validate the body through a named
+// schema, name the 200 shape as the return type, turn a missing row into a
+// status. The logic — which rows, whose, in what order — lives in the service,
+// which is why the service is the thing worth testing and this class has
+// nothing in it to get wrong.
+//
+// So there is one rule, and it is the whole reason the layer exists: a
+// controller does not import `Database`. If a method here starts reaching for a
+// table, the logic has leaked into the layer that is hardest to test.
+//
+// The dependency is a MODULE-LEVEL SINGLETON, imported. It is not a constructor
+// parameter: the runtime constructs this class with no arguments, and a
+// controller that declares one is refused at build with the class named rather
+// than handed `undefined` in production.
+
+export const NoteSchema = z.object({
+  id: z.string(),
+  user_id: z.string(),
+  body: z.string(),
+  created_at: z.string(),
+});
+export type NoteSchema = z.infer<typeof NoteSchema>;
+
+export const CreateNoteBody = z.object({
+  body: z.string().min(1),
+});
+export type CreateNoteBody = z.infer<typeof CreateNoteBody>;
+
+// Auth is required unless a route opts out, so `@User()` is non-null here and
+// every method below acts as somebody.
+@Controller("/notes")
+class NotesController {
+  @Get("")
+  list(@User() user: UserT): Promise<NoteSchema[]> {
+    return noteService.list(user.id);
+  }
+
+  @Post("")
+  create(@Body(CreateNoteBody) body: CreateNoteBody, @User() user: UserT): Promise<NoteSchema> {
+    return noteService.create(user.id, body.body);
+  }
+
+  @Get("/{id}")
+  async get(@Param("id") id: string): Promise<NoteSchema> {
+    // `null` covers both "no such note" and "not yours" — the second is not
+    // distinguishable from the outside on purpose, because telling a caller
+    // that a row they may not read exists is itself a leak.
+    const note = await noteService.get(id);
+    if (!note) throw new NotFound("no note with that id");
+    return note;
+  }
+
+  @Delete("/{id}")
+  remove(@Param("id") id: string): Promise<void> {
+    return noteService.remove(id);
+  }
+}

package/template/package.json

@@ -9,7 +9,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@palbase/backend": "^23.0.0"
+    "@palbase/backend": "^24.0.0"
   },
   "devDependencies": {
     "@types/node": "^22",

package/template/services/note.service.ts

@@ -0,0 +1,74 @@
+import { Database } from "@palbase/backend";
+import type { Tables } from "@palbase/backend/env";
+
+// A SERVICE is where the logic lives. It is a plain class — no decorator, no DI
+// container, nothing to register. What makes the layer real is the two lines at
+// the bottom of this file, not the folder name.
+//
+// THE SEAM IS THE CONSTRUCTOR. The class is handed the table it works on rather
+// than reaching for the singleton itself, so a test constructs it with a
+// stand-in and never needs a database:
+//
+//   const svc = new NoteService(fakeNotesTable);
+//   assert.deepEqual(await svc.list("u_1"), []);
+//
+// The module then wires the real one ONCE, on the last line, and that instance
+// is what a controller imports. That module-level singleton is also the
+// supported way to hold a dependency ANYWHERE in this runtime: a controller,
+// hook, job or webhook is constructed with no arguments, and one that declares
+// a constructor parameter is refused at build with the class named — there is
+// no injector to fill it, so the field would simply be `undefined` in
+// production.
+//
+// `Database.tables.notes` is typed from `db/schema.ts` through the generated
+// `palbase-env.d.ts`, which `palbase build` writes. Before the first build that
+// file does not exist yet and the table is unknown to the type checker; build
+// once and the whole surface below is typed with no import and no generic.
+
+/** One row of `notes`, exactly as `db/schema.ts` declares it. */
+export type Note = Tables["notes"]["row"];
+
+/** The typed surface of one table: `insert`, `update`, `delete`, `findById`,
+ * `findMany`. Naming it here is what keeps the seam ONE table wide — a test
+ * fake implements five methods, not the whole `Database`. */
+type NotesTable = typeof Database.tables.notes;
+
+export class NoteService {
+  private readonly notes: NotesTable;
+
+  // Assigned in the BODY, never as a parameter property (`constructor(private
+  // notes: NotesTable)`). `npm test` runs Node's type-stripping test runner,
+  // which refuses parameter properties — and refuses them for the whole FILE,
+  // so one of them anywhere in a test's import graph reads like a dozen broken
+  // tests and is one keyword.
+  constructor(notes: NotesTable) {
+    this.notes = notes;
+  }
+
+  /** The caller's notes. The filter is written out even though the table's RLS
+   * policy already scopes the read to `auth.uid()`: the policy is the backstop
+   * that holds when a query forgets, not a reason to stop writing the query. */
+  list(userId: string): Promise<Note[]> {
+    return this.notes.findMany({ user_id: userId });
+  }
+
+  /** `user_id` is `notNull` with no default, so ownership is written here —
+   * it is not something the request body may carry. */
+  create(userId: string, body: string): Promise<Note> {
+    return this.notes.insert({ user_id: userId, body });
+  }
+
+  /** No `userId` argument, and that is not an oversight: another user's note is
+   * invisible to this read, so it comes back `null` exactly as a missing id
+   * does. Postgres enforces it, not this method. */
+  get(id: string): Promise<Note | null> {
+    return this.notes.findById(id);
+  }
+
+  remove(id: string): Promise<void> {
+    return this.notes.delete(id);
+  }
+}
+
+/** The wired instance. Controllers import THIS, never the class. */
+export const noteService = new NoteService(Database.tables.notes);

package/template/tsconfig.json

@@ -19,12 +19,22 @@
     // it, so imports elsewhere stay extensionless.
     "allowImportingTsExtensions": true
   },
+  // Every directory the deploy path compiles has to be in here, or a file in it
+  // is type-checked by nothing until it is already running: `jobs/`, `hooks/`
+  // and `webhooks/` are read straight off disk by the bundler (one default-
+  // exported class per file), and `middleware/` only reaches a build through
+  // whichever controller imports it. `config/` is gone — 23.0.0 removed the
+  // declarations it held, and the settings it used to declare are written to the
+  // stack with the CLI.
   "include": [
     "controllers/**/*.ts",
     "models/**/*.ts",
     "services/**/*.ts",
-    "config/**/*.ts",
     "db/**/*.ts",
+    "jobs/**/*.ts",
+    "hooks/**/*.ts",
+    "webhooks/**/*.ts",
+    "middleware/**/*.ts",
     "*.d.ts"
   ]
 }

package/dist/chunk-HQRJDARQ.js

@@ -1,90 +0,0 @@
-import {
-  getRoutes
-} from "./chunk-RCLNBJCM.js";
-
-// src/decorators/controller.ts
-var CONTROLLER_META = /* @__PURE__ */ Symbol.for("palbase.backend.controllerMeta");
-var REGISTRY = /* @__PURE__ */ Symbol.for("palbase.backend.allControllers");
-function registry() {
-  const g = globalThis;
-  const existing = g[REGISTRY];
-  if (existing) return existing;
-  const fresh = [];
-  g[REGISTRY] = fresh;
-  return fresh;
-}
-function getRegisteredControllers() {
-  return registry().slice();
-}
-function __resetRegisteredControllers() {
-  registry().length = 0;
-}
-var RESERVED_FIRST_SEGMENT = "webhooks";
-function assertNotReserved(path, subject) {
-  const [first] = path.split("/").filter(Boolean);
-  if (first === RESERVED_FIRST_SEGMENT) {
-    throw new Error(
-      `${subject} resolves under the reserved /${RESERVED_FIRST_SEGMENT} path \u2014 inbound webhooks are served there and would shadow this route`
-    );
-  }
-}
-function Controller(basePath, options = {}) {
-  return function(ctor) {
-    assertNotReserved(basePath, `@Controller("${basePath}")`);
-    for (const route of getRoutes(ctor)) {
-      assertNotReserved(
-        `${basePath}${route.subpath}`,
-        `@${route.method}("${route.subpath}") in @Controller("${basePath}")`
-      );
-    }
-    const carrier = ctor;
-    const meta = {
-      __palbase: "controller",
-      basePath,
-      ...options.auth !== void 0 ? { defaultAuth: options.auth } : {}
-    };
-    Object.defineProperty(carrier, CONTROLLER_META, {
-      value: meta,
-      enumerable: false,
-      configurable: true,
-      writable: false
-    });
-    Object.defineProperty(carrier, "__palbase", {
-      value: "controller",
-      enumerable: false,
-      configurable: true,
-      writable: false
-    });
-    const all = registry();
-    if (!all.includes(ctor)) all.push(ctor);
-    return ctor;
-  };
-}
-function isController(value) {
-  if (typeof value !== "function" && (typeof value !== "object" || value === null)) {
-    return false;
-  }
-  const carrier = value;
-  return carrier.__palbase === "controller" && carrier[CONTROLLER_META] !== void 0;
-}
-function resolveController(ctor) {
-  if (typeof ctor !== "function" && (typeof ctor !== "object" || ctor === null)) {
-    throw new TypeError("resolveController: value is not a class");
-  }
-  const meta = ctor[CONTROLLER_META];
-  if (!meta) {
-    throw new TypeError(
-      "resolveController: class is not a @Controller \u2014 every controller file must `export default` a @Controller-decorated class"
-    );
-  }
-  return meta;
-}
-
-export {
-  getRegisteredControllers,
-  __resetRegisteredControllers,
-  Controller,
-  isController,
-  resolveController
-};
-//# sourceMappingURL=chunk-HQRJDARQ.js.map

package/dist/chunk-HQRJDARQ.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/decorators/controller.ts"],"sourcesContent":["// `@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` ⇒ secure-by-default. */\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  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/** 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 — every controller file must `export default` a @Controller-decorated class\",\n    );\n  }\n  return meta;\n}\n"],"mappings":";;;;;AA8BO,IAAM,kBAAiC,uBAAO,IAAI,gCAAgC;AAiBzF,IAAM,WAA0B,uBAAO,IAAI,gCAAgC;AAE3E,SAAS,WAAsB;AAC7B,QAAM,IAAI;AACV,QAAM,WAAW,EAAE,QAAQ;AAC3B,MAAI,SAAU,QAAO;AACrB,QAAM,QAAmB,CAAC;AAC1B,IAAE,QAAQ,IAAI;AACd,SAAO;AACT;AAUO,SAAS,2BAA+C;AAC7D,SAAO,SAAS,EAAE,MAAM;AAC1B;AAGO,SAAS,+BAAqC;AACnD,WAAS,EAAE,SAAS;AACtB;AAYA,IAAM,yBAAyB;AAe/B,SAAS,kBAAkB,MAAc,SAAuB;AAC9D,QAAM,CAAC,KAAK,IAAI,KAAK,MAAM,GAAG,EAAE,OAAO,OAAO;AAC9C,MAAI,UAAU,wBAAwB;AACpC,UAAM,IAAI;AAAA,MACR,GAAG,OAAO,iCAAiC,sBAAsB;AAAA,IAEnE;AAAA,EACF;AACF;AAaO,SAAS,WAAW,UAAkB,UAA6B,CAAC,GAAG;AAC5E,SAAO,SAA+D,MAAY;AAehF,sBAAkB,UAAU,gBAAgB,QAAQ,IAAI;AACxD,eAAW,SAAS,UAAU,IAAI,GAAG;AACnC;AAAA,QACE,GAAG,QAAQ,GAAG,MAAM,OAAO;AAAA,QAC3B,IAAI,MAAM,MAAM,KAAK,MAAM,OAAO,sBAAsB,QAAQ;AAAA,MAClE;AAAA,IACF;AAEA,UAAM,UAAU;AAChB,UAAM,OAAuB;AAAA,MAC3B,WAAW;AAAA,MACX;AAAA,MACA,GAAI,QAAQ,SAAS,SAAY,EAAE,aAAa,QAAQ,KAAK,IAAI,CAAC;AAAA,IACpE;AAEA,WAAO,eAAe,SAAS,iBAAiB;AAAA,MAC9C,OAAO;AAAA,MACP,YAAY;AAAA,MACZ,cAAc;AAAA,MACd,UAAU;AAAA,IACZ,CAAC;AAGD,WAAO,eAAe,SAAS,aAAa;AAAA,MAC1C,OAAO;AAAA,MACP,YAAY;AAAA,MACZ,cAAc;AAAA,MACd,UAAU;AAAA,IACZ,CAAC;AAGD,UAAM,MAAM,SAAS;AACrB,QAAI,CAAC,IAAI,SAAS,IAAI,EAAG,KAAI,KAAK,IAAI;AACtC,WAAO;AAAA,EACT;AACF;AAKO,SAAS,aAAa,OAAyB;AACpD,MAAI,OAAO,UAAU,eAAe,OAAO,UAAU,YAAY,UAAU,OAAO;AAChF,WAAO;AAAA,EACT;AACA,QAAM,UAAU;AAChB,SAAO,QAAQ,cAAc,gBAAgB,QAAQ,eAAe,MAAM;AAC5E;AAKO,SAAS,kBAAkB,MAA+B;AAC/D,MAAI,OAAO,SAAS,eAAe,OAAO,SAAS,YAAY,SAAS,OAAO;AAC7E,UAAM,IAAI,UAAU,yCAAyC;AAAA,EAC/D;AACA,QAAM,OAAQ,KAA2B,eAAe;AACxD,MAAI,CAAC,MAAM;AACT,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACA,SAAO;AACT;","names":[]}