@palbase/backend 24.3.0 → 25.0.0

package/template/AGENTS.md

@@ -1,353 +1,158 @@
 # Palbase backend project
 
-This project runs inside the Palbase backend runtime. You author TypeScript; the
-runtime discovers it and serves it as a typed HTTP API, and generates the client
-SDKs your apps call. Routing is explicit: a controller is a **class** whose
-methods are routes.
+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.
 
 Everything comes from one package:
 
 ```ts
-import { Controller, Get, Post, Patch, Delete, Body, QueryParams, Param, User, z, Database, Secrets, Conflict, NotFound } from "@palbase/backend";
+import { Controller, Get, Post, Body, Param, User, z, Database, NotFound } from "@palbase/backend";
 ```
 
 > Needs `experimentalDecorators: true` — already set in this scaffold's
-> `tsconfig.json`. They are legacy decorators; there is no `reflect-metadata`.
+> `tsconfig.json`. Legacy decorators; no `reflect-metadata`.
 
-## What is here
+**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.
 
-```
-controllers/<name>.controller.ts   a @Controller class; each method is a route
-services/<name>.service.ts         the logic, as a plain class
-db/schema.ts                       the database: tables, columns, RLS policies
-palbase-stack.d.ts                 GENERATED — the names your stack actually holds
-palbase-env.d.ts                   GENERATED — your tables, as types
-```
-
-Both generated files are written by `palbase build` and **committed**. They are
-what makes `Secrets.get("X")`, `Flags.isEnabled("y")`, `@Upload({ bucket })` and
-`Database.tables.*` compile: the names come from the stack and the schema, so
-there is no second list in this repo to drift out of date. A project that has
-never run `palbase build` has no valid names and those calls will not compile —
-that is the gate working, not a rough edge. Run it once and commit both files.
+## The layers
 
-Two folders appear as the project grows, and both are conventions the tooling
-already understands:
-
-```
-models/<controller>/<endpoint>.ts  zod schemas, once they outgrow the controller
-services/<name>.service.ts         business logic, calls Database/Cache/Storage
-```
-
-Put logic in a service. Keep controller methods thin — they validate through the
-decorator schemas and delegate. Do not call `Database` from a controller.
-
-## Controllers — a class of routes
+| 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 |
+| `db/public.ts` | IS the database: tables, columns, RLS policies | produces migration files — there are none |
 
-`@Controller("/base", { auth? })` sets the base path and an optional default auth
-for every route in the class. Each route is a method decorated with
-`@Get/@Post/@Put/@Patch/@Delete/@Query("<subpath>", { auth? })`. The served path
-is `base + subpath`.
+In one line: **controllers thin, services thick, models quiet, schema the single
+truth.**
 
-**The class does not have to be exported.** `@Controller` records the class, so
-importing the file IS the registration — there is no module to list it in.
+The scaffold ships one worked vertical — `notes` — across all four. Open it: the
+shape you find there is the shape to copy.
 
-The generated clients name a call `<class minus "Controller", lowercased>.<method>`:
-`NotesController.list` is `pb.notes.list()`. The verb and the path do not affect
-it, so restructure paths freely — but renaming a class or a method renames the
-call in every app. Those two names are your public API.
+## Where does this go
 
-The example below is not invented for the page: it is `notes`, the one vertical
-this scaffold ships, so every file it names is already on your disk to open.
+| The need | Its home |
+|---|---|
+| Validate input | a zod schema in `models/`, 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 |
+| 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 |
+
+## NEVER write this
+
+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 at build with the class named.
+- **`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 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.
+- **`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
+  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.
+
+**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.)
+
+**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
+path do not affect it, so restructure paths freely and rename these two carefully.
+
+## Adding a feature — this order
+
+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`.
+   Commit both.
+8. `npm test` — exercise the service.
+
+## The service shape, exactly
 
 ```ts
