@palbase/backend 32.0.0 → 33.0.1

package/docs/llms-full.txt

@@ -24,15 +24,24 @@ deploy gate or the TypeScript compile.
 
 ### Folder layout
 
+Every domain is a FOLDER under `modules/`, carrying its own controller, service,
+schemas, and the one module that lists them:
+
 ```
-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                      # one file per Postgres schema (db/public.ts in a fresh scaffold)
+modules/<domain>/<domain>.module.ts     # @Module: controllers · providers · exports · imports
+modules/<domain>/<name>.controller.ts   # @Controller class + @Get/@Post/… route methods (the API surface)
+modules/<domain>/<name>.service.ts      # @Injectable() class — the real logic (controllers stay thin)
+modules/<domain>/dto/<endpoint>.ts      # zod schemas — one file per endpoint
+db/<schema>.ts                          # one file per Postgres schema (db/public.ts in a fresh scaffold)
 ```
 
-The four folders above are the daily surface. Three more are discovered by name,
-one class per file, `export default` required: `jobs/` (background —
+There is no root `controllers/`, `services/` or `models/` directory, and no
+`app.module.ts` to mount anything into: a `*.module.ts` is found wherever it
+lives, so adding a domain means adding a folder — never a line in a file every
+branch edits.
+
+The schema stays at the root, in `db/`. Three more directories are discovered by
+name, one class per file, `export default` required: `jobs/` (background —
 [background.md](./background.md)), `webhooks/` and `hooks/` (events —
 [events.md](./events.md)).
 
@@ -66,7 +75,7 @@ service the controllers call.
    + 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
+5. **Schemas live in `modules/<domain>/dto/<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).
@@ -81,12 +90,12 @@ service the controllers call.
 
 > **Never** emit `defineController`, `defineHandler`, `defineEndpoint`, `route.get(...)`,
 > `req.input`, `req.params`, or `req.errors` — those are the removed legacy model
-> and will not compile against `@palbase/backend` 32.
+> and will not compile against `@palbase/backend` 33.
 
 ### Complete CRUD example (copy-pasteable, compiles)
 
 ```ts
-// models/todos/shared.ts — the response shape, reused across endpoints.
+// modules/todos/dto/shared.ts — the response shape, reused across endpoints.
 import { z } from "@palbase/backend";
 export const TodoSchema = z.object({
   id: z.string(),
@@ -97,41 +106,63 @@ export type TodoSchema = z.infer<typeof TodoSchema>;
 ```
 
 ```ts
-// models/todos/create.ts — the POST body.
+// modules/todos/dto/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.
+// modules/todos/todo.service.ts — @Injectable() classes. The real work.
 import { Database, Injectable, NotFound } from "@palbase/backend";
-import type { TodoSchema } from "../models/todos/shared.js";
+import type { Tables } from "@palbase/backend/env";
 
-/** The typed surface of ONE table. Naming it keeps the seam one table wide:
- * a test fake implements five methods, not the whole `Database`. */
-type TodosTable = typeof Database.public.todos;
+/** One row of `todos`, exactly as `db/public.ts` declares it. */
+export type Todo = Tables["todos"]["row"];
+
+/** The one table this vertical touches, behind a class the container can build.
+ * `Database.public.todos` is a VALUE, and a dependency is named by its
+ * parameter's TYPE — so the seam is an `abstract class`, and it stays ONE table
+ * wide: a test fake implements four methods, not the whole `Database`. */
+export abstract class TodoRepo {
+  // Mirror the table's own call shape: `findMany` takes `{ where, orderBy, … }`,
+  // not a bare filter.
+  abstract findMany(q: { where: { user_id: string } }): Promise<Todo[]>;
+  abstract insert(row: { user_id: string; title: string }): Promise<Todo>;
+  abstract findById(id: string): Promise<Todo | null>;
+  abstract delete(id: string): Promise<void>;
+}
 
 @Injectable()
-export class TodoService {
-  private readonly todos: TodosTable;
-
-  // THE SEAM IS THE CONSTRUCTOR: the class is handed the table rather than
-  // reaching for the singleton, so a test constructs it with a stand-in and
-  // never needs a database. Assign in the BODY — a parameter property
-  // (`constructor(private todos: …)`) is refused by Node's type-stripping test
-  // runner, and refused for the whole FILE.
-  constructor(todos: TodosTable) {
-    this.todos = todos;
+export class DbTodoRepo extends TodoRepo {
+  findMany(q: { where: { user_id: string } }): Promise<Todo[]> {
+    return Database.public.todos.findMany(q);
+  }
+  insert(row: { user_id: string; title: string }): Promise<Todo> {
+    return Database.public.todos.insert(row);
   }
+  findById(id: string): Promise<Todo | null> {
+    return Database.public.todos.findById(id);
+  }
+  delete(id: string): Promise<void> {
+    return Database.public.todos.delete(id);
+  }
+}
+
+@Injectable()
+export class TodoService {
+  // THE SEAM IS THE CONSTRUCTOR: the container supplies this, so a test hands in
+  // a stand-in and never needs a database. Nothing registers it and nothing
+  // wires it — `todos.module.ts` lists the class, and that list is the ownership.
+  constructor(private readonly todos: TodoRepo) {}
 
-  list(userId: string): Promise<TodoSchema[]> {
+  list(userId: string): Promise<Todo[]> {
     return this.todos.findMany({ where: { user_id: userId } });
   }
-  create(userId: string, title: string): Promise<TodoSchema> {
+  create(userId: string, title: string): Promise<Todo> {
     return this.todos.insert({ user_id: userId, title });
   }
-  async get(userId: string, id: string): Promise<TodoSchema> {
+  async get(userId: string, id: string): Promise<Todo> {
     const t = await this.todos.findById(id);
     if (!t || t.user_id !== userId) throw new NotFound("No todo with that id");
     return t;
@@ -141,68 +172,74 @@ export class TodoService {
     await this.todos.delete(id);
   }
 }
-
 ```
 
 ```ts
-// todos.module.ts — ONE module says what exists, who owns it, and what it may reach.
+// modules/todos/todos.module.ts — ONE module says what exists, who owns it, and what it may reach.
 import { Module, type Token } from "@palbase/backend";
-import { TodosController } from "./controllers/todos.controller.ts";
-import { TodoService } from "./services/todo.service.ts";
+import { TodosController } from "./todos.controller.ts";
+import { DbTodoRepo, TodoService } from "./todo.service.ts";
 
 @Module({
   controllers: [TodosController as Token],
-  providers: [TodoService as Token],
+  providers: [TodoService as Token, DbTodoRepo as Token],
+  exports: [],   // which of its own classes ANOTHER module may reach
+  imports: [],   // whose exports THIS module may reach
 })
 export class TodosModule {}
 ```
 
-A class no module lists does not exist: it is refused at build, by name, and it
-never reaches the route table or the OpenAPI document. Nothing is wired by hand
-— a controller names `TodoService` as a constructor parameter and the container
-supplies it. See [services.md](./services.md#your-own-service-layer).
+The abstraction is the TOKEN and the implementation is the PROVIDER: `DbTodoRepo`
+is listed, `TodoRepo` is not — the container resolves an abstraction to the single
+class that `extends` it. A class no module lists does not exist: it is refused at
+build, by name, and it never reaches the route table or the OpenAPI document.
+Nothing is wired by hand — a controller names `TodoService` as a constructor
+parameter and the container supplies it. See
+[services.md](./services.md#your-own-service-layer).
 
 ```ts
-// controllers/todos.controller.ts — class controller. Thin: delegates to the service.
+// modules/todos/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";
+import { TodoService } from "./todo.service";
+import { TodoSchema } from "./dto/shared";
+import { CreateTodoBody } from "./dto/create";
 
 @Controller("/todos")                                  // secure-by-default; { auth: false } opts the whole controller out
-export default class TodosController {
-  // The service arrives as an IMPORTED SINGLETON, not a constructor parameter:
-  // the runtime constructs this class with no arguments, and one that declares a
-  // parameter is refused when the route table is built at boot, with the class named.
+export class TodosController {
+  // The service arrives through the CONSTRUCTOR and the container supplies it.
+  // Nothing is imported as an instance and nothing is wired by hand.
+  constructor(private readonly todos: TodoService) {}
 
   @Get("")                                             // GET /todos → operationId todos.list
-  async list(@User() user: UserT): Promise<TodoSchema[]> {  // return type → 200 response schema
-    return todoService.list(user.id);
+  list(@User() user: UserT): Promise<TodoSchema[]> {   // return type → 200 response schema
+    return this.todos.list(user.id);
   }
 
   @Post("")                                            // POST /todos → todos.create
-  async create(@Body(CreateTodoBody) body: CreateTodoBody, @User() user: UserT): Promise<TodoSchema> {
-    return todoService.create(user.id, body.title);
+  create(@Body(CreateTodoBody) body: CreateTodoBody, @User() user: UserT): Promise<TodoSchema> {
+    return this.todos.create(user.id, body.title);
   }
 
   @Get("/{id}")                                        // GET /todos/{id} → todos.get
-  async get(@Param("id") id: string, @User() user: UserT): Promise<TodoSchema> {
-    return todoService.get(user.id, id);
+  get(@Param("id") id: string, @User() user: UserT): Promise<TodoSchema> {
+    return this.todos.get(user.id, id);
   }
 
   @Delete("/{id}")                                     // DELETE /todos/{id} → todos.remove; no body → : Promise<void>
-  async remove(@Param("id") id: string, @User() user: UserT): Promise<void> {
-    await todoService.remove(user.id, id);
+  remove(@Param("id") id: string, @User() user: UserT): Promise<void> {
+    return this.todos.remove(user.id, id);
   }
 }
-// No export is needed at all — @Controller registered the class as it decorated
-// it. `export default` here is style, not a requirement.
+// Exported by NAME, because `todos.module.ts` imports it to list it in
+// `controllers` — that list IS the registration. Nothing here is
+// default-exported.
 ```
 
 ```ts
 // db/public.ts — config-as-code; the deploy auto-migrates additive changes.
 // ONE SCHEMA PER FILE: this is `public`; a sibling `db/billing.ts` declares its own.
+// The schema stays at the ROOT — it is not part of any module.
 import { defineSchema, defineTable, uuid, text, boolean, timestamp, policy, ownedByUser } from "@palbase/backend";
 
 export const todos = defineTable("todos", {
@@ -213,8 +250,8 @@ export const todos = defineTable("todos", {
     completed:  boolean().default(false),
     created_at: timestamp().defaultNow(),
   },
-  rls: true,                                         // every Database.* query runs as the request user
-  policies: [
+  // RLS is ON by default, and `policies` is a CALLBACK — not an array.
+  policies: () => [
     policy("pb_owner_all")
       .for("all")
       .to("authenticated")
@@ -270,54 +307,63 @@ generated client surface) changes; the verb/path do not affect it.
 
 ## Mental model
 
-Every handler type imports service singletons the same way:
+Every handler type reaches the PLATFORM services through the same import:
 
 ```ts
-import { Database, Log, Cache, Queue } from "@palbase/backend";
+import { Database, Log, Cache } from "@palbase/backend";
 ```
 
+(Your OWN services are different: a controller names one as a constructor
+parameter and the container supplies it — see the example above.)
+
 The **only difference** is the trigger argument:
 
 | You are writing… | Handler signature | Trigger arg |
 |------------------|-------------------|-------------|
-| **Endpoints** (`controllers/` class controllers) | method `(…params)` | parameter decorators `@Body`/`@QueryParams`/`@Param`/`@User`/… — [endpoints.md](./endpoints.md) |
+| **Endpoints** (`modules/<domain>/` class controllers) | method `(…params)` | parameter decorators `@Body`/`@QueryParams`/`@Param`/`@User`/… — [endpoints.md](./endpoints.md) |
 | **Jobs** (`jobs/**`) | `(meta)` | `JobMeta` |
 | **Hooks** (`hooks/**`) | `(event, meta)` | typed event + `HookMeta` |
 | **Webhooks** (`webhooks/**`) | `(event, meta)` | typed event + `WebhookMeta` |
 
 `defineMiddleware(fn)` **throws when called**: no bundler reads a `middleware/`
 directory and the engine never calls one, so a handler written against it would
-deploy and never run. There is no `ctx` anywhere on a path that runs — every
-handler above imports its services.
+deploy and never run. There is no `ctx` anywhere on a path that runs — a handler
+imports the platform services it needs.
 
 `meta` carries non-service data: `env` (Environment variables),
-`environmentId`, and for webhooks `requestId`. Services always come from
-the imported singletons — not from `ctx` or any argument.
+`environmentId`, and for webhooks `requestId`. Platform services always come
+from the import — not from `ctx` or any argument.
 
 ## Project shape
 
 ```
 my-backend/
-├── package.json            # depends on @palbase/backend
-├── 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/public.ts            # the database itself: tables, columns, RLS policies
-├── jobs/                   # cron-scheduled jobs (optional)
-├── hooks/                  # auth/storage/document event hooks (optional)
-└── webhooks/               # inbound provider webhooks (optional)
+├── package.json                  # depends on @palbase/backend
+├── tsconfig.json                 # experimentalDecorators + emitDecoratorMetadata (both required)
+├── modules/                      # ONE FOLDER PER DOMAIN — there is no root module
+│   ├── health/
+│   │   ├── health.controller.ts  # @Controller("/health", { auth: false }) + @Get
+│   │   └── health.module.ts      # the four lists that make the class exist
+│   └── notes/
+│       ├── notes.controller.ts   # HTTP only — never imports `Database`
+│       ├── note.service.ts       # @Injectable(); the logic worth testing
+│       ├── note.service.test.ts  # the service, through the container, no database
+│       ├── notes.module.ts       # controllers · providers · exports · imports
+│       └── dto/create.ts         # zod schemas (value + same-named z.infer type)
+├── db/public.ts                  # the database itself: tables, columns, RLS policies
+├── jobs/                         # cron-scheduled jobs (optional)
+├── hooks/                        # auth/storage/document event hooks (optional)
+└── webhooks/                     # inbound provider webhooks (optional)
 ```
 
 There is **no `db/migrations/`**. Nothing generates a migration file, nothing
 commits one and nothing replays one: `db/*.ts` is diffed against the live
 database and applied — see [migrations.md](./migrations.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).
+HTTP endpoints are **not** file-path routed, and no directory mounts them. You
+author a class controller (`@Controller("/base")` with `@Get`/`@Post`/… methods)
+and a `@Module` lists it in `controllers` — that list is the registration. See
+[routing.md](./routing.md).
 
 ## Documentation
 
@@ -336,8 +382,6 @@ HTTP endpoints are **not** file-path routed. You author a class controller
 
 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>
 
 
 
@@ -378,7 +422,8 @@ The controllers use **decorators**, so the `tsconfig.json` must set
     "experimentalDecorators": true,
     "noEmit": true
   },
-  "include": ["controllers/**/*.ts", "models/**/*.ts", "services/**/*.ts", "db/**/*.ts", "*.d.ts"]
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", ".palbase"]
 }
 ```
 
@@ -388,7 +433,7 @@ Your backend runs on Palbase, not on your laptop — there is no local runtime t
 start. The loop is: edit, validate, push to a dev Environment.
 
 - `palbase build` — validate the tree the way the deploy will. It stages and
-  bundles your `controllers/` exactly as the deploy does and runs the deploy's
+  bundles your `modules/` exactly as the deploy does and runs the deploy's
   own metadata extractor over the result, so a bad decorator, an illegal return
   type or an SDK major skew fails here rather than shipping a deploy that
   serves zero endpoints. It is wired into a `pre-push` git hook for you. It also
@@ -402,10 +447,10 @@ start. The loop is: edit, validate, push to a dev Environment.
 
 ## Your first endpoint
 
-An endpoint is a method on a class controller. Declare the schemas in `models/`:
+An endpoint is a method on a class controller. Everything for one domain lives in `modules/<domain>/`; declare the schemas in its `dto/`:
 
 ```ts
-// models/hello/greet.ts
+// modules/hello/dto/greet.ts
 import { z } from "@palbase/backend";
 
 export const GreetQuery = z.object({ name: z.string().optional() });
@@ -415,13 +460,13 @@ export const HelloResponse = z.object({ message: z.string(), user: z.string().nu
 export type HelloResponse = z.infer<typeof HelloResponse>;
 ```
 
-Then write the controller in `controllers/hello.controller.ts`:
+Then write the controller in `modules/hello/hello.controller.ts`:
 
 ```ts
 import { Controller, Get, QueryParams, 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
+import { GreetQuery } from "./dto/greet.js";
+import type { HelloResponse } from "./dto/greet.js";  // the return TYPE names the 200 schema
 
 @Controller("/hello", { auth: false })
 export default class HelloController {
@@ -461,8 +506,11 @@ 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`/`@Query`. Request input + context are
 injected into the method via **parameter decorators** (`@Body`/`@QueryParams`/
-`@Param`/`@User`/…). Putting a controller file under `controllers/` mounts it —
-there is no central router and no manual registration.
+`@Param`/`@User`/…). A controller is mounted by being LISTED: its module names
+it in `controllers`, and that list is the only place ownership is decided. A
+class no module lists does not exist — the build refuses it by name, and it
+never reaches the route table or the OpenAPI document. Being in a particular
+folder grants nothing.
 
 ```ts
 import { Controller, Get, Post, Body, QueryParams, Param, User } from "@palbase/backend";
@@ -471,31 +519,51 @@ import { Controller, Get, Post, Body, QueryParams, Param, User } from "@palbase/
 ## Controllers — class + method decorators
 
 `@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).
+method declares its verb + subpath; the real work lives in an `@Injectable()`
+service that arrives through the CONSTRUCTOR (the controller method is thin).
 
 ```ts
-// controllers/places.controller.ts
+// modules/places/places.controller.ts
 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
+import { PlaceService } from "./place.service.js";
+import { ImportNearbyBody } from "./dto/import.js";
+import { PlaceSchema } from "./dto/shared.js";  // the return TYPE names the 200 schema
 
 @Controller("/places")
-export default class PlacesController {
+export class PlacesController {
+  constructor(private readonly places: PlaceService) {}
+
   @Post("/import")
   importNearby(@Body(ImportNearbyBody) body: ImportNearbyBody, @User() user: UserT): PlaceSchema {
-    return placeService.importNearby(body.lat, body.lng, user.id);
+    return this.places.importNearby(body.lat, body.lng, user.id);
   }
 
   @Get("/favorites", { auth: false })
   listFavorites(): PlaceSchema[] {
-    return placeService.listFavorites();
+    return this.places.listFavorites();
   }
 }
 ```
 
+The class is mounted by being LISTED, and nothing else mounts it:
+
+```ts
+// modules/places/places.module.ts
+import { Module, type Token } from "@palbase/backend";
+
+import { PlacesController } from "./places.controller.js";
+import { PlaceService } from "./place.service.js";
+
+@Module({
+  controllers: [PlacesController as Token],
+  providers: [PlaceService as Token],
+  exports: [],
+  imports: [],
+})
+export class PlacesModule {}
+```
+
 | Method name | Verb | Full path | operationId (dotted) |
 |---|---|---|---|
 | `importNearby`  | POST | `/places/import`    | `places.importNearby` |
@@ -533,36 +601,41 @@ options, the parameter decorators, auth cascade, and error classes).
 
 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`/`@Query`. 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`/`@QueryParams`/
-`@Param`/`@User`/…), each piece direct — no `req` god-object. Services are reached via the
-imported singletons (see [services.md](./services.md)).
+`@Patch`/`@Delete`/`@Query`. A controller lives in its domain's folder
+(`modules/<domain>/<name>.controller.ts`) and a `@Module` lists it in
+`controllers` — that list is the registration, not the directory (see
+[routing.md](./routing.md)). Request input + context are injected into the method
+via **parameter decorators** (`@Body`/`@QueryParams`/`@Param`/`@User`/…), each
+piece direct — no `req` god-object. Your own services arrive through the
+CONSTRUCTOR and the container supplies them (see [services.md](./services.md)).
 
 ## A controller
 
 ```ts
-// controllers/rooms.controller.ts
+// modules/rooms/rooms.controller.ts
 import { Controller, Get, Post, Body, Param, User } from "@palbase/backend";
 import type { UserT } from "@palbase/backend";
-import { roomService } from "../services/room.service.js";
-import { CreateRoomBody } from "../models/rooms/create.js";
-import type { RoomSchema } from "../models/rooms/shared.js";  // the return TYPE names the 200 schema
+import { RoomService } from "./room.service";
+import { CreateRoomBody } from "./dto/create";
+import { RoomSchema } from "./dto/shared";     // the return TYPE names the 200 schema
 
 // A controller does not import `Database`. Everything here is HTTP: validate the
 // body through a named schema, name the 200 shape as the return type, delegate.
 // Which rows, whose, in what order is the service's job — and the service is the
 // thing worth testing, because it is the thing that can be wrong.
 @Controller("/rooms")
-export default class RoomsController {
+export class RoomsController {
+  // The service arrives through the constructor; `rooms.module.ts` lists both.
+  constructor(private readonly rooms: RoomService) {}
+
   @Post("")
   create(@Body(CreateRoomBody) body: CreateRoomBody, @User() user: UserT): Promise<RoomSchema> {
-    return roomService.create(user.id, body);
+    return this.rooms.create(user.id, body);
   }
 
   @Get("/{id}")
   getOne(@Param("id") id: string): Promise<RoomSchema> {
-    return roomService.get(id);
+    return this.rooms.get(id);
   }
 }
 ```
@@ -572,13 +645,14 @@ export default class RoomsController {
 1. **The controller does not touch the database.** It delegates to a service, as
    above. A method here that reaches for `Database` has moved the logic into the
    layer that is hardest to test. (Export the class by NAME so its module can
-   list it in `controllers`; a class no module lists is refused at build with
-   `unowned class`. Nothing here is default-exported.)
+   import it and list it in `controllers`; a class no module lists is refused at
+   build with `unowned class`. Nothing here is default-exported.)
 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.)
+   (`: RoomSchema` on an `async` body is a `tsc` error). Both methods above hand
+   the service's promise straight back, so they need no `await` — but they still
+   return `Promise<RoomSchema>`. (A pure method that returns a literal and touches
+   no promise may stay synchronous.)
 
 ## Method decorators
 
@@ -604,8 +678,8 @@ a query string — complex search/filter endpoints that would otherwise be a
 
 ```ts
 @Query("/search")
-async search(@Body(SearchTodosBody) body: SearchTodosBody): Promise<TodoSchema[]> {
-  return todoService.search(body);
+search(@Body(SearchTodosBody) body: SearchTodosBody): Promise<TodoSchema[]> {
+  return this.todos.search(body);
 }
 ```
 
@@ -652,7 +726,7 @@ out. Resolution order (most specific wins):
 
 ```ts
 @Controller("/public", { auth: false })          // all routes default public
-export default class PublicController {
+export class PublicController {
   @Get("/open") open(): Info { ... }              // inherits → public
   @Get("/secret", { auth: true })                 // OVERRIDES → authed
   secret(@User() u: UserT): Secret { ... }
@@ -710,17 +784,20 @@ user.
 ```ts
 import { Controller, Get, Post, Body, User, OptionalUser } from "@palbase/backend";
 import type { UserT } from "@palbase/backend";
+import { TodoService } from "./todo.service";
 
 @Controller("/todos")                       // no auth option → every route needs a user
-export default class TodosController {
+export class TodosController {
+  constructor(private readonly todos: TodoService) {}
+
   @Post("")
   create(@Body(CreateTodoBody) body: CreateTodoBody, @User() user: UserT) {
-    return todoService.create(user.id, body.title);   // user is non-null — guaranteed
+    return this.todos.create(user.id, body.title);    // user is non-null — guaranteed
   }
 
   @Get("/featured", { auth: false })        // one public route
   featured(@OptionalUser() user: UserT | null) {
-    return todoService.featured(user?.id ?? null);    // may be null — handle it
+    return this.todos.featured(user?.id ?? null);     // may be null — handle it
   }
 }
 ```
@@ -728,11 +805,12 @@ export default class TodosController {
 ## What `@User()` gives you
 
 ```ts
-interface User {
+interface UserT {          // exported as `UserT`; the value name `User` is the decorator
   id: string;
   email?: string;          // absent for phone-only users
   emailVerified: boolean;
-  role: string;
+  role: string;            // the DATABASE role — always "authenticated" when signed in
+  roles: string[];         // your APPLICATION roles, read per request
   metadata: Record<string, unknown>;
   device: VerifiedDevice | null;
 }
@@ -741,35 +819,117 @@ interface User {
 Every field is **server-resolved** from the verified profile — nothing here is
 client-settable. `metadata` is your own `auth.users.metadata` (set through the
 admin users API); `role` is the **database** role RLS reads and is always
-`"authenticated"` for a signed-in user, so application roles belong in
-`metadata`, not there.
+`"authenticated"` for a signed-in user, so `user.role === "admin"` is always
+false and reads like a working check.
+
+Application roles are **`user.roles`** — a `string[]` resolved per request from
+`auth.user_roles`, the table `palbase roles` writes. They were once kept in
+`metadata`; they are not any more, and a role written there gates nothing.
+
+`emailVerified`, `email`, `role` and `metadata` come from the **verified token**,
+so they say what was true when it was minted: a user who confirms their address
+mid-session keeps reporting `false` until their next token. `roles` is the
+exception, and deliberately so — it is read from the table on every request, so
+a grant or a revocation lands immediately.
+
+## Roles and permissions
+
+Roles are **yours**. There is no built-in "admin": you declare the roles your
+app has, and what each one is allowed to do, from the command line —
 
-`emailVerified` is likewise read from the verified profile rather than a JWT
-claim: a claim is only true as of when the token was minted, so a user who
-verifies mid-session would keep reporting `false` until their token expired.
-Profile reads are cached for ~30 seconds, so a change shows up within that
-window, not on the very next request.
+```bash
+palbase roles create member    --default --permissions notes.create
+palbase roles create moderator           --permissions notes.create,notes.delete_any
+palbase roles assign usr_01a0… moderator
+```
+
+— and `palbase spec` brings them back as constants, so a misspelled permission
+is a compile error rather than a silent `403`:
+
+```ts
+import { Roles, Permissions } from "./palbe.gen";
+Roles.moderator            // 'moderator'
+Permissions.notesDeleteAny // 'notes.delete_any'
+```
 
-## Roles
+`--default` marks the one role every new sign-up receives, written in the same
+transaction as the user row.
 
-`auth: { role: "admin" }` gates on the caller's `metadata.role`:
+### The endpoint gate
 
 ```ts
-@Controller("/admin", { auth: { role: "admin" } })
-export default class AdminController {
-  @Get("/stats")
-  stats(): Promise<Stats> { … }   // only metadata.role === "admin" reaches here
+@Controller("/notes")
+export class NotesController {
+  // Anyone signed in.
+  @Get("") list(@User() user: UserT) { … }
+
+  // Only a caller holding the permission — the handler never runs otherwise.
+  @Delete("/{id}", { auth: { permission: "notes.delete_any" } })
+  remove(@Param("id") id: string) { … }
+
+  // Or by role, when the check really is "is this caller a moderator".
+  @Get("/queue", { auth: { role: "moderator" } })
+  queue() { … }
 }
 ```
 
-Not signed in → `401`. Signed in with a different (or missing) role → `403`. A
-role gate implies authentication, so the caller is resolved even on a route with
-no `@User()` parameter.
+Not signed in → `401`: declaring a permission or a role implies authentication,
+so the caller is resolved even on a route with no `@User()` parameter. Signed in
+without it → `403`, and the body names what was missing:
 
-The role is read from the verified profile, not from a claim baked into the
-token, so revoking it takes effect **within ~30 seconds** — the runtime caches a
-verified identity for that long — rather than whenever the token happens to
-expire.
+```json
+{ "error": "forbidden",
+  "error_description": "This endpoint requires the \"notes.delete_any\" permission" }
+```
+
+If you deliberately open a route with `auth: { required: false, permission: … }`,
+an unauthenticated caller reaches the gate and is refused with `403` — no
+identity means no roles, and the gate answers that rather than waving them
+through.
+
+**Authority is in no claim.** The gate reads `auth.user_roles` inside the
+transaction your handler is about to use — never a JWT claim — so
+`palbase roles revoke` closes the door on the **very next request**, with the
+same access token, no refresh and no re-login. Nothing is cached, and there is
+no epoch to bump.
+
+### The RLS half
+
+The gate decides whether the handler runs. It cannot decide which **rows** the
+handler sees — that is Postgres's job, and the same permissions are available
+there:
+
+```ts
+policies: () => [
+  policy("notes_owner").for("all").to("authenticated")
+    .using("user_id = (select auth.uid())")
+    .withCheck("user_id = (select auth.uid())"),
+
+  // Moderation. Permissive policies are OR'd, so these widen only.
+  policy("notes_moderate_read").for("select").to("authenticated")
+    .using("(select auth.has_permission('notes.delete_any'))"),
+  policy("notes_delete_any").for("delete").to("authenticated")
+    .using("(select auth.has_permission('notes.delete_any'))"),
+]
+```
+
+**The read policy is not optional, and leaving it out is the trap.**
+`DELETE … WHERE id = $1` has to FIND the row first, and that read is governed by
+the SELECT policies. With only the DELETE policy, a moderator holding the
+permission deletes **nothing**: the row is invisible to them, the `WHERE`
+matches nothing, and the statement answers `DELETE 0` — a silent no-op, not an
+error. The rule: **if a permission writes to somebody else's row, a SELECT
+policy has to show them that row.**
+
+Two helpers are available in every policy body:
+
+| helper | answers |
+|---|---|
+| `auth.has_permission(text)` | does the caller hold this permission, through any role they carry |
+| `auth.app_roles()` | the caller's roles as `text[]`, sorted, `{}` when none |
+
+Both take the caller from `auth.uid()` and accept no user id, so a policy cannot
+ask about somebody else.
 
 ## Email verification
 
@@ -817,7 +977,7 @@ publish(@User() user: UserT) {
   if (!user.emailVerified) {
     throw new Forbidden("Confirm your email address before publishing.");
   }
-  return postService.publish(user.id);
+  return this.posts.publish(user.id);
 }
 ```
 
@@ -893,8 +1053,9 @@ jobs, hooks, and webhooks all use the same import:
 import { Database } from "@palbase/backend";
 ```
 
-Only **middleware** still uses `ctx.db` (see [background.md](./background.md)
-and [events.md](./events.md) for worker/job/hook/webhook examples).
+There is no `ctx` and no `ctx.db` anywhere on a path that runs — every handler
+imports `Database` (see [background.md](./background.md) and
+[events.md](./events.md) for the job/hook/webhook examples).
 
 ## Typed by default — `Database.<şema>.<tablo>`
 
@@ -962,7 +1123,9 @@ await Database.public.crew_presence.findMany({
     AND: [sqlFragment`expires_at > now()`],
   },
 });
-``` The same filter language works for `updateMany`, `deleteMany`,
+```
+
+The same filter language works for `updateMany`, `deleteMany`,
 `count` and `search` — one language, so two spellings cannot drift apart. An
 empty `in` list means NO rows (written into the SQL as `false`), never a silent
 full scan.
@@ -1258,7 +1421,7 @@ filter object built from request input that happened to come back empty — is
 exactly the shape that must not silently succeed. `count()` with no filter IS
 allowed: counting is a read.
 
-### `Database.query` — raw SQL
+### `Database.$query` — raw SQL
 
 Use it for shapes the helpers do not cover (joins, aggregates, window functions).
 It runs in **the request's own transaction**, not a read-only one: a write inside
@@ -1283,7 +1446,7 @@ per row with a `23505` caught around each:
 
 ```ts
 await Database.$transaction((tx) => {
-  tx.tables.merchants.insertMany(rows, { onConflict: ["name"], action: "ignore" });
+  tx.public.merchants.insertMany(rows, { onConflict: ["name"], action: "ignore" });
   return null;
 });
 ```
@@ -1340,11 +1503,11 @@ middle, so nothing holds a database connection open while your code thinks.
 import { Database, NotFound } from "@palbase/backend";
 
 const { orderId } = await Database.$transaction((tx) => {
-  const order = tx.tables.orders
+  const order = tx.public.orders
     .insert({ amount: 1000, status: "pending" })
     .expectOne(new NotFound("order could not be created"));
 
-  tx.tables.order_items.insertMany(
+  tx.public.order_items.insertMany(
     cart.map((line) => ({ order_id: order.id, sku: line.sku })),
   );
 
@@ -1400,7 +1563,7 @@ filter plus an expectation — which is also stronger, because the check and the
 write are now the same statement and nothing can slip between them:
 
 ```ts
-tx.tables.invites
+tx.public.invites
   .updateWhere({ token, accepted_at: null }, { accepted_at: now() })
   .expectOne(new Conflict("invite already used", "invite_used"));
 ```
@@ -1440,7 +1603,7 @@ await Database.public.accounts.updateMany({
 
 // Inside a plan: the same expression, the same meaning.
 await Database.$transaction((tx) => {
-  tx.tables.accounts.updateWhere({ id: accountId }, { balance: decrement("5.00") });
+  tx.public.accounts.updateWhere({ id: accountId }, { balance: decrement("5.00") });
   return null;
 });
 ```
@@ -1546,7 +1709,8 @@ Sometimes you need to read or write **across all users** — an admin endpoint,
 background job that fans out notifications, a cleanup task. For that, call
 `Database.$asService()`. It returns a sibling client that runs as
 **`backend_service_role`** (the role that carries `BYPASSRLS`), exposing the
-exact same surface — `tables`, the raw string ops, and `transaction`:
+exact same surface — `public` (and every other schema), the `$`-prefixed raw ops,
+and `$transaction`:
 
 ```ts
 import { Database } from "@palbase/backend";
@@ -1555,32 +1719,32 @@ import { Database } from "@palbase/backend";
 const mine = await Database.public.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");
+const all  = await Database.$asService().public.todos.findMany({});
+const rows = await Database.$asService().$query("SELECT count(*) FROM todos");
 
 // A service-role transaction (the role is fixed for the whole plan):
-await Database.$asService().transaction((tx) => {
-  tx.tables.todos.updateWhere({ id }, { done: true });
+await Database.$asService().$transaction((tx) => {
+  tx.public.todos.updateWhere({ id }, { done: true });
   return null;
 });
 ```
 
 Guidelines:
 
-- **Be explicit.** Prefer the default `Database.*` and reach for `asService()`
+- **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 plan's role is fixed for the whole
+  `$asService()`, and `tx` never exposes it — a plan's role is fixed for the whole
   transaction. Use `Database.$transaction(...)` for an authenticated one and
-  `Database.$asService().transaction(...)` for a service-role one; you cannot mix
+  `Database.$asService().$transaction(...)` for a service-role one; you cannot mix
   enforced and bypassed operations inside a single plan.
 - **It is a second transaction, on a second connection.** It has to be: the
   Postgres role is bound once, when the transaction opens, so a sibling sharing
   the request's transaction would run as `backend_authenticated` and silently
   keep filtering. Three consequences worth knowing:
   - The request opens it at most once, however many times you call
-    `asService()`, and never at all if you don't use it.
+    `$asService()`, and never at all if you don't use it.
   - Both settle with the request — commit when your handler returns, roll back
     when it throws — but they settle as two transactions. A row written through
     one surface is **not visible** to the other until the request commits.
@@ -1614,9 +1778,10 @@ those values — never a dictionary, because a name in a dictionary key is a sec
 place the name is written, and a table built under a key does not yet know what
 to call itself when a sibling references it.
 
-Each table's only required field is `columns`; `rls` and `policies` enable
-[Row-Level Security](#row-level-security-rls), and `indexes` declares plain
-btree [indexes](#indexes).
+Each table's only required field is `columns`; `policies` (a callback — see
+[Row-Level Security](#row-level-security-rls)) declares the RLS rules, `rls`
+toggles enforcement (default `true`), and `indexes` declares plain btree
+[indexes](#indexes).
 
 ```ts
 import {
@@ -2042,14 +2207,28 @@ You do **not** wire anything per endpoint. Saving a file under `db/` regenerates
 of the schema, no generic, no cast:
 
 ```ts
-// services/room.service.ts — the layer that touches the database.
-import { Database } from "@palbase/backend";
+// modules/rooms/room.service.ts — the layer that touches the database.
+import { Database, Injectable } from "@palbase/backend";
+import type { Tables } from "@palbase/backend/env";
+
+type Room = Tables["rooms"]["row"];               // typed from your db/*.ts
 
-type RoomsTable = typeof Database.public.rooms;   // typed from your db/*.ts
+/** `Database.public.rooms` is a VALUE, and a dependency is named by its
+ * parameter's TYPE — so the seam is an `abstract class`, one table wide. */
+export abstract class RoomRepo {
+  abstract insert(row: { name: string }): Promise<Room>;
+}
 
+@Injectable()
+export class DbRoomRepo extends RoomRepo {
+  insert(row: { name: string }): Promise<Room> {
+    return Database.public.rooms.insert(row);     // typed: rooms.nope ← compile error
+  }
+}
+
+@Injectable()
 export class RoomService {
-  private readonly rooms: RoomsTable;
-  constructor(rooms: RoomsTable) { this.rooms = rooms; }
+  constructor(private readonly rooms: RoomRepo) {}
 
   async create(name: string) {
     const room = await this.rooms.insert({ name });
@@ -2057,41 +2236,48 @@ export class RoomService {
     // room.nope ← compile error
   }
 }
-
 ```
 
 ```ts
-// rooms.module.ts
+// modules/rooms/rooms.module.ts — the four lists that make these classes exist.
 import { Module, type Token } from "@palbase/backend";
-import { RoomsController } from "./controllers/rooms.controller.ts";
-import { RoomService } from "./services/room.service.ts";
+import { RoomsController } from "./rooms.controller.ts";
+import { DbRoomRepo, RoomService } from "./room.service.ts";
 
-@Module({ controllers: [RoomsController as Token], providers: [RoomService as Token] })
+@Module({
+  controllers: [RoomsController as Token],
+  providers: [RoomService as Token, DbRoomRepo as Token],
+  exports: [],
+  imports: [],
+})
 export class RoomsModule {}
 ```
 
 ```ts
-// controllers/rooms.controller.ts — HTTP only; no `Database` import here.
+// modules/rooms/rooms.controller.ts — HTTP only; no `Database` import here.
 import { Controller, Post, Body, z } from "@palbase/backend";
-import { RoomService } from "../services/room.service.js";
+import { RoomService } from "./room.service";
 
 const CreateRoomBody = z.object({ name: z.string() });
 const RoomOut = z.object({ id: z.string(), name: z.string() });
 
 @Controller("/rooms")
-export default class RoomsController {
+export class RoomsController {
+  constructor(private readonly rooms: RoomService) {}
+
   @Post("")
   // The return type names the 200 schema — `z.infer<typeof RoomOut>` works
   // inline, no separate `export type` needed.
   create(@Body(CreateRoomBody) body: z.infer<typeof CreateRoomBody>): Promise<z.infer<typeof RoomOut>> {
-    return roomService.create(body.name);
+    return this.rooms.create(body.name);
   }
 }
 ```
 
-`Database.public.<name>` exposes `insert`, `update(id, data)`, `delete(id)`,
-`findById(id)`, `findMany(query?)`. `Database.$transaction(fn)` yields a `tx`
-whose `tx.tables.<name>` is typed from the same schema, but carries plan
+`Database.public.<name>` exposes `insert(values)`,
+`update({ where: { id }, set })`, `delete(id)`, `findById(id)`,
+`findMany(query?)`. `Database.$transaction(fn)` yields a `tx`
+whose `tx.public.<name>` is typed from the same schema, but carries plan
 operations (`insert`/`insertMany`/`updateWhere`/`deleteWhere`/`select`) rather
 than awaited calls — see [database.md](./database.md#transactions). The raw
 string-keyed ops (`Database.$insert("rooms", …)`, `Database.$query(…)`) are still
@@ -2113,10 +2299,11 @@ 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.
+Add `policies` to a table — a **callback** returning the list, `policies: () =>
+[…]`, not a bare array. RLS defaults to `true`, and a non-empty `policies` forces
+it on regardless (a table with policies must have RLS enabled or the policies are
+inert). Write `rls: true` with no policies only as a deliberate deny-all
+intermediate step.
 
 ### The `policy()` builder
 
@@ -2175,6 +2362,34 @@ once per statement (an initPlan) instead of once per row. `auth.role()` and
 `auth.uid()` is `NULL`, so an `owner = (select auth.uid())` policy matches no
 rows.
 
+**`auth.has_permission('resource.action')`** answers whether the caller holds
+that permission through any role they carry, and **`auth.app_roles()`** returns
+their roles as a sorted `text[]` (`{}` when they hold none). Both read
+`auth.user_roles` — the table `palbase roles` writes — and both take the caller
+from `auth.uid()`, so a policy cannot ask about somebody else. A revoked role is
+gone from the very next statement; there is nothing cached.
+
+```ts
+policies: () => [
+  policy("notes_owner").for("all")
+    .using("user_id = (select auth.uid())")
+    .withCheck("user_id = (select auth.uid())"),
+
+  // Moderation. Permissive policies are OR'd, so these widen only.
+  policy("notes_moderate_read").for("select")
+    .using("(select auth.has_permission('notes.delete_any'))"),
+  policy("notes_delete_any").for("delete")
+    .using("(select auth.has_permission('notes.delete_any'))"),
+],
+```
+
+> **The read policy is not optional.** `DELETE … WHERE id = $1` has to FIND the
+> row first, and that read is governed by the SELECT policies. With only the
+> DELETE policy above, a moderator holding the permission deletes **nothing** —
+> the row is invisible to them, so the `WHERE` matches nothing and the statement
+> answers `DELETE 0`. No error, no log. If a permission writes to somebody
+> else's row, a SELECT policy has to show them that row.
+
 > 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, …).
@@ -2195,8 +2410,8 @@ export const todos = defineTable("todos", {
     done:       boolean().default(false),
     created_at: timestamp().defaultNow(),
   },
-  // `policies` non-empty ⇒ RLS is enabled + FORCEd automatically.
-  policies: [
+  // `policies` is a CALLBACK. Non-empty ⇒ RLS is enabled + FORCEd automatically.
+  policies: () => [
     // Read: a user sees only their own todos.
     policy("pb_todos_owner_select")
       .for("select")
@@ -2328,7 +2543,7 @@ Code and schema move at different speeds, so three things keep them together:
 ## Your schema change is not live anywhere you have not applied it
 
 The local stack and every Environment hold their own database, and editing
-Editing `db/*.ts` changes none of them: `palbase db apply` is what moves the local
+`db/*.ts` changes none of them: `palbase db apply` is what moves the local
 one, `palbase push` is what moves an Environment's. Until then the declaration is
 ahead of the tables.
 
@@ -2403,10 +2618,11 @@ existing data gets there.
 
 ## Row-Level Security
 
-Add `rls: true` + `policies: [policy(...)]` to a table in `db/*.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.public.*` access.
+Add `policies: () => [policy(...)]` to a table in `db/*.ts` — a CALLBACK, not an
+array — and the generated migration emits the `ENABLE ROW LEVEL SECURITY` +
+`CREATE POLICY` DDL. RLS is on by default, so `rls: true` is only worth writing
+as a deliberate deny-all with no policies. See [schema.md](./schema.md) for the
+column builders, the policy DSL, and typed `Database.public.*` access.
 
 ### Hand-writing a policy
 
@@ -2448,7 +2664,7 @@ no such safety net — write it the first time.
 **Two different things are called "services" here, and this page is the second
 one.** Read the first paragraph before searching this page for a layout rule.
 
-- **YOUR service layer** — `services/<name>.service.ts`, the plain classes your
+- **YOUR service layer** — `modules/<domain>/<name>.service.ts`, the `@Injectable()` classes your
   own business logic lives in. The scaffold ships one, and the contract is at
   the bottom of this page: [Your own service layer](#your-own-service-layer).
 - **THE service singletons** — the platform objects you import from
@@ -2471,9 +2687,26 @@ turns out to be empty — it fails at the import.
 a channel, but cannot subscribe (a stateless request can't hold a socket).
 Subscription lives on the client SDK (`pb.realtime`).
 
+`Auth` is available here for exactly one thing: **granting and revoking roles**.
+Signing in, signing up and session handling run on the client SDK — a backend
+handler never holds a user's credentials — but assignment is server work, so
+`assignRole`, `revokeRole` and `rolesOf` are on this side:
+
+```ts
+import { Auth } from "@palbase/backend";
+
+await Auth.assignRole(userId, "moderator");   // takes effect on the next request
+await Auth.revokeRole(userId, "moderator");   // and so does this
+const held = await Auth.rolesOf(userId);      // string[]
+```
+
+A role that does not exist throws `RoleNotDefined` naming it — declare it first
+with `palbase roles create`. A failed read throws rather than answering `[]`:
+"nobody could say" and "holds nothing" are different claims, and a handler that
+confuses them denies a user everything they hold.
+
 **Not available to backend handlers** (do not import them here): Functions, CMS,
-Links, Analytics, and Auth. Auth runs on the client SDK; the others are out of
-scope for backend endpoints.
+Links and Analytics — out of scope for backend endpoints.
 
 ## Cache
 
@@ -2603,7 +2836,7 @@ Writes mirror the `Database` / `Database.$asService()` model:
 - `Flags.setOverride(key, value)` (default) writes an override for the **current
   request user** — no `userId` argument, no admin power. It errors on an
   anonymous request (no signed-in user).
-- `Flags.asService()` returns the cross-user admin surface
+- `Flags.$asService()` returns the cross-user admin surface
   (`setOverrideForUser`, `setOverridesForUser`, `clearOverrideForUser`,
   `clearAllOverridesForUser`, `batchSetOverrides`) for writing overrides for an
   **arbitrary** user. Explicit and greppable, just like `Database.$asService()`.
@@ -2612,8 +2845,8 @@ Writes mirror the `Database` / `Database.$asService()` model:
 // Current request user — no userId needed:
 await Flags.setOverride("new-checkout", true);
 
-// Cross-user admin write — explicit target, via asService():
-await Flags.asService().setOverrideForUser("user_123", "new-checkout", true);
+// Cross-user admin write — explicit target, via $asService():
+await Flags.$asService().setOverrideForUser("user_123", "new-checkout", true);
 ```
 
 ## Realtime
@@ -2664,8 +2897,8 @@ to drive live chat, presence, dashboards, and other push features.
 ## Your own service layer
 
 The singletons above are what a service CALLS. This section is the layer that
-calls them — `services/<name>.service.ts`, which the scaffold ships a working
-example of (`services/note.service.ts` and the controller that uses it).
+calls them — `modules/<domain>/<name>.service.ts`, which the scaffold ships a working
+example of (`modules/notes/note.service.ts` and the controller that uses it).
 
 The contract is three rules, and the scaffold's own test enforces all three:
 
@@ -2680,7 +2913,7 @@ it.** Mark the class `@Injectable()` and name what it needs as ordinary
 constructor parameters:
 
 ```ts
-// services/note.service.ts
+// modules/notes/note.service.ts
 import { Database, Injectable } from "@palbase/backend";
 
 type NotesTable = typeof Database.public.notes;
@@ -2696,7 +2929,7 @@ export class NoteService {
 ```
 
 ```ts
-// services/report.service.ts — a service that depends on another service
+// modules/reports/report.service.ts — a service that depends on another service
 import { Injectable } from "@palbase/backend";
 import { NoteService } from "./note.service.ts";
 
@@ -2713,7 +2946,7 @@ export class ReportService {
 A controller asks the same way, and nothing wires it by hand:
 
 ```ts
-// controllers/notes.controller.ts
+// modules/notes/notes.controller.ts
 import { Controller, Get } from "@palbase/backend";
 import { NoteService } from "../services/note.service.ts";
 
@@ -2755,7 +2988,7 @@ never reaches the route table, the dispatcher or the OpenAPI document.
 ```ts
 // notes.module.ts — beside the domain it owns, not in a directory we name
 import { Module, type Token } from "@palbase/backend";
-import { NotesController } from "./controllers/notes.controller.ts";
+import { NotesController } from "./modules/notes/notes.controller.ts";
 import { NoteService } from "./services/note.service.ts";
 import { ReportService } from "./services/report.service.ts";
 
@@ -2808,7 +3041,7 @@ NoteService())` is ordinary TypeScript, and the container is not required for it
 to work.
 
 ```ts
-// services/note.service.test.ts — `npm test`, no database
+// modules/notes/note.service.test.ts — `npm test`, no database
 import { test } from "node:test";
 import assert from "node:assert/strict";
 
@@ -2872,9 +3105,8 @@ Palbase error envelope:
 { "error": "todo_not_found", "error_description": "No such todo", "status": 404, "request_id": "req_…" }
 ```
 
-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.
+Throw anywhere — in a controller method OR in a service. No `req`, no per-route
+error map: the runtime catches any thrown error class and emits the envelope.
 
 The runtime refuses some requests before a handler runs, and those refusals use
 the same envelope and the same codes as the classes below — so a client decodes
@@ -2933,10 +3165,11 @@ HttpError) … }` matches any of them.
 
 # Background Jobs
 
-`jobs/` is the background rail. A job uses the **singleton model** — the same
-imported service singletons as endpoints (`import { Database, Log } from
-"@palbase/backend"`). It does **not** receive a `req`; a small `meta` argument
-carries the non-service data (`env`, correlation ids).
+`jobs/` is the background rail, and it stays at the ROOT — a job is not part of
+any module. It reaches the platform services through the same import as everything
+else (`import { Database, Log } from "@palbase/backend"`). It does **not** receive
+a `req`; a small `meta` argument carries the non-service data (`env`, correlation
+ids).
 
 > **There is no queue.** `Queue.push` and `defineWorker` existed in earlier
 > versions and never ran: nothing consumed the queue, so a push returned a job id
@@ -2949,14 +3182,22 @@ carries the non-service data (`env`, correlation ids).
 
 ## Jobs (cron-scheduled)
 
-A job runs on a cron schedule. File lives under `jobs/` — the job's name is
-the file name, there is no `name` option.
+A job runs on a cron schedule. The file lives under `jobs/`, one class per file,
+`export default` required.
+
+**`name` is required and DECLARED.** It is the job's identity — the row the
+scheduler holds it under — so it is not taken from the file name any more:
+renaming the file would otherwise start a different job. Lowercase letters,
+digits and dashes.
 
 ```ts
 // jobs/cleanup.ts
 import { Database, Job, Log, type JobMeta } from "@palbase/backend";
 
-@Job({ schedule: "0 3 * * *", timeout: 120 }) // schedule: standard cron; timeout: optional, seconds
+// name: the scheduler's identity; schedule: standard 5-field cron;
+// timeout: optional seconds (default 30, ceiling 300);
+// retry: optional, how many times a FAILED run is retried (default 5, ceiling 10).
+@Job({ name: "cleanup", schedule: "0 3 * * *", timeout: 120 })
 export default class CleanupJob {
   async run(meta: JobMeta) {
     const expired = await Database.$findMany("sessions", { expired: true });
@@ -2975,53 +3216,87 @@ system-initiated).
 
 # Hooks & Webhooks
 
-Like 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`, `environmentId`; webhooks also
-get `requestId`).
+Like jobs, `hooks/` and `webhooks/` stay at the ROOT — neither is part of a
+module — and both reach the platform services through the same import as
+everything else (`import { Database, Log } from "@palbase/backend"`). They do
+**not** receive a `req`. A second `meta` argument carries the non-service data
+(`env`, `environmentId`; webhooks also get `requestId`).
 
 ## Hooks (platform events)
 
-React to auth, storage, and document events. Files live under `hooks/`. Builders
-are imported from `@palbase/backend`: `auth`, `storage`, `documents`.
+React to events this stack raises — auth, storage, documents. Files live under
+`hooks/`, one **default-exported class** per file, and the handlers are methods
+carrying a decorator. There are no builder functions to import.
+
+Two decorators, and the difference is whether the handler can stop the event:
+
+| | Where the event comes from | Can it block? |
+| --- | --- | --- |
+| `@Hook("before.…")` | this stack | **Yes** — `throw` cancels the operation |
+| `@On("after.…")` | this stack | No — a monitor; a throw reaches only the log |
+| `@Webhook` + `@On` | an OUTSIDE service | No — see the next section |
 
 ```ts
 // hooks/auth.ts
-import { auth, Database, Log } from "@palbase/backend";
-
-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,
-  });
-});
+import { Database, Deny, Hook, Log, On } from "@palbase/backend";
+import type { AuthHookEvent, HookMeta } from "@palbase/backend";
+
+export default class AuthHooks {
+  // The gate. A throw CANCELS the signup and the reason reaches the caller.
+  @Hook("before.user.create")
+  async gate(event: AuthHookEvent, _meta: HookMeta): Promise<void> {
+    if ((event.user?.email ?? "").endsWith("@blocked.test")) {
+      throw new Deny("this address is not accepted");
+    }
+  }
 
-export const onSignIn = auth.onSignIn(async (event, meta) => {
-  Log.info(`sign in: ${event.user.email} via ${event.provider}`);
-});
+  // The monitor. It runs after the fact, so a throw here is logged and the
+  // session is not un-created.
+  @On("after.login.failed")
+  async record(event: AuthHookEvent, meta: HookMeta): Promise<void> {
+    Log.info(`failed login for ${event.user?.email ?? "(no email)"} req=${meta.requestId}`);
+    await Database.$insert("login_failures", { email: event.user?.email ?? null });
+  }
+}
 ```
 
-`meta` shape: `{ env, environmentId }`. Environment variables are in
-`meta.env`; services come from the imported singletons.
+`Deny` is exported for exactly this: any throw denies, but `Deny` carries the
+reason deliberately instead of surfacing whatever a stray `TypeError` said. The
+engine is fail-closed — an unreachable hook denies — so keep a blocking handler
+narrow.
 
-Available hook builders: `auth.onUserCreated`, `auth.onSignIn`, `auth.onSignOut`,
-`auth.onPasswordReset`, `storage.onFileUploaded`, `storage.onFileDeleted`,
-`documents.onDocumentCreated`, `documents.onDocumentUpdated`,
-`documents.onDocumentDeleted`.
+`meta` shape: `{ env, environmentId, requestId? }`. Environment variables are in
+`meta.env`; the platform services (`Database`, `Log`, …) are imported as
+singletons, never passed in.
+
+> **Warning:** `auth`, `storage` and `documents` builder objects —
+> `auth.onUserCreated(handler)`, `storage.onFileUploaded(handler)` and friends —
+> **were removed in 26.0.0** and this page taught them until 33.0.0. They were
+> not merely renamed: nothing in the runtime or the bundler ever read the record
+> they returned, so a project that wrote one got a handler that was **never
+> called and no error said so**. The types went with them for the same reason —
+> `UserCreatedEvent` promised `user.role`, `user.metadata` and `user.createdAt`
+> and the auth engine sends none of the three. If you have such a file, the
+> import now fails to build, which is the point.
 
 ## Webhooks (inbound provider events)
 
 Receive and verify webhooks from third-party providers. Files live under
-`webhooks/` — the URL is `POST /webhooks/<file-name>` (e.g. `webhooks/stripe.ts`
-→ `POST /webhooks/stripe`); there is no `path` option.
+`webhooks/`, one class per file, `export default` required.
+
+**`name` is required and DECLARED.** It is the path segment the webhook is served
+at — `POST /webhooks/<name>` — so `name: "stripe"` answers at
+`POST /webhooks/stripe`. It is not taken from the file name any more: a PUBLIC
+URL, the one a sender is configured with, belongs beside the provider and the
+secret rather than in the file system. Lowercase letters, digits and dashes.
 
 ```ts
 // webhooks/stripe.ts
 import { Database, Log, On, Webhook, type WebhookMeta } from "@palbase/backend";
 
-@Webhook({ provider: "stripe", secret: { env: "STRIPE_WEBHOOK_SECRET" } }) // signing secret resolved from env
+// name: the path segment (POST /webhooks/stripe); secret: the signing secret,
+// resolved by the runtime from the named env var.
+@Webhook({ name: "stripe", provider: "stripe", secret: { env: "STRIPE_WEBHOOK_SECRET" } })
 export default class StripeWebhook {
   @On("checkout.session.completed")
   async checkoutCompleted(event: unknown, meta: WebhookMeta) {