@palbase/backend 13.0.0 → 14.0.0

package/docs/llms-full.txt

@@ -1,6 +1,6 @@
 # Palbase Backend SDK (`@palbase/backend`)
 
-> TypeScript backend SDK. NestJS-style class controllers: `@Controller` classes with `@Get`/`@Post`/`@Query`/… methods and `@Body`/`@QueryParams`/`@Param`/`@User` parameter decorators. All handler types import service singletons (`Database`, `Cache`, …). Trigger arg differs by type: endpoints use parameter decorators, workers `(payload, meta)`, jobs `(meta)`, hooks/webhooks `(event, meta)`. Middleware is the one exception (`ctx`). Not Express, not Supabase Edge Functions.
+> TypeScript backend SDK. NestJS-style class controllers: `@Controller` classes with `@Get`/`@Post`/`@Query`/… methods and `@Body`/`@QueryParams`/`@Param`/`@User` parameter decorators. All handler types import service singletons (`Database`, `Cache`, …). Trigger arg differs by type: endpoints use parameter decorators, jobs `(meta)`, hooks/webhooks `(event, meta)`. Middleware is the one exception (`ctx`). There is NO queue and no `defineWorker` — background work is a cron `@Job` under `jobs/`. Not Express, not Supabase Edge Functions.
 
 
 
@@ -33,7 +33,7 @@ db/schema.ts                        # config-as-code Postgres schema (tables, co
 
 The four folders above are the daily surface. These also exist (own docs, linked
 below): `resources/` (external connections — [resources.md](./resources.md)),
-`seeds/` (seed data), `jobs/` + `workers/` (background — [background.md](./background.md)),
+`seeds/` (seed data), `jobs/` (background — [background.md](./background.md)),
 `webhooks/` + `hooks/` (events — [events.md](./events.md)), `middleware/`.
 
 ### The 7 rules (checklist)
@@ -224,14 +224,13 @@ The **only difference** is the trigger argument:
 | You are writing… | Handler signature | Trigger arg |
 |------------------|-------------------|-------------|
 | **Endpoints** (`controllers/` class controllers) | method `(…params)` | parameter decorators `@Body`/`@QueryParams`/`@Param`/`@User`/… — [endpoints.md](./endpoints.md) |
-| **Workers** (`workers/**`) | `(payload, meta)` | typed payload + `WorkerMeta` |
 | **Jobs** (`jobs/**`) | `(meta)` | `JobMeta` |
 | **Hooks** (`hooks/**`) | `(event, meta)` | typed event + `HookMeta` |
 | **Webhooks** (`webhooks/**`) | `(event, meta)` | typed event + `WebhookMeta` |
 | **Middleware** (`middleware/**`) | `(ctx, next)` | `MiddlewareContext` — the **one exception** |
 
 `meta` carries non-service data: `env` (Environment variables),
-`environmentId`, and for workers/webhooks `requestId`. Services always come from
+`environmentId`, and for webhooks `requestId`. Services always come from
 the imported singletons — not from `ctx` or any argument.
 
 ## Project shape
@@ -249,7 +248,6 @@ my-backend/
 ├── db/migrations/          # explicit SQL migrations for type changes (optional)
 ├── resources/              # external connections, set up once at boot (optional)
 ├── seeds/                  # seed data (optional)
-├── workers/                # background job handlers (optional)
 ├── jobs/                   # cron-scheduled jobs (optional)
 ├── hooks/                  # auth/storage/document event hooks (optional)
 ├── webhooks/               # inbound provider webhooks (optional)
@@ -642,6 +640,122 @@ rest of the chain (other middleware, then the endpoint method).
 
 
 
