typion 0.0.0-stage → 0.1.0

package/docs/access.md

@@ -0,0 +1,112 @@
+# Access
+
+Who may read and write what is decided by each collection's `access` rules, and nowhere else. A page, a server action
+or a route that checks permissions on top is a convenience for the interface; the rule is what holds for every caller,
+over HTTP included.
+
+## The rules
+
+| Rule           | Decides                                                               | Gets                    | Returns           |
+| -------------- | --------------------------------------------------------------------- | ----------------------- | ----------------- |
+| `read`         | which rows a read sees, at every level                                | `ctx`, `meta`, `typion` | boolean or filter |
+| `create`       | whether this input may be created                                     | the same, and `data`    | boolean           |
+| `update`       | which rows may be updated, and with what                              | the same, and `data`    | boolean or filter |
+| `delete`       | which rows may be deleted                                             | the same, and `options` | boolean or filter |
+| `readDrafts`   | which drafts a `draft: true` read sees (collections with drafts)      | `ctx`, `meta`, `typion` | boolean or filter |
+| `readVersions` | whether the history may be read (collections with versions)           | `ctx`, `meta`, `typion` | boolean           |
+| `publish`      | which rows may be published and unpublished (collections with drafts) | `ctx`, `meta`, `typion` | boolean or filter |
+
+A rule is `true`, a filter object, or a function, possibly async, returning either. A rule a collection cannot have
+(`readDrafts` without drafts) is a compile error. `update` also governs the features' operations that write a row:
+`restore`, `discardDraft`, `versions.restore`.
+
+- **Deny by default.** A missing rule is `FORBIDDEN`, naming the collection, the operation and the rule.
+- **`false` is `FORBIDDEN`** for the operation itself, decided before any SQL, so it says nothing about any row. A
+  collection reached through `with` reads as `null` or `[]` instead.
+- **A filter limits the rows.** It is applied at the root, inside every `with`, inside every relation filter of a
+  `where`, to `count` and `page.total`, and to the row a write locks. A row outside it does not exist for the caller:
+  `findById`, `update` and `delete` on it are `NOT_FOUND`, never `FORBIDDEN`, so a caller cannot learn that it exists.
+- **Rules never receive the row.** Row-dependent logic is a filter, which the database applies. `create` has no row
+  yet: it checks the input (`data.authorId === ctx.actorId`).
+- **A filter may follow relations** (`{ project: { members: { userId: ctx.actorId } } }`). There a related row counts
+  only if the features let the call see it: a membership removed with soft delete, a draft or another tenant's row
+  grants nothing, whatever options the call gave. The related collection's own rules do not apply inside a rule,
+  which may look at rows the caller cannot read (an author whose profile is private).
+- **`typion` in a rule is a system instance**, for a lookup the rule needs (`typion.users.findById(…)`). It skips the
+  rules, so what it reads must not leak into anything but the rule's answer.
+
+## Patterns
+
+```ts
+import { collection } from 'typion'
+import { boolean, text, uuid } from 'drizzle-orm/pg-core'
+
+// Owners only: every operation is a filter on the owner, and creating checks the claimed owner.
+export const notes = collection('notes', {
+  columns: {
+    body: text().notNull(),
+    ownerId: uuid('owner_id').notNull(),
+    pinned: boolean().notNull(),
+  },
+}).define({
+  access: {
+    read: ({ ctx }) => (ctx.actorId === null ? false : { ownerId: ctx.actorId }),
+    create: ({ ctx, data }) => ctx.actorId !== null && data.ownerId === ctx.actorId,
+    update: ({ ctx, data }) =>
+      // The owner column is what makes the row theirs: moving it is refused, the rest is a filter.
+      ctx.actorId === null || data.ownerId !== undefined ? false : { ownerId: ctx.actorId },
+    delete: ({ ctx }) => (ctx.actorId === null ? false : { ownerId: ctx.actorId }),
+  },
+})
+```
+
+That collection is not in the config: a snippet like this one shows a shape, and a collection exists only once the
+config's `collections` lists it.
+
+- **Published to everyone, all of it to the author**: `read: true` on a collection with drafts already hides drafts
+  from plain reads; `readDrafts: ({ ctx }) => ({ authorId: ctx.actorId })` opens the author's own
+  ([collections.md](collections.md), `posts`).
+- **Approved to everyone, own to the author, all to admins**: an `OR` filter (`comments` in [hooks.md](hooks.md)).
+- **Roles**: compare `ctx.role` in the function; return `true` for the roles that see everything and a filter for the
+  others. The role comes from the context factory, which reads it from the database or the session, never from the
+  request's own claims.
+- **Tenants** are not a rule: `tenant: true` with multi-tenancy keeps every call in its tenant, and no rule can lift it
+  ([features/multi-tenant.md](features/multi-tenant.md)).
+
+## Columns
+
+`fields` in the structure decides, per column, beyond the row:
+
+- `read: false` removes the column from every type, read and filter: it cannot even be selected.
+- `read: ({ ctx }) => boolean` keeps it, typed `T | null`, and returns `null` to the callers it refuses.
+- `write: false | 'system' | ({ ctx, meta }) => boolean`: a write that names the column without the right is
+  `FORBIDDEN`, never silently dropped. It covers creates as well as updates: a column only admins may change but
+  anyone may set when creating a row says `({ ctx, meta }) => meta.operation === 'create' || ctx.role === 'admin'`.
+  Columns the features manage (`tenantId`, `deletedAt`, `status`, `publishedAt`) are `'system'` already.
+
+Field rules see the context registered in `interface Register { context }` ([collections.md](collections.md)).
+
+## What a caller sees
+
+```ts
+const anonymous = typion.$as({ actorId: null, role: null })
+
+// Published posts only; the drafts and the deleted ones do not exist here.
+const feed = await anonymous.posts.find({ columns: { id: true, title: true }, limit: 10 })
+
+// The author is never null (users are public); the address is, for anyone but an admin.
+const [first] = await anonymous.posts.find({
+  columns: { title: true },
+  with: { author: { columns: { name: true, email: true } } },
+  limit: 1,
+})
+first?.author satisfies { name: string; email: string | null } | undefined
+void feed
+```
+
+## System mode
+
+`typion.$system({ reason })` skips every rule, and only the rules: tenants, soft delete and drafts still apply, and so
+do validation and hooks. The reason is stored in the history and the audit trail. Use it for seeds, jobs, webhooks
+and the context factory's lookups — code no user drives — and never to answer a request because a rule refuses it:
+that is the rule to change.

