@palbase/backend 3.0.0 → 5.0.0

package/docs/llms-full.txt

@@ -1,6 +1,6 @@
 # Palbase Backend SDK (`@palbase/backend`)
 
-> File-based TypeScript backend SDK. All handler types import service singletons (`Database`, `Cache`, …). Trigger arg differs by type: endpoints use `req`, workers `(payload, meta)`, jobs `(meta)`, hooks/webhooks `(event, meta)`. Middleware is the one exception (`ctx`). Not Express, not Supabase Edge Functions.
+> TypeScript backend SDK. NestJS-style class controllers: `@Controller` classes with `@Get`/`@Post`/… methods and `@Body`/`@Query`/`@Param`/`@User` parameter decorators. All handler types import service singletons (`Database`, `Cache`, …). Trigger arg differs by type: endpoints use parameter decorators, workers `(payload, meta)`, jobs `(meta)`, hooks/webhooks `(event, meta)`. Middleware is the one exception (`ctx`). Not Express, not Supabase Edge Functions.
 
 
 
@@ -12,10 +12,202 @@ Write your backend as TypeScript files. Palbase discovers them by path, runs
 them inside the managed backend runtime, and exposes them as a typed HTTP API.
 
 This is **not** Express, Fastify, or a Supabase Edge Function. There is no
-`app.get(...)`, no manual route registration, no `import express`. You export
-definitions; the runtime wires them up.
+`app.get(...)`, no manual route registration, no `import express`. You author
+**class controllers** with method + parameter decorators (NestJS-style); the
+runtime wires them up.
 
