@palbase/backend 33.0.2 → 34.1.0

package/docs/README.md

@@ -82,7 +82,7 @@ service the controllers call.
 
 > **Never** emit `defineController`, `defineHandler`, `defineEndpoint`, `route.get(...)`,
 > `req.input`, `req.params`, or `req.errors` — those are the removed legacy model
-> and will not compile against `@palbase/backend` 33.
+> and will not compile against `@palbase/backend` 34.
 
 ### Complete CRUD example (copy-pasteable, compiles)
 

package/docs/auth.md

@@ -155,6 +155,64 @@ Two helpers are available in every policy body:
 Both take the caller from `auth.uid()` and accept no user id, so a policy cannot
 ask about somebody else.
 
+### `can` — what a row says you may do
+
+Every row a table hands back carries `can: string[]`: the names of the table's
+named **update** policies whose `using` expression is true for THIS row and THIS
+caller. It is computed in the same `SELECT` that fetched the row — the policy is
+the only copy of the rule, and `can` is its echo.
+
+```ts
+const transfer = await Database.public.transfers.findById(id);
+transfer?.can; // e.g. ["transfers_approve"] — typed from db/public.ts
+```
+
+To put it on the wire, name it in the response schema — the enum comes from the
+policy declaration, never from a hand-typed list:
+
+```ts
+import { z, can } from "@palbase/backend";
+import publicSchema from "../../db/public";
+
+export const TransferSchema = z.object({
+  id: z.string(),
+  status: z.string(),
+  can: can(publicSchema.tables.transfers),
+});
+```
+
+The contract, word for word: **`can` is for the interface; it cannot be used for
+an authorization decision; it may be incomplete; the server decides again on
+every request.** A policy whose `using` the engine cannot select as a column is
+dropped from `can` with a `warn` line — it never becomes a silent `true`. In a
+raw-string `using`, write column names unqualified (`status`, not
+`transfers.status` or `public.transfers.status`) and wrap every
+`auth.has_permission(...)` in `(select …)`; a comment, an unbalanced parenthesis
+or an unterminated quote drops the policy the same way.
+
+Rows read under `Database.$asService()` carry `can: []`: no policy applies to
+the service role and every `TO` gate is false for it, so a row fetched there and
+handed to a user says nothing about what that user may do — read it as the user.
+
+Only `.for("update")` policies are echoed. A `.for("all")` policy such as
+`notes_owner` above governs UPDATE too, but it is not a named update policy and
+never appears in `can` — a table whose only policy is `for("all")` gets
+`can: []` on every row, and `can(table)` refuses it by name. To get an
+affordance, declare a separate `.for("update")` policy beside it (the template's
+`notes_edit_own` next to `notes_owner`).
+
+The name `can` is reserved for this echo. A table that declares a column named
+`can` keeps its column and gets no echo (with a `warn`); a **relation** named
+`can` — a table named `can`, a `can_id` foreign key, `as: "can"` or
+`reverseAs: "can"` — is refused by `defineTable` itself, because `row.can` and
+`relations.can` cannot both be true of one row.
+
+When the server refuses, the 403 body names the cure: `required: "transfers.approve"`.
+`pb.auth.onPermissionDenied { required in … }` (iOS) / `pb.auth.onPermissionDenied(required => …)`
+(web) fires on it, so a screen drawn from a stale `can` refetches and repairs itself.
+`pb.auth.permissions.holds("transfers.approve")` is the live, observable set of the
+caller's permissions — pushed over realtime the moment a role changes.
+
 ## Email verification
 
 The platform handles verification end to end. **You do not configure a sender**,

package/docs/database.md

@@ -29,6 +29,69 @@ await Database.public.todos.delete(todo.id);
 
 See [schema.md](./schema.md) for the full typed-table surface.
 