+<!-- ===== auth.md ===== -->
+
+# Authentication
+
+Routes are **secure by default**: every endpoint requires a signed-in user
+unless it opts out with `auth: false`. Client SDKs attach the user's token
+automatically, so on the backend you declare what a route needs and inject the
+user.
+
+```ts
+import { Controller, Get, Post, Body, User, OptionalUser } from "@palbase/backend";
+import type { UserT } from "@palbase/backend";
+
+@Controller("/todos")                       // no auth option → every route needs a user
+export default class TodosController {
+  @Post("")
+  create(@Body(CreateTodoBody) body: CreateTodoBody, @User() user: UserT) {
+    return todoService.create(user.id, body.title);   // user is non-null — guaranteed
+  }
+
+  @Get("/featured", { auth: false })        // one public route
+  featured(@OptionalUser() user: UserT | null) {
+    return todoService.featured(user?.id ?? null);    // may be null — handle it
+  }
+}
+```
+
+## What `@User()` gives you
+
+```ts
+interface User {
+  id: string;
+  email?: string;          // absent for phone-only users
+  emailVerified: boolean;
+  role: string;
+  metadata: Record<string, unknown>;
+  device: VerifiedDevice | null;
+}
+```
+
+Every field is **server-resolved** from the verified token — nothing here is
+client-settable. `emailVerified` in particular is read from the user's verified
+profile, not from a JWT claim: a claim is only true as of when the token was
+minted, so a user who verifies mid-session would keep reporting `false` until
+their token expired.
+
+## Email verification
+
+The platform handles verification end to end. **You do not configure a sender**,
+and `config/notifications.ts` is unrelated — that file declares providers for
+**your app's own** notifications. Auth email goes out through Palbase's own
+notification tenant, not yours.
+
+What happens on `POST /auth/signup`:
+
+1. The account is created with `email_verified = false`.
+2. A verification email is sent — by default a **6-digit code, valid 5 minutes**.
+   (An Environment configured for link-based verification instead sends a link
+   token valid **24 hours**.)
+3. The client calls `verifyEmail({ code, email })` — or `verifyEmail({ token })`
+   for the link form — then `resendVerification(email)` if it expired.
+
+A send failure does **not** fail the signup: the account exists and the user can
+re-trigger delivery. Resend is rate-limited per IP on the same budget as signup.
+
+Branding (app name, logo, colours, support address) comes from the Environment's
+auth branding settings, not from your code.
+
+### Requiring a verified email
+
+By default a new account **can sign in immediately**, verified or not.
+
+To require verification, turn on **confirm email** for the Environment (Studio →
+Auth → Policy, or `confirm_email_required` on the auth settings API). With it on:
+
+- signup creates the account and returns the user, but **no tokens** — the
+  response carries no `access_token`, so there is no session until the address
+  is confirmed;
+- login returns `403 email_not_confirmed` until it is.
+
+That is the whole gate, and it sits at the credential layer where it cannot be
+routed around.
+
+For finer control — say, letting a user finish a profile before confirming —
+read the flag in your handler. It costs nothing; it is already on the request:
+
+```ts
+@Post("/publish")
+publish(@User() user: UserT) {
+  if (!user.emailVerified) {
+    throw new Forbidden("Confirm your email address before publishing.");
+  }
+  return postService.publish(user.id);
+}
+```
+
+> There is no per-route `requireVerifiedEmail` option. A route-level flag would
+> have to be enforced by the runtime, and the one-line check above is enforced by
+> your own code — visible where it applies, and impossible to declare on a route
+> and have quietly do nothing.
+
+## Password reset and magic links
+
+Both are client-driven and need no backend code: the client SDK calls the auth
+endpoints, Palbase sends the mail, the user completes the flow, and your next
+request simply arrives with a valid token. Reset tokens and magic links are
+single-use and expire; a used or expired one fails closed with a `400`.
+
+## Related
+
+- [Row-Level Security](./schema.md#row-level-security-rls) — pushing per-user
+  access rules into Postgres, where `auth.uid()` is this same verified user.
+- [Database](./database.md) — how `Database.asService()` steps outside RLS.
+
+
+
 <!-- ===== database.md ===== -->
 
 # Database
@@ -810,9 +924,17 @@ A plan may carry at most 1000 operations, 5000 rows in one `insertMany`, and
 ## Bypassing RLS — `Database.asService()`
 
 When a table has [Row-Level Security](./schema.md#row-level-security-rls)
-policies, every `Database.*` call runs as the request's verified user
-(`authenticated`), so the database filters out rows the user's policies don't
-allow. That is the secure default.
+policies, every `Database.*` call runs as the request's verified user, so the
+database filters out rows the user's policies don't allow. That is the secure
+default.
+
+The Postgres role it connects as is **`backend_authenticated`** (or
+`backend_anon` when there is no signed-in user) — not `authenticated`. You
+rarely need to know that, because a policy declared in `db/schema.ts` is
+deployed targeting both. It matters in exactly one place: **hand-written
+`CREATE POLICY` SQL in a migration must name both roles**, or it applies to
+nothing your code does. See
+[Row-Level Security](./schema.md#row-level-security-rls).
 
 Sometimes you need to read or write **across all users** — an admin endpoint, a
 background job that fans out notifications, a cleanup task. For that, call
@@ -962,8 +1084,8 @@ type Room = Tables["rooms"]["row"];
 ## Row-Level Security (RLS)
 
 RLS pushes per-user access control **into Postgres**: every `Database.*` query
-runs as the request's verified user (the `authenticated` role with that user's
-claims), and the database itself filters rows your policies don't allow. A
+runs as the request's verified user (with that user's claims), and the database
+itself filters rows your policies don't allow. A
 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.
@@ -990,11 +1112,39 @@ policy("pb_owner_all")
 | Method | Default | Meaning |
 |--------|---------|---------|
 | `.for(cmd)` | `"all"` | The SQL command the policy governs. |
-| `.to(...roles)` | `["authenticated"]` | DB roles the policy applies to. `.to()` with no args targets PUBLIC. |
+| `.to(...roles)` | `["authenticated"]` | DB roles the policy applies to. `.to()` with no args targets PUBLIC. The deploy also adds the backend twin — see below. |
 | `.using(sql)` | none | `USING (...)` — which existing rows are visible (SELECT/UPDATE/DELETE). |
 | `.withCheck(sql)` | none | `WITH CHECK (...)` — which rows may be written (INSERT/UPDATE). |
 | `.as(mode)` | `"permissive"` | `"permissive"` (policies OR together) or `"restrictive"` (AND together). |
 
+#### Which role your policy must target
+
+The runtime connects to Postgres as **`backend_authenticated`** (or
+`backend_anon` when anonymous), which is a **separate role from
+`authenticated`** — not a member of it. A policy addressed only to
+`authenticated` therefore applies to nothing your backend does, and with RLS on
+and no applicable policy, Postgres denies everything: reads come back empty and
+writes are refused, while your code compiles, your tests pass and the deploy
+reports success.
+
+You do not have to think about this when you declare policies here. `.to("authenticated")`
+is deployed as `TO authenticated, backend_authenticated` (and `anon` gains
+`backend_anon`); `service_role` is left alone because `backend_service_role` has
+`BYPASSRLS` and policies never apply to it.
+
+**Hand-written SQL is the case to watch.** A `CREATE POLICY` in a
+`db/migrations/*.sql` file is applied verbatim, so write both roles yourself:
+
+```sql
+CREATE POLICY owner_all ON notes FOR ALL
+  TO authenticated, backend_authenticated
+  USING (owner = (select auth.uid()));
+```
+
+Deploy repairs an existing policy that names only `authenticated`/`anon` by
+adding the twin, so a redeploy fixes one you already shipped — but write both
+and the policy means what it says the moment it is created.
+
 **`auth.uid()`** returns the verified user's id (palauth user id, TEXT) from the
 request's JWT claims. Wrap it as `(select auth.uid())` — Postgres evaluates that
 once per statement (an initPlan) instead of once per row. `auth.role()` and
@@ -1212,6 +1362,36 @@ 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.tables.*` access.
 
+### Hand-writing a policy
+
+Two things the generated path handles for you and raw SQL does not.
+
+**Name both roles.** The runtime connects as `backend_authenticated` /
+`backend_anon`, which are *not* members of `authenticated` / `anon`. A policy
+addressed only to `authenticated` applies to nothing your backend does — and with
+RLS on and no applicable policy, Postgres denies everything: empty reads, refused
+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:
+
+```sql
+DROP POLICY IF EXISTS owner_all ON notes;
+CREATE POLICY owner_all ON notes FOR ALL
+  TO authenticated, backend_authenticated
+  USING (owner = (select auth.uid()))
+  WITH CHECK (owner = (select auth.uid()));
+```
+
+`DROP … IF EXISTS` + `CREATE` is the idempotent pair for anything without an
+`IF NOT EXISTS` form — policies, triggers, and rules. Columns and tables have
+`IF NOT EXISTS`; use it there instead of dropping, which would lose data.
+
+Deploy repairs an already-shipped policy that names only `authenticated`/`anon`
+by adding the twin, so a redeploy rescues one you got wrong. The replay guard has
+no such safety net — write it the first time.
+
 
 
 <!-- ===== services.md ===== -->
@@ -1254,15 +1434,6 @@ const profile = await Cache.getOrSet("user:42", 300, async () => {
 `getOrSet` caches whatever `fn` returns, including `null` — return a sentinel or
 guard upstream if you don't want misses cached.
 
-## Queue
-
-Enqueue work for a worker (see [background.md](./background.md)).
-
-```ts
-import { Queue } from "@palbase/backend";
-const { jobId } = await Queue.push("process-order", { orderId: "ord_1", amount: 1000 });
-```
-
 ## Log
 
 ```ts
@@ -1558,45 +1729,21 @@ HttpError) … }` matches any of them.
 
 <!-- ===== background.md ===== -->
 
-# Workers & Jobs
+# Background Jobs
 
-Workers and jobs use the **singleton model** — the same imported service
-singletons as endpoints (`import { Database, Log } from "@palbase/backend"`).
-They do **not** receive a `req`. Instead, a small `meta` argument carries the
-non-service data (`env`, `user`, correlation ids).
-
-## Workers (queue consumers)
-
-A worker processes jobs pushed via `Queue.push(name, payload)`. File lives under
-`workers/`.
-
-```ts
-// workers/process-order.ts
-import { defineWorker, Database, Log } from "@palbase/backend";
-
-interface OrderPayload { orderId: string; amount: number; }
-
-export default defineWorker<OrderPayload>({
-  name: "process-order",       // must match the Queue.push() name
-  retry: 5,                    // optional, default 3
-  timeout: 60,                 // optional, seconds
-  backoff: "exponential",      // "exponential" | "linear" | "fixed", default exponential
-  handler: async (payload, meta) => {
-    Log.info(`processing ${payload.orderId} (env ${meta.environmentId})`);
-    await Database.update("orders", payload.orderId, { status: "processed" });
-  },
-});
-```
-
-`meta` shape: `{ env, user, requestId, environmentId }`. Environment
-variables are in `meta.env`; services come from the imported singletons.
-
-Enqueue from an endpoint:
-
-```ts
-import { Queue } from "@palbase/backend";
-await Queue.push("process-order", { orderId: "ord_1", amount: 1000 });
-```
+`jobs/` is the background rail. A job uses the **singleton model** — the same
+imported service singletons as endpoints (`import { Database, Log } from
+"@palbase/backend"`). It does **not** receive a `req`; a small `meta` argument
+carries the non-service data (`env`, correlation ids).
+
+> **There is no queue.** `Queue.push` and `defineWorker` existed in earlier
+> versions and never ran: nothing consumed the queue, so a push returned a job id
+> for work that was never performed. Both are removed, and a `workers/` directory
+> now fails the deploy rather than deploying green and doing nothing. Model
+> queue-shaped work as a job that sweeps its own table: write a row with a
+> `status` column, and let a cron job pick up the pending ones. A job may run for
+> up to 300 seconds, which is the longest budget available anywhere on the
+> platform.
 
 ## Jobs (cron-scheduled)
 
@@ -1626,7 +1773,7 @@ system-initiated).
 
 # Hooks & Webhooks
 
-Like workers/jobs, hooks and webhooks use the **singleton model** — the same
+Like jobs, hooks and webhooks use the **singleton model** — the same
 imported service singletons as endpoints (`import { Database, Log } from
 "@palbase/backend"`). They do **not** receive a `req`. A second `meta` argument
 carries the non-service data (`env`, `environmentId`; webhooks also
@@ -1698,3 +1845,155 @@ handlers access Environment variables via `meta.env`. The runtime verifies the
 signature before dispatching to your event handlers.
 
 `meta` shape: `{ env, requestId, environmentId }`.
+
+
+
+<!-- ===== config.md ===== -->
+
+# Module Config (config-as-code)
+
+Beyond `db/schema.ts`, four more module surfaces are git-authoritative: storage
+buckets, notification providers, feature-flag definitions, and the outbound-HTTP
+allowlist. You declare them in `config/*.ts` files (typed, imported from
+`@palbase/backend`) and on `git push` the deploy creates/updates them. Secrets
+(certs, keys, API tokens) NEVER go in git — they live in a reserved encrypted env
+namespace, uploaded by the guided CLI.
+
+You normally author these with `palbase <module> add …` (the CLI writes the
+config file + uploads any secret); the files below are what it generates.
+
+## Storage buckets — `config/storage.ts`
+
+```ts
+import { defineStorage, bucket } from "@palbase/backend";
+
+export default defineStorage({
+  buckets: {
+    avatars: bucket({
+      public: true,                       // served without a signed URL
+      fileSizeLimit: "5MB",               // "5MB"/"20MB"/"1GB" or a byte number
+      allowedMimeTypes: ["image/png", "image/jpeg", "image/webp"],
+    }),
+    invoices: bucket({ public: false, fileSizeLimit: "20MB", allowedMimeTypes: ["application/pdf"] }),
+  },
+});
+```
+
+Author it: `palbase storage buckets add avatars --public --max-size 5MB --mime image/png,image/jpeg`.
+On deploy, the buckets are created/updated. A bucket REMOVED from the file is
+**never auto-deleted** (its files would be lost) — drop it explicitly in Studio.
+The files inside a bucket are runtime state, not config.
+
+## Notification providers — `config/notifications.ts`
+
+Providers carry secrets (APNs `.p8`, FCM service-account JSON, Twilio token).
+The config file is **structural** — it names the enabled providers + their
+non-secret fields; the secret is bound by convention to a reserved env key and
+NEVER appears in git.
+
+```ts
+import { defineNotifications } from "@palbase/backend";
+
+export default defineNotifications({
+  push: {
+    apns: { enabled: true, teamId: "A1B2C3D4E5", keyId: "XYZ123", bundleId: "net.example.app" },
+    // no p8 key here — it's in the reserved secret PB_NOTIFICATIONS_APNS_P8
+  },
+  sms: {
+    twilio: { enabled: true, accountSid: "AC...", messagingServiceSid: "MG..." },
+  },
+});
+```
+
+Author it with the guided CLI — it knows each provider's fields and uploads the
+secret for you, so you never type a secret-name string:
+
+```bash
+palbase notifications providers          # list the catalog + what's configured
+palbase notifications add apns \
+  --team-id A1B2C3D4E5 --key-id XYZ123 --bundle-id net.example.app \
+  --p8-file ./AuthKey_XYZ123.p8          # → uploads PB_NOTIFICATIONS_APNS_P8 (encrypted)
+palbase notifications add twilio --account-sid AC... --messaging-sid MG...
+                                          # prompts for the auth token (hidden)
+```
+
+The reserved secret env keys (`PB_NOTIFICATIONS_*`) are managed by these
+commands — `palbase secret set PB_*` is refused. Your own custom env
+(`MY_API_KEY` etc.) is unaffected and still flows via `.env.local`. On deploy,
+each enabled provider's reserved secret is resolved and the provider is
+configured; a provider whose secret is missing is skipped (warned, not fatal).
+
+## Feature flags — `config/flags.ts`
+
+Flag DEFINITIONS (key, type, default) are config; the value set for a specific
+user / an A/B assignment is runtime (set via the SDK/Studio, not git).
+
+```ts
+import { defineFlags, flag } from "@palbase/backend";
+
+export default defineFlags({
+  flags: {
+    new_checkout: flag({ type: "boolean", default: false, description: "Gate the redesigned checkout" }),
+    upload_limit: flag({ type: "number", default: 10 }),
+    theme:        flag({ type: "string", default: "system", variants: ["light", "dark", "system"] }),
+    limits:       flag({ type: "json", default: { daily: 10, burst: 50 } }),
+  },
+});
+```
+
+Four types: `boolean`, `number`, `string`, `json`. A `json` flag's default is an
+object (not an array, not a scalar) and nests at most 3 deep. `variants` is for
+`string` only — the flags service rejects it on every other type.
+
+Author it: `palbase flags add new_checkout --type boolean --default false`, or
+`palbase flags add limits --type json --default '{"daily":10}'`. On
+deploy, the definitions are upserted to the flags service (idempotent). A flag
+removed from the file is **not auto-deleted** (orphan definitions are harmless).
+
+## Outbound HTTP — `config/egress.ts`
+
+Your backend has **no ambient network**. A `fetch()` to an external host is
+refused unless the host is declared here, and with no `config/egress.ts` at all
+there is no outbound network whatsoever.
+
+```ts
+import { defineEgress } from "@palbase/backend";
+
+export default defineEgress({
+  hosts: ["api.openai.com", ".example.com"], // leading dot also covers subdomains
+  timeoutMs: 90_000,                         // per-call ceiling; omitted ⇒ 30_000
+});
+```
+
+Hosts are bare hostnames — https on :443 only, so no scheme, port, path or
+wildcard. `timeoutMs` is 1_000–300_000.
+
+Unlike the three above, this one is **fail-closed**: a malformed host or an
+out-of-range `timeoutMs` ABORTS the deploy rather than logging a warning. An
+allowlist that silently dropped an entry would be a broken feature, and one that
+silently widened would be a hole; an out-of-range timeout is rejected rather than
+clamped so your config file and the running system never disagree.
+
+### How long a call may take
+
+`timeoutMs` is a ceiling, not a grant — the call still ends when the invocation
+around it ends, and it covers the whole call including redirects (three hops do
+not get three budgets).
+
+| Where the fetch runs | What else bounds it |
+|---|---|
+| Job (`jobs/`) | Its own `@Job({ timeout })`, max 300s — the longest budget available. |
+| Endpoint / webhook | The gateway's request ceiling. Long work belongs in a job. |
+
+Responses are **buffered whole** (5 MB cap) before your `fetch()` resolves.
+Requesting a streaming response from an upstream (`stream: true`, SSE) therefore
+buys nothing: no partial output, no earlier first byte, and the entire stream
+must still finish inside `timeoutMs`.
+
+## How it's applied
+
+All four are evaluated + applied **on deploy**, the same place `db/schema.ts`
+migrations run, reaching each module through your project's gateway with a
+service-role key. Storage/notifications/flags are fail-soft — a config error logs
+a warning but never aborts the deploy of your code. `config/egress.ts` is the
+exception and is fail-closed, for the reason above.

package/docs/llms.txt

@@ -1,6 +1,6 @@
 # Palbase Backend SDK (`@palbase/backend`)
 
-> TypeScript backend SDK. NestJS-style class controllers: `@Controller` classes with `@Get`/`@Post`/`@Query`/… methods and `@Body`/`@QueryParams`/`@Param`/`@User` parameter decorators. All handler types import service singletons (`Database`, `Cache`, …). Trigger arg differs by type: endpoints use parameter decorators, workers `(payload, meta)`, jobs `(meta)`, hooks/webhooks `(event, meta)`. Middleware is the one exception (`ctx`). Not Express, not Supabase Edge Functions.
+> TypeScript backend SDK. NestJS-style class controllers: `@Controller` classes with `@Get`/`@Post`/`@Query`/… methods and `@Body`/`@QueryParams`/`@Param`/`@User` parameter decorators. All handler types import service singletons (`Database`, `Cache`, …). Trigger arg differs by type: endpoints use parameter decorators, jobs `(meta)`, hooks/webhooks `(event, meta)`. Middleware is the one exception (`ctx`). There is NO queue and no `defineWorker` — background work is a cron `@Job` under `jobs/`. Not Express, not Supabase Edge Functions.
 
 ## Docs
 
@@ -8,6 +8,7 @@
 - [getting-started](./getting-started.md)
 - [routing](./routing.md)
 - [endpoints](./endpoints.md)
+- [auth](./auth.md)
 - [database](./database.md)
 - [schema](./schema.md)
 - [migrations](./migrations.md)
@@ -16,3 +17,4 @@
 - [errors](./errors.md)
 - [background](./background.md)
 - [events](./events.md)
+- [config](./config.md)

package/docs/migrations.md

@@ -146,3 +146,33 @@ Add `rls: true` + `policies: [policy(...)]` to a table in `db/schema.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.tables.*` access.
+
+### Hand-writing a policy
+
+Two things the generated path handles for you and raw SQL does not.
+
+**Name both roles.** The runtime connects as `backend_authenticated` /
+`backend_anon`, which are *not* members of `authenticated` / `anon`. A policy
+addressed only to `authenticated` applies to nothing your backend does — and with
+RLS on and no applicable policy, Postgres denies everything: empty reads, refused
+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:
+
+```sql
+DROP POLICY IF EXISTS owner_all ON notes;
+CREATE POLICY owner_all ON notes FOR ALL
+  TO authenticated, backend_authenticated
+  USING (owner = (select auth.uid()))
+  WITH CHECK (owner = (select auth.uid()));
+```
+
+`DROP … IF EXISTS` + `CREATE` is the idempotent pair for anything without an
+`IF NOT EXISTS` form — policies, triggers, and rules. Columns and tables have
+`IF NOT EXISTS`; use it there instead of dropping, which would lose data.
+
+Deploy repairs an already-shipped policy that names only `authenticated`/`anon`
+by adding the twin, so a redeploy rescues one you got wrong. The replay guard has
+no such safety net — write it the first time.

package/docs/schema.md

@@ -108,8 +108,8 @@ type Room = Tables["rooms"]["row"];
 ## Row-Level Security (RLS)
 
 RLS pushes per-user access control **into Postgres**: every `Database.*` query
-runs as the request's verified user (the `authenticated` role with that user's
-claims), and the database itself filters rows your policies don't allow. A
+runs as the request's verified user (with that user's claims), and the database
+itself filters rows your policies don't allow. A
 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.
@@ -136,11 +136,39 @@ policy("pb_owner_all")
 | Method | Default | Meaning |
 |--------|---------|---------|
 | `.for(cmd)` | `"all"` | The SQL command the policy governs. |
-| `.to(...roles)` | `["authenticated"]` | DB roles the policy applies to. `.to()` with no args targets PUBLIC. |
+| `.to(...roles)` | `["authenticated"]` | DB roles the policy applies to. `.to()` with no args targets PUBLIC. The deploy also adds the backend twin — see below. |
 | `.using(sql)` | none | `USING (...)` — which existing rows are visible (SELECT/UPDATE/DELETE). |
 | `.withCheck(sql)` | none | `WITH CHECK (...)` — which rows may be written (INSERT/UPDATE). |
 | `.as(mode)` | `"permissive"` | `"permissive"` (policies OR together) or `"restrictive"` (AND together). |
 
+#### Which role your policy must target
+
+The runtime connects to Postgres as **`backend_authenticated`** (or
+`backend_anon` when anonymous), which is a **separate role from
+`authenticated`** — not a member of it. A policy addressed only to
+`authenticated` therefore applies to nothing your backend does, and with RLS on
+and no applicable policy, Postgres denies everything: reads come back empty and
+writes are refused, while your code compiles, your tests pass and the deploy
+reports success.
+
+You do not have to think about this when you declare policies here. `.to("authenticated")`
+is deployed as `TO authenticated, backend_authenticated` (and `anon` gains
+`backend_anon`); `service_role` is left alone because `backend_service_role` has
+`BYPASSRLS` and policies never apply to it.
+
+**Hand-written SQL is the case to watch.** A `CREATE POLICY` in a
+`db/migrations/*.sql` file is applied verbatim, so write both roles yourself:
+
+```sql
+CREATE POLICY owner_all ON notes FOR ALL
+  TO authenticated, backend_authenticated
+  USING (owner = (select auth.uid()));
+```
+
+Deploy repairs an existing policy that names only `authenticated`/`anon` by
+adding the twin, so a redeploy fixes one you already shipped — but write both
+and the policy means what it says the moment it is created.
+
 **`auth.uid()`** returns the verified user's id (palauth user id, TEXT) from the
 request's JWT claims. Wrap it as `(select auth.uid())` — Postgres evaluates that
 once per statement (an initPlan) instead of once per row. `auth.role()` and

package/docs/services.md

@@ -36,15 +36,6 @@ const profile = await Cache.getOrSet("user:42", 300, async () => {
 `getOrSet` caches whatever `fn` returns, including `null` — return a sentinel or
 guard upstream if you don't want misses cached.
 
-## Queue
-
-Enqueue work for a worker (see [background.md](./background.md)).
-
-```ts
-import { Queue } from "@palbase/backend";
-const { jobId } = await Queue.push("process-order", { orderId: "ord_1", amount: 1000 });
-```
-
 ## Log
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palbase/backend",
-  "version": "13.0.0",
+  "version": "14.0.0",
   "description": "Palbase Backend SDK — class controllers (@Controller/@Get/@Post + @Body/@QueryParams/@Param), error classes, schema DSL",
   "license": "MIT",
   "repository": {
@@ -90,6 +90,8 @@
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "docs:build": "node scripts/build-llms.mjs",
-    "emit:openapi-fixture": "tsx scripts/emit-openapi-fixture.mjs"
+    "emit:openapi-fixture": "tsx scripts/emit-openapi-fixture.mjs",
+    "check:api": "node scripts/api-surface.mjs",
+    "api:update": "node scripts/api-surface.mjs --update"
   }
 }