@palbase/backend 24.2.0 → 25.0.0

package/docs/llms-full.txt

@@ -31,17 +31,26 @@ services/<name>.service.ts          # plain class + singleton — the real logic
 db/schema.ts                        # config-as-code Postgres schema (tables, columns, RLS) — auto-migrated on deploy
 ```
 
-The four folders above are the daily surface. These also exist (own docs, linked
-below): `resources/` (plain modules a controller imports — a client, a
-formatter, anything shared), `seeds/` (seed data), `jobs/` (background — [background.md](./background.md)),
-`webhooks/` + `hooks/` (events — [events.md](./events.md)), `middleware/`.
+The four folders above are the daily surface. Three more 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)).
+
+There is no `resources/`, no `seeds/` and no working `middleware/`. `middleware/`
+is discovered by nothing and the engine has no middleware pipeline: code written
+against it deploys, never runs, and nothing says so. Put cross-cutting work in a
+service the controllers call.
 
 ### The 7 rules (checklist)
 
-1. **`export default <ControllerClass>` is REQUIRED.** Every `controllers/*.controller.ts`
-   must default-export its `@Controller` class, or the deploy FAILS with a
-   "not a @Controller / non-controller export" error. Either `export default class X {}`
-   or a trailing `export default X;` — both work.
+1. **A controller needs NO export at all.** `@Controller` records the class into a
+   `globalThis` registry as it decorates it, and the bundler imports the file for
+   that side effect alone — the shipped scaffold's own `HealthController` and
+   `NotesController` are not exported. Exporting is harmless and reads well, so
+   these examples do it; it is not a requirement. (`export default` **is**
+   required for `jobs/`, `webhooks/`, `hooks/` and `db/public.ts`, one class per
+   file.) What IS fatal is a `@Controller` class that collected zero routes —
+   usually `experimentalDecorators` missing from `tsconfig.json`.
 2. **Methods that call a service are `async` and return `Promise<T>`.** Services
    `await Database`, so they return promises; a sync return type on an async body
    is a tsc error. Annotate `: Promise<TodoSchema>`, not `: TodoSchema`, whenever
@@ -70,7 +79,7 @@ formatter, anything shared), `seeds/` (seed data), `jobs/` (background — [back
 
 > **Never** emit `defineController`, `defineHandler`, `defineEndpoint`, `route.get(...)`,
 > `req.input`, `req.params`, or `req.errors` — those are the removed legacy model
-> and will not compile against `@palbase/backend` 4.
+> and will not compile against `@palbase/backend` 25.
 
 ### Complete CRUD example (copy-pasteable, compiles)
 
@@ -97,25 +106,44 @@ export type CreateTodoBody = z.infer<typeof CreateTodoBody>;
 import { Database, NotFound } from "@palbase/backend";
 import type { TodoSchema } from "../models/todos/shared.js";
 
+/** 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.tables.todos;
+
 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;
+  }
+
   list(userId: string): Promise<TodoSchema[]> {
-    return Database.tables.todos.findMany({ user_id: userId });
+    return this.todos.findMany({ user_id: userId });
   }
   create(userId: string, title: string): Promise<TodoSchema> {
-    return Database.tables.todos.insert({ user_id: userId, title });
+    return this.todos.insert({ user_id: userId, title });
   }
   async get(userId: string, id: string): Promise<TodoSchema> {
-    const t = await Database.tables.todos.findById(id);
+    const t = await this.todos.findById(id);
     if (!t || t.user_id !== userId) throw new NotFound("No todo with that id");
     return t;
   }
   async remove(userId: string, id: string): Promise<void> {
-    const t = await Database.tables.todos.findById(id);
-    if (!t || t.user_id !== userId) throw new NotFound("No todo with that id");
-    await Database.tables.todos.delete(id);
+    await this.get(userId, id);
+    await this.todos.delete(id);
   }
 }
-export const todoService = new TodoService();
+
+/** The wired instance. Controllers import THIS, never the class. It is also the
+ * ONLY supported way to hold a dependency: a controller, job, hook or webhook is
+ * constructed with no arguments, and one that declares a constructor parameter
+ * is refused at build with the class named. */
+export const todoService = new TodoService(Database.tables.todos);
 ```
 
 ```ts