+## Transaction boundaries and retries
+
+Ordinary Database writes commit when the request completes. `$transaction(fn)`
+builds a synchronous plan executed inside a savepoint of that same transaction.
+A savepoint cannot refresh its parent snapshot or retry the parent's COMMIT;
+passing a nonzero `retry` to `$transaction` is refused with a migration message.
+
+Use `$atomic` for an explicit, independently committed transaction with ordinary
+async reads and writes. Its promise resolves after COMMIT succeeds. Every retry
+opens a fresh transaction and reruns the complete callback, including decision
+reads. Choose `read committed`, `repeatable read` or `serializable` isolation.
+
+```ts
+import { Conflict, NotFound, decrement } from "@palbase/backend";
+
+const result = await Database.$atomic(async (tx) => {
+  const account = await tx.public.accounts.findById(accountId);
+  if (!account) throw new NotFound();
+  // All dependent writes, the ledger and an outbox event belong in this scope.
+  return tx.$transaction((plan) => {
+    return plan.public.accounts.updateWhere(
+      { id: accountId, balance: { gte: amount } },
+      { balance: decrement(amount) },
+    ).expectOne(new Conflict("Insufficient balance"));
+  });
+}, { isolation: "serializable", retry: 3, lockTimeoutMs: 1000, statementTimeoutMs: 5000 });
+```
+
+`retry` defaults to 0 and is limited to 10. Only serialization and deadlock
+failures are retried. A lost connection during COMMIT has an unknown outcome
+and is not automatically replayed; use an idempotency key to reconcile it.
+Keep external effects out of a retried callback: write an outbox record there
+and deliver it after commit.
+
+The complete [money-transfer.ts](./examples/money-transfer.ts) recipe uses the
+public `DBClient.atomic` seam, typed guards, exact integer minor units, a payload
+checked idempotency key, ordered account locks, balanced ledger entries and an
+outbox. Its `transferSchema` declares the database constraints and tenant RLS;
+export it from `db/public.ts`, review `palbase db plan` and run `palbase db apply`.
+It is the same transfer body used by the real PostgreSQL verification suite;
+importing it alone does not apply its constraints. Derive `input.tenant` from verified application scope. Use globally
+unique request keys, or include the tenant in the key. An outbox worker delivers
+after commit and consumers deduplicate by event id.
+
+`$atomic` commits independently: a later handler error does not undo it. Avoid
+writing the same data in the surrounding request transaction. The callback's
+typed `tx` and ambient `Database` calls share its transaction. Handles saved from
+another transaction, nested roots and `$asService()` inside it are refused.
+For service-role work choose `Database.$asService().$atomic(...)` before entering
+the callback; it keeps that one identity throughout every retry.
+
+The request's default and service-role surfaces remain separate transactions;
+their commits are not atomic together. Put a business operation's atomic writes
+in one `$atomic` scope. `fakeDatabase` does not emulate PostgreSQL isolation or
+commit/retry behavior; use a real PostgreSQL test for that boundary.
+
+Schema-aware timestamp results use UTC ISO strings with six fractional digits,
+preserving PostgreSQL microseconds through reads, returned writes, relations,
+aggregates and transaction plan references. Infinities, BC dates and years outside
+1–9999 retain PostgreSQL's text representation. These queries return the declared
+column shape. Raw `$query` results follow the driver's types; request `column::text`
+when a raw query must preserve timestamp precision rather than a JavaScript Date.
+
 ## Raw string-keyed operations
 
 For a table name computed at runtime, or for SQL the typed helpers do not
@@ -706,3 +769,248 @@ Guidelines:
     second surface waits for a lock the first cannot release until the handler
     returns. The service side gives up after five seconds and tells you this;
     the default side would wait until the edge cuts the request.