-// controllers/notes.controller.ts
-import { Body, Controller, Delete, Get, NotFound, Param, Post, User, z } from "@palbase/backend";
-import type { UserT } from "@palbase/backend";
-import { noteService } from "../services/note.service";
-
-// Small controllers declare their schemas beside the routes; `models/` below is
-// where these two move once they outgrow the file.
-export const NoteSchema = z.object({
-  id: z.string(),
-  user_id: z.string(),
-  body: z.string(),
-  created_at: z.string(),
-});
-export type NoteSchema = z.infer<typeof NoteSchema>;
-
-export const CreateNoteBody = z.object({ body: z.string().min(1) });
-export type CreateNoteBody = z.infer<typeof CreateNoteBody>;
-
-@Controller("/notes")
-class NotesController {
-  @Get("")
-  list(@User() user: UserT): Promise<NoteSchema[]> {
-    return noteService.list(user.id);
-  }
+// services/note.service.ts
+import { Database } from "@palbase/backend";
 
-  @Post("")
-  create(@Body(CreateNoteBody) body: CreateNoteBody, @User() user: UserT): Promise<NoteSchema> {
-    return noteService.create(user.id, body.body);
-  }
+type NotesTable = typeof Database.tables.notes;
 
-  @Get("/{id}")
-  async get(@Param("id") id: string): Promise<NoteSchema> {
-    const note = await noteService.get(id);
-    if (!note) throw new NotFound("no note with that id");
-    return note;
+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;
   }
 
-  @Delete("/{id}")
-  remove(@Param("id") id: string): Promise<void> {
-    return noteService.remove(id);
+  list(userId: string) {
+    return this.notes.findMany({ user_id: userId });
   }
 }
-```
-
-### Parameter decorators — each request piece, injected
-
-| Decorator | Injects | Notes |
-|---|---|---|
-| `@Body(schema)` | request body | annotate `: T` (the same-named `z.infer` type) |
-| `@QueryParams(schema)` | query string | typed + validated → OpenAPI query params |
-| `@Param("id")` | one path param | typed `string` |
-| `@Headers(schema?)` | request headers | raw `Record<string,string>`; pass a schema to type + validate |
-| `@User()` | the signed-in user (`: UserT`, non-null) | `@OptionalUser()` (`UserT \| null`) on `auth: false` routes |
-| `@Client()` | parsed client info | name / version / platform |
-| `@RequestId()` / `@TraceId()` | ids | `: string` |
-| `@Req()` | the raw request | escape hatch |
-
-> `@User()` (value) and `UserT` (type) are imported separately —
-> `import { User } from "@palbase/backend"` and
-> `import type { UserT } from "@palbase/backend"` — because the value name
-> `User` is the decorator. Write `@User() user: UserT`.
-
-`@Query(subpath)` is the HTTP **QUERY** method (RFC 10008): a read that is safe
-and idempotent but carries a body. Its input goes in `@Body` — never combine it
-with `@QueryParams`.
-
-### Output and errors
-
-The 200 response **is** the method's return type, and it must NAME a zod schema.
-There is no response decorator: both the runtime's output validation and the
-client codegen read the annotation.
-
-```ts
-@Get("")        list(): Promise<TodoSchema[]>              // array (auto-wrapped in z.array)
-@Get("/{id}")   one(): Promise<TodoSchema>                 // one object
-@Get("/ping")   ping(): void                               // no response body
-```
-
-`: TodoSchema` (non-Promise) and `: Promise<z.infer<typeof TodoSchema>>` are
-equally valid. A **missing** annotation, an inline object (`Promise<{ ok: boolean }>`),
-a union, or a name with no matching zod schema in scope is a hard build error —
-name the schema.
-
-Throw a global error class from anywhere; no request object needed:
-
-```ts
-import { NotFound, Conflict, Forbidden, Unauthorized, BadRequest, TooManyRequests } from "@palbase/backend";
-
-throw new Conflict("title already taken");              // → 409, standard envelope
-throw new BadRequest({ fields: ["title"] });            // data-first: the data, then an optional message
-throw new TooManyRequests({ retryAfter: 30 });          // data-first
-```
-
-### Auth is on unless you opt out
-
-Every route requires a signed-in user by default. `@Controller("/x", { auth: false })`
-opens all of a class's routes; `@Get("", { auth: true })` overrides it for one.
-
-An application-wide default sits under those two:
-
-```ts
-import { defineDefaultAuth } from "@palbase/backend";
-defineDefaultAuth({ verifiedEmail: true });   // every route, unless it says otherwise
-```
-
-Put that call in `auth.ts` at the project root — the bundler imports that file by
-name, so the declaration cannot be silently left out of the build. Resolution is
-route → controller → application → `true`. Writing the same auth setting on ten
-controllers is how the eleventh one gets forgotten.
-
-## Models — schemas, one file per endpoint
-
-```ts
-// models/todos/create.ts
-import { z } from "@palbase/backend";
-export const CreateTodoBody = z.object({ title: z.string().min(1) });
-export type  CreateTodoBody = z.infer<typeof CreateTodoBody>;
-```
-
-Each name is a zod **value** (passed to `@Body`/`@QueryParams`, named by a return
-type) plus an optional same-named `z.infer` **type**, which is what lets the
-annotation read `Promise<TodoSchema>` instead of `Promise<z.infer<typeof TodoSchema>>`.
-Shared response schemas go in `models/<controller>/shared.ts`.
-
-## Services — business logic
-
-Plain classes wired as a module-level singleton. No DI container, no decorators
-— and this is the ONLY supported way to hold a dependency anywhere in this
-runtime. A controller, hook, job or webhook is constructed with **no arguments**;
-one that declares a constructor parameter is refused at build with the class
-named, because there is no injector to fill it and the field would simply be
-`undefined` in production.
-
-`services/note.service.ts` in this scaffold is the worked example. The shape:
-
-```ts
-export class NoteService {
-  private readonly notes: typeof Database.tables.notes;
-  // Assigned in the BODY — `constructor(private notes: …)` is a parameter
-  // property, and Node's type-stripping test runner refuses those per FILE.
-  constructor(notes: typeof Database.tables.notes) { this.notes = notes; }
-  list(userId: string) { return this.notes.findMany({ user_id: userId }); }
-}
 
 /** Controllers import THIS, never the class. */
 export const noteService = new NoteService(Database.tables.notes);
 ```
 
-The constructor is the seam: 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. `fakeDatabase()` from `@palbase/backend/test` is that stand-in when you
-want the whole surface instead of one table.
-
-`Database.tables.<name>` gives:
-
-| | |
-|---|---|
-| `insert(row)` · `upsert(row, { onConflict })` | write one |
-| `update(id, data)` · `delete(id)` | write one, by id |
-| `updateMany(where, set)` · `deleteMany(where)` | write every row the filter matches, in ONE statement |
-| `findById(id)` · `findMany(where?, opts?)` | read |
-| `count(where?)` | how many match |
-
-`where` takes a plain value for equality or an operator object —
-`{ n: { gte: 3 } }`, `{ id: { in: [...] } }`, also `gt` / `lt` / `lte` / `neq`.
-`opts` takes `{ orderBy: { column, direction }, limit, offset }`, so ordering and
-paging happen in SQL rather than in JavaScript after fetching everything.
-`updateMany`/`deleteMany` REFUSE an empty filter — a whole-table write is not
-something to reach by accident.
-
-`Database.transaction(fn)` runs a plan that commits or rolls back as one, and
-`Database.attempt(fn)` opens a savepoint so one failed write does not poison the
-rest of the request.
-
-## The database — declared, not migrated
-
-`db/schema.ts` is the database. There are no migration files to write, order, or
-reconcile; three verbs share one engine:
-
-- **plan** — what it would take to make the live database match the declaration
-- **apply** — make it match, in one transaction
-- **push** — ship the code, and REFUSE while the two still disagree
-
-That refusal is the point: code and schema move at different speeds, and a deploy
-that lands a handler against a column that does not exist yet fails at the first
-request, in production. So: edit `db/schema.ts`, plan, apply, then push.
-
-RLS is on by default and a table with no policies is deny-all. Add
-`policies: [policy(...)]` so Postgres enforces ownership — a query that forgets
-its `where user_id = …` still cannot read another user's rows.
-
-After a schema change run `palbase build`: it regenerates BOTH generated files —
-`palbase-env.d.ts` (your tables) and `palbase-stack.d.ts` (the stack's names) —
-so `Database.tables.*` keeps matching what is actually there. Commit them.
-
-## Secrets, flags, buckets — read from the stack
-
-There is no `config/` directory and nothing to declare in this repo. Settings are
-written to the STACK with the CLI, and the code READS them:
-
-```ts
-import { Secrets, Flags } from "@palbase/backend";
-const dsn = await Secrets.get("SENTRY_DSN");     // compiles only if the stack holds it
-if (await Flags.isEnabled("newCheckout")) { … }  // same
-```
-
-The name in the quotes is checked by the compiler against `palbase-stack.d.ts`,
-which `palbase build` generates from the stack. A secret's VALUE never enters
-this repository, and you never read `process.env` for one.
-
-Writing a setting is a CLI job, not a code job — `palbase --help` names the
-commands (`secret`, `flags`, `storage`, `notifications`, `auth`). Settings have
-one door; a second one is how the two come to disagree.
-
-## Lifecycle — for things that are expensive to build
-
-Most handlers need nothing here: the SDK's singletons are already pooled. But a
-long-lived object you build yourself needs somewhere to close, and a process that
-never closes one leaks it per deploy:
-
-```ts
-import { onStart, onShutdown } from "@palbase/backend";
-
-let client: SomeClient | undefined;
-onStart("graph", () => { client = SomeClient.create({ maxPoolSize: 8 }); });
-onShutdown("graph", async () => { await client?.close(); });
-```
-
-The NAME is the first argument, and it is what a failure is reported by — a stack
-trace through an anonymous closure names nothing. `onStart` runs ONCE as the app
-comes up, and a hook that throws refuses the boot rather than letting the app
-serve traffic with a half-built dependency. `onShutdown` hooks run in reverse
-order and are best-effort: one that throws is reported and the rest still run.
-
-**These hooks run OUTSIDE a request, so no Palbase service is reachable from
-them** — `Secrets`, `Database`, `Log` and the rest all throw "accessed outside a
-request scope". If your object needs a secret, build it lazily on first use
-inside a handler instead:
-
-```ts
-let client: SomeClient | undefined;
-async function graph() {
-  client ??= SomeClient.create({ url: await Secrets.get("GRAPH_URL") });
-  return client;
-}
-onShutdown("graph", async () => { await client?.close(); });
-```
+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.
 
 ## Tests
 
-`npm test` runs Node's own test runner over every `*.test.ts`. Nothing to
-install and nothing to configure — Node discovers the files and strips the types
-itself.
-
-Test the **service** layer. Controllers are thin by construction, so the logic
-that can be wrong lives in a service — a plain class you construct directly with
-a stand-in, exactly as `services/note.service.ts` is written. For a stand-in
-covering the whole database surface rather than one table:
+`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.
 
-```ts
-import { fakeDatabase } from "@palbase/backend/test";
-const { db, queries } = fakeDatabase();
-```
-
-It answers `tables.*` from memory and records the `query` calls made. What it
-does NOT do is enforce RLS, constraints or unique violations — those are real
-database behaviour, and the test that proves them runs against a real one.
+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.
 
-Node **strips** types, it never emits code, so TypeScript features that require
-emitted code are refused outright: parameter properties (`constructor(private x: T)`),
-`enum`, and `namespace` all fail with `ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`. The
-refusal is per FILE, so one parameter property anywhere in a test's import graph
-takes down every test in that file at once — it reads like a dozen broken tests
-and is one keyword. Assign fields in the constructor body; use a `const` object
-or a union instead of `enum`; use a module instead of `namespace`.
-
-Node's ESM resolver wants the extension on relative imports, so a test imports
-`./note.service.ts`, not `./note.service`. This scaffold's `tsconfig.json`
-allows that.
+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.
 
 `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".
 
-## Commands and the full reference
-
-This file deliberately does not list the CLI surface: commands change, and a copy
-inside your repository goes stale silently. `palbase --help` is authoritative.
+## Commands
 
-The complete SDK reference — controllers, models, schema, services, errors,
-jobs, hooks, webhooks — lives at <https://app.dev.palbase.studio/docs/backend>.
+`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>.

package/template/CLAUDE.md

@@ -0,0 +1,13 @@
+@AGENTS.md
+
+<!--
+Claude Code reads CLAUDE.md, not AGENTS.md. This file exists so it reaches the
+one guide this project keeps — the line above imports it whole.
+
+Every other coding agent (Codex, Cursor, Copilot, Windsurf, Gemini CLI, Zed,
+Aider, …) reads AGENTS.md directly, so there is nothing to duplicate here.
+
+Keep the rules in AGENTS.md. Two hand-maintained copies drift apart, and the one
+that drifts is the one nobody is reading when it matters. Claude-specific
+instructions, if you ever need any, go BELOW the import.
+-->

package/template/controllers/notes.controller.ts

@@ -1,6 +1,7 @@
-import { Body, Controller, Delete, Get, NotFound, Param, Post, User, z } from "@palbase/backend";
+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";
 
 // The other half of the vertical that starts in `services/note.service.ts`.
@@ -20,18 +21,10 @@ import { noteService } from "../services/note.service";
 // controller that declares one is refused at build with the class named rather
 // than handed `undefined` in production.
 
-export const NoteSchema = z.object({
-  id: z.string(),
-  user_id: z.string(),
-  body: z.string(),
-  created_at: z.string(),
-});
-export type NoteSchema = z.infer<typeof NoteSchema>;
-
-export const CreateNoteBody = z.object({
-  body: z.string().min(1),
-});
-export type CreateNoteBody = z.infer<typeof CreateNoteBody>;
+// 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
+// find here is the shape the next file copies.
 
 // Auth is required unless a route opts out, so `@User()` is non-null here and
 // every method below acts as somebody.

package/template/db/public.ts

@@ -0,0 +1,38 @@
+import { defineSchema, defineTable, ownedByUser, policy, text, timestamp, uuid } from "@palbase/backend";
+
+// `db/public.ts` IS the database. There are no migration files to write, order,
+// or reconcile: the CLI diffs this declaration against the live database, shows
+// you what it would take to make them match, applies it in one transaction, and
+// REFUSES to push code while the two still disagree.
+//
+// Row-Level Security is on by default. A table with RLS and no policies is
+// deny-all — the correct starting state, because nothing reads a table until a
+// policy says who may. `notes` below is scoped to its owner; delete it and
+// declare your own.
+const notes = defineTable("notes", {
+  columns: {
+    id: uuid().primaryKey().defaultRandom(),
+    // The column that OWNS the row: a real foreign key to the tenant's own
+    // `auth.users`, so deleting an account takes its rows with it instead of
+    // leaving orphans an erasure request cannot reach. `ownedByUser()` implies
+    // text, NOT NULL and ON DELETE CASCADE — the three rules you would
+    // otherwise have to remember. For a column that merely POINTS at a user
+    // (`created_by`, `edited_by`), use `userRef({ onDelete })` instead.
+    user_id: ownedByUser(),
+    body: text().notNull(),
+    created_at: timestamp().defaultNow(),
+  },
+  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")
+      .for("all")
+      .to("authenticated")
+      .using("user_id = (select auth.uid())")
+      .withCheck("user_id = (select auth.uid())"),
+  ],
+});
+
+// A table knows its own name, so the schema just collects them. The schema's
+// own name is declared here — `public` is the one your handlers read.
+export default defineSchema("public", { tables: [notes] });

