@palbase/backend 25.1.0 → 27.1.0

package/template/AGENTS.md

@@ -1,8 +1,9 @@
 # Palbase backend project
 
-You write TypeScript files; the runtime discovers them **by location** and serves
-them as a typed HTTP API, then generates the client SDKs your apps call. There is
-no router to register with, no module to list things in, no DI container.
+You write TypeScript classes and ONE module lists them; the runtime serves them
+as a typed HTTP API and generates the client SDKs your apps call. There is no
+router to register with — a `@Module` says what exists, who owns it and what it
+may reach, and a class no module lists does not exist.
 
 Everything comes from one package:
 
@@ -10,21 +11,22 @@ Everything comes from one package:
 import { Controller, Get, Post, Body, Param, User, z, Database, NotFound } from "@palbase/backend";
 ```
 
-> Needs `experimentalDecorators: true` — already set in this scaffold's
-> `tsconfig.json`. Legacy decorators; no `reflect-metadata`.
+> Needs `experimentalDecorators: true` and `emitDecoratorMetadata: true` — both
+> already set in this scaffold's `tsconfig.json`. The container reads a
+> constructor's parameter TYPES out of that metadata; without it every injected
+> field would arrive `undefined`, and the build says so by name.
 
-**The full reference** — every decorator, every service singleton, every schema
-helper — is at <https://app.dev.palbase.studio/llms.txt> (one file for agents:
-`/llms-full.txt`). This file does not repeat it. This file says what the code
-should LOOK like.
+**The full reference** — every decorator, every platform service, every schema
+helper — is at <https://app.dev.palbase.studio/llms.txt> (`/llms-full.txt` for
+agents). This file does not repeat it; it says what the code should LOOK like.
 
 ## The layers
 
 | Layer | DOES | NEVER |
 |---|---|---|
-| `controllers/<name>.controller.ts` | HTTP only: validate the body through a named schema, name the 200 shape as the return type, turn a missing row into a status | imports `Database` / `Storage` / `Cache` · holds business rules · stores per-request state on the instance |
-| `services/<name>.service.ts` | the decisions: which rows, whose, in what order; throws the error classes | knows about HTTP (no `req`, no `res`) · reaches for a singleton itself — it takes its dependency through the constructor |
-| `models/<controller>/<endpoint>.ts` | zod schemas, exported twice under one name: a VALUE and a same-named `z.infer` TYPE | holds logic |
+| `modules/<domain>/<name>.controller.ts` | HTTP only: validate the body through a named schema, name the 200 shape as the return type, turn a missing row into a status | imports `Database` / `Storage` / `Cache` · holds business rules · stores per-request state on the instance |
+| `modules/<domain>/<name>.service.ts` | the decisions: which rows, whose, in what order; throws the error classes | knows about HTTP (no `req`, no `res`) · reaches for a singleton itself — it takes its dependency through the constructor |
+| `modules/<domain>/dto/<endpoint>.ts` | zod schemas, exported twice under one name: a VALUE and a same-named `z.infer` TYPE | holds logic |
 | `db/public.ts` | IS the database: tables, columns, RLS policies | produces migration files — there are none |
 
 In one line: **controllers thin, services thick, models quiet, schema the single
@@ -37,11 +39,11 @@ shape you find there is the shape to copy.
 
 | The need | Its home |
 |---|---|
-| Validate input | a zod schema in `models/`, passed to `@Body(Schema)` |
+| Validate input | a zod schema in the module's `dto/`, passed to `@Body(Schema)` |
 | Enforce ownership | an RLS policy in `db/public.ts` **and** the service's `where` — the policy is the backstop, not the reason to stop writing the filter |
 | 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 | import its service singleton |
+| 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** |
 | 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 |
@@ -51,37 +53,45 @@ shape you find there is the shape to copy.
 These are what a language model reaches for by default. Every one of them is
 wrong in this runtime:
 
-- **Express-style handlers** — `app.get(...)`, `(req, res) => …`, `req.params`,
-  `req.body`. A route is a **method on a class**.
-- **A `ctx` object** — services are imported directly. There is no context to
-  thread, and no handler signature that receives one.
-- **A DI container, or injection via decorators** — the only supported way to hold
-  a dependency is a module-level singleton. A controller, job, hook or webhook is
-  constructed with **no arguments**; one that declares a constructor parameter is
-  refused with the class named — at decoration time for `jobs/`, `hooks/` and
-  `webhooks/`, and when the route table is built at boot for a controller. The
-  release never serves either way.
+- **Express-style handlers** — `app.get(...)`, `(req, res) => …`, `req.params`, `req.body`. A route is a **method on a class**.
+- **A `ctx` object** — there is no context to thread and no handler receives one.
+- **`@Inject`, `useFactory`, `forwardRef`, or a token registry** — a dependency
+  is named by its constructor parameter's TYPE and by nothing else. None of them
+  exists here and none is needed: a real cycle cannot be built (the import dies
+  first), so there is nothing for `forwardRef` to rescue. Mark the class
+  `@Injectable()`, name what it needs, list it in a module's `providers`. An
+  `interface` cannot be a dependency (no runtime existence) — use a class or an
+  `abstract class`.
+- **A class that no module lists** — refused at build, by name; it never reaches
+  the route table, the dispatcher or the OpenAPI document. Being in
+  a folder grants nothing; being in a module's list is what does.
+- **I/O in a constructor** — it runs while the app comes up, is synchronous, and
+  stays pure wiring. Startup work goes in `onStart`, awaited before request one.
 - **`middleware/`** — nothing mounts it and the engine has no middleware pipeline.
   Code written against it deploys, never runs, and nothing reports it. Put
   cross-cutting work in a service; use route options for auth and rate limits.
-- **A repository or DAO layer** — `Database.tables.<name>` is already typed from
-  your schema. A wrapper over it buys nothing and hides the seam.
+- **A DAO layer over the whole database**, or a generic `Repository<T>` — the
+  first re-exposes what `Database.public.<name>` already types; the second is
+  refused outright, because a generic has no runtime type to read. The scaffold's
+  seam is narrower: one `abstract class` naming ONE table's methods, and one
+  `@Injectable()` class that `extends` it.
 - **A migration file** — there are none anywhere in this product. `db/public.ts`
   is diffed against the live database and applied.
-- **`process.env`** for configuration — a secret is read with `Secrets.get()`, and
-  its value never enters this repository.
+- **`process.env`** for configuration — read a secret with `Secrets.get()`; its
+  value never enters this repository.
 - **`try { … } catch { return 500 }`** — throw the error class and let the runtime
   build the envelope. Swallowing it turns a 404 into a 500.
-- **Hand-built responses** — no `JSON.stringify`, no `new Response(...)`. The 200
+- **Hand-built responses** — no `JSON.stringify`, no `new Response(...)`; the 200
   body IS the schema your return type names.
 - **An inline return type** — `Promise<{ ok: boolean }>`, a union, or a bare
-  `interface`. The deploy REFUSES it. Name a zod schema.
+  `interface`. The deploy REFUSES it; name a zod schema.
 
-**A controller needs no export.** `@Controller` records the class as it decorates
-it, so importing the file IS the registration — this scaffold's own
-`HealthController` and `NotesController` are not exported. (`export default` **is**
-required for `jobs/`, `webhooks/`, `hooks/` and `db/public.ts`, one class per
-file.)
+**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.)
 
 **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
@@ -92,63 +102,92 @@ path do not affect it, so restructure paths freely and rename these two carefull
 1. `db/public.ts` — declare the table and its RLS policies.
 2. `palbase db plan` — read what would change.
 3. `palbase db apply` — apply it in one transaction.
-4. `models/<controller>/<endpoint>.ts` — the schema, as a value and a type.
-5. `services/<name>.service.ts` — the logic; take the dependency through the
-   constructor, wire the singleton on the last line.
-6. `controllers/<name>.controller.ts` — the routes; import the service, never
-   `Database`.
-7. `palbase build` — regenerates `palbase-env.d.ts` and `palbase-stack.d.ts`.
+4. `modules/<domain>/dto/<endpoint>.ts` — the schema, as a value and a type.
+5. `modules/<domain>/<name>.service.ts` — the logic; `@Injectable()`, and name what it
+   needs as constructor parameters. Nothing is wired by hand.
+6. `modules/<domain>/<name>.controller.ts` — the routes; name the service in the
+   constructor, never import `Database`.
+7. `modules/<domain>/<domain>.module.ts` — list them. A new domain is a FOLDER.
+   Until a module names it, the class does not exist.
+8. `palbase build` — regenerates `palbase-env.d.ts` and `palbase-stack.d.ts`.
    Commit both.
-8. `npm test` — exercise the service.
+9. `npm test` — exercise the service.
 
 ## The service shape, exactly
 
 ```ts
