@palbase/backend 33.0.0 → 33.0.2

package/docs/migrations.md

@@ -90,7 +90,7 @@ Code and schema move at different speeds, so three things keep them together:
 ## Your schema change is not live anywhere you have not applied it
 
 The local stack and every Environment hold their own database, and editing
-Editing `db/*.ts` changes none of them: `palbase db apply` is what moves the local
+`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.
 
@@ -165,10 +165,11 @@ existing data gets there.
 
 ## Row-Level Security
 
-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.public.*` access.
+Add `policies: () => [policy(...)]` to a table in `db/*.ts` — a CALLBACK, not an
+array — and the generated migration emits the `ENABLE ROW LEVEL SECURITY` +
+`CREATE POLICY` DDL. RLS is on by default, so `rls: true` is only worth writing
+as a deliberate deny-all with no policies. See [schema.md](./schema.md) for the
+column builders, the policy DSL, and typed `Database.public.*` access.
 
 ### Hand-writing a policy
 

package/docs/routing.md

@@ -4,8 +4,11 @@ Routes are declared in code with **class controllers**. A controller is a class
 decorated with `@Controller(basePath)`; each route is a method decorated with
 `@Get`/`@Post`/`@Put`/`@Patch`/`@Delete`/`@Query`. Request input + context are
 injected into the method via **parameter decorators** (`@Body`/`@QueryParams`/
-`@Param`/`@User`/…). Putting a controller file under `controllers/` mounts it —
-there is no central router and no manual registration.
+`@Param`/`@User`/…). A controller is mounted by being LISTED: its module names
+it in `controllers`, and that list is the only place ownership is decided. A
+class no module lists does not exist — the build refuses it by name, and it
+never reaches the route table or the OpenAPI document. Being in a particular
+folder grants nothing.
 
 ```ts
 import { Controller, Get, Post, Body, QueryParams, Param, User } from "@palbase/backend";
@@ -14,31 +17,51 @@ import { Controller, Get, Post, Body, QueryParams, Param, User } from "@palbase/
 ## Controllers — class + method decorators
 
 `@Controller(basePath)` marks the class and sets the mount path. Each route
-method declares its verb + subpath; the real work lives in a `services/` class
-(the controller method is thin).
+method declares its verb + subpath; the real work lives in an `@Injectable()`
+service that arrives through the CONSTRUCTOR (the controller method is thin).
 
 ```ts
-// controllers/places.controller.ts
+// modules/places/places.controller.ts
 import { Controller, Get, Post, Body, User } from "@palbase/backend";
 import type { UserT } from "@palbase/backend";
-import { placeService } from "../services/place.service.js";
-import { ImportNearbyBody } from "../models/places/import.js";
-import type { PlaceSchema } from "../models/places/shared.js";  // the return TYPE names the 200 schema
+import { PlaceService } from "./place.service.js";
+import { ImportNearbyBody } from "./dto/import.js";
+import { PlaceSchema } from "./dto/shared.js";  // the return TYPE names the 200 schema
 
 @Controller("/places")