+## Cursor pages and bulk counts
+
+`page` returns `{ rows, pageInfo }`. A projection narrows `rows` in TypeScript;
+the cursor keeps the ordering values independently, including fields omitted by
+`select`.
+
+```ts
+const page = await Database.public.todos.page({
+  select: ["id", "title"],
+  orderBy: { column: "created_at", direction: "desc" },
+  first: 50,
+  after: cursor, // omit for the first page
+});
+// Next: after: page.pageInfo.endCursor
+// Previous: last: 50, before: page.pageInfo.startCursor
+```
+
+Sizes are 1–1000 (default 50). Use `first`/`after` or `last`/`before` together.
+The engine appends every missing primary-key column to the ordering, including
+composite keys. `direction` and `nulls` are honored independently. Both directions
+return rows in the requested order. Empty pages have null cursors and report
+whether matching rows remain on the opposite side of the supplied boundary.
+The page and its flags use one PostgreSQL statement snapshot. Across requests,
+inserts, deletes and changes to ordering fields can change the list; a cursor is
+not a frozen snapshot. Prefer immutable ordering columns for exports.
+
+Install the table declaration and an index matching the tenant/filter columns
+followed by the ordering columns and primary key. Keyset pagination avoids
+scanning a skipped prefix; it does not provide arbitrary page-number jumps.
+JSON/vector ordering is refused. Text ordering follows the database collation.
+
+In the engine, cursor encryption uses `PALBASE_CURSOR_SECRET`, falling back to
+`PALBASE_SERVICE_ROLE_KEY`. Keep this secret shared across replicas and restarts;
+rotation invalidates existing cursors. Cursors are tied to the table declaration,
+filter, projection, relations, ordering and authorization claims (JWT issuance/
+expiry identifiers are excluded). Reusing one with another query or identity
+returns `BadRequest`. A malformed token is rejected before database access.
+Standalone engine consumers configure `setCursorKey(secret)` from the engine
+entrypoint. `fakeDatabase` requires an explicit page test double; PostgreSQL
+integration tests cover collation, RLS and cursor semantics.
+
+```ts
+const inserted = await Database.public.todos.insertMany(rows, {
+  returning: false,
+});
+```
+
+`inserted` is a number. The engine omits `RETURNING` and reads PostgreSQL's affected
+row count, including zero when `onConflict` with `action: "ignore"` skips every
+row. `action: "update"` counts both inserted and updated rows. The default returns
+rows as before; a dynamic boolean produces a `number | Row[]` type. This option
+belongs to the asynchronous bulk surface; declarative transaction plan row handles
+continue to return their rows. Custom SQL drivers must expose an integer `count`
+on a non-returning result. Empty input opens no connection. The batch remains one
+statement and participates in its enclosing transaction's rollback.
+
+## Reusable queries and response contracts
+
+`defineQuery` combines an explicit selection with a reusable input/filter. The
+result is also a Zod array schema: a controller can return
+`Promise<z.infer<typeof ListTodos>>`, and the existing build binder uses that
+same value for response validation, OpenAPI and generated clients.
+
+```ts
+export const ListTodos = defineQuery("ListTodos", {
+  table: todos, // a defineTable value already registered by defineSchema
+  input: z.object({ prefix: z.string().default("") }),
+  select: ["id", "title"],
+  where: ({ prefix }) => ({ title: { startsWith: prefix } }),
+  orderBy: { column: "id" },
+  limit: 50,
+});
+
+const rows = await ListTodos.run(Database, { prefix: "Buy" });
+const compiled = ListTodos.sql(Database, { prefix: "Buy" }); // no connection
+// compiled.sql and compiled.params describe the same statement run() executes.
+```
+
+`run` validates its input before SQL and its response before returning. SQL uses
+the same SELECT compiler as `findMany`, under the caller's transaction and RLS
+identity. Table names retain their declared schema. Selection is mandatory;
+unselected database columns cannot silently expand the API. Numeric/bigint and
+timestamp outputs retain their exact string representations, and named codecs
+determine the surfaced type. A selected `jsonb<T>()` needs a matching Zod schema
+in `fields: { payload: PayloadSchema }`, because its TypeScript payload is erased
+at runtime. Free-form column transforms require migration to a named codec.
+
+Keep a contract manifest in the application repository:
+
+```ts
+const generated = queryManifest([ListTodos]);
+// Write generated JSON for the initial, reviewed baseline.
+assertQueryManifest([ListTodos], committedManifest); // run in the CI/build check
+```
+
+The manifest contains input/response OpenAPI components, selected storage types,
+nullability and codecs. A changed contract fails the check until its diff is
+reviewed and the committed baseline is updated. The runtime also refuses a query
+whose selected columns disagree with the installed declaration, before SQL.
+This check compares declarations; migration validation still owns drift in the
+physical PostgreSQL schema. Queries currently project one table; use `findMany`
+or `page` for nested relation reads.
+
+`await ListTodos.explain(Database, input)` executes plain `EXPLAIN (FORMAT JSON)`
+with the same role and parameters. It never enables `ANALYZE`. Plans can contain
+filter literals, so inspect them in development/operator tooling. No EXPLAIN is
+run automatically on production requests. The complete controller/schema example
+is [examples/database-dx.ts](./examples/database-dx.ts).
+
+## Nested relations and unique lookups
+
+`with` accepts three relation edges, with independent selection, filtering,
+ordering and limits at each level. The whole read remains one SQL statement.
+Each related table retains RLS; `many` returns an array, `one` returns a row or
+null. Numeric/bigint strings, timestamp microseconds, vectors and named codecs
+are restored at each level. Joins use the foreign key's declared target column,
+including a non-primary unique column.
+
+```ts
+const customers = await Database.billing.customers.findMany({
+  select: ["id"],
+  with: { invoices: { select: ["id"], limit: 10,
+    with: { customer: { select: ["name"] } },
+  } },
+});
+
+const account = await Database.public.accounts.findUnique({
+  where: { tenant_id: tenantId, account_number: number },
+  select: ["balance"],
+});
+```
+
+The lookup example requires a declared unique/primary key on
+`["tenant_id", "account_number"]`. Regenerate `palbase-env.d.ts` to get exact key
+types. Supply one entire key; partial composites, mixed keys, operators and null
+values are refused. A missing or RLS-hidden row returns null. More than one match
+raises a constraint-drift error. The direct `makeTypedDB` facade validates keys
+at runtime; the generated `Database.<schema>.<table>` surface also checks them at
+compile time. `findById` keeps its existing `id`-column contract.
+
+## Commands and workload admission
+
+`$command` accepts the synchronous transaction-plan callback used by
+`$transaction`. It retains guards, dependent row references, sequential visibility
+and savepoint rollback. Its default `mode: "auto"` compiles supported plans when
+the helper is installed and uses the sequential path otherwise. Choose
+`mode: "compiled"` to require compilation or `mode: "sequential"` to opt out.
+It settles with its enclosing transaction; an independently durable command
+belongs inside `$atomic`.
+
+Enable the helper with `PALBASE_DB_COMMANDS=true`; standalone engine consumers
+call `installCommandExecutor(driver, roles)`. Installation needs DDL rights.
+Execution is `SECURITY INVOKER`, so the caller's role and RLS remain active.
+Compilation currently excludes SQL fragments, column codecs/transforms, vector
+tables, nullable WHERE references and certain JavaScript number/JSON scalar
+bindings whose driver semantics would differ. Strict mode refuses these before
+SQL; automatic mode preserves the sequential behavior. Plans with no row refs
+send parameterized statements in order on one connection without waiting for
+each result before submitting the next. SQL guards abort before later queued
+writes run, and the engine drains every result before rollback. These are still
+separate SQL statements, with sequential visibility. Plans with row refs use
+one invoker helper call with sequential statements inside PostgreSQL. The helper
+adds JSON/dynamic-SQL processing; measure the actual plan and network before
+selecting it for throughput. Fewer round trips alone do not guarantee a speedup.
+
+For contention on the same accounts/resources, declare a workload once:
+
+```ts
+const transfers = defineWorkload("transfers", {
+  concurrency: 16, queueLimit: 128,
+  tenantConcurrency: 8, tenantQueueLimit: 32, queueTimeoutMs: 1000,
+});
+
+await Database.$atomic(async tx => {
+  // Decision reads, idempotency claim, writes, ledger and outbox belong here.
+}, {
+  workload: transfers,
+  conflictKeys: [fromAccountId, toAccountId],
+  timeoutMs: 3000, signal, retry: 2,
+});
+```
+
+Overlapping resource keys are admitted in order. Independent keys and tenants
+can proceed while those requests wait. Queue size and per-tenant budgets are
+bounded; full/expired queues return 429 before opening a transaction. Tenant
+identity comes from the configured verified claim (`tenant_id`, then `sub`, then
+one anonymous bucket). Keys are shared within a workload; include the tenant in
+a key if resource IDs are only tenant-unique. Rejected/cancelled waiters leave the
+queue. The lease spans every retry and transaction settlement.
+
+These limits apply per engine/driver instance. Divide pool/admission budgets
+across replicas; PostgreSQL locks and constraints remain authoritative across
+instances. Admission is optional because independent work also pays its cost.
+Each driver supports at most 64 named workloads.
+
+`timeoutMs` includes queueing, callback work and retries. The default driver uses
+a separate control pool of at most two connections to cancel active PostgreSQL
+statements. Reserve those connections in the deployment budget. Standalone Bun
+drivers can use `withQueryCancellation(applicationPool, controlPool)` with the
+same server/login. The engine waits for cancellation and rollback before releasing
+the application connection. JavaScript callbacks themselves are not preempted;
+late DB handles are invalidated. Pool acquisition and an in-flight COMMIT still
+have to settle, so the deadline is not a hard wall-clock response guarantee.
+An acknowledged COMMIT stays successful; an unknown commit outcome is never
+automatically replayed.
+
+## Query diagnostics and budgets
+
+Set `PALBASE_DB_DIAGNOSTICS=true` for request summaries, or provide
+`EngineConfig.databaseDiagnostics` with `onQuery`/`onComplete` callbacks.
+Standalone consumers pass the same options as the third argument to
+`createRequestDatabase`. Diagnostics are disabled by default. For a route budget:
+
+```ts
+@Get("/", { databaseBudget: { maxQueries: 8, maxRows: 100, maxBytes: 65536 } })
+```
+
+Counts include application SQL, authorization reads, service queries and retries;
+transaction setup is timed separately. Query count is checked before SQL. Row
+and estimated JSON-byte budgets are checked after results arrive; use SQL limits
+and projections to avoid producing excessive data. A caught budget error still
+prevents COMMIT of the affected transaction. An earlier independent `$atomic`
+commit remains durable.
+
+Summaries correlate the route/request ID with query names and SQL fingerprints.
+`captureSource: true` adds a bounded runtime stack; `includeSql: true` adds bounded
+SQL text. Bind values are never recorded. Raw SQL text can itself contain inline
+literals. `Database.$diagnostics()` returns the current snapshot, or null when
+disabled; the completion callback includes settlement timings. Only the first
+200 completed statements are retained, while totals cover every statement.
+
+| Metric | Meaning |
+| --- | --- |
+| `queueMs` | Workload admission wait, including refused waits |
+| `poolMs` | Driver acquisition through transaction callback entry, including BEGIN |
+| `setupMs` | Isolation, cancellation ticket and role/claims setup |
+| `sqlMs` | Awaited driver time, including execution, lock and network waits |
+| `commitMs` / `rollbackMs` | Observed settlement waits |
+| `rows` / `bytes` | Returned root rows / estimated JSON result bytes, not wire bytes |
+| `commits` / `commitFailures` | Acknowledged commits / failed commit acknowledgements |
+| `rollbackRequests` / `retries` | Requested rollbacks / whole-transaction replays |
+
+Durations can overlap across concurrent operations; summing them is not request
+wall time. The driver cannot separate lock wait from server execution. Telemetry
+callback failures do not change an acknowledged transaction outcome.