-// services/note.service.ts
-import { Database } from "@palbase/backend";
+// modules/notes/note.service.ts
+import { Database, Injectable } from "@palbase/backend";
+
+// `Database.public.notes` is a VALUE, so it cannot BE a dependency — a
+// dependency is named by its parameter's TYPE. Naming one table behind an
+// `abstract class` is what gives the service a seam, and keeps that seam one
+// table wide.
+export abstract class NoteRepo {
+  abstract findMany(where: { user_id: string }): Promise<Note[]>;
+}
 
-type NotesTable = typeof Database.tables.notes;
+@Injectable()
+export class DbNoteRepo extends NoteRepo {
+  findMany(where: { user_id: string }) {
+    return Database.public.notes.findMany(where);
+  }
+}
 
+@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, and refused for the whole
-  // FILE, so one of them anywhere in a test's import graph reads like a dozen
-  // broken tests and is one keyword.
-  constructor(notes: NotesTable) {
-    this.notes = notes;
-  }
+  // The container supplies this. Nothing registers it and nothing wires it.
+  constructor(private readonly notes: NoteRepo) {}
 
   list(userId: string) {
     return this.notes.findMany({ user_id: userId });
   }
 }
+```
 
-/** Controllers import THIS, never the class. */
-export const noteService = new NoteService(Database.tables.notes);
+```ts
+// notes.module.ts — named after the DOMAIN. There is no AppModule.
+@Module({
+  controllers: [NotesController],
+  providers: [NoteService, DbNoteRepo],
+  exports: [],   // nothing outside may reach these until a name is added here
+  imports: [],   // whose exports THIS module may reach
+})
+export class NotesModule {}
 ```
 
-The constructor is the seam, and it is the whole reason the layer pays off: a test
-hands in a stand-in and never needs a database. `services/note.service.test.ts` in
-this scaffold is that test — read it before writing your own.
+The constructor is the seam: a test hands in a stand-in and never needs a
+database. `modules/notes/note.service.test.ts` is that test — read it first.
+
+The abstraction is the TOKEN, the implementation is the PROVIDER: `DbNoteRepo` is
+listed, `NoteRepo` is not. The container finds the single class that `extends` it
+— zero or two, and the build refuses by name. Listing the `abstract class` itself
+is refused too: `new NoteRepo()` succeeds and returns an object missing every
+abstract member.
 
 ## Tests
 
-`npm test` runs the scaffold's canary test by name and then discovers the rest.
-The canary is named on purpose: a glob that matches nothing exits **0**, so a
-project whose tests silently stopped being discovered would report success.
+`npm test` runs `bun test` through `scripts/test.sh`. The wrapper reads the
+SUMMARY, not just the exit code: `bun test` exits **0** and prints nothing when
+something calls `process.exit()` mid-suite, and a run that discovered zero tests
+also exits 0. Either one exits **90** instead. Do not call `bun test` directly.
 
 Test the **service** layer. Controllers are thin by construction, so what can be
-wrong lives in a service — a plain class you construct directly with a stand-in.
-For a stand-in covering the whole database surface rather than one table, use
-`fakeDatabase()` from `@palbase/backend/test`; it answers from memory and does not
-enforce RLS, constraints or unique violations.
+wrong lives in a service, and you reach it through the container:
+
+```ts
+import { isolated } from "@palbase/backend/test";
+const svc = isolated().with(NoteRepo, new FakeRepo()).get(NoteService);
+```
+
+`isolated()` rebuilds the graph with the override in place. The substitution is
+DEEP — it works the same two hops below the class under test — and touches no
+process-wide state. For a stand-in covering the whole database rather than one
+table, use `fakeDatabase()` from `@palbase/backend/test`; it answers from memory
+and enforces no RLS, constraints or unique violations.
 
-Node **strips** types, it never emits code, so parameter properties, `enum` and
-`namespace` fail with `ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX` — per FILE. Relative
-imports inside a test need the extension (`./note.service.ts`); this scaffold's
-`tsconfig.json` allows it.
+Relative imports inside a test need the extension (`./note.service.ts`); this
+scaffold's `tsconfig.json` allows it.
 
 `npm test` answers "is the logic right". It is not the deploy's own validation —
 decorators, return types, SDK major — which answers "would this ship".
@@ -156,5 +195,4 @@ decorators, return types, SDK major — which answers "would this ship".
 ## Commands
 
 `palbase --help` is authoritative; a copy of the command surface inside this
-repository goes stale silently. The full SDK reference is at
-<https://app.dev.palbase.studio/llms.txt>.
+repository goes stale silently.

package/template/db/public.ts

@@ -22,7 +22,7 @@ const notes = defineTable("notes", {
     body: text().notNull(),
     created_at: timestamp().defaultNow(),
   },
-  policies: [
+  policies: () => [
     // Postgres enforces ownership, not the handler: a query that forgets
     // its `where user_id = …` still cannot see another user's rows.
     policy("notes_owner")

package/template/{controllers → modules/health}/health.controller.ts

@@ -22,7 +22,7 @@ export type HealthResponse = z.infer<typeof HealthResponse>;
 // Auth is required unless a route opts out. A health check is the rare route
 // that genuinely has no caller identity, hence `auth: false`.
 @Controller("/health", { auth: false })
-class HealthController {
+export class HealthController {
   @Get("")
   check(): HealthResponse {
     return { status: "ok" };

package/template/modules/health/health.module.ts

@@ -0,0 +1,24 @@
+import { Module, type Token } from "@palbase/backend";
+
+import { HealthController } from "./health.controller.ts";
+
+/**
+ * "Is this process answering?" — a domain like any other.
+ *
+ * There is NO root module in this system, and that is why you will not find an
+ * `app.module.ts` here. Nest has one because Nest mounts a tree: `AppModule`
+ * imports every feature module and the app is what that file lists. Here each
+ * `*.module.ts` is found wherever it lives, so a file named after the app would
+ * root nothing, list nothing, and teach a shape the runtime does not have.
+ *
+ * The rule has no exceptions, which is the point: EVERY domain is a folder under
+ * `modules/`, including this one. Adding a domain is adding a folder — never a
+ * line in a file every branch edits.
+ */
+@Module({
+  controllers: [HealthController as Token],
+  providers: [],
+  exports: [],
+  imports: [],
+})
+export class HealthModule {}

package/template/modules/notes/note.service.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "bun:test";
+import { isolated } from "@palbase/backend/test";
+
+import { NoteRepo, NoteService, type Note } from "./note.service.ts";
+
+// WHY THIS TEST NEEDS NO DATABASE
+//
+// `NoteService` asks for a `NoteRepo` and the container supplies it. A test
+// supplies a different one — `isolated()` rebuilds the graph with the override
+// in place and touches no process-wide state, so the next test in this file does
+// not meet whatever this one substituted.
+//
+// The substitution is DEEP: it would work the same if `NoteRepo` were two hops
+// below the class under test. That is what makes the constructor worth using as
+// the seam.
+//
+// Test your own services the same way.
+
+class FakeRepo extends NoteRepo {
+  readonly seen: unknown[] = [];
+  async findMany(where: { user_id: string }): Promise<Note[]> {
+    this.seen.push(where);
+    return [];
+  }
+  async insert(row: { user_id: string; body: string }): Promise<Note> {
+    return { id: "n_1", user_id: row.user_id, body: row.body } as Note;
+  }
+  async findById(): Promise<Note | null> {
+    return null;
+  }
+  async delete(): Promise<void> {}
+}
+
+describe("NoteService", () => {
+  it("asks only for the caller's notes", async () => {
+    const repo = new FakeRepo();
+    const svc = isolated().with(NoteRepo, repo).get(NoteService);
+
+    await svc.list("u_1");
+
+    expect(repo.seen).toEqual([{ user_id: "u_1" }]);
+  });
+
+  it("writes ownership from the CALLER, never from the body", async () => {
+    const svc = isolated().with(NoteRepo, new FakeRepo()).get(NoteService);
+    const note = await svc.create("u_1", "hello");
+    expect(note.user_id).toBe("u_1");
+  });
+});

package/template/modules/notes/note.service.ts

@@ -0,0 +1,108 @@
+import { Database, Injectable } from "@palbase/backend";
+import type { Tables } from "@palbase/backend/env";
+
+// A SERVICE is where the logic lives, and `@Injectable()` is the whole
+// declaration: it says this class can be resolved. Nothing registers it and
+// nothing wires it — a module lists it, and the container builds it.
+//
+// THE SEAM IS THE CONSTRUCTOR. A class names what it needs as ordinary
+// constructor parameters and the container supplies them, so a test can put a
+// stand-in in place of any of them, however deep:
+//
+//   import { isolated } from "@palbase/backend/test";
+//   const svc = isolated().with(NoteRepo, fakeRepo).get(NoteService);
+//
+// The constructor stays PURE WIRING: it runs while the app is coming up, it is
+// synchronous, and it does no I/O. Real work at startup goes in `onStart`,
+// which is awaited before the first request — a connection opened here would
+// fail somewhere nobody is watching.
+//
+// A dependency is named by its parameter's TYPE and by nothing else. There is
+// no `inject()`, no `@Inject`, no token registry — and an `interface` cannot be
+// one, because it does not exist at runtime. Use a class, or an `abstract
+// class` when you want the abstraction.
+//
+// `Database.public.notes` is typed from `db/public.ts` through the generated
+// `palbase-env.d.ts`, which `palbase build` writes. Before the first build that
+// file does not exist yet and the table is unknown to the type checker; build
+// once and the whole surface below is typed with no import and no generic.
+
+/** One row of `notes`, exactly as `db/public.ts` declares it. */
+export type Note = Tables["notes"]["row"];
+
+/** The typed surface of one table: `insert`, `update`, `delete`, `findById`,
+ * `findMany`. Naming it here is what keeps the seam ONE table wide — a test
+ * fake implements five methods, not the whole `Database`. */
+type NotesTable = typeof Database.public.notes;
+
+/**
+ * The one table this vertical touches, behind a class the container can build.
+ *
+ * `Database.public.notes` is a VALUE, not a class, so it cannot be a dependency
+ * on its own — a dependency is named by its parameter's TYPE. Naming the table
+ * here keeps the seam ONE table wide: a test stands in for five methods rather
+ * than for the whole `Database`.
+ *
+ * It is `abstract` so a test can substitute it by NAME. The container resolves
+ * an abstraction to the single class that extends it, and `DbNoteRepo` below is
+ * that class — declared by `extends`, not by a second syntax.
+ */
+export abstract class NoteRepo {
+  abstract findMany(where: { user_id: string }): Promise<Note[]>;
+  abstract insert(row: { user_id: string; body: string }): Promise<Note>;
+  abstract findById(id: string): Promise<Note | null>;
+  abstract delete(id: string): Promise<void>;
+}
+
+@Injectable()
+export class DbNoteRepo extends NoteRepo {
+  private readonly notes: NotesTable = Database.public.notes;
+
+  findMany(where: { user_id: string }): Promise<Note[]> {
+    // `where` is a NAMED field, not the whole argument: the same object also
+    // carries `orderBy`, `limit` and the operators, so the filter has to say
+    // which of them it is.
+    return this.notes.findMany({ where });
+  }
+  insert(row: { user_id: string; body: string }): Promise<Note> {
+    return this.notes.insert(row);
+  }
+  findById(id: string): Promise<Note | null> {
+    return this.notes.findById(id);
+  }
+  delete(id: string): Promise<void> {
+    return this.notes.delete(id);
+  }
+}
+
+@Injectable()
+export class NoteService {
+  // The dependency arrives through the constructor and the container supplies
+  // it. Nothing here registers anything: `notes.module.ts` lists this class,
+  // and that list is the only place ownership is decided.
+  constructor(private readonly notes: NoteRepo) {}
+
+  /** The caller's notes. The filter is written out even though the table's RLS
+   * policy already scopes the read to `auth.uid()`: the policy is the backstop
+   * that holds when a query forgets, not a reason to stop writing the query. */
+  list(userId: string): Promise<Note[]> {
+    return this.notes.findMany({ user_id: userId });
+  }
+
+  /** `user_id` is `notNull` with no default, so ownership is written here —
+   * it is not something the request body may carry. */
+  create(userId: string, body: string): Promise<Note> {
+    return this.notes.insert({ user_id: userId, body });
+  }
+
+  /** No `userId` argument, and that is not an oversight: another user's note is
+   * invisible to this read, so it comes back `null` exactly as a missing id
+   * does. Postgres enforces it, not this method. */
+  get(id: string): Promise<Note | null> {
+    return this.notes.findById(id);
+  }
+
+  remove(id: string): Promise<void> {
+    return this.notes.delete(id);
+  }
+}