package/docs/auth.md

@@ -0,0 +1,140 @@
+# Signing in
+
+Typion does not sign people in. The config's context factory reads who is calling from the request, through an auth
+library, and looks up what the application knows of them: their role, their tenant. This page sets up Better Auth,
+email and password, on the database Typion uses.
+
+```ts
+// src/db.ts
+import { Pool } from 'pg'
+
+// One pool for Typion and Better Auth. pg connects on the first query, so importing the config — the CLI does, the
+// tests do — opens nothing. Whatever the config imports must not connect when it is imported.
+export const pool = new Pool({ connectionString: process.env.DATABASE_URL })
+```
+
+Better Auth's tables are plain Drizzle tables in the config's `tables`, so `typion db generate` migrates them with the
+collections. They are not collections: no rule governs them, and nothing of the application's data goes through them.
+
+```ts
+// src/auth-schema.ts
+import { boolean, pgTable, text, timestamp } from 'drizzle-orm/pg-core'
+
+export const user = pgTable('user', {
+  id: text().primaryKey(),
+  name: text().notNull(),
+  email: text().notNull().unique(),
+  emailVerified: boolean('email_verified').notNull().default(false),
+  image: text(),
+  createdAt: timestamp('created_at').notNull().defaultNow(),
+  updatedAt: timestamp('updated_at').notNull().defaultNow(),
+})
+
+export const session = pgTable('session', {
+  id: text().primaryKey(),
+  expiresAt: timestamp('expires_at').notNull(),
+  token: text().notNull().unique(),
+  createdAt: timestamp('created_at').notNull().defaultNow(),
+  updatedAt: timestamp('updated_at').notNull().defaultNow(),
+  ipAddress: text('ip_address'),
+  userAgent: text('user_agent'),
+  userId: text('user_id')
+    .notNull()
+    .references(() => user.id, { onDelete: 'cascade' }),
+})
+
+export const account = pgTable('account', {
+  id: text().primaryKey(),
+  accountId: text('account_id').notNull(),
+  providerId: text('provider_id').notNull(),
+  userId: text('user_id')
+    .notNull()
+    .references(() => user.id, { onDelete: 'cascade' }),
+  accessToken: text('access_token'),
+  refreshToken: text('refresh_token'),
+  idToken: text('id_token'),
+  accessTokenExpiresAt: timestamp('access_token_expires_at'),
+  refreshTokenExpiresAt: timestamp('refresh_token_expires_at'),
+  scope: text(),
+  password: text(),
+  createdAt: timestamp('created_at').notNull().defaultNow(),
+  updatedAt: timestamp('updated_at').notNull().defaultNow(),
+})
+
+export const verification = pgTable('verification', {
+  id: text().primaryKey(),
+  identifier: text().notNull(),
+  value: text().notNull(),
+  expiresAt: timestamp('expires_at').notNull(),
+  createdAt: timestamp('created_at').notNull().defaultNow(),
+  updatedAt: timestamp('updated_at').notNull().defaultNow(),
+})
+
+export const authTables = { user, session, account, verification }
+```
+
+```ts
+// src/auth.ts
+import { betterAuth } from 'better-auth'
+import { drizzleAdapter } from 'better-auth/adapters/drizzle'
+import { drizzle } from 'drizzle-orm/node-postgres'
+import { authTables } from './auth-schema.ts'
+import { pool } from './db.ts'
+
+export const auth = betterAuth({
+  database: drizzleAdapter(drizzle({ client: pool }), { provider: 'pg', schema: authTables }),
+  emailAndPassword: { enabled: true },
+})
+```
+
+The config gives Typion the same pool, lists the tables, and turns a session into the context with
+`betterAuthContext(auth, map)` from `typion/auth/better-auth`, as [the guide's config](README.md#the-model) does:
+`map` gets the session (null for an anonymous caller) and the factory's input, with `system` to look the caller up.
+Better Auth's user has no role: the application keeps it on a row of its own, here `users`, found by e-mail. In a
+multi-tenant application the same lookup finds the caller's membership, and with it their tenant.
+
+```ts
+import { drizzle } from 'drizzle-orm/node-postgres'
+import { dbAdapter } from 'typion'
+import { pool } from '@/db.ts'
+
+// What the config's `db` is when Better Auth shares the pool; `close` ends it when the CLI is done.
+export const db = dbAdapter((relations) => drizzle({ client: pool, relations }), {
+  url: process.env.DATABASE_URL,
+  close: () => pool.end(),
+})
+```
+
+## Its routes
+
+Better Auth answers under `/api/auth/*`, next to Typion's transports under `/api/*`.
+
+```ts
+// src/app/api/auth/[...all]/route.ts
+import { toNextJsHandler } from 'better-auth/next-js'
+import { auth } from '@/auth.ts'
+
+export const { GET, POST } = toNextJsHandler(auth)
+```
+
+A server action that signs in sets cookies: add Better Auth's `nextCookies()` to its `plugins`. On Hono, the route goes
+before the transports' catch-all, which would otherwise answer it:
+
+```ts
+import { rest } from '@typion/rest'
+import { rpc } from '@typion/rpc'
+import { Hono } from 'hono'
+import { typionRoutes } from 'typion/hono'
+import { auth } from '@/auth.ts'
+import { config } from '@/typion.config.ts'
+
+export const server = new Hono()
+  .on(['GET', 'POST'], '/api/auth/*', (c) => auth.handler(c.req.raw))
+  .all('/api/*', typionRoutes(config, { transports: [rest(), rpc()] }))
+```
+
+## In tests
+
+A test binds its callers itself (`t.asUser(ctx)`), or replaces the context factory with
+`createTestTypion(config, { context })` ([testing.md](testing.md)), so it needs no session. Better Auth's tables are
+created with the collections either way.

package/docs/collections.md

@@ -0,0 +1,168 @@
+# Collections
+
+A collection is one file: its **structure** in the first object, its **behaviour** in `.define()`. The split is forced
+by the types: the structure is what every other collection is typed from, and the behaviour is typed against all of
+them, so it cannot be part of what they read.
+
+| In the structure                                   | In `define()`                                  |
+| -------------------------------------------------- | ---------------------------------------------- |
+| `columns` (Drizzle builders)                       | `access` ([access.md](access.md))              |
+| `relations`                                        | `hooks` ([hooks.md](hooks.md))                 |
+| `public`, `fields` (who reads and writes a column) | `validate` (Standard Schema refinements)       |
+| `softDelete`, `versions`, `tenant`, plugin options | `indexes` (Drizzle's third `pgTable` argument) |
+| `idColumn`, `timestamps`, `dbName`                 | `seed`, `defaultOrder`, `maxLimit`             |
+
+Every collection gets `id` (a uuid primary key) and `createdAt`/`updatedAt` unless it declares its own (`idColumn`,
+`timestamps: false`). Unknown keys are compile errors, so a misspelt option never passes in silence.
+
+`fields` is part of the structure, which is typed before the config exists: field rules see the context type
+registered in `interface Register { context }` ([README.md](README.md)), and without it only the base context
+(`actorId`, `mode`, `now`) and what the features add (`locale`, `tenantId`).
+
+```ts
+// src/typion/collections/users.ts
+import { text } from 'drizzle-orm/pg-core'
+import { collection } from 'typion'
+
+export const users = collection('users', {
+  columns: {
+    name: text().notNull(),
+    email: text().notNull().unique(),
+    role: text({ enum: ['admin', 'editor'] })
+      .notNull()
+      .default('editor'),
+  },
+  relations: (r) => ({ posts: r.many('posts', { from: 'id', to: 'authorId' }) }),
+  // Anyone may read a user's row, so `post.author` is typed non-null.
+  public: true,
+  fields: {
+    // The row is public, the address is not: typed `string | null`, `null` for everyone but admins.
+    email: { read: ({ ctx }) => ctx.role === 'admin' },
+    // Users edit their own row (below), but never their role.
+    role: { write: ({ ctx }) => ctx.role === 'admin' },
+  },
+}).define({
+  access: {
+    create: ({ ctx }) => ctx.role === 'admin',
+    update: ({ ctx }) =>
+      ctx.role === 'admin' ? true : ctx.actorId === null ? false : { id: ctx.actorId },
+    delete: false,
+  },
+})
+```
+
+```ts
+// src/typion/collections/posts.ts
+import { integer, text, uuid } from 'drizzle-orm/pg-core'
+import { collection, softUnique } from 'typion'
+import { users } from './users.ts'
+
+export const posts = collection('posts', {
+  columns: {
+    title: text().notNull(),
+    slug: text().notNull(),
+    body: text(),
+    views: integer().notNull().default(0),
+    authorId: uuid('author_id')
+      .notNull()
+      .references(() => users.table.id),
+  },
+  relations: (r) => ({
+    author: r.one('users', { from: 'authorId', to: 'id', optional: false }),
+    comments: r.many('comments', { from: 'id', to: 'postId' }),
+    tags: r.many('tags', {
+      from: 'id',
+      to: 'id',
+      through: { table: 'postsTags', from: 'postId', to: 'tagId' },
+      // Posts write their tags: `app.posts.link(id, 'tags', ids)`, under the post's update rule.
+      writable: true,
+    }),
+  }),
+  // Drafts and a history: `status`, `publishedAt`, `publish()`, `versions.list()` (features/versions.md).
+  versions: { drafts: true, max: 20 },
+  // A delete keeps the row: `deletedAt`, `restore()`, `withDeleted` (features/soft-delete.md).
+  softDelete: true,
+}).define({
+  access: {
+    // Plain reads see published posts only; `draft: true` reads need `readDrafts`.
+    read: true,
+    readDrafts: ({ ctx }) =>
+      ctx.role === 'admin' ? true : ctx.actorId === null ? false : { authorId: ctx.actorId },
+    readVersions: ({ ctx }) => ctx.actorId !== null,
+    // Nobody writes a post in someone else's name.
+    create: ({ ctx, data }) => ctx.actorId !== null && data.authorId === ctx.actorId,
+    update: ({ ctx }) =>
+      ctx.role === 'admin' ? true : ctx.actorId === null ? false : { authorId: ctx.actorId },
+    // A delete keeps the row; removing it for good is for code that runs in system mode.
+    delete: ({ ctx, options }) => ctx.role === 'admin' && options.hard !== true,
+    publish: ({ ctx }) => ctx.role === 'admin',
+  },
+  // Unique among the posts that are not deleted.
+  indexes: (t) => [softUnique('posts_slug_live', t.deletedAt).on(t.slug)],
+  defaultOrder: { createdAt: 'desc' },
+})
+```
+
+## Relations
+
+- Targets are named with a string (`r.one('users', …)`), so two collections that point at each other do not import
+  each other's types; the config checks that the target and the columns exist.
+- `r.one(target, { from, to, optional })`: `from` is the column here, `to` the one there. `optional: false` says the
+  row is always there (a `notNull` foreign key). The result is still `| null` when the target is **governed**: it has
+  a read rule other than `true` (or no `public: true`), or soft delete, drafts or a tenant, since the caller may not
+  see it. That `null` is a fact about access, not a bug to cast away.
+- `r.many(target, { from, to })` is always an array, filtered by the target's rules.
+- A **many-to-many** goes `through` a plain Drizzle table listed in the config's `tables`. Never make the join a
+  collection: its rules would be a way around the two sides'.
+- The side that owns a many-to-many says so with `writable: true`, and gets `link(id, relation, ids)` and
+  `unlink(id, relation, ids)`: a link is an edit of that row, under its `update` rule, to rows of the other side the
+  caller may read ([queries.md](queries.md#links)). The other side reads the relation and cannot write it, so a
+  permissive rule there (renaming tags) never lets anyone attach tags to posts that are not theirs.
+
+```ts
+// src/typion/collections/tags.ts
+import { pgTable, primaryKey, text, uuid } from 'drizzle-orm/pg-core'
+import { collection } from 'typion'
+import { posts } from './posts.ts'
+
+export const tags = collection('tags', {
+  columns: { label: text().notNull().unique() },
+  relations: (r) => ({
+    posts: r.many('posts', {
+      from: 'id',
+      to: 'id',
+      through: { table: 'postsTags', from: 'tagId', to: 'postId' },
+    }),
+  }),
+  public: true,
+}).define({ access: { create: ({ ctx }) => ctx.role === 'admin' } })
+
+// Not a collection: it has no API, and reads cross it under the rules of posts and tags.
+export const postsTags = pgTable(
+  'posts_tags',
+  {
+    postId: uuid('post_id')
+      .notNull()
+      .references(() => posts.table.id, { onDelete: 'cascade' }),
+    tagId: uuid('tag_id')
+      .notNull()
+      .references(() => tags.table.id, { onDelete: 'cascade' }),
+  },
+  (t) => [primaryKey({ columns: [t.postId, t.tagId] })],
+)
+```
+
+## Adding a collection
+
+1. `typion make collection <name>` writes `src/typion/collections/<name>.ts` and registers it in the config's
+   `collections` (or write the file and add it there yourself).
+2. Columns and relations in the structure. A column another collection references is `.references(() =>
+other.table.id)`; `other.table` exists once the config includes `other`.
+3. `access` for every operation callers use ([access.md](access.md)). With none, everything is `FORBIDDEN`.
+   `define({ access: allowAll() })` allows everything while prototyping, and must not reach production.
+4. `typion db generate --name add-<name>`, read the SQL, commit it ([database.md](database.md)).
+5. A test with a caller the rules allow and one they deny ([testing.md](testing.md)).
+
+A collection whose structure fails to type-check can make the whole registered config circular (TS2456 on
+`RegisteredPlugins`, "circularly references itself"). Fix the first error in the collection's own file; the rest
+usually follows from it.

package/docs/database.md

@@ -0,0 +1,74 @@
+# The database
+
+The schema lives in the config: the CLI reads it, so there is no `drizzle.config.ts` and no schema file to keep in
+step. Every table — the collections, the history tables the features derive (`typion.posts_versions`), a plugin's
+tables, the config's `tables` — is in `config.schema`.
+
+## Drivers
+
+The config's `db` opens the database on first use, not when the config is imported, so the CLI and drizzle-kit can
+read the config without one. The same must hold for whatever the config imports: an auth library built on a Drizzle
+instance connects when it is built, so it shares a `pg` pool, which connects on the first query ([auth.md](auth.md)).
+
+- **PGlite** in development and in tests: `db: pglite({ dataDir: '.pglite' })` from `typion/db/pglite`, Postgres in
+  the process, no server.
+- **Postgres** anywhere else: `dbAdapter((relations) => drizzle(url, { relations }), { url })` around any Drizzle
+  driver ([README.md](README.md) has it with node-postgres). Give `url` so `typion db studio` can open it.
+- **Neon**: node-postgres on the connection string from a Node runtime, or the `Pool` of `drizzle-orm/neon-serverless`
+  (WebSockets). Not Neon's HTTP driver: it has no interactive transactions, and every Typion write runs in one (the row
+  is locked, hooks run, the version is recorded, then it commits).
+
+At boot the instance compares its tables with the database and names what is missing (`checkSchema`, on by default):
+a database never pushed or migrated fails at once, not at the first query.
+
+## Commands
+
+| Command                              | Does                                                                       |
+| ------------------------------------ | -------------------------------------------------------------------------- |
+| `typion db push [--force]`           | makes a development database match the config; `--force` when data is lost |
+| `typion db generate --name <change>` | writes the SQL of what changed to `typion/migrations/`, with its snapshot  |
+| `typion db migrate`                  | applies the migrations the database has not applied                        |
+| `typion db status`                   | what is applied and what is pending                                        |
+| `typion db seed`                     | runs `src/typion/seed.ts` through the engine                               |
+| `typion db seed --random`            | rows from drizzle-seed instead; each feature fills its own columns         |
+| `typion db studio`                   | Drizzle Studio on the config's database                                    |
+| `typion make collection <name>`      | a collection file, registered in the config                                |
+| `typion init`                        | sets Typion up in an existing project, and refreshes the agent notes       |
+
+The config is found by walking up from the working directory (`typion.config.ts`, also under `src/`), or named with
+`--config`. The CLI reads `.env.local` and `.env` from the working directory, as Next.js does, never over a variable
+the shell set; an adapter given `url: process.env.DATABASE_URL` with the variable unset says so.
+
+## Migrations
+
+1. Change the collections.
+2. `typion db generate --name <what-changed>`; read the SQL it wrote. A rename is a drop and an add unless you edit
+   it: data is lost otherwise.
+3. Commit the SQL and the snapshot with the change.
+4. Deploys run `typion db migrate` before the new code serves requests.
+
+`typion db push` is for a development database you can throw away; it never touches a shared one.
+
+## Seed
+
+```ts
+// src/typion/seed.ts
+import type { Typion } from 'typion'
+import type { config } from '../typion.config.ts'
+
+// `typion db seed` calls it with the config's instance; a test can call it with its own.
+export async function seed({ typion }: { typion: Typion<typeof config> }) {
+  const system = typion.$system({ reason: 'seed' })
+  const ada = await system.users.create({ name: 'Ada', email: 'ada@example.test', role: 'admin' })
+
+  // Content written as its author, so rules, hooks and the history see what a real caller does.
+  const asAda = typion.$as({ actorId: ada.id, role: 'admin' })
+  const post = await asAda.posts.create({ title: 'Welcome', slug: 'welcome', authorId: ada.id })
+  await asAda.posts.publish(post.id)
+}
+```
+
+`typion db seed --if-empty` does nothing when the collections already hold rows, which is what a setup script wants;
+`--reset` empties every table of the config first — the collections, their history, the plugins' tables (the audit
+trail) and the config's `tables` (an auth library's users) — so the seed starts from nothing. `--random` needs
+`drizzle-seed@1.0.0-rc.5-ab785fc`, the build that runs on this Drizzle.

package/docs/features/localization.md

@@ -0,0 +1,112 @@
+# Localization
+
+Localized columns: one jsonb per field, resolved per locale. A feature of Typion's core ([the guide](../README.md)),
+configured once for the application in `defineSetup`.
+
+```ts
+// src/typion.config.ts
+import { defineConfig, defineSetup } from 'typion'
+import { pglite } from 'typion/db/pglite'
+import { pages } from './typion/collections/pages.ts'
+
+export const setup = defineSetup({
+  localization: {
+    locales: ['it', 'en'],
+    defaultLocale: 'it',
+    // Where the locale of a call comes from; without it the `x-locale` header, then the default locale.
+    locale: ({ headers }) => (headers?.get('cookie')?.includes('locale=en') ? 'en' : undefined),
+  },
+})
+
+export const config = defineConfig({
+  setup,
+  collections: [pages],
+  db: pglite({ dataDir: '.pglite' }),
+  context: (): { actorId: string | null } => ({ actorId: null }),
+})
+
+declare module 'typion' {
+  interface Register {
+    setup: typeof setup
+    config: typeof config
+  }
+}
+```
+
+```ts
+// src/typion/collections/pages.ts
+import { text } from 'drizzle-orm/pg-core'
+import { collection, localized, localizedIndex, localizedUnique } from 'typion'
+
+export const pages = collection('pages', {
+  columns: {
+    title: localized(text()).notNull(), // jsonb: { it: string; en?: string }
+    slug: localized(text()).notNull(),
+    body: localized(text()),
+  },
+  public: true,
+}).define({
+  access: { create: ({ ctx }) => ctx.actorId !== null, update: ({ ctx }) => ctx.actorId !== null },
+  indexes: (t) => [
+    localizedUnique('pages_slug_it', t.slug, 'it'),
+    localizedUnique('pages_slug_en', t.slug, 'en'),
+    localizedIndex('pages_title_it', t.title, 'it'),
+  ],
+})
+```
+
+```ts
+// In the locale of the call, falling back to the default one.
+const [page] = await app.pages.find({ columns: { title: true }, limit: 1 })
+page satisfies { title: string } | undefined
+
+// One locale, without the fallback, or the stored object.
+const english = await app.pages.find({ columns: { title: true }, locale: 'en', fallback: false })
+english satisfies { title: string | null }[]
+const stored = await app.pages.find({ columns: { title: true }, locale: 'all' })
+stored satisfies { title: { it: string; en?: string } }[]
+
+// A create gives the default locale of a NOT NULL column; `locale: 'all'` writes several at once.
+const about = await app.pages.create(
+  { title: { it: 'Chi siamo', en: 'About us' }, slug: { it: 'chi-siamo', en: 'about-us' } },
+  { locale: 'all' },
+)
+await app.pages.update(about.id, { title: 'About' }, { locale: 'en' })
+```
+
+- **Reads** resolve a localized column in the locale of the call and fall back to the default locale:
+  `title` is a `string`. `locale: 'en'` forces a locale, `fallback: false` gives `string | null`, `locale: 'all'`
+  returns the stored object (`{ it: string; en?: string }`). The types follow the option you pass.
+- **Filters and ordering** compare in the locale being read: `where: { title: { ilike: '%ciao%' } }` becomes
+  `coalesce(title->>'it', title->>'en') ilike …`. A filter an access rule returns compares the same way, in the
+  locale of the context, whatever locale the query asks for.
+- **Writes** take a plain value in the locale of the call, merged with the stored value under the row lock:
+  `update(id, { title: 'Hello' })` writes `ctx.locale`, `update(id, { title: 'Hello' }, { locale: 'en' })` writes
+  `en`, and `{ locale: 'all' }` takes the whole object (`{ it: 'Ciao', en: 'Hello' }`). A NOT NULL column always
+  holds the default locale: create it in that locale, or with `locale: 'all'`. `locale` is an option of the
+  collections with localized columns only.
+- **What a write returns** is what a read returns: `create(…)` gives `title` as a `string` in the locale written,
+  `create(…, { locale: 'all' })` the object.
+- **The context** gets `ctx.locale`, typed with your locales; `$as(ctx, { locale })`, `$system({ locale })` and
+  `getApp(config, { locale })` choose it explicitly.
+- **Validation** checks each locale's value as the column you wrapped (`localized(text())` takes strings,
+  `localized(integer())` numbers), with per-locale refinements (`validate.fields.title.it`). `localized()` refuses a
+  column JSON would not give back as it was (a date, a bigint). The audit trail records only the locales that changed.
+- **Indexes**, in the collection's `define({ indexes })`: `localizedIndex(name, column, locale)` for filters and
+  ordering, `localizedUnique(name, column, locale)` for a value unique within one locale (a slug per language), and
+  `localizedValue(column, locale)` for an index of your own:
+  `uniqueIndex('pages_path').on(t.tenantId, localizedValue(t.path, 'it'))`.
+- **The application reads its locales** from `setup.localization` (`locales`, `defaultLocale`), read-only: a
+  language switcher, the locale a form writes.
+- `typion db seed --random` writes a distinct object keyed by locale into every row.
+
+Without `localization` in the setup none of this exists: `locale` and `fallback` are unknown options,
+`ctx.locale` is not there, `localized()` does not compile, and `defineConfig` refuses a localized column.
+
+## For plugin authors
+
+Localization uses nothing a plugin of your own cannot: it is built on the column-kind API of `typion`
+(`defineColumnKind`, `Kinded`, `columnKinds` in `definePlugin`), the way a plugin adds a field type of its own,
+described with its rules in §2.13.1 of [Typion's ARCHITECTURE](https://github.com/the-escape-studio/typion/blob/main/docs/ARCHITECTURE.md).
+Its source, [`src/features/localization.ts`](https://github.com/the-escape-studio/typion/blob/main/packages/typion/src/features/localization.ts),
+is the worked example: neither is in the package.