-## Mental model (important)
+## AGENTS / AI codegen guide (read this first)
+
+If you are an AI generating a Palbase backend, this is the contract. Get these
+seven rules right and the deploy succeeds; get them wrong and it fails the
+deploy gate or the TypeScript compile.
+
+### Folder layout
+
+```
+controllers/<name>.controller.ts   # @Controller class + @Get/@Post/… route methods (the API surface)
+models/<controller>/<endpoint>.ts   # zod schemas — one folder per controller, one file per endpoint (+ shared.ts)
+services/<name>.service.ts          # plain class + singleton — the real logic (controllers stay thin)
+db/schema.ts                        # config-as-code Postgres schema (tables, columns, RLS) — auto-migrated on deploy
+```
+
+The four folders above are the daily surface. These also exist (own docs, linked
+below): `resources/` (external connections — [resources.md](./resources.md)),
+`seeds/` (seed data), `jobs/` + `workers/` (background — [background.md](./background.md)),
+`webhooks/` + `hooks/` (events — [events.md](./events.md)), `middleware/`.
+
+### The 7 rules (checklist)
+
+1. **`export default <ControllerClass>` is REQUIRED.** Every `controllers/*.controller.ts`
+   must default-export its `@Controller` class, or the deploy FAILS with a
+   "not a @Controller / non-controller export" error. Either `export default class X {}`
+   or a trailing `export default X;` — both work.
+2. **Methods that call a service are `async` and return `Promise<T>`.** Services
+   `await Database`, so they return promises; a sync return type on an async body
+   is a tsc error. Annotate `: Promise<TodoSchema>`, not `: TodoSchema`, whenever
+   the body awaits.
+3. **`@User()` (value) vs `UserT` (type) are two different imports.**
+   `import { User } from "@palbase/backend"` (the decorator) +
+   `import type { UserT } from "@palbase/backend"` (the user type). Write
+   `@User() user: UserT`. They are NOT the same symbol.
+4. **The method's RETURN TYPE names the response schema.** Write
+   `: Promise<TodoSchema>` (or `: Promise<z.infer<typeof TodoSchema>>`) — codegen
+   + the runtime read that named type to bind the 200 response zod schema. There
+   is no `@Returns` decorator. A body route with no named return type is a build
+   error; a method with no response body annotates `: Promise<void>` / `: void`.
+5. **Schemas live in `models/<controller>/<endpoint>.ts`,** exported as a zod
+   VALUE and a same-named `z.infer` TYPE. The controller imports them and writes
+   `@Body(CreateTodoBody) body: CreateTodoBody` (value in the decorator, same name
+   as the type annotation).
+6. **Errors are global throw classes.** `throw new Conflict("…")` / `NotFound` /
+   `BadRequest` / `Unauthorized` / `Forbidden` / `TooManyRequests` /
+   `PalError(status, code, msg)` — from a controller OR a service, with no `req`.
+   There is no per-route errors map and no `req.errors`.
+7. **Auth is secure-by-default.** Every route needs a signed-in user unless it
+   opts out: `@Controller("/x", { auth: false })` (whole controller) or
+   `@Get("", { auth: false })` (one route). Cascade: route > controller >
+   default(required). On a public route inject `@OptionalUser() user: UserT | null`.
+
+> **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` 4.
+
+### Complete CRUD example (copy-pasteable, compiles)
+
+```ts
+// models/todos/shared.ts — the response shape, reused across endpoints.
+import { z } from "@palbase/backend";
+export const TodoSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  completed: z.boolean(),
+});
+export type TodoSchema = z.infer<typeof TodoSchema>;
+```
+
+```ts
+// models/todos/create.ts — the POST body.
+import { z } from "@palbase/backend";
+export const CreateTodoBody = z.object({ title: z.string().min(1) });
+export type CreateTodoBody = z.infer<typeof CreateTodoBody>;
+```
+
+```ts
+// services/todo.service.ts — plain class + singleton. The real work.
+import { Database, NotFound } from "@palbase/backend";
+import type { TodoSchema } from "../models/todos/shared.js";
+
+export class TodoService {
+  list(userId: string): Promise<TodoSchema[]> {
+    return Database.tables.todos.findMany({ user_id: userId });
+  }
+  create(userId: string, title: string): Promise<TodoSchema> {
+    return Database.tables.todos.insert({ user_id: userId, title });
+  }
+  async get(userId: string, id: string): Promise<TodoSchema> {
+    const t = await Database.tables.todos.findById(id);
+    if (!t || t.user_id !== userId) throw new NotFound("No todo with that id");
+    return t;
+  }
+  async remove(userId: string, id: string): Promise<void> {
+    const t = await Database.tables.todos.findById(id);
+    if (!t || t.user_id !== userId) throw new NotFound("No todo with that id");
+    await Database.tables.todos.delete(id);
+  }
+}
+export const todoService = new TodoService();
+```
+
+```ts
+// controllers/todos.controller.ts — class controller. Thin: delegates to the service.
+import { Controller, Get, Post, Delete, Body, Param, User } from "@palbase/backend";
+import type { UserT } from "@palbase/backend";       // the user TYPE (@User is the value)
+import { todoService } from "../services/todo.service.js";
+import { TodoSchema } from "../models/todos/shared.js";
+import { CreateTodoBody } from "../models/todos/create.js";
+
+@Controller("/todos")                                  // secure-by-default; { auth: false } opts the whole controller out
+export class TodosController {
+  private todos = todoService;
+
+  @Get("")                                             // GET /todos → operationId getTodos
+  async list(@User() user: UserT): Promise<TodoSchema[]> {  // return type → 200 response schema
+    return this.todos.list(user.id);
+  }
+
+  @Post("")                                            // POST /todos → postTodos
+  async create(@Body(CreateTodoBody) body: CreateTodoBody, @User() user: UserT): Promise<TodoSchema> {
+    return this.todos.create(user.id, body.title);
+  }
+
+  @Get("/{id}")                                        // GET /todos/{id} → getTodosById
+  async get(@Param("id") id: string, @User() user: UserT): Promise<TodoSchema> {
+    return this.todos.get(user.id, id);
+  }
+
+  @Delete("/{id}")                                     // DELETE /todos/{id} → deleteTodosById; no body → : Promise<void>
+  async remove(@Param("id") id: string, @User() user: UserT): Promise<void> {
+    await this.todos.remove(user.id, id);
+  }
+}
+
+export default TodosController;                         // REQUIRED — the runtime loads the default export
+```
+
+```ts
+// db/schema.ts — config-as-code; the deploy auto-migrates additive changes.
+import { defineSchema, uuid, text, boolean, timestamp, policy } from "@palbase/backend";
+export default defineSchema({
+  tables: {
+    todos: {
+      columns: {
+        id:         uuid().primaryKey().defaultRandom(),
+        user_id:    text().notNull(),                  // palauth user id (TEXT, e.g. "usr_…")
+        title:      text().notNull(),
+        completed:  boolean().default(false),
+        created_at: timestamp().defaultNow(),
+      },
+      rls: true,                                       // every Database.* query runs as the request user
+      policies: [
+        policy("pb_owner_all")
+          .for("all")
+          .to("authenticated")
+          .using("user_id = (select auth.uid())")
+          .withCheck("user_id = (select auth.uid())"),
+      ],
+    },
+  },
+});
+```
+
+### operationId — what the generated clients call
+
+The operationId is derived FLAT from the verb + full path (NOT the method name):
+`GET /todos` → `getTodos`, `POST /todos` → `postTodos`, `GET /todos/{id}` →
+`getTodosById`. The generated iOS/TS clients expose these as `pb.getTodos()`,
+`pb.postTodos(...)`, `pb.getTodosById(id:)`. Rename the method freely; the
+operationId is unaffected. Change the verb and the operationId changes — no file
+rename needed.
+
+### CLI workflow
+
+- `palbase serve` — run `controllers/` locally with hot reload (proxies
+  `Database`/services to the deployed branch; runs `gen-types` on startup).
+- `palbase gen-types` — regenerate `palbase-env.d.ts` from `db/schema.ts` so
+  `Database.tables.*` is typed (no import, no generic). Standalone version of what
+  `serve` runs.
+- **Deploy is GitHub-native** — `git push` triggers the deploy (there is no
+  `palbase push`). Push a branch to deploy that branch.
+- `palbase secret set NAME=value` / `palbase secret list` — branch-scoped
+  secrets (encrypted at rest), read in code via `process.env.NAME`.
+- `palbase secret pull` / `palbase secret push` — sync the branch's env vars with
+  a local `.env.local` (gitignored). `pull` writes decrypted values for local dev
+  (merging local-only keys); `push` uploads changed keys (new keys default to
+  SECRET and need `--secret`/`--plain` classification, existing secrets are left
+  untouched unless `--force-secrets`).
+- `tsconfig.json` needs `"experimentalDecorators": true` (the scaffold sets it).
+
+## Mental model
 
 Every handler type imports service singletons the same way:
 
@@ -27,7 +219,7 @@ The **only difference** is the trigger argument:
 
 | You are writing… | Handler signature | Trigger arg |
 |------------------|-------------------|-------------|
-| **Endpoints** (`controllers/` + `handlers/`) | `(req)` | `req` — [PBRequest](./endpoints.md) |
+| **Endpoints** (`controllers/` class controllers) | method `(…params)` | parameter decorators `@Body`/`@Query`/`@Param`/`@User`/… — [endpoints.md](./endpoints.md) |
 | **Workers** (`workers/**`) | `(payload, meta)` | typed payload + `WorkerMeta` |
 | **Jobs** (`jobs/**`) | `(meta)` | `JobMeta` |
 | **Hooks** (`hooks/**`) | `(event, meta)` | typed event + `HookMeta` |
@@ -43,13 +235,16 @@ the imported singletons — not from `ctx` or any argument.
 ```
 my-backend/
 ├── package.json            # depends on @palbase/backend
-├── controllers/            # route maps: method+path → handler (mounts the API)
-│   └── hello.controller.ts # defineController("/hello", { … })
-├── handlers/               # one endpoint unit each (schema + thin logic)
-│   └── hello.ts            # defineHandler({ auth, input, output, handler })
-├── services/               # plain classes/singletons your handlers call
+├── tsconfig.json           # experimentalDecorators: true (required for the decorators)
+├── controllers/            # @Controller classes: @Get/@Post methods (mount the API)
+│   └── hello.controller.ts # @Controller("/hello") + @Get example
+├── models/<ctrl>/<ep>.ts   # zod schemas, folder per controller, file per endpoint
+│   └── hello/greet.ts      # GreetQuery + HelloResponse (zod value + z.infer type)
+├── services/               # plain classes/singletons your controllers call
 ├── db/schema.ts            # table definitions (optional, enables typed DB)
 ├── db/migrations/          # explicit SQL migrations for type changes (optional)
+├── resources/              # external connections, set up once at boot (optional)
+├── seeds/                  # seed data (optional)
 ├── workers/                # background job handlers (optional)
 ├── jobs/                   # cron-scheduled jobs (optional)
 ├── hooks/                  # auth/storage/document event hooks (optional)
@@ -57,27 +252,30 @@ my-backend/
 └── middleware/             # cross-cutting request middleware (optional)
 ```
 
-HTTP endpoints are **not** file-path routed. You author a `handler` (one
-endpoint: `auth`/`input`/`output`/`errors` + logic, no route) and mount it in a
-`controller` (a route map). See [routing.md](./routing.md).
+HTTP endpoints are **not** file-path routed. You author a class controller
+(`@Controller("/base")` with `@Get`/`@Post`/… methods); putting it under
+`controllers/` mounts it. See [routing.md](./routing.md).
 
 ## Documentation
 
 | Topic | File |
 |-------|------|
 | Getting started | [getting-started.md](./getting-started.md) |
-| File-based routing | [routing.md](./routing.md) |
-| Endpoints & `req` | [endpoints.md](./endpoints.md) |
+| Routing (class controllers) | [routing.md](./routing.md) |
+| Endpoints (decorators) | [endpoints.md](./endpoints.md) |
 | Database & transactions | [database.md](./database.md) |
 | Schema & typed DB | [schema.md](./schema.md) |
 | Migrations (additive vs type-change + drift-gate) | [migrations.md](./migrations.md) |
 | Services (Cache, Queue, Storage, …) | [services.md](./services.md) |
+| Resources (external connections) | [resources.md](./resources.md) |
 | Errors | [errors.md](./errors.md) |
 | Workers & Jobs | [background.md](./background.md) |
 | Hooks & Webhooks | [events.md](./events.md) |
 
 For AI coding tools: a single concatenated corpus is generated at
 [`llms-full.txt`](./llms-full.txt) (and an index at [`llms.txt`](./llms.txt)).
+</content>
+</invoke>
 
 
 
@@ -88,7 +286,7 @@ For AI coding tools: a single concatenated corpus is generated at
 There is no CLI init command. A starter project is created for you when your
 Palbase project is provisioned. You then edit the files locally and deploy them.
 
-## package.json
+## package.json + tsconfig.json
 
 Your project depends on the SDK and uses the Palbase CLI for the dev loop:
 
@@ -105,121 +303,153 @@ Your project depends on the SDK and uses the Palbase CLI for the dev loop:
 }
 ```
 
+The controllers use **decorators**, so the `tsconfig.json` must set
+`experimentalDecorators: true` (the scaffold ships it):
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "experimentalDecorators": true,
+    "noEmit": true
+  },
+  "include": ["controllers/**/*.ts", "models/**/*.ts", "services/**/*.ts", "db/**/*.ts", "*.d.ts"]
+}
+```
+
 ## Local dev loop
 
 - `palbase serve` — run your backend locally with hot reload. It runs your
-  `controllers/` locally but proxies `Database`/`ctx.*` to the **deployed**
-  branch, so the branch must already be deployed (serve tells you to push first
-  if it isn't). See [migrations.md](./migrations.md) for the schema/migration
-  side of this.
+  `controllers/` locally but proxies `Database` and the service singletons to
+  the **deployed** branch, so the branch must already be deployed (serve tells
+  you to push first if it isn't). On startup it also runs `gen-types`. See
+  [migrations.md](./migrations.md) for the schema/migration side of this.
+- `palbase gen-types` — regenerate `palbase-env.d.ts` from `db/schema.ts` so
+  `Database.tables.*` is typed (no import, no generic). Run it standalone after
+  editing the schema, or rely on `palbase serve` running it for you.
 - **Deploy is GitHub-native** — there is no `palbase push`. Commit and
   `git push` to your project's repo; the push triggers a deploy of the backend
   runtime. Push a **branch** to deploy that branch instead of `main`.
 
 ## Your first endpoint
 
-A handler is one endpoint unit; a controller maps method+path to it. Create
-`handlers/hello.ts`:
+An endpoint is a method on a class controller. Declare the schemas in `models/`:
 
 ```ts