package/template/{controllers → modules/notes}/notes.controller.ts

@@ -1,8 +1,8 @@
 import { Body, Controller, Delete, Get, NotFound, Param, Post, User } from "@palbase/backend";
 import type { UserT } from "@palbase/backend";
 
-import { CreateNoteBody, NoteSchema } from "../models/notes/create";
-import { noteService } from "../services/note.service";
+import { CreateNoteBody, NoteSchema } from "./dto/create";
+import { NoteService } from "./note.service";
 
 // The other half of the vertical that starts in `services/note.service.ts`.
 //
@@ -16,10 +16,14 @@ import { noteService } from "../services/note.service";
 // controller does not import `Database`. If a method here starts reaching for a
 // table, the logic has leaked into the layer that is hardest to test.
 //
-// The dependency is a MODULE-LEVEL SINGLETON, imported. It is not a constructor
-// parameter: the runtime constructs this class with no arguments, and a
-// controller that declares one is refused when the route table is built at boot,
-// with the class named — rather than handed `undefined` in production.
+// The dependency arrives through the CONSTRUCTOR and the container supplies it.
+// Nothing is wired by hand and nothing is imported as an instance: this class
+// names `NoteService` as a parameter, `notes.module.ts` lists both, and the
+// 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.
 
 // 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