@@ -127,31 +155,33 @@ import { TodoSchema } from "../models/todos/shared.js";
 import { CreateTodoBody } from "../models/todos/create.js";
 
 @Controller("/todos")                                  // secure-by-default; { auth: false } opts the whole controller out
-export class TodosController {
-  private todos = todoService;
+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 at build with the class named.
 
   @Get("")                                             // GET /todos → operationId todos.list
   async list(@User() user: UserT): Promise<TodoSchema[]> {  // return type → 200 response schema
-    return this.todos.list(user.id);
+    return todoService.list(user.id);
   }
 
   @Post("")                                            // POST /todos → todos.create
   async create(@Body(CreateTodoBody) body: CreateTodoBody, @User() user: UserT): Promise<TodoSchema> {
-    return this.todos.create(user.id, body.title);
+    return todoService.create(user.id, body.title);
   }
 
   @Get("/{id}")                                        // GET /todos/{id} → todos.get
   async get(@Param("id") id: string, @User() user: UserT): Promise<TodoSchema> {
-    return this.todos.get(user.id, id);
+    return todoService.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 this.todos.remove(user.id, id);
+    await todoService.remove(user.id, id);
   }
 }
-
-export default TodosController;                         // REQUIRED — the runtime loads the default export
+// No export is needed at all — @Controller registered the class as it decorated
+// it. `export default` here is style, not a requirement.
 ```
 
 ```ts
@@ -238,7 +268,10 @@ The **only difference** is the trigger argument:
 | **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** |
+
+`defineMiddleware` is still exported and takes `(ctx, next)`, but **no bundler
+reads a `middleware/` directory and the engine never calls one** — there is no
+`ctx` anywhere on a path that runs. Every handler above imports its services.
 
 `meta` carries non-service data: `env` (Environment variables),
 `environmentId`, and for webhooks `requestId`. Services always come from
@@ -255,16 +288,16 @@ my-backend/
 ├── models/<ctrl>/<ep>.ts   # zod schemas, folder per controller, file per endpoint
 │   └── hello/greet.ts      # GreetQuery + HelloResponse (zod value + z.infer type)
 ├── services/               # plain classes/singletons your controllers call
-├── db/schema.ts            # table definitions (optional, enables typed DB)
-├── db/migrations/          # explicit SQL migrations for type changes (optional)
-├── resources/              # external connections, set up once at boot (optional)
-├── seeds/                  # seed data (optional)
+├── 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)
-└── middleware/             # cross-cutting request middleware (optional)
+└── webhooks/               # inbound provider webhooks (optional)
 ```
 
+There is **no `db/migrations/`**. Nothing generates a migration file, nothing
+commits one and nothing replays one: `db/schema.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).
@@ -493,35 +526,38 @@ imported singletons (see [services.md](./services.md)).
 
 ```ts
 // controllers/rooms.controller.ts
-import { Controller, Get, Post, Body, Param, User, NotFound, Database } from "@palbase/backend";
+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
 
+// 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 {
   @Post("")
-  async create(@Body(CreateRoomBody) body: CreateRoomBody, @User() user: UserT): Promise<RoomSchema> {
-    const room = await Database.insert("rooms", { name: body.name, capacity: body.capacity ?? null });
-    return { id: room.id as string, name: room.name as string, capacity: (room.capacity as number) ?? null };
+  create(@Body(CreateRoomBody) body: CreateRoomBody, @User() user: UserT): Promise<RoomSchema> {
+    return roomService.create(user.id, body);
   }
 
   @Get("/{id}")
-  async getOne(@Param("id") id: string): Promise<RoomSchema> {
-    const room = await Database.findById("rooms", id);
-    if (!room) throw new NotFound("Room does not exist", "room_not_found");
-    return { id: room.id as string, name: room.name as string, capacity: (room.capacity as number) ?? null };
+  getOne(@Param("id") id: string): Promise<RoomSchema> {
+    return roomService.get(id);
   }
 }
 ```
 
 **Two non-negotiables** (the most common codegen mistakes):
 
