@palbase/backend 2.0.2 → 4.0.0

package/docs/llms-full.txt

@@ -1,6 +1,6 @@
 # Palbase Backend SDK (`@palbase/backend`)
 
-> File-based TypeScript backend SDK. Endpoints use `req` (PBRequest) + imported service singletons (`Database`, `Cache`, …). Workers/jobs/hooks/webhooks use a `ctx` object. Not Express, not Supabase Edge Functions.
+> 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.
 
 
 
@@ -15,25 +15,41 @@ 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.
 
-## The two mental models (important)
+## Mental model (important)
 
-| You are writing… | Handler receives | Services come from |
-|------------------|------------------|--------------------|
-| **Endpoints** (`endpoints/**`) | a single `req` ([PBRequest](./endpoints.md)) | imported singletons: `import { Database } from "@palbase/backend"` |
-| **Workers, Jobs, Hooks, Webhooks** | a `ctx` object | `ctx.db`, `ctx.log`, `ctx.cache`, `ctx.queue` |
+Every handler type imports service singletons the same way:
 
-Endpoints use `req` + imported singletons. Everything else uses `ctx`. Do not
-mix them: there is no `ctx` inside an endpoint handler, and no imported
-`Database` singleton call inside a worker (use `ctx.db`).
+```ts
+import { Database, Log, Cache, Queue } from "@palbase/backend";
+```
+
+The **only difference** is the trigger argument:
+
+| You are writing… | Handler signature | Trigger arg |
+|------------------|-------------------|-------------|
+| **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` |
+| **Webhooks** (`webhooks/**`) | `(event, meta)` | typed event + `WebhookMeta` |
+| **Middleware** (`middleware/**`) | `(ctx, next)` | `MiddlewareContext` — the **one exception** |
+
+`meta` carries non-service data: `env` (branch env vars), `projectId`,
+`environmentId`, and for workers/webhooks `requestId`. Services always come from
+the imported singletons — not from `ctx` or any argument.
 
 ## Project shape
 
 ```
 my-backend/
 ├── package.json            # depends on @palbase/backend
-├── endpoints/              # HTTP endpoints (file-based routing)
-│   └── hello/get.ts        # → GET /hello
+├── 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)
 ├── workers/                # background job handlers (optional)
 ├── jobs/                   # cron-scheduled jobs (optional)
 ├── hooks/                  # auth/storage/document event hooks (optional)
@@ -41,15 +57,20 @@ my-backend/
 └── middleware/             # cross-cutting request middleware (optional)
 ```
 
+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) |
 | Errors | [errors.md](./errors.md) |
 | Workers & Jobs | [background.md](./background.md) |
@@ -77,7 +98,6 @@ Your project depends on the SDK and uses the Palbase CLI for the dev loop:
   "private": true,
   "scripts": {
     "dev": "palbase serve",
-    "deploy": "palbase push",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": { "@palbase/backend": "latest" },
@@ -87,157 +107,245 @@ Your project depends on the SDK and uses the Palbase CLI for the dev loop:
 
 ## Local dev loop
 
-- `palbase serve` — run your backend locally with hot reload.
-- `palbase push` — deploy the current directory to your project's backend runtime.
-- `palbase push --branch <name>` — deploy to a branch instead of `main`.
+- `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.
+- **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
 
-Create `endpoints/hello/get.ts`:
+An endpoint is a method on a class controller. Declare the schemas in `models/`:
 
 ```ts
-import { defineEndpoint, z } from "@palbase/backend";
+// models/hello/greet.ts
+import { z } from "@palbase/backend";
 
-export default defineEndpoint({
-  method: "GET",
-  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,
-  }),
-});
+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 write the controller in `controllers/hello.controller.ts`:
+
+```ts
+import { Controller, Get, Returns, Query, OptionalUser } from "@palbase/backend";
+import type { UserT } from "@palbase/backend";
+import { GreetQuery, HelloResponse } from "../models/hello/greet.js";
+
+@Controller("/hello", { auth: false })
+export default class HelloController {
+  @Get("")
+  @Returns(HelloResponse)
+  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.
+This is served at `GET /hello`. The `@Query` schema validates the query string;
+the method's return type (paired with `@Returns(HelloResponse)`) validates and
+describes the response. See [routing.md](./routing.md) and
+[endpoints.md](./endpoints.md) for the full class-controller model.
 
 
 
 <!-- ===== routing.md ===== -->
 
-# File-based routing
+# Routing
 
-The path of a file under `endpoints/` plus its filename determine the route.
-The filename is the HTTP method.
+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.
 
-| File | Route |
-|------|-------|
-| `endpoints/hello/get.ts` | `GET /hello` |
-| `endpoints/items/post.ts` | `POST /items` |
-| `endpoints/posts/[id]/get.ts` | `GET /posts/:id` |
-| `endpoints/posts/[id]/patch.ts` | `PATCH /posts/:id` |
-| `endpoints/rooms/[id]/sessions/post.ts` | `POST /rooms/:id/sessions` |
+```ts
+import { Controller, Get, Post, Body, Query, Param, User } from "@palbase/backend";
+```
 
-Rules:
+## Controllers — class + method decorators
 
-- The method file name is one of `get`, `post`, `put`, `patch`, `delete` (`.ts`).
-- A `[segment]` directory becomes a `:segment` path param, read via `req.params.segment`.
-- Each method file `export default defineEndpoint({...})` — one endpoint per file.
-- There is no central router file and no manual registration. Adding a file adds a route.
+`@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
-// endpoints/posts/[id]/get.ts  → GET /posts/:id
-import { defineEndpoint, z, Database, HttpError } from "@palbase/backend";
-
-export default defineEndpoint({
-  method: "GET",
-  output: z.object({ id: z.string(), title: z.string() }),
-  handler: async (req) => {
-    const post = await Database.findById("posts", req.params.id!);
-    if (!post) throw new HttpError(404, "post_not_found", "No such post");
-    return { id: post.id as string, title: post.title as string };
-  },
-});
+// controllers/places.controller.ts
+import { Controller, Get, Post, Returns, Body, User, z } from "@palbase/backend";
+import type { UserT } from "@palbase/backend";
+import { placeService } from "../services/place.service.js";
+import { ImportNearbyBody } from "../models/places/import.js";
+import { PlaceSchema } from "../models/places/shared.js";
+
+@Controller("/places")
+export default class PlacesController {
+  @Post("/import")
+  @Returns(PlaceSchema)
+  importNearby(@Body(ImportNearbyBody) body: ImportNearbyBody, @User() user: UserT): PlaceSchema {
+    return placeService.importNearby(body.lat, body.lng, user.id);
+  }
+
+  @Get("/favorites", { auth: false })
+  @Returns(z.array(PlaceSchema))
+  listFavorites(): PlaceSchema[] {
+    return placeService.listFavorites();
+  }
+}
 ```
 
+| Method name (sugar) | Verb | Full path | operationId (flat) |
+|---|---|---|---|
+| `importNearby`  | POST | `/places/import`    | `postPlacesImport` |
+| `listFavorites` | GET  | `/places/favorites` | `getPlacesFavorites` |
+
+Rules:
+
+- The full path of a route is `basePath + subpath` (`"/places" + "/import"`).
+- 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; pair it with `@Returns(schema)` so the zod value
+  drives the OpenAPI 200 response (or annotate `: void` for no body).
+- The operationId is derived FLAT from method + full path (`postPlacesImport`),
+  not from the method name. Change `@Post` → `@Put` — no file rename.
+
+See [endpoints.md](./endpoints.md) for the full decorator reference (`@Controller`
+options, the parameter decorators, auth cascade, and error classes).
+
 
 
 <!-- ===== endpoints.md ===== -->
 
 # Endpoints
 
-An endpoint is `export default defineEndpoint({...})` in a method file. 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)).
 
-## `defineEndpoint` config
+## A controller
 
 ```ts
-defineEndpoint({
-  method: "POST",                    // required: GET | POST | PUT | PATCH | DELETE
-  auth: { required: true },          // optional; see Auth below. Omitted → public.
-  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
-});
+// controllers/rooms.controller.ts
+import { Controller, Get, Post, Returns, Body, Param, User, NotFound, Database } from "@palbase/backend";
+import type { UserT } from "@palbase/backend";
+import { CreateRoomBody } from "../models/rooms/create.js";
+import { RoomSchema } from "../models/rooms/shared.js";
+
+@Controller("/rooms")
+export default class RoomsController {
+  @Post("")
+  @Returns(RoomSchema)
+  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 };
+  }
+
+  @Get("/{id}")
+  @Returns(RoomSchema)
+  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 };
+  }
+}
+```
+
+## Method decorators
+
+`@Get`/`@Post`/`@Put`/`@Patch`/`@Delete` take `(subpath, options?)`:
+
+```ts
+interface RouteOptions {
+  auth?: boolean | { required?: boolean; role?: string };  // overrides controller default
+  rateLimit?: { max: number; window: number };             // optional, per route
+}
 ```
 
-## `req` (PBRequest)
+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).
+
+## Parameter decorators
 
-| 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) |
+| 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` | — |
 
-`User` is `{ id: string; email: string; role: string; metadata: Record<string, unknown> }`.
+`@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.
 
-## Auth
+## Output = return type
+
+The success response is the method's RETURN TYPE. Pair it with `@Returns(schema)`
+so the zod value drives the OpenAPI 200 response (the type annotation drives
+compile-time checking; the zod value is lossless for codegen). A method that
+returns nothing annotates `: 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
-auth: { required: true }                // require any authenticated user → req.user is non-null User
-auth: { required: true, role: "admin" } // require a specific role
-auth: { required: false }               // public → req.user may be null
-// auth omitted entirely                 // also public → req.user is User | 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 { ... }
+}
 ```
 
-Whether `req.user` is non-null is computed from the `auth` config at the type
-level:
+| effective `auth` | `@User()` type to annotate |
+|------------------|----------------------------|
+| required (omitted / `true` / `{ required: true }` / role-only) | `@User() u: UserT` |
+| public (`false` / `{ required: false }`) | `@OptionalUser() u: UserT \| null` |
 
-| `auth` value | `req.user` type |
-|--------------|-----------------|
-| omitted | `User \| null` |
-| `true` | `User` |
-| `false` | `User \| null` |
-| `{ required: true }` | `User` |
-| `{ required: false }` | `User \| null` |
-| `{ role: "admin" }` (object, no `required`) | `User` |
+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).
 
-To enforce authentication, set `auth: { required: true }` (or `auth: true`). 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.
+## Errors — global throw classes
 
-## Typed input/output
+Throw an error class anywhere (controller OR service) — no `req`, no per-route
+map. The runtime catches it and emits the standard envelope:
 
 ```ts
-import { defineEndpoint, z, Database } from "@palbase/backend";
+import { Conflict, NotFound, BadRequest, Unauthorized, Forbidden, TooManyRequests, PalError } from "@palbase/backend";
 
-export default defineEndpoint({
-  method: "POST",
-  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 };
-  },
-});
+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`:
@@ -254,23 +362,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 endpoint, import it and list it in the
-endpoint's `middleware` array:
-
-```ts
-import { defineEndpoint, z } from "@palbase/backend";
-import logger from "../../middleware/logger.js";
-
-export default defineEndpoint({
-  method: "GET",
-  middleware: [logger],
-  output: z.object({ ok: z.boolean() }),
-  handler: async (req) => ({ ok: true }),
-});
-```
+rest of the chain (other middleware, then the endpoint method).
 
 
 
@@ -278,17 +370,38 @@ export default defineEndpoint({
 
 # Database
 
-In **endpoints**, import the `Database` singleton:
+Import the `Database` singleton in every handler type — endpoints, workers,
+jobs, hooks, and webhooks all use the same import:
 
 ```ts
 import { Database } from "@palbase/backend";
 ```
 
-In **workers, jobs, hooks, and webhooks**, use `ctx.db` — the same surface,
-reached via the context object (see [background.md](./background.md) and
-[events.md](./events.md)).
+Only **middleware** still uses `ctx.db` (see [background.md](./background.md)
+and [events.md](./events.md) for worker/job/hook/webhook examples).
+
+## Typed by default — `Database.tables`
+
+When you declare `db/schema.ts`, `Database.tables.<name>` is typed everywhere
+with no import and no generic. `insert` demands the right columns; rows come
+back typed; nullable columns are `T | null`. This is the path you should use:
+
+```ts
+const todo = await Database.tables.todos.insert({ title: "buy milk" });
+todo.id;       // string ✓
+todo.done;     // boolean ✓
+const open = await Database.tables.todos.findMany({ done: false });
+await Database.tables.todos.update(todo.id, { done: true });
+await Database.tables.todos.delete(todo.id);
+// todo.nope ← compile error
+```
+
+See [schema.md](./schema.md) for the full typed-table surface.
 
-## Operations
+## Raw string-keyed operations
+
+For dynamic table names or read-only SQL, the string-keyed ops are still
+available:
 
 | Method | Returns |
 |--------|---------|
@@ -300,14 +413,6 @@ reached via the context object (see [background.md](./background.md) and
 | `Database.query(sql, params?)` | rows from a read-only SQL query (runs in a READ ONLY transaction) |
 | `Database.transaction(fn)` | runs `fn(tx)` in a transaction |
 
-```ts
-const row = await Database.insert("todos", { title: "buy milk", done: false });
-const one = await Database.findById("todos", row.id as string);
-const open = await Database.findMany("todos", { done: false });
-await Database.update("todos", row.id as string, { done: true });
-await Database.delete("todos", row.id as string);
-```
-
 `findMany`'s `query` is an equality filter: keys are ANDed together. For
 anything richer (ranges, ordering, joins) use `Database.query`.
 
@@ -328,14 +433,54 @@ transaction). Returning commits; throwing rolls back.
 
 ```ts
 await Database.transaction(async (tx) => {
-  const order = await tx.insert("orders", { amount: 1000, status: "pending" });
-  await tx.insert("order_items", { order_id: order.id, sku: "ABC" });
+  const order = await tx.tables.orders.insert({ amount: 1000, status: "pending" });
+  await tx.tables.order_items.insert({ order_id: order.id, sku: "ABC" });
   // throw here → both inserts roll back
 });
 ```
 
-For a typed `.tables.*` API instead of string table names, see
-[schema.md](./schema.md).
+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.
 
 
 
@@ -344,36 +489,50 @@ For a typed `.tables.*` API instead of string table names, see
 # Schema & typed database access
 
 Declare your tables in `db/schema.ts` with `defineSchema`. This drives
-migrations and, via `typedDatabase`, a fully-typed `.tables.*` API.
+[migrations](./migrations.md) (additive changes auto-apply on deploy; type
+changes need an explicit migration) and makes `Database.tables.*` typed
+everywhere — by default, with no import and no generic.
 
 ## Defining a schema
 
+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 {
-  defineSchema, table,
+  defineSchema,
   uuid, text, integer, boolean, timestamp, jsonb, enumType,
 } from "@palbase/backend";
 
 export default defineSchema({
-  rooms: table("rooms", {
-    id: uuid().primaryKey().defaultRandom(),
-    name: text().notNull(),
-    capacity: integer().nullable(),
-    is_active: boolean().default(true),
-    created_at: timestamp().defaultNow(),
-  }),
-  sessions: table("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(),
-  }),
-  orders: table("orders", {
-    id: uuid().primaryKey().defaultRandom(),
-    status: enumType("order_status", ["pending", "paid", "shipped", "cancelled"]),
-    amount: integer().notNull(),
-  }),
+  tables: {
+    rooms: {
+      columns: {
+        id: uuid().primaryKey().defaultRandom(),
+        name: text().notNull(),
+        capacity: integer().nullable(),
+        is_active: boolean().default(true),
+        created_at: timestamp().defaultNow(),
+      },
+    },
+    sessions: {
+      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: {
+      columns: {
+        id: uuid().primaryKey().defaultRandom(),
+        status: enumType("order_status", ["pending", "paid", "shipped", "cancelled"]),
+        amount: integer().notNull(),
+      },
+    },
+  },
 });
 ```
 
@@ -394,35 +553,245 @@ Chainable modifiers: `.primaryKey()`, `.notNull()` (default), `.nullable()`,
 `.defaultNow()` (timestamp → `now()`), `.references(table, column)`,
 `.onDelete("cascade" | "set null" | "restrict" | "no action")`.
 
-## Typed DB access
+## Typed DB access — by default
+
+You do **not** wire anything per endpoint. Saving `db/schema.ts` regenerates
+`palbase-env.d.ts`, which types `Database.tables.<name>` everywhere — no import
+of the schema, no generic, no cast:
+
+```ts
+import { Controller, Post, Returns, 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("")
+  @Returns(RoomOut)
+  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)`,
+`findById(id)`, `findMany(query?)`, and `Database.transaction(fn)` yields a `tx`
+with the same typed tables. The raw string-keyed ops
+(`Database.insert("rooms", …)`, `Database.query(…)`) are still available for
+dynamic table names and read-only SQL.
+
+If you want a row type explicitly, import it from the generated env module:
+
+```ts
+import type { Tables } from "@palbase/backend/env";
+type Room = Tables["rooms"]["row"];
+```
+
+## Row-Level Security (RLS)
 
-`typedDatabase(schema)` returns a typed facade. `insert` demands the right
-columns; rows come back typed; nullable columns are `T | null`.
+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.
+
+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.
+
+### The `policy()` builder
+
+`policy(name)` is a fluent builder, just like the column builders:
 
 ```ts
-import { defineEndpoint, z, typedDatabase } from "@palbase/backend";
-import schema from "../../db/schema.js";
+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)
+```
+
+| 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). |
 
-const Db = typedDatabase(schema);
+**`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.
 
-export default defineEndpoint({
-  method: "POST",
-  input: z.object({ name: z.string() }),
-  output: z.object({ id: z.string(), name: z.string() }),
-  handler: async (req) => {
-    const room = await Db.tables.rooms.insert({ name: req.input.name });
-    return { id: room.id, name: room.name };
+> 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, …).
+
+### Owner-scoped `todos` example
+
+```ts
+import { defineSchema, policy, uuid, text, boolean, timestamp } from "@palbase/backend";
+
+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())"),
+      ],
+    },
   },
 });
 ```
 
-Note the `.js` extension on `../../db/schema.js` even though the file is
-`db/schema.ts` — this is standard ESM module resolution; you still author the
-file as `.ts`.
+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
+
+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.
+
+> 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 ===== -->
 
-`Db.tables.<name>` exposes `insert`, `update(id, data)`, `delete(id)`,
-`findById(id)`, `findMany(query?)`, and `Db.transaction(fn)` mirrors the
-untyped transaction with typed tables.
+# Migrations
+
+`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.
+
+## Two kinds of change
+
+### 1. Additive — auto-applied, no migration file
+
+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.
+
+```ts
+// before
+todos: {
+  id: uuid().primaryKey().defaultRandom(),
+  title: text().notNull(),
+}
+
+// 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"),
+}
+```
+
+> 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).
+
+### 2. Destructive / type-changing — needs an explicit migration
+
+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/`:
+
+```
+db/migrations/
+  001_user_id_to_text.up.sql
+  001_user_id_to_text.down.sql
+```
+
+```sql
+-- 001_user_id_to_text.up.sql
+ALTER TABLE todos ALTER COLUMN user_id TYPE text USING user_id::text;
+```
+
+```sql
+-- 001_user_id_to_text.down.sql
+ALTER TABLE todos ALTER COLUMN user_id TYPE uuid USING user_id::uuid;
+```
+
+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
+
+On deploy, Palbase compares `db/schema.ts` to the live 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.
+
+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.
+
+## Local dev: `palbase serve` uses the deployed database
+
+`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.
+
+## Workflow
+
+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.
+
+See [schema.md](./schema.md) for the column builders and typed
+`Database.tables.*` access.
 
 
 
@@ -430,9 +799,9 @@ untyped transaction with typed tables.
 
 # Services
 
-In **endpoints**, import service singletons from `@palbase/backend`. In
-**workers/jobs/hooks/webhooks**, the equivalents live on `ctx` (`ctx.cache`,
-`ctx.queue`, `ctx.log`, `ctx.db`).
+Import service singletons from `@palbase/backend` in every handler type —
+endpoints, workers, jobs, hooks, and webhooks all use the same imports. Only
+**middleware** uses a `ctx` argument (`ctx.db`, `ctx.log`, etc.).
 
 Available singletons: `Database`, `Documents`, `Storage`, `Cache`, `Queue`,
 `Log`, `Notifications`, `Flags`.
@@ -520,18 +889,120 @@ await Notifications.sms.send({ /* PalbaseSmsSendParams */ });
 ## Flags
 
 ```ts
-import { defineEndpoint, z, Flags } from "@palbase/backend";
-
-export default defineEndpoint({
-  method: "GET",
-  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, Returns, 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
+  @Returns(FlagsOut)
+  async flags(@User() user: UserT): Promise<z.infer<typeof FlagsOut>> {
+    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 };
-  },
-});
+  }
+}
+```
+
+
+
+<!-- ===== resources.md ===== -->
+
+# Resources
+
+A `Resource` models one external connection — a pooled datastore, a stateless
+API client, or a per-user factory. You put it in `resources/`, export an
+instance, and **do not register it**: the framework discovers it, sets it up
+once at boot, and drains it on shutdown. On top of that lifecycle you expose
+your own clean facade.
+
+```ts
+import { Resource } from "@palbase/backend";
+```
+
+## Lifecycle (boot scope — not per request)
+
+A resource is created once at process boot — NOT per request. The framework:
+
+1. calls `init(env)` **once**, with only the secrets the resource declared;
+2. (optionally) calls `shutdown()` on SIGTERM, in reverse boot order.
+
+The instance lives for the whole process; your facade methods are called
+per-request. This makes "reconnect on every request" structurally impossible.
+
+## Pooled datastore — `init` + `shutdown`
+
+```ts
+import { Resource } from "@palbase/backend";
+import neo4j, { type Driver, type Session } from "neo4j-driver";
+
+export class Neo4jResource extends Resource {
+  static secrets = ["NEO4J_URL", "NEO4J_USER", "NEO4J_PASSWORD"] as const;
+  private driver!: Driver;
+  async init(env: { NEO4J_URL: string; NEO4J_USER: string; NEO4J_PASSWORD: string }) {
+    this.driver = neo4j.driver(env.NEO4J_URL, neo4j.auth.basic(env.NEO4J_USER, env.NEO4J_PASSWORD));
+  }
+  async shutdown() {
+    await this.driver.close();
+  }
+  session(): Session {
+    return this.driver.session();
+  }
+}
+
+export const graph = new Neo4jResource();
+```
+
+## Stateless API client — `init` only
+
+```ts
+import { Resource } from "@palbase/backend";
+import { Client } from "@googlemaps/google-maps-services-js";
+
+export class GoogleResource extends Resource {
+  static secrets = ["GOOGLE_MAPS_KEY"] as const;
+  private client = new Client();
+  private key = "";
+  init(env: { GOOGLE_MAPS_KEY: string }) {
+    this.key = env.GOOGLE_MAPS_KEY;
+  }
+  nearby(lat: number, lng: number) {
+    return this.client.placesNearby({ params: { location: { lat, lng }, radius: 1500, key: this.key } });
+  }
+}
+
+export const google = new GoogleResource();
+```
+
+A per-user (OAuth) resource adds a factory method on the base, e.g.
+`github.forUser(token)` — the same single model covers pooled, stateless, and
+per-user.
+
+## Secrets
+
+`static secrets` is the contract:
+
+- It **types** the `env` passed to `init` — only the declared names are
+  present, each a `string`. An undeclared key is a compile error.
+- A declared secret that is **missing at boot fails the deploy**, naming the
+  secret. Secrets are branch-scoped; set them with `palbase secret set NAME ...`
+  or in Studio. A resource is initialised once at boot, so rotating a secret
+  needs a redeploy/restart.
+
+`secrets` is optional — a resource that needs none simply omits it and gets an
+empty `env`.
+
+## Using a resource
+
+Import the singleton and call your facade — services and handlers reach
+resources the same way they reach `Database`:
+
+```ts
+import { google } from "../resources/google.js";
+
+const results = (await google.nearby(41.0, 29.0)).data.results;
 ```
 
 