package/docs/examples/check-query-contracts.ts

@@ -0,0 +1,5 @@
+import { readFileSync } from "node:fs";
+import { assertQueryManifest } from "@palbase/backend";
+import { ListTodos } from "./database-dx.js";
+
+assertQueryManifest([ListTodos], JSON.parse(readFileSync(new URL("./database-dx.contract.json", import.meta.url), "utf8")));

package/docs/examples/database-dx.contract.json

@@ -0,0 +1,65 @@
+{
+  "queries": [
+    {
+      "columns": {
+        "done": {
+          "nullable": false,
+          "type": "boolean"
+        },
+        "id": {
+          "nullable": false,
+          "type": "uuid"
+        },
+        "title": {
+          "nullable": false,
+          "type": "text"
+        }
+      },
+      "components": {
+        "parameters": {},
+        "schemas": {
+          "ListTodosInput": {
+            "properties": {
+              "prefix": {
+                "default": "",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "ListTodosResponse": {
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "done": {
+                  "type": "boolean"
+                },
+                "id": {
+                  "type": "string"
+                },
+                "title": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "id",
+                "title",
+                "done"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          }
+        }
+      },
+      "name": "ListTodos",
+      "select": [
+        "id",
+        "title",
+        "done"
+      ],
+      "table": "dx_todos"
+    }
+  ],
+  "version": 1
+}

package/docs/examples/database-dx.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import {
+  Controller, Get, QueryParams, Module, Injectable, Database, defineQuery, defineWorkload,
+  defineSchema, defineTable, uuid, text, boolean, timestamp, ownedByUser,
+} from "@palbase/backend";
+
+export const todos = defineTable("dx_todos", {
+  columns: {
+    id: uuid().primaryKey().defaultRandom(),
+    owner_id: ownedByUser(),
+    external_key: text(),
+    title: text(),
+    done: boolean().default(false),
+    created_at: timestamp().defaultNow(),
+  },
+  unique: [{ name: "dx_todos_owner_key", columns: ["owner_id", "external_key"] }],
+});
+export const schema = defineSchema("public", { tables: [todos] });
+
+export const ListTodos = defineQuery("ListTodos", {
+  table: todos,
+  input: z.object({ prefix: z.string().default("") }),
+  select: ["id", "title", "done"],
+  where: ({ prefix }) => ({ title: { startsWith: prefix } }),
+  orderBy: { column: "id" },
+  limit: 50,
+});
+
+@Injectable()
+export class TodoQueries {
+  list(input: z.input<typeof ListTodos.input>) { return ListTodos.run(Database, input); }
+}
+
+@Controller("/dx-todos", { auth: true })
+export class DatabaseDxController {
+  constructor(private readonly todos: TodoQueries) {}
+
+  @Get("/", { databaseBudget: { maxQueries: 8, maxRows: 50, maxBytes: 65536 } })
+  list(@QueryParams(ListTodos.input) input: z.input<typeof ListTodos.input>): Promise<z.infer<typeof ListTodos>> {
+    return this.todos.list(input);
+  }
+}
+
+@Module({ controllers: [DatabaseDxController], providers: [TodoQueries] })
+export class DatabaseDxModule {}
+
+// The generated palbase-env.d.ts knows the complete composite unique key.
+export function findExternalTodo(ownerId: string, key: string) {
+  return Database.public.dx_todos.findUnique({ where: { owner_id: ownerId, external_key: key }, select: ["id", "title"] });
+}
+
+// Optional admission for repeated writes to the same resource.
+const writes = defineWorkload("todo-writes", { concurrency: 8, queueLimit: 32, tenantConcurrency: 4, tenantQueueLimit: 8 });
+export function finishTodo(id: string, signal?: AbortSignal) {
+  return Database.$atomic(tx => tx.public.dx_todos.update({ where: { id }, set: { done: true } }), {
+    workload: writes, conflictKeys: [id], timeoutMs: 1000, signal, retry: 2,
+  });
+}
+
+export function readPage(after?: string) {
+  return Database.public.dx_todos.page({ select: ["id", "title"], first: 20, after,
+    orderBy: { column: "created_at", direction: "desc" } });
+}

package/docs/examples/money-transfer.ts

@@ -0,0 +1,73 @@
+/** Exact integer transfer with idempotency, ordered locks, ledger and outbox.
+ * Export transferSchema from db/public.ts and review/apply it with palbase db.
+ * This raw DBClient recipe is also exercised by the real PostgreSQL verifiers.
+ */
+import { defineSchema, defineTable, uuid, text, bigint, makeTypedDB, increment, decrement, policy } from "@palbase/backend";
+import type { DBClient, AtomicOptions } from "@palbase/backend";
+
+const tenant = "tenant_id = (SELECT current_setting('request.jwt.claims',true)::jsonb->>'tenant_id')";
+const tenantPolicy = () => policy("tenant_scope").for("all").to("authenticated").using(tenant).withCheck(tenant);
+const accounts = defineTable("accounts", { policies: () => [tenantPolicy()],
+  checks: [{ name: "accounts_nonnegative", expr: "balance >= 0" }], columns: {
+  id: uuid().primaryKey(), tenant_id: text().notNull(), balance: bigint().notNull(),
+} });
+const transfers = defineTable("transfers", { policies: () => [tenantPolicy()], checks: [
+  { name: "transfers_positive", expr: "amount > 0" }, { name: "transfers_distinct", expr: "from_id <> to_id" },
+], columns: {
+  id: text().primaryKey(), tenant_id: text().notNull(),
+  from_id: uuid().notNull().references(() => accounts.id, { reverseAs: "outgoing" }),
+  to_id: uuid().notNull().references(() => accounts.id, { reverseAs: "incoming" }), amount: bigint().notNull(),
+} });
+const ledger = defineTable("ledger", { appendOnly: true, policies: () => [
+  policy("tenant_read").for("select").to("authenticated").using(tenant),
+  policy("tenant_insert").for("insert").to("authenticated").withCheck(tenant),
+], unique: [{ name: "ledger_transfer_account", columns: ["transfer_id", "account_id"] }], columns: {
+  id: uuid().primaryKey(), tenant_id: text().notNull(),
+  transfer_id: text().notNull().references(() => transfers.id),
+  account_id: uuid().notNull().references(() => accounts.id), amount: bigint().notNull(),
+} });
+const outbox = defineTable("outbox", { policies: () => [tenantPolicy()], columns: {
+  id: text().primaryKey().references(() => transfers.id), tenant_id: text().notNull(), kind: text().notNull(),
+} });
+export const transferSchema = defineSchema("public", { tables: [accounts, transfers, ledger, outbox] });
+
+export interface TransferInput {
+  /** Tenant must come from the authenticated application scope, not a trusted body field. */
+  tenant: string;
+  key: string;
+  from: string;
+  to: string;
+  /** Integer minor units; no JS floating point arithmetic. */
+  amount: string;
+}
+
+export async function transferAtomic(database: Pick<DBClient, "atomic">, input: TransferInput, options: AtomicOptions = {}) {
+  const amount = BigInt(input.amount);
+  if (amount <= 0n || input.from === input.to || input.key.length === 0) throw new Error("invalid_transfer");
+  const canonical = amount.toString();
+  return database.atomic(async raw => {
+    const claim = await raw.claim("transfers", { id: input.key }, {
+      tenant_id: input.tenant, from_id: input.from, to_id: input.to, amount: canonical,
+    });
+    if (!claim.inserted) {
+      if (claim.row.from_id !== input.from || claim.row.to_id !== input.to ||
+          claim.row.tenant_id !== input.tenant || claim.row.amount !== canonical) throw new Error("idempotency_conflict");
+      return { id: input.key, inserted: false };
+    }
+    await raw.lockRows("accounts", [input.from, input.to]);
+    const typed = makeTypedDB(transferSchema, raw);
+    await typed.transaction(tx => {
+      tx.tables.accounts.updateWhere({ id: input.from, balance: { gte: canonical } }, { balance: decrement(canonical) })
+        .expectOne(new Error("insufficient_or_hidden_source"));
+      tx.tables.accounts.updateWhere({ id: input.to }, { balance: increment(canonical) })
+        .expectOne(new Error("missing_or_hidden_destination"));
+      tx.tables.ledger.insertMany([
+        { id: crypto.randomUUID(), tenant_id: input.tenant, transfer_id: input.key, account_id: input.from, amount: (-amount).toString() },
+        { id: crypto.randomUUID(), tenant_id: input.tenant, transfer_id: input.key, account_id: input.to, amount: canonical },
+      ]).expectAtLeast(2, new Error("ledger_missing"));
+      tx.tables.outbox.insert({ id: input.key, tenant_id: input.tenant, kind: "transfer.committed" })
+        .expectOne(new Error("outbox_missing"));
+    });
+    return { id: input.key, inserted: true };
+  }, options);
+}