-export default class PlacesController {
+export class PlacesController {
+  constructor(private readonly places: PlaceService) {}
+
   @Post("/import")
   importNearby(@Body(ImportNearbyBody) body: ImportNearbyBody, @User() user: UserT): PlaceSchema {
-    return placeService.importNearby(body.lat, body.lng, user.id);
+    return this.places.importNearby(body.lat, body.lng, user.id);
   }
 
   @Get("/favorites", { auth: false })
   listFavorites(): PlaceSchema[] {
-    return placeService.listFavorites();
+    return this.places.listFavorites();
   }
 }
 ```
 
+The class is mounted by being LISTED, and nothing else mounts it:
+
+```ts
+// modules/places/places.module.ts
+import { Module, type Token } from "@palbase/backend";
+
+import { PlacesController } from "./places.controller.js";
+import { PlaceService } from "./place.service.js";
+
+@Module({
+  controllers: [PlacesController as Token],
+  providers: [PlaceService as Token],
+  exports: [],
+  imports: [],
+})
+export class PlacesModule {}
+```
+
 | Method name | Verb | Full path | operationId (dotted) |
 |---|---|---|---|
 | `importNearby`  | POST | `/places/import`    | `places.importNearby` |

package/docs/schema.md

@@ -19,9 +19,10 @@ those values — never a dictionary, because a name in a dictionary key is a sec
 place the name is written, and a table built under a key does not yet know what
 to call itself when a sibling references it.
 
-Each table's only required field is `columns`; `rls` and `policies` enable
-[Row-Level Security](#row-level-security-rls), and `indexes` declares plain
-btree [indexes](#indexes).
+Each table's only required field is `columns`; `policies` (a callback — see
+[Row-Level Security](#row-level-security-rls)) declares the RLS rules, `rls`
+toggles enforcement (default `true`), and `indexes` declares plain btree
+[indexes](#indexes).
 
 ```ts
 import {
@@ -447,14 +448,28 @@ You do **not** wire anything per endpoint. Saving a file under `db/` regenerates
 of the schema, no generic, no cast:
 
 ```ts
-// services/room.service.ts — the layer that touches the database.
-import { Database } from "@palbase/backend";
+// modules/rooms/room.service.ts — the layer that touches the database.
+import { Database, Injectable } from "@palbase/backend";
+import type { Tables } from "@palbase/backend/env";
+
+type Room = Tables["rooms"]["row"];               // typed from your db/*.ts
 
-type RoomsTable = typeof Database.public.rooms;   // typed from your db/*.ts
+/** `Database.public.rooms` is a VALUE, and a dependency is named by its
+ * parameter's TYPE — so the seam is an `abstract class`, one table wide. */
+export abstract class RoomRepo {
+  abstract insert(row: { name: string }): Promise<Room>;
+}
 
+@Injectable()
+export class DbRoomRepo extends RoomRepo {
+  insert(row: { name: string }): Promise<Room> {
+    return Database.public.rooms.insert(row);     // typed: rooms.nope ← compile error
+  }
+}
+
+@Injectable()
 export class RoomService {
-  private readonly rooms: RoomsTable;
-  constructor(rooms: RoomsTable) { this.rooms = rooms; }
+  constructor(private readonly rooms: RoomRepo) {}
 
   async create(name: string) {
     const room = await this.rooms.insert({ name });
@@ -462,41 +477,48 @@ export class RoomService {
     // room.nope ← compile error
   }
 }
-
 ```
 
 ```ts
-// rooms.module.ts
+// modules/rooms/rooms.module.ts — the four lists that make these classes exist.
 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] })
+import { RoomsController } from "./rooms.controller.ts";
+import { DbRoomRepo, RoomService } from "./room.service.ts";
+
+@Module({
+  controllers: [RoomsController as Token],
+  providers: [RoomService as Token, DbRoomRepo as Token],
+  exports: [],
+  imports: [],
+})
 export class RoomsModule {}
 ```
 
 ```ts
-// controllers/rooms.controller.ts — HTTP only; no `Database` import here.
+// modules/rooms/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 "./room.service";
 
 const CreateRoomBody = z.object({ name: z.string() });
 const RoomOut = z.object({ id: z.string(), name: z.string() });
 
 @Controller("/rooms")
-export default class RoomsController {
+export class RoomsController {
+  constructor(private readonly rooms: RoomService) {}
+
   @Post("")
   // The return type names the 200 schema — `z.infer<typeof RoomOut>` works
   // inline, no separate `export type` needed.
   create(@Body(CreateRoomBody) body: z.infer<typeof CreateRoomBody>): Promise<z.infer<typeof RoomOut>> {
-    return roomService.create(body.name);
+    return this.rooms.create(body.name);
   }
 }
 ```
 
-`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
+`Database.public.<name>` exposes `insert(values)`,
+`update({ where: { id }, set })`, `delete(id)`, `findById(id)`,
+`findMany(query?)`. `Database.$transaction(fn)` yields a `tx`
+whose `tx.public.<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
@@ -518,10 +540,11 @@ missing `WHERE user_id = …` in your handler can no longer leak another user's
 rows — the policy enforces it. This is the recommended way to scope data per
 user.
 
-Add `policies` (and optionally `rls`) to a table. `policies` being non-empty
-implies `rls: true` automatically (a table with policies must have RLS enabled
-or the policies are inert). Set `rls: true` with no policies only as a
-deliberate deny-all intermediate step.
+Add `policies` to a table — a **callback** returning the list, `policies: () =>
+[…]`, not a bare array. RLS defaults to `true`, and a non-empty `policies` forces
+it on regardless (a table with policies must have RLS enabled or the policies are
+inert). Write `rls: true` with no policies only as a deliberate deny-all
+intermediate step.
 
 ### The `policy()` builder
 
@@ -588,15 +611,17 @@ from `auth.uid()`, so a policy cannot ask about somebody else. A revoked role is
 gone from the very next statement; there is nothing cached.
 
 ```ts
-policy("notes_owner").for("all")
-  .using("user_id = (select auth.uid())")
-  .withCheck("user_id = (select auth.uid())"),
-
-// Moderation. Permissive policies are OR'd, so these widen only.
-policy("notes_moderate_read").for("select")
-  .using("(select auth.has_permission('notes.delete_any'))"),
-policy("notes_delete_any").for("delete")
-  .using("(select auth.has_permission('notes.delete_any'))"),
+policies: () => [
+  policy("notes_owner").for("all")
+    .using("user_id = (select auth.uid())")
+    .withCheck("user_id = (select auth.uid())"),
+
+  // Moderation. Permissive policies are OR'd, so these widen only.
+  policy("notes_moderate_read").for("select")
+    .using("(select auth.has_permission('notes.delete_any'))"),
+  policy("notes_delete_any").for("delete")
+    .using("(select auth.has_permission('notes.delete_any'))"),
+],
 ```
 
 > **The read policy is not optional.** `DELETE … WHERE id = $1` has to FIND the
@@ -626,8 +651,8 @@ export const todos = defineTable("todos", {
     done:       boolean().default(false),
     created_at: timestamp().defaultNow(),
   },
-  // `policies` non-empty ⇒ RLS is enabled + FORCEd automatically.
-  policies: [
+  // `policies` is a CALLBACK. Non-empty ⇒ RLS is enabled + FORCEd automatically.
+  policies: () => [
     // Read: a user sees only their own todos.
     policy("pb_todos_owner_select")
       .for("select")

package/docs/services.md

@@ -3,7 +3,7 @@
 **Two different things are called "services" here, and this page is the second
 one.** Read the first paragraph before searching this page for a layout rule.
 
-- **YOUR service layer** — `services/<name>.service.ts`, the plain classes your
+- **YOUR service layer** — `modules/<domain>/<name>.service.ts`, the `@Injectable()` classes your
   own business logic lives in. The scaffold ships one, and the contract is at
   the bottom of this page: [Your own service layer](#your-own-service-layer).
 - **THE service singletons** — the platform objects you import from
@@ -26,9 +26,26 @@ turns out to be empty — it fails at the import.
 a channel, but cannot subscribe (a stateless request can't hold a socket).
 Subscription lives on the client SDK (`pb.realtime`).
 
+`Auth` is available here for exactly one thing: **granting and revoking roles**.
+Signing in, signing up and session handling run on the client SDK — a backend
+handler never holds a user's credentials — but assignment is server work, so
+`assignRole`, `revokeRole` and `rolesOf` are on this side:
+
+```ts
+import { Auth } from "@palbase/backend";
+
+await Auth.assignRole(userId, "moderator");   // takes effect on the next request
+await Auth.revokeRole(userId, "moderator");   // and so does this
+const held = await Auth.rolesOf(userId);      // string[]
+```
+
+A role that does not exist throws `RoleNotDefined` naming it — declare it first
+with `palbase roles create`. A failed read throws rather than answering `[]`:
+"nobody could say" and "holds nothing" are different claims, and a handler that
+confuses them denies a user everything they hold.
+
 **Not available to backend handlers** (do not import them here): Functions, CMS,
-Links, Analytics, and Auth. Auth runs on the client SDK; the others are out of
-scope for backend endpoints.
+Links and Analytics — out of scope for backend endpoints.
 
 ## Cache
 
@@ -158,7 +175,7 @@ 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
   anonymous request (no signed-in user).
-- `Flags.asService()` returns the cross-user admin surface
+- `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()`.
@@ -167,8 +184,8 @@ Writes mirror the `Database` / `Database.$asService()` model:
 // Current request user — no userId needed:
 await Flags.setOverride("new-checkout", true);
 
-// Cross-user admin write — explicit target, via asService():
-await Flags.asService().setOverrideForUser("user_123", "new-checkout", true);
+// Cross-user admin write — explicit target, via $asService():
+await Flags.$asService().setOverrideForUser("user_123", "new-checkout", true);
 ```
 
 ## Realtime
@@ -219,8 +236,8 @@ to drive live chat, presence, dashboards, and other push features.
 ## Your own service layer
 
 The singletons above are what a service CALLS. This section is the layer that
-calls them — `services/<name>.service.ts`, which the scaffold ships a working
-example of (`services/note.service.ts` and the controller that uses it).
+calls them — `modules/<domain>/<name>.service.ts`, which the scaffold ships a working
+example of (`modules/notes/note.service.ts` and the controller that uses it).
 
 The contract is three rules, and the scaffold's own test enforces all three:
 
@@ -235,7 +252,7 @@ it.** Mark the class `@Injectable()` and name what it needs as ordinary
 constructor parameters:
 
 ```ts
-// services/note.service.ts
+// modules/notes/note.service.ts
 import { Database, Injectable } from "@palbase/backend";
 
 type NotesTable = typeof Database.public.notes;
@@ -251,7 +268,7 @@ export class NoteService {
 ```
 
 ```ts
-// services/report.service.ts — a service that depends on another service
+// modules/reports/report.service.ts — a service that depends on another service
 import { Injectable } from "@palbase/backend";
 import { NoteService } from "./note.service.ts";
 
@@ -268,7 +285,7 @@ export class ReportService {
 A controller asks the same way, and nothing wires it by hand:
 
 ```ts
-// controllers/notes.controller.ts
+// modules/notes/notes.controller.ts
 import { Controller, Get } from "@palbase/backend";
 import { NoteService } from "../services/note.service.ts";
 
@@ -310,7 +327,7 @@ 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 { NotesController } from "./modules/notes/notes.controller.ts";
 import { NoteService } from "./services/note.service.ts";
 import { ReportService } from "./services/report.service.ts";
 
@@ -363,7 +380,7 @@ NoteService())` is ordinary TypeScript, and the container is not required for it
 to work.
 
 ```ts
-// services/note.service.test.ts — `npm test`, no database
+// modules/notes/note.service.test.ts — `npm test`, no database
 import { test } from "node:test";
 import assert from "node:assert/strict";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palbase/backend",
-  "version": "33.0.0",
+  "version": "33.0.2",
   "description": "Palbase Backend SDK — class controllers (@Controller/@Get/@Post + @Body/@QueryParams/@Param), error classes, schema DSL",
   "license": "MIT",
   "repository": {
@@ -91,6 +91,7 @@
   "files": [
     "dist",
     "docs",
+    "stack-images.json",
     "stager",
     "template"
   ],

package/stack-images.json

@@ -0,0 +1,24 @@
+{
+  "33": [
+    {
+      "env": "PALBASE_PALSVC_IMAGE",
+      "ref": "ghcr.io/palgroup/palbase/palsvc:0.42.0",
+      "build": "cd v2 && DOCKER_BUILDKIT=1 docker build -t palbase-palsvc -f Dockerfile ."
+    },
+    {
+      "env": "PALBASE_RUNTIME_IMAGE",
+      "ref": "ghcr.io/palgroup/palbase/runtime-dev:0.42.0",
+      "build": "cd v2/runtime && DOCKER_BUILDKIT=1 docker build --target dev -t palbase-runtime-dev -f Dockerfile ."
+    },
+    {
+      "env": "PALBASE_EDGE_IMAGE",
+      "ref": "ghcr.io/palgroup/palbase/edge:0.42.0",
+      "build": "cd v2/deploy/envoy && DOCKER_BUILDKIT=1 docker build -t palbase-edge ."
+    },
+    {
+      "env": "PALBASE_POSTGRES_IMAGE",
+      "ref": "pgvector/pgvector:pg16",
+      "build": ""
+    }
+  ]
+}

package/template/AGENTS.md

@@ -44,7 +44,7 @@ shape you find there is the shape to copy.
 | A business rule, a calculation, an ordering | the service |
 | Return an HTTP status | `throw new NotFound(…)` in the controller (or the service — no request object needed) |
 | Call another feature | name its class in your constructor — its module must `exports` it and yours must `imports` that module |
-| Scheduled or background work | a `@Job` class in `jobs/` — **there is no queue** |
+| Scheduled or background work | a `@Job` class listed in a module's `providers` — **there is no queue** |
 | Read a setting or a secret | `Secrets.get(name)` / `Flags.isEnabled(name)` — the names are checked by the compiler |
 | Share code between controllers | a plain module they import; not a base class, not middleware |
 
@@ -86,12 +86,12 @@ wrong in this runtime:
 - **An inline return type** — `Promise<{ ok: boolean }>`, a union, or a bare
   `interface`. The deploy REFUSES it; name a zod schema.
 
-**A controller is exported by NAME, and no file is default-exported.** Its module
-imports it (`import { NotesController } from "./notes.controller"`) to
-list it in `controllers` — that list is the registration, and a class no list
-names is refused at build. (`export default` **is** required for `jobs/`,
-`webhooks/`, `hooks/` and `db/public.ts`, one class per file — those are read off
-disk by name, not through a module.)
+**A controller is exported by NAME, and no file is default-exported.** Its module imports
+it (`import { NotesController } from "./notes.controller"`) to list it in `controllers`;
+that list is the registration. `@Job`, `@Webhook`, `@Hook` and `@Room` go in the same
+module's `providers`. There is no `jobs/`, `webhooks/` or `hooks/` directory and nothing
+reads one — a surface class no module lists is never imported, so its decorator never
+runs and nothing says so. Only the schema is read by location: `db/*.ts`, one per schema.
 
 **Class and method names are your public API.** `NotesController.list` generates
 `pb.notes.list()`. Renaming either renames the call in every app; the verb and the

package/template/modules/health/health.controller.ts

@@ -3,15 +3,18 @@ import { Controller, Get, z } from "@palbase/backend";
 // A route's success response IS its return type — a NAMED zod schema, read by
 // both the runtime (output validation) and the client codegen. Small projects
 // declare it beside the route; once a controller grows, move the schemas to
-// `models/<controller>/<endpoint>.ts` and import them.
+// `dto/<endpoint>.ts` inside the same module and import them — the way
+// `modules/notes/dto/create.ts` does.
 export const HealthResponse = z.object({
   status: z.string(),
 });
 export type HealthResponse = z.infer<typeof HealthResponse>;
 
-// A controller is a CLASS whose methods are routes. There is no module to
-// register it in and no export to remember: `@Controller` records the class,
-// and importing the file is the registration.
+// A controller is a CLASS whose methods are routes, and `health.module.ts`
+// beside this file is what REGISTERS it: the module imports the class by name
+// and lists it in `controllers`. That list is the registration — a class no
+// module names is refused at build, by name. `@Controller` describes the class;
+// it does not enrol it, and neither does the folder the file sits in.
 //
 // The full path is the controller base + the method subpath, so this serves
 // `GET /health`. The generated clients call it `pb.health.check()` —

package/template/modules/notes/dto/create.ts

@@ -1,8 +1,9 @@
 import { z } from "@palbase/backend";
 
-// SCHEMAS LIVE HERE once a controller has more than a screen of them:
-// `models/<controller>/<endpoint>.ts`. Nothing discovers this directory — it is
-// an ordinary import path — so the shape is yours. What is NOT optional is the
+// SCHEMAS LIVE HERE once a controller has more than a screen of them: the
+// module's own `dto/<endpoint>.ts`, which is where this file sits. Nothing
+// discovers this directory — it is an ordinary import path — so the shape is
+// yours. What is NOT optional is the
 // double export below.
 //
 // Each name is exported TWICE, under the SAME name:

package/template/modules/notes/notes.controller.ts

@@ -4,7 +4,7 @@ import type { UserT } from "@palbase/backend";
 import { CreateNoteBody, NoteSchema } from "./dto/create";
 import { NoteService } from "./note.service";
 
-// The other half of the vertical that starts in `services/note.service.ts`.
+// The other half of the vertical that starts in `./note.service.ts`.
 //
 // Everything a controller does here is HTTP: validate the body through a named
 // schema, name the 200 shape as the return type, turn a missing row into a
@@ -22,12 +22,14 @@ import { NoteService } from "./note.service";
 // container builds the graph once at boot.
 //
 // A class no module lists does not exist — it is refused at build, by name, and
-// never reaches the route table or the OpenAPI document. Being in `controllers/`
-// grants nothing; being in a module's list is what does.
+// never reaches the route table or the OpenAPI document. WHERE the file sits
+// grants nothing: the bundler walks the tree for `*.module.ts` and reads
+// nothing else, so a class reached by no module is never even imported. Being
+// in a module's list is what does it.
 
-// The schemas are in `models/notes/create.ts`. A controller with one endpoint
-// can keep them beside the routes; the moment there are two, they go to
-// `models/`, and this scaffold ships them already moved — because the shape you
+// The schemas are in `./dto/create.ts`. A controller with one endpoint can keep
+// them beside the routes; the moment there are two, they go to the module's
+// `dto/`, and this scaffold ships them already moved — because the shape you
 // find here is the shape the next file copies.
 
 // Auth is required unless a route opts out, so `@User()` is non-null here and