typion 0.0.0-stage → 0.1.0

package/docs/features/multi-tenant.md

@@ -0,0 +1,165 @@
+# Multi-tenancy
+
+Every row of a collection that asks for it belongs to a tenant, and every read and write stays in the tenant of the
+call. A feature of Typion's core ([the guide](../README.md)), configured once for the application in `defineSetup`,
+turned on per collection.
+
+```ts
+// src/typion.config.ts
+import { type AnyPgColumn, uuid } from 'drizzle-orm/pg-core'
+import { defineConfig, defineSetup } from 'typion'
+import { pglite } from 'typion/db/pglite'
+import { auth } from './auth.ts'
+import { members } from './typion/collections/members.ts'
+import { projects } from './typion/collections/projects.ts'
+import { tenants } from './typion/collections/tenants.ts'
+
+export const setup = defineSetup({
+  // Every tenant column references the tenants. The column's type is written, since the tenants' table is typed
+  // from the setup itself: without it, `setup` refers to itself (TS7022).
+  multiTenant: {
+    column: () =>
+      uuid('tenant_id')
+        .notNull()
+        .references((): AnyPgColumn => tenants.table.id),
+  },
+})
+
+// The context carries the caller's tenant, typed as the column is.
+export type AppContext = { actorId: string | null; tenantId: string | null }
+
+export const config = defineConfig({
+  setup,
+  collections: [tenants, members, projects],
+  db: pglite({ dataDir: '.pglite' }),
+  // `system` here crosses tenants: it looks the caller up before their tenant is known.
+  context: async ({ headers, system }): Promise<AppContext> => {
+    const session = headers === undefined ? null : await auth.api.getSession({ headers })
+    const member =
+      session === null
+        ? null
+        : await system.members.findOne({
+            where: { userId: session.user.id },
+            columns: { tenantId: true },
+          })
+    return { actorId: session?.user.id ?? null, tenantId: member?.tenantId ?? null }
+  },
+})
+declare module 'typion' {
+  interface Register {
+    setup: typeof setup
+    config: typeof config
+  }
+}
+```
+
+```ts
+// src/typion/collections/tenants.ts
+import { text } from 'drizzle-orm/pg-core'
+import { collection } from 'typion'
+
+// The tenants themselves belong to no tenant. Anyone reads an agency's name and slug, visitors of its pages included.
+export const tenants = collection('tenants', {
+  columns: { name: text().notNull(), slug: text().notNull().unique() },
+  public: true,
+})
+```
+
+```ts
+// src/typion/collections/members.ts
+import { text, uuid } from 'drizzle-orm/pg-core'
+import { collection } from 'typion'
+
+export const members = collection('members', {
+  columns: { userId: uuid('user_id').notNull(), role: text().notNull() },
+  tenant: true, // adds `tenantId`, built by `column`
+  public: true,
+})
+```
+
+```ts
+// src/typion/collections/projects.ts
+import { text, uniqueIndex } from 'drizzle-orm/pg-core'
+import { collection } from 'typion'
+
+export const projects = collection('projects', {
+  columns: { name: text().notNull() },
+  tenant: true,
+}).define({
+  access: {
+    read: true,
+    create: ({ ctx }) => ctx.actorId !== null,
+    update: ({ ctx }) => ctx.actorId !== null,
+  },
+  // Unique within a tenant.
+  indexes: (t) => [uniqueIndex('projects_name').on(t.tenantId, t.name)],
+})
+```
+
+```ts
+// A caller of one tenant reads and writes there only; `create` fills the tenant.
+const inAcme = typion.$as({ actorId: null, tenantId: '0b5c…' })
+const project = await inAcme.projects.create({ name: 'Roadmap' })
+project.tenantId satisfies string
+
+// Jobs: one tenant, or every tenant with `unscoped`, where nothing fills the column and the job names it.
+const importer = typion.$system({ reason: 'import', ctx: { tenantId: '0b5c…' } })
+await importer.projects.create({ name: 'Imported' })
+const report = typion.$system({ reason: 'billing report', unscoped: true })
+const perTenant = await report.projects.count()
+void perTenant
+```
+
+- **Reads** stay in the context's tenant at the root, in every `with` and in every relation filter, counts included:
+  another tenant's row is `NOT_FOUND` and cannot be probed. Relations to a tenant collection are typed `| null`, in
+  system mode too.
+- **Writes** lock inside the tenant, so another tenant's row is `NOT_FOUND`; `create` fills `tenantId`, and a write
+  that names another tenant is `FORBIDDEN` (repeating the call's own is harmless). `tenantId` is managed: callers do
+  not write it, system mode can.
+- **References** stay in the tenant: a write that points a tenant collection's row at another tenant's (a project's
+  `clientId` naming another agency's client) is `VALIDATION`, with an issue on the column, as a reference to a row
+  that does not exist is, so it tells the caller nothing. Only `unscoped` calls are not checked.
+- **History and drafts** stay in the tenant too: the versions table clones the column, and `@typion/audit` records the
+  tenant of each entry and keeps its log in the tenant of the call, whoever reads it.
+- **It fails closed**: a call without a tenant is `FORBIDDEN`, system mode included. A job works in one tenant with
+  `$system({ reason, ctx: { tenantId } })` and across all of them with `$system({ reason, unscoped: true })`, where
+  nothing fills the column and the job names it. `unscoped` is not an option of `$as()`, in the types or at runtime.
+- **The context factory** gets a system instance that crosses tenants: it looks the caller up before their tenant is
+  known.
+- **Rules and hooks** see `ctx.unscoped`, true when a system call crosses tenants.
+- **Uniqueness** within a tenant is an index in the collection's `define()`:
+  `indexes: (t) => [uniqueIndex('projects_name').on(t.tenantId, t.name)]`.
+- **Any column** can hold the tenant. A not-null `uuid`, `text` or `integer` costs next to nothing to type-check; the
+  builder of any other is carried in the setup's type, which costs about 13,500 instantiations more and 33 per
+  read on the engine's stress fixture.
+- `typion db seed --random` puts generated rows in `multiTenant: { seedTenant }` or the config's
+  `seed: { values: { tenant } }`.
+
+Without `multiTenant` in the setup none of this exists: no `tenant` option or column, no `unscoped`, no
+`ctx.unscoped`. On a collection that does not ask for it the same holds, and a system call needs no tenant there.
+
+`tenantColumn(entity)` gives the tenant column of an entity's metadata, or `null` where multi-tenancy does not act:
+for a plugin that needs to know which rows belong to a tenant.
+
+## Visitors of a tenant's pages
+
+A visitor has no membership, so the context factory finds no tenant for them, and a read of a tenant collection fails
+closed. The tenant of a public page comes from where the page is: its address. A page that has it in its path binds
+the visitor itself:
+
+```ts
+// The public page /acme/projects: nobody signed in, the tenant from the address. `tenants` is public, so the slug
+// resolves without one.
+const visitor = typion.$as({ actorId: null, tenantId: null })
+const acme = await visitor.tenants.findOne({ where: { slug: 'acme' }, columns: { id: true } })
+if (acme !== null) {
+  const projects = await typion
+    .$as({ actorId: null, tenantId: acme.id })
+    .projects.find({ columns: { name: true } })
+  void projects
+}
+```
+
+The rules decide the rest as for anyone: a visitor reads what `read` lets an anonymous caller read, in that tenant.
+When the tenant is the host (`acme.example.com`), the context factory can read it from `headers` instead, with the
+same lookup, for every route of the application at once.

package/docs/features/soft-delete.md

@@ -0,0 +1,85 @@
+# Soft delete
+
+A deleted row keeps its row and its id, and every read hides it. A feature of Typion's core
+([the guide](../README.md)), in every config: a collection turns it on.
+
+```ts
+// src/typion.config.ts
+import { defineConfig, defineSetup } from 'typion'
+import { pglite } from 'typion/db/pglite'
+import { notes } from './typion/collections/notes.ts'
+
+// Soft delete and versions need no line here: a collection turns them on.
+export const setup = defineSetup({})
+
+export const config = defineConfig({
+  setup,
+  collections: [notes],
+  db: pglite({ dataDir: '.pglite' }),
+  context: (): { actorId: string | null; role: 'admin' | 'editor' | null } => ({
+    actorId: null,
+    role: null,
+  }),
+})
+
+declare module 'typion' {
+  interface Register {
+    setup: typeof setup
+    config: typeof config
+  }
+}
+```
+
+```ts
+// src/typion/collections/notes.ts
+import { text } from 'drizzle-orm/pg-core'
+import { collection, softUnique } from 'typion'
+
+export const notes = collection('notes', {
+  columns: { title: text().notNull(), slug: text().notNull() },
+  softDelete: true, // adds a nullable `deletedAt` (`deleted_at timestamptz`)
+  public: true,
+}).define({
+  access: {
+    create: ({ ctx }) => ctx.actorId !== null,
+    update: ({ ctx }) => ctx.actorId !== null, // also `restore`
+    // The rule sees the options of the call: removing a row for good is for admins.
+    delete: ({ ctx, options }) => options.hard !== true || ctx.role === 'admin',
+  },
+  // Unique among the rows that are not deleted.
+  indexes: (t) => [softUnique('notes_slug_live', t.deletedAt).on(t.slug)],
+})
+```
+
+```ts
+const note = await app.notes.create({ title: 'Draft plan', slug: 'plan' })
+await app.notes.delete(note.id)
+
+await app.notes.count() // the deleted note is not counted
+await app.notes.find({ columns: { title: true }, withDeleted: true }) // it is here
+await app.notes.restore(note.id)
+await app.notes.delete(note.id, { hard: true }) // gone for good
+```
+
+- **Deletes** set `deletedAt` on the row; `delete(id, { hard: true })` removes it for good, deleted or not. The
+  `delete` rule sees the options of the call: `delete: ({ options, ctx }) => !options.hard || ctx.role === 'admin'`.
+- **Reads** hide deleted rows at the root, in every `with` and in every relation filter, counts included;
+  `withDeleted: true` shows them for the whole read. Relations to a soft-deleted collection are typed `| null`.
+- **`restore(id)`** clears `deletedAt` through the update pipeline (the `update` rule, hooks with `op: 'restore'`, the
+  version, the audit trail), on deleted rows only. It is also a descriptor (`q.posts.restore({ id })`), a route, and
+  a method of `typion` in hooks and rules, which get the application's own instance.
+- **References** to a deleted row are refused: a create or an update that points at one (a task on an archived
+  project) is `VALIDATION`, with an issue on the column, as a reference to a row that does not exist is. A write that
+  means it says so, `create(data, { withDeleted: true })`: the option exists on the collections with a relation to a
+  soft-deleted one. Drafts are not refused; another tenant's row is, whatever the option (multi-tenancy).
+- **`deletedAt` is managed**: callers cannot write it, system mode can.
+- **Over HTTP**: `DELETE /api/posts/:id?hard=true`, `GET /api/posts?withDeleted=true`, `POST /api/posts/:id/restore`.
+- **Uniqueness** among the rows that are not deleted is a partial index, in the collection's `define()`:
+  `indexes: (t) => [softUnique('posts_slug_live', t.deletedAt).on(t.slug)]`.
+- `typion db seed --random` generates rows that are not deleted.
+
+On a collection that does not ask for it none of this exists: no column, no `withDeleted`, `hard` or `restore`, no
+route; the types refuse them, and the runtime has no `restore` there and answers `UNSUPPORTED` to its options.
+
+`softDeleteColumn(entity)` gives the column of an entity's metadata, or `null` where soft delete does not act: for a
+plugin that needs to know which rows are deleted.

package/docs/features/versions.md

@@ -0,0 +1,106 @@
+# Versions and drafts
+
+Every change of a collection that asks for it appends a version, and with drafts a published document keeps its live
+row while edits wait for `publish`. A feature of Typion's core ([the guide](../README.md)), in every config: a
+collection turns it on.
+
+```ts
+// src/typion.config.ts
+import { defineConfig, defineSetup } from 'typion'
+import { pglite } from 'typion/db/pglite'
+import { posts } from './typion/collections/posts.ts'
+
+// Soft delete and versions need no line here: a collection turns them on.
+export const setup = defineSetup({})
+
+export const config = defineConfig({
+  setup,
+  collections: [posts],
+  db: pglite({ dataDir: '.pglite' }),
+  context: (): { actorId: string | null; role: 'admin' | 'editor' | null } => ({
+    actorId: null,
+    role: null,
+  }),
+})
+
+declare module 'typion' {
+  interface Register {
+    setup: typeof setup
+    config: typeof config
+  }
+}
+```
+
+```ts
+// src/typion/collections/posts.ts
+import { text, uuid } from 'drizzle-orm/pg-core'
+import { collection } from 'typion'
+
+export const posts = collection('posts', {
+  columns: {
+    title: text().notNull(),
+    slug: text().notNull(),
+    authorId: uuid('author_id').notNull(),
+  },
+  versions: { drafts: true, max: 20 }, // adds `status` and `publishedAt`; `versions: true` for a history alone
+}).define({
+  access: {
+    read: true, // plain reads see published rows only
+    readDrafts: ({ ctx }) => (ctx.actorId === null ? false : { authorId: ctx.actorId }), // `draft: true` reads, instead of `read`
+    readVersions: ({ ctx }) => ctx.actorId !== null, // the history
+    create: ({ ctx, data }) => ctx.actorId !== null && data.authorId === ctx.actorId,
+    update: ({ ctx }) => (ctx.actorId === null ? false : { authorId: ctx.actorId }),
+    publish: ({ ctx }) => ctx.role === 'admin', // publish, unpublish, create({ publish: true })
+  },
+})
+```
+
+```ts
+const actorId = app.$ctx.actorId
+if (actorId !== null) {
+  const post = await app.posts.create({ title: 'Hello', slug: 'hello', authorId: actorId }) // a draft
+  await app.posts.publish(post.id)
+  await app.posts.update(post.id, { title: 'Hello, world' }, { draft: true }) // the live row stays as it is
+
+  const drafts = await app.posts.find({ draft: true, columns: { title: true } }) // the latest drafts
+  drafts satisfies { title: string }[]
+  const [latest] = await app.posts.versions.list(post.id, { limit: 1 })
+  if (latest !== undefined) {
+    latest.data.title satisfies string
+    await app.posts.versions.restore(post.id, latest.versionId, { draft: true })
+  }
+  await app.posts.discardDraft(post.id)
+}
+```
+
+- **History**: every create, update and kept delete records a version in `typion.posts_versions`, a copy of the
+  collection's columns with the actor, the mode, the system reason and the request. `versions.list(id, { limit,
+offset, state })`, `versions.get(id, versionId)` and `versions.diff(id, from, to)` read it under `readVersions`;
+  `versions.restore(id, versionId, { draft })` writes a version back through the update pipeline. `max` keeps the
+  newest versions, the latest and the last published one.
+- **Drafts**: `create` makes a draft unless `{ publish: true }`; `update(id, data, { draft: true })` on a published
+  document writes a draft version and leaves the live row as it is, `publish(id)` makes the latest draft live,
+  `unpublish(id)` turns the live row back into a draft, and `discardDraft(id)` records the live row again. A live
+  update over a pending draft supersedes it, or is refused with `onPendingDraft: 'reject'`.
+- **Reads** see published rows only, at the root, in every `with` and in every relation filter, so relations to a
+  collection with drafts are typed `| null`. `find({ draft: true })` reads the latest drafts at the root, under
+  `readDrafts`; nested levels stay live.
+- **Hooks** get `draft` (the write left the live row as it is), `previousDraft` (the pending draft it built on,
+  published, superseded or discarded) and `version` (the version it recorded) — on every collection, `false` and
+  `null` where it does not act; a plugin's hooks get them too, typed. The
+  workflow's `op` is `publish`, `unpublish`, `discardDraft` or `versions.restore`; soft delete's `restore` is
+  recorded under its own name.
+- **`status` and `publishedAt` are managed**: callers cannot write them, system mode can.
+- **Over HTTP**: `POST /api/posts/:id/publish` (also `/unpublish`, `/discard-draft`), `GET /api/posts?draft=true`,
+  `GET /api/posts/:id/versions?limit=10`, `GET /api/posts/:id/versions/:versionId`,
+  `GET /api/posts/:id/diff?from=&to=`, `POST /api/posts/:id/versions/:versionId/restore`; each is also a descriptor
+  (`q.posts.publish({ id })`, `q.posts.versions.list({ id, limit })`).
+- **Partitions** hold for the history and the drafts: with multi-tenancy a tenant never reads another's versions,
+  since the versions table copies its column.
+- `typion db seed --random` generates published rows: a draft would be invisible to every plain read.
+
+On a collection that does not ask for drafts none of the workflow exists, and without `versions` none of the history:
+no columns or table, no `draft` or `publish` option, no method, descriptor or route, no `readDrafts`, `readVersions`
+or `publish` rule; the types refuse them, and the runtime answers `UNSUPPORTED`.
+
+`versionsTable(entity)` gives the versions table of an entity's metadata, or `null` where versions does not act.

package/docs/hooks.md

@@ -0,0 +1,106 @@
+# Hooks
+
+Hooks run when a row is written. They sit in a collection's `define({ hooks })` and are typed against the registered
+config, so `typion` inside them is the application's own instance.
+
+```ts
+// src/typion/collections/comments.ts
+import { boolean, text, uuid } from 'drizzle-orm/pg-core'
+import { collection } from 'typion'
+import { sendMail } from '../../lib/mailer.ts'
+import { posts } from './posts.ts'
+import { users } from './users.ts'
+
+export const comments = collection('comments', {
+  columns: {
+    body: text().notNull(),
+    approved: boolean().notNull().default(false),
+    postId: uuid('post_id')
+      .notNull()
+      .references(() => posts.table.id),
+    authorId: uuid('author_id')
+      .notNull()
+      .references(() => users.table.id),
+  },
+  relations: (r) => ({
+    post: r.one('posts', { from: 'postId', to: 'id', optional: false }),
+    author: r.one('users', { from: 'authorId', to: 'id', optional: false }),
+  }),
+  // Only admins approve; a caller who sets `approved` gets FORBIDDEN, never a silent drop.
+  fields: { approved: { write: ({ ctx }) => ctx.role === 'admin' } },
+}).define({
+  access: {
+    read: ({ ctx }) =>
+      ctx.role === 'admin'
+        ? true
+        : ctx.actorId === null
+          ? { approved: true }
+          : { OR: [{ approved: true }, { authorId: ctx.actorId }] },
+    create: ({ ctx, data }) => ctx.actorId !== null && data.authorId === ctx.actorId,
+    update: ({ ctx }) => ctx.role === 'admin',
+    delete: ({ ctx }) => ctx.role === 'admin',
+  },
+  hooks: {
+    beforeChange: async ({ op, data, typion }) => {
+      if (op !== 'create') return
+      // The caller's own instance, in the same transaction: a post they may not read is NOT_FOUND here too,
+      // so nobody comments on a draft they cannot see.
+      await typion.posts.findById(data.postId, { columns: { id: true } })
+      return { ...data, body: data.body.trim() }
+    },
+    // After the commit, outside the transaction: e-mail, webhooks and caches go here, never in afterChange, which
+    // would still have run if the write rolled back.
+    afterCommit: async ({ op, doc }) => {
+      if (op === 'create' && doc !== null) {
+        await sendMail({
+          to: 'moderation@example.test',
+          subject: 'A comment to review',
+          text: doc.body,
+        })
+      }
+    },
+  },
+})
+```
+
+## Order of a write
+
+Access → the features' values (the tenant set or checked, the draft plan) → `beforeValidate` → defaults → validation →
+`beforeChange` → the references checked (the tenant, deleted rows) → the write → the version recorded → `afterChange` → `COMMIT` →
+`afterCommit`. A throw anywhere before
+the commit rolls everything back, the history and the audit trail included.
+
+| Hook             | Gets                                                                | May return           |
+| ---------------- | ------------------------------------------------------------------- | -------------------- |
+| `beforeValidate` | `op`, `data` (as the caller gave it), `original` (`null` on create) | a replacement `data` |
+| `beforeChange`   | the same, after defaults and validation                             | a replacement `data` |
+| `afterChange`    | `op`, `doc`, `previous`, `changes` (the keys that changed)          | nothing              |
+| `beforeDelete`   | `doc`, `options` (`{ hard }` with soft delete)                      | nothing              |
+| `afterDelete`    | `doc`, `options`                                                    | nothing              |
+| `afterCommit`    | `op`, `doc`, `previous`, `ctx`, `meta`                              | nothing              |
+
+- `op` is `'create'` or `'update'`, or the operation of a feature that writes the row: `restore`, `publish`,
+  `unpublish`, `discardDraft`, `versions.restore`. Narrow on it before reading `data`: on create every required
+  column is there, on update `data` is partial.
+- Every hook but `afterCommit` also gets `ctx`, `meta` (entity, operation, mode, request id, time), `typion`, `tx` and
+  `bag`, and with versions `draft`, `previousDraft` and `version` ([features/versions.md](features/versions.md)).
+- `doc`, `previous` and `original` are whole stored rows: every column, a localized one as its object of locales.
+
+## What hooks may do
+
+- **Write through `typion`.** It is the caller's own instance, in the caller's mode, joined to the same transaction:
+  rules, tenant and features apply, and each nested call runs in a savepoint, so a hook can catch a failure without
+  aborting the write. This is how a hook keeps another collection in step.
+- **Not leave the transaction for side effects.** E-mail, HTTP calls and cache revalidation go in `afterCommit`; its
+  errors go to the config's `onAfterCommitError` and cannot fail the write, which has already committed.
+- **`tx` is the raw Drizzle transaction**, for a table that is not a collection (an outbox, a plugin's table). Rule 1
+  of [README.md](README.md) holds: the application's collections are written through `typion`.
+- **`bag`** is a `Map` shared by every hook and plugin of one operation, for what one hook computes and another reads.
+- A hook does not authorize. A check that decides who may write belongs in `access`, which runs first and which every
+  caller hits, the HTTP routes included.
+
+## An audit trail
+
+`@typion/audit` records every write in a table of its own, inside the write's transaction, with who made it and what
+changed; installed in `defineSetup({ plugins: [audit()] })`. Its README, `node_modules/@typion/audit/README.md`, says
+how to read the trail and who may: in a multi-tenant application each tenant reads its own.

package/docs/http.md

@@ -0,0 +1,184 @@
+# Pages, routes and the browser
+
+Typion reaches HTTP through **transports**, each a package of its own: `@typion/rest` gives every collection a
+resource, `@typion/rpc` an endpoint for descriptors, which the browser client speaks. The handler mounts the ones the
+application lists and nothing else; every transport turns its requests into descriptors that the core checks before
+they run, so they all answer to the same rules.
+
+## Next.js
+
+The routes of every collection, with the rules of each, in one file:
+
+```ts
+// src/app/api/[...path]/route.ts
+import { rest } from '@typion/rest'
+import { rpc } from '@typion/rpc'
+import { routeHandlers } from 'typion/next'
+import { config } from '@/typion.config.ts'
+
+export const { GET, POST, PATCH, PUT, DELETE, OPTIONS } = await routeHandlers(config, {
+  transports: [rest(), rpc()],
+})
+```
+
+Server components and server actions have no `Request`: `getApp(config)` binds the caller from the headers Next
+resolves for them, through the config's context factory. A page that calls it is rendered per request: with Cache
+Components on, the prerender stops there (`getApp` calls `connection()`), so put what may be static above it or in a
+`<Suspense>` boundary of its own.
+
+```ts
+import { getApp } from 'typion/next'
+import { config } from '@/typion.config.ts'
+import { postCards } from '@/typion/queries.ts'
+
+// What a server component calls; the reader sees what the rules let them see.
+export async function loadFeed() {
+  const app = await getApp(config)
+  return app.$run(postCards)
+}
+```
+
+```ts
+'use server'
+
+import { isTypionError } from 'typion'
+import { getApp } from 'typion/next'
+import { config } from '@/typion.config.ts'
+
+export async function approveComment(id: string): Promise<{ error: string } | null> {
+  const app = await getApp(config)
+  try {
+    await app.comments.update(id, { approved: true })
+    return null
+  } catch (error) {
+    // Refusals and invalid input are outcomes to show; anything else is a bug.
+    if (isTypionError(error)) return { error: error.message }
+    throw error
+  }
+}
+```
+
+A server action needs no permission check of its own: `comments.update` is `FORBIDDEN` for anyone but an admin,
+because the collection says so.
+
+## Hono
+
+```ts
+// src/server.ts
+import { rest } from '@typion/rest'
+import { rpc } from '@typion/rpc'
+import { Hono } from 'hono'
+import { type TypionEnv, typionMiddleware, typionRoutes } from 'typion/hono'
+import { typionErrorResponse } from 'typion/http'
+import { config } from './typion.config.ts'
+
+const app = new Hono<TypionEnv<typeof config>>()
+  // The transports, under the prefix the handler expects (`/api`, its `basePath`).
+  .all('/api/*', typionRoutes(config, { transports: [rest(), rpc()] }))
+  // A route of the application's own, with the caller's instance as `c.var.typion`.
+  .post('/app/posts/:id/archive', typionMiddleware(config), async (c) => {
+    const id = c.req.param('id')
+    const post = await c.var.typion.$transaction(async (tx) => {
+      await tx.comments.deleteMany({ postId: id }, { max: 500 })
+      return tx.posts.delete(id)
+    })
+    return c.json({ data: post })
+  })
+  // A refusal in the application's own routes answers as the transports do: `{ error: { code, status, … } }`, and
+  // `401` to a caller who has not signed in.
+  .onError((error, c) => typionErrorResponse(error, { caller: c.var.typion }))
+
+export default app
+```
+
+- `typionRoutes` passes the request on as it came; mount it with `app.all` at the handler's base path. Hono's `mount()`
+  strips the prefix first and would leave the handler nothing to match.
+- `typionMiddleware` runs the config's context factory for every request it covers: put it on the routes that use it,
+  not on `*`. Routes written this way are typed end to end by Hono's client (`hc`).
+- Nothing before Typion may read the request's body. An auth route (Better Auth's `/api/auth/*`) goes before the
+  `/api/*` catch-all ([auth.md](auth.md)).
+- `typionErrorResponse(error)` answers a `TypionError` with its status and the wire envelope, and anything else with
+  a bare `500` that does not leak its message. Given the caller (`{ caller: app }`), it answers a refusal of one who
+  has not signed in with `401`, as the transports do.
+- Node, Bun and Vercel run it as written. Cloudflare Workers do not yet: the instance keeps its database connection
+  across requests, which Workers forbid.
+
+## Other frameworks
+
+`createHandler(typion, { transports })` from `typion/http` is a `(request: Request) => Promise<Response>`, mounted
+under `/api` by default; `toRouteHandlers(handler)` turns it into one function per method. On TanStack Start, a server
+route gives each method `({ request }) => handler(request)`.
+
+## The routes
+
+`@typion/rest`:
+
+| Route                                                                     | Does                                               |
+| ------------------------------------------------------------------------- | -------------------------------------------------- |
+| `GET /api/posts?columns=slug,title&with=author&limit=10`                  | `find`, configured by the query string             |
+| `GET /api/posts?where[title][ilike]=%25x%25&sort=-createdAt`              | filters in brackets, sorting with `sort`           |
+| `POST /api/posts/find`, `/find-one`, `/page`, `/count`                    | the read with its whole config as JSON             |
+| `GET /api/posts/:id`                                                      | `findById`                                         |
+| `POST /api/posts` · `PATCH /api/posts/:id` · `DELETE /api/posts/:id`      | `create` (`{ data, options }`), `update`, `delete` |
+| `POST /api/posts/:id/publish`, `/unpublish`, `/discard-draft`, `/restore` | the features' operations                           |
+| `GET /api/posts/:id/versions`, `/versions/:versionId`, `/diff?from=&to=`  | the history                                        |
+| `POST /api/posts/:id/link/tags`, `/unlink/tags`                           | the links of a many-to-many (`{ ids }`)            |
+
+`@typion/rpc`: `POST /api/_rpc` takes one descriptor, or an array of them run one after the other.
+
+What a request carries is checked before anything reaches SQL: an unknown key, column, relation or operator is
+`400`, as are `RAW`, `extras`, callbacks, a `limit` over `maxLimit` (100) and a `with` deeper than `maxDepth` (4).
+Bulk writes (`update-many`, `delete-many`, over either transport) run only with `exposeBulk: true`. A refusal is
+`403 FORBIDDEN`, or `401 UNAUTHENTICATED` when the caller has not signed in (the context's `actorId` is null), so a
+page can tell "sign in" from "not allowed"; in process both are `FORBIDDEN`. The handler's
+options: `transports`, `basePath`, `expose` (the collections to serve; all by default, each behind its rules, a
+plugin's entity such as audit's `auditLog` included), `exclude` (the ones to leave out),
+`exposeBulk`, `maxLimit`, `maxDepth`, `codecs` (`['json', 'superjson']` to keep dates exact), `cors`, `debug`,
+`onError` (where a `500` is reported: the server's log by default, an error tracker's `captureException`). The
+plugins' own routes (`/api/_plugins/<id>/…`) are served whatever transports are mounted.
+
+## The browser client
+
+```ts
+import { createClient } from '@typion/rpc/client'
+import { postCards } from '@/typion/queries.ts'
+
+const client = createClient({ url: '/api' })
+// Plain JSON: dates arrive as ISO strings, which the result type says.
+const cards = await client.run(postCards)
+cards satisfies { id: string; slug: string; title: string; author: { name: string } }[]
+```
+
+The client posts descriptors to `/api/_rpc`, so it needs `rpc()` mounted; it imports no server code and no Drizzle.
+A mobile app uses the same client with `headers: () => ({ authorization: 'Bearer ' + token })`, and the config's
+context factory reads the token. A failed call throws `TypionRequestError` with the wire error's `code`, `status` and
+`issues`: `UNAUTHENTICATED` is the cue to send the user to sign in.
+
+## Business operations
+
+Typion has no procedures of its own. An operation that is more than one write — archiving a post with its comments,
+an order with its lines — is a server action, a route handler or a Hono route (above) that binds the caller and runs
+the writes in one transaction. The rules still decide each write; the operation only composes them.
+
+```ts
+// src/app/api/posts/[id]/archive/route.ts
+import { getTypion } from 'typion'
+import { typionErrorResponse } from 'typion/http'
+import { config } from '@/typion.config.ts'
+
+export async function POST(request: Request, { params }: { params: Promise<{ id: string }> }) {
+  const typion = await getTypion(config)
+  const app = await typion.$fromRequest(request)
+  const { id } = await params
+  try {
+    const post = await app.$transaction(async (tx) => {
+      await tx.comments.deleteMany({ postId: id }, { max: 500 })
+      return tx.posts.delete(id)
+    })
+    return Response.json({ data: post })
+  } catch (error) {
+    // NOT_FOUND for a post the caller may not delete, VALIDATION, CONFLICT: as the transports answer them.
+    return typionErrorResponse(error)
+  }
+}
+```