-1. **`export default <Controller>` is REQUIRED.** Above it is
-   `export default class RoomsController`; the trailing form `export class
-   RoomsController {…}` + `export default RoomsController;` is equivalent. Without
-   a default export the deploy aborts with a "not a @Controller / non-controller
-   export" error — the runtime loads the file's default export.
+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. (An export is not required at all: `@Controller`
+   records the class as it decorates it, and importing the file IS the
+   registration — the shipped scaffold's own controllers are not exported.
+   `export default` here is style.)
 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
@@ -631,23 +667,17 @@ throw new PalError(418, "teapot", "custom");  // → custom status/code
 
 See [errors.md](./errors.md) for the full set + the wire envelope shape.
 
-## Middleware
+## There is no middleware
 
-A middleware wraps a request. Define one in `middleware/<name>.ts`:
+`defineMiddleware(async (ctx, next) => { … })` is still exported and still
+type-checks, but **nothing mounts a `middleware/` directory and the engine has no
+middleware pipeline** — a handler written against it deploys, never runs, and
+nothing reports it. There is no `ctx` object anywhere on a path that executes, so
+treat the export as a leftover rather than a seam.
 
-```ts
-// middleware/logger.ts
-import { defineMiddleware } from "@palbase/backend";
-
-export default defineMiddleware(async (ctx, next) => {
-  ctx.log.info(`start ${ctx.requestId}`);
-  await next();
-  ctx.log.info(`done ${ctx.requestId}`);
-});
-```
-
-The middleware handler receives `(ctx, next)` — call `await next()` to run the
-rest of the chain (other middleware, then the endpoint method).
+Cross-cutting work goes in a service the controllers call, and the route concerns
+that used to live in a wrapper are route options instead: `auth` on `@Controller`
+or the method decorator, and `rateLimit: { max, window }` per route.
 
 
 
@@ -1172,51 +1202,109 @@ Guidelines:
 
 # Schema & typed database access
 
-Declare your tables in `db/schema.ts` with `defineSchema`. This drives
+Declare your tables under `db/`, **one file per schema**: `db/public.ts` is the
+schema Palbase expects to find, `db/billing.ts` declares a second one. Each file
+default-exports a `defineSchema("<name>", { tables })` call. That drives
 [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.
 
+> Coming from a single `db/schema.ts` with tables declared inline? That layout is
+> gone, and a push says so by name. The migration guide at
+> `/docs/backend/schema-migration` walks the four changes with before/after code.
+
 ## Defining a schema
 
-The table NAME comes from the object key under `tables`. Each table value is an
-object whose only required field is `columns`; `rls` and `policies` enable
+A table is declared with `defineTable("<name>", { … })` and is a **value that
+knows its own name**. `defineSchema` takes the schema's name and an ARRAY of
+those values — never a dictionary, because a name in a dictionary key is a second
+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).
 
 ```ts
 import {
-  defineSchema,
-  uuid, text, integer, boolean, timestamp, jsonb, enumType,
+  defineSchema, defineTable,
+  uuid, text, integer, boolean, timestamp, jsonb, enumType, ownedByUser,
 } from "@palbase/backend";
 
-export default defineSchema({
-  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(),
-      },
-    },
+export const rooms = defineTable("rooms", {
+  columns: {
+    id: uuid().primaryKey().defaultRandom(),
+    name: text().notNull(),
+    capacity: integer().nullable(),
+    is_active: boolean().default(true),
+    created_at: timestamp().defaultNow(),
+  },
+});
+
+export const sessions = defineTable("sessions", {
+  columns: {
+    id: uuid().primaryKey().defaultRandom(),
+    room_id: uuid().references(() => rooms.id).onDelete("cascade"),
+    user_id: ownedByUser(),
+    data: jsonb().nullable(),
+    started_at: timestamp().defaultNow(),
+  },
+});
+
+export const orders = defineTable("orders", {
+  columns: {
+    id: uuid().primaryKey().defaultRandom(),
+    status: enumType("order_status", ["pending", "paid", "shipped", "cancelled"]),
+    amount: integer().notNull(),
+  },
+});
+
+export default defineSchema("public", {
+  tables: [rooms, sessions, orders],
+});
+```
+
+A `defineTable` value **is its columns** — `rooms.id` is the `id` builder, which
+is what makes `references(() => rooms.id)` an ordinary expression. The table's own
+metadata hangs off a symbol rather than a plain field, so a column may be called
+`name`, `columns`, `rls` or `indexes` without shadowing the table's identity.
+
+### One file per schema, and `exposed`
+
+The schema name comes from the declaration; the file name must agree with it. A
+`db/billing.ts` declaring `defineSchema("accounts", …)` is refused at push with
+both names in the error.
+
+`exposed` decides whether a schema is served over `/v1/db`, and the default is
+NOT uniform: **`public` defaults to `true`**, every other schema to `false`. The
+asymmetry is deliberate — `public` is reachable today and stays reachable, because
+a uniform default would silently 404 every existing project's `/v1/db` traffic on
+upgrade, while a schema you add later is not on the internet just because you
+declared it.
+
+```ts
+// db/public.ts — reachable, and you write nothing to get that
+export default defineSchema("public", { tables: [rooms, sessions] });
+
+// db/billing.ts — declared and typed, but not reachable from a client
+export default defineSchema("billing", { tables: [invoices] });
+```
+
+Write the field only to go against the grain — `exposed: false` closes `public`,
+`exposed: true` opens a second schema. Server-side `Database.*` ignores it either
+way: your controllers, jobs and hooks read every schema you declared.
+
+A foreign key may cross schemas: import the table binding and point at it.
+
+```ts
+// db/billing.ts
+import { lists } from "./public";
+
+export const invoices = defineTable("invoices", {
+  columns: {
+    id: uuid().primaryKey().defaultRandom(),
+    list_id: uuid().references(() => lists.id),
+    amount: numeric(),
   },
 });
 ```
