@palbase/backend 25.0.0 → 25.0.2

package/dist/{registry-CgJvDYUW.d.cts → registry-CC0WBQq6.d.cts}

@@ -1,4 +1,4 @@
-import { A as AuthSpec, R as RateLimitConfig } from './endpoint-BSGw1pTu.cjs';
+import { A as AuthSpec, R as RateLimitConfig } from './endpoint-DYHMo6cC.cjs';
 import { ZodTypeAny } from 'zod';
 import { PalbaseBucketName } from './stack.cjs';
 

package/dist/{registry-B8pld3fj.d.ts → registry-dZZ5JKYg.d.ts}

@@ -1,4 +1,4 @@
-import { A as AuthSpec, R as RateLimitConfig } from './endpoint-DMwJjEHQ.js';
+import { A as AuthSpec, R as RateLimitConfig } from './endpoint-CTEHhb7A.js';
 import { ZodTypeAny } from 'zod';
 import { PalbaseBucketName } from './stack.js';
 

package/dist/test/index.d.cts

@@ -1,4 +1,4 @@
-import { D as DBClient } from '../endpoint-BSGw1pTu.cjs';
+import { D as DBClient } from '../endpoint-DYHMo6cC.cjs';
 import 'zod';
 import '../stack.cjs';
 

package/dist/test/index.d.ts

@@ -1,4 +1,4 @@
-import { D as DBClient } from '../endpoint-DMwJjEHQ.js';
+import { D as DBClient } from '../endpoint-CTEHhb7A.js';
 import 'zod';
 import '../stack.js';
 

package/docs/README.md

@@ -20,7 +20,7 @@ deploy gate or the TypeScript compile.
 controllers/<name>.controller.ts   # @Controller class + @Get/@Post/… route methods (the API surface)
 models/<controller>/<endpoint>.ts   # zod schemas — one folder per controller, one file per endpoint (+ shared.ts)
 services/<name>.service.ts          # plain class + singleton — the real logic (controllers stay thin)
-db/schema.ts                        # config-as-code Postgres schema (tables, columns, RLS) — auto-migrated on deploy
+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,
@@ -40,7 +40,7 @@ service the controllers call.
    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