-import { defineHandler, z } from "@palbase/backend";
-
-export default defineHandler({
-  input: z.object({ name: z.string().optional() }),
-  output: z.object({ message: z.string(), user: z.string().nullable() }),
-  handler: async (req) => ({
-    message: `hello, ${req.input.name ?? "world"}!`,
-    user: req.user?.id ?? null,
-  }),
-});
+// models/hello/greet.ts
+import { z } from "@palbase/backend";
+
+export const GreetQuery = z.object({ name: z.string().optional() });
+export type GreetQuery = z.infer<typeof GreetQuery>;
+
+export const HelloResponse = z.object({ message: z.string(), user: z.string().nullable() });
+export type HelloResponse = z.infer<typeof HelloResponse>;
 ```
 
-Then mount it in `controllers/hello.controller.ts`:
+Then write the controller in `controllers/hello.controller.ts`:
 
 ```ts
-import { defineController, route } from "@palbase/backend";
-import hello from "../handlers/hello.js";
-
-export default defineController("/hello", {
-  hello: route.get("/", hello),
-});
+import { Controller, Get, Query, OptionalUser } from "@palbase/backend";
+import type { UserT } from "@palbase/backend";
+import { GreetQuery } from "../models/hello/greet.js";
+import type { HelloResponse } from "../models/hello/greet.js";  // the return TYPE names the 200 schema
+
+@Controller("/hello", { auth: false })
+export default class HelloController {
+  @Get("")
+  greet(@Query(GreetQuery) q: GreetQuery, @OptionalUser() user: UserT | null): HelloResponse {
+    return { message: `hello, ${q.name ?? "world"}!`, user: user?.id ?? null };
+  }
+}
 ```
 
-This is served at `GET /hello`. The Zod `input` schema validates the request and
-flows into `req.input`; the `output` schema validates your return value. See
-[routing.md](./routing.md) for the handler + controller model.
+This is served at `GET /hello`. The `@Query` schema validates the query string;
+the method's RETURN TYPE (`: HelloResponse`) names the response schema — codegen
++ the runtime read it to validate and describe the 200 response. There is no
+`@Returns` decorator; a body route with no named return type is a build error.
 
+Two things every controller file MUST have:
 
+- **A default export of the `@Controller` class.** Above it is `export default class
+  HelloController` (inline); the equivalent trailing form is `export class
+  HelloController {…}` then `export default HelloController;`. Without a default
+  export the deploy fails ("not a @Controller").
+- **`async` + `Promise<T>` once the method awaits a service.** `greet` above is
+  synchronous (pure), so it returns `HelloResponse` directly. The moment a method
+  calls a service that awaits `Database`, make it `async` and return
+  `Promise<HelloResponse>`.
 
-<!-- ===== routing.md ===== -->
+See [routing.md](./routing.md) and [endpoints.md](./endpoints.md) for the full
+class-controller model.
 
-# Routing
 
-Routes are declared in code. A **handler** is one endpoint unit (schema + thin
-logic) with NO route on it; a **controller** is a route map (method+path →
-handler). Putting a controller file under `controllers/` mounts it — there is no
-central router and no manual registration.
 
-```ts
-import { defineController, route } from "@palbase/backend";
-```
+<!-- ===== routing.md ===== -->
 
-## Handlers — one endpoint per file, no route
+# Routing
 
-A handler declares everything that types `req` (`auth`/`input`/`output`/
-`errors`) and the logic; it has no method or path.
+Routes are declared in code with **class controllers**. A controller is a class
+decorated with `@Controller(basePath)`; each route is a method decorated with
+`@Get`/`@Post`/`@Put`/`@Patch`/`@Delete`. Request input + context are injected
+into the method via **parameter decorators** (`@Body`/`@Query`/`@Param`/`@User`/
+…). Putting a controller file under `controllers/` mounts it — there is no
+central router and no manual registration.
 
 ```ts
-// handlers/places/import-nearby.ts
-import { defineHandler, z } from "@palbase/backend";
-import { placeService } from "../../services/place.service.js";
-
-export default defineHandler({
-  auth:   { required: true },
-  input:  z.object({ lat: z.number(), lng: z.number() }),
-  output: z.object({ imported: z.number() }),
-  errors: { quotaExceeded: { status: 429, code: "quota_exceeded" } },
-  handler: (req) => placeService.importNearby(req.input.lat, req.input.lng),
-});
+import { Controller, Get, Post, Body, Query, Param, User } from "@palbase/backend";
 ```
 
-## Controllers — the route map
+## Controllers — class + method decorators
 
-A controller maps method+path to handlers with `route.get|post|put|patch|delete`.
-The route-map KEY is authoring sugar only (it is NOT the operationId).
+`@Controller(basePath)` marks the class and sets the mount path. Each route
+method declares its verb + subpath; the real work lives in a `services/` class
+(the controller method is thin).
 
 ```ts
 // controllers/places.controller.ts