@@ -29,15 +33,17 @@ import { noteService } from "../services/note.service";
 // Auth is required unless a route opts out, so `@User()` is non-null here and
 // every method below acts as somebody.
 @Controller("/notes")
-class NotesController {
+export class NotesController {
+  constructor(private readonly notes: NoteService) {}
+
   @Get("")
   list(@User() user: UserT): Promise<NoteSchema[]> {
-    return noteService.list(user.id);
+    return this.notes.list(user.id);
   }
 
   @Post("")
   create(@Body(CreateNoteBody) body: CreateNoteBody, @User() user: UserT): Promise<NoteSchema> {
-    return noteService.create(user.id, body.body);
+    return this.notes.create(user.id, body.body);
   }
 
   @Get("/{id}")
@@ -45,13 +51,13 @@ class NotesController {
     // `null` covers both "no such note" and "not yours" — the second is not
     // distinguishable from the outside on purpose, because telling a caller
     // that a row they may not read exists is itself a leak.
-    const note = await noteService.get(id);
+    const note = await this.notes.get(id);
     if (!note) throw new NotFound("no note with that id");
     return note;
   }
 
   @Delete("/{id}")
   remove(@Param("id") id: string): Promise<void> {
-    return noteService.remove(id);
+    return this.notes.remove(id);
   }
 }

package/template/modules/notes/notes.module.ts

@@ -0,0 +1,37 @@
+import { Module, type Token } from "@palbase/backend";
+
+import { NotesController } from "./notes.controller.ts";
+import { DbNoteRepo, NoteService } from "./note.service.ts";
+
+/**
+ * ONE module says what exists, who owns it, and what it may reach.
+ *
+ * Named after the DOMAIN and living WITH it: `modules/notes/` holds the module,
+ * the controller, the service and the schemas that belong to notes, and nothing
+ * else. A second domain is a second folder — never a second entry in a file
+ * everybody edits, which is the merge conflict a module system exists to avoid.
+ *
+ * There is no root module and nothing to mount one into — the health probe is
+ * `modules/health/`, a domain like this one. The rule has no exceptions, which
+ * is what makes "add a domain" mean "add a folder".
+ *
+ * The four lists answer four different questions, and nothing else answers them:
+ *
+ *   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
+ *
+ * A class listed nowhere does not exist: the build refuses it by name, and it
+ * never reaches the route table, the dispatcher or the OpenAPI document.
+ */
+@Module({
+  controllers: [NotesController as Token],
+  providers: [NoteService as Token, DbNoteRepo as Token],
+  // Nothing is exported yet, so nothing outside this module can depend on its
+  // classes. Add a name here when another module genuinely needs it — and say
+  // why in the commit, because an export is a promise.
+  exports: [],
+  imports: [],
+})
+export class NotesModule {}

package/template/package.json

@@ -5,17 +5,19 @@
   "type": "module",
   "description": "A Palbase backend — class controllers, a declared database, and the secrets it needs.",
   "scripts": {
-    "test": "node --test --experimental-strip-types services/note.service.test.ts && node --test --experimental-strip-types",
+    "test": "./scripts/test.sh",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@palbase/backend": "^25.0.0"
+    "@palbase/backend": "^27.0.0",
+    "reflect-metadata": "^0.2.2"
   },
   "engines": {
     "node": ">=22.18.0"
   },
   "devDependencies": {
     "@types/node": "^22",
-    "typescript": "^5"
+    "typescript": "^5",
+    "bun-types": "^1.3.0"
   }
 }