+   required for `jobs/`, `webhooks/`, `hooks/` and every `db/*.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
@@ -177,7 +177,7 @@ export default class TodosController {
 ```
 
 ```ts
-// db/schema.ts — config-as-code; the deploy auto-migrates additive changes.
+// db/public.ts — config-as-code; the deploy auto-migrates additive changes.
 import { defineSchema, uuid, text, boolean, timestamp, policy } from "@palbase/backend";
 export default defineSchema({
   tables: {
@@ -218,7 +218,7 @@ generated client surface) changes; the verb/path do not affect it.
   (stage, bundle, extract controller metadata). Exits non-zero on a decorator,
   return-type or version-skew error, so a push that would deploy zero endpoints
   fails on your machine instead. It also regenerates `palbase-env.d.ts` from
-  `db/schema.ts`, which is what types `Database.tables.*` (no import, no
+  your `db/*.ts` files, which is what types `Database.tables.*` (no import, no
   generic) — so run it after editing the schema. There is no separate command
   for that: `build` regenerates everything derived.
 - `palbase push` — deploy the current backend to the selected Environment. For a
@@ -261,9 +261,10 @@ The **only difference** is the trigger argument:
 | **Hooks** (`hooks/**`) | `(event, meta)` | typed event + `HookMeta` |
 | **Webhooks** (`webhooks/**`) | `(event, meta)` | typed event + `WebhookMeta` |
 
-`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.
+`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.
 
 `meta` carries non-service data: `env` (Environment variables),
 `environmentId`, and for webhooks `requestId`. Services always come from
@@ -287,7 +288,7 @@ my-backend/
 ```
 
 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
+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

package/docs/database.md

@@ -12,7 +12,7 @@ and [events.md](./events.md) for worker/job/hook/webhook examples).
 
 ## Typed by default — `Database.tables`
 
-When you declare `db/schema.ts`, `Database.tables.<name>` is typed everywhere
+When you declare a schema under `db/*.ts`, `Database.tables.<name>` is typed everywhere
 with no import and no generic. `insert` demands the right columns; rows come
 back typed; nullable columns are `T | null`. This is the path you should use:
 
@@ -274,7 +274,7 @@ default.
 
 The Postgres role it connects as is **`backend_authenticated`** (or
 `backend_anon` when there is no signed-in user) — not `authenticated`. You
-rarely need to know that, because a policy declared in `db/schema.ts` is
+rarely need to know that, because a policy declared in `db/*.ts` is
 deployed targeting both. It matters in exactly one place: **hand-written
 `CREATE POLICY` SQL in a migration must name both roles**, or it applies to
 nothing your code does. See

package/docs/endpoints.md

@@ -155,11 +155,12 @@ See [errors.md](./errors.md) for the full set + the wire envelope shape.
 
 ## There is no middleware
 
-`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.
+`defineMiddleware(async (ctx, next) => { … })` **throws**. Nothing mounts a
+`middleware/` directory and the engine has no middleware pipeline, so a handler
+written against it used to deploy and then never run — silently. The call now
+refuses and names where the work belongs, rather than handing you a shell.
+
+There is no `ctx` object anywhere on a path that executes.
 
 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`

package/docs/getting-started.md

@@ -47,7 +47,7 @@ start. The loop is: edit, validate, push to a dev Environment.
   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
-  regenerates `palbase-env.d.ts` from `db/schema.ts`, which is what types
+  regenerates `palbase-env.d.ts` from your `db/*.ts` files, which is what types
   `Database.tables.*` (no import, no generic), so run it after editing the
   schema — there is no separate command for that. See
   [migrations.md](./migrations.md) for the schema side.

package/docs/llms-full.txt

@@ -28,7 +28,7 @@ deploy gate or the TypeScript compile.
 controllers/<name>.controller.ts   # @Controller class + @Get/@Post/… route methods (the API surface)
 models/<controller>/<endpoint>.ts   # zod schemas — one folder per controller, one file per endpoint (+ shared.ts)
 services/<name>.service.ts          # plain class + singleton — the real logic (controllers stay thin)
-db/schema.ts                        # config-as-code Postgres schema (tables, columns, RLS) — auto-migrated on deploy
+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,
@@ -48,7 +48,7 @@ service the controllers call.
    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
+   required for `jobs/`, `webhooks/`, `hooks/` and every `db/*.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
@@ -185,7 +185,7 @@ export default class TodosController {
 ```
 
 ```ts
-// db/schema.ts — config-as-code; the deploy auto-migrates additive changes.
+// db/public.ts — config-as-code; the deploy auto-migrates additive changes.
 import { defineSchema, uuid, text, boolean, timestamp, policy } from "@palbase/backend";
 export default defineSchema({
   tables: {
@@ -226,7 +226,7 @@ generated client surface) changes; the verb/path do not affect it.
   (stage, bundle, extract controller metadata). Exits non-zero on a decorator,
   return-type or version-skew error, so a push that would deploy zero endpoints
   fails on your machine instead. It also regenerates `palbase-env.d.ts` from
-  `db/schema.ts`, which is what types `Database.tables.*` (no import, no
+  your `db/*.ts` files, which is what types `Database.tables.*` (no import, no
   generic) — so run it after editing the schema. There is no separate command
   for that: `build` regenerates everything derived.
 - `palbase push` — deploy the current backend to the selected Environment. For a
@@ -269,9 +269,10 @@ The **only difference** is the trigger argument:
 | **Hooks** (`hooks/**`) | `(event, meta)` | typed event + `HookMeta` |
 | **Webhooks** (`webhooks/**`) | `(event, meta)` | typed event + `WebhookMeta` |
 
-`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.
+`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.
 
 `meta` carries non-service data: `env` (Environment variables),
 `environmentId`, and for webhooks `requestId`. Services always come from
@@ -295,7 +296,7 @@ my-backend/
 ```
 
 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
+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
@@ -375,7 +376,7 @@ start. The loop is: edit, validate, push to a dev Environment.
   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
-  regenerates `palbase-env.d.ts` from `db/schema.ts`, which is what types
+  regenerates `palbase-env.d.ts` from your `db/*.ts` files, which is what types
   `Database.tables.*` (no import, no generic), so run it after editing the
   schema — there is no separate command for that. See
   [migrations.md](./migrations.md) for the schema side.
@@ -669,11 +670,12 @@ See [errors.md](./errors.md) for the full set + the wire envelope shape.
 
 ## There is no middleware
 
-`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.
+`defineMiddleware(async (ctx, next) => { … })` **throws**. Nothing mounts a
+`middleware/` directory and the engine has no middleware pipeline, so a handler
+written against it used to deploy and then never run — silently. The call now
+refuses and names where the work belongs, rather than handing you a shell.
+
+There is no `ctx` object anywhere on a path that executes.
 
 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`
@@ -881,7 +883,7 @@ and [events.md](./events.md) for worker/job/hook/webhook examples).
 
 ## Typed by default — `Database.tables`
 
-When you declare `db/schema.ts`, `Database.tables.<name>` is typed everywhere
+When you declare a schema under `db/*.ts`, `Database.tables.<name>` is typed everywhere
 with no import and no generic. `insert` demands the right columns; rows come
 back typed; nullable columns are `T | null`. This is the path you should use:
 
@@ -1143,7 +1145,7 @@ default.
 
 The Postgres role it connects as is **`backend_authenticated`** (or
 `backend_anon` when there is no signed-in user) — not `authenticated`. You
-rarely need to know that, because a policy declared in `db/schema.ts` is
+rarely need to know that, because a policy declared in `db/*.ts` is
 deployed targeting both. It matters in exactly one place: **hand-written
 `CREATE POLICY` SQL in a migration must name both roles**, or it applies to
 nothing your code does. See
@@ -1323,7 +1325,8 @@ export const invoices = defineTable("invoices", {
 
 Chainable modifiers: `.primaryKey()`, `.notNull()` (default), `.nullable()`,
 `.default(value)`, `.defaultRandom()` (uuid → `gen_random_uuid()`),
-`.defaultNow()` (timestamp → `now()`), `.references(() => table.column, opts?)`,
+`.defaultNow()` (timestamp → `now()`),
+`.references(() => table.column, { as?, reverseAs?, onDelete? })`,
 `.selfReferences("column", opts?)`,
 `.onDelete("cascade" | "set null" | "restrict" | "no action")`, `.ignored()`.
 
@@ -1368,14 +1371,38 @@ export const orgs = defineTable("orgs", {
 });
 ```
 
-**Two foreign keys to the same table** would derive the same relation name from
-their columns, so name one of them:
+### Relation names
+
+Every foreign key produces **two** named relations, and the two names are derived
+separately:
+
+| Direction | Where it appears | Default name | Option that changes it |
+|---|---|---|---|
+| forward (child → parent) | on the child | the column minus `_id` — `list_id` → `list` | `as` |
+| reverse (parent → children) | on the parent | the **child table's** name — `lists.todos` | `reverseAs` |
+
+So `todos.list_id → lists` gives `todos.list` and `lists.todos`, and neither
+needs declaring. `as` renames the forward side only: `author_id` declared
+`{ as: "author" }` gives `posts.author` and still gives `users.posts`. That is
+why the two options exist separately — `posts` and `comments` can both call their
+forward relation `author` without colliding, because what lands on `users` is
+`posts` and `comments`.
+
+**Two foreign keys from one table to the same parent** collide on the reverse
+side: both reverse relations want the child table's name. Name them:
 
 ```ts
-billing_address_id:  uuid().references(() => addresses.id, { as: "billing_address" }),
-shipping_address_id: uuid().references(() => addresses.id, { as: "shipping_address" }),
+billing_address_id:  uuid().references(() => addresses.id, { reverseAs: "billed_orders" }),
+shipping_address_id: uuid().references(() => addresses.id, { reverseAs: "shipped_orders" }),
 ```
 
+The forward names here (`billing_address`, `shipping_address`) are already
+distinct, so no `as` is needed. Add one when two columns WOULD derive the same
+forward name.
+
+Any two relations resolving to one name on one table are refused at push, with
+both relations named and the option that separates them.
+
 ## Rows that belong to a user
 
 There is no `public.users` table: auth users live in the `auth` schema of the same
@@ -1397,6 +1424,12 @@ device_id:  installationRef({ onDelete: "cascade" }),
 | Account erasure follows it | yes | no | no |
 | Per table | **at most one** | unlimited | unlimited |
 
+Several `userRef` columns on one table are fine — they are ordinary foreign keys
+and each takes its own relation name from its column (`created_by`, `edited_by`).
+Only two of them resolving to the SAME name is refused, and `userRef({ onDelete,
+as })` is how you separate them. `auth.users` is not a table of your schema, so
+none of these produce a reverse relation to collide over.
+
 `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.
@@ -1489,7 +1522,7 @@ 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.)
+--    (Declare it in the schema file; 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.
@@ -1589,7 +1622,7 @@ of the schema, no generic, no cast:
 // 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
+type RoomsTable = typeof Database.tables.rooms;   // typed from your db/*.ts
 
 export class RoomService {
   private readonly rooms: RoomsTable;
@@ -1773,7 +1806,9 @@ so they apply without the `acceptDataLoss` confirmation that column drops need.
 
 # Migrations
 
-`db/schema.ts` is the single source of truth for your Postgres schema. You change
+Your `db/*.ts` files are the single source of truth for your Postgres schema — one
+file per schema, `db/public.ts` in a fresh scaffold. (It was a single
+`db/schema.ts` until 2026-08-31.) You change
 the schema by editing that file — and **nothing generates a migration from it**.
 There is no diff-to-file step: the change is computed against the database *as it
 is right now*, by the stack that owns it, which is what lets it cover type
@@ -1794,7 +1829,7 @@ It is not where an ordinary column change goes any more.
 ## The workflow
 
 ```bash
-# 1. Edit db/schema.ts (add a column, a table, a policy, …)
+# 1. Edit the schema file — db/public.ts in a fresh scaffold (add a column, a table, a policy, …)
 
 # 2. See what it would take. THIS APPLIES NOTHING.
 palbase db plan
@@ -1810,9 +1845,9 @@ palbase db apply
 palbase push
 ```
 
-`palbase db plan` hands `db/schema.ts` to the local stack, which computes the plan
+`palbase db plan` hands your `db/*.ts` declarations to the local stack, which computes the plan
 against its own database and answers with what it would change. When there is
-nothing to do it says `✓ the database matches db/schema.ts`. It writes nothing,
+nothing to do it says `✓ the database matches db/*.ts`. It writes nothing,
 ever — neither a file nor a row — so it is safe to run at any moment, including
 from a script (`--detailed-exitcode` exits 2 when the plan would change
 something, 0 when it is in sync).
@@ -1854,19 +1889,19 @@ Code and schema move at different speeds, so three things keep them together:
   validation the deploy runs, so a push that would produce a failed deploy is
   caught on your machine first. (Bypass with `git push --no-verify` — the server
   still gates it.)
-- On deploy, the migrations run and Palbase then asserts `db/schema.ts` matches
+- On deploy, the migrations run and Palbase then asserts `db/*.ts` matches
   the live database. Unresolved drift **fails the deploy** and keeps the previous
   version live — a broken schema never goes out silently.
 
 ## Your schema change is not live anywhere you have not applied it
 
 The local stack and every Environment hold their own database, and editing
-`db/schema.ts` changes none of them: `palbase db apply` is what moves the local
+Editing `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.
 
 The TYPES move separately again. `palbase build` regenerates `palbase-env.d.ts`
-from `db/schema.ts`, which is what types `Database.tables.<name>` in your
+from `db/*.ts`, which is what types `Database.tables.<name>` in your
 services — so after a schema edit, run it. (There is no second command for this:
 `build` regenerates everything derived, because one verb to remember is one verb
 to forget.) Typed and applied are independent, and knowing which one you are
@@ -1881,7 +1916,7 @@ trigger, a `CHECK` constraint, an `EXCLUDE` constraint, a composite/multi-column
 `UNIQUE`, an index (`CREATE INDEX`), or `CREATE EXTENSION` for an extension that
 isn't in the DSL allowlist (e.g. `btree_gist`). The DSL column builders cover
 single-column constraints only; everything above is hand-written SQL. Where the
-DSL *can* model the table, keep `db/schema.ts` as the declared end-state and add
+DSL *can* model the table, keep `db/*.ts` as the declared end-state and add
 only the extra object in raw SQL so the drift gate passes (see below); a table
 the DSL can't model at all lives entirely in raw SQL.
 
@@ -1889,7 +1924,7 @@ Migrations run on the privileged DDL connection, so `CREATE EXTENSION` and
 `ALTER TABLE ... ADD CONSTRAINT` work. Example — race-free, DB-enforced
 double-booking prevention (no instructor in two overlapping sessions), which the
 DSL can't express. The `during` column is a `tstzrange` (no DSL builder), so the
-whole table is created in raw SQL — it can't come from `db/schema.ts`:
+whole table is created in raw SQL — it can't come from `db/*.ts`:
 
 ```sql
 CREATE EXTENSION IF NOT EXISTS btree_gist;
@@ -1910,7 +1945,7 @@ different instructor in the same slot are accepted. No application-level check.
 ### Drift gate and raw-SQL objects
 
 The deploy-time drift gate only asserts that everything **declared** in
-`db/schema.ts` exists in the live DB (declared ⊆ live), and it inspects tables,
+`db/*.ts` declares exists in the live DB (declared ⊆ live), and it inspects tables,
 columns, and column types **only** — not constraints or indexes. So a
 hand-written constraint or index is invisible to the gate, and a live object you
 never declared is tolerated (not drift, not dropped — it survives redeploys).
@@ -1918,12 +1953,12 @@ never declared is tolerated (not drift, not dropped — it survives redeploys).
 Two patterns follow from this:
 
 - **Extra constraint/index on a DSL-expressible table** — declare the table in
-  `db/schema.ts` and add **only** the constraint/index via the migration. The
+  `db/*.ts` and add **only** the constraint/index via the migration. The
   base table stays modeled, the gate ignores the constraint, and `palbase db
   plan` stays clean.
 - **A whole object the DSL can't model** (like `instructor_sessions` above — its
   `tstzrange` column has no DSL builder) — the table lives entirely in raw SQL,
-  not in `db/schema.ts`. The deploy still succeeds, but `palbase db plan` will
+  not in `db/*.ts`. The deploy still succeeds, but `palbase db plan` will
   list it as a ⚠ would-be-drop for the local database; that is expected, and the
   deploy-time gate does not block on it. Never approve that one.
 
@@ -1931,12 +1966,12 @@ Two patterns follow from this:
 
 There's nothing to put in existing rows, so do it in two migrations: first add it
 nullable (or with a default) and backfill, then a follow-up `ALTER ... SET NOT
-NULL`. `db/schema.ts` describes the end state; the migrations describe how
+NULL`. `db/*.ts` describes the end state; the migrations describe how
 existing data gets there.
 
 ## Row-Level Security
 
-Add `rls: true` + `policies: [policy(...)]` to a table in `db/schema.ts`; the
+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.tables.*` access.
@@ -2020,7 +2055,8 @@ const v = await Cache.get<{ hits: number }>("k"); // typed, null on miss
 await Cache.incr("counter");
 await Cache.del("k");
 
-// Stampede-safe read-through: only one caller across all pods runs fn.
+// Stampede-safe read-through: concurrent callers wait on ONE execution of fn
+// and share its result, however many of them there are.
 const profile = await Cache.getOrSet("user:42", 300, async () => {
   return Database.findById("users", "42");
 });

package/docs/migrations.md

@@ -1,6 +1,8 @@
 # Migrations
 
-`db/schema.ts` is the single source of truth for your Postgres schema. You change
+Your `db/*.ts` files are the single source of truth for your Postgres schema — one
+file per schema, `db/public.ts` in a fresh scaffold. (It was a single
+`db/schema.ts` until 2026-08-31.) You change
 the schema by editing that file — and **nothing generates a migration from it**.
 There is no diff-to-file step: the change is computed against the database *as it
 is right now*, by the stack that owns it, which is what lets it cover type
@@ -21,7 +23,7 @@ It is not where an ordinary column change goes any more.
 ## The workflow
 
 ```bash
-# 1. Edit db/schema.ts (add a column, a table, a policy, …)
+# 1. Edit the schema file — db/public.ts in a fresh scaffold (add a column, a table, a policy, …)
 
 # 2. See what it would take. THIS APPLIES NOTHING.
 palbase db plan
@@ -37,9 +39,9 @@ palbase db apply
 palbase push
 ```
 
-`palbase db plan` hands `db/schema.ts` to the local stack, which computes the plan
+`palbase db plan` hands your `db/*.ts` declarations to the local stack, which computes the plan
 against its own database and answers with what it would change. When there is
-nothing to do it says `✓ the database matches db/schema.ts`. It writes nothing,
+nothing to do it says `✓ the database matches db/*.ts`. It writes nothing,
 ever — neither a file nor a row — so it is safe to run at any moment, including
 from a script (`--detailed-exitcode` exits 2 when the plan would change
 something, 0 when it is in sync).
@@ -81,19 +83,19 @@ Code and schema move at different speeds, so three things keep them together:
   validation the deploy runs, so a push that would produce a failed deploy is
   caught on your machine first. (Bypass with `git push --no-verify` — the server
   still gates it.)
-- On deploy, the migrations run and Palbase then asserts `db/schema.ts` matches
+- On deploy, the migrations run and Palbase then asserts `db/*.ts` matches
   the live database. Unresolved drift **fails the deploy** and keeps the previous
   version live — a broken schema never goes out silently.
 
 ## Your schema change is not live anywhere you have not applied it
 
 The local stack and every Environment hold their own database, and editing
-`db/schema.ts` changes none of them: `palbase db apply` is what moves the local
+Editing `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.
 
 The TYPES move separately again. `palbase build` regenerates `palbase-env.d.ts`
-from `db/schema.ts`, which is what types `Database.tables.<name>` in your
+from `db/*.ts`, which is what types `Database.tables.<name>` in your
 services — so after a schema edit, run it. (There is no second command for this:
 `build` regenerates everything derived, because one verb to remember is one verb
 to forget.) Typed and applied are independent, and knowing which one you are
@@ -108,7 +110,7 @@ trigger, a `CHECK` constraint, an `EXCLUDE` constraint, a composite/multi-column
 `UNIQUE`, an index (`CREATE INDEX`), or `CREATE EXTENSION` for an extension that
 isn't in the DSL allowlist (e.g. `btree_gist`). The DSL column builders cover
 single-column constraints only; everything above is hand-written SQL. Where the
-DSL *can* model the table, keep `db/schema.ts` as the declared end-state and add
+DSL *can* model the table, keep `db/*.ts` as the declared end-state and add
 only the extra object in raw SQL so the drift gate passes (see below); a table
 the DSL can't model at all lives entirely in raw SQL.
 
@@ -116,7 +118,7 @@ Migrations run on the privileged DDL connection, so `CREATE EXTENSION` and
 `ALTER TABLE ... ADD CONSTRAINT` work. Example — race-free, DB-enforced
 double-booking prevention (no instructor in two overlapping sessions), which the
 DSL can't express. The `during` column is a `tstzrange` (no DSL builder), so the
-whole table is created in raw SQL — it can't come from `db/schema.ts`:
+whole table is created in raw SQL — it can't come from `db/*.ts`:
 
 ```sql
 CREATE EXTENSION IF NOT EXISTS btree_gist;
@@ -137,7 +139,7 @@ different instructor in the same slot are accepted. No application-level check.
 ### Drift gate and raw-SQL objects
 
 The deploy-time drift gate only asserts that everything **declared** in
-`db/schema.ts` exists in the live DB (declared ⊆ live), and it inspects tables,
+`db/*.ts` declares exists in the live DB (declared ⊆ live), and it inspects tables,
 columns, and column types **only** — not constraints or indexes. So a
 hand-written constraint or index is invisible to the gate, and a live object you
 never declared is tolerated (not drift, not dropped — it survives redeploys).
@@ -145,12 +147,12 @@ never declared is tolerated (not drift, not dropped — it survives redeploys).
 Two patterns follow from this:
 
 - **Extra constraint/index on a DSL-expressible table** — declare the table in
-  `db/schema.ts` and add **only** the constraint/index via the migration. The
+  `db/*.ts` and add **only** the constraint/index via the migration. The
   base table stays modeled, the gate ignores the constraint, and `palbase db
   plan` stays clean.
 - **A whole object the DSL can't model** (like `instructor_sessions` above — its
   `tstzrange` column has no DSL builder) — the table lives entirely in raw SQL,
-  not in `db/schema.ts`. The deploy still succeeds, but `palbase db plan` will
+  not in `db/*.ts`. The deploy still succeeds, but `palbase db plan` will
   list it as a ⚠ would-be-drop for the local database; that is expected, and the
   deploy-time gate does not block on it. Never approve that one.
 
@@ -158,12 +160,12 @@ Two patterns follow from this:
 
 There's nothing to put in existing rows, so do it in two migrations: first add it
 nullable (or with a default) and backfill, then a follow-up `ALTER ... SET NOT
-NULL`. `db/schema.ts` describes the end state; the migrations describe how
+NULL`. `db/*.ts` describes the end state; the migrations describe how
 existing data gets there.
 
 ## Row-Level Security
 
-Add `rls: true` + `policies: [policy(...)]` to a table in `db/schema.ts`; the
+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.tables.*` access.

package/docs/schema.md

@@ -121,7 +121,8 @@ export const invoices = defineTable("invoices", {
 
 Chainable modifiers: `.primaryKey()`, `.notNull()` (default), `.nullable()`,
 `.default(value)`, `.defaultRandom()` (uuid → `gen_random_uuid()`),
-`.defaultNow()` (timestamp → `now()`), `.references(() => table.column, opts?)`,
+`.defaultNow()` (timestamp → `now()`),
+`.references(() => table.column, { as?, reverseAs?, onDelete? })`,
 `.selfReferences("column", opts?)`,
 `.onDelete("cascade" | "set null" | "restrict" | "no action")`, `.ignored()`.
 
@@ -166,14 +167,38 @@ export const orgs = defineTable("orgs", {
 });
 ```
 
-**Two foreign keys to the same table** would derive the same relation name from
-their columns, so name one of them:
+### Relation names
+
+Every foreign key produces **two** named relations, and the two names are derived
+separately:
+
+| Direction | Where it appears | Default name | Option that changes it |
+|---|---|---|---|
+| forward (child → parent) | on the child | the column minus `_id` — `list_id` → `list` | `as` |
+| reverse (parent → children) | on the parent | the **child table's** name — `lists.todos` | `reverseAs` |
+
+So `todos.list_id → lists` gives `todos.list` and `lists.todos`, and neither
+needs declaring. `as` renames the forward side only: `author_id` declared
+`{ as: "author" }` gives `posts.author` and still gives `users.posts`. That is
+why the two options exist separately — `posts` and `comments` can both call their
+forward relation `author` without colliding, because what lands on `users` is
+`posts` and `comments`.
+
+**Two foreign keys from one table to the same parent** collide on the reverse
+side: both reverse relations want the child table's name. Name them:
 
 ```ts
-billing_address_id:  uuid().references(() => addresses.id, { as: "billing_address" }),
-shipping_address_id: uuid().references(() => addresses.id, { as: "shipping_address" }),
+billing_address_id:  uuid().references(() => addresses.id, { reverseAs: "billed_orders" }),
+shipping_address_id: uuid().references(() => addresses.id, { reverseAs: "shipped_orders" }),
 ```
 
+The forward names here (`billing_address`, `shipping_address`) are already
+distinct, so no `as` is needed. Add one when two columns WOULD derive the same
+forward name.
+
+Any two relations resolving to one name on one table are refused at push, with
+both relations named and the option that separates them.
+
 ## Rows that belong to a user
 
 There is no `public.users` table: auth users live in the `auth` schema of the same
@@ -195,6 +220,12 @@ device_id:  installationRef({ onDelete: "cascade" }),
 | Account erasure follows it | yes | no | no |
 | Per table | **at most one** | unlimited | unlimited |
 
+Several `userRef` columns on one table are fine — they are ordinary foreign keys
+and each takes its own relation name from its column (`created_by`, `edited_by`).
+Only two of them resolving to the SAME name is refused, and `userRef({ onDelete,
+as })` is how you separate them. `auth.users` is not a table of your schema, so
+none of these produce a reverse relation to collide over.
+
 `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.
@@ -287,7 +318,7 @@ 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.)
+--    (Declare it in the schema file; 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.
@@ -387,7 +418,7 @@ of the schema, no generic, no cast:
 // 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
+type RoomsTable = typeof Database.tables.rooms;   // typed from your db/*.ts
 
 export class RoomService {
   private readonly rooms: RoomsTable;

package/docs/services.md

@@ -42,7 +42,8 @@ const v = await Cache.get<{ hits: number }>("k"); // typed, null on miss
 await Cache.incr("counter");
 await Cache.del("k");
 
-// Stampede-safe read-through: only one caller across all pods runs fn.
+// Stampede-safe read-through: concurrent callers wait on ONE execution of fn
+// and share its result, however many of them there are.
 const profile = await Cache.getOrSet("user:42", 300, async () => {
   return Database.findById("users", "42");
 });