@@ -540,52 +1011,58 @@ export default defineEndpoint({
 
 # 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?)`.
-
-## 2. Declared errors (typed)
+Each class fixes its HTTP status. The constructor is
+`new <Class>(message?, code?, data?)`:
 
-Declare them on the endpoint; throw via `req.errors.<name>(...)`. Declared
-errors are described in the endpoint's OpenAPI and codegen'd into a typed enum
-for iOS callers.
+- `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
-import { defineEndpoint, z, Database } from "@palbase/backend";
+throw new NotFound("Room does not exist", "room_not_found");
+throw new Conflict("locked", "title_locked", { retryAfter: 30 });
+```
 
-export default defineEndpoint({
-  method: "POST",
-  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 };
-  },
-});
+## `PalError` / `HttpError` (custom status)
+
+For a status/code not covered by a named class:
+
+```ts
+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.
 
 
 
@@ -593,10 +1070,10 @@ one without `data` takes no arguments. This is enforced by the types.
 
 # Workers & Jobs
 
-Workers and jobs use the **`ctx` model**: their handler receives a context
-object with `ctx.db`, `ctx.log`, `ctx.cache`, `ctx.queue`, `ctx.env`. They do
-**not** receive a `req`, and you do **not** import the `Database` singleton
-inside them — use `ctx.db`.
+Workers and jobs use the **singleton model** — the same imported service
+singletons as endpoints (`import { Database, Log } from "@palbase/backend"`).
+They do **not** receive a `req`. Instead, a small `meta` argument carries the
+non-service data (`env`, `user`, correlation ids).
 
 ## Workers (queue consumers)
 
@@ -605,7 +1082,7 @@ A worker processes jobs pushed via `Queue.push(name, payload)`. File lives under
 
 ```ts
 // workers/process-order.ts