@@ -1235,27 +1323,202 @@ export default defineSchema({
 
 Chainable modifiers: `.primaryKey()`, `.notNull()` (default), `.nullable()`,
 `.default(value)`, `.defaultRandom()` (uuid → `gen_random_uuid()`),
-`.defaultNow()` (timestamp → `now()`), `.references(table, column)`,
-`.onDelete("cascade" | "set null" | "restrict" | "no action")`.
+`.defaultNow()` (timestamp → `now()`), `.references(() => table.column, opts?)`,
+`.selfReferences("column", opts?)`,
+`.onDelete("cascade" | "set null" | "restrict" | "no action")`, `.ignored()`.
+
+## Foreign keys
+
+The target of `references` is a **thunk**, not a direct reference. The callback is
+invoked inside `defineSchema`, where every binding exists and every table already
+knows its name — which is what makes a cycle expressible at all: in `x → y, y → x`
+the second table does not exist yet when the first is built.
+
+```ts
+list_id: uuid().references(() => lists.id),
+```
+
+**Pointing at this same table** takes no thunk and no annotation — the target
+table is the one being declared, so there is nothing to defer:
+
+```ts
+parent_id: uuid().nullable().selfReferences("id"),
+```
+
+Naming a column the table does not have is refused where you declare it.
+
+**Two tables that point at each other** need an explicit return type on ONE side,
+and one is enough — measured. Without it TypeScript chases its own tail (TS7022):
+
+```ts
+import { type AnyColumn } from "@palbase/backend";
+
+export const users = defineTable("users", {
+  columns: {
+    id: uuid().primaryKey().defaultRandom(),
+    primary_org_id: uuid().nullable().references((): AnyColumn => orgs.id),
+  },
+});
+
+export const orgs = defineTable("orgs", {
+  columns: {
+    id: uuid().primaryKey().defaultRandom(),
+    owner_id: uuid().nullable().references(() => users.id),
+  },
+});
+```
+
+**Two foreign keys to the same table** would derive the same relation name from
+their columns, so name one of them:
+
+```ts
+billing_address_id:  uuid().references(() => addresses.id, { as: "billing_address" }),
+shipping_address_id: uuid().references(() => addresses.id, { as: "shipping_address" }),
+```
+
+## Rows that belong to a user
+
+There is no `public.users` table: auth users live in the `auth` schema of the same
+Postgres. Three column factories declare a real foreign key onto it. They are
+factories rather than chain methods because the column type, its nullability and
+its `ON DELETE` are part of what each one MEANS — so they cannot be written wrong.
+
+```ts
+user_id:    ownedByUser(),                              // text, NOT NULL, ON DELETE CASCADE
+edited_by:  userRef({ onDelete: "set null" }).nullable(),
+device_id:  installationRef({ onDelete: "cascade" }),
+```
+
+| | `ownedByUser()` | `userRef({ onDelete })` | `installationRef({ onDelete })` |
+|---|---|---|---|
+| References | `auth.users(id)` | `auth.users(id)` | `auth.installations(id)` |
+| Means | the row **belongs to** that user | the row **points at** a user | the row is scoped to an app install |
+| `ON DELETE` | `cascade`, no argument | required: `cascade` / `set null` | required: `cascade` / `set null` |
+| Account erasure follows it | yes | no | no |
+| Per table | **at most one** | unlimited | unlimited |
+
+`ownedByUser()` takes no `onDelete` because there is only one correct answer:
+ownership is what account erasure walks, so a row owned by an account has to go
+when the account does. `"set null"` on a `userRef` needs a `.nullable()` column.
+
+**One `ownedByUser()` per table, enforced.** Two on one table are refused at push
+with both column names in the error. The rule exists because the alternative was
+worse than a refusal: when several columns could reference `auth.users`, the owner
+was whichever came FIRST IN DECLARATION ORDER — so moving a `created_by` above a
+`user_id` silently changed which rows an account deletion took with it.
+
+An installation reference is **not** ownership. A user-owned row still needs its
+own `ownedByUser()`, or erasing the account leaves it behind.
+
+## Removing a column
+
+A deploy applies the schema while the PREVIOUS release is still answering requests, so
+dropping a column that release still names breaks it the instant the change lands. The
+gate therefore refuses the drop — and until now it refused every drop, with no way
+through: deleting the code that used the column changed nothing, because the gate never
+read your code.
+
+`.ignored()` is how you tell it. The mark is a PROMISE about the release that carries
+it: **this release neither reads nor writes this column, and never names it in a filter,
+a sort or a SET.**
+
+Removing a column is therefore two deploys:
+
+```ts
+// 1. Mark it. The column stays; nothing breaks; no DDL is produced.
+const notes = defineTable("notes", {
+  columns: { id: uuid().primaryKey(), old_body: text().ignored() },
+});
+export default defineSchema("public", { tables: [notes] });
+```
+
+```ts
+// 2. Ship that. Then delete the column and ship again — this time the gate passes,
+//    because the release now serving promised it does not name the column.
+const notes = defineTable("notes", { columns: { id: uuid().primaryKey() } });
+export default defineSchema("public", { tables: [notes] });
+```
+
+`palbase db plan` tells you which step you are on before you push. Locally,
+`palbase db apply` is not restricted — local is where you experiment, and there is no
+traffic to protect.
+
+### When you cannot wait two deploys
+
+There is an escape, and it is deliberately loud:
+
+```
+palbase push --accept-breaking
+```
+
+It opens the gate for one push. Use it when the running release is ALREADY broken and
+the fix is the very change the gate refuses — an incident, not an inconvenience. Outside
+that, two deploys cost less than the one this can break.
+
+It is not silent, and that is the whole design: the push prints the consents it is
+sending, and the server records a `BREAK-GLASS` line naming the digest that was serving
+and every object the gate had refused. So the decision has an author and a time, and
+whoever asks later why a column disappeared finds the answer instead of a normal-looking
+push.
+
+Two things it will not do. It does not apply to a cloud push — `--accept-breaking` there
+is refused by name rather than ignored, because the gate needs to know what is serving
+and only a linked checkout can tell it. And it does not skip the data-loss consent:
+`--approve` is a separate question about erasing rows, and answering one does not answer
+the other.
+
+The word is `ignored` and not `deprecated` on purpose: deprecation is defined, in
+RFC 9745 and in the GraphQL spec alike, as changing NO behaviour. This changes what a
+deploy will accept.
+
+**What the mark cannot do.** No static mark can PROVE your code does not name the
+column — that question is only answerable from traffic. `.ignored()` is your promise.
+What the gate adds is that it reads the promise from the release that is ACTUALLY
+SERVING, not from the file in front of you.
+
+## Renaming an enum value
+
+There is no `renamedFrom` for enum values, and the reason is measured rather than
+stylistic: on PostgreSQL 16, `ALTER TYPE … RENAME VALUE` is an **atomic cutover**. While
+the rename is uncommitted a writer using the OLD label succeeds and one using the NEW
+label fails; at commit that flips. The two names are never both valid, so there is no
+window in which a running release can be migrated across — the instant the rename
+commits, that release's writes fail with `invalid input value for enum`.
+
+Add a value instead, and let the old one die:
+
+```sql
+-- 1. Add the new label. This IS safe while the previous release serves.
+--    (Declare it in db/public.ts; the rail emits ALTER TYPE … ADD VALUE.)
+-- 2. Move the data:
+UPDATE posts SET status = 'review' WHERE status = 'onay';
+-- 3. Stop naming the old value in the next release.
+```
+
+Postgres cannot delete an enum label, so `'onay'` stays — unused and harmless.
+
+**One trap, measured.** A rename is followed automatically by everything Postgres stores
+as a parse tree: column defaults, enum-typed CHECKs, views, materialized-view
+definitions, partial-index predicates, RLS policies, partition bounds, generated columns.
+It is NOT followed by anything stored as TEXT. A constraint written
+`CHECK (status::text = 'onay')` keeps its text after a rename and now checks a label that
+no longer exists — a dead constraint, silently. Measured on PG16: an INSERT the check
+used to reject passed after the rename.
 
 ## Indexes
 
 `indexes` declares plain (non-unique) btree indexes over an ordered column list:
 
 ```ts
-export default defineSchema({
-  tables: {
-    sessions: {
-      columns: {
-        id:         uuid().primaryKey().defaultRandom(),
-        room_id:    uuid().notNull().references("rooms", "id"),
-        started_at: timestamp().defaultNow(),
-      },
-      indexes: [
-        { name: "sessions_room_started_idx", columns: ["room_id", "started_at"] },
-      ],
-    },
+export const sessions = defineTable("sessions", {
+  columns: {
+    id:         uuid().primaryKey().defaultRandom(),
+    room_id:    uuid().references(() => rooms.id),
+    started_at: timestamp().defaultNow(),
   },
+  indexes: [
+    { name: "sessions_room_started_idx", columns: ["room_id", "started_at"] },
+  ],
 });
 ```
 
@@ -1267,7 +1530,7 @@ name and every column are identifier-validated before any SQL is built.
 knowing before you name an index:
 
 - An index that exists in the database but is not in `indexes` is never dropped.
-  `db/schema.ts` does not own the database's indexes; it only adds the ones it
+  Your schema file does not own the database's indexes; it only adds the ones it
   names.
 - Removing an entry from `indexes` therefore does **not** drop the index. Drop it
   in an explicit [migration](./migrations.md).
@@ -1293,10 +1556,9 @@ nothing. Rather than ship a half-working partial-index path, the typed field
 stays columns-only and `raw()` carries the rest:
 
 ```ts
-import { defineSchema, raw, uuid, text, timestamp } from "@palbase/backend";
+import { defineTable, raw, uuid, text, timestamp } from "@palbase/backend";
 
-// …
-orders: {
+export const orders = defineTable("orders", {
   columns: {
     id:         uuid().primaryKey().defaultRandom(),
     status:     text().notNull(),
@@ -1309,7 +1571,7 @@ orders: {
       { down: "DROP INDEX IF EXISTS orders_pending_idx" },
     ),
   ],
-},
+});
 ```
 
 `raw()`'s `up` is emitted verbatim on the privileged DDL connection and, like
@@ -1319,12 +1581,34 @@ and an index is not one.
 
 ## Typed DB access — by default
 
-You do **not** wire anything per endpoint. Saving `db/schema.ts` regenerates
+You do **not** wire anything per endpoint. Saving a file under `db/` regenerates
 `palbase-env.d.ts`, which types `Database.tables.<name>` everywhere — no import
 of the schema, no generic, no cast:
 
 ```ts
-import { Controller, Post, Body, Database, z } from "@palbase/backend";
+// services/room.service.ts — the layer that touches the database.
+import { Database } from "@palbase/backend";
+
+type RoomsTable = typeof Database.tables.rooms;   // typed from db/schema.ts
+
+export class RoomService {
+  private readonly rooms: RoomsTable;
+  constructor(rooms: RoomsTable) { this.rooms = rooms; }
+
+  async create(name: string) {
+    const room = await this.rooms.insert({ name });
+    return { id: room.id, name: room.name };      // room.id: string ✓
+    // room.nope ← compile error
+  }
+}
+
+export const roomService = new RoomService(Database.tables.rooms);
+```
+
+```ts
+// controllers/rooms.controller.ts — HTTP only; no `Database` import here.
+import { Controller, Post, Body, z } from "@palbase/backend";
+import { roomService } from "../services/room.service.js";
 
 const CreateRoomBody = z.object({ name: z.string() });
 const RoomOut = z.object({ id: z.string(), name: z.string() });
@@ -1334,10 +1618,8 @@ export default class RoomsController {
   @Post("")
   // The return type names the 200 schema — `z.infer<typeof RoomOut>` works
   // inline, no separate `export type` needed.
-  async create(@Body(CreateRoomBody) body: z.infer<typeof CreateRoomBody>): Promise<z.infer<typeof RoomOut>> {
-    const room = await Database.tables.rooms.insert({ name: body.name });
-    return { id: room.id, name: room.name }; // room.id: string ✓
-    // room.nope ← compile error
+  create(@Body(CreateRoomBody) body: z.infer<typeof CreateRoomBody>): Promise<z.infer<typeof RoomOut>> {
+    return roomService.create(body.name);
   }
 }
 ```
@@ -1435,36 +1717,37 @@ rows.
 ### 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())"),
+import {
+  defineSchema, defineTable, policy, ownedByUser,
+  uuid, text, boolean, timestamp,
+} from "@palbase/backend";
 
-        // 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())"),
-      ],
-    },
+export const todos = defineTable("todos", {
+  columns: {
+    id:         uuid().primaryKey().defaultRandom(),
+    owner:      ownedByUser(),           // text FK onto auth.users(id), NOT NULL, CASCADE
+    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())"),
+  ],
 });
