@palbase/backend 25.1.0 → 27.1.0

package/docs/llms-full.txt

@@ -43,14 +43,16 @@ service the controllers call.
 
 ### The 7 rules (checklist)
 
-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**
+1. **A controller is exported by NAME and listed in a module.** `@Controller`
+   records the class as it decorates it, but that registration only says the
+   class EXISTS — a module's `controllers` list is what decides it should be
+   served. So the module imports it by name, which means the class is exported;
+   an unexported one is registered, owned by nothing, and refused at build with
+   `unowned class`. Nothing is default-exported here. (`export default` **is**
    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`.
+   file — those are read off disk by name, not through a module.) 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
@@ -79,7 +81,7 @@ 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` 25.
+> and will not compile against `@palbase/backend` 27.
 
 ### Complete CRUD example (copy-pasteable, compiles)
 
@@ -103,13 +105,14 @@ export type CreateTodoBody = z.infer<typeof CreateTodoBody>;
 
 ```ts
 // services/todo.service.ts — plain class + singleton. The real work.
-import { Database, NotFound } from "@palbase/backend";
+import { Database, Injectable, 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;
+type TodosTable = typeof Database.public.todos;
 
+@Injectable()
 export class TodoService {
   private readonly todos: TodosTable;
 
@@ -123,7 +126,7 @@ export class TodoService {
   }
 
   list(userId: string): Promise<TodoSchema[]> {
-    return this.todos.findMany({ user_id: userId });
+    return this.todos.findMany({ where: { user_id: userId } });
   }
   create(userId: string, title: string): Promise<TodoSchema> {
     return this.todos.insert({ user_id: userId, title });
@@ -139,14 +142,26 @@ export class 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 with the class named — at decoration time for jobs/hooks/webhooks, and
- * when the route table is built at boot for a controller. */
-export const todoService = new TodoService(Database.tables.todos);
 ```
 
+```ts
+// 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";
+
+@Module({
+  controllers: [TodosController as Token],
+  providers: [TodoService as Token],
+})
+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).
+
 ```ts
 // controllers/todos.controller.ts — class controller. Thin: delegates to the service.
 import { Controller, Get, Post, Delete, Body, Param, User } from "@palbase/backend";
@@ -227,7 +242,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
-  your `db/*.ts` files, which is what types `Database.tables.*` (no import, no
+  your `db/*.ts` files, which is what types `Database.public.*` (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
@@ -378,7 +393,7 @@ start. The loop is: edit, validate, push to a dev Environment.
   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 your `db/*.ts` files, which is what types
-  `Database.tables.*` (no import, no generic), so run it after editing the
+  `Database.public.*` (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.
 - `palbase push` deploys the current backend to the selected Environment. For a
@@ -556,10 +571,9 @@ export default class RoomsController {
 
 1. **The controller does not touch the database.** It delegates to a service, as
    above. A method here that reaches for `Database` has moved the logic into the
-   layer that is hardest to test. (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.)
+   layer that is hardest to test. (Export the class by NAME so its module can
+   list it in `controllers`; a class no module lists is refused at build with
+   `unowned class`. Nothing here is default-exported.)
 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
@@ -864,7 +878,7 @@ single-use and expire; a used or expired one fails closed with a `400`.
 
 - [Row-Level Security](./schema.md#row-level-security-rls) — pushing per-user
   access rules into Postgres, where `auth.uid()` is this same verified user.
-- [Database](./database.md) — how `Database.asService()` steps outside RLS.
+- [Database](./database.md) — how `Database.$asService()` steps outside RLS.
 
 
 
@@ -882,19 +896,19 @@ import { Database } from "@palbase/backend";
 Only **middleware** still uses `ctx.db` (see [background.md](./background.md)
 and [events.md](./events.md) for worker/job/hook/webhook examples).
 
-## Typed by default — `Database.tables`
+## Typed by default — `Database.<şema>.<tablo>`
 
-When you declare a schema under `db/*.ts`, `Database.tables.<name>` is typed everywhere
+When you declare a schema under `db/*.ts`, `Database.public.<name>` is typed everywhere
 with no import and no generic. `insert` demands the right columns; rows come
 back typed; nullable columns are `T | null`. This is the path you should use:
 
 ```ts
-const todo = await Database.tables.todos.insert({ title: "buy milk" });
+const todo = await Database.public.todos.insert({ title: "buy milk" });
 todo.id;       // string ✓
 todo.done;     // boolean ✓
-const open = await Database.tables.todos.findMany({ done: false });
-await Database.tables.todos.update(todo.id, { done: true });
-await Database.tables.todos.delete(todo.id);
+const open = await Database.public.todos.findMany({ where: { done: false } });
+await Database.public.todos.update({ where: { id: todo.id }, set: { done: true } });
+await Database.public.todos.delete(todo.id);
 // todo.nope ← compile error
 ```
 
@@ -907,18 +921,18 @@ cover, the string-keyed ops are still available:
 
 | Method | Returns |
 |--------|---------|
-| `Database.insert(table, data)` | the inserted row (`Record<string, unknown>`) |
-| `Database.upsert(table, data, { onConflict })` | the inserted-or-updated row |
-| `Database.update(table, id, data)` | the updated row, or `null` if none matched |
-| `Database.delete(table, id)` | `void` |
-| `Database.updateMany(table, where, set)` | every row the filter matched, updated |
-| `Database.deleteMany(table, where)` | how many rows went |
-| `Database.findById(table, id)` | the row or `null` |
-| `Database.findMany(table, where?, opts?)` | matching rows (array) |
-| `Database.count(table, where?)` | how many rows match |
-| `Database.query(sql, params?)` | rows from a SQL query, in the request's own transaction |
-| `Database.transaction(fn)` | runs a whole transaction plan in one request |
-| `Database.attempt(fn)` | a savepoint: a failure inside rolls back only its own writes |
+| `Database.$insert(table, data)` | the inserted row (`Record<string, unknown>`) |
+| `Database.$put(table, data, { onConflict })` | the inserted-or-updated row |
+| `Database.$update(table, id, data)` | the updated row, or `null` if none matched |
+| `Database.$delete(table, id)` | `void` |
+| `Database.$updateMany(table, where, set)` | every row the filter matched, updated |
+| `Database.$deleteMany(table, where)` | how many rows went |
+| `Database.$findById(table, id)` | the row or `null` |
+| `Database.$findMany(table, where?, opts?)` | matching rows (array) |
+| `Database.$count(table, where?)` | how many rows match |
+| `Database.$query(sql, params?)` | rows from a SQL query, in the request's own transaction |
+| `Database.$transaction(fn)` | runs a whole transaction plan in one request |
+| `Database.$attempt(fn)` | a savepoint: a failure inside rolls back only its own writes |
 
 ### Filters
 
@@ -926,26 +940,137 @@ A filter's keys are ANDed. Each value is either a plain value (equality) or an
 operator object:
 
 ```ts
-await Database.tables.entries.findMany({
-  household_id: hid,                 // equality
-  amount_kurus: { gte: 1000 },       // >=
-  category: { in: ["food", "rent"] },
-  status: { neq: "void" },
+await Database.public.entries.findMany({
+  where: {
+    household_id: hid,               // equality
+    amount_kurus: { gte: 1000 },     // >=
+    category: { in: ["food", "rent"] },
+    status: { neq: "void" },
+  },
+});
+```
+
+Operators: `gt` · `gte` · `lt` · `lte` · `neq` · `in` · `contains` ·
+`icontains` · `startsWith` · `endsWith` · `isNull`, plus `OR` / `AND` / `NOT`
+for composition. A branch of `OR` / `AND` / `NOT` may also be a `sqlFragment`,
+so one hand-written predicate does not force the whole query into raw SQL:
+
+```ts
+await Database.public.crew_presence.findMany({
+  where: {
+    city: "IST",
+    AND: [sqlFragment`expires_at > now()`],
+  },
+});
+``` The same filter language works for `updateMany`, `deleteMany`,
+`count` and `search` — one language, so two spellings cannot drift apart. An
+empty `in` list means NO rows (written into the SQL as `false`), never a silent
+full scan.
+
+### Comparing against server time — `now()`
+
+`expires_at > now()` is one of the most-written predicates in any backend, and
+the answer must come from the DATABASE's clock: sending `new Date()` from
+JavaScript silently switches to the client's clock, and two machines do not
+agree.
+
+```ts
+import { now } from "@palbase/backend";
+
+await Database.public.sessions.findMany({
+  where: { user_id, expires_at: { gt: now() } },
 });
 ```
 
-Operators: `gt` · `gte` · `lt` · `lte` · `neq` · `in`. The same filter language
-works for `updateMany`, `deleteMany` and `count` — one language, so two spellings
-cannot drift apart. An empty `in` list means NO rows (written into the SQL as
-`false`), never a silent full scan.
+It renders as `now()` with NO bound parameter. The bare form is equality
+(`{ last_seen: now() }`), exactly like `col()`.
+
+`increment()` / `decrement()` are refused here by name: they are WRITE
+expressions, and a comparison against one would silently match nothing. And a
+`{ "$expr": { "fn": "now" } }` object arriving in a request body is not `now()`
+— only the `now()` call produces one, so spreading untrusted input into a filter
+cannot forge a server-time comparison.
+
+### Comparing one column with another — `col()`
+
+The right-hand side of a comparison is normally a VALUE. `col()` puts a COLUMN
+there, which is otherwise a reason to drop to raw SQL:
+
+```ts
+import { col } from "@palbase/backend";
+
+// Invoices that are not fully paid.
+await Database.public.invoices.findMany({ where: { total: { gt: col("amount_paid") } } });
+```
+
+The name is checked at COMPILE time against the row type: `col("amont_paid")`
+does not compile. It is legal in `gt` / `gte` / `lt` / `lte` / `neq` and as a
+bare value (which means equality); anywhere else — inside `in`, in a `set`, in
+`orderBy` — it is refused by name.
+
+`col()` is only ever produced by the `col()` call. A `{ "$col": "…" }` object
+that arrives in a request body is NOT a column reference and is refused as an
+unknown operator, so spreading untrusted input into a filter cannot turn a
+tenant predicate into a tautology.
+
+### Filtering through a relation — `has`
+
+A filter on the row next to yours is the most common reason to drop to raw SQL,
+and it is the one the schema already knows how to answer. Every foreign key you
+declare produces a named relation on BOTH sides, and `has` filters through it:
+
+```ts
+// Interests that THIS user picked.
+await Database.public.interests.findMany({
+  where: { has: { user_interests: { user_id: userId } } },
+  orderBy: { column: "sort_order", direction: "asc" },
+});
+```
+
+That compiles to a correlated `IN (SELECT …)` — one statement, one round trip,
+the RLS policies of BOTH tables still applied. The hand-written alternative was
+a `sqlFragment` carrying a subquery, or two queries and a `Set` in JavaScript.
+
+The relation names come from the schema, so `has: { user_intrests: … }` is a
+compile error, and so is a column that the OTHER table does not have. A table
+that declares no foreign key at all has no `has` — the key is absent, not empty.
+
+Both directions work. From the child, the relation is the parent:
+
+```ts
+await Database.public.user_interests.findMany({
+  where: { has: { interest: { name: { icontains: "yoga" } } } },
+});
+```
+
+The inner filter is the SAME language: operators, `OR` / `AND` / `NOT`, `col()`,
+and a nested `has` one table further (three levels — the relation graph points
+both ways, so it is a cycle, and an unbounded type would follow it forever).
+
+`has` is available wherever a filter is: `findMany`, `count`, `updateMany`,
+`deleteMany`, and inside `$transaction`. In a transaction the update still takes
+its rows in primary-key order under `FOR NO KEY UPDATE`, exactly as a plain
+filter does:
+
+```ts
+await Database.$transaction((tx) => {
+  tx.public.interests.updateWhere(
+    { has: { user_interests: { user_id: userId } } },
+    { last_seen_at: now() },
+  );
+  return [];
+});
+```
 
 ### Ordering and paging
 
 ```ts
-await Database.tables.entries.findMany(
-  { household_id: hid },
-  { orderBy: { column: "created_at", direction: "desc" }, limit: 20, offset: 40 },
-);
+await Database.public.entries.findMany({
+  where: { household_id: hid },
+  orderBy: { column: "created_at", direction: "desc" },
+  limit: 20,
+  offset: 40,
+});
 ```
 
 `orderBy.column` is checked against the row type: a mistyped column name is a
@@ -969,7 +1094,7 @@ It runs in **the request's own transaction**, not a read-only one: a write insid
 it commits with the rest of the request.
 
 ```ts
-const rows = await Database.query(
+const rows = await Database.$query(
   "SELECT c.name, count(*) FROM entries e JOIN categories c ON c.id = e.category_id" +
   " WHERE e.household_id = $1 GROUP BY c.name",
   [hid],
@@ -986,7 +1111,7 @@ Inside a transaction, `insertMany` takes an optional conflict rule — which is
 per row with a `23505` caught around each:
 
 ```ts
-await Database.transaction((tx) => {
+await Database.$transaction((tx) => {
   tx.tables.merchants.insertMany(rows, { onConflict: ["name"], action: "ignore" });
   return null;
 });
@@ -1013,7 +1138,7 @@ carrying the constraint Postgres named:
 import { UniqueViolation, Conflict } from "@palbase/backend";
 
 try {
-  return await Database.tables.users.insert({ email });
+  return await Database.public.users.insert({ email });
 } catch (e) {
   if (UniqueViolation.is(e) && e.constraint === "users_email_key") {
     throw new Conflict("That email is taken", "email_taken");
@@ -1043,7 +1168,7 @@ middle, so nothing holds a database connection open while your code thinks.
 ```ts
 import { Database, NotFound } from "@palbase/backend";
 
-const { orderId } = await Database.transaction((tx) => {
+const { orderId } = await Database.$transaction((tx) => {
   const order = tx.tables.orders
     .insert({ amount: 1000, status: "pending" })
     .expectOne(new NotFound("order could not be created"));
@@ -1092,9 +1217,9 @@ does not write is not part of the transaction:
 
 ```ts
 // Before the transaction: an ordinary value you can branch on.
-const overrides = await Database.tables.category_overrides.findMany({ household_id });
+const overrides = await Database.public.category_overrides.findMany({ where: { household_id } });
 
-const stmt = await Database.transaction((tx) => { /* … */ });
+const stmt = await Database.$transaction((tx) => { /* … */ });
 ```
 
 ### Writing conditions as filters
@@ -1125,19 +1250,113 @@ Three expressions may appear in the values you write:
 
 | Expression | Where | Meaning |
 |---|---|---|
-| `now()` | anywhere | the server's clock |
-| `inc(n)` | `updateWhere`'s `set` | `column = column + n`, atomically |
-| `dec(n)` | `updateWhere`'s `set` | `column = column - n`, atomically |
+| `now()` | any `set` — `updateMany` and `updateWhere` | the server's clock |
+| `increment(n)` | any `set` | `column = column + n`, atomically |
+| `decrement(n)` | any `set` | `column = column - n`, atomically |
+
+`inc` / `dec` are the OLD names for `increment` / `decrement`. They are the same
+factory (`inc === increment`), kept as deprecated aliases; write the long names.
+
+The expressions work on BOTH surfaces — the direct `updateMany` and the plan's
+`updateWhere` — because they are one object:
+
+```ts
+// Direct: one statement, no transaction needed.
+await Database.public.accounts.updateMany({
+  where: { id: accountId },
+  set: { balance: decrement("5.00") },
+});
+
+// Inside a plan: the same expression, the same meaning.
+await Database.$transaction((tx) => {
+  tx.tables.accounts.updateWhere({ id: accountId }, { balance: decrement("5.00") });
+  return null;
+});
+```
+
+**Give money a STRING amount.** `increment(0.1)` binds a JS number and
+`0.1 + 0.2` is `0.30000000000000004`; `increment("0.1")` binds the decimal and
+Postgres adds it exactly. Measured: `12345678901234567890` as a number becomes
+`12345678901234600000`, as a string it stays whole.
+
+**The amount is a magnitude, not a signed number.** `decrement("-5")` is
+refused: a negative amount would ADD money through a call that reads as a
+withdrawal, and the guard names `increment()` as the way to say the other
+direction.
+
+`increment` / `decrement` read the column's current value, which an inserted row
+does not have — using one in an `insert` is a compile error, and the engine
+refuses it by name if it arrives untyped.
+
+### Zero rows is not silent success
+
+`updateMany` returns EVERY row it matched, and matching nothing is an answer the
+caller has to read:
+
+```ts
+const [row] = await Database.public.accounts.updateMany({
+  where: { id: accountId, balance: { gte: amount } },   // the guard IS the filter
+  set: { balance: decrement(amount) },
+});
+if (row === undefined) throw new Conflict("insufficient balance");
+```
+
+The filter carries the condition, so the check and the write are ONE statement —
+there is no window between reading a balance and spending it. An empty array
+means the balance was too low, or the row does not exist, or RLS hides it from
+this caller. None of those is "the transfer happened".
+
+### Append-only tables — a record that cannot be rewritten
+
+`appendOnly: true` on a table declaration means a row can be INSERTED and read,
+never updated and never deleted. A correction is a COMPENSATING ENTRY: a new row
+carrying the opposite sign.
+
+```ts
+export const entries = defineTable("entries", {
+  appendOnly: true,
+  columns: { /* … */ },
+});
+```
+
+**Three locks, because the first two are not enough on their own:**
+
+| Lock | Stops | Does not stop |
+|---|---|---|
+| The TYPE | `update` / `updateMany` / `delete` / `deleteMany` / `put` / `supersede` are not on the table | untyped `$`-prefixed calls, anything off the wire |
+| The ENGINE | those same operations refused by name, whichever door they come through | SQL that never passes through this SDK |
+| The DATABASE | `REVOKE UPDATE, DELETE`, a RESTRICTIVE policy, and two triggers — `BEFORE UPDATE OR DELETE` per row and `BEFORE TRUNCATE` per statement | the table's OWNER, who can `ALTER TABLE … DISABLE TRIGGER` first (measured) — as an owner can also simply drop the table |
+
+The triggers are not belt-and-braces. Measured on a live stack: the platform
+re-grants table privileges on every boot, which quietly undid the REVOKE, and
+the service role carries `BYPASSRLS`, so the policy never applied to it either.
+With both gone the row really was deletable. The triggers are what actually
+hold, and they say so:
 
-`inc`/`dec` read the column's current value, which an inserted row does not
-have — using them in an `insert` is a compile error.
+```
+ERROR:  table entries is append-only: a row cannot be updated or deleted.
+        Write a COMPENSATING ENTRY instead (an INSERT carrying the opposite sign).
+```
+
+`SELECT` and `INSERT` are untouched — append-only means the history is kept, not
+that it is unreadable, and the correction path has to stay open.
+
+**TRUNCATE needs its own trigger, and finding that out took a measurement.** A
+row-level trigger never sees a `TRUNCATE` — Postgres truncates without touching
+rows — so the owner could empty the whole ledger in one statement while every
+other door was shut. The statement-level `BEFORE TRUNCATE` trigger closes it.
+
+What is NOT closed: the table's owner can `ALTER TABLE … DISABLE TRIGGER` and
+then write freely. That is not a hole this can fix — the same owner can drop the
+table — and saying otherwise would be the kind of claim this table exists to
+avoid.
 
 ### Limits
 
 A plan may carry at most 1000 operations, 5000 rows in one `insertMany`, and
 8 MiB of JSON. Exceeding any of them is reported before the request is sent.
 
-## Bypassing RLS — `Database.asService()`
+## Bypassing RLS — `Database.$asService()`
 
 When a table has [Row-Level Security](./schema.md#row-level-security-rls)
 policies, every `Database.*` call runs as the request's verified user, so the
@@ -1154,7 +1373,7 @@ nothing your code does. See
 
 Sometimes you need to read or write **across all users** — an admin endpoint, a
 background job that fans out notifications, a cleanup task. For that, call
-`Database.asService()`. It returns a sibling client that runs as
+`Database.$asService()`. It returns a sibling client that runs as
 **`backend_service_role`** (the role that carries `BYPASSRLS`), exposing the
 exact same surface — `tables`, the raw string ops, and `transaction`:
 
@@ -1162,14 +1381,14 @@ exact same surface — `tables`, the raw string ops, and `transaction`:
 import { Database } from "@palbase/backend";
 
 // RLS-enforced (default): only the caller's own rows.
-const mine = await Database.tables.todos.findMany({});
+const mine = await Database.public.todos.findMany({});
 
 // Service-role bypass: every user's rows. Explicit and greppable.
-const all  = await Database.asService().tables.todos.findMany({});
-const rows = await Database.asService().query("SELECT count(*) FROM todos");
+const all  = await Database.$asService().tables.todos.findMany({});
+const rows = await Database.$asService().query("SELECT count(*) FROM todos");
 
 // A service-role transaction (the role is fixed for the whole plan):
-await Database.asService().transaction((tx) => {
+await Database.$asService().transaction((tx) => {
   tx.tables.todos.updateWhere({ id }, { done: true });
   return null;
 });
@@ -1182,8 +1401,8 @@ Guidelines:
   grep for in review.
 - **No double-bypass / no nesting.** The sibling does not re-expose
   `asService()`, and `tx` never exposes it — a plan's role is fixed for the whole
-  transaction. Use `Database.transaction(...)` for an authenticated one and
-  `Database.asService().transaction(...)` for a service-role one; you cannot mix
+  transaction. Use `Database.$transaction(...)` for an authenticated one and
+  `Database.$asService().transaction(...)` for a service-role one; you cannot mix
   enforced and bypassed operations inside a single plan.
 - **It is a second transaction, on a second connection.** It has to be: the
   Postgres role is bound once, when the transaction opens, so a sibling sharing
@@ -1209,7 +1428,7 @@ 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
+changes need an explicit migration) and makes `Database.public.*` typed
 everywhere — by default, with no import and no generic.
 
 > Coming from a single `db/schema.ts` with tables declared inline? That layout is
@@ -1616,14 +1835,14 @@ and an index is not one.
 ## Typed DB access — by default
 
 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
+`palbase-env.d.ts`, which types `Database.public.<name>` everywhere — no import
 of the schema, no generic, no cast:
 
 ```ts
 // services/room.service.ts — the layer that touches the database.
 import { Database } from "@palbase/backend";
 
-type RoomsTable = typeof Database.tables.rooms;   // typed from your db/*.ts
+type RoomsTable = typeof Database.public.rooms;   // typed from your db/*.ts
 
 export class RoomService {
   private readonly rooms: RoomsTable;
@@ -1636,13 +1855,22 @@ export class RoomService {
   }
 }
 
-export const roomService = new RoomService(Database.tables.rooms);
+```
+
+```ts
+// rooms.module.ts
+import { Module, type Token } from "@palbase/backend";
+import { RoomsController } from "./controllers/rooms.controller.ts";
+import { RoomService } from "./services/room.service.ts";
+
+@Module({ controllers: [RoomsController as Token], providers: [RoomService as Token] })
+export class RoomsModule {}
 ```
 
 ```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";
+import { RoomService } from "../services/room.service.js";
 
 const CreateRoomBody = z.object({ name: z.string() });
 const RoomOut = z.object({ id: z.string(), name: z.string() });
@@ -1658,12 +1886,12 @@ export default class RoomsController {
 }
 ```
 
-`Database.tables.<name>` exposes `insert`, `update(id, data)`, `delete(id)`,
-`findById(id)`, `findMany(query?)`. `Database.transaction(fn)` yields a `tx`
+`Database.public.<name>` exposes `insert`, `update(id, data)`, `delete(id)`,
+`findById(id)`, `findMany(query?)`. `Database.$transaction(fn)` yields a `tx`
 whose `tx.tables.<name>` is typed from the same schema, but carries plan
 operations (`insert`/`insertMany`/`updateWhere`/`deleteWhere`/`select`) rather
 than awaited calls — see [database.md](./database.md#transactions). The raw
-string-keyed ops (`Database.insert("rooms", …)`, `Database.query(…)`) are still
+string-keyed ops (`Database.$insert("rooms", …)`, `Database.$query(…)`) are still
 available for dynamic table names and read-only SQL.
 
 If you want a row type explicitly, import it from the generated env module:
@@ -1784,10 +2012,10 @@ export const todos = defineTable("todos", {
 export default defineSchema("public", { tables: [todos] });
 ```
 
-With this in place, `await Database.tables.todos.findMany({})` returns only the
+With this in place, `await Database.public.todos.findMany({})` returns only the
 calling user's rows — no `WHERE owner = …` needed in the handler. To read or
 write across all users (e.g. an admin job), use the explicit bypass:
-`Database.asService()` (see [database.md](./database.md#bypassing-rls--databaseasservice)).
+`Database.$asService()` (see [database.md](./database.md#bypassing-rls--databaseasservice)).
 
 ### How policies are applied
 
@@ -1902,7 +2130,7 @@ one, `palbase push` is what moves an Environment's. Until then the declaration i
 ahead of the tables.
 
 The TYPES move separately again. `palbase build` regenerates `palbase-env.d.ts`
-from `db/*.ts`, which is what types `Database.tables.<name>` in your
+from `db/*.ts`, which is what types `Database.public.<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
@@ -1975,7 +2203,7 @@ existing data gets there.
 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.
+`Database.public.*` access.
 
 ### Hand-writing a policy
 
@@ -2059,7 +2287,7 @@ await Cache.del("k");
 // 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");
+  return Database.$findById("users", "42");
 });
 ```
 
@@ -2167,7 +2395,7 @@ export default class CheckoutController {
 
 ### Overriding a flag — current user vs cross-user
 
-Writes mirror the `Database` / `Database.asService()` model:
+Writes mirror the `Database` / `Database.$asService()` model:
 
 - `Flags.setOverride(key, value)` (default) writes an override for the **current
   request user** — no `userId` argument, no admin power. It errors on an
@@ -2175,7 +2403,7 @@ Writes mirror the `Database` / `Database.asService()` model:
 - `Flags.asService()` returns the cross-user admin surface
   (`setOverrideForUser`, `setOverridesForUser`, `clearOverrideForUser`,
   `clearAllOverridesForUser`, `batchSetOverrides`) for writing overrides for an
-  **arbitrary** user. Explicit and greppable, just like `Database.asService()`.
+  **arbitrary** user. Explicit and greppable, just like `Database.$asService()`.
 
 ```ts
 // Current request user — no userId needed:
@@ -2244,47 +2472,137 @@ A controller's job is HTTP — validate a body through a named schema, name the
 whose, in what order is the service's. A controller that reaches for `Database`
 has moved the logic into the layer that is hardest to test.
 
-**2. The dependency arrives through the CONSTRUCTOR, and the module exports one
-wired instance.** There is no DI container and no decorator — the last line of
-the file is the wiring:
+**2. A dependency arrives through the CONSTRUCTOR, and the container supplies
+it.** Mark the class `@Injectable()` and name what it needs as ordinary
+constructor parameters:
 
 ```ts
 // services/note.service.ts
-import { Database } from "@palbase/backend";
+import { Database, Injectable } from "@palbase/backend";
 
-type NotesTable = typeof Database.tables.notes;
+type NotesTable = typeof Database.public.notes;
 
+@Injectable()
 export class NoteService {
-  private readonly notes: NotesTable;
-
-  // Assigned in the BODY. A parameter property (`constructor(private notes: …)`)
-  // is refused by Node's type-stripping test runner, for the whole file.
-  constructor(notes: NotesTable) {
-    this.notes = notes;
-  }
+  private readonly notes: NotesTable = Database.public.notes;
 
   list(userId: string) {
-    return this.notes.findMany({ user_id: userId });
+    return this.notes.findMany({ where: { user_id: userId } });
   }
 }
+```
 
-export const noteService = new NoteService(Database.tables.notes);
+```ts
+// services/report.service.ts — a service that depends on another service
+import { Injectable } from "@palbase/backend";
+import { NoteService } from "./note.service.ts";
+
+@Injectable()
+export class ReportService {
+  constructor(private readonly notes: NoteService) {}
+
+  async count(userId: string): Promise<number> {
+    return (await this.notes.list(userId)).length;
+  }
+}
 ```
 
+A controller asks the same way, and nothing wires it by hand:
+
 ```ts
 // controllers/notes.controller.ts
-import { noteService } from "../services/note.service";
+import { Controller, Get } from "@palbase/backend";
+import { NoteService } from "../services/note.service.ts";
+
+@Controller("/notes")
+export class NotesController {
+  constructor(private readonly notes: NoteService) {}
+
+  @Get("") list(): Promise<Note[]> { return this.notes.list(currentUserId()); }
+}
 ```
 
-**3. That module-level singleton is the only way to hold a dependency.**
-Controllers, hooks, jobs and webhooks are all constructed by the runtime with
-**no arguments**. A class that declares a constructor parameter is refused at
-build with the class named — there is no injector to fill it, so the field would
-otherwise be `undefined` in production. Import the singleton instead.
+There is **no `inject()`, no `@Inject`, and no token registry**. A dependency is
+named by its parameter's TYPE and by nothing else — which is also why an
+`interface` cannot be one: an interface does not exist at runtime, so there is
+nothing to hand over. Use a class, or an `abstract class` when you want the
+abstraction:
+
+```ts
+export abstract class Clock {
+  abstract now(): number;
+}
+
+@Injectable()
+export class SystemClock extends Clock {
+  now(): number { return Date.now(); }
+}
+```
+
+The abstraction is the TOKEN; the implementation is the PROVIDER. `SystemClock`
+goes in a module's `providers` and `Clock` goes in nobody's: the container
+resolves an abstraction to the single owned class that `extends` it. Listing
+`Clock` itself is refused — `new Clock()` succeeds in JavaScript and hands back
+an object missing every abstract member, and that object would be injected.
+
+**3. ONE module says what exists, who owns it, and what it may reach.** A class
+that no module lists does not exist: it is refused at build, by name, and it
+never reaches the route table, the dispatcher or the OpenAPI document.
+
+```ts
+// notes.module.ts — beside the domain it owns, not in a directory we name
+import { Module, type Token } from "@palbase/backend";
+import { NotesController } from "./controllers/notes.controller.ts";
+import { NoteService } from "./services/note.service.ts";
+import { ReportService } from "./services/report.service.ts";
+
+@Module({
+  controllers: [NotesController as Token],   // the entry points this module owns
+  providers: [NoteService as Token, ReportService as Token],  // what it owns
+  exports: [NoteService as Token],           // what OTHER modules may reach
+  imports: [],                               // whose exports THIS module may reach
+})
+export class NotesModule {}
+```
+
+The four lists answer four different questions, and nothing else answers them:
+
+| list | question |
+|---|---|
+| `providers` | which classes does this module OWN |
+| `controllers` | which entry points does it own |
+| `exports` | which of its own classes may another module reach |
+| `imports` | whose exports may this module reach |
+
+`ReportService` is NOT exported above, so no other module can depend on it —
+and the build says so by name if one tries. That is the whole boundary: a
+module's internals stay internal until it says otherwise.
+
+There is no root module and nothing to mount one into. A small project writes
+one module file; a large one writes a module per domain and the boundaries are
+enforced at build rather than by convention.
+
+**A constructor stays pure wiring.** It runs while the app is coming up, it is
+synchronous, and it must not do I/O. Real work at startup belongs in `onStart`,
+which is awaited before the first request is served — a connection opened in a
+constructor fails somewhere nobody is watching, and one opened in `onStart`
+fails at boot with the error in front of the operator.
+
+Rule 2 is also what makes rule 1 pay off. A test can build the graph with a
+stand-in in place of any part of it, however deep:
+
+```ts
+import { isolated } from "@palbase/backend/test";
+
+const frozen = new (class extends Clock { now() { return 0; } })();
+const report = isolated().with(Clock, frozen).get(ReportService);
+```
 
-Rule 2 is also what makes rule 1 pay off: because the service is handed its
-table rather than reaching for the singleton, a test constructs it with a
-stand-in and never needs a database.
+`isolated()` rebuilds the graph with the overrides in place and touches no
+process-wide state, so the next test in the same file does not meet whatever
+this one substituted. Or construct the class yourself — `new ReportService(new
+NoteService())` is ordinary TypeScript, and the container is not required for it
+to work.
 
 ```ts
 // services/note.service.test.ts — `npm test`, no database
@@ -2438,8 +2756,8 @@ import { Database, Job, Log, type JobMeta } from "@palbase/backend";
 @Job({ schedule: "0 3 * * *", timeout: 120 }) // schedule: standard cron; timeout: optional, seconds
 export default class CleanupJob {
   async run(meta: JobMeta) {
-    const expired = await Database.findMany("sessions", { expired: true });
-    for (const s of expired) await Database.delete("sessions", s.id as string);
+    const expired = await Database.$findMany("sessions", { expired: true });
+    for (const s of expired) await Database.$delete("sessions", s.id as string);
     Log.info(`cleaned ${expired.length} sessions in ${meta.environmentId}`);
   }
 }
@@ -2471,7 +2789,7 @@ import { auth, Database, Log } from "@palbase/backend";
 
 export const onUserCreated = auth.onUserCreated(async (event, meta) => {
   Log.info(`new user: ${event.user.email}`);
-  await Database.insert("profiles", {
+  await Database.$insert("profiles", {
     user_id: event.user.id,
     email: event.user.email,
   });
@@ -2504,13 +2822,13 @@ import { Database, Log, On, Webhook, type WebhookMeta } from "@palbase/backend";
 export default class StripeWebhook {
   @On("checkout.session.completed")
   async checkoutCompleted(event: unknown, meta: WebhookMeta) {
-    await Database.insert("orders", { status: "paid", data: event });
+    await Database.$insert("orders", { status: "paid", data: event });
   }
 
   @On("payment_intent.payment_failed")
   async paymentFailed(event: unknown, meta: WebhookMeta) {
     Log.error("payment failed");
-    await Database.insert("payment_failures", { data: event });
+    await Database.$insert("payment_failures", { data: event });
   }
 }
 ```