-import { defineController, route } from "@palbase/backend";
-import importNearby  from "../handlers/places/import-nearby.js";
-import addFavorite   from "../handlers/places/add-favorite.js";
-import listFavorites from "../handlers/places/list-favorites.js";
-
-export default defineController("/places", {
-  importNearby:  route.post("/import",    importNearby),
-  addFavorite:   route.post("/favorites", addFavorite),
-  listFavorites: route.get ("/favorites", listFavorites),
-});
+import { Controller, Get, Post, Body, User } from "@palbase/backend";
+import type { UserT } from "@palbase/backend";
+import { placeService } from "../services/place.service.js";
+import { ImportNearbyBody } from "../models/places/import.js";
+import type { PlaceSchema } from "../models/places/shared.js";  // the return TYPE names the 200 schema
+
+@Controller("/places")
+export default class PlacesController {
+  @Post("/import")
+  importNearby(@Body(ImportNearbyBody) body: ImportNearbyBody, @User() user: UserT): PlaceSchema {
+    return placeService.importNearby(body.lat, body.lng, user.id);
+  }
+
+  @Get("/favorites", { auth: false })
+  listFavorites(): PlaceSchema[] {
+    return placeService.listFavorites();
+  }
+}
 ```
 
-| Map key (sugar) | Method | Full path | operationId (flat) |
+| Method name (sugar) | Verb | Full path | operationId (flat) |
 |---|---|---|---|
 | `importNearby`  | POST | `/places/import`    | `postPlacesImport` |
-| `addFavorite`   | POST | `/places/favorites` | `postPlacesFavorites` |
 | `listFavorites` | GET  | `/places/favorites` | `getPlacesFavorites` |
 
 Rules:
 
 - The full path of a route is `basePath + subpath` (`"/places" + "/import"`).
-- A `{segment}` in a path becomes a route param, read via `req.params.segment`.
-- Each route value MUST be a `route.*(...)` result — a bare handler is a
-  compile error, which keeps logic out of controllers.
+- A `{segment}` in a path becomes a path param, injected via `@Param("segment")`.
+- Input is declared with the parameter decorators — `@Body(schema)`,
+  `@Query(schema)`, `@Param("id")`, `@Headers(schema?)`. The success response is
+  the method's RETURN TYPE (`: PlaceSchema` or `: z.infer<typeof PlaceSchema>`):
+  codegen + the runtime read that named type to drive the OpenAPI 200 response.
+  A body route with no named return type is a build error — annotate `: void`
+  (or `: Promise<void>`) for no body.
 - The operationId is derived FLAT from method + full path (`postPlacesImport`),
-  not from the map key. Change a verb with `route.post` → `route.put` — no file
-  rename.
+  not from the method name. Change `@Post` → `@Put` — no file rename.
 
-See [endpoints.md](./endpoints.md) for the full `defineHandler` config (`req`,
-auth, input/output, errors, middleware) reference.
+See [endpoints.md](./endpoints.md) for the full decorator reference (`@Controller`
+options, the parameter decorators, auth cascade, and error classes).
 
 
 
@@ -227,106 +457,139 @@ auth, input/output, errors, middleware) reference.
 
 # Endpoints
 
-An endpoint is a **handler** — `export default defineHandler({...})` in a file
-under `handlers/`. A handler has NO method or path; a **controller** maps
-method+path to it (see [routing.md](./routing.md)). The handler receives **one
-argument**, `req` (a `PBRequest`). Services are NOT on `req` — import them as
-singletons (see [services.md](./services.md)).
+An endpoint is a **method on a class controller** — a class decorated with
+`@Controller(basePath)` whose methods are decorated with `@Get`/`@Post`/`@Put`/
+`@Patch`/`@Delete`. Controller files live under `controllers/` and are mounted
+automatically (see [routing.md](./routing.md)). Request input + context are
+injected into the method via **parameter decorators** (`@Body`/`@Query`/`@Param`/
+`@User`/…), each piece direct — no `req` god-object. Services are reached via the
+imported singletons (see [services.md](./services.md)).
 
-## `defineHandler` config
+## A controller
 
 ```ts
-defineHandler({
-  auth: { required: true },          // see Auth below. Omitted → AUTH REQUIRED (secure-by-default).
-  rateLimit: { max: 100, window: 60 }, // optional: max requests per window seconds
-  input: z.object({ ... }),          // optional Zod schema → validates & types req.input
-  output: z.object({ ... }),         // optional Zod schema → validates the return value
-  errors: { ... },                   // optional declared errors (see errors.md)
-  middleware: [ ... ],               // optional Middleware[] (see below)
-  handler: async (req) => { ... },   // required
-});
-```
-
-There is no `method` field — the HTTP verb (and path) live in the controller
-that mounts the handler via `route.get|post|put|patch|delete`.
+// controllers/rooms.controller.ts
+import { Controller, Get, Post, Body, Param, User, NotFound, Database } from "@palbase/backend";
+import type { UserT } from "@palbase/backend";
+import { CreateRoomBody } from "../models/rooms/create.js";
+import type { RoomSchema } from "../models/rooms/shared.js";  // the return TYPE names the 200 schema
+
+@Controller("/rooms")
+export default class RoomsController {
+  @Post("")
+  async create(@Body(CreateRoomBody) body: CreateRoomBody, @User() user: UserT): Promise<RoomSchema> {
+    const room = await Database.insert("rooms", { name: body.name, capacity: body.capacity ?? null });
+    return { id: room.id as string, name: room.name as string, capacity: (room.capacity as number) ?? null };
+  }
 
-## `req` (PBRequest)
+  @Get("/{id}")
+  async getOne(@Param("id") id: string): Promise<RoomSchema> {
+    const room = await Database.findById("rooms", id);
+    if (!room) throw new NotFound("Room does not exist", "room_not_found");
+    return { id: room.id as string, name: room.name as string, capacity: (room.capacity as number) ?? null };
+  }
+}
+```
 
-| Field | Type | Notes |
-|-------|------|-------|
-| `req.input` | inferred from `input` schema | request body for POST/PUT/PATCH; `{}` otherwise |
-| `req.params` | `Record<string,string>` | route params, e.g. `req.params.id` |
-| `req.query` | `Record<string,string>` | parsed query string |
-| `req.headers` | `Record<string,string>` | lowercase keys |
-| `req.user` | `User` when authenticated; `User \| null` when `auth` is omitted or `required: false` | see Auth below |
-| `req.client` | `ClientInfo` | calling SDK/app/platform/os version (all nullable) |
-| `req.file` | `FileContext \| null` | uploaded file, if any |
-| `req.method` | `string` | the HTTP method |
-| `req.requestId` / `req.traceId` / `req.spanId` | `string` | correlation ids |
-| `req.errors` | typed throwers | present when `errors` is declared (see errors.md) |
+**Two non-negotiables** (the most common codegen mistakes):
 
-`User` is `{ id: string; email?: string; role: string; metadata: Record<string, unknown> }`.
+1. **`export default <Controller>` is REQUIRED.** Above it is
+   `export default class RoomsController`; the trailing form `export class
+   RoomsController {…}` + `export default RoomsController;` is equivalent. Without
+   a default export the deploy aborts with a "not a @Controller / non-controller
+   export" error — the runtime loads the file's default export.
+2. **A method that awaits a service is `async` + `Promise<T>`.** `Database`
+   returns promises, so a body that `await`s it cannot have a sync return type
+   (`: RoomSchema` on an `async` body is a `tsc` error). Both methods above are
+   `async` and return `Promise<RoomSchema>`. (A pure method that returns a literal
+   with no `await` may stay synchronous.)
 
-## Auth
+## Method decorators
 
