@palbase/backend 23.0.0 → 24.0.0

package/docs/llms-full.txt

@@ -195,10 +195,10 @@ generated client surface) changes; the verb/path do not affect it.
 - `palbase build` — validate the tree locally exactly the way a deploy would
   (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.
-- `palbase db types` — regenerate `palbase-env.d.ts` from `db/schema.ts` so
-  `Database.tables.*` is typed (no import, no generic). Run it after editing the
-  schema.
+  fails on your machine instead. It also regenerates `palbase-env.d.ts` from
+  `db/schema.ts`, which is what types `Database.tables.*` (no import, no
+  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
   GitHub-backed project it runs `git push`; the pushed source Git branch deploys
   to the Environment configured for that branch.
@@ -337,10 +337,11 @@ start. The loop is: edit, validate, push to a dev Environment.
   bundles your `controllers/` exactly as the deploy does and runs the deploy's
   own metadata extractor over the result, so a bad decorator, an illegal return
   type or an SDK major skew fails here rather than shipping a deploy that
-  serves zero endpoints. It is wired into a `pre-push` git hook for you.
-- `palbase db types` — regenerate `palbase-env.d.ts` from `db/schema.ts` so
-  `Database.tables.*` is typed (no import, no generic). Run it after editing the
-  schema. See [migrations.md](./migrations.md) for the schema/migration side.
+  serves zero endpoints. It is wired into a `pre-push` git hook for you. It also
+  regenerates `palbase-env.d.ts` from `db/schema.ts`, which is what types
+  `Database.tables.*` (no import, no generic), so run it after editing the
+  schema — there is no separate command for that. See
+  [migrations.md](./migrations.md) for the schema side.
 - `palbase push` deploys the current backend to the selected Environment. For a
   GitHub-backed project it runs `git push`; Studio maps the pushed source Git
   branch to its configured Environment.
@@ -864,32 +865,136 @@ See [schema.md](./schema.md) for the full typed-table surface.
 
 ## Raw string-keyed operations
 
-For dynamic table names or read-only SQL, the string-keyed ops are still
-available:
+For a table name computed at runtime, or for SQL the typed helpers do not
+cover, the string-keyed ops are still available:
 
 | Method | Returns |
 |--------|---------|
 | `Database.insert(table, data)` | the inserted row (`Record<string, unknown>`) |
-| `Database.update(table, id, data)` | the updated row |
+| `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, query?)` | matching rows (array) |
-| `Database.query(sql, params?)` | rows from a read-only SQL query (runs in a READ ONLY transaction) |
+| `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 |
 
-`findMany`'s `query` is an equality filter: keys are ANDed together. For
-anything richer (ranges, ordering, joins) use `Database.query`.
+### Filters
 
-`Database.query` is **read-only** — use it for selects/joins the helpers don't
-cover. Writes must go through `insert`/`update`/`delete` or a transaction.
+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" },
+});
+```
+
+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.
+
+### Ordering and paging
+
+```ts
+await Database.tables.entries.findMany(
+  { 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
+compile error, not a runtime rejection. `offset` without `limit` is refused —
+"skip 40 of an unbounded result" is not a page. Pair `count(where)` with the same
+filter to get the total; fetching everything to read `.length` is the shape this
+surface exists to remove.
+
+### Bulk writes refuse an empty filter
+
+`updateMany({}, …)` and `deleteMany({})` throw with the table named. `UPDATE …
+WHERE true` is a whole-table write, and the way to reach it by accident — a
+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
+
+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
+it commits with the rest of the request.
 
 ```ts
 const rows = await Database.query(
-  "SELECT id, title FROM todos WHERE done = $1 ORDER BY created_at DESC LIMIT $2",
-  [false, 20],
+  "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],
 );
 ```
 
+A JavaScript array parameter is encoded as a Postgres array literal, so
+`= ANY($1::uuid[])` works.
+
+### Bulk writes with a conflict rule
+
+Inside a transaction, `insertMany` takes an optional conflict rule — which is how
+"insert the ones that are new" becomes ONE statement instead of one round-trip
+per row with a `23505` caught around each:
+
+```ts
+await Database.transaction((tx) => {
+  tx.tables.merchants.insertMany(rows, { onConflict: ["name"], action: "ignore" });
+  return null;
+});
+```
+
+`action: "ignore"` emits `ON CONFLICT DO NOTHING`; `action: "update"` emits
+`ON CONFLICT DO UPDATE`, setting every column that is not part of the conflict
+key.
+
+**With `"ignore"`, the returned rows are the ones actually INSERTED.** Postgres
+does not return what it did not write, so a row that collided is absent from the
+result — if you need the existing row's id too, use `"update"`, which writes
+every row and therefore returns every row.
+
+Without the second argument nothing changes: a collision aborts the transaction,
+exactly as it did before the option existed.
+
+### Unique violations are typed
+
+A write that duplicates a row raises `UniqueViolation` (a `Conflict`, HTTP 409)
+carrying the constraint Postgres named:
+
+```ts
+import { UniqueViolation, Conflict } from "@palbase/backend";
+
+try {
+  return await Database.tables.users.insert({ email });
+} catch (e) {
+  if (UniqueViolation.is(e) && e.constraint === "users_email_key") {
+    throw new Conflict("That email is taken", "email_taken");
+  }
+  throw e;
+}
+```
+
+**Use `UniqueViolation.is(e)`, not `e instanceof UniqueViolation`.** A controller
+bundle inlines its own copy of `@palbase/backend`, and the engine that raises this
+error is the runtime's copy — two copies, two class identities, so `instanceof` is
+false in the one place you would write it. `is()` matches on shape and works
+across the boundary.
+
+The constraint name is on the `constraint` field, for you. It is deliberately NOT
+in the message that reaches the client — an uncaught error becomes an HTTP
+response, and a constraint name there tells an end user how your schema is built.
+
 ## Transactions
 
 A transaction is a **plan**, not a conversation. The callback DESCRIBES the
@@ -1071,8 +1176,9 @@ everywhere — by default, with no import and no generic.
 ## Defining a schema
 
 The table NAME comes from the object key under `tables`. Each table value is an
-object `{ columns, rls?, policies? }` — `columns` is required; `rls` and
-`policies` enable [Row-Level Security](#row-level-security-rls).
+object whose only required field is `columns`; `rls` and `policies` enable
+[Row-Level Security](#row-level-security-rls), and `indexes` declares plain
+btree [indexes](#indexes).
 
 ```ts
 import {
@@ -1128,6 +1234,85 @@ Chainable modifiers: `.primaryKey()`, `.notNull()` (default), `.nullable()`,
 `.defaultNow()` (timestamp → `now()`), `.references(table, column)`,
 `.onDelete("cascade" | "set null" | "restrict" | "no action")`.
 
+## Indexes
+
+`indexes` declares plain (non-unique) btree indexes over an ordered column list:
+
+```ts
+export default defineSchema({
+  tables: {
+    sessions: {
+      columns: {
+        id:         uuid().primaryKey().defaultRandom(),
+        room_id:    uuid().notNull().references("rooms", "id"),
+        started_at: timestamp().defaultNow(),
+      },
+      indexes: [
+        { name: "sessions_room_started_idx", columns: ["room_id", "started_at"] },
+      ],
+    },
+  },
+});
+```
+
+On deploy each entry becomes a statement of its own — `CREATE INDEX IF NOT
+EXISTS <name> ON <table> (<columns>)` — not a clause of the `CREATE TABLE`. The
+name and every column are identifier-validated before any SQL is built.
+
+**The diff key is the NAME, and the diff is additive.** Three consequences, worth
+knowing before you name an index:
+
+- An index that exists in the database but is not in `indexes` is never dropped.
+  `db/schema.ts` does not own the database's indexes; it only adds the ones it
+  names.
+- Removing an entry from `indexes` therefore does **not** drop the index. Drop it
+  in an explicit [migration](./migrations.md).
+- Changing `columns` under a name that is already live does **nothing** — the
+  deploy matches the name, sees it, and skips. Give the new column list a NEW
+  name (and drop the old index in a migration if you want it gone).
+
+### Scope: plain btree over columns, nothing else
+
+`indexes` models exactly one kind of index. It cannot express:
+
+| what you want | declare it with |
+|---------------|-----------------|
+| a UNIQUE index | `unique: [{ name, columns }]` on the table |
+| a partial index (`WHERE …`) | `raw()` |
+| an expression index (`lower(email)`, …) | `raw()` |
+| any other method (`gin`, `gist`, `hnsw`, …) | `raw()` |
+
+The limit is deliberate, not an oversight. Comparing a partial predicate or an
+expression against the live database needs the same round-trip through Postgres'
+own deparse that `checks` uses; without it an edited predicate would silently do
+nothing. Rather than ship a half-working partial-index path, the typed field
+stays columns-only and `raw()` carries the rest:
+
+```ts
+import { defineSchema, raw, uuid, text, timestamp } from "@palbase/backend";
+
+// …
+orders: {
+  columns: {
+    id:         uuid().primaryKey().defaultRandom(),
+    status:     text().notNull(),
+    created_at: timestamp().defaultNow(),
+  },
+  raw: [
+    raw(
+      "orders_pending_idx",
+      "CREATE INDEX IF NOT EXISTS orders_pending_idx ON orders (created_at) WHERE status = 'pending'",
+      { down: "DROP INDEX IF EXISTS orders_pending_idx" },
+    ),
+  ],
+},
+```
+
+`raw()`'s `up` is emitted verbatim on the privileged DDL connection and, like
+`indexes`, is tracked by NAME only — a changed body needs a new name. Pass
+`down` yourself for an index: the default drop statement drops a *constraint*,
+and an index is not one.
+
 ## Typed DB access — by default
 
 You do **not** wire anything per endpoint. Saving `db/schema.ts` regenerates
@@ -1303,88 +1488,109 @@ so they apply without the `acceptDataLoss` confirmation that column drops need.
 # Migrations
 
 `db/schema.ts` is the single source of truth for your Postgres schema. You change
-the schema by editing that file, then generating a **migration** from the diff
-with `palbase db diff`. Every schema change — additive or destructive — flows
-through a reviewable migration file committed to git. The deploy applies the
-migrations in `db/migrations/`; nothing is auto-applied behind your back.
+the schema by editing that file — and **nothing generates a migration from it**.
+There is no diff-to-file step: the change is computed against the database *as it
+is right now*, by the stack that owns it, which is what lets it cover type
+changes, policies and constraints that a text diff cannot see.
+
+Two paths lead out of an edit, for two different moments:
+
+- **On your machine** — `palbase db plan` and `palbase db apply` act on the local
+  stack (`palbase start`). Try the change, look at it, keep going.
+- **Anywhere real** — `palbase push` carries the code AND the schema to the
+  selected Environment together, because a deploy that lands a handler against a
+  column that does not exist yet fails at the first request, in production.
+
+`db/migrations/*.sql` still exists, and still runs on deploy, for the objects the
+declaration cannot express — see [Hand-written migrations](#hand-written-migrations).
+It is not where an ordinary column change goes any more.
 
 ## The workflow
 
 ```bash
 # 1. Edit db/schema.ts (add a column, a table, a policy, …)
 
-# 2. Generate the migration from the diff (declared schema vs the selected Environment)
-palbase db diff -f add_priority
-#   → writes db/migrations/<timestamp>_add_priority.sql
+# 2. See what it would take. THIS APPLIES NOTHING.
+palbase db plan
+#   ALTER TABLE todos ADD COLUMN priority text
+#   ⚠ drop todos.notes — 41908 value(s) in 41908 row(s)
+#
+#   the ⚠ changes take data away — `palbase db apply --approve` runs them too
 
-# 3. Review the generated SQL (especially destructive changes — see below),
-#    then commit + push. git push deploys; the migration runs on deploy.
-git add db/migrations && git commit -m "add priority column" && git push
+# 3. Do it — one transaction, against the LOCAL database.
+palbase db apply
+
+# 4. Ship it. Code and schema travel together.
+palbase push
 ```
 
-`palbase db diff` introspects the selected Environment's live database (there is
-no local database — each Environment runs on the server), diffs it against
-`db/schema.ts`, and writes one migration SQL file. If the schema is already in
-sync it writes nothing and tells you so.
+`palbase db plan` hands `db/schema.ts` to the local stack, which computes the plan
+against its own database and answers with what it would change. When there is
+nothing to do it says `✓ the database matches db/schema.ts`. It writes nothing,
+ever — neither a file nor a row — so it is safe to run at any moment, including
+from a script (`--detailed-exitcode` exits 2 when the plan would change
+something, 0 when it is in sync).
 
 ## Additive vs destructive
 
-The generated SQL labels what it does. An additive change (new table, new column)
-is plain DDL:
-
-```sql
--- palbase db diff: add_priority
--- generated 20260605T142233
+The plan separates the two, and a **destructive** change (dropping a column or a
+table) is REFUSED unless you say so again:
 
-ALTER TABLE todos ADD COLUMN IF NOT EXISTS priority text;
 ```
-
-A **destructive** change (dropping a column or table — losing data) is generated
-with a clear warning comment, and `palbase db diff` prints a warning. Review it
-before committing:
-
-```sql
--- DESTRUCTIVE: dropping todos.notes loses its data
-ALTER TABLE todos DROP COLUMN notes;
+$ palbase db apply
+refused: this would take data away — run it again with --approve if that is
+what you mean
 ```
 
-A **column type change** is emitted as a commented stub — auto-migration never
-alters types, so you write the real `ALTER ... TYPE` with whatever `USING` cast
-and backfill your data needs:
+Destructive lines carry their **row counts**, and that is the whole design: "this
+drops a column" is a shrug, "this drops a column with 41,908 values in it" is a
+decision. `palbase db apply --approve` runs them; `palbase push --approve` is the
+same consent for an Environment.
+
+A **column type change** is not applied by this rail at all. The plan lists it
+under `not applied by this rail — change these yourself:` and you write the real
+`ALTER ... TYPE` as a hand-written migration, with whatever `USING` cast and
+backfill your data needs:
 
 ```sql
--- TYPE CHANGE: todos.priority text -> integer (review; auto-migrate does not ALTER types)
--- ALTER TABLE todos ALTER COLUMN priority TYPE integer;
+-- todos.priority text -> integer
+ALTER TABLE todos ALTER COLUMN priority TYPE integer USING priority::integer;
 ```
 
 ## The drift gate
 
-You can't push a schema change without its migration:
-
-- **`palbase db check`** exits non-zero when `db/schema.ts` declares something the
-  database lacks (i.e. you edited the schema but didn't run `palbase db diff`).
-- The scaffold installs a **git pre-push hook** that runs `palbase db check`, so a
-  plain `git push` is **blocked** until you generate + commit the migration.
-  (Bypass with `git push --no-verify` — but the deploy-time gate still rejects it.)
-- On deploy, after migrations run, Palbase asserts `db/schema.ts` matches the live
-  database. Any unresolved drift **fails the deploy** and keeps the previous
+Code and schema move at different speeds, so three things keep them together:
+
+- **`palbase db plan --detailed-exitcode`** exits 2 when the declaration and the
+  database disagree and 0 when they match — the form to put in CI, because it
+  answers with a status code and still writes nothing.
+- The CLI installs a **git pre-push hook** that runs `palbase build`, the same
+  validation the deploy runs, so a push that would produce a failed deploy is
+  caught on your machine first. (Bypass with `git push --no-verify` — the server
+  still gates it.)
+- On deploy, the migrations run and Palbase then asserts `db/schema.ts` matches
+  the live database. Unresolved drift **fails the deploy** and keeps the previous
   version live — a broken schema never goes out silently.
 
-## Your schema change is not live until you deploy it
+## Your schema change is not live anywhere you have not applied it
+
+The local stack and every Environment hold their own database, and editing
+`db/schema.ts` changes none of them: `palbase db apply` is what moves the local
+one, `palbase push` is what moves an Environment's. Until then the declaration is
+ahead of the tables.
 
-There is no local database. `Database` always talks to the selected deployed
-Environment, so a change in `db/schema.ts` does not exist in that database until
-you generate the migration and deploy it — the types can be ahead of the tables.
-Run `palbase db types` after editing the schema to refresh `palbase-env.d.ts` so
-`Database.tables.<name>` is fully typed in your services, and deploy to a dev
-Environment to exercise it against real data.
+The TYPES move separately again. `palbase build` regenerates `palbase-env.d.ts`
+from `db/schema.ts`, which is what types `Database.tables.<name>` in your
+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
+missing is usually the whole debugging step.
 
 ## Hand-written migrations
 
 `db/migrations/*.sql` is plain SQL applied in filename order and tracked in
-`schema_migrations` (idempotent — a migration runs once). `palbase db diff`
-generates them for you, but you can also hand-write one for anything the diff
-can't express: a data backfill, a complex type change with a `USING` cast, a
+`schema_migrations` (idempotent — a migration runs once). Nothing generates
+these; you write one for anything the declaration cannot express: a data backfill, a complex type change with a `USING` cast, a
 trigger, a `CHECK` constraint, an `EXCLUDE` constraint, a composite/multi-column
 `UNIQUE`, an index (`CREATE INDEX`), or `CREATE EXTENSION` for an extension that
 isn't in the DSL allowlist (e.g. `btree_gist`). The DSL column builders cover
@@ -1428,12 +1634,12 @@ Two patterns follow from this:
 - **Extra constraint/index on a DSL-expressible table** — declare the table in
   `db/schema.ts` and add **only** the constraint/index via the migration. The
   base table stays modeled, the gate ignores the constraint, and `palbase db
-  check` stays clean.
+  plan` stays clean.
 - **A whole object the DSL can't model** (like `instructor_sessions` above — its
   `tstzrange` column has no DSL builder) — the table lives entirely in raw SQL,
-  not in `db/schema.ts`. The deploy still succeeds, but `palbase db check` (the
-  read-only client warning) will print a `- table <name>` would-be-drop line for
-  it; that's expected and the deploy-time gate does not block on it.
+  not in `db/schema.ts`. The deploy still succeeds, but `palbase db plan` will
+  list it as a ⚠ would-be-drop for the local database; that is expected, and the
+  deploy-time gate does not block on it. Never approve that one.
 
 ## Adding a NOT NULL column to a table with rows
 
@@ -1460,8 +1666,9 @@ RLS on and no applicable policy, Postgres denies everything: empty reads, refuse
 writes, no error anywhere that says why.
 
 **Guard the CREATE.** Postgres has no `CREATE POLICY IF NOT EXISTS`, so a
-migration that replays — a fresh Environment, a branch, `palbase db reset` —
-fails on the second run. Drop first:
+migration that replays — a fresh Environment, or `palbase start --reset`, which
+throws the local database away and brings it back empty — fails on the second
+run. Drop first:
 
 ```sql
 DROP POLICY IF EXISTS owner_all ON notes;
@@ -1483,15 +1690,30 @@ no such safety net — write it the first time.
 
 <!-- ===== services.md ===== -->
 
-# Services
+# Service singletons — `Database`, `Storage`, `Cache`, …
+
+**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.
 
-Import service singletons from `@palbase/backend` in every handler type —
-endpoints, workers, jobs, hooks, and webhooks all use the same imports. Only
-**middleware** uses a `ctx` argument (`ctx.db`, `ctx.log`, etc.).
+- **YOUR service layer** — `services/<name>.service.ts`, the plain 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
+  `@palbase/backend` (`Database`, `Cache`, `Storage`, …). Everything between
+  here and that last section is about these.
 
-Available singletons: `Database`, `Documents`, `Storage`, `Cache`, `Queue`,
+Import them in every handler type — endpoints, workers, jobs, hooks, and
+webhooks all use the same imports. Only **middleware** uses a `ctx` argument
+(`ctx.db`, `ctx.log`, etc.).
+
+Available singletons: `Database`, `Documents`, `Storage`, `Cache`,
 `Log`, `Notifications`, `Flags`, `Realtime`.
 
+There is **no `Queue`**. It was listed here for months and has never been
+exported: background work is a cron `@Job` under `jobs/` (see
+[background.md](./background.md)). Importing it does not fail at a queue that
+turns out to be empty — it fails at the import.
+
 `Realtime` is **broadcast-only** on the backend — a handler can push an event to
 a channel, but cannot subscribe (a stateless request can't hold a socket).
 Subscription lives on the client SDK (`pb.realtime`).
@@ -1561,9 +1783,10 @@ const { data: doc } = await Documents.doc("rooms/abc").get();
 ## Notifications
 
 **No provider setup is required.** Every project starts with a managed sender, so
-email and SMS deliver on a brand-new project with no provider, no API key, and no
-`config/notifications.ts`. You configure your own provider only to send from your
-own domain — see [Config](./config.md).
+email and SMS deliver on a brand-new project with no provider and no API key. You
+configure your own provider only to send from your own domain, and that is a CLI
+act against the stack, not a file in this repository:
+`palbase notifications providers`.
 
 ```ts
 import { Notifications } from "@palbase/backend";
@@ -1576,7 +1799,7 @@ await Notifications.email.send({
 });
 await Notifications.email.send({
   to: user.email,
-  templateSlug: "receipt",         // defined in config/notifications.ts
+  templateSlug: "receipt",         // created with `palbase notifications templates`
   locale: "tr",                    // without this the extra locale rows are unreachable
   variables: { total: "₺240" },
 });
@@ -1684,6 +1907,79 @@ and never blocks the handler waiting on subscribers.
 Pair it with the client SDK's `pb.realtime.channel("room:42").on("message", …)`
 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).
+
+The contract is three rules, and the scaffold's own test enforces all three:
+
+**1. The logic lives in a service; the controller does not touch the database.**
+A controller's job is HTTP — validate a body through a named schema, name the
+200 shape as the return type, turn a missing row into a status. Which rows,
+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:
+
+```ts
+// services/note.service.ts
+import { Database } from "@palbase/backend";
+
+type NotesTable = typeof Database.tables.notes;
+
+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;
+  }
+
+  list(userId: string) {
+    return this.notes.findMany({ user_id: userId });
+  }
+}
+
+export const noteService = new NoteService(Database.tables.notes);
+```
+
+```ts
+// controllers/notes.controller.ts
+import { noteService } from "../services/note.service";
+```
+
+**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.
+
+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.
+
+```ts
+// services/note.service.test.ts — `npm test`, no database
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { NoteService } from "./note.service.ts";
+
+test("list filters by owner", async () => {
+  const seen: unknown[] = [];
+  const fake = { findMany: async (q: unknown) => (seen.push(q), []) };
+  await new NoteService(fake as never).list("u_1");
+  assert.deepEqual(seen, [{ user_id: "u_1" }]);
+});
+```
+
+Node's ESM resolver wants the extension on a relative import inside a test
+(`./note.service.ts`); the scaffold's `tsconfig.json` allows it.
+
 
 
 <!-- ===== errors.md ===== -->