@palbase/backend 32.0.0 → 33.0.1

package/docs/README.md

@@ -16,15 +16,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)).
 
@@ -58,7 +67,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).
@@ -73,12 +82,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(),
@@ -89,41 +98,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";
+
+/** 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>;
+}
 
-/** 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;
+@Injectable()
+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 {
-  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;
-  }
+  // 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;
@@ -133,68 +164,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", {
@@ -205,8 +242,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")
@@ -262,54 +299,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
 
@@ -328,5 +374,3 @@ 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>

package/docs/auth.md

@@ -8,17 +8,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
   }
 }
 ```
@@ -26,11 +29,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;
 }
@@ -39,35 +43,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.
 
-`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.
+## Roles and permissions
 
-## Roles
+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 —
 
-`auth: { role: "admin" }` gates on the caller's `metadata.role`:
+```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
-@Controller("/admin", { auth: { role: "admin" } })
-export default class AdminController {
-  @Get("/stats")
-  stats(): Promise<Stats> { … }   // only metadata.role === "admin" reaches here
+import { Roles, Permissions } from "./palbe.gen";
+Roles.moderator            // 'moderator'
+Permissions.notesDeleteAny // 'notes.delete_any'
+```
+
+`--default` marks the one role every new sign-up receives, written in the same
+transaction as the user row.
+
+### The endpoint gate
+
+```ts
+@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:
+
+```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 |
 
-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.
+Both take the caller from `auth.uid()` and accept no user id, so a policy cannot
+ask about somebody else.
 
 ## Email verification
 
@@ -115,7 +201,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);
 }
 ```
 

package/docs/background.md

@@ -1,9 +1,10 @@
 # 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
@@ -16,14 +17,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 });