-import { defineWorker } from "@palbase/backend";
+import { defineWorker, Database, Log } from "@palbase/backend";
 
 interface OrderPayload { orderId: string; amount: number; }
 
@@ -614,13 +1091,16 @@ export default defineWorker<OrderPayload>({
   retry: 5,                    // optional, default 3
   timeout: 60,                 // optional, seconds
   backoff: "exponential",      // "exponential" | "linear" | "fixed", default exponential
-  handler: async (ctx, payload) => {
-    ctx.log.info(`processing ${payload.orderId} for $${payload.amount}`);
-    await ctx.db.update("orders", payload.orderId, { status: "processed" });
+  handler: async (payload, meta) => {
+    Log.info(`processing ${payload.orderId} (env ${meta.environmentId})`);
+    await Database.update("orders", payload.orderId, { status: "processed" });
   },
 });
 ```
 
+`meta` shape: `{ env, user, requestId, projectId, environmentId }`. Branch env
+vars are in `meta.env`; services come from the imported singletons.
+
 Enqueue from an endpoint:
 
 ```ts
@@ -634,29 +1114,34 @@ A job runs on a cron schedule. File lives under `jobs/`.
 
 ```ts
 // jobs/cleanup.ts
-import { defineJob } from "@palbase/backend";
+import { defineJob, Database, Log } from "@palbase/backend";
 
 export default defineJob({
   name: "cleanup-expired",
   schedule: "0 3 * * *",       // standard cron
   timeout: 120,                // optional, seconds
-  handler: async (ctx) => {
-    const expired = await ctx.db.findMany("sessions", { expired: true });
-    for (const s of expired) await ctx.db.delete("sessions", s.id as string);
-    ctx.log.info(`cleaned ${expired.length} sessions`);
+  handler: async (meta) => {
+    const expired = await Database.findMany("sessions", { expired: true });
+    for (const s of expired) await Database.delete("sessions", s.id as string);
+    Log.info(`cleaned ${expired.length} sessions in ${meta.projectId}`);
   },
 });
 ```
 
+`meta` shape: `{ env, projectId, environmentId }`. No `user` (jobs are
+system-initiated).
+
 
 
 <!-- ===== events.md ===== -->
 
 # Hooks & Webhooks
 
-Like workers/jobs, hooks and webhooks use the **`ctx` model** (`ctx.db`,
-`ctx.log`, `ctx.cache`, `ctx.queue`, `ctx.env`) — not `req`, and not imported
-singletons.
+Like workers/jobs, hooks and webhooks use the **singleton model** — the same
+imported service singletons as endpoints (`import { Database, Log } from
+"@palbase/backend"`). They do **not** receive a `req`. A second `meta` argument
+carries the non-service data (`env`, `projectId`, `environmentId`; webhooks also
+get `requestId`).
 
 ## Hooks (platform events)
 
@@ -665,21 +1150,24 @@ are imported from `@palbase/backend`: `auth`, `storage`, `documents`.
 
 ```ts
 // hooks/auth.ts
-import { auth } from "@palbase/backend";
+import { auth, Database, Log } from "@palbase/backend";
 
-export const onUserCreated = auth.onUserCreated(async (ctx, event) => {
-  ctx.log.info(`new user: ${event.user.email}`);
-  await ctx.db.insert("profiles", {
+export const onUserCreated = auth.onUserCreated(async (event, meta) => {
+  Log.info(`new user: ${event.user.email}`);
+  await Database.insert("profiles", {
     user_id: event.user.id,
     email: event.user.email,
   });
 });
 
-export const onSignIn = auth.onSignIn(async (ctx, event) => {
-  ctx.log.info(`sign in: ${event.user.email} via ${event.provider}`);
+export const onSignIn = auth.onSignIn(async (event, meta) => {
+  Log.info(`sign in: ${event.user.email} via ${event.provider}`);
 });
 ```
 
+`meta` shape: `{ env, projectId, environmentId }`. Branch env vars are in
+`meta.env`; services come from the imported singletons.
+
 Available hook builders: `auth.onUserCreated`, `auth.onSignIn`, `auth.onSignOut`,
 `auth.onPasswordReset`, `storage.onFileUploaded`, `storage.onFileDeleted`,
 `documents.onDocumentCreated`, `documents.onDocumentUpdated`,
@@ -692,22 +1180,25 @@ Receive and verify webhooks from third-party providers. Files live under
 
 ```ts
 // webhooks/stripe.ts
-import { defineWebhook } from "@palbase/backend";
+import { defineWebhook, Database, Log } from "@palbase/backend";
 
 export default defineWebhook({
   provider: "stripe",
   secret: { env: "STRIPE_WEBHOOK_SECRET" },   // signing secret resolved from env
   events: {
-    "checkout.session.completed": async (ctx, event) => {
-      await ctx.db.insert("orders", { status: "paid", data: event });
+    "checkout.session.completed": async (event, meta) => {
+      await Database.insert("orders", { status: "paid", data: event });
     },
-    "payment_intent.payment_failed": async (ctx, event) => {
-      ctx.log.error("payment failed");
-      await ctx.db.insert("payment_failures", { data: event });
+    "payment_intent.payment_failed": async (event, meta) => {
+      Log.error("payment failed");
+      await Database.insert("payment_failures", { data: event });
     },
   },
 });
 ```
 
-The signing secret is read from the project's env/secrets (`{ env: "NAME" }`);
-the runtime verifies the signature before dispatching to your event handlers.
+The signing secret is resolved by the runtime from `secret: { env: "NAME" }`;
+your handlers access branch env vars via `meta.env`. The runtime verifies the
+signature before dispatching to your event handlers.
+
+`meta` shape: `{ env, requestId, projectId, environmentId }`.