@palbase/backend 33.0.0 → 33.0.1

package/docs/README.md

@@ -16,15 +16,24 @@ deploy gate or the TypeScript compile.
 
 ### Folder layout
 
+Every domain is a FOLDER under `modules/`, carrying its own controller, service,
+schemas, and the one module that lists them:
+
 ```
-controllers/<name>.controller.ts   # @Controller class + @Get/@Post/… route methods (the API surface)
-models/<controller>/<endpoint>.ts   # zod schemas — one folder per controller, one file per endpoint (+ shared.ts)
-services/<name>.service.ts          # plain class + singleton — the real logic (controllers stay thin)
-db/<schema>.ts                      # one file per Postgres schema (db/public.ts in a fresh scaffold)
+modules/<domain>/<domain>.module.ts     # @Module: controllers · providers · exports · imports
+modules/<domain>/<name>.controller.ts   # @Controller class + @Get/@Post/… route methods (the API surface)
+modules/<domain>/<name>.service.ts      # @Injectable() class — the real logic (controllers stay thin)
+modules/<domain>/dto/<endpoint>.ts      # zod schemas — one file per endpoint
+db/<schema>.ts                          # one file per Postgres schema (db/public.ts in a fresh scaffold)
 ```
 
-The four folders above are the daily surface. Three more are discovered by name,
-one class per file, `export default` required: `jobs/` (background —
+There is no root `controllers/`, `services/` or `models/` directory, and no
+`app.module.ts` to mount anything into: a `*.module.ts` is found wherever it
+lives, so adding a domain means adding a folder — never a line in a file every
+branch edits.
+
+The schema stays at the root, in `db/`. Three more directories are discovered by
+name, one class per file, `export default` required: `jobs/` (background —
 [background.md](./background.md)), `webhooks/` and `hooks/` (events —
 [events.md](./events.md)).
 
@@ -58,7 +67,7 @@ service the controllers call.
    + the runtime read that named type to bind the 200 response zod schema. There
    is no `@Returns` decorator. A body route with no named return type is a build
    error; a method with no response body annotates `: Promise<void>` / `: void`.
-5. **Schemas live in `models/<controller>/<endpoint>.ts`,** exported as a zod
+5. **Schemas live in `modules/<domain>/dto/<endpoint>.ts`,** exported as a zod
    VALUE and a same-named `z.infer` TYPE. The controller imports them and writes
    `@Body(CreateTodoBody) body: CreateTodoBody` (value in the decorator, same name
    as the type annotation).
@@ -78,7 +87,7 @@ service the controllers call.
 ### Complete CRUD example (copy-pasteable, compiles)
 
 ```ts
-// models/todos/shared.ts — the response shape, reused across endpoints.
+// modules/todos/dto/shared.ts — the response shape, reused across endpoints.
 import { z } from "@palbase/backend";
 export const TodoSchema = z.object({
   id: z.string(),
@@ -89,41 +98,63 @@ export type TodoSchema = z.infer<typeof TodoSchema>;
 ```
 
 ```ts
-// models/todos/create.ts — the POST body.
+// modules/todos/dto/create.ts — the POST body.
 import { z } from "@palbase/backend";
 export const CreateTodoBody = z.object({ title: z.string().min(1) });
 export type CreateTodoBody = z.infer<typeof CreateTodoBody>;
 ```
 
 ```ts
-// services/todo.service.ts — plain class + singleton. The real work.
+// modules/todos/todo.service.ts — @Injectable() classes. The real work.
 import { Database, Injectable, NotFound } from "@palbase/backend";
-import type { TodoSchema } from "../models/todos/shared.js";
+import type { Tables } from "@palbase/backend/env";
+
+/** One row of `todos`, exactly as `db/public.ts` declares it. */
+export type Todo = Tables["todos"]["row"];
+
+/** The one table this vertical touches, behind a class the container can build.
+ * `Database.public.todos` is a VALUE, and a dependency is named by its
+ * parameter's TYPE — so the seam is an `abstract class`, and it stays ONE table
+ * wide: a test fake implements four methods, not the whole `Database`. */
+export abstract class TodoRepo {
+  // Mirror the table's own call shape: `findMany` takes `{ where, orderBy, … }`,
+  // not a bare filter.
+  abstract findMany(q: { where: { user_id: string } }): Promise<Todo[]>;
+  abstract insert(row: { user_id: string; title: string }): Promise<Todo>;
+  abstract findById(id: string): Promise<Todo | null>;
+  abstract delete(id: string): Promise<void>;
+}
 
-/** The typed surface of ONE table. Naming it keeps the seam one table wide:
- * a test fake implements five methods, not the whole `Database`. */
-type TodosTable = typeof Database.public.todos;
+@Injectable()
+export class DbTodoRepo extends TodoRepo {
+  findMany(q: { where: { user_id: string } }): Promise<Todo[]> {
+    return Database.public.todos.findMany(q);
+  }
+  insert(row: { user_id: string; title: string }): Promise<Todo> {
+    return Database.public.todos.insert(row);
+  }
+  findById(id: string): Promise<Todo | null> {
+    return Database.public.todos.findById(id);
+  }
+  delete(id: string): Promise<void> {
+    return Database.public.todos.delete(id);
+  }
+}
 
 @Injectable()
 export class TodoService {
-  private readonly todos: TodosTable;
-
-  // THE SEAM IS THE CONSTRUCTOR: the class is handed the table rather than
-  // reaching for the singleton, so a test constructs it with a stand-in and
-  // never needs a database. Assign in the BODY — a parameter property
-  // (`constructor(private todos: …)`) is refused by Node's type-stripping test
-  // runner, and refused for the whole FILE.
-  constructor(todos: TodosTable) {
-    this.todos = todos;
-  }
+  // THE SEAM IS THE CONSTRUCTOR: the container supplies this, so a test hands in
+  // a stand-in and never needs a database. Nothing registers it and nothing
+  // wires it — `todos.module.ts` lists the class, and that list is the ownership.
+  constructor(private readonly todos: TodoRepo) {}
 
-  list(userId: string): Promise<TodoSchema[]> {
+  list(userId: string): Promise<Todo[]> {
     return this.todos.findMany({ where: { user_id: userId } });
   }
-  create(userId: string, title: string): Promise<TodoSchema> {
+  create(userId: string, title: string): Promise<Todo> {
     return this.todos.insert({ user_id: userId, title });
   }
-  async get(userId: string, id: string): Promise<TodoSchema> {
+  async get(userId: string, id: string): Promise<Todo> {
     const t = await this.todos.findById(id);
     if (!t || t.user_id !== userId) throw new NotFound("No todo with that id");
     return t;
@@ -133,68 +164,74 @@ export class TodoService {
     await this.todos.delete(id);
   }
 }
-
 ```
 
 ```ts
-// todos.module.ts — ONE module says what exists, who owns it, and what it may reach.
+// modules/todos/todos.module.ts — ONE module says what exists, who owns it, and what it may reach.
 import { Module, type Token } from "@palbase/backend";
-import { TodosController } from "./controllers/todos.controller.ts";
-import { TodoService } from "./services/todo.service.ts";
+import { TodosController } from "./todos.controller.ts";
+import { DbTodoRepo, TodoService } from "./todo.service.ts";
 
 @Module({
   controllers: [TodosController as Token],
-  providers: [TodoService as Token],
+  providers: [TodoService as Token, DbTodoRepo as Token],
+  exports: [],   // which of its own classes ANOTHER module may reach
+  imports: [],   // whose exports THIS module may reach
 })
 export class TodosModule {}
 ```
 
-A class no module lists does not exist: it is refused at build, by name, and it
-never reaches the route table or the OpenAPI document. Nothing is wired by hand
-— a controller names `TodoService` as a constructor parameter and the container
-supplies it. See [services.md](./services.md#your-own-service-layer).
+The abstraction is the TOKEN and the implementation is the PROVIDER: `DbTodoRepo`
+is listed, `TodoRepo` is not — the container resolves an abstraction to the single
+class that `extends` it. A class no module lists does not exist: it is refused at
+build, by name, and it never reaches the route table or the OpenAPI document.
+Nothing is wired by hand — a controller names `TodoService` as a constructor
+parameter and the container supplies it. See
+[services.md](./services.md#your-own-service-layer).
 
 ```ts
-// controllers/todos.controller.ts — class controller. Thin: delegates to the service.
+// modules/todos/todos.controller.ts — class controller. Thin: delegates to the service.
 import { Controller, Get, Post, Delete, Body, Param, User } from "@palbase/backend";
 import type { UserT } from "@palbase/backend";       // the user TYPE (@User is the value)
-import { todoService } from "../services/todo.service.js";
-import { TodoSchema } from "../models/todos/shared.js";
-import { CreateTodoBody } from "../models/todos/create.js";
+import { TodoService } from "./todo.service";
+import { TodoSchema } from "./dto/shared";
+import { CreateTodoBody } from "./dto/create";
 
 @Controller("/todos")                                  // secure-by-default; { auth: false } opts the whole controller out
-export default class TodosController {
-  // The service arrives as an IMPORTED SINGLETON, not a constructor parameter:
-  // the runtime constructs this class with no arguments, and one that declares a
-  // parameter is refused when the route table is built at boot, with the class named.
+export class TodosController {
+  // The service arrives through the CONSTRUCTOR and the container supplies it.
+  // Nothing is imported as an instance and nothing is wired by hand.
+  constructor(private readonly todos: TodoService) {}
 
   @Get("")                                             // GET /todos → operationId todos.list
-  async list(@User() user: UserT): Promise<TodoSchema[]> {  // return type → 200 response schema
-    return todoService.list(user.id);
+  list(@User() user: UserT): Promise<TodoSchema[]> {   // return type → 200 response schema
+    return this.todos.list(user.id);
   }
 
   @Post("")                                            // POST /todos → todos.create
-  async create(@Body(CreateTodoBody) body: CreateTodoBody, @User() user: UserT): Promise<TodoSchema> {
-    return todoService.create(user.id, body.title);
+  create(@Body(CreateTodoBody) body: CreateTodoBody, @User() user: UserT): Promise<TodoSchema> {
+    return this.todos.create(user.id, body.title);
   }
 
   @Get("/{id}")                                        // GET /todos/{id} → todos.get
-  async get(@Param("id") id: string, @User() user: UserT): Promise<TodoSchema> {
-    return todoService.get(user.id, id);
+  get(@Param("id") id: string, @User() user: UserT): Promise<TodoSchema> {
+    return this.todos.get(user.id, id);
   }
 
   @Delete("/{id}")                                     // DELETE /todos/{id} → todos.remove; no body → : Promise<void>
-  async remove(@Param("id") id: string, @User() user: UserT): Promise<void> {
-    await todoService.remove(user.id, id);
+  remove(@Param("id") id: string, @User() user: UserT): Promise<void> {
+    return this.todos.remove(user.id, id);
   }
 }
-// No export is needed at all — @Controller registered the class as it decorated
-// it. `export default` here is style, not a requirement.
+// Exported by NAME, because `todos.module.ts` imports it to list it in
+// `controllers` — that list IS the registration. Nothing here is
+// default-exported.
 ```
 
 ```ts
 // db/public.ts — config-as-code; the deploy auto-migrates additive changes.
 // ONE SCHEMA PER FILE: this is `public`; a sibling `db/billing.ts` declares its own.
+// The schema stays at the ROOT — it is not part of any module.
 import { defineSchema, defineTable, uuid, text, boolean, timestamp, policy, ownedByUser } from "@palbase/backend";
 
 export const todos = defineTable("todos", {
@@ -205,8 +242,8 @@ export const todos = defineTable("todos", {
     completed:  boolean().default(false),
     created_at: timestamp().defaultNow(),
   },
-  rls: true,                                         // every Database.* query runs as the request user
-  policies: [
+  // RLS is ON by default, and `policies` is a CALLBACK — not an array.
+  policies: () => [
     policy("pb_owner_all")
       .for("all")
       .to("authenticated")
@@ -262,54 +299,63 @@ generated client surface) changes; the verb/path do not affect it.
 
 ## Mental model
 
-Every handler type imports service singletons the same way:
+Every handler type reaches the PLATFORM services through the same import:
 
 ```ts
-import { Database, Log, Cache, Queue } from "@palbase/backend";
+import { Database, Log, Cache } from "@palbase/backend";
 ```
 
+(Your OWN services are different: a controller names one as a constructor
+parameter and the container supplies it — see the example above.)
+
 The **only difference** is the trigger argument:
 
 | You are writing… | Handler signature | Trigger arg |
 |------------------|-------------------|-------------|
-| **Endpoints** (`controllers/` class controllers) | method `(…params)` | parameter decorators `@Body`/`@QueryParams`/`@Param`/`@User`/… — [endpoints.md](./endpoints.md) |
+| **Endpoints** (`modules/<domain>/` class controllers) | method `(…params)` | parameter decorators `@Body`/`@QueryParams`/`@Param`/`@User`/… — [endpoints.md](./endpoints.md) |
 | **Jobs** (`jobs/**`) | `(meta)` | `JobMeta` |
 | **Hooks** (`hooks/**`) | `(event, meta)` | typed event + `HookMeta` |
 | **Webhooks** (`webhooks/**`) | `(event, meta)` | typed event + `WebhookMeta` |
 
 `defineMiddleware(fn)` **throws when called**: no bundler reads a `middleware/`
 directory and the engine never calls one, so a handler written against it would
-deploy and never run. There is no `ctx` anywhere on a path that runs — every
-handler above imports its services.
+deploy and never run. There is no `ctx` anywhere on a path that runs — a handler
+imports the platform services it needs.
 
 `meta` carries non-service data: `env` (Environment variables),
-`environmentId`, and for webhooks `requestId`. Services always come from
-the imported singletons — not from `ctx` or any argument.
+`environmentId`, and for webhooks `requestId`. Platform services always come
+from the import — not from `ctx` or any argument.
 
 ## Project shape
 
 ```
 my-backend/
-├── package.json            # depends on @palbase/backend
-├── tsconfig.json           # experimentalDecorators: true (required for the decorators)
-├── controllers/            # @Controller classes: @Get/@Post methods (mount the API)
-│   └── hello.controller.ts # @Controller("/hello") + @Get example
-├── models/<ctrl>/<ep>.ts   # zod schemas, folder per controller, file per endpoint
-│   └── hello/greet.ts      # GreetQuery + HelloResponse (zod value + z.infer type)
-├── services/               # plain classes/singletons your controllers call
-├── db/public.ts            # the database itself: tables, columns, RLS policies
-├── jobs/                   # cron-scheduled jobs (optional)
-├── hooks/                  # auth/storage/document event hooks (optional)
-└── webhooks/               # inbound provider webhooks (optional)
+├── package.json                  # depends on @palbase/backend
+├── tsconfig.json                 # experimentalDecorators + emitDecoratorMetadata (both required)
+├── modules/                      # ONE FOLDER PER DOMAIN — there is no root module
+│   ├── health/
+│   │   ├── health.controller.ts  # @Controller("/health", { auth: false }) + @Get
+│   │   └── health.module.ts      # the four lists that make the class exist
+│   └── notes/
+│       ├── notes.controller.ts   # HTTP only — never imports `Database`
+│       ├── note.service.ts       # @Injectable(); the logic worth testing
+│       ├── note.service.test.ts  # the service, through the container, no database
+│       ├── notes.module.ts       # controllers · providers · exports · imports
+│       └── dto/create.ts         # zod schemas (value + same-named z.infer type)
+├── db/public.ts                  # the database itself: tables, columns, RLS policies
+├── jobs/                         # cron-scheduled jobs (optional)
+├── hooks/                        # auth/storage/document event hooks (optional)
+└── webhooks/                     # inbound provider webhooks (optional)
 ```
 
 There is **no `db/migrations/`**. Nothing generates a migration file, nothing
 commits one and nothing replays one: `db/*.ts` is diffed against the live
 database and applied — see [migrations.md](./migrations.md).
 
-HTTP endpoints are **not** file-path routed. You author a class controller
-(`@Controller("/base")` with `@Get`/`@Post`/… methods); putting it under
-`controllers/` mounts it. See [routing.md](./routing.md).
+HTTP endpoints are **not** file-path routed, and no directory mounts them. You
+author a class controller (`@Controller("/base")` with `@Get`/`@Post`/… methods)
+and a `@Module` lists it in `controllers` — that list is the registration. See
+[routing.md](./routing.md).
 
 ## Documentation
 
@@ -328,5 +374,3 @@ HTTP endpoints are **not** file-path routed. You author a class controller
 
 For AI coding tools: a single concatenated corpus is generated at
 [`llms-full.txt`](./llms-full.txt) (and an index at [`llms.txt`](./llms.txt)).
-</content>
-</invoke>

package/docs/auth.md

@@ -8,17 +8,20 @@ user.
 ```ts
 import { Controller, Get, Post, Body, User, OptionalUser } from "@palbase/backend";
 import type { UserT } from "@palbase/backend";
+import { TodoService } from "./todo.service";
 
 @Controller("/todos")                       // no auth option → every route needs a user
-export default class TodosController {
+export class TodosController {
+  constructor(private readonly todos: TodoService) {}
+
   @Post("")
   create(@Body(CreateTodoBody) body: CreateTodoBody, @User() user: UserT) {
-    return todoService.create(user.id, body.title);   // user is non-null — guaranteed
+    return this.todos.create(user.id, body.title);    // user is non-null — guaranteed
   }
 
   @Get("/featured", { auth: false })        // one public route
   featured(@OptionalUser() user: UserT | null) {
-    return todoService.featured(user?.id ?? null);    // may be null — handle it
+    return this.todos.featured(user?.id ?? null);     // may be null — handle it
   }
 }
 ```
@@ -26,11 +29,12 @@ export default class TodosController {
 ## What `@User()` gives you
 
 ```ts
-interface User {
+interface UserT {          // exported as `UserT`; the value name `User` is the decorator
   id: string;
   email?: string;          // absent for phone-only users
   emailVerified: boolean;
-  role: string;
+  role: string;            // the DATABASE role — always "authenticated" when signed in
+  roles: string[];         // your APPLICATION roles, read per request
   metadata: Record<string, unknown>;
   device: VerifiedDevice | null;
 }
@@ -79,7 +83,7 @@ transaction as the user row.
 
 ```ts
 @Controller("/notes")
-export default class NotesController {
+export class NotesController {
   // Anyone signed in.
   @Get("") list(@User() user: UserT) { … }
 
@@ -197,7 +201,7 @@ publish(@User() user: UserT) {
   if (!user.emailVerified) {
     throw new Forbidden("Confirm your email address before publishing.");
   }
-  return postService.publish(user.id);
+  return this.posts.publish(user.id);
 }
 ```
 

package/docs/background.md

@@ -1,9 +1,10 @@
 # Background Jobs
 
-`jobs/` is the background rail. A job uses the **singleton model** — the same
-imported service singletons as endpoints (`import { Database, Log } from
-"@palbase/backend"`). It does **not** receive a `req`; a small `meta` argument
-carries the non-service data (`env`, correlation ids).
+`jobs/` is the background rail, and it stays at the ROOT — a job is not part of
+any module. It reaches the platform services through the same import as everything
+else (`import { Database, Log } from "@palbase/backend"`). It does **not** receive
+a `req`; a small `meta` argument carries the non-service data (`env`, correlation
+ids).
 
 > **There is no queue.** `Queue.push` and `defineWorker` existed in earlier
 > versions and never ran: nothing consumed the queue, so a push returned a job id
@@ -16,14 +17,22 @@ carries the non-service data (`env`, correlation ids).
 
 ## Jobs (cron-scheduled)
 
-A job runs on a cron schedule. File lives under `jobs/` — the job's name is
-the file name, there is no `name` option.
+A job runs on a cron schedule. The file lives under `jobs/`, one class per file,
+`export default` required.
+
+**`name` is required and DECLARED.** It is the job's identity — the row the
+scheduler holds it under — so it is not taken from the file name any more:
+renaming the file would otherwise start a different job. Lowercase letters,
+digits and dashes.
 
 ```ts
 // jobs/cleanup.ts
 import { Database, Job, Log, type JobMeta } from "@palbase/backend";
 
-@Job({ schedule: "0 3 * * *", timeout: 120 }) // schedule: standard cron; timeout: optional, seconds
+// name: the scheduler's identity; schedule: standard 5-field cron;
+// timeout: optional seconds (default 30, ceiling 300);
+// retry: optional, how many times a FAILED run is retried (default 5, ceiling 10).
+@Job({ name: "cleanup", schedule: "0 3 * * *", timeout: 120 })
 export default class CleanupJob {
   async run(meta: JobMeta) {
     const expired = await Database.$findMany("sessions", { expired: true });

package/docs/database.md

@@ -7,8 +7,9 @@ jobs, hooks, and webhooks all use the same import:
 import { Database } from "@palbase/backend";
 ```
 
-Only **middleware** still uses `ctx.db` (see [background.md](./background.md)
-and [events.md](./events.md) for worker/job/hook/webhook examples).
+There is no `ctx` and no `ctx.db` anywhere on a path that runs — every handler
+imports `Database` (see [background.md](./background.md) and
+[events.md](./events.md) for the job/hook/webhook examples).
 
 ## Typed by default — `Database.<şema>.<tablo>`
 
@@ -76,7 +77,9 @@ await Database.public.crew_presence.findMany({
     AND: [sqlFragment`expires_at > now()`],
   },
 });
-``` The same filter language works for `updateMany`, `deleteMany`,
+```
+
+The same filter language works for `updateMany`, `deleteMany`,
 `count` and `search` — one language, so two spellings cannot drift apart. An
 empty `in` list means NO rows (written into the SQL as `false`), never a silent
 full scan.
@@ -372,7 +375,7 @@ filter object built from request input that happened to come back empty — is
 exactly the shape that must not silently succeed. `count()` with no filter IS
 allowed: counting is a read.
 
-### `Database.query` — raw SQL
+### `Database.$query` — raw SQL
 
 Use it for shapes the helpers do not cover (joins, aggregates, window functions).
 It runs in **the request's own transaction**, not a read-only one: a write inside
@@ -397,7 +400,7 @@ per row with a `23505` caught around each:
 
 ```ts
 await Database.$transaction((tx) => {
-  tx.tables.merchants.insertMany(rows, { onConflict: ["name"], action: "ignore" });
+  tx.public.merchants.insertMany(rows, { onConflict: ["name"], action: "ignore" });
   return null;
 });
 ```
@@ -454,11 +457,11 @@ middle, so nothing holds a database connection open while your code thinks.
 import { Database, NotFound } from "@palbase/backend";
 
 const { orderId } = await Database.$transaction((tx) => {
-  const order = tx.tables.orders
+  const order = tx.public.orders
     .insert({ amount: 1000, status: "pending" })
     .expectOne(new NotFound("order could not be created"));
 
-  tx.tables.order_items.insertMany(
+  tx.public.order_items.insertMany(
     cart.map((line) => ({ order_id: order.id, sku: line.sku })),
   );
 
@@ -514,7 +517,7 @@ filter plus an expectation — which is also stronger, because the check and the
 write are now the same statement and nothing can slip between them:
 
 ```ts
-tx.tables.invites
+tx.public.invites
   .updateWhere({ token, accepted_at: null }, { accepted_at: now() })
   .expectOne(new Conflict("invite already used", "invite_used"));
 ```
@@ -554,7 +557,7 @@ await Database.public.accounts.updateMany({
 
 // Inside a plan: the same expression, the same meaning.
 await Database.$transaction((tx) => {
-  tx.tables.accounts.updateWhere({ id: accountId }, { balance: decrement("5.00") });
+  tx.public.accounts.updateWhere({ id: accountId }, { balance: decrement("5.00") });
   return null;
 });
 ```
@@ -660,7 +663,8 @@ Sometimes you need to read or write **across all users** — an admin endpoint,
 background job that fans out notifications, a cleanup task. For that, call
 `Database.$asService()`. It returns a sibling client that runs as
 **`backend_service_role`** (the role that carries `BYPASSRLS`), exposing the
-exact same surface — `tables`, the raw string ops, and `transaction`:
+exact same surface — `public` (and every other schema), the `$`-prefixed raw ops,
+and `$transaction`:
 
 ```ts
 import { Database } from "@palbase/backend";
@@ -669,32 +673,32 @@ import { Database } from "@palbase/backend";
 const mine = await Database.public.todos.findMany({});
 
 // Service-role bypass: every user's rows. Explicit and greppable.
-const all  = await Database.$asService().tables.todos.findMany({});
-const rows = await Database.$asService().query("SELECT count(*) FROM todos");
+const all  = await Database.$asService().public.todos.findMany({});
+const rows = await Database.$asService().$query("SELECT count(*) FROM todos");
 
 // A service-role transaction (the role is fixed for the whole plan):
-await Database.$asService().transaction((tx) => {
-  tx.tables.todos.updateWhere({ id }, { done: true });
+await Database.$asService().$transaction((tx) => {
+  tx.public.todos.updateWhere({ id }, { done: true });
   return null;
 });
 ```
 
 Guidelines:
 
-- **Be explicit.** Prefer the default `Database.*` and reach for `asService()`
+- **Be explicit.** Prefer the default `Database.*` and reach for `$asService()`
   only where you genuinely need cross-user access. It is intentionally easy to
   grep for in review.
 - **No double-bypass / no nesting.** The sibling does not re-expose
-  `asService()`, and `tx` never exposes it — a plan's role is fixed for the whole
+  `$asService()`, and `tx` never exposes it — a plan's role is fixed for the whole
   transaction. Use `Database.$transaction(...)` for an authenticated one and
-  `Database.$asService().transaction(...)` for a service-role one; you cannot mix
+  `Database.$asService().$transaction(...)` for a service-role one; you cannot mix
   enforced and bypassed operations inside a single plan.
 - **It is a second transaction, on a second connection.** It has to be: the
   Postgres role is bound once, when the transaction opens, so a sibling sharing
   the request's transaction would run as `backend_authenticated` and silently
   keep filtering. Three consequences worth knowing:
   - The request opens it at most once, however many times you call
-    `asService()`, and never at all if you don't use it.
+    `$asService()`, and never at all if you don't use it.
   - Both settle with the request — commit when your handler returns, roll back
     when it throws — but they settle as two transactions. A row written through
     one surface is **not visible** to the other until the request commits.