-**Secure by default:** a handler requires authentication UNLESS it explicitly
-opts out. Omitting `auth` means AUTH REQUIRED — a forgotten `auth` fails safe
-(401), never silently public. Mark a route PUBLIC with `auth: { required: false }`.
+`@Get`/`@Post`/`@Put`/`@Patch`/`@Delete` take `(subpath, options?)`:
 
 ```ts
-// auth omitted entirely                 // AUTH REQUIRED → req.user is non-null User
-auth: { required: true }                // same: require any authenticated user
-auth: { required: true, role: "admin" } // require a specific role
-auth: { required: false }               // PUBLIC → req.user may be null (anon key only)
+interface RouteOptions {
+  auth?: boolean | { required?: boolean; role?: string };  // overrides controller default
+  rateLimit?: { max: number; window: number };             // optional, per route
+}
 ```
 
-Whether `req.user` is non-null is computed from the `auth` config at the type
-level (and matches the runtime exactly):
-
-| `auth` value | `req.user` type |
-|--------------|-----------------|
-| omitted | `User` (secure-by-default) |
-| `true` | `User` |
-| `false` | `User \| null` (public) |
-| `{ required: true }` | `User` |
-| `{ required: false }` | `User \| null` (public) |
-| `{ role: "admin" }` (object, no `required`) | `User` |
+Input and output are NOT method-decorator options: input comes from the
+parameter decorators, output from the method's return type. The method decorator
+only carries route concerns (path, auth, rateLimit).
 
-To make a route PUBLIC, set `auth: { required: false }` (or `auth: false`). An
-object with a `role` but no `required` key is treated as authenticated. When
-`auth` is omitted, the endpoint is public and `req.user` may be null.
+## Parameter decorators
 
-## Typed input/output
+| Decorator | Injects | Typed by | OpenAPI |
+|---|---|---|---|
+| `@Body(schema)` | request body | `: T` (`z.infer<schema>`, same name) | requestBody |
+| `@Query(schema)` | query params | `: T` | query parameters |
+| `@Param("id")` | one path param | `: string` | path parameter |
+| `@Headers(schema?)` | request headers | `Record<string,string>` (+ typed with schema) | header parameters |
+| `@User()` | authenticated user | `: UserT` | — (from token) |
+| `@OptionalUser()` | user, possibly anon | `: UserT \| null` | — |
+| `@Client()` | parsed client info | `: ClientInfo` | — |
+| `@RequestId()` / `@TraceId()` | correlation ids | `: string` | — |
+| `@Req()` | raw request (escape hatch) | `: PBRequest` | — |
+
+`@Body`/`@Query`/`@Headers` take a zod schema (validation + codegen source); the
+developer writes the matching type annotation (same name). `UserT` is the
+authenticated-user type (`{ id: string; email?: string; role: string; metadata:
+Record<string, unknown> }`) — exported under the alias `UserT` because the value
+name `User` is the `@User()` decorator.
+
+## Output = return type
+
+The success response is the method's RETURN TYPE — there is no `@Returns`
+decorator. Annotate `: Promise<RoomSchema>` (or `: Promise<z.infer<typeof
+RoomSchema>>`); codegen + the runtime read that named type to bind the OpenAPI
+200 response zod schema. A body route with no named return type is a build
+error. A method that returns nothing annotates `: void` (or `: Promise<void>`).
+
+## Auth — controller default + route override cascade
+
+**Secure by default:** a route requires authentication UNLESS it explicitly opts
+out. Resolution order (most specific wins):
+
+1. Route-level `@Post("", { auth })` — wins if present.
+2. Controller-level `@Controller("/x", { auth })` — applies to routes without
+   their own `auth`.
+3. Default `true` (secure-by-default).
 
 ```ts
-import { defineHandler, z, Database } from "@palbase/backend";
-
-export default defineHandler({
-  auth: { required: true },
-  input: z.object({ name: z.string().min(1).max(100), capacity: z.number().int().positive().optional() }),
-  output: z.object({ id: z.string(), name: z.string(), capacity: z.number().nullable() }),
-  handler: async (req) => {
-    const room = await Database.insert("rooms", {
-      name: req.input.name,
-      capacity: req.input.capacity ?? null,
-    });
-    return { id: room.id as string, name: room.name as string, capacity: (room.capacity as number) ?? null };
-  },
-});
+@Controller("/public", { auth: false })          // all routes default public
+export default class PublicController {
+  @Get("/open") open(): Info { ... }              // inherits → public
+  @Get("/secret", { auth: true })                 // OVERRIDES → authed
+  secret(@User() u: UserT): Secret { ... }
+}
 ```
 
-A controller then mounts it with a method + path:
+| effective `auth` | `@User()` type to annotate |
+|------------------|----------------------------|
+| required (omitted / `true` / `{ required: true }` / role-only) | `@User() u: UserT` |
+| public (`false` / `{ required: false }`) | `@OptionalUser() u: UserT \| null` |
+
+The runtime always applies the resolved effective auth; the static type you
+annotate is best-effort (a parameter decorator cannot see the controller default
+at the type level).
+
+## Errors — global throw classes
+
+Throw an error class anywhere (controller OR service) — no `req`, no per-route
+map. The runtime catches it and emits the standard envelope:
 
 ```ts
-// controllers/rooms.controller.ts
-import { defineController, route } from "@palbase/backend";
-import create from "../handlers/rooms/create.js";
+import { Conflict, NotFound, BadRequest, Unauthorized, Forbidden, TooManyRequests, PalError } from "@palbase/backend";
 
-export default defineController("/rooms", {
-  create: route.post("/", create),
-});
+throw new Conflict("title taken");            // → 409
+throw new NotFound();                         // → 404 ("Not found")
+throw new PalError(418, "teapot", "custom");  // → custom status/code
 ```
 
+See [errors.md](./errors.md) for the full set + the wire envelope shape.
+
 ## Middleware
 
 A middleware wraps a request. Define one in `middleware/<name>.ts`:
@@ -343,22 +606,7 @@ export default defineMiddleware(async (ctx, next) => {
 ```
 
 The middleware handler receives `(ctx, next)` — call `await next()` to run the
-rest of the chain (other middleware, then the endpoint handler). Note this uses
-the `ctx` model, not `req`.
-
-To attach middleware to a specific handler, import it and list it in the
-handler's `middleware` array:
-
-```ts
-import { defineHandler, z } from "@palbase/backend";
-import logger from "../../middleware/logger.js";
-
-export default defineHandler({
-  middleware: [logger],
-  output: z.object({ ok: z.boolean() }),
-  handler: async (req) => ({ ok: true }),
-});
-```
+rest of the chain (other middleware, then the endpoint method).
 
 
 
@@ -438,6 +686,46 @@ await Database.transaction(async (tx) => {
 The `tx` carries the same typed `tx.tables.<name>` API as `Database.tables`
 (no nested transaction). See [schema.md](./schema.md) for the full surface.
 
+## Bypassing RLS — `Database.asService()`
+
+When a table has [Row-Level Security](./schema.md#row-level-security-rls)
+policies, every `Database.*` call runs as the request's verified user
+(`authenticated`), so the database filters out rows the user's policies don't
+allow. That is the secure default.
+
+Sometimes you need to read or write **across all users** — an admin endpoint, a
+background job that fans out notifications, a cleanup task. For that, call
+`Database.asService()`. It returns a sibling client that runs as the
+`service_role` (which has `BYPASSRLS`), exposing the exact same surface —
+`tables`, the raw string ops, and `transaction`:
+
+```ts
+import { Database } from "@palbase/backend";
+
+// RLS-enforced (default): only the caller's own rows.
+const mine = await Database.tables.todos.findMany({});
+
+// Service-role bypass: every user's rows. Explicit and greppable.
+const all  = await Database.asService().tables.todos.findMany({});
+const rows = await Database.asService().query("SELECT count(*) FROM todos");
+
+// A service-role transaction (the role is fixed for the whole tx):
+await Database.asService().transaction(async (tx) => {
+  await tx.tables.todos.update(id, { done: true });
+});
+```
+
+Guidelines:
+
+- **Be explicit.** Prefer the default `Database.*` and reach for `asService()`
+  only where you genuinely need cross-user access. It is intentionally easy to
+  grep for in review.
+- **No double-bypass / no nesting.** The sibling does not re-expose
+  `asService()`, and `tx` never exposes it — a transaction's role is fixed when
+  it begins. Use `Database.transaction(...)` for an authenticated tx and
+  `Database.asService().transaction(...)` for a service-role tx; you cannot mix
+  enforced and bypassed ops inside one interactive transaction.
+
 
 
 <!-- ===== schema.md ===== -->
@@ -451,8 +739,9 @@ everywhere — by default, with no import and no generic.
 
 ## Defining a schema
 
-The table NAME comes from the object key under `tables` — there is one
-canonical form.
+The table NAME comes from the object key under `tables`. Each table value is an
+object `{ columns, rls?, policies? }` — `columns` is required; `rls` and
+`policies` enable [Row-Level Security](#row-level-security-rls).
 
 ```ts
 import {
@@ -463,23 +752,29 @@ import {
 export default defineSchema({
   tables: {
     rooms: {
-      id: uuid().primaryKey().defaultRandom(),
-      name: text().notNull(),
-      capacity: integer().nullable(),
-      is_active: boolean().default(true),
-      created_at: timestamp().defaultNow(),
+      columns: {
+        id: uuid().primaryKey().defaultRandom(),
+        name: text().notNull(),
+        capacity: integer().nullable(),
+        is_active: boolean().default(true),
+        created_at: timestamp().defaultNow(),
+      },
     },
     sessions: {
-      id: uuid().primaryKey().defaultRandom(),
-      room_id: uuid().notNull().references("rooms", "id").onDelete("cascade"),
-      user_id: uuid().notNull(),
-      data: jsonb().nullable(),
-      started_at: timestamp().defaultNow(),
+      columns: {
+        id: uuid().primaryKey().defaultRandom(),
+        room_id: uuid().notNull().references("rooms", "id").onDelete("cascade"),
+        user_id: uuid().notNull(),
+        data: jsonb().nullable(),
+        started_at: timestamp().defaultNow(),
+      },
     },
     orders: {
-      id: uuid().primaryKey().defaultRandom(),
-      status: enumType("order_status", ["pending", "paid", "shipped", "cancelled"]),
-      amount: integer().notNull(),
+      columns: {
+        id: uuid().primaryKey().defaultRandom(),
+        status: enumType("order_status", ["pending", "paid", "shipped", "cancelled"]),
+        amount: integer().notNull(),
+      },
     },
   },
 });
@@ -509,17 +804,22 @@ You do **not** wire anything per endpoint. Saving `db/schema.ts` regenerates
 of the schema, no generic, no cast:
 
 ```ts
-import { defineHandler, z, Database } from "@palbase/backend";
-
-export default defineHandler({
-  input: z.object({ name: z.string() }),
-  output: z.object({ id: z.string(), name: z.string() }),
-  handler: async (req) => {
-    const room = await Database.tables.rooms.insert({ name: req.input.name });
+import { Controller, Post, Body, Database, z } from "@palbase/backend";
+
+const CreateRoomBody = z.object({ name: z.string() });
+const RoomOut = z.object({ id: z.string(), name: z.string() });
+
+@Controller("/rooms")
+export default class RoomsController {
+  @Post("")
+  // The return type names the 200 schema — `z.infer<typeof RoomOut>` works
+  // inline, no separate `export type` needed.
+  async create(@Body(CreateRoomBody) body: z.infer<typeof CreateRoomBody>): Promise<z.infer<typeof RoomOut>> {
+    const room = await Database.tables.rooms.insert({ name: body.name });
     return { id: room.id, name: room.name }; // room.id: string ✓
     // room.nope ← compile error
-  },
-});
+  }
+}
 ```
 
 `Database.tables.<name>` exposes `insert`, `update(id, data)`, `delete(id)`,
@@ -535,107 +835,209 @@ import type { Tables } from "@palbase/backend/env";
 type Room = Tables["rooms"]["row"];
 ```
 
+## Row-Level Security (RLS)
 
+RLS pushes per-user access control **into Postgres**: every `Database.*` query
+runs as the request's verified user (the `authenticated` role with that user's
+claims), and the database itself filters rows your policies don't allow. A
+missing `WHERE user_id = …` in your handler can no longer leak another user's
+rows — the policy enforces it. This is the recommended way to scope data per
+user.
 
-<!-- ===== migrations.md ===== -->
+Add `policies` (and optionally `rls`) to a table. `policies` being non-empty
+implies `rls: true` automatically (a table with policies must have RLS enabled
+or the policies are inert). Set `rls: true` with no policies only as a
+deliberate deny-all intermediate step.
 
-# Migrations
+### The `policy()` builder
+
+`policy(name)` is a fluent builder, just like the column builders:
+
+```ts
+import { policy } from "@palbase/backend";
+
+policy("pb_owner_all")
+  .for("all")                              // "all" | "select" | "insert" | "update" | "delete"
+  .to("authenticated")                     // one or more DB roles; .to() with no args = PUBLIC
+  .using("owner = (select auth.uid())")    // row-visibility filter (SELECT/UPDATE/DELETE)
+  .withCheck("owner = (select auth.uid())"); // write-validation (INSERT/UPDATE)
+```
 
-`db/schema.ts` is the single source of truth for your Postgres schema. On every
-deploy, Palbase diffs your declared schema against the live branch database and
-reconciles it — but *how* it reconciles depends on whether the change is safe to
-apply automatically.
+| Method | Default | Meaning |
+|--------|---------|---------|
+| `.for(cmd)` | `"all"` | The SQL command the policy governs. |
+| `.to(...roles)` | `["authenticated"]` | DB roles the policy applies to. `.to()` with no args targets PUBLIC. |
+| `.using(sql)` | none | `USING (...)` — which existing rows are visible (SELECT/UPDATE/DELETE). |
+| `.withCheck(sql)` | none | `WITH CHECK (...)` — which rows may be written (INSERT/UPDATE). |
+| `.as(mode)` | `"permissive"` | `"permissive"` (policies OR together) or `"restrictive"` (AND together). |
 
-## Two kinds of change
+**`auth.uid()`** returns the verified user's id (palauth user id, TEXT) from the
+request's JWT claims. Wrap it as `(select auth.uid())` — Postgres evaluates that
+once per statement (an initPlan) instead of once per row. `auth.role()` and
+`auth.jwt()` are also available. With no user on the request (anon/public),
+`auth.uid()` is `NULL`, so an `owner = (select auth.uid())` policy matches no
+rows.
 
-### 1. Additive — auto-applied, no migration file
+> Name policies with a `pb_` prefix. Palbase reconciliation only manages
+> policies it authored (`pb_`-prefixed) and never touches policies created by
+> other modules (storage, cron, …).
 
-A new table, or a new **nullable** or **defaulted** column, is additive: the
-deploy applies it automatically (`CREATE TABLE` / `ADD COLUMN`) with no manual
-step and no backfill risk. Just edit `db/schema.ts` and deploy.
+### Owner-scoped `todos` example
 
 ```ts
-// before
-todos: {
-  id: uuid().primaryKey().defaultRandom(),
-  title: text().notNull(),
-}
+import { defineSchema, policy, uuid, text, boolean, timestamp } from "@palbase/backend";
 
-// after — additive: `notes` (nullable) + `priority` (defaulted) auto-apply on deploy
-todos: {
-  id: uuid().primaryKey().defaultRandom(),
-  title: text().notNull(),
-  notes: text().nullable(),
-  priority: text().nullable().default("normal"),
-}
+export default defineSchema({
+  tables: {
+    todos: {
+      columns: {
+        id:         uuid().primaryKey().defaultRandom(),
+        owner:      text().notNull(),        // palauth user id (TEXT)
+        title:      text().notNull(),
+        done:       boolean().default(false),
+        created_at: timestamp().defaultNow(),
+      },
+      // `policies` non-empty ⇒ RLS is enabled + FORCEd automatically.
+      policies: [
+        // Read: a user sees only their own todos.
+        policy("pb_todos_owner_select")
+          .for("select")
+          .to("authenticated")
+          .using("owner = (select auth.uid())"),
+
+        // Write: a user can insert/update/delete only rows they own.
+        policy("pb_todos_owner_write")
+          .for("all")
+          .to("authenticated")
+          .using("owner = (select auth.uid())")
+          .withCheck("owner = (select auth.uid())"),
+      ],
+    },
+  },
+});
 ```
 
-> A new **NOT NULL column without a default** is NOT additive-safe on a table
-> that already has rows (there is nothing to put in the existing rows). Make it
-> `.nullable()`, give it a `.default(...)`, or apply it as an explicit migration
-> (add nullable → backfill → set NOT NULL).
+With this in place, `await Database.tables.todos.findMany({})` returns only the
+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)).
+
+### How policies are applied
 
-### 2. Destructive / type-changing — needs an explicit migration
+On deploy, Palbase diffs your declared schema against the live database and
+applies RLS **additively**: it emits `ENABLE`/`FORCE ROW LEVEL SECURITY` only
+when the table doesn't already have it, and `CREATE POLICY` only for policies
+that don't already exist (keyed by `(table, name)`). These are non-destructive,
+so they apply without the `acceptDataLoss` confirmation that column drops need.
 
-Renaming or dropping a column, changing a column's type, or adding a NOT NULL
-constraint can lose or corrupt existing data — so the deploy's **drift-gate
-blocks them** and the deploy fails until you provide an explicit migration.
-Write the SQL yourself in `db/migrations/`:
+> Changing a policy's body (its `USING`/`WITH CHECK` SQL) in place is not yet
+> auto-applied — rename the policy (new `(table, name)`) or drop the old one in
+> a hand-written migration. Policy DROP/rewrite churn is a documented TODO.
+
+
+
+
+<!-- ===== migrations.md ===== -->
 
+# Migrations
+
+`db/schema.ts` is the single source of truth for your Postgres schema. You change
+the schema by editing that file, then generating a **migration** from the diff
+with `palbase db diff`. Every schema change — additive or destructive — flows
+through a reviewable migration file committed to git. The deploy applies the
+migrations in `db/migrations/`; nothing is auto-applied behind your back.
+
+## The workflow
+
+```bash
+# 1. Edit db/schema.ts (add a column, a table, a policy, …)
+
+# 2. Generate the migration from the diff (declared schema vs the live branch)
+palbase db diff -f add_priority
+#   → writes db/migrations/<timestamp>_add_priority.sql
+
+# 3. Review the generated SQL (especially destructive changes — see below),
+#    then commit + push. git push deploys; the migration runs on deploy.
+git add db/migrations && git commit -m "add priority column" && git push
 ```
-db/migrations/
-  001_user_id_to_text.up.sql
-  001_user_id_to_text.down.sql
+
+`palbase db diff` introspects your **live branch database** (there is no local
+database — every branch runs on the server), diffs it against `db/schema.ts`, and
+writes one migration SQL file. If the schema is already in sync it writes nothing
+and tells you so.
+
+## Additive vs destructive
+
+The generated SQL labels what it does. An additive change (new table, new column)
+is plain DDL:
+
+```sql
+-- palbase db diff: add_priority
+-- generated 20260605T142233
+
+ALTER TABLE todos ADD COLUMN IF NOT EXISTS priority text;
 ```
 
+A **destructive** change (dropping a column or table — losing data) is generated
+with a clear warning comment, and `palbase db diff` prints a warning. Review it
+before committing:
+
 ```sql
--- 001_user_id_to_text.up.sql
-ALTER TABLE todos ALTER COLUMN user_id TYPE text USING user_id::text;
+-- DESTRUCTIVE: dropping todos.notes loses its data
+ALTER TABLE todos DROP COLUMN notes;
 ```
 
+A **column type change** is emitted as a commented stub — auto-migration never
+alters types, so you write the real `ALTER ... TYPE` with whatever `USING` cast
+and backfill your data needs:
+
 ```sql
--- 001_user_id_to_text.down.sql
-ALTER TABLE todos ALTER COLUMN user_id TYPE uuid USING user_id::uuid;
+-- TYPE CHANGE: todos.priority text -> integer (review; auto-migrate does not ALTER types)
+-- ALTER TABLE todos ALTER COLUMN priority TYPE integer;
 ```
 
-Migrations are golang-migrate style: numbered `NNN_name.up.sql` / `.down.sql`
-pairs, applied in order and tracked so each runs exactly once (idempotent).
-`db/schema.ts` always describes the **end state**; the migration describes **how
-existing data gets there**. Keep the two in sync — after the migration lands,
-`schema.ts` should already reflect the new column type.
+## The drift gate
+
+You can't push a schema change without its migration:
 
-## The drift-gate
+- **`palbase db check`** exits non-zero when `db/schema.ts` declares something the
+  database lacks (i.e. you edited the schema but didn't run `palbase db diff`).
+- The scaffold installs a **git pre-push hook** that runs `palbase db check`, so a
+  plain `git push` is **blocked** until you generate + commit the migration.
+  (Bypass with `git push --no-verify` — but the deploy-time gate still rejects it.)
+- On deploy, after migrations run, Palbase asserts `db/schema.ts` matches the live
+  database. Any unresolved drift **fails the deploy** and keeps the previous
+  version live — a broken schema never goes out silently.
 
-On deploy, Palbase compares `db/schema.ts` to the live database:
+## `palbase serve` uses the deployed database
 
-- **Additive** diffs → auto-applied.
-- **Type-changing / destructive** diffs **with** a matching migration → the
-  migration runs.
-- **Type-changing / destructive** diffs **without** a migration → the deploy
-  **aborts** and your currently-running version keeps serving.
+`palbase serve` runs your controllers locally but proxies `Database` and `ctx.*`
+to the **deployed** branch — it does not spin up a local Postgres. So a schema
+change in `db/schema.ts` doesn't exist in the database until you generate the
+migration and push. Run `palbase gen-types` (or just `palbase serve`, which
+regenerates on change) after editing the schema to refresh `palbase-env.d.ts` so
+`Database.tables.<name>` is fully typed in your services.
 
-This is deliberate: it stops an accidental column-type change from silently
-dropping production data. A blocked deploy is a prompt to write the migration,
-not a failure to work around.
+## Hand-written migrations
 
-## Local dev: `palbase serve` uses the deployed database
+`db/migrations/*.sql` is plain SQL applied in filename order and tracked in
+`schema_migrations` (idempotent — a migration runs once). `palbase db diff`
+generates them for you, but you can also hand-write one for anything the diff
+can't express (a data backfill, a complex type change with a `USING` cast, a
+trigger). Keep `db/schema.ts` as the declared end-state so the drift gate passes.
 
-`palbase serve` runs your controllers locally but proxies `Database` and
-`ctx.*` to the **deployed** branch — it does **not** spin up a local Postgres or
-apply migrations locally. So when your local `db/schema.ts` or `db/migrations/`
-is ahead of what's deployed, serve prints a note: new tables/columns won't exist
-until you push. Deploy to apply them.
+## Adding a NOT NULL column to a table with rows
 
-## Workflow
+There's nothing to put in existing rows, so do it in two migrations: first add it
+nullable (or with a default) and backfill, then a follow-up `ALTER ... SET NOT
+NULL`. `db/schema.ts` describes the end state; the migrations describe how
+existing data gets there.
 
-1. Edit `db/schema.ts`.
-2. **Additive** change? → `git push`. It auto-migrates on deploy.
-3. **Type change / rename / drop?** → add `db/migrations/NNN_*.up.sql` (+
-   `.down.sql`), then `git push`. The runner applies it; without it the
-   drift-gate blocks the deploy.
-4. `palbase serve` warns locally until the change is deployed.
+## Row-Level Security
 
-See [schema.md](./schema.md) for the column builders and typed
+Add `rls: true` + `policies: [policy(...)]` to a table in `db/schema.ts`; the
+generated migration emits the `ENABLE ROW LEVEL SECURITY` + `CREATE POLICY` DDL.
+See [schema.md](./schema.md) for the column builders, the policy DSL, and typed
 `Database.tables.*` access.
 
 
@@ -734,17 +1136,20 @@ await Notifications.sms.send({ /* PalbaseSmsSendParams */ });
 ## Flags
 
 ```ts
-import { defineHandler, z, Flags } from "@palbase/backend";
-
-export default defineHandler({
-  auth: { required: true },           // req.user is non-null here
-  output: z.object({ enabled: z.boolean() }),
-  handler: async (req) => {
-    const { data: enabled } = await Flags.isEnabled("new-checkout", { userId: req.user.id });
-    const { data: variant } = await Flags.getVariant("button-color", { userId: req.user.id });
+import { Controller, Get, User, Flags, z } from "@palbase/backend";
+import type { UserT } from "@palbase/backend";
+
+const FlagsOut = z.object({ enabled: z.boolean() });
+
+@Controller("/checkout")
+export default class CheckoutController {
+  @Get("/flags")                       // auth omitted → required → user is non-null
+  async flags(@User() user: UserT): Promise<z.infer<typeof FlagsOut>> {  // return type names the 200 schema
+    const { data: enabled } = await Flags.isEnabled("new-checkout", { userId: user.id });
+    const { data: variant } = await Flags.getVariant("button-color", { userId: user.id });
     return { enabled: enabled ?? false };
-  },
-});
+  }
+}
 ```
 
 
@@ -852,51 +1257,58 @@ const results = (await google.nearby(41.0, 29.0)).data.results;
 
 # Errors
 
-Two ways to fail a request. Both serialize to the standard Palbase error
-envelope:
+Throw an error class to fail a request. Every one serializes to the standard
+Palbase error envelope:
 
 ```json
 { "error": "todo_not_found", "error_description": "No such todo", "status": 404, "request_id": "req_…" }
 ```
 
-## 1. `HttpError` (ad-hoc)
+Throw anywhere — in a controller method OR in a `services/` class. No `req`, no
+per-route error map: the runtime catches any thrown error class and emits the
+envelope.
+
+## Named status classes
 
 ```ts
-import { HttpError } from "@palbase/backend";
-throw new HttpError(404, "todo_not_found", "No such todo");
-// optional structured payload (4th arg) rides along under `data`:
-throw new HttpError(423, "todo_locked", "Locked", { retryAfter: 30 });
+import { BadRequest, Unauthorized, Forbidden, NotFound, Conflict, TooManyRequests } from "@palbase/backend";
+
+throw new Conflict("title taken");      // → 409  ("conflict" code by default)
+throw new NotFound();                   // → 404  ("not_found", "Not found")
+throw new BadRequest("missing field");  // → 400
+throw new Unauthorized();               // → 401
+throw new Forbidden();                  // → 403
+throw new TooManyRequests();            // → 429
 ```
 
-`new HttpError(status, code, description, data?)`.
+Each class fixes its HTTP status. The constructor is
+`new <Class>(message?, code?, data?)`:
+
+- `message` overrides the human-readable `error_description` (defaults to a label
+  derived from the class name).
+- `code` overrides the wire `error` code (defaults to the class's snake_case
+  code, e.g. `not_found`).
+- `data` rides along under the envelope's `data` field for structured context.
+
+```ts
+throw new NotFound("Room does not exist", "room_not_found");
+throw new Conflict("locked", "title_locked", { retryAfter: 30 });
+```
 
-## 2. Declared errors (typed)
+## `PalError` / `HttpError` (custom status)
 
-Declare them on the handler; throw via `req.errors.<name>(...)`. Declared
-errors are described in the endpoint's OpenAPI and codegen'd into a typed enum
-for iOS callers.
+For a status/code not covered by a named class:
 
 ```ts
-import { defineHandler, z, Database } from "@palbase/backend";
-
-export default defineHandler({
-  input: z.object({ id: z.string() }),
-  output: z.object({ ok: z.boolean() }),
-  errors: {
-    notFound: { status: 404, code: "todo_not_found", description: "No such todo" },
-    locked: { status: 423, code: "todo_locked", data: z.object({ retryAfter: z.number() }) },
-  },
-  handler: async (req) => {
-    const todo = await Database.findById("todos", req.input.id);
-    if (!todo) throw req.errors.notFound();              // no data → no args
-    if (todo.locked) throw req.errors.locked({ retryAfter: 30 }); // data schema → required arg
-    return { ok: true };
-  },
-});
+import { PalError } from "@palbase/backend";
+throw new PalError(418, "teapot", "I'm a teapot");
+// optional structured payload (4th arg) rides along under `data`:
+throw new PalError(423, "todo_locked", "Locked", { retryAfter: 30 });
 ```
 
-A declared error with a `data` Zod schema requires that payload as an argument;
-one without `data` takes no arguments. This is enforced by the types.
+`PalError` (and its base `HttpError`) take `(status, code, description, data?)`.
+The named classes all extend `HttpError`, so `catch (e) { if (e instanceof
+HttpError) … }` matches any of them.