package/template/models/notes/create.ts

@@ -0,0 +1,38 @@
+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
+// double export below.
+//
+// Each name is exported TWICE, under the SAME name:
+//
+//   * a zod VALUE — what you pass to `@Body(...)` / `@QueryParams(...)`, and what
+//     a return type names;
+//   * a same-named `z.infer` TYPE — what the parameter and return annotations are
+//     written with.
+//
+// That pairing is what lets a route read `Promise<NoteSchema>` instead of
+// `Promise<z.infer<typeof NoteSchema>>`. Drop the type and the annotation stops
+// compiling; drop the value and the deploy refuses the route, because a response
+// schema has to be a value it can bind.
+//
+// Import them as VALUES (`import { NoteSchema }`), never with `import type` — the
+// deploy emits a value reference to the name, and `import type` erases the
+// binding it would reference.
+
+/** One note row, as it goes out on the wire. */
+export const NoteSchema = z.object({
+  id: z.string(),
+  user_id: z.string(),
+  body: z.string(),
+  created_at: z.string(),
+});
+export type NoteSchema = z.infer<typeof NoteSchema>;
+
+/** The POST /notes body. Ownership is NOT here: the service writes `user_id`
+ * from the signed-in user, so a caller cannot claim someone else's row. */
+export const CreateNoteBody = z.object({
+  body: z.string().min(1),
+});
+export type CreateNoteBody = z.infer<typeof CreateNoteBody>;

package/template/package.json

@@ -3,13 +3,16 @@
   "version": "0.1.0",
   "private": true,
   "type": "module",
-  "description": "A Palbase backend \u2014 class controllers, a declared database, and the secrets it needs.",
+  "description": "A Palbase backend — class controllers, a declared database, and the secrets it needs.",
   "scripts": {
-    "test": "node --test --experimental-strip-types",
+    "test": "node --test --experimental-strip-types services/note.service.test.ts && node --test --experimental-strip-types",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@palbase/backend": "^24.0.0"
+    "@palbase/backend": "^25.0.0"
+  },
+  "engines": {
+    "node": ">=22.18.0"
   },
   "devDependencies": {
     "@types/node": "^22",