+
+export default defineSchema("public", { tables: [todos] });
 ```
 
 With this in place, `await Database.tables.todos.findMany({})` returns only the
@@ -1486,7 +1769,6 @@ so they apply without the `acceptDataLoss` confirmation that column drops need.
 
 
 
-
 <!-- ===== migrations.md ===== -->
 
 # Migrations
@@ -1969,16 +2251,51 @@ stand-in and never needs a database.
 
 ```ts
 // services/note.service.test.ts — `npm test`, no database
-import assert from "node:assert/strict";
 import { test } from "node:test";
+import assert from "node:assert/strict";
+
 import { NoteService } from "./note.service.ts";
 
-test("list filters by owner", async () => {
+// WHY THIS TEST NEEDS NO DATABASE
+//
+// `NoteService` is handed the table it works on rather than reaching for the
+// singleton itself. That constructor is the seam: a stand-in goes in here, and
+// the logic — which rows, whose, in what order — is exercised without a
+// database. Test your own services the same way.
+//
+// When you want the whole database surface instead of one table, `fakeDatabase()`
+// from `@palbase/backend/test` is the stand-in.
+//
+// Node's ESM resolver wants the extension on a relative import inside a test
+// (`./note.service.ts`); this scaffold's `tsconfig.json` allows it.
+
+test("list asks only for the caller's notes", async () => {
   const seen: unknown[] = [];
-  const fake = { findMany: async (q: unknown) => (seen.push(q), []) };
-  await new NoteService(fake as never).list("u_1");
+  const notes = {
+    findMany: async (where: unknown) => {
+      seen.push(where);
+      return [];
+    },
+  };
+
+  await new NoteService(notes as never).list("u_1");
+
   assert.deepEqual(seen, [{ user_id: "u_1" }]);
 });
+
+test("create writes ownership from the argument, never from the body", async () => {
+  const written: unknown[] = [];
+  const notes = {
+    insert: async (row: unknown) => {
+      written.push(row);
+      return row;
+    },
+  };
+
+  await new NoteService(notes as never).create("u_1", "hello");
+
+  assert.deepEqual(written, [{ user_id: "u_1", body: "hello" }]);
+});
 ```
 
 Node's ESM resolver wants the extension on a relative import inside a test