package/template/scripts/test.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+#
+# `bun test` EXIT CODE IS NOT ENOUGH.
+#
+# Measured on macOS with bun 1.3.9: a suite that calls `process.exit(0)` part way
+# through — which anything in the import graph can do — makes `bun test` exit 0
+# and print NO SUMMARY AT ALL. A CI step reading only the exit code calls that a
+# pass, and the tests that never ran are the ones you needed.
+#
+# So the summary is read, and a run that discovered zero tests is a failure too:
+# a filter that matches nothing reports silence, and silence is not a pass.
+set -uo pipefail
+
+out="$(bun test "$@" 2>&1)"
+code=$?
+printf '%s\n' "$out"
+
+if [ "$code" -ne 0 ]; then
+  exit "$code"
+fi
+
+# `Ran 1 test` is singular — a pattern that demands `tests` fails a healthy
+# one-test suite, and a gate that gives a false positive is not a gate.
+if ! printf '%s' "$out" | grep -qE 'Ran [0-9]+ tests?'; then
+  echo "test.sh: bun test exited 0 but printed no summary — the run did not finish." >&2
+  echo "         Something called process.exit() mid-suite; the tests after it never ran." >&2
+  exit 90
+fi
+
+if printf '%s' "$out" | grep -qE 'Ran 0 tests?'; then
+  echo "test.sh: zero tests ran. A filter that matches nothing reports silence." >&2
+  exit 90
+fi